Skip to main content
Every product tree starts the same way: a ready/ directory, a root manifest, at least one stage, and a first primitive to anchor everything else. This guide walks you through each step so your tree is valid, reviewable, and ready to grow.
1

Choose your starting point

Pick the approach that fits your project’s current state. All three converge on the same product tree structure; they differ only in where you extract initial premises from.

Human docs only

You have a PRD, spec, or design doc. Extract premises and intents from it. Mark them as inferred confidence until a product lead confirms them.

Existing codebase

You have running code but no product tree. Read the code to infer what product promises are already being kept. Start with services and intents, then write premises that justify them.

Discovery conversation

You have stakeholder interviews or a discovery session. Use question cards for anything unresolved and write premises only for what was actually agreed.
Whichever path you take, resist writing intents until you have at least one premise that justifies them.
2

Create the ready/ directory structure

Make the root ready/ directory and its required subdirectories. The layout below matches the Ready Standard directory layout.
The top-level plural Markdown files (premises.md, intents.md, etc.) inside each stage directory are navigation indexes, not primitive sources. Primitive source records are .ready.yml files inside the subdirectories.
3

Populate ready/manifest.yaml

The root manifest owns the stage registry. Copy the template below and replace every {{placeholder}} with your project’s values.
Every stage entry needs all nine fields: id, title, path, manifest, kind, status, order, default_candidate, and coding_claims_enabled. Tools rely on these fields — do not infer meaning from directory names or sort order.
4

Create the first stage manifest

Each stage directory needs its own manifest.yaml. Create ready/m1/manifest.yaml:
The field name on stage manifests is milestone for the stage id — this is the v1 field name. The root manifest uses stages. Both refer to the same concept.
5

Set up ready/governance/

Governance documents constrain how product truth is created, changed, approved, and handed to agents. Create four files under ready/governance/:Start with stubs if you do not have full content yet. These files are Markdown, not primitives, and they are referenced by path from stage manifests.
6

Write the first premise primitive

Anchor the tree with at least one premise before adding intents. Create ready/m1/premises/p-001-core-problem.ready.yml:
A premise inferred only from a document should start at evidence_confidence: low or medium. Raise it to high only after a product lead or stakeholder explicitly confirms it.
7

Run a validator pass

Before adding more primitives, validate what you have. Run your team’s validator (or the Ready Room built-in check) against the tree:
Fix any schema errors before continuing. A clean validator pass on a minimal tree is far easier to debug than one on a hundred files.
At minimum, check that: schema is present on every .ready.yml file, id values are unique across the stage, milestone matches the stage id in the root manifest, and every refs entry uses an approved role.
8

Handle uncertainty correctly

You will hit gaps immediately. Use these patterns instead of prose notes:Unresolved questions → question cards. Create a question_card primitive for anything that would change the shape of an intent or premise if answered differently.
Low confidence → evidence_confidence: low field. Do not write confident-sounding summaries for premises you are guessing at. Mark the confidence and move on.Unknowns in intents → status: draft. A draft intent signals that the promise is not yet accepted product truth. Keep it draft until the question card is resolved.
Commit your tree after each step. Git is how you review and audit product decisions. Small commits make the diff meaningful when a premise changes.