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:

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 → 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 packs/built-in/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]
    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:
    - name: "research"
    - name: "implement"
    - name: "review"
agent_context: |
  You are a software development agent following TDD practices.
mcp_tools:
  required: [filesystem, git]
  recommended: [code-search, test-runner]
validation:
  checks: [git_clean, all_tests_pass, kanban_complete]

v1 fields (state machine):

yaml
initial: discovery
states:
  - name: discovery
  - name: specify
  - name: plan
  - name: implement
  - name: review
  - name: done
transitions:
  - trigger: advance
    source: specify
    dest: plan
    conditions:
      - 'artifact_exists("spec.md")'
guards:
  has_spec:
    description: "Specification document must exist"
    check: 'artifact_exists("spec.md")'

mission-steps/ (Agent Prompts)

Markdown files shown to agents at each step:

• mission-steps/software-dev/specify/prompt.md — Instructions for writing the specification
• mission-steps/software-dev/plan/prompt.md — Instructions for creating the implementation plan
• mission-steps/software-dev/tasks/prompt.md — Instructions for creating tasks and work packages
• mission-steps/software-dev/implement/prompt.md — Instructions for implementing a work package
• mission-steps/software-dev/review/prompt.md — Instructions for reviewing a work package
• mission-steps/software-dev/accept/prompt.md — Instructions for final acceptance validation

templates/ (Content Templates)

Scaffolding files for artifacts:

• spec-template.md — Starting structure for spec.md
• plan-template.md — Starting structure for plan.md
• task-prompt-template.md — Starting structure for WP prompt files
• tasks-template.md — Starting structure for tasks.md

Doctrine Composition Layer

Missions are backed by structured doctrine artifacts that define action behavior and link to reusable knowledge.

MissionStepContract (Action Contracts)

Each public action (specify, plan, implement, review) has a step contract that defines its internal structure:

yaml
# implement.step-contract.yaml
id: implement
action: implement
mission: software-dev
schema_version: "1.0"
steps:
  - id: setup-workspace
    description: "Create or enter the WP workspace"
  - id: implement-code
    description: "Write code following governance constraints"
    delegates_to:
      kind: tactic
      candidates: [tdd-red-green-refactor, zombies-tdd]
  - id: validate
    description: "Run tests and lint checks"

The delegates_to field links a step to doctrine artifacts. This is how mission behavior connects to the knowledge layer: the contract says what to do, the referenced tactic/directive/procedure says how.

Procedure (Reusable Workflow Primitives)

Procedures are multi-step doctrine artifacts with prerequisites and ordered steps. They are the reusable building blocks that step contracts delegate to. Each procedure describes a complete mini-workflow (e.g., a refactoring sequence, a test-first bug fix, a situational assessment).

Procedures live in packs/built-in/procedures/ (shipped) or .kittify/procedures/ (project-local). Access via DoctrineService:

python
procedure = service.procedures.get("refactoring")
# procedure.steps → ordered list of actions
# procedure.prerequisites → what must be true before starting
# All procedures: read packs/built-in/procedures/ or .kittify/procedures/

To validate project-layer doctrine artifacts:

bash
spec-kitty doctrine validate .kittify/

Agent Profiles (Role-Based WP Assignment)

Agent profiles define roles, specializations, and boundaries for work package assignment. Each profile has these sections: purpose, specialization (languages, frameworks, boundaries), collaboration (handoffs, outputs), mode_defaults, and initialization_declaration. Doctrine references are authored on the top-level *-references fields (directive-references, tactic-references, toolguide-references, styleguide-references); the retired context-sources block was removed (mission doctrine-drg-silent-drop-boundary; #3629).

Profiles do not use relationship fields such as specializes_from. Lineage and specialization relationships belong in the doctrine DRG; profile matching uses weighted signals (language, framework, file path, keyword, exact-id).

The mission.yaml task_types section maps WP actions to agent roles:

yaml
task_types:
  implement:
    agent_role: implementer
  review:
    agent_role: reviewer
  plan:
    agent_role: planner

bash
# Discover activated profiles (--all for the full on-disk catalog)
spec-kitty agent profile list

# Inspect a profile's boundaries and initialization context (resolved
# through DRG lineage and context sources)
spec-kitty agent profile show <profile-id>

There is no separate hierarchy command: specialization lineage is declared in the doctrine DRG (see the org-pack DRG YAML / generated graph.yaml); profile show displays the resolved result.

Action Indices (Doctrine Scoping)

Each mission action has an index that declares which doctrine artifacts are relevant to that step:

yaml
# packs/built-in/missions/software-dev/actions/implement/index.yaml
action: implement
directives: [TEST_FIRST]
tactics: [tdd-red-green-refactor, zombies-tdd, acceptance-test-first]
styleguides: [python-implementation]
toolguides: []
procedures: [implementation-handoff]

The charter context builder uses these indices to scope what gets injected into the agent prompt at each step. This prevents agents from seeing review-scoped doctrine during implementation and vice versa.

6 Guard Primitives

Guards block step transitions until conditions are met:

| Guard | Syntax | What it checks | |---|---|---| | artifact_exists | artifact_exists("spec.md") | File exists in mission dir | | gate_passed | gate_passed("review_approved") | Event exists in mission event log | | all_wp_status | all_wp_status("approved_or_done") | Every WP is in the specified lane, or in any lane in a named accepted-ready set | | any_wp_status | any_wp_status("for_review") | At least one WP is in the lane | | input_provided | input_provided("architecture") | Input was provided to runtime | | event_count | event_count("source_documented", 3) | Minimum event count in log |

Guards are composed as conditions lists on transitions. All conditions in the list must pass for the transition to fire.

Template Resolution (6-Tier Chain)

When a command prompt is needed, spec-kitty resolves the current doctrine mission-step prompt:

| Scope | Path | Purpose | |---|---|---| | Package | packs/built-in/missions/mission-steps/<mission>/<step>/prompt.md | Built-in default | | Project doctrine | .kittify/doctrine/... | Project-local doctrine overrides where supported | | Org doctrine | org doctrine pack | Shared organization doctrine where installed |

The package default is always the fallback. Legacy command-templates paths are pre-migration artifacts, not the current package layout.

Selecting a Mission Type

The mission type is set when you create a mission with /spec-kitty.specify. It's recorded in meta.json and cannot be changed after creation.

Commands:

bash
# List available mission types
spec-kitty mission-type list
spec-kitty doctrine mission-type list

# Specify a mission with a specific mission type
spec-kitty specify --mission-type research "What are the best auth patterns?"

# Check which mission type a mission uses
cat kitty-specs/<mission-slug>/meta.json | jq .mission

Decision guide:

| If you're... | Use mission type | |---|---| | Building a component, fixing a bug, refactoring | software-dev | | Investigating, evaluating options, literature review | research | | Planning architecture, roadmaps, design docs | plan | | Writing tutorials, API docs, how-to guides | documentation |

The Two State Machines

Missions involve two orthogonal state machines:

Mission-type state — which phase of the workflow are we in?

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

Managed by mission-runtime.yaml DAG and spec-kitty next.

WP status — where is each work package in its lifecycle?

planned → claimed → in_progress → for_review → in_review → approved → done
                                                    ↕
                                                 blocked / canceled

Managed by the status model (append-only event log).

Together they determine what spec-kitty next returns: "we're in the implement phase, WP01 is done, WP02 is in_progress, WP03 is planned — your next action is implement WP03."

Runtime Bootstrap

On every CLI invocation, ensure_runtime() runs:

1. Checks ~/.kittify/cache/version.lock — if version matches, fast path (< 100ms)
2. If stale: copies mission files from installed package to ~/.kittify/missions/
3. Uses file locking to prevent concurrent corruption

This ensures ~/.kittify/ always matches the installed spec-kitty version.

CLI Surface Contract

agent action implement / agent action review — text-only output

The canonical agent surfaces spec-kitty agent action implement <wp_id> and spec-kitty agent action review <wp_id> return plain text only. They do not accept a --json flag. Passing --json to either command produces a Typer exit-2 error.

The top-level command spec-kitty implement does accept --json, but it is the internal allocator used by the harness — not the surface intended for agent prompt steps. Do not invoke spec-kitty implement --json from prompt steps; that is an internal-only surface. Use spec-kitty agent action implement <wp_id> for work-package execution.

Summary:

| Command | --json? | Intended for | |---|---|---| | spec-kitty agent action implement <wp_id> | no | Agent prompt steps | | spec-kitty agent action review <wp_id> | no | Agent prompt steps | | spec-kitty implement <wp_id> | yes | Internal harness allocator only |

If you need structured output from the implement action, use spec-kitty agent tasks status --json to query the resulting WP state after the action completes.

Workspace recovery

If a worktree is missing or corrupted, use the real recovery command (post-#2135, the former worktree repair subcommand no longer exists):

bash
spec-kitty doctor workspaces --fix

This removes husk directories (entries in .worktrees/ that lack a .git entry) without touching registered live worktrees.

References

• references/mission-comparison-matrix.md -- Side-by-side comparison of all 4 mission types