Spec Kitty

└─ kitty-specs
   └─ Comprehensive End-User Documentation

Mission Run:

📚 Docs ↗

Implementation Plan: Comprehensive End-User Documentation

Branch: 014-comprehensive-end-user-documentation | Date: 2026-01-16 | Spec: spec.md Input: Feature specification from /kitty-specs/014-comprehensive-end-user-documentation/spec.md Mission: documentation

Summary

Create fresh, comprehensive, professional documentation for spec-kitty targeting end users. The documentation will follow the Divio 4-type system (Tutorials, How-To Guides, Reference, Explanations) and replace all existing documentation after auditing for salvageable content. Uses existing DocFX infrastructure with GitHub Pages deployment.

Technical Context

Framework: DocFX 2.76.0 (existing) Hosting: GitHub Pages via .github/workflows/docs-pages.yml Format: Markdown with YAML frontmatter Navigation: docs/toc.yml (DocFX table of contents) Search: Enabled in docs/docfx.json Assets: docs/assets/ (CSS, images)

Target Audience: End users of spec-kitty (not contributors/developers)

Constitution Check

No constitution file exists at .kittify/memory/constitution.md - proceeding without constitution constraints.

Project Structure

Documentation (this feature)

kitty-specs/014-comprehensive-end-user-documentation/
├── spec.md              # Feature specification
├── plan.md              # This file
├── research.md          # Audit findings and coverage matrix
├── meta.json            # Feature metadata
├── checklists/
│   └── requirements.md  # Spec quality checklist
└── tasks/               # Work package prompts (created by /spec-kitty.tasks)

Target Documentation Structure

docs/
├── index.md                      # Landing page with Divio navigation
├── toc.yml                       # Restructured for Divio 4-type
├── docfx.json                    # Keep existing config
├── assets/                       # Keep existing assets
│   ├── css/custom.css
│   └── images/
│
├── tutorials/                    # Learning-oriented (step-by-step)
│   ├── getting-started.md        # Installation + first feature (30 min)
│   ├── your-first-feature.md     # Complete workflow walkthrough
│   ├── missions-overview.md      # Understanding software-dev, research, documentation
│   └── multi-agent-workflow.md   # Coordinating multiple AI agents
│
├── how-to/                       # Task-oriented (problem-solving)
│   ├── install-and-upgrade.md    # Installation methods + upgrading
│   ├── create-specification.md   # /spec-kitty.specify workflow
│   ├── create-plan.md            # /spec-kitty.plan workflow
│   ├── generate-tasks.md         # /spec-kitty.tasks workflow
│   ├── implement-work-package.md # /spec-kitty.implement workflow
│   ├── review-work-package.md    # /spec-kitty.review workflow
│   ├── accept-and-merge.md       # /spec-kitty.accept + /spec-kitty.merge
│   ├── handle-dependencies.md    # WP dependencies and --base flag
│   ├── switch-missions.md        # Per-feature mission selection
│   ├── use-dashboard.md          # Real-time kanban dashboard
│   └── parallel-development.md   # Multiple agents, multiple WPs
│
├── reference/                    # Information-oriented (complete details)
│   ├── cli-commands.md           # All spec-kitty CLI commands
│   ├── slash-commands.md         # All /spec-kitty.* slash commands
│   ├── agent-subcommands.md      # spec-kitty agent * commands
│   ├── configuration.md          # docfx.json, toc.yml, meta.json
│   ├── environment-variables.md  # SPECIFY_FEATURE, CODEX_HOME, etc.
│   ├── file-structure.md         # .kittify/, kitty-specs/, docs/
│   ├── missions.md               # software-dev, research, documentation details
│   └── supported-agents.md       # All 12 supported AI agents
│
└── explanation/                  # Understanding-oriented (concepts)
    ├── spec-driven-development.md # Philosophy and methodology
    ├── divio-documentation.md     # Why we use Divio 4-type system
    ├── workspace-per-wp.md        # 0.11.0 model explained
    ├── git-worktrees.md           # Git worktrees explained for spec-kitty users
    ├── mission-system.md          # Why missions exist, how they work
    ├── kanban-workflow.md         # planned → doing → for_review → done
    └── ai-agent-architecture.md   # How slash commands work across agents

Coverage Requirements

Mandatory Coverage Areas

Area	Items	Divio Types
Setup	Installation (pip, uv, pipx, uvx), Quickstart, Upgrading	Tutorial, How-To, Reference
Missions	software-dev, research, documentation	Tutorial, Reference, Explanation
Workflow	specify → plan → tasks → implement → review → accept → merge	Tutorial, How-To
Philosophy	Spec-driven development, Divio rationale, workspace-per-WP	Explanation
Git Concepts	Git worktrees (what they are, why spec-kitty uses them), sparse checkouts, branch isolation	Explanation, How-To

Slash Commands (14 total)

Command	Must Document
`/spec-kitty.specify`	✅
`/spec-kitty.plan`	✅
`/spec-kitty.tasks`	✅
`/spec-kitty.implement`	✅
`/spec-kitty.review`	✅
`/spec-kitty.accept`	✅
`/spec-kitty.merge`	✅
`/spec-kitty.status`	✅
`/spec-kitty.dashboard`	✅
`/spec-kitty.constitution`	✅
`/spec-kitty.research`	✅
`/spec-kitty.checklist`	✅
`/spec-kitty.analyze`	✅

CLI Commands

Command	Subcommands	Must Document
`spec-kitty init`	-	✅
`spec-kitty upgrade`	-	✅
`spec-kitty implement`	-	✅
`spec-kitty accept`	-	✅
`spec-kitty merge`	-	✅
`spec-kitty dashboard`	-	✅
`spec-kitty research`	-	✅
`spec-kitty mission`	list, current, info	✅
`spec-kitty agent feature`	create-feature, check-prerequisites, setup-plan, accept, merge, finalize-tasks	✅
`spec-kitty agent tasks`	move-task, mark-status, list-tasks, add-history, finalize-tasks, validate-workflow, status	✅
`spec-kitty agent context`	(subcommands)	✅
`spec-kitty agent workflow`	implement, review	✅
`spec-kitty agent release`	(subcommands)	✅
`spec-kitty validate-encoding`	-	✅
`spec-kitty validate-tasks`	-	✅
`spec-kitty verify-setup`	-	✅
`spec-kitty list-legacy-features`	-	✅
`spec-kitty repair`	-	✅

Audit Approach

Phase 1: Inventory & Assessment

1. List all existing docs in docs/ directory 2. Rate each document:

3. Classify by Divio type (what it should be) 4. Identify salvageable content (paragraphs, examples worth keeping)

✅ Accurate (matches 0.11.0 codebase)
⚠️ Outdated (references old model, wrong paths, deprecated commands)
❌ Wrong (factually incorrect, misleading)

Phase 2: Coverage Matrix

Create a matrix: [Feature/Concept] × [Divio Type] showing:

✅ Covered adequately
⚠️ Partially covered
❌ Missing entirely

Phase 3: Content Creation

1. Remove all outdated/wrong documents 2. Migrate salvageable content to appropriate Divio type 3. Write new content for missing coverage 4. Update toc.yml for Divio structure 5. Validate all cross-references work

Key Decisions

Decision	Choice	Rationale
Framework	Keep DocFX	Already configured, GitHub Pages workflow exists
Structure	Divio 4-type folders	Clear separation, industry standard
index.md	Complete rewrite	Current version tries to be everything, too long
Audit first	Yes	Identify valuable content before deletion
Subdirectories	Yes (tutorials/, how-to/, etc.)	Better organization, clearer navigation

Complexity Tracking

No constitution violations to justify - no constitution file exists.

Dependencies

Existing DocFX configuration (docs/docfx.json)
GitHub Actions workflow (.github/workflows/docs-pages.yml)
Logo and assets (docs/assets/)

Risks

Risk	Mitigation
Breaking existing doc links	Create redirects or update all internal links
Missing functionality coverage	Use CLI `--help` as source of truth
DocFX compatibility	Test build locally before committing