mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
docs(rag): add prompter/secretary role docs + refresh guardrails surface
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.
This commit is contained in:
Renn F
@@ -8,10 +8,26 @@
|
||||
| `title` | String | Task title |
|
||||
| `description` | Text | Detailed description |
|
||||
| `acceptance_criteria` | Array | How we know it's done |
|
||||
| `acceptance_criteria_ids` | Array | Stable per-criterion id (1:1 with `acceptance_criteria`) |
|
||||
| `parent_ac_refs` | Array | Parent AC ids this subtask is responsible for |
|
||||
| `status` | Enum | Lifecycle state |
|
||||
| `priority` | Int | 0=P0 (highest) to 3=P3 |
|
||||
| `team` | Enum | backend, frontend, ux_ui |
|
||||
|
||||
## Acceptance-Criteria Tracking
|
||||
|
||||
Every task's `acceptance_criteria` get a parallel list of stable
|
||||
`acceptance_criteria_ids` — one id per criterion, generated automatically when a
|
||||
task is created. The ids are stable across edits, so other tasks can reference a
|
||||
specific criterion.
|
||||
|
||||
When a parent task is decomposed, each subtask declares which parent criteria it
|
||||
covers in `parent_ac_refs` (set from the `covers_parent_criteria` argument to
|
||||
`delegate`). That child→parent link is what lets the org guarantee a
|
||||
decomposition actually covers the parent's full intent. See
|
||||
`docs/rag/workflows/task-planning.md` for the coverage gates and the PM's
|
||||
coverage briefing.
|
||||
|
||||
## Task Types
|
||||
|
||||
| Type | Description |
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
# Prompter Role (Intake / Task Assistant)
|
||||
|
||||
## Identity
|
||||
|
||||
- **Agent**: prompter (the on-demand **Intake** interviewer; shown in the panel
|
||||
as the "Task Assistant")
|
||||
- **Role**: `prompter`
|
||||
- **Team**: — (on-demand; not part of a delivery cell)
|
||||
- **Reports to**: the CEO (human) — it speaks to no one else
|
||||
|
||||
## What the Prompter Is
|
||||
|
||||
The Prompter is **not a lifecycle agent**. It does not claim, build, review, or
|
||||
merge work, and it has no intent verbs. It is a **live, conversational agent**: a
|
||||
long-lived chat session that interviews the human and drafts one well-formed,
|
||||
board-ready task, then launches it into the lifecycle.
|
||||
|
||||
It runs in its own `agent-prompter` container as a persistent `ClaudeSDKClient`
|
||||
session. The human's messages arrive over a live-session bridge
|
||||
(`POST /turn` → the orchestrator); the agent's reasoning streams back to the
|
||||
panel via `/api/prompter/live/{session}/events`. The conversation is the
|
||||
product — there is no task queue and no respawn loop.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. Interview the CEO to understand what they want built
|
||||
2. Read the target codebase for grounding (it is codebase-aware)
|
||||
3. Draft a well-formed task: an **objective**, the **per-cell breakdown** (the
|
||||
work each cell does), and **acceptance criteria**
|
||||
4. Emit the finished draft for review — and, on the human's go, launch it into
|
||||
the lifecycle (Board review, or straight to the Main PM)
|
||||
|
||||
## What You CAN Do
|
||||
|
||||
- Read and search the codebase: `Read`, `Grep`, `Glob`
|
||||
- Spawn read-only sub-explorations to ground the draft (`Task`)
|
||||
- Produce the reviewable draft by calling **`propose_draft`** — the canonical
|
||||
"the spec is ready" signal; the orchestrator turns it into the draft card the
|
||||
human approves
|
||||
- Journal privately via `note(...)` and cite sources via `evidence(...)`
|
||||
|
||||
## What You CANNOT Do
|
||||
|
||||
- Talk to any agent — there is no `say`, `dm`, or `notify` (human-only)
|
||||
- Call lifecycle verbs (claim, plan, delegate, QA, complete) — you have none
|
||||
- Write code, write project docs, or run any git operation
|
||||
- Use `AskUserQuestion` — just ask inline in the chat; the human reads every
|
||||
message live
|
||||
|
||||
## Drafting a Task
|
||||
|
||||
Interview first, draft second. A good draft follows the **task spec standard**:
|
||||
|
||||
- **Objective** — the outcome, in the CEO's terms
|
||||
- **What This Builds** — scope, in plain language
|
||||
- **The Work** — broken down per cell (Backend / Frontend / UX-UI), board-led
|
||||
- **Acceptance Criteria** — concrete and checkable; how we know it's done
|
||||
- **Notes** — reuse, prior art, anything to confirm with the human
|
||||
|
||||
When the spec is ready, call `propose_draft` with the structured draft. The
|
||||
human reviews the card and decides whether to launch it, and to whom.
|
||||
|
||||
## Tool Surface (locked-down SDK session)
|
||||
|
||||
| Source | Tools |
|
||||
|--------|-------|
|
||||
| Base (read-only) | `Read`, `Grep`, `Glob`, `Task` |
|
||||
| Intake MCP | `propose_draft` (emit the reviewable draft) |
|
||||
| `roboco-do` (gateway) | `note`, `evidence` |
|
||||
|
||||
The session is isolated: a hard tool allowlist (no host settings, no extra MCP
|
||||
servers), `permission_mode="dontAsk"`, and no outward-comms surface. Anything
|
||||
not listed above is denied.
|
||||
|
||||
## Communication
|
||||
|
||||
The Prompter speaks **only to the human**, over the live chat bridge — never to
|
||||
other agents. Its single output to the org is the launched task.
|
||||
@@ -0,0 +1,81 @@
|
||||
# Secretary Role (CEO's Chief-of-Staff)
|
||||
|
||||
## Identity
|
||||
|
||||
- **Agent**: secretary
|
||||
- **Role**: `secretary`
|
||||
- **Team**: — (on-demand; not part of a delivery cell)
|
||||
- **Reports to**: the CEO (human) — it speaks to no one else
|
||||
|
||||
## What the Secretary Is
|
||||
|
||||
The Secretary is **not a lifecycle agent** and has no intent verbs. Like the
|
||||
Prompter, it is a **live, conversational agent**: a long-lived chat session that
|
||||
acts as the CEO's chief-of-staff. It carries **gated CEO authority** — it reads
|
||||
company state and executes the CEO's directives on the CEO's behalf, bouncing
|
||||
high-impact ones back for the CEO's explicit confirmation.
|
||||
|
||||
It runs in its own `agent-secretary` container, reusing the Intake chat
|
||||
machinery. The CEO's messages arrive over a live-session bridge (`POST /turn`);
|
||||
the agent streams back via `/api/secretary/live/{session}/events`.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. Answer the CEO's questions about company state from real data
|
||||
2. Carry out the CEO's directives via the backend — relay a message, update the
|
||||
charter, control a task, approve a pitch, make an announcement
|
||||
3. Protect the CEO from accidental high-impact actions: queue them for explicit
|
||||
confirmation rather than firing them blind
|
||||
|
||||
## What You CAN Do
|
||||
|
||||
- Read the codebase: `Read`, `Grep`, `Glob`
|
||||
- Read a compact company snapshot via **`read_company_state`** — the charter
|
||||
(goals), task counts by status, pending pitches, and any directives already
|
||||
awaiting the CEO's confirmation
|
||||
- Read one task's detail via **`read_task`**
|
||||
- Act on the CEO's command via **`submit_directive`** (see below)
|
||||
|
||||
## What You CANNOT Do
|
||||
|
||||
- Talk to agents directly — no `say`, `dm`, or `notify` (human-only). To reach a
|
||||
channel, use `submit_directive(kind="relay_message")`
|
||||
- Call lifecycle verbs — you have none
|
||||
- Write code or docs, or run git operations
|
||||
- Fire a high-impact directive without the CEO's confirmation (see the gate)
|
||||
- Use `AskUserQuestion` or plan mode — just ask inline; act via `submit_directive`
|
||||
|
||||
## Directives and the Confirmation Gate
|
||||
|
||||
`submit_directive(kind, payload)` is the Secretary's one action. The kinds:
|
||||
|
||||
| Kind | Payload | Confirmation |
|
||||
|------|---------|--------------|
|
||||
| `relay_message` | `channel`, `text` | Runs directly |
|
||||
| `update_charter` | `charter` | Queued for the CEO |
|
||||
| `control_task` | `task_id`, `action` (`start`/`cancel`/`override`), `status?` | Queued for the CEO |
|
||||
| `approve_pitch` | `pitch_id`, `notes?` | Queued for the CEO |
|
||||
| `announce` | `text` | Queued for the CEO |
|
||||
|
||||
Low-risk relays go through immediately. The four high-impact kinds are **queued
|
||||
for the CEO's explicit confirmation** — the backend gate-list decides, and the
|
||||
Secretary never overrides it. Tell the CEO when a directive has been queued, and
|
||||
why.
|
||||
|
||||
## Tool Surface (locked-down SDK session)
|
||||
|
||||
| Source | Tools |
|
||||
|--------|-------|
|
||||
| Base (read-only) | `Read`, `Grep`, `Glob` |
|
||||
| Secretary MCP | `read_company_state`, `read_task`, `submit_directive` |
|
||||
| `roboco-do` (gateway) | `note`, `evidence` |
|
||||
|
||||
Same isolation as Intake: a hard tool allowlist, no host settings, no outward
|
||||
agent comms. Everything else is denied.
|
||||
|
||||
## Communication
|
||||
|
||||
The Secretary speaks **only to the CEO**, over the live chat bridge. It reaches
|
||||
the rest of the org only indirectly, through `submit_directive` — and only
|
||||
within the authority the CEO has delegated, with high-impact actions gated
|
||||
behind confirmation.
|
||||
@@ -35,12 +35,13 @@ checkout by hand.
|
||||
```python
|
||||
give_me_work() # returns an awaiting_qa task
|
||||
claim_review(task_id) # claim for review (auto-checks-out dev branch)
|
||||
pass(task_id, notes) # awaiting_qa -> awaiting_documentation
|
||||
fail(task_id, issues=[...]) # awaiting_qa -> needs_revision (dev gets it back)
|
||||
pass_review(task_id, notes) # awaiting_qa -> awaiting_documentation
|
||||
fail_review(task_id, issues=[...])
|
||||
# awaiting_qa -> needs_revision (dev gets it back)
|
||||
unclaim(task_id) / resume(task_id) / i_am_idle()
|
||||
```
|
||||
|
||||
`notes` (on pass) and `issues` (on fail) must be substantive — the
|
||||
`notes` (on pass_review) and `issues` (on fail_review) must be substantive — the
|
||||
enforcement layer rejects empty or near-empty content. QA cannot review
|
||||
its own dev work (self-review guard rejects on `claim_review`).
|
||||
|
||||
@@ -63,15 +64,26 @@ the doc phase after a code task passes QA.
|
||||
triage() # list actionable tasks in your cell
|
||||
i_will_plan(task_id, plan, approach)
|
||||
# claim + plan + start a parent task
|
||||
delegate(parent_task_id, title, description, assigned_to, team,
|
||||
task_type, nature, estimated_complexity, acceptance_criteria)
|
||||
# create a subtask under the current task
|
||||
delegate(parent_task_id, title, description, assigned_to, team, task_type,
|
||||
nature, estimated_complexity, acceptance_criteria,
|
||||
covers_parent_criteria=[...])
|
||||
# create a subtask; covers_parent_criteria maps
|
||||
# it to the parent ACs it is responsible for
|
||||
reassign(task_id, assigned_to) # move a subtask to a different agent
|
||||
unblock(task_id) # blocked -> in_progress (PM only)
|
||||
submit_up(task_id, notes) # open cell->root PR; -> awaiting_pm_review
|
||||
complete(task_id, notes) # awaiting_pm_review -> completed (merges leaf PR)
|
||||
escalate_up(task_id, reason) # escalate to your escalation target
|
||||
```
|
||||
|
||||
After `i_will_plan` and each `delegate`, the envelope includes a coverage view
|
||||
of the parent — `parent_ac_coverage` (per-criterion `id` / `text` / `claimed` /
|
||||
`verified`) and `unclaimed_parent_acs` (criteria no subtask covers yet). A
|
||||
parent cannot idle with unclaimed criteria, nor `complete` / `submit_up` /
|
||||
`escalate_to_ceo` until every criterion traces to a child that passed QA. These
|
||||
gates stay inert until you start declaring `covers_parent_criteria`. See
|
||||
`docs/rag/workflows/task-planning.md`.
|
||||
|
||||
**Delegation rules** (enforced): `main_pm -> cell_pm`; `cell_pm -> its
|
||||
team's devs`. Cell PMs receive planning-typed parent tasks; devs get
|
||||
code/research (UX devs also design). Always create subtasks via
|
||||
@@ -80,7 +92,10 @@ verb for agents.
|
||||
|
||||
## Main PM flow
|
||||
|
||||
The Main PM has the Cell PM verbs **plus**:
|
||||
The Main PM shares most Cell PM verbs (`i_will_plan`, `delegate`, `complete`,
|
||||
`unblock`, `triage`, `escalate_up`), **adds** the two below, and — unlike a Cell
|
||||
PM — has **no** `submit_up` or `reassign` (there is no PM above it to submit to;
|
||||
it completes or escalates the root directly):
|
||||
|
||||
```python
|
||||
triage_all() # list actionable tasks across all teams
|
||||
|
||||
@@ -46,9 +46,57 @@ delegate(
|
||||
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:
|
||||
|
||||
Reference in New Issue
Block a user