How the loop works

One PRD goes around one loop, from an idea to a retro. At three points it waits for a person; everywhere else, agents do the work, and write down every decision they took without you. This page shows the loop three ways: its stages, its pull requests, and its skills. Use cases then says what to type for each thing you want to do.

The loop, stage by stage

Three rules hold the loop together:

• The folder is the status. A PRD's folder sits in the inbox until it ships, and in the shipped folder after. omni prd followed by a PRD's number says where it is, and every skill looks there before it acts.
• Only a person merges into the default branch. The agents merge slices into a PRD's feature branch, never further. The phase-0, feature, retro and knowledge pull requests are yours to merge.
• Every decision an agent takes alone becomes an outbox item, which you answer or adopt. Nothing is decided behind your back, and nothing stops a build to wait for you.

Your three gates

1. The phase-0 pull request. Merging it approves the PRD and puts it in the inbox, on the default branch (why, below). It holds documents only, no code: this is the cheapest moment to change your mind.
2. The outbox. When the build is done, the feature pull request lists every question the agents met, in plain words, each with the option they built (always A) and the others. You answer them all in one comment, and /omni:yolo-fix rebuilds what you changed. The lighter decisions are adopted as each wave merges: they stand unless someone objects later.
3. The feature pull request. It is marked ready for review once no question is left open. Its description says what was built, how it was checked, the risk and how to roll it back. Merging it ships the PRD.

Between two gates, nothing asks you anything. Only two things hold a slice: a confirmed rule of your knowledge base it would break, and an action only a person can take, such as adding a secret. Both come back to you with what to do.

Why the phase-0 pull request goes into the default branch

The PRD's feature branch already holds the spec, the plan and the before/after: /omni:brainstorm wrote them there. The phase-0 pull request carries the same files, byte for byte, into the default branch, and it is that merge which puts the PRD in the inbox. It matters for four reasons:

• The inbox is read on the default branch. The folder is the status, and omni status, the status line and every teammate's checkout read the folders from the default branch. Until the phase-0 pull request is merged, they show the PRD as in review: counted apart, not yet approved. Once merged, its folder sits in .omni-loop/delivery/inbox/ for everyone: approved, ready to build.
• The merge is the approval, on record. Only a person merges into the default branch. The merge says who approved which spec and which plan, and when, before a line of code was written.
• The next PRDs can build on it. Every new PRD starts from the default branch, so from then on it can read this spec and this plan, and name this PRD among the ones it waits for (blocked-by), which the kit accepts only for a PRD already in the inbox or shipped.
• The feature pull request stays about the code. Before it ships, /omni:yolo merges the default branch into the feature branch; the two copies of the documents are identical, so they reconcile to nothing. The feature pull request then shows what changed since the approval: the code, and the PRD's folder moving from inbox/ to shipped/. You read the documents once, at phase 0, and the code once, at the end.

The pull requests you will see

Every PRD opens the same few issues and pull requests, each with its label:

The retro and knowledge pull requests open only when the delivery taught something worth keeping. Three more labels say a state rather than a kind:

• omni:in-progress: an agent is working on this pull request right now. Leave it be.
• omni:needs-fix: a slice or a check stayed red after its tries. Its status comment says what a person must do.
• omni:outbox-go: a person lets the outbox gate pass while questions are still open. The loop never adds it.

Each of the loop's pull requests carries a status comment, kept current: where it is, and the steps left to a person.

Slices and waves

The PRD's plan, plan.md, cuts it into thin slices. Each slice has a territory, the files it may touch; the slices it waits for; and a wave. The slices of a wave are built side by side, each by its own agent in its own copy of the repository, each ending in its own sub-pull request. The loop merges them into the feature branch one at a time, checks the wave as a whole, then starts the next wave.

A slice that stays red after its tries gets omni:needs-fix; it holds only the slices that wait for it, and the rest go on. To see a PRD's slices, which are merged, in flight, stuck, ready or waiting, and what can run next:

omni board 7

Which skill runs which

Every skill, what it does and when to use it: Skills.

Given a name, /omni:help explains one skill or command: /omni:help yolo.

In a terminal

A few omni commands are for you, in a terminal at the root of the repository or from Claude Code with ! before them. None of them changes anything, except omni signin and omni update.

The skills run the others themselves, such as omni ship or omni adopt: you never need to.

Next → Your first PRD