> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotready.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Product Tree: The Git-Backed Source of Product Truth
> A Ready product tree is a Git-backed filetree that stores product truth as typed YAML records, compiled into views for any audience or tool.
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.
The `id` field — such as `I-001` or `P-003` — is the durable handle. Paths and titles are refactorable without breaking references.
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.
```yaml theme={null}
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
| Kind | Purpose |
| ------------ | ------------------------------------------------------------------- |
| `normal` | A buildable product stage available for default selection. |
| `horizon` | A future product concept shelf — not claimable implementation work. |
| `experiment` | An alternative branch or product plan under evaluation. |
| `archive` | A historical stage no longer selectable as the default. |
| `template` | A 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:
Why the product, milestone, or feature should exist. Carries evidence confidence and provenance so you can trace every decision back to validated insight.
What the product promises to do. Defines actor, action, expected end state, value, scope, failure behavior, and operating envelope.
How the product must be built, measured, judged, or maintained. Applied globally via workspace refs or per-primitive via `governed_by` refs.
What the product depends on to build, prove, run, or monitor. Captures readiness by environment, failure modes, and simulation rules.
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
Project-specific files constraining how product work happens — agent guidelines, orchestrator charters, process docs, authority and access policies.
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.