Ready Standard Quickstart: Your First Product Tree

This guide walks you through creating a minimal, conforming Ready product tree from scratch. By the end you will have a working ready/ directory with a root manifest, your first primitive record, and governance stubs — ready to commit and review in Git.

Create the ready/ directory structure

Start by scaffolding the required directories. The root ready/ directory lives at the top level of your repository. Inside it you need at least one stage directory (this guide uses m1) and a governance/ directory.

mkdir -p ready/governance
mkdir -p ready/end-state
mkdir -p ready/m1/premises
mkdir -p ready/m1/intents
mkdir -p ready/m1/standards
mkdir -p ready/m1/services
mkdir -p ready/m1/flags/seed
mkdir -p ready/m1/flags/delta
mkdir -p ready/m1/flags/discovery
mkdir -p ready/m1/artifacts/samples
mkdir -p ready/m1/artifacts/resources

Your tree should now look like this:

ready/
  governance/
  end-state/
  m1/
    premises/
    intents/
    standards/
    services/
    flags/
      seed/
      delta/
      discovery/
    artifacts/
      samples/
      resources/

Stage directories can use any project-specific name — alpha, client-pilot, v2, and so on. Ready tools read stage identity from manifest.yaml, not from the directory name itself. Pick names that are meaningful to your team.

Initialize ready/manifest.yaml

The root manifest is required in every conforming tree. It declares the stage registry, the default stage, and the location of your governance directory. Create ready/manifest.yaml with the following content, replacing the placeholder values with your own product id and stage details:

schema: "readyroom/product-tree-root/v1"
product: "my-product"
source_root: "ready"
default_stage: "m1"
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

Key fields to understand:

Field	Purpose
`default_stage`	The stage tools open by default. Must match an `id` in the `stages` list.
`kind: normal`	A buildable product stage — eligible for default selection.
`kind: horizon`	A future concept shelf. Not claimable as implementation work.
`default_candidate`	When `true`, this stage is a candidate for automatic default selection.
`coding_claims_enabled`	When `true`, coding work can be claimed against this stage’s primitives.
`order`	Numeric sort order used when resolving the default stage automatically.

The end-state stage is excluded from the default selection path because it is kind: horizon and default_candidate: false. Its high order value of 9999 does not promote it — stage kind takes precedence over order.

You also need a stage-level manifest for m1. 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"
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"
primitive_directories:
  premises: "premises/"
  intents: "intents/"
  standards: "standards/"
  services: "services/"
flag_directories:
  seed: "flags/seed/"
  delta: "flags/delta/"
  discovery: "flags/discovery/"
artifact_directories:
  manifest: "artifacts/manifest.yaml"
  samples: "artifacts/samples/"
  resources: "artifacts/resources/"

Write your first primitive record

Primitive records are the heart of a Ready tree. Each .ready.yml file describes one unit of product truth. Create your first premise record at ready/m1/premises/p-001-initial-premise.ready.yml:

schema: "readyroom/primitive/v1"
kind: "primitive"
id: "p-001"
type: "premise"
title: "Users need a single source of truth for product direction"
milestone: "m1"
status: "active"
summary: >
  Product teams lose alignment when requirements, decisions, and context
  are scattered across separate tools. A committed filetree of typed records
  gives every contributor — human or agent — one place to read and update
  what the product is and why it exists.
fields:
  premise_type: "need"
  statement: "Teams need one authoritative place for product direction that all contributors can read and update."
  evidence_provenance: "Observed across multiple product teams where misalignment led to rework."
  evidence_confidence: "high"
  product_implication: "The product must provide a committed, versioned filetree as the primary record format."
refs: []
artifacts: []
owner_notes: >
  This is the foundational premise for the entire product. All other
  premises and intents should trace back to this one.

The fields to know:

Field	Required	Description
`schema`	✅	Always `readyroom/primitive/v1` for primitive records.
`kind`	✅	Always `primitive` for primitive source records.
`id`	✅	Stable, unique identifier. Never change this after a record is published.
`type`	✅	One of `premise`, `intent`, `standard`, `service`, or `question_card`.
`title`	✅	Human-readable name. Refactorable — the `id` is the durable identity.
`milestone`	✅	The stage `id` this primitive belongs to.
`status`	✅	Lifecycle state, e.g. `active`, `draft`, `deprecated`.
`summary`	✅	A concise explanation in plain language.
`refs`	✅	Directed references to other primitive `id` values. Use `[]` when empty.
`artifacts`	✅	References to supporting samples or resources. Use `[]` when empty.

Use a consistent id prefix per type — p- for premises, i- for intents, st- for standards, sv- for services. Numeric suffixes (001, 002) keep files sorted predictably in any file explorer.

Never commit secrets, API keys, credentials, or personal data inside a .ready.yml file. Product trees are often committed to shared or public repositories. Use your project’s secrets management system for sensitive values, and reference them by name only if needed.

Set up governance

Governance documents live in ready/governance/ and define how product truth is created, reviewed, changed, and handed to agents. Create the four standard stubs:

touch ready/governance/agent-guidelines.md
touch ready/governance/product-orchestrator-charter.md
touch ready/governance/product-process.md
touch ready/governance/workspace-authority-and-access.md

Populate each file with a minimal header so they are recognisable. Here is a starter for each:agent-guidelines.md — Rules and constraints for any AI agent that reads or writes the product tree. Define what an agent may propose, what it must never modify directly, and how it should signal uncertainty.

# Agent Guidelines

Agents may propose changes to primitive records by creating draft `.ready.yml`
files or opening a pull request. Agents must not modify `ready/manifest.yaml`
or governance documents without explicit human approval.

product-orchestrator-charter.md — Defines the role of the product orchestrator (human or agent) responsible for maintaining the integrity of the tree and resolving conflicts between competing primitives.

# Product Orchestrator Charter

The product orchestrator is responsible for the structural integrity of the
ready/ tree, stage transitions, and primitive lifecycle decisions.

product-process.md — Documents the team’s process for proposing, reviewing, and merging product records — including branching conventions, review requirements, and how question_card primitives get resolved.

# Product Process

All new primitives begin as a draft pull request. A premise requires one
product review approval before merging to the default stage.

workspace-authority-and-access.md — Defines who (or which agent role) has authority to read, write, or approve changes to each part of the tree.

# Workspace Authority and Access

| Path | Read | Write | Approve |
|---|---|---|---|
| ready/manifest.yaml | all | orchestrator | orchestrator |
| ready/governance/ | all | orchestrator | orchestrator |
| ready/m1/ | all | contributors | reviewer |

Even stub governance files are valuable from day one. They make the tree’s rules explicit to agents and new contributors, and they give you a clear place to evolve process decisions without burying them in chat or wikis.

Validate your tree

Before committing, run a validator or importer against your tree to check structural integrity. A conforming validator will verify that:

ready/manifest.yaml exists and uses a recognised schema.
Every stage listed in the root manifest has a corresponding directory and stage manifest.
Every .ready.yml file has the required fields (schema, kind, id, type, title, milestone, status, summary, refs, artifacts).
All refs entries point to id values that exist in the tree.
No primitive id is duplicated within a stage.
Generated views are marked as generated and not treated as source records.

If you are using Ready Room, the importer runs automatically when you open the tree and surfaces validation errors in the UI.For CI pipelines, you can invoke the validator directly:

# Example — adjust the command for your chosen validator tool
ready validate --tree ./ready

See Validator Rules for the complete list of structural rules a conforming tree must satisfy. The reference includes the exact error codes the importer emits and how to resolve each one.

Do not skip validation before merging a pull request that changes ready/manifest.yaml or adds a new stage. An invalid stage entry can prevent tools from resolving the default stage correctly and break agent workflows that depend on the stage registry.

Once your tree passes validation, commit the whole ready/ directory and open a pull request. Your product tree is now live in Git and ready to review.

git add ready/
git commit -m "chore: initialise Ready product tree"
git push origin main

Next steps

You now have a minimal conforming Ready tree. From here you can:

Add more primitive records (intents/, standards/, services/) using the same .ready.yml pattern from Step 3. See Writing Primitives for field-by-field guidance on each type.
Explore the full Directory Layout reference to understand every optional directory and file.
Read the Product Tree Standard to understand stage kinds, default selection logic, and how generated views must be structured.
Learn about Flags & Claims to understand how seed, delta, coverage_gap, blocker, and other flag types signal work-readiness state across the tree.
Load the Ready Product Leader Skill Pack to give an AI agent structured task modules for reviewing and extending your tree.
Browse the Governance & Manifest Templates to copy conforming starters for root manifests, stage manifests, and governance documents.
Connect Ready Room to your repository to get a UI for authoring, reviewing, and compiling your tree.

​Next steps

Next steps