description: "Work package task list for comprehensive end-user documentation"
Work Packages: Comprehensive End-User Documentation
Inputs: Design documents from /kitty-specs/014-comprehensive-end-user-documentation/ Prerequisites: plan.md (required), spec.md (user stories), research.md (audit findings)
Tests: Not applicable - documentation mission.
Organization: Fine-grained subtasks (Txxx) roll up into work packages (WPxx). Each work package must be independently deliverable.
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.
Path Conventions
- Documentation:
docs/with Divio subdirectories (tutorials/,how-to/,reference/,explanation/)
Work Package WP01: Audit & Directory Setup (Priority: P0)
Goal: Audit existing docs, create Divio directory structure, remove outdated content. Independent Test: Directory structure exists, outdated docs removed, audit report complete. Prompt: tasks/WP01-audit-and-setup.md
Included Subtasks
- ✅ T001 Audit all existing docs in
docs/- rate accuracy, classify by Divio type - ✅ T002 Create Divio directory structure (
tutorials/,how-to/,reference/,explanation/) - ✅ T003 Remove outdated/out-of-scope docs (testing-guidelines.md, local-development.md, etc.)
- ✅ T004 Migrate salvageable content to appropriate Divio locations (preserve workspace-per-wp.md, upgrading-to-0-11-0.md)
Implementation Notes
- Use research.md audit findings as guide
- Preserve: installation.md, workspace-per-wp.md, upgrading-to-0-11-0.md, documentation-mission.md
- Remove: contributor docs, outdated worktree model docs
Parallel Opportunities
- T002-T004 can proceed in parallel after T001 audit is reviewed
Dependencies
- None (starting package)
Risks & Mitigations
- Risk: Accidentally delete valuable content → Verify against research.md before deletion
Work Package WP02: Landing Page & Navigation (Priority: P0)
Goal: Rewrite index.md as clean landing page with Divio navigation, update toc.yml. Independent Test: index.md renders correctly with clear navigation to all 4 Divio sections. Prompt: tasks/WP02-landing-page.md
Included Subtasks
- ✅ T005 Rewrite
docs/index.mdas landing page with Divio navigation - ✅ T006 Update
docs/toc.ymlfor Divio 4-type structure - ✅ T007 Verify DocFX build with new structure
Implementation Notes
- Landing page should be concise (< 100 lines)
- Clear navigation to: Tutorials, How-To Guides, Reference, Explanations
- Keep dashboard screenshots and logo
Parallel Opportunities
- None - must complete before content WPs to establish navigation
Dependencies
- Depends on WP01 (directory structure must exist)
Risks & Mitigations
- Risk: DocFX compatibility issues → Test build before committing
Work Package WP03: Tutorials (Priority: P1) 🎯 MVP
Goal: Create learning-oriented tutorials for new users. Independent Test: A new user can follow getting-started.md and create their first feature. Prompt: tasks/WP03-tutorials.md
Included Subtasks
- ✅ T008 [P] Create
docs/tutorials/getting-started.md- installation + first spec (30 min tutorial) - ✅ T009 [P] Create
docs/tutorials/your-first-feature.md- complete 0.11.0 workflow walkthrough - ✅ T010 [P] Create
docs/tutorials/missions-overview.md- understanding software-dev, research, documentation - ✅ T011 [P] Create
docs/tutorials/multi-agent-workflow.md- coordinating multiple AI agents on parallel WPs
Implementation Notes
- Tutorials are learning-oriented, step-by-step
- Must be testable end-to-end
- Include troubleshooting for common errors
- Multi-agent tutorial must show parallel WP execution
Parallel Opportunities
- All 4 tutorials can be written in parallel (different files)
Dependencies
- Depends on WP02 (navigation structure)
Risks & Mitigations
- Risk: Tutorials become outdated quickly → Use CLI --help output as source of truth
Work Package WP04: How-To Guides - Core Workflow (Priority: P1)
Goal: Create task-oriented how-to guides for the core specify→merge workflow. Independent Test: User can follow each guide to accomplish the specific task. Prompt: tasks/WP04-howto-core-workflow.md
Included Subtasks
- ✅ T012 [P] Create
docs/how-to/install-and-upgrade.md- installation methods + upgrading - ✅ T013 [P] Create
docs/how-to/create-specification.md- /spec-kitty.specify workflow - ✅ T014 [P] Create
docs/how-to/create-plan.md- /spec-kitty.plan workflow - ✅ T015 [P] Create
docs/how-to/generate-tasks.md- /spec-kitty.tasks workflow - ✅ T016 [P] Create
docs/how-to/implement-work-package.md- /spec-kitty.implement workflow - ✅ T017 [P] Create
docs/how-to/review-work-package.md- /spec-kitty.review workflow - ✅ T018 [P] Create
docs/how-to/accept-and-merge.md- /spec-kitty.accept + /spec-kitty.merge
Implementation Notes
- How-tos are task-oriented, problem-solving
- Each guide focuses on ONE specific task
- Include command examples and expected output
Parallel Opportunities
- All 7 guides can be written in parallel (different files)
Dependencies
- Depends on WP02 (navigation structure)
Risks & Mitigations
- Risk: Command syntax changes → Generate from CLI --help
Work Package WP05: How-To Guides - Advanced Workflow (Priority: P2)
Goal: Create how-to guides for advanced features and parallel development. Independent Test: User can follow guides for dependencies, missions, dashboard, parallel work. Prompt: tasks/WP05-howto-advanced.md
Included Subtasks
- ✅ T019 [P] Create
docs/how-to/handle-dependencies.md- WP dependencies and --base flag - ✅ T020 [P] Create
docs/how-to/switch-missions.md- per-feature mission selection - ✅ T021 [P] Create
docs/how-to/use-dashboard.md- real-time kanban dashboard usage - ✅ T022 [P] Create
docs/how-to/parallel-development.md- multiple agents working on multiple WPs simultaneously
Implementation Notes
- parallel-development.md is critical - must explain:
- How to run multiple agents on different WPs
- Dependency patterns (linear, fan-out, diamond)
- When parallel is possible vs. sequential required
- Include concrete examples with commands
Parallel Opportunities
- All 4 guides can be written in parallel
Dependencies
- Depends on WP02 (navigation structure)
- Can run in parallel with WP04
Risks & Mitigations
- Risk: Parallel workflow is complex → Include diagrams and examples
Work Package WP06: Reference - Commands (Priority: P1)
Goal: Create complete reference documentation for all CLI and slash commands. Independent Test: 100% of commands documented with syntax, flags, and examples. Prompt: tasks/WP06-reference-commands.md
Included Subtasks
- ✅ T023 Create
docs/reference/cli-commands.md- all spec-kitty CLI commands - ✅ T024 Create
docs/reference/slash-commands.md- all 14 /spec-kitty.* slash commands - ✅ T025 Create
docs/reference/agent-subcommands.md- spec-kitty agent * commands
Implementation Notes
- Generate from CLI --help output for accuracy
- Include all flags, options, and examples
- Reference docs should be complete and exhaustive
Parallel Opportunities
- T023-T025 can proceed in parallel after structure defined
Dependencies
- Depends on WP02 (navigation structure)
Risks & Mitigations
- Risk: Missing commands → Verify against codebase CLI definitions
Work Package WP07: Reference - Configuration & Structure (Priority: P2)
Goal: Create reference documentation for configuration, file structure, and supported agents. Independent Test: All configuration options and file paths documented. Prompt: tasks/WP07-reference-config.md
Included Subtasks
- ✅ T026 [P] Create
docs/reference/configuration.md- docfx.json, toc.yml, meta.json - ✅ T027 [P] Create
docs/reference/environment-variables.md- SPECIFY_FEATURE, CODEX_HOME, etc. - ✅ T028 [P] Create
docs/reference/file-structure.md- .kittify/, kitty-specs/, .worktrees/ - ✅ T029 [P] Create
docs/reference/missions.md- software-dev, research, documentation details - ✅ T030 [P] Create
docs/reference/supported-agents.md- all 12 supported AI agents
Implementation Notes
- file-structure.md must explain .worktrees/ for workspace-per-WP model
- missions.md should detail each mission's phases and artifacts
- supported-agents.md should list all 12 agents with their directories
Parallel Opportunities
- All 5 references can be written in parallel
Dependencies
- Depends on WP02 (navigation structure)
Risks & Mitigations
- Risk: Configuration options change → Cross-reference with source code
Work Package WP08: Explanations (Priority: P2)
Goal: Create understanding-oriented explanations of concepts and architecture. Independent Test: User can understand "why" behind spec-kitty design decisions. Prompt: tasks/WP08-explanations.md
Included Subtasks
- ✅ T031 [P] Create
docs/explanation/spec-driven-development.md- philosophy and methodology - ✅ T032 [P] Create
docs/explanation/divio-documentation.md- why we use Divio 4-type system - ✅ T033 [P] Migrate/update
docs/explanation/workspace-per-wp.md- 0.11.0 model explained - ✅ T034 [P] Create
docs/explanation/git-worktrees.md- git worktrees for spec-kitty users - ✅ T035 [P] Create
docs/explanation/mission-system.md- why missions exist, how they work - ✅ T036 [P] Create
docs/explanation/kanban-workflow.md- planned → doing → for_review → done - ✅ T037 [P] Create
docs/explanation/ai-agent-architecture.md- how slash commands work across agents
Implementation Notes
- git-worktrees.md is critical for understanding parallel development
- What are git worktrees?
- Why does spec-kitty use them?
- How do sparse checkouts work?
- Branch isolation explained
- Explanations focus on "why" not "how"
- Link to tutorials and how-tos for practical application
Parallel Opportunities
- All 7 explanations can be written in parallel
Dependencies
- Depends on WP02 (navigation structure)
- Can reference existing workspace-per-wp.md
Risks & Mitigations
- Risk: Explanations become too technical → Focus on end-user perspective
Work Package WP09: Cross-References & Links (Priority: P3)
Goal: Add cross-references between all docs, ensure consistent navigation. Independent Test: Every doc has relevant cross-references, no broken links. Prompt: tasks/WP09-cross-references.md
Included Subtasks
- ✅ T038 Add cross-references to all tutorial docs
- ✅ T039 Add cross-references to all how-to docs
- ✅ T040 Add cross-references to all reference docs
- ✅ T041 Add cross-references to all explanation docs
- ✅ T042 Verify all internal links work
Implementation Notes
- Each tutorial should link to related how-tos and reference
- Each how-to should link to related reference and explanation
- Each explanation should link back to tutorials and how-tos
Parallel Opportunities
- T038-T041 can proceed in parallel
Dependencies
- Depends on WP03-WP08 (content must exist to link)
Risks & Mitigations
- Risk: Broken links → Automated link checking
Work Package WP10: Validation & Polish (Priority: P3)
Goal: Test DocFX build, verify all content, final polish. Independent Test: DocFX builds successfully, no broken links, clean output. Prompt: tasks/WP10-validation.md
Included Subtasks
- ✅ T043 Test DocFX build locally
- ✅ T044 Verify all links work (internal and external)
- ✅ T045 Review all docs for consistency (tone, formatting, terminology)
- ✅ T046 Update docfx.json if needed for new structure
- ✅ T047 Final review against spec.md success criteria
Implementation Notes
- Run
docfx docs/docfx.jsonto build locally - Check for warnings/errors in build output
- Verify GitHub Pages workflow will work
Parallel Opportunities
- T044-T045 can run in parallel after T043
Dependencies
- Depends on WP01-WP09 (all content must be complete)
Risks & Mitigations
- Risk: DocFX build fails → Fix issues before committing
Dependency & Execution Summary
WP01 (Audit & Setup)
↓
WP02 (Landing & Navigation)
↓
├── WP03 (Tutorials) ──────────────┐
├── WP04 (How-To Core) ────────────┤
├── WP05 (How-To Advanced) ────────┤ [Can run in parallel]
├── WP06 (Reference Commands) ─────┤
├── WP07 (Reference Config) ───────┤
└── WP08 (Explanations) ───────────┘
↓
WP09 (Cross-References)
↓
WP10 (Validation)- Sequence: WP01 → WP02 → Content WPs (parallel) → WP09 → WP10
- Parallelization: WP03-WP08 can run simultaneously with 6 agents
- MVP Scope: WP01 + WP02 + WP03 (tutorials) + WP06 (command reference)
Subtask Index (Reference)
| Subtask ID | Summary | Work Package | Priority | Parallel? |
|---|---|---|---|---|
| T001 | Audit existing docs | WP01 | P0 | No |
| T002 | Create Divio directories | WP01 | P0 | Yes |
| T003 | Remove outdated docs | WP01 | P0 | Yes |
| T004 | Migrate salvageable content | WP01 | P0 | Yes |
| T005 | Rewrite index.md | WP02 | P0 | No |
| T006 | Update toc.yml | WP02 | P0 | No |
| T007 | Verify DocFX build | WP02 | P0 | No |
| T008 | getting-started.md | WP03 | P1 | Yes |
| T009 | your-first-feature.md | WP03 | P1 | Yes |
| T010 | missions-overview.md | WP03 | P1 | Yes |
| T011 | multi-agent-workflow.md | WP03 | P1 | Yes |
| T012 | install-and-upgrade.md | WP04 | P1 | Yes |
| T013 | create-specification.md | WP04 | P1 | Yes |
| T014 | create-plan.md | WP04 | P1 | Yes |
| T015 | generate-tasks.md | WP04 | P1 | Yes |
| T016 | implement-work-package.md | WP04 | P1 | Yes |
| T017 | review-work-package.md | WP04 | P1 | Yes |
| T018 | accept-and-merge.md | WP04 | P1 | Yes |
| T019 | handle-dependencies.md | WP05 | P2 | Yes |
| T020 | switch-missions.md | WP05 | P2 | Yes |
| T021 | use-dashboard.md | WP05 | P2 | Yes |
| T022 | parallel-development.md | WP05 | P2 | Yes |
| T023 | cli-commands.md | WP06 | P1 | Yes |
| T024 | slash-commands.md | WP06 | P1 | Yes |
| T025 | agent-subcommands.md | WP06 | P1 | Yes |
| T026 | configuration.md | WP07 | P2 | Yes |
| T027 | environment-variables.md | WP07 | P2 | Yes |
| T028 | file-structure.md | WP07 | P2 | Yes |
| T029 | missions.md | WP07 | P2 | Yes |
| T030 | supported-agents.md | WP07 | P2 | Yes |
| T031 | spec-driven-development.md | WP08 | P2 | Yes |
| T032 | divio-documentation.md | WP08 | P2 | Yes |
| T033 | workspace-per-wp.md | WP08 | P2 | Yes |
| T034 | git-worktrees.md | WP08 | P2 | Yes |
| T035 | mission-system.md | WP08 | P2 | Yes |
| T036 | kanban-workflow.md | WP08 | P2 | Yes |
| T037 | ai-agent-architecture.md | WP08 | P2 | Yes |
| T038 | Cross-refs: tutorials | WP09 | P3 | Yes |
| T039 | Cross-refs: how-tos | WP09 | P3 | Yes |
| T040 | Cross-refs: reference | WP09 | P3 | Yes |
| T041 | Cross-refs: explanations | WP09 | P3 | Yes |
| T042 | Verify internal links | WP09 | P3 | No |
| T043 | Test DocFX build | WP10 | P3 | No |
| T044 | Verify all links | WP10 | P3 | Yes |
| T045 | Review consistency | WP10 | P3 | Yes |
| T046 | Update docfx.json | WP10 | P3 | No |
| T047 | Final review vs spec | WP10 | P3 | No |
<!-- status-model:start -->
Canonical Status (Generated)
<!-- status-model:end -->
- WP01: done
- WP02: done
- WP03: done
- WP04: done
- WP05: done
- WP06: done
- WP07: done
- WP08: done
- WP09: done
- WP10: done