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, restore=True)`
- Complete tasks via `complete(task_id, notes)` — this merges the leaf
  PR (no separate `merge_pr` tool exists; the choreographer does it)
- Submit a finished cell-scoped task up to Main PM via
  `submit_up(task_id, notes)`
- 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 the master PR → that's Main PM's `complete` on the root parent
- Run shell git — blocked by the bash-guard hook

## 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=...,
         body={"assigned_to": "be-dev-1", "team": "backend",
               "task_type": "code", "acceptance_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
complete(task_id, notes)       → merges the leaf PR; transitions task
                                 to completed (or escalates root parent
                                 to CEO via Main PM)

submit_up(task_id, notes)      → bubble cell-scoped completion up
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`, `complete`, `escalate_up`, `unclaim`, `resume`, `i_am_idle` |
| `roboco-do`           | `note`, `say`, `dm`, `notify`, `evidence` (no `commit`) |
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
| `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

```python
delegate(
    parent_task_id="<your-parent>",
    title="Implement Redis rate limiter",
    description="Token-bucket per-route, 100 req/s default.",
    body={
        "assigned_to": "be-dev-1",
        "team": "backend",
        "task_type": "code",
        "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",
    },
)
```

`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`).

## Completing Tasks

After QA passed and docs complete (`awaiting_pm_review` state):

```python
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)

## Monitoring Your Cell

```python
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

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

# Cell-wide announcement (visible to whole cell)
say(channel="backend-cell", text="Heads up — sprint cut at 18:00 UTC.")

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

## 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

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