saga

# Continuing a saga

Use this when asked to continue, resume, or pick up a saga — typically a fresh orchestrator with no memory of the earlier session. Everything you need is on disk in the saga directory; the specs are the contract and `PROGRESS.md` is the current state. Your job is to reconstruct where the saga stands, reconcile it against reality, and resume the Phase 2/3 loop from `SKILL.md` — without re-reading the whole tree into context.

## 1. Locate the saga directory

Find the saga under `~/.sagas/`. If the user named it or gave a path, use that. Otherwise `ls ~/.sagas/` and, if ambiguous, ask the user which one (via `ask_user_question` listing the candidates). The directory name is the saga's stable identity.

## 2. Rebuild orientation cheaply

Read, in this order, and stop once you know the next action:

1. `SAGA.md` — problem statement, environment/capabilities, saga exit criteria, milestone index, and `Status`.
2. `PROGRESS.md` — `Phase`, `Current milestone`, per-task status, worker run IDs for any in-progress tasks, integration notes, open questions, and the recent log.

Do **not** bulk-read every `MILESTONE.md` and task spec. Open only the spec(s) for the milestone you're about to act on. This is the same context discipline the orchestrator uses normally.

## 3. Reconcile the log against reality

`PROGRESS.md` can be stale if the previous session was interrupted. Before trusting it, verify the actual state for anything not clearly settled:

- Check git: do the branches/worktrees referenced for `done`/`in progress` tasks exist? Were they merged? All saga branches follow the convention `saga/<saga-name>/m<M>t<T>-<task-slug>` (possibly behind a team/user branch prefix), so you can enumerate them with `git branch --list '*saga/<saga-name>/*'` even without reading `PROGRESS.md`.
- For tasks marked `done`, spot-check the evidence still holds — re-run the task's validation if there's any doubt that it landed. A task is only really done when its criteria pass against the current integrated code.
- For tasks marked `in progress`, use the recorded `worker_run_id` to decide whether the prior worker is still reachable. Do not rely on a display name alone; if there is no addressable run ID, or the agent is no longer reachable, treat the task as not started and re-delegate from its spec.

Update `PROGRESS.md` to match reality before proceeding, noting the reconciliation in the log.

## 4. Determine the next action and resume

From the reconciled state:

- If milestones remain, resume the **Phase 2 orchestration loop** at the current milestone: launch the next batch of pending/blocked tasks (workers in isolated worktrees), collect reports, integrate, run milestone-level validation, and advance. Follow `SKILL.md` Phase 2.
- If all milestones are integrated and validated, move to **Phase 3 final validation**: check the saga exit criteria and loop the user in for manual acceptance.
- If a blocker or open question recorded in `PROGRESS.md` needs the user, resolve it first via `ask_user_question` with options.

## 5. Keep the contract intact

You are bound by the same specs and validation criteria as the original orchestrator. Don't silently re-scope. If resuming reveals the spec is wrong or a task's criteria are unachievable, update the relevant spec file (and note it under "Decisions & deviations" in `PROGRESS.md`), and escalate to the user if it changes agreed behavior or the saga exit criteria.

## Quick checklist

- [ ] Found and confirmed the saga directory.
- [ ] Read `SAGA.md` + `PROGRESS.md`; know phase, current milestone, and next action.
- [ ] Reconciled branches/worktrees/evidence with git; fixed `PROGRESS.md`.
- [ ] Resumed the correct phase loop from `SKILL.md`.
- [ ] Kept specs and `PROGRESS.md` current as work proceeds.

# Saga directory & spec templates

A saga is a *tree* of spec files plus a progress log, stored in its own directory outside the repo so it survives across orchestrator sessions and can be resumed. Each level carries its own validation criteria. Vagueness here becomes defects later — prefer concrete, checkable language over aspirational prose.

## Directory layout

```
~/.sagas/<saga-name>/
├── SAGA.md                      # overview, environment, saga-level exit criteria, milestone index
├── PROGRESS.md                  # live, continuously-updated execution log and current state
└── milestones/
    ├── 01-<slug>/
    │   ├── MILESTONE.md          # milestone spec + milestone-level validation criteria
    │   └── tasks/
    │       ├── 01-<slug>.md      # task spec + task-level validation criteria
    │       └── 02-<slug>.md
    └── 02-<slug>/
        ├── MILESTONE.md
        └── tasks/ ...
```

- `<saga-name>` must be **unique and stable** — a feature slug plus a timestamp, e.g. `dark-mode-20260609-0028`. It is how a fresh orchestrator finds and resumes the saga.
- Number milestone/task directories and files (`01-`, `02-`, …) so order is obvious and dependency references are stable. Refer to tasks as `M<milestone>.<task>` (e.g. `1.2`).
- Keep `SAGA.md` small; push detail down into `MILESTONE.md` and task specs so the orchestrator reads only what the current step needs.

## `SAGA.md`

```markdown
# Saga: <feature name>
- Saga directory: ~/.sagas/<saga-name>
- Repo: <path> @ <base branch>
- Status: planning | in-progress | final-validation | complete

## Problem statement
<1–2 paragraphs: what we are building and why. The user-facing outcome.>

## Scope & non-goals
- In scope: <bullets>
- Out of scope / non-goals: <bullets — explicit, so workers don't gold-plate>
- Decisions delegated to agent discretion: <only those the user explicitly allowed; otherwise "none">

## Environment & capabilities
- Program type: <web app | native GUI | TUI | CLI/library | backend service | ...>
- Run/launch command: <how to start it for manual/interactive verification>
- Test command(s): <unit / integration runner commands, confirmed working>
- Build / lint / typecheck command(s): <commands>
- Computer use available: <yes (local) | yes (remote only) | no>
- Default validation method for this saga: <derived from the above; see validation-strategies.md>

## Saga exit criteria
<Concrete, checkable conditions that mean the entire feature is done and correct.
Each is verifiable, not a feeling. Validated in Phase 3.>
1. <criterion>
2. <criterion>

## Milestone index
<Ordered list with one line each + dependency notes. The detail lives in each MILESTONE.md.>
1. 01-<slug> — <one line>; depends on: none
2. 02-<slug> — <one line>; depends on: 01-<slug>
```

## `MILESTONE.md`

```markdown
# Milestone <n>: <name>
- Saga: <saga-name>
- Depends on: <milestone ids, or "none">

## Goal
<What this milestone delivers and why it sits here in the order.>

## Milestone validation criteria
<Checkable conditions that mean the whole milestone is done and integrates correctly.
Run these after integrating the milestone's tasks.>
1. <criterion>
2. <criterion>

## Tasks
<Index of this milestone's task specs + intra-milestone dependencies.>
- 01-<slug> — <one line>; depends on: none
- 02-<slug> — <one line>; depends on: 01-<slug>
```

## Task spec (`tasks/NN-<slug>.md`)

```markdown
# Task <m>.<n>: <name>
- Milestone: <m>
- Depends on: <task ids, or "none">

## Scope
<What this single worker does; small enough for one focused effort.>

## Owned files/surfaces
<Paths/modules this task may touch. Two parallel tasks must not own the same files.>

## Interfaces produced/consumed
<Exact API, schema, or function signatures other tasks rely on, if any.>

## Validation method
<computer use | interactive CLI | unit tests | integration tests | combination>

## Validation criteria (the contract)
<Explicit, checkable. Satisfying all of these should leave little-to-no possibility
the task was done incorrectly. Cover unhappy paths and "must not change" cases.>
1. <criterion>
2. <criterion>

## Evidence required
<What the worker must return to prove completion: named test output, screenshots,
CLI transcript, sample command output, etc.>
```

## `PROGRESS.md`

The source of truth for execution state. Keep it current as work happens — a fresh orchestrator resumes entirely from this file plus the specs.

```markdown
# Saga progress: <feature name>
- Saga directory: ~/.sagas/<saga-name>
- Repo: <path> @ <base branch>
- Phase: 2 (implementation) | 3 (final validation)
- Current milestone: <n>

## Task status
<One line per task: status, branch, evidence pointer.
Branch naming convention: saga/<saga-name>/m<M>t<T>-<task-slug> (prepend a team/user branch prefix if your repo requires one)>
- 1.1 <name>: done — branch saga/<saga-name>/m1t1-<slug>, commit <hash>, evidence: <pointer / test names / screenshot path>
- 1.2 <name>: in progress — worker <name>, worker_run_id <agent/run id>, branch saga/<saga-name>/m1t2-<slug>, worktree ../saga-<saga-name>-m1t2
- 1.3 <name>: blocked — <reason / decision needed>
- 2.1 <name>: pending

## Integration notes
<Per milestone: merge order, conflicts resolved, milestone-level validation results.>

## Decisions & deviations
<Any spec changes made mid-flight and why; keep the specs themselves updated too.>

## Open questions for user
<Only if a blocker truly requires escalation.>

## Log
<Reverse-chronological short entries: timestamp — what happened.>
- 2026-06-09T00:40Z — Milestone 1 integrated; all milestone criteria pass.
```

## Rules

- **Saga exit criteria / milestone criteria / task criteria** form nested contracts. Each must be checkable by a concrete method; if you can't say how you'd verify one, it isn't a criterion yet.
- **Milestones** are ordered by dependency and independently meaningful. Tasks *within* a milestone should be as independent (parallelizable) as the feature allows.
- **Tasks** must be sized for a single worker in one focused effort. If a task needs multiple distinct deliverables or spans many unrelated files, split it.
- **Owned files/surfaces** prevent collisions between parallel workers.
- Keep `PROGRESS.md` and the specs in sync with reality; they are the only state a resuming orchestrator has.

# Validation strategies

Validation is what makes a saga autonomous: if each task's criteria are airtight and checked by an appropriate method, workers can self-verify and the orchestrator can trust their reports. This file covers (1) discovering what's feasible, (2) choosing a method, and (3) writing criteria tight enough to be a contract.

## 1. Discover what validation is feasible

Before defining any criteria (Phase 1), establish — by inspecting the repo/environment first, asking the user only for what you can't discover:

- The program type (web app, native GUI, TUI, CLI/library, backend service).
- Whether **computer use** (browser/GUI automation, visual inspection) is available to you or to remote workers.
- The **test toolchain**: test runner, integration harness, build, lint, typecheck — and confirm the commands actually run.
- How the program is launched for manual/interactive verification.

Record these in `SAGA.md`. Criteria you can't actually check are worthless, so feasibility constrains the criteria you write.

## 2. Choose a validation method

Pick the strongest method the task and environment support. Tests are the baseline regardless — prefer to add automated tests for everything that can be tested, even when also using computer use or CLI verification, because tests are repeatable and guard against regressions.

Priority order:

1. **Computer use — for GUI and web UI behavior.** When the task's correctness is visual or interaction-driven (rendering, layout, flows, click/keyboard behavior), and computer use is available, validate by driving the running app and inspecting the result (screenshots, asserted on-screen state). If computer use is only available remotely, route that validation through a remote worker with computer use enabled and have it return screenshots/evidence as a durable artifact.
2. **Interactive CLI subagent — for TUIs and interactive terminal programs.** When the program is a TUI or otherwise interactive in the terminal, validate by driving it in an interactive session (e.g. a subagent operating a live PTY): send input, observe rendered output, assert expected states. This catches behavior that non-interactive runs miss.
3. **Unit & integration tests — otherwise, or when the above are unavailable/not applicable.** For libraries, CLIs, backend services, and pure logic, write and run unit and integration tests that assert the task's criteria. This is also the fallback when computer use / interactivity isn't available even for a GUI/TUI task.

A task may combine methods (e.g. integration tests *and* a computer-use check of the resulting UI). State the method(s) explicitly in the task.

## 3. Write airtight validation criteria

The bar: when the criteria are satisfied, there should be little-to-no possibility the task was completed incorrectly. To get there:

- **Make each criterion checkable, not aspirational.** "Login works" is not a criterion. "Submitting valid credentials redirects to `/dashboard` and shows the user's name; invalid credentials show an inline error and do not navigate" is.
- **Name the observable signal.** Tie each criterion to a concrete signal: a passing test name, an HTTP status + body, an on-screen element/text, a CLI exit code + output, a file's contents.
- **Cover the unhappy paths.** Specify error handling, empty/edge inputs, and boundaries — not just the happy path. Most "done but wrong" outcomes hide here.
- **Pin down interfaces.** If the task produces an API, schema, or function signature other tasks depend on, state the exact shape so parallel workers integrate cleanly.
- **State what must NOT change.** Where regressions are a risk, include "existing X still passes / behaves as before" as an explicit criterion.
- **Require evidence.** Each task must specify what the worker returns to prove completion: test output, screenshots, an interactive transcript, sample command output. No evidence, no pass.

If you cannot express a task's criteria this concretely, the task is under-specified: split it, add detail, or resolve the ambiguity with the user (with options via `ask_user_question`).

## 4. What workers do with criteria (self-validation loop)

Each worker should treat its criteria as a checklist to drive a fix→validate loop:

1. Implement the task.
2. Run the prescribed validation method and check every criterion.
3. If any fail, fix and re-validate. Repeat until all pass or genuinely blocked.
4. Return the evidence and a clear pass/blocked status.

The orchestrator trusts a "pass" only when the returned evidence actually demonstrates the criteria. At milestone boundaries, re-run validation across the integrated result, since independently-passing tasks can still conflict once merged.

---
name: saga
description: Run an autonomous, spec-driven development "saga" for medium-to-large features using an orchestrator agent and a fleet of worker subagents. Use this skill whenever the user invokes /saga, asks to autonomously build a sizable feature end-to-end with minimal human intervention, wants a comprehensive spec broken into milestones and tasks with airtight validation criteria before parallelized implementation, or wants an orchestrator to delegate implementation to worker agents while preserving its own context window. Trigger on phrases like "run a saga", "autonomously implement this feature", "spec it out then build it with subagents", "orchestrate this big feature end-to-end", or "build this with workers and validate each step". Also use this skill when asked to continue, resume, or pick up an existing saga from its saga directory (e.g. under ~/.sagas).
---

# Saga

Saga is an autonomous, spec-driven development workflow for **medium-to-large features** that should be implemented mostly without human intervention, except at a few discrete touch points. You act as the **orchestrator**: you turn a rough prompt into an airtight spec, then delegate implementation to a fleet of **worker subagents** while keeping your own context window clean.

The whole method rests on one bet: if the spec defines every task with validation criteria tight enough to form a *contract*, then workers can execute in parallel and self-verify, and the saga succeeds with almost no human babysitting. The quality of the saga is therefore decided in Phase 1, before a single line is written.

## Core principles

- **Airtight contracts over good intentions.** A task is only ready to delegate when its validation criteria are so explicit that meeting them leaves little-to-no possibility the task was done wrong. Ambiguity is the enemy; resolve it during planning, not during implementation.
- **No whitespace.** During planning, make every requirement explicit. Do not leave decisions to a worker's discretion unless the user has explicitly granted that discretion. Workers should never have to guess what "done" means.
- **Protect the orchestrator's context.** You are the long-lived coordinator. Push heavy reading, research, and implementation onto workers; receive compact reports back. Keep state on disk (in the saga directory's spec tree and `PROGRESS.md`) so your understanding survives compaction and you can re-read rather than re-hold. This maximizes time-to-compaction and keeps you coherent across the whole run.
- **Validation is first-class.** Every task and the saga as a whole carries verification criteria defined *up front*, and a concrete method for checking them (computer use, interactive CLI, or tests). See `references/validation-strategies.md`.
- **A few human touch points, not zero.** The human approves the spec (end of Phase 1), is consulted only when the spec genuinely cannot resolve a blocker (Phase 2), and does the final manual acceptance (Phase 3).

## The saga directory

Each saga lives in its own directory **outside the repo**, under `~/.sagas/`, so it survives across orchestrator sessions and can be resumed by a fresh agent. Name it uniquely from a slug of the feature plus a timestamp, e.g. `~/.sagas/dark-mode-20260609-0028/`. Confirm the exact path with the user and record it — it is the saga's stable identity.

The directory holds a *tree* of spec files plus a progress log. Each level carries its own validation criteria, so detail scales with the size of the saga instead of bloating one file:

```
~/.sagas/<saga-name>/
├── SAGA.md                      # overview, environment, saga-level exit criteria, milestone index
├── PROGRESS.md                  # live, continuously-updated execution log and current state
└── milestones/
    ├── 01-<slug>/
    │   ├── MILESTONE.md          # milestone spec + milestone-level validation criteria
    │   └── tasks/
    │       ├── 01-<slug>.md      # task spec + task-level validation criteria
    │       └── 02-<slug>.md
    └── 02-<slug>/
        ├── MILESTONE.md
        └── tasks/ ...
```

`SAGA.md` stays small — it indexes the milestones and holds only saga-wide content. Milestone and task specs hold the detail. This is what keeps your context clean: read only the spec for the milestone or task you are currently coordinating, and rely on `PROGRESS.md` for state rather than re-deriving it.

Use the templates and field definitions in `references/saga-spec-template.md` verbatim. Read it before drafting specs.

---

## Phase 1 — Planning & spec generation (orchestrator + user)

Goal: produce a comprehensive, unambiguous saga spec tree. This phase is **fully collaborative** with the user. It ends only when the user approves the spec.

When asking the user anything in this phase, **always use the `ask_user_question` tool and provide concrete options** (single- or multi-select) rather than open-ended questions. Set a `recommended_option_index` when there is a sensible default. Open-ended prose questions slow the user down and invite vague answers; options force crisp decisions.

### 1. Intake and frame

Restate the request as a one-paragraph problem statement and the rough shape of the feature. Identify the major unknowns you will need to close. Pick a unique saga directory path under `~/.sagas/` (feature slug + timestamp), confirm it with the user, and create it; everything below is written there.

### 2. Establish machine & runtime capabilities

You cannot define realistic validation criteria without knowing what can actually be tested on this machine and against this program. Determine, by inspecting the repo and environment first and asking the user only for what you cannot discover:

- **What kind of program is this?** Web app, native GUI, TUI, CLI/library, backend service, etc. This dictates the validation method (see `references/validation-strategies.md`).
- **Is computer use available?** Check whether a computer-use / browser-automation capability is available to you or to cloud workers. If GUI/web validation is needed but computer use is only available remotely, plan to route that validation through remote workers.
- **What is the test/build toolchain?** Discover the test runner, build, lint, and typecheck commands (e.g. from README, CI config, package manifests, project rules). Confirm they run.
- **How is the program run/launched** for manual or interactive verification?

Record these findings in `SAGA.md` under the environment section — workers and any future orchestrator rely on them.

### 3. Close every gap of ambiguity

Iterate with the user, via `ask_user_question` with options, until there is no whitespace left in the requirements: behavior, scope boundaries, edge cases, data shapes, error handling, non-goals, and acceptance bar. Batch related questions (max 4 per call). Stop only when the remaining decisions are either resolved or explicitly delegated to your discretion by the user.

### 4. Define the saga exit criteria

Before decomposing, write the saga-level **exit criteria**: the concrete, checkable conditions that mean the entire feature is done and correct. These are the contract for the whole saga and the basis for Phase 3.

### 5. Decompose into milestones and tasks

Break the work into **milestones** (coherent, independently meaningful chunks, ordered by dependency) and within each, **tasks** scoped so a *single worker agent* can complete one in one focused effort. For each task specify: scope, owned files/surfaces, dependencies on other tasks, and **validation criteria + validation method**. Shape the topology pragmatically around the feature's real dependencies — maximize tasks that can run in parallel within a milestone, and sequence milestones where later work depends on earlier work.

Write this out as the spec tree in the saga directory: the milestone index and saga exit criteria in `SAGA.md`, each milestone's detail and milestone-level validation criteria in its `MILESTONE.md`, and each task's detail and validation criteria in its own task spec file. Each task's validation criteria must be airtight per `references/validation-strategies.md`. If you cannot write airtight criteria for a task, the task is under-specified — split it or go back to the user.

### 6. Get approval

Present the saga spec — walk the user through `SAGA.md` and the milestone/task specs — and ask them to approve or request changes (via `ask_user_question`). **Do not begin Phase 2 until the user approves.** This is the primary human checkpoint.

---

## Phase 2 — Implementation & validation (worker fleet, looped)

Goal: execute every task to its validation criteria, milestone by milestone, delegating to workers and keeping yourself lean. The user is involved here only if a blocker cannot be resolved from the spec.

### Orchestration mechanics

- **Delegate, don't implement.** Use `run_agents` to launch workers. You coordinate; you do not write feature code yourself. This is what protects your context.
- **Batch by parallelism.** Within a milestone, launch all independent tasks as one `run_agents` batch (shared `base_prompt`, per-task `prompt`). Run dependent milestones in sequence. Use a Mermaid/DAG mental model from the task dependencies.
- **Isolate local workers.** When workers modify the same repo, give each its own git worktree and branch. Follow the **saga branch naming convention** so every branch is traceable back to its saga directory, milestone, and task without consulting `PROGRESS.md`:
  ```
  saga/<saga-name>/m<M>t<T>-<task-slug>
  ```
  Example: `saga/dark-mode-20260609-0028/m1t2-setup-tokens`. Create with:
  ```
  git worktree add ../saga-<saga-name>-m<M>t<T> -b saga/<saga-name>/m<M>t<T>-<task-slug> <base>
  ```
  If your team or repo has a branch-prefix convention (e.g. a per-user prefix like `<username>/`, or a required prefix enforced by CI), prepend it consistently while keeping the `saga/<saga-name>/...` structure intact so branches stay filterable. Workers must never share a checkout or work on the user's current branch. Decide the merge strategy up front (typically: integrate each milestone's branches at the milestone boundary). Worker changes must be committed, pushed, or otherwise durably handed off before any worktree is removed.
  
  To list all branches for a saga: `git branch --list '*saga/<saga-name>/*'`
- **Remote workers for computer use.** If a task's validation needs computer use and it is only available remotely, launch that worker (or its validation step) remotely with computer use enabled, and have it return a durable artifact (pushed branch, draft PR, or a compact patch/diff) rather than leaving work only in the remote environment.

### The per-task contract given to each worker

Put shared rules in `base_prompt` (repo path, base branch, toolchain commands, coding standards, the validation method, how to report back) and the specific task in each per-worker `prompt`. Instruct every worker to:

1. Implement only its assigned task and owned files.
2. **Self-validate in a loop** against the task's validation criteria using the prescribed method (computer use / interactive CLI subagent / unit + integration tests). Iterate fix→validate until all criteria pass or it is genuinely blocked.
3. **Create a durable handoff before cleanup.** For local git worktree tasks, commit the validated changes to the task branch and make sure the branch is visible to the orchestrator. For remote tasks, push the branch, open a draft PR, or return a complete patch/diff; do not leave the only copy of the work in a remote checkout. If blocked with partial useful work, preserve it as a WIP commit or patch before reporting; if no partial work is worth preserving, say so explicitly.
4. **Remove the worktree only after the durable handoff exists**: `git worktree remove <worktree-path> --force`. The branch or patch persists; the worktree does not. Stale worktrees are unacceptable, but cleanup must never be allowed to discard the only copy of validated or useful partial work.
5. Report back compactly: branch name, commit hash or patch/pushed-branch artifact, changed files, the validation evidence (test output, screenshots, CLI transcript), and a clear pass/blocked status. Keep findings terse — you are protecting context.

See `references/validation-strategies.md` for choosing and applying the validation method and for what counts as sufficient evidence.

### The orchestration loop

For each milestone, in order:

1. Launch the milestone's parallelizable tasks as worker(s). Immediately record each worker's addressable agent/run ID in `PROGRESS.md` alongside its task, branch, and worktree. Display names are not sufficient for resume; a fresh orchestrator needs the run ID to message an in-progress worker.
2. Collect reports as they arrive (read the worker's message content; don't rely on lifecycle success alone). Update `PROGRESS.md` in the saga directory with per-task status and evidence pointers.
3. **Handle blocked tasks.** If a worker can't meet its criteria, decide: re-scope and re-delegate to the same worker (it retains context), adjust the task in its task spec file, or — only if the blocker is a genuine spec gap or external decision — escalate to the user with options. Prefer not to escalate; the spec should usually have the answer.
4. **Integrate and run milestone-level validation.** Merge the milestone's branches into the integration branch, resolve conflicts, and verify the milestone holds together (run the relevant tests/validation across the integrated result). If any worker left a worktree behind despite instructions, remove it now (`git worktree remove <path> --force`) before proceeding.
5. Move to the next milestone.

Re-read the relevant spec files and `PROGRESS.md` from disk whenever you need state instead of holding it in context. Keep `PROGRESS.md` updated as you go — it is the source of truth a fresh orchestrator uses to resume the saga, so a stale log means a lost saga. If you sense your context filling, write a concise progress checkpoint to `PROGRESS.md` first.

---

## Phase 3 — Final validation (orchestrator + user)

Goal: confirm the saga's exit criteria are met, then hand off to the user for manual acceptance.

1. Run the full saga-level exit criteria using the strongest available method (computer use for GUI/web, interactive CLI for TUIs, the full test/integration suite otherwise). Summarize the evidence against each exit criterion.
2. Present the user a concise completion report: what was built, how each exit criterion was validated, and exact steps for them to manually verify (how to run/launch, what to look for).
3. **Loop in the user for manual acceptance** via `ask_user_question`: accept, or report specific issues. If they report issues, capture them as new tasks, run a focused Phase 2 mini-loop (delegate → self-validate → integrate), and re-present. Repeat until the user accepts.

Only consider the saga complete when the user confirms acceptance.

---

## Resuming a saga

Because the saga directory and `PROGRESS.md` live outside the repo and capture full state, a saga can be picked up by a fresh orchestrator at any time (after compaction, a new session, or a handoff). When asked to continue, resume, or pick up a saga, **read `references/continuing-a-saga.md` and follow it.**

## Practical notes

- Never commit or open PRs unless the user asks; follow the repo's version-control rules when you do.
- Keep the spec tree current — if implementation forces a change to scope or criteria, update the relevant spec file rather than letting it drift.
- For very large sagas (≈10+ concurrent workers), prefer remote execution so you don't exhaust the user's machine.
- Don't expose internal worker agent IDs in user-facing summaries unless asked.

## Reference files

- `references/saga-spec-template.md` — the saga directory layout and the exact templates for `SAGA.md`, `MILESTONE.md`, task specs, and `PROGRESS.md`. Read before drafting specs.
- `references/validation-strategies.md` — how to choose a validation method, write airtight criteria, and gather sufficient evidence. Read during Phase 1 (criteria) and Phase 2 (execution).
- `references/continuing-a-saga.md` — how a fresh orchestrator picks up an existing saga directory and resumes safely. Read when asked to continue/resume a saga.