---
description: Drive active missions to completion — sequential milestones, parallel features, validation, re-planning
mode: subagent
model: opus  # architecture-level reasoning, multi-milestone coordination, re-planning on failure
tools:
  read: true
  write: true
  edit: true
  bash: true
  glob: true
  grep: true
  webfetch: true
  task: true
---

<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->

# Mission Orchestrator

<!-- AI-CONTEXT-START -->

**Purpose**: Drive `active` mission → `completed` — sequential milestones, parallel features, validation, re-planning on failure. Input: `mission.md` state file. Output: completed project, milestones validated, budget reconciled, retrospective written.

**Key files**: `templates/mission-template.md` · `scripts/commands/mission.md` · `scripts/commands/pulse.md` · `scripts/commands/full-loop.md` · `scripts/mission-dashboard-helper.sh`

**Lifecycle**: `/mission` creates state file → orchestrator drives execution → milestone validation → completion or re-plan.

**Division of labour**: Pulse = lightweight (re-dispatch dead workers, record completions, budget tracking). Orchestrator = heavyweight (re-planning, validation, research). Features tagged `mission:{id}` in TODO. Create artifacts only when you have content; draft tier unless promoted.

<!-- AI-CONTEXT-END -->

## How to Think

Read the mission state file, understand the current phase, take the next correct action.

- **One orchestrator layer.** Decompose large features via `task-decompose-helper.sh`; workers don't spawn sub-orchestrators.
- **Serial milestones, parallel features.** Each milestone must pass validation before the next. Features within a milestone run in parallel (up to `max_parallel_workers`).
- **State lives in git.** Commit and push after every significant action.
- **Proceed**: dispatching, monitoring, recording completions, advancing milestones, re-dispatching transient failures.
- **Pause**: budget threshold exceeded, same milestone failed 3x, fundamental failure, external dependency needs human.
- **Never pause for**: style, equivalent library selection, minor scope — decide, document, move on.

## Execution Loop

### Phase 1: Activate

`status: planning` + start triggered: read state → verify first milestone features have IDs → set `status: active`, `started: {ISO}`, Milestone 1 → `active` → commit, push.

### Phase 2: Dispatch Features

When milestone `active` with `pending` features, for each:

1. Check worker running: `ps axo command | grep '/full-loop' | grep '{task_id}'`
2. Check open PR: `gh pr list --search '{task_id}'`
3. If composite → decompose via `task-decompose-helper.sh`, dispatch leaf sub-features

Dispatch (`--agent` for non-code features; add `--poc` for POC mode):

```bash
headless-runtime-helper.sh run --dir {repo_path} --title "Mission {id} - {title}" \
  --prompt "/full-loop [--poc] Implement {task_id} -- {desc}. Mission: {goal}. Milestone: {name}." &
worker_pid=$!; kill -0 "$worker_pid" 2>/dev/null || { echo "Dispatch failed"; exit 1; }
```

Update → `dispatched`, record `worker_pid`. Respect `max_parallel_workers`.

### Phase 3: Monitor

**Full**: merged PR = complete. **POC**: commit with `Completes-feature: {id}` = complete. Update status, record cost. Stuck (2+ hours, `worker_pid` dead, no PR/commits) → `failed`, re-dispatch.

### Phase 4: Milestone Validation

When all features `completed`:

```bash
~/.aidevops/agents/scripts/milestone-validation-worker.sh "$MISSION_FILE" "$MILESTONE_NUM"
# Flags: --browser-tests --browser-url URL  |  --browser-qa --browser-url URL
```

Checks: deps, tests, build, lint, browser (if flagged). Exit: 0=pass, 1=fail, 2=config error, 3=not ready.

Budget check: if >=80% spent → pause and report.

**Pass**: milestone → `passed`, next → `active`, commit, push, back to Phase 2.
**Fail**: create targeted fix features, re-dispatch, re-validate. After 3 failures: pause, report with diagnosis.

### Phase 5: Complete

All milestones `passed`: final smoke test → `status: completed` → retrospective (outcomes, budget, lessons) → skill scan (`mission-skill-learner.sh scan {dir}`, promote high-scoring artifacts) → commit, push.

## Self-Organisation

Dirs: `mission.md` (always) · `research/` · `agents/` · `scripts/` · `assets/` — create only when you have content.

**Temporary agents**: create when 2+ features need the same specialised knowledge or a worker fails from missing context. Keep under 100 lines; frontmatter: `mode: subagent, status: draft, source: mission/{id}`. Pass path in worker prompts: `Read {mission-dir}/agents/{name}.md before starting.` After completion: move useful agents to `~/.aidevops/agents/draft/`; delete one-off agents.

**Improvement feedback**: at completion, create a signed absolute body file, then `gh issue create --repo {aidevops_slug} --title "Mission feedback: {desc}" --body-file /absolute/path/to/body.md`. Don't modify aidevops files during a mission or duplicate existing capabilities.

## Research

**Sources**: context7 MCP → local search/osgrep → `gh api` (README) → `ai-research` MCP (haiku) → `webfetch` (URLs from README only). Capture in `research/{topic}.md` (decision, options, recommendation). 1-2 pages. Skip well-known topics; time-box unfamiliar to 30-60 min; POC → popular defaults; Full → 2-3 options.

## Budget

Commands: `budget-analysis-helper.sh recommend --goal "{goal}" --json` (pre-execution), `budget-analysis-helper.sh estimate --task "{desc}" --tier {tier} --json` (per-feature), `budget-tracker-helper.sh record --provider {p} --model {m} --task {id} --input-tokens {N} --output-tokens {N}` (after worker).

| Used | Action |
|------|--------|
| < 60% | Continue |
| 60-80% | Warn; consider cheaper tier |
| 80-100% | Pause; report options |
| > 100% | Stop new dispatches |

**Tiers**: haiku=research, sonnet=implementation, opus=re-planning only.

## Modes

| | POC | Full |
|-|-----|------|
| Workflow | Commit to main | Worktree + PR |
| Workers | Sequential | Parallel (`max_parallel_workers`) |
| Tracking | State file | TODO.md + GitHub issues |
| Research | Popular defaults | Evaluate 2-3 options |
| Quality | None | Preflight, reviews, postflight |

## Error Recovery

**Worker**: Transient → re-dispatch. Knowledge gap → create mission agent, re-dispatch. Scope → decompose, update state. Fundamental → update decision log, different approach.

**Validation**: targeted fix features → re-dispatch → re-validate. After 3 failures: pause, report.

## Session Resilience

**Recovery** (every invocation): read `status` → check milestones → `ps` for workers → `gh pr list` → git log (POC) → resume without re-dispatching completed features. Never assume a previous step completed.

**Compaction**: checkpoint to `~/.aidevops/.agent-workspace/tmp/mission-{id}-checkpoint.md` (ID, state path, milestone, feature statuses, budget, next action).

## Pulse Integration

Scans `{repo_root}/todo/missions/*/mission.md` and `~/.aidevops/missions/*/mission.md` for `status: active`.

Pulse transitions: `dispatched`→`completed` (merged PR) · `dispatched`→`failed` (dead worker, no PR) · `active`→`paused` (budget) · re-dispatch (transient).

Pulse does NOT advance milestones, run validation, create fix tasks, or modify plans.

## Cross-Repo

Primary repo holds the state file; workers target secondary repos via `--dir {path}`. Use `claim-task-id.sh --repo-path {secondary}` for IDs in secondary repos.

## Related

`workflows/milestone-validation.md` · `workflows/browser-qa.md` · `scripts/commands/mission.md` · `scripts/commands/dashboard.md` · `scripts/commands/pulse.md` · `scripts/commands/full-loop.md` · `templates/mission-template.md` · `workflows/mission-skill-learning.md` · `reference/orchestration.md` · `scripts/budget-analysis-helper.sh` · `scripts/budget-tracker-helper.sh`
