.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:
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 directedrefs entries. Each ref names a target primitive id and a role that describes the relationship. The five built-in ref roles are:
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:
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 rootready/manifest.yaml registers every stage and its kind. The five stage kinds are:
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.