mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Adjusted documentation
This commit is contained in:
Renn F
@@ -0,0 +1,302 @@
|
||||
# Task Lifecycle
|
||||
|
||||
This document describes all task states, valid transitions, and workflow enforcement in the RoboCo system.
|
||||
|
||||
## Task States
|
||||
|
||||
Tasks follow a defined lifecycle from creation to completion. Each state represents a specific phase of work.
|
||||
|
||||
### State Definitions
|
||||
|
||||
| State | Description |
|
||||
|-------|-------------|
|
||||
| `backlog` | PM setup phase - task with dependencies or needs session setup |
|
||||
| `pending` | Ready for work - orchestrator can spawn agents |
|
||||
| `claimed` | Agent has taken ownership but not started |
|
||||
| `in_progress` | Active work being performed |
|
||||
| `blocked` | Waiting on another task or external dependency |
|
||||
| `paused` | Temporarily suspended by the assigned agent |
|
||||
| `verifying` | Self-verification by the developer |
|
||||
| `needs_revision` | QA or CEO has requested changes |
|
||||
| `awaiting_qa` | Ready for QA review |
|
||||
| `awaiting_documentation` | Docs + Developer PR creation in parallel |
|
||||
| `awaiting_pm_review` | After docs + PR ready, PM reviews |
|
||||
| `awaiting_ceo_approval` | PMs approved, CEO makes final decision |
|
||||
| `completed` | Task finished successfully (terminal) |
|
||||
| `cancelled` | Task cancelled (terminal) |
|
||||
| `quarantined` | Special state for problematic tasks |
|
||||
|
||||
### State Categories
|
||||
|
||||
```python
|
||||
# Terminal states - cannot transition out
|
||||
TERMINAL_STATES = ["completed", "cancelled"]
|
||||
|
||||
# Waiting states - agent can work on other tasks
|
||||
WAITING_STATES = [
|
||||
"blocked",
|
||||
"paused",
|
||||
"awaiting_qa",
|
||||
"awaiting_documentation",
|
||||
"awaiting_pm_review",
|
||||
"awaiting_ceo_approval",
|
||||
]
|
||||
|
||||
# Active states - agent is actively working
|
||||
ACTIVE_STATES = ["claimed", "in_progress", "verifying", "needs_revision"]
|
||||
```
|
||||
|
||||
## State Transition Diagram
|
||||
|
||||
```
|
||||
+-----------+
|
||||
| quarantined|
|
||||
+-----+-----+
|
||||
|
|
||||
v
|
||||
+--------+ +----------+ +---------+ +-------------+
|
||||
| backlog| --> | pending | --> | claimed | --> | in_progress |
|
||||
+---+----+ +----+-----+ +----+----+ +------+------+
|
||||
| | | |
|
||||
v v v |
|
||||
+---------+ +---------+ +-----------+ |
|
||||
|cancelled| |cancelled| | pending | |
|
||||
+---------+ +---------+ |(unclaim) | |
|
||||
+-----------+ |
|
||||
|
|
||||
+-----------------------------------+
|
||||
| | | |
|
||||
v v v v
|
||||
+----------+ +----------+ +---------+
|
||||
| blocked | | paused | |verifying|
|
||||
+----+-----+ +----+-----+ +----+----+
|
||||
| | |
|
||||
v v |
|
||||
in_progress in_progress |
|
||||
|
|
||||
+-----------------------------+
|
||||
| | |
|
||||
v v v
|
||||
+-------------+ +---------------+ +---------------------+
|
||||
| awaiting_qa | |needs_revision | |awaiting_documentation|
|
||||
+------+------+ +-------+-------+ +----------+----------+
|
||||
| | |
|
||||
| v |
|
||||
| claimed/in_progress |
|
||||
| |
|
||||
+-----------------+---------------------+
|
||||
|
|
||||
v
|
||||
+------------------+
|
||||
|awaiting_pm_review|
|
||||
+--------+---------+
|
||||
|
|
||||
+-------------------------+-------------------------+
|
||||
| | |
|
||||
v v v
|
||||
+-----------+ +--------------------+ +-----------+
|
||||
| completed | |awaiting_ceo_approval| | cancelled |
|
||||
+-----------+ +---------+----------+ +-----------+
|
||||
|
|
||||
+-------------------------+-------------------------+
|
||||
| | |
|
||||
v v v
|
||||
+-----------+ +---------------+ +-----------+
|
||||
| completed | | needs_revision| | cancelled |
|
||||
+-----------+ +---------------+ +-----------+
|
||||
```
|
||||
|
||||
## Valid Transitions
|
||||
|
||||
The following table shows all valid state transitions:
|
||||
|
||||
| From State | To States |
|
||||
|------------|-----------|
|
||||
| `backlog` | `pending`, `cancelled` |
|
||||
| `pending` | `claimed`, `cancelled` |
|
||||
| `claimed` | `in_progress`, `pending`, `cancelled` |
|
||||
| `in_progress` | `blocked`, `paused`, `verifying`, `awaiting_pm_review`, `awaiting_documentation`, `needs_revision`, `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`, `awaiting_ceo_approval`, `completed`, `cancelled` |
|
||||
| `awaiting_ceo_approval` | `completed`, `needs_revision`, `cancelled` |
|
||||
| `completed` | (none - terminal) |
|
||||
| `cancelled` | (none - terminal) |
|
||||
| `quarantined` | `pending` |
|
||||
|
||||
## Role-Based Restrictions
|
||||
|
||||
Certain transitions require specific roles:
|
||||
|
||||
### PM-Only Transitions
|
||||
- `backlog` -> `pending` (activate task)
|
||||
- `awaiting_pm_review` -> `completed`
|
||||
- `awaiting_pm_review` -> `awaiting_ceo_approval`
|
||||
- `in_progress` -> `completed` (PM completing their own task)
|
||||
- All cancellation transitions
|
||||
|
||||
### QA-Only Transitions
|
||||
- `awaiting_qa` -> `claimed` (QA claims)
|
||||
- `awaiting_qa` -> `awaiting_documentation` (QA pass)
|
||||
- `awaiting_qa` -> `needs_revision` (QA fail)
|
||||
- `in_progress` -> `awaiting_documentation` (direct QA assignment pass)
|
||||
- `in_progress` -> `needs_revision` (direct QA assignment fail)
|
||||
|
||||
### Documenter-Only Transitions
|
||||
- `awaiting_documentation` -> `claimed` (Documenter claims)
|
||||
- `awaiting_documentation` -> `awaiting_pm_review` (Docs complete)
|
||||
|
||||
### CEO-Only Transitions
|
||||
- `awaiting_ceo_approval` -> `completed` (CEO approves)
|
||||
- `awaiting_ceo_approval` -> `needs_revision` (CEO requests changes)
|
||||
- `awaiting_ceo_approval` -> `cancelled` (CEO cancels)
|
||||
|
||||
### PM Cancel Roles
|
||||
The following roles can cancel tasks:
|
||||
- `cell_pm`
|
||||
- `main_pm`
|
||||
- `product_owner`
|
||||
- `head_marketing`
|
||||
|
||||
## Git Integration
|
||||
|
||||
Tasks with `requires_git=True` have additional requirements:
|
||||
|
||||
### Git Workflow Requirements
|
||||
|
||||
1. **Starting Work** (`claimed` -> `in_progress`):
|
||||
- Task must have `branch_name` set (PM created the branch)
|
||||
|
||||
2. **Documentation to PM Review** (`awaiting_documentation` -> `awaiting_pm_review`):
|
||||
- Requires BOTH `docs_complete=True` AND `pr_created=True`
|
||||
- Documenter and Developer work in parallel during this phase
|
||||
|
||||
3. **PM Review to CEO Approval** (`awaiting_pm_review` -> `awaiting_ceo_approval`):
|
||||
- Task must have `pr_number` set (PR exists)
|
||||
|
||||
4. **CEO Approval to Completed** (`awaiting_ceo_approval` -> `completed`):
|
||||
- PR should be merged (CEO merges as final action)
|
||||
|
||||
### Parallel Execution Phase
|
||||
|
||||
During `awaiting_documentation`:
|
||||
- **Documenter**: Works on docs, calls `roboco_task_docs_complete()` when done
|
||||
- **Developer**: Creates PR, calls `roboco_git_create_pr()` when ready
|
||||
|
||||
Both must complete before transitioning to `awaiting_pm_review`.
|
||||
|
||||
```python
|
||||
def check_parallel_completion(docs_complete: bool, pr_created: bool, requires_git: bool = True) -> bool:
|
||||
"""Check if parallel execution is complete."""
|
||||
if not requires_git:
|
||||
return docs_complete
|
||||
return docs_complete and pr_created
|
||||
```
|
||||
|
||||
## Task Types
|
||||
|
||||
Task types determine whether git workflow applies:
|
||||
|
||||
| Type | Git Required | Description |
|
||||
|------|-------------|-------------|
|
||||
| `code` | Yes | Technical work - full git workflow |
|
||||
| `documentation` | Optional | May or may not need git |
|
||||
| `research` | No | Investigation/analysis tasks |
|
||||
| `planning` | No | Planning and design tasks |
|
||||
| `design` | No | UX/UI design tasks |
|
||||
| `administrative` | No | Administrative tasks |
|
||||
|
||||
## Workflow Enforcement
|
||||
|
||||
The `task_lifecycle.py` module enforces these rules:
|
||||
|
||||
```python
|
||||
from roboco.enforcement.task_lifecycle import (
|
||||
validate_task_transition,
|
||||
validate_git_requirements,
|
||||
can_agent_transition,
|
||||
is_terminal_state,
|
||||
is_waiting_state,
|
||||
is_active_state,
|
||||
)
|
||||
|
||||
# Validate a transition
|
||||
validate_task_transition(
|
||||
current_status="in_progress",
|
||||
target_status="verifying",
|
||||
agent_role="developer"
|
||||
)
|
||||
|
||||
# Check git requirements
|
||||
from roboco.enforcement.task_lifecycle import GitContext
|
||||
|
||||
git_ctx = GitContext(
|
||||
requires_git=True,
|
||||
docs_complete=True,
|
||||
pr_created=True,
|
||||
pr_number=42,
|
||||
branch_name="feature/backend/ABC123"
|
||||
)
|
||||
|
||||
validate_git_requirements(
|
||||
current_status="awaiting_documentation",
|
||||
target_status="awaiting_pm_review",
|
||||
git_ctx=git_ctx
|
||||
)
|
||||
```
|
||||
|
||||
## Exceptions
|
||||
|
||||
The lifecycle module raises specific exceptions:
|
||||
|
||||
- `TaskLifecycleError`: Invalid state transition or role not permitted
|
||||
- `GitRequirementError`: Git requirements not met for a transition
|
||||
|
||||
Example error handling:
|
||||
|
||||
```python
|
||||
from roboco.exceptions import TaskLifecycleError
|
||||
from roboco.enforcement.task_lifecycle import GitRequirementError
|
||||
|
||||
try:
|
||||
validate_task_transition("pending", "in_progress", "developer")
|
||||
except TaskLifecycleError as e:
|
||||
print(f"Invalid transition: {e.current_status} -> {e.target_status}")
|
||||
print(f"Valid transitions: {e.valid_transitions}")
|
||||
|
||||
try:
|
||||
validate_git_requirements("claimed", "in_progress", git_ctx)
|
||||
except GitRequirementError as e:
|
||||
print(f"Git requirement not met: {e.requirement}")
|
||||
print(f"Message: {e.message}")
|
||||
```
|
||||
|
||||
## Related API Endpoints
|
||||
|
||||
Task lifecycle operations are exposed via the Task API:
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `POST /tasks/{id}/claim` | Claim a pending task |
|
||||
| `POST /tasks/{id}/start` | Start working on claimed task |
|
||||
| `POST /tasks/{id}/block` | Block task on dependency |
|
||||
| `POST /tasks/{id}/soft-block` | Block on external factor |
|
||||
| `POST /tasks/{id}/unblock` | Unblock a task |
|
||||
| `POST /tasks/{id}/pause` | Pause active task |
|
||||
| `POST /tasks/{id}/resume` | Resume paused task |
|
||||
| `POST /tasks/{id}/verify` | Submit for self-verification |
|
||||
| `POST /tasks/{id}/submit-qa` | Submit to QA |
|
||||
| `POST /tasks/{id}/pass-qa` | QA passes task |
|
||||
| `POST /tasks/{id}/fail-qa` | QA fails task |
|
||||
| `POST /tasks/{id}/docs-complete` | Mark docs complete |
|
||||
| `POST /tasks/{id}/submit-pm-review` | Submit for PM review |
|
||||
| `POST /tasks/{id}/escalate-to-ceo` | Escalate to CEO |
|
||||
| `POST /tasks/{id}/ceo-approve` | CEO approves |
|
||||
| `POST /tasks/{id}/ceo-reject` | CEO rejects |
|
||||
| `POST /tasks/{id}/complete` | Complete task (PM) |
|
||||
| `POST /tasks/{id}/cancel` | Cancel task (PM) |
|
||||
| `POST /tasks/{id}/activate` | Activate from backlog (PM) |
|
||||
Reference in New Issue
Block a user