Primitive records are the atoms of a Ready product tree. Each record is a single .ready.yml file — plain YAML with a distinct extension so importers know exactly how to parse it. You, your agents, and your tools read compiled views in the Ready Room app or docs; the raw file is optimized for parsing, validation, diffing, and merge review. Every value an app, compiler, validator, search index, or agent must read lives in YAML. Reader-friendly summaries, PM briefs, designer views, and customer-facing docs are compiled from these records.
Common structure
Every primitive shares a base template. The fields below appear in all five types:
schema: readyroom/primitive/v1
kind: primitive
id: I-001
type: intent
title: Browse and edit the primitive-backed product spine
milestone: m1
status: active
summary: The concise product-truth statement.
fields:
value: Why this matters to the user or operator.
failure_behavior: What happens when the intent cannot be fulfilled.
refs:
- from: I-001
role: serves
to: P-001
artifacts: []
owner_notes: []
Core file rules
Follow these rules for every primitive record you create or edit:
- One primitive per file. Never combine multiple records in a single
.ready.yml.
- Keep IDs stable. Paths and titles are refactorable; the
id field is the durable identity.
- Store relationships in
refs, not prose. Use directed edges: intent --serves--> premise, intent --contains_premise--> premise, intent --requires--> service, intent --governed_by--> standard.
- Do not store inverse tree edges. Compiled views derive inverse labels automatically. Do not write
premise --serves--> intent or service --serves--> intent.
- Use compact refs only for outgoing edges. Compact refs infer
from as the current primitive’s ID.
- Reference bulky material, don’t embed it. Store 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.
Primitive types
Premise
Intent
Standard
Service
Question Card
Premises explain why the product should exist. Every premise needs evidence confidence and provenance in its fields so reviewers can assess how well-founded the reasoning is. A premise inferred only from documents should be marked inferred or low-confidence until the product lead confirms it.schema: readyroom/primitive/v1
kind: primitive
id: P-001
type: premise
title: Developers lose context switching between product docs and code
milestone: m1
status: active
summary: Context switching between scattered docs and code increases error rates and slows delivery.
fields:
evidence: User interviews with 12 engineering leads, Q3 research cohort.
confidence: high
provenance: Confirmed by product lead 2024-11-14.
value: Reducing context switches cuts rework and speeds reviews.
refs: []
artifacts: []
owner_notes: []
Mark unconfirmed premises with confidence: low or confidence: inferred until the product lead signs off. Low-confidence premises are valid open questions — not errors.
Intents are product promises. A committed intent must define the actor, action, expected end state, value, scope, non-scope, failure behavior, input/output data, required services, required standards, and an Operating Envelope when behavior can vary materially after release.schema: readyroom/primitive/v1
kind: primitive
id: I-001
type: intent
title: Browse and edit the primitive-backed product spine
milestone: m1
status: active
summary: A product lead can navigate the full product tree and edit any primitive from a single view.
fields:
actor: Product lead
action: Browse and edit primitives
end_state: All primitives reachable and editable without switching tools.
value: Reduces friction in maintaining product truth.
scope: Primitive read and write within a single workspace.
non_scope: Real-time multi-user collaborative editing.
failure_behavior: Show a clear error if a write fails; do not silently discard changes.
inputs: Workspace path, user identity.
outputs: Updated .ready.yml file, committed change.
operating_envelope: Works on workspaces up to 10,000 primitives.
refs:
- from: I-001
role: serves
to: P-001
- from: I-001
role: requires
to: SV-001
artifacts: []
owner_notes: []
Completion Proof does not live on the persistent intent body. It belongs on the seed or delta flag that gates coding work.
Standards state rules for implementation, measurement, judgment, behavior, or maintenance. Apply a standard globally via workspace standard refs, or per-primitive via a directed governed_by ref on the primitive that must follow the rule.schema: readyroom/primitive/v1
kind: primitive
id: ST-001
type: standard
title: All API responses must include a request trace ID
milestone: m1
status: active
summary: Every API response must carry a trace ID header for observability and support.
fields:
rule: Include X-Trace-ID in all HTTP responses.
measurement: Automated header check in integration tests.
judgment: Fail any deploy that omits the header on any route.
maintenance: Review quarterly when observability tooling changes.
refs: []
artifacts: []
owner_notes: []
Services capture dependencies required to build, prove, run, or monitor the product. For each service, record readiness by environment, access expectations, proof policy, failure modes, simulation rules, observability, privacy, owner, and any readiness gaps.schema: readyroom/primitive/v1
kind: primitive
id: SV-001
type: service
title: Auth token verification service
milestone: m1
status: active
summary: Verifies bearer tokens issued by the identity provider before granting API access.
fields:
environments:
local: Simulated via mock; see SV-001-mock artifact.
staging: Live integration with staging IdP.
production: Live integration with production IdP.
access: API key stored in secrets manager; never in source.
failure_modes: Token expiry returns 401; network timeout returns 503.
simulation: Use mock token fixtures from artifacts/sv-001-fixtures.yaml.
observability: Token verification latency tracked in Datadog dashboard.
privacy: Tokens are not logged; only trace IDs are emitted.
owner: Platform team.
readiness_gaps: Production rate limit not yet confirmed with IdP.
refs: []
artifacts:
- artifacts/sv-001-mock.yaml
owner_notes: []
Question cards hold unresolved product-shaping ambiguity. When the question is answered, apply the resulting primitive edits or flags, then close the card. History belongs in Git, events, assessments, or implementation refs — not on the card body.schema: readyroom/primitive/v1
kind: primitive
id: Q-001
type: question_card
title: Should offline mode be in scope for M1?
milestone: m1
status: active
summary: Unresolved: whether M1 must support full offline editing or defer it to a later stage.
fields:
question: Is full offline primitive editing required for M1 launch?
trigger: Customer pilot feedback indicated offline use cases may be common.
options:
- Include offline mode in M1 scope and update I-001 operating envelope.
- Defer offline mode to M2 and add a coverage_gap flag to I-001.
decision_owner: Product lead.
refs:
- from: Q-001
role: questions
to: I-001
artifacts: []
owner_notes: []
When you resolve a question card, apply the chosen primitive edits or raise the appropriate flags, then remove the card from the tree. Its history is preserved in Git — you do not need to keep the file to retain the audit trail.
