--- name: bartsoj/COMMAND_SPEC.md source: https://app.decimal.ai/s/bartsoj-command-spec-md@1/SKILL.md source_sha256: fba035c19b67 --- # 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//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//COMMAND_SPEC.md` in the consuming project, where `` 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. --- ## Rules ### Single source of truth — no overlap with CLI_IA CLI_IA owns command identity and contract; COMMAND_SPEC owns composition. The boundary: - **CLI_IA owns** — that the command exists; its grammar (`tool {verb} {noun}`); its place in the inventory tree; its global flags by reference; its primary outcome (one sentence); its failure-matrix summary (rows + exit code per row); its use-case traceability; the exit-code taxonomy; the shared-surface inventory by name; the terminal capability tier names. - **COMMAND_SPEC owns** — argument-parsing order sensitivity and conflict resolution; default-from-context derivation; auto-detection rules; argument expansion semantics; per-stream composition rules; the exact JSON shape for each machine mode; the table layout, block ordering, and color usage in human mode; the prompt and progress and pager choreography; the signal-cleanup steps; the per-failure detection signal and stderr message structure and recovery hint and cleanup; the per-capability-tier rendering rules; the idempotency / lock / resume / dry-run semantics. Do not redefine CLI_IA's grammar, globals, exit codes, primary outcome, failure-matrix summary, or traceability in this document. Reference them. When CLI_IA and COMMAND_SPEC appear to disagree on any owned concern, CLI_IA decides; this document is updated to match. ### Citation rules Every cross-document reference uses the cited document's stable identifier verbatim: - **Design tokens** are cited by name from DESIGN.md (`color-warning`, `glyph-bullet-primary`, `table-style-compact`, `prompt-style-default`, `progress-style-bar`). Do not paraphrase; do not introduce a new token. - **Exit codes** are cited by the ID and integer assigned in CLI_IA's Exit-Code Taxonomy (e.g., `EX-AUTH (4)`). Never invent a code; never use a bare integer without its taxonomy ID. - **Capability tiers** are cited by the names CLI_IA's Terminal Capability section uses (e.g., "24-bit color", "256 color", "16 color", "no color", "Unicode", "ASCII-only", "narrow terminal"). Do not invent tier names. - **Shared interactive surfaces** are cited by name from CLI_IA's Shared Surfaces section (e.g., "confirmation prompt", "single-select", "progress bar"). Do not redefine the surface inline; reference it. - **Flags** are cited by their long form (`--json`, `--quiet`, `--no-color`, `--yes`), never by short form alone. Short forms are mentioned only in the Flags table in section 2. - **Environment variables** are cited in `UPPER_SNAKE_CASE` exactly as declared in CLI_IA (e.g., `NO_COLOR`, `TOOL_AUTH_TOKEN`). - **Sibling commands** in flow citations use the canonical command path from CLI_IA's inventory (e.g., `tool repo push`). ### Forbidden patterns - **Defining new exit codes.** CLI_IA's Exit-Code Taxonomy is authoritative. If a failure in this command needs a code that does not exist, surface it in section 12 Open Questions and re-run CLI_IA before re-running this skill. - **Brand color decisions.** Hex codes, RGB triplets, named-from-thin-air color words. Cite DESIGN.md tokens by name only. - **Implementation library names.** No `clap`, `cobra`, `commander`, `argparse`, `click`, `cli-ux`, `kingpin`, `pflag`, `yargs` — those belong in per-unit SPEC. - **Final user-facing copy.** CLI_IA owns prompt and message structure at the role level; COMMAND_SPEC owns composition rules (where the prompt appears, how it composes with progress, how it degrades). Concrete English sentences are owned by a UX-writing phase. - **Restating CLI_IA.** Do not redefine grammar, global flags, exit-code taxonomy, primary outcome, failure-matrix row presence, use-case traceability, or capability-tier definitions in this document. - **Code or pseudocode.** Compose by prose and tables. Pseudocode is permitted only when a specific algorithm is non-obvious and cannot be described unambiguously in prose; in that case, include a one-line note explaining why prose was insufficient. ### Strict template Twelve sections, every section mandatory. If a concern genuinely does not apply — the command is not interactive, has no signal-specific behavior beyond defaults, or supports only one output mode — the section heading remains and its body states the no-op explicitly (e.g., "Non-interactive only; no prompts, progress, or pager.", "Default signal disposition; no command-specific cleanup."). Silent omission is forbidden; an empty section is a quality-checklist failure. ### Single YAML frontmatter block - Exactly one YAML frontmatter block at the top of the COMMAND_SPEC.md output, never two — even when refining an existing COMMAND_SPEC, merge into a single block. The block carries every field enumerated in the Output Format template (`skill`, `date`, `status`, `command_id`, `flags_specified`, `output_modes_specified`, `interactive_surfaces_specified`, `signals_handled`, `failure_modes_specified`, `capability_tiers_specified`, `open_questions`). - Every count in the frontmatter matches the body exactly: `flags_specified` is the row count of section 2's Flags table; `output_modes_specified` is the number of output-mode subsections in section 5; `interactive_surfaces_specified` is the number of surfaces enumerated in section 7 (zero when the section reads "Non-interactive only"); `signals_handled` is the number of signal entries in section 8 (always at minimum the four primary signals SIGINT / SIGTERM / SIGHUP / SIGPIPE — when one has default disposition, it still counts as a row); `failure_modes_specified` is the number of failures detailed in section 9, which must equal the row count of CLI_IA's failure-matrix summary for this command minus any "N/A" rows; `capability_tiers_specified` is the number of tier subsections in section 10 (always the full set CLI_IA's Terminal Capability section enumerates); `open_questions` is the count of unresolved questions in section 12 (zero when section 12 reads "All questions resolved."). - `status` is `complete` only when section 12 reads "All questions resolved."; `has_open_questions` when one or more questions remain; `blocked` only when a missing input (an absent CLI_IA, an absent DESIGN.md when the project requires one, an unregistered exit code the command needs) prevents authoring and section 12 makes the gap explicit. ### Precision rules - Use exact names — flag long forms, environment-variable names, capability-tier names, shared-surface names, design-token names, exit-code IDs, sibling-command paths. No "appropriate", "relevant", "as needed", "etc." - Describe stream composition by ordered structure ("First line: header summary; subsequent lines: one record per row; final line: total summary"), not by vague summary ("appropriate tabular output"). - Distinguish between "writes nothing" and "writes empty" — state which one, and what triggers the empty-output case. - Distinguish between "exits silently" and "exits with a recovery hint" — state which one per failure row. ### Three-mode interactive rule Every command that can prompt must document its behavior across all three modes — interactive (TTY, no `--yes`), non-interactive with blanket confirmation (`--yes` or `CI=true`), and non-interactive without blanket confirmation (pipe / `--no-input` / no TTY and no `--yes`). The third mode typically resolves to "exit with the non-interactive mode unavailable failure code from CLI_IA's taxonomy". State the resolution per surface, not just generally. If the command never prompts, state "Non-interactive only; no prompts, progress, or pager." in section 7 and skip the three-mode bullets. ### Capability degradation completeness Every tier listed in CLI_IA's Terminal Capability section must appear as a subsection in section 10 — full color tier, mid-color tiers, no-color, Unicode, ASCII-only, narrow-terminal. For each tier, state what is rendered differently versus the previous-richer tier (palette swap, glyph substitution, column collapse, wrap policy). Do not omit a tier on the grounds that "behavior is the same as the higher tier" — state the no-op explicitly ("Same palette as 24-bit; no degradation."). ### Failure-matrix completeness Section 9 details every failure row CLI_IA's failure-matrix summary lists for this command, in the same order, by the same name. Each row provides: the detection signal (what condition triggers it), the exit code (citing the taxonomy ID and integer), the stderr message format (one-line summary; optional detail block; optional remediation hint — describe the structure, not the literal copy), the recovery hint (what the user should try), and the cleanup steps (what state must be removed before exiting — lockfiles, temp files, partial output). Rows CLI_IA marks "N/A — {reason}" are skipped here, preserving the reason in a one-line note. Rows that exist in CLI_IA but cannot be detailed must surface as open questions in section 12. --- ## Output Format The COMMAND_SPEC.md file must follow this exact structure. Every section is mandatory. If a section's concern does not apply to this command, include the heading with an explicit no-op statement underneath. ```markdown --- skill: COMMAND_SPEC.md date: {YYYY-MM-DD} status: {complete | has_open_questions | blocked} command_id: {command-id-from-CLI_IA} flags_specified: {N} output_modes_specified: {N} interactive_surfaces_specified: {N} signals_handled: {N} failure_modes_specified: {N} capability_tiers_specified: {N} open_questions: {N} --- # COMMAND_SPEC: `{command path}` — {short name} ## 1. Identity & Cross-references - **Command ID:** {ID from CLI_IA inventory} - **Canonical invocation:** `{full grammar — e.g., tool repo push [] [--force] [--json]}` - **CLI_IA blueprint:** `CLI_IA.md` § {section anchor} — read this entry first; this COMMAND_SPEC extends it with composition rules. - **Tokens cited from DESIGN.md:** - **Colors:** `{token-name}`, `{token-name}` - **Glyphs:** `{token-name}`, `{token-name}` - **Table style:** `{token-name}` - **Error-block style:** `{token-name}` - **Prompt style:** `{token-name}` - **Progress style:** `{token-name}` *(If DESIGN.md is absent: state "DESIGN.md not present in project — visual choices surfaced as open questions in section 12.")* - **Sibling commands referenced in flows:** `{command path}` (handoff target / handoff source); `{command path}` (...). *(Or "None — command stands alone in CLI_IA flows.")* --- ## 2. Synopsis & Argument Structure **Synopsis:** `{usage(1)-style synopsis — e.g., tool repo push [] [--force] [--json]}` ### Positional arguments | Name | Type | Required | Default | Validation | Env-var fallback | |------|------|----------|---------|------------|------------------| | `` | {type} | {yes/no} | {default or "—"} | {validation rule} | {`UPPER_SNAKE` or "—"} | *(Or "No positional arguments.")* ### Flags | Long form | Short | Type | Default | Env-var | Mutually exclusive with | Required with | Purpose | |-----------|-------|------|---------|---------|-------------------------|---------------|---------| | `--{flag}` | `-{s}` | {boolean / string / integer / enum / repeated} | {default} | `UPPER_SNAKE` or "—" | `--{flag}` or "—" | `--{flag}` or "—" | {one-line role} | *(Standard global flags are documented in CLI_IA § Global Flags & Environment and apply by reference. Only command-specific flags appear here.)* ### Subcommand structure {If the command has subcommands: enumerate them by name with one-line role each. Each subcommand should have its own COMMAND_SPEC if it meets the selection criteria. Otherwise: "No subcommands.")} ### Argument normalization - **Case folding:** {rule — e.g., "flag names case-sensitive; positional `` lowercased before validation"} - **Whitespace stripping:** {rule} - **Prefix expansion:** {rule for unique-prefix flag matching, or "Not supported — full flag names required."} --- ## 3. Argument Parsing Rules Beyond the grammar declared in CLI_IA. - **Order sensitivity:** {does flag order matter; can flags appear after positionals; can `--` terminate flag parsing} - **Conflict resolution:** {when two mutually-exclusive flags are both present, behavior — last-wins, first-wins, or error with which exit code from the taxonomy} - **Default-from-context:** {when a flag is absent, what context supplies a default — config-file key, environment variable, a previous-invocation marker file. Per-flag rules.} - **Auto-detection:** {behavior that depends on context — TTY check on stdout, pipe detection on stdin, presence of a marker env var like `CI`, presence of a config file. Per-rule.} - **Argument expansion:** {glob expansion rules; brace expansion if supported; file-list expansion via `@filename`; or "No expansion — arguments are taken literally."} --- ## 4. Stdin / Stdout / Stderr Composition ### Stdin - **When read:** {condition — e.g., "read when `` is `-`", "always read when stdin is not a TTY", "never read"} - **Format expected:** {format — e.g., "newline-delimited list of identifiers", "raw bytes", "JSON object matching the shape declared in section 5"} - **End-of-input detection:** {EOF / blank line / sentinel marker} - **Malformed input handling:** {which failure row in section 9 it triggers; what is salvaged before exit} - *(Or "Not read.")* ### Stdout - **Reservation:** Stdout is reserved exclusively for the command's primary output per CLI_IA's scriptability contract. No progress, no warnings, no logs ever appear on stdout. - **Mode-dependent shape:** Per-mode structural composition is detailed in section 5. - **Empty-output trigger:** {when stdout is intentionally empty — e.g., "no records match the query in machine mode"; or "Stdout is never empty in any mode."} ### Stderr - **Composition order:** {what stderr emits and in what order — e.g., "1. progress lines during execution; 2. warnings as they arise; 3. on failure, the error block; 4. on success in `--verbose`, the summary line"} - **Color rules:** {which lines colored, by DESIGN.md token name; suppression rules per capability tier — full detail lives in section 10} - **Stream interleaving:** {explicit confirmation that stdout and stderr never interleave; if the command writes both, state which is flushed when} --- ## 5. Output Modes For each output mode this command supports, a subsection. Common modes: human-readable (default), `--json`, `--yaml`, `--quiet`, `--verbose`, `--plain`. Document only the modes the command actually supports per CLI_IA's blueprint. ### Human mode (default) - **Triggering:** Default mode when stdout is a TTY and no machine flag is set. Suppressed when {condition — e.g., "stdout is not a TTY and `--json` was not requested → defaults to `--json` per CLI_IA convention"}. - **Shape:** {top-level structural composition — e.g., "header line; tabular body; footer summary line"}. Detailed table layout in section 6. - **Color usage:** Cited by token name; full rules in section 6. - **Truncation:** {what wraps, what truncates, what triggers a pager — full pager rules in section 7} ### `--json` mode - **Triggering:** `--json` flag, or auto-selected when stdout is not a TTY and the command supports it. Per CLI_IA's Output Modes section. - **Top-level shape:** ```json { "{field}": "{type}", "{field}": "{type or nested object}" } ``` - **Field naming convention:** {snake_case / camelCase per CLI_IA's wire-format conventions; cite the section if applicable} - **Pretty-print rules:** {indent, key ordering, line breaks. Default pretty-print in TTY; compact one-line per record otherwise.} - **Truncation rules:** {none — JSON is never truncated; or specific truncation policy if applicable} ### `--quiet` mode - **Triggering:** `--quiet` flag, or `TOOL_QUIET=1` env var. - **Shape:** {minimal output — e.g., "stdout: empty on success, error code only on failure; stderr: error block on failure"} - **Suppression:** {what is suppressed vs default — progress, summary lines, warnings} *(Repeat for each additional mode the command supports — `--verbose`, `--yaml`, `--plain`, `--format