name: git-workflow description: > Use this skill when the user asks to commit changes, create a branch, open a pull request, or update a PR description.

Git & PR Workflow

Read this file fully before taking any git or PR action.

Branches

Each issue gets its own git worktree, created by running python3 scripts/start_issue.py XCE-123 from the main repo. The branch name is the Linear issue ID (e.g. XCE-123), branched from dev.

Do not create branches manually. If no worktree exists yet, ask the user to run the start script first.

Commits

Format

Type - Short description of what changed and why

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Types

Rules

• One concern per commit — don't bundle unrelated changes
• Stage specific files by name, never git add . or git add -A
• Always pass the commit message via heredoc to preserve formatting:

git commit -m "$(cat <<'EOF'
Type - Description of change

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

Pull Requests

GitHub Tool Reference

Flow

1. Make commits (one concern per commit)
2. Push: git push -u origin <branch-name>
3. A PR is automatically created — never create one manually unless the user explicitly asks
   • Wait a few seconds, then run gh pr list --head <branch-name> to confirm it exists and get the PR number
   • If the auto-created PR does not appear after waiting, check again before considering any other action (this could take up to 30s)
4. Only update the PR title and description after all commits are pushed. GitHub wipes any custom description on each push — set it once, at the very end.
5. Fetch the Linear issue title using mcp__linear__get_issue, then update the PR title and description together using mcp__github__update_pull_request:
   • Title: Type - <Linear issue title> (e.g. Feat - Add logout button to profile screen)
   • Body: see PR Description Format below
6. Verify both were applied: gh pr view <number> --json title,body -q '{title:.title,body:.body}'
   • If either still shows auto-generated content, re-run step 5

This is where the agent's job ends. Tell the user the PR is ready for review, and remind them:

• For a subissue: run /done XCE-101 to mark it Done (worktree stays open for remaining subissues)
• For a top-level issue: run /done to mark it Done and clean up the worktree

PR Description Format

## Summary
- [bullet point summary of what changed and why]
- ...

## Test plan
- [ ] [what to manually verify or what tests to run]
- [ ] ...

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

Rules

• Base branch is always dev (not main)
• Keep the title short and in the same format as commits: Type - Description
• Do not push to main directly
• Do not force-push unless the user explicitly asks

What Not to Do

• Don't git add . — stage files explicitly
• Don't skip Co-Authored-By in commit messages
• Don't create branches or PRs manually — branches come from the start script, PRs are auto-created on push
• Don't amend published commits
• Don't push to main
• Don't mark Linear issues Done — that is always the user's step via /done