/spec-kitty-mission-system

name: spec-kitty-mission-system
description: >-
  Understand how Spec Kitty missions work: the 4 built-in mission types, how
  they define workflows via step contracts and action indices, how missions and
  work packages relate, how templates are resolved through the 5-tier chain,
  and how doctrine artifacts (procedures, tactics, directives) compose mission
  behavior.
  Triggers: "what missions are available", "how do missions work",
  "which mission should I use", "explain the mission system",
  "what is a mission", "change the mission", "mission templates",
  "step contracts", "action index", "mission procedures".
  Does NOT handle: runtime loop advancement (use runtime-next),
  setup or repair (use setup-doctor), governance (use charter-doctrine),
  or glossary curation (use glossary-context).

spec-kitty-mission-system

Understand how missions structure work in Spec Kitty. A mission is a domain-specific workflow blueprint that defines what steps you go through, the template each step provides, what artifacts you produce, and how to validate success.

---

How Missions Work

The Core Concept

A mission answers: "What process should we follow to achieve this goal?"

Different goals need different processes. Building a software component is different from conducting research or writing documentation. Each mission provides domain-appropriate:

• **Steps** — the ordered phases of work (specify → plan → implement → review); each step provides the prompt/content **template** agents follow
• **Artifacts** — expected outputs (spec.md, plan.md, tasks.md)
• **Guards** — conditions that must be met before advancing (e.g., spec.md must exist before planning)
• **Validation** — checks that verify the output quality
• **Agent context** — personality and instructions for the AI agent

The Hierarchy: Mission Type → Mission → Work Package → Workspace

Mission Type (e.g., software-dev)
  └── Mission (kitty-specs/042-auth-system/)
        ├── meta.json           ← links mission to mission type + target branch
        ├── spec.md             ← what we're building
        ├── plan.md             ← how we'll build it
        ├── tasks.md            ← WP breakdown
        └── tasks/
              ├── WP01.md       ← work package prompt
              ├── WP02.md
              └── WP03.md
                    └── Workspace (.worktrees/042-auth-system-lane-b/)

• **Mission Type** = the workflow blueprint (reusable across missions)
• **Mission** = a concrete thing you're building, linked to a mission type via `meta.json`
• **Work Package (WP)** = one parallelizable slice of work within a mission
• **Workspace** = an isolated git worktree owned by one execution lane

meta.json (Mission → Mission Type Link)

Every mission has a `meta.json` that records which mission type it uses:

{
  "feature_number": "042",
  "slug": "042-auth-system",
  "mission": "software-dev",
  "target_branch": "<target-branch>",
  "created_at": "2026-03-22T10:00:00Z",
  "vcs": "git"
}

The `mission` field determines which templates, guards, and validation rules apply. Default is `software-dev` if omitted.

---

The 4 Built-In Mission Types

software-dev (default)

Full software development lifecycle with work packages and code review.

**Steps:**

discovery → specify → plan → tasks → implement → review → accept

**Required artifacts:** `spec.md`, `plan.md`, `tasks.md`

**Guards:**

• `specify → plan`: `spec.md` must exist
• `plan → implement`: `plan.md` and `tasks.md` must exist
• `implement → review`: all WPs must be `approved` or `done`
• `review → accept`: review must be approved

**Agent context:** TDD practices, library-first architecture, tests before code.

**Use when:** Building components, fixing bugs, refactoring code — any work that produces code changes.

research

Systematic research with evidence-gated transitions.

**Steps (state machine):**

scoping → methodology → gathering → synthesis → output → done
                            ↑            │
                            └── gather_more (loop back)

**Required artifacts:** `spec.md`, `plan.md`, `tasks.md`, `findings.md`

**Guards:**

• `scoping → methodology`: scope document must exist
• `methodology → gathering`: methodology plan must exist
• `gathering → synthesis`: at least 3 sources documented
• `synthesis → output`: findings document must exist
• `output → done`: publication approved

**Special:** The `gathering → synthesis → gathering` loop allows iterative evidence collection. Source tracking in `source-register.csv`, evidence in `evidence-log.csv`.

**Use when:** Investigating technologies, conducting literature reviews, evaluating options, any work requiring structured evidence gathering.

plan

Goal-oriented planning with iterative refinement.

**Steps:**

specify → research → plan → review

**Use when:** Planning a project, designing architecture, creating roadmaps — any work that produces planning artifacts but not code.

documentation

Documentation creation following the Divio 4-type system.

**Workflow phases:**

discover → audit → design → generate → validate → publish

**Required artifacts:** `spec.md`, `plan.md`, `tasks.md`, `gap-analysis.md`

**Divio types:** Tutorial (learning-oriented), How-To (task-oriented), Reference (information-oriented), Explanation (understanding-oriented).

**Special:** Supports auto-generation via JSDoc, Sphinx, or rustdoc. Gap analysis identifies missing documentation by classifying existing docs and finding coverage gaps.

**Use when:** Creating docs for a project, filling documentation gaps, documenting a specific component or API.

---

Mission Type Definition Files

Each mission type lives in `src/doctrine/missions/{mission-key}/` with:

mission-runtime.yaml (Runtime DAG)

Defines steps as a directed acyclic graph with dependencies:

mission:
  key: software-dev
  name: Software Dev Kitty
  version: "2.1.0"

steps: