Task: Generate CLIIA.md — Command-Line Information Architecture Registry

Task: Generate CLI_IA.md — Command-Line Information Architecture Registry

Objective

Produce a CLI_IA.md that serves as the single source of truth for a command-line application's information architecture: the command grammar, global flags and environment, full command-template tree, per-command blueprint (purpose, inputs, outputs, side effects, exit codes, failure matrix, interactive vs non-interactive behavior), multi-command flows, shared interactive surfaces (prompts, progress, pager, error format), exit-code taxonomy, terminal capability strategy, and bidirectional traceability from product use cases to commands. An agent or developer reading this document knows exactly what commands exist, how to invoke them, what they read and write, how they fail, and how every use case is realized on the CLI surface — without making any independent grammar, naming, or exit-code decisions. CLI_IA sits between product requirements (proposal, use cases) and per-unit CLI SPECs, the same way WEB_IA sits between product requirements and per-unit web SPECs.

Inputs

1. Product / proposal document (required) — product purpose, target users, and rationale. Sets the scope and audience frame for the IA.
2. Use cases document (required) — enumerates user interactions and jobs-to-be-done. Primary input. Every use case with a CLI surface must map to one or more commands in the inventory.
3. Architecture document (optional but recommended) — CLI framework choice (clap, cobra, commander, argparse, click, etc.), binary distribution plan, auth model, language. Informs grammar conventions and shared-surface choices. If absent, infer conservative defaults and flag non-obvious choices as open questions.
4. Existing CLI codebase (auto-discovered) — discover current commands, subcommands, and flags from source (e.g., clap derive macros, cobra command tree, commander definitions, argparse calls). Treat as reference only — CLI_IA is the target state, not a mirror of the current state.
5. Decision documents (optional) — architectural decisions that constrain the IA (e.g., "all destructive commands require confirmation unless --yes", "auth via OAuth device flow").
6. Web IA document (optional) — if WEB_IA.md exists, use-case traceability must be consistent across both documents. Every use case surfaces on web, CLI, both, or is explicitly classified as having neither surface.
7. Interface contract (optional) — if INTERFACES.md is present, per-command input/output may reference endpoints by EP-name; wire formats are owned by INTERFACES.md, not redefined here.

The user may override scope (e.g., "only the end-user CLI, not the internal admin CLI"). Support that by recording the narrowed scope in the Identity & Context section and excluding out-of-scope binaries from the inventory.

Scope note: this skill covers terminal-invoked binaries that read args / stdin / environment and write stdout / stderr and exit with a status code. Interactive REPLs are in scope. Full TUI applications with a richer UI surface than prompts and progress indicators are out of scope — declare them out of scope in Phase 1 if they arise.

Workflow

CLI IA generation proceeds in seven phases: scope, grammar and globals, inventory, per-command blueprint, flows and shared surfaces, exit codes and terminal capability, traceability and validation. Phases are sequential — later phases depend on earlier decisions — but revisit earlier phases if a later phase reveals a gap.

Phase 1: Scope & Audience

Derive from the product doc and use cases document the target CLI surface (single binary, multi-binary suite, subcommands of a host tool) and the audiences the IA serves (end user, automation / CI, contributor, operator). Record explicitly what is not in scope for this CLI_IA document — GUI wrappers, web surfaces, TUI apps with a richer UI than simple prompts. Keep audience treatment thin — named user types and their 3–7 top tasks per audience. No deep persona work.

Phase 2: Command Grammar, Global Flags & Environment

Decide grammar and globals before enumerating commands. This prevents per-command drift where each command invents its own flag names or argument conventions.

Decide:

• Grammar shape — tool <noun> <verb>, tool <verb> <noun>, or tool <verb>; subcommand depth limit
• Flag conventions — short vs long, boolean vs value, repeatable flags, = vs space between flag and value
• Positional vs flag rules — when a value is a positional argument versus a flag