Saga

Saga

Contract

Inputs

• Feature request (user-provided prompt or description).
• Target repository path.
• Saga directory is confirmed with user before creation.

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. 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/<saga-name>/m<M>t<T>-<task-slug>. Create with:

   git worktree add ../saga-<saga-name>-m<M>t<T> -b saga/<saga-name>/m<M>t<T>-<task-slug> <base>
   

   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; for remote workers, obtain explicit human approval before pushing a branch, opening a draft PR, or sharing a patch); remove the worktree only after the durable handoff exists (git worktree remove <path> --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.