Spec Kitty

└─ kitty-specs
   └─ Documentation Mission

Mission Run:

📚 Docs ↗

Work Packages: Documentation Mission

Inputs: Design documents from /kitty-specs/012-documentation-mission/ Prerequisites: plan.md (required), spec.md (user stories), research.md, data-model.md, quickstart.md

Tests: Testing tasks included for mission config validation, template structure, and generator integration per spec requirements.

Organization: Fine-grained subtasks (Txxx) roll up into work packages (WPxx). Each work package must be independently deliverable and testable.

Prompt Files: Each work package references a matching prompt file in /tasks/ generated by /spec-kitty.tasks. Lane status is stored in YAML frontmatter (lane: planned|doing|for_review|done).

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

[P] indicates the subtask can proceed in parallel (different files/components).
Include precise file paths or modules.

Path Conventions

Single project: src/specify_cli/, tests/specify_cli/
Adjust paths to match the implementation plan.

Work Package WP01: Mission Infrastructure (Priority: P0)

Goal: Create documentation mission directory structure, mission.yaml configuration, and validate mission loading. Independent Test: Mission loads successfully via get_mission_by_name("documentation"), appears in mission list. Prompt: /tasks/WP01-mission-infrastructure.md

Included Subtasks

✅ T001 Create src/specify_cli/missions/documentation/ directory structure
✅ T002 Create mission.yaml with workflow phases (discover → audit → design → generate → validate → publish)
✅ T003 Define artifacts (required: spec.md, plan.md, tasks.md, gap-analysis.md; optional: divio-templates/, generator-configs/, release.md)
✅ T004 Define path conventions (workspace: "docs/", deliverables: "docs/output/")
✅ T005 Define validation checks (all_divio_types_valid, no_conflicting_generators, templates_populated)
✅ T006 Add agent context with documentation mission instructions
✅ T007 Add command customizations for specify, plan, tasks, implement, review

Implementation Notes

1. Follow existing mission patterns from software-dev and research 2. Use domain: "other" (or extend enum if needed) 3. Mission config must pass pydantic validation 4. Version: "1.0.0"

Parallel Opportunities

None (foundation for all other work packages)

Dependencies

None (starting package)

Risks & Mitigations

Mission config schema changes breaking existing missions → Use strict validation tests
Invalid YAML syntax → Validate with yaml.safe_load() before committing

Work Package WP02: Core Mission Templates (Priority: P0)

Goal: Create spec, plan, and tasks templates following existing patterns but tailored for documentation missions. Independent Test: Templates load successfully, have required sections, follow markdown structure. Prompt: /tasks/WP02-core-mission-templates.md

Included Subtasks

✅ T008 [P] Create spec-template.md in templates/ (adapt software-dev template)
✅ T009 [P] Create plan-template.md in templates/ (adapt software-dev template)
✅ T010 [P] Create tasks-template.md in templates/ (adapt software-dev template)
✅ T011 [P] Create task-prompt-template.md in templates/ (adapt software-dev template)

Implementation Notes

1. Templates should reference documentation-specific workflow phases 2. Include placeholders for Divio types, generators, gap analysis 3. Follow existing template structure for consistency

Parallel Opportunities

All four templates can be created in parallel (different files)

Dependencies

Depends on WP01 (mission directory structure must exist)

Risks & Mitigations

Template inconsistencies → Use existing templates as reference
Missing placeholders → Validate against data-model.md entity definitions

Work Package WP03: Divio Documentation Templates (Priority: P0)

Goal: Create 4 Divio type templates (tutorial, how-to, reference, explanation) with guidance following Write the Docs best practices. Independent Test: Each template has frontmatter, required sections per Divio principles, accessibility prompts. Prompt: /tasks/WP03-divio-templates.md

Included Subtasks

✅ T012 [P] Create divio/ subdirectory in templates/
✅ T013 [P] Create tutorial-template.md (learning-oriented, step-by-step, beginners)
✅ T014 [P] Create howto-template.md (goal-oriented, problem-solving, experienced users)
✅ T015 [P] Create reference-template.md (information-oriented, technical specs, API docs)
✅ T016 [P] Create explanation-template.md (understanding-oriented, concepts, architecture)
✅ T017 Add Write the Docs guidance (accessible language, bias-free examples, heading structure)
✅ T018 Add placeholders for project-specific content ({project_name}, {target_audience}, etc.)

Implementation Notes

1. Follow research.md findings on Divio characteristics 2. Each template must have YAML frontmatter with type field 3. Include section structure appropriate to type (see data-model.md) 4. Add inline prompts guiding authors on content

Parallel Opportunities

All 4 Divio templates can be created in parallel (different files)
Write the Docs guidance (T017) and placeholders (T018) can be done alongside template creation

Dependencies

Depends on WP01 (templates/ directory must exist)

Risks & Mitigations

Template content quality → Validated against Write the Docs research
Divio type confusion → Clear descriptions in frontmatter and headings

Work Package WP04: Command Templates (Priority: P0)

Goal: Create command instruction templates for specify, plan, tasks, implement, review tailored to documentation missions. Independent Test: Command templates exist, reference documentation workflow phases, provide clear instructions. Prompt: /tasks/WP04-command-templates.md

Included Subtasks

✅ T019 [P] Create command-templates/ subdirectory
✅ T020 [P] Create specify.md (discovery questions for iteration mode, Divio types, target audience)
✅ T021 [P] Create plan.md (planning guidance for doc structure, generator config, gap analysis)
✅ T022 [P] Create tasks.md (work package generation for documentation work)
✅ T023 [P] Create implement.md (template generation, generator invocation, template population)
✅ T024 [P] Create review.md (quality checks for Divio adherence, accessibility, completeness)

Implementation Notes

1. Each command template should reference appropriate workflow phase 2. Include specific questions/checks relevant to documentation missions 3. Reference Divio types, generators, and gap analysis concepts

Parallel Opportunities

All 5 command templates can be created in parallel (different files)

Dependencies

Depends on WP01 (command-templates/ directory must exist)

Risks & Mitigations

Command instructions too vague → Use specific examples and references
Inconsistent with existing command patterns → Review software-dev command templates

Work Package WP05: Documentation Generator Protocol (Priority: P1)

Goal: Implement DocGenerator protocol and concrete generators for JSDoc, Sphinx, rustdoc. Independent Test: Each generator detects appropriate projects, configures correctly, invokes subprocess successfully. Prompt: /tasks/WP05-generator-protocol.md

Included Subtasks

✅ T025 Create src/specify_cli/doc_generators.py module
✅ T026 Define DocGenerator Protocol with detect(), configure(), generate() methods
✅ T027 Define GeneratorResult dataclass (success, output_dir, errors, warnings, generated_files)
✅ T028 Implement JSDocGenerator class (detect JS/TS files, generate jsdoc.json, invoke npx jsdoc)
✅ T029 Implement SphinxGenerator class (detect Python files, generate conf.py, invoke sphinx-build)
✅ T030 Implement RustdocGenerator class (detect Cargo.toml, invoke cargo doc)
✅ T031 Add error handling for missing generators (graceful degradation)
✅ T032 Add generator config templates (jsdoc.json.template, sphinx-conf.py.template)

Implementation Notes

1. Use subprocess.run() for generator invocation per research.md 2. Capture stdout/stderr for error reporting 3. Check for required tools (npm, sphinx-build, cargo) before invoking 4. Follow research.md patterns for config generation

Parallel Opportunities

JSDocGenerator (T028), SphinxGenerator (T029), RustdocGenerator (T030) can be implemented in parallel
Generator config templates (T032) can be created alongside generator classes

Dependencies

Depends on WP01 (mission directory structure exists)

Risks & Mitigations

Generator tool not installed → Detect and provide clear error message with installation instructions
Subprocess failures → Capture errors, log clearly, fall back to manual templates
Cross-platform compatibility → Test on macOS, Linux, Windows paths

Work Package WP06: Gap Analysis & Coverage Matrix (Priority: P1)

Goal: Implement gap analysis algorithm to audit existing documentation and identify missing Divio types. Independent Test: Analyze test documentation directory, correctly classify docs into Divio types, identify gaps. Prompt: /tasks/WP06-gap-analysis.md

Included Subtasks

✅ T033 Create src/specify_cli/gap_analysis.py module
✅ T034 Implement framework detection (detect_doc_framework for Sphinx, MkDocs, Docusaurus, Jekyll)
✅ T035 Implement Divio type classification (parse frontmatter, apply content heuristics)
✅ T036 Implement CoverageMatrix class (build matrix, get_gaps, get_coverage_percentage)
✅ T037 Implement gap prioritization logic (high/medium/low based on user impact)
✅ T038 Implement version mismatch detection (compare code API vs documented API)
✅ T039 Generate gap-analysis.md report with coverage matrix and prioritized gaps

Implementation Notes

1. Follow research.md multi-strategy approach (file structure, frontmatter, content heuristics) 2. Use conservative heuristics to avoid false positives 3. Support partial Divio adoption (not every project needs all 4 types) 4. Generate markdown table representation of coverage matrix

Parallel Opportunities

Framework detection (T034) and Divio classification (T035) can be developed in parallel
CoverageMatrix (T036) and prioritization (T037) can be developed after classification exists

Dependencies

Depends on WP01 (mission infrastructure)
Related to WP03 (understands Divio types)

Risks & Mitigations

False positives confusing users → Conservative heuristics, allow user overrides
Custom doc structures not detected → Provide manual classification options
Performance on large doc sets → Limit analysis to markdown files only

Work Package WP07: Iteration State Management (Priority: P1)

Goal: Implement iteration state persistence in meta.json to support gap-filling and multi-run documentation missions. Independent Test: State persists between runs, iteration mode and selections are restored correctly. Prompt: /tasks/WP07-state-management.md

Included Subtasks

✅ T040 Extend meta.json schema with documentation_state field
✅ T041 Store iteration_mode (initial, gap_filling, feature_specific)
✅ T042 Store divio_types_selected list
✅ T043 Store generators_configured list with config paths
✅ T044 Store last_audit_date and coverage_percentage
✅ T045 Implement state read/write functions in mission logic
✅ T046 Handle state migration from previous versions (if field missing)

Implementation Notes

1. Use JSON format consistent with existing meta.json structure 2. Follow data-model.md schema for documentation_state 3. Ensure backward compatibility (old features without documentation_state)

Parallel Opportunities

State schema definition (T040-T044) and read/write functions (T045-T046) can proceed in parallel

Dependencies

Depends on WP01 (mission infrastructure)
Depends on WP06 (gap analysis generates coverage_percentage)

Risks & Mitigations

Schema changes breaking old features → Handle missing fields gracefully
State corruption → Validate JSON schema on read

Work Package WP08: Mission Installation Migration (Priority: P1)

Goal: Write migration to install documentation mission to user projects' .kittify/missions/ directory. Independent Test: Migration detects when documentation mission missing, copies mission directory successfully. Prompt: /tasks/WP08-migration.md

Included Subtasks

✅ T047 Create src/specify_cli/upgrade/migrations/m_0_12_0_documentation_mission.py
✅ T048 Implement detect() to check if documentation mission exists in .kittify/missions/
✅ T049 Implement apply() to copy documentation mission from src/specify_cli/missions/ to .kittify/missions/
✅ T050 Test migration doesn't affect existing missions (software-dev, research)
✅ T051 Test migration is idempotent (safe to run multiple times)
✅ T052 Register migration in migration registry

Implementation Notes

1. Follow existing migration patterns (see m_0_9_1_complete_lane_migration.py) 2. Use shutil.copytree() to copy mission directory 3. Preserve file permissions and structure 4. Log migration actions clearly

Parallel Opportunities

None (migration is sequential)

Dependencies

Depends on WP01-04 (all mission files must be created first)
Depends on WP05 (generator templates included in mission)

Risks & Mitigations

Migration conflicts with user customizations → Only install if directory doesn't exist
Copy errors → Validate source exists before copying, check destination after

Work Package WP09: Testing & Validation (Priority: P1)

Goal: Comprehensive test suite for mission loading, template validation, generator integration, and gap analysis. Independent Test: All tests pass, 80%+ code coverage for new modules. Prompt: /tasks/WP09-testing.md

Included Subtasks

✅ T053 [P] Create tests/specify_cli/missions/test_documentation_mission.py (mission config loading tests)
✅ T054 [P] Test mission.yaml loads correctly and passes validation
✅ T055 [P] Test workflow phases are correct (6 phases: discover → publish)
✅ T056 [P] Test artifacts and path conventions are defined
✅ T057 [P] Create tests/specify_cli/missions/test_documentation_templates.py (template structure tests)
✅ T058 [P] Test each Divio template has frontmatter with type field
✅ T059 [P] Test each Divio template has required sections
✅ T060 [P] Test command templates exist and reference correct phases
✅ T060A [P] Test release-template.md has required sections for publish guidance
✅ T061 [P] Create tests/specify_cli/test_doc_generators.py (generator protocol tests)
✅ T062 [P] Test JSDocGenerator detects JS/TS projects correctly
✅ T063 [P] Test SphinxGenerator detects Python projects correctly
✅ T064 [P] Test RustdocGenerator detects Rust projects correctly
✅ T065 [P] Test generator graceful degradation when tool missing
✅ T066 [@pytest.mark.integration] Test end-to-end generator invocation (requires tools installed)
✅ T067 [P] Create tests/specify_cli/test_gap_analysis.py (gap detection tests)
✅ T068 [P] Test framework detection (Sphinx, MkDocs, etc.)
✅ T069 [P] Test Divio type classification from frontmatter
✅ T070 [P] Test coverage matrix calculation
✅ T071 [P] Test gap prioritization logic
✅ T072 [P] Create tests/specify_cli/upgrade/migrations/test_m_0_12_0_documentation_mission.py (migration tests)
✅ T073 [P] Test migration detects missing documentation mission
✅ T074 [P] Test migration copies mission directory correctly
✅ T075 [P] Test migration is idempotent
✅ T076 [P] Test migration doesn't affect existing missions

Implementation Notes

1. Use pytest framework consistent with existing spec-kitty tests 2. Use tmp_path fixture for file system tests 3. Mock subprocess calls for unit tests, use real invocations for integration tests 4. Parametrize tests for multiple Divio types and generators

Parallel Opportunities

All test files can be written in parallel (different modules)
Within each test file, individual test functions are independent

Dependencies

Depends on WP01-08 (all implementation must be complete to test)

Risks & Mitigations

Integration tests fail on CI without generators installed → Mark with @pytest.mark.integration, skip if tools missing
Flaky subprocess tests → Use deterministic test fixtures
Low coverage → Aim for 80%+ coverage on new modules

Work Package WP10: Documentation & Agent Updates (Priority: P2)

Goal: Update spec-kitty documentation to explain documentation missions, update all 12 agent context files. Independent Test: Documentation covers all features, agent context files mention documentation mission. Prompt: /tasks/WP10-documentation.md

Included Subtasks

✅ T077 Create user guide for documentation missions in docs/documentation-mission.md
✅ T078 Document workflow phases (discover, audit, design, generate, validate, publish)
✅ T079 Document Divio documentation types with examples
✅ T080 Document iteration modes (initial, gap_filling, feature_specific)
✅ T081 Document generator usage (JSDoc, Sphinx, rustdoc)
✅ T082 Add troubleshooting section (common errors, solutions)
✅ T083 Update CLAUDE.md with documentation mission patterns (already done in planning)
✅ T084 [P] Update all 12 agent context files (use AGENT_DIRS from m_0_9_1_complete_lane_migration.py)
✅ T085 Add example: "Run documentation mission on small Python project"
✅ T086 Add example: "Gap-fill existing documentation"

Implementation Notes

1. Follow existing spec-kitty documentation style 2. Use AGENT_DIRS constant to update all agents consistently 3. Reference quickstart.md and data-model.md for details 4. Include command examples with expected outputs

Parallel Opportunities

User guide sections (T077-T082) can be written in parallel
Agent context updates (T084) can be done in parallel across all 12 agents

Dependencies

Depends on WP01-09 (all features must be implemented and tested)

Risks & Mitigations

Documentation becomes outdated → Link to definitive sources (mission.yaml, templates)
Agent context inconsistencies → Use migration to update all agents atomically

Dependency & Execution Summary

Execution Sequence

WP01 (Mission Infrastructure)
  ↓
WP02, WP03, WP04 (Templates & Commands - can proceed in parallel)
  ↓
WP05, WP06, WP07 (Generators, Gap Analysis, State - can proceed in parallel after WP01)
  ↓
WP08 (Migration - requires WP01-07 complete)
  ↓
WP09 (Testing - requires WP01-08 complete)
  ↓
WP10 (Documentation - requires WP01-09 complete)

Parallelization Opportunities

Wave 1: WP01 alone (foundation)
Wave 2: WP02, WP03, WP04 together (all template creation)
Wave 3: WP05, WP06, WP07 together (core logic implementation)
Wave 4: WP08 alone (migration after all features ready)
Wave 5: WP09 alone (testing after implementation complete)
Wave 6: WP10 alone (documentation polish)

MVP Scope

Minimum Viable Product = WP01 + WP02 + WP03 + WP04 + WP08

This enables:

Documentation mission loads and appears in mission list
Core templates and Divio templates are available
Command templates provide guidance
Migration installs mission to user projects

Without generators, gap analysis, or comprehensive tests - suitable for manual documentation authoring using templates only.

Full Feature Set = All 10 work packages for complete functionality including automated generators and gap analysis.

Subtask Index (Reference)

Subtask ID	Summary	Work Package	Priority	Parallel?
T001	Create mission directory structure	WP01	P0	No
T002	Create mission.yaml config	WP01	P0	No
T003	Define artifacts	WP01	P0	No
T004	Define path conventions	WP01	P0	No
T005	Define validation checks	WP01	P0	No
T006	Add agent context	WP01	P0	No
T007	Add command customizations	WP01	P0	No
T008	Create spec-template.md	WP02	P0	Yes
T009	Create plan-template.md	WP02	P0	Yes
T010	Create tasks-template.md	WP02	P0	Yes
T011	Create task-prompt-template.md	WP02	P0	Yes
T012	Create divio/ subdirectory	WP03	P0	Yes
T013	Create tutorial-template.md	WP03	P0	Yes
T014	Create howto-template.md	WP03	P0	Yes
T015	Create reference-template.md	WP03	P0	Yes
T016	Create explanation-template.md	WP03	P0	Yes
T017	Add Write the Docs guidance	WP03	P0	Yes
T018	Add content placeholders	WP03	P0	Yes
T019	Create command-templates/ subdirectory	WP04	P0	Yes
T020	Create specify.md command template	WP04	P0	Yes
T021	Create plan.md command template	WP04	P0	Yes
T022	Create tasks.md command template	WP04	P0	Yes
T023	Create implement.md command template	WP04	P0	Yes
T024	Create review.md command template	WP04	P0	Yes
T025	Create doc_generators.py module	WP05	P1	No
T026	Define DocGenerator protocol	WP05	P1	No
T027	Define GeneratorResult dataclass	WP05	P1	No
T028	Implement JSDocGenerator	WP05	P1	Yes
T029	Implement SphinxGenerator	WP05	P1	Yes
T030	Implement RustdocGenerator	WP05	P1	Yes
T031	Add error handling for missing generators	WP05	P1	No
T032	Add generator config templates	WP05	P1	Yes
T033	Create gap_analysis.py module	WP06	P1	No
T034	Implement framework detection	WP06	P1	Yes
T035	Implement Divio classification	WP06	P1	Yes
T036	Implement CoverageMatrix class	WP06	P1	No
T037	Implement gap prioritization	WP06	P1	No
T038	Implement version mismatch detection	WP06	P1	Yes
T039	Generate gap-analysis.md report	WP06	P1	No
T040	Extend meta.json schema	WP07	P1	No
T041	Store iteration_mode	WP07	P1	Yes
T042	Store divio_types_selected	WP07	P1	Yes
T043	Store generators_configured	WP07	P1	Yes
T044	Store audit metadata	WP07	P1	Yes
T045	Implement state read/write functions	WP07	P1	No
T046	Handle state migration	WP07	P1	No
T047	Create migration file	WP08	P1	No
T048	Implement detect() method	WP08	P1	No
T049	Implement apply() method	WP08	P1	No
T050	Test existing missions unaffected	WP08	P1	No
T051	Test migration idempotency	WP08	P1	No
T052	Register migration	WP08	P1	No
T053	Create test_documentation_mission.py	WP09	P1	Yes
T054	Test mission.yaml loading	WP09	P1	Yes
T055	Test workflow phases	WP09	P1	Yes
T056	Test artifacts and paths	WP09	P1	Yes
T057	Create test_documentation_templates.py	WP09	P1	Yes
T058	Test Divio frontmatter	WP09	P1	Yes
T059	Test Divio sections	WP09	P1	Yes
T060	Test command templates	WP09	P1	Yes
T060A	Test release template structure	WP09	P1	Yes
T061	Create test_doc_generators.py	WP09	P1	Yes
T062	Test JSDoc detection	WP09	P1	Yes
T063	Test Sphinx detection	WP09	P1	Yes
T064	Test rustdoc detection	WP09	P1	Yes
T065	Test graceful degradation	WP09	P1	Yes
T066	Test integration (generators)	WP09	P1	No
T067	Create test_gap_analysis.py	WP09	P1	Yes
T068	Test framework detection	WP09	P1	Yes
T069	Test Divio classification	WP09	P1	Yes
T070	Test coverage matrix	WP09	P1	Yes
T071	Test gap prioritization	WP09	P1	Yes
T072	Create test_m_0_12_0_documentation_mission.py	WP09	P1	Yes
T073	Test migration detection	WP09	P1	Yes
T074	Test migration copy	WP09	P1	Yes
T075	Test migration idempotency	WP09	P1	Yes
T076	Test migration doesn't break existing	WP09	P1	Yes
T077	Create docs/documentation-mission.md	WP10	P2	No
T078	Document workflow phases	WP10	P2	Yes
T079	Document Divio types	WP10	P2	Yes
T080	Document iteration modes	WP10	P2	Yes
T081	Document generator usage	WP10	P2	Yes
T082	Add troubleshooting section	WP10	P2	Yes
T083	Update CLAUDE.md	WP10	P2	No
T084	Update all 12 agent contexts	WP10	P2	Yes
T085	Add initial project example	WP10	P2	Yes
T086	Add gap-filling example	WP10	P2	Yes

Total: 87 subtasks across 10 work packages MVP: 25 subtasks (T001-T024 + migration T047-T052) Full Feature: All 87 subtasks

Canonical Status (Generated)

WP01: done
WP02: done
WP03: done
WP04: done
WP05: done
WP06: done
WP07: done
WP08: done
WP09: done
WP10: done

Spec Kitty

Work Packages: Documentation Mission

Subtask Format: [Txxx] [P?] Description

Path Conventions

Work Package WP01: Mission Infrastructure (Priority: P0)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP02: Core Mission Templates (Priority: P0)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP03: Divio Documentation Templates (Priority: P0)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP04: Command Templates (Priority: P0)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP05: Documentation Generator Protocol (Priority: P1)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP06: Gap Analysis & Coverage Matrix (Priority: P1)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP07: Iteration State Management (Priority: P1)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP08: Mission Installation Migration (Priority: P1)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP09: Testing & Validation (Priority: P1)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Work Package WP10: Documentation & Agent Updates (Priority: P2)

Included Subtasks

Implementation Notes

Parallel Opportunities

Dependencies

Risks & Mitigations

Dependency & Execution Summary

Execution Sequence

Parallelization Opportunities

MVP Scope

Subtask Index (Reference)

Canonical Status (Generated)

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