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

# How to Start a New Ready Product Tree from Scratch

> Bootstrap a Ready product tree for any project — from human docs, an existing codebase, or a discovery conversation — step by step.

Every product tree starts the same way: a `ready/` directory, a root manifest, at least one stage, and a first primitive to anchor everything else. This guide walks you through each step so your tree is valid, reviewable, and ready to grow.

<Steps>
  <Step title="Choose your starting point">
    Pick the approach that fits your project's current state. All three converge on the same product tree structure; they differ only in where you extract initial premises from.

    <CardGroup cols={3}>
      <Card title="Human docs only" icon="file-lines">
        You have a PRD, spec, or design doc. Extract premises and intents from it. Mark them as `inferred` confidence until a product lead confirms them.
      </Card>

      <Card title="Existing codebase" icon="code">
        You have running code but no product tree. Read the code to infer what product promises are already being kept. Start with services and intents, then write premises that justify them.
      </Card>

      <Card title="Discovery conversation" icon="comments">
        You have stakeholder interviews or a discovery session. Use question cards for anything unresolved and write premises only for what was actually agreed.
      </Card>
    </CardGroup>

    Whichever path you take, resist writing intents until you have at least one premise that justifies them.
  </Step>

  <Step title="Create the ready/ directory structure">
    Make the root `ready/` directory and its required subdirectories. The layout below matches the Ready Standard directory layout.

    ```bash theme={null}
    mkdir -p ready/governance
    mkdir -p ready/end-state
    mkdir -p ready/m1/premises ready/m1/intents ready/m1/standards
    mkdir -p ready/m1/services ready/m1/flags/seed ready/m1/flags/delta
    mkdir -p ready/m1/flags/discovery
    mkdir -p ready/m1/artifacts/samples ready/m1/artifacts/resources
    mkdir -p ready/m1/artifacts/snippets ready/m1/artifacts/designs
    mkdir -p ready/m1/artifacts/manifests
    touch ready/README.md ready/m1/README.md ready/end-state/README.md
    ```

    <Note>
      The top-level plural Markdown files (`premises.md`, `intents.md`, etc.) inside each stage directory are navigation indexes, not primitive sources. Primitive source records are `.ready.yml` files inside the subdirectories.
    </Note>
  </Step>

  <Step title="Populate ready/manifest.yaml">
    The root manifest owns the stage registry. Copy the template below and replace every `{{placeholder}}` with your project's values.

    ```yaml theme={null}
    schema: "readyroom/product-tree-root/v1"
    product: "my-product"           # short stable id, no spaces
    source_root: "ready"
    default_stage: "m1"             # must match an id in stages list
    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
    ```

    Every stage entry needs all nine fields: `id`, `title`, `path`, `manifest`, `kind`, `status`, `order`, `default_candidate`, and `coding_claims_enabled`. Tools rely on these fields — do not infer meaning from directory names or sort order.
  </Step>

  <Step title="Create the first stage manifest">
    Each stage directory needs its own `manifest.yaml`. 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"
    primitive_directories:
      premises: "premises/"
      intents: "intents/"
      standards: "standards/"
      services: "services/"
    flag_directories:
      seed: "flags/seed/"
      delta: "flags/delta/"
      discovery: "flags/discovery/"
    artifact_directories:
      index: "artifacts.md"
      manifest: "artifacts/manifest.yaml"
      samples: "artifacts/samples/"
      resources: "artifacts/resources/"
      snippets: "artifacts/snippets/"
      designs: "artifacts/designs/"
      manifests: "artifacts/manifests/"
    ```

    <Tip>
      The field name on stage manifests is `milestone` for the stage id — this is the v1 field name. The root manifest uses `stages`. Both refer to the same concept.
    </Tip>
  </Step>

  <Step title="Set up ready/governance/">
    Governance documents constrain how product truth is created, changed, approved, and handed to agents. Create four files under `ready/governance/`:

    | File                                | Purpose                                                        |
    | ----------------------------------- | -------------------------------------------------------------- |
    | `agent-guidelines.md`               | Rules for product and coding agents working in this tree       |
    | `product-orchestrator-charter.md`   | Authority and scope of the product orchestrator role           |
    | `product-process.md`                | How your team moves primitives from draft to active            |
    | `workspace-authority-and-access.md` | Who can approve what, and which credentials/environments exist |

    Start with stubs if you do not have full content yet. These files are Markdown, not primitives, and they are referenced by path from stage manifests.
  </Step>

  <Step title="Write the first premise primitive">
    Anchor the tree with at least one premise before adding intents. Create `ready/m1/premises/p-001-core-problem.ready.yml`:

    ```yaml theme={null}
    schema: readyroom/primitive/v1
    kind: primitive
    id: P-001
    type: premise
    title: Core problem this product solves
    milestone: m1
    status: active
    summary: >
      One or two sentences stating the observable problem or opportunity
      that justifies building this product.
    fields:
      evidence_confidence: medium   # low | medium | high
      evidence_provenance: "Product lead interview, 2024-01-15"
      product_implication: >
        If this premise is true, the product must be able to do X.
        If it is false, Y feature is unnecessary.
    refs: []
    artifacts: []
    owner_notes:
      - "Confidence will rise to high once user research confirms session drop data."
    ```

    <Warning>
      A premise inferred only from a document should start at `evidence_confidence: low` or `medium`. Raise it to `high` only after a product lead or stakeholder explicitly confirms it.
    </Warning>
  </Step>

  <Step title="Run a validator pass">
    Before adding more primitives, validate what you have. Run your team's validator (or the Ready Room built-in check) against the tree:

    ```bash theme={null}
    # Example — adapt to your toolchain
    ready validate ready/
    ```

    Fix any schema errors before continuing. A clean validator pass on a minimal tree is far easier to debug than one on a hundred files.

    <Note>
      At minimum, check that: `schema` is present on every `.ready.yml` file, `id` values are unique across the stage, `milestone` matches the stage id in the root manifest, and every `refs` entry uses an approved `role`.
    </Note>
  </Step>

  <Step title="Handle uncertainty correctly">
    You will hit gaps immediately. Use these patterns instead of prose notes:

    **Unresolved questions → question cards.** Create a `question_card` primitive for anything that would change the shape of an intent or premise if answered differently.

    ```yaml theme={null}
    schema: readyroom/primitive/v1
    kind: primitive
    id: QC-001
    type: question_card
    title: Who is the primary actor for the billing flow?
    milestone: m1
    status: active
    summary: >
      It is unclear whether billing is self-serve by the end user
      or managed by an admin on their behalf.
    fields:
      resolution_path: "Schedule a 30-min session with product lead."
      blocking: ["I-004"]
    refs: []
    artifacts: []
    owner_notes: []
    ```

    **Low confidence → `evidence_confidence: low` field.** Do not write confident-sounding summaries for premises you are guessing at. Mark the confidence and move on.

    **Unknowns in intents → `status: draft`.** A draft intent signals that the promise is not yet accepted product truth. Keep it draft until the question card is resolved.
  </Step>
</Steps>

<Tip>
  Commit your tree after each step. Git is how you review and audit product decisions. Small commits make the diff meaningful when a premise changes.
</Tip>