External/roboco
1
0
Fork 0
mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs(0.7.0): document Grok provider, self-heal, PR-reviewer across the RAG + how-to docs

Browse Source 
Close the doc gaps the audit found in the agent knowledge base and the human
walkthrough:
- config-reference: add the Grok provider env table (host ~/.grok subscription
  mount, grok-build, idle-kill, cost cap) and the Self-Healing CI loop toggles.
- agent-model: provider-aware Model Configuration (ANTHROPIC default / GROK) +
  add the pr_reviewer / prompter / secretary roles to the Roles table.
- tool-permissions: 'three' -> five MCP servers (roboco-optimal, roboco-docs) +
  PR Reviewer / Prompter / Secretary tool sections.
- new roles/pr-reviewer.md (the 22nd agent had no role doc); permissions +
  agent-uuids + task-tools 'PR Reviewer flow' all gain the role.
- api-endpoints: drop the removed USAGE_UPDATE event (only USAGE_SNAPSHOT exists).
- how-to: self-healing CI loop + Company Scorecard (ch.5), inbound external-PR
  review + CEO Supersede/Dismiss queue (ch.4).

Every claim verified against current code by the audit (grok model grok-build,
auth ~/.grok, no metered API; opencode fully removed).
This commit is contained in:
Renn F
2026-06-19 10:50:58 +02:00
parent 982da35cc0
commit 68094d5f2a
10 changed files with 137 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/rag/architecture/agent-model.md
+5
View File
@@ -24,6 +24,9 @@
| `developer` | Writes code |
| `qa` | Reviews and tests |
| `documenter` | Writes documentation |
| `pr_reviewer` | Read-only reviewer of inbound external/fork + internal PRs (agent `pr-reviewer-1`) |
| `prompter` | On-demand intake interviewer, human-only (agent `intake-1`) |
| `secretary` | On-demand chief-of-staff, human-only (agent `secretary-1`) |
| `system` | Internal orchestrator |
## Teams
@@ -61,6 +64,8 @@ Stored in `model_config` JSON:
- Temperature
- Other settings
The **provider** selects the agent backend, resolved through the `ProviderRegistry` (`roboco/llm/providers/`). `ModelProvider` is `ANTHROPIC` (default — Claude Code), `GROK` (xAI's official `grok` CLI, model `grok-build`, on a SuperGrok subscription), `LOCAL`, `OLLAMA_CLOUD`, or `OPENAI` (reserved). An agent with no dedicated provider falls back to the built-in Claude Code spawn. Grok auth is the host `~/.grok` subscription mount (auto-refreshed by the orchestrator), not a metered API key.
## Agent-Specific Fields
| Field | Description |
docs/rag/architecture/agent-uuids.md
+3
View File
@@ -64,6 +64,9 @@ delegate(assigned_to="00000000-0000-0000-0001-000000000001", ...)
| `product-owner` | `00000000-0000-0000-0004-000000000002` |
| `head-marketing` | `00000000-0000-0000-0004-000000000003` |
| `auditor` | `00000000-0000-0000-0004-000000000004` |
| `intake-1` (prompter) | `00000000-0000-0000-0004-000000000005` |
| `secretary-1` | `00000000-0000-0000-0004-000000000006` |
| `pr-reviewer-1` | `00000000-0000-0000-0004-000000000007` |
## CEO (0000)
docs/rag/architecture/config-reference.md
+27
View File
@@ -62,6 +62,33 @@ Environment variables for RoboCo (prefix: `ROBOCO_`).
| `ROBOCO_LOCAL_LLM_BASE_URL` | `http://roboco-ollama:11434/v1` | OpenAI-compat API |
| `ROBOCO_OLLAMA_BASE_URL` | `http://roboco-ollama:11434` | Native Ollama API |
## Grok provider (xAI)
Agents whose provider is `GROK` run xAI's official `grok` CLI. Auth is the host SuperGrok subscription (mounted `~/.grok`), not a metered API key.
| Variable | Default | Description |
|----------|---------|-------------|
| `ROBOCO_HOST_GROK_DIR` | `~/.grok` | Host dir holding `auth.json`, mounted into Grok agents; the orchestrator auto-refreshes the ~6h token in place. Set up once with `grok login`. |
| `ROBOCO_GROK_CLI_MODEL` | `grok-build` | Grok CLI model id |
| `ROBOCO_GROK_AGENT_IMAGE` | `roboco-agent-grok:latest` | Image for Grok delivery agents |
| `ROBOCO_GROK_REASONING_EFFORT` | (blank) | Per-run reasoning-effort override; blank = the grok CLI default |
| `ROBOCO_GROK_IDLE_KILL_SECONDS` | `900` | Kill + evict a Grok container that has been ACTIVE-yet-idle (no gateway verb) this long |
| `ROBOCO_GROK_MAX_COST_USD` | `0.0` | Per-agent Grok cost ceiling (USD); `0` disables |
## Self-Healing CI loop
RoboCo watching its own repo's CI. All default-off / dormant.
| Variable | Default | Description |
|----------|---------|-------------|
| `ROBOCO_SELF_HEAL_ENABLED` | `false` | Master switch (detect + notify the CEO); off = the loop never runs and no CI is fetched |
| `ROBOCO_SELF_HEAL_ORIGINATE_ENABLED` | `false` | Second opt-in: also open a PENDING fix task on a regression — CEO-gated, never auto-started/merged/deployed |
| `ROBOCO_SELF_HEAL_PROJECT_SLUG` | (empty) | The registered project that IS RoboCo itself — the only repo it watches and fixes; empty = no-op |
| `ROBOCO_SELF_HEAL_CI_WORKFLOW` | (empty) | GitHub Actions workflow to scope the CI signal to (e.g. `ci.yml`); empty = latest across all workflows |
| `ROBOCO_SELF_HEAL_INTERVAL_SECONDS` | `1800` | Seconds between assessment passes |
| `ROBOCO_SELF_HEAL_MAX_OPEN_TASKS` | `3` | Rolling cap on concurrently-open self-heal tasks |
| `ROBOCO_SELF_HEAL_MAX_PER_CYCLE` | `1` | Max fix tasks originated per cycle |
## Security
| Variable | Default | Description |
docs/rag/architecture/permissions.md
+4
View File
@@ -12,6 +12,10 @@ What each role can do in the system.
| MAIN_PM | main_pm |
| CELL_PM | cell_pm |
| CELL_MEMBER | developer, qa, documenter |
| (read-only reviewer) | pr_reviewer |
| (human-only) | prompter, secretary |
`pr_reviewer` is a board-adjacent, read-only role (QA level): it claims and posts inbound-PR reviews (`claim_pr_review` / `post_pr_review`) but creates, assigns, completes, and notifies nothing. `prompter` (intake) and `secretary` are **human-only** — they chat with the CEO and have only `note` + `evidence`, with no task or notification permissions; they don't appear in the action tables below.
## Task Permissions
docs/rag/architecture/tool-permissions.md
+23 -1
View File
@@ -2,13 +2,15 @@
## Overview
Agents call gateway verbs through three MCP servers, scoped per role:
Agents call gateway verbs through up to five MCP servers, scoped per role:
| MCP server | Provides |
|------------|----------|
| `roboco-flow` | Lifecycle verbs (give_me_work, i_will_work_on, open_pr, complete, …) |
| `roboco-do` | Content/write verbs (commit, note, say, dm, notify, evidence) |
| `roboco-git-readonly` | Read-only git inspection (status, log, diff, branch_list) |
| `roboco-optimal` | RAG (`roboco_ask_mentor`, `roboco_kb_search`) |
| `roboco-docs` | Project docs file management (selected roles) |
Native shell git is blocked by the bash-guard hook for everyone. There is **no** `roboco_git_commit / _push / _create_pr / _merge_pr / _checkout` tool — write operations happen through the lifecycle verbs and the choreographer handles git as a side-effect.
@@ -80,6 +82,26 @@ The canonical source of role → verb mapping is `roboco/services/gateway/role_c
**Read-only git:** none.
## PR Reviewer
**Flow verbs:** `give_me_work`, `claim_pr_review`, `post_pr_review`, `i_am_idle` (read-only)
**Content verbs:** `note`, `evidence`, plus notification reads (`notify_list`, `notify_get`) and channel discovery — no `say` / `dm`: the change-request is posted server-side on the PR itself.
**Read-only git:** none.
**Workspace writes:** none — reviews inbound external/fork + internal PRs only.
## Prompter (Intake) & Secretary
Both are human-only roles — they chat with the CEO, not other agents.
**Flow verbs:** `i_am_idle` only.
**Content verbs:** `note`, `evidence` only (no `say` / `dm` / `notify`).
**Read-only git / workspace writes:** none.
## Tool Permissions Summary
| Capability | Dev | Doc | QA | Cell PM | Main PM | Board | Auditor |
docs/rag/roles/pr-reviewer.md
+51
View File
@@ -0,0 +1,51 @@
# PR Reviewer Role
## Identity
- **Agent:** pr-reviewer-1 (the single global reviewer — one review at a time)
- **Role:** `pr_reviewer`
- **Team:** none (board-adjacent, read-only; `RoleLevel.QA`)
- **Reports to:** CEO
## Core Responsibilities
1. Review **inbound** pull requests the org did not open — external / fork PRs (gated by an author allowlist), and, behind a second flag, internal org-repo PRs opened outside the agent task-flow.
2. Read the PR diff adversarially against the project's standards and post **one** complete change-request as a real GitHub review **on the PR itself** — no agent-to-agent chatter.
3. Journal evidence of what was checked.
The org's own in-flight integration PRs are skipped — a live task already owns their branch and they pass QA + PM review. Re-review is driven by the PR's head commit: an unchanged PR is skipped, new commits open a fresh review.
## What You CAN Do
- Pull an inbound-PR review task via `give_me_work()` and claim it via `claim_pr_review(task_id)`.
- Post your verdict via `post_pr_review(task_id, ...)` — the change-request lands on the PR as a GitHub review (server-side; you never push to the contributor's fork).
- Read-only inspect git via `roboco_git_status / _log / _diff / _branch_list`.
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`.
- Note evidence via `note(...)` and `evidence(...)`.
## What You CANNOT Do
- Modify code, `commit`, push, open / merge PRs — not in your manifest.
- `say` / `dm` other agents — you have no comms surface; your output is the PR review.
- Send `notify` (ack-required notifications) — PMs / Board only.
- Decide the PR's fate. You review; the **CEO** decides. Your completed review surfaces in the **CEO PR Review Queue** (Command Center), where the CEO chooses **Supersede** (the org cuts its own branch off the contributor's commits, hardens the work, opens its own PR, and — once that merges — closes and links the contributor PR) or **Dismiss**.
## Task Flow (gateway verbs)
```
give_me_work() → returns an inbound-PR review task
claim_pr_review(task_id) → claim it (planless, branchless — read-only)
post_pr_review(task_id, ...) → posts the change-request on the PR; task -> completed
i_am_idle() → out of work
```
## Tool Surface (per-spawn manifest)
| MCP server | Verbs you can call |
|-----------------------|--------------------|
| `roboco-flow` | `give_me_work`, `claim_pr_review`, `post_pr_review`, `i_am_idle` |
| `roboco-do` | `note`, `evidence`, `notify_list`, `notify_get`, channel discovery (no `say` / `dm` / `commit` / `notify`) |
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
There is **no** `commit` / `roboco_git_commit / _push / _create_pr / _merge_pr` tool in your surface — the PR reviewer is read-only by design. Your single change-request, posted via `post_pr_review`, is the entire output.
docs/rag/tools/api-endpoints.md
+1 -1
View File
@@ -90,7 +90,7 @@ Base URL: `http://{host}:{port}/api/v1`
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/system/rate-limits` | Active per-provider rate-limit state (`{ entries: [...] }`) |
| WS | `/ws/system` | Operator stream — rate-limit lifecycle (`RATE_LIMIT_HIT` / `RATE_LIMIT_LIFTED`) and live usage (`USAGE_UPDATE` / `USAGE_SNAPSHOT`) pushed to the usage dashboard |
| WS | `/ws/system` | Operator stream — rate-limit lifecycle (`RATE_LIMIT_HIT` / `RATE_LIMIT_LIFTED`) and live usage (`USAGE_SNAPSHOT`) pushed to the usage dashboard |
| WS | `/ws/agents/{id}`, `/ws/channels/{id}`, `/ws/sessions/{id}`, `/ws/notifications/{id}` | Per-resource live streams |
## Documentation
docs/rag/tools/task-tools.md
+11
View File
@@ -101,6 +101,17 @@ i_am_idle()
The Auditor is a silent observer: read-only `triage`, no `say`/`dm`/ `notify`, no claim/complete/cancel.
## PR Reviewer flow
```python
give_me_work() # returns an inbound-PR review task
claim_pr_review(task_id) # claim it (planless, branchless — read-only)
post_pr_review(task_id, ...) # posts one change-request on the PR; task -> completed
i_am_idle()
```
The PR Reviewer reviews inbound external/fork (and, behind a flag, internal) PRs the org did not open. It is read-only: no `commit`/`open_pr`/`merge`, no `say`/`dm` — the change-request is posted server-side on the PR itself, and the CEO decides Supersede/Dismiss from the PR Review Queue.
## Cancel
Cancelling a task (any non-terminal status -> `cancelled`) is restricted to **PM roles and the CEO**. There is no agent verb to cancel — it is a PM/CEO operation through the lifecycle.