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

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]
•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
•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

bash

# Stage specific files
git add <file1> <file2> <file3>

# Verify staged changes before commit
git diff --cached

PAW Artifact Staging

Before staging .paw/ files, check if artifact tracking is disabled:

bash

# Check for .gitignore in work directory
if [ -f ".paw/work/<feature-slug>/.gitignore" ]; then
  # Tracking disabled - skip .paw/ artifacts
  git add <non-paw-files-only>
else
  # Tracking enabled - stage all changed files
  git add <all-changed-files>
fi

Why: Users can disable artifact tracking via .gitignore. Respect this by checking before staging .paw/ files.

Branch Verification

Before every commit, verify you're on the expected branch:

bash

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

Pre-Commit Checklist

•✓ Verify current branch matches expected pattern
•✓ Stage only related files (no git add .)
•✓ Check .paw/work/<slug>/.gitignore before staging .paw/ artifacts
•✓ 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

bash

# 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:

code

Phase <N>: <one-sentence objective>

🐾 Generated with [PAW](https://github.com/lossyrob/phased-agent-workflow)

Complex phases:

code

## 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 create output
•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:

code

**🐾 PAW 🤖:**

[What was changed and commit hash reference]