[Feature]: Add artifact, optional, and handoffs to the command manifest schema
- Dominant language
- Python
- Stars
- 137k
- Forks
- 12.3k
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 159
Description
### Problem Statement
`ExtensionCommand` and preset command entries model fields such as `type`, `name`, `file`, `description`, and `strategy`, but do not expose `artifact` (the repo-relative output path a command produces), `optional` (whether a flow can skip it), or `handoffs` (declarative follow-on commands).
`handoffs` currently lives in command frontmatter and is stripped by several markdown integrations, including Forge. This forces downstream consumers such as wizard UIs, flow runners, and pipeline visualizers to re-parse markdown frontmatter and prevents these semantics from being consistently available through the command manifest model.
### Proposed Solution
Add optional `artifact`, `optional`, and `handoffs` fields to extension and preset command manifest entries:
```yaml
commands:
- name: speckit.plan
file: commands/speckit.plan.md
description: "..."
artifact: specs/{feature}/plan.md
optional: false
handoffs:
- to: speckit.tasks
when: "plan.status == 'done'"
message: "Ready to break plan into tasks"
```
Parse command frontmatter during manifest loading and merge its `handoffs` into the command entry when the manifest does not declare them. If both sources provide `handoffs`, the manifest value takes precedence.
Keep `handoffs` in the in-memory model, while continuing to strip it on the Forge export path. Define how the existing frontmatter shape (`label`, `agent`, `prompt`, `send`) maps to or coexists with the manifest shape (`to`, `when`, `message`). In other words, add handoffs to the normalized in-memory command model and JSON output. Accept an explicit manifest declaration as an optional override, but derive it from command frontmatter when absent. Authors should not need to duplicate handoffs in both files.
### Alternatives Considered
- Leave `handoffs` frontmatter-only and require consumers to parse it. Rejected because downstream consumers would duplicate parsing.
- Derive `artifact` from the command file. Rejected because a command may produce multiple artifacts or none.
- Bump `schema_version` without a compatibility strategy. Current validators use exact-version matching, so a bump would reject existing manifests. Prefer an additive change under the current version unless compatibility policy is deliberately changed.
### Component
Specify CLI (initialization, commands)
### AI Agent (if applicable)
Not applicable
### Use Cases
1. A wizard renders a Spec-Driven Development pipeline graph by walking `handoffs` edges without opening markdown files.
2. A flow runner shows a skip action for commands with `optional: true` and refuses to auto-skip mandatory commands.
3. An audit joins a command's `artifact` path to files in the repository.
### Acceptance Criteria
- [ ] Extension and preset command schemas accept optional `artifact` (string), `optional` (bool, default `false`), and `handoffs` (list of `{to, when?, message?}`).
- [ ] The manifest loader merges command-file frontmatter `handoffs` when the manifest does not declare its own value.
- [ ] Manifest-declared `handoffs` takes precedence over frontmatter.
- [ ] Forge export continues to strip `handoffs` from exported frontmatter.
- [ ] `artifact` is validated as repo-relative; `handoffs[].to` resolves to a known command; `optional` is validated as a boolean.
- [ ] The schema-version decision is recorded, with backward-compatible behavior for existing manifests.
- [ ] Valid and malformed manifest entries, frontmatter merge precedence, and Forge stripping are covered by the implementation verification.
- [ ] The manifest schema and `handoffs` semantics are documented in the relevant existing documentation.
### Additional Context
Impacts `preset info --json` / `extension info --json`, which are tracked separately.
Relevant implementation locations include `src/specify_cli/extensions/__init__.py`, `src/specify_cli/presets/__init__.py`, `src/specify_cli/_utils.py::relative_extension_path_violation`, and `src/specify_cli/integrations/forge/__init__.py`. Existing command frontmatter examples include `templates/commands/plan.md`.
Contributor guide
Research direction
Start with src/specify_cli/extensions/__init__.py and src/specify_cli/presets/__init__.py, then inspect relative_extension_path_violation in src/specify_cli/_utils.py and the Forge integration. Compare the existing command frontmatter in templates/commands/plan.md with the manifest models and determine the normalized handoff mapping. Done means validation, precedence, backward-compatible schema behavior, Forge stripping, and documentation are covered by implementation verification.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 64/100