claude-skills-reference/standards/git/git-workflow-standards.md

Git Workflow Standards

Core Principles

1. Conventional Commits

• All commits follow conventional commits specification
• Enable automated changelog generation
• Clear categorization of all changes
• Explicit marking of breaking changes

2. Semantic Versioning

• Automated versioning based on commit types
• MAJOR version: BREAKING CHANGE
• MINOR version: feat type commits
• PATCH version: fix type commits

3. Branch Protection

• Main branch requires review
• All quality gates must pass
• No force pushes to main
• Signed commits recommended

Conventional Commits Specification

Commit Message Structure

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Standard Types

feat:     # New features (agents, skills, tools)
fix:      # Bug fixes
docs:     # Documentation only changes
style:    # Formatting changes (no functional impact)
refactor: # Code restructuring without feature changes
perf:     # Performance improvements
test:     # Adding or correcting tests
chore:    # Maintenance tasks (dependencies, build)
ci:       # CI/CD configuration changes

Examples

# New agent implementation
feat(agents): implement cs-content-creator agent

# Bug fix in Python tool
fix(seo-optimizer): correct keyword density calculation

# Documentation update
docs(README): add agent catalog section

# Breaking change
feat(agents)!: replace agent template structure

BREAKING CHANGE: agent frontmatter now requires 'tools' field

Scopes for Claude Skills

Common Scopes:
  agents:           # Agent implementation
  skills:           # Skill packages
  standards:        # Standards library
  templates:        # Templates
  docs:             # Documentation
  foundation:       # Core infrastructure
  marketing:        # Marketing domain
  c-level:          # C-level domain
  product:          # Product domain
  engineering:      # Engineering domain
  ra-qm:            # RA/QM domain

Branch Strategy

Branch Naming Conventions

# Feature branches (agent/skill development)
feature/agents-{name}:         # New agent implementation
feature/skills-{name}:         # New skill package
feature/{domain}-{component}:  # Domain-specific features

# Documentation branches
docs/{component}:              # Documentation updates
docs/standards-{name}:         # Standards library updates

# Bug fixes
fix/{issue-number}-{description}: # Bug fixes

# Hotfixes (critical production issues)
hotfix/{issue}-{description}:   # Emergency fixes

# Test branches
test/{feature}:                # Testing and validation

Examples

# Create feature branch for new agent
git checkout -b feature/agents-ceo-advisor

# Create documentation branch
git checkout -b docs/installation-guide

# Create fix branch
git checkout -b fix/23-broken-relative-paths

# Create test branch
git checkout -b test/agent-path-resolution

Workflow Process

1. Development Workflow

# Start new feature
git checkout -b feature/agents-product-manager

# Make changes
# ... edit files ...

# Stage changes
git add agents/product/cs-product-manager.md

# Commit with conventional message
git commit -m "feat(agents): implement cs-product-manager agent

- Add YAML frontmatter
- Document RICE prioritization workflow
- Add interview analysis integration
- Test relative path resolution

Phase: 2.3
Issue: #13"

# Push to remote
git push origin feature/agents-product-manager

2. Pull Request Workflow

# Create PR using gh CLI
gh pr create \
  --base main \
  --head feature/agents-product-manager \
  --title "feat(agents): implement cs-product-manager agent" \
  --body "Closes #13

## Summary
Implements product management agent with RICE prioritization and interview analysis.

## Testing
- [x] Relative paths resolve correctly
- [x] Python tools execute successfully
- [x] Workflows documented
- [x] Quality gates pass"

3. Review & Merge

# After review approval
gh pr merge feature/agents-product-manager \
  --squash \
  --delete-branch

4. Release Workflow

# Create release with semantic versioning
git tag v1.0.0-agents
git push origin v1.0.0-agents

# GitHub Actions automatically creates release with changelog

Commit Message Templates

For Agent Implementation

feat(agents): implement cs-{agent-name}

- Add YAML frontmatter with required fields
- Document {number} workflows
- Add integration examples
- Test Python tool execution
- Verify relative path resolution

Phase: {phase-number}
Issue: #{issue-number}

For Skill Development

feat(skills): add {skill-name} to {domain} domain

- Create skill directory structure
- Implement {number} Python automation tools
- Add knowledge base references
- Create user templates

Domain: {domain}
Issue: #{issue-number}

For Standards Updates

docs(standards): update {standard-name} for {context}

- Adapt for claude-skills context
- Remove factory-specific references
- Add agent-specific guidelines
- Update examples

Issue: #{issue-number}

For Bug Fixes

fix({scope}): resolve {issue-description}

Problem: {what was broken}
Solution: {what was fixed}
Impact: {who/what this affects}

Fixes #{issue-number}

Git Hooks

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Running pre-commit checks..."

# Check for secrets
if git diff --cached | grep -iE '(api[_-]?key|secret|password|token).*=.*[^x{5}]'; then
    echo "❌ Potential secret detected in commit"
    exit 1
fi

# Validate Python syntax
python -m compileall $(git diff --cached --name-only --diff-filter=ACM | grep '\.py$')
if [ $? -ne 0 ]; then
    echo "❌ Python syntax errors detected"
    exit 1
fi

echo "✅ Pre-commit checks passed"

Commit-msg Hook

#!/bin/bash
# .git/hooks/commit-msg

# Validate conventional commit format
commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert)(\([a-z-]+\))?(!)?:\ .{1,}'

if ! head -1 "$1" | grep -qE "$commit_regex"; then
    echo "❌ Commit message does not follow conventional commits format"
    echo "Format: <type>[(scope)]: <description>"
    echo "Example: feat(agents): implement cs-product-manager"
    exit 1
fi

echo "✅ Commit message format valid"

Quality Gates Integration

Pre-push Validation

#!/bin/bash
# .git/hooks/pre-push

echo "Running pre-push validation..."

# Run quality checks
/review

# Check for TODO comments in production code
if git diff origin/main...HEAD | grep -i "TODO"; then
    echo "⚠️  TODO comments found - consider addressing before push"
fi

echo "✅ Pre-push validation complete"

Branch Protection Rules

Main Branch Protection

branch_protection:
  required_status_checks:
    strict: true
    contexts:
      - "ci-quality-gate"
      - "claude-review"

  required_pull_request_reviews:
    required_approving_review_count: 1
    dismiss_stale_reviews: true
    require_code_owner_reviews: false

  enforce_admins: true
  required_conversation_resolution: true
  allow_force_pushes: false
  allow_deletions: false

Common Workflows

Hotfix Process

# Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-path-resolution

# Fix issue
# ... make changes ...

# Commit with high priority
git commit -m "fix(agents)!: resolve critical path resolution failure

BREAKING CHANGE: agent path resolution now requires absolute project root

Fixes #42
Priority: P0"

# Create PR with hotfix label
gh pr create --label "P0,hotfix" --base main

# After merge, tag immediately
git tag v1.0.1-hotfix
git push origin v1.0.1-hotfix

Multi-Agent Coordination

# Coordinating changes across multiple agents
git checkout -b feature/update-all-marketing-agents

# Update cs-content-creator
git add agents/marketing/cs-content-creator.md
git commit -m "feat(agents): enhance cs-content-creator workflows"

# Update cs-demand-gen-specialist
git add agents/marketing/cs-demand-gen-specialist.md
git commit -m "feat(agents): enhance cs-demand-gen-specialist workflows"

# Push coordinated changes
git push origin feature/update-all-marketing-agents

Best Practices

Do's

• ✅ Use conventional commit format for all commits
• ✅ Reference issue numbers in commit messages
• ✅ Keep commits atomic (one logical change per commit)
• ✅ Write clear, descriptive commit messages
• ✅ Test changes before committing
• ✅ Pull before pushing to avoid conflicts
• ✅ Use feature branches for all changes
• ✅ Delete branches after merging

Don'ts

• ❌ Commit directly to main (use PRs)
• ❌ Force push to shared branches
• ❌ Commit secrets or credentials
• ❌ Mix multiple unrelated changes in one commit
• ❌ Use vague commit messages ("fix stuff", "updates")
• ❌ Skip quality checks
• ❌ Leave branches unmerged for extended periods

Emergency Procedures

Rollback Commit

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

# Revert specific commit
git revert <commit-hash>

# Force rollback (use with caution!)
git reset --hard HEAD~1
git push origin main --force  # Only if absolutely necessary!

Fix Bad Commit Message

# Amend last commit message (before push)
git commit --amend -m "feat(agents): corrected commit message"

# After push (creates new commit)
git revert HEAD
git commit -m "feat(agents): correct implementation with proper message"

---

Standard: Conventional Commits v1.0.0 Versioning: Semantic Versioning v2.0.0 Updated: November 2025 Review: Monthly git workflow assessment