roboco/docs/workflows/GIT_WORKFLOW.md

Git Workflow

Status: Implemented

This document describes the git workflow for RoboCo agents working on code tasks.

---

Multi-Agent Workspace Structure

Each agent gets their own isolated workspace (git clone) for a project. This allows multiple agents to work on the same project in parallel, each on their own branch, without file conflicts.

{workspaces_root}/
└── {project-slug}/
    └── {team}/
        └── {agent-slug}/
            └── [git repo files]

Example Structure

/data/workspaces/
└── roboco/
    ├── backend/
    │   ├── be-dev-1/    # Backend Developer 1's workspace
    │   ├── be-dev-2/    # Backend Developer 2's workspace
    │   ├── be-qa/       # Backend QA's workspace
    │   ├── be-pm/       # Backend PM's workspace
    │   └── be-doc/      # Backend Documenter's workspace
    ├── frontend/
    │   ├── fe-dev-1/
    │   ├── fe-dev-2/
    │   └── ...
    └── ux_ui/
        ├── ux-dev-1/
        └── ...

Workspace Features

• Auto-clone: When workspace_auto_clone is enabled, workspaces are automatically cloned when first accessed
• Isolation: Each agent has their own working tree - no file locking conflicts
• Branch independence: Agents can be on different branches simultaneously
• Project-scoped: Workspaces are organized by project slug

---

Branch Naming

Branches are created by PMs and include team context:

{type}/{team}/{task-id-prefix}

Types

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

Examples

feature/backend/a1b2c3d4
fix/frontend/e5f6g7h8
refactor/backend/i9j0k1l2

---

Commit Messages

Commits are automatically linked to tasks with a task ID prefix:

[{task-id-prefix}] {message}

Automatic Linking

When you use roboco_git_commit(), the commit:

1. Is prefixed with the task ID (first 8 chars)
2. Is recorded in the task's commit history
3. Is added to the work session if one exists

Manual Format

{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: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Co-authored-by: be-dev-1

---

Workflow

PM Setup Phase

1. PM CREATES TASK (status: backlog)
   │
   ▼
2. PM CREATES SESSION
   │  roboco_session_start(channel, "collaborative", task_id)
   │
   ▼
3. PM ACTIVATES TASK (status: pending)
   │  roboco_task_activate(task_id)
   │
   ▼
4. PM CREATES BRANCH
   │  roboco_git_create_branch(project_slug, task_id, "feature")
   │  → Creates: feature/{team}/{task-id-prefix}
   │  → Auto-pushes to remote with tracking
   │
   ▼
5. PM ASSIGNS DEVELOPER
   │  roboco_task_claim(task_id, agent_id="be-dev-1")

Developer Flow

1. CLAIM TASK
   │  roboco_task_claim(task_id)
   │
   ▼
2. START WORK (requires branch for git tasks)
   │  roboco_task_start(task_id)
   │
   ▼
3. CHECKOUT BRANCH
   │  roboco_git_checkout(project_slug, branch_name)
   │
   ▼
4. WORK & COMMIT
   │  # Multiple commits linked to task
   │  roboco_git_commit(project_slug, task_id, "add rate limiter")
   │  roboco_git_commit(project_slug, task_id, "add tests")
   │
   ▼
5. PUSH BRANCH
   │  roboco_git_push(project_slug)
   │
   ▼
6. SUBMIT FOR QA
   │  roboco_task_submit_qa(task_id, notes)
   │
   ▼
7. QA REVIEWS (on branch)
   │
   ├── PASS → Continue to Documentation
   └── FAIL → Task returns to needs_revision

QA Flow

QA reviews the code on the branch:

1. QA CLAIMS TASK
   │  roboco_task_claim(task_id)
   │
   ▼
2. QA CHECKS OUT BRANCH
   │  roboco_git_checkout(project_slug, branch_name)
   │
   ▼
3. QA REVIEWS
   │  roboco_git_status(project_slug)
   │  roboco_git_diff(project_slug)
   │  roboco_git_log(project_slug)
   │
   ├── PASS: roboco_task_pass_qa(task_id, notes)
   │         → Status: awaiting_documentation
   │
   └── FAIL: roboco_task_fail_qa(task_id, notes)
             → Status: needs_revision

Documentation Phase (Parallel Execution)

When a task reaches awaiting_documentation, two things happen in parallel:

                 awaiting_documentation
                          │
          ┌───────────────┴───────────────┐
          │                               │
     DOCUMENTER                      DEVELOPER
          │                               │
    writes docs                     creates PR
          │                               │
 roboco_task_docs_complete()    roboco_git_create_pr()
          │                               │
          │    sets docs_complete=True    │
          │                               │
          │      sets pr_created=True     │
          │                               │
          └───────────────┬───────────────┘
                          │
              BOTH must be true
                          │
                          ▼
                awaiting_pm_review

PR Creation

Developer creates PR after QA passes:

roboco_git_create_pr(
    project_slug="roboco",
    task_id="a1b2c3d4-...",
    title="[TASK-a1b2c3d4] Add rate limiting",
    body="## Summary\n- Implemented sliding window...\n\n## Test Plan\n..."
)

This:

• Creates PR via GitHub CLI (gh pr create)
• Targets the project's default branch
• Sets pr_created=True on the task
• Records PR number and URL on the task

---

PM Review and Completion

Standard Completion

1. TASK IN awaiting_pm_review
   │
   ▼
2. PM REVIEWS PR
   │  - Check commits: roboco_git_log(project_slug, branch)
   │  - Check changes: roboco_git_diff(project_slug)
   │
   ▼
3. PM COMPLETES TASK
   │  roboco_task_complete(task_id)
   │
   ▼
4. PM MERGES PR (Optional)
   │  roboco_git_merge_pr(project_slug, pr_number, "squash")

CEO Approval (Major Tasks)

For significant changes, PM escalates to CEO:

1. TASK IN awaiting_pm_review
   │
   ▼
2. PM ESCALATES TO CEO
   │  roboco_task_escalate_to_ceo(task_id, notes)
   │  → Status: awaiting_ceo_approval
   │  → Requires PR number to exist
   │
   ▼
3. CEO REVIEWS
   │
   ├── APPROVE: roboco_task_ceo_approve(task_id, notes)
   │            → Status: completed
   │
   └── REJECT: roboco_task_ceo_reject(task_id, notes)
               → Status: needs_revision
               → Assigned back to developer

---

Git API Endpoints

Read-Only Operations

Endpoint	Tool	Description
GET /git/status	roboco_git_status	Get git status for project
GET /git/log	roboco_git_log	Get commit history
GET /git/branches	roboco_git_branches	List branches
GET /git/diff	roboco_git_diff	View changes

Write Operations

Endpoint	Tool	Description
POST /git/commit	roboco_git_commit	Create commit linked to task
POST /git/push	roboco_git_push	Push to remote
POST /git/branch/create	roboco_git_create_branch	Create task branch (PM only)
POST /git/checkout	roboco_git_checkout	Checkout branch
POST /git/pr/create	roboco_git_create_pr	Create pull request
POST /git/pr/merge	roboco_git_merge_pr	Merge PR (PM only)

---

Git Requirements for Transitions

Tasks with requires_git=True have additional validation:

claimed -> in_progress

• Requirement: branch_name must be set
• Why: PM must create branch before developer can start

awaiting_documentation -> awaiting_pm_review

• Requirements: BOTH docs_complete=True AND pr_created=True
• Why: Parallel workflow - documenter and developer must both finish

awaiting_pm_review -> awaiting_ceo_approval

• Requirement: pr_number must be set
• Why: CEO needs to review the PR before final approval

---

Branch Protection (Main)

• No direct pushes
• PR required
• QA must pass
• PM approval required
• CI must pass (when configured)

---

Handling QA Failures

QA finds issues
      │
      ▼
Developer gets task back (needs_revision)
      │
      ▼
Developer claims, continues on SAME branch
      │
      ▼
Fix commits:
  roboco_git_commit(project_slug, task_id, "fix edge case X")
      │
      ▼
Push to same branch
  roboco_git_push(project_slug)
      │
      ▼
Re-submit for QA
  roboco_task_submit_qa(task_id, "Fixed issues noted in QA")

---

Commit Linking

Every commit made through roboco_git_commit is:

1. Prefixed with task ID (first 8 chars)
2. Recorded in task.commits array
3. Linked to work session if active
4. Attributed to the committing agent

This creates full traceability from commit back to task.