How to Start a New Ready Product Tree from Scratch

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.

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.

Create the ready/ directory structure

Make the root ready/ directory and its required subdirectories. The layout below matches the Ready Standard directory layout.

mkdir -p ready/governance
mkdir -p ready/end-state
mkdir -p ready/m1/premises ready/m1/intents ready/m1/standards
mkdir -p ready/m1/services ready/m1/flags/seed ready/m1/flags/delta
mkdir -p ready/m1/flags/discovery
mkdir -p ready/m1/artifacts/samples ready/m1/artifacts/resources
mkdir -p ready/m1/artifacts/snippets ready/m1/artifacts/designs
mkdir -p ready/m1/artifacts/manifests
touch ready/README.md ready/m1/README.md ready/end-state/README.md

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.

Populate ready/manifest.yaml

The root manifest owns the stage registry. Copy the template below and replace every {{placeholder}} with your project’s values.

schema: "readyroom/product-tree-root/v1"
product: "my-product"           # short stable id, no spaces
source_root: "ready"
default_stage: "m1"             # must match an id in stages list
governance_directory: "ready/governance"
ready_standard:
  repository: "https://github.com/seanbhart/ready-standard"
  docs_source: "https://github.com/seanbhart/ready-standard/tree/main/docs"
  skill_package_source: "https://github.com/seanbhart/ready-standard/tree/main/skills"
  templates_source: "https://github.com/seanbhart/ready-standard/tree/main/templates"
stages:
  - id: "m1"
    title: "M1"
    path: "ready/m1"
    manifest: "ready/m1/manifest.yaml"
    kind: "normal"
    status: "active"
    order: 10
    default_candidate: true
    coding_claims_enabled: false
  - id: "end-state"
    title: "End State"
    path: "ready/end-state"
    manifest: "ready/end-state/manifest.yaml"
    kind: "horizon"
    status: "horizon"
    order: 9999
    default_candidate: false
    coding_claims_enabled: false

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.

Create the first stage manifest

Each stage directory needs its own manifest.yaml. Create ready/m1/manifest.yaml:

schema: "readyroom/product-tree/v1"
product: "my-product"
milestone: "m1"
stage:
  id: "m1"
  title: "M1"
  kind: "normal"
  status: "active"
  order: 10
  default_candidate: true
  coding_claims_enabled: false
source_model: "file_per_record_ready_yaml"
source_root: "ready/m1"
governance_docs:
  root: "../governance/"
  agent_guidelines: "../governance/agent-guidelines.md"
  product_orchestrator_charter: "../governance/product-orchestrator-charter.md"
  product_process: "../governance/product-process.md"
  workspace_authority_and_access: "../governance/workspace-authority-and-access.md"
primitive_directories:
  premises: "premises/"
  intents: "intents/"
  standards: "standards/"
  services: "services/"
flag_directories:
  seed: "flags/seed/"
  delta: "flags/delta/"
  discovery: "flags/discovery/"
artifact_directories:
  index: "artifacts.md"
  manifest: "artifacts/manifest.yaml"
  samples: "artifacts/samples/"
  resources: "artifacts/resources/"
  snippets: "artifacts/snippets/"
  designs: "artifacts/designs/"
  manifests: "artifacts/manifests/"

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.

Set up ready/governance/

Governance documents constrain how product truth is created, changed, approved, and handed to agents. Create four files under ready/governance/:

File	Purpose
`agent-guidelines.md`	Rules for product and coding agents working in this tree
`product-orchestrator-charter.md`	Authority and scope of the product orchestrator role
`product-process.md`	How your team moves primitives from draft to active
`workspace-authority-and-access.md`	Who can approve what, and which credentials/environments exist

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.

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:

schema: readyroom/primitive/v1
kind: primitive
id: P-001
type: premise
title: Core problem this product solves
milestone: m1
status: active
summary: >
  One or two sentences stating the observable problem or opportunity
  that justifies building this product.
fields:
  evidence_confidence: medium   # low | medium | high
  evidence_provenance: "Product lead interview, 2024-01-15"
  product_implication: >
    If this premise is true, the product must be able to do X.
    If it is false, Y feature is unnecessary.
refs: []
artifacts: []
owner_notes:
  - "Confidence will rise to high once user research confirms session drop data."

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.

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:

# Example — adapt to your toolchain
ready validate ready/

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.

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.

schema: readyroom/primitive/v1
kind: primitive
id: QC-001
type: question_card
title: Who is the primary actor for the billing flow?
milestone: m1
status: active
summary: >
  It is unclear whether billing is self-serve by the end user
  or managed by an admin on their behalf.
fields:
  resolution_path: "Schedule a 30-min session with product lead."
  blocking: ["I-004"]
refs: []
artifacts: []
owner_notes: []

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.