Saga

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.