Implementation Plan: Short Help Flag

Branch: short-help-flag-01KW6N7D | Date: 2026-06-28 | Spec: spec.md Input: Feature specification from /kitty-specs/short-help-flag-01KW6N7D/spec.md

Summary

Add -h as an equivalent help flag wherever --help is accepted across the Spec Kitty CLI. The implementation should centralize help-option naming at CLI construction/registration boundaries so root commands, command groups, and nested subcommands inherit the same behavior without per-command drift.

Technical Context

Language/Version: Python 3.11+ Primary Dependencies: Typer, Click, Rich, pytest Storage: N/A; no persisted data changes Testing: Focused CLI tests with Typer CliRunner for root, command group, and nested subcommand help paths Target Platform: Cross-platform command-line interface on macOS, Linux, and Windows Project Type: Single Python CLI package Performance Goals: Help requests remain immediate, under 500 ms for representative command paths Constraints: --help remains available; -h must not execute command actions Scale/Scope: Full user-facing Typer command hierarchy exposed by spec-kitty

Charter Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

  • Python 3.11+ and Typer/Rich CLI stack are preserved.
  • Tests are required for new help behavior.
  • No mission terminology regressions or new --feature flags are introduced.
  • No secrets, network calls, or storage migrations are introduced.

Project Structure

Documentation (this mission)

kitty-specs/short-help-flag-01KW6N7D/
├── spec.md
├── plan.md
├── tasks.md
└── tasks/
    └── WP01-short-help-flag.md

Source Code (repository root)

src/
└── specify_cli/
    ├── __init__.py
    └── cli/
        └── commands/
            └── __init__.py

tests/
└── specify_cli/
    └── cli/
        └── commands/
            └── test_short_help_flag.py

Structure Decision: Keep help flag behavior near root app construction and command registration because this is a CLI-wide option contract.

Implementation Concern Map

IC-01 — Universal Short Help Flag

  • Purpose: Make -h behave like --help at root, command group, and nested subcommand levels.
  • Relevant requirements: FR-001, FR-002, FR-003, FR-004, FR-005, NFR-001, NFR-002, NFR-003, NFR-004, C-001, C-002, C-003
  • Affected surfaces: src/specify_cli/__init__.py, src/specify_cli/cli/commands/__init__.py, tests/specify_cli/cli/commands/test_short_help_flag.py, docs/api/cli-commands.md, docs/api/agent-subcommands.md
  • Sequencing/depends-on: none
  • Risks: Typer command and group objects may need explicit propagation so nested commands do not retain Click's default --help only behavior.