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 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:
  - 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):

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):

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:

# 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 src/doctrine/procedures/shipped/ (shipped) or .kittify/procedures/ (project-local). Access via DoctrineService:

procedure = service.procedures.get("refactoring")
# procedure.steps → ordered list of actions
# procedure.prerequisites → what must be true before starting
# All procedures: read src/doctrine/procedures/shipped/ or .kittify/procedures/

To validate project-layer doctrine artifacts:

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 6 sections: context_sources, purpose, specialization (languages, frameworks, boundaries), collaboration (handoffs, outputs), mode_defaults, and initialization_declaration.

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:

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

# 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:

# src/doctrine/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:

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

---

Template Resolution (5-Tier Chain)

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

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:

# 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:

---

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:

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):

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