> ## 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.yml Primitive Source Record Schema Reference

> Complete field reference for the .ready.yml primitive source format, including required fields, type-specific content, artifact metadata, and ref syntax.

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:

```yaml theme={null}
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

<ParamField path="schema" type="string" required>
  Always `readyroom/primitive/v1`. Importers use this value to identify the record format version.
</ParamField>

<ParamField path="kind" type="string" required>
  Always `primitive`. Distinguishes source records from manifests and other YAML files in the tree.
</ParamField>

<ParamField path="id" type="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.
</ParamField>

<ParamField path="type" 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
</ParamField>

<ParamField path="title" type="string" required>
  Human-readable label for this primitive. Used in compiled views, indexes, and navigation.
</ParamField>

<ParamField path="milestone" type="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`.
</ParamField>

<ParamField path="status" type="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.
</ParamField>

<ParamField path="summary" type="string" required>
  A concise, reader-friendly statement of the product truth this primitive captures. Compiled views often surface this field as the primary description.
</ParamField>

<ParamField path="fields" type="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.
</ParamField>

<ParamField path="refs" type="array" required>
  Directed semantic edges to other primitives. See [Ref Roles Reference](/reference/ref-roles) for approved roles and direction rules.
</ParamField>

## Optional fields

<ParamField path="artifacts" type="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.
</ParamField>

<ParamField path="owner_notes" type="array">
  Free-form notes from the primitive owner. These do not carry product-truth weight and are excluded from compiled views by default.
</ParamField>

## Type-specific `fields` content

Each primitive type has its own expected `fields` shape. The table below lists the key fields by type.

| Type            | Key fields                                                                                                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `premise`       | `confidence`, `evidence_source`, `provenance`                                                                                                                                   |
| `intent`        | `value`, `actor`, `action`, `end_state`, `scope`, `non_scope`, `failure_behavior`, `input_data`, `output_data`, `required_services`, `required_standards`, `operating_envelope` |
| `standard`      | `rule`, `applies_to`, `measurement`, `enforcement`                                                                                                                              |
| `service`       | `readiness`, `environments`, `access`, `proof_policy`, `failure_modes`, `simulation_rules`, `observability`, `privacy`, `owner`, `readiness_gaps`                               |
| `question_card` | `question`, `context`, `options`, `resolution_criteria`                                                                                                                         |

<Note>
  `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.
</Note>

## Refs format

Use the **full ref format** when the edge source is another primitive:

```yaml theme={null}
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:

```yaml theme={null}
refs:
  - role: requires
    id: SV-001
```

<Warning>
  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.
</Warning>

For the full list of approved roles and direction rules, see the [Ref Roles Reference](/reference/ref-roles).

## 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:

```yaml theme={null}
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
```

<ParamField path="id" type="string" required>
  Stable artifact id using the artifact-family prefix — for example `SA-001` for sample data.
</ParamField>

<ParamField path="artifact_type" type="string" required>
  The artifact family. Valid values: `sample_data`, `resource`, `snippet`, `design`, `manifest`.
</ParamField>

<ParamField path="path" type="string" required>
  Repo-relative path to the artifact file.
</ParamField>

<ParamField path="privacy" type="string" required>
  Privacy classification. For sample data use `sanitized_fixture` or `explicit_user_stub`.
</ParamField>

<ParamField path="used_by" type="array">
  List of primitive ids that reference this artifact.
</ParamField>

<ParamField path="roles" type="array">
  Semantic roles this artifact plays, such as `input_sample`, `proof_screenshot`, or `design_ref`.
</ParamField>

## 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.