[Feature]: Add artifact, optional, and handoffs to the command manifest schema
- 主要言語
- Python
- スター
- 137k
- フォーク
- 12.3k
- 平均マージ
- 2日 12時間
- マージ済み PR(30日)
- 159
説明
### 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`.
コントリビューションガイド
調査の方向性
src/specify_cli/extensions/__init__.py と src/specify_cli/presets/__init__.py から始め、次に src/specify_cli/_utils.py の relative_extension_path_violation と Forge 統合を調査します。templates/commands/plan.md の既存の command frontmatter と manifest モデルを比較し、normalized handoff mapping を特定します。実装の検証によって、validation、precedence、後方互換な schema の動作、Forge stripping、documentation がカバーされれば完了です。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- python
- 領域
- cli, tooling
- issue の種類
- 機能追加
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 活発さ
- 活発
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 64/100