---
name: mosaic-orchestrator
description: Initialize and run Mosaic orchestration missions. Use when starting a new mission (set of tasks for a project), checking mission status, resuming an orchestrator session, or running the coordinator loop. Wraps scripts in ~/.config/mosaic/tools/orchestrator/. Read ORCHESTRATOR.md and E2E-DELIVERY.md before initiating Orchestrator mode.
---

# mosaic-orchestrator

Mosaic mission and orchestrator session management.

## Mandatory Pre-Flight

Before initiating Orchestrator mode, always read:
1. `~/.config/mosaic/guides/ORCHESTRATOR.md`
2. `~/.config/mosaic/guides/E2E-DELIVERY.md`

Then declare: **"Now initiating Orchestrator mode..."**

## Binary

```bash
export PATH="$HOME/.config/mosaic/bin:$PATH"
mosaic --help
```

## CLI Commands

```bash
# Initialize a mission (PRD-driven)
mosaic prdy init --project <path>

# Initialize coordinator mission
mosaic coord init --name <name> --project <path> [--milestones m1,m2]

# Run coordinator (launches orchestrator session)
mosaic coord run --project <path>

# Launch a coding worker (Claude Code with mosaic rails)
mosaic yolo claude   # Claude Code
mosaic yolo codex    # Codex
mosaic yolo glm      # GLM-5

# Health audit
mosaic doctor
```

## Orchestrator Scripts

Located in `~/.config/mosaic/tools/orchestrator/`.

| Script | Purpose |
|---|---|
| `mission-init.sh` | Initialize mission.json and TASKS.md scaffold |
| `mission-status.sh` | Show current mission + task state |
| `session-run.sh` | Launch an orchestrator session |
| `session-resume.sh` | Resume a paused orchestrator session |
| `session-status.sh` | Check session health / lock status |
| `smoke-test.sh` | Post-deploy smoke test |
| `continue-prompt.sh` | Generate a continue prompt for session |

## Mission Init Pattern

```bash
export PATH="$HOME/.config/mosaic/bin:$PATH"
cd ~/src/<repo>
mosaic coord init \
  --name "<mission-name>" \
  --project . \
  --milestones "milestone-1,milestone-2"
mosaic coord run --project .
```

## Worker Launch Rules (MANDATORY)

- **Max 1 Claude (Sonnet) worker at a time** — serial only
- **Max 6 Codex workers at a time**
- Always use `mosaic yolo <agent>` from the project directory — never `sessions_spawn` for coding
- Workers: implement → lint → push branch → open PR → fire system event → **EXIT** (never merge)

## Agent State

```bash
~/.openclaw/workspace/agents/bin/agent-state status   # Check active agents
~/.openclaw/workspace/agents/bin/agent-state clear <task>  # Clear stale entry
```

## Completion Gates

A task is NOT done until all of:
- [ ] Code review ✓
- [ ] Security review ✓
- [ ] Tests GREEN ✓
- [ ] CI green ✓
- [ ] Issue closed ✓
- [ ] Docs updated ✓