# Saga > Use when a user runs saga or asks to autonomously build a sizable feature. Produces a spec tree, delegates to worker subagents in isolated worktrees, validates at each milestone, and gates user acceptance before VCS commit. Not for executing a given plan — use subagent-driven. - Skill: `majiayu000/saga` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds add majiayu000/saga` - Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/saga/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: majiayu000 (https://skillmd.com/u/majiayu000) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/majiayu000/saga --- # Saga ## Contract | Field | Bound contract | |---|---| | Trigger | User runs saga or asks to autonomously build a sizable feature. | | Authority | Orchestrator writes specs to disk, delegates to workers via run_agents, and validates each task to its criteria before integration and user acceptance gate. All local writes happen in git worktrees (VCS-reversible). Milestone-level validation gates progression. User acceptance is the terminal gate before any VCS commit. | | Side effect | Creates a saga directory outside the repo and spawns workers in isolated git worktrees. | | Done | All tasks meet validation, milestones pass, user accepts. | ## Inputs - Feature request (user-provided prompt or description). - Target repository path. - Saga directory is confirmed with user before creation. - Reference materials (saga-spec-template, validation-strategies, continuing-a-saga) are embedded in this skill and read before drafting specs or resuming. ## Procedure ### Phase 1 — planning (orchestrator + user) 1. **Intake.** Restate the request as a one-paragraph problem statement and the rough shape of the feature. Identify major unknowns. Pick a saga directory name under `~/.sagas/` from a feature slug plus timestamp (e.g. `~/.sagas/dark-mode-20260609-0028/`). Confirm the path with the user before creating anything. 2. **Discover environment.** By inspecting the repo first, determine: - Program type (web app, native GUI, TUI, CLI/library, backend service). - Whether computer use is available (local, remote only, or not available). - Test runner, build, lint, and typecheck commands — confirm they run. - How the program is launched for manual or interactive verification. Record findings in `SAGA.md` under the environment section. 3. **Close ambiguity.** Iterate with the user via `ask_user_question` (with concrete options, recommended_option_index set) until behavior, scope boundaries, edge cases, data shapes, error handling, non-goals, and the acceptance bar are unambiguous. Batch up to 4 related questions per call. 4. **Write saga exit criteria.** Before decomposing, define the concrete, checkable conditions that mean the feature is complete and correct. These are the Phase 3 contract. 5. **Decompose into milestones and tasks.** Break work into milestones (ordered by dependency, independently meaningful) and tasks (scoped for one worker in one focused effort). For each task, specify its scope, owned files/surfaces, dependencies, validation criteria, and validation method. Use the templates in the Reference files section below. Write the spec tree: milestone index and exit criteria in `SAGA.md`, milestone detail in `MILESTONE.md`, task detail in each task spec. 6. **Get approval.** Present the full spec tree to the user via `ask_user_question`. Do not begin Phase 2 until approved. ### Phase 2 — implementation (worker fleet) 1. **Launch workers.** Use `run_agents` to delegate tasks. The orchestrator never implements feature code. Immediately record each worker's agent/run ID, task, branch, and worktree in `PROGRESS.md`. 2. **Isolate local workers.** Give each worker its own git worktree and branch following the convention `saga//mt-`. Create with: ``` git worktree add ../saga--mt -b saga//mt- ``` Workers must never share a checkout. 3. **Per-worker contract.** Instruct each worker to: implement only its assigned task; self-validate against the task's criteria using the prescribed method (computer use, interactive CLI, or tests) in a fix→validate loop; create a durable handoff (commit to the task branch for local workers; pushed branch, draft PR, or patch for remote workers); remove the worktree only after the durable handoff exists (`git worktree remove --force`); report branch name, commit hash, changed files, validation evidence, and pass/blocked status. 4. **Collect and act on reports.** Update `PROGRESS.md` with per-task status and evidence. Handle blocked tasks: re-delegate with retained context, adjust the task spec, or escalate to the user via `ask_user_question` with options — only if the blocker is a genuine spec gap or external decision. 5. **Integrate each milestone.** Merge the milestone's branches into an integration branch, resolve conflicts, run milestone-level validation, and remove any worktrees left behind before proceeding. 6. **Maintain state.** Update `PROGRESS.md` continuously. Re-read specs and `PROGRESS.md` from disk rather than holding state in context. ### Phase 3 — final validation 1. **Run exit criteria.** Execute all saga-level exit criteria using the strongest available method. Summarize evidence against each criterion. 2. **Present completion report.** What was built, how each exit criterion was validated, exact steps for manual verification. 3. **Loop user for acceptance.** Present via `ask_user_question` (accept or report specific issues). If issues are reported, capture them as new tasks, run a focused Phase 2 mini-loop, and re-present. Repeat until the user accepts. Only then is the saga complete. ### Continuing a saga When asked to continue, resume, or pick up a saga: 1. **Locate.** Find the saga directory under `~/.sagas/`. If ambiguous, ask the user via `ask_user_question`. 2. **Rebuild orientation.** Read `SAGA.md` (problem, environment, exit criteria, phase, milestone index) and `PROGRESS.md` (phase, current milestone, task statuses, worker run IDs, open questions, recent log). Open only the spec for the milestone about to be acted on. 3. **Reconcile.** Verify git state for done/in-progress tasks: check whether branches and worktrees exist, whether they have been merged. Spot-check validation evidence for done tasks. Update `PROGRESS.md` to match reality. 4. **Resume.** From the reconciled state, resume Phase 2 at the current milestone or Phase 3 if all milestones are integrated. Follow the Phase 2/3 procedure above. 5. **Keep the contract.** Do not silently re-scope. If the spec is wrong, update the relevant spec file and note it in `PROGRESS.md` under Decisions & Deviations; escalate to the user if agreed behavior or exit criteria change. ## Failure and recovery - Spec gap: ambiguity unresolved in Phase 1 blocks delegation. Escalate to user via `ask_user_question` with options; do not proceed until resolved. - Worker blocked: collect the report, update `PROGRESS.md`, re-delegate with retained context or adjust the task spec; escalate to user if the blocker is not resolvable from the spec. - Milestone validation failure: revert to pre-integration state (branches and commits are preserved in git history); re-delegate affected tasks. - Phase 3 rejection: capture reported issues as new tasks; run a focused Phase 2 mini-loop; re-present. - Unachievable validation: if a criterion cannot be checked with available tools, update the spec and note the finding; escalate to the user. - Partial-result rule: never remove a worktree while validated or useful partial work is still inside it. - Non-rollback rule: once a durable handoff exists (commit pushed, draft PR opened, patch returned), the work is preserved regardless of subsequent failures. - Non-converged result: if a task cannot be completed despite re-delegation and spec adjustment, record the blocker in `PROGRESS.md` and escalate to the user. Do not silently declare done. ## Output A completed feature meeting all saga exit criteria. A completion report listing what was built, how each criterion was validated, and exact steps for manual verification. Terminal state is user acceptance.