saga

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 09b9a1833d94 · 31 Oct 2026Report an issue or request a re-scan

• Publisherwarpdotdev GitHub organizationOwner of the repository this skill is read from
• Source folderwarpdotdev/common-skills/.agents/skills/sagaThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict09b9a1833d94A new audit runs when the source changes
• Repository statusNot archivedLast push 2 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Run an autonomous, spec-driven development "saga" for medium-to-large features using an orchestrator agent and a fleet of worker subagents. Use this skill whenever the user invokes /saga, asks to autonomously build a…

---
name: saga
description: Run an autonomous, spec-driven development "saga" for medium-to-large features using an orchestrator agent and a fleet of worker subagents. Use this skill whenever the user invokes /saga, asks to autonomously build a sizable feature end-to-end with minimal human intervention, wants a comprehensive spec broken into milestones and tasks with airtight validation criteria before parallelized implementation, or wants an orchestrator to delegate implementation to worker agents while preserving its own context window. Trigger on phrases like "run a saga", "autonomously implement this feature", "spec it out then build it with subagents", "orchestrate this big feature end-to-end", or "build this with workers and validate each step". Also use this skill when asked to continue, resume, or pick up an existing saga from its saga directory (e.g. under ~/.sagas).
---

# 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 capabilit

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/warpdotdev/common-skills
git -C common-skills checkout 09b9a1833d94

Works in

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source 09b9a1833d94

Questions about saga

• github.com/warpdotdev/common-skills/tree/main/.agents/skills/sag — the audited source at commit 09b9a1833d94 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology