# Git Workflow Manager

> Handle git branch creation, commits, and PR creation for feature and bugfix workflows. Follows git best practices with structured commit messages and proper PR formatting.

- Skill: `timogilvie/git-workflow-manager` (Agent Skill)
- Install (CLI): `npx skillmds@latest add timogilvie/git-workflow-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/timogilvie/git-workflow-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: timogilvie (https://skillmd.com/u/timogilvie)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/timogilvie/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:**
```bash
# 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:**
```bash
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.

```bash
# 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:

```bash
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:

```bash
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:**
```bash
git log -1 --oneline
```

### Step 4: Push Branch

Push the branch to remote:
```bash
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:
```bash
# 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:
```markdown
## 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:
```markdown
## 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:**
```bash
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:
```bash
gh pr view --web
```

Or get PR URL:
```bash
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:
```bash
git checkout feature/<name>
```
Warn user: "Branch already exists, checked out existing branch"

### Uncommitted Changes
If uncommitted changes exist:
```bash
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](https://www.conventionalcommits.org/):
- `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)