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

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 がカバーされれば完了です。

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:

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.