mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
16 KiB
16 KiB
Task Lifecycle Standards
Comprehensive standards for task management in the RoboCo system. These standards are derived from the actual implementation in the codebase.
Source Files:
- Task Status Enum:
roboco/models/base.py(lines 19-34) - Lifecycle Enforcement:
roboco/enforcement/task_lifecycle.py - Task Service:
roboco/services/task.py
Table of Contents
- Task States
- Valid Transitions
- Role-Restricted Transitions
- Task Service Methods
- Workflow by Role
- Quality Gates
- State Categories
Task States
WF-001: TaskStatus Enum
Source: roboco/models/base.py
class TaskStatus(str, Enum):
"""Task lifecycle states."""
BACKLOG = "backlog" # PM setup phase
PENDING = "pending" # Ready for work
CLAIMED = "claimed" # Agent has ownership
IN_PROGRESS = "in_progress" # Active work
BLOCKED = "blocked" # Waiting on dependency
PAUSED = "paused" # Temporarily stopped
VERIFYING = "verifying" # Self-verification
NEEDS_REVISION = "needs_revision"# QA rejected
AWAITING_QA = "awaiting_qa" # Ready for QA
AWAITING_DOCUMENTATION = "awaiting_documentation" # QA passed
AWAITING_PM_REVIEW = "awaiting_pm_review" # Docs done
COMPLETED = "completed" # TERMINAL
CANCELLED = "cancelled" # TERMINAL
WF-002: State Diagram
PM CREATES
│
▼
┌──────────┐
│ BACKLOG │───► cancelled
└────┬─────┘
│ activate()
▼
┌──────────┐
┌──────│ PENDING │◄─────────────────────────────────┐
│ └────┬─────┘───► cancelled │
│ │ │
│ claim() │
│ │ │
▼ ▼ │
┌──────────┐ │
│ CLAIMED │───► pending, cancelled │
└────┬─────┘ │
│ start() │
▼ │
┌─────────────┐ │
┌──────────│ IN_PROGRESS │───► completed, cancelled │
│ └──────┬──────┘ │
│ │ │
block() pause() │
│ │ │
▼ ▼ │
┌──────────┐ ┌─────────┐ │
│ BLOCKED │ │ PAUSED │ │
└────┬─────┘ └────┬────┘ │
│ │ │
unblock() resume() │
│ │ │
└────────►───────►└──────►──────┐ │
│ │
submit_for_verification() │
│ │
▼ │
┌───────────┐ │
│ VERIFYING │───► cancelled │
└─────┬─────┘ │
│ │
┌───────────────────────┼───────────────────────┐ │
│ │ │ │
submit_for_qa() needs_revision direct to docs│
│ │ │ │
▼ ▼ ▼ │
┌─────────────┐ ┌─────────────────┐ ┌─────────────────────┐
│ AWAITING_QA │◄───────│ NEEDS_REVISION │──│ AWAITING_DOCUMENTATION│
└──────┬──────┘ └─────────────────┘ └──────────┬──────────┘
│ ▲ │
┌─────────┼─────────┐ │ │
│ │ │ │ docs_complete()
pass_qa() fail_qa() block │ │
│ │ │ │ ▼
│ └─────────┴───────────────┘ ┌────────────────────┐
│ │ AWAITING_PM_REVIEW │
└────────────────────────────────────────────────└─────────┬──────────┘
│
complete()
│
▼
┌───────────┐
│ COMPLETED │
└───────────┘
Valid Transitions
WF-010: Transition Matrix
Source: roboco/enforcement/task_lifecycle.py (lines 17-56)
| From Status | Valid Next States |
|---|---|
backlog |
pending, cancelled |
pending |
claimed, cancelled |
claimed |
in_progress, pending, cancelled |
in_progress |
blocked, paused, verifying, completed, cancelled |
blocked |
in_progress, cancelled |
paused |
in_progress, cancelled |
verifying |
awaiting_qa, needs_revision, awaiting_documentation, cancelled |
needs_revision |
claimed, in_progress, cancelled |
awaiting_qa |
claimed, awaiting_documentation, needs_revision, blocked, cancelled |
awaiting_documentation |
claimed, awaiting_pm_review, cancelled |
awaiting_pm_review |
claimed, completed, cancelled |
completed |
(TERMINAL - no transitions) |
cancelled |
(TERMINAL - no transitions) |
WF-011: Invalid Transitions
Any transition NOT in the matrix above will raise InvalidTransitionError.
from roboco.enforcement.task_lifecycle import validate_task_transition
# This will raise InvalidTransitionError
validate_task_transition(
TaskStatus.PENDING,
TaskStatus.COMPLETED, # Cannot skip the workflow!
agent_role="developer"
)
Role-Restricted Transitions
WF-020: Permission Matrix
Source: roboco/enforcement/task_lifecycle.py (lines 66-93)
Certain transitions require specific roles:
| Transition | Allowed Roles |
|---|---|
backlog → pending |
cell_pm, main_pm, product_owner, head_marketing |
awaiting_qa → claimed |
qa |
awaiting_qa → awaiting_documentation |
qa |
awaiting_qa → needs_revision |
qa |
awaiting_documentation → claimed |
documenter |
awaiting_documentation → awaiting_pm_review |
documenter |
awaiting_pm_review → claimed |
cell_pm, main_pm, product_owner, head_marketing |
awaiting_pm_review → completed |
cell_pm, main_pm, product_owner, head_marketing |
in_progress → completed |
cell_pm, main_pm, product_owner, head_marketing |
* → cancelled |
cell_pm, main_pm, product_owner, head_marketing |
WF-021: Role Validation
from roboco.enforcement.task_lifecycle import can_agent_transition
# Check if role can make transition
if can_agent_transition(
current_status=TaskStatus.AWAITING_QA,
new_status=TaskStatus.AWAITING_DOCUMENTATION,
agent_role="developer" # False - only QA can do this
):
# proceed
Task Service Methods
WF-030: Status Change Methods
Source: roboco/services/task.py
| Method | Status Change | Calling Roles |
|---|---|---|
activate() |
BACKLOG → PENDING | PM roles |
claim() |
→ CLAIMED | developer, qa, documenter (based on current status) |
start() |
CLAIMED/PAUSED/NEEDS_REVISION → IN_PROGRESS | Owner |
block() |
IN_PROGRESS → BLOCKED | Owner |
soft_block() |
IN_PROGRESS → BLOCKED | Owner (external factor) |
unblock() |
BLOCKED → IN_PROGRESS | Owner or PM |
pause() |
IN_PROGRESS → PAUSED | Owner |
resume() |
PAUSED → IN_PROGRESS | Owner |
submit_for_verification() |
IN_PROGRESS → VERIFYING | Developer |
submit_for_qa() |
VERIFYING → AWAITING_QA | Developer |
pass_qa() |
AWAITING_QA → AWAITING_DOCUMENTATION | QA |
fail_qa() |
AWAITING_QA → NEEDS_REVISION | QA |
docs_complete() |
AWAITING_DOCUMENTATION → AWAITING_PM_REVIEW | Documenter |
submit_for_pm_review() |
IN_PROGRESS → AWAITING_PM_REVIEW | Any (non-dev tasks) |
complete() |
AWAITING_PM_REVIEW → COMPLETED | PM roles |
cancel() |
ANY → CANCELLED | PM roles |
WF-031: Core Validation Method
All status changes go through _validate_and_set_status():
def _validate_and_set_status(
self,
task: TaskTable,
new_status: TaskStatus,
agent_role: str | None = None,
) -> None:
"""
Validate and set task status with lifecycle enforcement.
This is the single point of truth for status changes.
"""
Workflow by Role
WF-040: Developer Workflow
PENDING
│ claim()
▼
CLAIMED
│ start()
▼
IN_PROGRESS ←──────────────┐
│ │
│ submit_for_ │ (from NEEDS_REVISION)
│ verification() │
▼ │
VERIFYING │
│ │
│ submit_for_qa() │
▼ │
AWAITING_QA ──fail_qa()──► NEEDS_REVISION
│ │
│ pass_qa() (by QA) │ claim() + start()
▼ │
[QA/Docs workflow] └───────────────────┘
Developer can:
- Claim
pendingandneeds_revisiontasks - Start, pause, resume work
- Submit for verification and QA
- Block (with dependency)
Developer cannot:
- Pass/fail QA (that's QA's job)
- Complete tasks (that's PM's job)
- Cancel tasks
WF-041: QA Workflow
AWAITING_QA
│ claim()
▼
CLAIMED (QA owns)
│ start()
▼
IN_PROGRESS
│
├── pass_qa() ────► AWAITING_DOCUMENTATION
│
└── fail_qa() ────► NEEDS_REVISION (reassigned to developer)
QA can:
- Claim
awaiting_qatasks only - Pass or fail QA
- Block tasks
QA cannot:
- Claim pending tasks (developers do that)
- Complete documentation
- Complete tasks
WF-042: Documenter Workflow
AWAITING_DOCUMENTATION
│ claim()
▼
CLAIMED (Documenter owns)
│ start()
▼
IN_PROGRESS
│ docs_complete()
▼
AWAITING_PM_REVIEW
Documenter can:
- Claim
awaiting_documentationtasks - Complete documentation
Documenter cannot:
- Claim pending tasks
- Pass/fail QA
- Complete tasks
WF-043: PM Workflow
BACKLOG
│ activate()
▼
PENDING
│ (developers claim)
...
▼
AWAITING_PM_REVIEW
│ complete()
▼
COMPLETED
PM can:
- Create tasks in backlog
- Activate backlog → pending
- Complete awaiting_pm_review tasks
- Cancel any task
- Unblock blocked tasks
Quality Gates
WF-050: Before Claiming
- [ ] Task is in valid claim status for your role
- [ ] No existing in_progress task (one at a time)
- [ ] Dependencies are completed
WF-051: Before Starting
- [ ] Task is claimed by you
- [ ] Plan is documented
- [ ] Cell channel notified
WF-052: Before Submit to QA
- [ ] Tests passing: `uv run pytest`
- [ ] Linting clean: `uv run ruff check .`
- [ ] Type check: `uv run mypy roboco/`
- [ ] Self-review completed
- [ ] Journal reflection written
WF-053: Before Completion
- [ ] QA approved
- [ ] Documentation complete
- [ ] PM review approved
State Categories
WF-060: Helper Functions
Source: roboco/enforcement/task_lifecycle.py
| Function | Returns True For |
|---|---|
is_terminal_state() |
completed, cancelled |
is_waiting_state() |
blocked, paused, awaiting_qa, awaiting_documentation, awaiting_pm_review |
is_active_state() |
claimed, in_progress, verifying, needs_revision |
WF-061: Terminal States
Once a task reaches COMPLETED or CANCELLED, no further transitions are possible.
get_valid_transitions(TaskStatus.COMPLETED) # Returns []
get_valid_transitions(TaskStatus.CANCELLED) # Returns []
WF-062: Waiting States
Tasks in waiting states are "on hold" pending some external action:
BLOCKED- Waiting for blocker taskPAUSED- Waiting for agent to resumeAWAITING_QA- Waiting for QA reviewAWAITING_DOCUMENTATION- Waiting for docsAWAITING_PM_REVIEW- Waiting for PM approval
WF-063: Active States
Tasks where an agent is actively working:
CLAIMED- Agent owns, about to startIN_PROGRESS- Active developmentVERIFYING- Self-verificationNEEDS_REVISION- Fixing QA issues
Quick Reference
Valid Claim Statuses by Role
| Role | Can Claim From |
|---|---|
| Developer | pending, needs_revision |
| QA | awaiting_qa |
| Documenter | awaiting_documentation |
| PM | pending, backlog |
Common Status Flows
Happy Path:
backlog → pending → claimed → in_progress → verifying → awaiting_qa
→ awaiting_documentation → awaiting_pm_review → completed
QA Rejection:
awaiting_qa → needs_revision → claimed → in_progress → verifying → awaiting_qa
Direct PM Review (non-dev task):
pending → claimed → in_progress → awaiting_pm_review → completed
Cancellation:
any_state → cancelled