Skip to main content
A product tree is a committed filetree that stores every product decision in typed records. Instead of scattering truth across wikis, tickets, and chat logs, you commit one .ready.yml file per primitive — and every view your team uses (PM summary, developer brief, designer spec, customer doc) compiles from that single source. The tree behaves like a healthy codebase: fragmented enough to review in a pull request, explicit enough to validate, and structured enough to compile into anything.

​
The source-of-truth model

Each primitive owns its durable truth in exactly one .ready.yml file. That file is the machine contract. Apps, compilers, validators, search indexes, and agents all read the YAML directly.

Stable IDs are identity

The id field — such as I-001 or P-003 — is the durable handle. Paths and titles are refactorable without breaking references.

Generated views are projections

PM summaries, developer briefs, designer specs, and customer docs compile from the tree. They do not replace it, and they must not duplicate record truth.
Markdown is still useful for navigation, governance docs, and generated views — but it is not the primitive source format. Top-level index files are allowed for navigation, but they must not duplicate record truth.
When a human-authored document proposes a product change, the accepted change must be applied back to the product tree. The document is the proposal; the tree is the decision.

​
Stage registry

The root ready/manifest.yaml owns the stage registry. A stage is a named slice of the product tree — a milestone, a rollout phase, or an experimental branch. Give stages project-specific IDs like m1, alpha, or client-pilot. Tools should read manifest metadata rather than infer meaning from directory names or sort order. 
default_stage: m1
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

​
Stage kinds

KindPurpose
normalA buildable product stage available for default selection.
horizonA future product concept shelf — not claimable implementation work.
experimentAn alternative branch or product plan under evaluation.
archiveA historical stage no longer selectable as the default.
templateA reusable starter shape for new stages.

​
Default selection algorithm

Tools pick the default stage using this deterministic order:
  1. Use default_stage when it points to a valid stage.
  2. Otherwise choose the highest-order stage where kind: normal and default_candidate: true.
  3. Otherwise choose the highest-order stage where kind: normal.
  4. Only fall back to horizon, experiment, archive, or template when no normal stage exists.
end-state is excluded from the normal default path because it is kind: horizon and default_candidate: false — not because of its name. The algorithm ignores names entirely.

​
Primitive types

Five core types cover the full product truth surface:

premise

Why the product, milestone, or feature should exist. Carries evidence confidence and provenance so you can trace every decision back to validated insight.

intent

What the product promises to do. Defines actor, action, expected end state, value, scope, failure behavior, and operating envelope.

standard

How the product must be built, measured, judged, or maintained. Applied globally via workspace refs or per-primitive via governed_by refs.

service

What the product depends on to build, prove, run, or monitor. Captures readiness by environment, failure modes, and simulation rules.

question_card

Unresolved product-shaping ambiguity. When answered, you apply the resulting primitive edits or flags and close the card. History lives in Git.

​
Governance and artifacts

ready/governance/

Project-specific files constraining how product work happens — agent guidelines, orchestrator charters, process docs, authority and access policies.

ready/**/artifacts/

Supporting material attached to primitives, flags, proof, generated views, or handoff — samples, snippets, design assets, screenshots, and handoff notes.
Reusable Ready resources, task-skill packages, and primitive templates live in the Ready standard package — not in any project’s governance or artifact directories.

​
Non-goals

The product tree is not a permanent backend replacement. It is the first durable source of truth. A backend can later index it, render it, coordinate live team state, and host agents — without changing the core product model.
The tree also does not store local chat logs, raw provider transcripts, source diffs, secrets, or unreviewed scratch content. Those belong in the local cache, which is never committed.