Skip to main content
A conforming Ready product tree stores product truth in a predictable layout so importers, validators, and reading tools can find every primitive without guessing. The root manifest declares the stage registry; tools must read that manifest rather than infer stage order or meaning from directory names.

​
Full directory tree

ready/
  README.md
  manifest.yaml
  governance/
    agent-guidelines.md
    product-orchestrator-charter.md
    product-process.md
    workspace-authority-and-access.md
  end-state/
    README.md
    manifest.yaml
  m1/
    README.md
    manifest.yaml
    premises.md
    premises/
      p-001-example.ready.yml
    intents.md
    intents/
      i-001-example.ready.yml
    standards.md
    standards/
      st-001-example.ready.yml
    services.md
    services/
      sv-001-example.ready.yml
    flags.md
    flags/
      seed/
        f-001-example.md
      delta/
      discovery/
    artifacts.md
    artifacts/
      manifest.yaml
      samples/
        MANIFEST.json
        SA-001.json
      resources/
      snippets/
      designs/
      manifests/

​
Top-level files

ready/README.md — A human-authored navigation index for the entire product tree. Link to stages and governance here; do not duplicate primitive truth in this file. ready/manifest.yaml — The root stage registry. Every tool that loads the product tree must start here. This file lists all stages, their paths, kinds, statuses, and default-selection metadata. See the Manifest Schema Reference for the full field list.

​
ready/governance/

Store project-specific governance documents here — agent behavior guidelines, the product-orchestrator charter, process documents, and workspace authority policies. Governance documents are first-class product-tree records.
Reusable Ready resources, task-skill packages, and templates belong in the Ready standard package, not in ready/governance/. Copy them here only when your project needs a vendored offline copy, and mark them as vendored.

​
ready/end-state/

The horizon stage shelf. Declare this stage with kind: horizon and default_candidate: false in the root manifest. Tools exclude horizon stages from the normal default-selection path.

​
ready/m1/ (or any stage directory)

Each active stage gets its own directory. The directory name — m1, m2, alpha, client-pilot — is a project-chosen identifier. Tools read meaning from the stage manifest, not from the directory name.

​
manifest.yaml

The per-stage manifest. It records stage metadata, references to primitive and flag directories, artifact directory layout, and governance doc paths. See Manifest Schema Reference for all fields.

​
premises/, intents/, standards/, services/

Each subdirectory holds primitive source records for that type. Every file in these directories is a .ready.yml file — one primitive per file.

​
premises.md, intents.md, standards.md, services.md

These plural Markdown files at the stage root are navigation indexes only. They do not contain primitive truth. Importers and validators must read the .ready.yml files in the corresponding directories.
The .md index files exist to help humans browse the tree in a plain Git viewer. They do not replace or duplicate the .ready.yml source records.

​
flags/

Contains three subdirectories:
  • seed/ — Seed flags that gate new coding claims on a primitive.
  • delta/ — Delta flags that gate incremental changes to an already-shipped primitive.
  • discovery/ — Discovery flags used to surface research findings and resolve question_card primitives.
Seed and delta flags are non-claimable unless they pass the claim gate. Ready flags with a non-empty blocked_by field remain non-claimable regardless of other fields.

​
artifacts/

Holds supporting materials for the stage: sample data, resources, code snippets, design assets, and structured manifests. Artifacts support primitives and proof; they are not primitive source records.
SubdirectoryID prefixContents
samples/SASanitized fixture data, user stubs
resources/RESafe references, public resources
snippets/SNMarkdown or plain-text code snippets
designs/DAExternal or binary design file references
manifests/MAStructured JSON or YAML manifests
Do not store governing docs or Ready standard resources under artifact directories. Governance belongs in ready/governance/. Reusable Ready resources should be referenced from the standard package or an explicitly vendored copy.

​
Generated outputs

You may add compiled/ or views/ directories to cache generated output alongside the source tree. Any generated directory must meet two requirements:
  1. Clearly marked as generated — include a header or metadata field that identifies the file as derived output.
  2. Traceable to source record hashes — every generated file must record the content hashes of the .ready.yml source records it was compiled from so staleness is detectable.
A generated file that cannot be traced to source hashes is indistinguishable from edited truth. Always record provenance.