Create CLI

Prefix your first line with 🥷 inline. Be direct: mode detection first, then interview.

Defer To Instead

• think — general architecture decisions not specific to CLIs
• work — actual implementation after spec is approved
• review — auditing CLI code quality and security

Determine mode from user input:

Greenfield — user describes what the CLI should do, no existing code referenced. Retrofit — user points to an existing script/binary, wants to formalize the interface.

If ambiguous, ask.

Greenfield Mode

Phase 1: Fast Clarify

Ask these via AskUserQuestion (batch max 4, recommended option first):

1. Command name — what users type. Short, memorable, no hyphens if possible.
2. One-liner — what it does in ≤10 words.
3. User type — developer, ops, end-user, or CI/automation.
4. Language/framework — read references/framework-matrix.md to recommend based on:
   • Distribution needs (single binary vs npm)
   • Team expertise
   • Performance requirements
   • Ecosystem (existing deps)

Then ask: 5. Input sources — stdin, files, args, env, API? 6. Output contract — human text, JSON, both (detect TTY)? 7. Interactivity — fully interactive, --no-input mode, or non-interactive only? 8. Config model — flags only, env vars, config file, or layered?

Phase 2: Design Spec

Produce the spec using references/spec-template.md. Enforce these conventions:

Mandatory Conventions (from clig.dev)

• -h/--help on every command and subcommand
• --version on root command
• --json for machine-readable output
• --no-input disables all prompts (CI-safe)
• --quiet suppresses non-essential output
• --verbose / --debug for troubleshooting
• -f/--force skips confirmations (dangerous ops only)
• -n/--dry-run for destructive operations
• Exit codes: 0 success, 1 general error, 2 usage error, 126 permission, 127 not found, 130 SIGINT
• Errors to stderr, data to stdout
• Respect NO_COLOR env var
• Config precedence: flags > env > project config > user config > system config
• XDG base directories for config/cache/data

Design Checklist

• Command tree (max 2 levels deep unless justified)
• Every flag: long form, short form (if warranted), type, default, description
• Subcommand semantics: noun-verb or verb-noun (pick one, be consistent)
• Output format for each command (human vs JSON)
• Error messages: pattern, codes, and recovery hints
• Config file format and location
• Shell completion story
• Signal handling (SIGINT, SIGTERM)
• Platform constraints (macOS, Linux, Windows?)

Phase 3: Implementation Roadmap

After spec approval, produce:

1. Framework choice with rationale (reference framework-matrix.md)
2. Project structure — directories and key files
3. Ordered task list — each task is one PR-sized unit:
   • Task 1: Scaffold project, arg parsing, --help/--version
   • Task 2: Core command implementation (one per subcommand)
   • Task 3: Config loading (if applicable)
   • Task 4: Output formatting (human + JSON)
   • Task 5: Error handling and exit codes
   • Task 6: Shell completions
   • Task 7: Tests (unit + integration)
   • Task 8: Distribution (see references/shipping-checklist.md)
4. Shipping plan — how it gets to users (reference shipping-checklist.md)

Retrofit Mode

Phase 1: Extract Current Interface

1. Read the existing script/code
2. Map current behavior:
   • What arguments does it accept?
   • What env vars does it read?
   • What does it output (format, destination)?
   • What exit codes does it use?
   • Does it read config files?
3. Document the as-is interface in spec format

Phase 2: Gap Analysis

Compare as-is against clig.dev conventions. Produce a table:

Flag breaking changes explicitly. Ask user which breaks are acceptable.

Phase 3: Redesign Spec

Produce the target spec (same format as greenfield Phase 2), noting:

• What stays the same (backwards-compatible)
• What changes (with migration notes)
• What's new

Phase 4: Migration Roadmap

Like greenfield Phase 3, but ordered to minimize breakage:

1. Non-breaking additions first (new flags, help text)
2. Deprecation warnings for things that will change
3. Breaking changes last (with version bump)

Output Format

Save to: .kit/planning/cli-{name}-spec.md (spec) and .kit/planning/cli-{name}-roadmap.md (roadmap).

These integrate with /brainstorm → /to-plan → /work workflow.

Frontmatter:

---
title: CLI Spec — {name}
description: {one-liner}
status: draft
created: {date}
tags: [cli, {language}]
---

See references/examples.md for sample spec and roadmap outputs.