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:
Show more
Installs
586
Repository
warpdotdev/common-skills
GitHub Stars
110
First Seen
2 days ago
Security Audits
Gen Agent Trust Hub
Warn
Socket
Pass
Snyk
Pass