Skip to main content
Every product primitive lives in a .ready.yml file — one primitive per file. The .ready.yml extension is intentional: it lets tools reliably distinguish primitive source records from navigation Markdown, generated docs, manifests, and generic artifacts. Humans normally read compiled views in the Ready Room app or docs; the raw .ready.yml file is optimized for parsing, validation, diffing, and Git merge review.

​
Complete primitive record

The following example shows all required fields and the most common optional fields:

​
Required fields

​
string
required
Always readyroom/primitive/v1. Importers use this value to identify the record format version.
​
string
required
Always primitive. Distinguishes source records from manifests and other YAML files in the tree.
​
string
required
Stable identifier for this primitive. Use the type prefix followed by a zero-padded number — for example P-001, I-001, ST-001, or SV-001. Keep id stable across renames; paths and titles are refactorable, ids are not.
​
enum
required
The primitive type. Valid values:
  • premise — why the product, milestone, or feature should exist
  • intent — what the product promises to do
  • standard — how the product must be built, measured, judged, or maintained
  • service — what the product depends on to build, prove, run, or monitor
  • question_card — unresolved product-shaping ambiguity
​
string
required
Human-readable label for this primitive. Used in compiled views, indexes, and navigation.
​
string
required
The owning stage id — for example m1 or end-state. The v1 field name is milestone even though the root manifest groups stages under the key stages.
​
string
required
Product-facing status. Common values are active, draft, and blocked. This is product status, not implementation lifecycle state. Do not store coding lifecycle state on primitives.
​
string
required
A concise, reader-friendly statement of the product truth this primitive captures. Compiled views often surface this field as the primary description.
​
object
required
Type-specific structured content. Every value that an app, compiler, validator, search index, or agent must read belongs in YAML here — not in prose comments or Markdown files.
​
array
required
Directed semantic edges to other primitives. See Ref Roles Reference for approved roles and direction rules.

​
Optional fields

​
array
List of artifact ids or paths that support this primitive. Artifacts live in the stage artifacts/ directory. Use ids or paths; do not inline large payloads.
​
array
Free-form notes from the primitive owner. These do not carry product-truth weight and are excluded from compiled views by default.

​
Type-specific fields content

Each primitive type has its own expected fields shape. The table below lists the key fields by type.
required_services and required_standards in an intent’s fields are reader aids. You still need matching refs entries with role: requires and role: governed_by so validators and graph-traversal tools can follow the edges.

​
Refs format

Use the full ref format when the edge source is another primitive:
Use the compact ref format when the current primitive is the edge source. The from field is inferred as the current primitive id:
Use compact refs only for outgoing edges from the current primitive. If a record stores an edge whose source is a different primitive, always write the explicit from and to so the canonical direction is unambiguous.
For the full list of approved roles and direction rules, see the Ref Roles Reference.

​
Artifact metadata format

Artifacts are not primitives. They use typed manifests or index rows rather than primitive fields. At minimum, each artifact entry should identify the id, artifact type, path, privacy state, and the primitives that use it:
​
string
required
Stable artifact id using the artifact-family prefix — for example SA-001 for sample data.
​
string
required
The artifact family. Valid values: sample_data, resource, snippet, design, manifest.
​
string
required
Repo-relative path to the artifact file.
​
string
required
Privacy classification. For sample data use sanitized_fixture or explicit_user_stub.
​
array
List of primitive ids that reference this artifact.
​
array
Semantic roles this artifact plays, such as input_sample, proof_screenshot, or design_ref.

​
File rules

Keep these rules in mind when authoring .ready.yml files:
  • Use one primitive per file.
  • Keep files fragmented and small enough to review in a pull request.
  • Store relationships in refs, not in prose.
  • Store bulky samples, mockups, screenshots, snippets, and generated outputs as artifacts referenced by id or path.
  • Do not store local chat logs, raw provider transcripts, source diffs, secrets, or unreviewed scratch content in primitive records.
  • Do not store coding lifecycle state on primitives — seed and delta flags gate coding claims.