How to Version and Review a Ready Product Tree with Git

Ready Standard is built for Git from the ground up. Because every primitive is a plain YAML file with a distinct extension, the same branching, review, merge, and fork tools your team uses for code work identically for product truth. A pull request reviewing a changed intent is structurally no different from a pull request reviewing a changed interface — the diff is meaningful, the history is auditable, and the merge represents a deliberate decision.

What Git handles

Git is the backbone of the product tree. Use it for all of the following:

Branching product alternatives

Create a branch to explore a different scope, actor, or product approach without affecting the main product truth. Merge if it is accepted; close the branch if it is not.

Reviewing primitive edits

Open a pull request when a primitive changes. Reviewers see exactly which fields changed and can comment on specific lines — the same workflow as a code review.

Merging accepted product truth

A merge into the main branch means the team has accepted the change as product truth. Merges are the authoritative record of decisions.

Forking for experiments

Fork the tree to explore a radically different product direction or to run a spike. Forks can be merged back, used as references, or discarded.

Comparing implementation plans

Use git diff between branches to compare two milestone plans or two versions of an intent side by side.

Auditable decision history

Every accepted primitive edit lives in Git history with author, timestamp, and message. You can reconstruct the product at any point in time.

What the app layer adds

The Ready Room app layers workflow on top of the Git-backed tree. It does not replace Git; it interprets the tree and manages the Git operations for teams that want a UI.

App responsibility	Description
Compiled views	Interprets the tree for PM, developer, designer, and customer views
Git management	Manages pulls, rebases, commits, and branches on your behalf
Local agents	Runs product agents and coding handoff locally
Portal targets	Displays local or remote portal targets for publishing views
Commit frequency	Configurable commit cadence to match team latency preferences

Your tree is valid without the app. If you prefer to use Git directly, every workflow in this guide works with standard Git commands.

Branch conventions

Use feature branches for product experiments and decisions in progress. Merge into the main branch only when a change is accepted product truth.

# Start a new product experiment
git checkout -b product/onboarding-skip-step2

# Work on primitives, then open a PR
git add ready/m1/intents/i-001-onboarding.ready.yml
git commit -m "intent(I-001): scope onboarding to 2 steps — skip step 2 experiment"
git push origin product/onboarding-skip-step2

# After acceptance, merge to main
git checkout main
git merge product/onboarding-skip-step2

Commit messages that name the primitive id and type of change (intent(I-001): ..., premise(P-003): ...) make the log scannable. A reader can reconstruct product history from commit messages alone.

What NOT to commit to Git

Local cache is not product truth and must never be committed to the product tree repository.

Do not commit any of the following:

Chats with agents — these are transient and private
Search indexes — these are derived and regeneratable
Scratch run context — intermediate work before a decision is made
Raw provider transcripts — the raw output of AI sessions before review
Raw local process logs — generated by tools, not reviewed product content
Temporary evidence bundles — pre-review artifacts that have not been promoted

Add a .gitignore entry for your local cache directory to prevent accidental commits:

# .gitignore
.ready-cache/
.local-cache/
*.scratch.md
*.raw-transcript.txt

When local cache becomes product truth

Local cache is ephemeral by design. When a conversation, agent run, or scratch session produces something durable, it does not go directly into Git. Instead, the app or product agent promotes it into the right primitive type:

Cache content	Promoted to
Agreed product decision from a chat	Premise or intent primitive
Resolved question from a session	Primitive edit + question card removal
Evidence from a discovery run	Evidence summary or artifact ref
Coding agent output	Flag status update + completion evidence artifact

The promotion step is the moment of review. Only reviewed, accepted content enters the committed tree.

Sensitive and bulky material

The committed product tree stores references to sensitive or bulky content — not the content itself.

# ✅ Store the credential location, not the credential
fields:
  credential_location: "1Password vault > Engineering > Auth Service API Keys"

# ❌ Never commit this
fields:
  api_key: "sk-live-abc123xyz..."

# ✅ Store an artifact ref for a large binary
artifacts:
  - id: DS-001
    path: "ready/m1/artifacts/designs/DS-001-onboarding-flow.pdf"

# ❌ Do not inline binary content or large base64 blobs

Do not commit secrets, API keys, tokens, passwords, or any credential values to the product tree. Store the location (vault path, environment variable name, secret manager key) instead.

Items to store as refs rather than raw content:

Type	What to store instead
Secrets and credentials	Vault path or environment variable name
Source code excerpts	Snippet artifact ref + path
Diffs and patches	Branch name or commit hash
Large binary files	Artifact ref with path and hash
Raw logs	Evidence summary artifact ref

Small sanitized samples are allowed when they are intentionally product fixtures — for example, a 10-row JSON file that represents realistic input data for an acceptance test. These should be explicitly marked privacy: sanitized_fixture in the artifact manifest.

PR review as product review

Treat primitive edits in a pull request the same way you treat code changes. The diff is the product record.

# Example: a meaningful primitive diff in a PR

- scope: Steps 1–3 of the web and iOS onboarding funnel.
+ scope: Steps 1–2 of the web and iOS onboarding funnel.
+         Step 3 (avatar upload) is deferred to post-signup.

- non_scope: Avatar upload during onboarding.
+ non_scope: Avatar upload during onboarding is now in scope for M2.

A reviewer who understands the product can evaluate this diff the same way an engineer reviews an interface change. The history of who merged what, and when, is the auditable record of accepted product decisions.

Because primitive ids are stable and paths are refactorable, a rename or reorganization commit produces a near-zero-content diff. This makes structural housekeeping easy to review and keeps meaningful product changes distinct in the log.

Introduction

Core Concepts

Guides

Skills & Templates

How to Version and Review a Ready Product Tree with Git

What Git handles

Branching product alternatives

Reviewing primitive edits

Merging accepted product truth

Forking for experiments

Comparing implementation plans

Auditable decision history

What the app layer adds

Branch conventions

What NOT to commit to Git

When local cache becomes product truth

Sensitive and bulky material

PR review as product review

​What Git handles

Branching product alternatives

Reviewing primitive edits

Merging accepted product truth

Forking for experiments

Comparing implementation plans

Auditable decision history

​What the app layer adds

​Branch conventions

​What NOT to commit to Git

​When local cache becomes product truth

​Sensitive and bulky material

​PR review as product review

What Git handles

What the app layer adds

Branch conventions

What NOT to commit to Git

When local cache becomes product truth

Sensitive and bulky material

PR review as product review