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

RAG expansion + Optimal API

Browse Source
This commit is contained in:
Renn F
2025-12-27 21:53:38 +01:00
parent 3f48a93504
commit 1116e597d0
58 changed files with 11768 additions and 7840 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/standards/workflow/agent_roles.md
+444
View File
@@ -0,0 +1,444 @@
# Agent Roles and Permissions
Comprehensive reference for agent roles, permissions, and organizational structure in the RoboCo system. Derived from actual implementation in the codebase.
**Source Files:**
- Role Definitions: `roboco/models/base.py` (lines 56-78)
- Agent Config: `roboco/agents_config.py`
- Permissions Model: `roboco/models/permissions.py`
---
## Table of Contents
1. [Agent Roles](#agent-roles)
2. [Organizational Structure](#organizational-structure)
3. [Agent Roster](#agent-roster)
4. [Permission Levels](#permission-levels)
5. [Task Permissions](#task-permissions)
6. [Knowledge Base Permissions](#knowledge-base-permissions)
7. [Communication Permissions](#communication-permissions)
8. [Role Capabilities](#role-capabilities)
---
## Agent Roles
### ROLE-001: AgentRole Enum
**Source:** `roboco/models/base.py`
```python
class AgentRole(str, Enum):
# System (internal orchestrator operations)
SYSTEM = "system"
# Executive
CEO = "ceo"
# Board
PRODUCT_OWNER = "product_owner"
HEAD_MARKETING = "head_marketing"
AUDITOR = "auditor"
# Management
MAIN_PM = "main_pm"
CELL_PM = "cell_pm"
# Cell Members
DEVELOPER = "developer"
QA = "qa"
DOCUMENTER = "documenter"
```
### ROLE-002: Role Descriptions
| Role | Description | Count |
|------|-------------|-------|
| `ceo` | Human executive, final authority | 1 |
| `product_owner` | Product strategy and direction | 1 |
| `head_marketing` | Marketing and external comms | 1 |
| `auditor` | Silent observer, quality oversight | 1 |
| `main_pm` | Coordinates all cells | 1 |
| `cell_pm` | Manages a single cell | 3 |
| `developer` | Writes code | 5 |
| `qa` | Reviews and tests | 3 |
| `documenter` | Writes documentation | 3 |
| **Total** | | **19** |
---
## Organizational Structure
### ROLE-010: Hierarchy
```
CEO (Renzo - Human)
│
┌──────────────────────┼──────────────────────┐
│ │ │
Product Owner Head of Marketing Auditor
(Board) (Board) (Silent Observer)
│ │ │
└──────────────────────┼──────────────────────┘
│
Main PM
│
┌──────────────────────┼──────────────────────┐
│ │ │
Backend Cell Frontend Cell UX/UI Cell
│ │ │
┌────┴────┐ ┌────┴────┐ ┌────┴────┐
PM DEV*2 QA PM DEV*2 QA PM DEV QA
DOC DOC DOC
```
### ROLE-011: Cells
| Cell | PM | Developers | QA | Documenter |
|------|-----|------------|-----|------------|
| Backend | be-pm | be-dev-1, be-dev-2 | be-qa | be-doc |
| Frontend | fe-pm | fe-dev-1, fe-dev-2 | fe-qa | fe-doc |
| UX/UI | ux-pm | ux-dev | ux-qa | ux-doc |
---
## Agent Roster
### ROLE-020: Complete Agent List
**Source:** `roboco/agents_config.py`
| Slug | Role | Cell | Team |
|------|------|------|------|
| `ceo` | ceo | - | executive |
| `product-owner` | product_owner | - | board |
| `head-marketing` | head_marketing | - | board |
| `auditor` | auditor | - | board |
| `main-pm` | main_pm | - | management |
| `be-pm` | cell_pm | backend | management |
| `fe-pm` | cell_pm | frontend | management |
| `ux-pm` | cell_pm | uxui | management |
| `be-dev-1` | developer | backend | developers |
| `be-dev-2` | developer | backend | developers |
| `fe-dev-1` | developer | frontend | developers |
| `fe-dev-2` | developer | frontend | developers |
| `ux-dev` | developer | uxui | developers |
| `be-qa` | qa | backend | qa |
| `fe-qa` | qa | frontend | qa |
| `ux-qa` | qa | uxui | qa |
| `be-doc` | documenter | backend | documentation |
| `fe-doc` | documenter | frontend | documentation |
| `ux-doc` | documenter | uxui | documentation |
---
## Permission Levels
### ROLE-030: Permission Hierarchy
**Source:** `roboco/models/permissions.py`
```python
ROLE_PERMISSION_LEVELS: dict[str, str] = {
"system": "CEO", # System/orchestrator - CEO-level access
"ceo": "CEO", # Full access
"product_owner": "BOARD", # Cross-org access
"head_marketing": "BOARD", # Cross-org access
"auditor": "AUDITOR", # Special: silent read all
"main_pm": "MAIN_PM", # All cells access
"cell_pm": "CELL_PM", # Own cell + PM channel
"developer": "CELL_MEMBER", # Own cell only
"qa": "CELL_MEMBER", # Own cell only
"documenter": "CELL_MEMBER", # Own cell only
}
```
### ROLE-031: Level Descriptions
| Level | Description | Scope |
|-------|-------------|-------|
| `CEO` | Full access to everything | Organization-wide |
| `BOARD` | Cross-organization access | Cross-cell |
| `AUDITOR` | Silent read access to all | Read-only, all channels |
| `MAIN_PM` | All cells access | All cells |
| `CELL_PM` | Own cell + PM channel | Single cell + PM |
| `CELL_MEMBER` | Own cell only | Single cell |
---
## Task Permissions
### ROLE-040: Task Permission Matrix
**Source:** `roboco/models/permissions.py`
| Role | VIEW_ALL | VIEW_OWN | CREATE | ASSIGN | CLAIM | UPDATE_OWN | CLOSE | CHANGE_PRIORITY |
|------|:--------:|:--------:|:------:|:------:|:-----:|:----------:|:-----:|:---------------:|
| system | X | | X | X | X | X | X | X |
| ceo | X | | X | X | | | X | X |
| product_owner | X | | X | X | | | X | X |
| head_marketing | X | | X | X | | | X | X |
| auditor | X | | X | X | | | X | X |
| main_pm | X | | X | X | X | X | X | X |
| cell_pm | | X | X | X | X | X | X | X |
| developer | | X | | | X | X | X | |
| qa | | X | | | X | X | | |
| documenter | | X | | | X | X | X | |
### ROLE-041: Key Task Capabilities
**Who can CREATE tasks:**
- ceo, product_owner, head_marketing, auditor
- main_pm, cell_pm
**Who can ASSIGN tasks:**
- ceo, product_owner, head_marketing, auditor
- main_pm, cell_pm
**Who can CLAIM tasks:**
- main_pm, cell_pm
- developer, qa, documenter (role-appropriate statuses)
**Who can CLOSE (complete) tasks:**
- ceo, product_owner, head_marketing, auditor
- main_pm, cell_pm
- developer, documenter (their own tasks)
**Who can CANCEL tasks:**
- cell_pm, main_pm, product_owner, head_marketing
- NOT ceo (by design)
- NOT auditor
---
## Knowledge Base Permissions
### ROLE-050: KB Permission Matrix
**Source:** `roboco/models/permissions.py`
| Role | INDEX_CODE | INDEX_DOCS | SEARCH | QUERY | VIEW_STATS | CLEAR | REFRESH |
|------|:----------:|:----------:|:------:|:-----:|:----------:|:-----:|:-------:|
| ceo | X | X | X | X | X | X | X |
| product_owner | | X | X | X | X | | |
| head_marketing | | X | X | X | | | |
| auditor | | | X | X | X | | |
| main_pm | X | X | X | X | X | X | X |
| cell_pm | X | X | X | X | X | | |
| developer | X | X | X | X | | | |
| qa | | | X | X | | | |
| documenter | | X | X | X | | | |
### ROLE-051: KB Capability Summary
**Who can INDEX_CODE:**
- ceo, main_pm, cell_pm, developer
**Who can INDEX_DOCS:**
- ceo, product_owner, head_marketing
- main_pm, cell_pm
- developer, documenter
**Who can SEARCH/QUERY:**
- Everyone
**Who can CLEAR_INDEX/REFRESH:**
- ceo, main_pm only
---
## Communication Permissions
### ROLE-060: Notification Permissions
**Who CAN send notifications:**
- cell_pm
- main_pm
- product_owner
- head_marketing
- auditor
- ceo
**Who CANNOT send notifications:**
- developer
- qa
- documenter
### ROLE-061: Channel Access
**Cell Channels** (e.g., `#backend-cell`):
- Read: Cell members + Main PM
- Write: Cell members
- Silent: Auditor
**Cross-Cell Channels** (e.g., `#dev-all`, `#qa-all`):
- Read/Write: Respective role members + Cell PMs + Main PM
- Silent: Auditor
**Management Channels** (e.g., `#main-pm-board`):
- Read/Write: Board + Main PM
- Silent: Auditor
**Broadcast Channels** (e.g., `#announcements`):
- Read: Everyone
- Write: PMs and Board only
### ROLE-062: Communication Matrix
Each role can communicate with:
| Role | Can Communicate With |
|------|---------------------|
| CEO | Everyone |
| Board Members | CEO, other board, Auditor, Main PM |
| Auditor | Everyone (silent read all channels) |
| Main PM | CEO, Board, Cell PMs |
| Cell PM | CEO, Auditor, Main PM, other Cell PMs, cell members |
| Cell Members | CEO, Auditor, own Cell PM, other cell members |
---
## Role Capabilities
### ROLE-070: Developer Capabilities
```markdown
CAN:
- Claim pending and needs_revision tasks
- Start, pause, resume work
- Submit for verification and QA
- Block tasks (with dependency)
- Search and query knowledge base
- Index code and documentation
- Journal their work
CANNOT:
- Create or assign tasks
- Pass/fail QA
- Complete tasks
- Cancel tasks
- Send notifications
- Clear/refresh KB indexes
```
### ROLE-071: QA Capabilities
```markdown
CAN:
- Claim awaiting_qa tasks
- Pass or fail QA
- Block tasks
- Search and query knowledge base
- Journal their work
CANNOT:
- Claim pending tasks
- Create or assign tasks
- Index content
- Complete documentation
- Complete tasks
- Cancel tasks
- Send notifications
```
### ROLE-072: Documenter Capabilities
```markdown
CAN:
- Claim awaiting_documentation tasks
- Complete documentation
- Index documentation
- Search and query knowledge base
- Journal their work
CANNOT:
- Claim pending tasks
- Create or assign tasks
- Index code
- Pass/fail QA
- Cancel tasks
- Send notifications
```
### ROLE-073: Cell PM Capabilities
```markdown
CAN:
- Create tasks in backlog
- Activate backlog → pending
- Assign tasks to cell members
- Complete awaiting_pm_review tasks
- Cancel any task (in cell)
- Unblock blocked tasks
- Send notifications
- Index code and documentation
- Full KB access (except clear/refresh)
CANNOT:
- Access other cells' tasks (unless Main PM)
- Clear/refresh KB indexes
```
### ROLE-074: Main PM Capabilities
```markdown
CAN:
- Everything Cell PM can do
- Access ALL cells
- Clear and refresh KB indexes
- Coordinate cross-cell work
```
### ROLE-075: Auditor Capabilities
```markdown
CAN:
- View all tasks
- View all channels (silent)
- Search and query knowledge base
- View KB stats
- Create tasks
- Assign tasks
CANNOT:
- Claim tasks
- Update tasks
- Clear KB indexes
- Write to most channels (silent observer)
```
---
## Quick Reference
### Role by Task Action
| Action | Allowed Roles |
|--------|---------------|
| Create task | CEO, Board, PMs |
| Activate task | PMs |
| Assign task | CEO, Board, PMs |
| Claim task | Developer, QA, Documenter, PMs |
| Pass QA | QA only |
| Fail QA | QA only |
| Complete docs | Documenter only |
| Complete task | PMs only |
| Cancel task | PMs, Board (not CEO, not Auditor) |
### Role Hierarchy
```
CEO
└─ Board (Product Owner, Head Marketing)
└─ Auditor (silent observer)
└─ Main PM
└─ Cell PMs
└─ Cell Members (Developer, QA, Documenter)
```
### Escalation Chain
```
Developer/QA/Documenter → Cell PM → Main PM → Product Owner → CEO
```
docs/standards/workflow/task_lifecycle.md
+467
View File
@@ -0,0 +1,467 @@
# 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
1. [Task States](#task-states)
2. [Valid Transitions](#valid-transitions)
3. [Role-Restricted Transitions](#role-restricted-transitions)
4. [Task Service Methods](#task-service-methods)
5. [Workflow by Role](#workflow-by-role)
6. [Quality Gates](#quality-gates)
7. [State Categories](#state-categories)
---
## Task States
### WF-001: TaskStatus Enum
**Source:** `roboco/models/base.py`
```python
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`.
```python
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
```python
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()`:
```python
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 `pending` and `needs_revision` tasks
- 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_qa` tasks 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_documentation` tasks
- 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
```markdown
- [ ] 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
```markdown
- [ ] Task is claimed by you
- [ ] Plan is documented
- [ ] Cell channel notified
```
### WF-052: Before Submit to QA
```markdown
- [ ] 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
```markdown
- [ ] 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.
```python
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 task
- `PAUSED` - Waiting for agent to resume
- `AWAITING_QA` - Waiting for QA review
- `AWAITING_DOCUMENTATION` - Waiting for docs
- `AWAITING_PM_REVIEW` - Waiting for PM approval
### WF-063: Active States
Tasks where an agent is actively working:
- `CLAIMED` - Agent owns, about to start
- `IN_PROGRESS` - Active development
- `VERIFYING` - Self-verification
- `NEEDS_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
```