roboco/docs/company/task-lifecycle.md

The task lifecycle

Everything in RoboCo is a task, and every task walks the same path. Each step is gated by role — only QA can pass QA, only the CEO can merge to master — so work can't skip a stage or land unreviewed. This is the backbone that makes the company trustworthy.

stateDiagram-v2
    direction LR
    [*] --> backlog
    backlog --> pending: PM activates
    pending --> claimed: agent claims
    claimed --> in_progress: start work
    in_progress --> verifying: self-verify
    verifying --> awaiting_qa: submit (PR is open)
    awaiting_qa --> awaiting_documentation: QA passes
    awaiting_qa --> needs_revision: QA fails
    needs_revision --> in_progress: rework
    awaiting_documentation --> awaiting_pm_review: docs done
    awaiting_pm_review --> completed: PM merges
    awaiting_pm_review --> awaiting_ceo_approval: escalate
    awaiting_ceo_approval --> completed: CEO approves & merges
    awaiting_ceo_approval --> needs_revision: CEO requests changes
    completed --> [*]

    in_progress --> blocked: external dependency
    in_progress --> paused: temporarily stopped
    blocked --> in_progress: unblocked
    paused --> in_progress: resumed

The states

State	What it means	Who owns the next move
backlog	PM setup phase — dependencies or session setup still needed.	PM
pending	Ready for work; the orchestrator can spawn an agent for it.	the matching role
claimed	An agent has locked the task.	the assignee
in_progress	Active development.	the assignee
blocked	An external dependency is blocking progress.	whoever clears it
paused	Temporarily stopped; can resume.	the assignee
verifying	The developer is self-verifying before handing off.	the developer
awaiting_qa	Submitted for QA — a pull request is already open so QA reviews the real diff.	QA
needs_revision	QA, a PR reviewer, or the CEO asked for changes.	the developer
awaiting_documentation	The Documenter writes up what was built (the PR is already open).	Documenter / Developer
awaiting_pr_review	The in-path PR-review gate: a reviewer checks an assembled pull request before the PM merges it.	PR reviewer
awaiting_pm_review	Docs are done; the PM reviews and merges.	PM
awaiting_ceo_approval	A major task escalated to you for the final call.	you
completed	Terminal — work done and merged.	—
cancelled	Terminal — work cancelled.	—

!!! note "The PR comes before QA" A pull request is opened before QA review, not after. That lets QA read the actual PR diff on GitHub, and means the whole downstream approval chain — PM, then you — is signing off on a pull request that already exists.

When work is rejected

Rejection isn't a dead end — it's a loop. When QA fails a task, or a PR reviewer rejects an assembled pull request, the task drops back to needs_revision, the developer reworks it, and it re-enters the flow. The same is true when you request changes from the CEO Approval Queue. Nothing is lost; the task carries its history, branch, and pull request with it the whole way around.

A failed developer task is routed back to the developer who worked it (resolved from the work session), not the pool — so the revision lands with whoever has the context, rather than being re-claimed cold by a cell PM. Only a task no developer ever touched falls back to the pool.

The in-path PR-review gate

Most leaf developer tasks are reviewed by QA and never need a separate PR review. But when work is assembled and pushed up the chain as a pull request, it stops for a dedicated review before any PM merges it:

stateDiagram-v2
    direction LR
    in_progress --> awaiting_pr_review: submit_up / submit_root
    awaiting_pr_review --> awaiting_pm_review: pr_pass
    awaiting_pr_review --> needs_revision: pr_fail

• A cell PM runs submit_up to open the cell → root pull request.
• The Main PM runs submit_root to open the root → master pull request.
• Both land in awaiting_pr_review, where a PR reviewer either pr_passes it on to the PM merge or pr_fails it back to needs_revision.

This gives the merge step a real reviewer with the power to reject — the one thing a PM otherwise lacks. Leaf dev tasks and branchless coordination roots skip the gate.

Role-gated transitions

Transitions aren't suggestions; they're enforced. A handful of the rules:

• Activating a task (backlog → pending) is PM-only.
• Passing or failing QA is QA-only, and a pass requires real review notes.
• pr_pass / pr_fail are PR-reviewer-only.
• Merging (awaiting_pm_review → completed) is PM-only; escalating to the CEO and the final approve / request-changes / cancel are CEO-only.
• Cancelling is PM-only.
• A Main-PM coordination root can never be task_type=code. The Main PM coordinates; it doesn't write code itself, so the combination is rejected at creation — a structural guard, not a hint.

How those role boundaries are enforced — and why a developer literally cannot call the merge verb — is the subject of How agents are sandboxed.

Next

→ The merge model — how a task's branch travels up to master.