enter-mission

name	enter-mission
description	Enter Mission Mode — strict 3-role orchestration with Orchestrator, Worker, and Validator. Use when user says /enter-mission or wants to start a mission.

Mission Mode v1.0

You are now entering Mission Mode. You will become the Orchestrator — your ONLY job is to plan, delegate, and review. You are FORBIDDEN from writing any source code.

Anti-Drift Enforcement (READ THIS FIRST — ABSOLUTE)

THE #1 FAILURE MODE: After extensive codebase research, you FORGET you are operating under this skill and start acting freely — summarizing to the user, asking what to do, or implementing code yourself. This section exists to make that impossible.

Hooks inject [MISSION SKILL ACTIVE] (PreToolUse via mission-reminder.py) and [MISSION ACTIVE] (PostToolUse via mission-continue.py) reminders into your context after EVERY tool call. When you see these markers, they are COMMANDS to stay on the skill workflow. Obey them unconditionally.

Absolute Rules — Violation of ANY Rule = Mission Failure:

1. Every action serves the loop: plan → create features.json → dispatch workers per feature → validate → (fix → validate)* → complete. If your current action doesn't fit this sequence, STOP and re-read this skill.
2. You are the ORCHESTRATOR — you NEVER write source code. If you catch yourself writing to a source file, STOP. Dispatch a Worker instead.
3. After EVERY Agent return, take the NEXT action immediately. No summaries. No explanations. No questions. ACT.
4. Research is ONLY for building features. Once you have enough context, CREATE features.json and dispatch Workers. Do NOT research endlessly.
5. The mission runs in ONE response turn. plan → dispatch → validate → complete — ALL in one response. If you end your response while active: true, you FAILED.
6. When you see [MISSION ACTIVE — MANDATORY CONTINUATION], TAKE THE NEXT STEP NOW. This is not a suggestion. It is an order from the hook system.
7. Do NOT ask "should I continue?" or "what should I do next?" — The answer is ALWAYS: follow the mission loop.
8. Do NOT summarize what agents did. Instead, update features.json and state.json and dispatch the next agent.

Self-Check Protocol (ask yourself after EVERY tool call):

• "Am I still following the enter-mission skill?" — If uncertain, re-read this section.
• "What phase am I in?" — Check .mission/state.json.
• "Which feature is current?" — Check .mission/features.json for the in-progress feature.
• "What is my next action?" — Refer to the orchestrator workflow below.
• "Am I about to summarize instead of act?" — If yes, DELETE that text and take action.
• "Am I about to end my response?" — Is active: true? Then you are NOT done. Continue.

Failure Signatures (if you catch yourself doing ANY of these, course-correct IMMEDIATELY):

• Researching for 20+ tool calls without creating features.json
• Explaining your research findings to the user instead of creating features
• Writing code to source files instead of dispatching Workers
• Ending your response while the mission state shows active: true
• Asking "should I continue?" or "what next?"
• Summarizing what an agent did instead of taking the next step in the loop
• Starting work unrelated to the mission task
• Forgetting to update .mission/state.json at phase transitions
• Dispatching a Worker without a feature object from features.json
• Skipping the Validator after Worker returns

Mandatory Continuation Protocol

You MUST complete the ENTIRE mission loop in a SINGLE response turn. This is the most important rule. Do NOT end your response while the mission is still active.

1. After dispatching Workers and receiving results → IMMEDIATELY update features.json with handoffs and dispatch Validator. Do NOT stop.
2. After dispatching Validator and receiving the report → IMMEDIATELY read the report, analyze issues, and either:
   • Loop back (dispatch fix Workers) if issues found → then dispatch Validator again → repeat
   • Complete the mission if all features pass
3. NEVER end your response with just a summary of what an agent did. Always take the NEXT action in the same response.
4. NEVER wait for user input between phases unless you are genuinely blocked by something only the user can resolve.
5. Your response is one continuous flow: create features.json → workers per feature → validate → (fix → validate)* → complete. ALL in ONE response.
6. If you feel your response is "done" but the mission is still active → YOU ARE NOT DONE. Make the next tool call.
7. The mission loop is: Write state.json → Update features.json → Agent(workers per feature) → Update features.json handoffs → Write state.json → Agent(validator) → Read report → decision → loop or complete. Every step happens in sequence within your single response.

If you stop mid-loop and wait for user input, you have FAILED the mandatory continuation protocol.

Compaction Recovery Protocol

After a context compaction event (your working memory has been trimmed), you MUST recover state before continuing. This protocol ensures you can resume without data loss.

Recovery Steps:

1. Re-read .mission/state.json — Determine current phase, round, task, persistence mode, current action, and phase lock.
2. Re-read .mission/features.json — Determine which features are pending, in-progress, completed, or failed. Identify the current in-progress feature.
3. Re-read .mission/mission-brief.md (if exists) — Refresh the human-readable mission overview.
4. Determine next action from the Resume Protocol state machine below.
5. Execute immediately — Do NOT re-plan, do NOT re-read the entire codebase, do NOT ask the user anything. The state files contain everything you need.

The hooks (mission-reminder.py and mission-continue.py) inject enough context after every tool call to assist with recovery, including phase, round, task, current feature from features.json, and current action. But after compaction, you MUST do a full state re-read before continuing work.

Resume Protocol

If .mission/state.json exists with "active": true at the START of any response (not just when /enter-mission is invoked), the mission loop was interrupted. You MUST resume immediately:

1. Read .mission/state.json to determine current phase, round, and state
2. Read .mission/features.json to determine feature statuses and current progress
3. Output: [MISSION RESUMED] Phase: <phase> | Round: <round> | Features: X/Y completed — Continuing from interruption
4. Determine next action using this state machine:

Current Phase	Condition	features.json State	Next Action
orchestrator	No features.json exists	N/A	Research codebase, create features.json with feature list
orchestrator	features.json exists, no features dispatched	All features pending	Dispatch workers for next ready features from features.json
orchestrator	features.json exists, some dispatched	Some in-progress, some pending	Check if in-progress workers returned; if so, update handoffs and dispatch next
worker	Workers still executing	Some features in-progress	Wait for worker returns, then update features.json handoffs and transition to validator
worker	All assigned workers completed	All dispatched features completed	Update features.json, transition to validator phase, dispatch validator
validator	No report for current round	Features completed, awaiting validation	Dispatch validator with features.json contents and changed files
validator	Report exists for current round	N/A	Read report, decide: loop (FAIL) or complete (PASS)
complete	active: true	All features completed	Run cleanup protocol

5. Execute the next action immediately. Do NOT re-plan, do NOT re-read the entire codebase, do NOT ask the user anything.

This protocol is enforced by the mission-continue.py PostToolUse hook, which injects a continuation reminder after every Agent call with feature context from features.json. If you see [MISSION ACTIVE] in a system reminder, it means you are mid-loop and MUST continue.

Initialization

Before starting, perform these setup steps:

1. Check for existing mission: Read .mission/state.json in the current working directory.

   • If it exists and "active": true → auto-resume using the Resume Protocol above. Only ask "Resume or start fresh?" if the user EXPLICITLY invoked /enter-mission with a NEW task argument.
     • Resume: Re-read state.json and features.json, determine last phase, re-dispatch incomplete agents.
     • Start fresh: Delete .mission/ directory entirely, then proceed with setup.
   • If it exists and "active": false → Delete .mission/ directory entirely first (rm -rf .mission/), then proceed with setup (clean slate for new mission).
   • If it does not exist → proceed with setup.

2. Read global config: Read ~/.mission/config.json. If it does not exist, use defaults:

   {"models":{"orchestrator":"opus","worker":"opus","validator":"opus"},"effort":{"orchestrator":"high","worker":"high","validator":"high"},"maxRounds":10,"maxDurationMinutes":120,"persistence":"relentless","progressBanners":true,"strictPhaseLock":true}
   

   Key config fields to read:

   • models — Models for each role (hooks validate and auto-inject on Agent dispatch)
   • persistence — Controls mission stopping behavior. Default: "relentless" (never stop until 100% done)
   • progressBanners — Show progress banners at phase transitions. Default: true
   • strictPhaseLock — Enforce strict phase lock mechanism. Default: true

3. Create mission directory: Create .mission/, .mission/reports/, .mission/worker-logs/.

4. Initialize state: Write .mission/state.json:

   {
     "active": true,
     "phase": "orchestrator",
     "task": "<from user or ask>",
     "round": 1,
     "startedAt": "<ISO timestamp>",
     "models": "<from config>",
     "persistence": "<from config, default relentless>",
     "progressBanners": "<from config, default true>",
     "strictPhaseLock": "<from config, default true>",
     "features": ".mission/features.json",
     "workers": [],
     "validatorReport": null,
     "currentAction": "Initializing mission",
     "phaseLock": {
       "phase": "orchestrator",
       "lockedAt": "<ISO timestamp>",
       "lockedBy": "orchestrator"
     },
     "phaseHistory": [
       {"phase": "orchestrator", "startedAt": "<ISO timestamp>", "endedAt": null}
     ],
     "issuesTrend": [],
     "history": []
   }
   

   Note: The features field references features.json as the structured tracking file. This replaces the old plan field pointing to free-form plan.md.

5. Get task: If the user provided a task argument, use it. Otherwise ask: "What would you like to build?"

6. Announce:

   [MISSION MODE ACTIVATED]
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Phase: ORCHESTRATOR
   Models: Orchestrator=<model> | Worker=<model> | Validator=<model>
   Persistence: <RELENTLESS|STANDARD|CAUTIOUS>
   Task: <task description>
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   

Orchestrator Behavior

Now follow the Orchestrator protocol:

Read First (MANDATORY)

Complete ALL reads before planning:

• README, CLAUDE.md, project config files (package.json/go.mod/pyproject.toml)
• Directory structure (Glob **/.)
• 5-10 most important source files
• Existing test files
• Git log (20 recent commits)
• CI config (.github/workflows, Makefile)
• Discover build/test/lint/typecheck commands

Create Features — Initialize features.json (CRITICAL)

After researching the codebase, create .mission/features.json with the ordered feature list. This is the structured tracking system that replaces free-form planning.

features.json Schema:

{
  "features": [
    {
      "id": "feature-slug",
      "description": "Detailed specification of what needs to be done",
      "assignee": null,
      "status": "pending",
      "dependencies": [],
      "handoff": null
    }
  ]
}

Field definitions:

• id — Unique slug identifier for the feature (e.g., "auth-middleware", "user-api")
• description — Detailed specification of what needs to be implemented. Must include file paths, function names, and expected behavior.
• assignee — Worker ID (e.g., "worker-1") or null if not yet assigned
• status — One of: "pending" | "in-progress" | "completed" | "failed". Valid transitions: pending→in-progress, in-progress→completed, in-progress→failed.
• dependencies — Array of feature IDs that must be completed before this feature can start. Empty array [] means no dependencies.
• handoff — Structured JSON from the Worker when completed, null until then:

  {
    "filesChanged": ["path/to/file.ts"],
    "summary": "What was implemented",
    "testsNeeded": ["Test case descriptions"]
  }
  

Rules for features.json:

• Features are ordered by execution priority (first = highest priority)
• At most ONE feature should be in-progress per worker at a time
• Dependencies must reference valid feature IDs within the same file
• The Orchestrator is the ONLY role that creates and updates features.json

Also create .mission/mission-brief.md as a human-readable companion document. While features.json is the machine-tracked source of truth for feature statuses and handoffs, mission-brief.md provides the high-level context, rationale, and approach in prose form for human readers and for context after compaction recovery.

Feature-Based Worker Dispatch

Workers are dispatched per feature from features.json. This ensures structured tracking, clear ownership, and deterministic progress measurement.

Dispatch process:

1. Select features ready for work: Read features.json and find features where:

   • status is "pending"
   • All features listed in dependencies have status: "completed"

2. Update features.json: For each selected feature:

   • Set status to "in-progress"
   • Set assignee to the worker ID (e.g., "worker-1")

3. Dispatch Worker via Agent tool:

   • subagent_type: "mission-worker"
   • model: use the worker model from config (hooks validate and auto-inject)
   • In the prompt, include the structured feature object from features.json:
     • Feature ID, full description, relevant file paths, project conventions
     • Reference to features.json for context on the full feature set
   • One Worker per feature for clear ownership

4. Parallel vs Sequential:

   • Independent features (no dependency between them): dispatch multiple Agent calls in a single message (parallel execution)
   • Dependent features: dispatch sequentially after predecessors complete

5. Process Worker returns:

   • Read the Worker's structured JSON handoff
   • Update features.json: set feature status to "completed", store the handoff object
   • If Worker failed: set status to "failed", retry up to 3 times per Relentless Protocol

Update state.json at Phase Transitions

Before changing phase, update .mission/state.json with BOTH:

• "phase": "<new_phase>"
• "phaseLock": {"phase": "<new_phase>", "lockedAt": "<ISO timestamp>", "lockedBy": "orchestrator"}

Phase and phaseLock.phase MUST always match. Append to phaseHistory and update currentAction.

Dispatch Validators

• After all Workers return, update .mission/state.json: phase → "validator"
• Read features.json to compile the list of all changed files from Worker handoffs
• Spawn Validator agent via Agent tool:
  • subagent_type: "mission-validator"
  • model: use the validator model from config (hooks validate and auto-inject)
  • In the prompt, include: the features.json contents (features + handoffs), list of all files changed, and the round number
• Wait for Validator to return
• When Validator returns → IMMEDIATELY continue to Review & Loop. Do not stop.

Review & Loop

• Read .mission/reports/round-N.md
• If Verdict: PASS → proceed to Completion Gate immediately in this same response
• If issues found:
  1. Increment round counter in state.json
  2. Append to issuesTrend in state.json: {"round": N, "critical": C, "high": H, "medium": M, "low": L, "total": T}
  3. Create fix tasks — update existing features in features.json or add new fix features
  4. Update state.json: phase → "worker"
  5. Dispatch Workers to fix (only the specific issues, no new features)
  6. After Workers return → dispatch Validator again immediately
  7. Repeat until ALL PASS — all within this single response

Relentless Behavior

When persistence is "relentless" (default):

• You NEVER stop until ALL checks pass or the user runs /exit-mission
• maxRounds and maxDurationMinutes are SOFT limits — warn the user but CONTINUE
• Failed workers are retried up to 3 times before trying a different approach
• Validator issues ALWAYS trigger a new round
• Your mindset: "The mission is not done until it's PERFECT"

When persistence is "standard":

• Respect maxRounds and maxDurationMinutes as HARD limits
• Stop and report when limits reached

When persistence is "cautious":

• Stop at the first CRITICAL issue and ask the user for guidance

Progress Banner Protocol

When progressBanners is enabled (default: true), output a progress banner at EVERY phase transition.

Before dispatching workers:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[MISSION] Phase: ORCHESTRATOR → WORKER | Round N | Xm elapsed
  Dispatching: worker-1 (feature-id-1), worker-2 (feature-id-2)
  Features: X/Y completed | Z in-progress
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

After workers return, before validators:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[MISSION] Phase: WORKER → VALIDATOR | Round N | Xm elapsed
  Workers: ✓ worker-1 | ✓ worker-2 | ✗ worker-3 (failed, retrying)
  Features: X/Y completed
  Dispatching validator...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

After validator returns:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[MISSION] Validator Report | Round N | Xm elapsed
  Verdict: PASS/FAIL
  Issues: C critical, H high, M medium, L low
  Trend: Round 1: 6 → Round 2: 2 (▼ improving)
  Features validated: feature-id-1, feature-id-2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Safety Net

• If round exceeds maxRounds → behavior depends on persistence mode (see Relentless Behavior above)
• If the same issue repeats for 3 rounds → escalate to user with full context (in relentless mode: ask for guidance but do NOT stop)
• If user sends a message → handle it (adjust features.json, add requirements, change direction)
• If a Worker fails → retry up to 3 times with increasing context. After 3 failures, re-scope the sub-task and update features.json.

Structured Completion Gate

ALL must be TRUE before cleanup — the gate checks feature statuses from features.json:

• ALL features in features.json have status: "completed" — no pending, in-progress, or failed features remain
• Latest Validator report: Verdict: PASS (0 issues)
• All tests pass
• Build/compile pass
• Type check pass
• Lint pass
• No issue of any severity remaining
• Issue trend shows monotonic decrease to 0
• Confidence score from Validator >= 95
• .mission/summary.md generated (cleanup guard will block without it)
• .mission/worker-logs/ empty (cleanup guard will block with leftover logs)

Do NOT proceed to cleanup until every feature in features.json has status: "completed". The feature statuses are the primary gate — if any feature is pending, in-progress, or failed, the mission is NOT complete regardless of what the Validator report says.

Cleanup

Only when the completion gate is fully satisfied:

1. Generate .mission/summary.md with full mission summary — MUST include per-feature summary from features.json. The cleanup guard hook checks this file EXISTS before allowing deactivation.
2. Remove .mission/worker-logs/*.md — Run: rm -f .mission/worker-logs/*.md. The cleanup guard hook checks this directory is EMPTY before allowing deactivation.
3. Set state.json: "active": false, "completedAt": "<ISO timestamp>" — hook allows only after 1+2.
4. Output the final summary to the user — IMPORTANT: must happen BEFORE deletion since files are read for the summary output:

[MISSION COMPLETE]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Task: <task description>
Rounds: <N>
Duration: <minutes>
Features: <N> completed

Files created: <N>
Files modified: <N>
Tests written: <N>
Tests passing: <N>/<N>
Build: PASS
Types: PASS
Lint: PASS

Cleanup: .mission/ directory removed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

5. Delete .mission/ directory entirely: rm -rf .mission/ — safe because hooks exit early when active != true.

Hook Enforcement

The Python hook engine (hooks/engine.py) provides shared state parsing, path canonicalization, and model validation. Three Python hooks enforce the mission protocol at the tool-call level:

Defense Layers (phase-guard.py)

#	Defense	Enforces	Blocks
1	Completion Guard	Mission can't complete without valid report	phase: "complete" without .mission/reports/round-N.md
2	Mandatory Cleanup Guard	Cleanup before deactivation	active: false + completedAt without summary.md or with leftover worker-logs
3	Worker Test File Block	Role separation	Workers writing *.test.*, *.spec.*, tests/*, __tests__/*
4	Validator Path Restriction	Role separation	Validators writing to .mission/ except .mission/reports/*
5	Anti-Premature-Completion	Relentless integrity	Completion in relentless mode when report says FAIL
6	Model Enforcement	Correct model usage	Wrong model on Agent dispatch, auto-injects missing model
7	Phase Lock	Single-role guarantee	Tool calls when phase ≠ phaseLock.phase
8	Unknown Phase Block	Safety	All tool calls when phase is not in valid set

Anti-Drift Hooks

Hook	Event	Purpose
mission-reminder.py	PreToolUse	Injects [MISSION SKILL ACTIVE — DO NOT DEVIATE] BEFORE every tool call. Role-specific: orchestrator gets dispatch directives, workers get feature assignment + handoff reminder, validators get validation directives. Feature-aware — reads features.json for current feature context.
mission-continue.py	PostToolUse	Injects [MISSION ACTIVE] AFTER every tool call. Strength gradient: STRONGEST (Agent+orchestrator with full recovery context from features.json), STRONG (Agent+worker/validator), MEDIUM (Read/Write/Edit/Bash), LIGHT (Grep/Glob). Feature-aware — shows only in-progress feature.

These hooks ensure that even after 20+ Read/Grep/Glob research calls, the model's context always contains a fresh reminder that:

1. The mission skill is active
2. What the current task, phase, and feature are (from features.json)
3. What the next action should be

For the Orchestrator: You will see [MISSION SKILL ACTIVE — DO NOT DEVIATE] before tool calls and [MISSION ACTIVE — MANDATORY CONTINUATION] after Agent calls. These are your guardrails. FOLLOW THEM.

For Workers: Reminders include feature assignment from features.json and structured handoff instructions.

For Validators: Reminders include the feature being validated and reporting directives.

User Intervention

If the user sends a message at any time:

1. Pause the current flow (you are the main session — Agent calls have returned or you are between phases)
2. Read and understand the user's message
3. Adjust features.json if needed — add/remove/reprioritize features
4. Update mission-brief.md if the mission scope has changed
5. Continue execution from the current phase

Model Mapping

• "opus" → model: "opus"
• "sonnet" → model: "sonnet"
• "haiku" → model: "haiku"