Mission Types

A Mission is the canonical spec-to-merge workflow unit. Every mission is an instance of one mission type, which shapes the phases it moves through, the artifacts it produces, and the agent instructions used along the way. As of this writing there are exactly four mission types, each defined by its own mission.yaml under src/specify_cli/missions/: software-dev, research, documentation, and plan. There is no fifth type — if you're choosing, pick from this list.

How to choose

Your situation Mission type
You're building or changing software: a feature, a fix, a refactor, with tests software-dev
You need to systematically investigate a question and produce evidence-backed findings research
You're creating or overhauling user-facing or contributor documentation documentation
You need a goal-oriented plan/strategy document, not code or docs, with room to iterate plan

If your task doesn't need a spec, a review gate, or multi-session tracking at all, you may not need a Mission — see Ops vs. Missions for the Op alternative.

software-dev

Purpose: "Build high-quality software with structured workflows and test-driven development." Enforces Library-First, CLI Interface, and Test-First principles; tests are written before code.

Phases (discovery → specify → plan → implement → review → done, per the mission's v1 state machine):

  1. Discovery & Research
  2. Specification
  3. Implementation Planning
  4. Implementation
  5. Code Review
  6. Complete

The legacy workflow description frames the same arc as research → design → implement → test → review. Required artifacts: spec.md, plan.md, tasks.md; source code lands under src/.

Best for: any code change — new features, bug fixes, refactors — where tests, an implementation plan, and code review matter.

research

Purpose: "Conduct systematic research with structured methodology and evidence synthesis." Enforces research integrity and methodological rigor: all sources must be documented, findings must trace back to evidence, and at least 3 sources must be documented before synthesis can begin (event_count guard).

Phases (scoping → methodology → gathering → synthesis → output → done):

  1. Research Scoping
  2. Methodology Design
  3. Data Gathering
  4. Analysis & Synthesis
  5. Output & Publication
  6. Complete

Required artifacts: spec.md (research question/scope), plan.md (methodology), tasks.md, findings.md (synthesized findings). The mission also expects a source-register.csv documenting sources with citations, URLs, and access dates, and gates publication on approval (gate_passed).

Best for: systematic literature reviews, empirical investigations, or any question that needs a defensible, cited evidence trail rather than a single freeform answer.

documentation

Purpose: "Create and maintain high-quality software documentation following Write the Docs and Divio principles." Drives documentation as code, using the Divio four-type system (tutorial, how-to, reference, explanation) and supporting three iteration modes: initial (from scratch), gap_filling (audit existing docs and fill gaps), and feature_specific (document one component). This mission ran the mission that produced this very page.

Phases (declared under workflow.phases; this mission type does not carry a v1 state-machine block, only the legacy phase list):

  1. Discover — identify documentation needs and target audience
  2. Audit — analyze existing documentation and identify gaps
  3. Design — plan documentation structure and Divio types
  4. Generate — create documentation from templates and generators
  5. Validate — check quality, accessibility, and completeness
  6. Publish — deploy documentation and notify stakeholders

Required artifacts: spec.md, plan.md, tasks.md, gap-analysis.md. Supports generator integration (JSDoc, Sphinx, rustdoc) for API reference docs.

Best for: standing up documentation from nothing, auditing and closing gaps in existing docs, or documenting one specific component in depth.

plan

Purpose: "Goal-oriented planning with rollback for iteration." Designed for planning artifacts (strategy, structured plans) rather than code or end-user docs, with explicit revise transitions that let a draft or review step roll back to an earlier phase instead of forcing linear progress.

Phases (goals → research → structure → draft → review → done, with revise transitions from draft back to structure and from review back to draft):

  1. Define Goals
  2. Research & Analysis
  3. Structure & Outline
  4. Draft Plan
  5. Review & Approval
  6. Complete

Required artifacts: goals.md, plan.md; optional research.md and a data/ directory. Unlike the other three types, this mission type's approval gate is gate_passed("plan_approved") rather than a code-review or publication gate.

Best for: producing a goal-oriented plan or strategy document where you expect to iterate — research findings can send you back to restructuring, and review can send a draft back for another pass — before anything is implemented.

Verifying this list yourself

This page is generated from reading each mission type's own definition directly, not from memory:

ls src/specify_cli/missions/
# documentation/  plan/  research/  software-dev/
cat src/specify_cli/missions/<type>/mission.yaml

If a fifth mission type appears in that directory listing that isn't described above, this page is stale — file a docs gap rather than guessing at its purpose.

For the distinction between starting a Mission and using a lightweight Op instead, see Ops vs. Missions.

Edit this page