baphuongna/pi-crew/git-master

git-master

Use this skill for commit/release hygiene. This skill covers git workflow from local changes to published releases.

Pre-commit Checklist

Before every commit:

1. Run git status --short — understand what changed
2. Stage only files related to the current task
3. Review staged diff with git diff --staged
4. Check for unintended changes (generated files, temp files, secrets)
5. Ensure tests pass locally before committing

Commit Rules

• Independent commits: Each commit should be self-contained and revertible. Don't mix unrelated changes.
• Concise messages: Use imperative mood, 50 chars or less for subject. Add body for context.
• Format: type(scope): subject where type is fix, feat, chore, docs, test, refactor
• Do not include: secrets, OTPs, local temp files, node_modules, dist/, *.log, *.tmp
• Do not push/publish unless explicitly requested
• Verify before staging large generated files (tarballs, build outputs)

Commit Message Format

type(scope): short description (50 chars max)
 
 Longer description if needed. Explain WHY the change was made,
 not just what changed. Reference issues/PRs if applicable.
 
Refs: #123

Examples:

fix(live-agent): prevent cross-workspace agent access
feat(widget): add snapshot cache with 500ms TTL
docs(skills): add event-log-tracing skill
chore(tests): add integration test for reconcileAllStaleRuns

Branch Naming

Rollback Procedures

Revert last commit (safe, keeps history)

git revert HEAD
git push

Reset to known-good state (rewrites history)

# Soft: keep changes staged
git reset --soft HEAD~1
 
# Mixed: keep changes unstaged
git reset HEAD~1
 
# Hard: discard all changes (DESTRUCTIVE)
git reset --hard <commit-hash>

Checkout single file from a past commit

git checkout <commit-hash> -- path/to/file

Recover from a bad reset

git reflog  # find the commit before reset
git reset --hard <reflog-entry>

Regression Hunting with git bisect

When a regression is found and the culprit commit is unknown:

git bisect start
git bisect bad              # current commit is bad
git bisect good <known-good> # a commit that worked
 
# git checks out a middle commit
# test it: if bad, mark it; if good, mark it
# repeat until culprit found
git bisect bad   # or: git bisect good
 
# after bisect completes:
git bisect reset  # return to original branch
 
# culprit is the first bad commit in the range

Amend and Force-Push

Amend last commit (before push)

# Make additional changes
git add .
git commit --amend --no-edit  # amend without changing message
git commit --amend -m "new message"  # or with new message

Force-push (DESTRUCTIVE — only when necessary)

# Only force-push to feature branches, never main/master
git push --force-with-lease origin <branch>
 
# --force-with-lease is safer: fails if someone else pushed
# Regular --force can overwrite others' work

When safe to force-push:

• Your feature branch that only you use
• After git rebase (rebase rewrites commit history)
• After amending commits not yet pushed

When to NEVER force-push:

• Shared branches (main, master, develop)
• Branch with active PR
• Branch others may have based work on

Tag and Release

Create a version tag

git tag -a v1.2.3 -m "Release 1.2.3: Add skill templates"
git push origin v1.2.3

Tag after version bump

git add CHANGELOG.md package.json
git commit -m "chore: bump version to 1.2.3"
git tag -a 1.2.3 -m "Version 1.2.3"
git push && git push --tags

List and verify tags

git tag -l
git show <tag-name>

Version Bump Sequence

1. Verify: npx tsc --noEmit passes
2. Verify: npm test passes
3. Update CHANGELOG.md with changes for this version
4. Update package.json version field
5. Commit: chore: bump version to X.Y.Z
6. Tag: git tag -a X.Y.Z -m "Release X.Y.Z"
7. Publish: npm publish --access public
8. Verify: npm view pi-crew shows new version

Stash Patterns

Stash work-in-progress

git stash -u           # include untracked files
git stash push -m "WIP: feature X"  # with message

Apply and manage stashes

git stash list         # show all stashes
git stash pop          # apply latest and remove
git stash apply         # apply latest, keep in stash
git stash apply stash@{2}  # apply specific stash
git stash drop          # remove latest stash
git stash clear         # remove all stashes

Enforcement — Git Master Gate

Before committing or publishing, verify:

• [ ] git status reviewed — only related files staged
• [ ] git diff --staged reviewed — no unintended changes
• [ ] Tests pass locally (npm test or appropriate test command)
• [ ] No secrets in staged changes (API keys, tokens, passwords)
• [ ] Commit message follows format: type(scope): subject (50 chars or less)
• [ ] No generated files staged unless intentional

If ANY answer is NO → Stop. Fix issues before committing.

Anti-patterns

• Committing generated files: Don't commit dist/, build/, *.min.js unless intentional
• Large commits: If >500 lines changed, consider splitting
• Committing with unverified tests: Run tests before commit
• Force-pushing main/master: Never
• Committing secrets: Check for API_KEY, TOKEN, PASSWORD, SECRET before staging
• Unclear messages: "fix stuff" is not a valid commit message

Source patterns

• src/state/atomic-write.ts — atomic git-safe file writes
• src/worktree/worktree-manager.ts — worktree git operations
• src/utils/conflict-detect.ts — git conflict detection
• package.json — version field, publish scripts

Verification

cd pi-crew
git status --short
git log --oneline -5
git diff --staged --stat
 
# TypeScript
npx tsc --noEmit
 
# Tests
npm test
 
# Package dry-run before publish
npm pack --dry-run