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

# Governance Documents, Standard Resources, and Artifacts

> Project governance, the Ready standard package, and artifact directories each serve a distinct role in constraining and supporting product work.

Governance documents and Ready standard resources are first-class product-tree records, not afterthoughts. Knowing where each kind of file belongs keeps your tree unambiguous: agents know which rules are binding, which templates are reusable, and which material is supporting evidence. The three storage locations below are mutually exclusive by design — placing a file in the wrong location causes tools and agents to misread its authority.

## Three storage locations

<CardGroup cols={1}>
  <Card title="ready/governance/" icon="shield-halved">
    **Project-specific constraints on how product work happens.**

    Store files here when they tell agents or contributors what authority they have, what project-specific process they must follow, or what project-specific standard wins during a conflict. Typical contents:

    * Agent behavior guidelines
    * Product-orchestrator charters
    * Product process documentation
    * Workspace authority and access policies
  </Card>

  <Card title="Ready standard package" icon="box-open">
    **Project-agnostic, reusable Ready resources.**

    Store files here when they define reusable Ready procedure or provide starter templates that any project can adopt. Typical contents:

    * Ready Skill packages
    * Product task-skill modules
    * Governance templates
    * Manifest templates
    * Primitive templates
  </Card>

  <Card title="ready/**/artifacts/" icon="paperclip">
    **Supporting material attached to primitives, flags, proof, generated views, or handoff.**

    Store files here when they help explain, test, prove, or illustrate a primitive. Typical contents:

    * Sample data
    * Code snippets
    * Design assets
    * Portal manifests
    * Screenshots
    * Handoff notes
  </Card>
</CardGroup>

## The decision rule

When you are unsure where a file belongs, apply these questions in order:

<Note>
  **Does it tell an agent what authority it has, what project-specific process to follow, or what project-specific standard wins?** → `ready/governance/`

  **Does it define a reusable Ready procedure or a starter template for other projects?** → Ready standard package

  **Does it help explain, test, prove, or illustrate a primitive?** → `ready/**/artifacts/`
</Note>

A file that belongs in the standard package should never live in a project's governance directory. Governance is project-scoped and binding; the standard package is project-agnostic and adoptable. Mixing them makes agent authority ambiguous.

## Runtime use

When an agent runs, its context manifest should record every governance document and standard package resource it loaded for that run:

```yaml theme={null}
context_manifest:
  governance_docs:
    - path: ready/governance/agent-guidelines.md
      version: "1.2.0"
      source_ref: "a3f9c12"
      hash: "sha256:4e2a1b..."
  standard_resources:
    - path: skill-packages/product-orchestrator/v2
      version: "2.0.1"
      source_ref: "7d83e44"
      hash: "sha256:9c7f3d..."
```

Recording versions, source refs, and hashes keeps agent behavior fully auditable without treating private chats, local scratchpads, or generated work packages as governance.

## Git and local cache

The product tree is designed for Git. Use branches, merges, and forks to manage the full lifecycle of product truth:

| Git operation | Use it for                                                                 |
| ------------- | -------------------------------------------------------------------------- |
| Branch        | Hold product experiments, milestone alternatives, or implementation plans. |
| Merge         | Record accepted product truth — merges are decisions.                      |
| Fork          | Explore an alternative product direction without polluting the main tree.  |
| Review        | Inspect and approve primitive edits before they become canonical.          |
| History       | Maintain an auditable record of every accepted decision.                   |

Local cache stores useful private or transient material that must never be committed:

* Chats with agents
* Search indexes
* Scratch run context
* Raw provider transcripts
* Raw local process logs
* Temporary evidence bundles

<Warning>
  Local cache is **not committed**. When a conversation or agent run produces durable product truth, the app or product agent promotes that truth into a primitive, flag, evidence summary, or artifact ref before it enters the tree.
</Warning>

## Sensitive and bulky material

Keep the committed tree lean and clean. Store refs instead of embedding any of the following directly in primitives or governance files:

* **Secrets** — API keys, tokens, credentials. Store refs to your secrets manager.
* **Source excerpts and diffs** — Reference the commit or PR instead.
* **Raw logs** — Summarize findings and store the ref; do not paste log output.
* **Large binary payloads** — Reference the asset by URL or artifact path.

<Tip>
  Small, sanitized samples are allowed when they are intentionally product fixtures — for example, a canonical JSON response shape that an intent's test suite validates against. Keep them in `artifacts/` and reference them by path from the primitive.
</Tip>