saga

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
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 crite