saga

SKILL.md

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: