Mission Specification: CLI Autocompletion
Mission Branch: cli-autocompletion-01KW6N5G Created: 2026-06-28 Status: Draft Input: User description: "add cli autocompletion so that hitting TAB will autocomplete the available commands. If subcommands are available, they should also be autocompleted"
User Scenarios & Testing (mandatory)
User Story 1 - Discover Commands With Tab Completion (Priority: P1)
A CLI user can press TAB after typing spec-kitty and see or complete the available top-level commands without consulting documentation.
Why this priority: Top-level command discovery is the core usability improvement and provides immediate value even before subcommand-specific completion is considered.
Independent Test: Can be tested by enabling completion in a supported shell, typing spec-kitty , pressing TAB, and verifying the offered completions match the available command surface.
Acceptance Scenarios:
1. Given shell completion is installed for a supported shell, When a user types spec-kitty and presses TAB, Then available top-level commands are offered for completion. 2. Given a user has typed a partial top-level command, When the user presses TAB, Then the command completes when the partial text uniquely identifies one command. 3. Given multiple top-level commands share the typed prefix, When the user presses TAB, Then the shell presents only matching commands.
User Story 2 - Discover Nested Subcommands With Tab Completion (Priority: P1)
A CLI user can press TAB after a command group and discover or complete the subcommands available within that group.
Why this priority: The CLI has nested command groups, and completion that stops at the top level would still leave users guessing through important workflows.
Independent Test: Can be tested by typing a command group such as spec-kitty agent , pressing TAB, and confirming the offered completions are valid subcommands for that group.
Acceptance Scenarios:
1. Given a top-level command has subcommands, When a user types that command followed by a space and presses TAB, Then only the valid subcommands for that command are offered. 2. Given a subcommand path has additional nested commands, When the user presses TAB after that path, Then the next level of available subcommands is offered. 3. Given a command path has no subcommands, When the user presses TAB after that path, Then command completion does not suggest unrelated commands from another command group.
Edge Cases
- Completion should not require a project to already contain a mission unless the completed command itself requires one at execution time.
- Completion should handle command names containing hyphens.
- Completion should not execute commands or mutate project state while gathering completion candidates.
- Completion should remain accurate when commands are added, removed, or renamed in the CLI.
Requirements (mandatory)
Functional Requirements
| ID | Title | User Story | Priority | Status |
|---|---|---|---|---|
| FR-001 | Top-level command completion | As a CLI user, I want TAB after spec-kitty to offer available top-level commands so that I can discover valid actions quickly. | High | Open |
| FR-002 | Partial command completion | As a CLI user, I want a unique partial command to complete when I press TAB so that I can type commands faster. | High | Open |
| FR-003 | Subcommand completion | As a CLI user, I want TAB after command groups to offer their available subcommands so that nested workflows are discoverable. | High | Open |
| FR-004 | Scoped nested suggestions | As a CLI user, I want completion suggestions to stay scoped to the current command path so that I am not shown invalid commands. | High | Open |
| FR-005 | Non-mutating completion | As a CLI user, I want completion candidate generation to avoid side effects so that pressing TAB is safe in any repository state. | High | Open |
Non-Functional Requirements
| ID | Title | Requirement | Category | Priority | Status |
|---|---|---|---|---|---|
| NFR-001 | Responsive completion | Completion suggestions for common command paths must be available within 500 ms on a typical developer machine. | Usability | High | Open |
| NFR-002 | Command coverage | Completion must cover 100% of user-facing top-level commands and command groups exposed by the CLI help surface. | Completeness | High | Open |
| NFR-003 | Shell safety | Completion candidate generation must not create, modify, or delete project files in 100% of completion invocations. | Reliability | High | Open |
| NFR-004 | Regression coverage | Automated tests must verify top-level completion and at least two nested subcommand completion paths. | Testability | High | Open |
Constraints
| ID | Title | Constraint | Category | Priority | Status |
|---|---|---|---|---|---|
| C-001 | Existing command surface | Completion must reflect the existing CLI command hierarchy rather than introducing alternate command names. | Product | High | Open |
| C-002 | Independent PR | This mission must remain independently reviewable from the short help flag, alphabetical command listing, and version output missions. | Delivery | High | Open |
| C-003 | Cross-platform CLI | The completed behavior must preserve the project's supported macOS, Linux, and Windows CLI expectations. | Compatibility | Medium | Open |
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: A user can discover all top-level commands by pressing TAB after
spec-kittyin a supported shell. - SC-002: A user can discover nested subcommands for at least two command groups by pressing TAB after the command group.
- SC-003: Completion suggestions appear within 500 ms for common command paths on a typical developer machine.
- SC-004: Completion candidate generation completes without modifying project files in all automated completion tests.
Assumptions
- "Available commands" means the user-facing command names shown by the CLI help surface.
- The implementation may rely on the CLI framework's completion support as long as the user-facing behavior meets this specification.
- Shell-specific installation instructions, if needed, may be documented as part of the implementation PR.