tomevault-io Git Operations
Branch Naming Conventions
| Branch Type | Pattern | Example |
|---|---|---|
| Phase branch | <target>_phase[N] |
feature/auth-system_phase1 |
| Multi-phase | <target>_phase[M-N] |
feature/auth-system_phase1-3 |
| Planning branch | <target>_plan |
feature/auth-system_plan |
| Docs branch | <target>_docs |
feature/auth-system_docs |
Target branch is the feature branch from WorkflowContext.md (e.g., feature/auth-system).
Execution Checkout Contract
- Read
WorkflowContext.mdbefore any git mutation. - Treat
Repository Identityas literal<normalized-origin-slug>@<root-commit-sha>metadata fromWorkflowContext.md. - Treat
Execution Bindingas literalworktree:<work-id>:<target-branch>metadata fromWorkflowContext.md. - Compare those values literally; do not invent alternate formats.
- If
Execution Mode: worktree, continue only when the intended execution checkout directory can be proven fromWorkflowContext.mdmetadata plus the repo/branch/worktree state for that checkout. The session cwd may differ from the execution checkout. - When the session cwd differs, all git operations MUST execute in the proven execution checkout directory, either by using path-scoped git commands (for example,
git -C <execution-checkout-path> ...) or by switching the process cwd there. Do not use the caller checkout as proof or fallback. - The caller checkout must never be mutated.
- If the execution checkout is ambiguous or cannot be proven from this session, STOP and report recovery guidance instead of guessing.
Branch-State Matrix
| Execution Mode / Strategy | Caller checkout | Execution checkout |
|---|---|---|
current-checkout |
Existing behavior; caller checkout is the execution checkout | Target Branch and any planning/phase/docs branches behave as they do today |
worktree + local |
Branch, HEAD, upstream, and status remain unchanged for the full run |
Starts on explicit Target Branch; all local-strategy commits and pushes happen here |
worktree + prs |
Branch, HEAD, upstream, and status remain unchanged for the full run |
Starts on explicit Target Branch; planning/phase/docs branches are created, pushed, and reviewed from here |
Strategy-Based Branching Logic
PRs Strategy
Create intermediate branches for each workflow stage; push and create PRs for review.
Phase work:
- Check current branch:
git branch --show-current - If not on correct phase branch:
- Checkout target branch:
git checkout <target> - Set upstream if not set:
git branch --set-upstream-to=<remote>/<target> - Pull latest:
git pull - Create phase branch from target:
git checkout -b <target>_phase[N]
- Checkout target branch:
- Verify:
git branch --show-current - Implement on phase branch, commit locally
- Push:
git push -u <remote> <target>_phase[N] - Create PR:
<target>_phase[N]→<target>
Planning work:
- Checkout target branch:
git checkout <target> - Set upstream if not set:
git branch --set-upstream-to=<remote>/<target> - Pull latest:
git pull - Create planning branch:
git checkout -b <target>_plan - Commit planning artifacts
- Push:
git push -u <remote> <target>_plan - Create PR:
<target>_plan→<target>
Docs work:
- Checkout target branch:
git checkout <target> - Set upstream if not set:
git branch --set-upstream-to=<remote>/<target> - Pull latest:
git pull - Create docs branch:
git checkout -b <target>_docs - Commit documentation
- Push:
git push -u <remote> <target>_docs - Create PR:
<target>_docs→<target>
Local Strategy
Work directly on target branch; no intermediate branches or PRs between stages.
All work:
- Check current branch:
git branch --show-current - If not on target branch:
- Checkout target:
git checkout <target> - Set upstream if not set:
git branch --set-upstream-to=<remote>/<target> - Pull latest:
git pull
- Checkout target:
- Verify:
git branch --show-current - Implement, commit to target branch
- Push:
git push <remote> <target> - Skip intermediate PR creation
Selective Staging Discipline
CRITICAL: Never use git add . or git add -A. Always stage files explicitly.
Standard Staging
# Stage specific files
git add <file1> <file2> <file3>
# Verify staged changes before commit
git diff --cached
PAW Artifact Staging
Before staging .paw/ files, determine the artifact lifecycle mode:
- Check WorkflowContext.md for
Artifact Lifecycle:field - If absent, check for legacy fields:
artifact_tracking: enabledortrack_artifacts: true→commit-and-clean;disabled/false→never-commit - If absent, check for
.paw/work/<feature-slug>/.gitignore— if exists with*: treat asnever-commit - If none: default to
commit-and-clean
# commit-and-clean or commit-and-persist: stage .paw/ files
# (excluding local-only scratch ignore markers)
git add <all-changed-files-except-scratch-ignore-markers>
# never-commit: skip .paw/ files
git add <non-paw-files-only>
Why: Artifact lifecycle mode controls whether .paw/ files are committed. commit-and-clean and commit-and-persist stage artifacts during development; never-commit keeps them local-only.
Scratch ignore markers are always local-only:
- Treat
.gitignorefiles created to keep workflow/scratch areas local-only as lifecycle markers, not repository content - Examples:
.paw/work/<feature-slug>/.gitignore,.paw/work/<feature-slug>/planning/.gitignore,.paw/work/<feature-slug>/reviews/.gitignore, and nested review output.gitignorefiles - Do NOT stage or commit them in normal commits
- If any scratch ignore marker appears in
git ls-files,git diff --cached --name-only, or the planned PR diff, remove it from the index before committing (for examplegit rm --cached <marker-path>)
Branch Verification
Before every commit, verify you're on the expected branch:
# Get current branch
git branch --show-current
# Expected patterns by work type:
# - Phase work (prs): *_phase[N] or *_phase[M-N]
# - Planning (prs): *_plan
# - Docs (prs): *_docs
# - Any work (local): <target> (no suffix)
If on wrong branch: STOP immediately. Do not commit. Switch to correct branch first.
Worktree mode note: The "current branch" above means the branch in the established execution checkout, not the caller checkout that launched PAW.
Pre-Commit Checklist
- ✓ Verify current branch matches expected pattern
- ✓ Stage only related files (no
git add .) - ✓ Check artifact lifecycle mode before staging
.paw/artifacts - ✓ Verify no scratch ignore markers are staged or tracked
- ✓ Review staged changes:
git diff --cached - ✓ Commit with descriptive message
Phase PR Creation
After implementation review passes, create Phase PR (PRs strategy only).
Push and Create PR
# 1. Verify on phase branch
git branch --show-current # Should be <target>_phase[N]
# 2. Push branch
git push -u <remote> <target>_phase[N]
# 3. Create PR via gh CLI
gh pr create \
--base <target> \
--head <target>_phase[N] \
--title "[<Work Title>] Phase <N>: <description>" \
--body "<PR body>"
PR Title Format
[<Work Title>] Phase <N>: <one-sentence description>
Example: [Auth System] Phase 1: Add JWT token validation
PR Body Scaling
Simple phases:
Phase <N>: <one-sentence objective>
🐾 Generated with [PAW](https://github.com/lossyrob/phased-agent-workflow)
Complex phases:
## Summary
<Key changes and approach>
## Design Decisions
<Noteworthy decisions made>
## Reviewer Notes
<Items for reviewer attention>
🐾 Generated with [PAW](https://github.com/lossyrob/phased-agent-workflow)
Post-PR Actions
- Capture PR URL from
gh pr createoutput - Update ImplementationPlan.md with PR link in phase notes
- Report PR URL to user
PR Update Policy
After a PR is opened, post progress updates as PR comments, not modifications to the PR body. PR body modifications require explicit user request.
Reply Format (PR Comments)
When replying to review comments:
**🐾 PAW 🤖:**
[What was changed and commit hash reference]
Converted and distributed by TomeVault — claim your Tome and manage your conversions.