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

git checkout main
git pull origin main
git checkout -b feat/TASK-ID-description

During Work

# Commit often
git add -A
git commit -m "TASK-ID: Implement X"

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

Finishing Work

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

# 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