mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
403 lines
9.5 KiB
Markdown
403 lines
9.5 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
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.
|