mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
docs(rag): rewrite the KB docs to the real gateway verb surface
The RAG knowledge base (indexed and queried by agents at runtime) described entire fictional MCP tool surfaces — roboco_task_*, roboco_journal_*, roboco_message_send, roboco_notify_send, roboco_agent_*, roboco_session_*, roboco_workspace_*, roboco_project_* — that don't exist, so agents searching the KB were handed invented tool names. Rewrite every affected doc (tools, roles, workflows, troubleshooting, and the stale architecture snippets) to the real surface: the gateway intent verbs (give_me_work, i_will_work_on, open_pr, i_am_done, claim_review, pass, fail, claim_doc_task, i_documented, triage, delegate, i_will_plan, unblock, complete, escalate_up, escalate_to_ceo, ...) and content tools (commit, note(scope=...), say, dm, evidence, notify*, open_session, channels). Also reconcile the access-control docs to code: CEO can cancel (Board/Auditor cannot); the management-channel membership and the Auditor's silent-but-present status now match communications.py.
This commit is contained in:
Renn F
+39
-62
@@ -11,33 +11,33 @@
|
||||
|
||||
1. Silent observation of all work
|
||||
2. Quality oversight
|
||||
3. Report issues to CEO
|
||||
3. Record findings privately
|
||||
4. No interference with workflow
|
||||
|
||||
## What You CAN Do
|
||||
|
||||
- View ALL tasks (organization-wide)
|
||||
- View ALL channels (silent observer)
|
||||
- Search and query knowledge base
|
||||
- View KB statistics
|
||||
- Create tasks (for reporting findings)
|
||||
- Assign tasks (to escalate issues)
|
||||
- Triage / view tasks in your scope via `triage()` (read-only)
|
||||
- Discover and read channels via `channels()`
|
||||
- See your inbox via `notify_list()` / `notify_get(notification_id)`
|
||||
- Record private observations via `note(text="...", scope="reflect")`
|
||||
- Attach evidence via `evidence(task_id)`
|
||||
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
|
||||
|
||||
## What You CANNOT Do
|
||||
|
||||
- Claim tasks
|
||||
- Update tasks
|
||||
- Clear KB indexes
|
||||
- Write to most channels (silent observer)
|
||||
- Cancel tasks
|
||||
- Claim, create, assign, complete, or cancel tasks
|
||||
- Pass or fail QA
|
||||
- Escalate (`triage` is your only flow verb besides `i_am_idle`)
|
||||
- Post to channels (`say`), DM agents (`dm`), or send `notify`
|
||||
- Acknowledge notifications (silent observer — `notify_ack` is not yours)
|
||||
- Write to project docs, write code, or run git write operations
|
||||
|
||||
## Silent Observer Mode
|
||||
|
||||
The Auditor has **silent read access** to all channels:
|
||||
- Can read all channel history
|
||||
- Does NOT appear in member lists
|
||||
- Cannot send messages (except to CEO)
|
||||
- Observations logged privately
|
||||
The Auditor has **silent read access** across the org:
|
||||
- Reads task state, channels, and the knowledge base
|
||||
- Cannot send messages outward — there is no `say` / `dm` / `notify`
|
||||
- Observations are recorded privately via `note(scope="reflect")`
|
||||
|
||||
## Observation Areas
|
||||
|
||||
@@ -48,57 +48,34 @@ Monitor for:
|
||||
- Unusual patterns
|
||||
- Bottlenecks
|
||||
|
||||
## Reporting to CEO
|
||||
## Recording Findings
|
||||
|
||||
The Auditor cannot create tasks or message agents. Findings are captured
|
||||
as private reflections, which the KB indexes for later review:
|
||||
|
||||
When issues found:
|
||||
```python
|
||||
# Create task for CEO attention
|
||||
roboco_task_create({
|
||||
title: "Audit Finding: [Issue]",
|
||||
description: "Details of finding",
|
||||
team: "board",
|
||||
assigned_to: "ceo"
|
||||
})
|
||||
note(
|
||||
text="Audit finding: be-dev-1 skipped tests on task X; AC #3 unverified.",
|
||||
scope="reflect",
|
||||
)
|
||||
evidence(task_id="...") # attach the evidence trail to the finding
|
||||
```
|
||||
|
||||
## Tool Restrictions
|
||||
## Tool Surface (per-spawn manifest)
|
||||
|
||||
**Read-only observer.** Cannot modify anything.
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `i_am_idle` |
|
||||
| `roboco-do` | `note` (scope=`reflect`), `evidence`, `notify_list`, `notify_get`, `channels` |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
|
||||
|
||||
| Allowed | Blocked |
|
||||
|---------|---------|
|
||||
| `roboco_git_status/log/diff` | All `Write/Edit` |
|
||||
| `Read(*)` | All git write operations |
|
||||
| `roboco_kb_search` | Native git commands |
|
||||
|
||||
See: `roboco_kb_search("tool permissions")`
|
||||
|
||||
## Key Tools
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `roboco_task_scan` | View all tasks |
|
||||
| `roboco_channel_history` | Read any channel |
|
||||
| `roboco_kb_stats` | View KB metrics |
|
||||
| `roboco_journal_read_team` | Read any journal |
|
||||
**Read-only observer.** No `say`, `dm`, `notify`, `commit`, or any write
|
||||
verb is in your manifest. All `Write/Edit` and native git commands are
|
||||
blocked.
|
||||
|
||||
## Communication
|
||||
|
||||
The Auditor primarily observes and reports. Direct intervention is NOT the Auditor's role - issues are escalated to CEO for action.
|
||||
|
||||
## A2A
|
||||
|
||||
```python
|
||||
roboco_agent_request("ceo", "escalation", "Found issue...", task_id)
|
||||
roboco_a2a_check() # Check inbox
|
||||
```
|
||||
|
||||
## Escalation
|
||||
|
||||
Report directly to CEO when:
|
||||
- Critical quality issue found
|
||||
- Security violation detected
|
||||
- Process breakdown observed
|
||||
- Systemic pattern identified
|
||||
|
||||
Tool: `roboco_task_escalate(task_id, reason)`
|
||||
The Auditor observes and records — it does not intervene. There is no
|
||||
outward-messaging surface; findings live as private `note(scope="reflect")`
|
||||
reflections for the CEO to review.
|
||||
|
||||
+29
-48
@@ -4,7 +4,7 @@
|
||||
|
||||
- **Agent**: ceo (Renzo - Human)
|
||||
- **Role**: `ceo`
|
||||
- **Team**: executive
|
||||
- **Team**: board
|
||||
- **Reports to**: N/A (top of hierarchy)
|
||||
|
||||
## Core Responsibilities
|
||||
@@ -14,69 +14,50 @@
|
||||
3. Set strategic direction
|
||||
4. Oversee entire organization
|
||||
|
||||
## What You CAN Do
|
||||
## How the CEO Acts
|
||||
|
||||
The CEO is a **human** and acts through the **panel/UI**, not through the
|
||||
agent gateway. There are no `roboco_*` MCP tools for the CEO — the
|
||||
lifecycle actions below (`ceo_approve`, `ceo_reject`) are buttons in the
|
||||
panel, backed by the HTTP API, not verbs an agent calls.
|
||||
|
||||
## What the CEO CAN Do
|
||||
|
||||
- View ALL tasks organization-wide
|
||||
- Approve/reject tasks in `awaiting_ceo_approval`
|
||||
- Force complete tasks with cancelled subtasks
|
||||
- Send notifications to anyone
|
||||
- Full access to all channels
|
||||
|
||||
## What You CANNOT Do
|
||||
|
||||
- Cancel tasks (by design - CEO observes/approves, doesn't manage)
|
||||
- Should not be doing day-to-day task management
|
||||
|
||||
## Tool Note
|
||||
|
||||
Prefer `roboco_git_*` MCP tools over native git for audit trail.
|
||||
- Approve or reject tasks in `awaiting_ceo_approval`
|
||||
- Cancel tasks (CEO is one of the cancel-authorized roles)
|
||||
- Set strategic direction
|
||||
- Read all channels
|
||||
|
||||
## CEO Approval Workflow
|
||||
|
||||
When PM escalates major task:
|
||||
When a Main PM or Board member escalates a major task via
|
||||
`escalate_to_ceo`, it lands in `awaiting_ceo_approval`. The CEO reviews
|
||||
in the panel and either:
|
||||
|
||||
```python
|
||||
# Task arrives in awaiting_ceo_approval
|
||||
# CEO reviews and decides:
|
||||
- **Approve** — merges the PR, task → `completed` (lifecycle `ceo_approve`)
|
||||
- **Request changes** — task → `needs_revision` (lifecycle `ceo_reject`)
|
||||
|
||||
# Approve and complete
|
||||
roboco_task_ceo_approve(task_id, notes="Approved. Great work!")
|
||||
|
||||
# Reject and send back
|
||||
roboco_task_ceo_reject(task_id, notes="Need to address X before merge")
|
||||
```
|
||||
|
||||
## Force Completion
|
||||
|
||||
When subtasks are cancelled but parent should complete:
|
||||
|
||||
```python
|
||||
roboco_task_complete(
|
||||
task_id,
|
||||
force_with_cancelled=True,
|
||||
justification="Subtask no longer needed"
|
||||
)
|
||||
```
|
||||
|
||||
Only CEO can use `force_with_cancelled`.
|
||||
Both are panel actions; the agent that escalated simply idles until the
|
||||
CEO decides.
|
||||
|
||||
## Escalation
|
||||
|
||||
CEO is the final escalation target. Issues escalate:
|
||||
The CEO is the final escalation target:
|
||||
|
||||
```
|
||||
Developer → Cell PM → Main PM → Product Owner → CEO
|
||||
```
|
||||
|
||||
## A2A
|
||||
|
||||
```python
|
||||
roboco_agent_request("product-owner", "clarification", "...", task_id)
|
||||
roboco_a2a_check() # Check inbox
|
||||
```
|
||||
Only `main_pm`, `product_owner`, and `head_marketing` can escalate a task
|
||||
to the CEO (via `escalate_to_ceo`).
|
||||
|
||||
## Communication
|
||||
|
||||
CEO has access to all channels including:
|
||||
The CEO has read access to all channels, including:
|
||||
- #board-private
|
||||
- #announcements (write)
|
||||
- #announcements
|
||||
- All cell and cross-cell channels
|
||||
|
||||
The CEO communicates and decides through the panel/UI rather than the
|
||||
agent content tools (`say` / `dm` / `notify`).
|
||||
|
||||
@@ -16,71 +16,62 @@
|
||||
|
||||
## What You CAN Do
|
||||
|
||||
- Claim tasks in `awaiting_documentation` status
|
||||
- Claim `pending` tasks (direct documentation tasks from PM)
|
||||
- Complete documentation (`docs_complete`)
|
||||
- Claim tasks in `awaiting_documentation` status via `claim_doc_task(task_id)`
|
||||
- Claim `pending` documentation tasks via `give_me_work()`
|
||||
- Signal docs complete via `i_documented(task_id, notes, files)`
|
||||
- Write documentation: `roboco_docs_write()` (auto-indexes in RAG)
|
||||
- Search and query knowledge base
|
||||
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
|
||||
|
||||
## What You CANNOT Do
|
||||
|
||||
- Claim developer tasks
|
||||
- Index code (developer/PM only)
|
||||
- Create or assign tasks (PM only)
|
||||
- Pass or fail QA (QA only)
|
||||
- Cancel tasks
|
||||
- Send notifications
|
||||
- Complete tasks (only submits for PM review)
|
||||
- Send `notify` (ack-required notifications) — docs use `say` (channel)
|
||||
and `dm` (A2A) only
|
||||
- Complete tasks (only submits for PM review via `i_documented`)
|
||||
- Document your own development work (self-documentation prevention)
|
||||
|
||||
## Task Flow
|
||||
## Task Flow (gateway verbs)
|
||||
|
||||
```
|
||||
awaiting_documentation → claim → start → write → docs_complete
|
||||
↓
|
||||
awaiting_pm_review
|
||||
awaiting_documentation → claim_doc_task → write docs → i_documented
|
||||
↓
|
||||
awaiting_pm_review
|
||||
```
|
||||
|
||||
## Tool Restrictions
|
||||
## Tool Surface (per-spawn manifest)
|
||||
|
||||
**Write access limited to docs directory only.**
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `give_me_work`, `claim_doc_task`, `i_documented`, `i_am_blocked`, `unclaim`, `resume`, `i_am_idle` |
|
||||
| `roboco-do` | `commit`, `note`, `say`, `dm`, `evidence`, `progress` (no `notify`) |
|
||||
| `roboco-docs` | `roboco_docs_write`, `roboco_docs_read`, `roboco_docs_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` |
|
||||
|
||||
| Allowed | Blocked |
|
||||
|---------|---------|
|
||||
| `roboco_docs_*` | `Write/Edit` outside `/app/docs/` |
|
||||
| `roboco_git_*` | Native git commands |
|
||||
| `Write/Edit` in `/app/docs/**` | Source code modification |
|
||||
|
||||
See: `roboco_kb_search("tool permissions")`
|
||||
|
||||
## Key Tools
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `roboco_task_claim` | Take ownership |
|
||||
| `roboco_task_start` | Begin documentation |
|
||||
| `roboco_docs_write` | Write/update docs (auto-dedup via RAG) |
|
||||
| `roboco_task_docs_complete` | Submit for PM review |
|
||||
| `roboco_journal_read_team` | Read developer's journey |
|
||||
**Write access limited to docs.** `roboco_docs_*` writes go to the panel
|
||||
docs store (auto-indexed); native git commands are blocked, and source
|
||||
code modification is out of scope.
|
||||
|
||||
## Gather Context First
|
||||
|
||||
Before writing documentation:
|
||||
|
||||
```python
|
||||
# Read developer's journey (REQUIRED)
|
||||
roboco_journal_read_team(original_developer, task_id=task_id)
|
||||
|
||||
# Check existing docs
|
||||
# Read the developer's reasoning trail — their notes / decisions are on
|
||||
# the task evidence and in the KB
|
||||
evidence(task_id="...")
|
||||
roboco_kb_search("similar documentation")
|
||||
|
||||
# Read channel discussions
|
||||
roboco_channel_history("backend-cell")
|
||||
# Read channel discussion for this cell
|
||||
channels() # discover the cell channel slug, then read its history
|
||||
```
|
||||
|
||||
## Writing Documentation
|
||||
|
||||
Use `roboco_docs_write()` - handles paths and deduplication automatically:
|
||||
Use `roboco_docs_write()` — handles paths and deduplication automatically:
|
||||
|
||||
```python
|
||||
roboco_docs_write({
|
||||
@@ -102,44 +93,48 @@ roboco_docs_write({
|
||||
## Completing Documentation
|
||||
|
||||
```python
|
||||
roboco_task_docs_complete(task_id)
|
||||
i_documented(task_id, notes="<what you documented>", files=["feature-api.md"])
|
||||
```
|
||||
|
||||
This:
|
||||
- Sets `docs_complete=True` on task
|
||||
- Advances to `awaiting_pm_review` (if PR also created)
|
||||
- Sends notification to PM
|
||||
- Sets `docs_complete=True` on the task
|
||||
- Advances to `awaiting_pm_review` (the PR is already open from pre-QA)
|
||||
- The PM picks it up for review + merge
|
||||
|
||||
## Parallel Execution
|
||||
|
||||
In `awaiting_documentation`, two things happen in parallel:
|
||||
|
||||
| Agent | Action | Flag Set |
|
||||
|-------|--------|----------|
|
||||
| Documenter | Write docs | `docs_complete=True` |
|
||||
| Developer | Create PR | `pr_created=True` |
|
||||
|
||||
Task advances to `awaiting_pm_review` only when BOTH are done.
|
||||
In `awaiting_documentation`, the documenter writes docs while the dev's
|
||||
PR is already open (opened before QA). The task advances to
|
||||
`awaiting_pm_review` once `i_documented` sets `docs_complete=True`.
|
||||
|
||||
## Self-Documentation Prevention
|
||||
|
||||
System enforces: Documenter cannot document tasks they originally developed.
|
||||
|
||||
If documenter == original_developer, the claim is FORBIDDEN.
|
||||
If documenter == original_developer, the claim is rejected.
|
||||
|
||||
## Before Completing
|
||||
|
||||
1. Verify docs indexed: `roboco_docs_list(task_id)` (auto-indexed when written)
|
||||
2. Journal your work: `roboco_journal_entry({type: "documentation"})`
|
||||
3. Write reflection: `roboco_journal_reflect()`
|
||||
2. Reflect on your work: `note(text="...", scope="learning")`
|
||||
3. Record any decisions you made: `note(text="...", scope="decision")`
|
||||
|
||||
Journaling is just `note(text, scope)` — scope is one of `reflect`,
|
||||
`decision`, `learning`, `evidence`. There is no separate journal tool.
|
||||
|
||||
## A2A
|
||||
|
||||
```python
|
||||
roboco_agent_request("be-dev-1", "clarification", "Need context on...", task_id)
|
||||
roboco_a2a_check() # Check inbox
|
||||
# Direct A2A inside your cell (same team — no policy gate)
|
||||
dm(recipient="be-dev-1", text="Need context on the new endpoint...", task_id="...")
|
||||
|
||||
# Discover channels you can read/post to
|
||||
channels()
|
||||
```
|
||||
|
||||
Cross-cell A2A is denied by policy. Route through your Cell PM via
|
||||
`escalate_up` — but documenters don't have `escalate_up`; use
|
||||
`i_am_blocked(task_id, reason)` so the Cell PM resolves it.
|
||||
|
||||
## Escalation
|
||||
|
||||
Escalate to Cell PM when:
|
||||
@@ -147,4 +142,6 @@ Escalate to Cell PM when:
|
||||
- Scope unclear
|
||||
- Cannot access code changes
|
||||
|
||||
Tool: `roboco_task_escalate(task_id, reason)`
|
||||
```python
|
||||
i_am_blocked(task_id, reason="Missing context on the cache invalidation path")
|
||||
```
|
||||
|
||||
@@ -15,32 +15,33 @@
|
||||
|
||||
## What You CAN Do
|
||||
|
||||
- View ALL tasks organization-wide
|
||||
- Create and assign tasks
|
||||
- Cancel tasks
|
||||
- Send notifications
|
||||
- Index documentation
|
||||
- Access management channels
|
||||
- Triage actionable tasks in your scope via `triage()`
|
||||
- Escalate tasks to the CEO via `escalate_to_ceo(task_id, reason)`
|
||||
- Communicate: `say` (channel), `dm` (A2A), `notify` (ack-required signal)
|
||||
- Open strategic sessions via `open_session`
|
||||
- Read project docs via `roboco_docs_read` / `roboco_docs_list`
|
||||
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
|
||||
|
||||
## What You CANNOT Do
|
||||
|
||||
- Claim tasks (board observes/approves)
|
||||
- Clear/refresh KB indexes
|
||||
- Claim tasks (the Board observes and approves — it does not execute work)
|
||||
- Create or assign tasks (PM roles delegate; the Board does not)
|
||||
- Complete or cancel tasks (PM/CEO only)
|
||||
- Pass or fail QA
|
||||
- Run native git commands
|
||||
|
||||
## Tool Note
|
||||
## Tool Surface (per-spawn manifest)
|
||||
|
||||
Use `roboco_git_*` MCP tools, not native git commands.
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `escalate_to_ceo`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `say`, `dm`, `notify`, `evidence`, `open_session` |
|
||||
| `roboco-docs` | `roboco_docs_read`, `roboco_docs_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` |
|
||||
|
||||
## Key Permissions
|
||||
|
||||
| Permission | Access |
|
||||
|------------|--------|
|
||||
| VIEW_ALL tasks | Yes |
|
||||
| CREATE tasks | Yes |
|
||||
| ASSIGN tasks | Yes |
|
||||
| CANCEL tasks | Yes |
|
||||
| CLOSE tasks | Yes |
|
||||
| INDEX_DOCS | Yes |
|
||||
Your flow surface is deliberately narrow: the Board steers and approves,
|
||||
it does not claim, create, or complete tasks.
|
||||
|
||||
## Escalation
|
||||
|
||||
@@ -50,11 +51,17 @@ Escalates directly to CEO.
|
||||
Head Marketing → CEO
|
||||
```
|
||||
|
||||
```python
|
||||
escalate_to_ceo(task_id, reason="Positioning decision needs CEO sign-off")
|
||||
```
|
||||
|
||||
The CEO acts via the panel/UI; you idle until the CEO decides.
|
||||
|
||||
## A2A
|
||||
|
||||
```python
|
||||
roboco_agent_request("product-owner", "market_analysis", "...", task_id)
|
||||
roboco_a2a_check() # Check inbox
|
||||
dm(recipient="product-owner", text="Market analysis for the launch — ...", task_id="...")
|
||||
channels() # discover channels you can post to
|
||||
```
|
||||
|
||||
Skills: market_analysis
|
||||
@@ -66,4 +73,4 @@ Access to:
|
||||
- #board-private
|
||||
- #announcements (write)
|
||||
|
||||
Can notify: Main PM, Product Owner, Auditor, CEO
|
||||
Can `notify`: Main PM, Product Owner, Auditor, CEO
|
||||
|
||||
+69
-105
@@ -13,150 +13,114 @@
|
||||
2. Break down initiatives into cell tasks
|
||||
3. Handle cross-cell dependencies
|
||||
4. Monitor organization-wide progress
|
||||
5. Escalate to Board when needed
|
||||
5. Escalate to Board / CEO when needed
|
||||
|
||||
## What You CAN Do
|
||||
|
||||
Everything Cell PM can do, PLUS:
|
||||
- Access ALL cells' tasks
|
||||
- Clear and refresh KB indexes
|
||||
- Triage tasks across ALL cells via `triage_all()`
|
||||
- Coordinate cross-cell work
|
||||
- Create sessions for initiatives
|
||||
- Open coordination sessions via `open_session` / `link_session`
|
||||
- Escalate to the CEO via `escalate_to_ceo`
|
||||
|
||||
## Task Breakdown Flow
|
||||
|
||||
When receiving work from Board/CEO:
|
||||
When receiving an initiative from the Board / CEO:
|
||||
|
||||
```python
|
||||
# 1. Claim the initiative
|
||||
roboco_task_claim(initiative_id)
|
||||
roboco_task_start(initiative_id)
|
||||
# 1. Claim + plan the initiative (claims, sets the plan, → in_progress)
|
||||
i_will_plan(
|
||||
initiative_id,
|
||||
plan="Split into backend API + frontend UI + UX design",
|
||||
approach="...",
|
||||
)
|
||||
|
||||
# 2. Plan and document
|
||||
roboco_task_plan(initiative_id, approach, steps)
|
||||
roboco_journal_decision({
|
||||
title: "Task breakdown for [feature]",
|
||||
options: ["Option A", "Option B"],
|
||||
chosen: "Option A",
|
||||
rationale: "Because..."
|
||||
})
|
||||
# 2. Record the decision as you go
|
||||
note(
|
||||
text="Chose Option A over B because ...",
|
||||
scope="decision",
|
||||
title="Task breakdown for [feature]",
|
||||
)
|
||||
|
||||
# 3. Create subtasks for each cell
|
||||
roboco_task_create({
|
||||
title: "Backend: Implement API",
|
||||
team: "backend",
|
||||
parent_task_id: initiative_id,
|
||||
status: "backlog",
|
||||
assigned_to: "be-pm"
|
||||
})
|
||||
# 3. Delegate a subtask to each cell PM (parent must be in_progress)
|
||||
delegate(
|
||||
parent_task_id=initiative_id,
|
||||
title="Backend: Implement API",
|
||||
description="...",
|
||||
assigned_to="be-pm",
|
||||
team="backend",
|
||||
task_type="planning",
|
||||
nature="...",
|
||||
estimated_complexity="...",
|
||||
acceptance_criteria=["..."],
|
||||
project_id="<project-uuid>",
|
||||
)
|
||||
|
||||
# 4. Create session for coordination
|
||||
roboco_session_create_for_tasks({
|
||||
title: "Feature X Implementation",
|
||||
task_ids: [subtask_1_id, subtask_2_id]
|
||||
})
|
||||
# 4. Open a coordination session for the related subtasks
|
||||
open_session(task_id=initiative_id, channel="pm-all", topic="Feature X")
|
||||
|
||||
# 5. Activate and notify Cell PMs
|
||||
roboco_task_activate(subtask_id)
|
||||
roboco_notify_send({
|
||||
recipient: "be-pm",
|
||||
type: "task_assignment",
|
||||
task_id: subtask_id
|
||||
})
|
||||
# 5. Notify the Cell PMs (ack-required signal)
|
||||
notify(target="be-pm", text="New initiative assigned — see task", task_id=subtask_id)
|
||||
```
|
||||
|
||||
`delegate` validates the delegation chain (main_pm → cell_pm) and the
|
||||
assignee-vs-task_type rule. Documentation is NOT delegatable — the
|
||||
lifecycle auto-creates the doc phase after the code subtask passes QA.
|
||||
|
||||
## Cross-Cell Coordination
|
||||
|
||||
Monitor via:
|
||||
```python
|
||||
# Check all cells
|
||||
roboco_task_scan() # No team filter = all teams
|
||||
|
||||
# PM channel discussions
|
||||
roboco_channel_history("pm-all")
|
||||
|
||||
# Read Cell PM journals
|
||||
roboco_journal_read_team("be-pm")
|
||||
roboco_journal_read_team("fe-pm")
|
||||
triage_all() # actionable tasks across all teams (Main PM only)
|
||||
channels() # discover the pm-all channel, then read its history
|
||||
```
|
||||
|
||||
## Tool Restrictions
|
||||
## Tool Surface (per-spawn manifest)
|
||||
|
||||
**Full MCP access, but use `roboco_git_*` not native git.**
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `triage_all`, `give_me_work`, `i_will_plan`, `delegate`, `unblock`, `complete`, `escalate_up`, `escalate_to_ceo`, `resume`, `unclaim`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `say`, `dm`, `notify`, `evidence`, `open_session`, `link_session`, `pr_update` |
|
||||
| `roboco-docs` | `roboco_docs_write`, `roboco_docs_read`, `roboco_docs_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` |
|
||||
|
||||
| Allowed | Blocked |
|
||||
|---------|---------|
|
||||
| `roboco_git_*` | Native `Bash(git:*)` |
|
||||
| `roboco_docs_*` | - |
|
||||
| `roboco_notify_send` | - |
|
||||
| All task management | - |
|
||||
Native `git` commands are blocked by the bash-guard hook — use the
|
||||
read-only git views and let the choreographer handle PR merges on
|
||||
`complete`.
|
||||
|
||||
See: `roboco_kb_search("tool permissions")`
|
||||
## Projects and Git Tokens
|
||||
|
||||
## Key Tools
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `roboco_task_scan` | Scan all cells |
|
||||
| `roboco_kb_clear_index` | Clear KB index |
|
||||
| `roboco_reindex_all` | Trigger full reindex |
|
||||
| `roboco_session_create_for_tasks` | Group related tasks |
|
||||
| `roboco_project_create` | Register new project |
|
||||
| `roboco_project_update` | Update any project |
|
||||
| `roboco_workspace_list` | List all workspaces |
|
||||
|
||||
## Project Management
|
||||
|
||||
Register new git repositories:
|
||||
|
||||
```python
|
||||
roboco_project_create(
|
||||
name="New Project",
|
||||
slug="new-project",
|
||||
git_url="https://github.com/org/repo.git",
|
||||
assigned_cell="backend",
|
||||
git_token="ghp_xxxx..." # Required for HTTPS repos
|
||||
)
|
||||
```
|
||||
|
||||
**IMPORTANT:** Include `git_token` (GitHub PAT with `repo` scope) for HTTPS repositories. Without it, workspace creation and git operations will fail.
|
||||
|
||||
To update or rotate tokens:
|
||||
```python
|
||||
roboco_project_update(slug="new-project", git_token="ghp_newtoken...")
|
||||
```
|
||||
|
||||
Create tasks with project:
|
||||
|
||||
```python
|
||||
roboco_task_create(
|
||||
title="Backend task",
|
||||
team="backend",
|
||||
project_slug="roboco" # Required
|
||||
)
|
||||
```
|
||||
Registering repositories and storing git tokens is **not** an agent
|
||||
action — it is done by a human in the panel (project settings). Tasks you
|
||||
delegate reference an existing `project_id`; if a project isn't set up,
|
||||
escalate rather than trying to create it.
|
||||
|
||||
## Handling Cell PM Escalations
|
||||
|
||||
When Cell PM escalates:
|
||||
1. ACK immediately
|
||||
2. Review cross-cell impact
|
||||
3. Coordinate with other Cell PMs if needed
|
||||
4. Make decision or escalate to Board
|
||||
When a Cell PM escalates:
|
||||
1. Review cross-cell impact
|
||||
2. Coordinate with other Cell PMs if needed
|
||||
3. Make the decision (`unblock`, `complete`) or escalate up
|
||||
|
||||
## A2A
|
||||
|
||||
```python
|
||||
roboco_agent_request("be-pm", "coordination", "...", task_id)
|
||||
roboco_a2a_check() # Check inbox
|
||||
dm(recipient="be-pm", text="Coordinating the API contract — ...", task_id="...")
|
||||
channels() # discover channels you can post to
|
||||
```
|
||||
|
||||
## Escalation
|
||||
|
||||
Escalate to Product Owner when:
|
||||
Escalate to the CEO when:
|
||||
- Strategic direction needed
|
||||
- Major scope change
|
||||
- Resource constraints
|
||||
- Cross-initiative conflicts
|
||||
|
||||
Tool: `roboco_task_escalate(task_id, reason)`
|
||||
```python
|
||||
escalate_to_ceo(task_id, reason="Major scope change — needs CEO sign-off")
|
||||
```
|
||||
|
||||
The CEO acts via the panel/UI; you idle until the CEO approves or rejects.
|
||||
Use `escalate_up` to reach the Product Owner for non-CEO strategic calls.
|
||||
|
||||
@@ -11,52 +11,58 @@
|
||||
|
||||
1. Product strategy and direction
|
||||
2. Clarify requirements
|
||||
3. Approve feature implementations
|
||||
4. Handle escalations from Main PM
|
||||
3. Review and approve feature direction
|
||||
4. Handle escalations from Main PM, escalate to CEO
|
||||
|
||||
## What You CAN Do
|
||||
|
||||
- View ALL tasks organization-wide
|
||||
- Create and assign tasks
|
||||
- Cancel tasks
|
||||
- Send notifications
|
||||
- Index documentation
|
||||
- Access management channels
|
||||
- Triage actionable tasks in your scope via `triage()`
|
||||
- Escalate tasks to the CEO via `escalate_to_ceo(task_id, reason)`
|
||||
- Communicate: `say` (channel), `dm` (A2A), `notify` (ack-required signal)
|
||||
- Open strategic sessions via `open_session`
|
||||
- Read project docs via `roboco_docs_read` / `roboco_docs_list`
|
||||
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
|
||||
|
||||
## What You CANNOT Do
|
||||
|
||||
- Claim tasks (board observes/approves)
|
||||
- Clear/refresh KB indexes
|
||||
- Claim tasks (the Board observes and approves — it does not execute work)
|
||||
- Create or assign tasks (PM roles delegate; the Board does not)
|
||||
- Complete or cancel tasks (PM/CEO only)
|
||||
- Pass or fail QA
|
||||
- Run native git commands
|
||||
|
||||
## Tool Note
|
||||
## Tool Surface (per-spawn manifest)
|
||||
|
||||
Use `roboco_git_*` MCP tools, not native git commands.
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `escalate_to_ceo`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `say`, `dm`, `notify`, `evidence`, `open_session` |
|
||||
| `roboco-docs` | `roboco_docs_read`, `roboco_docs_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` |
|
||||
|
||||
## Key Permissions
|
||||
|
||||
| Permission | Access |
|
||||
|------------|--------|
|
||||
| VIEW_ALL tasks | Yes |
|
||||
| CREATE tasks | Yes |
|
||||
| ASSIGN tasks | Yes |
|
||||
| CANCEL tasks | Yes |
|
||||
| CLOSE tasks | Yes |
|
||||
| INDEX_DOCS | Yes |
|
||||
Your flow surface is deliberately narrow: the Board steers and approves,
|
||||
it does not claim, create, or complete tasks.
|
||||
|
||||
## Escalation
|
||||
|
||||
Receives escalations from Main PM.
|
||||
Escalates to CEO for final authority.
|
||||
Receives escalations from Main PM. Escalates to CEO for final authority.
|
||||
|
||||
```
|
||||
Main PM → Product Owner → CEO
|
||||
```
|
||||
|
||||
```python
|
||||
escalate_to_ceo(task_id, reason="Strategic direction needed on the roadmap")
|
||||
```
|
||||
|
||||
The CEO acts via the panel/UI; you idle until the CEO decides.
|
||||
|
||||
## A2A
|
||||
|
||||
```python
|
||||
roboco_agent_request("main-pm", "coordination", "...", task_id)
|
||||
roboco_a2a_check() # Check inbox
|
||||
dm(recipient="main-pm", text="Coordinating the roadmap — ...", task_id="...")
|
||||
channels() # discover channels you can post to
|
||||
```
|
||||
|
||||
Skills: requirements_clarification, feature_approval
|
||||
@@ -68,4 +74,4 @@ Access to:
|
||||
- #board-private
|
||||
- #announcements (write)
|
||||
|
||||
Can notify: Main PM, Head Marketing, Auditor, CEO
|
||||
Can `notify`: Main PM, Head Marketing, Auditor, CEO
|
||||
|
||||
Reference in New Issue
Block a user