Implementation Plan: CLI Autocompletion

Branch: cli-autocompletion-01KW6N5G | Date: 2026-06-28 | Spec: spec.md Input: Feature specification from /kitty-specs/cli-autocompletion-01KW6N5G/spec.md

Summary

Enable Spec Kitty's root CLI completion surface so users can install and use shell TAB completion for top-level commands and nested subcommands. The plan is to restore the CLI framework's completion commands at the root Typer app and add focused regression tests proving the completion surface is visible and includes representative nested command paths.

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, plus targeted command invocation checks where useful Target Platform: Cross-platform command-line interface on macOS, Linux, and Windows Project Type: Single Python CLI package Performance Goals: Completion command generation remains fast enough for shell completion, under 500 ms for representative command paths Constraints: Completion generation must not mutate repository files or mission state Scale/Scope: Root command surface and nested Typer command groups 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.
  • New code must pass ruff and mypy without blanket suppressions.
  • Tests are required for the new CLI behavior.
  • No secrets, network calls, or storage migrations are introduced.

Project Structure

Documentation (this mission)

kitty-specs/cli-autocompletion-01KW6N5G/
├── spec.md
├── plan.md
├── tasks.md
└── tasks/
    └── WP01-cli-autocompletion.md

Source Code (repository root)

src/
└── specify_cli/
    └── __init__.py

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

Structure Decision: Keep the change at the root CLI construction point because completion availability is configured on the root Typer app. Add tests near existing CLI command tests.

Implementation Concern Map

IC-01 — Root Completion Surface

  • Purpose: Make the root CLI expose framework completion commands so shells can install and request completion metadata.
  • 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, tests/specify_cli/cli/commands/test_root_completion.py
  • Sequencing/depends-on: none
  • Risks: Enabling completion may change root help output by adding completion options; tests should assert behavior rather than brittle full snapshots.