> ## 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 Standard Product Tree Directory Layout Reference

> The recommended filetree structure for a conforming Ready product tree, with guidance on each directory, its purpose, and the rules that govern it.

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

```text theme={null}
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](/reference/manifest-schema) 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.

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

## `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](/reference/manifest-schema) 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.

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

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

| Subdirectory | ID prefix | Contents                                  |
| ------------ | --------- | ----------------------------------------- |
| `samples/`   | `SA`      | Sanitized fixture data, user stubs        |
| `resources/` | `RE`      | Safe references, public resources         |
| `snippets/`  | `SN`      | Markdown or plain-text code snippets      |
| `designs/`   | `DA`      | External or binary design file references |
| `manifests/` | `MA`      | Structured JSON or YAML manifests         |

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

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

<Tip>
  A generated file that cannot be traced to source hashes is indistinguishable from edited truth. Always record provenance.
</Tip>