External/roboco
1
0
Fork 0
mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

Adjusted documentation

Browse Source
This commit is contained in:
Renn F
2025-12-30 19:37:03 +01:00
parent d7e93ece25
commit eedf06d18a
12 changed files with 3056 additions and 482 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workflows/GIT_WORKFLOW.md
+277 -74
View File
@@ -1,15 +1,58 @@
# Git Workflow (Future)
# Git Workflow
> **Status:** Planned - Not yet implemented
> **Status:** Implemented
>
> This document describes the intended git workflow for when code tools are added.
> 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}/{task-id}-{short-description}
{type}/{team}/{task-id-prefix}
```
### Types
@@ -26,16 +69,30 @@
### Examples
```
feature/TASK-042-rate-limiter
fix/TASK-055-auth-token-expiry
refactor/TASK-067-extract-service
docs/TASK-089-api-documentation
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}
@@ -68,7 +125,7 @@ Implements sliding window rate limiter using Redis.
- Lua script for atomic operations
- Returns rate limit headers
Task: TASK-042
Task: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Co-authored-by: be-dev-1
```
@@ -76,61 +133,225 @@ 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. CREATE BRANCH
│
│ git checkout -b feature/TASK-042-rate-limiter
2. START WORK (requires branch for git tasks)
│ roboco_task_start(task_id)
│
▼
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"
3. CHECKOUT BRANCH
│ roboco_git_checkout(project_slug, branch_name)
│
▼
4. PUSH BRANCH
│
│ git push -u origin feature/TASK-042-rate-limiter
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. SUBMIT FOR QA
5. PUSH BRANCH
│ roboco_git_push(project_slug)
│
▼
6. SUBMIT FOR QA
│ roboco_task_submit_qa(task_id, notes)
│
▼
6. QA REVIEWS (on branch)
7. 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
├── 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)
@@ -139,18 +360,7 @@ Co-authored-by: be-dev-1
- 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 |
- CI must pass (when configured)
---
@@ -167,33 +377,26 @@ Developer claims, continues on SAME branch
│
▼
Fix commits:
git commit -m "fix(auth): handle edge case X"
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")
```
---
## Planned Git Tools
## Commit Linking
| 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 |
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
## 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
This creates full traceability from commit back to task.