Governance documents are project-specific files stored in ready/governance/ that constrain how product work happens for your project. They are the first thing product agents load, and they take precedence over everything except explicit user instruction. A governance document that still contains {{PLACEHOLDER}} values is a template — it has no authority until you fill it in, review it, and commit it.
The four governance templates cover the distinct concerns you need to resolve before agents work reliably in your project.
All governance documents go in ready/governance/. Do not place them in artifact directories, under a milestone path, or anywhere outside the governance root. The governance manifest at ready/governance/manifest.yaml indexes them for agent discovery.
The four governance templates
agent-guidelines
orchestrator-charter
product-process
workspace-authority
agent-guidelines.template.md
Copy to: ready/governance/agent-guidelines.mdPurpose: Governs product-agent behavior for your project. Every product agent that runs in this project reads this file and follows its rules. It defines which sources rank higher than others, what agents may and may not do, and any project-specific operating notes.Key sections:Source Hierarchy — five levels, in priority order:
ready/governance/product-process.mdready/governance/product-orchestrator-charter.mdready/governance/workspace-authority-and-access.md- Milestone primitives, services, flags, and artifacts
- User chat and local cache — as evidence only, not automatic truth
Operating Rules — non-negotiable behaviors agents must follow:
- Treat docs, code, chat, mockups, generated samples, and model output as evidence, not automatic product truth.
- Preserve uncertainty as question cards, flags, low confidence, or blocked service readiness.
- Do not claim implementation is ready while required samples, designs, accounts, credentials, environments, or Completion Proof are missing.
- Never store secrets, raw private data, or sensitive logs in the Ready tree.
- Record loaded governance docs, standard resources, and hashes in agent context manifests when product agents run.
Placeholders to fill in:| Placeholder | What to replace it with |
|---|
{{PRODUCT_ID}} | Your project’s unique product identifier (e.g., acme-payments) |
{{PROJECT_SPECIFIC_AGENT_NOTES}} | Any project-specific rules, constraints, or context agents need — or remove the section if none apply |
# Agent Guidelines
Project: `acme-payments`
## Source Hierarchy
1. `ready/governance/product-process.md`
2. `ready/governance/product-orchestrator-charter.md`
3. `ready/governance/workspace-authority-and-access.md`
4. Milestone primitives, services, flags, and artifacts.
5. User chat and local cache as evidence only.
## Operating Rules
- Treat docs, code, chat, mockups, generated samples, and model
output as evidence, not automatic product truth.
- Preserve uncertainty as question cards, flags, low confidence,
or blocked service readiness.
...
## Project Notes
Agents must not create or modify Stripe webhook configurations
without explicit approval from the technical authority owner.
product-orchestrator-charter.template.md
Copy to: ready/governance/product-orchestrator-charter.mdPurpose: Defines the product-orchestrator agent’s authority, scope, and responsibilities for your project. This is the standing context the orchestrator loads on every run. If it conflicts with product-process.md, the product process wins.Key sections:Mission — the orchestrator’s goal: help the user create, maintain, and review a Ready product tree that is clear enough for coding agents to build from without avoidable blockers.Authority — records who owns product, technical, merge/release, and one-way-door decisions.Context Loading — instructs the agent to load only what the task needs: this charter, relevant process sections, relevant primitives and artifacts, relevant Ready standard resources. The agent must not load every document into every run.Delegation — instructs the orchestrator to use subagents for bounded review, assigning distinct roles (psychological, physical, logical, evidence/resource, design, access/handoff) instead of duplicating the same work.Completion — a product-agent run is complete only when it records findings, proposed edits or an explicit no-op rationale, evidence refs, uncertainty, and follow-up questions.Placeholders to fill in:| Placeholder | What to replace it with |
|---|
{{PRODUCT_ID}} | Your project’s unique product identifier |
{{PRODUCT_AUTHORITY_OWNER}} | Name or role of the person with final product decisions |
{{TECHNICAL_AUTHORITY_OWNER}} | Name or role of the person with final technical decisions |
{{MERGE_RELEASE_AUTHORITY_OWNER}} | Name or role responsible for merge and release approvals |
{{ONE_WAY_DOOR_APPROVAL_RULE}} | Rule for actions that cannot be reversed (e.g., “explicit approval from product authority owner”) |
# Product Orchestrator Charter
Project: `acme-payments`
## Authority
- Product authority owner: Jane Smith (Head of Product)
- Technical authority owner: Alex Chen (Engineering Lead)
- Merge/release authority owner: Alex Chen
- One-way-door actions require: explicit approval from
product authority owner and technical authority owner
product-process.template.md
Copy to: ready/governance/product-process.mdPurpose: Documents the product decision-making process for your project — how primitives get created, how evidence becomes approved truth, how work reaches coding agents, and who reviews what. This is the highest-priority governance document; it overrides the orchestrator charter when they conflict.Key sections:Source Of Truth — durable product truth lives in ready/ as .ready.yml files. Generated views compile from primitives. Chat and local cache are evidence until promoted into the tree.Discovery — start with the product-user problem. Capture premises before solutioning. Preserve unresolved ambiguity as question cards or discovery flags.Evidence And Resources — every build-critical intent or service should have sample data, expected outputs, public resources, user-only asks, or explicit blockers.Access And Services — every required service names account owner, access state, credential location reference, setup path, verification check, simulation policy, and failure modes. Raw secrets are never committed.Design And Artifacts — UI work needs enough mockups, flows, states, copy, assets, and component snippets for coding agents to implement faithfully.Coding Handoff — seed and delta flags become claimable only when scope, non-scope, required standards, services, artifacts, setup, samples, expected outputs, Completion Proof, and blocker policy are clear.Review — product agents close flags only after proof passes. Coding agents attach evidence and request review; they do not decide product completion.Placeholder to fill in:| Placeholder | What to replace it with |
|---|
{{PRODUCT_ID}} | Your project’s unique product identifier |
workspace-authority-and-access.template.md
Copy to: ready/governance/workspace-authority-and-access.mdPurpose: Records project-specific authority hierarchy and access policy. Agents and coding agents consult this file to determine what they may do without asking for permission and what requires explicit approval.Key sections:Owners — records the four authority roles.Allowed Actions — separates reversible two-way-door actions agents may take independently from one-way-door actions that require explicit approval. Destructive file changes, credential rotation, shared-state changes, branch protection changes, and deployments are always one-way-door actions regardless of project-specific additions.Local Access — defines which file paths agents may touch, what clean-tree policy applies before making changes, and which CLI tools are permitted.Secret Handling — reaffirms that raw secrets never go in ready/. Only safe secret-location references are stored: variable names, storage system, owner, required scope, setup status, and verification command.Placeholders to fill in:| Placeholder | What to replace it with |
|---|
{{PRODUCT_ID}} | Your project’s unique product identifier |
{{PRODUCT_AUTHORITY_OWNER}} | Product authority owner name or role |
{{TECHNICAL_AUTHORITY_OWNER}} | Technical authority owner name or role |
{{REPOSITORY_AUTHORITY_OWNER}} | Repository authority owner name or role |
{{MERGE_RELEASE_AUTHORITY_OWNER}} | Merge/release authority owner name or role |
{{REVERSIBLE_ACTION}} | List of reversible actions agents may perform independently |
{{PROJECT_SPECIFIC_ONE_WAY_ACTION}} | Any project-specific one-way-door actions to add to the list |
{{ALLOWED_LOCAL_PATHS}} | File paths agents are permitted to read or write locally |
{{CLEAN_TREE_POLICY}} | Required git state before agents make changes (e.g., clean working tree required) |
{{ALLOWED_CLI_TOOLS}} | CLI tools agents are permitted to invoke |
# Workspace Authority And Access
Project: `acme-payments`
## Owners
- Product authority: Jane Smith
- Technical authority: Alex Chen
- Repository authority: Alex Chen
- Merge/release authority: Alex Chen
## Allowed Actions
Two-way-door actions product agents may perform without approval:
- Create or edit primitives, flags, and artifacts in ready/
- Generate fixture data under ready/m1/artifacts/samples/
One-way-door actions requiring explicit approval:
- destructive file or data changes
- credential creation or rotation
- shared-state changes
- repo branch protection, merge, release, or deployment changes
- modifying Stripe webhook or payment-provider configuration
## Secret Handling
Never store raw secrets in ready/. Record safe
secret-location references only.
Filling in governance templates step by step
- Copy all four template files into
ready/governance/ in your project.
- Start with
product-process.md — it is the highest-authority document and shapes how you fill in the others.
- Fill in
workspace-authority-and-access.md next — decide authority owners and allowed actions before writing the charter.
- Fill in
product-orchestrator-charter.md using the authority owners you just defined.
- Fill in
agent-guidelines.md last — add any project-specific notes that extend the standard operating rules.
- Copy the governance manifest template into
ready/governance/manifest.yaml and verify the four document paths are correct.
- Commit all five files (four governance docs + governance manifest) together. Agents should never find a partial governance directory.
Remove placeholder lines entirely rather than leaving them blank or with filler text like “TBD”. A placeholder left in a committed file tells agents the document has not been reviewed — they may treat it as draft rather than authority.
