/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 6-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 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 (runtime DAG):**

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

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

**Gating:** step ordering comes from the `mission-runtime.yaml` DAG (`depends_on`); work-package lane transitions are validated by the status model, and a WP cannot be claimed past its dependencies until each is `approved` or `done`. Review must be approved before acceptance.

**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 synthesis.

**Steps (runtime DAG):**

scoping → methodology → gathering → synthesis → output → accept

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

**Gating:** step ordering comes from the `mission-runtime.yaml` DAG (`depends_on`). The mission expects at least 3 documented sources before synthesis, and publication is approved at acceptance.

**Special:** Source gathering is iterative — sources are registered as they are found until the evidence base is sufficient for synthesis. 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 `packs/built-in/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:
  - id: specify
    title: Specification
    depends_on: [discovery]