mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
docs(rag): fix PM delegate signature + cross-link cell-pm ↔ main-pm
The cell-pm role doc showed delegate with a nonexistent nested body={...}
and omitted covers_parent_criteria, so an agent following it would make a
malformed call and burn turns rediscovering the real shape. Both PM docs now
match the actual flow_server.delegate signature (flat keywords, with
covers_parent_criteria; the subtask inherits the parent's project — resolved
from the product cell→project map for coordination roots, never passed).
Also document reassign (cell PM could call it but it was undocumented) and
cross-link the two roles: cell-pm explains submit_up hands finished work to
Main PM; main-pm explains the receiving side — the integration-branch chain,
that its complete on the root opens the master PR, and that only Main PM and
the CEO act on master.
This commit is contained in:
+26
-16
@@ -42,18 +42,22 @@ give_me_work() → returns a pending parent task assigned to you
|
|||||||
i_will_plan(task_id, plan) → claims + starts + auto-creates the parent
|
i_will_plan(task_id, plan) → claims + starts + auto-creates the parent
|
||||||
branch feature/{team}/{root}/{your_id}
|
branch feature/{team}/{root}/{your_id}
|
||||||
delegate(parent_task_id=..., title=..., description=...,
|
delegate(parent_task_id=..., title=..., description=...,
|
||||||
body={"assigned_to": "be-dev-1", "team": "backend",
|
assigned_to="be-dev-1", team="backend", task_type="code",
|
||||||
"task_type": "code", "acceptance_criteria": [...]})
|
nature="technical", acceptance_criteria=[...],
|
||||||
|
covers_parent_criteria=[...])
|
||||||
→ creates a subtask, child branch will
|
→ creates a subtask, child branch will
|
||||||
fork off yours when the dev claims it
|
fork off yours when the dev claims it
|
||||||
|
|
||||||
triage() → scan your cell's queue
|
triage() → scan your cell's queue
|
||||||
unblock(task_id, restore=True) → unblock + restore prior status
|
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 leaf PR; transitions task
|
complete(task_id, notes) → merges the leaf PR; transitions task
|
||||||
to completed (or escalates root parent
|
to completed (or escalates root parent
|
||||||
to CEO via Main PM)
|
to CEO via Main PM)
|
||||||
|
|
||||||
submit_up(task_id, notes) → bubble cell-scoped completion up
|
submit_up(task_id, notes) → bubble finished cell-scoped work up to
|
||||||
|
Main PM, who integrates it (see below)
|
||||||
escalate_up(task_id, reason) → ask Main PM for help (cross-cell, etc.)
|
escalate_up(task_id, reason) → ask Main PM for help (cross-cell, etc.)
|
||||||
unclaim(task_id) / resume(task_id) / i_am_idle()
|
unclaim(task_id) / resume(task_id) / i_am_idle()
|
||||||
```
|
```
|
||||||
@@ -62,7 +66,7 @@ unclaim(task_id) / resume(task_id) / i_am_idle()
|
|||||||
|
|
||||||
| MCP server | Verbs you can call |
|
| 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-flow` | `give_me_work`, `i_will_plan`, `delegate`, `submit_up`, `triage`, `unblock`, `reassign`, `complete`, `escalate_up`, `unclaim`, `resume`, `i_am_idle` |
|
||||||
| `roboco-do` | `note`, `say`, `dm`, `notify`, `evidence` (no `commit`) |
|
| `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-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||||
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
|
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
|
||||||
@@ -81,21 +85,21 @@ delegate(
|
|||||||
parent_task_id="<your-parent>",
|
parent_task_id="<your-parent>",
|
||||||
title="Implement Redis rate limiter",
|
title="Implement Redis rate limiter",
|
||||||
description="Token-bucket per-route, 100 req/s default.",
|
description="Token-bucket per-route, 100 req/s default.",
|
||||||
body={
|
assigned_to="be-dev-1",
|
||||||
"assigned_to": "be-dev-1",
|
team="backend",
|
||||||
"team": "backend",
|
task_type="code",
|
||||||
"task_type": "code",
|
nature="technical",
|
||||||
"acceptance_criteria": [
|
acceptance_criteria=[
|
||||||
"POST /api/foo with 101 reqs in 1s returns 429",
|
"POST /api/foo with 101 reqs in 1s returns 429",
|
||||||
"Redis key TTL matches the configured window",
|
"Redis key TTL matches the configured window",
|
||||||
"Tests cover happy path + boundary",
|
"Tests cover happy path + boundary",
|
||||||
],
|
],
|
||||||
"estimated_complexity": "medium",
|
estimated_complexity="medium",
|
||||||
},
|
covers_parent_criteria=["<parent-ac-id>", "..."],
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
|
|
||||||
`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`).
|
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
|
## Completing Tasks
|
||||||
|
|
||||||
@@ -138,6 +142,12 @@ notify(target="be-dev-1", text="Please prioritise task X by EOD.",
|
|||||||
priority="high", task_id="...")
|
priority="high", task_id="...")
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Submitting Finished Work Up
|
||||||
|
|
||||||
|
When a cell-scoped task is done (QA green, docs landed, leaf PR merged into your cell branch via `complete`), `submit_up(task_id, notes)` hands it to **Main PM (main-pm)**. Main PM owns the integration branch and the master PR — it merges your cell branch up the chain and ultimately into master (you never open a master PR yourself). See the Main PM role doc, "Integrating cell work + completing the root."
|
||||||
|
|
||||||
|
`submit_up` is for finished work moving up; `escalate_up` (below) is for *help* you need while work is still in flight.
|
||||||
|
|
||||||
## Escalating to Main PM
|
## Escalating to Main PM
|
||||||
|
|
||||||
Use `escalate_up(task_id, reason)` when:
|
Use `escalate_up(task_id, reason)` when:
|
||||||
|
|||||||
@@ -42,7 +42,10 @@ note(
|
|||||||
title="Task breakdown for [feature]",
|
title="Task breakdown for [feature]",
|
||||||
)
|
)
|
||||||
|
|
||||||
# 3. Delegate a subtask to each cell PM (parent must be in_progress)
|
# 3. Delegate a subtask to each cell PM (parent must be in_progress).
|
||||||
|
# Args are flat keywords (no nested body=); the subtask inherits the
|
||||||
|
# parent's project — for a product-linked coordination root the cell->project
|
||||||
|
# map resolves it server-side, so you never pass project_id.
|
||||||
delegate(
|
delegate(
|
||||||
parent_task_id=initiative_id,
|
parent_task_id=initiative_id,
|
||||||
title="Backend: Implement API",
|
title="Backend: Implement API",
|
||||||
@@ -50,10 +53,10 @@ delegate(
|
|||||||
assigned_to="be-pm",
|
assigned_to="be-pm",
|
||||||
team="backend",
|
team="backend",
|
||||||
task_type="planning",
|
task_type="planning",
|
||||||
nature="...",
|
nature="technical",
|
||||||
estimated_complexity="...",
|
|
||||||
acceptance_criteria=["..."],
|
acceptance_criteria=["..."],
|
||||||
project_id="<project-uuid>",
|
estimated_complexity="medium",
|
||||||
|
covers_parent_criteria=["<initiative-ac-id>", "..."],
|
||||||
)
|
)
|
||||||
|
|
||||||
# 4. Open a coordination session for the related subtasks
|
# 4. Open a coordination session for the related subtasks
|
||||||
@@ -91,11 +94,26 @@ Registering repositories and storing git tokens is **not** an agent action — i
|
|||||||
|
|
||||||
## Handling Cell PM Escalations
|
## Handling Cell PM Escalations
|
||||||
|
|
||||||
When a Cell PM escalates:
|
When a Cell PM escalates (`escalate_up`):
|
||||||
1. Review cross-cell impact
|
1. Review cross-cell impact
|
||||||
2. Coordinate with other Cell PMs if needed
|
2. Coordinate with other Cell PMs if needed
|
||||||
3. Make the decision (`unblock`, `complete`) or escalate up
|
3. Make the decision (`unblock`, `complete`) or escalate up
|
||||||
|
|
||||||
|
This is for *help while work is in flight*. Finished cell-scoped work arrives by a different path — `submit_up` (below).
|
||||||
|
|
||||||
|
## Integrating cell work + completing the root
|
||||||
|
|
||||||
|
You own the integration-branch chain and the master PR. Cell PMs `submit_up(task_id, notes)` their finished cell-scoped tasks to you; they merge only their own cell/leaf PRs and never touch master (see the Cell PM role doc, "Submitting Finished Work Up").
|
||||||
|
|
||||||
|
```
|
||||||
|
master ← feature/main_pm/{root} ← feature/{cell}/{root}/{cell-pm} ← dev branches
|
||||||
|
(you + CEO) (you) (cell PM) (devs)
|
||||||
|
```
|
||||||
|
|
||||||
|
- A cell PM's `complete` merges a leaf PR into its cell branch; `submit_up` then hands the cell-scoped result to you.
|
||||||
|
- Your `complete(root_task_id, notes)` on the **root** parent is what opens/merges the master-bound PR — once every cell's subtasks are terminal.
|
||||||
|
- For major work, escalate the finished root to the CEO with `escalate_to_ceo(root_task_id, reason)` instead; the CEO approves and merges from the panel. Only Main PM and the CEO ever act on master.
|
||||||
|
|
||||||
## A2A
|
## A2A
|
||||||
|
|
||||||
```python
|
```python
|
||||||
|
|||||||
Reference in New Issue
Block a user