CLI Forge Design

cli-forge Design

Use this stage when the workflow needs one authoritative description contract for a generated Rust CLI Skill before later stages proceed.

Purpose

Define the skill's high-level identity: what it is, who it serves, and how it is positioned. Produce a single approved description contract that all downstream surfaces must reuse instead of inventing competing wording.

This stage answers the question "What is this skill?" The detailed CLI contract (commands, flags, formats) belongs to the Plan stage downstream.

Canonical References

• ./instructions/design-contract.md
• ./planning-brief.md
• ./contracts/design-contract.yml.tpl

Entry Gate

Required Inputs

• Classified workflow intent from the Router
• Current or proposed skill scope
• Any existing description surfaces that must stay aligned
• Whether this is a new skill or a refresh of an existing contract

Workflow

1. Confirm whether the work creates a new skill or changes the user-facing contract of an existing one.
2. Read ./planning-brief.md to load the shared constraints.
3. Define or refresh the approved purpose summary (one line).
4. Define or refresh the positioning statement (one paragraph).
5. Record which downstream surfaces must stay synchronized:
   • Cargo.toml package.description
   • SKILL.md purpose section
   • README.md header and description
   • Help text summary line across non-leaf auto-help, --help, and structured help
   • Release notes summary (when publish is in scope)
   • npm package description (when publish is in scope)
6. Record the downstream help contract for later stages:
   • leaf defaults stay structured failures instead of auto-help
   • non-leaf defaults auto-render man-like human-readable help
   • --help renders man-like human-readable help
   • help returns structured output
   • human-readable help preserves NAME -> SYNOPSIS -> DESCRIPTION -> OPTIONS -> FORMATS -> EXAMPLES -> EXIT CODES
7. Record the publish contract for later release work: Publish owns both the repo-native GitHub Release and npm publication.
8. Generate .cli-forge/design-contract.yml using the format defined in ./contracts/design-contract.yml.tpl.
9. Request user approval of the design contract before moving forward. Call the runtime's dialog-based chooser (e.g., AskUserQuestion) with the options approve and continue, request changes, or stop for now when it is available. If no dialog-based chooser is available, use a numbered text menu with the same three options and add Other: <custom response> as the fallback escape hatch. Accept exact replies 1, 2, or 3, or Other: .... If a numeric reply includes additional text, ask for clarification before proceeding. Do not require the user to type the full option label.

Outputs

• .cli-forge/design-contract.yml — approved description contract

Exit Gate

Guardrails

• CRITICAL DIRECTIVE TO THE ASSISTANT: You MUST STOP execution and ask for the user's explicit approval after generating design-contract.yml. Do NOT proceed to the Plan or Scaffold stage autonomously. Call the runtime's dialog-based chooser (e.g., AskUserQuestion) for approval when it is available, or use the standardized numbered text fallback with 1. approve and continue, 2. request changes, 3. stop for now, and Other: <custom response>.
• This stage is the authoritative source for user-facing purpose and positioning. Downstream stages consume the approved contract; they do not redefine it.
• Do not define CLI commands, flags, or output formats here. That work belongs to the Plan stage.
• When publish support is later adopted, all release-facing wording must reuse the approved summary.
• npm package descriptions must reuse the same approved contract whenever the Publish stage adopts npm publication.

Next Step

Continue with ../cli-forge-plan/SKILL.md to define the detailed CLI contract.