DocsOpen the app →

Switch to game mode?

The arcade opens on its menu.

Switch

How the loop works

The loop in three drawings — its six stages and who acts at each, the pull requests you will see, and which skill runs which.

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

IDEAtalked throughwith the agentno file yetPRDspec, plan andbefore/afterphase-0 PRINBOXapproved, andready to builddelivery/inbox/OUTBOXbeing built; theagents' questionsfeature PR, draftSHIPPEDmerged into thedefault branchdelivery/shipped/RETROhow it went, andwhat it taughtretro + knowledgeYOU + AGENT/omni:brainstormwrites the PRDYOUreview, mergethe phase-0 PRAGENTS/omni:yolo <n>you start it; they planand build every sliceYOUanswer the outbox/omni:yolo-fix <n>merge feature PROMNI APPopens the retro+ knowledge PRsKNOWLEDGEwhat it taughtshapes the next ideaWHO ACTSyou: a person decidesagents: the agent buildsOmni App: on GitHubOnly a person merges into the default branch.
StageWhat it meansWhere you see itWhat moves it on
ideatalked through with your coding agent, nothing written yetyour coding agent's session/omni:brainstorm writes the PRD; a vast idea goes through /omni:think-big first
PRDa spec, a plan and a before/after page, waiting for a person's approvalthe PRD issue, the phase-0 pull request, or the PRD's page when phase 0 is approved on the serveryou merge the phase-0 pull request, or approve on the PRD's page
inboxapproved, ready to build.omni-loop/delivery/inbox//omni:yolo builds it
outboxbeing built; what the agents decided alone waits for youthe feature pull request, a draftyou answer the questions, then merge the feature pull request
shippedthe change is on the default branch.omni-loop/delivery/shipped/the Omni App opens the retro and knowledge pull requests
retrohow the delivery went, and what it taughtthe retro and knowledge pull requestsyou merge them, and the next idea starts from what they keep

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.

How long each step took

A PRD's page has a Timeline tab, after Plan. It lists the PRD's own milestones (idea, plan, approved), then one lane per repository the PRD lands in (one lane for most PRDs), each with its milestones and their dates, linked to their pull requests. Between two milestones it shows the step's name, how long it took and who it waited on, and it marks the longest step. A step still going is counted up to now; a milestone not reached yet reads not yet, and a step whose start was never recorded reads not recorded, never zero. The line under the stage words gives the total from idea to merged, or the time running so far, and the longest wait.

The Engineering board has a Time per step panel. For each step it gives the median over the PRDs done in the board's period, how many PRDs it covers, and the slowest step.

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. In a repository whose phase 0 is approved on the server, there is no phase-0 pull request: you approve the PRD on its page instead (Approvals).
  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.

Approvals

A PRD is approved once, before any code is written: through its phase-0 pull request, or with Approve on its page. A PRD may also ask for a Tech Approval first, from one named member who reviews the coding side with /omni:tech-review. Approvals has both: who approves, what voids an approval, and the omni/approved check.

The pull requests you will see

phase-0 PRdefault branchfeature branchfeat/<topic>sub-PRsone per slicespec, plan, before/afterYOU MERGEthe phase-0 PR:the PRD is in the inboxplan.md, draftfeature PRs1s2s3WAVE 1WAVE 2/omni:yolo: agents build and merge each sub-PRshipPR readyYOU MERGEthe feature PROMNI APPretro, knowledge

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

LabelWhat it isOpened byMerged by
omni:prdthe PRD's issue: its number is the PRD's number/omni:brainstormclosed when the PRD ships
omni:phase-0the PRD's folder alone: spec, plan, before/after; none when phase 0 is approved on the server/omni:brainstormyou, into the default branch
omni:featurethe whole change: a draft until no question is open/omni:plan, run by /omni:brainstormyou, into the default branch
omni:subone slice, or one rework/omni:wave, /omni:do-workthe loop, into the feature branch
omni:retrohow the delivery wentthe Omni App, once shippedyou
omni:knowledgethe decisions you settled, written back into the knowledge basethe Omni App, once shippedyou

The retro and knowledge pull requests open only when the delivery taught something worth keeping. When a retro keeps a lesson, the Omni App queues /omni:retro-apply --retro <retro PR> for a runner (the same line is in the retro pull request's body, to run in your terminal): each lesson becomes a rule in a playbook form, or stays here with its reason, and the retro pull request quotes each one for you to approve before you merge it. When a shipped PRD breaks main within seven days of its merge (a red job on its merge commit, a revert of one of its pull requests, or a regression traced to it), the Omni App queues /omni:rewind <n> for a runner, once: it walks back from the break to the spec and proposes, on the PRD's Main tab, where the break started and what would have stopped it, for you to approve or reject. When you approve a finding that started in knowledge nobody wrote down, about a playbook rule or a product fact, the page queues /omni:rewind-apply <n> <finding> for a runner, sent by you: it proposes the rule in one docs-only pull request in your repository (a playbook line, or a register entry marked proposed, never a law), or names the rule that already says it, or asks you one question. The finding's card shows which. It writes only in your repository's own knowledge, never the kit, and never merges. 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.
  • omni:approved: on a PRD's issue, once a member approved it on its page (phase 0 on the server). For display: the loop reads the approval from the page, never from the label.

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

Laws and their tests

A few rules cost the most when they break. Your repository can lock them as laws, each proven by a test, and only the people who own a law can approve a change to it. Every change to a rule, locked or not, needs a person's answer on the pull request. Knowledge › Laws and their tests explains it all: locking a law, owners and delegates, /omni:enforce and the sweep.

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.

When a reviewer, a bot or a person, has left comments on a sub-pull request, the wave handles them before it merges it, as /omni:pr-care handles the feature pull request's: each one is fixed, pushed back with its reason, or left open for you. A comment left open for you holds that slice alone, unmerged, and the wave says which; the rest of the wave goes on. Only the comments posted when the wave reaches the slice count: it waits for no review still to come.

A small plan builds without sub-pull-requests

A sub-pull request costs more than the work of its slice: a worktree of its own and an install, the preflight before the pull request opens, its CI run, the claim, the status comment and the merge. For a plan of one or two slices the feature pull request already is the record of the whole feature, so a repository can ask for those to be built on the feature branch directly:

FILE · .omni-loop/config.yml
wave:
  inlineBelow: 3   # a plan with fewer slices than this builds inline; 0 (the default) never does

Below the threshold, /omni:wave builds each slice with /omni:do-work --inline, one after the other, committed on the feature branch itself: no claim, no sub-pull request, no merge by an agent. Everything else stays: the territory, the outbox questions and their accounts, the check of the wave, and the feature pull request as the one pull request into the default branch, which ticks each slice as built inline with its commit. A slice that stays red, or stops, pushes nothing to the feature branch: its work waits on its slice branch, with no pull request, and the wave says so. omni board reads a slice as merged once a commit on the feature branch carries its Omni-Slice: <id> trailer line, and says inline: true in its --json. A PRD that already has a sub-pull request finishes with them; a PRD of several landings counts the slices of the landing it builds; a PRD that spans repositories never builds inline.

When /loop /omni:drive drives several PRDs, their waves also run side by side, up to three at once and never two that touch the same files (Drive the loop).

In a repository that turned design craft on, a slice that changes a screen is also looked at before its sub-pull request is marked ready: /omni:do-work runs /omni:pixel-perfect review on its own, fixes what it can in one batch, and writes a Design review section on the sub-pull request, one ✓, ✗ or — line per step. It never blocks: what it leaves becomes an outbox question like any other.

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:

TERMINALCODING AGENT
omni board 7

Open points

A fix or a review often sees more than it fixes. Each point it leaves open goes in .omni-loop/delivery/follow-ups/, one file per point, named by its date and its first words. A bug fix writes its points on the fix branch, and a review reply that postpones a comment writes its point on the feature branch, so each one merges with the change that raised it.

  • omni follow-up list prints the open points, oldest first. omni status shows how many there are and the oldest, under the bar of each PRD line.
  • Nothing opens a GitHub issue or sends a notification for a point. The workspace's members read the list and decide what deserves an issue.
  • A person closes a point by deleting its file, in any pull request, or by opening an issue for it first. The loop never deletes one.
  • A bug record that lists a point under ## Still open refuses to close without its file, and a PRD refuses to ship while a postponed review comment has none.

Which skill runs which

you type ita skill runs it/omni:brainstorm/omni:yolo <n>/omni:yolo-fix <n>/omni:dossier-open/omni:dossier-push/omni:plan <n>/omni:wave <n>/omni:do-workits pagethen plans itno plan yet?each waveone agentper sliceone perrework/omni:prevery PR the skills open: the claim, the body, the status comment, CI until greenYOURS, ANY TIME/omni:invadethe knowledge base/omni:statusthis session's status/omni:dashboardwhere the PRDs are/omni:helpevery command/omni:ask onanswer on the webA MILESTONE OF PRDS/omni:roadmap <source>every PRD, one phase-0 PRphase-0merged/loop /omni:drive --roadmap <n>each PRD built once its blockers mergedeach tick runsa skill above
SkillType it whenIt ends with
/omni:think-bigyou have a vast idea, one that would take several PRDs, and want to see bold directions before any is cutthe concept pull request, with its vision tour and its areas, and the concept's page under Work › Concepts on the Omni page; its last line is the /omni:brainstorm --concept line of the first area
/omni:brainstormyou have an ideathe PRD issue, the phase-0 pull request (none when phase 0 is approved on the server) and the draft feature pull request; its last line is the /omni:yolo line
/omni:yolo <n>the phase-0 pull request is merged, or the PRD is approved on its pageevery slice merged into the feature branch; the feature pull request ready, or questions for you
/omni:yolo-fix <n>you answered the questionswhat you changed rebuilt, and the feature pull request ready
/omni:roadmap <source>a milestone takes several PRDs, and you have its planevery PRD's issue and spec, roadmap.md, and one phase-0 pull request; its last line is the /loop /omni:drive --roadmap line (Roadmaps)
/loop /omni:drivePRDs, or with --roadmap <n> a roadmap, are approved and you want them built without typing each next commandeach PRD ready, or parked with what it waits on; up to limits.parallelSteps steps (3 by default) run at once when they share no ground, and the loop stops itself (Drive the loop)
/omni:plan <n>a PRD has no plan yet; /omni:yolo runs it for youplan.md, and the draft feature pull request
/omni:wave <n>you want one wave at a time; /omni:yolo runs it for youthe wave's slices merged into the feature branch
/omni:do-work <n> <slice>you want one slice alone; /omni:wave runs it for youone sub-pull request into the feature branch
/omni:pixel-perfect <command> <screen>you want a screen critiqued, audited or polished; with design craft on, /omni:do-work and /omni:visual-fix run its review for youthe screen fixed in one bounded pass, and a report
/omni:pra pull request of the loop is red or conflicts; the skills run it for youthe pull request green, or stuck, with the reason
/omni:enforce <issue>a law issue (omni:law) waits for its test (Laws and their tests)one pull request a person merges: the law's test, seen red with the law broken and green with it restored
/omni:retro-apply --retro <n>never by hand unless no runner took it: the retro pull request's body carries the line when a kept lesson has no outcomeeach kept lesson settled on the retro pull request's branch: a rule appended to its playbook slot and quoted in the body, or the reason it stays here, or one question; it never merges
/omni:rewind <n>never by hand unless no runner took it: a shipped PRD's page reads Broke main, and its Main tab carries the line until a rewind ranthe PRD's Main tab listing where the break started, each finding with its check, its evidence and its fix, for you to approve or reject; it writes nothing to the repository and never merges
/omni:rewind-apply <n> <finding>never by hand unless no runner took it: an approved knowledge finding's card reads Proposing the rule…one docs-only pull request proposing the rule in your repository's knowledge, or the rule that already says it, or one question, shown on the finding's card; it never merges
/omni:tech-review <n>you were named for a PRD's Tech Approval (Tech Approval)the coding parts of the spec and plan changed with you, each settled question recorded under ### Tech review, and the PRD's page link; it gives no approval and never merges, and a runner never runs it
/omni:invadeonce, after the install; with --refresh when the repository has changed a lotone docs pull request: the knowledge base
/omni:statusyou want to know where this session's work standsone plain block: the verdict, the step, what you must do, the links
/omni:dashboardyou want to see where all the PRDs areone screen
/omni:helpyou want to know what a command doesone screen
/omni:ask onyou would rather answer your agent's questions on a web pagethe page's link
/omni:dossier-open, /omni:dossier-pushnever: /omni:brainstorm, /omni:think-big and /omni:plan run themthe PRD's page on the Omni page, or a concept's page under Work › Concepts

Every skill, what it does and when to use it: Skills. The table gives each skill in the kit's form, /omni:<name>; an agent other than Claude Code types it in its own form (Any coding agent).

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 your coding agent (in Claude Code: with ! before them). None of them changes anything, except omni signin, omni update, omni knowledge judge, which writes the sweep's edits into your working tree and opens law issues, and the last two: omni roadmap answer comments on the roadmap's issue, and omni roadmap push updates the roadmap's page.

CommandWhat it says
omni statuswhere the repository's PRDs are, read from git; with --fetch, fetched first
omni status 7whether PRD 7 still has open questions: its outbox gate
omni prd 7where PRD 7 lives, and its files
omni board 7PRD 7's slices, and what can run next
omni roadmap check 1200whether roadmap 1200 holds together: its PRDs wave by wave, or what it refuses
omni kb show briefingone form of the playbook, as the agents read it: briefing, testing…
omni knowledge BR-QUOTE-1one rule of the knowledge base, by its id
omni knowledge judge [<id>]the sweep: asks "worth a law?" of every unenforced law, once per repository, or of the one law <id> names (Laws and their tests)
omni signinsigns this laptop in to the Omni page
omni versionwhich kit the repository runs, and whether a newer one exists
omni updateopens the pull request that brings the repository to the newer kit
omni helpevery command, on one screen
omni roadmap answer 1200 Q5 "…"answers question Q5 of roadmap 1200, in a comment on its issue
omni roadmap push 1200sends where each PRD of roadmap 1200 stands to its page; the drive runs it after every tick

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

Next → Your first PRD