spec-kitty-mission-system

# spec-kitty-mission-system

Understand how missions structure work in Spec Kitty. A mission is a
domain-specific workflow blueprint that defines what phases you go through,
what templates agents see, 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)
- **Templates** — prompts that tell agents what to do at each step
- **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:

```json
{
  "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_outline → tasks_packages → tasks_finalize → 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:

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

steps:
  - id: specify
    title: Specification
    depends_on: [discovery]
    prompt_template: specify.md
    description: Define user scenarios and acceptance criteria

  - id: plan
    depends_on: [specify]
    prompt_template: plan.md

  - id: implement
    depends_on: [tasks_finalize]
    prompt_template: implement.md
```

This is what `spec-kitty next` uses to determine step ordering.

### mission.yaml (Configuration + State Machine)

Contains both v0 configuration (artifacts, validation, agent context) and
v1 state machine definitions (states, transitions, guards):

**v0 fields (configuration):**
```yaml
name: "Software Dev Kitty"
domain: "software"
artifacts:
  required: [spec.md, plan.md, tasks.md]
  optional: [data-model.md, quickstart.md]
workflow:
  phases:
    - n