Mission Orchestrator

Table of Contents

• Overview
• When to Use
• Mission Lifecycle
• Interactive Plan Review
• Mission Types
• Phase-to-Skill Mapping
• Session Recovery
• Module Reference
• Related Skills
• Related Commands
• Exit Criteria

Mission Orchestrator

Overview

Wraps the entire attune development lifecycle (brainstorm → specify → plan → execute) into a single mission with automatic state detection, type selection, and phase routing. Follows the "persistent presence lens" pattern from spec-kit:speckit-orchestrator: delegates entirely to existing skills via Skill() calls, never re-implements phase logic.

When To Use

• Starting a new project from scratch (full lifecycle)
• Resuming an interrupted project workflow
• Running a focused tactical implementation from existing specs
• Quick-fixing from an existing implementation plan

When NOT To Use

• Running a single phase directly (use /attune:brainstorm, /attune:specify, etc.)
• Non-project work (code review, debugging, research)
• When you need fine-grained control over phase transitions

Mission Lifecycle

1. State Detection
   Scan for existing artifacts (project-brief.md, specification.md, etc.)
       |
2. Mission Type Selection
   Auto-detect type based on artifacts, or accept user override
       |
3. Phase Routing Loop
   For each phase in the mission type:
       a. Pre-phase validation (check prerequisites)
       b. Invoke Skill(attune:{phase-skill})
       c. Post-phase artifact check (verify output exists)
       d. Post-phase backlog triage (create GitHub issues
          for out-of-scope items after brainstorm/specify)
       e. Update mission state
       f. User checkpoint (skippable with --auto)
       g. Error handling via leyline:damage-control
       |
4. Completion
   All phases complete, final state saved

Mission Types

See modules/mission-types.md for full type definitions and custom type support.

Phase-to-Skill Mapping

The orchestrator never re-implements phase logic. Each phase is a complete Skill() invocation that handles its own workflow.

Session Recovery

Missions persist state to .attune/mission-state.json. On resume:

1. Load mission state file 2. Validate referenced artifacts still exist on disk 3. Identify last completed phase 4. Continue from next phase in sequence

See modules/mission-state.md for the state schema and recovery protocol.

Interactive Plan Review

The plan-to-execute transition uses an interactive review loop instead of a simple checkpoint. Plans are reviewed section by section, revised based on feedback, and must pass a mandatory war-room gate before execution.

Key capabilities:

• Section-by-section terminal review (architecture

first, then phases)

• Approve/revise/reject verdicts with rationale
• Plan version tracking with diff summaries
• Context improvement from structured feedback
• Additive bias scanning before user review
• Maximum 3 revision rounds before forced decision
• Mandatory war-room approval with Prosecution Counsel

See modules/plan-review.md for the full protocol.

Review Modules

• plan-review.md: Main orchestrator for the review loop
• plan-versioner.md: Version tracking and diff generation
• feedback-collector.md: Verdict capture and JSON output
• context-injector.md: Revision prompt construction
• iteration-governor.md: Round tracking and escalation

User Directive Overrides

The orchestrator parses the user's command-args and free-text at mission start for natural-language trust signals. Phrases like "ignore scope guard", "ultrathink", "don't keep asking", and "be autonomous" are recognized as directive overrides that adjust the constraint profile without requiring an explicit --constraints= flag.

Directive overrides win over mission-type defaults but never bypass the Safety Floor (pre-commit hooks, proof-of-work evidence, destructive-operation confirmation, external-facing actions). When a directive is detected, the orchestrator acknowledges it once at mission start and stops asking for the corresponding checkpoints. Repeated approval-seeking after a directive override is itself a workflow bug.

See modules/adaptive-constraints.md "User Directive Override" section for the parsing table.

Mission Charter

Define mission boundaries using the structured template from references/mission-charter.md. A Mission Charter specifies:

• Outcome: What success looks like
• Success metric: Measurable completion criteria
• Deadline: Time boundary (session, date, or duration)
• Constraints: Token/time budgets, forbidden actions
• Scope: In-scope and out-of-scope areas
• Stop criteria: Conditions that halt the mission

See references/mission-charter.md for the full template and examples.

Progress Reports

Track progress with structured checkpoints using references/progress-report.md. Generate reports at:

• Phase boundaries (between brainstorm→specify→plan→execute)
• Blocker identification
• Risk escalation
• Budget thresholds (50%, 75%, 90%)

See references/progress-report.md for the template and checkpoint rhythm guidance.

Module Reference

Core modules (always loaded)

• mission-types.md: Type definitions, auto-detection logic,

custom types

• state-detection.md: Artifact existence checks, quality

validation, staleness

• phase-routing.md: Phase execution protocol, transition

hooks, error handling

• mission-state.md: State schema, persistence, recovery

protocol

Plan-review modules (load when plan phase runs)

• plan-review.md: Interactive section-by-section review

with bias scanning

• plan-versioner.md: Version tracking and diff summaries
• feedback-collector.md: Verdict capture and feedback files
• context-injector.md: Revision prompt construction from

feedback

• iteration-governor.md: Round tracking, cap enforcement,

escalation

Conditional modules (load only when triggered)

• reflexion-buffer.md: Cross-session learning buffer; load

when iteration count > 1 or after a failed revision round.

• trust-tier.md: Constraint-profile classifier; load when

a user directive override is detected at mission start.

• adaptive-constraints.md: Constraint adaptation rules;

load alongside trust-tier.md when directive overrides are active.

Module Loading by Mission Type

This skill declares progressive_loading: true. To keep the orchestrator's resident token cost minimal, load only the subset of modules each mission type actually needs. The orchestrator itself loads only the four core modules at mission start; the rest are loaded on-demand when their phase runs.

Token cost (approximate, computed from wc -w on hub + loaded modules and converted at ~1.3 tokens per word):

The previous load-all pattern brought in roughly 10,100 tokens for every mission, including quickfix runs that only need the execute phase. With per-type loading, quickfix is ~60% lighter and the standard / tactical / full paths save 22-32%.

When a directive override fires, the trust-tier + adaptive-constraints pair adds ~2,200 tokens on top of the mission-type baseline.

Reference Modules

• mission-charter.md: Structured mission definition

template (load only when defining a charter)

• progress-report.md: Checkpoint status report template

(load only when emitting a progress report)

Related Skills

• Skill(attune:project-brainstorming) - Brainstorm phase
• Skill(attune:project-specification) - Specify phase
• Skill(attune:project-planning) - Plan phase
• Skill(attune:project-execution) - Execute phase
• Skill(attune:war-room-checkpoint) - Risk assessment for RED/CRITICAL tasks
• Skill(leyline:risk-classification) - Task risk classification
• Skill(leyline:damage-control) - Error recovery during phases

Related Commands

• /attune:mission - Invoke this skill
• /attune:mission --resume - Resume from saved state
• /attune:mission --type tactical - Override mission type

Exit Criteria

• All phases in mission type completed successfully
• Artifacts exist for each completed phase
• Mission state saved to .attune/mission-state.json
• Risk summary generated (tier counts across all tasks)
• No unresolved errors or blockers

Adaptive Constraints (Nen-Free Zones)

Problem

All missions load the same governance weight regardless of complexity. Past 150 soft rules, compliance drops for all rules. A focused 50-line CLAUDE.md beats an unfocused 300-line one; bad context performs worse than none. SWE-agent mini proves 100 lines of focused code reaches 74% on SWE-bench Verified. Simple tasks need less governance, not the same governance.

Constraint Profiles

Profile Selection

By Mission Type

Manual Override

Override with --constraints=minimal|standard|full. The override bypasses mission-type defaults and risk upgrades (always wins).

User Directive Override (Natural Language)

Parse the command-args and any free-text the user provides at mission start. If a recognized trust signal is present, treat it as a manual override with the tier shown below. Directive overrides behave exactly like --constraints= flags: they win over mission-type defaults and risk upgrades, but never bypass the Safety Floor.

Match is case-insensitive substring. Multiple matches: the most-restrictive directive wins (Full beats Minimal). The orchestrator records the matched directive and resulting profile in .attune/mission-state.json under directive_override:

{
  "directive_override": {
    "matched_phrase": "ignore scope guard",
    "effective_profile": "standard_minus_scope_guard",
    "matched_at": "2026-04-25T17:30:00Z"
  }
}

When a directive override is detected, the orchestrator MUST acknowledge it once at mission start, then stop asking for the corresponding checkpoints. Repeated approval-seeking after a directive override is itself a workflow bug; see /sanctum:fix-workflow retrospectives for examples.

What Directives Cannot Override

The Safety Floor below applies regardless of directive. Even "trust me, just do it" cannot waive:

• Pre-commit hooks
• Proof-of-work evidence capture
• Destructive-operation confirmation (rm -rf, force

push, DROP TABLE, branch deletion)

• External-facing actions (PR creation, issue

comments, release tags)

• Cost threshold breaches (token/time budget exceeded)

When the orchestrator hits one of these even under a Minimal directive override, it pauses. The override gives autonomy on routine decisions; it does not surrender oversight on irreversible ones.

Persistent vs Per-Mission Directives

Directive overrides apply for the current mission only. They do not persist to subsequent missions. For permanent autonomy escalation, the user should either set the profile flag on each mission or elevate skill trust tiers via repeated successful runs (see trust-tier.md).

Risk Upgrade

leyline:risk-classification can upgrade (never downgrade) the profile:

Selection order: mission-type default, then risk upgrade, then manual override.

What Each Profile Strips

Minimal (vs Full)

Stripped:

• scope-guard worthiness evaluation
• war-room checkpoint
• plan-review iteration loop
• backlog triage (issue creation from Out of Scope)
• additive-bias-defense check

Kept:

• proof-of-work evidence (always required)
• Iron Law enforcement (always active)
• Pre-commit hooks (always run)
• Destructive operation confirmation (always prompt)

Standard (vs Full)

Stripped:

• war-room checkpoint
• additive-bias-defense audit
• Plan review limited to single pass (no iteration

governor, no multi-round revision)

Kept:

• scope-guard worthiness evaluation
• proof-of-work evidence
• Single checkpoint per critical phase
• Pre-commit hooks
• Iron Law enforcement
• Destructive operation confirmation

Safety Floor

These constraints are never stripped regardless of profile, forming the absolute minimum governance:

1. Pre-commit hooks always run. No path through adaptive-constraints disables --no-verify protection. 2. proof-of-work evidence is always required. Every mission must produce verifiable artifacts. 3. Hard vows from vow-enforcement are always enforced. Soft vows may be relaxed by profile. 4. Destructive operation confirmation always prompts. No silent rm -rf, git push --force, or DROP TABLE.

Any code path bypassing the safety floor is a bug. The floor is not configurable.

Token Savings

Savings compound: 5 quickfixes save ~10k tokens.

Integration with Phase Routing

The phase-routing.md module consults adaptive- constraints before each phase transition:

1. At mission start, the orchestrator determines the constraint profile and records it in .attune/mission-state.json under constraint_profile.

2. Before each phase, phase-routing checks the active profile against the phase's governance requirements.

3. If the profile says "skip checkpoint for this phase," phase-routing auto-continues without presenting the checkpoint prompt.

4. The profile is locked at mission start. No mid- mission changes. If risk escalates, the orchestrator logs a warning; the user can abort and restart with a higher profile.

Phase-Routing Decision Table

Context Injector

Purpose

When a plan revision is requested, transform the structured feedback into a prompt addition that guides the planning skill to address the specific complaints without repeating rejected patterns.

Revision Prompt Template

The context injector reads the latest round-N.json and builds this prompt block:

## Revision Context (Round {N} Feedback)

The previous plan version was reviewed. Address
these items in the revised plan:

### Sections Requiring Revision

**{section_name}** (verdict: {verdict})
Feedback: {rationale}
{annotations if any}

### Sections Approved (Do Not Change)

- {section_name}: approved, keep as-is

### Anti-Patterns to Avoid

Do NOT repeat these patterns from the rejected plan:
- {extracted patterns from rejected sections}

### Constraints Added by Reviewer

- {constraint annotations}

Building the Prompt

Algorithm

1. Read .attune/plan-history/feedback/round-N.json 2. For each section with verdict revise or reject:

• Include the section name, verdict, and rationale
• Include any typed annotations
• Extract specific patterns to avoid from rejected

content 3. For each section with verdict approve:

• List as "keep as-is" to prevent regression

4. Collect all constraint type annotations into a dedicated section 5. If bias findings exist, include them as additional constraints

Feeding Back to the Planning Skill

The revision prompt is passed as additional context when re-invoking Skill(attune:project-planning):

The orchestrator re-invokes the planning skill with:
1. The original specification (docs/specification.md)
2. The revision context block (built above)
3. The previous plan version for reference

The planning skill sees the revision context as requirements that constrain its output.

War Room Feedback

When the war room returns concerns or rejection:

1. Read the war-room verdict from mission state 2. Convert war-room concerns into the same revision prompt format 3. Include the prosecution counsel's specific objections as constraints 4. Mark this as "war-room feedback" so the planning skill knows the source

Guard Rails

• The context injector NEVER modifies the plan directly
• It only produces prompt context for the planning skill
• Approved sections are explicitly marked "do not change"

to prevent regression during revision

Feedback Collector

Purpose

Capture the user's section-by-section review verdicts and write them as structured JSON for consumption by the context injector and plan versioner.

Verdict Types

Optional Typed Annotations

When the user wants finer-grained control than section-level verdicts, they can add typed annotations:

Feedback File Schema

Written to .attune/plan-history/feedback/round-N.json:

{
  "round": 1,
  "plan_version": 1,
  "timestamp": "2026-04-13T14:30:00Z",
  "sections": [
    {
      "name": "architecture",
      "verdict": "revise",
      "rationale": "Split the API layer into read/write services",
      "annotations": []
    },
    {
      "name": "phase-1",
      "verdict": "approve",
      "rationale": null,
      "annotations": []
    },
    {
      "name": "phase-2",
      "verdict": "reject",
      "rationale": "Wrong approach entirely, use event sourcing",
      "annotations": [
        {
          "type": "constraint",
          "text": "Must support event replay for auditing"
        }
      ]
    }
  ],
  "overall": "revision_requested",
  "bias_findings": [],
  "war_room": null
}

Field Descriptions

Overall Verdict Logic

if len(sections) > 0 and all sections have verdict "approve":
    overall = "approved"
elif len(sections) == 0:
    overall = "error: no sections parsed"
else:
    overall = "revision_requested"

An empty sections array MUST NOT resolve to "approved." If the plan parser produces zero sections, report the error rather than silently approving an unreviewed plan.

Writing the Feedback File

mkdir -p .attune/plan-history/feedback
# Write JSON to round-N.json

The orchestrator writes the JSON after collecting all section verdicts in a single review pass.

Iteration Governor

Purpose

Prevent infinite plan-churn by capping review iterations at 3 rounds. If the plan is still not satisfactory after 3 rounds, the problem is likely upstream in the specification.

Round Tracking

War Room Feedback Counts

War-room feedback that triggers a revision counts toward the iteration cap. If the user approves on round 2 but the war room sends it back, that revision is round 3 (final).

Example:

• Round 1: User reviews, requests revision
• Round 2: User approves, war room rejects
• Round 3: Final revision, then forced decision

Escalation at Cap

When round 3 is exhausted (user or war room still not satisfied), present these options:

Round 3 exhausted. 3 review rounds completed.

Options:
  [A] Approve current version as-is
  [B] Abort mission
  [C] Restart planning from specification
      (re-invoke Skill(attune:project-planning)
       with clean slate, no revision context)

Option C resets the iteration counter to 0 and starts fresh. The previous plan history is preserved for reference but not fed as context.

Round 2 Warning

At the start of round 2 review, display:

--- Warning: Round 2 of 3 ---
This is the penultimate review round.
Round 3 will be the final opportunity to revise.
After round 3, you must approve, abort, or restart.
-----------------------------------------

State Integration

The governor reads and writes plan_review.current_round in .attune/mission-state.json. See mission-state module for the schema.

Governor Logic

function check_iteration(current_round):
    # Called BEFORE round starts. current_round is
    # incremented after each completed round, so
    # current_round == 4 means 3 rounds completed.
    if current_round > 3:
        present_escalation_options()
        return BLOCKED
    elif current_round == 3:
        display "Final round (3/3)"
        return FINAL
    elif current_round == 2:
        display round 2 warning
        return WARNING
    else:
        return NORMAL

Mission State

State Schema

{
  "mission_id": "mission-20260207-220000",
  "type": "tactical",
  "started_at": "2026-02-07T22:00:00Z",
  "updated_at": "2026-02-07T23:30:00Z",
  "status": "in_progress",
  "phases": {
    "brainstorm": {
      "status": "skipped",
      "reason": "Not in mission type 'tactical'"
    },
    "specify": {
      "status": "skipped",
      "reason": "Not in mission type 'tactical'"
    },
    "plan": {
      "status": "completed",
      "started_at": "2026-02-07T22:00:00Z",
      "completed_at": "2026-02-07T22:45:00Z",
      "artifact": "docs/implementation-plan.md",
      "notes": "Generated 24 tasks across 5 phases"
    },
    "execute": {
      "status": "in_progress",
      "started_at": "2026-02-07T22:50:00Z",
      "completed_at": null,
      "artifact": ".attune/execution-state.json",
      "notes": "12/24 tasks complete"
    }
  },
  "risk_summary": {
    "GREEN": 18,
    "YELLOW": 4,
    "RED": 2,
    "CRITICAL": 0
  },
  "errors": [
    {
      "phase": "execute",
      "task_id": "T015",
      "error": "Test timeout on integration suite",
      "category": "TRANSIENT",
      "recovery": "Retried successfully",
      "resolved": true
    }
  ],
  "user_decisions": [
    {
      "checkpoint": "plan → execute",
      "decision": "continue",
      "timestamp": "2026-02-07T22:48:00Z"
    }
  ],
  "plan_review": {
    "current_round": 2,
    "max_rounds": 3,
    "status": "in_review",
    "versions": [
      {
        "version": 1,
        "created_at": "2026-04-13T14:00:00Z",
        "path": ".attune/plan-history/plan-v1.md",
        "feedback_path": ".attune/plan-history/feedback/round-1.json",
        "overall_verdict": "revision_requested"
      },
      {
        "version": 2,
        "created_at": "2026-04-13T14:30:00Z",
        "path": ".attune/plan-history/plan-v2.md",
        "feedback_path": null,
        "overall_verdict": null
      }
    ],
    "war_room_verdict": null,
    "bias_findings_count": 3
  }
}

Field Descriptions

Persistence

State is persisted to .attune/mission-state.json:

• Write frequency: After each phase completion and on error
• Atomic write: Uses temp file + rename pattern to prevent corruption
• Directory creation: Creates .attune/ if it doesn't exist

# State file location
.attune/mission-state.json

Recovery Protocol

When resuming a mission (/attune:mission --resume):

Step 1: Load State

Read .attune/mission-state.json
If not found: No mission to resume, start fresh
If found: Parse and validate

Step 2: Validate Artifacts

For each completed phase, verify its artifact still exists on disk:

For each phase where status == "completed":
    Check artifact path exists
    If missing: Mark phase as "needs_rerun"
    If present: Confirm still valid (quality checks)

Step 3: Continue from Last Completed Phase

Find first phase where status != "completed" and status != "skipped"
If "in_progress": Resume this phase
If "pending": Start this phase
If all complete: Mission already done

Step 4: Display Resume Summary

Resuming Mission: mission-20260207-220000
  Type: tactical
  Status: in_progress

  Phase Status:
    plan:    completed (22:00 - 22:45)
    execute: in_progress (12/24 tasks, started 22:50)

  Continuing from: execute phase
  Next task: T013

State Transitions

           start
             |
             v
        in_progress ──────► completed
             |
             ├──► paused (--resume to continue)
             |
             ├──► aborted (user choice)
             |
             └──► failed (unrecoverable error)

• paused → in_progress: Via --resume
• failed → in_progress: Via --resume --force (resets failed phase)
• aborted: Terminal state (start new mission to retry)

Plan Review Status Transitions

plan_review.status:
    pending --> in_review (first section presented)
    in_review --> approved (all sections approved)
    in_review --> revision_requested (any section rejected/revised)
    approved --> war_room_pending (war room invoked)
    war_room_pending --> approved (war room approves)
    war_room_pending --> revision_requested (war room rejects)
    revision_requested --> in_review (next round starts)

Mission Types

Type Definitions

full

Phases: brainstorm → specify → plan → execute

Use when: Starting from scratch with no existing artifacts. The complete development lifecycle from ideation to implementation.

Auto-detected when: None of the following exist:

• docs/project-brief.md
• docs/specification.md
• docs/implementation-plan.md

standard

Phases: specify → plan → execute

Use when: A project brief exists but needs to be turned into a specification, planned, and executed.

Auto-detected when: docs/project-brief.md exists but docs/specification.md does not.

tactical

Phases: plan → execute

Use when: Specification is complete and ready for planning and implementation.

Auto-detected when: docs/specification.md exists but docs/implementation-plan.md does not.

quickfix

Phases: execute

Use when: Implementation plan exists and is ready for execution. Useful for resuming execution or running a quick fix with a pre-written plan.

Auto-detected when: docs/implementation-plan.md exists.

Auto-Detection Logic

function detect_mission_type():
    if exists("docs/implementation-plan.md"):
        return "quickfix"
    elif exists("docs/specification.md"):
        return "tactical"
    elif exists("docs/project-brief.md"):
        return "standard"
    else:
        return "full"

Priority: Later artifacts take precedence. If both a brief and a spec exist, the type is tactical (because the spec is a more advanced artifact).

Quality check: Existence alone is not sufficient. The artifact must be non-empty and contain expected sections. See state-detection.md for validation rules.

User Override

Users can override auto-detection:

# Force full lifecycle even if artifacts exist
/attune:mission --type full

# Skip brainstorming, go straight to spec
/attune:mission --type standard

# Just plan and execute
/attune:mission --type tactical

# Execute existing plan
/attune:mission --type quickfix

Custom Phase Sequences

For non-standard workflows, users can specify exact phases:

# Brainstorm then execute (skip spec and plan)
/attune:mission --phases brainstorm,execute

# Specify and plan without execution
/attune:mission --phases specify,plan

Validation: Custom sequences must maintain phase order (brainstorm < specify < plan < execute). Out-of-order phases are rejected.

Type Selection Display

When the orchestrator starts, it displays the detected type and asks for confirmation:

Mission Type: tactical (auto-detected)
  Reason: docs/specification.md exists, no implementation plan found
  Phases: plan → execute

Proceed with this mission type? [Y/n/override]

With --auto flag, this confirmation is skipped.

Phase Routing

Phase Execution Protocol

For each phase in the mission type's sequence, the orchestrator follows this protocol:

Phase: {phase_name}
  |
  1. Pre-Phase Validation
  |   Check prerequisites (prior phase artifacts exist and are valid)
  |   If invalid: STOP, report missing prerequisites
  |
  2. Invoke Skill
  |   Call Skill(attune:{phase-skill})
  |   The skill handles its own workflow entirely
  |
  3. Post-Phase Artifact Check
  |   Verify the expected output artifact was created
  |   If missing: Phase failed, enter error handling
  |
  4. Update Mission State
  |   Record phase completion in .attune/mission-state.json
  |   Include timestamps, artifact paths, any warnings
  |
  5. User Checkpoint (skippable with --auto)
  |   Present phase results and ask to proceed
  |   User can: continue, pause, abort, or re-run phase
  |
  6. Error Handling
      If phase failed: invoke leyline:damage-control
      Determine recovery action (retry, skip, escalate)

Skill Invocation Table

Pre-Phase Validation

Each phase has prerequisites that must be satisfied:

If a prerequisite is missing but a prior phase should have produced it, the orchestrator reports the gap rather than silently skipping.

Transition Hooks

Between phases, the orchestrator performs lightweight transitions:

brainstorm → specify

• Verify project brief is concrete (has goals and constraints)
• Pass brief path to specification skill
• Backlog triage: Scan spec/brief for "Out of Scope"

section. Create a GitHub issue for each deferred item. See below.

specify → plan

• Verify specification has testable requirements
• Check if war-room review was completed (recommended for RED+ projects)
• Backlog triage: If the specification skill did not

already create issues (check for issue numbers in the Out of Scope section), create them now.

plan → execute (Interactive Review Loop)

This transition is no longer a simple checkpoint. It invokes the full interactive review loop from modules/plan-review.md.

Transition protocol:

1. Version the plan: invoke plan-versioner to copy docs/implementation-plan.md to .attune/plan-history/plan-v1.md

2. Check iteration governor: verify round count (should be 1 for first pass)

3. Scan for additive bias: apply leyline:additive-bias-defense scrutiny questions to each plan section

4. Present for review: invoke plan-review to show sections one at a time with verdicts

5. Collect feedback: if any section is revise/reject, invoke feedback-collector

6. Inject context and re-plan: if revision needed, invoke context-injector, then re-invoke Skill(attune:project-planning) with revision context. Increment round. Go to step 1.

7. Mandatory war-room gate: when all sections approved, invoke Skill(attune:war-room) with full context including bias findings and the Prosecution Counsel role active

8. War room verdict:

• APPROVE: classify tasks by risk tier, generate

risk summary, proceed to execute

• CONCERNS/REJECT: convert war-room feedback to

revision context, increment round, go to step 1 (the governor check at step 2 enforces the cap)

• If iteration governor returns BLOCKED: present

escalation options (approve as-is / abort / restart from spec)

9. Risk classification: after war-room approval, invoke leyline:risk-classification on all tasks and generate risk summary for mission state

This replaces the previous 3-line transition. The old behavior (verify, classify, and summarize) is now step 9 after the review loop completes.

Post-Phase Backlog Triage

After the brainstorm and specify phases, scan the produced artifact for an "Out of Scope" section and create GitHub issues for each deferred item.

When to run: After brainstorm and specify phases. Skip after plan and execute (no new scope decisions).

Algorithm: 1. Read the phase artifact (brief or spec) 2. Find the "Out of Scope" heading 3. Extract each bullet point as a deferred item 4. For each item, check if it already has an issue reference (e.g., (#123)) 5. For items without references, create a GitHub issue:

   gh issue create \
     --title "[Backlog] <project>: <item summary>" \
     --body "## Context
   Identified during <phase> phase.
   Artifact: <artifact-path>

   ## Description
   <full item text from spec>" \
     --label "feature,low-priority"

6. Update the artifact's Out of Scope section with issue references: - Item description (#NNN) 7. Report created issues at the user checkpoint

Skip conditions:

• --no-auto-issues flag
• Item already has an issue reference
• Fewer than 1 item in Out of Scope section

User Checkpoints

After each phase, the orchestrator presents a checkpoint:

Phase Complete: specify
  Output: docs/specification.md (2,450 words, 8 user stories)
  Duration: 15 minutes
  Status: Success

  Next phase: plan
  [C]ontinue | [P]ause | [A]bort | [R]e-run phase

Checkpoint Behavior

Auto Mode

With --auto flag, checkpoints are skipped and phases proceed automatically. The orchestrator logs checkpoint data but does not pause.

Plan Review Checkpoint (replaces standard checkpoint for plan → execute)

The plan-to-execute transition uses the interactive review loop instead of the standard checkpoint. The user checkpoint is embedded in the section-by-section review process (see modules/plan-review.md).

The standard checkpoint format (Continue/Pause/Abort/ Re-run) is NOT shown for plan → execute. It is still used for all other phase transitions.

Error Handling

When a phase fails (skill errors, artifact not produced, validation failure):

1. Classify error: Map to leyline:damage-control categories

• Timeout/context overflow → context-overflow module
• Skill crash → agent-crash-recovery module
• Partial output → partial-failure-handling module

2. Attempt recovery:

• TRANSIENT: Retry phase (max 2 attempts)
• PERMANENT: Present error to user with options
• CRASH: Clear context, retry with fresh state

3. Update mission state: Record error, recovery attempt, and outcome

4. User decision: If recovery fails, present options:

• Retry phase manually
• Skip phase and continue (if safe)
• Abort mission

Plan Review

Purpose

Replace the lightweight plan-to-execute checkpoint with an interactive review loop. The user reviews the plan section by section, provides verdicts, and the plan is revised until approved or the iteration cap is reached. After user approval, the plan must pass a mandatory war-room review.

Review Flow

plan skill produces docs/implementation-plan.md
         |
         v
Plan Versioner: copy to plan-v1.md
         |
         v
Iteration Governor: check round (1/3)
         |
         v
Additive Bias Scan: scan plan for unjustified additions
  (findings displayed alongside plan sections)
         |
         v
Plan Presenter: show architecture section
  user: approve / revise / reject
         |
Plan Presenter: show phase 1
  user: approve / revise / reject
         |
... (remaining phases) ...
         |
         v
Feedback Collector: write round-N.json
         |
         v
All sections approved?
  |                    |
  no                   yes
  |                    |
  v                    v
Context Injector    Mandatory War Room Gate
  build revision      Skill(attune:war-room)
  re-invoke planning    |
  increment round       v
  loop back           War Room approves?
                        |            |
                        yes          no
                        |            |
                        v            v
                      EXECUTE     Feedback from war room
                                  counts as next round
                                  loop back to review

Section Parsing

Parse docs/implementation-plan.md into reviewable sections:

1. Architecture section: everything from the start of the plan through the first ## Phase or ## Task heading. This includes the Goal, Architecture, Tech Stack, and File Structure.

2. Phase sections: each ## Phase N: heading and its content through the next phase heading or EOF.

If the plan uses ### Task N: without phase groupings, group tasks into logical clusters of 3-5 tasks each.

Presentation Format

Section Display

--- Plan Review: {Section Name} (v{V}, round {R}/{MAX}) ---

{section content, verbatim from the plan}

{bias findings for this section, if any:}
  [BIAS] New caching layer -- which spec requirement
         demands this? (scrutiny Q4: no evidence)

------------------------------------------------------------
Verdict? [A]pprove / [R]evise / re[J]ect
>

Revision Rationale Prompt

When verdict is revise or reject:

Rationale (what to change):
>

Diff Summary (Round 2+)

At the start of round 2+, before section review:

--- Changes in v{V} (from round {R-1} feedback) ---
 {section}: +N lines, -M lines
   Addressed: "{feedback summary}"
 {section}: unchanged
-------------------------------------------------

War Room Gate

After all sections are approved:

1. Save the approved plan as the final version 2. Invoke Skill(attune:war-room) with:

• docs/implementation-plan.md (approved version)
• docs/specification.md (cross-reference)
• .attune/plan-history/feedback/ (revision history)
• .attune/plan-history/plan-v*.md (all versions)
• Risk classification from leyline:risk-classification
• Additive bias scan findings

3. The Prosecution Counsel role is always active 4. War room verdict determines next step:

• APPROVE: proceed to execute phase
• CONCERNS/REJECT: feedback enters revision loop,

counts toward iteration cap

Additive Bias Integration

Before presenting each section to the user, scan it using leyline:additive-bias-defense:

1. Apply the 5 scrutiny questions to each proposed component or abstraction in the section 2. Flag items where evidence (Q4) or consequence (Q5) answers are weak 3. Display findings inline with the section content 4. Record findings in the feedback file

This means the user sees bias warnings before making their verdict, giving them ammunition for targeted revision requests.

State Management

The plan-review module reads and writes the plan_review object in .attune/mission-state.json. See mission-state module for the full schema.

On each round:

• Increment current_round
• Append to versions array
• Update status (in_review / approved / rejected)
• Record war_room_verdict when available

Plan Versioner

Purpose

Track every iteration of the implementation plan as a separate file. Generate human-readable diff summaries showing what changed between versions and why.

Storage Layout

.attune/
  plan-history/
    plan-v1.md          # First version
    plan-v2.md          # After round 1 feedback
    plan-v3.md          # After round 2 feedback
    feedback/
      round-1.json      # Feedback that prompted v2
      round-2.json      # Feedback that prompted v3

Versioning Protocol

On Initial Plan Creation

When Skill(attune:project-planning) produces docs/implementation-plan.md:

1. Create .attune/plan-history/ if it does not exist 2. Copy docs/implementation-plan.md to .attune/plan-history/plan-v1.md 3. Record version 1 in mission state

mkdir -p .attune/plan-history/feedback
cp docs/implementation-plan.md .attune/plan-history/plan-v1.md

On Plan Revision

When the planning skill produces a revised plan after feedback:

1. Copy new docs/implementation-plan.md to .attune/plan-history/plan-v{N}.md 2. Generate diff summary between v{N-1} and v{N} 3. Record version N in mission state

cp docs/implementation-plan.md .attune/plan-history/plan-v${N}.md

Diff Summary Generation

Compare the previous and current versions section by section. Produce a human-readable summary:

--- Changes in v2 (from round 1 feedback) ---
 Architecture: +12 lines, -8 lines
   Addressed: "Split API layer" -> added read/write separation
 Phase 1: unchanged
 Phase 3: +4 lines (new error handling tasks)
----------------------------------------------

Algorithm

1. Split both versions by heading (## or ### ) 2. For each section present in both versions:

• If identical: report "unchanged"
• If different: count added/removed lines, summarize

what changed by correlating with the feedback that prompted the revision 3. For sections only in the new version: report "new" 4. For sections only in the old version: report "removed"

Diff Command

diff --unified=3 \
  .attune/plan-history/plan-v${PREV}.md \
  .attune/plan-history/plan-v${CURR}.md \
  | head -100

Cleanup

After execution phase completes, plan history can be kept for retrospectives or removed:

# Optional cleanup (not automatic)
rm -rf .attune/plan-history/

The orchestrator does NOT auto-delete plan history. Users decide whether to keep it.

Reflexion Buffer

Purpose

When a phase fails and damage-control triggers a retry, the agent retries blind. This module maintains an episodic memory of what was tried, what failed, and why, so each retry sees the full failure history and avoids repeating the same mistakes.

Based on the Reflexion pattern (Shinn et al., NeurIPS 2023): verbal self-critiques stored in a buffer provide reinforcement across attempts without fine-tuning.

Buffer Structure

Each phase maintains its own buffer. Entries accumulate across retry attempts within a single iteration-governor round.

{
  "phase": "execute",
  "max_attempts": 3,
  "entries": [
    {
      "attempt": 1,
      "action": "Ran integration test suite after T012",
      "result": "Timeout after 120s on test_api_auth",
      "diagnosis": "Auth mock server not started before test invocation",
      "adjustment": "Start mock server in setup fixture, add health check before test run"
    }
  ]
}

Field Definitions

Context Injection Format

Before each retry, inject the full buffer into the phase prompt. The retry MUST see all prior failures, not just the most recent.

## Reflexion Buffer (Phase: {phase}, Attempt {N}/{max})

### Attempt 1: FAILED
**Action**: {action}
**Result**: {result}
**Diagnosis**: {diagnosis}
**Adjustment**: {adjustment}

Repeat the block for each prior attempt. One heading block, no redundant framing.

Integration with Phase Routing

The buffer hooks into the error handling path defined in modules/phase-routing.md, step 6:

Phase fails
  |
  1. Classify error (existing damage-control step)
  |
  2. Build reflexion entry
  |   Extract: action, result, diagnosis, adjustment
  |   Append to buffer
  |
  3. Check convergence (see below)
  |   If converged: escalate, skip retry
  |
  4. Inject buffer into retry context
  |   Prepend buffer block to phase prompt
  |
  5. Retry phase (existing damage-control step)

Steps 2-4 are new. Steps 1 and 5 are the existing damage-control flow.

Convergence Detection

If the buffer shows the same failure repeating, retrying is pointless. Detect convergence and escalate instead.

Algorithm:

function is_converged(entries):
    if len(entries) < 2:
        return false

    last = entries[-1]
    prev = entries[-2]

    # Same error category repeating
    if similar(last.result, prev.result) and
       similar(last.diagnosis, prev.diagnosis):
        return true

    return false

Similarity check: Compare result and diagnosis fields. If both share the same error type or message, the attempts are converging. Exact string matching is sufficient; the agent will reuse phrasing for identical root causes.

On convergence: Skip remaining retries:

Reflexion buffer detected repeated failure pattern.

  Attempt {N-1}: {diagnosis}
  Attempt {N}:   {diagnosis}

Retrying is unlikely to help. Options:
  [A] Retry anyway (override convergence detection)
  [B] Skip this phase and continue
  [C] Abort mission

Buffer Lifecycle

1. Created: When a phase begins execution. Empty buffer initialized with phase name and max_attempts.

2. Populated: On each phase failure, before retry. One entry appended per failed attempt.

3. Persisted: Written to mission-state.json under the phase object on phase completion (success or exhaustion) for post-mission analysis.

4. Cleared: When the next phase begins. Prior phase buffers remain in mission-state.json.

State Schema Addition

Add reflexion_buffer to each phase entry in mission-state.json (same schema as the buffer structure above). An empty entries array means the phase succeeded on first attempt.

Integration with Ralph Wiggum

When ralph-wiggum:ralph-loop is active, each rejection becomes a reflexion entry:

• action: the completion claim
• result: "Rejected by ralph-loop: {reason}"
• diagnosis: extracted from ralph's feedback
• adjustment: derived from ralph's specific ask

The buffer is injected into the next ralph iteration, preventing the agent from repeating incomplete work that ralph already rejected.

Self-Critique Quality

The diagnosis field must contain a root cause, not a restatement of the error.

• Bad: "The test failed." (restates the result)
• Good: "Auth mock not initialized before test

runner started. Setup fixture creates the mock but does not wait for its health endpoint."

If the root cause is unclear, say so: "Root cause unclear. Possible: resource contention, missing async await, or flaky external dependency." An honest "I do not know" beats a fabricated diagnosis.

State Detection

Artifact Existence Checks

The orchestrator scans for these artifacts to determine project state:

Alternative Paths

Some projects may use non-standard paths. The orchestrator also checks:

• project-brief.md (root level)
• specification.md (root level)
• implementation-plan.md (root level)
• .specify/ directory (spec-kit convention)

Quality Validation

An artifact file must pass quality checks to be considered "complete":

Non-Empty Check

File must contain more than just whitespace or a single heading. Minimum: 100 characters of content.

Required Sections

Frontmatter Status

If the artifact has YAML frontmatter with a status field, it must be:

• complete or approved: artifact is ready
• draft or in-progress: artifact exists but is not ready (treated as non-existent for type detection)
• rejected: artifact should be regenerated

Staleness Detection

Artifacts may become stale when the codebase evolves after they were written:

Staleness Signals

Staleness Response

Stale artifacts trigger a warning but do not block mission execution:

Warning: docs/specification.md was last modified 14 days ago.
The codebase has 23 commits since then.
Consider refreshing with /attune:specify before proceeding.

Continue anyway? [Y/n]

With --auto flag, stale artifacts are accepted with a logged warning.

State Detection Result

The detection phase produces a structured result:

{
  "artifacts": {
    "project_brief": {
      "exists": true,
      "path": "docs/project-brief.md",
      "quality": "valid",
      "last_modified": "2026-02-01T10:00:00Z",
      "stale": false
    },
    "specification": {
      "exists": true,
      "path": "docs/specification.md",
      "quality": "valid",
      "last_modified": "2026-02-05T14:30:00Z",
      "stale": false
    },
    "implementation_plan": {
      "exists": false
    },
    "execution_state": {
      "exists": false
    }
  },
  "detected_type": "tactical",
  "confidence": "high"
}

Trust Tier

Purpose

Reduce checkpoint friction for skills that have demonstrated competence. Trust is earned slowly through repeated success and lost quickly on failure. This follows the Auto MoC principle: by batch four, 95% of fixes ran without asking permission. Experienced users increase both autonomy and strategic interruption (Anthropic autonomy research).

Three Trust Tiers

Trust Score Tracking

Track per skill in .attune/trust-scores.json:

{
  "brainstorm": {
    "executions": 18, "successes": 17, "failures": 1,
    "tier": "T3",
    "last_promotion": "2026-03-20T14:00:00Z",
    "last_failure": "2026-02-15T10:30:00Z"
  }
}

Success: phase completed without user intervention or rollback. Failure: phase required user correction, damage-control, or rollback.

Tier Transitions

Trust is earned slowly, lost quickly: 5 successes to promote, 1 failure to demote.

Promotion

Check after every successful execution:

function check_promotion(skill):
    record = trust_scores[skill]
    rate = record.successes / record.executions
    if record.tier == "T1"
       and record.executions >= 5
       and rate > 0.85:
        promote(skill, "T2")
    elif record.tier == "T2"
       and record.executions >= 15
       and rate > 0.95:
        promote(skill, "T3")

Demotion

Immediate on any failure at T2 or T3:

function on_failure(skill):
    record = trust_scores[skill]
    record.failures += 1
    if record.tier == "T3":
        demote(skill, "T2")
    elif record.tier == "T2":
        demote(skill, "T1")
    # T1 stays at T1 (already maximum oversight)

Demotion does not reset execution counts. The skill must re-qualify by accumulating enough successes to restore its success rate above the threshold.

Checkpoint Reduction Rules

The --auto flag overrides all tiers to T3 behavior. This is the existing feature from phase-routing; trust tiers provide the same outcome without the global flag.

Integration with Phase Routing

Phase-routing step 5 (User Checkpoint) consults the trust tier before presenting a checkpoint:

function should_checkpoint(phase, skill):
    tier = trust_scores[skill].tier

    # Safety checkpoints always fire (see below)
    if is_safety_checkpoint(phase):
        return true

    if tier == "T1":
        return true
    elif tier == "T2":
        return phase in ["specify", "execute"]
    elif tier == "T3":
        return false  # start/end handled by orchestrator

When the tier allows skipping, the orchestrator logs the checkpoint data (for auditability) but does not pause for user input. When the tier requires it, the checkpoint presents as normal.

Strategic Interruption

Even at T3, certain events always trigger a checkpoint regardless of trust tier. Trust reduces routine checkpoints, not safety checkpoints.

Always-checkpoint events:

• Destructive operations: file deletion, force push,

branch reset

• External-facing actions: PR creation, issue comments,

release tagging

• Scope expansion: adding features not in the original

plan or specification

• Cost thresholds: operations exceeding estimated

token/time budgets

function is_safety_checkpoint(phase_context):
    return (phase_context.has_destructive_ops
         or phase_context.has_external_actions
         or phase_context.scope_expanded
         or phase_context.budget_exceeded)

State and Dashboard

Storage: .attune/trust-scores.json (alongside mission state). The orchestrator reads scores at mission start and writes updates after each phase. Scores persist across missions; they track long-term skill reliability, not single-mission state. If the file does not exist, all skills default to T1.

For /attune:status, display current trust tiers:

Trust Tiers:
  T3 (Autonomous): brainstorm, specify [15+ runs, 97%]
  T2 (Guided):     plan, execute [8 runs, 88%]
  T1 (Supervised): new-skill [0 runs]

Mission Charter Template

Structured mission definition for coordinated agent work.

Purpose

A Mission Charter defines the boundaries and success criteria for a mission before execution begins. It prevents scope drift, establishes clear completion criteria, and provides a reference point for checkpoint reviews.

When to Use

Use a Mission Charter when:

• Starting a new mission that will span multiple phases
• Coordinating work across multiple agents or sessions
• You need clear scope boundaries to prevent drift
• Success criteria need to be explicit and measurable
• Resource constraints (tokens, time) must be tracked

Do NOT use when:

• The task is a single, self-contained change
• Scope is obvious and doesn't need formalization
• The work is exploratory and boundaries are unknown

Getting Started

1. Copy the template below into your mission planning document 2. Fill in the required fields: outcome, success_metric, deadline, scope, stop_criteria 3. Add optional constraints if you have token/time budgets 4. Store in .attune/mission-state.json or your planning document 5. Reference during checkpoint reviews to verify scope adherence

Why This Pattern

Mission Charters prevent the common failure mode of "scope creep by accident." Without explicit boundaries, missions tend to expand to fill available time and tokens. The charter creates a contract that forces explicit decisions when scope changes are proposed.

This pattern emerged from observing that agents with clear boundaries complete missions faster and with fewer reworks than agents who discover scope as they go.

Template

mission_charter:
  # REQUIRED: What success looks like
  outcome: |
    Clear description of the desired end state.
    Should be specific enough to verify completion.

  # REQUIRED: How we measure success
  success_metric: |
    Measurable criteria for mission completion.
    Example: "All tests pass, no lint errors, feature works in demo"

  # REQUIRED: Time boundary
  deadline: session | YYYY-MM-DD | "<duration>"
    # session = complete within this Claude session
    # date = absolute deadline
    # duration = relative (e.g., "2 hours", "3 days")

  # OPTIONAL: Resource and action constraints
  constraints:
    token_budget: 50000      # Maximum tokens to spend (optional)
    time_budget: "2 hours"   # Maximum time (optional)
    forbidden:               # Actions that must NOT be taken
      - "No database schema changes"
      - "No API breaking changes"

  # REQUIRED: Scope boundaries
  scope:
    in_scope:                # Areas to work on
      - "src/api/"
      - "tests/api/"
    out_of_scope:            # Areas to avoid
      - "Frontend code"
      - "Database migrations"

  # REQUIRED: Conditions that halt the mission
  stop_criteria:
    - "Token budget exceeded"
    - "Blocker identified that requires user decision"
    - "External dependency unavailable"

Examples

Example 1: Feature Implementation

mission_charter:
  outcome: |
    Implement user authentication with JWT tokens, including
    login, logout, and token refresh endpoints.

  success_metric: |
    - All auth endpoints return correct responses
    - Token validation works for protected routes
    - Test coverage > 90% for auth module

  deadline: session

  constraints:
    token_budget: 80000
    forbidden:
      - "No changes to existing user schema"
      - "No breaking changes to public API"

  scope:
    in_scope:
      - "src/auth/"
      - "tests/auth/"
      - "docs/api/auth.md"
    out_of_scope:
      - "Frontend login UI"
      - "OAuth integration"

  stop_criteria:
    - "Token budget exceeded"
    - "Security vulnerability discovered"
    - "User requirement clarification needed"

Example 2: Bug Fix

mission_charter:
  outcome: |
    Fix the race condition in the order processing queue that
    causes duplicate orders under high load.

  success_metric: |
    - Load test with 1000 concurrent requests shows no duplicates
    - All existing tests pass
    - Fix verified in staging environment

  deadline: "2024-03-20"

  constraints:
    time_budget: "4 hours"
    forbidden:
      - "No changes to queue infrastructure"
      - "No breaking API changes"

  scope:
    in_scope:
      - "src/queue/order_processor.py"
      - "tests/queue/"
    out_of_scope:
      - "Other queue handlers"
      - "Database schema"

  stop_criteria:
    - "Root cause requires architectural changes"
    - "Fix would impact other queue handlers"

Example 3: Refactoring

mission_charter:
  outcome: |
    Extract the validation logic from the monolithic service
    class into separate validator modules following SRP.

  success_metric: |
    - All validators have single responsibility
    - Test coverage maintained or improved
    - No behavior changes (same test results)

  deadline: session

  constraints:
    token_budget: 60000
    forbidden:
      - "No public API changes"
      - "No new dependencies"

  scope:
    in_scope:
      - "src/services/order_service.py"
      - "src/validators/"
      - "tests/validators/"
    out_of_scope:
      - "Other service classes"
      - "Frontend validation"

  stop_criteria:
    - "Refactoring reveals deeper architectural issues"
    - "Tests start failing unexpectedly"

Integration with Mission Orchestrator

The mission-orchestrator skill uses Mission Charters to:

1. Initialize mission state - Store charter in .attune/mission-state.json 2. Guide phase execution - Each phase checks scope boundaries 3. Enable checkpoint reviews - Progress Reports reference original charter 4. Determine completion - Success metric verified before mission close

Related References

• progress-report.md - Checkpoint template that references

mission charter

• ../modules/mission-types.md - Mission type definitions
• ../modules/phase-routing.md - Phase execution protocol

Progress Report Template

Checkpoint status report for mission progress tracking.

Purpose

Progress Reports provide structured checkpoints during mission execution. They track progress, surface blockers, monitor budget consumption, and update risk status. Use them at natural phase boundaries or when significant changes occur.

When to Use

Generate a Progress Report when:

• Crossing phase boundaries (brainstorm→specify→plan→execute)
• A blocker is identified that halts forward progress
• Risk level escalates (e.g., Level 1→Level 2)
• Budget thresholds reached (50%, 75%, 90% of tokens/time)
• Every 30-60 minutes for long-running missions
• User asks "what's the status?"

Do NOT generate when:

• Progress is continuous and unremarkable
• No blockers, budget concerns, or risk changes
• Less than 15 minutes since last report

Getting Started

1. Copy the template below 2. Fill required fields: timestamp, phase, progress, blockers, budget, risks, next_actions 3. Add optional decisions if significant choices were made 4. Store in mission state or append to session log 5. Compare against Mission Charter to check scope adherence

Why This Pattern

Progress Reports create a verifiable audit trail. Without them, long missions become opaque: blockers hide, budgets silently exhaust, and scope drifts undetected until it's too late.

The structured format forces explicit acknowledgment of:

• What's blocked (and who owns unblocking)
• How much budget remains (and whether to continue)
• What risks have changed (and whether to escalate)

This pattern emerged from observing that missions with regular checkpoints have higher success rates and fewer "surprise failures."

Template

progress_report:
  # REQUIRED: When this report was generated
  timestamp: "2024-03-20T14:30:00Z"

  # REQUIRED: Current phase in the mission lifecycle
  phase: brainstorm | specify | plan | execute

  # REQUIRED: Task progress summary
  progress:
    tasks_complete: 3
    tasks_total: 8
    tasks_blocked: 1
    tasks_in_progress: 2

  # REQUIRED: Items blocking progress (empty if none)
  blockers:
    - description: "Waiting for API key from ops team"
      impact: "Cannot test production integration"
      owner: "user"
      ETA: "2024-03-21"

  # REQUIRED: Budget consumption
  budget:
    tokens_used: 45000
    tokens_budget: 80000        # null if unlimited
    time_elapsed: "1h 30m"
    time_budget: "3 hours"      # null if unlimited

  # REQUIRED: Risk status updates
  risks:
    current_readiness_level: 1  # 0-3 scale
    new_risks:
      - "Third-party API has stricter rate limits than documented"
    resolved_risks:
      - "Database migration approach validated"
    escalated_risks: []         # Risks moved to higher level

  # REQUIRED: Immediate next steps
  next_actions:
    - "Complete task T004 (API client implementation)"
    - "Resolve blocker: obtain API key"
    - "Run integration tests before checkpoint"

  # OPTIONAL: Decisions made since last report
  decisions:
    - choice: "Use Redis for caching instead of Memcached"
      rationale: "Better support for our data structures"
      alternatives_considered: ["Memcached", "In-memory"]

  # OPTIONAL: Notes for the record
  notes: |
    Discovered that the legacy API returns different error codes
    than documented. Updated test expectations accordingly.

Example Reports

Example 1: Mid-Execution Checkpoint

progress_report:
  timestamp: "2024-03-20T14:30:00Z"
  phase: execute

  progress:
    tasks_complete: 5
    tasks_total: 12
    tasks_blocked: 0
    tasks_in_progress: 2

  blockers: []

  budget:
    tokens_used: 52000
    tokens_budget: 100000
    time_elapsed: "2h 15m"
    time_budget: "4 hours"

  risks:
    current_readiness_level: 1
    new_risks: []
    resolved_risks:
      - "API authentication approach confirmed working"
    escalated_risks: []

  next_actions:
    - "Complete T006: Add pagination to list endpoint"
    - "Complete T007: Write integration tests"
    - "Review all API endpoints for consistency"

  decisions:
    - choice: "Use cursor-based pagination"
      rationale: "Better performance for large datasets"
      alternatives_considered: ["Offset-based pagination"]

  notes: |
    All API endpoints now return consistent error responses.
    Ready to proceed with frontend integration.

Example 2: Blocked Checkpoint

progress_report:
  timestamp: "2024-03-20T16:00:00Z"
  phase: execute

  progress:
    tasks_complete: 7
    tasks_total: 12
    tasks_blocked: 2
    tasks_in_progress: 0

  blockers:
    - description: "Database migration requires DBA approval"
      impact: "Cannot test schema changes in staging"
      owner: "DBA team"
      ETA: "2024-03-21T10:00:00Z"
    - description: "Feature flag not configured in production"
      impact: "Cannot verify production behavior"
      owner: "Platform team"
      ETA: "2024-03-21"

  budget:
    tokens_used: 68000
    tokens_budget: 100000
    time_elapsed: "3h 45m"
    time_budget: "4 hours"

  risks:
    current_readiness_level: 2
    new_risks:
      - "Time budget nearly exhausted with blockers pending"
    resolved_risks: []
    escalated_risks: []

  next_actions:
    - "Follow up with DBA team on migration approval"
    - "Request feature flag configuration from platform"
    - "Document current state for handoff if needed"

  decisions: []

  notes: |
    Mission paused pending external dependencies.
    All implementable tasks complete. Ready to resume
    once blockers clear.

Example 3: Risk Escalation Checkpoint

progress_report:
  timestamp: "2024-03-20T11:00:00Z"
  phase: plan

  progress:
    tasks_complete: 2
    tasks_total: 5
    tasks_blocked: 0
    tasks_in_progress: 1

  blockers: []

  budget:
    tokens_used: 25000
    tokens_budget: 80000
    time_elapsed: "45m"
    time_budget: "2 hours"

  risks:
    current_readiness_level: 2  # Escalated from 1
    new_risks: []
    resolved_risks: []
    escalated_risks:
      - risk: "Authentication changes affect production users"
        from_level: 1
        to_level: 2
        reason: "Discovered 10x more active users than expected"

  next_actions:
    - "Request war-room checkpoint for Level 2 review"
    - "Complete implementation plan with additional controls"
    - "Add staged rollout to plan"

  decisions:
    - choice: "Add feature flag for gradual rollout"
      rationale: "Mitigates risk of widespread auth failure"
      alternatives_considered: ["Direct deploy", "Canary only"]

  notes: |
    Discovered production user count is 10x higher than
    documented. Escalating to Level 2 for additional controls.

Checkpoint Rhythm

When to generate Progress Reports:

1. Phase boundaries: Between brainstorm→specify→plan→execute 2. Blocker identification: When progress is blocked 3. Risk escalation: When readiness level increases 4. Budget thresholds: At 50%, 75%, 90% budget consumption 5. Time intervals: Every 30-60 minutes for long missions 6. User request: When user asks for status

Integration with Mission Charter

Progress Reports reference the original Mission Charter:

mission_charter_ref: "docs/project-brief.md"
charter_status:
  outcome_progress: "60% complete"
  success_metric_status: "On track"
  constraints_status: "Within budget, no forbidden actions"
  scope_adherence: "No scope drift detected"

Integration with Mission Orchestrator

The mission-orchestrator skill uses Progress Reports to:

1. Track phase progress - Update mission state with task completion 2. Surface blockers - Alert user to items requiring attention 3. Monitor budget - Warn when approaching limits 4. Update risk status - Adjust readiness level as needed

Related References

• mission-charter.md - Original mission definition
• ../modules/mission-state.md - State persistence schema
• ../../project-execution/references/mission-report.md - Final mission report