---

name: commit description: Standardized git commit, push, and PR creation workflow. triggers:

• commit
• push
• commit-push-pr allowed-tools: Bash, Read, Glob model: opus user-invocable: true argument-hint: "[type] [message]"

---

Commit Workflow

Working Tree

!git status --short 2>/dev/null !git diff --stat HEAD 2>/dev/null | tail -5 !git log --oneline -5 2>/dev/null

Quick Commit

# 1. Check what changed
git status --short
git diff --stat

# 2. Stage specific files (prefer targeted adds over git add -A)
git add src/components/new-feature.tsx src/lib/utils.ts

# 3. Commit with conventional format
git commit -m "feat: add playlist drag-drop reorder"

Conventional Commits (Required)

<type>: <short description>

[optional body]

Type	When
feat	New feature
fix	Bug fix
refactor	Code restructure, no behavior change
chore	Dependencies, config, tooling
docs	Documentation only
test	Add or update tests
perf	Performance improvement

Rules:

• Subject line < 70 chars
• Imperative mood: "add" not "added"
• No period at end
• Body explains WHY, not WHAT
• Include story ID when available: feat(S13-001): add playlist UI

Commit + Push

git add <files>
git commit -m "feat: description"
git push origin HEAD

Branch Strategy

Check before branching:

# Solo project? (1 contributor, no branch protection)
CONTRIBUTORS=$(git shortlog -sn --all 2>/dev/null | wc -l)
HAS_REMOTE=$(git remote 2>/dev/null | head -1)

• Solo project (1 contributor or no remote): commit directly to main — branching adds ceremony with zero value.
• Team project (2+ contributors or CI/branch protection): create a feature branch from main.

# Only branch for team projects
if [ "$CONTRIBUTORS" -gt 1 ] && [ -n "$HAS_REMOTE" ]; then
  BRANCH=$(git branch --show-current)
  if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
    git checkout -b feat/[descriptive-name]
  fi
fi

Post-Commit Quick Check

After every commit, run a 5-second sanity check:

npm run build 2>&1 | tail -3
# If dev server running, check for console errors
curl -s http://localhost:3000 > /dev/null 2>&1 && agent-browser open http://localhost:3000 && agent-browser snapshot -i

If errors found, fix immediately and amend the commit.

Full PR Flow (commit-push-pr)

# 1. Create branch if on main
BRANCH=$(git branch --show-current)
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
  git checkout -b feat/[descriptive-name]
fi

# 2. Stage and commit
git add <files>
git commit -m "feat: add playlist UI with drag-drop"

# 3. Push
git push -u origin HEAD

Auto-Generate PR Description from prd.json

If prd.json exists and has completed stories, generate the PR body from them:

node -e "
const p=require('./prd.json');
const stories=p.stories||{};
const done=Object.entries(stories).filter(([,s])=>s.passes===true);
if(done.length){
  console.log('## Changes');
  done.forEach(([id,s])=>console.log('- **'+id+'**: '+s.title+(s.resolution?' ('+s.resolution+')':'')));
  console.log('\n## Test Plan');
  done.forEach(([id,s])=>console.log('- [ ] Verify '+s.title));
}
"

Use this output as the PR body:

gh pr create --title "[Sprint summary]" --body "[generated from prd.json]"

Safety Checks

Before committing (if ANY fail, fix before proceeding):

• npm run typecheck passes
• npm run build passes
• npm test -- --watchAll=false --passWithNoTests passes
• No .env files staged — unstage if found
• No console.log in staged files — remove if found
• No hardcoded secrets — remove if found

Before pushing:

• Branch is correct (not pushing to main accidentally)
• Branch is up-to-date with remote: git fetch && git status
• Commit messages are clean

If issues found: fix them, re-stage, re-run checks, THEN commit.

Version Sync Check (claude-auto-dev repo only)

When committing to this repo, check for stale version strings before staging:

# Read current version
VERSION=$(cat VERSION 2>/dev/null)

# Grep for previous version references (skip CHANGELOG.md - it's historical)
grep -rn "4\.9\.4\|v4\.9" --include="*.md" --include="*.json" --include="*.ps1" --include="*.sh" . \
  | grep -v CHANGELOG.md | grep -v node_modules | grep -v .git

If stale versions found: fix them before committing.

Files to check: VERSION, package.json, manifest.json, README.md badge, commands.md, install.sh fallback, install.ps1 fallback.

The current version is: !cat VERSION 2>/dev/null

Batch Commit (During Auto Mode)

During auto, commit every 3 tasks:

git add -A -- ':!.env*' ':!*.pem' ':!*.key' ':!*.secret'
git commit -m "feat: complete S9-1 through S9-3

- S9-1: Playlist UI with drag-drop
- S9-2: Song extend from timestamp
- S9-3: Onboarding wizard"

Amend Last Commit

Only if not pushed yet:

git add <missed-files>
git commit --amend --no-edit

Undo Last Commit (Keep Changes)

git reset --soft HEAD~1