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

```markdown
| 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 and Capsule Format

The coordinator generates this (via `mosaic coord continue`) and writes a machine-readable capsule at `.mosaic/orchestrator/next-task.json`:

```
## 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

### Between Sessions (r0 assisted)

Use `mosaic coord run` to remove copy/paste steps:

1. Agent stops
2. Human runs `mosaic coord run [--claude|--codex]`
3. Coordinator regenerates continuation prompt + `next-task.json`
4. Coordinator launches selected runtime with scoped kickoff context
5. New session resumes from next task

---

## 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 run [--claude|--codex]` | Generate continuation context and launch runtime |
| `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 → run → 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)