mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
568ae7a25d
The agents' runtime KB had drifted three releases behind the gateway. Add the two missing role docs (prompter, secretary — both live-session SDK chat roles, human-only) and fold the AC/decomposition guardrails and per-dev code queues into the high-traffic PM docs: - task-model: acceptance_criteria_ids + parent_ac_refs fields and how the child->parent AC link works. - task-planning: covers_parent_criteria on delegate, the parent_ac_coverage / unclaimed_parent_acs briefing fields, the decomposition-floor and roll-up gates (safe-by-construction), and per-dev sequenced code queues. - task-tools: same coverage note + correct stale verbs — QA is pass_review/fail_review (not pass/fail), cell_pm gains reassign, and main_pm no longer claims submit_up/reassign it does not have.
113 lines
4.1 KiB
Markdown
113 lines
4.1 KiB
Markdown
# Task Planning Workflow
|
|
|
|
## Overview
|
|
|
|
Planning is a **PM activity**. When a PM (Cell PM or Main PM) picks up a
|
|
coordination or parent task, they record a plan with `i_will_plan` and
|
|
then fan the work out into subtasks with `delegate`.
|
|
|
|
```
|
|
triage / give_me_work → i_will_plan → delegate (one per subtask) → i_am_idle
|
|
```
|
|
|
|
Developers do not have a separate planning verb — they pass a short
|
|
`plan` argument directly to `i_will_work_on(task_id, plan="...")` when
|
|
they claim a coding task.
|
|
|
|
## Submitting a Plan (PM)
|
|
|
|
```python
|
|
i_will_plan(
|
|
task_id="<task>",
|
|
plan="One-paragraph summary of how this work will be broken down",
|
|
approach="High-level implementation strategy",
|
|
sub_tasks=[
|
|
"UX/UI: design the settings panel",
|
|
"Frontend: wire the panel to the API",
|
|
"Backend: add the settings endpoint",
|
|
],
|
|
technical_considerations=["Reuse the existing config service"],
|
|
risks=["Frontend depends on the UX design landing first"],
|
|
open_questions=["Confirm the default toggle state with the CEO"],
|
|
)
|
|
```
|
|
|
|
After `i_will_plan`, the envelope's `next` field points you at
|
|
`delegate` — create one subtask per unit of work:
|
|
|
|
```python
|
|
delegate(
|
|
parent_task_id="<task>",
|
|
title="Add the settings endpoint",
|
|
description="...",
|
|
assigned_to="be-dev-1",
|
|
team="backend",
|
|
task_type="code",
|
|
nature="feature",
|
|
estimated_complexity="medium",
|
|
acceptance_criteria=["Endpoint returns 200 with the saved settings"],
|
|
covers_parent_criteria=["<parent-ac-id>"],
|
|
)
|
|
```
|
|
|
|
## Acceptance-Criteria Coverage
|
|
|
|
When you decompose a parent task, declare which parent criteria each subtask is
|
|
responsible for with **`covers_parent_criteria`** (a list of the parent's
|
|
`acceptance_criteria_ids`). This is what lets the org prove a decomposition
|
|
covers the parent's full intent — and it drives two gates and your coverage
|
|
briefing.
|
|
|
|
After `i_will_plan` and after each `delegate`, your envelope carries a coverage
|
|
view of the parent so you can see what is still unmapped:
|
|
|
|
- **`parent_ac_coverage`** — one entry per parent criterion: its `id`, `text`,
|
|
whether a live subtask `claimed` it, and whether a completed subtask
|
|
`verified` it.
|
|
- **`unclaimed_parent_acs`** — the parent criterion ids that no live subtask
|
|
covers yet. Keep delegating until this is empty.
|
|
|
|
Two gates build on the coverage link:
|
|
|
|
- **Decomposition floor** — you cannot go `i_am_idle` on a parent while a
|
|
criterion is still unclaimed. Delegate (or `reassign`) subtasks until every
|
|
criterion is covered.
|
|
- **Roll-up gate** — a parent cannot `complete`, `submit_up`, or
|
|
`escalate_to_ceo` unless every criterion traces to a child that **passed QA**
|
|
on it.
|
|
|
|
Both gates are **safe-by-construction**: they stay inert until you start
|
|
declaring `covers_parent_criteria`, so a decomposition that never declares
|
|
coverage is never blocked. Declaring coverage is how you opt your parent into
|
|
the guarantee.
|
|
|
|
## Delegating Code Work: Per-Dev Queues
|
|
|
|
For code subtasks, delegate each developer their **full queue up front** rather
|
|
than one task at a time. Both of a cell's developers build in parallel, and each
|
|
works its own queue one task at a time, in order:
|
|
|
|
- A per-lane dispatch barrier holds a developer's later subtasks until their
|
|
current one is in flight — so each dev's lane stays sequenced while the two
|
|
devs run concurrently.
|
|
- Leaf PRs are still merged into the shared cell branch **in sequence**, not
|
|
in parallel.
|
|
- Order the queue by dependency: the subtask others build on goes first.
|
|
|
|
Caps still apply: at most 12 subtasks per parent, and same-title duplicate
|
|
subtasks are rejected.
|
|
|
|
## Git Workflow
|
|
|
|
All code tasks follow the git workflow:
|
|
- **Branches are auto-created when a developer claims the task** via
|
|
`i_will_work_on` — no manual branch creation
|
|
- Root tasks: branch created from the default branch (main/master)
|
|
- Subtasks: branch forked from the parent's branch
|
|
|
|
Coordination/parent tasks that only plan and delegate (no code) do not
|
|
need a branch of their own.
|
|
|
|
Hierarchical branch naming uses `--` between task IDs to avoid git ref
|
|
conflicts: `feature/{team}/{ROOT}--{SUB}--{SUBSUB}`.
|