mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
feat(board): Board Programs — the complete twelve-program catalog (Phases 1-3) (#699)
* feat(board): Pest Control — the first project-scoped Board Program The Product Owner hunts latent defects (what the org records but nobody reads): a weekly cycle — accelerated off-schedule when the trailing-7-day rework rate crosses pest_rework_threshold, with the cheap dedup/scope gates evaluated before the metrics queries — opens one held exploration task against the least-recently-explored opted-in project (deterministic round-robin; opted_in_projects gains a stable ORDER BY), with server- assembled evidence in the spawn prompt (rework hotspots, recurring-findings and waived-minor ledger aggregates, all capped) plus prior-cycle LEARN context. The PO calls the new PO-only propose_bug_hunt verb once: ≤5 items, evidence required per item, targets validated against pest_control participation. CEO decides per item — approve materializes a BACKLOG task (source pest_control, never auto-starts), reject records the reason; both feed the LEARN ledger by exploration task id; all-terminal completes the cycle. Telegram queue pushes carry working Approve/Reject handlers mirroring the roadmap kind. Doctrine: board.md Pest Control section + product-owner verb entry + regenerated verb tables. * feat(panel): Pest Control review queue Command Center gains the pest review queue (per-item approve/reject with reason, mirroring the roadmap queue); the Programs card and the project settings participates-in checkboxes pick the new program up registry-driven — the settings section renders for the first time now that a project-scoped program exists. * feat(board): Periscope — HoM market-research brief program Weekly org-scoped cycle: a solo HoM spawn researches the market (web research with mandatory source URLs — uncited findings are rejected) and files one structured brief via the new HoM-only propose_market_brief verb: headline, cited findings, threats/opportunities, positioning note, all soup-checked and screened through the injection guard at persist time (web-derived text later reaches prompts; flags recorded, content never dropped). A brief is a report, not a proposal: the verb completes the exploration in the same call (the x_feature asymmetry), the cycle ledger auto-closes, and the CEO gets a best-effort notification with no approve/reject surface (periscope deliberately never joins Telegram's action kinds). The latest brief is injected into the roadmap exploration prompt — Periscope feeds Printer, the first cross-role program input. * feat(panel): Market Briefs tab (read-only) Business page gains a Market Briefs tab listing Periscope briefs — headline, cited findings, threats/opportunities — read-only by design; a report has nothing to approve. * feat(board): Coroner — event-triggered Auditor postmortems The first EVENT program: no cron — three best-effort hooks open an autopsy when a task bounces to its 3rd revision (the audit chokepoint), is cancelled after work started, or is budget-blocked; all gated on arming + one-open-autopsy dedup, none can fail the underlying transition. A solo Auditor spawn reads the incident (server-assembled findings + transition context) and files one propose_postmortem: incident summary, root cause, failed stage (validated against the real status vocabulary), and ONE process change — a playbook-kind change drafts via PlaybookService directly into the normal pending-curation queue; the briefed draft_playbook manifest grant was deliberately NOT added, preserving the existing 'auditor curates but never drafts' invariant test. Complete-at-propose (report asymmetry), cycle ledger auto-closes, CEO notified link-only. Integrated as a union with Periscope across the shared program surfaces. * feat(panel): Coroner postmortems card Read-only postmortems list under Business → Programs — incident, root cause, failed stage, process change; nothing to approve, the process-change artifact (a draft playbook) rides the existing curation queue. * feat(board): Sentinel — Auditor drift-watch quality reports Weekly org-scoped cycle: a solo Auditor spawn receives a server-assembled drift context (waived-findings trend, open findings by severity, conventions-violation hotspots, top spend — all capped, pure ORM) and files one propose_quality_report: headline, 1-7 area-validated items with evidence and suggested actions, overall assessment. Report semantics — complete-at-propose, cycle auto-closes, CEO notified display-only (never on Telegram's approve/reject surface); items are structured so a later convert-to-task control is cheap. Integration adopts Sentinel's module- level dict-dispatch for board-program routing (xenon-driven), folding all prior programs in; app router mounting extracted to a helper for the same budget. * feat(panel): Quality Reports tab (read-only) Business page gains the Sentinel quality-reports tab — headline, per-area observations with evidence and suggested actions; read-only, a report has nothing to approve. * feat(board): Spackle — gap-fill audit program Biweekly project-scoped PO cycle over the half-shipped surface area: API routes without panel surfaces (and vice versa), armed flags without docs, docs promises the code doesn't keep, dead-end tabs — the inventory diffing is the PO's own read-tool work, ordered by the spawn prompt with file:line citations required; the server injects only prior-cycle LEARN and the rotation target. Rotation is now a shared module-level helper (pick_rotation_target, parameterized by source) both project-scoped engines use — pest_control delegates to it, behavior-identical, with a cross-pollution test proving the two programs' rotations stay independent. propose_gap_fill mirrors the bug-hunt verb (≤5 items, two-sided evidence required, participation gate); per-item CEO decide materializes BACKLOG source=spackle tasks; full Telegram kind incl. approve/reject handlers. All seven program routers now mount from one helper. * feat(panel): Spackle gap-fill review queue Command Center gains the gap-fill queue mirroring the pest-control one — per-item approve/reject with the two-sided gap evidence rendered. * feat(board): Scales — monthly portfolio rebalance Org-scoped PO cycle over the stale backlog: the spawn receives a capped stale-task snapshot (BACKLOG/PENDING unclaimed >30 days) plus the charter and prior-cycle LEARN, and files one propose_rebalance — 1-7 items, each a resolvable task_ref with action reprioritize (validated new priority) or cancel, rationale required. Per-item CEO decide: approve EXECUTES the action (audited priority update, or the normal cancel path) — the first program whose materializer mutates existing tasks instead of creating them; reject records the reason; LEARN by exploration task id; all-terminal completes the cycle. Full Telegram decide-kind wiring. Integrated as the eight-program union (registry, dict dispatch, routers helper, teardown enumerations). * feat(panel): Scales rebalance review queue Command Center gains the rebalance queue — per-item approve/reject with the action, target task, and rationale rendered. * feat(board): Mirror — quarterly positioning audit Project-scoped HoM cycle over messaging surfaces: README claims vs shipped reality, docs-site promises vs code, charter alignment — the audit is the HoM's own read-tool work with citations required; the server injects the charter, prior-cycle LEARN, and the shared rotation target. propose_ messaging_fixes mirrors the gap-fill verb (≤5 items, drift evidence naming claim + contradicting reality, participation gate); per-item CEO decide materializes BACKLOG source=mirror documentation tasks; full Telegram decide-kind wiring. Nine-program union across the shared surfaces. * feat(panel): Mirror messaging-fixes review queue * feat(board): Megaphone — HoM standing editorial calendar Cron cycle (3 days, org-scoped, gated on X credentials — drafting content nobody can post is pointless): the HoM receives a shipped-this-week digest plus Unreleased changelog bullets and files one propose_editorial_post (angle-validated, ≤280, brand voice) that materializes a held x_editorial draft through the SAME X-queue origination chokepoint release posts use — zero new approval surface, notifications and CEO decide for free. Complete-at-propose; cycle auto-closes. Ten-program union. * feat(panel): x_editorial source labels in the X queue surfaces * feat(board): Librarian — proactive playbook mining Biweekly org-scoped Auditor cycle: mines recurring non-private learning journals (≥2-count grouping with a recency fallback) against the existing playbook-title inventory and files one propose_playbook_drafts — 1-3 drafts, each with the repeated-pattern evidence that justifies it, duplicate titles rejected in-batch and against the live store. Drafts are created via PlaybookService directly (the Coroner precedent — the 'auditor curates but never drafts' do-verb invariant stays intact and tested) and land in the normal pending-curation queue the Auditor's own triage already surfaces; no new panel surface. Complete-at-propose; display-only CEO notification. Eleven-program union. * feat(board): War Room — release campaign planning EVENT program with a REAL originator (unlike coroner's stub): a release publish hooks a campaign brief beside the release-post seam, and the CEO's run-now originates on demand — the cron loop never fires it. The HoM designs a 2-6 post arc (teaser → launch → follow-up → spotlight; 280-cap, future strictly-ascending publish_after, stage vocabulary) and one propose_campaign call materializes each post as a held x_campaign draft through the X-queue chokepoint. V1 is manual-cadence by design: publish_ after renders as queue guidance and the CEO approves each post at its moment — nothing auto-posts, ever; the auto-schedule upgrade is a documented ceiling. Twelve-program union: full registry complete. * feat(panel): x_campaign labels + publish-after guidance in the X queue * feat(board): Barfly — adjacent-conversation replies Cron cycle (2 days, org-scoped, X-credentials gated): the engine searches X for conversations where RoboCo is relevant but unmentioned (new OAuth- signed search_recent on the client; queries + candidate cap configurable), screens every fetched tweet through the injection guard (stored unclamped — a clamp was truncating the candidate under the envelope, caught by the dev's own tests), dedupes via the existing x_seen_mentions ledger (no migration; also prevents double-drafting against the mentions poll), and opens one held HoM exploration carrying the screened candidates. propose_ conversation_replies enforces candidate-id-only replies (≤5, 280-cap); each materializes a held x_barfly draft through the X-queue chokepoint, threaded via a new in_reply_to seam on post_tweet that only x_barfly drafts use. The X redraft machinery is now dict-dispatch over per-source extractors with reply-ref carry for x_barfly. Thirteen-program registry. War Room's test fakes gained the new abstract search_recent stub. * feat(board): Dogfood — the PO walks the product The fourteenth and final registry entry, completing the catalog. EVENT program (release-publish hook beside the war-room hook + CEO run-now, both through the same real originator; the cron loop never fires it), project- scoped with shared rotation. The permission surface is the careful part: the PO's dogfood spawn — and ONLY that spawn — gets the Playwright MCP mounted, via a task-scoped fail-closed probe mirroring the video-authoring precedent (a PO spawned for roadmap/pest/scales never sees browser tools; tested both ways); the PM agent image bakes chromium unconditionally like the ux image, the mount stays task-gated in code. The walk targets the rotation target's live surfaces (panel_base_url only when the target is the org's own project, honest degradation otherwise); propose_friction_ fixes files ≤5 walked-path-evidenced items; per-item CEO decide materializes BACKLOG source=dogfood tasks; full Telegram decide kind. Also: megaphone/librarian/war_room arming keys restored to the settings validator — their panel toggles would have been rejected (dropped in earlier unions; the same silent-arming class the drill killed once already). * feat(panel): Dogfood friction review queue * chore(board): final whole-branch sweep fixes The night's closing adversarial pass over the integrated fourteen-program registry found ONE functional defect — the war-room test fakes' post_tweet predated Barfly's in_reply_to_tweet_id kwarg (LSP violation, the only red in an otherwise fully green gate) — plus doc/test drift, all fixed: the source-parity test completes to fourteen (spackle/mirror were silently absent while its neighboring comment claimed full coverage), the PO identity doc gains its missing Dogfood verb, the auditor quick-list gains propose_postmortem, three stale comments corrected (rotation docstring, panel registry header, X source enumerations), the dogfood release-hook gains the exception-swallow test its four sibling hooks already had, and the CHANGELOG's Unreleased section documents the whole Board Programs train. Full make quality: exit 0, all gates green. * docs: full documentation sweep for the Board Programs train CLAUDE.md's roadmap-engine entry superseded by the Board Program registry entry (all fourteen programs, arming, scoping, LEARN, guardrails) with the role verb tables and playwright row refreshed; docs/rag gains the agent- facing architecture doc plus full propose_* call-shape sections in the three board role docs, and corrects the strategy-engine section to shipped reality (only idle→roadmap is wired); docs/map covers the registry + all twelve engines with flags, gotchas, and drift notes. The 0.27.0 reference inventory confirmed only the release-executor's canonical set carries the version — left for the 0.28.0 cut. * feat(board): human titles + descriptions on every program surface Raw registry keys rendered as bare panel labels — an operator reading x_feature had no idea what enabling or running it does. The registry dataclass gains title/description (test-enforced non-empty for every entry, unique titles), the API passes them through, and every surface renders title-with-description-tooltip instead of the key: the Programs card (label, toggle hint, run-now toast), and the project settings participates-in/excluded-from checkboxes. --------- Co-authored-by: Renn F <rennf93@users.noreply.github.com>
This commit is contained in:
Renzo F
@@ -0,0 +1,95 @@
|
||||
# Board Program Registry
|
||||
|
||||
## What It Is
|
||||
|
||||
Fourteen periodic/event-driven origination cycles — the Board actually doing strategic work instead of only reviewing it — ride one generic registry + engine instead of bespoke per-engine loops. `BoardProgram` (`roboco/foundation/policy/board_programs.py`) is a frozen registry entry; `PROGRAMS` holds all fourteen. `BoardProgramEngine` (`roboco/services/board_programs.py`) is the shared trigger/dedup/originate/LEARN machinery every entry rides. Every artifact any program produces is HELD — the CEO is the only path to materialization. Nothing auto-starts, auto-posts, or auto-merges.
|
||||
|
||||
The lifecycle is uniform across every program:
|
||||
|
||||
```
|
||||
TRIGGER → EXPLORE → PROPOSE → DECIDE → MATERIALIZE → LEARN
|
||||
(loop) (solo (one verb (CEO (per-program (outcome fed to
|
||||
spawn, call, queue, materializer) next cycle's
|
||||
read-only held) per-item) exploration prompt)
|
||||
```
|
||||
|
||||
## The fourteen programs
|
||||
|
||||
| Key | Role | Trigger | Scope | Source marker | Proposal verb | Materializer |
|
||||
|-----|------|---------|-------|----------------|----------------|---------------|
|
||||
| `roadmap` (Printer) | product_owner | cron, weekly | org | `board_roadmap` | `propose_roadmap` | backlog tasks, per-item CEO decision |
|
||||
| `pest_control` (Pest Control) | product_owner | cron, weekly + rework-spike metric | project | `board_pest_control` | `propose_bug_hunt` | backlog tasks, per-item CEO decision |
|
||||
| `spackle` (Spackle) | product_owner | cron, biweekly | project | `board_spackle` | `propose_gap_fill` | backlog tasks, per-item CEO decision |
|
||||
| `scales` (Scales) | product_owner | cron, monthly | org | `board_scales` | `propose_rebalance` | mutates a LIVE task in place (reprioritize/cancel) on approval — never creates a task |
|
||||
| `dogfood` (Dogfood) | product_owner | event (release-publish hook or CEO run-now) | project | `board_dogfood` | `propose_friction_fixes` | backlog tasks, per-item CEO decision |
|
||||
| `periscope` (Periscope) | head_marketing | cron, weekly | org | `board_periscope` | `propose_market_brief` | held report only, no task, no per-item decision |
|
||||
| `megaphone` (Megaphone) | head_marketing | cron, every 3 days | org | `board_megaphone` | `propose_editorial_post` | held X draft (existing X queue) |
|
||||
| `mirror` (Mirror) | head_marketing | cron, quarterly | project | `board_mirror` | `propose_messaging_fixes` | backlog docs tasks, per-item CEO decision |
|
||||
| `barfly` (Barfly) | head_marketing | cron, every 2 days | org | `board_barfly` | `propose_conversation_replies` | held X draft per reply (existing X queue) |
|
||||
| `war_room` (War Room) | head_marketing | event (release-publish hook or CEO run-now) | org | `board_war_room` | `propose_campaign` | N held X drafts as one batch (existing X queue) |
|
||||
| `x_feature` (feature spotlight) | head_marketing | cron, default daily | org | `x_feature_exploration` | `propose_feature_spotlight` | held X draft (existing X queue) |
|
||||
| `coroner` (Coroner) | auditor | event only — no cron | org | `board_coroner` | `propose_postmortem` | a held process-change item, or a playbook drafted directly when `process_change.kind='playbook'` |
|
||||
| `librarian` (Librarian) | auditor | cron, biweekly | org | `board_librarian` | `propose_playbook_drafts` | 1-3 DRAFT playbooks via `PlaybookService` directly, into the same curation queue |
|
||||
| `sentinel` (Sentinel) | auditor | cron, weekly | org | `board_sentinel` | `propose_quality_report` | held report only, no task, no per-item decision |
|
||||
|
||||
`roadmap` and `x_feature` predate the registry; migrating them onto it was deliberately behavior-identical (Phase 1). The other twelve are new (Phase 2/3).
|
||||
|
||||
## Enable/Disable — no master flag
|
||||
|
||||
Unlike most feature-flagged subsystems, there is **no `ROBOCO_BOARD_PROGRAMS_ENABLED`**. Every program is armed independently through `program_armed(session, key)` — THE single chokepoint every origination path routes through (the cron loop, the metric-predicate check, the CEO's "run now", the strategy-engine idle trigger). It reads a settings-store row `board_program.{key}.enabled`; only `roadmap` and `x_feature` fall back to a legacy env flag (`ROBOCO_ROADMAP_ENGINE_ENABLED`; `ROBOCO_X_ENGINE_ENABLED` AND `ROBOCO_X_FEATURE_SPOTLIGHT_ENABLED`) when no settings-store row exists yet. Every other program is settings-store-only and defaults **off** — a fresh deployment originates nothing until the CEO flips a toggle on the Board Programs panel page.
|
||||
|
||||
The one env knob among the twelve new programs: `ROBOCO_PEST_REWORK_THRESHOLD` (default `0.3`) — the 7-day rework rate above which Pest Control's metric predicate opens a cycle off-schedule, on top of its own weekly cron. No other new program has a compose-level setting; per-program cadence overrides (when set) also live in the settings store, not env.
|
||||
|
||||
## Scope and dual-polarity project participation
|
||||
|
||||
`projects.board_programs` (migration `088`, nullable jsonb list of strings) governs which projects a program runs against or outputs into:
|
||||
|
||||
- **`scope="project"`** programs (they read one repo: Pest Control, Spackle, Dogfood, Mirror — see the table above) need an **affirmative opt-in**: the plain key (`"pest_control"`) must be present in the list, or the program has no opted-in project and a cycle is never even opened (`_scope_gate`). Null/absent = out.
|
||||
- **`scope="org"`** programs (they read the org's own process or the external market: roadmap, Scales, Periscope, Megaphone, Barfly, War Room, Coroner, Librarian, Sentinel, x_feature) run **org-wide by default** and are excluded per-project only by the opposite-polarity entry: `"!roadmap"` opts a project OUT of that program's output. Null/absent = in.
|
||||
|
||||
One pure helper, `project_participates(program, board_programs_field)`, implements both polarities; `validate_board_programs_field` rejects an unknown key, a meaningless `"!"` on a project-scoped key, or a meaningless plain key on an org-scoped key. Panel: the project settings page's budget/ops card renders project-scoped programs as "participates in" checkboxes and org-scoped programs as "excluded from" checkboxes.
|
||||
|
||||
## The engine mechanics
|
||||
|
||||
`BoardProgramEngine.run_due_programs` (called by the orchestrator's `_board_program_loop` on a floor interval — the shortest registered cadence, clamped 300s-3600s) walks every CRON program: enabled → scope-gated → dedup-checked against the `board_program_cycles` ledger (migration `087`; one row per cycle, `closed_at IS NULL` = open, auto-closed the moment its exploration task goes terminal) → cron-due (`program_due`) → originate via the program's `_ORIGINATORS` callable (each program's own engine's `run_cycle`, e.g. `PestControlEngine.run_cycle`) → record the cycle row. It then separately runs every registered metric predicate (`_METRIC_PREDICATES`, today only Pest Control's rework-spike check) — cheap gates (scope, dedup) run BEFORE the predicate itself, so a multi-query metric check never runs on a tick that was always going to be rejected.
|
||||
|
||||
`open_program_cycle(key)` is the same enabled+scope+dedup path minus the cron-due check — the seam the CEO's panel "run now" button and the Strategy Engine's `idle` trigger both use (`docs/rag/architecture/company-layer.md`). **Only Printer is wired to the strategy-engine idle trigger** — the design intent to also trigger Coroner off `stranded_blocked` was not built; Coroner is event-only, triggered exclusively by its own three hooks (see below).
|
||||
|
||||
Every exploration is a **solo one-shot spawn** — the board dispatcher's `_dispatch_board_program_exploration` (a dict-dispatch table keyed by `task['source']`) routes it to a dedicated one-shot dispatcher (e.g. `_dispatch_pest_control_exploration`) that bypasses the two-reviewer board-review gate (`_handle_board_assigned_task`) entirely — a program cycle has exactly one author, never a PO+HoM pair. Every dispatcher reuses the `_board_dispatched` one-shot tracker + respawn breaker. Every program source is in the dispatchers' skip bucket (`_is_non_dev_dispatch_source`) — a program exploration task is never mistaken for delivery work.
|
||||
|
||||
### Coroner's event hooks
|
||||
|
||||
Coroner is the one program with `trigger=event` AND a real trigger wired outside the loop (unlike `war_room`, whose event trigger IS also reachable through `open_program_cycle` for a CEO on-demand run — Coroner has no on-demand path, only incidents). Three chokepoints call `CoronerEngine.open_for_incident(task_id, kind=...)` directly:
|
||||
|
||||
- `TaskService`'s bounce transition — a task crossing into `needs_revision` for the 3rd+ time (`revision_count >= 3`), `kind="bounced"`.
|
||||
- `TaskService`'s cancel path — a task cancelled after real work had started, `kind="cancelled"`.
|
||||
- The orchestrator's budget-block path — a task blocked on a budget breach, `kind="budget"`.
|
||||
|
||||
Only one autopsy is open at a time (the same `board_program_cycles` dedup every cron program uses); a second incident firing while one is open waits.
|
||||
|
||||
### War Room and Dogfood's release hooks
|
||||
|
||||
`WarRoomEngine.open_for_release(...)` and the release-publish path both bypass `_ORIGINATORS` entirely and open a cycle directly, mirroring Coroner's `open_for_incident` shape — War Room's release brief carries the version + curated highlights so posts never invent a feature; a CEO on-demand run (blank brief) instead rides the ordinary `open_program_cycle("war_room")` path. Dogfood similarly has a real `_ORIGINATORS["dogfood"]` binding (unlike Coroner's always-`None` stub) — a walk needs no external incident id, just the next opted-in project in rotation, so both the release-publish hook and a CEO "run now" open a cycle through the ordinary path.
|
||||
|
||||
### Rotation for project-scoped programs
|
||||
|
||||
Pest Control, Spackle, Mirror, and Dogfood share one round-robin picker, `pick_rotation_target`: among a program's opted-in projects, never-explored beats explored, else the oldest `last_opened_at` wins (read from the programs' own exploration tasks, not the LEARN ledger — a project-scoped program can run its engine's `run_cycle` directly, outside `BoardProgramEngine`, so the ledger alone would be blind to some cycles).
|
||||
|
||||
## LEARN
|
||||
|
||||
`BoardProgramEngine.record_decision(program_key, item_ref, verdict, reason, exploration_task_id=...)` accrues one CEO approve/reject onto the cycle row's `decisions` jsonb column, incrementing `items_proposed`/`items_approved`/`items_rejected`. `prior_cycle_context(program_key, limit=2)` renders the last two CLOSED cycles ("proposed N, approved N; rejected: item — reason") for injection into the NEXT cycle's exploration prompt — every producer of a per-item decision (`RoadmapService`, `PestControlService`-equivalent per-program services) calls this, so a program stops re-proposing something the CEO already rejected without explanation. This is the one genuinely new pipeline stage the registry introduced; the pre-registry roadmap/spotlight engines had no memory of prior outcomes at all.
|
||||
|
||||
## Panel and API
|
||||
|
||||
`GET /api/board-programs` and `POST /api/board-programs/{key}/run-now` (`roboco/api/routes/board_programs.py`, CEO-only, `require_ceo_role`) back the Board Programs page (Business section, `board-programs-card.tsx`): each program's live enablement, trigger kind, scope, opted-in project slugs, last-run timestamp, whether a cycle is currently open, and the most recent closed cycle's summary — plus a `Switch` that writes `board_program.{key}.enabled` through the generic feature-flag settings endpoint and a "Run now" button (disabled while a cycle is already open) that calls `open_program_cycle` off-schedule. `run-now` 404s on an unregistered key and 409s when the program is disabled, already has an open cycle, or (a project-scoped program) has no opted-in project — the three collapse into one `None` result with no finer-grained distinction available to the caller.
|
||||
|
||||
Per-program held artifacts reuse existing queues where the shape matches — the roadmap review queue, the X post queue (Megaphone/Barfly/War Room/spotlight all land there) — rather than growing a new panel surface per program; reports (Periscope, Sentinel) and process-change items (Coroner) and the playbook curation queue (Librarian) are the only genuinely distinct surfaces.
|
||||
|
||||
## Related
|
||||
|
||||
- CLAUDE.md's "Board Program registry" entry — the condensed architectural summary.
|
||||
- `docs/rag/architecture/company-layer.md` — the Strategy Engine's `idle` → Printer trigger.
|
||||
- `docs/rag/architecture/x-engine.md` — the X held-draft queue every X-bound program (Megaphone/Barfly/War Room/spotlight) materializes into.
|
||||
- `docs/rag/architecture/review-findings.md` — the findings ledger Pest Control reads.
|
||||
- `docs/rag/roles/auditor.md` — the playbook curation queue (`approve_playbook`/`reject_playbook`/`archive_playbook`) Coroner and Librarian both feed.
|
||||
- `docs/rag/roles/product-owner.md` / `docs/rag/roles/head-marketing.md` / `docs/rag/roles/auditor.md` — each role's exact `propose_*` call shape and when it fires.
|
||||
@@ -1,6 +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); research and provisioning ship default-**on** (but degrade gracefully until configured), while the strategy engine and the roadmap engine 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); research and provisioning ship default-**on** (but degrade gracefully until configured), while the strategy engine and every Board Program are **opt-in and default-off** — the org runs fine without any of them.
|
||||
|
||||
## The Charter (Company Goals)
|
||||
|
||||
@@ -34,22 +34,25 @@ When a pitch is approved and **provisioning is enabled** (`ROBOCO_PROVISIONING_E
|
||||
|
||||
## 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`). Mostly it only **observes and surfaces**, but `idle` is now also a Board Program trigger: `run_cycle` calls `BoardProgramEngine.open_program_cycle("roadmap")` (enabled + dedup checked there, so a still-open cycle is a harmless no-op) and folds the outcome into the CEO notification instead of only describing the drift. `stranded_blocked` stays notify-only — Coroner is triggered by its own dedicated event hooks (a bounce past `revision_count>=3`, a cancel-after-work-started, or a budget block; see `docs/rag/architecture/board-programs.md`), not by this engine.
|
||||
|
||||
Those observations are the "needs your attention" signals shown on the Dashboard, served by `GET /api/cockpit/signals`.
|
||||
|
||||
## Board Roadmap Engine
|
||||
## Board Program Registry (Printer and thirteen siblings)
|
||||
|
||||
The **roadmap engine** (`ROBOCO_ROADMAP_ENGINE_ENABLED`, default off) is a weekly counterpart to the pitch pipeline: instead of a one-off product proposal, the Product Owner explores the company's projects, charter, recent releases, and metrics, then proposes one themed **cycle** of 3-7 roadmap item drafts.
|
||||
The **roadmap engine** described here is now `roadmap` ("Printer") — one entry in a fourteen-program registry (`roboco/foundation/policy/board_programs.py`) that also covers Pest Control, Spackle, Scales, Dogfood (Product Owner), Periscope, Megaphone, Mirror, Barfly, War Room, x_feature spotlight (Head of Marketing), and Coroner, Librarian, Sentinel (Auditor). See `docs/rag/architecture/board-programs.md` for the full catalog and each program's exact verb call shape; this section keeps Printer's own mechanics as the worked example, since every cron/metric program follows the identical shape.
|
||||
|
||||
Printer is a weekly counterpart to the pitch pipeline: instead of a one-off product proposal, the Product Owner explores the company's projects, charter, recent releases, and metrics, then proposes one themed **cycle** of 3-7 roadmap item drafts.
|
||||
|
||||
Mechanically it mirrors the release manager's "detect → originate a CEO-gated artifact → hold" shape:
|
||||
|
||||
1. Weekly, `RoadmapEngine.run_cycle()` opens ONE held, PENDING exploration task assigned to the Product Owner (`source=board_roadmap`, `confirmed_by_human=False`) — only when no cycle is already open.
|
||||
1. Weekly (or off-schedule — see the Strategy Engine's `idle` trigger below), `BoardProgramEngine` opens ONE held, PENDING exploration task assigned to the Product Owner (`source=board_roadmap`, `confirmed_by_human=False`) via `RoadmapEngine.run_cycle()` — only when no cycle is already open (`board_program_cycles` dedup ledger).
|
||||
2. The board dispatcher one-shot-spawns the Product Owner for it, who explores and calls `propose_roadmap(cycle_goal, items)` **exactly once**, persisting the goal + item drafts as a marker on the task (no dedicated table).
|
||||
3. The CEO reviews the authored cycle in the roadmap queue and approves or rejects each item **individually** (`GET /api/roadmap/cycles`, `POST /api/roadmap/cycles/{task_id}/items/{item_id}/{approve,reject}`, CEO-only).
|
||||
4. An approved item materializes as a real BACKLOG task (`source=roadmap`) via the same `create_task_from_draft` path pitches use — nothing here auto-starts it; normal PM activation takes it from there. The exploration task itself completes once every item is terminal (approved or rejected).
|
||||
5. The CEO's per-item decisions accrue onto the cycle's LEARN ledger row (`board_program_cycles.decisions`) and feed forward into the NEXT roadmap-exploration prompt ("last cycle you proposed X, the CEO rejected it because Y") — Printer is no longer amnesiac.
|
||||
|
||||
Like every company-layer engine, it never authors work outside this held/approved chain, and it never starts anything itself.
|
||||
Like every Board Program, it never authors work outside this held/approved chain, and it never starts anything itself.
|
||||
|
||||
## The Secretary
|
||||
|
||||
@@ -62,6 +65,6 @@ The CEO's chief-of-staff reads this layer (`read_company_state` returns the char
|
||||
| `ROBOCO_RESEARCH_ENABLED` | **on** | Board / PM web research |
|
||||
| `ROBOCO_STRATEGY_ENGINE_ENABLED` | off | The strategy watcher loop |
|
||||
| `ROBOCO_PROVISIONING_ENABLED` | on (inert without a token/org) | Pitch → auto-provisioned repos |
|
||||
| `ROBOCO_ROADMAP_ENGINE_ENABLED` | off | The weekly board roadmap engine above |
|
||||
| `ROBOCO_ROADMAP_ENGINE_ENABLED` | off | Legacy alias arming Printer only — every other Board Program is settings-store-only, no env flag (see `docs/rag/architecture/board-programs.md`) |
|
||||
|
||||
With every toggle off, the company layer is just the charter plus the pitch record — research and provisioning ship on by default but degrade gracefully (no key/token configured) rather than doing anything until set up.
|
||||
|
||||
@@ -89,7 +89,7 @@ The PR-gate turn cut (when every child of an assembled parent is terminal, `_try
|
||||
| `ROBOCO_NOTIFICATION_SPAWN_COOLDOWN_SECONDS` | `600` | Cross-tick damper for notification-triggered spawns (escalation/approval/audit/a2a — task-less, so the readiness gate and respawn breaker never see them): one spawn per (agent, notification) per window; the notification stays pending so the next window retries. `0` = legacy every-tick respawn. |
|
||||
| `ROBOCO_SANDBOX_DB_ENABLED` | `false` | Sandboxed per-agent-spawn test DB/Redis/Mongo: throwaway sibling containers provisioned from the engine registry in `roboco/models/sandbox.py` (postgres:16-alpine / redis:8-alpine / mongo:8), per-project opt-in. The valid-service set is `VALID_SANDBOX_SERVICES` (registry-derived). See "Sandboxed Dev DB/Redis/Mongo" below and `docs/rag/architecture/sandbox-db.md`. |
|
||||
| `ROBOCO_X_ENGINE_ENABLED` | `false` | The X (Twitter) engine: draft release/mention posts, ALL held for per-post CEO approval. See "X (Twitter) Engine" below and `docs/rag/architecture/x-engine.md`. |
|
||||
| `ROBOCO_ROADMAP_ENGINE_ENABLED` | `false` | The board roadmap engine: weekly Product-Owner-authored cycle, CEO approves each item individually into BACKLOG. See "Board Roadmap Engine" below. |
|
||||
| `ROBOCO_ROADMAP_ENGINE_ENABLED` | `false` | Legacy alias for the `roadmap` Board Program (Printer): weekly Product-Owner-authored cycle, CEO approves each item individually into BACKLOG. See "Board Program Registry" below and `docs/rag/architecture/board-programs.md`. |
|
||||
| `ROBOCO_OBSIDIAN_VAULT_ENABLED` | `false` (both compose files set `true`) | The Obsidian vault projection: tasks/journals/A2A become wikilinked markdown, rebuildable from the DB. See `docs/rag/architecture/obsidian-vault.md`. |
|
||||
| `ROBOCO_VAULT_INTAKE_ENABLED` | `false` (both compose files set `true`) | The vault's `#roboco`-tag inbox watcher — requires `ROBOCO_OBSIDIAN_VAULT_ENABLED` also on. See `docs/rag/architecture/obsidian-vault.md`. |
|
||||
| `ROBOCO_VAULT_ARCHIVE_DAYS` | `30` (`0` disables) | Age (past its terminal timestamp) a completed/cancelled task's note must reach before the vault janitor moves it to `RoboCo/Archive/<year>/`. |
|
||||
@@ -176,18 +176,21 @@ Drafts release-announcement and mention-reply posts, ALL held for per-post CEO a
|
||||
| `ROBOCO_X_ACCOUNT_USER_ID` | (empty) | Numeric X user id of the account's own account. Empty resolves it once per mentions cycle via `GET /2/users/me` (one extra call). |
|
||||
| `ROBOCO_X_REQUEST_TIMEOUT_SECONDS` | `15.0` | Per-request timeout for outbound X API HTTP calls. |
|
||||
|
||||
## Board Roadmap Engine
|
||||
## Board Program Registry
|
||||
|
||||
Weekly, the Product Owner explores the company's projects and proposes a themed cycle of roadmap item drafts; the CEO approves or rejects each one individually. Default-off; approved items land in BACKLOG and nothing auto-starts. See `docs/rag/architecture/company-layer.md`.
|
||||
Fourteen registered programs (Printer/roadmap, feature-spotlight, and twelve new ones across Product Owner / Head of Marketing / Auditor) ride one generic registry + engine instead of bespoke per-engine loops. Every artifact is HELD; the CEO is the only path to materialization. See `docs/rag/architecture/board-programs.md` for the full lifecycle, the fourteen-program catalog, and each role's exact `propose_*` call shape.
|
||||
|
||||
**Arming has no master flag.** Each program is armed independently through a settings-store row (`board_program.{key}.enabled`, toggled from the panel's Board Programs page, Business section) — `roadmap` and `x_feature` additionally accept their pre-existing legacy env flags as a fallback when no settings-store row exists yet (byte-for-byte migration); every other program is settings-store-only and defaults OFF.
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `ROBOCO_ROADMAP_ENGINE_ENABLED` | `false` | Master switch. Off = no exploration cycle is originated and the Product Owner is never spawned for this. |
|
||||
| `ROBOCO_ROADMAP_INTERVAL_SECONDS` | `604800` | Seconds between roadmap-exploration cycles (default weekly). |
|
||||
| `ROBOCO_ROADMAP_ENGINE_ENABLED` | `false` | Legacy fallback for the `roadmap` program only (see above). |
|
||||
| `ROBOCO_ROADMAP_INTERVAL_SECONDS` | `604800` | Seconds between roadmap-exploration cycles (default weekly) when no settings-store interval override is set. |
|
||||
| `ROBOCO_ROADMAP_MIN_ITEMS_PER_CYCLE` | `3` | Minimum roadmap item drafts a themed cycle must propose. |
|
||||
| `ROBOCO_ROADMAP_MAX_ITEMS_PER_CYCLE` | `7` | Maximum roadmap item drafts a themed cycle may propose. |
|
||||
| `ROBOCO_PEST_REWORK_THRESHOLD` | `0.3` | The one compose-settable knob among the twelve new programs: the 7-day rework rate above which Pest Control's metric predicate opens a cycle off-schedule, on top of its weekly cron. Every other new program has no env knob at all — cadence overrides, when set, also live in the settings store. |
|
||||
|
||||
No dedicated migration — a cycle is marker-backed (`orchestration_markers` on the held exploration task), not a new table.
|
||||
No dedicated migration for a cycle's own payload — a cycle is marker-backed (`orchestration_markers` on the held exploration task) for every program, not a new table per program. The shared LEARN ledger (`board_program_cycles`, migration `087`) and the per-project scoping column (`projects.board_programs`, migration `088`) are the only new tables/columns.
|
||||
|
||||
## Possibilities Matrix
|
||||
|
||||
|
||||
@@ -46,6 +46,7 @@ You still cannot claim tasks, initiate a message to a peer agent, or write code
|
||||
- Curate the KB's playbook queue via `approve_playbook` / `reject_playbook` / `archive_playbook` — a deliberate, bounded expansion of your read-only surface (KB curation, not agent-initiated comms)
|
||||
- Read `dm`s and reply in-thread when the CEO opens a DM with you (`read_a2a` / `dm`) — reachable mid-task if you're stuck, but you still never *initiate* to a peer agent
|
||||
- Curate the Obsidian vault's narrative for a just-completed root task-tree via `curate_vault(task_id, narrative)` — see below (only when `ROBOCO_OBSIDIAN_VAULT_ENABLED`)
|
||||
- Author three Board Program exploration cycles, each its own periodic/event spawn: `propose_postmortem(...)` (Coroner, event-only), `propose_playbook_drafts(drafts)` (Librarian, the one exception to "you curate but don't draft"), `propose_quality_report(headline, items, overall_assessment)` (Sentinel) — see "Board Programs" below
|
||||
|
||||
## What You CANNOT Do
|
||||
|
||||
@@ -97,6 +98,70 @@ note(
|
||||
evidence(task_id="...") # attach the evidence trail to the finding
|
||||
```
|
||||
|
||||
## Board Programs
|
||||
|
||||
Three of your spawns ride the generic Board Program registry (`docs/rag/architecture/board-programs.md`) — one settings-store toggle per program (`board_program.{key}.enabled`, no master flag). Unlike the Product Owner/Head of Marketing programs, none of these puts an item in a per-item CEO decision queue — each completes its own exploration task in the same call it proposes in.
|
||||
|
||||
### Coroner (Postmortems)
|
||||
|
||||
Event-triggered ONLY — no cron. An incident already happened by the time you're spawned: a task bounced into `needs_revision` 3+ times, was cancelled after work had started, or was blocked on a budget breach (the incident id is named in your task prompt). You are alone here — autopsy, not review.
|
||||
|
||||
```python
|
||||
propose_postmortem(
|
||||
incident_summary="...",
|
||||
root_cause="...",
|
||||
failed_stage="awaiting_qa", # a real task-lifecycle status
|
||||
process_change={
|
||||
"kind": "playbook", # playbook | prompt_fix | conventions_rule | other
|
||||
"description": "...",
|
||||
},
|
||||
playbook={"title": "...", "body": "..."}, # REQUIRED iff kind == "playbook"
|
||||
)
|
||||
```
|
||||
|
||||
Propose the ONE smallest change that would have caught or prevented this, not a wishlist. A `kind='playbook'` change drafts immediately into the pending-playbook curation queue — the same queue any delivery role's `draft_playbook` feeds; you do not self-approve it in this call. `i_am_idle()` completes the autopsy task immediately — unlike Pest Control/Spackle, there is no further per-item decision to leave open.
|
||||
|
||||
### Librarian (Proactive Playbook Mining)
|
||||
|
||||
Biweekly cron, org-scoped. Playbook curation is otherwise reactive — you only judge what delivery roles happen to draft with `draft_playbook`, which you do NOT carry. This is the proactive half: mine journals/learnings org-wide for a repeated pattern nobody has turned into a playbook yet, and draft it yourself.
|
||||
|
||||
```python
|
||||
propose_playbook_drafts(
|
||||
drafts=[
|
||||
{
|
||||
"title": "...", # <=200 chars, must not duplicate an existing playbook (case-insensitive)
|
||||
"body": "...", # <=4000 chars, the procedure itself
|
||||
"pattern_evidence": "...", # REQUIRED, <=500 chars — which repeated journal/learning pattern justifies this
|
||||
},
|
||||
# 1-3 drafts
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
Each draft is created immediately as a real DRAFT playbook via `PlaybookService` directly — never through `draft_playbook` — landing in the SAME curation queue a LATER Auditor spawn (you, another day) reviews with `approve_playbook`/`reject_playbook`. You never self-approve in this call. `i_am_idle()` next.
|
||||
|
||||
### Sentinel (Drift Watch)
|
||||
|
||||
Weekly cron, org-scoped. An org-wide "state of quality" report — waiver-accumulation trends, conventions-violation hotspots, budget anomalies. The task prompt server-assembles the evidence (waived-findings trend, open-findings-by-severity, conventions hotspots, top spend) for you.
|
||||
|
||||
```python
|
||||
propose_quality_report(
|
||||
headline="one-line summary of the cycle's biggest quality signal, <=200 chars",
|
||||
items=[
|
||||
{
|
||||
"area": "waivers", # waivers | findings | conventions | budget | docs | other
|
||||
"observation": "...",
|
||||
"evidence": "the ledger row / metric / file that backs it",
|
||||
"suggested_action": "...",
|
||||
},
|
||||
# 1-7 items
|
||||
],
|
||||
overall_assessment="synthesis across all items, <=800 chars",
|
||||
)
|
||||
```
|
||||
|
||||
Completes your exploration task in the same call — a report, not a task queue. `i_am_idle()` next.
|
||||
|
||||
## Vault curation
|
||||
|
||||
When the Obsidian vault is armed, the orchestrator spawns you once per completed ROOT task (a one-shot, not something you poll for) with the task id and title named in your prompt. Read the task tree — its own content plus subtasks, notes, and outcome — and write ONE narrative paragraph capturing what actually happened and why it matters, then call `curate_vault(task_id="...", narrative="...")` exactly once. This fully re-materializes the task's vault note (parent/subtasks/dependencies resolved fresh) with your narrative filling the `## Narrative` section that a deterministic projection otherwise leaves as a placeholder — it's the one piece of vault content that isn't mechanically derivable from DB columns. The write is idempotent; a retry just re-materializes the same note.
|
||||
@@ -106,7 +171,7 @@ When the Obsidian vault is armed, the orchestrator spawns you once per completed
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `waive_finding`, `i_am_idle` |
|
||||
| `roboco-do` | `note` (scope=`reflect`), `evidence`, `notify_list`, `notify_get`, `approve_playbook`, `reject_playbook`, `archive_playbook`, `curate_vault` |
|
||||
| `roboco-do` | `note` (scope=`reflect`), `evidence`, `notify_list`, `notify_get`, `approve_playbook`, `reject_playbook`, `archive_playbook`, `curate_vault`, `propose_postmortem`, `propose_playbook_drafts`, `propose_quality_report` |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
|
||||
|
||||
|
||||
@@ -20,6 +20,7 @@
|
||||
- Communicate: `dm` (A2A), `notify` (ack-required signal)
|
||||
- Propose a product via `pitch(title, slug, problem, proposed_solution, target_cells)` — queues for CEO approval, then auto-provisions
|
||||
- Propose a feature spotlight via `propose_feature_spotlight(feature_slug, feature_title, body)` — periodic, one per exploration cycle, held for CEO approval in the X post queue
|
||||
- Author five more Board Program exploration cycles, each its own periodic/event spawn: `propose_market_brief(headline, findings, ...)` (Periscope), `propose_editorial_post(angle, body, rationale)` (Megaphone), `propose_messaging_fixes(items)` (Mirror), `propose_campaign(campaign_name, posts)` (War Room), `propose_conversation_replies(items)` (Barfly) — see "Board Programs" below
|
||||
- Read project docs via `roboco_docs_read` / `roboco_docs_list`
|
||||
- Research the market via `web_search` / `web_fetch` (when `ROBOCO_RESEARCH_ENABLED`)
|
||||
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
|
||||
@@ -37,13 +38,17 @@
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `escalate_to_ceo`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `pitch`, `dm`, `notify`, `evidence`, `propose_feature_spotlight` |
|
||||
| `roboco-do` | `note`, `pitch`, `dm`, `notify`, `evidence`, `propose_feature_spotlight`, `propose_market_brief`, `propose_messaging_fixes`, `propose_editorial_post`, `propose_campaign`, `propose_conversation_replies` |
|
||||
| `roboco-docs` | `roboco_docs_read`, `roboco_docs_list` |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
| `roboco-search` | `web_search`, `web_fetch` (only when `ROBOCO_RESEARCH_ENABLED`) |
|
||||
| `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. You still don't get the Product Owner's `propose_roadmap` — that stays Product-Owner-only — but you do get your own equivalent: `propose_feature_spotlight`, covered below.
|
||||
Your flow surface is deliberately narrow: the Board steers and approves, it does not claim, create, or complete tasks. You still don't get the Product Owner's `propose_roadmap`/`propose_bug_hunt`/`propose_gap_fill`/`propose_rebalance`/`propose_friction_fixes` — those stay Product-Owner-only — but you carry your own five-plus-spotlight equivalents, covered below.
|
||||
|
||||
## Board Programs
|
||||
|
||||
Six of your exploration cycles ride the generic Board Program registry (`docs/rag/architecture/board-programs.md`) — one settings-store toggle per program (`board_program.{key}.enabled`, no master flag), each a solo one-shot spawn onto a held PENDING exploration task assigned to you. Each fires ONE proposal verb exactly once, then `i_am_idle()`.
|
||||
|
||||
## X (Twitter) Engine — Release Posts, Mentions, and Your Feature-Spotlight Cycle
|
||||
|
||||
@@ -51,7 +56,98 @@ The X engine (`ROBOCO_X_ENGINE_ENABLED`, default off) posts on the company's X a
|
||||
|
||||
Release-announcement and mention-reply posts are still not a tool call and still don't spawn you: `XEngine` (`roboco/services/x_engine.py`) drafts them directly via a local-model call, not by spawning you as an agent. Every one of these drafts lands as a held task **owned by the Secretary** (`assigned_to=secretary-1`, `team=main_pm`), never assigned to you. The CEO reviews and approves/rejects each in the panel (`GET/POST /api/x/posts{,/{id}/approve,/reject}`, CEO-only) — nothing posts without that explicit per-post approval. If you want to influence one of these drafts, raise it through the escalation chain below rather than expecting it in your queue.
|
||||
|
||||
Feature spotlights are different: they **are** a real tool call and they **do** spawn you. Gated by a second, independent switch (`ROBOCO_X_FEATURE_SPOTLIGHT_ENABLED`, also default off), the engine periodically opens a held `x_feature_exploration` task assigned to you — the one case where the X engine puts something in your own queue. When you're spawned on it, investigate what RoboCo has actually shipped (CHANGELOG.md, the feature-flags ledger, docs/map/, the company charter, the knowledge base), pick ONE under-publicized, currently-real capability not already in the task's seen-features list, and call `propose_feature_spotlight(feature_slug, feature_title, body)` **exactly once** — it drafts a held X post the same way the release/mention path does, then completes your exploration task. Call `i_am_idle()` next. The CEO reviews, edits, approves, or rejects the draft from the same X post queue — you never post anything yourself.
|
||||
Feature spotlights are different: they **are** a real tool call and they **do** spawn you. Gated by a second, independent switch (`ROBOCO_X_FEATURE_SPOTLIGHT_ENABLED`, also default off — now also the `x_feature` entry in the Board Program registry, same `board_program.x_feature.enabled` chokepoint), the engine periodically opens a held `x_feature_exploration` task assigned to you — the one case where the X engine puts something in your own queue. When you're spawned on it, investigate what RoboCo has actually shipped (CHANGELOG.md, the feature-flags ledger, docs/map/, the company charter, the knowledge base), pick ONE under-publicized, currently-real capability not already in the task's seen-features list, and call `propose_feature_spotlight(feature_slug, feature_title, body)` **exactly once** — it drafts a held X post the same way the release/mention path does, then completes your exploration task. Call `i_am_idle()` next. The CEO reviews, edits, approves, or rejects the draft from the same X post queue — you never post anything yourself.
|
||||
|
||||
## Periscope (Market Research Briefs)
|
||||
|
||||
Weekly cron, org-scoped (no per-project opt-in — it researches the outside market, not a repo). Research competitors, adjacent-tool releases, and positioning shifts; every claim you act on needs a real citation.
|
||||
|
||||
```python
|
||||
propose_market_brief(
|
||||
headline="One-line summary of the cycle's biggest signal",
|
||||
findings=[
|
||||
{"claim": "...", "source_url": "https://...", "relevance": "..."},
|
||||
# 1-7 findings, source_url REQUIRED per finding — an uncited claim is rejected
|
||||
],
|
||||
threats=["..."], # optional, up to 5
|
||||
opportunities=["..."], # optional, up to 5
|
||||
positioning_note="...", # optional
|
||||
)
|
||||
```
|
||||
|
||||
This completes your exploration task in the same call — no per-item CEO decision, unlike a roadmap/pest-control cycle. The CEO reads it as a report in the panel; your brief also feeds forward as the Product Owner's cross-role input into the next Printer (roadmap) cycle. `i_am_idle()` next.
|
||||
|
||||
## Megaphone (Editorial Calendar)
|
||||
|
||||
Cron every 3 days, org-scoped. The standing editorial calendar beyond release posts and feature spotlights: a dev-log thread on what the fleet shipped this week, a behind-the-scenes note, or a changelog highlight. The task prompt server-assembles a shipped-this-week digest (completed tasks + the CHANGELOG.md Unreleased section) for you.
|
||||
|
||||
```python
|
||||
propose_editorial_post(
|
||||
angle="dev_log", # dev_log | behind_scenes | changelog_highlight | other
|
||||
body="the post itself, your voice, plain text, max 280 chars",
|
||||
rationale="why this angle, this cycle",
|
||||
)
|
||||
```
|
||||
|
||||
Lands in the SAME X post queue release/spotlight drafts do — no separate approval surface. `i_am_idle()` next.
|
||||
|
||||
## Mirror (Positioning Audits)
|
||||
|
||||
Quarterly cron, project-scoped (`projects.board_programs` contains `"mirror"`). Distinct from Periscope: Mirror looks inward — the gap between what your own README/docs-site/website claim and what the product actually ships.
|
||||
|
||||
```python
|
||||
propose_messaging_fixes(
|
||||
items=[
|
||||
{
|
||||
"title": "...", "description": "...", "acceptance_criteria": ["..."],
|
||||
"project_slug": "roboco-website", "team": "backend", "priority": 2,
|
||||
"evidence": "BOTH the drifted claim and the reality it contradicts — REQUIRED",
|
||||
},
|
||||
# 1-5 items
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
An approved item materializes as a real docs BACKLOG task, same per-item CEO decision as roadmap.
|
||||
|
||||
## War Room (Campaign Planning)
|
||||
|
||||
Event-triggered — a release-publish hook (highlights pre-curated, ground every post in them) or the CEO's on-demand "run now" (a blank brief; investigate CHANGELOG.md/feature-flags/docs/map/KB yourself). Org-scoped. Design an ordered arc of 2-6 posts (teaser → launch → follow-up → optional spotlight); drop any stage that doesn't earn its place.
|
||||
|
||||
```python
|
||||
propose_campaign(
|
||||
campaign_name="...",
|
||||
posts=[
|
||||
{
|
||||
"body": "...", # <=280 chars, your voice
|
||||
"publish_after": "2026-08-01T09:00:00Z", # ISO 8601, STRICTLY ascending across posts
|
||||
"stage_label": "teaser", # teaser | launch | follow_up | spotlight | other
|
||||
},
|
||||
# 2-6 ordered posts
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
Materializes every post as a held draft in the X post queue and completes your planning task in the same call. **`publish_after` is guidance only** — V1 is manual-cadence; nothing auto-posts once the timestamp passes. The CEO reviews/edits/approves/rejects each post individually.
|
||||
|
||||
## Barfly (Conversation Replies)
|
||||
|
||||
Cron every 2 days, org-scoped. The task carries a set of SCREENED candidate X conversations (X posts where RoboCo is relevant but unmentioned — keyword/topic search, not the mentions timeline; run through `injection_guard.screen_external_text` before you ever see them). You may reply ONLY to a candidate already on that list.
|
||||
|
||||
```python
|
||||
propose_conversation_replies(
|
||||
items=[
|
||||
{
|
||||
"tweet_id": "...", # REQUIRED — must be one of the candidate ids verbatim
|
||||
"reply_body": "...", # your voice, <=280 chars, no invented facts
|
||||
"rationale": "why this conversation is worth replying to", # REQUIRED
|
||||
},
|
||||
# up to 5 items
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
Each reply materializes its own held draft in the existing X post queue — the CEO reviews each individually.
|
||||
|
||||
## Escalation
|
||||
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
- Communicate: `dm` (A2A), `notify` (ack-required signal)
|
||||
- Propose a product via `pitch(title, slug, problem, proposed_solution, target_cells)` — queues for CEO approval, then auto-provisions
|
||||
- Author the weekly roadmap-engine exploration cycle via `propose_roadmap(cycle_goal, items)` — see "Roadmap Engine" below
|
||||
- Author four more Board Program exploration cycles, each its own periodic/event spawn: `propose_bug_hunt(items)` (Pest Control), `propose_gap_fill(items)` (Spackle), `propose_rebalance(items)` (Scales), `propose_friction_fixes(items)` (Dogfood, with a task-scoped Playwright grant) — see "Board Programs" below
|
||||
- Read project docs via `roboco_docs_read` / `roboco_docs_list`
|
||||
- Research the market via `web_search` / `web_fetch` (when `ROBOCO_RESEARCH_ENABLED`)
|
||||
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
|
||||
@@ -38,17 +39,22 @@
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `escalate_to_ceo`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `pitch`, `propose_roadmap`, `dm`, `notify`, `evidence` |
|
||||
| `roboco-do` | `note`, `pitch`, `propose_roadmap`, `propose_bug_hunt`, `propose_gap_fill`, `propose_rebalance`, `propose_friction_fixes`, `dm`, `notify`, `evidence` |
|
||||
| `roboco-docs` | `roboco_docs_read`, `roboco_docs_list` |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
| `roboco-search` | `web_search`, `web_fetch` (only when `ROBOCO_RESEARCH_ENABLED`) |
|
||||
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
|
||||
| `playwright` | Browser tools — mounted ONLY for a `board_dogfood` spawn (task-scoped, not a blanket grant); see "Dogfood" below |
|
||||
|
||||
Your flow surface is deliberately narrow: the Board steers and approves, it does not claim, create, or complete tasks. `propose_roadmap` is a content verb, not a flow verb — you author the roadmap cycle without claiming a delivery task.
|
||||
Your flow surface is deliberately narrow: the Board steers and approves, it does not claim, create, or complete tasks. `propose_roadmap`/`propose_bug_hunt`/`propose_gap_fill`/`propose_rebalance`/`propose_friction_fixes` are content verbs, not flow verbs — you author each cycle without claiming a delivery task.
|
||||
|
||||
## Board Programs
|
||||
|
||||
Five of your exploration cycles ride the generic Board Program registry (`docs/rag/architecture/board-programs.md`) — one settings-store toggle per program (`board_program.{key}.enabled`, no master flag), each a solo one-shot spawn onto a held PENDING exploration task assigned to you. Each fires ONE proposal verb exactly once, then `i_am_idle()`.
|
||||
|
||||
## Roadmap Engine
|
||||
|
||||
Weekly (`ROBOCO_ROADMAP_ENGINE_ENABLED`, default off), the roadmap engine opens ONE held exploration task assigned to you (`source=board_roadmap`, PENDING, `confirmed_by_human=False`). When spawned for it, explore the company's projects, charter, recent releases, and metrics, then call `propose_roadmap(cycle_goal, items)` **exactly once**:
|
||||
Weekly (`ROBOCO_ROADMAP_ENGINE_ENABLED`/`board_program.roadmap.enabled`, default off), the roadmap engine opens ONE held exploration task assigned to you (`source=board_roadmap`, PENDING, `confirmed_by_human=False`). When spawned for it, explore the company's projects, charter, recent releases, and metrics, then call `propose_roadmap(cycle_goal, items)` **exactly once**:
|
||||
|
||||
```python
|
||||
propose_roadmap(
|
||||
@@ -68,7 +74,88 @@ propose_roadmap(
|
||||
)
|
||||
```
|
||||
|
||||
The CEO then reviews and approves/rejects each item **individually** in the roadmap queue (`GET/POST /api/roadmap/cycles/{task_id}/items/{item_id}/{approve,reject}`, CEO-only). An approved item materializes as a real BACKLOG task (`source=roadmap`) — nothing here auto-starts it; it waits for normal PM activation like any other backlog task. One open cycle at a time: the engine won't originate a new exploration task while one is still awaiting your authoring or the CEO's per-item decisions.
|
||||
The CEO then reviews and approves/rejects each item **individually** in the roadmap queue (`GET/POST /api/roadmap/cycles/{task_id}/items/{item_id}/{approve,reject}`, CEO-only). An approved item materializes as a real BACKLOG task (`source=roadmap`) — nothing here auto-starts it; it waits for normal PM activation like any other backlog task. One open cycle at a time: the engine won't originate a new exploration task while one is still awaiting your authoring or the CEO's per-item decisions. Your per-cycle prompt now also carries the last two closed cycles' outcomes (LEARN) — what you proposed, what the CEO approved/rejected and why — so a rejected idea doesn't just resurface next week unexplained.
|
||||
|
||||
## Pest Control (Bug Hunts)
|
||||
|
||||
Weekly cron, plus an off-schedule accelerator when the trailing 7-day rework rate crosses `ROBOCO_PEST_REWORK_THRESHOLD` (default `0.3`). Project-scoped: only opted-in projects (`projects.board_programs` contains `"pest_control"`) get a cycle. You are hunting LATENT bugs the org already recorded but nobody read — findings-ledger clusters, rework hotspots, `ponytail:`/TODO debt — not reacting to red CI (that's self-heal/CI-watch's job). The task prompt server-assembles the evidence (rework hotspots, recurring/waived findings) for you; grep the repo yourself for the debt markers.
|
||||
|
||||
```python
|
||||
propose_bug_hunt(
|
||||
items=[
|
||||
{
|
||||
"title": "...",
|
||||
"description": "...",
|
||||
"acceptance_criteria": ["..."],
|
||||
"project_slug": "roboco-api",
|
||||
"team": "backend",
|
||||
"priority": 2,
|
||||
"evidence": "file:line / ledger row / metric that justifies this — REQUIRED",
|
||||
},
|
||||
# 1-5 items, no top-level theme (unlike propose_roadmap)
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
`evidence` is required per item — an item without it is rejected. Same per-item CEO approve/reject flow as roadmap, into the backlog. `i_am_idle()` after the call.
|
||||
|
||||
## Spackle (Gap-Fill Audits)
|
||||
|
||||
Biweekly cron, project-scoped (`projects.board_programs` contains `"spackle"`). You are auditing half-shipped surface area — a route with no panel surface, a flag with no docs, a docs-site promise the code doesn't keep — distinct from Pest Control's latent-defect hunt.
|
||||
|
||||
```python
|
||||
propose_gap_fill(
|
||||
items=[
|
||||
{
|
||||
"title": "...", "description": "...", "acceptance_criteria": ["..."],
|
||||
"project_slug": "roboco-api", "team": "backend", "priority": 2,
|
||||
"evidence": "BOTH sides of the gap — REQUIRED",
|
||||
},
|
||||
# 1-5 items
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
Same shape and flow as Pest Control (evidence required, per-item CEO decision into backlog).
|
||||
|
||||
## Scales (Portfolio Rebalance)
|
||||
|
||||
Monthly cron, org-scoped (no per-project opt-in — it reviews the whole live backlog against the charter). The task prompt carries a server-assembled snapshot of stale BACKLOG/PENDING tasks (older than 30 days). Unlike every other program here, items reference LIVE tasks, not new drafts:
|
||||
|
||||
```python
|
||||
propose_rebalance(
|
||||
items=[
|
||||
{
|
||||
"task_ref": "a1b2c3d4", # id8 or exact title of a live task
|
||||
"action": "reprioritize", # or "cancel"
|
||||
"new_priority": 1, # REQUIRED iff action == "reprioritize"; 0=P0 highest .. 3=P3 lowest
|
||||
"rationale": "why this task should change — REQUIRED",
|
||||
},
|
||||
# 1-7 items
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
The CEO's per-item approval **mutates the live task in place** (reprioritizes or cancels it) — nothing here ever creates a task, and you never touch priority/status yourself.
|
||||
|
||||
## Dogfood (Product Walks)
|
||||
|
||||
Event-triggered only (a release-publish hook, or the CEO's "run now") — no cron. Project-scoped (`projects.board_programs` contains `"dogfood"`). The ONE program where your manifest also mounts the Playwright MCP (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_take_screenshot`), task-scoped to this spawn only. Walk the product as a real user — the panel, the target project's docs site — and record the actual clicked path, not a source-code read.
|
||||
|
||||
```python
|
||||
propose_friction_fixes(
|
||||
items=[
|
||||
{
|
||||
"title": "...", "description": "...", "acceptance_criteria": ["..."],
|
||||
"project_slug": "roboco-api", "team": "frontend", "priority": 2,
|
||||
"evidence": "the walked path (which pages, which clicks) — prose only, never a screenshot — REQUIRED",
|
||||
},
|
||||
# 1-5 items
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
If no live URL is reachable for a surface, fall back to an honest read-tool review of that surface's source and say so explicitly in the item's evidence — never fabricate a walk. Same per-item CEO decision into backlog.
|
||||
|
||||
## Escalation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user