bootstrap/guides/ORCHESTRATOR-PROTOCOL.md

Orchestrator Protocol — Mission Lifecycle Guide

Operational guide for agent sessions. Distilled from the full specification at jarvis-brain/docs/protocols/ORCHESTRATOR-PROTOCOL.md (1,066 lines).

Load this guide when: active mission detected, multi-milestone orchestration, mission continuation. Load ORCHESTRATOR.md for per-session execution protocol (planning, coding, review, commit cycle).

---

1. Relationship to ORCHESTRATOR.md

Concern	Guide
How to execute within a session (plan, code, test, review, commit)	ORCHESTRATOR.md
How to manage a mission across sessions (resume, continue, handoff)	This guide
Both guides are active simultaneously during orchestration missions.

---

2. Mission Manifest

Location: docs/MISSION-MANIFEST.md Owner: Orchestrator (sole writer) Template: ~/.config/mosaic/templates/docs/MISSION-MANIFEST.md.template

The manifest is the persistent document tracking full mission scope, status, milestones, and session history. It survives session death.

Update Rules

• Update Phase when transitioning (Intake → Planning → Execution → Continuation → Completion)
• Update Current Milestone when starting a new milestone
• Update Progress after each milestone completion
• Append to Session History at session start and end
• Update Status to completed only when ALL success criteria are verified

Hard Rule

The manifest is the source of truth for mission scope. If the manifest says a milestone is done, it is done. If it says remaining, it remains.

---

3. Scratchpad Protocol

Location: docs/scratchpads/{mission-id}.md Template: ~/.config/mosaic/templates/docs/mission-scratchpad.md.template

Rules

1. First action — Before ANY planning or coding, write the mission prompt to the scratchpad
2. Append-only — NEVER delete or overwrite previous entries
3. Session log — Record session start, tasks done, and outcome at session end
4. Decisions — Record all planning decisions with rationale
5. Corrections — Record course corrections from human or coordinator
6. Never deleted — Scratchpads survive mission completion (archival reference)

---

4. TASKS.md as Control Plane

Location: docs/TASKS.md Owner: Orchestrator (sole writer). Workers read but NEVER modify.

Table Schema

| id | status | milestone | description | pr | notes |

Status Values

not-started → in-progress → done (or blocked / failed)

Planning Tasks Are First-Class

Include explicit planning tasks (e.g., PLAN-001: Break down milestone into tasks). These count toward progress.

Post-Merge Tasks Are Explicit

Include verification tasks after merge: CI check, deployment verification, Playwright test. Don't assume they happen automatically.

---

5. Session Resume Protocol

When starting a session and an active mission is detected, follow this checklist:

Detection (5-point check)

1. docs/MISSION-MANIFEST.md exists → read Phase, Current Milestone, Progress
2. docs/scratchpads/*.md exists → read latest scratchpad for decisions and corrections
3. docs/TASKS.md exists → read task state (what's done, what's next)
4. Git state → current branch, open PRs, recent commits
5. Provider state → open issues, milestone status (if accessible)

Resume Procedure

1. Read the mission manifest FIRST
2. Read the scratchpad for session history and corrections
3. Read TASKS.md for current task state
4. Identify the next not-started or in-progress task
5. Continue execution from that task
6. Update Session History in the manifest

Dirty State Recovery

State	Recovery
Dirty git working tree	Stash changes, log stash ref in scratchpad, resume clean
Open PR in bad state	Check PR status, close if broken, re-create if needed
Half-created issues	Audit issues against TASKS.md, reconcile
Tasks marked in-progress	Check if work was committed; if so, mark done; if not, restart task

Hard Rule

Session state is NEVER automatically deleted. The coordinator (human or automated) must explicitly request cleanup.

---

6. Mission Continuation

When a milestone completes and more milestones remain:

Agent Handoff (at ~55-60% context)

If context usage is high, produce a handoff message:

1. Update TASKS.md with final task statuses
2. Update mission manifest with session results
3. Append session summary to scratchpad
4. Commit all state files
5. The coordinator will generate a continuation prompt for the next session

Continuation Prompt Format

The coordinator generates this (via mosaic coord continue):

## Continuation Mission
Continue **{mission}** from existing state.
- Read docs/MISSION-MANIFEST.md for scope and status
- Read docs/scratchpads/{id}.md for decisions
- Read docs/TASKS.md for current state
- Continue from task {next-task-id}

Between Sessions (r0 manual)

1. Agent stops (expected — this is the confirmed stamina limitation)
2. Human runs mosaic coord mission to check status
3. Human runs mosaic coord continue to generate continuation prompt
4. Human launches new session and pastes the prompt
5. New agent reads manifest, scratchpad, TASKS.md and continues

---

7. Failure Taxonomy Quick Reference

Code	Type	Recovery
F1	Premature Stop	Continuation prompt → new session (most common)
F2	Context Exhaustion	Handoff message → new session
F3	Session Crash	Check git state → mosaic coord resume → new session
F4	Error Spiral	Kill session, mark task blocked, skip to next
F5	Quality Gate Failure	Create QA remediation task
F6	Infrastructure Failure	Pause, retry when service recovers
F7	False Completion	Append correction to scratchpad, relaunch
F8	Scope Drift	Kill session, relaunch with scratchpad ref
F9	Subagent Failure	Orchestrator retries or creates remediation
F10	Deadlock	Escalate to human

F1: Premature Stop — Detailed Recovery

This is the confirmed, most common failure. Every session will eventually trigger F1.

1. Session ends with tasks remaining in TASKS.md
2. Run mosaic coord mission — verify milestone status
3. If milestone complete: verify CI green, deployed, issues closed
4. Run mosaic coord continue — generates scoped continuation prompt
5. Launch new session, paste prompt
6. New session reads state and continues from next pending task

---

8. r0 Manual Coordinator Process

In r0, the Coordinator is Jason + shell scripts. No daemon. No automation.

Commands

Command	Purpose
mosaic coord init --name "..." --milestones "..."	Initialize a new mission
mosaic coord mission	Show mission progress dashboard
mosaic coord status	Check if agent session is still running
mosaic coord continue	Generate continuation prompt for next session
mosaic coord resume	Crash recovery (detect dirty state, generate fix)
mosaic coord resume --clean-lock	Clear stale session lock after review

Typical Workflow

init → launch agent → [agent works] → agent stops →
status → mission → continue → launch agent → repeat

---

9. Operational Checklist

Pre-Mission

• Mission initialized: mosaic coord init
• docs/MISSION-MANIFEST.md exists with scope and milestones
• docs/TASKS.md scaffolded
• docs/scratchpads/{id}.md scaffolded
• Success criteria defined in manifest

Session Start

• Read manifest → know phase, milestone, progress
• Read scratchpad → know decisions, corrections, history
• Read TASKS.md → know what's done and what's next
• Write session start to scratchpad
• Update Session History in manifest

Planning Gate (Hard Gate — No Coding Until Complete)

• Milestones created in provider (Gitea/GitHub)
• Issues created for all milestone tasks
• TASKS.md populated with all planned tasks (including planning + verification tasks)
• All planning artifacts committed and pushed

Per-Task

• Update task status to in-progress in TASKS.md
• Execute task following ORCHESTRATOR.md cycle
• Update task status to done (or blocked/failed)
• Commit, push

Milestone Completion

• All milestone tasks in TASKS.md are done
• CI/pipeline green
• PR merged to main
• Issues closed
• Update manifest: milestone status → completed
• Update scratchpad: session log entry
• If deployment target: verify accessible

Mission Completion

• ALL milestones completed
• ALL success criteria verified with evidence
• manifest status → completed
• Final scratchpad entry with completion evidence
• Release tag created and pushed (if applicable)