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:
- Describe the idea, with
/omni:brainstorm. - Review and merge the phase-0 pull request: the written plan, before any code exists.
- Run
/omni:yolo, then read the questions the agents left you, and answer them. - 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):
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):
/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 conventionslists them:CLAUDE.md,AGENTS.md, the readme of yourdocsfolder and the pages they link to). The spec lists every name it chose in a## Conventionstable, 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 theomni:prdlabel. 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) andbefore-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:featurelabel. It stays a draft for now. - The phase-0 pull request, with the
omni:phase-0label: 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 as2.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:
/omni:yolo 7
It asks you nothing. What you see on GitHub while it runs:
- The feature pull request gets the
omni:in-progresslabel, 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:sublabel, 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-fixwith 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:yoloagain. 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:yoloagain: it picks up where it stopped.
/omni:yolo leaves your checkout on a detached commit. To come back to your default branch:
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:
1: A
2: B because the export must include cancelled invoices
1: Akeeps 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: okonce 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:
/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:
releaseNotes:
enabled: true
Dossiers need you signed in on this computer (step 3 of Install). To check what the loop sees, at any time:
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.