/meta-planning-cli-planning

name: meta-planning-cli-planning
description: CLI specification frameworks — flag contracts, prompt flows, config precedence, exit codes, output per context (TTY, piped, JSON), error and help text, signals and cross-platform behaviour. Use when a spec adds or changes a command surface, an interactive flow, a config key, an exit path or what a command prints.

CLI Planning Patterns

> **Quick Guide:** A command's flags, exit codes, output streams and config keys are contracts that humans, scripts and CI all branch on, so the spec states each one the feature touches — user-facing text verbatim — and leaves out the sections it does not touch. Four facts change the answer more often than taste does: a secret never takes a flag value; Ctrl+C at a key-reading prompt is a keypress, not a signal; exiting 130 is not the same as dying by SIGINT; and prompts render on stdout unless the spec moves them.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — a fill-in template for each section below, and a worked specification for a deploy command that uses them

---

Which sections the spec needs

Each section governs one kind of contract. Include it only when the spec touches that contract — a section filled with placeholders reads as a decision nobody made.

• **Adds or changes a command, argument or flag** — Command Surface, Exit-Code Contract and Output Contract (Patterns 1, 4 and 5).
• **Adds or changes a prompt or a wizard step** — Interactive Flow (Pattern 2).
• **Adds or changes a config key** — Configuration Precedence (Pattern 3), one table per key.
• **Changes only messages, help or diagnostics** — Error Messages and Help Text (Pattern 6).
• **Runs longer than an instant, or writes anything** — Signal Handling and Cancellation (Pattern 7), on top of whatever else applies.
• **Touches paths, files or terminal capabilities** — Cross-Platform Concerns (Pattern 8).

When none of these holds, the feature has no CLI contract and the spec carries no CLI section.

---

<critical_requirements>

Before specifying a CLI change

**Read the closest existing command first, and reuse its flag names, prompt helpers, config resolver, exit-code constants and output helpers.** They are the vocabulary the spec has to speak; a spec that invents its own ships a CLI with two conventions, and leaves the developer to pick which one is wrong.

**Give every prompted value a non-interactive twin, and state what happens with no TTY and no twin.** A value only a prompt can supply makes the command unusable in CI, and nobody finds out until a pipeline hangs.

**Give every terminating path an exit code, named by its constant, with cancellation kept apart from failure.** Scripts branch on the code, so a path the spec leaves open exits with a number the developer chose and nobody documented.

**Specify output for every context — TTY, piped, `--json`, quiet, verbose — and which stream carries the payload.** stdout is what a pipe captures, so anything else written there corrupts the consumer's input.

**State config precedence per key as a table, with the merge rule for arrays and objects.** "Merged" without a rule gets implemented as replace in one place and concatenate in another.

</critical_requirements>

---

**Auto-detection:** CLI spec, command surface, subcommand design, flag contract, `--json` output, `--dry-run`, `--yes`, `--no-input`, non-interactive mode, prompt flow, wizard step, exit codes, exit status 130, SIGINT, SIGTERM, `NO_COLOR`, `FORCE_COLOR`, config precedence, help text, flag deprecation

**Applies to:**

• Specifying a new command or subcommand — arguments, flags, aliases, help
• Specifying an interactive flow — prompt order, keys, cancellation, the non-interactive path
• Config keys and the order they resolve in
• Exit codes, output per context, error text and signal behaviour
• Changing an existing surface without breaking the scripts that call it

**Handled elsewhere:**

• Implementing the command — parser declarations, prompt code and rendering belong to the implementation; this skill fixes the contract they implement.
• The spec's general sections — goal, scope fence, file references and success criteria — belong to whoever writes the spec; this skill supplies the CLI sections that sit inside it.
• Contracts for an HTTP API or a UI — status codes, request shapes and UI states are planned with frameworks of their own.

---

<philosophy>

Philosophy

A CLI's public API is bigger than its code. Flags, exit codes, output streams and config keys are what humans, scripts and CI branch on, and a contract the spec leaves implicit is one the developer invents and nobody documents.

So the spec answers three callers at once: a human at a TTY, a script piping the output, and CI with no TTY at all. User-facing text is written verbatim, because approximate wording produces a CLI that words one failure five ways. Cancellation and cleanup are stated as invariants a tester can assert, not as intentions.

The spec's size follows the surface it changes. A flag-only change needs no prompt-flow table, a new exit code is proposed only when no existing class fits, and a new subcommand only when a flag on an existing command cannot do the job. Handler bodies and parser wiring stay out — the spec fixes contracts, not code.

</philosophy>

---

<decision_framework>

Argument, flag, subcommand or prompt

Decided by the value's role, not by preference:

Is the value the thing the command acts on, and supplied in almost every call?
├─ YES → positional argument (app deploy <environment>)
└─ NO  → Does it change how the command behaves?
    ├─ YES → flag (--dry-run, --force, --concurrency=4)
    └─ NO  → Does it select a different operation altogether?
        ├─ YES → subcommand (app config get | app config set)
        └─ NO  → Can only the human at the terminal supply it?
            ├─ YES → prompt, with a twin that supplies the same value
            └─ NO  → derive it from config o