github / github/spec-kit

[Feature]: Add artifact, optional, and handoffs to the command manifest schema

未关闭
#4,209 5 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
enhancement feature-assess feature-go
主要语言
Python
星标
137k
派生
12.3k
平均合并
2 天 12 小时
30 天内合并 PR
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`.

贡献指南

打开贡献指南

调研方向

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.

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
cli, tooling
Issue 类型
功能
难度
4/5
预计耗时
3-5 天
活跃度
活跃
描述清晰度
基本清楚
新手友好度
64/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。