
Saga
- 8.3k installs
- 148 repo stars
- Updated July 24, 2026
- warpdotdev/common-skills
A workflow and set of patterns for orchestrating autonomous, spec-driven feature development where an orchestrator agent transforms requirements into airtight specs, delegates parallelizable tasks to worker subagents, an
About
Saga is an orchestrator skill for medium-to-large feature implementation using a three-phase workflow: spec planning, delegated worker execution, and final validation. The orchestrator transforms rough requirements into airtight specs with explicit validation criteria, then delegates parallelizable tasks to worker subagents while preserving its own context window. State lives in a saga directory (outside the repo) enabling resumption across sessions. Workers self-validate against contracts, commit durably, and report compactly. Human involvement is limited to spec approval and final manual acceptance. Success depends on tight task definitions and validation criteria written before any implementation begins.
- Three-phase workflow: Planning (spec + approval), Execution (worker delegation + validation), Acceptance (final criteria
- Spec-driven contracts with airtight validation criteria per task, preventing ambiguity and enabling parallel execution
- Saga directory persists outside repo for resumption, state recovery, and multi-session coherence
- Orchestrator stays lean by delegating code to workers, reading compact reports, and keeping state on disk
- Git worktree isolation per task with saga-traceable branch naming (saga/<name>/m<M>t<T>-<slug>)
Saga by the numbers
- 8,349 all-time installs (skills.sh)
- +1,937 installs in the week ending Jul 28, 2026 (Skillselion tracking)
- Ranked #104 of 16,659 AI & Agent Building skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Jul 28, 2026 (Skillselion catalog sync)
saga capabilities & compatibility
- Capabilities
- transform rough feature requests into airtight s · decompose features into milestones and paralleli · delegate tasks to worker subagents via run_agent · manage git worktrees and saga traceable branch n · track execution state in saga directory and prog · validate task work against explicit criteria bef · escalate blockers to user only when spec gaps or · run saga level exit criteria validation and pres · resume sagas by reading progress.md and current
- Use cases
- orchestration · api development · devops · project management · refactoring
npx skills add https://github.com/warpdotdev/common-skills --skill sagaAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 8.3k |
|---|---|
| repo stars | ★ 148 |
| Security audit | 2 / 3 scanners passed |
| Last updated | July 24, 2026 |
| Repository | warpdotdev/common-skills ↗ |
What it does
Orchestrate autonomous, spec-driven feature development across worker subagents with airtight validation contracts and milestone-based parallelism.
Who is it for?
Medium-to-large features with clear decomposition into independent tasks,Teams/workflows where workers operate in parallel and must self-validate,Projects requiring durable state across multiple agent sessions,Feature wo
Skip if: Small, single-task features better handled by direct implementation,Highly exploratory work where requirements are genuinely unknown mid-build,Work requiring tight iterative human feedback on each task,Codebases without
When should I use this skill?
User invokes /saga or says 'autonomously build this feature',Request mentions 'spec it out then build with subagents' or 'orchestrate this end-to-end',Feature is medium-to-large and can decompose into parallelizable task
What you get
A feature spec broken into independent, validatable tasks with explicit pass/fail criteria, executed in parallel by worker agents, validated automatically, and handed off to the user for final manual acceptance—all while
Files
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_agentsto 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_agentsbatch (sharedbase_prompt, per-taskprompt). 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 forSAGA.md,MILESTONE.md, task specs, andPROGRESS.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.
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 progresstasks exist? Were they merged? All saga branches follow the conventionsaga/<saga-name>/m<M>t<T>-<task-slug>(possibly behind a team/user branch prefix), so you can enumerate them withgit branch --list '*saga/<saga-name>/*'even without readingPROGRESS.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 recordedworker_run_idto 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.mdPhase 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.mdneeds the user, resolve it first viaask_user_questionwith 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.mdcurrent 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 asM<milestone>.<task>(e.g.1.2). - Keep
SAGA.mdsmall; push detail down intoMILESTONE.mdand task specs so the orchestrator reads only what the current step needs.
SAGA.md
# 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
# 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)
# 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.
# 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.mdand 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
/dashboardand 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.
Related skills
FAQ
How do I know if my feature is big enough for a saga?
Use Saga for medium-to-large features that decompose into 3+ independent tasks. For small features, direct implementation is faster. If you are unsure, ask the user or sketch the decomposition first.
What if a task fails validation?
Re-scope the task, update its spec file, and re-delegate to the same worker (it keeps context). Only escalate to the user if the blocker is a genuine spec gap or requires external decision.
Can I resume a saga after compaction?
Yes. Read references/continuing-a-saga.md, then use the saga directory and PROGRESS.md to reconstruct state. A fresh orchestrator can pick up any saga by reading its PROGRESS.md and the current spec.
Is Saga safe to install?
skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.