# Branch Workflow

> Branch and commit conventions that keep an agent's work reviewable — one branch per task, main stays clean, nothing force-pushed.

- Skill: `toruai/branch-workflow` (Agent Skill)
- Install (CLI): `npx skillmds add toruai/branch-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/toruai/branch-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ToruAI (https://skillmd.com/u/toruai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/toruai/branch-workflow

---


# Branch Workflow - Safe Autonomous Coding

All work happens on branches. Main stays clean. The user reviews before merge.

## Branch Naming

```
feat/TASK-ID-short-description    # New features
fix/TASK-ID-short-description     # Bug fixes
docs/TASK-ID-short-description    # Documentation
research/TASK-ID-description      # Exploration
refactor/TASK-ID-description      # Code improvements
```

**Examples:**
- `feat/API-142-rate-limiting`
- `fix/WEB-87-login-redirect`
- `docs/API-150-auth-guide`

## Commit Format

```
TASK-ID: Brief description of change

- Detail 1
- Detail 2

Co-Authored-By: Claude <co-author>
```

**Good commits:**
- Atomic (one logical change)
- Buildable (tests pass at each commit)
- Descriptive (explains what, not how)

## Workflow

### Starting Work
```bash
git checkout main
git pull origin main
git checkout -b feat/TASK-ID-description
```

### During Work
```bash
# Commit often
git add -A
git commit -m "TASK-ID: Implement X"

# Push periodically
git push -u origin feat/TASK-ID-description
```

### Finishing Work
```bash
# Ensure tests pass
cargo test  # or npm test, pytest, etc.

# Push final state
git push

# Log completion (megg or BACKLOG.md)
```

## Rules

### NEVER Do
- Push directly to main
- Force push (`git push --force`)
- Merge your own branches
- Delete branches without the user's approval
- Commit secrets or credentials

### ALWAYS Do
- Create branch before changing code
- Run tests before pushing
- Commit with clear messages
- Push branches for review
- Document decisions

## When Blocked

1. Push current work to branch
2. Document blocker in `.megg/blocked.md` or commit message
3. Move to next task
4. The user will review on return

## Review Workflow

The user reviews branches by:
```bash
# See all work
git branch -a

# Review specific branch
git log main..feat/BRANCH-NAME
git diff main..feat/BRANCH-NAME

# Merge if good
git checkout main
git merge feat/BRANCH-NAME
```

## Integration with OpenSpec

For OpenSpec changes:
- Branch name matches change ID: `feat/add-plugin-system`
- One branch per OpenSpec change
- Archive OpenSpec change only after merge

## Emergency Fixes

For critical bugs in production:
1. Create `hotfix/description` branch
2. Minimal fix only
3. Tests must pass
4. Document urgency in commit
5. Flag for immediate user review