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

Mission configuration: workflow phases, expected artifacts, commands, agent context, and validation rules. (The former v1 state-machine blocks — initial, states, transitions, guards, inputs, outputs — were retired with the mission-DSL v1 runtime in dead-port-disposition-01M1TZVN; step sequencing is authored in mission-runtime.yaml instead.)

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]

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 packs/built-in/procedures/ (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 packs/built-in/procedures/ (built-in) or
# .kittify/doctrine/procedure/ (project layer, written by `spec-kitty charter new`)

To validate project-layer doctrine artifacts:

spec-kitty charter validate .kittify/doctrine

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:

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.