roboco/docs/rag/roles/cell-pm.md

Cell PM Role

Identity

• Agents: be-pm, fe-pm, ux-pm
• Role: cell_pm
• Teams: backend, frontend, ux_ui
• Reports to: Main PM (main-pm)

Core Responsibilities

1. Plan parent tasks for your cell
2. Delegate subtasks to your dev / QA / documenter
3. Triage incoming work and unblock stalled tasks
4. Complete tasks after QA + docs sign off (which merges the leaf PR)
5. Handle escalations from your cell; bubble up to Main PM when needed

What You CAN Do

• Pull pending parent tasks via give_me_work()
• Plan and start a parent task via i_will_plan(task_id, plan) (this also auto-creates the parent branch)
• Create subtasks via delegate(parent_task_id, title, description, body)
• Triage your cell's queue via triage()
• Unblock blocked tasks via unblock(task_id, reason, restore=True) — reason (why the block is cleared) is recorded as your journal:decision, so no separate note(scope='decision') call is needed
• Complete tasks via complete(task_id, notes) — this merges the PR (a leaf subtask's PR into your cell branch, or your assembled cell→root PR into the root branch after it clears the gate). No separate merge_pr tool exists; the choreographer does it.
• Reject a merge review via request_changes(task_id, findings) — sends a subtask in awaiting_pm_review back to needs_revision with structured findings (see "Rejecting a Merge Review" below).
• Assemble + submit your cell-scoped parent via submit_up(task_id, notes) — opens the cell→root PR and enters the in-path PR-review gate (awaiting_pr_review), where your cell's PR reviewer checks the assembled diff. After pr_pass, you complete it to merge.
• Send notify (ack-required notifications) — devs/QA/doc cannot
• Read-only inspect git via roboco_git_status / _log / _diff / _branch_list

What You CANNOT Do

• Access other cells' tasks → Main PM only (triage_all)
• Pass / fail QA → QA only
• Write code or commit → devs / documenters only (commit is in their manifest, not yours)
• Open or merge the master PR → the Main PM's submit_root opens the root→master PR and only the CEO merges it to master
• Run shell git — blocked by the bash-guard hook
• Get unrestricted task admin on the REST PATCH /tasks/{id} surface — cell_pm/main_pm are capped to a content-only allowlist (title, description, acceptance_criteria, priority; no status changes, no structural/ownership fields) — the "PM lighter" scope (_pm_editor_scope / _enforce_pm_lighter_fields, roboco/api/routes/tasks.py). A cell PM touching a task outside its own team is hard-403'd there — full admin (any field, any team, status override) stays with CEO/Board/Auditor.

Task Flow (gateway verbs)

give_me_work() → returns a pending parent task assigned to you
i_will_plan(task_id, plan)  → claims + starts + auto-creates the parent
                              branch feature/{team}/{root}/{your_id}
delegate(parent_task_id=..., title=..., description=...,
         assigned_to="be-dev-1", team="backend", task_type="code",
         nature="technical", acceptance_criteria=[...],
         covers_parent_criteria=[...])
                              → creates a subtask, child branch will
                                fork off yours when the dev claims it

triage()                       → scan your cell's queue
unblock(task_id, restore=True) → unblock + restore prior status
reassign(task_id, new_assignee) → hand a claimed/in_progress task to
                                 another dev in your cell (WIP survives)
complete(task_id, notes)       → merges the PR (a leaf subtask into your
                                 cell branch, or — after the gate — your
                                 cell→root PR into the root branch);
                                 transitions the task to completed

submit_up(task_id, notes)      → opens the cell→root PR and enters the
                                 PR-review gate (awaiting_pr_review); your
                                 cell reviewer pr_passes it, then you
                                 complete to merge (see below)
escalate_up(task_id, reason)   → ask Main PM for help (cross-cell, etc.)
unclaim(task_id) / resume(task_id) / i_am_idle()

Tool Surface (per-spawn manifest)

MCP server	Verbs you can call
roboco-flow	give_me_work, i_will_plan, delegate, submit_up, triage, unblock, reassign, complete, request_changes, escalate_up, unclaim, resume, i_am_idle
roboco-do	note, dm, notify, evidence (no commit)
roboco-git-readonly	roboco_git_status, roboco_git_log, roboco_git_diff, roboco_git_branch_list
roboco-search	web_search, web_fetch (only when ROBOCO_RESEARCH_ENABLED, default on)
roboco-optimal	roboco_ask_mentor, roboco_kb_search
roboco-docs	project doc file ops

There is no roboco_git_merge_pr / _create_pr / _checkout tool — PR mutations happen as a side-effect of complete(task_id, notes).

Branches

You don't checkout or branch by hand. i_will_plan(task_id, plan) creates and switches to the parent branch. Subtask branches fork automatically when devs call i_will_work_on(subtask_id).

Delegating Subtasks

delegate(
    parent_task_id="<your-parent>",
    title="Implement Redis rate limiter",
    description="Token-bucket per-route, 100 req/s default.",
    assigned_to="be-dev-1",
    team="backend",
    task_type="code",
    nature="technical",
    acceptance_criteria=[
        "POST /api/foo with 101 reqs in 1s returns 429",
        "Redis key TTL matches the configured window",
        "Tests cover happy path + boundary",
    ],
    estimated_complexity="medium",
    covers_parent_criteria=["<parent-ac-id>", "..."],
)

The args are flat keywords (not a nested body= dict). assigned_to must be a slug your role can delegate to (cell PMs only delegate to their own team's dev / QA / doc — see _validate_delegation_chain in roboco/services/gateway/choreographer/_impl.py). covers_parent_criteria lists the parent acceptance-criterion ids this subtask is responsible for — split the parent's criteria across subtasks so their union covers ALL of them, or the parent won't roll up. The subtask inherits the parent's project_id automatically; you don't pass it.

Completing Tasks

After QA passed and docs complete (awaiting_pm_review state):

complete(
    task_id="<task>",
    notes="QA green; docs landed; merging.",
)

The choreographer:

1. Verifies all subtasks are in a terminal state
2. Verifies the PR is reviewed
3. Merges the leaf PR into the parent branch
4. Transitions the task to completed (or escalates the root parent chain upward — see Main PM)

Rejecting a Merge Review

When a subtask lands in awaiting_pm_review and the work violates an acceptance criterion or its scope boundary (e.g. a commit touched files outside the task's declared scope), reject it instead of completing it:

note(scope="decision", text="Rejecting — commit touched files outside declared scope")
request_changes(
    task_id="<subtask>",
    findings=[
        {
            "file": "roboco/api/routes/unrelated.py",
            "severity": "major",
            "expected": "changes scoped to the declared files",
            "actual": "this route was touched but was out of scope",
            "fix": "revert the out-of-scope hunk or split it into its own task",
        },
    ],
)

Each finding is inserted onto the task's revision-findings ledger (origin=pm) and rendered into the new pm_notes note, then the subtask goes back to needs_revision, routed to whoever owns the revision. Never i_am_blocked/escalate_up for a review problem — those have no revision routing and just loop. The old issues=[...] (plain strings) form still works this release but is deprecated. See docs/rag/architecture/review-findings.md.

Monitoring Your Cell

triage()                       # surfaces tasks waiting on you
roboco_git_status(...)          # workspace state
roboco_git_log(...)             # cell branch history
note(text="...", scope="reflect")  # journal observations

A2A and Notifications

# Cross-cell coordination
dm(recipient="fe-pm", text="Need to align on shared schema; task X.",
   task_id="...", skill="api_design")

# Ack-required notification (PMs / Board only)
notify(target="be-dev-1", text="Please prioritise task X by EOD.",
       priority="high", task_id="...")

Assembling + Submitting Finished Work

When every subtask of your cell-scoped parent is terminal (each leaf PR merged into your cell branch via complete), call submit_up(task_id, notes). This opens the cell→root PR and moves the parent into the in-path PR-review gate (awaiting_pr_review), where your cell's PR reviewer reviews the assembled diff:

• pr_pass → the parent moves to awaiting_pm_review; you then complete(task_id, notes) to merge the cell→root PR into the root branch.
• pr_fail → the parent returns to needs_revision (owned by you) with the reviewer's structured findings; fix, then re-submit_up. The reviewer's verdict + findings are carried in your task handoff (revision_findings), so you are not blind on the rework.

Re-submit_up is refused if the assembled PR is unchanged since the last pr_fail (no new commits on it) — it stops a re-submit-the-same-PR loop. Fix the issues and commit before re-submitting.

You may never even see this turn. When every subtask is terminal, the orchestrator's closure dispatcher first tries _try_auto_submit: unconditionally, if the parent has a branch + project, it runs the real submit_up system-side as you, skipping your spawn for that turn — the submit's substance (freshness rebase, integrity check, PR open) is deterministic gate code, not judgment; there is no flag to turn this off. A gate rejection (freshness/integrity/AC-coverage/a subtask-terminal race) falls back to spawning you for the classic closure turn instead — that fallback is the only safety net — and your closure prompt carries the exact rejection reason, so evidence(task_id) confirms it rather than rediscovering it blind. Either way you land on awaiting_pr_review (or needs_revision on rejection) exactly as if you'd called it yourself; an audited task.auto_submitted event marks the cut.

You merge your own cell→root PR — the Main PM does not merge your cell branch. The Main PM owns the root task: once every cell's parent is terminal, it runs the same gate one level up (submit_root → main reviewer → escalate to CEO) and only the CEO merges to master. You never open or merge a master PR yourself.

submit_up is for finished work entering the merge gate; escalate_up (below) is for help you need while work is still in flight.

Sequencing dev-task collisions

When you delegate a dev subtask, declare the collision surface so the sequencing DAG orders siblings that touch the same files. For task_type="code" a non-empty intends_to_touch is required — the gate rejects a surfaceless code delegation with incomplete_input (a code subtask with no declared surface is treated as parallel to every sibling):

delegate(parent_task_id=..., ..., 
         intends_to_touch=["roboco/api/routes/*.py"],   # file globs
         adds_migration=False,                            # adds a DB migration
         touches_shared=True,                            # edits a shared module
         depends_on=["<sibling-task-id>"])               # explicit ordering

Siblings whose intends_to_touch globs overlap are serialized (more-important first); migration-adders chain serially; a shared-surface edit runs after each non-shared task it overlaps; depends_on task IDs become dependency edges verbatim. Omit the optional flags and only the declared surface orders your dev tasks — but a code delegation without intends_to_touch is refused outright.

Escalating to Main PM

Use escalate_up(task_id, reason) when:

• Cross-cell coordination is required
• Resource / priority conflict
• Scope grew beyond the cell
• A non-cell agent is blocking you

escalate_up(task_id="<task>",
            reason="Frontend cell needs the new auth endpoint we own; "
                   "they're blocked. Want to confirm priority swap.")