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