Skip to main content
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 responsibilityDescription
Compiled viewsInterprets the tree for PM, developer, designer, and customer views
Git managementManages pulls, rebases, commits, and branches on your behalf
Local agentsRuns product agents and coding handoff locally
Portal targetsDisplays local or remote portal targets for publishing views
Commit frequencyConfigurable 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 contentPromoted to
Agreed product decision from a chatPremise or intent primitive
Resolved question from a sessionPrimitive edit + question card removal
Evidence from a discovery runEvidence summary or artifact ref
Coding agent outputFlag 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:
TypeWhat to store instead
Secrets and credentialsVault path or environment variable name
Source code excerptsSnippet artifact ref + path
Diffs and patchesBranch name or commit hash
Large binary filesArtifact ref with path and hash
Raw logsEvidence 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.