/meta-planning-cli-planning

name: meta-planning-cli-planning
description: CLI specification planning frameworks. Use when a spec touches a command surface, an interactive flow, config precedence, exit codes, or output modes. Covers flag contracts, prompt flow design, precedence tables, exit-code taxonomy, TTY/piped/JSON output, error text, signals, and cross-platform concerns.

CLI Planning Frameworks

> **Quick Guide:** Specify each contract the feature actually touches — the full flag table for a new surface, the per-step prompt table for an interactive flow, a precedence table per config key, an exit code for every terminating path, and output behaviour per context (TTY, piped, `--json`, quiet, verbose). Apply a framework only when the spec touches its artifact class; a config-only change needs no prompt-flow section.

---

<critical_requirements>

CRITICAL: Before Specifying CLI Contracts

> **All specifications must be grounded in the codebase's real commands, prompts, resolvers, and constants** — reference specific files with line numbers

**(You MUST give every prompted value a non-interactive twin — a flag or config key — and state what happens with no TTY and no flag)**

**(You MUST give every terminating path an exit code named as a constant, with cancellation distinct from failure)**

**(You MUST specify output per context — TTY, piped, `--json`, quiet, verbose — and state which stream carries payload versus diagnostics)**

**(You MUST state config precedence per key as a table with merge semantics — "merged" without a rule is not a rule)**

**(You MUST apply each framework only when the spec touches its artifact class — an unused section is omitted, never filled with placeholders)**

</critical_requirements>

---

**Auto-detection:** CLI spec, command surface design, flag contract, subcommand, interactive wizard spec, prompt flow, config precedence, exit codes, JSON output mode, help text spec, signal handling spec

**When to use:**

• Specifying a new command or subcommand surface (arguments, flags, aliases)
• Specifying an interactive flow (prompt sequence, keybindings, cancellation)
• Specifying configuration keys and their resolution order
• Specifying output contracts (TTY, piped, `--json`, quiet, verbose)
• Specifying exit codes, error messages, help text, or signal handling
• Changing an existing surface (backward compatibility, deprecation path)

**When NOT to use:**

• When implementing CLI code (use the relevant CLI implementation skill)
• For backend API or frontend UI specifications (use the api/web planning skills)
• For the planning PROCESS itself — research, scope fencing, success criteria — which the PM agent carries

**Key patterns covered:**

• Command surface design (argument vs flag vs subcommand vs prompt)
• Per-flag contract fields and naming rules
• Interactive flow design (when to prompt, per-step specification)
• Configuration precedence tables and merge semantics
• Exit-code contract rules
• Output contract per context, stream split, `--json` shape
• Error-message anatomy and help-text requirements
• Signal handling and cancellation invariants
• Cross-platform concerns
• Common CLI spec failures

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Per-artifact spec section templates and a worked example specification

---

<philosophy>

Philosophy

**A CLI's public API is bigger than its code.** Flags, exit codes, output streams, and config keys are contracts that humans, scripts, and CI all branch on. A spec that leaves one of them implicit forces the developer to invent it — and an invented contract is one nobody documented.

**When specifying CLI work:**

• Read the closest existing command first; its flag names, exit constants, and output helpers are the vocabulary the spec must reuse
• Specify for all three callers at once: a human at a TTY, a script piping output, and CI with no TTY at all
• Write user-facing text verbatim — approximate wording produces an inconsistent CLI
• State cancellation and cleanup as invariants a tester can assert ("after SIGINT during upload, no `.tmp` files remain and exit code is 130")

**When NOT to specify:**

• Don't fill a framework section the feature never touches — a flag-only change needs no interactive-flow table
• Don't propose a new exit code when an existing failure class fits
• Don't design a subcommand when a flag on an existing command achieves the goal
• Don't specify implementation (handler bodies, parser wiring) — contracts, not code

**Core principles:**

• **Every prompt has a flag twin**: a value only a prompt can supply makes the command unusable in CI
• **One code per actionable failure class**: two failures a script handles identically need one code
• **stdout is payload, stderr is everything else**: progress must survive piping without polluting the pipe
• **Proportionality**: the spec's size follows the surface it changes, not the framework list

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Command Surface Design

Argument, flag, subcommand, or prompt — decided by role, not preference.

Is the value the thing the command acts ON, and required in almost every call?
├─ YES -> positional argument (app deploy <environment>)
└─ NO  -> Does it modify HOW the command behaves?
    ├─ YES -> flag (--dry-run, --force, --concurrency=4)
    └─ NO  -> Does it select a fundamentally different operation?
        ├─ YES -> subcommand (app config get | app config set)
        └─ NO  -> Is it only knowable by asking the human?
            ├─ YES -> prompt, with a flag that supplies the same value non-interactively
            └─ NO  -> derive it from config or the filesystem; do not ask

**Naming rules to specify:**

| Rule | Specify as | | ---------------- | ---------------------------------------------------------------------- | | Command names | Lowercase verb or noun-verb, matching the vocabulary alrea