roboco/docs/workflows/GIT_WORKFLOW.md

Git Workflow (Future)

Status: Planned - Not yet implemented

This document describes the intended git workflow for when code tools are added.

---

Branch Naming

{type}/{task-id}-{short-description}

Types

Type	Use
feature/	New functionality
fix/	Bug fixes
refactor/	Code restructuring
docs/	Documentation
test/	Test additions
chore/	Maintenance

Examples

feature/TASK-042-rate-limiter
fix/TASK-055-auth-token-expiry
refactor/TASK-067-extract-service
docs/TASK-089-api-documentation

---

Commit Messages

{type}({scope}): {description}

{body}

Task: {task-id}
Co-authored-by: {agent-name}

Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation
style	Formatting
refactor	Code restructure
test	Tests
chore	Maintenance
perf	Performance

Example

feat(auth): add Redis-based rate limiting

Implements sliding window rate limiter using Redis.
- Configurable limits per endpoint
- Lua script for atomic operations
- Returns rate limit headers

Task: TASK-042
Co-authored-by: be-dev-1

---

Workflow

Developer Flow

1. CLAIM TASK
   │
   ▼
2. CREATE BRANCH
   │
   │  git checkout -b feature/TASK-042-rate-limiter
   │
   ▼
3. WORK & COMMIT
   │
   │  # Multiple small commits
   │  git commit -m "feat(auth): add rate limit decorator"
   │  git commit -m "feat(auth): integrate Redis counter"
   │  git commit -m "test(auth): add rate limit tests"
   │
   ▼
4. PUSH BRANCH
   │
   │  git push -u origin feature/TASK-042-rate-limiter
   │
   ▼
5. SUBMIT FOR QA
   │
   │  roboco_task_submit_qa(task_id, notes)
   │
   ▼
6. QA REVIEWS (on branch)
   │
   ├── PASS → Continue
   └── FAIL → Fix on same branch, re-push
   │
   ▼
7. CREATE PR (after QA pass)
   │
   │  Target: main (or develop)
   │  Title: [TASK-042] Add rate limiting
   │  Body: Summary + test plan
   │
   ▼
8. PM REVIEWS PR
   │
   ▼
9. MERGE
   │
   │  Squash merge preferred
   │
   ▼
10. CLEANUP
    │
    │  Delete feature branch

---

Branch Protection (Main)

• No direct pushes
• PR required
• QA must pass
• PM approval required
• CI must pass

---

Commit Frequency

Stage	Commit Frequency
During development	Frequently (logical chunks)
Before QA	Ensure all changes committed
After QA feedback	Fix commits
Before merge	Squash if messy

---

Handling QA Failures

QA finds issues
      │
      ▼
Developer gets task back (needs_revision)
      │
      ▼
Developer claims, continues on SAME branch
      │
      ▼
Fix commits:
  git commit -m "fix(auth): handle edge case X"
      │
      ▼
Push to same branch
      │
      ▼
Re-submit for QA

---

Planned Git Tools

Tool	Purpose
roboco_git_branch	Create task branch
roboco_git_commit	Create commit with task link
roboco_git_push	Push to remote
roboco_git_pr	Create pull request
roboco_git_status	Check branch state

---

Integration with Task System

When implemented:

• Branch creation linked to task claim
• Commits linked to task in metadata
• PR creation triggers PM review
• Merge triggers completion flow