dev-cli-tooling-workflow

---
name: dev-cli-tooling-workflow
description: Use to design, implement, review, or test CLI tools, flags, config precedence, terminal UX, errors, and docs.
metadata:
  version: "0.3"
  updated: "2026-06-12"
---

# CLI tooling workflow

Use this workflow when a task changes or creates a command-line interface.

## Steps

1. Map the existing command surface.
   - Entry points
   - Help output
   - Subcommands
   - Flags and environment variables
   - Config file discovery
   - Output formats
   - Exit codes

2. Define user flows.
   - Human interactive use
   - Script/CI automation
   - Debug mode
   - Offline or failure behavior

3. Design compatibility.
   - Preserve existing flags and output where scripts may depend on them.
   - Add explicit non-interactive modes for automation.
   - Keep stdout/stderr separation intentional.

4. Implement ergonomically.
   - Clear help text
   - Useful error messages
   - Stable exit codes
   - Sensible defaults
   - Shell completion or config docs when appropriate

5. Validate.
   - Run `--help` or equivalent.
   - Run at least one success path and one failure path when feasible.
   - Add tests for parsing, config precedence, and exit behavior.

## Output

Return:

1. CLI surface
2. Compatibility notes
3. Implementation or review summary
4. Commands run
5. Remaining risks

## Do not

- Do not add prompts that block automation without a bypass.
- Do not silently change stdout, JSON shape, or exit codes.
- Do not invent config precedence without checking existing docs or code.