mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
docs(0.7.0): document Grok provider, self-heal, PR-reviewer across the RAG + how-to docs
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
@@ -24,6 +24,10 @@ The cells' work is folded up, the Main PM opens the **final pull request** into
|
||||
|
||||
*Your two words. **Approve & Merge** and it ships to `master`; **Request Changes** and it goes around for another lap. The last call has the same shape as the first — one decision, yours alone.*
|
||||
|
||||
## The other queue: PRs you didn't open
|
||||
|
||||
Not every pull request comes from inside the company. When someone opens a PR against your repo — an external contributor, a fork — the read-only **PR Reviewer** picks it up, reads the diff against your standards, and posts a single change-request directly on the PR (it never chats, never merges, never decides). The PR then surfaces in the **PR Review Queue** on the Command Center — your second decision surface. There you **Supersede** it: the company cuts its own branch from the contributor's commits, hardens the work to your standards, opens its own PR, and — once that replacement merges — closes and links the original. Or you **Dismiss** it. Either way the call is yours, and the org never pushes to anyone else's fork.
|
||||
|
||||
---
|
||||
|
||||
## And round it goes
|
||||
|
||||
@@ -14,6 +14,10 @@ Where the charter says what the company *should* be doing, the Cockpit shows wha
|
||||
|
||||
<!-- Screenshot to capture: the Cockpit with spend-vs-budget and the signals panel. -->
|
||||
|
||||
## The Company Scorecard
|
||||
|
||||
On the Business tab's Goals view sits the Company Scorecard — live performance against the charter in one card. Where the Cockpit surfaces signals to act on, the Scorecard is the one-glance answer to "how is the company actually doing?": what's been delivered, spend against budget, the median lead time from task to merge, and progress on the objectives you set. It is the company's vital signs, read off the same work the rest of the panel tracks.
|
||||
|
||||
## The Secretary
|
||||
|
||||
The Secretary is your conversational chief-of-staff. You chat with it the way you'd brief a human one — ask it where things stand, or dictate a change to the charter. What it never does is act on its own: every directive it derives from your instruction is **gated**, landing in a queue for your explicit confirmation before anything happens. It reads the whole company's state to advise you, but it spends nothing, builds nothing, and approves nothing until you say the word. It is leverage with a safety catch — your intent, executed, but only after you confirm it.
|
||||
@@ -32,6 +36,10 @@ Flip **Web research** on in Settings → Feature Flags (or set `ROBOCO_RESEARCH_
|
||||
|
||||
Flip **the strategy engine** on in Settings → Feature Flags (or set `ROBOCO_STRATEGY_ENGINE_ENABLED=true`) and a background loop begins watching the company against its charter. When it spots drift from the objectives, agents gone idle, or work blocked for too long, it tells you. It is **notify-only by design**: it never spends, never builds, never approves — it raises the flag and leaves the decision where every decision belongs, with you. Off, it is fully dormant.
|
||||
|
||||
### The self-healing CI loop
|
||||
|
||||
The same shape, pointed inward: flip **self-healing** on in Settings → Feature Flags (or set `ROBOCO_SELF_HEAL_ENABLED=true`) and RoboCo begins watching its **own** repository's CI. When a run regresses it tells you. Turn on the second switch (`ROBOCO_SELF_HEAL_ORIGINATE_ENABLED=true`) and it goes one step further — it opens a fix task for the regression, but only as far as **PENDING, awaiting your approval**. It never starts, merges, or deploys that work itself: the company can notice it broke its own build and queue the repair, but the call to run it stays yours. Both switches are off by default, and it watches only the one repo you name as RoboCo itself.
|
||||
|
||||
## Feel the whole thing
|
||||
|
||||
The cleanest way to understand this layer is to walk it once, end to end:
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user