---

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.

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
5. Always include ticket ID - in branch names AND PR titles

---

Naming Conventions

Branch Names

Format: <type>/<id>-short-description

Examples:

• feature/123-user-auth
• fix/456-memory-leak
• refactor/789-api-structure

PR Titles

Format: [#<id>] <type>(<scope>): <subject>

Examples:

• [#123] feat(auth): add OAuth2 login support
• [#456] fix(database): resolve connection pool timeout
• [#789] refactor(api): simplify response handling

---

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:

Copygh pr view <PR_NUMBER> --json headRefName --jq '.headRefName'

Save this branch name - use it for ALL operations.

1. Checkout the PR branch:

Copygit fetch origin
git checkout <branch_name>

1. Make changes using Edit/Write tools

2. Commit with proper format:

Copygit add <files>
git commit -m "fix(scope): description of fix"
git push origin <branch_name>

1. No new PR needed - same PR URL

Example

CopyUser: "Fix the failing tests in PR #33"

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

IMPORTANT: You must know the ticket ID before proceeding. Ask the user if not provided.

Steps

1. Start from main:

Copygit checkout main
git pull origin main

1. Create feature branch with ticket ID:

Copygit checkout -b feature/<id>-short-description

1. Make changes using Edit/Write tools

2. Commit and push:

Copygit add -A
git commit -m "feat(scope): description"
git push -u origin feature/<id>-short-description

1. Create PR with ticket ID in title:

Copygh pr create --base main --title "[#<id>] 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

IMPORTANT: Each subtask has its own ticket ID. Use the appropriate ticket ID for each phase.

Critical Concept

Each phase builds on the PREVIOUS phase, NOT main.

Copymain <- phase-1 <- phase-2 <- phase-3

Phase 1 (Foundation)

Copygit checkout main
git pull origin main
git checkout -b feature/<id1>-phase1-description
# Make changes
git commit -m "feat(phase1): description"
git push -u origin feature/<id1>-phase1-description
gh pr create --base main --title "[#<id1>] feat(scope): Phase 1 - Description"

Phase 2 (Builds on Phase 1)

Copy# IMPORTANT: Branch from phase-1, NOT main
git checkout feature/<id1>-phase1-description
git pull origin feature/<id1>-phase1-description
git checkout -b feature/<id2>-phase2-description
# Make changes
git commit -m "feat(phase2): description"
git push -u origin feature/<id2>-phase2-description
gh pr create --base feature/<id1>-phase1-description --title "[#<id2>] feat(scope): Phase 2 - Description"

Phase 3+ (Continue stacking)

Copygit checkout feature/<id2>-phase2-description
git checkout -b feature/<id3>-phase3-description
# ... continue pattern

After Phase 1 Merges to Main

Copygit checkout main && git pull
git checkout feature/<id2>-phase2-description
git rebase main
git push -f origin feature/<id2>-phase2-description

Now Phase 2 is based on updated main.

---

Commit Message Format

Always use:

Copy<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"

---

Quick Reference

---

GitHub Backlinks in PRs

When creating PRs, always include backlinks to application resources so users can navigate from GitHub back to the app.

When to Add Backlinks

• Worker submitting work → Link to ticket and agent session
• Reviewer commenting → Link to ticket being reviewed
• Any GitHub interaction → Include relevant app URLs

URL Format

Use the standard Tinker URL pattern: https://{project_name}.tinkerai.win

For the main tinker project: https://tinker.tinkerai.win

PR Description Template

Copygh pr create --base main --title "[#<id>] feat(scope): description" --body '## Summary

Brief description of changes.

## Changes

- Change 1
- Change 2

---

**Application Links:**
[View Ticket](https://tinker.tinkerai.win/tickets/42) | [View Session](https://tinker.tinkerai.win/agent_sessions/123)
'

Getting Project Name

The project name is available via the get_ticket MCP tool response. For most Tinker deployments, use tinker:

Copy# Get ticket info to confirm project
ticket_info=$(get_ticket ticket_id: 42)
project_name="tinker"  # Default for main tinker project

ticket_url="https://${project_name}.tinkerai.win/tickets/42"

---

Critical DOs and DON'Ts