Skip to main content
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

ready/governance/

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

Ready standard package

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

ready/**/artifacts/

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

​
The decision rule

When you are unsure where a file belongs, apply these questions in order:
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 packageDoes it help explain, test, prove, or illustrate a primitive? → ready/**/artifacts/
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: 
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 operationUse it for
BranchHold product experiments, milestone alternatives, or implementation plans.
MergeRecord accepted product truth — merges are decisions.
ForkExplore an alternative product direction without polluting the main tree.
ReviewInspect and approve primitive edits before they become canonical.
HistoryMaintain 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
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.

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