DocsOpen the app →

Switch to game mode?

The arcade opens on its menu.

Switch

Your first PRD

From an idea to a merged feature and its release note.

This page takes one idea of yours all the way through the loop: from a conversation with your coding agent to a feature merged into your default branch. You do four things along the way, and the loop does the rest:

  1. Describe the idea, with /omni:brainstorm.
  2. Review and merge the phase-0 pull request: the written plan, before any code exists.
  3. Run /omni:yolo, then read the questions the agents left you, and answer them.
  4. Review and merge the feature pull request: the finished change.

Nothing reaches your default branch unless you merge it yourself.

Before you start

Your laptop is set up (Install), and your repository has the loop installed and invaded: you set it up and followed Invade, and merged both pull requests, or you joined a team whose repository runs it (Join a team). Bring your checkout up to date, then open your coding agent at the root of the repository (in Claude Code: claude):

TERMINAL
git switch main
git pull
claude

Use your own default branch in place of main if it has another name. The checkout must have no uncommitted changes: /omni:yolo refuses to start on one that has.

Pick a small idea for the first run: a change to something that already exists, which you could explain to a colleague in two minutes. The loop copes with big ideas, but a small one lets you see every step in an afternoon.

1. Describe the idea: /omni:brainstorm

In your coding agent, type /omni:brainstorm, followed by your idea in one sentence. That is the kit's form of a skill; other agents type it in their own (Any coding agent):

CODING AGENT
/omni:brainstorm Let people export their invoices as a CSV file

What you see:

  • A link to follow along, when your repository has dossiers switched on: a line starting with "follow along at", which opens a page where anyone in your workspace can read the PRD as it is written. With dossiers off, there is no link, and nothing else changes.
  • How big the agent thinks the idea is. It says so out loud before its first question: a spike (a "can we…?" question, answered without building anything), bounded (a well-scoped change to something that exists) or architectural (something new, or a change to how parts fit together). If you disagree, say so: it takes the heavier one.
  • Questions, one at a time. What you want, who it is for, what success looks like. Answer in plain words. For a bigger idea it proposes two or three approaches and recommends one.
  • The design, for your approval. Nothing is written until you say yes. For an architectural idea it shows the design section by section, then asks you to review the written spec too.
  • Names that follow your conventions. Before it names a table, a column or a field, the agent reads the pages where your repository writes its conventions (omni conventions lists them: CLAUDE.md, AGENTS.md, the readme of your docs folder and the pages they link to). The spec lists every name it chose in a ## Conventions table, each with the page it comes from (which pages are read).

A spike ends here, with an answer and no pull request. Anything else carries on by itself, and the agent opens, in your repository:

  • The PRD issue, titled PRD: <your title>, with the omni:prd label. Its number is the PRD's number: every later step uses it.
  • A feature branch, feat/<topic>, holding the PRD's folder: spec.md (what changes, and why), plan.md (how it gets built, in thin slices) and before-after.html (three tabs: Functional, Technical and Pixel perfect, where each screen that changes is drawn whole, today beside after).
  • The feature pull request, as a draft, with the omni:feature label. It stays a draft for now.
  • The phase-0 pull request, with the omni:phase-0 label: the same folder, and nothing else, going into your default branch.

The reply ends with three blocks: the PRD's folder, Where it is (the loop's six stages, with "you are here" under PRD), and What is next?, whose last line is the command to run next, /omni:yolo followed by the PRD's number.

If the agent stops with "needs clarification", the plan could not be written without a guess: it has asked its question on the PRD issue. Answer it there, then tell the agent, in the same session, that it is answered: it writes the plan and opens the phase-0 pull request.

2. Review and merge the phase-0 pull request

Open the phase-0 pull request from the link under What is next?. It holds only documents, no code: this is the cheapest moment to change your mind. Its body opens with the PRD's page on the Omni app when the repository has one (a link of the shape <ask.url>/prd/<dossier id>), where the spec, the plan and the before/after sit side by side, every version kept; a repository with no page opens with the Refs #<n> line alone.

  • Read spec.md: is this what you asked for?
  • Look at before-after.html: is the after the one you want? GitHub shows its source, so open it from the dossier link when you have one, or download the file from the pull request and open it in your browser. Its Pixel perfect tab names each screen by a reference such as 2.C; the reference names the same state in every later version, so you can ask for a change by it. When the agent had a tool to show the page to you alone first, it did so before committing: you answered Iterate or Carry on, and what you approved is what is in the file.
  • Skim plan.md: the slices, each with the files it may touch, and the waves they are built in.

Something wrong? Do not merge. Tell the agent what to change, in the same session, and ask it to update the PRD on the feature branch and on the phase-0 pull request alike. When it is right, merge the phase-0 pull request on GitHub. The PRD is now in the inbox: approved, and ready to build.

The phase-0 pull request goes into your default branch, not into the PRD's feature branch, which holds the same documents already. That merge is what puts the PRD in the inbox: the loop reads the inbox on the default branch, so until then omni status shows the PRD as in review, and the merge is your approval on record. How the loop works gives all four reasons.

Phase 0 approved on the server. When a workspace owner has switched your repository so its phase 0 is approved on the Omni page, the brainstorm says phase 0: server and opens no phase-0 pull request. Review the same three files on the PRD's page, then press Approve there: the page records who approved and when, and pins the files you approved. If one changes on the feature branch afterwards, the build refuses until you restore it (omni approval restore <n>) or approve again, and the feature pull request's omni/approved check says so. Phase 0 approved on the server says more.

3. Build it: /clear, then /omni:yolo <n>

Start from a clean session: type /clear (or open a new terminal and run claude again). Everything the next step needs is in the repository and on GitHub, so nothing is lost. Then run /omni:yolo with the PRD's number, for example:

CODING AGENT
/omni:yolo 7

It asks you nothing. What you see on GitHub while it runs:

  • The feature pull request gets the omni:in-progress label, and a status comment that says where it is ("merging slices", then how many slices are merged out of how many).
  • One sub-pull request per slice, with the omni:sub label, opened into the feature branch (not into your default branch) and merged there by the loop, one at a time. Slices of the same wave are built side by side.
  • Every decision an agent had to take without you becomes a question in the PRD's outbox, instead of a stop. You answer them all at once, at the end.

When it has finished, the reply ends with the same three blocks, the "you are here" marker now under outbox, and one of three endings:

  • Nothing to run: merging the feature pull request is yours. Every slice is merged, no question is waiting for you, and the feature pull request is marked ready for review. Go to step 5.
  • The last line is /omni:yolo-fix with the PRD's number. Every slice is merged, but questions wait for you: the feature pull request stays a draft. Go to step 4.
  • The last line is /omni:yolo again. Something holds it: a slice that could not be built, a check that stayed red, or something only a person can do (a secret, an access right). Step 1 of What is next? links the pull request that holds it, and step 2 says what to do. Do it, then run /omni:yolo again: it picks up where it stopped.

/omni:yolo leaves your checkout on a detached commit. To come back to your default branch:

TERMINALCODING AGENT
git switch main

4. Answer the outbox, then /omni:yolo-fix <n>

On the feature pull request, a comment lists every open question, each under a number: the question in plain words, the options, and which one was built (always A, the recommended one). Reply to it in a new comment on that pull request, one line per question:

GITHUB COMMENT
1: A
2: B because the export must include cancelled invoices
  • 1: A keeps what was built.
  • 2: B because … chooses another option, and says why.
  • go with recommendation, alone on a line, keeps what was built for every question.
  • A question that asks something of a person (to add a secret, say) takes 3: ok once it is done.

Only people with write access to the repository are read. A reply changes nothing on its own: once you have answered, type /clear, then run:

CODING AGENT
/omni:yolo-fix 7

It reads your replies and records them. Where you chose another option than the one built, it rebuilds that part, one sub-pull request per question, never wider than the question said it could go. It raises no question of its own. When nothing is left open, it marks the feature pull request ready for review. A reply it could not read is asked again, in a new comment on the pull request: answer that one, and run /omni:yolo-fix again.

5. Merge the feature pull request

The feature pull request is ready: review it like any other. Its description says what was built, how it was checked, the risk and how to roll it back, and where to look first. The outbox comment lists every decision the agents took, and your answers.

When the Omni Loop GitHub App is installed on the repository, it posts a check named outbox on the feature pull request: green means no question is left open.

Merge it. The PRD is shipped: the change is on your default branch, and the PRD issue is closed. Its folder moves from .omni-loop/delivery/inbox/ to .omni-loop/delivery/shipped/, with its outbox inside it.

With the GitHub App installed, two more pull requests open a little later: a retro (how the delivery went, with the omni:retro label) and a knowledge pull request (the decisions you settled, written back into what the loop knows about your repository, with the omni:knowledge label). Review and merge each.

6. The release note

When release notes are switched on in your repository, the loop writes one before it marks the feature pull request ready: release.md, in the PRD's folder beside spec.md, a title and one short paragraph saying what shipped, for people outside the team. You review it with the rest of the feature pull request, and once merged it sits in the shipped folder, at .omni-loop/delivery/shipped/<n>-<topic>/release.md.

A switch worth turning on

omni init switches dossiers on and points the kit at the Omni Loop app, but it leaves release notes off. To turn them on, add these lines to .omni-loop/config.yml, then commit and merge the change:

FILE · .omni-loop/config.yml
releaseNotes:
  enabled: true

Dossiers need you signed in on this computer (step 3 of Install). To check what the loop sees, at any time:

TERMINALCODING AGENT
omni status
omni status 7

The first lists your PRDs and where each one stands; the second says whether PRD 7 still has open questions.

Next → Several repositories