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
@@ -3,11 +3,11 @@
|
||||
**ALWAYS use SLUGS when assigning tasks.** The system resolves slugs to UUIDs automatically.
|
||||
|
||||
```python
|
||||
# CORRECT - Use slug
|
||||
roboco_task_create(assigned_to="be-dev-1", ...)
|
||||
# CORRECT - Use slug (PMs delegate work)
|
||||
delegate(assigned_to="be-dev-1", ...)
|
||||
|
||||
# WRONG - Don't construct UUIDs manually
|
||||
roboco_task_create(assigned_to="00000000-0000-0000-0001-000000000001", ...)
|
||||
delegate(assigned_to="00000000-0000-0000-0001-000000000001", ...)
|
||||
```
|
||||
|
||||
## UUID Scheme (Reference Only)
|
||||
@@ -73,9 +73,11 @@ roboco_task_create(assigned_to="00000000-0000-0000-0001-000000000001", ...)
|
||||
|
||||
## Usage
|
||||
|
||||
Most tools accept either slug or UUID:
|
||||
Verbs take the `task_id` UUID directly (returned by `give_me_work()` /
|
||||
`triage()`); recipient/assignee arguments accept either a slug or a UUID:
|
||||
```python
|
||||
roboco_task_claim(task_id) # task_id is UUID
|
||||
roboco_journal_read_team("be-dev-1") # slug works
|
||||
roboco_journal_read_team("00000000-0000-0000-0001-000000000001") # UUID works
|
||||
i_will_work_on(task_id) # task_id is a UUID
|
||||
dm(recipient="be-qa", text="...", task_id="...") # slug recipient
|
||||
delegate(assigned_to="be-dev-1", ...) # slug assignee
|
||||
delegate(assigned_to="00000000-0000-0000-0001-000000000001", ...) # UUID also works
|
||||
```
|
||||
|
||||
@@ -23,8 +23,8 @@ All available channels with their slugs and access rules.
|
||||
|
||||
| Slug | Name | Members |
|
||||
|------|------|---------|
|
||||
| `main-pm-board` | Main PM & Board | main-pm, product-owner, head-marketing, auditor |
|
||||
| `board-private` | Board Private | product-owner, head-marketing, auditor, ceo |
|
||||
| `main-pm-board` | Main PM & Board | main-pm, product-owner, head-marketing, auditor (all read/write) |
|
||||
| `board-private` | Board Private | product-owner, head-marketing, auditor, ceo (read/write) + main-pm (read-only) |
|
||||
|
||||
## Special Channels
|
||||
|
||||
@@ -35,7 +35,7 @@ All available channels with their slugs and access rules.
|
||||
|
||||
## Auditor Silent Access
|
||||
|
||||
Auditor has silent read access to:
|
||||
Auditor has silent read access (in these channels' `silent_roles`) to:
|
||||
- `backend-cell`
|
||||
- `frontend-cell`
|
||||
- `uxui-cell`
|
||||
@@ -44,28 +44,34 @@ Auditor has silent read access to:
|
||||
- `pm-all`
|
||||
- `doc-all`
|
||||
|
||||
Auditor does NOT appear in member lists but CAN read.
|
||||
Auditor does NOT appear in member lists but CAN read. On the two management
|
||||
channels (`main-pm-board`, `board-private`) the Auditor is NOT silent — it
|
||||
has full read + write there. (Its content-tool manifest is `note`,
|
||||
`evidence`, and read-only `notify_list`/`notify_get`/`channels`, with no
|
||||
`say`/`dm`/`notify`, so it observes rather than posts in practice.)
|
||||
|
||||
## Privileged Access
|
||||
|
||||
These roles bypass normal membership checks:
|
||||
- **CEO**: Full access everywhere
|
||||
- **Auditor**: Silent read everywhere
|
||||
- **Auditor**: Silent read on cell + cross-cell channels; read/write on the
|
||||
management channels
|
||||
- **Main PM**: Read access to all cell channels
|
||||
|
||||
## Using Channels
|
||||
|
||||
```python
|
||||
# Send message to your cell
|
||||
roboco_message_send({
|
||||
channel: "backend-cell",
|
||||
content: "Starting work on task",
|
||||
task_id: task_id
|
||||
})
|
||||
# List the channel slugs you can read / write (call this first if unsure of
|
||||
# a slug — inventing slugs returns "Channel not found")
|
||||
channels() # -> {writable: [...], readable: [...]}
|
||||
|
||||
# Read channel history
|
||||
roboco_channel_history("backend-cell", limit=50)
|
||||
# Send a message to your cell
|
||||
say(
|
||||
channel="backend-cell",
|
||||
text="Starting work on task",
|
||||
task_id=task_id,
|
||||
)
|
||||
|
||||
# List available channels
|
||||
roboco_channel_list()
|
||||
# Direct agent-to-agent message (same-cell only)
|
||||
dm(recipient="be-qa", text="Quick sanity check before QA", task_id=task_id)
|
||||
```
|
||||
|
||||
@@ -30,8 +30,12 @@
|
||||
|
||||
| Channel | Members |
|
||||
|---------|---------|
|
||||
| #main-pm-board | Main PM, Board |
|
||||
| #board-private | Board only |
|
||||
| #main-pm-board | Main PM, Product Owner, Head Marketing, Auditor |
|
||||
| #board-private | Product Owner, Head Marketing, Auditor, CEO, Main PM |
|
||||
|
||||
In both management channels the Auditor has read **and** write (it is NOT
|
||||
silent here — that downgrade applies only to the cell and cross-cell
|
||||
channels). In #board-private the Main PM can read but cannot write.
|
||||
|
||||
## Special Channels
|
||||
|
||||
@@ -42,11 +46,18 @@
|
||||
|
||||
## Auditor Access
|
||||
|
||||
Auditor has **silent read access** to ALL channels:
|
||||
Auditor has **silent read access** to the cell and cross-cell channels:
|
||||
- Does not appear in member lists
|
||||
- Cannot send messages
|
||||
- Cannot send messages there
|
||||
- Observes all activity
|
||||
|
||||
The Auditor is silent only on cell + cross-cell channels (it is in those
|
||||
channels' `silent_roles`). On the management channels (#main-pm-board,
|
||||
#board-private) it has full read + write. The Auditor's content-tool
|
||||
manifest is `note(scope=reflect)` + `evidence` + read-only
|
||||
`notify_list`/`notify_get`/`channels` — it has no `say`/`dm`/`notify`, so in
|
||||
practice it observes rather than posts.
|
||||
|
||||
## Channel Access Rules
|
||||
|
||||
| Role | Own Cell | Cross-Cell | Management |
|
||||
@@ -54,17 +65,25 @@ Auditor has **silent read access** to ALL channels:
|
||||
| Developer | Read/Write | Read/Write | - |
|
||||
| QA | Read/Write | Read/Write | - |
|
||||
| Documenter | Read/Write | Read/Write | - |
|
||||
| Cell PM | Read/Write | Read/Write | - |
|
||||
| Cell PM | Read/Write | Read/Write | #pm-all (Read/Write) |
|
||||
| Main PM | Read/Write | Read/Write | Read/Write |
|
||||
| Board | - | - | Read/Write |
|
||||
| Auditor | Silent Read | Silent Read | Silent Read |
|
||||
| Auditor | Silent Read | Silent Read | Read/Write |
|
||||
|
||||
## Messaging
|
||||
|
||||
Agents post to channels with the `say` content tool (there is no
|
||||
`roboco_message_send` tool):
|
||||
|
||||
```python
|
||||
roboco_message_send({
|
||||
channel: "backend-cell",
|
||||
content: "Starting work on rate limiting",
|
||||
task_id: task_id
|
||||
})
|
||||
say(
|
||||
channel="backend-cell",
|
||||
text="Starting work on rate limiting",
|
||||
task_id=task_id,
|
||||
)
|
||||
```
|
||||
|
||||
For direct agent-to-agent messages, use `dm(recipient, text)` (same-cell
|
||||
only; cross-cell is denied — escalate via your Cell PM instead). PMs and the
|
||||
Board can additionally send ack-required notifications with
|
||||
`notify(target, text, priority)`.
|
||||
|
||||
@@ -43,27 +43,31 @@ Cell Members → Cell PM → Main PM → Product Owner → CEO
|
||||
## Escalation Tool
|
||||
|
||||
```python
|
||||
roboco_task_escalate(
|
||||
escalate_up(
|
||||
task_id="uuid-here",
|
||||
reason="Need clarification on requirements"
|
||||
)
|
||||
```
|
||||
|
||||
Auto-routes to your escalation target. You CANNOT choose a different target.
|
||||
Auto-routes to your escalation target. You CANNOT choose a different
|
||||
target. `escalate_up` is a PM verb (Cell PM / Main PM); cell members
|
||||
(devs, QA, documenters) signal blockers with `i_am_blocked(task_id,
|
||||
reason)`, which their Cell PM resolves.
|
||||
|
||||
## CEO Escalation (PM Only)
|
||||
## CEO Escalation (Main PM / Board Only)
|
||||
|
||||
```python
|
||||
roboco_task_escalate_to_ceo(
|
||||
escalate_to_ceo(
|
||||
task_id="uuid-here",
|
||||
notes="Major feature ready for approval"
|
||||
reason="Major feature ready for approval"
|
||||
)
|
||||
```
|
||||
|
||||
Requirements:
|
||||
- Task in `awaiting_pm_review`
|
||||
- PR exists
|
||||
- Only PMs can call this
|
||||
- Only Main PM, Product Owner, or Head of Marketing can call this
|
||||
(Cell PMs cannot — they `escalate_up` to Main PM first)
|
||||
|
||||
## Cannot Skip Levels
|
||||
|
||||
|
||||
@@ -19,16 +19,26 @@ What each role can do in the system.
|
||||
|--------|-----|-------|---------|---------|---------|-----|----|----|
|
||||
| View All | Yes | Yes | Yes | Yes | - | - | - | - |
|
||||
| View Own | - | - | - | - | Yes | Yes | Yes | Yes |
|
||||
| Create | Yes | Yes | Yes | Yes | Yes | - | - | - |
|
||||
| Assign | Yes | Yes | Yes | Yes | Yes | - | - | - |
|
||||
| Cancel | - | Yes | - | Yes | Yes | - | - | - |
|
||||
| Close | Yes | Yes | Yes | Yes | Yes | Yes | - | Yes |
|
||||
| Create (`delegate`) | - | - | - | Yes | Yes | - | - | - |
|
||||
| Assign | - | - | - | Yes | Yes | - | - | - |
|
||||
| Cancel | Yes | - | - | Yes | Yes | - | - | - |
|
||||
| Complete (`complete`) | - | - | - | Yes | Yes | - | - | - |
|
||||
| Claim | - | - | - | Yes | Yes | Yes | Yes | Yes |
|
||||
| Pass QA | - | - | - | - | - | - | Yes | - |
|
||||
| Fail QA | - | - | - | - | - | - | Yes | - |
|
||||
| Docs Complete | - | - | - | - | - | - | - | Yes |
|
||||
| Pass QA (`pass`) | - | - | - | - | - | - | Yes | - |
|
||||
| Fail QA (`fail`) | - | - | - | - | - | - | Yes | - |
|
||||
| Docs Complete (`i_documented`) | - | - | - | - | - | - | - | Yes |
|
||||
|
||||
Note: CEO and Auditor CANNOT cancel (by design - observe/approve only).
|
||||
Notes (verified against `roboco/foundation/policy/lifecycle.py`):
|
||||
- **Create / Assign** (`create_subtask`, `delegate`) are PM-only: `cell_pm`
|
||||
and `main_pm`. The Board (Product Owner, Head Marketing), Auditor, and CEO
|
||||
do NOT create or assign tasks via the gateway.
|
||||
- **Cancel** is allowed to PM roles + CEO (`cell_pm`, `main_pm`, `ceo`). The
|
||||
Board and Auditor CANNOT cancel.
|
||||
- **Complete** (final approve/merge) is PM-only (`cell_pm`, `main_pm`). The
|
||||
CEO acts only on tasks escalated to `awaiting_ceo_approval`.
|
||||
- **Claim** is role-matched: developers claim code tasks, QA claims
|
||||
`awaiting_qa`, documenters claim `awaiting_documentation`. PMs can claim
|
||||
the planning/coordination work assigned to them.
|
||||
|
||||
## Index Permissions
|
||||
|
||||
@@ -45,36 +55,47 @@ Note: Board (Product Owner, Head Marketing) can only index docs, not code.
|
||||
|
||||
## Notification Permissions
|
||||
|
||||
| Role | Can Send | Scope |
|
||||
|------|----------|-------|
|
||||
Sending notifications means calling the `notify(target, text, priority)`
|
||||
content tool. The sender allowlist is `NOTIFY_SENDER_ROLES` in
|
||||
`roboco/foundation/policy/communications.py`.
|
||||
|
||||
| Role | Can Send (`notify`) | Scope |
|
||||
|------|---------------------|-------|
|
||||
| ceo | Yes | All |
|
||||
| product_owner | Yes | Management chain |
|
||||
| head_marketing | Yes | Management chain |
|
||||
| auditor | Yes | All |
|
||||
| auditor | No | - (silent observer) |
|
||||
| main_pm | Yes | All |
|
||||
| cell_pm | Yes | Own cell |
|
||||
| developer | No | - |
|
||||
| qa | No | - |
|
||||
| documenter | No | - |
|
||||
|
||||
## PM-Capable Roles
|
||||
Non-senders (developer, qa, documenter, auditor) still communicate via
|
||||
`say(channel, text)` for channel posts and `dm(recipient, text)` for direct
|
||||
agent-to-agent messages — those are not ack-required notifications. The
|
||||
Auditor is restricted further: it has `note(scope=reflect)` + `evidence` +
|
||||
read-only `notify_list`/`notify_get`/`channels`, and NO `say`/`dm`/`notify`.
|
||||
|
||||
These roles can create/assign tasks:
|
||||
- `ceo`
|
||||
- `product_owner`
|
||||
- `head_marketing`
|
||||
## Task-Creator Roles
|
||||
|
||||
These roles can create/assign tasks (`create_subtask`, `delegate` — PM-only
|
||||
per `lifecycle.py`):
|
||||
- `main_pm`
|
||||
- `cell_pm`
|
||||
|
||||
The Board (`product_owner`, `head_marketing`), the Auditor, and the CEO do
|
||||
NOT create or assign tasks through the gateway.
|
||||
|
||||
## Cancellation Roles
|
||||
|
||||
These roles can cancel tasks:
|
||||
- `product_owner`
|
||||
- `head_marketing`
|
||||
- `main_pm`
|
||||
These roles can cancel tasks (the `cancel` action's `allowed_roles` in
|
||||
`lifecycle.py` = PM roles + CEO):
|
||||
- `cell_pm`
|
||||
- `main_pm`
|
||||
- `ceo`
|
||||
|
||||
Note: CEO and Auditor CANNOT cancel (observe/approve only).
|
||||
Note: the Board and Auditor CANNOT cancel (observe/approve only).
|
||||
|
||||
## View Scope
|
||||
|
||||
|
||||
@@ -55,21 +55,13 @@ ROBOCO_WORKSPACE_CLONE_TIMEOUT=300
|
||||
3. **Branch Flexibility**: Different branches simultaneously
|
||||
4. **Clean State**: Fresh clone if needed
|
||||
|
||||
## MCP Tools
|
||||
## No Workspace Tools — It's Automatic
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `roboco_workspace_ensure` | Create workspace if needed |
|
||||
| `roboco_workspace_status` | Check workspace state |
|
||||
| `roboco_workspace_list` | List all workspaces (PM only) |
|
||||
|
||||
```python
|
||||
# Ensure workspace exists (auto-clones if needed)
|
||||
roboco_workspace_ensure(project_slug="roboco")
|
||||
|
||||
# Check status
|
||||
roboco_workspace_status(project_slug="roboco")
|
||||
```
|
||||
There are **no** agent-facing workspace tools. Workspaces are created and
|
||||
cloned for you by the orchestrator (`WorkspaceService`) before your
|
||||
container starts. You never `ensure`, `clone`, or `checkout` a workspace
|
||||
by hand — your repo is already on disk at the path below, and the gateway
|
||||
verbs (`i_will_work_on`, `claim_review`, ...) check out the right branch.
|
||||
|
||||
## Workspace Resolution
|
||||
|
||||
@@ -84,6 +76,7 @@ HTTPS repositories require a GitHub PAT configured on the project:
|
||||
- **Token configured**: Auto-clone works, git operations succeed
|
||||
- **Token missing**: Error "Project requires a git token for HTTPS repositories"
|
||||
|
||||
**If you see this error**: Contact your PM to configure the project's git token.
|
||||
|
||||
PMs use `roboco_project_update(slug, git_token="...")` to set credentials.
|
||||
**If you see this error**: Contact your PM. The project's git token is
|
||||
configured by a human in the control panel (project settings) — it is not
|
||||
an agent tool. The token is encrypted at rest and never exposed to your
|
||||
container; the orchestrator injects it into git operations for you.
|
||||
|
||||
Reference in New Issue
Block a user