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: add the user-facing MkDocs documentation site

Browse Source 
Build a complete user-facing documentation site (MkDocs Material) under docs/, served at roboco.dev/docs via a new gh-pages deploy workflow.

- Sections: Get Started, The Company, the Tour, Operating the Panel, Choosing & Running Models, Cost & Observability, Optional Subsystems, Configure & Deploy, API Reference, Troubleshooting & Security (55 pages).
- mkdocs.yml (Material theme; excludes the agent-facing rag/ corpus, internal scratch, and orphaned stub trees) and .github/workflows/docs.yml (mkdocs gh-deploy to gh-pages).
- Retire the stale root usage.md and deployment.md to redirect stubs into the site.
- Fix the docs tooling: add the pymarkdownlnt dependency + .pymarkdown.json, run serve-docs/lint-docs/fix-docs under the docs extra, add a build-docs strict gate.
- Fix the roboco console-script entry point (cli, not the un-awaited async main).
- README: correct the project-structure tree (optimal.py, alembic) and link the docs site.
This commit is contained in:
Renn F
2026-06-22 15:53:00 +02:00
parent 3a3cd69e1e
commit 2fb63fed1f
64 changed files with 3553 additions and 500 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/company/agent-gateway.md
+49
View File
@@ -0,0 +1,49 @@
# How agents are sandboxed
The most important thing to understand about trusting RoboCo with your repository: **agents never touch your API, your database, or a shell directly.** Every action an agent can take goes through a narrow, server-side gateway that only exposes the handful of verbs that agent's *role* is allowed to use. Capability is decided by role at spawn time — not by the model's good behavior.
## Agents speak in verbs, not API calls
Each agent container talks to RoboCo through two thin MCP servers, both backed by a single server-side component (the **Choreographer**) that composes the real services behind the scenes:
| Server | What it exposes |
|--------|-----------------|
| `roboco-flow` | **Intent verbs** — the lifecycle actions: `give_me_work`, `i_will_work_on`, `open_pr`, `i_am_done`, `claim_review`, `pass_review`, `complete`, `submit_up`, `submit_root`, `pr_pass`, … |
| `roboco-do` | **Content tools** — `commit`, `note`, `say`, `dm`, `evidence`. |
Two more read-only servers give agents a read-only view of git (`status`, `log`, `diff`) and access to the knowledge base. That's the entire surface. There is no "run arbitrary SQL," no "call any endpoint," no general shell.
## A role can only call its own verbs
At spawn, every agent is handed a **manifest** listing exactly the verbs its role may call — and nothing else. The manifest is built from a server-side role configuration and mounted read-only into the container. The result is that the lifecycle's role rules aren't just policy, they're *unreachable code* for the wrong role:
- A **developer** can `give_me_work`, open a PR, and mark itself done — but there is no merge verb in its manifest.
- **QA** can claim a review and pass or fail it — but it has no `commit`.
- A **PR reviewer** can pass or fail an assembled PR and post its review on the PR — but it never gets agent chat verbs.
- The **Auditor** is restricted to leaving a private note and reading evidence; it cannot `say` or `dm`. It observes; it does not participate.
So when [the lifecycle](task-lifecycle.md#role-gated-transitions) says "only QA can pass QA" or "only the CEO merges to master," that boundary is enforced at the gateway: the verb simply isn't available to anyone else.
## Every action returns a structured envelope
Agents don't guess at state. Every verb returns a standardized **envelope**:
- On success: `{ status, task_id, next, evidence?, context_briefing }` — where `next` tells the agent what to call next.
- On error: `{ error, message, remediate, missing }` — where `remediate` tells the agent exactly how to fix it and retry.
That `next` / `remediate` contract is why agents move through the lifecycle reliably instead of flailing: the gateway leads them, step by step, and rejects anything out of order with an explanation rather than a crash.
## The other guardrails
A few more protections run by construction, the same way on every backend (Claude or Grok):
- **Claim-locking** serializes work, so two agents can't grab the same task or race a merge.
- **The token never enters the container.** Your GitHub PAT is injected only for the moment of a git operation, orchestrator-side, and scrubbed from every clone — see [Register a project](../get-started/first-project.md#what-happens-under-the-hood).
- **A prompt-injection guard** screens task prompts, and a bash guard blocks credential-exfiltration and identity-forgery patterns.
- **Rate limits and overloads park, they don't crash-loop.** If a provider returns a 429 or a persistent overload, RoboCo *queues* that agent's work and probes for recovery instead of burning tokens retrying. You'll see an amber banner; the work resumes automatically when the provider does.
The practical upshot for you as operator: the workforce is structurally constrained to do its job and only its job. You're not relying on twenty-five models all choosing to behave — you're relying on the fact that the misbehaving action isn't on the menu.
## Next
→ Watch it all in motion in [the Tour](../how-to/README.md), or head back to [the lifecycle](task-lifecycle.md).
docs/company/index.md
+35
View File
@@ -0,0 +1,35 @@
# The Company
What keeps twenty-five agents from dissolving into noise is that RoboCo is relentlessly opinionated about *how* work happens. Everything is a task, no task moves without acceptance criteria, and every task walks the same strict, role-gated lifecycle — built, QA'd, documented, reviewed, approved. The structure is the point. It's what turns a roster of models into a company that actually ships.
This section explains the machinery:
<div class="grid cards" markdown>
- **[Org & roles](org-and-roles.md)**
---
The twenty-five agents, the three cells, the Board, and the chain of command you sit on top of.
- **[The task lifecycle](task-lifecycle.md)**
---
The fifteen states every task moves through, who owns each step, and how rejected work loops back.
- **[The merge model](merge-model.md)**
---
How work flows up a cell → root → master pull-request chain — and why only you ever touch `master`.
- **[How agents are sandboxed](agent-gateway.md)**
---
Agents never touch your API or your shell. They act only through a narrow set of role-scoped verbs.
</div>
If you'd rather see these ideas in motion than read about them, [the Tour](../how-to/README.md) follows one real feature through the whole company.
docs/company/merge-model.md
+61
View File
@@ -0,0 +1,61 @@
# The merge model
A feature in RoboCo isn't one commit on one branch — it's a small tree of work that converges, as real pull requests, up a fixed chain to your repository's default branch. The rule at the top is simple and absolute: **only you ever merge to `master`.**
## Branches, commits, and PRs are traceable
Every branch, commit, and pull request carries the task ID it belongs to, so your git history reads back to the work that produced it.
- **Branches** follow `{type}/{team}/{task-hierarchy}`, where the hierarchy uses `--` between levels (a `/` would collide with git's ref storage). Types are `feature`, `bug`, `chore`, `docs`, `hotfix`.
```text
feature/backend/ABC12345 # a root task
feature/backend/ABC12345--DEF67890 # a subtask
feature/backend/ABC12345--DEF67890--GHI11111 # a sub-subtask (max depth)
```
- **Commits** are auto-prefixed with the short task ID: `[ABC12345] Add the auth endpoint`.
- **Pull requests** are titled the same way: `[ABC12345] <title>`.
A branch is created automatically the moment an agent claims a task, and a **work session** tracks its branch, base, commits, files changed, and pull request from claim to merge.
## Work converges up a chain
Each developer works in their **own clone** and opens a pull request from their branch. Those flow upward:
```mermaid
graph BT
D1["dev branch"] --> C["cell branch"]
D2["dev branch"] --> C
C --> R["root / integration branch"]
C2["other cell branch"] --> R
R --> M["master"]
M:::ceo
classDef ceo fill:#1f6feb,color:#fff,stroke:#1f6feb;
```
1. **Developers → cell.** A cell's developers merge their work into the cell's branch.
2. **Cell → root.** The **cell PM** runs `submit_up` to open the cell → root pull request. The Main PM keeps one integration (root) branch per repository.
3. **Root → master.** The **Main PM** runs `submit_root` to open the final root → master pull request.
Each of those assembled pull requests passes through the [in-path PR-review gate](task-lifecycle.md#the-in-path-pr-review-gate) before its PM merges it.
## Only the CEO merges to master
The final pull request — root → master — is the one place the company stops and hands the decision back to you. It lands in your **CEO Approval Queue** and waits.
- The agent-facing merge path **hard-refuses to target the default branch.** A PM can merge a cell PR up to the root, but the merge to `master` is reserved for the CEO action, taken from `awaiting_ceo_approval`.
- **Force-push is CEO-only** too.
From the queue you **Approve & Merge** (it ships to `master`), **Request Changes** (it loops back for another pass), or **Cancel**. This is the second of the only two moments the company needs you — the first being the green light that started the work.
!!! info "Why a squash and one integration branch"
Cell pull requests are squash-merged, so each cell's work lands as a single verified commit on the integration branch, co-authored by the agent that wrote it. The final pull request then carries one clean commit per cell — three streams of work folded into one reviewable history.
## Pull requests you didn't open
Not every pull request comes from inside the company. When an external contributor or a fork opens one against your repository, the read-only **PR Reviewer** reads the diff against your standards and posts a single change-request on the PR — it never chats, merges, or decides. The PR then surfaces in the **PR Review Queue** on the Command Center, where you **Supersede** it (the company cuts its own branch from the contributor's commits, hardens it, opens its own PR, and links back to the original once that merges) or **Dismiss** it. Either way the call is yours, and the org never pushes to anyone else's fork. *(This inbound-review flow is feature-flagged; see the optional-subsystems reference.)*
## Next
→ **[How agents are sandboxed](agent-gateway.md)** — why a developer agent literally cannot perform the merge.
docs/company/org-and-roles.md
+92
View File
@@ -0,0 +1,92 @@
# Org & roles
RoboCo is **25 AI agents and one human — you, the CEO**. They're organized as a real company: a Board sets direction, a Main PM coordinates three delivery cells, and an Auditor watches everything. A few agents sit at your side on demand. You're on top of all of it.
```mermaid
graph TD
CEO["👤 CEO — you (human)"]
subgraph Support["At your side (on demand)"]
INTAKE["Intake<br/>drafts tasks with you"]
SEC["Secretary<br/>gated chief-of-staff"]
PRR["PR Reviewer<br/>inbound + root→master gate"]
end
subgraph Board["Board"]
PO["Product Owner"]
HOM["Head of Marketing"]
AUD["Auditor (silent)"]
end
MPM["Main PM<br/>coordinates the cells"]
subgraph Cells["Delivery cells (6 agents each)"]
BE["Backend cell"]
FE["Frontend cell"]
UX["UX/UI cell"]
end
CEO --- Support
CEO --> Board
Board --> MPM
MPM --> BE & FE & UX
```
## The cells
The three delivery cells — **Backend, Frontend, UX/UI** — are where code gets written. Each cell is a small, complete team of **six agents**:
| Role | Count | What they do |
|------|-------|--------------|
| **Cell PM** | 1 | Runs the cell like an engineering manager: delegates, clears blockers, triages, and folds the cell's work up to the Main PM. |
| **Developers** | 2 | Build the code in their own clones and open pull requests. |
| **QA** | 1 | Reads the real diff and decides whether work ships or comes back. Doesn't rubber-stamp. |
| **Documenter** | 1 | Writes down what was built, so the next agent — and you — don't start cold. |
| **PR Reviewer** | 1 | Reviews the cell's assembled pull request at the in-path gate before the PM merges it up. |
UX/UI usually leads and sets the contracts; Frontend and Backend build against them.
## The Board and the Main PM
| Role | Reports to | What they do |
|------|-----------|--------------|
| **Product Owner** | CEO | Turns your ask into requirements and acceptance criteria. |
| **Head of Marketing** | CEO | Reviews work from the positioning / naming / user angle. |
| **Auditor** | CEO | Silent observer with read access to *everything*; reports quality concerns to you and never interferes. |
| **Main PM** | Board | Coordinates all three cells: fans a task out into per-cell subtasks, integrates the results, and opens the final pull request. |
## At your side, on demand
Three agents work directly with you rather than in the delivery flow. They run only while you're interacting with them or have given an explicit instruction:
| Role | What they do |
|------|--------------|
| **Intake** | The conversational **Task Assistant** on the Prompter page. Reads your codebase and drafts a well-formed task with you. Chats only with you. |
| **Secretary** | Your conversational chief-of-staff. Reads the whole company's state to advise you and executes your directives — but every high-impact action is **gated** for your explicit confirmation. It spends nothing and approves nothing on its own. |
| **PR Reviewer** | The read-only main reviewer. Handles inbound external/fork pull requests and acts as the in-path gate on the final root → master pull request. It posts a review on the PR; it never chats, merges, or decides. |
## The full roster
25 agents, by their panel IDs:
- **Backend:** `be-pm`, `be-dev-1`, `be-dev-2`, `be-qa`, `be-doc`, `be-pr-reviewer`
- **Frontend:** `fe-pm`, `fe-dev-1`, `fe-dev-2`, `fe-qa`, `fe-doc`, `fe-pr-reviewer`
- **UX/UI:** `ux-pm`, `ux-dev-1`, `ux-dev-2`, `ux-qa`, `ux-doc`, `ux-pr-reviewer`
- **Coordination:** `main-pm`
- **Board:** `product-owner`, `head-marketing`, `auditor`
- **At your side:** `intake-1`, `secretary-1`, `pr-reviewer-1`
## How agents talk
Communication is constant and logged. Agents narrate their reasoning, and formal **notifications** (the ones that need your acknowledgment) come only from PMs and the Board. Channels are seeded automatically:
- **Cell channels** — `#backend-cell`, `#frontend-cell`, `#uxui-cell`
- **Cross-cell** — `#dev-all`, `#qa-all`, `#pm-all`, `#doc-all`
- **Management** — `#main-pm-board`, `#board-private`
- **Company-wide** — `#announcements` (read-only except Board / Main PM), `#all-hands`
The **Auditor has silent read access to every channel.** You watch all of it from the **Communications** page.
## Next
→ **[The task lifecycle](task-lifecycle.md)** — the path every piece of work walks.
docs/company/task-lifecycle.md
+89
View File
@@ -0,0 +1,89 @@
# The task lifecycle
Everything in RoboCo is a task, and every task walks the same path. Each step is gated by role — only QA can pass QA, only the CEO can merge to `master` — so work can't skip a stage or land unreviewed. This is the backbone that makes the company trustworthy.
```mermaid
stateDiagram-v2
direction LR
[*] --> backlog
backlog --> pending: PM activates
pending --> claimed: agent claims
claimed --> in_progress: start work
in_progress --> verifying: self-verify
verifying --> awaiting_qa: submit (PR is open)
awaiting_qa --> awaiting_documentation: QA passes
awaiting_qa --> needs_revision: QA fails
needs_revision --> in_progress: rework
awaiting_documentation --> awaiting_pm_review: docs done
awaiting_pm_review --> completed: PM merges
awaiting_pm_review --> awaiting_ceo_approval: escalate
awaiting_ceo_approval --> completed: CEO approves & merges
awaiting_ceo_approval --> needs_revision: CEO requests changes
completed --> [*]
in_progress --> blocked: external dependency
in_progress --> paused: temporarily stopped
blocked --> in_progress: unblocked
paused --> in_progress: resumed
```
## The states
| State | What it means | Who owns the next move |
|-------|---------------|------------------------|
| `backlog` | PM setup phase — dependencies or session setup still needed. | PM |
| `pending` | Ready for work; the orchestrator can spawn an agent for it. | the matching role |
| `claimed` | An agent has locked the task. | the assignee |
| `in_progress` | Active development. | the assignee |
| `blocked` | An external dependency is blocking progress. | whoever clears it |
| `paused` | Temporarily stopped; can resume. | the assignee |
| `verifying` | The developer is self-verifying before handing off. | the developer |
| `awaiting_qa` | Submitted for QA — **a pull request is already open** so QA reviews the real diff. | QA |
| `needs_revision` | QA, a PR reviewer, or the CEO asked for changes. | the developer |
| `awaiting_documentation` | The Documenter writes up what was built (the PR is already open). | Documenter / Developer |
| `awaiting_pr_review` | The in-path PR-review gate: a reviewer checks an assembled pull request before the PM merges it. | PR reviewer |
| `awaiting_pm_review` | Docs are done; the PM reviews and merges. | PM |
| `awaiting_ceo_approval` | A major task escalated to you for the final call. | **you** |
| `completed` | Terminal — work done and merged. | — |
| `cancelled` | Terminal — work cancelled. | — |
!!! note "The PR comes *before* QA"
A pull request is opened *before* QA review, not after. That lets QA read the actual PR diff on GitHub, and means the whole downstream approval chain — PM, then you — is signing off on a pull request that already exists.
## When work is rejected
Rejection isn't a dead end — it's a loop. When **QA fails** a task, or a **PR reviewer rejects** an assembled pull request, the task drops back to `needs_revision`, the developer reworks it, and it re-enters the flow. The same is true when *you* request changes from the CEO Approval Queue. Nothing is lost; the task carries its history, branch, and pull request with it the whole way around.
## The in-path PR-review gate
Most leaf developer tasks are reviewed by QA and never need a separate PR review. But when work is **assembled and pushed up the chain as a pull request**, it stops for a dedicated review before any PM merges it:
```mermaid
stateDiagram-v2
direction LR
in_progress --> awaiting_pr_review: submit_up / submit_root
awaiting_pr_review --> awaiting_pm_review: pr_pass
awaiting_pr_review --> needs_revision: pr_fail
```
- A **cell PM** runs `submit_up` to open the cell → root pull request.
- The **Main PM** runs `submit_root` to open the root → master pull request.
- Both land in `awaiting_pr_review`, where a PR reviewer either **`pr_pass`es** it on to the PM merge or **`pr_fail`s** it back to `needs_revision`.
This gives the merge step a real reviewer with the power to reject — the one thing a PM otherwise lacks. **Leaf dev tasks and branchless coordination roots skip the gate.**
## Role-gated transitions
Transitions aren't suggestions; they're enforced. A handful of the rules:
- **Activating** a task (`backlog → pending`) is PM-only.
- **Passing or failing QA** is QA-only, and a pass requires real review notes.
- **`pr_pass` / `pr_fail`** are PR-reviewer-only.
- **Merging** (`awaiting_pm_review → completed`) is PM-only; **escalating to the CEO** and the final **approve / request-changes / cancel** are CEO-only.
- **Cancelling** is PM-only.
How those role boundaries are enforced — and why a developer literally cannot call the merge verb — is the subject of [How agents are sandboxed](agent-gateway.md).
## Next
→ **[The merge model](merge-model.md)** — how a task's branch travels up to `master`.