> ## 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 Quickstart: Your First Product Tree

> Set up your first Ready product tree step by step — from creating the directory structure to writing your first primitive record and governance stubs.

This guide walks you through creating a minimal, conforming Ready product tree from scratch. By the end you will have a working `ready/` directory with a root manifest, your first primitive record, and governance stubs — ready to commit and review in Git.

<Steps>
  <Step title="Create the ready/ directory structure">
    Start by scaffolding the required directories. The root `ready/` directory lives at the top level of your repository. Inside it you need at least one stage directory (this guide uses `m1`) and a `governance/` directory.

    ```bash theme={null}
    mkdir -p ready/governance
    mkdir -p ready/end-state
    mkdir -p ready/m1/premises
    mkdir -p ready/m1/intents
    mkdir -p ready/m1/standards
    mkdir -p ready/m1/services
    mkdir -p ready/m1/flags/seed
    mkdir -p ready/m1/flags/delta
    mkdir -p ready/m1/flags/discovery
    mkdir -p ready/m1/artifacts/samples
    mkdir -p ready/m1/artifacts/resources
    ```

    Your tree should now look like this:

    ```text theme={null}
    ready/
      governance/
      end-state/
      m1/
        premises/
        intents/
        standards/
        services/
        flags/
          seed/
          delta/
          discovery/
        artifacts/
          samples/
          resources/
    ```

    <Tip>
      Stage directories can use any project-specific name — `alpha`, `client-pilot`, `v2`, and so on. Ready tools read stage identity from `manifest.yaml`, not from the directory name itself. Pick names that are meaningful to your team.
    </Tip>
  </Step>

  <Step title="Initialize ready/manifest.yaml">
    The root manifest is required in every conforming tree. It declares the stage registry, the default stage, and the location of your governance directory. Create `ready/manifest.yaml` with the following content, replacing the placeholder values with your own product id and stage details:

    ```yaml theme={null}
    schema: "readyroom/product-tree-root/v1"
    product: "my-product"
    source_root: "ready"
    default_stage: "m1"
    governance_directory: "ready/governance"
    ready_standard:
      repository: "https://github.com/seanbhart/ready-standard"
      docs_source: "https://github.com/seanbhart/ready-standard/tree/main/docs"
      skill_package_source: "https://github.com/seanbhart/ready-standard/tree/main/skills"
      templates_source: "https://github.com/seanbhart/ready-standard/tree/main/templates"
    stages:
      - id: "m1"
        title: "M1"
        path: "ready/m1"
        manifest: "ready/m1/manifest.yaml"
        kind: "normal"
        status: "active"
        order: 10
        default_candidate: true
        coding_claims_enabled: false
      - id: "end-state"
        title: "End State"
        path: "ready/end-state"
        manifest: "ready/end-state/manifest.yaml"
        kind: "horizon"
        status: "horizon"
        order: 9999
        default_candidate: false
        coding_claims_enabled: false
    ```

    Key fields to understand:

    | Field                   | Purpose                                                                   |
    | ----------------------- | ------------------------------------------------------------------------- |
    | `default_stage`         | The stage tools open by default. Must match an `id` in the `stages` list. |
    | `kind: normal`          | A buildable product stage — eligible for default selection.               |
    | `kind: horizon`         | A future concept shelf. Not claimable as implementation work.             |
    | `default_candidate`     | When `true`, this stage is a candidate for automatic default selection.   |
    | `coding_claims_enabled` | When `true`, coding work can be claimed against this stage's primitives.  |
    | `order`                 | Numeric sort order used when resolving the default stage automatically.   |

    <Note>
      The `end-state` stage is excluded from the default selection path because it is `kind: horizon` and `default_candidate: false`. Its high `order` value of `9999` does not promote it — stage kind takes precedence over order.
    </Note>

    You also need a stage-level manifest for `m1`. Create `ready/m1/manifest.yaml`:

    ```yaml theme={null}
    schema: "readyroom/product-tree/v1"
    product: "my-product"
    milestone: "m1"
    stage:
      id: "m1"
      title: "M1"
      kind: "normal"
      status: "active"
      order: 10
      default_candidate: true
      coding_claims_enabled: false
    source_model: "file_per_record_ready_yaml"
    source_root: "ready/m1"
    governance_docs:
      root: "../governance/"
      agent_guidelines: "../governance/agent-guidelines.md"
      product_orchestrator_charter: "../governance/product-orchestrator-charter.md"
      product_process: "../governance/product-process.md"
      workspace_authority_and_access: "../governance/workspace-authority-and-access.md"
    ready_standard:
      repository: "https://github.com/seanbhart/ready-standard"
      docs_source: "https://github.com/seanbhart/ready-standard/tree/main/docs"
      skill_package_source: "https://github.com/seanbhart/ready-standard/tree/main/skills"
      templates_source: "https://github.com/seanbhart/ready-standard/tree/main/templates"
    primitive_directories:
      premises: "premises/"
      intents: "intents/"
      standards: "standards/"
      services: "services/"
    flag_directories:
      seed: "flags/seed/"
      delta: "flags/delta/"
      discovery: "flags/discovery/"
    artifact_directories:
      manifest: "artifacts/manifest.yaml"
      samples: "artifacts/samples/"
      resources: "artifacts/resources/"
    ```
  </Step>

  <Step title="Write your first primitive record">
    Primitive records are the heart of a Ready tree. Each `.ready.yml` file describes one unit of product truth. Create your first premise record at `ready/m1/premises/p-001-initial-premise.ready.yml`:

    ```yaml theme={null}
    schema: "readyroom/primitive/v1"
    kind: "primitive"
    id: "p-001"
    type: "premise"
    title: "Users need a single source of truth for product direction"
    milestone: "m1"
    status: "active"
    summary: >
      Product teams lose alignment when requirements, decisions, and context
      are scattered across separate tools. A committed filetree of typed records
      gives every contributor — human or agent — one place to read and update
      what the product is and why it exists.
    fields:
      premise_type: "need"
      statement: "Teams need one authoritative place for product direction that all contributors can read and update."
      evidence_provenance: "Observed across multiple product teams where misalignment led to rework."
      evidence_confidence: "high"
      product_implication: "The product must provide a committed, versioned filetree as the primary record format."
    refs: []
    artifacts: []
    owner_notes: >
      This is the foundational premise for the entire product. All other
      premises and intents should trace back to this one.
    ```

    The fields to know:

    | Field       | Required | Description                                                               |
    | ----------- | -------- | ------------------------------------------------------------------------- |
    | `schema`    | ✅        | Always `readyroom/primitive/v1` for primitive records.                    |
    | `kind`      | ✅        | Always `primitive` for primitive source records.                          |
    | `id`        | ✅        | Stable, unique identifier. Never change this after a record is published. |
    | `type`      | ✅        | One of `premise`, `intent`, `standard`, `service`, or `question_card`.    |
    | `title`     | ✅        | Human-readable name. Refactorable — the `id` is the durable identity.     |
    | `milestone` | ✅        | The stage `id` this primitive belongs to.                                 |
    | `status`    | ✅        | Lifecycle state, e.g. `active`, `draft`, `deprecated`.                    |
    | `summary`   | ✅        | A concise explanation in plain language.                                  |
    | `refs`      | ✅        | Directed references to other primitive `id` values. Use `[]` when empty.  |
    | `artifacts` | ✅        | References to supporting samples or resources. Use `[]` when empty.       |

    <Tip>
      Use a consistent `id` prefix per type — `p-` for premises, `i-` for intents, `st-` for standards, `sv-` for services. Numeric suffixes (`001`, `002`) keep files sorted predictably in any file explorer.
    </Tip>

    <Warning>
      Never commit secrets, API keys, credentials, or personal data inside a `.ready.yml` file. Product trees are often committed to shared or public repositories. Use your project's secrets management system for sensitive values, and reference them by name only if needed.
    </Warning>
  </Step>

  <Step title="Set up governance">
    Governance documents live in `ready/governance/` and define how product truth is created, reviewed, changed, and handed to agents. Create the four standard stubs:

    ```bash theme={null}
    touch ready/governance/agent-guidelines.md
    touch ready/governance/product-orchestrator-charter.md
    touch ready/governance/product-process.md
    touch ready/governance/workspace-authority-and-access.md
    ```

    Populate each file with a minimal header so they are recognisable. Here is a starter for each:

    **`agent-guidelines.md`** — Rules and constraints for any AI agent that reads or writes the product tree. Define what an agent may propose, what it must never modify directly, and how it should signal uncertainty.

    ```markdown theme={null}
    # Agent Guidelines

    Agents may propose changes to primitive records by creating draft `.ready.yml`
    files or opening a pull request. Agents must not modify `ready/manifest.yaml`
    or governance documents without explicit human approval.
    ```

    **`product-orchestrator-charter.md`** — Defines the role of the product orchestrator (human or agent) responsible for maintaining the integrity of the tree and resolving conflicts between competing primitives.

    ```markdown theme={null}
    # Product Orchestrator Charter

    The product orchestrator is responsible for the structural integrity of the
    ready/ tree, stage transitions, and primitive lifecycle decisions.
    ```

    **`product-process.md`** — Documents the team's process for proposing, reviewing, and merging product records — including branching conventions, review requirements, and how `question_card` primitives get resolved.

    ```markdown theme={null}
    # Product Process

    All new primitives begin as a draft pull request. A premise requires one
    product review approval before merging to the default stage.
    ```

    **`workspace-authority-and-access.md`** — Defines who (or which agent role) has authority to read, write, or approve changes to each part of the tree.

    ```markdown theme={null}
    # Workspace Authority and Access

    | Path | Read | Write | Approve |
    |---|---|---|---|
    | ready/manifest.yaml | all | orchestrator | orchestrator |
    | ready/governance/ | all | orchestrator | orchestrator |
    | ready/m1/ | all | contributors | reviewer |
    ```

    <Tip>
      Even stub governance files are valuable from day one. They make the tree's rules explicit to agents and new contributors, and they give you a clear place to evolve process decisions without burying them in chat or wikis.
    </Tip>
  </Step>

  <Step title="Validate your tree">
    Before committing, run a validator or importer against your tree to check structural integrity. A conforming validator will verify that:

    * `ready/manifest.yaml` exists and uses a recognised schema.
    * Every stage listed in the root manifest has a corresponding directory and stage manifest.
    * Every `.ready.yml` file has the required fields (`schema`, `kind`, `id`, `type`, `title`, `milestone`, `status`, `summary`, `refs`, `artifacts`).
    * All `refs` entries point to `id` values that exist in the tree.
    * No primitive `id` is duplicated within a stage.
    * Generated views are marked as generated and not treated as source records.

    If you are using Ready Room, the importer runs automatically when you open the tree and surfaces validation errors in the UI.

    For CI pipelines, you can invoke the validator directly:

    ```bash theme={null}
    # Example — adjust the command for your chosen validator tool
    ready validate --tree ./ready
    ```

    <Note>
      See [Validator Rules](/reference/validator-rules) for the complete list of structural rules a conforming tree must satisfy. The reference includes the exact error codes the importer emits and how to resolve each one.
    </Note>

    <Warning>
      Do not skip validation before merging a pull request that changes `ready/manifest.yaml` or adds a new stage. An invalid stage entry can prevent tools from resolving the default stage correctly and break agent workflows that depend on the stage registry.
    </Warning>

    Once your tree passes validation, commit the whole `ready/` directory and open a pull request. Your product tree is now live in Git and ready to review.

    ```bash theme={null}
    git add ready/
    git commit -m "chore: initialise Ready product tree"
    git push origin main
    ```
  </Step>
</Steps>

## Next steps

You now have a minimal conforming Ready tree. From here you can:

* Add more primitive records (`intents/`, `standards/`, `services/`) using the same `.ready.yml` pattern from Step 3. See [Writing Primitives](/guides/writing-primitives) for field-by-field guidance on each type.
* Explore the full [Directory Layout](/reference/directory-layout) reference to understand every optional directory and file.
* Read the [Product Tree Standard](/concepts/product-tree) to understand stage kinds, default selection logic, and how generated views must be structured.
* Learn about [Flags & Claims](/concepts/flags-and-claims) to understand how `seed`, `delta`, `coverage_gap`, `blocker`, and other flag types signal work-readiness state across the tree.
* Load the [Ready Product Leader Skill Pack](/skills/overview) to give an AI agent structured task modules for reviewing and extending your tree.
* Browse the [Governance & Manifest Templates](/templates/overview) to copy conforming starters for root manifests, stage manifests, and governance documents.
* Connect Ready Room to your repository to get a UI for authoring, reviewing, and compiling your tree.