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: 
schema: readyroom/primitive/v1
kind: primitive
id: I-001
type: intent
title: Human-readable title
milestone: m1
status: active
summary: Concise product-truth statement
fields:
  value: Why this matters to the user or operator.
  failure_behavior: What happens when the intent cannot be fulfilled.
  input_data: What the intent reads.
  output_data: What the intent produces.
refs:
  - from: I-001
    role: serves
    to: P-001
artifacts: []
owner_notes: []

​
Required fields

​
schema
string
required
Always readyroom/primitive/v1. Importers use this value to identify the record format version.
​
kind
string
required
Always primitive. Distinguishes source records from manifests and other YAML files in the tree.
​
id
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.
​
type
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
​
title
string
required
Human-readable label for this primitive. Used in compiled views, indexes, and navigation.
​
milestone
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.
​
status
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.
​
summary
string
required
A concise, reader-friendly statement of the product truth this primitive captures. Compiled views often surface this field as the primary description.
​
fields
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.
​
refs
array
required
Directed semantic edges to other primitives. See Ref Roles Reference for approved roles and direction rules.

​
Optional fields

​
artifacts
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.
​
owner_notes
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.
TypeKey fields
premiseconfidence, evidence_source, provenance
intentvalue, actor, action, end_state, scope, non_scope, failure_behavior, input_data, output_data, required_services, required_standards, operating_envelope
standardrule, applies_to, measurement, enforcement
servicereadiness, environments, access, proof_policy, failure_modes, simulation_rules, observability, privacy, owner, readiness_gaps
question_cardquestion, context, options, resolution_criteria
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: 
refs:
  - from: I-001
    role: serves
    to: P-001
Use the compact ref format when the current primitive is the edge source. The from field is inferred as the current primitive id: 
refs:
  - role: requires
    id: SV-001
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: 
id: SA-001
artifact_type: sample_data
path: ready/m1/artifacts/samples/SA-001.json
privacy: sanitized_fixture
used_by:
  - I-001
roles:
  - input_sample
​
id
string
required
Stable artifact id using the artifact-family prefix — for example SA-001 for sample data.
​
artifact_type
string
required
The artifact family. Valid values: sample_data, resource, snippet, design, manifest.
​
path
string
required
Repo-relative path to the artifact file.
​
privacy
string
required
Privacy classification. For sample data use sanitized_fixture or explicit_user_stub.
​
used_by
array
List of primitive ids that reference this artifact.
​
roles
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.