Task: Create COMMANDSPEC.md for a CLI Command

Task: Create COMMAND_SPEC.md for a CLI Command

Objective

Produce a COMMAND_SPEC.md that serves as the single source of truth for one command's deep composition rules: how arguments parse beyond the grammar declared in CLI_IA, how stdin / stdout / stderr compose under each output mode, how human-mode tables and blocks lay out using DESIGN.md tokens, how interactive prompts and progress and pager choreograph across the three-mode rule, how the four primary POSIX signals are handled, how each failure listed in CLI_IA's matrix is detected and cleaned up and recovered from, and how the rendering degrades across terminal capability tiers. The defining claim — and the definition of "done" — is that an implementing agent reading CLI_IA's per-command blueprint plus DESIGN.md's terminal style tokens plus this COMMAND_SPEC can compose the command exactly as designed across all output modes and capability tiers, without inventing parsing rules, output shapes, prompt choreography, signal-cleanup steps, or capability-degradation rules.

COMMAND_SPEC is the rarest of the per-item leaf specs in the framework — most CLI commands are simple enough that the inline blueprint at CLI_IA.md is sufficient. Use this skill only for commands that exceed the inline form: dense interactive prompts, materially different shapes across --json / --quiet / human modes, intricate flag interactions, non-trivial signal handling, multi-stage progress reporting, or extensive failure-recovery semantics. Most projects will have few or zero COMMAND_SPEC files.

The commonest violation is to overlap with CLI_IA. CLI_IA owns identity — that the command exists, its grammar, its global flags by reference, its primary outcome, its failure-matrix summary, its exit-code taxonomy, its use-case traceability. COMMAND_SPEC owns composition — the parsing rules beyond the grammar, the output composition beyond the contract, the interactive choreography beyond the surface name, the signal handling beyond the failure-row name, the capability degradation beyond the tier names. When COMMAND_SPEC restates CLI_IA, the two documents drift; cite by reference instead.

Inputs

1. Command identifier (required) — the stable command identifier from CLI_IA.md. Conventionally the canonical command path (tool repo push) or an assigned ID. The skill produces one COMMAND_SPEC per command identifier.
2. CLI_IA.md (required) — the parent surface IA document. Read in full: command grammar, global flags, environment variables, exit-code taxonomy, terminal capability strategy, scriptability contract, shared interactive surfaces, and the target command's per-command blueprint entry. Every citation in this COMMAND_SPEC resolves into CLI_IA.
3. DESIGN.md (required if present in the project) — the terminal style-token document. Read in full: color palette and tiers, glyph set with ASCII fallbacks, table style, error-block style, prompt style, progress style. Every visual decision in COMMAND_SPEC's human-mode and capability-degradation sections cites a token by name. If DESIGN.md is absent for the project, surface the absence as an open question rather than inventing tokens.
4. Sibling COMMAND_SPEC.md files (optional, auto-discovered) — for each command this command hands off to or receives output from in a CLI_IA flow, load that command's COMMAND_SPEC if it exists. Use only as a cross-reference for naming consistency; never copy content.
5. Prior cli-commands/<cmd-id>/COMMAND_SPEC.md (optional, auto-discovered — only if refining) — read fully; preserve every resolved open question, every assigned mode shape, every cleanup step already specified. Re-run citations against the current CLI_IA and DESIGN — do not assume stale tokens or exit-code IDs are still valid.

Read-set size: CLI_IA's full target-command blueprint plus the surrounding policy sections (grammar, globals, exit codes, capability) and DESIGN.md when present are always read; sibling COMMAND_SPECs are read only when CLI_IA's flow entries name them.

The output file is conventionally placed at cli-commands/<cmd-id>/COMMAND_SPEC.md in the consuming project, where <cmd-id> is the stable identifier from CLI_IA.

Selection Criteria

COMMAND_SPEC is opt-in and is the rarest of the per-item specs in the framework. Do not create one for a command unless at least one of the following holds:

• The composition would exceed roughly thirty lines if expressed inline in CLI_IA's per-command blueprint entry.
• The command supports two or more output modes whose shapes differ materially (not just "the same data, JSON vs human" — distinct top-level structures).
• The command has rich interactive prompts (multi-step wizard), multi-stage progress reporting (more than a single bar), or invokes a pager.
• The command launches an embedded TUI surface (in which case a separate VIEW_SPEC may also exist for the launched view; COMMAND_SPEC owns the launching command, VIEW_SPEC owns the view).
• Signal handling is non-trivial — graceful shutdown with cleanup, resume-from-interrupt, side-effect rollback.
• Failure recovery requires command-specific cleanup steps beyond exiting with a code (lockfiles, partial state, temp directories).
• Multiple work units touch the same command and benefit from a shared composition contract.

If none of the above holds, do not produce a COMMAND_SPEC. Stay with CLI_IA's inline blueprint. Most commands fall into this category.