Git Workflow Manager

Git Workflow Manager

This skill handles all git operations for workflow and bugfix commands including branch creation, commits, and PR creation.

When to Use

Use this skill when:

• Creating a feature or bugfix branch
• Committing changes with structured messages
• Creating pull requests with proper formatting
• Ready to push work for review

Instructions

Step 1: Load Task Context

Read the selected task from the feature/bug directory:

• For features: features/<feature-name>/selected-task.json
• For bugs: bugs/<bug-name>/selected-task.json

The featureName field in the JSON tells you which directory to look in.

Extract:

• workflowType: "feature" or "bugfix"
• featureName: Directory name for locating files
• title: Task title for branch naming
• taskId: Linear issue ID for commit references
• description: For PR body

Step 2: Create Git Branch

Sanitize the title:

• Convert to lowercase
• Replace spaces with hyphens
• Remove special characters except hyphens
• Limit to 50 characters
• Remove leading/trailing hyphens

Create branch:

# For features
git checkout -b feature/<sanitized-title>

# For bugfixes
git checkout -b bugfix/<sanitized-title>

Example:

• Input: "Add User Authentication System"
• Output: git checkout -b feature/add-user-authentication-system

Confirm branch creation:

git branch --show-current

Record review baseline commit:

After creating the branch, record the current HEAD commit SHA in selected-task.json as reviewBaseCommit. This allows the self-review tool to scope its diff to only task-specific changes, filtering out any pre-existing branch changes.

# Get current HEAD commit SHA
REVIEW_BASE=$(git rev-parse HEAD)

# Add reviewBaseCommit to selected-task.json
# For features:
npx tsx -e "
const fs = require('fs');
const path = 'features/<feature-name>/selected-task.json';
const task = JSON.parse(fs.readFileSync(path, 'utf-8'));
task.reviewBaseCommit = '${REVIEW_BASE}';
fs.writeFileSync(path, JSON.stringify(task, null, 2) + '\n');
"

This commit SHA marks the point where task implementation begins. The review tool will automatically detect it and only review changes made after this point.

Step 3: Commit Changes

For feature workflows:

After implementation is complete, create a structured commit:

git add .

git commit -m "$(cat <<'EOF'
feat: <concise description of what was added>

<Optional detailed explanation of changes>

Implements: <Linear-ID>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

For bugfix workflows:

After fix is complete, create a structured commit:

git add .

git commit -m "$(cat <<'EOF'
fix: <concise description of what was fixed>

Root cause: <brief description of root cause>
Solution: <brief description of solution>

Fixes: <Linear-ID>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Commit message guidelines:

• First line: feat: or fix: prefix + concise summary (max 72 chars)
• Blank line
• Optional detailed explanation
• References to Linear issues
• Claude Code attribution

Verify commit:

git log -1 --oneline

Step 4: Push Branch

Push the branch to remote:

git push -u origin $(git branch --show-current)

Check for any errors:

• Merge conflicts → Report to user
• Permission issues → Report to user
• Network issues → Retry once

Step 4.5: Run Build Check

IMPORTANT: Before creating a PR, the build must pass.

Run the build check from the config:

# Read build command from config (claude/config.json or codex/config.json)
# Default build command is typically: npm run build
npm run build

What to do if build fails:

1. Review the build errors carefully
2. Fix any build errors
3. Commit the fixes
4. Re-run the build check
5. Only proceed to PR creation after build passes

Override (rare cases only): If you need to bypass the build check (e.g., for documentation-only changes), you can set "requireBuildBeforePR": false in the checks section of your config. However, this should be avoided in most cases.

Why this matters:

• Prevents broken code from being submitted for review
• Catches build errors early before CI runs
• Maintains code quality standards
• Reduces wasted reviewer time

Step 5: Create Pull Request

Generate PR title:

• For features: feat: <Title from Linear task>
• For bugfixes: fix: <Title from Linear task>

Generate PR body:

For feature PRs:

## Summary
- <Bullet point 1 from tasks.md>
- <Bullet point 2 from tasks.md>
- <Bullet point 3 from tasks.md>

## Test plan
- [ ] All tests pass locally
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Edge cases validated

## Related
- Linear: <Linear-ID with URL>
- PRD: `features/<name>/prd.md`
- Tasks: `features/<name>/tasks.md`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

For bugfix PRs:

## Summary
**Root Cause:** <From investigation.md>
**Solution:** <From fix-tasks.md>

## Changes
- <Bullet point 1 from fix-tasks.md>
- <Bullet point 2 from fix-tasks.md>

## Test plan
- [ ] Bug reproduction test added
- [ ] Fix verified against reproduction steps
- [ ] Regression tests added
- [ ] All tests pass

## Validation Steps for Reviewers
1. <Step 1 to reproduce original bug>
2. <Step 2 to verify fix>

## Related
- Linear: <Linear-ID with URL>
- Investigation: `bugs/<name>/investigation.md`
- Fix tasks: `bugs/<name>/fix-tasks.md`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Create PR using GitHub CLI:

gh pr create --title "<PR-TITLE>" --body "$(cat <<'EOF'
<PR-BODY>
EOF
)"

Alternative if gh CLI not available: Provide user with:

1. PR title
2. PR body
3. Instructions to create manually

Step 6: Verify PR Creation

Check PR was created successfully:

gh pr view --web

Or get PR URL:

gh pr view --json url -q .url

Step 7: Return Summary

Provide user with:

✓ Git workflow complete:
  - Branch: feature/add-user-authentication-system
  - Commit: feat: Add user authentication system
  - PR: https://github.com/org/repo/pull/123

Ready for review checklist:
- [ ] All tasks in tasks.md completed
- [ ] Tests pass locally and on CI
- [ ] Feature validated on preview
- [ ] Reviewer confirmed PRD alignment

Examples

Example 1: Feature Workflow

Input: features/add-email-generation/selected-task.json with workflowType: "feature"
Process:
1. Create branch: feature/add-email-generation
2. (User implements feature)
3. Commit: "feat: Add DSPy email generation\n\nImplements: HOK-125"
4. Push: git push -u origin feature/add-email-generation
5. Run build check: npm run build (must pass before PR)
6. Create PR with summary from tasks.md
7. Return PR URL

Example 2: Bugfix Workflow

Input: bugs/contact-discovery-timeout/selected-task.json with workflowType: "bugfix"
Process:
1. Create branch: bugfix/contact-discovery-timeout
2. (User fixes bug)
3. Commit: "fix: Contact discovery timeout\n\nRoot cause: Missing timeout config\nFixes: HOK-130"
4. Push: git push -u origin bugfix/contact-discovery-timeout
5. Run build check: npm run build (must pass before PR)
6. Create PR with root cause and solution
7. Return PR URL

Error Handling

Branch Already Exists

If branch exists:

git checkout feature/<name>

Warn user: "Branch already exists, checked out existing branch"

Uncommitted Changes

If uncommitted changes exist:

git status --short

Options:

1. Ask user: "Commit these changes? (y/n)"
2. If yes, proceed with commit
3. If no, suggest: git stash

Build Check Failures

If the build check fails:

1. Display the build error output clearly
2. Guide user to fix the errors:

   ❌ Build check failed. Cannot create PR until build passes.
   
   Build errors:
   [show error output]
   
   Steps to fix:
   1. Review the errors above
   2. Fix the build issues
   3. Run 'npm run build' locally to verify
   4. Commit your fixes
   5. Try PR creation again
   
   To bypass (not recommended): Set "requireBuildBeforePR": false in config
   

3. Wait for user to fix and confirm
4. Re-run build check before proceeding

Note: Do not bypass the build check unless explicitly requested by the user for special cases (e.g., documentation-only PRs).

Push Conflicts

If push fails with conflicts:

1. Check if remote branch exists: git fetch && git branch -r
2. If exists: git pull --rebase origin $(git branch --show-current)
3. Resolve conflicts (ask user for help)
4. Retry push

PR Creation Fails

If gh pr create fails:

1. Check gh auth status
2. If not authenticated: gh auth login
3. Retry PR creation
4. If still fails, provide manual instructions

No GitHub CLI

If gh command not found:

1. Provide manual PR creation instructions
2. Include PR title and body
3. Guide user to create PR via web UI

Git Best Practices

Commit Message Format

Follow Conventional Commits:

• feat: for new features
• fix: for bug fixes
• docs: for documentation changes
• test: for test additions
• refactor: for code refactoring

Branch Naming

• feature/* for new features
• bugfix/* for bug fixes
• Descriptive but concise names
• Use hyphens, not underscores

PR Descriptions

• Clear summary of changes
• Test plan with checkboxes
• Links to related issues/docs
• Validation steps for reviewers

Output

This skill outputs:

• New git branch (feature/* or bugfix/*)
• Structured git commits
• Pull request with formatted description
• Console: Summary with PR URL and checklist

Integration

This skill integrates with:

• Input from: linear-task-selector (task context), document-orchestrator (PRD/tasks)
• Used by: workflow, bugfix commands
• External tools: git, gh (GitHub CLI)