mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
21 KiB
21 KiB
Task Status Transitions
Complete Lifecycle
┌─────────────────────────────────────────────────────────────────────────────────┐
│ FULL TASK LIFECYCLE │
└─────────────────────────────────────────────────────────────────────────────────┘
PM CREATES
│
▼
┌──────────┐
│ BACKLOG │ ◄─── PM setup phase
└────┬─────┘ (create session, plan)
│
PM ACTIVATES
│
▼
┌──────────┐
┌──────│ PENDING │◄─────────────────────────────────┐
│ └────┬─────┘ │
│ │ │
DEV or QA DEV or PM │
CLAIMS ASSIGNS │
│ │ │
▼ ▼ │
┌──────────┐ │
│ CLAIMED │ ◄─── Agent owns it │
└────┬─────┘ │
│ │
DEV STARTS │
│ │
▼ │
┌─────────────┐ │
┌──────────│ IN_PROGRESS │──────────┐ │
│ └──────┬──────┘ │ │
│ │ │ │
BLOCKED PAUSED WORKING │
│ │ │ │
▼ ▼ │ │
┌──────────┐ ┌─────────┐ │ │
│ BLOCKED │ │ PAUSED │ │ │
└────┬─────┘ └────┬────┘ │ │
│ │ │ │
UNBLOCK RESUME │ │
│ │ │ │
└────────►───────►└─────────►───────┘ │
│ │
DEV VERIFIES │
│ │
▼ │
┌───────────┐ │
│ VERIFYING │ ◄─── Self-check │
└─────┬─────┘ │
│ │
DEV SUBMITS QA │
│ │
▼ │
┌─────────────┐ │
│ AWAITING_QA │ ◄─── QA picks up │
└──────┬──────┘ │
│ │
┌───────────┴───────────┐ │
│ │ │
QA PASS QA FAIL │
│ │ │
▼ ▼ │
┌───────────────────────────┐ ┌─────────────────┐ │
│ AWAITING_DOCUMENTATION │ │ NEEDS_REVISION │───────────────────┘
└───────────┬───────────────┘ └─────────────────┘
│ (back to dev)
DOCS COMPLETE
│
▼
┌────────────────────┐
│ AWAITING_PM_REVIEW │ ◄─── PM final review
└─────────┬──────────┘
│
┌───────┴───────┐
│ │
PM COMPLETES PM ESCALATES
(simple tasks) (major tasks)
│ │
│ ▼
│ ┌────────────────────────┐
│ │ AWAITING_CEO_APPROVAL │ ◄─── CEO final decision
│ └──────────┬─────────────┘
│ │
│ ┌───────┴───────┐
│ │ │
│ CEO APPROVES CEO REJECTS
│ │ │
│ │ ▼
│ │ ┌─────────────────┐
│ │ │ NEEDS_REVISION │───────► (back to dev)
│ │ └─────────────────┘
│ │
└───────┴───────┐
│
▼
┌───────────┐
│ COMPLETED │
└───────────┘
Status Definitions
| Status | Description | Who Owns It |
|---|---|---|
backlog |
PM is setting up the task | PM |
pending |
Ready for someone to claim | Unassigned or pre-assigned |
claimed |
Agent has taken ownership | Developer/QA/Documenter |
in_progress |
Active work happening | Developer/QA/Documenter |
blocked |
Waiting on another task | Developer |
paused |
Temporarily stopped | Developer |
verifying |
Developer self-checking | Developer |
awaiting_qa |
Ready for QA review | QA |
needs_revision |
QA found issues | Developer |
awaiting_documentation |
QA passed, needs docs | Documenter |
awaiting_pm_review |
Docs done, PM reviews | PM |
awaiting_ceo_approval |
Major task, CEO decides | CEO |
completed |
Done | - |
cancelled |
Cancelled | - |
Transition Rules
Who Can Trigger What
| Transition | Triggered By | Tool |
|---|---|---|
| backlog → pending | PM | roboco_task_activate() |
| pending → claimed | Any agent | roboco_task_claim() |
| claimed → in_progress | Owner | roboco_task_start() |
| in_progress → blocked | Owner | roboco_task_block() |
| in_progress → paused | Owner | roboco_task_pause() |
| blocked → in_progress | Owner or PM | roboco_task_unblock() |
| paused → in_progress | Owner | roboco_task_start() (resume) |
| in_progress → verifying | Developer | roboco_task_submit_verification() |
| verifying → awaiting_qa | Developer | roboco_task_submit_qa() |
| awaiting_qa → claimed | QA | roboco_task_claim() |
| awaiting_qa → awaiting_documentation | QA | roboco_task_qa_pass() |
| awaiting_qa → needs_revision | QA | roboco_task_qa_fail() |
| needs_revision → claimed | Developer | roboco_task_claim() |
| awaiting_documentation → claimed | Documenter | roboco_task_claim() |
| awaiting_documentation → awaiting_pm_review | Documenter | roboco_task_docs_complete() |
| awaiting_pm_review → completed | PM | roboco_task_complete() |
| awaiting_pm_review → awaiting_ceo_approval | PM | roboco_task_escalate_to_ceo() |
| awaiting_ceo_approval → completed | CEO | roboco_task_ceo_approve() |
| awaiting_ceo_approval → needs_revision | CEO | roboco_task_ceo_reject() |
| any → cancelled | PM/CEO | roboco_task_cancel() |
| in_progress → pending/blocked/awaiting_qa | Owner | roboco_task_substitute() |
| in_progress → awaiting_pm_review | Any agent | roboco_task_submit_pm_review() |
What Each Role Can Claim
| Role | Can Claim From |
|---|---|
| Developer | pending, needs_revision |
| QA | awaiting_qa |
| Documenter | pending, awaiting_documentation |
| PM | pending, backlog |
Blocking Rules
An agent CANNOT claim a new task if they have:
- A task in
in_progress - A task in
claimed(should start it first) - A task in
verifying(should submit to QA first)
An agent CAN claim even if they have:
- A task in
paused(can work on something else while waiting) - A task in
blocked(can work on something else while waiting)
Exception: If claiming a task already assigned to them (PM pre-assigned), the blocking check is skipped for THAT specific task.
Substitution (Graceful Exit)
Agents can substitute out of a task when they cannot continue:
roboco_task_substitute(task_id, reason, details)
| Reason | New Status | When to Use |
|---|---|---|
low_context |
pending | Insufficient context to continue safely |
out_of_scope_team |
pending | Task belongs to different team |
out_of_scope_role |
pending | Task requires different role (QA, not dev) |
task_complete |
awaiting_qa | Finished work, releasing for next stage |
max_retries |
pending | Exceeded retry limit, need fresh perspective |
blocked_external |
blocked | Need skills outside your capabilities |
Key: Substitution BYPASSES the "can't claim while in_progress" rule. After substituting, you are free to claim new work.
Direct PM Submission (Alternate Path)
For non-dev tasks that don't need QA review:
roboco_task_submit_pm_review(task_id, notes)
Status: in_progress → awaiting_pm_review
Use for: validation tasks, audits, research, or any task assigned directly that doesn't produce code.
Automatic PM Assignment
The system automatically assigns tasks to the responsible PM and sends notifications in these cases:
| Trigger | New Status | PM Assigned | Notification |
|---|---|---|---|
roboco_task_docs_complete() |
awaiting_pm_review | Cell PM (or Main PM) | ✅ task_assignment |
roboco_task_submit_pm_review() |
awaiting_pm_review | Cell PM (or Main PM) | ✅ task_assignment |
roboco_task_substitute() with task_complete (QA/Documenter) |
awaiting_pm_review | Cell PM | ✅ task_assignment |
roboco_task_unblock() |
in_progress | (unchanged) | ✅ to assigned agent |
PM Resolution Chain:
- Get PM for the agent's role (QA → Cell PM, Cell PM → Main PM)
- Fallback to team PM (backend → be-pm, frontend → fe-pm)
- Task is assigned to resolved PM's UUID
- Real-time notification delivered via Redis Streams
CEO Approval Workflow
For major tasks that require executive sign-off, PMs can escalate to CEO:
When to Escalate to CEO
| Task Type | Escalate? | Reason |
|---|---|---|
| Parent task with subtasks | ✅ Yes | Aggregate work needs final approval |
| Breaking changes | ✅ Yes | Architectural impact |
| High-priority features | ✅ Yes | Business-critical |
| Security changes | ✅ Yes | Risk assessment |
| Simple bug fixes | ❌ No | PM can complete directly |
| Documentation updates | ❌ No | PM can complete directly |
Escalation Flow
PM reviews task in awaiting_pm_review
│
├─── Simple task? → roboco_task_complete() → COMPLETED
│
└─── Major task? → roboco_task_escalate_to_ceo(notes) → AWAITING_CEO_APPROVAL
│
▼
CEO receives notification
│
┌───────────────┴───────────────┐
│ │
CEO APPROVES CEO REJECTS
roboco_task_ceo_approve() roboco_task_ceo_reject(reason)
│ │
▼ ▼
COMPLETED NEEDS_REVISION
(back to developer)
CEO Actions (Human-in-the-Loop)
The CEO is human and receives notifications when tasks are escalated. CEO uses the API directly:
| API Endpoint | Description |
|---|---|
POST /api/v1/tasks/{id}/ceo-approve |
Approve and complete the task |
POST /api/v1/tasks/{id}/ceo-reject |
Reject and send back for revision |
Note: PM escalation automatically sends a high-priority notification to the CEO.
Git Integration
Tasks with requires_git=True follow the git workflow alongside the task lifecycle.
Git Workflow Overview
PM creates branch ──► Dev checkouts ──► Dev commits ──► Dev pushes ──► QA reviews on branch
│
▼
[QA PASSES]
│
┌─────────────────────────┴─────────────────────────┐
│ PARALLEL EXECUTION │
│ (awaiting_documentation) │
│ │
▼ ▼
Documenter Developer
writes docs ──► reviews all ──►
commits docs ──► creates PR ──►
docs_complete=True pr_created=True
│ │
└───────────────────┬───────────────────────────────┘
│
[BOTH complete]
│
▼
awaiting_pm_review
│
PM(s) review PR
│
▼
awaiting_ceo_approval
│
CEO merges PR
│
▼
completed
Branch Naming Convention
{reason}/{team}/{task-id}[/{subtask-id}]
| Reason | Description |
|---|---|
feature |
New functionality |
bug |
Bug fix |
chore |
Maintenance, refactoring |
docs |
Documentation-only changes |
hotfix |
Urgent production fix |
Examples:
feature/backend/abc123- Parent task branchfeature/backend/abc123/xyz789- Subtask branchbug/frontend/def456- Bug fix branch
Git Operations by Role
| Role | Git Operations |
|---|---|
| Main PM | Create parent branches from main |
| Cell PM | Create subtask branches from parent, merge subtask PRs |
| Developer | Checkout, commit, push, create PR |
| QA | Read-only (review code on branch) |
| Documenter | Read + commit docs to branch |
| CEO | Merge final PR to main |
Parallel Execution in awaiting_documentation
When QA passes, the task enters awaiting_documentation. Two things happen in parallel:
- Documenter is notified and writes documentation, commits to branch
- Developer is notified and reviews everything, creates the PR
The task has two flags:
docs_complete- Set when documenter callsroboco_task_docs_complete()pr_created- Set when developer callsroboco_git_create_pr()
The task only moves to awaiting_pm_review when BOTH flags are true.
Hierarchical Branch Strategy
main
│
└── feature/backend/ABC123 ← Main PM creates (parent task)
│ Forks from: main
│
├── feature/backend/ABC123/XYZ789 ← Cell PM creates (subtask)
│ │ Forks from: parent branch
│ └── MERGES INTO: parent branch ↑ (Cell PM approves)
│
└── feature/backend/ABC123/QRS456 ← Cell PM creates (subtask)
│ Forks from: parent branch
└── MERGES INTO: parent branch ↑ (Cell PM approves)
When all subtasks merged:
feature/backend/ABC123 ──► PR to main ──► Main PM + Cell PM review ──► CEO merges
Git Tools Reference
Read-Only (All Agents):
roboco_git_status(project_slug)- Branch and file statusroboco_git_log(project_slug, limit)- Commit historyroboco_git_branch_list(project_slug)- List branchesroboco_git_diff(project_slug, staged)- View changes
Developer:
roboco_git_commit(project_slug, message, task_id)- Create commitroboco_git_push(project_slug, task_id)- Push to remoteroboco_git_create_pr(project_slug, task_id, title, body)- Create PR
PM:
roboco_git_create_branch(project_slug, task_id, branch_type, parent_branch)- Create branchroboco_git_checkout(project_slug, branch)- Switch branchesroboco_git_merge_pr(project_slug, pr_number, task_id, merge_method)- Merge PR