> ## 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.
# Ready Standard: Git-Backed File Format for Product Truth
> Ready Standard is a specification for storing product direction as typed YAML records in git — review, diff, and merge product decisions alongside code.
Ready Standard is a file-based specification for keeping product direction durable. It stores everything that defines your product — premises, intents, standards, and services — as typed `.ready.yml` YAML records committed to a git repository, so your entire team can branch, review, merge, and diff product decisions with the same tools they already use for code.
## Why Ready Standard exists
Product direction drifts when the things that define it live in separate, disconnected systems. Requirements end up in one tool, decisions in another, tickets somewhere else, mockups in a design system, and key context buried in chat threads. No single place reflects what the product actually is at any moment.
Ready Standard solves this by keeping the **durable part** of product truth small, explicit, and colocated with your codebase. A filetree of typed records becomes the authoritative source for what the product should do and why — while richer views for PMs, developers, designers, and customers are compiled from that same tree on demand.
Ready Standard is a **specification**, not an application. It defines the shape, naming rules, and schema contracts for a product tree. Ready Room is an app that reads and writes conforming trees — but any tool, agent, or script that understands the schema can work with a Ready tree.
## The core model
A Ready product tree lives in a `ready/` directory at the root of your repository. It contains four categories of content:
* **Primitive source records** — `.ready.yml` files that each describe one unit of product truth (a premise, an intent, a standard, or a service). These are the machine contract.
* **Flag files** — lightweight Markdown files that track attention and work-readiness state without polluting the durable record.
* **Governance documents** — plain Markdown files that define how product truth is created, changed, approved, and handed to agents.
* **Generated views** — compiled projections (PM briefs, developer handoffs, customer docs) that derive from the tree. They are clearly marked as generated and traceable back to source record hashes.
## Durable truth vs. transient state
The most important design decision in Ready Standard is what it deliberately excludes. Local chat transcripts, scratchpads, search indexes, raw agent logs, and exploratory notes are **transient** — they belong in a local cache, not committed to the tree. A product record only enters the tree when a human or agent intentionally promotes it.
This separation means your git history reflects actual product decisions, not noise, and your tree stays small enough to review in a pull request.
## Minimum conforming tree
Every valid Ready product tree must include at least the following structure. Stage directories (like `m1`) can use any project-specific name — tools read stage metadata from `manifest.yaml`, not from the directory name itself.
```text theme={null}
ready/
manifest.yaml
governance/
m1/
manifest.yaml
premises/
intents/
standards/
services/
flags/
seed/
delta/
discovery/
artifacts/
samples/
resources/
```
The root `ready/manifest.yaml` is required in every conforming tree. It declares the stage registry, default stage, and governance directory. Tools must not infer stage order or default selection from directory names alone.
## Primitive types
Each `.ready.yml` file describes exactly one primitive. The five core primitive types are:
| Type | What it captures |
| --------------- | ------------------------------------------------------ |
| `premise` | Why the product, milestone, or feature should exist |
| `intent` | What the product promises to deliver to users |
| `standard` | How the product must be built, measured, or maintained |
| `service` | What the product depends on to build, run, or monitor |
| `question_card` | An unresolved product-shaping ambiguity |
These five types are sufficient to compile useful product, design, and implementation views. Your project can extend the record kinds as it matures.
## Refs and relationships
Primitives connect to each other through directed `refs` entries. Each ref names a target primitive `id` and a role that describes the relationship. The five built-in ref roles are:
| Role | Meaning |
| ------------------ | ------------------------------------------------------- |
| `serves` | This primitive supports or enables the target |
| `contains_premise` | This primitive is grounded in the target premise |
| `requires` | This primitive depends on the target to function |
| `governed_by` | This primitive is constrained by the target standard |
| `questions` | This primitive raises an open question about the target |
## Flags and claim gates
Flag files are lightweight Markdown files that capture attention and work-readiness state without modifying the durable record. The eight flag types are:
| Flag | When to use |
| -------------- | ----------------------------------------------------- |
| `seed` | A primitive is ready to be considered for coding work |
| `delta` | A change to an existing primitive needs attention |
| `discovery` | An open area of investigation |
| `coverage_gap` | A required area has no primitive coverage yet |
| `blocker` | Something is preventing progress |
| `drift` | Implementation has diverged from the primitive |
| `proof_gap` | Completion proof is missing or insufficient |
| `question` | An unresolved question needs a decision |
Claim gates control whether coding work may proceed against a primitive. The five claim gate fields are `flag_type`, `status`, `blocked_by`, `claimable`, and `completion_proof_state`. Together they let a product orchestrator — human or agent — enforce a checkpoint before implementation starts.
## Stage kinds
The root `ready/manifest.yaml` registers every stage and its kind. The five stage kinds are:
| Kind | Purpose |
| ------------ | --------------------------------------------------------- |
| `normal` | A buildable product stage, eligible for default selection |
| `horizon` | A future concept shelf — not claimable as coding work |
| `experiment` | An alternative branch or product plan under evaluation |
| `archive` | A historical stage, not default-selectable |
| `template` | A reusable starter shape for new stage scaffolding |
## Skills and templates
The Ready Product Leader Skill Pack (`skills/manifest.yaml`, schema `readyroom/skill-package/v1`) is a portable set of task modules that can be loaded by an AI agent to review, validate, and extend a product tree. The five skill modules are `evidence-resource-review`, `access-readiness`, `design-artifact-readiness`, `coding-handoff-readiness`, and `perspective-review`.
Starter templates cover governance documents, stage manifests, root manifests, and artifact manifests. Copy them into your project to get a conforming structure from day one.
## Ready Room app
Ready Room is an application that reads and writes conforming Ready product trees. It provides a UI for authoring primitives, reviewing flags, compiling views, and running agent workflows against your tree. Because Ready Room works against the standard — not a proprietary format — your tree remains fully portable: you can open it in any editor, run your own scripts against it, and version it in any git host.
The full rules for what makes a tree conforming — schemas, stage kinds, default selection logic, and generated-view constraints.
The recommended filetree layout for a Ready product tree, with every directory and file explained.
How to write a `.ready.yml` file, what fields every primitive requires, and how refs and artifacts attach to records.
Flag types, claim gate fields, and how work-readiness state flows through the tree without polluting durable records.
What belongs in `ready/governance/` and how governance documents constrain agent and human workflows.
The Ready Product Leader Skill Pack and reusable starter templates for governance, manifests, and primitives.