roboco/docs/rag/lifecycle/intent-verbs.md

Intent Verbs (gateway-facing surface)

claim_doc_task

Claim awaiting_documentation. Returns evidence inline.

Allowed roles: documenter

Composes: (no atomic actions)

claim_gate_review

Claim an assembled-PR review task (awaiting_pr_review) WITHOUT transitioning it — mirrors QA's claim_review. The assembled diff and the parent task's acceptance criteria are returned inline.

Allowed roles: pr_reviewer

Composes: (no atomic actions)

claim_pr_review

Claim an inbound external-PR review task and start work. pending -> claimed -> in_progress.

Allowed roles: pr_reviewer

Composes: claim → start

Preconditions: external_review_state

claim_review

Claim a task in awaiting_qa for review. Returns evidence inline.

Allowed roles: qa

Composes: (no atomic actions)

complete

Cell PM merges the PR (leaf into the cell branch, or the gated cell→root PR into the root branch) + transitions to completed; Main PM escalates the root to the CEO (who merges root→master). The merge runs BEFORE the complete transition: TaskService.complete asserts the PR is already merged, so the choreographer verb body (cell_pm_complete / main_pm_complete) owns the merge-first ordering — no trailing pr_merge side_effect is declared here.

Allowed roles: cell_pm, main_pm

Composes: complete

declare_coverage

Stamp parent acceptance criteria onto an existing child's parent_ac_refs after the fact — for a replacement child whose delegate omitted covers_parent_criteria. Or, targeting your OWN root/coordination task, declare criteria as root-owned (only your own machinery satisfies them — never push these into a cell). No status change; the verb body owns ownership + criterion validation.

Allowed roles: cell_pm, main_pm

Composes: (no atomic actions)

delegate

Create a subtask under the current task. Validates the delegation chain (main_pm->cell_pm; cell_pm->its team's devs) and the assignee-vs-task_type rule (Cell PMs get planning-typed tasks; devs get code/research, UX devs also design). documentation is NOT delegatable — the lifecycle auto-creates the doc phase after the code subtask passes QA.

Allowed roles: cell_pm, main_pm

Composes: create_subtask

escalate_to_ceo

Escalate to CEO with reason. Transitions to awaiting_ceo_approval.

Allowed roles: head_marketing, main_pm, product_owner

Composes: escalate_to_ceo

escalate_up

Escalate to your role's escalation_target.

Allowed roles: cell_pm, main_pm

Composes: (no atomic actions)

Preconditions: non_terminal

fail_review

Fail QA with concrete issues. Transitions to needs_revision.

Allowed roles: qa

Composes: qa_fail

give_me_work

Return your most-actionable task or signal idle.

Allowed roles: cell_pm, developer, documenter, main_pm, pr_reviewer, qa

Composes: (no atomic actions)

i_am_blocked

Escalate to PM. Logs a struggle journal entry.

Allowed roles: developer, documenter, qa

Composes: block

i_am_done

Submit work for QA. Auto-runs in_progress->verifying then verifying->awaiting_qa. Strict - PR must be open (call open_pr first) and >=1 commit.

Allowed roles: developer

Composes: submit_verification → submit_qa

Preconditions: commits>=1, owns_task

i_am_idle

Signal you have no active work. PMs auto-pause owned in_progress tasks.

Allowed roles: auditor, cell_pm, developer, documenter, head_marketing, main_pm, pr_reviewer, product_owner, prompter, qa, secretary

Composes: (no atomic actions)

i_documented

Signal docs complete. Transitions to awaiting_pm_review.

Allowed roles: documenter

Composes: docs_complete

i_will_plan

PM mirror of i_will_work_on for parent tasks. Claim, plan, transition to in_progress; from there delegate subtasks.

Allowed roles: cell_pm, main_pm

Composes: claim → set_plan → start

Preconditions: plan

i_will_work_on

Claim a task, set the plan, and transition to in_progress. Atomic - preconditions checked before any state mutation.

Allowed roles: developer

Composes: claim → set_plan → start

Preconditions: plan

open_pr

Push the branch and open a PR. Atomic - preconditions (assignee, >=1 commit, no prior PR) checked BEFORE any git operation. After success, call i_am_done.

Allowed roles: developer

Composes: (no atomic actions)

Side effects: push_branch, create_pr

Preconditions: commits>=1, no_prior_pr, owns_task, pr_open_state

pass_review

Pass QA. Transitions awaiting_qa -> awaiting_documentation.

Allowed roles: qa

Composes: qa_pass

post_pr_review

Post one complete change-request to the external PR and finish the review task. in_progress -> completed.

Allowed roles: pr_reviewer

Composes: pr_review_done

pr_fail

Fail the assembled-PR review with concrete issues. Transitions awaiting_pr_review -> needs_revision, routed back like a QA fail.

Allowed roles: pr_reviewer

Composes: pr_fail

pr_pass

Pass the assembled-PR review. Transitions awaiting_pr_review -> awaiting_pm_review so the PM can merge.

Allowed roles: pr_reviewer

Composes: pr_pass

reassign

Hand a claimed/in_progress task to another developer in your own cell. The branch is keyed to the task (not the agent), so it is preserved — the new developer continues the work-in-progress. No status change.

Allowed roles: cell_pm

Composes: (no atomic actions)

request_changes

Reject the merge review with concrete issues. Transitions awaiting_pm_review -> needs_revision, routed back like a QA fail (original developer for a leaf, revision PM for an assembled task). Use this for an AC/scope violation caught at merge review — never i_am_blocked/escalate, which have no revision routing.

Allowed roles: cell_pm, main_pm

Composes: request_changes

resume

Resume a paused task you own. paused -> in_progress.

Allowed roles: cell_pm, developer, documenter, main_pm, qa

Composes: resume

submit_root

Main PM opens the root→master PR and moves the root task to awaiting_pr_review for the main reviewer (the root analogue of the cell PM's submit_up). After pr_pass, call complete to escalate to the CEO. For branch-bearing roots (a Main-PM root-subtask assembles the cells' merged work); branchless coordination roots skip the gate and complete directly. The gate is branch-keyed, not task_type-keyed — a Main-PM root is planning-typed, never code.

Allowed roles: main_pm

Composes: submit_for_review

Pre side effects: create_root_pr

Preconditions: root_not_code

submit_up

Cell PM opens the cell→root PR and moves the cell task into the PR-review gate (awaiting_pr_review). The cell reviewer reviews the assembled diff; after pr_pass the same Cell PM completes it.

Allowed roles: cell_pm

Composes: submit_for_review

Pre side effects: create_pr

sync_branch

Rebase your task's branch onto its current base THROUGH the gate (raw git is denied). Use when your branch has fallen behind its base — e.g. a sibling task's PR merged into the parent branch while you worked. Fetches origin, rebases head onto base, and force-pushes (with-lease). No DB state change. On conflicts the rebase is aborted and the conflicted files are returned — resolve by hand, commit, then sync_branch again. Pass stash=True to auto-stash uncommitted changes instead of refusing DIRTY_WORKSPACE; they are restored after the rebase.

Allowed roles: developer

Composes: (no atomic actions)

Preconditions: owns_task, sync_branch_state

triage

List actionable tasks in your scope.

Allowed roles: auditor, cell_pm, head_marketing, main_pm, product_owner

Composes: (no atomic actions)

triage_all

List actionable tasks across all teams (Main PM only).

Allowed roles: main_pm

Composes: (no atomic actions)

unblock

PM unblocks a blocked task; restores pre-block state.

Allowed roles: cell_pm, main_pm

Composes: unblock

unclaim

Voluntarily release a claim back to pending. The work-in-progress branch is preserved. A PR reviewer who claimed an external review (in_progress) or a gate review (awaiting_pr_review) and cannot finish releases the claim here rather than wedging the lane until the stale-claim reaper.

Allowed roles: cell_pm, developer, documenter, main_pm, pr_reviewer, qa

Composes: (no atomic actions)

waive_finding

Waive one minor/nit review finding by id with a required note. Blocker/major findings must be fixed, never waived. No task status change.

Allowed roles: auditor

Composes: (no atomic actions)