Spec Kitty

└─ kitty-specs
   └─ Documentation Sprint: Agent Management and Cleanup

Mission Run:

📚 Docs ↗

Work Packages: Documentation Sprint: Agent Management and Cleanup

Inputs: Design documents from /kitty-specs/023-documentation-sprint-agent-management-cleanup/ Prerequisites: spec.md (5 user stories, 19 FRs), plan.md (validation strategy), research.md (R1-R5 findings), quickstart.md (implementation order)

Tests: Not applicable - documentation feature with code-first validation

Organization: 36 subtasks (T001-T036) roll up into 8 work packages (WP01-WP08). Each work package is independently deliverable and focused on a specific documentation area.

Prompt Files: Each work package references a matching prompt file in /tasks/ generated by /spec-kitty.tasks. This file serves as the high-level checklist; detailed implementation guidance lives in the prompt files.

Subtask Format: `[Txxx] [P?] Description`

[P] indicates the subtask can proceed in parallel (different files/independent work).
File paths are relative to repository root.

Path Conventions

Documentation: docs/ (how-to/, reference/, tutorials/, explanation/)
Source files (validation only, read-only): src/specify_cli/
Architecture: architecture/adrs/

Work Package WP01: Agent Config Command Research (Priority: P0)

Goal: Extract command signatures, config schema, and agent mappings from source code to establish validation baseline. Independent Test: All command signatures, flags, defaults, and agent mappings documented in research notes. Prompt: /tasks/WP01-agent-config-command-research.md Estimated Size: ~250 lines

Included Subtasks

✅ T001 [P] Read and extract command signatures from src/specify_cli/cli/commands/agent/config.py
✅ T002 [P] Read and extract config schema from src/specify_cli/orchestrator/agent_config.py
✅ T003 [P] Read and extract agent mappings from m_0_9_1_complete_lane_migration.py

Implementation Notes

All three subtasks are parallel (read-only source code inspection)
Extract exact syntax: command names, arguments, flags, defaults, error messages
Extract config.yaml structure from AgentConfig and AgentSelectionConfig dataclasses
Extract all 12 agent keys and directory mappings (including 3 special cases)
Document findings in working notes for use in WP02-WP06

Parallel Opportunities

All three subtasks are independent and can be completed in any order

Dependencies

None (starting package)

Risks & Mitigations

Risk: Source code changes during implementation
Mitigation: Use git commit hash (b74536b) as reference point

Work Package WP02: Manage Agents How-To Guide - Core Commands (Priority: P1)

Goal: Create docs/how-to/manage-agents.md with all 5 agent config commands documented comprehensively. Independent Test: User can follow guide to add/remove agents, verify with status command, and understand config-driven model. Prompt: /tasks/WP02-manage-agents-how-to-core-commands.md Estimated Size: ~500 lines

Included Subtasks

✅ T004 Create docs/how-to/manage-agents.md - Overview and prerequisites section
✅ T005 Write "Agent Configuration Model" section with config-driven explanation
✅ T006 Document spec-kitty agent config list command with examples
✅ T007 Document spec-kitty agent config add command with examples and error handling
✅ T008 Document spec-kitty agent config remove command with --keep-config flag
✅ T009 Document spec-kitty agent config status command with table format
✅ T010 Document spec-kitty agent config sync command with all flags

Implementation Notes

Sequential subtasks (T004-T010): Build document section by section
Extract command syntax from WP01 research findings
Include concrete examples for each command
Document error handling behavior (e.g., invalid agent keys)
Explain output format (Rich Console tables, status indicators)
Use spec-kitty documentation style (task-oriented how-to format)

Parallel Opportunities

None (sequential document construction)

Dependencies

Depends on WP01 (requires command signatures and config schema)

Risks & Mitigations

Risk: Commands documented don't match actual CLI behavior
Mitigation: Cross-reference against spec-kitty agent config --help output

Work Package WP03: Manage Agents How-To Guide - Supplementary Content (Priority: P1)

Goal: Complete docs/how-to/manage-agents.md with agent mappings table, troubleshooting, and cross-references. Independent Test: Guide includes all 12 agent mappings with special cases highlighted, troubleshooting covers common issues, and cross-references link to relevant docs. Prompt: /tasks/WP03-manage-agents-how-to-supplementary.md Estimated Size: ~200 lines

Included Subtasks

✅ T011 Create agent directory mappings table (12 agents, special cases highlighted)
✅ T012 Write troubleshooting section for manage-agents.md
✅ T013 Add cross-reference links (ADR #6, CLI reference, supported agents)

Implementation Notes

T011: Create markdown table with columns (Agent Key, Directory Path, Notes)
Highlight special cases: copilot (.github), auggie (.augment), q (.amazonq)
T012: Common issues (orphaned dirs, missing dirs, corrupt config.yaml)
T013: Link to architecture/adrs/2026-01-23-6-config-driven-agent-management.md
Link to docs/reference/cli-commands.md#spec-kitty-agent-config
Link to docs/reference/supported-agents.md

Parallel Opportunities

T011, T012, T013 can be completed in parallel after WP02

Dependencies

Depends on WP02 (manage-agents.md must exist)
Depends on WP01 (requires agent mappings from research)

Risks & Mitigations

Risk: Agent mappings change in future versions
Mitigation: Reference research.md R3 as source of truth

Work Package WP04: Migration Guide for 0.12.0 (Priority: P1)

Goal: Provide 0.11.x → 0.12.0 upgrade guidance explaining config-driven agent management. Independent Test: Existing 0.11.x users can follow migration steps to remove unwanted agents and verify they stay deleted after upgrade. Prompt: /tasks/WP04-migration-guide-012.md Estimated Size: ~350 lines

Included Subtasks

✅ T014 [P] Read ADR #6 for migration guide content extraction
✅ T015 Create 0.12.0 migration section in upgrade-to-0-11-0.md
✅ T016 Write "What Changed" and "Why This Change" explanations
✅ T017 Write step-by-step migration workflow (5 steps with commands)
✅ T018 Add migration troubleshooting subsection

Implementation Notes

T014: Extract key points from ADR #6 (problem, solution, user workflow)
T015: Decide whether to add section to existing file or create new upgrade-to-0-12-0.md
Decision criteria: If content > 500 words, create separate file
T016: Explain problem (migrations recreated deleted dirs) and solution (config.yaml as single source)
T017: Five-step workflow with commands (status → remove → verify → upgrade → confirm)
T018: Handle common issues (orphaned dirs, missing dirs)
Keep under 500 words total (SC-002 requirement)
Link to ADR #6 for architectural details

Parallel Opportunities

T014 can start immediately
T015-T018 sequential after T014 completes

Dependencies

Loosely depends on WP02 (can reference manage-agents.md in cross-references)
Depends on WP01 (requires config schema understanding)

Risks & Mitigations

Risk: Migration steps don't match actual upgrade behavior
Mitigation: Reference ADR #6 as authoritative source

Work Package WP05: CLI Reference - Agent Config Commands (Priority: P2)

Goal: Document spec-kitty agent config command group with all 5 subcommands in CLI reference. Independent Test: Developer can consult CLI reference to find complete command syntax, flags, defaults, and examples. Prompt: /tasks/WP05-cli-reference-agent-config.md Estimated Size: ~450 lines

Included Subtasks

✅ T019 Update docs/reference/cli-commands.md - Add spec-kitty agent config main section
✅ T020 Document list subcommand in CLI reference (synopsis, options, examples)
✅ T021 Document add subcommand in CLI reference
✅ T022 Document remove subcommand in CLI reference
✅ T023 Document status subcommand in CLI reference
✅ T024 Document sync subcommand in CLI reference

Implementation Notes

T019: Insert new section after existing spec-kitty agent entry
Follow existing CLI reference format/style
Each subcommand (T020-T024) includes:
Synopsis: Command syntax
Description: What the command does
Arguments: If any (e.g., <agents> for add/remove)
Options: Flags with defaults (e.g., --keep-config, --create-missing, --remove-orphaned)
Output: What user sees (e.g., table format for status)
Examples: Concrete usage examples
Extract exact syntax from WP01 research findings
Match style of existing cli-commands.md entries

Parallel Opportunities

T020-T024 can be parallelized (different subcommands)

Dependencies

Depends on WP01 (requires command signatures)
Should reference WP02 (manage-agents.md) for detailed guidance

Risks & Mitigations

Risk: CLI reference style inconsistent with existing entries
Mitigation: Review existing cli-commands.md format before writing

Work Package WP06: Cross-Reference Updates (Priority: P2)

Goal: Add cross-references to agent config documentation from related pages (agent-subcommands, configuration, install guide, supported-agents). Independent Test: Agent config commands are discoverable via CLI help and referenced from at least 3 related documentation pages (SC-006). Prompt: /tasks/WP06-cross-reference-updates.md Estimated Size: ~280 lines

Included Subtasks

✅ T025 Update docs/reference/agent-subcommands.md - Add config to command index
✅ T026 [P] Update docs/reference/configuration.md - Add config-driven model section
✅ T027 [P] Update docs/how-to/install-spec-kitty.md - Add cross-reference to manage-agents
✅ T028 [P] Update docs/reference/supported-agents.md - Add cross-reference to manage-agents

Implementation Notes

T025: Add row to agent subcommands table: config | Manage project AI agent configuration
T026: Add new section explaining config-driven agent model, link to ADR #6 and manage-agents.md
T027: Add note after init examples: "To manage agents after initialization, see Managing AI Agents"
T028: Add intro paragraph: "Use spec-kitty agent config commands to manage active agents. See Managing AI Agents for details."
Verify cross-references use correct relative paths

Parallel Opportunities

T026, T027, T028 are independent and can be parallelized

Dependencies

Depends on WP02 (manage-agents.md must exist for linking)
Depends on WP05 (CLI reference section must exist for linking)

Risks & Mitigations

Risk: Broken relative link paths
Mitigation: Verify links resolve before committing

Work Package WP07: Jujutsu Reference Cleanup (Priority: P3)

Goal: Remove all jujutsu/jj references from documentation and fix broken links to deleted jj files. Independent Test: grep -r "jujutsu|jj\s" docs/ returns zero matches (SC-005), and all internal links resolve (SC-003). Prompt: /tasks/WP07-jujutsu-reference-cleanup.md Estimated Size: ~300 lines

Included Subtasks

✅ T029 Run grep audit for jujutsu/jj references in docs
✅ T030 Update docs/reference/cli-commands.md init section - Remove jj VCS detection mentions
✅ T031 [P] Fix broken jj links in how-to guides
✅ T032 [P] Fix broken jj links in tutorials
✅ T033 [P] Fix broken jj links in explanation articles

Implementation Notes

T029: Run grep -r "jujutsu\|jj\s\|\.jj" docs/ | grep -v ".jj/" | grep -v "jjust"
Expected: Zero matches (cleanup in commit 99b0d84)
If matches found, list for removal in T030-T033
T030: Update init command VCS detection order - Remove "jj preferred if available"
Update to reflect git-only workflow
T031-T033: Search for broken links to deleted files:
auto-rebase-and-conflicts.md
jujutsu-for-multi-agent.md
handle-conflicts-jj.md
use-operation-history.md
jujutsu-workflow.md
Remove or fix links to these files

Parallel Opportunities

T031, T032, T033 can be parallelized (different doc sections)

Dependencies

None (independent cleanup work)

Risks & Mitigations

Risk: Missed jujutsu references in obscure locations
Mitigation: Use comprehensive grep pattern, check git commit 99b0d84 for complete removal

Work Package WP08: Opportunistic Documentation Fixes (Priority: P3)

Goal: Fix obvious documentation-code mismatches discovered during validation (outdated command syntax, broken links, config examples). Independent Test: Documented commands match --help output, config examples match AgentConfig schema, and all internal links resolve. Prompt: /tasks/WP08-opportunistic-documentation-fixes.md Estimated Size: ~200 lines

Included Subtasks

✅ T034 [P] Validate command syntax in tutorials against source code
✅ T035 [P] Validate config examples against AgentConfig dataclass
✅ T036 [P] Check and fix broken internal documentation links

Implementation Notes

T034: Scan tutorials for command examples, verify against --help output
Common issues: Renamed flags, deprecated commands, outdated syntax
T035: Find config.yaml examples in docs, verify field names/types match dataclass
Check: agents.available (list[str]), agents.selection.strategy (enum), etc.
T036: Scan for text links, verify referenced files exist
Fix: Update paths, remove dead links, update to new file locations
Scope: Only "obvious" issues (don't do comprehensive audit)

Parallel Opportunities

All three subtasks are independent and can be parallelized

Dependencies

Loosely depends on WP01 (for config schema reference)

Risks & Mitigations

Risk: Scope creep (finding too many issues)
Mitigation: Limit to "obvious" mismatches only, defer others to future work

Dependency & Execution Summary

Sequential Dependencies

WP01 (Research) → WP02 (Manage Agents Core) → WP03 (Manage Agents Supplementary)
                                             ↘
WP01 → WP04 (Migration Guide)                  → WP06 (Cross-References)
                                             ↗
WP01 → WP05 (CLI Reference)

WP07 (Jujutsu Cleanup) - Independent
WP08 (Opportunistic Fixes) - Independent (loosely depends on WP01)

Parallelization Opportunities

After WP01 completes: WP02, WP04, WP05, WP07, WP08 can all start in parallel
After WP02 completes: WP03 can start
After WP02 + WP05 complete: WP06 can start
WP07 and WP08: Can run anytime (independent)

MVP Scope (Priority P1)

Minimum Viable Release: WP01 + WP02 + WP03 + WP04

Provides complete agent management how-to guide
Provides migration guide for 0.11.x users
Satisfies P1 user stories (FR-001 to FR-005)

Full Release: All WPs (WP01-WP08)

Adds CLI reference documentation (WP05)
Adds cross-references for discoverability (WP06)
Removes jujutsu references (WP07)
Fixes opportunistic issues (WP08)

Recommended Implementation Order

1. WP01 (Research) - Foundation for all doc work 2. Parallel wave 1: WP02 + WP04 + WP05 + WP07 (4 agents) 3. WP03 (after WP02 completes) 4. WP06 (after WP02 + WP05 complete) 5. WP08 (anytime, lowest priority)

Estimated Total Time: 4-6 hours (from quickstart.md)

WP01: 30 min
WP02: 1.5 hours
WP03: 30 min
WP04: 1 hour
WP05: 1 hour
WP06: 45 min
WP07: 45 min
WP08: 30 min

Subtask Index (Reference)

Subtask ID	Summary	Work Package	Priority	Parallel?
T001	Extract command signatures from agent/config.py	WP01	P0	Yes
T002	Extract config schema from agent_config.py	WP01	P0	Yes
T003	Extract agent mappings from m_0_9_1_complete_lane_migration.py	WP01	P0	Yes
T004	Create manage-agents.md overview and prerequisites	WP02	P1	No
T005	Write Agent Configuration Model section	WP02	P1	No
T006	Document `config list` command	WP02	P1	No
T007	Document `config add` command	WP02	P1	No
T008	Document `config remove` command	WP02	P1	No
T009	Document `config status` command	WP02	P1	No
T010	Document `config sync` command	WP02	P1	No
T011	Create agent mappings table	WP03	P1	Yes
T012	Write troubleshooting section	WP03	P1	Yes
T013	Add cross-reference links	WP03	P1	Yes
T014	Read ADR #6 for migration content	WP04	P1	Yes
T015	Create 0.12.0 migration section	WP04	P1	No
T016	Write "What Changed" explanation	WP04	P1	No
T017	Write migration workflow steps	WP04	P1	No
T018	Add migration troubleshooting	WP04	P1	No
T019	Add agent config main section to CLI reference	WP05	P2	No
T020	Document `list` in CLI reference	WP05	P2	Yes
T021	Document `add` in CLI reference	WP05	P2	Yes
T022	Document `remove` in CLI reference	WP05	P2	Yes
T023	Document `status` in CLI reference	WP05	P2	Yes
T024	Document `sync` in CLI reference	WP05	P2	Yes
T025	Add config to agent-subcommands index	WP06	P2	No
T026	Update configuration.md with config-driven model	WP06	P2	Yes
T027	Update install-spec-kitty.md cross-reference	WP06	P2	Yes
T028	Update supported-agents.md cross-reference	WP06	P2	Yes
T029	Run grep audit for jujutsu references	WP07	P3	No
T030	Remove jj from init VCS detection docs	WP07	P3	No
T031	Fix broken jj links in how-to guides	WP07	P3	Yes
T032	Fix broken jj links in tutorials	WP07	P3	Yes
T033	Fix broken jj links in explanation articles	WP07	P3	Yes
T034	Validate command syntax in tutorials	WP08	P3	Yes
T035	Validate config examples	WP08	P3	Yes
T036	Fix broken internal links	WP08	P3	Yes

> This task breakdown provides 8 well-sized work packages (200-500 lines each) covering all 36 subtasks. Each WP is independently deliverable, testable, and focused on a specific documentation area.

Canonical Status (Generated)

WP01: done
WP03: done
WP04: done
WP05: done
WP06: done
WP07: done
WP08: done

Spec Kitty

Work Packages: Documentation Sprint: Agent Management and Cleanup

Subtask Format: [Txxx] [P?] Description

Path Conventions

Work Package WP01: Agent Config Command Research (Priority: P0)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP02: Manage Agents How-To Guide - Core Commands (Priority: P1)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP03: Manage Agents How-To Guide - Supplementary Content (Priority: P1)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP04: Migration Guide for 0.12.0 (Priority: P1)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP05: CLI Reference - Agent Config Commands (Priority: P2)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP06: Cross-Reference Updates (Priority: P2)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP07: Jujutsu Reference Cleanup (Priority: P3)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP08: Opportunistic Documentation Fixes (Priority: P3)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Dependency & Execution Summary

Sequential Dependencies

Parallelization Opportunities

MVP Scope (Priority P1)

Recommended Implementation Order

Subtask Index (Reference)

Canonical Status (Generated)

Subtask Format: `[Txxx] [P?] Description`