Mission Runner

Mission Runner

Long-running mission orchestrator. Files are the memory; build outputs and git diff are the truth; LLM self-report is not.

---

Rule 0 — The one rule you cannot skip

A task is marked [x] only when BOTH are true:

1. Step 3 (build / lint / test) passed.
2. Step 3.6 (Compliance Check) verdict = pass.

LLM saying "I did X" is a hope, not a signal. The [x] is the synthesis of "code runs" plus "code does the right thing". Skip this and the whole anti-hallucination design collapses into ordinary self-report.

This rule survives the Escape Hatch. There is no mode in which "I did the work" alone justifies [x].

> Cross-mapping: legacy docs and references/prompt-template.md call this Mandate 5 / > [x] timing. Same rule.

---

At-a-glance: the four prohibitions + five mandates

These are the named protocol anchors that older docs (including the still-canonical references/prompt-template.md) and Escape-Hatch cross-references resolve to. The detail behind each lives in the corresponding section of this file or in references/.

Four Prohibitions (never do this):

| # | Prohibition | Anchor | |---|---|---| | 1 | Do NOT skip Read-Before-Decide at iteration start | §3 Step 1 | | 2 | Do NOT silently skip validation; every failure goes to mission_notes.md > Failures & Learnings | §3 Step 3 + Step 3.5 | | 3 | Do NOT close an iteration without updating mission_plan.md Progress Log AND mission_notes.md | §3 Step 4 + §4 micro-audit | | 4 | Do NOT guess on Low confidence; AskUserQuestion and record the answer | §3 Step 1.5 |

Five Mandates (always do this):

| # | Mandate | Anchor | |---|---|---| | 1 | Read-Before-Decide at iteration start (every iteration, no exceptions) | §3 Step 1 | | 2 | Validate by running real build/lint/test, never by claim | §3 Step 3 | | 3 | Issue Mission Accomplished ONLY after 5-item Pre-Promise Audit all pass | §5 | | 4 | Pre-Promise Audit applies even under Escape Hatch | §5 + §7 | | 5 | [x] is marked ONLY after Step 3 pass AND Step 3.6 verdict = pass — this is Rule 0 above | §3 Step 3.6 + §3 Step 4 |

Mandates 2 / 4 / 5 remain binding under Escape Hatch (see §7). Mandates 1 / 3 are the default per-iteration loop and can pause only if the mission is paused.

---

1. When to activate

Use when the task is one of:

• Multi-file / multi-layer implementation (typically 3+ files).
• Refactor that touches several subsystems.
• Anything framed as a "mission", "auto-iterate", "implement this end-to-end", or "iterate on this for me".
• Work that will plausibly span a /compact boundary.

Do not use for: single-file edits, one bug fix, Q&A, configuration tweaks.

---

2. Filesystem as memory

Three files (gitignored, single-mission scope) plus one cross-mission archive:

| File | Purpose | Lifecycle | |---|---|---| | _planning/mission_plan.md | Objective + Success Criteria + task list + Progress Log | Lives for the mission | | _planning/mission_notes.md | Append-only: findings, decisions, failures, compliance verdicts, audit trail, deviations | Lives for the mission | | _planning/workflow_state.json | OPTIONAL — crash-recovery cursor | Optional, most missions skip | | ~/.claude/mission-archive/{slug}/lessons/*.md | Phase 5 lessons; future missions glob these in Phase 0 step 3 | Persists across missions |

Schemas + ready-to-copy templates: see [references/file-templates.md](references/file-templates.md). Live examples filled in: see examples/_planning/.

Why files (not chat scrollback or memory tools): files survive /compact, survive subagent boundaries, and let mid-mission audits run against an external source of truth rather than what the LLM happens to remember.

---

Phase 0 — Initialization (one-shot, at mission start)

Before the per-iteration loop starts, do these in order:

1. Derive project slug (no cd — just read command output):

• Bash / Git Bash:

``bash slug=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" | tr '[:upper:]' '[:lower:]' | tr ' _' '--') ``

• PowerShell:

``powershell $root = (git rev-parse --show-toplevel 2>$null); if (-not $root) { $root = (Get-Location).Path } $slug = (Split-Path -Leaf $root).ToLower() -replace '[ _]', '-' ``

• Examples: E:\Yoji\Prism-OS → prism-os; /Users/foo/My App → my-app.

1. Glob historical lessons from ~/.claude/mission-archive/{slug}/lessons/ (the cross-mission learning consumption end):

• If the directory does not exist → first mission for this project, skip to step 3.
• Otherwise, read every *.md file's frontmatter (name, description, keywords).
• Match algorithm: a lesson is a hit when AT LEAST ONE of:
• Any keywords[i] (case-insensitive substring) appears in the user's task description, OR
• Any whitespace-tokenized word of description (case-insensitive substring) appears in the task description.
• Cap: keep at most 5 hits (highest-relevance by keyword count first, ties broken by mission_date descending). Drop the rest — Prior Lessons block must not pollute context.
• Cache the full body of each hit for step 4.

1. Create _planning/ directory:

• Bash: mkdir -p _planning
• PowerShell: New-Item -ItemType Directory -Force -Path _planning | Out-Null
• Do not mix shells: mkdir -p raises A positional parameter cannot be found in PowerShell; the agent must pick the form matching its current shell tool.

1. Write _planning/mission_plan.md using the template in references/file-templates.md. The ## Prior Lessons block content:

• Hits in step 2 → list each lesson's file name + full body verbatim + a one-line "Source:" footer.
• No hits → write the literal line (no historical lessons matched this task).

1. Write _planning/mission_notes.md with all standard sections empty (Research Findings / Decisions Made / Failures & Learnings / Self-Reflections / Compliance Checks / Clarifications / Open Questions / Distilled Lessons / Audit Trail / Deviations & Reasons). See references/file-templates.md for the canonical empty form.

1. Start the loop (§3 Step 1 Read-Before-Decide kicks in).

---

3. The loop (per iteration)

Step 1   Read-Before-Decide      Read plan + notes + Prior Lessons block
Step 1.5 Confidence Check        High / Medium / Low + one-line reason
Step 2   Execute                 One task only. Do NOT mark [x] here.
Step 3   Validate                build / lint / test
Step 3.5 Self-Reflection         Only if Step 3 failed OR Step 3.6 escalated
Step 3.6 Compliance Check        diff matches task description?
                                 verdict in {pass, needs-revision, escalate}
Step 4   Checkpoint              If 3.6=pass → NOW mark [x] → next task or all done

Step 1 — Read-Before-Decide

Read _planning/mission_plan.md:

• What's the Objective?
• What Phase am I in?
• What is the next unchecked [ ] task?
• Read the ## Prior Lessons block (filled in Phase 0 step 3). If any matched lesson warns about a trap that applies to the current task, downgrade Solution Certainty / Risk Estimate accordingly in Step 1.5.

Read _planning/mission_notes.md:

• Last iteration's failures / learnings.
• Prior Clarifications (so you don't re-ask).
• Compliance Checks with verdict ≠ pass (those are unfinished business).
• Audit Trail (so you know which promise attempts already failed).

Step 1.5 — Confidence Check (compact form)

State confidence in one sentence and proceed:

• High — proceed. ("High — plan §4 is explicit + I've already verified the file shape.")
• Medium — record one concern to mission_notes.md > Open Questions, pick the conservative option, proceed.
• Low — STOP. Use AskUserQuestion. Record the answer to mission_notes.md > Clarifications before continuing.

When Low confidence needs a surgical question to the user, the 4-dimension breakdown (Task understanding / Solution certainty / Dependency clarity / Risk estimate) makes the question much sharper. Full structured form: [references/confidence-check.md](references/confidence-check.md).

Step 2 — Execute

One task at a time. Follow project conventions.

Update mission_plan.md > Progress Log with a row for this iteration. Do not mark [x] here; that happens at Step 4 after Compliance passes (Rule 0).

Step 3 — Validate

Run the project's build / lint / test commands. Failed → Step 3.5. Passed → Step 3.6.

Step 3.5 — Self-Reflection (compact form)

Triggered by Step 3 failure or Step 3.6 escalate.

Classify and act:

| Type | Examples | Action | |---|---|---| | Simple | Typo, missing import, unused-var lint | Fix inline. Max 2 retries this iteration. One-line note to Failures & Learnings. | | Medium | Logic bug, missed edge case, wrong assumption | 1-2 sentence written reflection → Self-Reflections section → next iteration handles. | | Complex / 3rd time same error | Architecture conflict, requirement ambiguity, repeated failure | AskUserQuestion. Do NOT retry blindly. |

Full Reflexion-paper protocol with structured prompt + record format: [references/self-reflection.md](references/self-reflection.md). The compact form above is correct for most cases.

Step 3.6 — Compliance Check (NOT optional)

This is what makes [x] honest. Even if build passes, do BOTH parts:

(a) Collect 3 signals first (so Q1/Q2 are answered from evidence, not memory):

1. Current [ ] task description from mission_plan.md (re-read it; don't paraphrase from memory).
2. Current iteration's diff: git diff HEAD.
3. Most recent Decisions Made entry in mission_notes.md, if any (last decision is the most likely source of in-scope changes).

(b) Then ask 2 questions in chat:

1. Q1 — Completeness: does this diff implement the task described in the plan? (Not "code compiles" — feature ≈ description.)
2. Q2 — Drift: did I change anything outside the task scope? (Sneaky refactors, rename-while-you're-there, "drive-by" fixes.)

Step 3.6 without git diff HEAD is theatre — the agent can only honestly answer Q1/Q2 against an actual diff readout, not from "I remember what I changed".

Write a verdict to mission_notes.md > Compliance Checks:

- [Iter N] Task: "{name}"
  Diff files: [...]
  Q1: complete / partial / drift
  Q2: none / [list]
  Verdict: pass / needs-revision / escalate

| Verdict | Action | |---|---| | pass | Mark [x]. Proceed to Step 4. | | needs-revision | Do NOT mark [x]. Append a sub-task under this task in the plan. Next iteration continues here. | | escalate | Do NOT mark [x]. Feed Q1/Q2 answers into Step 3.5. |

Step 4 — Checkpoint

(Reaching here implies build pass + Step 3.6 = pass + [x] now marked.)

• All tasks [x] and all Success Criteria [x]? → Phase 4 Debrief → Phase 5 Distill → 5-item Pre-Promise Audit.
• Otherwise → next iteration (back to Step 1).

---

4. Mid-iteration micro-audit (3 items, per task)

Before moving from one task to the next within the same mission, verify on external evidence (not LLM self-report):

1. The build / test command actually ran in this conversation, and its output shows pass. (Not "I ran tests" without the command appearing.)
2. mission_notes.md > Compliance Checks has a verdict entry for this iteration. Probe:

• Bash: grep -n "Iter $N" _planning/mission_notes.md
• PowerShell: Select-String -Path _planning/mission_notes.md -Pattern "Iter $N"

1. mission_plan.md > Progress Log has a new row for this iteration AND the corresponding task's [ ] is now [x]. (Both, not just the row.)

Failing any of these means the iteration is not actually complete. Do not advance.

This is the small-scale analog of §5's Pre-Promise Audit. The reason it exists: most LLM hallucination of completeness happens between tasks, not at final promise time. Catching it per-iteration is much cheaper than catching it at the end.

---

5. Pre-Promise Audit — before Mission Accomplished

All 5 must pass. Items 3 / 4 / 5 are external signals that cannot be hallucinated.

| # | Check | Source | Concrete probe | |---|---|---|---| | 1 | Every - [ ] (including indented sub-tasks) in mission_plan.md is now [x] | plan file | Bash: grep -cE "^\s*- \[ \]" _planning/mission_plan.md → 0; PowerShell: (Select-String -Path _planning/mission_plan.md -Pattern '^\s*- \[ \]').Count → 0 | | 2 | All Success Criteria are [x] | plan file | Scan the Success Criteria block (same probe as #1, scoped to that block) | | 3 | git diff --stat shows a non-empty diff vs base | git | At least 1 file modified/added (same command both shells) | | 4 | Latest Progress Log row references real build output | command output | A row containing verified: pass or equivalent. Bash: tail -n 5 _planning/mission_plan.md \| grep -F "verified: pass"; PowerShell: Get-Content _planning/mission_plan.md -Tail 5 \| Select-String -SimpleMatch "verified: pass" | | 5 | At least one lesson file exists under today's archive folder | filesystem | Bash: ls ~/.claude/mission-archive/{slug}/lessons/$(date +%Y-%m-%d)-*.md; PowerShell: Get-ChildItem "$env:USERPROFILE\.claude\mission-archive\{slug}\lessons\$(Get-Date -Format yyyy-MM-dd)-*.md" |

The probes for items 1, 2, 4 are cross-shell; the agent picks the form matching its current shell tool. Items 3 and 5 are described above with explicit branches. Do NOT mix Bash and PowerShell syntax in the same probe call — the failure mode is silent (command-not-found gets logged to stderr but the agent may interpret an empty stdout as "0 matches" = pass, which silently bypasses the audit).

Any item fails → output Partial Report. Append failure + reason to mission_notes.md > Audit Trail. Do NOT issue the promise.

Item 5 is the firewall that prevents skipping Phase 5. Without it, cross-mission learning never accumulates and the next mission inherits nothing from this one.

---

6. Phase 5 — Distill (required before promise)

Once all Success Criteria are [x]:

1. Derive slug (same as Phase 0 step 1; do not re-derive, reuse the value cached at mission start):

• Bash: slug=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" | tr '[:upper:]' '[:lower:]' | tr ' _' '--')
• PowerShell: $root = (git rev-parse --show-toplevel 2>$null); if (-not $root) { $root = (Get-Location).Path }; $slug = (Split-Path -Leaf $root).ToLower() -replace '[ _]', '-'

1. Ensure archive directory exists:

• Bash: mkdir -p ~/.claude/mission-archive/$slug/lessons/
• PowerShell: New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\mission-archive\$slug\lessons"

1. Scan mission_notes.md for lesson candidates from:

• Decisions Made — which choice is worth reusing?
• Self-Reflections — which failure root cause has cross-mission transferability?
• Compliance Checks where verdict = escalate — which class of drift should future missions watch for? (Skip needs-revision verdicts; those usually self-resolve in the next iteration and don't represent a stable lesson.)

1. Produce 1-3 lessons — not more. Quality over quantity. Each lesson is Distilled Lessons** with a one-line summary each.

Full lesson schema (frontmatter, body shape, why 150 words is strict): [references/file-templates.md](references/file-templates.md) § "Lesson file format".

---

7. Escape Hatch (when the loop doesn't fit)

If the state-machine recommendation is wrong for the situation (path conflict, user override, requirement collapsed, evidence contradicts the plan), switch to free-form execution. Record the deviation in mission_notes.md > Deviations & Reasons with: trigger, original state, why, outcome.

What the Escape Hatch does NOT excuse — these are protocol-level, not state-machine suggestions:

1. Rule 0 (Step 3.6 must still gate every [x]).
2. Phase 5 Distill (no lesson f

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sputnicyoji
• Source: sputnicyoji/Claude-Skill-MissionRunner
• License: MIT

Install and usage instructions live in the source repository linked above.