Git Workflow Skill

[!FIXED!]

Purpose

This skill provides procedures for Git operations in the development workflow. It covers branching, commits, and pull requests.

When to use:

• Creating branches for new work
• Making commits
• Creating pull requests
• Merging changes [!FIXED!]

=== PREREQUISITES ===

Before using this skill:

• Git is installed
• Repository is cloned locally
• Commit message standard exists (@ref(CB-STD-COMMITS-001))
• You have push access (or will create PR)

=== PROCEDURE: CREATE BRANCH ===

Branch Naming Convention

<type>/<description>

Types:
- feature/  : New features
- bugfix/   : Bug fixes
- hotfix/   : Urgent production fixes
- refactor/ : Code refactoring
- docs/     : Documentation only
- test/     : Test additions
- chore/    : Maintenance tasks

Steps

1. Ensure you're on main/develop

   bashCopy

   git checkout main
   git pull origin main
   

2. Create and checkout new branch

   bashCopy

   git checkout -b feature/add-user-authentication
   

3. Log in buildlog

   markdownCopy

   | HH:MM | #micro-decision | Created branch feature/add-user-authentication | - |
   

Branch Naming Examples

=== PROCEDURE: MAKE COMMITS ===

Commit Message Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

Steps

1. Stage changes

   bashCopy

   git add <files>
   # or for all changes:
   git add .
   

2. Review staged changes

   bashCopy

   git status
   git diff --staged
   

3. Commit with message

   bashCopy

   git commit -m "feat(auth): add OAuth2 login support"
   

4. Log in buildlog

   markdownCopy

   | HH:MM | #commit | feat(auth): add OAuth2 login support | PR #XX |
   

Commit Message Examples

Commit Frequency

• Commit logical chunks of work
• Each commit should be independently functional
• Don't bundle unrelated changes
• Can be squashed later if needed

=== PROCEDURE: CREATE PULL REQUEST ===

Before Creating PR

1. Ensure all commits are pushed

   bashCopy

   git push origin <branch-name>
   

2. Run pre-merge checks

   • All tests pass
   • Linter passes
   • Code reviewed by self
   • Documentation updated if needed

PR Title Format

<type>(<scope>): <description>

Same format as commit messages.

PR Description Template

## Summary
Brief description of what this PR does.

## Changes
- List of significant changes
- Bullet points preferred

## Testing
- How was this tested?
- Test coverage info

## Related Issues
Closes #123
Related to #456

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

Steps

1. Push branch

   bashCopy

   git push -u origin feature/add-user-authentication
   

2. Create PR via GitHub/GitLab/etc.

   • Use PR title format
   • Fill in description template
   • Add reviewers
   • Add labels

3. Log in buildlog

   markdownCopy

   | HH:MM | #micro-decision | Created PR #42 for feature/add-user-authentication | PR #42 |
   

=== PROCEDURE: MERGE CHANGES ===

Merge Strategies

Steps

1. Ensure PR is approved

   • Required reviews complete
   • CI checks pass
   • No merge conflicts

2. Merge using preferred strategy

   • Via GitHub UI, or:
   bashCopy

   git checkout main
   git merge --squash feature/add-user-authentication
   git commit -m "feat(auth): add OAuth2 login support (#42)"
   git push origin main
   

3. Delete branch

   bashCopy

   git branch -d feature/add-user-authentication
   git push origin --delete feature/add-user-authentication
   

4. Log in buildlog

   markdownCopy

   | HH:MM | #commit | Merged feat(auth): add OAuth2 login support | PR #42 |
   

=== PROCEDURE: HANDLE CONFLICTS ===

Steps

1. Update main and rebase

   bashCopy

   git checkout main
   git pull origin main
   git checkout feature/your-branch
   git rebase main
   

2. Resolve conflicts

   • Open conflicting files
   • Resolve conflict markers
   • Test resolution
   bashCopy

   git add <resolved-files>
   git rebase --continue
   

3. Force push (if rebased)

   bashCopy

   git push --force-with-lease origin feature/your-branch
   

4. Log in buildlog

   markdownCopy

   | HH:MM | #resolution | Resolved merge conflicts in <files> | PR #42 |
   

Conflict Prevention

• Rebase frequently against main
• Communicate about files being modified
• Break large changes into smaller PRs

=== PROCEDURE: REVERT CHANGES ===

Revert a Commit

# Revert last commit (creates new commit)
git revert HEAD

# Revert specific commit
git revert <commit-hash>

# Revert without auto-commit
git revert -n <commit-hash>

Log in Buildlog

| HH:MM | #resolution | Reverted commit <hash> due to <reason> | - |

AI-Assisted Commit

When committing AI-generated or AI-assisted code, follow APS (Agentic Provenance Standard).

Prerequisites:

• Agent registered in .aps/registry.yaml (if using APS)
• Git hooks installed (optional but recommended)
• Code has been human-reviewed

Steps:

1. Set APS environment variables:

# Required
export APS_AGENT_ID="anthropic:claude-code@1.5.0+sk7b2c#a7b3c9d2"
export APS_HUMAN_REVIEWED="true"

# Recommended
export APS_MODEL="claude-sonnet-4-5-20250929"
export APS_KERNEL="claude-code@1.5.0"
export APS_SESSION="sess_feature_001"
export APS_SKILLS="code-generator@2.1.0, security-check@1.5.0"
export APS_CONTRIBUTION="generate"
export APS_TOKENS_IN="12450"
export APS_TOKENS_OUT="3280"

2. Stage changes:

git add <files>

3. Commit with conventional format:

git commit -m "feat(auth): implement OAuth2 PKCE flow

Implements secure OAuth2 authorization code flow with PKCE for mobile
clients. Includes token refresh logic and secure storage integration."

4. Verify trailers were added:

git log -1 --format='%(trailers)'

Expected output:

AI-Agent: anthropic:claude-code@1.5.0+sk7b2c#a7b3c9d2
AI-Model: claude-sonnet-4-5-20250929
AI-Kernel: claude-code@1.5.0
AI-Session: sess_feature_001
AI-Skills: code-generator@2.1.0, security-check@1.5.0
AI-Tokens-In: 12450
AI-Tokens-Out: 3280
AI-Contribution: generate
AI-Human-Reviewed: true

5. Clear environment variables (optional):

unset APS_AGENT_ID APS_HUMAN_REVIEWED APS_MODEL APS_KERNEL APS_SESSION APS_SKILLS APS_CONTRIBUTION APS_TOKENS_IN APS_TOKENS_OUT

Without Git Hooks:

If hooks aren't installed, manually add trailers:

git commit -m "feat(auth): implement OAuth2 PKCE flow

Implements secure OAuth2 authorization code flow.

AI-Agent: anthropic:claude-code@1.5.0+sk7b2c#a7b3c9d2
AI-Human-Reviewed: true"

Multi-Agent Workflow:

When multiple agents contribute:

export APS_AGENT_ID="anthropic:coder@1.0.0+sk123#abc12345"
export APS_SUBAGENTS="security-reviewer#def456 (review), test-runner#ghi789 (validation)"
export APS_CONTRIBUTION_GRAPH="main→security-reviewer→test-runner"
export APS_HUMAN_REVIEWED="true"

git commit -m "feat(api): refactor authentication middleware"

Log in Buildlog

| HH:MM | #commit | feat(auth): implement OAuth2 PKCE flow | AI-assisted (anthropic:claude-code@1.5.0), human-reviewed |

See: @ref(CB-STD-APS-001) for complete APS specification

=== ANTI-PATTERNS ===

=== RELATED DOCUMENTS ===