mission-driver

name

mission-driver

description

Create roadmaps and mission configs, then drive the mission-driver AI dev-loop engine. mission-driver lives at tools/mission-driver/ — it reads missions/<name>.json and loops CHECK → REVIEW_PLANS → EXEC_PLANS → DRAFT_PLANS → DEEP_AUDIT until the roadmap is done or the audit budget is exhausted. Use this skill when the user wants to: (1) plan a development goal as a roadmap ("create roadmap", "make a roadmap", "new dev goal"); (2) bootstrap a mission config from an existing roadmap ("create mission", "config mission", "draft mission"); (3) launch / resume / monitor a mission ("run mission", "start mission-driver", "continue mission", "mission stuck"); (4) mentions "roadmap", "mission-driver", "dev loop", "auto development", "AGE loop". Trigger words: roadmap, mission, mission-driver, dev loop, draft-mission, list-missions.

mission-driver — Roadmap creation and mission execution

This skill operates the tools/mission-driver/ engine shipped with this repo. It is stack-agnostic: it works for Node, Python, Java, Go, or any project whose verification commands can be expressed as shell strings. Project-specific values (test command, module layout, commit format) are read from missions/base.json, docs/context/project-context.md, and AGENTS.md rather than hardcoded here.

Companion docs (read on demand, not all at once):

• tools/mission-driver/docs/user-manual.zh.md / user-manual.en.md — full training handbook
• tools/mission-driver/README.md — command cheat-sheet
• tools/mission-driver/EXECUTION-PRINCIPLE.md — internal execution deep dive
• tools/mission-driver/TROUBLESHOOTING.md — diagnostics when stuck
• docs/plans/00-plan-authoring-and-execution-guide.md — plan format and lifecycle
• references/mission-config-schema.md — full mission.json schema (companion to this file)
• references/roadmap-template.md — roadmap structure with annotated example

Mental model

A mission = a fixed config (missions/<name>.json) for one development goal. The engine reads it and enters a loop:

CHECK (health: tests/build pass)
  → REVIEW_PLANS (review draft plans → promote active; empty forEach = passthrough)
  → EXEC_PLANS (one plan-execution subflow per active plan:
                   EXECUTE → CLOSURE_SCRIPT_CHECK → CLOSURE_AUDIT → BUILD_VERIFY)
  → DRAFT_PLANS (draft 1-3 plans from roadmap → sub-agent review → promote active)
  → [loop back to REVIEW_PLANS]
  → nothing to draft → DEEP_AUDIT (multi-audit + open-audit → draft remediation plans)
                       → REVIEW_PLANS (execute audit-created plans)
  → ... until maxAuditRounds exhausted and nothing outstanding

Key facts:

• Roadmap precedes mission. The draft command will generate both roadmap and missions/<name>.json from a single description, but only after the brief stage confirms scope is clear.
• missions/<name>.json is pure static config — no runtime state. The engine's runtime state lives in _tmp/<runDir>/run-state.json.
• Every AI step is a child opencode run process; logs land in _tmp/<ts>-mission-driver/.
• Plan lifecycle: draft → (REVIEW_PLANS) → active → (EXEC_PLANS) → completed. Subflow plan-execution runs once per active plan.
• Ctrl-C / SIGTERM is caught by main.js for graceful process-tree cleanup.
• Plan format is a fixed contract enforced by tools/mission-driver/src/plan-check.mjs.

Decision: is mission-driver the right tool?

Use it when	Don't use it when
Task takes >1 hour and has clear acceptance criteria	Quick fix, <30 min
Multi-step work: docs + code + tests must stay in sync	Rename a file
Roadmap has 3+ work items needing audit closure	One-off script
Refactor / tech-debt cleanup with verification gates	Exploratory prototyping
Feature implementation from an FSD or design doc	"Make it look nicer" without measurable criteria

If unsure, ask the user to estimate effort and acceptance criteria first.

Workflow A: Create a Roadmap

Trigger: user gives a development goal (e.g. "refactor the auth module", "implement the reporting feature from the FSD"), and no roadmap exists yet.

A.1 Pre-flight

1. Read docs/context/project-context.md once to learn the project's stack, verification commands, and AI-block conditions.
2. Read docs/backlog/00-roadmap-authoring-guide.md (or the project's equivalent) for the controlling roadmap structure rules.
3. Scan docs/backlog/ for existing related roadmaps; scan docs/analysis/, docs/requirements/, docs/design/, docs/input/ for source material (FSD, bug list, optimization checklist).
4. Scan missions/*.json to see if a mission already targets this goal.

A.2 Write the roadmap

Path: docs/backlog/{slug}-roadmap.md where {slug} is a short kebab-case topic (e.g. auth-refactor, q3-tech-debt).

Follow the structure in references/roadmap-template.md. Core rules:

• Status-section header is a hard contract: the dynamic status block MUST be headed exactly ## Work Item Status (legacy ## 阶段状态 also accepted). The monitor dashboard's parser (tools/mission-driver/src/roadmap-check.mjs) matches ONLY these headers — any paraphrase (## Work Items, ## Tasks, …) yields zero phases and the dashboard shows "暂无 roadmap 数据". The engine's terminal reconciliation reads the same parser, so a wrong header also breaks the false-failure downgrade path.
• Work-item granularity: each todo/planned/done item must be completable by a single execution plan (~5-15 files, 200-500 lines, 1-4 phases). Larger initiatives must be split into multiple items.
• Single dynamic state block: maintain state only in the Work Item Status section. Do not duplicate status anywhere else.
• Human/AI division of labor: humans set items and order; AI takes the first todo item, drafts/executes plans, marks done after closure audit passes.
• No implementation steps: roadmap is an index layer, not an execution plan. Stage details list deliverable scope, never checkboxes.
• Dependency graph: use Mermaid graph TD; conflicts with the stage table resolve in favor of the table.

An annotated example is in references/roadmap-template.md.

A.3 Self-check

After writing, verify against the anti-pattern list in references/roadmap-template.md:

• Status section header is exactly ## Work Item Status (parser contract — wrong wording = empty dashboard)
• Each work item is completable by one plan (no epic-sized items)
• Only one dynamic state block (the Work Item Status section)
• Stage details have no checkboxes or implementation steps
• Framework/platform reuse explicitly noted (avoid rebuilding existing capabilities)
• Dependency graph matches the stage table
• Owner-doc references are accurate (don't restate owner-doc business rules)

Parser smoke-test (recommended): confirm the roadmap parses to non-zero phases before handing off to Workflow B:

node --input-type=module -e "import{parseRoadmapMarkdown}from'./tools/mission-driver/src/roadmap-check.mjs';import{readFileSync}from'node:fs';const r=parseRoadmapMarkdown(readFileSync('docs/backlog/<slug>-roadmap.md','utf8'));console.log('phases:',r.phases.length,'progress:',r.overallProgress)"

If phases: 0, the status-section header is wrong — fix it to ## Work Item Status.

Record the roadmap file path — Workflow B needs it.

Workflow B: Create the mission config

Trigger: roadmap exists, need a missions/<name>.json to drive the loop.

B.1 Two creation paths

Path 1 (recommended): use draft to auto-generate

./tools/mission-driver.sh draft "<goal description>" \
  --target-file <path/to/requirements-or-fsd.md> \
  [--flow-hint mission-driver] \
  [--skip-brief]   # collapse to single-stage draft (skip scope-gate brief)

The draft command runs two stages:

1. Brief stage: a mission-brief agent judges scope clarity and emits a brief at docs/backlog/<slug>-brief.md. If scope is unclear, it returns <BRIEF_GATE>blocked</BRIEF_GATE> and stops — fix the open questions in the brief, then re-run.
2. Draft stage: a draft-mission agent reads the brief + AGENTS.md + project structure and emits mission.json + Roadmap doc.

Always review the generated mission.json before running it.

Path 2: hand-write when draft's output is unsatisfactory or precise control is needed. See references/mission-config-schema.md for the full schema.

B.2 Decide field values (stack-agnostic)

Full schema in references/mission-config-schema.md. Key conventions:

Field	Value rule
name	Short kebab-case name matching the filename
extends	"base" to inherit missions/base.json defaults (model, agent, maxCycles). commands is NOT inherited silently — write it explicitly (see below).
roadmapPath	Output of Workflow A: docs/backlog/{slug}-roadmap.md
plansDir	docs/plans/{mission-name} — each mission must have its own subdirectory or plans from different missions will mix
planGuide	docs/plans/00-plan-authoring-and-execution-guide.md (fixed in this template)
auditsDir	docs/audits/{mission-name} (recommended per-mission; legacy default audits)
contextDir	docs/context (fixed)
moduleDir	Target module root relative to project (e.g. src/auth, packages/api, tools/parser). Cross-cutting work uses project root .
commands	Required block — ALWAYS write it in the mission file. Each mission targets a specific module, so its verification commands usually differ from base. Writing them makes the config self-documenting and survives base.json changes.
commands.test	Required, non-empty. Read from docs/context/project-context.md "Verification Commands" if filled; otherwise infer from package.json / pom.xml / Cargo.toml / pyproject.toml. Placeholder commands must be replaced before run.
commands.build / lint / typecheck	Optional. Missing/empty = step skips that command.

Why write commands explicitly even with extends: "base"? A mission config that silently inherits commands is not self-reviewable — you cannot tell from the mission file which test/build commands the loop will run. Different missions target different modules (e.g. an engine mission vs a web mission) and need different commands. If the commands genuinely equal base, still write them: explicit > implicit, and a future base.json edit won't silently change this mission's verification surface.

Stack command cheat-sheet (replace brackets with real values):

Stack	test	build	typecheck	lint
Node (pnpm)	pnpm test	pnpm build	pnpm typecheck	pnpm lint
Node (npm)	npm test	npm run build	npx tsc --noEmit	npm run lint
Python (pytest)	pytest	(omit)	(omit)	ruff check .
Java (Maven)	mvn -pl {MODULE} -am test -T 4	mvn -pl {MODULE} -am clean package -DskipTests -T 4	mvn -pl {MODULE} -am test-compile -T 4	mvn -pl {MODULE} -am validate
Go	go test ./...	go build ./...	go vet ./...	golangci-lint run
Rust	cargo test	cargo build --release	(use build)	cargo clippy

B.3 Validate the mission config

Before running the validator, self-check:

• commands block is present IN the mission file (not just inherited from base)
• commands.test is a real, non-placeholder command for this mission's module
• No REPLACE_WITH_* / <fill ...> placeholders anywhere in the config

node tools/mission-driver/src/mission-check.mjs missions/<name>.json .

Checks required fields (name, roadmapPath, plansDir, commands) and path existence. Fix failures and re-run.

B.4 Pre-flight: plans directory and plan-guide

• Ensure plansDir exists (create empty dir if not; the engine scans it for .md).
• Ensure planGuide file exists. The template ships docs/plans/00-plan-authoring-and-execution-guide.md.
• Optional: place a 00--prefixed index file in plansDir (the engine skips 00--prefixed files when scanning for executable plans).

Workflow C: Run and monitor the mission

Trigger: mission config validated, ready to launch the auto dev loop.

C.1 Pre-flight checks

1. Health pre-check: the mission's CHECK step will run typecheck/build/test. For slow-compile stacks (Java, large monorepos), manually confirm baseline green first:

   <the mission's commands.typecheck or commands.test>
   

   If baseline is red, fix it before starting — otherwise CHECK wastes 3 retries.

2. No leftover locks: check _tmp/ for orphan processes from a previous crashed run:

   node tools/mission-driver/src/reap-orphans.mjs --startup _tmp <PID>
   

3. No conflicting active plans: if plansDir already has active-status plans, the engine will execute them first.

C.2 Launch commands

# Standard run (foreground, starts monitor on port 9300)
./tools/mission-driver.sh run <mission-name>

# Equivalent main-command form (no "run" keyword — same effect)
./tools/mission-driver.sh <mission-name>

# List all available missions
./tools/mission-driver.sh list

# List a mission's steps
./tools/mission-driver.sh list-steps <mission-name>

# Single-step debug (run only CHECK then exit)
./tools/mission-driver.sh run <mission-name> --step CHECK

# Resume from a specific step (run that step then continue the loop normally)
./tools/mission-driver.sh run <mission-name> --from-step EXEC_PLANS

# Dry-run (mock agent, no real model calls — verify flow orchestration)
./tools/mission-driver.sh run <mission-name> --dry-run

# Cap loops to prevent runaway
./tools/mission-driver.sh run <mission-name> --max-cycles 5 --max-total-steps 50

# Skip monitor (CI / background)
./tools/mission-driver.sh run <mission-name> --no-monitor

# Fast mode (skip fastSkipSteps — default skips DEEP_AUDIT)
./tools/mission-driver.sh run <mission-name> --fast

Optional environment variables: OPENCODE_AGENT, OPENCODE_MODEL, OPENCODE_PARSE_MODEL, MAX_CYCLES, MAX_TOTAL_STEPS, MONITOR_PORT, MONITOR_DISABLE=1, PROJECT_ROOT, OPENCODE_PURE=1.

--step vs --from-step: --step runs ONE step then exits (debug, maxSteps=1). --from-step starts at that step then keeps looping normally (resume). They are mutually exclusive — both at once exits with error.

Platform note: on Windows, run ./tools/mission-driver.sh under Git Bash or WSL.

C.3 Monitor a running mission

After launch, do not start the same mission again in the same opencode session (nested subprocesses corrupt state). Monitor in a separate terminal or browser.

Monitor dashboard (recommended): open http://localhost:9300 in a browser. If port is taken (another monitor or mission running), it auto-increments (9301, 9302, …).

Or run standalone monitor for browsing history:

./tools/mission-driver.sh monitor

Read state directly (most authoritative):

# _tmp/<runDir>/run-state.json
# Fields: status, currentStep, steps[], auditRound, maxAuditRounds

Tail logs:

• Main flow log: tail -f _tmp/<runDir>/<mission-name>.log — step transitions, markers, retries
• Per-step agent log: tail -f _tmp/<runDir>/oc-<STEP>-*.log — the agent's actual output

C.4 Interrupt and resume

Graceful interrupt: Ctrl-C or kill -TERM <main-pid>. main.js catches SIGTERM/SIGINT, calls runner.close(), cleans up the process tree (SIGTERM → 6s grace → SIGKILL).

Resume: re-run ./tools/mission-driver.sh <mission-name>. The engine recovers from disk state:

• Scans plansDir for draft/active-status plans (active runs first; draft is reviewed and promoted first).
• Incomplete plans resume from their checkbox progress ([x] / [ ]).
• Past run-state.json step history is for audit only — recovery is driven entirely by disk scan, not by replaying steps.

Resume from a specific step (debug):

./tools/mission-driver.sh run <mission-name> --from-step DRAFT_PLANS

C.5 When stuck

Read tools/mission-driver/TROUBLESHOOTING.md in full. Quick triage:

Symptom	Likely mode	Action
Step process 0% CPU, log mtime frozen >10min	Silent sub-agent stream stall	Wait for 60min watchdog, or kill -TERM -<STEP_PID> to advance flow
Main log shows level=ERROR "stream error"	Explicit model error	Usually auto-retries; on exhaustion the step fails and flow continues
oc-<STEP>-*.log has only the header, no body	Spawn failure	Check model id, opencode in PATH, permissions
Main log shows max_cycles / max_total_steps	Loop cap reached	Normal termination; check if roadmap has remaining todo, or raise caps
Main log shows ping_pong	Two-step death loop	Inspect step transitions and prompts for contradictions
Empty <ts>-mission-driver dirs piling up in _tmp/	Test pollution (historical)	Safe to delete: find _tmp -maxdepth 1 -type d -empty -delete

Orphan-process cleanup:

# Clean up orphans from a previous crash on startup
node tools/mission-driver/src/reap-orphans.mjs --startup _tmp <RUN_PID>
# Clean up a specific process group
node tools/mission-driver/src/reap-orphans.mjs <PGID> _tmp/<run-dir>

Workflow D: Postmortem

Trigger: mission completed (or aborted) and you want durable lessons.

./tools/mission-driver.sh analyze                  # postmortem the latest run
./tools/mission-driver.sh analyze <runId>          # specific run

analyze scans all events/logs, runs a postmortem agent, and writes a structured report to tools/mission-driver/memory/ as long-term reflexion memory. Future missions in the same module auto-load this memory on startup.

Command quick reference

Purpose	Command
List missions	./tools/mission-driver.sh list
Generate mission.json + roadmap	./tools/mission-driver.sh draft "<desc>" --target-file <doc>
List steps	./tools/mission-driver.sh list-steps <mission>
Run mission	./tools/mission-driver.sh run <mission>
Single-step debug	./tools/mission-driver.sh run <mission> --step <STEP>
Resume from step	./tools/mission-driver.sh run <mission> --from-step <STEP>
Dry-run	./tools/mission-driver.sh run <mission> --dry-run
Cap loops	./tools/mission-driver.sh run <mission> --max-cycles N
Validate mission.json	node tools/mission-driver/src/mission-check.mjs missions/<name>.json .
Validate plan format	node tools/mission-driver/src/plan-check.mjs <plan.md> --strict
Standalone monitor	./tools/mission-driver.sh monitor
Postmortem	./tools/mission-driver.sh analyze [<runId>]
Clean orphan processes	node tools/mission-driver/src/reap-orphans.mjs --startup _tmp <PID>

Constraints and prohibitions

• Do not hand-edit a plan file the mission is currently executing (write race with the AI subprocess).
• Do not put implementation steps or checkboxes in the roadmap — it's an index layer, not a plan.
• Do not mark a roadmap work item done before closure audit passes.
• Do not launch a mission with mission-check.mjs failing (missing required fields crash the engine mid-run).
• Do not bypass git hooks via --no-verify or similar — BUILD_VERIFY respects hooks and fails on rejection.
• Do not nest mission launches in the same opencode session — the mission itself spawns child opencode run processes; nesting corrupts state. Launch in a fresh terminal.
• If you must edit the roadmap during a mission (add/remove/reorder items), stop the mission first (Ctrl-C), edit, then restart. The AI will not re-arbitrate priority mid-run.
• Do not start a mission while another mission on the same missionsDir is still running unless you intentionally want concurrency (port auto-increments; plan writes may conflict if plansDirs overlap).
• Replace placeholder verification commands in missions/base.json / docs/context/project-context.md before relying on them — placeholder commands cause silent CHECK failures.

Output specification

After creating or modifying a mission config, always include these commands in the reply (without waiting for the user to ask):

# Validate mission config
node tools/mission-driver/src/mission-check.mjs missions/<name>.json .

# Dry-run validation (recommended before first real run — no real model calls)
./tools/mission-driver.sh run <mission-name> --dry-run --no-monitor

# Real run (after validation passes)
./tools/mission-driver.sh run <mission-name>

After creating a roadmap, always output the roadmap file path for later reference.