Create Git Workflow Skills for Tinker Agents

Home Epics Create Git Workflow Skills for Tinker AgentsEdit

Cancel

Title *

Project *

Description

## Problem

Worker agents have poor git workflow habits:

1. **PR branch confusion** - When asked to fix an issue in PR #33, they create a new random branch instead of using the PR's existing branch
2. **No branch stacking** - All phases branch from main instead of stacking (phase-2 from phase-1, etc.)
3. **Incorrect push targets** - Changes are pushed to wrong branches
4. **Bad commit messages** - Vague, inconsistent format

## Solution

Create **one comprehensive Claude Code skill** that teaches agents proper git workflows. The skill is automatically invoked based on context and provides step-by-step instructions for all git operations.

## Skill to Create

### Skill: `git-workflow`

**Location:** `.claude/skills/git-workflow/SKILL.md`

**Purpose:** Comprehensive git workflow guide for all operations

**When to use:** Whenever git operations are needed (fixing PRs, creating commits, creating branches, pushing changes)

```yaml
---
name: git-workflow
description: Use for any git operations: fixing PRs, creating commits, creating branches, pushing changes. Handles proper branch management, commit conventions, and stacked PRs.
allowed-tools: Bash, gh
---

# Git Workflow - Complete Guide

## Golden Rules

1. **Never push to main**
2. **Fix PRs on their existing branch** - don't create new branches
3. **Stack phased work** - Phase N branches from Phase N-1
4. **Use conventional commits** - type(scope): subject

---

## Scenario 1: Fixing an Existing PR

When user says: "Fix PR #33" or "Update pull request 45" or "Modify #123"

### Steps

1. **Get the PR branch:**
```bash
gh pr view <PR_NUMBER> --json headRefName --jq '.headRefName'
```
Save this branch name - use it for ALL operations.

2. **Checkout the PR branch:**
```bash
git fetch origin
git checkout <branch_name>
```

3. **Make changes** using Edit/Write tools

4. **Commit with proper format:**
```bash
git add <files>
git commit -m "fix(scope): description of fix"
git push origin <branch_name>
```

5. **No new PR needed** - same PR URL

### Example
```
User: "Fix the failing tests in PR #33"

1. gh pr view 33 --json headRefName → "feature/ticket-81-ui-foundation"
2. git checkout feature/ticket-81-ui-foundation
3. [fix test files]
4. git commit -m "fix(tests): resolve assertion failures in dashboard spec"
5. git push origin feature/ticket-81-ui-foundation
```

---

## Scenario 2: Creating a New Feature (Single PR)

When user says: "Implement X" or "Add feature Y" (no mention of phases/stacking)

### Steps

1. **Start from main:**
```bash
git checkout main
git pull origin main
```

2. **Create feature branch:**
```bash
git checkout -b feature/descriptive-name
```

3. **Make changes** using Edit/Write tools

4. **Commit and push:**
```bash
git add -A
git commit -m "feat(scope): description"
git push -u origin feature/descriptive-name
```

5. **Create PR:**
```bash
gh pr create --base main --title "feat(scope): description"
```

---

## Scenario 3: Creating Stacked PRs (Phased Epic)

When user says: "Create Phase 1, Phase 2, Phase 3" OR working on epic subtasks sequentially

### Critical Concept
Each phase builds on the PREVIOUS phase, NOT main.

```
main ← phase-1 ← phase-2 ← phase-3
```

### Phase 1 (Foundation)
```bash
git checkout main
git pull origin main
git checkout -b feature/phase-1-description
# Make changes
git commit -m "feat(phase1): description"
git push -u origin feature/phase-1-description
gh pr create --base main --title "Phase 1: Description"
```

### Phase 2 (Builds on Phase 1)
```bash
# IMPORTANT: Branch from phase-1, NOT main
git checkout feature/phase-1-description
git pull origin feature/phase-1-description
git checkout -b feature/phase-2-description
# Make changes
git commit -m "feat(phase2): description"
git push -u origin feature/phase-2-description
gh pr create --base feature/phase-1-description --title "Phase 2: Description"
```

### Phase 3+ (Continue stacking)
```bash
git checkout feature/phase-2-description
git checkout -b feature/phase-3-description
# ... continue pattern
```

### After Phase 1 Merges to Main
```bash
git checkout main && git pull
git checkout feature/phase-2-description
git rebase main
git push -f origin feature/phase-2-description
```
Now Phase 2 is based on updated main.

---

## Commit Message Format

Always use:

```
<type>(<scope>): <subject>
```

### Types
- `feat`: New feature
- `fix`: Bug fix
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `docs`: Documentation changes
- `chore`: Maintenance tasks

### Rules
- Subject: imperative mood, max 50 chars, no period
- Examples:
  - ✅ "fix(auth): prevent SQL injection in login"
  - ✅ "feat(dashboard): add real-time agent status"
  - ✅ "test(models): add ticket dependency coverage"
  - ❌ "Fixed the bug"
  - ❌ "Update file.rb"

---

## Quick Reference

| Task | Base Branch | PR Base |
|------|-------------|---------|
| New feature | main | main |
| Fix PR #X | PR's branch | (no new PR) |
| Phase 1 | main | main |
| Phase 2 | phase-1 branch | phase-1 branch |
| Phase 3 | phase-2 branch | phase-2 branch |

---

## Critical DOs and DON'Ts

| ✅ DO | ❌ DON'T |
|-------|---------|
| Checkout PR branch when fixing | Create new branch for PR fixes |
| Stack phases (phase-2 from phase-1) | Branch all phases from main |
| Use conventional commit format | Write vague commit messages |
| Push to the branch you're working on | Push to random branches |
| Set correct PR base for stacked PRs | Base all PRs on main |
```

---

## Implementation Steps

1. **Create skill directory:**
```bash
mkdir -p .claude/skills/git-workflow
```

2. **Create SKILL.md** with content above

3. **Update agent configuration** to include the skill:
```yaml
---
name: tinker-worker
description: Implement features, fix bugs, write code
skills: git-workflow
tools: Read, Write, Edit, Bash, Grep, Glob
---

You are the Tinker Worker agent...

When performing any git operations, always follow the git-workflow skill.
```

## Acceptance Criteria

1. `.claude/skills/git-workflow/SKILL.md` created
2. Agent configuration updated to include skill
3. When asked to "fix PR #33", agent checks out the correct branch and pushes to it
4. When asked to commit, agent uses conventional commit format
5. When creating phased work, agent creates stacked branches
6. No more random branches
7. No more pushes to wrong branches

## Files to Create

- `.claude/skills/git-workflow/SKILL.md`

## Files to Modify

- Agent configuration files (add `skills: git-workflow`)

## Notes

- One skill covers all git scenarios
- Skills are auto-invoked based on keywords in the description
- Test by giving agents specific git tasks and verifying correct behavior