Mission Driver

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?

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:

• 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 top "Work Items" list. 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:

• Each work item is completable by one plan (no epic-sized items)
• Only one dynamic state block (the Work Items list)
• 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)

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:

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

B.3 Validate the mission config

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

Checks required fields (name, roadmapPath, plansDir, commands.test) 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:

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

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.