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
@@ -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")
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user