meta-planning-cli-planning

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 - Per-artifact spec section templates and a worked example specification

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

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:

Per-flag contract the spec must carry:

Backward compatibility. When changing an existing surface, state for every removed or renamed flag: what old invocations do now, whether a deprecation warning is emitted on stderr, which release removes the alias, and whether the exit code changes. A silently changed flag breaks scripts that nobody will report.

Why this matters: an undefined flag contract makes the developer invent a parser declaration, and every invention is a convention the CLI does not have.

Pattern 2: Interactive Flow Design

Prompt only what cannot be derived, and give every step a complete contract.

Can the value be derived from config, a flag, or the filesystem?
├─ YES -> derive it; do not prompt
└─ NO  -> Is stdin a TTY?
    ├─ NO  -> fail with a usage error naming the flag that supplies it
    └─ YES -> Is the action destructive or expensive?
        ├─ YES -> prompt for confirmation, skippable with --yes
        └─ NO  -> prompt for the value, pre-filled with the best default

Per-step specification:

Keyboard interactions to specify explicitly when a step adds any beyond the defaults: arrow keys, Space, Enter, Tab, Escape, Ctrl+C, and any single-letter accelerator. State whether accelerators are case sensitive, and whether they are inert when a filter or text input has focus. An accelerator that swallows a keystroke a text field needed is the classic wizard bug.

Terminal-size constraints: state the minimum usable width and what degrades first (truncate labels, drop hint column, stack instead of columns). State whether the flow redraws on resize. If the flow renders a grid or table, give the column priority order for narrow terminals.

Resumability: state whether partial progress is persisted, where, and what a re-run does with it — resume silently, prompt to resume, or discard. If nothing is persisted, say so; that is a decision, not an omission.

Pattern 3: Configuration Precedence

Specify config as a table per key, never as prose. The resolution order is the contract:

Rules the spec must state:

• Per-key layer participation. Not every key exists at every layer. Name the layers each key participates in, and the exact key or flag name at each.
• Merge semantics. Scalars: first non-undefined wins. Arrays and objects: state replace or merge explicitly, per key. "Merge" without a rule is the most common source of config bugs.
• Absent versus empty. State whether an explicitly empty value (--tag "", tags: []) overrides a lower layer or is treated as unset.
• Discovery. For project config: which filenames, searched from where, walking up how far, and what happens when two match.
• Validation timing. Whether the config is validated on load or on use, and which exit code an invalid config produces.
• Write-back. If the command writes config, state which file and layer it writes, whether it preserves comments and key order, and whether it writes atomically.

Pattern 4: Exit-Code Contract

Every terminating path gets a code, and every code gets a documented meaning. Scripts branch on these; they are as much a public API as the flags.

Rules the spec must state:

• Read the codebase's existing exit-code constants first and reuse them. Propose a new code only when no existing class fits, and say what it means.
• One code per failure class the caller can act on differently. Two failures a script would handle identically do not need two codes.
• Cancellation is not an error. Ctrl+C and a declined confirmation get their own codes, distinct from failure.
• Partial success needs an explicit decision: fail the whole run, or succeed with a warning and a code that says "some items failed".
• --dry-run exits 0 when the plan is valid, and the same failure code as a real run when it is not.
• Name the constant, not the number, when the codebase has constants.

Pattern 5: Output Contract

Stream split: stdout carries the data the caller asked for. stderr carries everything else — progress, warnings, diagnostics, prompts. A command whose output is piped must still show its progress, and must not pollute the pipe with it.

Mode matrix to fill in per command:

Rules the spec must state:

• --json schema. Give the exact object shape, including the error shape. --json must emit valid JSON on failure too, and must never interleave log lines into stdout.
• Colour detection. Honour NO_COLOR and FORCE_COLOR and the TTY check. State the fallback glyphs when Unicode is unavailable.
• Quiet and verbose ladder. State exactly which messages each level suppresses or adds. Whether they combine with --json and which wins.
• Progress thresholds. Which operations warrant a spinner (typically anything over ~500ms), and what the spinner says at each phase.
• Idempotent re-runs. State what the output says when there is nothing to do — silence is a decision, "Already up to date." is usually better.

Pattern 6: Error Messages and Help Text

Message anatomy — specify all four parts, verbatim:

1. What failed — the operation, named the way the user named it
2. Why — the underlying cause, in the user's vocabulary, not the exception's
3. How to fix — a concrete next command or edit
4. Where to look — the file path, config key, or doc reference when one exists

BAD:  Error: ENOENT
GOOD: Error: config file not found at ./app.config.ts.
      Run 'app init' to create one, or pass --config <path>.

Rules the spec must state:

• Errors go to stderr; never to stdout.
• Never print a raw stack trace by default. State which flag or env var reveals it.
• Unknown command or flag: state whether a "did you mean" suggestion is offered and the matching rule.
• Validation errors name the offending value and the accepted set.
• Errors caused by another tool quote that tool's message rather than paraphrasing it.

Help text to specify per command: one-line summary, usage line with argument arity, argument descriptions, flags grouped and ordered, at least two worked examples of real invocations, and any related commands. State whether the command's help is reachable as --help, -h, and help <command>.

Pattern 7: Signal Handling and Cancellation

Specify for every command that runs longer than an instant, or writes anything:

State cleanup as an invariant the tester can assert: "after SIGINT during upload, no .tmp files remain under the target directory and exit code is 130."

Pattern 8: Cross-Platform Concerns

Include the ones that apply; state explicitly when a concern is out of scope:

• Paths: join with the platform separator, never string concatenation. State whether user-supplied paths are resolved relative to CWD or the config file.
• Home directory: resolve via the platform API, not $HOME. State the config location per platform when they differ.
• Case sensitivity: whether a name collision that is distinct on Linux and identical on macOS is an error.
• Line endings: what the command writes, and whether it preserves what it reads.
• Shell quoting: any example in help text must be valid in the shells the project supports.
• Executable permissions: any file the command creates that must be executable.
• Long paths and reserved names: relevant on Windows for generated file names.
• Colour and Unicode support: the fallback for terminals that lack them.

<decision_framework>

Decision Framework

Which Spec Sections Does This Feature Need?

Apply a framework only when the spec touches its artifact class. The per-artifact section templates live in examples/core.md.

Does the spec add or change a command, argument, or flag?
├─ YES → Command Surface section (Pattern 1) + Exit Codes (Pattern 4) + Output Contract (Pattern 5)
└─ Does it add or change prompts or a wizard step?
    ├─ YES → Interactive Flow section (Pattern 2), each prompt with its flag twin
    └─ Does it add or change config keys?
        ├─ YES → Configuration Resolution section (Pattern 3), one table per key
        └─ Does it only change messages, help, or diagnostics?
            ├─ YES → Error Messages / Help Text section (Pattern 6) with verbatim text
            └─ NO  → None of these frameworks applies; do not force one in

Always applicable when the command runs long or writes: Signal Handling (Pattern 7). Always worth a pass when files or paths are involved: Cross-Platform (Pattern 8).

Common Spec Failures

</decision_framework>

<red_flags>

RED FLAGS

High Priority Issues (a spec with one of these is incomplete):

• A prompted value with no flag or config twin
• A terminating path with no exit code, or a magic number instead of a constant
• Output described only for the TTY case
• A config key whose merge semantics are "merged"
• Error or prompt text described rather than written verbatim
• A long-running or writing command with no cancellation invariant

Medium Priority Issues:

• A new exit code where an existing failure class fits
• A new subcommand where a flag on an existing command would do
• A renamed or removed flag with no deprecation path
• Help text without worked examples
• A --json mode with no error shape

Common Mistakes:

• Designing flags without reading sibling commands (short-form collisions)
• Treating cancellation as an error instead of its own exit class
• Specifying spinner text but not the piped-output equivalent
• Leaving "nothing to do" output unspecified on idempotent re-runs

Gotchas & Edge Cases:

• An accelerator key that is live while a text input has focus swallows typed characters
• --dry-run must share the real run's failure codes or CI cannot trust it
• An explicitly empty value (--tag "") and an absent one are different inputs; decide which wins
• Second Ctrl+C during cleanup needs its own answer

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

All specifications must be grounded in the codebase's real commands, prompts, resolvers, and constants

(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)

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

Failure to specify these contracts produces CLIs whose developers invent flags, guess exit codes, break piped and CI callers, and leave half-written files behind on Ctrl+C.

</critical_reminders>