.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 aready/ directory at the root of your repository. It contains four categories of content:
- Primitive source records —
.ready.ymlfiles 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 (likem1) can use any project-specific name — tools read stage metadata from manifest.yaml, not from the directory name itself.
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 |
Refs and relationships
Primitives connect to each other through directedrefs 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 |
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 rootready/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.Product Tree Standard
The full rules for what makes a tree conforming — schemas, stage kinds, default selection logic, and generated-view constraints.
Directory Layout
The recommended filetree layout for a Ready product tree, with every directory and file explained.
Primitive Records
How to write a
.ready.yml file, what fields every primitive requires, and how refs and artifacts attach to records.Flags & Claims
Flag types, claim gate fields, and how work-readiness state flows through the tree without polluting durable records.
Governance
What belongs in
ready/governance/ and how governance documents constrain agent and human workflows.Skills & Templates
The Ready Product Leader Skill Pack and reusable starter templates for governance, manifests, and primitives.