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
+47
-101
@@ -1,115 +1,61 @@
|
||||
# Project Tools
|
||||
# Project & Workspace Tools
|
||||
|
||||
## Overview
|
||||
|
||||
Project tools manage git repositories and agent workspaces.
|
||||
There is **no** `roboco_project_*` or `roboco_workspace_*` agent tool.
|
||||
Agents do **not** create projects, manage git tokens, or ensure
|
||||
workspaces. Those are handled for you:
|
||||
|
||||
## List Projects
|
||||
- **Workspaces are auto-cloned by the orchestrator** (`WorkspaceService`).
|
||||
Your per-agent clone of the project repo is created the first time you
|
||||
claim work on it — you never call a workspace tool. Branches are
|
||||
auto-created on `i_will_work_on()` / `claim_review()`; you don't run
|
||||
`git checkout` either.
|
||||
- **Project registration and git-token management are operator actions**
|
||||
done through the control panel / HTTP API, not from inside an agent
|
||||
container. Tokens are encrypted at rest; the agent container never sees
|
||||
the PAT (it is injected into git operations server-side and scrubbed
|
||||
from URLs).
|
||||
|
||||
## What a task already tells you
|
||||
|
||||
A task carries its project linkage; you don't look it up with a tool. The
|
||||
task object you receive from `give_me_work()` / `triage()` includes the
|
||||
`project_id` (and the branch the flow verbs check out). Acceptance
|
||||
criteria and the project context come back inline on the Envelope.
|
||||
|
||||
## Inspecting the repo
|
||||
|
||||
Read-only git inspection is available through the `roboco-git-readonly`
|
||||
MCP server (developers and QA):
|
||||
|
||||
```python
|
||||
roboco_project_list() # All accessible projects
|
||||
roboco_project_list(cell="backend") # Filter by cell
|
||||
roboco_git_status(project_slug="roboco")
|
||||
roboco_git_log(project_slug="roboco")
|
||||
roboco_git_diff(project_slug="roboco")
|
||||
roboco_git_branch_list(project_slug="roboco")
|
||||
```
|
||||
|
||||
Returns projects you have access to (cell-scoped for non-PMs).
|
||||
There is **no** `roboco_git_commit / _push / _checkout / _create_pr /
|
||||
_merge_pr` tool. Commits go through the `commit` content tool (auto-
|
||||
prefixed with `[task-id]`, auto-pushed by the choreographer); PRs open at
|
||||
`open_pr` time; merges are a PM `complete` operation.
|
||||
|
||||
## Get Project Details
|
||||
## Finding project knowledge
|
||||
|
||||
To learn how a project's codebase is laid out or how a subsystem works,
|
||||
query the knowledge base rather than a project tool:
|
||||
|
||||
```python
|
||||
roboco_project_get(slug="roboco")
|
||||
roboco_kb_search(query="rate limiting redis", project="roboco",
|
||||
index_types=["code", "documentation"])
|
||||
roboco_ask_mentor(question="How is auth wired up in this project?")
|
||||
```
|
||||
|
||||
Returns: `name`, `git_url`, `assigned_cell`, `default_branch`, `has_git_token`, `test_command`, etc.
|
||||
## PM note: creating work
|
||||
|
||||
**Note:** `has_git_token` indicates if authentication is configured (required for HTTPS repos).
|
||||
|
||||
## Create Project (PM+ Only)
|
||||
|
||||
```python
|
||||
# Example: register a separate frontend-only repo as a project.
|
||||
# (The built-in RoboCo control panel lives in this same repo under
|
||||
# panel/ and is NOT registered as a separate project.)
|
||||
roboco_project_create(
|
||||
name="Customer Portal",
|
||||
slug="customer-portal",
|
||||
git_url="https://github.com/org/customer-portal.git",
|
||||
assigned_cell="frontend",
|
||||
git_token="ghp_xxxx...", # GitHub PAT with repo scope
|
||||
default_branch="main",
|
||||
test_command="pnpm test",
|
||||
lint_command="pnpm lint"
|
||||
)
|
||||
```
|
||||
|
||||
**Who can create:** Main PM, Board, CEO
|
||||
|
||||
**IMPORTANT:** `git_token` is **required** for HTTPS repositories. Without it, workspace creation and git operations will fail.
|
||||
|
||||
## Update Project
|
||||
|
||||
```python
|
||||
roboco_project_update(
|
||||
slug="roboco-panel",
|
||||
git_token="ghp_newtoken...", # Update/rotate token
|
||||
test_command="pnpm test:ci",
|
||||
lint_command="pnpm lint:fix"
|
||||
)
|
||||
```
|
||||
|
||||
**Who can update:**
|
||||
- CEO, Main PM: Any project
|
||||
- Cell PM: Own cell's projects only
|
||||
|
||||
**Token rotation:** Pass `git_token` to update credentials. Pass empty string to clear.
|
||||
|
||||
## Workspace Tools
|
||||
|
||||
### Ensure Workspace
|
||||
|
||||
```python
|
||||
roboco_workspace_ensure(project_slug="roboco")
|
||||
```
|
||||
|
||||
Creates your workspace if it doesn't exist. Auto-clones the repository.
|
||||
|
||||
### Check Workspace Status
|
||||
|
||||
```python
|
||||
roboco_workspace_status(project_slug="roboco")
|
||||
```
|
||||
|
||||
Returns: `exists`, `branch`, `has_uncommitted`, `staged_files`, `unstaged_files`
|
||||
|
||||
### List Workspaces (PM Only)
|
||||
|
||||
```python
|
||||
roboco_workspace_list(project_slug="roboco")
|
||||
```
|
||||
|
||||
Lists all agent workspaces for a project. Cell PM sees own cell only.
|
||||
|
||||
## Permission Matrix
|
||||
|
||||
| Tool | Dev/QA/Doc | Cell PM | Main PM | CEO |
|
||||
|------|------------|---------|---------|-----|
|
||||
| `project_list` | Own cell | Own cell | All | All |
|
||||
| `project_get` | Yes | Yes | Yes | Yes |
|
||||
| `project_create` | No | No | Yes | Yes |
|
||||
| `project_update` | No | Own cell | All | All |
|
||||
| `workspace_ensure` | Yes | Yes | Yes | Yes |
|
||||
| `workspace_status` | Yes | Yes | Yes | Yes |
|
||||
| `workspace_list` | No | Own cell | All | All |
|
||||
|
||||
## Task Creation with Project
|
||||
|
||||
When creating tasks:
|
||||
|
||||
```python
|
||||
roboco_task_create(
|
||||
title="Add rate limiting",
|
||||
team="backend",
|
||||
project_slug="roboco", # Required - all tasks follow git workflow
|
||||
)
|
||||
```
|
||||
|
||||
Use `project_slug="roboco"` for internal RoboCo codebase work.
|
||||
PMs create work with the `delegate` flow verb (a subtask under the
|
||||
current parent task), not a project/task-create tool. `delegate` takes an
|
||||
optional `project_id`; the parent task's project is inherited when you
|
||||
omit it. There is no agent-facing standalone project- or task-create
|
||||
tool.
|
||||
|
||||
Reference in New Issue
Block a user