From e2baab4ce4764b978d11776c57e05d45aae72965 Mon Sep 17 00:00:00 2001 From: Sam Tukra Date: Wed, 12 Aug 2026 12:14:02 +0100 Subject: [PATCH] docs(v2): adopt v2 rearchitecture plan from 3-repo deep-dive review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopt all 12 features synthesized from full-source reviews of oh-my-claudecode (yeachan-heo), ruflo (ruvnet), and ralph (snarktank), organized into five layer-based workstreams across six gated phases. - plans/zo-v2-rearchitecture.md: 20-check tiered oracle, anti-scope, reference repo links (+ .gitignore exception) - docs/reference/v2-rearchitecture.mdx: full feature table w/ provenance - docs/roadmap.mdx: v2 section (4 pillars + repo credits) - website: new §11 'What's next' crediting the three source repos - memory: STATE session 040, DECISION_LOG v2 decision, research corpus at memory/zo-platform/research/2026-08-12-repo-reviews/ Website change verified via HTML balance check + static-server DOM inspection; Astro build deferred to CI (no Node.js on this machine). Co-Authored-By: Claude Fable 5 --- .gitignore | 1 + docs/mint.json | 3 +- docs/reference/v2-rearchitecture.mdx | 113 ++ docs/roadmap.mdx | 32 +- memory/zo-platform/DECISION_LOG.md | 12 + memory/zo-platform/STATE.md | 8 +- .../2026-08-12-repo-reviews/README.md | 37 + .../oh-my-claudecode.md | 426 ++++++ .../research/2026-08-12-repo-reviews/ralph.md | 108 ++ .../2026-08-12-repo-reviews/raw-findings.json | 1328 +++++++++++++++++ .../research/2026-08-12-repo-reviews/ruflo.md | 360 +++++ .../2026-08-12-repo-reviews/synthesis.md | 110 ++ .../2026-08-12-repo-reviews/zo-baseline.md | 64 + .../sessions/session-040-2026-08-12.md | 65 + plans/zo-v2-rearchitecture.md | 160 ++ website/src/pages/index.html | 64 +- 16 files changed, 2883 insertions(+), 8 deletions(-) create mode 100644 docs/reference/v2-rearchitecture.mdx create mode 100644 memory/zo-platform/research/2026-08-12-repo-reviews/README.md create mode 100644 memory/zo-platform/research/2026-08-12-repo-reviews/oh-my-claudecode.md create mode 100644 memory/zo-platform/research/2026-08-12-repo-reviews/ralph.md create mode 100644 memory/zo-platform/research/2026-08-12-repo-reviews/raw-findings.json create mode 100644 memory/zo-platform/research/2026-08-12-repo-reviews/ruflo.md create mode 100644 memory/zo-platform/research/2026-08-12-repo-reviews/synthesis.md create mode 100644 memory/zo-platform/research/2026-08-12-repo-reviews/zo-baseline.md create mode 100644 memory/zo-platform/sessions/session-040-2026-08-12.md create mode 100644 plans/zo-v2-rearchitecture.md diff --git a/.gitignore b/.gitignore index 15ec79e..ca68880 100644 --- a/.gitignore +++ b/.gitignore @@ -19,6 +19,7 @@ website/.astro/ # ZO platform's own files are explicitly preserved below. plans/* !plans/zero-operators-build.md +!plans/zo-v2-rearchitecture.md !plans/mnist-digit-classifier.md !plans/cifar10-classifier.md targets/* diff --git a/docs/mint.json b/docs/mint.json index c7fea30..a172f86 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -71,6 +71,7 @@ { "group": "Reference", "pages": [ + "reference/v2-rearchitecture", "reference/low-token-preset", "reference/cost-benchmark" ] @@ -101,4 +102,4 @@ "permanent": true } ] -} +} \ No newline at end of file diff --git a/docs/reference/v2-rearchitecture.mdx b/docs/reference/v2-rearchitecture.mdx new file mode 100644 index 0000000..c41c637 --- /dev/null +++ b/docs/reference/v2-rearchitecture.mdx @@ -0,0 +1,113 @@ +--- +title: "v2 Rearchitecture" +description: "The full feature set ZO v2 adopts from a deep-dive review of oh-my-claudecode, ruflo, and ralph — and how each will be built, tested, and verified." +--- + +## Where this comes from + +In August 2026 we ran a full-source review of three agent-orchestration systems +— reading implementations, not READMEs, and separating genuinely-built +capability from aspiration: + + + + Hook-enforced execution guarantees, battle-tested across thousands of users. Its enforcement hooks each trace to a real production failure. + + + Self-verification machinery: witness manifests, behavioral smoke-test CI, temporal memory semantics. + + + The fresh-context loop: 113 lines of bash proving statelessness can be the architecture. + + + +The review's seven deep-dive passes catalogued 63 features (nine passes in +total, including a ZO baseline map and an adversarial synthesis), then distilled +them to the 12 below — deduplicated, ranked by leverage against ZO's documented +failure modes, and stripped of the things those repos get wrong (we documented +11 anti-patterns we are explicitly *not* copying, from keyword-triggered +orchestration to self-asserted completion). + +The conclusion in one line: **ZO's oracle discipline stays; underneath it we're +adding a deterministic enforcement plane, a machine-readable control plane, a +fresh-context execution substrate, and an oracle for the platform itself.** + +## The 12 features + +Organized into five layer-based workstreams. The source repo is provenance, not +architecture — features from different repos interlock into single mechanisms. + +### Workstream A — Enforcement plane + +*What spawn prompts promise, hooks now guarantee.* + +| # | Feature | From | Priority | +|---|---------|------|----------| +| 1 | **Machine-checked deliverable contracts** — every agent's produced/consumed contract compiles to JSON (required files, sections, patterns) verified mechanically when the agent stops, plus a zero-cost "completion claim vs. TODO-stub diff" drift guard | oh-my-claudecode | P0 | +| 3 | **Hook-enforced memory protocol** — STATE.md flushes before compaction, session summaries verified at session end, structured failure records captured automatically; the model can't forget because the model isn't asked | oh-my-claudecode | P0 | +| 7 | **Anti-forgery gate approvals** — approvals only valid as structured tags carrying a per-verification nonce, so no agent can forge gate passage by echoing text | oh-my-claudecode | P1 | +| 9 | **Structurally trustworthy verifiers** — the oracle and reviewers mechanically cannot edit code (tool-level enforcement), evaluators emit a strict JSON contract, and evaluation files are sealed against modification by the loop they evaluate | oh-my-claudecode | P1 | + +### Workstream B — Control plane + +*Progress becomes a query, not prose interpretation.* + +| # | Feature | From | Priority | +|---|---------|------|----------| +| 4 | **Machine-readable plan ledger with oracle-owned pass flags** — every subtask carries acceptance criteria, a verification command, and a boolean `passes` that only the oracle may flip; plan validation enforces ralph's "Number One Rule": every story fits one context window | ralph + oh-my-claudecode | P0 | + +### Workstream C — Execution substrate + +*The failure unit becomes one iteration, not one 38-hour session.* + +| # | Feature | From | Priority | +|---|---------|------|----------| +| 2 | **Watchdog from proven parts** — heartbeat-file liveness, a taxonomy of stops that must never be fought (context-limit, rate-limit, auth, user abort), bounded nudge budgets, and rate-limit wait-and-resume for overnight runs | oh-my-claudecode + ruflo | P0 | +| 6 | **Fresh-context-per-subtask execution loop** — a new agent per iteration re-derives state from the ledger, experiment lineage, and a curated priors digest; git commits are the checkpoints; context rot and compounding hallucination are eliminated structurally | ralph + oh-my-claudecode | P1 | + +### Workstream D — Self-learning & platform oracle + +*The self-evolution loop gets the same rigor ZO applies to ML work.* + +| # | Feature | From | Priority | +|---|---------|------|----------| +| 5 | **Witness manifests + fixture regression** — every verified fix in PRIORS binds to a code marker checked in CI, and prompt-level rule edits replay the original failure fixture before promotion; "this rule would have caught it" becomes a standing check, not a one-time claim | ruflo + oh-my-claudecode | P1 | +| 11 | **Platform CI doctrine** — behavioral smoke tests reproducing each documented failure symptom, monotone quality ratchets on agent definitions, and doc counts generated from the filesystem instead of hand-maintained | ruflo + oh-my-claudecode | P2 | +| 12 | **Memory layer upgrades** — temporal supersession semantics (refuted knowledge is invalidated with a pointer to its replacement, never overwritten), a three-question quality gate on new priors, a curated read-first digest, and a CI-enforced context budget | ruflo + oh-my-claudecode + ralph | P2 | + +### Workstream E — Operator experience + +*Observe/notify/control as load-bearing infrastructure.* + +| # | Feature | From | Priority | +|---|---------|------|----------| +| 8 | **Two-way gate notifications** — gate-pending, loop verdicts, and stall alerts pushed to Slack/Telegram with cooldowns; replies ("approve" / "reject: reason") route back into the running session with authorization and sanitization | oh-my-claudecode | P1 | +| 10 | **ZO HUD statusline** — project, phase, pending gate, oracle status, iteration, active agents, and context usage at a glance, rendered from control-plane files | oh-my-claudecode | P2 | + +## How it ships + +The build follows ZO's own discipline — the plan lives at +`plans/zo-v2-rearchitecture.md` with a full oracle: + +1. **Plan** — six gated phases (enforcement → control plane → substrate → + platform oracle → operator UX → integration), each with named verification + checks agreed before work starts. +2. **Build** — every feature lands as a PR with a **seeded-failure test**: the + enforcement mechanism must catch a deliberately planted violation before it + merges. Nothing ships unwired — no mechanism merges without a runtime caller + and an observable test. +3. **Test** — the 854-test platform suite stays green on Python 3.11 and 3.12 + throughout; new mechanisms add their own unit + integration coverage. +4. **Verify** — 20 oracle verification checks (tiered must/should/could), ending + with a full demo project run where every new mechanism is observed firing — + and a substrate go/no-go: the fresh-context loop must match v1's demo + accuracy at ≤ 1.15× cost before it becomes the default. +5. **Ship** — phase-gated releases; the roadmap and this page track progress. + +## What we're deliberately not copying + +The review also produced an anti-pattern catalog — dead code presented as +capability, unverified performance claims, keyword-triggered orchestration, +self-asserted completion, verification theater, surface-area maximalism. These +are encoded in the plan's anti-scope and enforced in review. ZO's small, honest +surface is the asset we're protecting. diff --git a/docs/roadmap.mdx b/docs/roadmap.mdx index 3164d69..f822b5e 100644 --- a/docs/roadmap.mdx +++ b/docs/roadmap.mdx @@ -11,9 +11,39 @@ For cost-sensitive plans (Anthropic Pro, student tier, individual researchers on --- +## The v2 rearchitecture + +The headline: after a full-source review of three agent-orchestration systems — +[oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode), +[ruflo](https://github.com/ruvnet/ruflo), and +[ralph](https://github.com/snarktank/ralph) — ZO v2 adopts 12 features across +five workstreams. ZO's oracle discipline stays; underneath it we're adding: + + + + Deterministic hooks that mechanically guarantee what spawn prompts currently promise: deliverable contracts checked when an agent stops, memory that persists automatically, gate approvals that can't be forged, verifiers that structurally cannot edit code. + + + A plan ledger where every subtask has verifiable acceptance criteria and a pass flag only the oracle may flip — progress becomes a query, not prose interpretation. STATE.md stays as the human-readable projection. + + + A new agent per iteration, all state on disk, git as the checkpoint — context rot and compounding errors eliminated structurally, with a watchdog built from battle-tested parts (heartbeats, never-fight-these-stops taxonomy, rate-limit auto-resume). + + + Every learned rule binds to a code marker checked in CI; every documented failure gets a smoke test reproducing its symptom. The self-evolution loop gets the same rigor ZO applies to ML work. + + + +The full feature list, provenance, and the plan/build/test/verify/ship process +live on the [v2 rearchitecture page](/reference/v2-rearchitecture). Credit where +due: these three open-source projects each solved a piece of this puzzle in +public, and the review that shaped v2 reads their source closely. + +--- + ## What we're working on -Three workstreams shape the next 1–2 quarters, driven by recent user feedback on cost, accessibility, and cross-phase autonomy. Grouped by horizon: **Now**, **Next quarter**, and **Major design**. +Alongside the v2 rearchitecture, three ongoing tracks shape the next 1–2 quarters, driven by recent user feedback on cost, accessibility, and cross-phase autonomy — they fold into or queue behind the v2 workstreams above. Grouped by horizon: **Now**, **Next quarter**, and **Major design**. ### Now (next 2–4 weeks) diff --git a/memory/zo-platform/DECISION_LOG.md b/memory/zo-platform/DECISION_LOG.md index bcc8bb7..35dffd5 100644 --- a/memory/zo-platform/DECISION_LOG.md +++ b/memory/zo-platform/DECISION_LOG.md @@ -1227,3 +1227,15 @@ The `--no-headlines` flag is preserved (not removed) for backwards compatibility **Rationale:** PR #99 shipped extension points whose documented purpose is letting downstream builds add CLI commands via entry points discovered at `zo.cli` import. A strict-equality command-set test makes the CORE suite fail in any environment where such a plugin is installed — the first real downstream plugin (registering a new command group) surfaced exactly that. The test's job is "core commands all present"; removals still fail under subset. **Alternatives considered:** (1) Computing `actual` minus plugin-contributed commands — `load_cli_plugins` doesn't record which commands each plugin added; tracking that adds machinery for a test. (2) Re-importing `zo.cli` with plugin discovery monkeypatched off — fragile import gymnastics for marginal benefit. (3) Leave it and tell downstream users to expect one red test — contradicts the extension point being a supported public mechanism. **Outcome:** Single-assertion diff + memory. 854 passed / 7 skipped on Python 3.11 AND 3.12, ruff clean, validate-docs 0 failures. Branch `claude/cli-test-plugin-tolerant`. + +## Decision: 2026-08-12T00:00:00Z +**Type:** ARCHITECTURE + SCOPE +**Title:** ZO v2 rearchitecture — adopt all 12 reviewed features, organized by layer (not by source repo) + +**Decision:** Following the 2026-08-12 deep-dive review of oh-my-claudecode (yeachan-heo), ruflo (ruvnet), and ralph (snarktank) — full findings in `memory/zo-platform/research/2026-08-12-repo-reviews/` — Sam decided to adopt ALL 12 synthesized features. Work is organized into five **layer-based workstreams** (A: enforcement plane, B: control plane, C: execution substrate, D: self-learning & platform oracle, E: operator experience) with the source repo kept as provenance metadata, and sequenced into six gated phases in `plans/zo-v2-rearchitecture.md` with a 20-check tiered oracle. The initiative is documented publicly: `docs/reference/v2-rearchitecture.mdx` (full feature table + reference repo links), a v2 section atop `docs/roadmap.mdx`, and a new §11 "What's next" on the website crediting the three repos. + +**Rationale:** The review showed the three repos triangulate ZO's documented weaknesses (aspirational contracts, 38-hour silent stall, manual self-evolution verification, prose-parsed progress). Layer-based workstreams were chosen over source-repo categories because features from different repos interlock into single mechanisms (e.g., ralph's ledger + OMC's contract hook + oracle-owned flags form one control-plane unit; repo-based grouping would force interleaved PRs over the same files). Phase order puts small, pure-addition enforcement/control work first to de-risk the one structural change (fresh-context substrate), which lands behind a demo-validated go/no-go gate (≥ v1 demo accuracy at ≤ 1.15× cost). + +**Alternatives considered:** (1) Source-repo workstreams ("ralph track", "ruflo track") — rejected, provenance is not architecture; (2) P0-only scope — rejected by Sam, all 12 wanted; (3) waiting for the SDK refactor before substrate work — rejected, the fresh-context loop is the cheapest on-ramp to that refactor, not a competitor. + +**Outcome:** Shipped: plan (+ gitignore exception), docs reference page + mint.json nav, roadmap v2 section, website §11 + drawer nav + §12 renumber, STATE/session-040/research-README memory updates. Verification honest note: **no Node.js available on this machine**, so the Astro build was NOT run locally — the website edit was verified via HTML tag-balance parsing and DOM inspection through a static file server (section renders, all 4 external links present, drawer link + renumbering correct); the deploy pipeline's build is the binding check. validate-docs run pre-commit per protocol. diff --git a/memory/zo-platform/STATE.md b/memory/zo-platform/STATE.md index fd2fd50..7df8d3d 100644 --- a/memory/zo-platform/STATE.md +++ b/memory/zo-platform/STATE.md @@ -8,7 +8,9 @@ status: complete ## Current Position -**Session 039 (current) — pick up here.** Test-only change making the CLI command-set test plugin-tolerant: `tests/unit/test_cli.py::TestCliGroup::test_cli_group_has_all_commands` asserted strict equality on `cli.commands`, which contradicts the extension points ZO itself shipped in PR #99 — any downstream build installing a `zo.commands` entry-point plugin (the documented mechanism in `zo.extensions.load_cli_plugins`) adds commands and turned the core suite red in that environment, despite zero core changes. Changed `assert expected == actual` → `assert expected <= actual` with an explanatory comment. Trade-off accepted: equality also caught *core* commands added without updating the test; subset still catches removals, and additions have always required updating this test's `expected` set anyway. Surfaced by the first real downstream plugin registering a new command group. No code, version, agents, or docs touched — single-assertion diff (+ memory). **854 passed / 7 skipped on Python 3.11 AND 3.12, ruff `src/` clean, validate-docs 0 failures.** **Next:** unchanged — Batch **D** / **E**, standing Tier-1 (caveman, onboarding). +**Session 040 (current) — pick up here.** Research + decision session: deep-dive review of three agent-orchestration repos (oh-my-claudecode, ruflo, ralph — cloned to `~/Documents/code/`) to inform the ZO v2 rearchitecture. 9-agent workflow (7 source-reading lenses + ZO baseline + adversarial synthesis, ~1.06M tokens) catalogued **63 features**, distilled to **12 ranked adoptions** + 6 rearchitecture themes + 11 anti-patterns; all findings persisted to `memory/zo-platform/research/2026-08-12-repo-reviews/` (per-repo markdown + `raw-findings.json`). **Sam decided: adopt all 12.** Work organized into **five layer-based workstreams** (A enforcement plane, B control plane, C execution substrate, D self-learning/platform oracle, E operator experience) — NOT source-repo categories, because features from different repos interlock into single mechanisms. Shipped this session: `plans/zo-v2-rearchitecture.md` (full plan: 6 gated phases, 20-check oracle, anti-scope; + `.gitignore` exception), `docs/reference/v2-rearchitecture.mdx` (all 12 features w/ provenance + repo links; added to mint.json Reference nav), `docs/roadmap.mdx` v2 section (4 pillars + repo credits), website §11 "What's next" (new section w/ 3 repo credit cards; quick start renumbered §12; drawer nav updated). **Verification caveat: no Node.js on this machine** — Astro build NOT run; website change verified via HTML-parser balance check + static-server DOM inspection (section text, all 4 links, drawer entry, renumbering all confirmed rendered). CI/deploy build must confirm. No src/ code, agents, commands, or version touched. **Next:** v2 Phase 1 (enforcement foundations, WS-A) per `plans/zo-v2-rearchitecture.md`; prior Batch D/E + Tier-1 items (caveman, onboarding) fold into or queue behind the v2 plan. + +**Session 039 (prior).** Test-only change making the CLI command-set test plugin-tolerant: `tests/unit/test_cli.py::TestCliGroup::test_cli_group_has_all_commands` asserted strict equality on `cli.commands`, which contradicts the extension points ZO itself shipped in PR #99 — any downstream build installing a `zo.commands` entry-point plugin (the documented mechanism in `zo.extensions.load_cli_plugins`) adds commands and turned the core suite red in that environment, despite zero core changes. Changed `assert expected == actual` → `assert expected <= actual` with an explanatory comment. Trade-off accepted: equality also caught *core* commands added without updating the test; subset still catches removals, and additions have always required updating this test's `expected` set anyway. Surfaced by the first real downstream plugin registering a new command group. No code, version, agents, or docs touched — single-assertion diff (+ memory). **854 passed / 7 skipped on Python 3.11 AND 3.12, ruff `src/` clean, validate-docs 0 failures.** **Next:** unchanged — Batch **D** / **E**, standing Tier-1 (caveman, onboarding). **Session 038 hand-off (prior).** Shipped **concurrent report sessions** (the *surrogate* model): `zo report` runs an Opus report-lead in an isolated git worktree ALONGSIDE a live `zo continue` model session on the same project, with safe consolidation back. New modules — `src/zo/surrogate.py` (worktree + `report/` branch + per-PID liveness lock files + delta-memory store at `.zo/surrogates//`), `src/zo/consolidate.py` (fold deltas → canonical: append DECISION_LOG, dedup PRIORS, copy session summaries, commit+merge the report branch, archive; **never** writes canonical STATE), `src/zo/report.py` (Opus report-lead prompt: verify via `oracle-qa` + `data-engineer`, write LaTeX, hard read-only boundaries on canonical memory + experiments). `flock` added to `memory.append_decision/append_prior`. New CLI: `zo report` (`--objective`/`--resume`/`--no-consolidate`/`--no-tmux`/`--bypass-permissions`) + `zo consolidate` (`--dry-run`); `_launch_and_monitor` gains per-PID registration + auto-consolidation when the **last** session exits + liveness-gated overlay cleanup. **Two safety hardenings (PRIORS PR-045):** (1) a report session NEVER touches the shared permission overlay — cleanup is gated to orchestrator-role sessions only, so a report can't disrupt a running `zo continue` even though that session predates the liveness registry; (2) `--no-consolidate` suppresses exit-merge for exactly that predates-the-registry case (merge later with `zo consolidate`). Verified: 28 new tests (unit prompt + real-git round-trip incl. deferred-merge/no-double-fold + CLI wiring + concurrency/conflict/resume/STATE-untouched/overlay-isolation + bypass-inherit), **826 → 854 passed, 7 skipped on Python 3.11 AND 3.12**, ruff clean, validate-docs 0 failures, plus a 12-check real-`uv run zo` smoke. Follow-up safety: `apply_bypass_overlay` now inherits an already-active bypass overlay (no-op) instead of clobbering it, so `zo report --bypass-permissions` is safe alongside a model session running in bypass (no lingering-bypass after exit). Surrogate sessions assume both sessions share a filesystem (same machine — matches "another tmux window"); cross-machine is out of scope. Branch `claude/zo-report-surrogate` (PR pending). **Next:** unchanged — Batch **D** / **E**, standing Tier-1 (caveman, onboarding). @@ -188,8 +190,8 @@ ZO **v1.0.2** + **`--low-token` mode** (session-024) — cost-saving preset for ## Session Metadata -last_checkpoint: 2026-06-04T00:00:00Z -last_session: session-038 (concurrent report sessions — `zo report`/`zo consolidate` surrogate model, safe alongside a live model session; PRIORS PR-045) +last_checkpoint: 2026-08-12T00:00:00Z +last_session: session-040 (v2 rearchitecture research + decision — 3-repo deep dive, 12 adoptions across 5 workstreams, plan + docs + website shipped) branch: claude/beautiful-bhabha-69ae22 (worktree, roadmap commit pending) v1_status: COMPLETE — all 8 PRD §9 acceptance criteria met, all Known Issues closed docs_site: deployed at docs.zerooperators.com via Mintlify (mint.json + 16 pages: 3 get-started + 7 concepts + 4 cli + 2 reference; redirect rule /concepts/agents → /concepts/the-team for stale-cache hardening). Build verified live 2026-04-27 — all sibling concept pages return 200 except `/concepts/the-team` which 404'd due to MDX 2 prose `<500 lines, functions <50 lines` parser bug on line 51 (`<` followed by digit treated as JSX opening tag). Fixed by replacing `<500` / `<50` with `under 500` / `under 50` natural-prose. (Original planning URL `docs.zero-operators.dev` documented in DECISION_LOG was changed to the no-hyphen `docs.zerooperators.com` during actual setup; README badge + docs/README updated to match.) diff --git a/memory/zo-platform/research/2026-08-12-repo-reviews/README.md b/memory/zo-platform/research/2026-08-12-repo-reviews/README.md new file mode 100644 index 0000000..cc7cccc --- /dev/null +++ b/memory/zo-platform/research/2026-08-12-repo-reviews/README.md @@ -0,0 +1,37 @@ +# Repo Deep-Dive Reviews — 2026-08-12 + +Purpose: thorough review of three agent-orchestration repos to inform a potential +Zero Operators rearchitecture. Requested by Sam; findings feed a rearchitecture +decision session. + +## Repos under review (cloned to ~/Documents/code/) + +| Repo | Source | Shape | +|------|--------|-------| +| oh-my-claudecode | https://github.com/yeachan-heo/oh-my-claudecode | ~6k files; TypeScript Claude Code plugin ecosystem (agents, hooks, skills, HUD, magic keywords) | +| ruflo | https://github.com/ruvnet/ruflo | ~5.5k files; claude-flow successor, v3; Rust crates + TS, agentdb.rvf, swarm orchestration | +| ralph | https://github.com/snarktank/ralph | 31 files; bash loop + prompt.md autonomous-agent technique, PRD-driven | + +## Status + +- [x] Repos cloned (2026-08-12) +- [x] Deep-dive workflow complete (9 agents, 63 features catalogued, 0 errors) +- [x] Findings persisted per-repo +- [x] Synthesis + ZO gap analysis persisted (12 ranked adoptions, 6 themes, 11 anti-patterns) +- [x] Rearchitecture decision made (same day): **adopt all 12 features**, five layer-based workstreams, plan at `plans/zo-v2-rearchitecture.md` + +## Recovery info (if session dropped) + +- Workflow run ID: `wf_64cc6a3c-6fc` (task w15fmlpc9), session e6a7e986-69d1-46cd-817f-1e0760ccc2a9 +- Script: `~/.claude/projects/-Users-sam101fe4x-Documents-code-zero-operators/e6a7e986-69d1-46cd-817f-1e0760ccc2a9/workflows/scripts/repo-deep-dive-review-wf_64cc6a3c-6fc.js` +- Agent journal: `.../subagents/workflows/wf_64cc6a3c-6fc/journal.jsonl` +- 8 dive lenses: omcc:orchestration, omcc:components, omcc:runtime, ruflo:core, ruflo:swarm, ruflo:dx, ralph:all, zo-baseline; then 1 synthesis agent. + +## Files in this directory + +- `oh-my-claudecode.md` — full findings (orchestration, components, runtime UX lenses) +- `ruflo.md` — full findings (core/memory, swarm, plugins/DX lenses) +- `ralph.md` — full findings (complete review) +- `zo-baseline.md` — honest map of ZO's current architecture, strengths, gaps +- `synthesis.md` — cross-repo comparison, ranked features to adopt, rearchitecture themes +- `raw-findings.json` — machine-readable full workflow output (for re-querying) diff --git a/memory/zo-platform/research/2026-08-12-repo-reviews/oh-my-claudecode.md b/memory/zo-platform/research/2026-08-12-repo-reviews/oh-my-claudecode.md new file mode 100644 index 0000000..25f706b --- /dev/null +++ b/memory/zo-platform/research/2026-08-12-repo-reviews/oh-my-claudecode.md @@ -0,0 +1,426 @@ +# oh-my-claudecode — Deep Dive Findings (2026-08-12) + +## Lens: orchestration + +### Summary + +oh-my-claudecode (OMC, v4.15.7, MIT) is a very large, very active Claude Code plugin (~1,155 TS files / ~337K lines in src/, thousands of merged PRs, last commit the day of review) that turns a single Claude Code session into a multi-agent orchestration layer. Its core design pattern is a split between non-deterministic "prompt protocols" (19 agent persona .md files with model-tier frontmatter, ~45 skills as markdown workflow specs) and deterministic TypeScript state machines wired into every Claude Code hook event (UserPromptSubmit, Stop, PreToolUse, PostToolUse, SubagentStart/Stop, PreCompact, SessionStart/End). The hooks detect "magic keywords" in prompts, inject system-reminders that activate skill protocols, persist per-mode JSON state under .omc/state/ (session-scoped, atomically written, lock-protected), and — most distinctively — intercept Stop events to force continuation until file-based completion criteria are met. + +Execution modes compose as layers: ultrawork (parallel delegation protocol, no persistence) ⊂ ralph (PRD-driven persistence loop: auto-generated prd.json user stories with acceptance criteria, progress.txt cross-iteration memory, reviewer verification with anti-forgery approval tags before completion is accepted) ⊂ autopilot (5-phase pipeline: expansion → planning → execution → QA → validation with per-phase iteration caps and 3-perspective validation). Orthogonal modes: team (staged pipeline team-plan → team-prd → team-exec → team-verify → team-fix over either native Claude Code agent teams or a 27K-line tmux/CLI worker runtime with heartbeats, mailboxes, git-worktree isolation, and cross-provider workers — codex/gemini/antigravity/cursor), ralplan (3-agent consensus planning: planner/architect/critic), ultraqa (test-fix cycling with same-failure early exit), and autoresearch (evaluator-contract improvement loop — the closest analog to ZO's oracle). + +The stop decision is the most engineered part of the system: a 2,564-line persistent-mode Stop hook resolves an authoritative workflow ledger (parent mode wins in nested runs), then applies ~10 circuit breakers learned from production failures (context-limit deadlocks #213, rate-limit retry loops #777, auth-error loops #1308, thinking-only streak detection, oversize tool-result redirects, SHA-256-authenticated cancel signals, PID-aware stale-state detection) before deciding to block a stop and re-inject a continuation prompt. Iterations are bounded per-mode (ralph default 10, autopilot per-phase caps) under a global security-config hard cap (500, 200 in strict mode). + +The quality-measurement story is the weakest part: benchmark/ is a complete SWE-bench Verified vanilla-vs-OMC harness, but results are empty templates and the only committed run is a 5-instance smoke test where OMC failed 5/5; benchmarks/ (agent-prompt regression scoring with ground-truth findings) has all-zero placeholder baselines; geobench/ is not a quality benchmark at all but a marketing "GEO visibility" profile. Several sophisticated-looking subsystems (signal-based model routing engine, verification tier-selector, task-decomposer) are exported library code with no runtime callers — actual model routing is declarative prompt guidance, not code. + +### Key Features + +#### Magic keyword detection with false-positive suppression and under-specification gating + +- **What:** A UserPromptSubmit hook that detects mode-triggering keywords (ralph, autopilot, ulw/ultrawork, ralplan, tdd, ultrathink, deepsearch, ccg, cancelomc, etc., in English/Korean/Japanese/Chinese) and injects [MAGIC KEYWORD: ...] system-reminders that activate the corresponding skill. +- **Why special:** Not the regexes themselves but the guardrails around them: it strips code blocks, file paths, git diffs, quoted spans, pasted transcripts, and XML blocks before matching; suppresses activation for informational contexts ('what is ralph?'), diagnostic complaints ('ralph keeps looping'), and banter; classifies task size (<50 words = small) and suppresses heavy modes for small tasks; and applies a 'ralplan-first gate' that redirects underspecified execution prompts (no file paths, symbols, issue refs, or structure) to planning instead, with force:/! escape hatches. This is hundreds of lines of hard-won UX engineering that any keyword-triggered agent system will eventually need. +- **How it works:** src/hooks/keyword-detector/index.ts (1,114 lines): KEYWORD_PATTERNS + KEYWORD_PRIORITY, sanitizeForKeywordDetection(), isInformationalKeywordContext() with quoted-span exemptions and per-language diagnostic-intent regexes, getAllKeywordsWithSizeCheck() using classifyTaskSize() from src/hooks/task-size-detector/index.ts, applyRalplanGate() with WELL_SPECIFIED_SIGNALS. Wired via hooks/hooks.json UserPromptSubmit → scripts/keyword-detector.mjs; conflict resolution (cancel beats all, team beats autopilot) and detection results flow into src/hooks/bridge.ts. +- **ZO relevance:** Directly adoptable pattern: ZO's slash-command entry points (zo build/continue) avoid this problem, but if ZO ever adds natural-language triggers or auto-detects 'plan-edited' intent, the two useful ideas are (1) the underspecification gate — refuse to spawn a heavy agent team when the plan/prompt lacks concrete anchors, redirect to planning instead — and (2) task-size gating to prevent over-orchestration. ZO's oracle-first principle already implies a specification gate; OMC shows how to implement it as a deterministic pre-spawn check. +- **Evidence:** `src/hooks/keyword-detector/index.ts`, `src/hooks/task-size-detector/index.ts`, `hooks/hooks.json`, `src/hooks/bridge.ts` + +#### Stop-hook persistence engine (the 'when to stop' machinery) + +- **What:** A Stop-event hook that decides whether Claude is allowed to stop. If a persistent mode (ralph/autopilot/team/ralplan/ultrawork/autoresearch) is active with incomplete work, it blocks the stop and injects a continuation prompt; a stack of circuit breakers prevents the blocking from becoming an infinite or harmful loop. +- **Why special:** This is the most battle-tested 'agent persistence' implementation I've seen in the Claude Code ecosystem. Every escape valve carries an issue number from a real production failure: never block context-limit stops (deadlock, #213), rate-limit stops (429 retry loop, #777), auth failures (#1308), user aborts, scheduled wakeups, oversize tool-result redirects (bounded window of 3), sessions with pending async work; a thinking-only streak guard releases the stop after N consecutive assistant turns with no tool_use (detects unproductive rumination by parsing the transcript); cancel signals are authenticated with SHA-256 digests of the target state + workflowRunId + 30s TTL so a stale or forged cancel cannot kill the wrong run; a workflow-slot ledger resolves nested modes so the authoritative parent (autopilot over ralph) does the stop-gating; global hard cap of 500 iterations (200 strict) from security config. +- **How it works:** src/hooks/persistent-mode/index.ts (2,564 lines): resolvePersistentModeBlock() runs the bypass checks then priority order (workflow-ledger authority → ralph/autopilot → autoresearch → ralplan → team → ultrawork → skill-active-state → todo-continuation, max 5 attempts); applyThinkingOnlyStreakGuard() classifies the last assistant turn from transcript JSONL; createHookOutput() returns continue:false to hard-block. Registered as Stop hook in hooks/hooks.json (persistent-mode.mjs, alongside context-guard-stop.mjs and workflow-drift-guard.mjs). Hard cap via getHardMaxIterations() in src/lib/security-config.ts. +- **ZO relevance:** Highest-value study target for ZO. ZO's spec (297adac added a watchdog/heartbeat anti-stall design spec) is heading exactly here. The lessons to steal wholesale: (1) enumerate stop-context types and never fight the platform on context-limit/rate-limit/auth stops; (2) bound every continuation loop at multiple levels (per-mode max, global hard cap, attempt counters with TTL); (3) detect 'thinking-only' non-progress from the transcript, not from wall-clock time; (4) authenticate cancellation against a state digest so stale signals can't kill live runs; (5) when modes nest (ZO: orchestrator → phase agents), the parent must own stop-gating via an authoritative ledger. ZO can implement this in its Claude Code hook layer with far less code since it has fewer modes. +- **Evidence:** `src/hooks/persistent-mode/index.ts`, `src/hooks/todo-continuation/index.ts`, `src/lib/security-config.ts`, `hooks/hooks.json` + +#### Ralph: PRD-driven persistence loop with anti-forgery completion verification + +- **What:** The flagship 'keep working until done' mode. Startup force-generates a prd.json of user stories with acceptance criteria (model must refine generic scaffold criteria into task-specific ones); the loop picks the next passes:false story each iteration; completion of the whole run requires a reviewer agent (architect default, critic or external Codex via --critic=) to approve against the specific acceptance criteria. +- **Why special:** Two genuinely clever mechanisms. First, completion approval is an XML tag with a per-verification random UUID: VERIFIED_COMPLETE, and detectArchitectApproval() strips injected prompt examples before matching and requires the request-id (and story-id) to correlate — the executing model cannot self-approve by echoing text it saw in its own context. Second, progress.txt accumulates per-story implementation notes, files changed, learnings, and codebase patterns that get re-injected each iteration — cross-iteration memory that survives context resets. Verification is bounded (3 attempts then force-accept) and scoped per-story or per-completion. +- **How it works:** src/hooks/ralph/loop.ts (state, PRD startup gate, linked ultrawork auto-activation), prd.ts (story schema, scaffold generation, status), progress.ts (append-only learnings), verifier.ts (VerificationState, startVerification, getArchitectVerificationPrompt with correlated approval tag, detectArchitectApproval/Rejection). The skill prompt protocol is skills/ralph/SKILL.md; stop-hook integration in persistent-mode/index.ts checkRalphLoop; default 10 iterations. +- **ZO relevance:** Direct analog to ZO's oracle loop, but weaker and stronger in different places. Weaker: OMC's verifier is an LLM reviewer with regex-based rejection detection — ZO's hard, executable oracle metric is strictly better as ground truth. Stronger: (1) the request-id-correlated approval tag is a pattern ZO should adopt for any LLM-judged gate (gates:approve) to prevent an agent from forging gate passage from in-context examples; (2) prd.json's per-story acceptance criteria with passes flags is a finer-grained progress ledger than a phase-level plan — ZO subtasks could carry machine-checkable passes state; (3) progress.txt's 'learnings and patterns' feed is a lightweight in-run version of ZO's PRIORS.md worth mirroring at the iteration level. +- **Evidence:** `src/hooks/ralph/loop.ts`, `src/hooks/ralph/verifier.ts`, `src/hooks/ralph/prd.ts`, `src/hooks/ralph/progress.ts`, `skills/ralph/SKILL.md` + +#### Autopilot: 5-phase autonomous pipeline with multi-perspective validation and evidence-bound stage advancement + +- **What:** Idea-to-working-code mode: expansion (analyst+architect spec) → planning (architect plan + critic validation) → execution (ralph+ultrawork) → QA (ultraqa cycling, max 5, early-exit if same error 3x) → validation (functional/security/quality reviewers must ALL approve, max 3 re-validation rounds). Also 'named workflow profiles' v1: user-configurable stage schedules ([ralplan, execution, ralph, qa] subsets) declared in omc.jsonc. +- **Why special:** The phase state machine is fully materialized in typed state (AutopilotState with per-phase sub-state, phase_durations, total_agents_spawned) rather than living only in the prompt, so the Stop hook can enforce phase-appropriate continuation and report progress. The named-workflow v1 goes further than anything comparable: an immutable SHA-256-hashed workflow descriptor, and Stop hooks that advance a stage only after an 'authorized assistant completion record' appears after the stage's persisted transcript boundary (Linux flock + no-follow fd traversal) — i.e., stage transitions require transcript evidence, rejecting stale, wrong-stage, or non-assistant output. Notably, the docs are candid about deferrals (no stageModels/model routing, Linux-only). +- **How it works:** src/hooks/autopilot/types.ts (phases, DEFAULT_CONFIG: maxQaCycles 5, maxValidationRounds 3, parallelExecutors 5, validationArchitects functional/security/quality), enforcement.ts (checkAutopilot: hard-max then per-state max iteration stops, phase-tagged continuation prompts), pipeline.ts/pipeline-types.ts (unified stage orchestrator), named-workflow-resume-validator.ts, state.ts; skill protocol skills/autopilot/SKILL.md (including artifact reuse: skip phases when a ralplan consensus plan or deep-interview spec already exists). +- **ZO relevance:** ZO's phase pipeline (specs/workflow.md) is the same shape, and ZO already does fresh-context phase transitions. Two adoptable ideas: (1) materialize phase state as typed, session-scoped JSON that hooks can enforce against — ZO's STATE.md is human-readable but not machine-enforced; a parallel state.json would let a ZO stop-hook verify 'phase N gate passed' deterministically; (2) transcript-evidence-bound stage advancement is the strongest anti-hallucination gate design available for 'the agent claims the phase is done' — overkill for v1 ZO but the right direction for unattended runs. The multi-perspective validation (3 reviewer types must all approve) maps to widening ZO's oracle gate with security/quality lanes. +- **Evidence:** `src/hooks/autopilot/types.ts`, `src/hooks/autopilot/enforcement.ts`, `src/hooks/autopilot/pipeline.ts`, `skills/autopilot/SKILL.md`, `docs/adr/03487-named-autopilot-stage-profiles.md` + +#### Team runtime: staged pipeline + tmux/CLI worker infrastructure with cross-provider workers + +- **What:** Two team implementations: (a) native Claude Code implicit agent teams (Task tool with name= workers) driving a canonical staged pipeline team-plan → team-prd → team-exec → team-verify → team-fix with a bounded fix loop; (b) a 27,781-line tmux/CLI worker runtime (src/team, 79 modules) where workers can be Claude, Codex, Gemini, Antigravity, or Cursor CLIs. +- **Why special:** The tmux runtime is a serious distributed-systems build: per-worker heartbeat JSON files with freshness-based liveness (heartbeat.ts), append-only inbox/outbox JSONL mailboxes with rotation and cursors, git-worktree-per-worker isolation with a merge coordinator/orchestrator, epoch-based team ownership, worker health checks and restarts, a dispatch queue, an intent-inference role router (task text → implementation/verification/review/debug/design/docs/build-fix/cleanup lane → role), per-role provider/model routing via .claude/omc.jsonc team.roleRouting (e.g., codex critic, gemini reviewer), and audit logs. Also instructive: they DISABLED the 'team' magic keyword (never-match regex in keyword-detector) because Claude workers receiving prompts containing 'team' caused infinite recursive spawning — a production scar worth learning from. +- **How it works:** Pipeline state machine: src/hooks/team-pipeline/{types,state,transitions}.ts (phase history, fix_loop attempt/max_attempts, cancel with preserve_for_resume). Worker runtime: src/team/{heartbeat,inbox-outbox,tmux-session,git-worktree,merge-orchestrator,role-router,runtime-v2,scaling,worker-health,worker-restart,team-owner-epoch}.ts. Stage-agent routing table (which specialist agents at which model tier per stage) lives in skills/team/SKILL.md. Ralph composition: getTeamPhaseDirective() in ralph/loop.ts lets ralph's stop enforcement track team phases. +- **ZO relevance:** ZO's contract-first parallel spawning is philosophically similar but ZO relies on Claude Code's native subagents. The transferable pieces: (1) the team-verify/team-fix bounded loop is exactly ZO's oracle→rework cycle — OMC's explicit fix_loop {attempt, max_attempts, last_failure_reason} state is a clean schema to copy; (2) heartbeat-file liveness + PID-aware ownership is the cheapest robust answer to ZO's watchdog/anti-stall spec for parallel agents; (3) per-role provider routing is a concrete design if ZO ever wants non-Claude verifiers (an external-model oracle reviewer is genuinely useful for adversarial verification); (4) the recursive-spawn scar argues for ZO keeping team spawning explicit/imperative, never keyword-triggered. +- **Evidence:** `src/team/heartbeat.ts`, `src/team/inbox-outbox.ts`, `src/team/role-router.ts`, `src/team/runtime-v2.ts`, `src/team/merge-orchestrator.ts`, `src/hooks/team-pipeline/types.ts`, `skills/team/SKILL.md` + +#### Model tiering: declarative agent frontmatter + prompt-driven routing (programmatic router is dead code) + +- **What:** 19 agent personas with model tiers in frontmatter (explore/writer=haiku; executor/debugger/verifier/tracer/qa-tester/etc=sonnet; analyst/planner/architect/critic/code-reviewer/code-simplifier=opus), read-only enforcement via disallowedTools on advisory agents, and skills that instruct the orchestrator to pass model= explicitly per delegation (haiku=lookup, sonnet=standard, opus=complex). +- **Why special:** The honest finding is what ISN'T wired: src/features/model-routing/ is a complete signal-extraction → complexity-scoring → tier-selection engine with escalation (routeTask, routeWithEscalation), and src/verification/tier-selector.ts scales verification effort (LIGHT/STANDARD/THOROUGH) from change metadata — but neither has any caller outside barrel exports and tests; no hook script bundles them. Actual routing is 100% prompt-convention: CLAUDE.md , per-skill Tool_Usage sections, and the team stage-routing table. This is a useful data point: OMC shipped and iterated on prompt-declared routing and never needed to wire the programmatic version. +- **How it works:** agents/*.md frontmatter (model:, level:, disallowedTools:); CLAUDE.md agent_catalog and model_routing sections; skills/ultrawork/SKILL.md and skills/team/SKILL.md routing tables; unwired engine at src/features/model-routing/{router,scorer,signals,rules}.ts and src/verification/tier-selector.ts (verified via grep: only re-exported from src/features/index.ts, absent from scripts/*.mjs bundles). +- **ZO relevance:** ZO already does frontmatter model routing per agent (specs/agents.md model tiers), so parity. The lesson is negative-space: don't build a complexity-scoring router; the prompt-declared tier tables plus a downgrade cost-mode rule ('opus→sonnet where quality permits; verify never below sonnet') cover the need. The one gap worth copying is tier-selector's IDEA even if OMC didn't wire it: scale oracle/verification effort with change surface (files changed, security-sensitive paths) — ZO could implement this deterministically in its gate logic. +- **Evidence:** `agents/executor.md`, `agents/architect.md`, `agents/critic.md`, `src/features/model-routing/router.ts`, `src/verification/tier-selector.ts`, `CLAUDE.md` + +#### Autoresearch: evaluator-contract improvement loop (OMC's oracle analog) + +- **What:** A stateful single-mission mode: a mission directory holds mission.md plus sandbox.md whose frontmatter declares an evaluator command that must emit JSON {pass: boolean, score?: number}, with keep_policy score_improvement or pass_only. The loop runs one experiment per iteration, runs the evaluator, persists per-iteration evaluation JSON and markdown decision logs, continues through failures, and stops only on max-runtime or explicit cancel. +- **Why special:** This is the only place OMC has a HARD, machine-verifiable success signal — everything else (ralph, autopilot validation) is LLM-judged. The contract is minimal and correct: structured evaluator output, keep-policy for hill-climbing vs. gating, durable per-iteration artifacts, and a wall-clock ceiling as the primary stop. The committed missions are thin (mission 'optimize omc' with evaluator 'npm run build'), showing it's early, but the contract design is sound. +- **How it works:** src/autoresearch/{contracts,runtime,setup-contract}.ts (frontmatter parsing, evaluator invocation, git-anchored mission dirs); skills/autoresearch/SKILL.md (artifact shape: .omc/autoresearch//runs//evaluations/iteration-NNNN.json + decision-log.md); missions/*/sandbox.md examples; stop-hook integration via checkAutoresearch in persistent-mode/index.ts; mission generation delegated to /deep-interview --autoresearch. +- **ZO relevance:** ZO's oracle-first principle is this exact idea but more mature (tiered criteria, drift detection per specs/oracle.md). Still worth borrowing: (1) the keep_policy distinction (score_improvement vs pass_only) cleanly separates hill-climbing experiments from pass/fail gates — useful for ZO's ML loops where val-metric improvement, not a binary gate, drives iteration; (2) per-iteration machine-readable evaluation JSON alongside a human decision log mirrors and validates ZO's DECISION_LOG pattern; (3) max-runtime as the primary hard stop for unattended loops is simpler and safer than iteration counts for ML workloads with variable step cost. +- **Evidence:** `src/autoresearch/contracts.ts`, `src/autoresearch/runtime.ts`, `skills/autoresearch/SKILL.md`, `missions/prove-reliability-by-finding-and-fixing-flaky-te/sandbox.md` + +#### Benchmark infrastructure: SWE-bench harness and agent-prompt regression scoring (both without real results) + +- **What:** benchmark/: a Dockerized SWE-bench Verified comparison suite (run_vanilla.sh vs run_omc.sh, evaluate.py, compare_results.py, failure analysis). benchmarks/: an agent-prompt regression harness scoring agent outputs against fixtures with embedded flaws — ground-truth findings with severities and keyword matching, composite TP/FN scores, saved baselines for prompt-change regression testing. geobench/: a YAML profile for measuring LLM answer visibility/citations of OMC itself (marketing, not quality). +- **Why special:** The DESIGN of benchmarks/ is the special part: treating agent prompts as testable artifacts with ground-truth fixtures and regression baselines is the right way to evolve prompts safely, and the harsh-critic scorer (matchFindings/scoreFixture/aggregateScores) is reusable. But the evidence status is damning: benchmark/results/README.md is an all-placeholder template ('-%' everywhere), predictions/ contains only a 5-instance smoke run where OMC failed 5/5 (vanilla 5/5, 0 tokens recorded — likely harness debugging), and benchmarks/baselines contains explicit zero-filled placeholders ('run bench:prompts:save to populate'). No in-repo proof OMC outperforms vanilla Claude Code. +- **How it works:** benchmark/{run_benchmark.py,evaluate.py,compare_results.py,analyze_failures.py,Dockerfile}; benchmark/predictions/*/stats.json (the failed smoke run); benchmarks/shared/{types,scorer,runner,reporter}.ts re-exporting benchmarks/harsh-critic/scoring/scorer.ts; benchmarks/baselines/2026-03-08-consolidation.json (placeholders); geobench/oh-my-claudecode.yaml (GEO visibility profile). +- **ZO relevance:** Two takeaways. Cautionary: OMC demonstrates that orchestration frameworks accrete unverified self-improvement claims — ZO's oracle-first stance is the antidote, and ZO should never ship a mode without a completed benchmark run backing it. Adoptable: the agent-prompt regression pattern (fixtures with planted flaws + keyword-matched ground truth + baseline snapshots) is exactly what ZO needs for its own agent persona evolution — when the self-evolution protocol edits an agent's rules after a failure, a fixture regression run would verify the edit catches the original failure without degrading other behaviors, mechanizing ZO's 'verify the updated rule would have caught the original failure' step. +- **Evidence:** `benchmark/README.md`, `benchmark/results/README.md`, `benchmark/predictions/omc/stats.json`, `benchmarks/shared/types.ts`, `benchmarks/shared/scorer.ts`, `benchmarks/baselines/2026-03-08-consolidation.json`, `geobench/oh-my-claudecode.yaml` + +#### Cross-provider orchestration (ccg, omc ask, external critics) + +- **What:** Structured use of non-Claude CLIs as advisors and workers: /ccg decomposes a request into a Codex prompt (architecture/backend/risk) and an Antigravity/Gemini prompt (UX/docs/alternatives), runs both via omc ask, and has Claude synthesize; team workers can be codex/gemini/antigravity/cursor; ralph's completion critic can be external Codex (--critic=codex). +- **Why special:** The role-shaped decomposition is more disciplined than 'ask another model': each provider gets a lane matched to its strengths, artifacts land under .omc/artifacts/ask/, and graceful degradation is specified when a CLI is missing. Using an external model as the completion critic is a real defense against same-model blind-spot correlation in verification. +- **How it works:** skills/ccg/SKILL.md (decompose → omc ask codex / omc ask antigravity → synthesize); src/team/cli-worker-contract.ts and cli-detection.ts for worker CLIs; ralph verifier codex mode in src/hooks/ralph/verifier.ts (getVerificationAgentStep 'codex' branch); per-role routing in omc.jsonc team.roleRouting. +- **ZO relevance:** Optional but interesting for ZO's oracle tier: an external-provider critic reviewing completion claims decorrelates verifier errors from executor errors (both Claude in ZO today). For ML projects this is lower value than ZO's executable metrics, but for the code-quality gates (phase reviews) a cheap cross-model second opinion is a genuine robustness upgrade. Low priority; adds CLI dependencies ZO's philosophy avoids. +- **Evidence:** `skills/ccg/SKILL.md`, `src/hooks/ralph/verifier.ts`, `src/team/cli-worker-contract.ts` + +### Architecture Notes + +Core pattern: "prompt protocols + deterministic hook-boundary state machines." Skills (markdown) define agent behavior; compiled TS hooks (scripts/*.mjs bundled from src/, loaded via hooks/hooks.json into every Claude Code hook event) enforce state transitions, block stops, and inject system-reminders. The two layers communicate through file-based JSON state under .omc/state/ with strict session scoping (.omc/state/sessions/{sessionId}/), atomic writes, advisory file locks, session-identity validation on every read (state.session_id !== sessionId → null), and worktree-root resolution (OMC_STATE_DIR > .omc-workspace marker > git root > cwd) for multi-repo setups. mode-registry does file-existence-based mode detection only (no imports from mode modules) to avoid circular dependencies. Modes compose as layers (autopilot ⊃ ralph ⊃ ultrawork; team × ralph via getTeamPhaseDirective), with a skill-state workflow ledger resolving which mode is the stop-gating authority in nested runs. Kill switches everywhere: DISABLE_OMC, OMC_SKIP_HOOKS (per-hook granularity), OMC_TEAM_WORKER (workers exempt from persistence). Local-fork discipline: plugin loads dist/ not src/, so TS edits require npm run build — documented in CLAUDE.md with a reminder skill. + +Development culture is regression-driven: nearly every guard clause cites a GitHub issue number (context-limit deadlock #213, rate-limit loop #777, auth loop #1308, over-orchestration #790, ralplan gate #997, skill-state blocking #1033, unified pipeline #1130), and the commit protocol mandates trailers (Constraint/Rejected/Directive/Confidence/Scope-risk/Not-tested) that preserve decision context in git history — functionally OMC's version of ZO's DECISION_LOG+PRIORS, but encoded in code comments, tests, and commit metadata rather than markdown memory files. The scale cost is real: 3,366-line bridge.ts, 2,564-line persistent-mode hook, 27,781-line team runtime; the system needs its own doctor command (omc-doctor), HUD statusline (src/hud with mission board, agent overlay, context/usage tracking), and setup/repair tooling to stay operable. Distribution is a Claude Code plugin (.claude-plugin/, agents/, skills/, commands/, hooks/) with 12 translated READMEs — a mass-market product posture, versus ZO's single-team platform posture. + +### Weaknesses + +- Self-improvement claims are unverified in-repo: the SWE-bench vanilla-vs-OMC harness exists but results/README.md is an empty template, and the only committed run data is a 5-instance smoke test where OMC failed 5/5 (vanilla 5/5) — benchmark/predictions/omc/stats.json. Agent-prompt benchmark baselines are explicit zero placeholders. +- Significant aspirational/dead code presented as capability: src/features/model-routing (signal-based complexity router with escalation), src/verification/tier-selector.ts, and src/features/task-decomposer are exported but have zero runtime callers — actual model routing and verification tiering are prompt-convention only. +- Completion verification outside autoresearch is LLM-judged, not oracle-grade: detectArchitectRejection() matches rejection via brittle regexes over free text; approvals force-accept after 3 failed verification attempts, so a persistently failing verifier silently converts to a pass. +- Complexity is at the edge of maintainability: 337K LOC of TS in src/, a 1,114-line keyword detector whose bulk is multilingual false-positive suppression (fundamental fragility of magic-keyword UX), and a stop-decision path whose correctness depends on ~10 interacting circuit breakers accreted from production incidents. +- The stop-blocking design generated repeated production failure loops before the guards existed (context-limit deadlocks, rate-limit retry loops, auth loops) — evidence that hard-blocking Stop events is intrinsically hazardous and each new stop-context type is a new failure mode. +- geobench/ is marketing tooling (LLM answer share-of-voice for the project itself) living in the repo under a name that suggests quality benchmarking. +- Named autopilot workflow profiles (the most rigorously engineered stage-advancement path) are Linux-only (flock, no-follow fd traversal) and defer model routing, making the flagship v1 feature unavailable to macOS-default Claude Code users. +- The 'team' magic keyword had to be permanently disabled after causing infinite recursive worker spawning — keyword-triggered heavy orchestration proved unsafe for any prompt text that can reach workers. + +### Notable Files + +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/persistent-mode/index.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/keyword-detector/index.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/ralph/loop.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/ralph/verifier.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/ralph/prd.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/autopilot/types.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/autopilot/enforcement.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/team-pipeline/types.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/team/heartbeat.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/team/role-router.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/team/runtime-v2.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/task-size-detector/index.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/autoresearch/contracts.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/lib/security-config.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/ralph/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/autopilot/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/team/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/ultrawork/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/autoresearch/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/hooks/hooks.json` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/CLAUDE.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/benchmark/results/README.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/benchmarks/shared/types.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/agents/critic.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/agents/executor.md` + +## Lens: components + +### Summary + +OMC is a large (v4.15.7, ~3.7k GitHub PRs/issues referenced in commits) Claude Code plugin implementing multi-agent orchestration through four interlocking component types: 19 markdown agent personas, 41 skills, 28 slash commands, and lifecycle hooks, all backed by a TypeScript runtime (src/, compiled to dist/) that is dual-distributed as both an npm package (bin: omc) and a Claude Code marketplace plugin. The component taxonomy is real and deliberate: agents are organized into 4 "lanes" (Build/Analysis, Review, Domain, Coordination) with a canonical workflow (explore → analyst → planner → critic → executor → verifier); skills carry a 1–7 "level" tier in frontmatter and compose via an explicit inclusion algebra (ultrawork ⊂ ralph ⊂ autopilot) documented in every skill's Use_When/Do_Not_Use_When sections; commands are deliberately thin dispatch shims that exist purely to save context tokens. + +The design philosophy is "behavior injection over agent swapping": skills modify how the orchestrator operates (an Execution layer + 0-N Enhancement layers + optional Guarantee layer like ralph's can't-stop loop), activated by three channels — slash commands, hook-detected magic keywords ("ralph", "ultrawork", "autopilot" in natural language), and a skill-injector hook that recursively loads user/project learned skills. The most sophisticated engineering is invisible in the README: a tested context-budget system (64KB total / 2KB per skill) that compacts full SKILL.md bodies into registry shims at plugin install time, machine-checked per-stage deliverable contracts enforced by a SubagentStop hook, hash-validated user-defined workflow profiles constrained to whitelisted stage sequences, and a mission/sandbox evaluator contract (JSON pass/score, sealed benchmark files) that is a close cousin of ZO's oracle concept. + +Verification of claims: the marketplace metadata ("28 agents, 32 skills") is stale — actual counts are 19 agent .md files and 41 SKILL.md dirs, and the README itself says 19. The LOW/MEDIUM/HIGH tier-variant agent system described in docs/agent-templates (executor-low etc.) is largely vestigial — real tiering now happens via a PreToolUse "delegation enforcer" hook that injects the model parameter into Task calls from agent definitions. The agent benchmark harness (fixtures + ground-truth + shared scorer) exists but is thin (3 ground-truth files for code-reviewer). Everything else inventoried here was verified in source. + +### Key Features + +#### Structured agent persona schema with explicit non-responsibilities and handoff pointers + +- **What:** All 19 agent .md files follow one pseudo-XML schema: Role (including 'You are NOT responsible for X (that's agent Y)'), Why_This_Matters, Success_Criteria, Constraints (with named handoff targets), Investigation_Protocol, Tool_Usage, Execution_Policy, Output_Format. Frontmatter carries name, description, model (haiku/sonnet/opus), level, and disallowedTools (review agents are hard-blocked from Write/Edit). +- **Why special:** Most agent libraries define personas by what they do; OMC defines them equally by what they must NOT do, with an explicit routing pointer for each exclusion ('hand off to critic for plan review'). Combined with a documented role-disambiguation table for the 4 opus-tier agents (architect/analyst/planner/critic), this makes 19 agents composable without overlap. disallowedTools in frontmatter is enforcement, not convention. +- **How it works:** agents/*.md are the source of truth; src/agents/definitions.ts loads them (esbuild injects prompts at build time via __AGENT_PROMPTS__, runtime file-read fallback), applies config-based model overrides, and exposes getAgentDefinitions() to the SDK. 10 deprecated agent names alias to current agents for backward compat. The lead orchestrator prompt (omcSystemPrompt in definitions.ts) carries the full roster with lane groupings. +- **ZO relevance:** Directly adoptable. ZO's specs/agents.md personas would get sharper contract-first boundaries by adding the 'not responsible for (agent X)' cross-reference pattern and Why_This_Matters rationale blocks. The disallowedTools frontmatter (read-only reviewers/oracle) is a mechanical guarantee ZO's oracle agent should have — the verifier that cannot edit is structurally more trustworthy. +- **Evidence:** `agents/architect.md`, `agents/critic.md`, `agents/analyst.md`, `src/agents/definitions.ts`, `src/agents/utils.ts` + +#### Skill composition algebra with level taxonomy (ultrawork ⊂ ralph ⊂ autopilot) + +- **What:** Skills declare a level (1–7) in frontmatter and compose in documented layers: Execution skill + 0-N Enhancement skills + optional Guarantee layer. ultrawork is explicitly 'a component, not a standalone persistence mode'; ralph wraps ultrawork with a PRD-driven persistence loop and reviewer sign-off; autopilot wraps ralph with the full idea-to-code pipeline. Every skill's Do_Not_Use_When section names the neighboring skill to use instead. +- **Why special:** This is the cleanest answer I've seen to 'how do you keep 41 skills from being 41 overlapping monoliths': make inclusion relations explicit in both directions, so the model routing between skills is written into the skills themselves. Level distribution observed: 1=reminders, 2=utilities (cancel/hud/setup), 3=artifact workflows (release/ultraqa/ultragoal), 4=orchestration engines (autopilot/ralph/ultrawork/team/plan/ralplan/self-improve/autoresearch), 5=multi-model (ccg), 7=self-improving (learner/writer-memory). +- **How it works:** skills//SKILL.md with Purpose/Use_When/Do_Not_Use_When/Why_This_Exists/Execution_Policy sections. ARCHITECTURE.md documents the 3-layer formula. Activation via slash command, magic keyword (keyword-detector.mjs UserPromptSubmit hook with priority-ordered hardcoded + configurable triggers), or skill-injector.mjs (recursive discovery of learned skills in .claude/skills, .omc/skills, .agents/skills). +- **ZO relevance:** ZO's skill set (memory:*, gates:*, observe:*, project:*) is heading toward the same sprawl. Adopt: (1) mandatory Use_When/Do_Not_Use_When cross-links naming the alternative skill, (2) an explicit component-vs-workflow distinction so e.g. memory:recall is marked as a component that project:launch includes. Caveat: OMC never documents what the level numbers mean anywhere discoverable — adopt the idea, not the undocumented execution. +- **Evidence:** `skills/ultrawork/SKILL.md`, `skills/ralph/SKILL.md`, `skills/autopilot/SKILL.md`, `docs/ARCHITECTURE.md`, `scripts/keyword-detector.mjs` + +#### Context-budget engineering: compact skill shims + dispatch commands + +- **What:** Two-tier defense against the context tax of a 41-skill library: (1) all 28 commands/*.md are ~15-line dispatch shims with empty descriptions that tell Claude to read the full SKILL.md on demand; (2) at plugin install, compactPluginSkillPayload() archives every full SKILL.md and replaces the registered copy with a ~2KB shim pointing at the archived body, enforced by a vitest gate: 64KB total / 2KB per-file budget across all registered skills. +- **Why special:** This is a genuinely hard-won insight most agent-library authors miss: every registered skill description is a permanent tax on every session's context window, so a large library must actively fight its own weight. OMC made the budget a CI-enforced invariant (plugin-skill-budget.test.ts references issues #2943/#2986), not a style guideline. The lazy-load indirection (shim → full body under a plugin-root-relative path) is ugly but measured. +- **How it works:** commands/*.md say 'read skills//SKILL.md and follow it, treating arguments as $ARGUMENTS'. src/installer/index.ts renderCompactPluginSkillShim() rewrites frontmatter (description preserved, omc-full-body path added) and writes a body instructing Claude to read the archived full skill. Test asserts plugin.json skills array exactly equals skills/ dirs AND total shim bytes under budget. +- **ZO relevance:** High. ZO already has ~25 skills registered and each description loads into every session. Adopt the budget-as-test idea directly: a CI check on total frontmatter-description bytes across .claude/skills and commands, plus thin-shim pattern for rarely-used skills. This is cheap to implement in ZO's validate-docs.sh cascade. +- **Evidence:** `commands/verify.md`, `src/installer/index.ts`, `src/__tests__/plugin-skill-budget.test.ts`, `commands/autoresearch.md` + +#### Machine-checked stage deliverable contracts (templates/deliverables.json + SubagentStop hook) + +- **What:** A JSON contract declaring, per team-pipeline stage, what files the stage must produce with minimum size, required sections, and required regex patterns (e.g. team-plan must yield DESIGN.md ≥500 bytes containing '## File Ownership' and '## Architecture'; team-verify must yield QA_REPORT.md matching \b(PASS|FAIL)\b). The verify-deliverables.mjs hook checks this on SubagentStop. +- **Why special:** This converts 'contract-first spawning' from a prompt-level promise into a mechanically enforced gate — the subagent literally cannot be considered finished if its artifact is missing, too small, or lacks required sections. It's a small file but it's the difference between asking for a deliverable and verifying one. +- **How it works:** hooks/hooks.json registers scripts/... verify-deliverables.mjs on SubagentStop; it reads templates/deliverables.json keyed by pipeline stage (team-plan/team-prd/team-exec/team-verify/team-fix) and validates the produced files. +- **ZO relevance:** Very high — this is ZO's contract-first principle, mechanized. ZO defines agent interfaces before spawning but (per its specs) verifies via the oracle at phase level. Adding a per-agent deliverable schema (files + requiredSections + patterns) checked by a SubagentStop hook would catch contract violations at spawn granularity, before the oracle phase gate. Trivially portable: it's one JSON file + one hook script. +- **Evidence:** `templates/deliverables.json`, `hooks/hooks.json`, `scripts/verify-deliverables.mjs` + +#### Mission/sandbox evaluator contract (autoresearch) — OMC's oracle analog + +- **What:** Missions are mission.md (goal) + sandbox.md (YAML frontmatter declaring evaluator.command, evaluator.format=json, optional keep_policy of score_improvement|pass_only) pairs. The autoresearch skill runs a bounded single-mission improvement loop where evaluator output MUST be JSON with a required boolean `pass` and optional numeric `score`; non-passing iterations continue; stop conditions are explicit (max-runtime). Contract violations are hard errors parsed in src/autoresearch/contracts.ts. The sibling self-improve skill adds tournament selection across N executor candidates, sealed benchmark files (validate.sh prevents the loop from modifying its own evaluation), plateau detection, and circuit breakers. +- **Why special:** This is a strictly-typed, tamper-resistant version of 'hard verifiable success metric'. The sealed-files rule (the improvement loop cannot edit the benchmark) and keep_policy semantics (only keep changes that improve score) are exactly the anti-Goodhart mechanics an autonomous improvement loop needs, and they are enforced in code, not prose. +- **How it works:** src/autoresearch/contracts.ts validates sandbox.md frontmatter with specific error messages per violation; runtime keeps per-iteration evaluation JSON + markdown decision logs under .omc/autoresearch/. self-improve (skills/self-improve/SKILL.md) orchestrates research→plan→architect/critic review→N parallel executors→benchmark→tournament merge via git-master, with state under .omc/self-improve/ (config/goal.md, harness.md guardrail rules H001-H003, iteration history, plan archive). +- **ZO relevance:** ZO's oracle is the same idea; what's worth stealing is the formalization: (1) evaluator output as a strict JSON schema {pass: bool, score?: number} rather than free-form verification, (2) sealed-files enforcement so agents can't touch oracle code — ZO's repo-separation partially covers this but not within the delivery repo, (3) keep_policy as an explicit merge criterion, (4) plateau/circuit-breaker stop conditions for ZO's build loops. The tournament-of-N-executors pattern is also a candidate for ZO's hardest subtasks. +- **Evidence:** `skills/autoresearch/SKILL.md`, `src/autoresearch/contracts.ts`, `skills/self-improve/SKILL.md`, `missions/optimize-omc/sandbox.md` + +#### Delegation Enforcer: hook-based model routing instead of prompt-trusted routing + +- **What:** A PreToolUse hook (pre-tool-enforcer.mjs) that intercepts Task/Agent calls and auto-injects the model parameter from the agent's definition when the orchestrator omitted it, so model routing is guaranteed rather than dependent on the orchestrator remembering. +- **Why special:** Recognizes that Claude Code does not automatically apply per-agent model defaults on Task calls, and that trusting the orchestrator prompt to always pass model= is a silent cost/quality bug (forgotten params default to the expensive parent model). Turning routing policy into middleware is the correct architectural move. Complemented by a cross-provider Model × Agent compatibility matrix doc encoding rules like 'planning/review = expensive, implementation = cheap (5-20x token weight difference)' and 'agent X breaks with GPT-family tool calling'. +- **How it works:** hooks/hooks.json wires scripts/pre-tool-enforcer.mjs on PreToolUse matcher *; agent default models come from agents/*.md frontmatter via the TS registry; docs/DELEGATION-ENFORCER.md describes the injection; scripts/lib/agent-model-config.mjs and model-routing-override-message.mjs support overrides. +- **ZO relevance:** ZO's specs/agents.md defines model tiers per agent but (as a spec) relies on the lead orchestrator honoring them. A PreToolUse hook that validates/injects model per agent — and blocks spawns violating tier policy — would make ZO's routing self-enforcing. Also adopt the matrix's budgeting rule of thumb: spend on rare decisive calls (planner/oracle), economize on high-volume executor calls. +- **Evidence:** `docs/DELEGATION-ENFORCER.md`, `scripts/pre-tool-enforcer.mjs`, `docs/agents/model-compatibility.md`, `scripts/lib/agent-model-config.mjs` + +#### Skillify: session-to-skill extraction with a quality gate + +- **What:** A meta-skill that turns a workflow discovered during a session into a reusable skill draft, gated by three tests that ALL must pass: not Googleable in 5 minutes, specific to this codebase/workflow, and required real debugging/design effort to discover. Extracted skills are stored in user/project skill dirs and re-injected into future sessions by the skill-injector hook. +- **Why special:** The quality gate is the notable part — it prevents the failure mode where a self-improving system accumulates hundreds of trivial 'skills' that are really documentation. The learner skill (its predecessor) even separates a self-updatable Expertise section from a stable Workflow section, with explicit BAD/GOOD examples distinguishing principle-extraction from snippet-mimicking. +- **How it works:** skills/skillify/SKILL.md defines the gate and requires frontmatter-complete skill files written to flat file-backed paths; scripts/skill-injector.mjs (UserPromptSubmit) recursively discovers and injects learned skills with per-session caps (MAX_SKILLS_PER_SESSION, descriptor char limits). +- **ZO relevance:** Maps directly onto ZO's PRIORS.md self-evolution protocol. ZO's 'add a prior after every failure' rule has no quality gate — adopting skillify's three-question filter (non-Googleable / project-specific / hard-won) would keep PRIORS.md high-signal as it grows. The injection caps (max N learned items per session, char budgets) are also relevant to keeping ZO's memory-priming lean. +- **Evidence:** `skills/skillify/SKILL.md`, `skills/learner/SKILL.md`, `scripts/skill-injector.mjs` + +#### Whitelisted workflow profiles with hash-validated descriptors + +- **What:** Users can define named autopilot workflows in .claude/omc.jsonc / user config, but stage sequences are constrained to exactly four approved compositions ([ralplan, execution], [ralplan, execution, ralph], [ralplan, execution, qa], [ralplan, execution, ralph, qa]); names are regex-validated with a reserved-name blacklist; the selected profile becomes a canonical-JSON sha256-hashed descriptor validated on every read; runtime support is gated (Linux + flock only). +- **Why special:** An unusually disciplined take on extensibility: instead of letting users compose arbitrary stage graphs (which would explode the test matrix), OMC whitelists the sequences it has actually verified. The tamper-evident descriptor hashing and the paranoid transcript reader (O_NOFOLLOW path walking, stat-before/after identity checks, bounded JSONL records) show state-integrity engineering rare in prompt-orchestration projects. +- **How it works:** scripts/lib/workflow-profile-runtime.mjs: SEQUENCES frozen whitelist, validateDefinitions() with reserved names, selectWorkflowProfile() producing hash-stamped descriptors, resolveWorkflowStagePrompt() only for hash-valid state; consumed by keyword-detector.mjs on /autopilot --workflow invocations. +- **ZO relevance:** ZO's workflow.md phases + gates are a fixed pipeline today. When ZO adds configurable pipelines (e.g., per-project phase subsets), copy the whitelist-plus-hash approach: enumerate approved phase sequences rather than allowing arbitrary DAGs, and stamp the chosen profile into STATE.md with a hash so mid-project tampering or drift is detectable — this aligns with ZO's oracle drift-detection goals. +- **Evidence:** `scripts/lib/workflow-profile-runtime.mjs`, `scripts/lib/workflow-stage-prompts.mjs`, `scripts/keyword-detector.mjs` + +#### Agent prompt benchmark harness (regression tests for personas) + +- **What:** benchmarks/ contains per-agent benchmark suites (code-reviewer, debugger, executor, harsh-critic) with code fixtures, ground-truth JSON (e.g. known findings in code-sql-injection.json), a shared scorer (finding-matching + aggregation, harsh-critic scorer as reference implementation), runner, and baselines dir. +- **Why special:** Treats agent persona prompts as testable software: change the critic's prompt, re-run the benchmark, compare found-vs-ground-truth findings against a baseline. Almost nobody regression-tests their prompt library. Caveat: coverage is thin (3 ground-truth files for code-reviewer), so this is more proof-of-pattern than mature infrastructure. +- **How it works:** benchmarks/shared/{runner,scorer,parser,reporter}.ts + benchmarks//{fixtures,ground-truth,prompts,run-benchmark.ts}; run-all.ts orchestrates; baselines/ stores prior scores. +- **ZO relevance:** ZO evolves its own rules and agent specs after every failure (self-evolution protocol) but has no way to know whether a rule edit made agents better or worse. A ground-truth benchmark per critical agent (especially ZO's oracle and reviewer personas) would let the self-evolution protocol verify its own edits — closing the loop ZO's evolution.md aspires to. Start with the same shape: fixtures + expected-findings JSON + scorer. +- **Evidence:** `benchmarks/shared/scorer.ts`, `benchmarks/code-reviewer/run-benchmark.ts`, `benchmarks/code-reviewer/ground-truth/code-sql-injection.json`, `benchmarks/run-all.ts` + +#### Dual distribution with generated-closure verification and version sync + +- **What:** One repo ships as an npm package (bin: omc/oh-my-claudecode, compiled dist/ + bridge/ bundles) and as a Claude Code plugin (.claude-plugin/plugin.json listing all 41 skill dirs, commands dir, and .mcp.json MCP server). scripts/sync-version.sh (npm version lifecycle hook) syncs the version into plugin.json, marketplace.json, and a docs/CLAUDE.md marker; scripts/plugin-shipping-surface.mjs computes the exact generated-file closure from entrypoints and CI commits 'authorize exact generated closure' for each PR; compose-docs.mjs assembles docs from {{INCLUDE:}} partials copied to docs/shared for skills to reference. +- **Why special:** The generated-closure verifier is the standout: because the plugin checkout must carry built artifacts, they made 'which generated files are legitimate' a computed, CI-authorized set starting from entrypoints — preventing both stale bundles and smuggled files. Version sync via lifecycle hook plus tests asserting plugin.json == skills/ dirs is the automated version of ZO's manual cascade rules. +- **How it works:** package.json files whitelist; sync-version.sh perl-patches satellite files and stages them into the version commit; plugin-shipping-surface.mjs resolves module graphs with the TS compiler API; src/__tests__/plugin-skill-budget.test.ts asserts registry completeness. +- **ZO relevance:** ZO's CLAUDE.md cascade chains (agent added → update 6 files) are enforced by validate-docs.sh + a commit-blocking hook, which is philosophically identical but manual-update-then-verify. OMC shows the next step: generate or sync satellites from a single source (version sync script) and assert registry==filesystem in tests, so most cascade steps become impossible to forget rather than checked after the fact. The count-drift OMC still suffers (marketplace says 28 agents/32 skills vs actual 19/41) is exactly the failure ZO's cascade discipline exists to prevent — evidence that verification must cover marketing metadata too. +- **Evidence:** `scripts/sync-version.sh`, `scripts/plugin-shipping-surface.mjs`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `scripts/compose-docs.mjs` + +#### Full lifecycle-event hook lattice (11 events) with persistence and drift guards + +- **What:** hooks/hooks.json wires node scripts to UserPromptSubmit (keyword detection, skill injection), SessionStart (memory load, setup/maintenance matchers), PreToolUse (delegation enforcement), PermissionRequest (bash permission handling), PostToolUse (+failure variant), SubagentStart/Stop (tracking, deliverable verification), PreCompact (notepad save, project-memory save), Stop (context-guard, workflow-drift-guard, persistent-mode 'the boulder never stops', optional auto code-simplifier), SessionEnd (async session summary, wiki update). +- **Why special:** OMC uses hooks as the enforcement plane for everything its prompts promise: persistence modes survive because a Stop hook refuses to let the session end; memory survives compaction because PreCompact hooks snapshot to .omc/notepad.md; workflow drift is caught by a dedicated Stop-time guard. The prompt says 'never stop', but the hook makes it true. Escape hatches exist (DISABLE_OMC=1, OMC_SKIP_HOOKS). +- **How it works:** All hooks route through scripts/run.cjs wrapper with per-hook timeouts; state lives under .omc/ split into control plane (.omc/state/**) vs data plane (plans/notepads/prompts) with an explicit artifact-descriptor + bounded-handoff rule for large payloads (documented in ARCHITECTURE.md). +- **ZO relevance:** ZO uses one PreToolUse hook (commit blocking on validate-docs.sh). The gap: ZO's 'AUTOMATIC memory protocol' (STATE.md at session end, priors after failures) is prompt-enforced only. Porting three hooks would mechanize it: PreCompact → snapshot STATE.md-relevant context; Stop → refuse stop if session summary/DECISION_LOG not updated; SubagentStop → verify contract deliverables. The control-plane/data-plane split with descriptors instead of inline payloads is also a good pattern for ZO's comms JSONL logs. +- **Evidence:** `hooks/hooks.json`, `scripts/persistent-mode.mjs`, `scripts/pre-compact.mjs`, `scripts/workflow-drift-guard.mjs`, `docs/ARCHITECTURE.md` + +### Architecture Notes + +Component model: four types with distinct contracts. (1) Agents = markdown personas (agents/*.md, single source of truth) mirrored by a TS registry (src/agents/definitions.ts) that build-injects prompts via esbuild define (__AGENT_PROMPTS__) with runtime file-read fallback — so the same persona works in plugin mode, npm CLI mode, and SDK mode. (2) Skills = directories with SKILL.md, self-describing activation conditions (Use_When/Do_Not_Use_When), composition level in frontmatter. (3) Commands = pure dispatch shims to skills (token-cost indirection). (4) Hooks = the enforcement plane; ~25 node scripts on 11 lifecycle events, all routed through run.cjs with timeouts. + +Layering: the orchestrator lives in the main session (system prompt appended, ALL-CAPS persistence rhetoric — the older prompt generation), skills mutate its behavior, agents execute via Task with model injected by hook middleware. State is filesystem-first under .omc/ with an explicit control-plane (small JSON state) vs data-plane (plans, notepads, prompts, artifacts) split and a documented artifact-descriptor schema (kind/path/hash/producer/retention) for bounded handoffs — the same problem ZO's comms.md addresses. + +There are visibly two generations of design in the repo: an older template-based tier-variant system (docs/agent-templates with {{TIER_INSTRUCTIONS}} injection, executor-low/-medium/-high naming, stale model names) that is now vestigial, and the current single-persona-plus-model-routing system. Deprecated names are kept as aliases everywhere (10 agent aliases, learner→skillify, swarm removed with PR reference) — heavy backward-compat discipline consistent with a plugin that has thousands of external users. Cross-CLI escape hatches exist throughout: team workers can be Codex/Gemini/Antigravity CLIs, ralplan can route architect/critic passes to Codex (--architect codex), ccg fans out to three model vendors — the component system treats non-Claude models as pluggable workers within Claude-orchestrated pipelines. + +Scale management is the meta-lesson: with 41 skills and 19 agents, OMC's biggest engineering investments are in (a) context-budget enforcement, (b) discoverability (omc-reference skill, ARCHITECTURE.md decision tables, magic keywords so users never memorize the taxonomy), and (c) registry==filesystem test gates. The taxonomy teaches that lanes (grouping by pipeline position) beat flat rosters, and inclusion algebra beats feature lists for overlapping workflow skills. + +### Weaknesses + +- Metadata count drift: .claude-plugin/marketplace.json advertises '28 agents, 32 skills' while the repo actually contains 19 agent .md files and 41 SKILL.md dirs (README correctly says 19) — the marketing surface is not covered by the otherwise strict registry tests. +- The skill 'level' (1–7) frontmatter taxonomy is undocumented anywhere discoverable; levels 5 and 6 are nearly/completely unused, and the meaning must be reverse-engineered from one sentence inside the deprecated learner skill ('Level 7 = self-improving'). +- The LOW/MEDIUM/HIGH tier-variant agent template system (docs/agent-templates/, executor-low examples, stale model IDs like claude-opus-4-8/claude-sonnet-4-5) is vestigial — actual routing moved to frontmatter model + delegation-enforcer hook, but the docs still teach the old flow. +- Skill sprawl with overlapping persistence/looping modes (ralph vs ultragoal vs autopilot vs team+ralph vs self-improve vs autoresearch vs ultraqa): each pair is disambiguated in prose, but the cognitive load is high and the disambiguation burden falls on Do_Not_Use_When paragraphs rather than structural simplification. +- missions/ in the repo root contains near-empty dogfooding artifacts (mission.md files with 2-3 words) committed to the public repo — the mission format is real (autoresearch contract) but these files are noise, and nothing in-repo consumes the missions/ directory itself. +- Two generations of prompt style coexist: the orchestrator system prompt uses threat-style ALL-CAPS prompting ('VIOLATION IS FAILURE', 'saying complete without verification is a LIE') while the newer agent .md files use evidence-based structured personas — an unreconciled internal inconsistency. +- Agent benchmarks are proof-of-pattern, not coverage: only 3 ground-truth fixtures for code-reviewer, 4 agent suites total for 19 agents; persona changes for the other 15 agents ship untested. +- Duplication between templates/hooks/*.mjs and scripts/*.mjs hook implementations creates a second copy of hook logic to keep in sync. +- Deep platform coupling for advanced features: workflow profiles hard-require Linux + /usr/bin/flock; several state-integrity paths depend on /proc/self/fd — degrading silently on macOS where much of the audience runs. + +### Notable Files + +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/docs/ARCHITECTURE.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/agents/critic.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/agents/architect.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/agents/definitions.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/ralph/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/ultrawork/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/autopilot/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/self-improve/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/autoresearch/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/skillify/SKILL.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/autoresearch/contracts.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/templates/deliverables.json` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/hooks/hooks.json` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/scripts/keyword-detector.mjs` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/scripts/lib/workflow-profile-runtime.mjs` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/installer/index.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/__tests__/plugin-skill-budget.test.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/docs/DELEGATION-ENFORCER.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/docs/agents/model-compatibility.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/docs/agent-templates/tier-instructions.md` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/benchmarks/shared/scorer.ts` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/scripts/sync-version.sh` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/scripts/plugin-shipping-surface.mjs` +- `/Users/sam101fe4x/Documents/code/oh-my-claudecode/commands/verify.md` + +## Lens: runtime-ux + +### Summary + +oh-my-claudecode (OMC, npm package `oh-my-claude-sisyphus` v4.15.7) is a large, mature Claude Code plugin providing multi-agent orchestration with an unusually deep runtime-UX layer. Through the runtime-ux lens, its design philosophy is: (1) the session must never silently stall — a Stop-hook engine blocks premature stops while work remains, with an extensive taxonomy of escape hatches learned from production incidents; (2) the operator should never wonder what's happening — a rich HUD statusline surfaces mode/iteration/agents/context/rate-limits, and multi-channel notifications (Discord/Telegram/Slack) with a two-way reply-injection daemon allow remote monitoring and control of unattended sessions; (3) state must survive every lifecycle boundary — compaction, session end, crashes, plugin updates — via hook-enforced persistence (project memory, wiki, notepad, boulder plan state) rather than trusting the model to follow a protocol. + +The engineering quality of the guardrails is the standout. Every anti-stall mechanism carries circuit breakers (bounded retries, TTL'd counters, thinking-only-streak bailouts, tombstoned mode state from crashed sessions), and the code cites the specific GitHub issue each safeguard answers: compaction deadlock (#213), rate-limit infinite retry (#777), auth-failure loops (#1308), recursive team spawning (keyword disabled), SubagentStop context reinjection (#3209). Team mode gets a genuinely distributed-systems treatment: per-worker heartbeat files, freshness checks by the lead, bounded tmux idle nudges, process-identity locks (PID+start-time), and worker restart/recovery sagas. A rate-limit-wait daemon auto-resumes blocked sessions when limits reset — solving the single biggest killer of overnight autonomous runs. + +Verified as implemented: the entire hook chain in hooks/hooks.json wired through scripts/*.mjs to compiled TypeScript, the HUD with ~30 element renderers and installer integration, the notifications stack including a hand-rolled Slack Socket Mode client with HMAC verification, heartbeat/idle-nudge machinery, and the permission auto-allow handler. Flagged as aspirational/dead: src/hooks/recovery/ (context-window/session/edit-error recovery) and src/hooks/thinking-block-validator/ are ports from oh-my-opencode targeting hook points (onError, experimental.chat.messages.transform) that do not exist in Claude Code's hook system — they are exported as library code but wired to no hooks.json event; actual failure recovery flows through the PostToolUseFailure -> Stop-hook retry-guidance path instead. preemptive-compaction also self-describes as a 'simplified version' that only injects warnings versus the original's automatic summarization. + +### Key Features + +#### Persistent-mode Stop-hook engine (anti-stall core) + +- **What:** A Stop-event interceptor that refuses to let the session go idle while work remains: Ralph loops, autopilot, ultrawork, team pipeline, active skills, and plain incomplete todos all block the stop and inject a continuation prompt, in a strict authority/priority order. +- **Why special:** Not the blocking itself (trivial) but the escape-hatch taxonomy hardened over ~4 years of issues: never block context-limit stops (compaction deadlock, #213), rate-limit stops (infinite 429 retry loop, #777), auth failures (#1308), user aborts, explicit /cancel (with cancel-race protection), scheduled wakeups, or oversize-tool-result redirect stops (bounded window of 3). Circuit breakers everywhere: max 5 todo-continuation attempts, a thinking-only streak guard that detects the model burning blocked stops on thinking-only turns and bails out, stop-breaker counters with TTLs, 2h stale-state thresholds, and a workflow-slot ledger with tombstones so stale mode files from crashed sessions cannot re-arm enforcement. +- **How it works:** hooks.json Stop event -> scripts/persistent-mode.mjs -> checkPersistentModes() in src/hooks/persistent-mode/index.ts (2,564 lines). Reads StopContext (stop_reason strings pattern-matched by isUserAbort/isContextLimitStop/isRateLimitStop/isAuthenticationError in src/hooks/todo-continuation/index.ts), consults a skill-active-state ledger (resolveAuthoritativeWorkflowSkill) so nested workflows (autopilot->ralph) escalate to the live parent, then returns {continue:false, message} to hard-block. applyThinkingOnlyStreakGuard() classifies the last assistant turn from the transcript and releases the stop after N thinking-only turns. +- **ZO relevance:** Directly actionable: ZO just committed a watchdog/heartbeat anti-stall design spec (297adac). Before implementing it, steal OMC's escape-hatch list wholesale — the categories of stops you must NEVER block (context-limit, rate-limit, auth, user-abort, cancel-in-progress) plus TTL'd circuit breakers and tombstoned state for crashed sessions. Each one is a production incident OMC already paid for. ZO's oracle-first framing pairs well: block the stop only while the oracle says the phase gate is unmet, with these same bypasses. +- **Evidence:** `src/hooks/persistent-mode/index.ts`, `src/hooks/todo-continuation/index.ts`, `scripts/persistent-mode.mjs`, `hooks/hooks.json`, `src/hooks/persistent-mode/stop-hook-blocking.test.ts` + +#### OMC HUD (statusline as operator dashboard) + +- **What:** A full statusline program (`omc hud`) with ~30 composable element renderers: context %, todos with current item, active agent count, ralph/autopilot iteration and phase, background tasks, rate-limit buckets from the usage API, token usage, git repo/branch/status, thinking mode, last tool, a team-mode mission board, and an auto-generated session summary. +- **Why special:** This is the single biggest day-to-day UX differentiator: the operator sees orchestration state (which mode is active, which iteration, how many agents are alive, how close to compaction) at a glance without asking the model. Configurable presets (minimal/focused/full/dense/analytics/opencode), element ordering, maxWidth/wrap, and locale label packs (en, zh-CN). It even spawns a throttled background process to summarize the session for display, with PID-liveness guards against process accumulation. +- **How it works:** Claude Code statusline stdin JSON -> src/hud/index.ts -> parseTranscript + readHudState + omc-state readers (readRalphStateForHud, readAutopilotStateForHud) + usage-api.ts -> render.ts composes elements from src/hud/elements/*. Installer writes/repairs the statusLine entry in settings.json and tags it so non-OMC statuslines are preserved (isOmcStatusLine in src/installer/index.ts). Mission board state (src/hud/mission-board.ts) is fed by team/session events with atomic file writes. +- **ZO relevance:** High-value adopt. ZO's observe:watch is a pull-model command; a statusline showing {project alias, current phase, pending gate, oracle status, agents active, context %} would give Sam ambient awareness during long autonomous runs for near-zero cost. The element-renderer + preset architecture is worth copying; the ZO brand system even gives it a visual language. Start small: phase + gate + agent count + context bar. +- **Evidence:** `src/hud/index.ts`, `src/hud/render.ts`, `src/hud/elements/`, `src/hud/mission-board.ts`, `src/installer/index.ts`, `docs/REFERENCE.md` + +#### Two-way remote notifications (Discord/Telegram/Slack reply injection) + +- **What:** Outbound notifications on session-start/stop/end/idle/ask-user-question/agent-call to Discord, Telegram, Slack (webhook and bot), generic webhooks, and tmux — plus a reply-listener daemon that receives human replies on those channels and injects them into the correct tmux pane, turning a phone into a remote control for an unattended session. +- **Why special:** Genuinely implemented two-way remote operation, not just fire-and-forget pings. The reply path is security-engineered: 0600 state files, bot tokens kept out of env, two-layer input sanitization, pane verification before injection, per-user authorization, rate limiting, and a hand-rolled Slack Socket Mode client with HMAC signature verification and replay-attack windows rather than a heavy SDK. Idle notifications have a cooldown so a stalled session pings you once, not sixty times. +- **How it works:** src/notifications/dispatcher.ts (all sends non-blocking with 10s/15s timeouts, failures swallowed), config.ts + presets.ts (including an OpenClaw gateway preset), template-engine.ts with redact.ts. Reply side: src/notifications/reply-listener.ts daemon polls Discord/Telegram and holds a Slack Socket Mode WebSocket (src/notifications/slack-socket.ts), maps message IDs to sessions via session-registry.ts, and injects via tmux send-keys. Idle-notification gating lives in persistent-mode (shouldSendIdleNotification/recordIdleNotificationSent). +- **ZO relevance:** Strong fit for ZO's unattended-run model: gate approvals are the obvious use case — when a phase gate goes pending, notify Slack/Telegram; the human replies 'approve'/'reject: reason' and the reply-listener injects /gates:approve into the session. The idle-notification-with-cooldown pattern also belongs in ZO's watchdog spec. Caveat: the injection path is tmux-only; ZO would need the same constraint or a different transport. +- **Evidence:** `src/notifications/dispatcher.ts`, `src/notifications/reply-listener.ts`, `src/notifications/slack-socket.ts`, `src/notifications/session-registry.ts`, `src/notifications/presets.ts` + +#### Rate-limit auto-resume daemon + +- **What:** A background daemon that polls rate-limit status every minute, scans tmux panes for Claude Code sessions blocked on a rate limit, and sends the resume keystroke sequence when the limit resets — so an overnight run continues instead of sitting dead until morning. +- **Why special:** Solves the most common real-world killer of long autonomous runs (5-hour rate-limit windows) with zero human involvement. Complements the Stop-hook side, which deliberately refuses to loop-retry on 429 and instead pauses Ralph with a visible message. +- **How it works:** src/features/rate-limit-wait/daemon.ts (spawned detached, PID file + 0600 perms + 1MB log rotation), rate-limit-monitor.ts checks status, tmux-detector.ts scans panes for blocked prompts and sends resume sequences. Process liveness via src/platform process-identity checks (PID + start time) to avoid acting on recycled PIDs. +- **ZO relevance:** Adopt for ZO's long ML training/build phases. ZO's watchdog spec should distinguish 'stalled because stuck' (nudge/restart) from 'stalled because rate-limited' (wait for reset, then resume) — OMC implements exactly this split: persistent-mode pauses on 429, daemon resumes on reset. +- **Evidence:** `src/features/rate-limit-wait/daemon.ts`, `src/features/rate-limit-wait/rate-limit-monitor.ts`, `src/features/rate-limit-wait/tmux-detector.ts` + +#### Context-lifecycle guardrails (guard-stop, preemptive compaction, pre-compact persistence, notepad) + +- **What:** A set of hooks that manage the context window as a first-class resource: a Stop hook that suggests session refresh above 75% usage (max 2 blocks, never blocks context-limit stops), PostToolUse warnings at 70%/90% with cooldowns and rapid-fire debounce for concurrent subagent floods, PreCompact hooks that persist project memory and wiki state before compaction destroys it, and a three-tier compaction-resilient notepad (Priority Context <=500 chars always reloaded; Working Memory auto-pruned after 7 days; MANUAL never pruned). +- **Why special:** Treats compaction as a survivable lifecycle event rather than a catastrophe. The notepad tiering is a clean, simple design for what survives context resets; the PreCompact hook point is the key mechanism ZO currently doesn't use at all. +- **How it works:** scripts/context-guard-stop.mjs (threshold via OMC_CONTEXT_GUARD_THRESHOLD, retry-guard file capping blocks at 2 per transcript, worktree-aware transcript path repair); src/hooks/preemptive-compaction/index.ts (500ms rapid-fire debounce, per-session warning state); hooks.json PreCompact -> pre-compact.mjs + project-memory-precompact.mjs + wiki-pre-compact.mjs; src/hooks/notepad/index.ts with file locks and atomic writes. +- **ZO relevance:** ZO's memory protocol (STATE.md at session start/end) has a blind spot: mid-session compaction. A PreCompact hook that flushes current phase/decisions to STATE.md before compaction would close it. The notepad's 'Priority Context always reloaded, size-capped' tier is a better-engineered version of what ZO wants STATE.md's header to be — adopt the size cap and auto-prune discipline. +- **Evidence:** `scripts/context-guard-stop.mjs`, `src/hooks/preemptive-compaction/index.ts`, `src/hooks/notepad/index.ts`, `scripts/pre-compact.mjs`, `hooks/hooks.json` + +#### Team-mode watchdog: heartbeats, idle nudges, worker restart sagas + +- **What:** For multi-agent team mode (workers in tmux panes): each worker writes a heartbeat file every poll cycle; the lead checks freshness to detect dead workers; idle panes (prompt visible, no active task) get up to 3 tmux send-keys nudges after 30s ('Continue working... report concrete progress (not ACK-only)'); dead workers go through restart/recovery sagas with task checkpoints. +- **Why special:** This is a real distributed-systems treatment of agent liveness: atomic heartbeat writes, process-identity locks (PID + start-time so a recycled PID isn't mistaken for a live worker), owner epochs, recovery checkpoints, and a nudge tracker with per-pane budgets. Most agent frameworks have nothing between 'spawn' and 'hope'. +- **How it works:** src/team/heartbeat.ts (heartbeat files under .omc/state/team-bridge/{team}/), src/team/idle-nudge.ts (paneLooksReady && !paneHasActiveTask => nudge via tmux-session.ts), src/team/worker-health.ts, worker-restart.ts, recovery-saga.ts, task-recovery-checkpoint.ts, process-identity-lock.ts, team-owner-epoch.ts. Wired through the team MCP bridge (bridge/team-mcp.cjs, src/mcp/team-server.ts) during omc_run_team_wait polling. +- **ZO relevance:** This is the reference implementation for ZO's freshly-specced watchdog/heartbeat system (297adac). The specific patterns to port: heartbeat-file freshness as the liveness primitive (works with ZO's file-based memory philosophy), idle detection requiring BOTH 'ready prompt' AND 'no active task', bounded nudge budgets before escalating to restart, and process-identity (PID+start-time) checks before any kill/restart decision. +- **Evidence:** `src/team/heartbeat.ts`, `src/team/idle-nudge.ts`, `src/team/worker-restart.ts`, `src/team/recovery-saga.ts`, `src/team/process-identity-lock.ts`, `src/team/worker-health.ts` + +#### Verification-at-stop guards (workflow-drift-guard + verify-deliverables) + +- **What:** Two cheap, deterministic 'did you actually finish?' checks: a Stop hook that blocks when the last assistant message claims completion ('done/fixed/ready to merge') while the diff contains .skip/.only tests, TODO-implement placeholders, or 'throw new Error(NotImplemented)'; and a SubagentStop hook that verifies completing agents actually produced their configured deliverable files with minimum content (advisory, non-blocking). +- **Why special:** Hook-level, zero-LLM-cost lie detection. It catches the classic failure mode — agent declares victory over stubs — before any expensive verification runs. Deliberately fails open on ambiguity and (after regression #3209) never emits additionalContext on SubagentStop because that context gets reinjected into the finishing subagent. +- **How it works:** scripts/workflow-drift-guard.mjs (regex COMPLETION_CLAIM_RE on last_assistant_message + BLOCKER_PATTERNS scan over changed code files via git, returns decision:'block' with evidence); scripts/verify-deliverables.mjs (loads .omc/deliverables.json or templates/deliverables.json, path-traversal-sanitized existence/size checks). +- **ZO relevance:** Perfect complement to ZO's oracle: the oracle is the expensive tier-N gate; these are tier-0 gates that run on every stop for free. ZO's contract-first spawning already defines agent deliverables — verify-deliverables is literally 'check the contract's output files exist', which ZO could wire into SubagentStop today. The drift guard maps to ZO's 'evolution' principle: encode each observed lie pattern as a regex. +- **Evidence:** `scripts/workflow-drift-guard.mjs`, `scripts/verify-deliverables.mjs`, `templates/deliverables.json` + +#### Tool-failure retry guidance loop + +- **What:** PostToolUseFailure hook records every tool failure (tool name, input preview, error, retry count) to session-scoped state; the Stop hook reads it and injects targeted retry guidance instead of a generic 'continue' when re-blocking a stop. +- **Why special:** Turns the anti-stall loop from 'nag harder' into 'nag with a diagnosis'. Retry counts let guidance escalate, and the state is session-scoped so parallel sessions don't cross-contaminate. +- **How it works:** scripts/post-tool-use-failure.mjs writes .omc/state/sessions//last-tool-error-state.json (atomic, session-id validated); src/hooks/persistent-mode/index.ts readLastToolError()/getToolErrorRetryGuidance() folds it into the continuation message. +- **ZO relevance:** Feeds ZO's self-evolution protocol mechanically: PRIORS.md entries currently depend on the model remembering to write them; a PostToolUseFailure hook gives a guaranteed, structured failure feed that a session-end job can distill into priors. Adopt the session-scoped state file pattern verbatim. +- **Evidence:** `scripts/post-tool-use-failure.mjs`, `src/hooks/persistent-mode/index.ts` + +#### Auto-allow permission handler + +- **What:** A PermissionRequest hook that auto-approves a conservative safe-list of read-only/build commands (git status|diff|log, npm/pnpm/yarn lint|build|typecheck, tsc, eslint, prettier, cargo check, ls) and defers everything else to the normal prompt. +- **Why special:** Reduces permission-prompt fatigue without opening injection holes: any command containing shell metacharacters (;&|`$()<> etc.) is refused auto-approval; cat/head/tail were deliberately removed (arbitrary file reads); heredocs only whitelisted for git commit/tag (issue #608: heredoc bodies were being persisted into settings.local.json); it also honors existing settings.json allowlists. +- **How it works:** hooks.json PermissionRequest matcher Bash -> scripts/permission-handler.mjs -> src/hooks/permission-handler/index.ts (SAFE_PATTERNS, DANGEROUS_SHELL_CHARS, SAFE_HEREDOC_PATTERNS, readPermissionStringEntries against settings files). +- **ZO relevance:** Directly reusable for ZO's autonomous phases where permission prompts stall unattended runs. The security posture (metacharacter rejection, no file-read commands, heredoc carve-outs) is the part worth copying rather than reinventing — a naive allowlist is how injection happens. +- **Evidence:** `src/hooks/permission-handler/index.ts`, `scripts/permission-handler.mjs` + +#### Magic-keyword mode activation + +- **What:** UserPromptSubmit hook that pattern-matches user prompts for mode keywords (ralph, autopilot/'build me an app', ulw/ultrawork, tdd, code review, deepsearch, ask codex/gemini/cursor) — including Korean and Japanese variants — and injects the corresponding mode activation into context, plus task-size classification to auto-scale effort. +- **Why special:** Zero-ceremony mode entry ('just say ralph'). The scars are instructive: the 'team' keyword is a never-match placeholder because worker prompts containing the word 'team' caused infinite recursive spawning; code fences are stripped to prevent false positives; 'ralph' excludes 'Ralph Lauren' in three languages; explicit slash invocations are parsed separately with path-collision lookaheads. +- **How it works:** scripts/keyword-detector.mjs -> src/hooks/keyword-detector/index.ts (KEYWORD_PATTERNS, KEYWORD_PRIORITY, removeCodeBlocks, KEYWORD_SKIP_PREDICATES, parseExplicitWorkflowSlashInvocation) + src/hooks/task-size-detector. +- **ZO relevance:** Low priority for ZO (single sophisticated operator, explicit skills already exist), but the anti-footgun details matter if ZO ever adds NL triggers: strip code fences, never let keywords that can appear in agent-to-agent prompts trigger spawning (the 'team' incident is exactly the recursive-spawn bug ZO's orchestrator could hit). +- **Evidence:** `src/hooks/keyword-detector/index.ts`, `scripts/keyword-detector.mjs`, `src/hooks/task-size-detector/` + +#### Automatic cross-session memory (project-memory, wiki, boulder, friction report) + +- **What:** Hook-enforced state persistence: project-memory auto-detects project environment at SessionStart and injects a summary (with rescan merging that preserves user directives and hot paths); an LLM wiki (self-maintained markdown KB with ingest/query/lint) hooks SessionStart/SessionEnd/PreCompact; boulder-state persists the active plan across sessions with appended session IDs; session-friction-report mines transcripts for friction signals (error rates >20%, idle gaps >45min, oversized messages) to tell the operator which sessions went badly. +- **Why special:** The persistence is hook-automatic, not protocol-dependent — the model cannot forget to do it, because SessionEnd/PreCompact hooks do it regardless. The friction report is a genuinely novel operator tool: retrospective UX telemetry over your own transcripts. +- **How it works:** scripts/project-memory-session.mjs / -posttool.mjs / -precompact.mjs -> src/hooks/project-memory/* (detector, hot-path-tracker, directive-detector, learner); src/hooks/wiki/* (storage with locks, ingest, lint); src/features/boulder-state/*; src/features/session-friction-report/index.ts scanning transcript JSONL. +- **ZO relevance:** ZO's CLAUDE.md declares memory updates 'AUTOMATIC (NON-NEGOTIABLE)' but enforcement is prompt-protocol plus one commit-blocking hook. OMC shows the stronger pattern: SessionEnd/PreCompact hooks that write state unconditionally. Port that to STATE.md/DECISION_LOG. The friction report concept maps to ZO's retrospectives — mine session transcripts for stall/error signals to feed PRIORS.md with evidence instead of recollection. +- **Evidence:** `src/hooks/project-memory/index.ts`, `src/hooks/wiki/index.ts`, `src/features/boulder-state/index.ts`, `src/features/session-friction-report/index.ts`, `src/hooks/session-end/index.ts` + +### Architecture Notes + +Delivery model: OMC is a Claude Code plugin + npm CLI (package `oh-my-claude-sisyphus`, v4.15.7). Runtime chain: hooks/hooks.json registers every Claude Code hook event -> scripts/run.cjs (cross-platform runner) -> thin scripts/*.mjs shims -> compiled TypeScript in dist/. run.cjs is itself a resilience layer: it launches hooks with process.execPath (no PATH dependence), self-heals a stale CLAUDE_PLUGIN_ROOT by scanning the plugin cache for the newest semver directory after plugin updates, and runs trusted UserPromptSubmit hooks in worker_threads so the runner owns the synchronous timeout boundary. Every hook fails open ({continue:true, suppressOutput:true} on any error), reads stdin with timeout protection, and honors kill switches (DISABLE_OMC, per-hook OMC_SKIP_HOOKS). State layout: per-project .omc/state with session-scoped subdirectories (state/sessions//...), plus a global config dir; all writes go through atomic-write + file-lock helpers; session IDs are regex-validated to block path traversal. Worktree-aware path resolution (resolveToWorktreeRoot, transcript path repair for git worktrees) appears everywhere. Hook events used: UserPromptSubmit, SessionStart (with matcher variants init/maintenance), PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, SubagentStart/Stop, PreCompact, Stop (4 chained hooks), SessionEnd (async). The development style is conspicuously issue-driven: the code cites dozens of GitHub issues inline (#213 compaction deadlock, #777 rate-limit infinite loop, #1308 auth-error loop, #1047 idle nudges, #3209 SubagentStop context reinjection), and each incident became a typed, tested escape hatch — the codebase is effectively a fossil record of every way blocking the Stop event can go wrong. Cost of this maturity: a 2,564-line Stop-hook module, ~30 interacting state files, and multi-MB bundled .cjs artifacts checked into bridge/ (cli.cjs 4MB, mcp-server.cjs 1.1MB). + +### Weaknesses + +- Extreme complexity budget: the Stop-hook module alone is 2,564 lines with ~10 interacting state files (mode files, skill ledgers, tombstones, stop-breakers, cancel signals); the sheer number of escape hatches documents how often hard-blocking Stop events backfired. ZO should treat this as evidence that stop-blocking is a last resort, not a foundation. +- Brittle heuristics at the core: stop-reason classification (isRateLimitStop, isAuthenticationError, isContextLimitStop) is substring matching on undocumented stop_reason strings; workflow-drift-guard's completion-claim detection is regex-on-English. Upstream wording changes silently break the safety layer. +- Dead/aspirational code presented alongside live code: src/hooks/recovery/ and thinking-block-validator are OpenCode ports wired to nonexistent Claude Code hook points; a reader (or LLM) auditing capabilities would overcount what actually runs. +- Heavy tmux coupling: the best operator features (idle nudges, remote reply injection, rate-limit auto-resume, team panes) require tmux; outside it the runtime UX degrades to one-way notifications. +- Anti-stall is prompt-nagging, not progress verification: continuation messages assert 'keep working' with only heuristic checks (todo counts, deliverable file existence, TODO regexes) that work happened — no semantic oracle. The thinking-only streak guard patches the worst case but is itself heuristic. +- Multi-MB bundled .cjs artifacts (bridge/cli.cjs 4MB, mcp-server.cjs 1.1MB, team.js 0.7MB) checked into the repo, plus an npm-root-g NODE_PATH hack at bridge startup — fragile packaging that has clearly needed repair tooling (repair-plugin-cache.mjs, stale-plugin-root recovery in run.cjs). +- Notification reply injection, though carefully sanitized, is still remote text-to-terminal injection gated on chat-platform identity (Discord user ID / Telegram chat ID / Slack channel); a compromised chat account becomes code execution on the host. + +### Notable Files + +- `hooks/hooks.json` +- `scripts/run.cjs` +- `src/hooks/persistent-mode/index.ts` +- `src/hooks/todo-continuation/index.ts` +- `scripts/context-guard-stop.mjs` +- `scripts/workflow-drift-guard.mjs` +- `scripts/verify-deliverables.mjs` +- `scripts/post-tool-use-failure.mjs` +- `src/hooks/permission-handler/index.ts` +- `src/hooks/keyword-detector/index.ts` +- `src/hud/index.ts` +- `src/hud/render.ts` +- `src/hud/mission-board.ts` +- `src/notifications/reply-listener.ts` +- `src/notifications/slack-socket.ts` +- `src/notifications/dispatcher.ts` +- `src/features/rate-limit-wait/daemon.ts` +- `src/team/heartbeat.ts` +- `src/team/idle-nudge.ts` +- `src/team/recovery-saga.ts` +- `src/team/process-identity-lock.ts` +- `src/hooks/notepad/index.ts` +- `src/hooks/preemptive-compaction/index.ts` +- `src/hooks/session-end/index.ts` +- `src/features/session-friction-report/index.ts` +- `src/hooks/recovery/index.ts` +- `src/hooks/thinking-block-validator/index.ts` +- `docs/REFERENCE.md` diff --git a/memory/zo-platform/research/2026-08-12-repo-reviews/ralph.md b/memory/zo-platform/research/2026-08-12-repo-reviews/ralph.md new file mode 100644 index 0000000..83b441b --- /dev/null +++ b/memory/zo-platform/research/2026-08-12-repo-reviews/ralph.md @@ -0,0 +1,108 @@ +# ralph — Deep Dive Findings (2026-08-12) + +## Lens: full + +### Summary + +Ralph (snarktank/ralph, based on Geoffrey Huntley's "Ralph Wiggum" pattern) is a ~113-line bash loop plus two prompt files that turns a single-shot CLI coding agent (Amp or Claude Code) into a long-running autonomous builder. The entire technique: a human-authored PRD is converted (by a skill) into prd.json — a flat list of user stories, each with verifiable acceptanceCriteria, an integer priority, and a boolean `passes` flag. ralph.sh then loops up to MAX_ITERATIONS (default 10), each iteration spawning a COMPLETELY FRESH agent process (`claude --dangerously-skip-permissions --print < CLAUDE.md`, or `cat prompt.md | amp --dangerously-allow-all`) with zero conversational carryover. The prompt tells each fresh instance to: read prd.json, read progress.txt (Codebase Patterns section first), check out the PRD's branch, pick the highest-priority story with passes:false, implement ONLY that story, run the project's quality checks, commit `feat: [ID] - [Title]` only if green, flip passes:true, and append learnings to progress.txt. When the agent observes all stories pass, it emits the literal sentinel `COMPLETE`; the bash loop greps stdout for it and exits 0, else exits 1 at the iteration cap. + +The design philosophy is the inverse of orchestration-heavy systems like ZO: instead of adding roles, contracts, and verification layers at runtime, Ralph pushes ALL intelligence to plan time (story slicing) and ALL state to disk (git history + prd.json + progress.txt + in-repo AGENTS.md files), so the runtime can be trivially dumb. The core insight — stated explicitly in skills/ralph/SKILL.md as "The Number One Rule" — is that each story must be completable within one context window, because the executor has no memory. Fresh context per story structurally eliminates the three classic long-agent failure modes: context rot (every iteration starts clean), state hallucination (all state is re-read from files each time, so confabulated state cannot persist), and compounding errors (each commit is a checkpoint gated by typecheck/tests; "broken code compounds across iterations" is the stated reason for the CI-green rule). That is why such a tiny system reportedly works: the loop IS the context-management strategy, and git IS the checkpoint system. + +What is genuinely implemented: the loop, dual-tool support, sentinel completion detection, archive-on-branch-change lifecycle, the append-only memory protocol, and two well-crafted skills (PRD generation with lettered-option clarifying questions; PRD→prd.json conversion encoding sizing/ordering/verifiability rules). What is NOT implemented despite the framing: any independent verification. The harness never runs a test, never inspects a diff, never validates prd.json — the agent grades its own homework and self-asserts passes:true; the only harness-level check is a grep for a sentinel string. The "dev-browser skill" that browser verification depends on is referenced everywhere but not shipped in this repo (the Claude variant softens it to "if available"). The flowchart/ directory is a React Flow presentation deployed to GitHub Pages — real code, but marketing material, not system capability. + +### Key Features + +#### Fresh-context iteration loop (the Ralph technique core) + +- **What:** A bash for-loop that spawns a brand-new agent process per iteration with clean context, feeding the same static prompt file every time; the prompt makes the agent re-derive all state from disk. +- **Why special:** This is the load-bearing idea and it is genuinely contrarian: rather than keeping one long agent session alive (and fighting context rot, drift, and stale beliefs), it makes statelessness the default and forces all memory through files and git. Iteration N cannot inherit iteration N-1's hallucinations — only its commits and written notes. The runtime harness needs zero intelligence; total harness complexity is ~113 lines of bash. +- **How it works:** ralph.sh lines 84-108: `for i in $(seq 1 $MAX_ITERATIONS)`; per iteration runs `claude --dangerously-skip-permissions --print < CLAUDE.md` (prompt injected via stdin, --print = non-interactive single response) or `cat prompt.md | amp --dangerously-allow-all`, capturing output via `$(... 2>&1 | tee /dev/stderr) || true` so the user sees live streaming while the script greps the transcript. No --continue/--resume flag anywhere: fresh session is deliberate. `sleep 2` between iterations. `set -e` at top with `|| true` on the agent call so agent failures don't kill the loop. +- **ZO relevance:** Directly adoptable as ZO's execution primitive. ZO already does fresh context at phase transitions; Ralph argues for fresh context per SUBTASK, with the plan file as the ledger. ZO's builder agents could be spawned per-plan-item in a loop rather than living across items, with STATE.md/plan.md as the re-read ground truth. This would also make ZO's watchdog/anti-stall problem (see ZO's recent watchdog spec) much smaller: a hung agent costs one iteration, not a session. +- **Evidence:** `ralph.sh`, `CLAUDE.md`, `prompt.md`, `AGENTS.md` + +#### prd.json as machine-checkable task ledger + +- **What:** A flat JSON file of user stories, each with id, title, description, acceptanceCriteria[], integer priority, boolean passes, and a notes field; plus project-level branchName. The passes flags are the entire progress state machine. +- **Why special:** Boolean passes flags make resume, progress inspection, and completion detection mechanical (`jq '.userStories[] | {id, title, passes}'` is the documented debug command). Compare with markdown plans where 'what is done' is prose interpretation. The ledger doubles as the completion oracle input: 'all passes true' is a decidable predicate. +- **How it works:** prd.json.example shows the schema. CLAUDE.md/prompt.md step 4: 'Pick the highest priority user story where passes: false'; step 9: 'Update the PRD to set passes: true for the completed story'. ralph.sh reads only branchName from it (via jq) for archiving. Caveat: passes:true is SELF-ASSERTED by the agent after running whatever checks it chooses — no external process validates it. The notes field exists in the schema but no prompt ever instructs its use (vestigial). +- **ZO relevance:** High. ZO's plan.md (specs/plan.md) is markdown; adding a machine-readable per-subtask status ledger (or generating one from plan.md) would let ZO's continue/build auto-detection and gate logic work off decidable predicates instead of prose parsing. Unlike Ralph, ZO should keep the flag-flipping privilege with the oracle, not the builder — that single change fixes Ralph's biggest hole while keeping the ledger mechanics. +- **Evidence:** `prd.json.example`, `CLAUDE.md`, `prompt.md`, `ralph.sh`, `skills/ralph/SKILL.md` + +#### Context-window-budgeted story sizing ('The Number One Rule') + +- **What:** A hard planning constraint, enforced by the PRD-conversion skill, that every story must be completable by a fresh agent in ONE context window, with concrete right-sized/too-big examples and a 2-3-sentence rule of thumb. +- **Why special:** This is the real scaling law of the system and the most transferable insight: the unit of work is sized to the executor's memory, not to human sprint conventions. 'Add a DB column and migration' = right; 'Add authentication' = split into schema/middleware/login UI/session handling. It converts the vague art of task decomposition into a checkable planning rule, and it is WHY the dumb loop can work — oversized stories are named as the primary failure mode ('the LLM runs out of context before finishing and produces broken code'). +- **How it works:** skills/ralph/SKILL.md sections 'Story Size: The Number One Rule', 'Story Ordering: Dependencies First' (schema → backend → UI, no forward dependencies since execution is strictly serial by priority), 'Acceptance Criteria: Must Be Verifiable' (good: 'Filter dropdown has options: All, Active, Completed'; bad: 'Works correctly'), plus mandatory 'Typecheck passes' on every story and a pre-save checklist. skills/prd/SKILL.md seeds the same structure at PRD-writing time and targets 'junior developer or AI agent' as the reader. +- **ZO relevance:** Directly adoptable into ZO's plan schema validation (specs/plan.md): add a validation rule that each plan subtask fits a single context window and has only machine-verifiable acceptance criteria, with Ralph's good/bad criterion examples as the lint spec. ZO's oracle-first principle already demands verifiable metrics at project level; Ralph shows how to push that discipline down to per-subtask granularity. +- **Evidence:** `skills/ralph/SKILL.md`, `skills/prd/SKILL.md`, `README.md` + +#### Three-channel file memory: progress.txt + Codebase Patterns + in-repo AGENTS.md + +- **What:** Cross-iteration memory via (1) an append-only progress.txt with per-story entries including a mandatory 'Learnings for future iterations' section, (2) a curated '## Codebase Patterns' section promoted to the TOP of progress.txt for general reusable knowledge, and (3) instructions to write directory-local learnings into AGENTS.md/CLAUDE.md files inside the target codebase itself. +- **Why special:** The two-tier split (raw append-only log vs. consolidated patterns at top, read-first) is a compact PRIORS.md. The genuinely clever third channel: putting learnings in per-directory AGENTS.md/CLAUDE.md means every future agent invocation auto-loads them contextually for free — the coding tool's own memory mechanism becomes the knowledge store, benefiting humans and agents alike, with explicit quality gates ('genuinely reusable knowledge' only; do NOT add story-specific details or debugging notes). +- **How it works:** CLAUDE.md/prompt.md 'Progress Report Format' (APPEND, never replace; date/story-id header; learnings subsection with patterns/gotchas/context), 'Consolidate Patterns' (promote general learnings to top section, read it FIRST each iteration per step 2 and the 'Important' footer), 'Update AGENTS.md Files' (identify edited dirs, find nearest AGENTS.md, add module conventions/gotchas/dependencies, with good/bad example lists). The Amp variant also logs the thread URL ($AMP_CURRENT_THREAD_ID) so future iterations can call read_thread on prior sessions. +- **ZO relevance:** ZO already has richer versions (PRIORS.md, DECISION_LOG.md, semantic index), so the log itself is not new. Two adoptable ideas: (a) the read-first consolidated-patterns section — ZO agents should load a small curated PRIORS digest, not the full log; (b) writing learnings into per-directory CLAUDE.md files IN THE DELIVERY REPO so they auto-load contextually. Note the tension with ZO's 'never commit ZO artefacts to target repos' rule — but codebase-convention CLAUDE.md files are arguably delivery-repo content, not ZO artefacts; worth an explicit carve-out decision. +- **Evidence:** `prompt.md`, `CLAUDE.md`, `README.md`, `AGENTS.md` + +#### Sentinel-based completion + hard iteration cap + +- **What:** Termination protocol: the agent emits the literal string COMPLETE only when ALL stories have passes:true; the bash loop greps each iteration's stdout for it (exit 0), otherwise stops at MAX_ITERATIONS (exit 1) pointing the user at progress.txt. +- **Why special:** It is the cheapest possible completion contract between an LLM and a shell script, and it is self-healing in one direction: if the agent finishes the last story but forgets the sentinel, the NEXT fresh iteration sees all passes:true and emits it. The iteration cap is the entire runaway/cost guardrail — a crude but effective bound on drift, loops, and spend. +- **How it works:** ralph.sh lines 98-104 (`grep -q "COMPLETE"` on captured OUTPUT) and 110-113 (cap exhaustion exit 1). CLAUDE.md/prompt.md 'Stop Condition' section defines the emit rule. Fragilities: grep can false-positive if the model quotes its own instructions (the sentinel appears verbatim in the prompt text); there is no timeout on the agent subprocess, so a hung CLI stalls the loop indefinitely; there is no per-story failure counter, so one impossible story silently burns every remaining iteration with no escalation. +- **ZO relevance:** ZO just spec'd a watchdog/heartbeat anti-stall design; Ralph's cap is the degenerate-but-robust version worth keeping as an outer bound regardless of smarter watchdogs: a max-iterations circuit breaker per phase. The sentinel idea maps to ZO gates, but ZO should use structured output or oracle-side predicates ('all plan items verified') rather than grepping model prose — Ralph shows both the pattern and its failure modes. +- **Evidence:** `ralph.sh`, `CLAUDE.md`, `prompt.md` + +#### Archive-on-branch-change run lifecycle + +- **What:** ralph.sh detects when prd.json's branchName differs from the last run's (persisted in a .last-branch dotfile), archives the old prd.json + progress.txt to archive/YYYY-MM-DD-/, and resets progress.txt to a fresh header before starting the new feature. +- **Why special:** Small but thoughtful: it prevents cross-feature memory contamination (stale Codebase Patterns from feature A polluting feature B's iterations) while keeping an auditable history of every run. It's the only lifecycle management in the system and it's fully automatic. The ralph skill mirrors the same rule for manual prd.json updates. +- **How it works:** ralph.sh lines 42-73: jq-extract branchName, compare to .last-branch, mkdir archive/$DATE-$(branch minus ralph/ prefix), cp both files, rewrite progress.txt header, update .last-branch. skills/ralph/SKILL.md 'Archiving Previous Runs' duplicates the protocol for the manual path. .gitignore treats prd.json/progress.txt/.last-branch as ephemeral working files. +- **ZO relevance:** ZO's memory/{project}/sessions/ already scopes memory per project, but Ralph's reset-on-new-feature is a useful sub-project idea: ZO could archive-and-reset phase-scoped scratch state when a plan's branch/phase changes, keeping only PRIORS (which are meant to generalize) live across features. Also a reminder that ZO's continue-mode auto-detection could key off a persisted last-branch/last-phase marker file — trivially cheap and robust. +- **Evidence:** `ralph.sh`, `skills/ralph/SKILL.md`, `.gitignore` + +#### Tool-agnostic dual-prompt design (Amp / Claude Code) + +- **What:** The same loop drives either Amp or Claude Code via --tool flag; the ONLY difference is which prompt file is piped in (prompt.md vs CLAUDE.md) and the tool's own permission-bypass flag. The two prompt files are near-identical hand-maintained copies. +- **Why special:** Proves the technique is model/tool-independent — the harness contract is just 'text in, text out, grep for sentinel'. That is a strong architecture statement: no SDK, no API coupling, no session management. But the duplication is a real maintenance hazard: the two prompts have already drifted (browser testing is 'Required' for Amp vs 'If Available' for Claude; Amp logs thread URLs, Claude doesn't; AGENTS.md vs CLAUDE.md as the learnings target). +- **How it works:** ralph.sh lines 11-35 (arg parsing/validation), 91-96 (the two invocations). Note the Claude prompt file is named CLAUDE.md and piped via stdin — a pun on Claude Code's memory-file convention, but mechanically it is just the stdin prompt for `--print` mode, not auto-loaded project memory. .claude-plugin/{marketplace.json,plugin.json} additionally package the two skills as a Claude Code marketplace plugin. +- **ZO relevance:** Low-to-moderate. ZO is committed to Claude Code, so multi-tool is not a goal; the transferable lesson is negative — do not maintain duplicated prompt variants by hand (generate them from one source). The marketplace plugin packaging of skills is a distribution pattern ZO could copy for its own skills. +- **Evidence:** `ralph.sh`, `CLAUDE.md`, `prompt.md`, `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `README.md` + +#### Mandatory browser verification for UI stories + +- **What:** Every UI-touching story must carry 'Verify in browser using dev-browser skill' as an acceptance criterion, injected at PRD time by both skills; the Amp prompt declares 'A frontend story is NOT complete until browser verification passes.' +- **Why special:** It bakes an empirical feedback loop into the plan artifact itself rather than relying on the agent to remember to test visually — the criterion travels with the story. This is the closest Ralph gets to an oracle for the class of work (UI) where typecheck/tests are weakest. PARTIALLY ASPIRATIONAL: the dev-browser skill is referenced in prompt.md, both SKILL.md files, and README, but is NOT shipped in this repo; the Claude Code variant downgrades it to 'if you have browser testing tools configured... If no browser tools are available, note that manual browser verification is needed' — i.e., on Claude Code the guarantee silently degrades to a self-reported TODO. +- **How it works:** skills/prd/SKILL.md (UI stories template includes the criterion), skills/ralph/SKILL.md ('For stories that change UI, also include...'), prompt.md 'Browser Testing (Required for Frontend Stories)' vs CLAUDE.md 'Browser Testing (If Available)'. prd.json.example shows it on US-002 through US-004. +- **ZO relevance:** The pattern — verification method named INSIDE each acceptance criterion at plan time — is directly adoptable into ZO's plan.md schema and oracle spec: every subtask criterion should name its check command/tool, so the oracle can execute it mechanically. ZO should implement the actual browser-check tooling rather than inherit Ralph's unshipped dependency. +- **Evidence:** `skills/prd/SKILL.md`, `skills/ralph/SKILL.md`, `prompt.md`, `CLAUDE.md`, `prd.json.example` + +### Architecture Notes + +Total system = 1 bash script (113 lines) + 2 near-duplicate prompt files + 2 planning skills + 1 example JSON + docs. No Python, no SDK, no API calls, no orchestrator process, no agent roles, no model routing, no parallelism — strictly serial, one story per fresh single-agent invocation. Control flow: bash for-loop → spawn CLI agent with static stdin prompt in full-permission-bypass mode (`--dangerously-skip-permissions` / `--dangerously-allow-all`) → tee output for live viewing while capturing → grep for `COMPLETE` → exit 0 / sleep 2 / iterate → exit 1 at cap. State machine lives entirely on disk: prd.json (which stories are done, which branch), progress.txt (append-only learnings + consolidated Codebase Patterns section read first each iteration), .last-branch (run identity for archiving), git history (code checkpoints; each green commit is the recovery point), and AGENTS.md/CLAUDE.md files in the target codebase (auto-loaded contextual knowledge). Idempotency/recovery is implicit: because every iteration re-derives state from files, a crashed iteration is simply retried by the next fresh instance; the worst case is redoing a story whose commit landed but whose passes flag didn't get flipped. Trust model: total trust in the agent — the harness performs no verification of any kind (never runs tests, never inspects diffs, never validates JSON); quality gates (typecheck/test/browser) exist only as prompt instructions, and passes:true is self-asserted. Completion is agent-declared via sentinel with the iteration cap as backstop. The flowchart/ subdir (React 19 + @xyflow/react + Vite, deployed to GitHub Pages via .github/workflows/deploy.yml) is a click-through presentation of the loop — real, working, but explanatory material only. Repo history is tiny (~20 commits): initial Amp-only version, Claude Code support bolted on by a contributor (hence the prompt-file duplication), then marketplace packaging. The one-line philosophy: make the runtime dumb and the plan smart; use fresh context as the drift guardrail, files as the memory, git as the checkpoint, and feedback loops (typecheck/tests/CI) as the only selection pressure. + +### Weaknesses + +- No independent verification anywhere: the agent grades its own homework — it runs whatever checks it chooses, flips passes:true itself, and the harness only greps for a sentinel string. The entire 'quality checks must pass' guarantee is a prompt instruction, not an enforced gate. This is the antithesis of ZO's oracle-first principle. +- Sentinel detection is fragile: `COMPLETE` appears verbatim in the prompt text, so a model that quotes or paraphrases its own stop condition in output would falsely terminate the loop; conversely detection depends on exact string reproduction. +- No per-story failure tracking or escalation: a story that repeatedly fails burns all remaining iterations silently retrying; the prd.json `notes` field that could carry failure context is defined in the schema but never referenced by any prompt (vestigial). +- No subprocess timeout or stall detection: a hung CLI invocation blocks the loop forever; the only watchdog is the human reading the tee'd output. +- Runs with all permission systems disabled by design (--dangerously-skip-permissions / --dangerously-allow-all), with no sandboxing, no command allowlist, and no guard against the agent touching files outside the feature scope. +- prompt.md and CLAUDE.md are hand-maintained near-duplicates that have already semantically diverged (browser testing Required vs If Available; thread-URL logging Amp-only; AGENTS.md vs CLAUDE.md learning targets) — a template-generation problem left unsolved. +- The dev-browser skill that UI verification depends on is referenced throughout but not shipped in this repo; on Claude Code the browser gate degrades to a self-reported 'manual verification needed' note. +- The task ledger (prd.json) and memory (progress.txt) are gitignored as ephemeral working files, so run state is not versioned or recoverable from git — an interrupted machine loses the ledger while the prompt simultaneously says 'commit ALL changes', a mild contradiction. +- No cost/token accounting or budget control beyond the iteration cap; no metrics on iteration success rate. +- Serial-only execution with a single generalist agent: no way to parallelize independent stories, no model tiering (every story pays the same model cost regardless of difficulty), no reviewer/second-opinion role. +- The self-improvement loop is shallow relative to ZO's evolution protocol: learnings are appended prose with no root-cause classification, no rule-update mechanism, and no check that a learning would have prevented the original failure. + +### Notable Files + +- `ralph.sh` +- `prompt.md` +- `CLAUDE.md` +- `AGENTS.md` +- `skills/ralph/SKILL.md` +- `skills/prd/SKILL.md` +- `prd.json.example` +- `README.md` +- `.claude-plugin/marketplace.json` +- `.gitignore` diff --git a/memory/zo-platform/research/2026-08-12-repo-reviews/raw-findings.json b/memory/zo-platform/research/2026-08-12-repo-reviews/raw-findings.json new file mode 100644 index 0000000..ed6f4fe --- /dev/null +++ b/memory/zo-platform/research/2026-08-12-repo-reviews/raw-findings.json @@ -0,0 +1,1328 @@ +{ + "zoBaseline": { + "summary": "Zero Operators (ZO) is a plan-driven autonomous AI research/ML engineering team built on Claude Code. A human writes/approves plan.md; a Lead Orchestrator (Opus) decomposes it into a 6-phase gated ML workflow and spawns a contract-first team of 21 defined agents; a hard oracle (numeric, tiered must/should/could thresholds) gates every phase; per-project markdown memory (STATE/DECISION_LOG/PRIORS + fastembed/SQLite semantic index) provides cross-session continuity; a post-mortem/self-evolution protocol turns every failure into a rule update. v1 is complete (854 platform tests, all 8 PRD acceptance criteria met), validated on MNIST (99.66%) and CIFAR-10 demos plus one production project (prod-001, currently at Phase 2). Its strongest assets are oracle discipline that is enforced in code rather than in prompts, a genuinely wired learning loop, and an unusually honest empirical culture (it refuted its own 70-80% cost-savings claim down to a measured ~30%). Its biggest weaknesses are the fragile tmux/CLI-subprocess execution substrate, a still-unimplemented anti-stall watchdog (a real 38-hour silent stall occurred), a rigid linear ML-only workflow DAG, a structural cost ceiling without an SDK refactor, and a recurring pattern where agent contracts are ignored unless hard-enforced \u2014 enforcement coverage remains incomplete.", + "current_architecture": "TWO-REPO MODEL (\"surgeon and patient\"): The ZO repo holds all infrastructure (specs/, .claude/agents/, memory/, plans/, targets/, logs/); delivery repos receive only clean project artifacts. A target file (targets/{project}.target.md) bridges them: target repo path, branch, per-agent working dirs, a zo_only_paths blocklist, and enforce_isolation. Projects can optionally carry portable state in a .zo/ directory inside the delivery repo (config.yaml, memory/, plans/, experiments/), making projects movable via git pull; `zo migrate` copies state over and `zo continue`/`zo status` auto-detect from .zo/config.yaml. Platform memory (memory/zo-platform/) always stays in the ZO repo, with a hard confidentiality regime: client info never in tracked files, sequential aliases (prod-001, demo-mnist), gitignored plans/targets/memory, and a fail-closed blocklist for promoting learnings.\n\nOPERATING MODES / CLI: Two user-facing modes \u2014 Build (input plan \u2192 spawn team \u2192 produce code; auto-detects fresh/continue/plan-edited) and Continue (thin alias for build). The `zo` CLI (src/zo/cli.py, ~3,400 lines; whole package ~15.8k lines across 33 modules) exposes: build, continue, init (conversational Init Architect or headless with --dry-run/--reset), draft (Plan Architect + Data Scout draft plan.md conversationally from docs/data), preflight (10 validation checks), status, migrate, gates set (supervised/auto/full-auto mid-session), experiments list/show/diff, learnings promote, watch-training (Rich Live dashboard), report and consolidate (concurrent Opus report session in an isolated git worktree alongside a live model session, with delta-memory consolidation back to canonical memory), plus 24 slash commands in 8 categories (.claude/commands/: agents, document, gates, memory, observe, project, commit, zo-dev). Execution substrate: a LifecycleWrapper (wrapper.py) launches the Claude Code CLI as a subprocess in tmux (interactive, paste-buffer prompt injection, liveness polling with startup grace/debounce) or headless (--no-tmux with --dangerously-skip-permissions); a permissions overlay writes bypassPermissions into settings.local.json with backup/restore for unattended runs. Extension points (PR #99) allow workflow resolution overrides, orchestrator subclassing, and zo.commands entry-point CLI plugins. A --low-token preset swaps the lead to Sonnet, caps iterations, and trims agents (measured ~30% savings).\n\nAGENTS: 21 agent definitions in .claude/agents/ (md files with YAML frontmatter: name, model, role, tier, team), in four teams \u2014 Project Delivery (12): lead-orchestrator (Opus), data-engineer, model-builder (Opus), oracle-qa, code-reviewer, test-engineer, research-scout (Opus), plus phase-in xai-agent, domain-evaluator (Opus), ml-engineer, infra-engineer (Haiku), training-checker (per-run live training monitor); Platform Build (6): software-architect, backend-engineer, frontend-engineer, platform-test-engineer, platform-code-reviewer, documentation-agent; Draft Scouts (2): plan-architect + data-scout; Init (1): init-architect. Model routing is static per agent (Haiku=glue, Sonnet=analysis/iteration, Opus=architecture/orchestration). Coordination uses Claude Code native agent teams (TeamCreate + Agent + SendMessage, peer-to-peer), with contract-first spawning: every spawn prompt specifies ownership, off-limits paths, produced/consumed contracts, coordination rules, and a validation checklist. Projects can add custom agents via a plan.md block (written to .claude/agents/custom/) and per-project agent adaptations injected at spawn time.\n\nWORKFLOW: Six gated phases (+ Phase 0 literature review in research mode) encoded in specs/workflow.md and the ml-workflow skill: 1 Data Review (13 subtasks, sequential), 2 Feature Engineering/representation design, 3 Model Design (parallel: architecture, loss, training strategy, oracle setup, tracking), 4 Training & Iteration (autonomous loop), 5 Analysis & Validation (SHAP/explainability, error analysis, ablations, significance, reproducibility), 6 Packaging (parallel: inference pipeline, model card, validation report, drift detection, tests). Three workflow modes (classical_ml, deep_learning, research) selected from plan.md. Human checkpoints at Gate 2 (feature/representation approval) and Gate 4 (model approval); Gate 3 is the automated oracle threshold. Phase 4 runs inside an experiment capture layer: each iteration gets .zo/experiments/exp-NNN/ (hypothesis.md, config.yaml, metrics.jsonl + training_status.json via a mandatory ZOTrainingCallback \u2014 hard-gated, the Phase 4 gate fails if the artifacts are missing \u2014, result.md from Oracle, diagnosis.md, next.md) with parent_id lineage and an auto-maintained CHECKLIST.md. In auto/full-auto gate modes an autonomous loop evaluator (experiment_loop.py) issues verdicts: TARGET_HIT / BUDGET_EXHAUSTED / PLATEAU / DEAD_END (Jaccard-similar hypotheses = builder stuck rephrasing) / CONTINUE, with policy defaults (max_iterations=10, plateau_epsilon=0.01) overridable via a plan ## Experiment Loop block.\n\nMEMORY: Four markdown files per project \u2014 STATE.md (checkpoint: mode, phase, blockers, next steps, git_head; validated at parse time), DECISION_LOG.md (append-only audit trail with rationale/alternatives/outcome), PRIORS.md (domain knowledge, never deleted, superseded-only), session summaries \u2014 plus a fastembed+SQLite semantic index (cosine similarity, full rebuild at session end, no incremental indexing). Session lifecycle: read STATE + query index + read recent summaries + verify git HEAD at start; write summary + update STATE + append decisions + reindex at end, with periodic checkpoints via hooks for interrupt recovery. Context Reset Protocol: phase transitions open fresh conversations loading only prior-phase artifacts as files. Memory is strictly per-project; platform memory is separate.\n\nORACLE: Every plan must declare primary metric, ground-truth source, evaluation method, target threshold, evaluation frequency before work begins. Tiered criteria (Tier 1 must-pass blocks progression; Tiers 2/3 informational by default). Explicit anti-patterns: no soft signals (\"tests pass\" is not an oracle), no post-hoc threshold adjustment. Four-stage validation loop after any \"work complete\": self-checklist \u2192 oracle \u2192 adversarial cross-review \u2192 integration validation.\n\nSELF-EVOLUTION: Post-mortem protocol on every failure \u2014 document in DECISION_LOG, root-cause into missing_rule/incomplete_rule/ignored_rule/novel_case/regression, fix, update the corresponding document (PRIORS/spec/agent definition), verify the updated rule would have caught the original failure. Since session 035 this is wired into code: plan domain_priors seed project PRIORS on first run, up to 8 priors are injected into lead prompts, an EvolutionEngine records auto-learning priors on loop DEAD_END/PLATEAU verdicts, and `zo learnings promote` does fail-closed sanitized promotion of generic learnings to platform memory. A retrospective protocol and evolution metrics (regression rate, coverage growth) are specified. Platform-side, the same protocol runs on ZO itself via CLAUDE.md's non-negotiable memory/docs cascade (validate-docs.sh hook blocks commits on doc drift).", + "strengths": [ + "Oracle-first discipline that is enforced in code, not prose: gates check for actual artifacts (ZOTrainingCallback's metrics.jsonl/training_status.json, Oracle's result.md), a lesson learned after a Sonnet lead silently ignored aspirational contracts (PRIORS PR-035: 'enforcement > aspiration')", + "Genuinely wired self-evolution loop (as of session 035): plan priors seed project memory, priors are injected into prompts, dead-ends/plateaus persist auto-learning priors, and a fail-closed sanitized promotion path moves generic learnings to platform memory without confidentiality risk", + "Unusually honest empirical culture: the platform refuted its own 70-80% cost-savings claim with a measured benchmark (~30%, $7.75 MNIST run), documented the structural reason, and cascaded corrections through all docs \u2014 STATE.md and PRIORS read like a real lab notebook of verified fixes and refuted hypotheses", + "Contract-first spawning with explicit ownership/off-limits/produced/consumed contracts per agent, preventing silent integration failures in parallel work", + "Strong auditability and session recovery: append-only DECISION_LOG, STATE.md checkpointing with git_head verification, proven interrupt-resume (ACTIVE-phase resume bug found and fixed via a real prod-001 incident), portable .zo/ memory for cross-machine continuity", + "The Phase 4 experiment capture layer + autonomous loop is a differentiated capability: hypothesis\u2192config\u2192metrics\u2192result\u2192next lineage with parent_id, dead-end detection via hypothesis similarity, plateau/budget stopping, and an auto-maintained checklist \u2014 closing the loop without human input in auto modes", + "Rigorous confidentiality architecture for a public repo operating on private client projects: alias convention, gitignore enforcement, client-term blocklist, block-not-strip promotion", + "Novel concurrent report sessions (surrogate model): an Opus report-lead runs in an isolated git worktree alongside a live model session with per-PID liveness locks and safe delta-memory consolidation \u2014 real multi-session concurrency on one project", + "Strong platform engineering hygiene: 854 tests green on Python 3.11 and 3.12, ruff clean, a PreToolUse hook that blocks commits when docs drift from code, and documented cascade rules for every interface change", + "Extension points (workflow resolution, orchestrator subclass, CLI entry-point plugins) already exercised by a real downstream plugin", + "Comprehensive, opinionated ML workflow spec (60+ subtasks across 6 phases, 3 modes) encoding real research discipline: leakage denylists, purge-gap temporal splits, ablations, statistical significance, reproducibility verification" + ], + "gaps": [ + "No anti-stall mechanism implemented: specs/watchdog.md is an RFC only, written after a real ~38-hour silent stall in a long autonomous run \u2014 the event-driven orchestrator has a silent-death hole (all-idle team emits no wake signal; absence of errors read as progress), and a dedicated monitor agent would itself be a single point of failure", + "Fragile execution substrate: ZO drives the Claude Code CLI as a tmux subprocess with paste-buffer prompt injection, pane-liveness polling, and a settings.local.json permissions overlay \u2014 multiple sessions were consumed fixing races in this layer (15ms premature teardown, TUI-ready misdetection selecting 'No, exit' on a consent dialog, cold-start paste timing), and the watcher was at one point 'more fragile than the thing it watches'", + "Structural cost ceiling (~25-30% savings) without an SDK refactor: sub-agents are already on Sonnet, so --low-token only touches the lead's share; prompt caching, Batch API, and Files API are all unreachable from the CLI-launcher architecture and the refactor is deferred as a multi-week effort", + "Recurring 'aspirational contracts get ignored' failure mode with incomplete enforcement coverage: known deferred items include semantic reindex at session end, an agent failure-reporting protocol, end_session DECISION_LOG/PRIORS integration, and a zo retrospective CLI (audit items #13/#15/#16/#17) \u2014 each past incident was hard-gated individually rather than via a systematic enforcement layer", + "Workflow is a rigid linear DAG: no cross-phase backedges (RETURN_TO_PHASE primitive and weighted-graph refactor are roadmap items F3 Phase A/B only), so discovering mid-Phase-4 that features are wrong has no first-class path back to Phase 2 short of human intervention", + "ML/research-specific: the entire workflow, agent roster, and oracle framing assume an ML/data pipeline; general software-engineering delivery is unproven (the planned software-engineer agent and optimization audit, Batch D, are not done), and oracles for non-quantifiable deliverables are unaddressed", + "Thin validation base: two toy demos (MNIST, CIFAR-10) and one production project (prod-001), which is still at Phase 2 awaiting GPU work \u2014 memory-scale features (session-summary consolidation, incremental indexing, cross-project rule propagation, SONA routing) are all untested v2 triggers gated on 3-5+ projects that don't exist yet", + "Single-project-per-session, no dashboard, no external integrations: monitoring is terminal-only (tmux + watch-training), human checkpoints require polling DECISION_LOG rather than notifications (Slack/GitHub integration is v2), and the VS Code extension is roadmap only", + "Hard dependency on Claude Code's proprietary agent-teams capabilities (TeamCreate/Agent/SendMessage): multi-provider support was assessed and reframed to a limited worker-pool model because full peer-to-peer parity would require rebuilding that infrastructure on bare APIs", + "Onboarding friction acknowledged but unaddressed: setup requires uv + Claude CLI + tmux + setup.sh; the planned one-line installer, Homebrew formula, and zo doctor command (Tier 1 'onboarding hardening') remain queued", + "ZO violates its own coding conventions in its core: cli.py is ~3,400 lines against the stated 'files under 500 lines' rule, indicating the platform build has outgrown its module structure", + "STATE.md and other memory files are hand-editable markdown parsed by code \u2014 a hand-edited invalid status previously crashed the orchestrator deep in restore (now validated at parse time, but the format remains a fragile human/machine dual-use interface)" + ], + "open_questions": [ + "When (and whether) to do the SDK refactor: switching from CLI-subprocess launching to the Anthropic SDK unlocks prompt caching, Batch API, Files API (70-80% cost target) and programmatic control that would eliminate the fragile tmux layer \u2014 but sacrifices the interactive tmux experience and Claude Code's native agent-teams; the roadmap sequences it after cost quick-wins but the substrate fragility argues for sooner", + "How to implement the watchdog: the RFC requires an active wall-clock heartbeat independent of teammate messages plus liveness-by-evidence and auto-remediation \u2014 but where does the heartbeat live (orchestrator wrapper? cron? external process?) so it isn't itself a silent single point of failure?", + "Is the RETURN_TO_PHASE backedge primitive (F3 Phase A) enough to validate cross-phase autonomy cheaply, or does credible autonomy require the full weighted-graph refactor with per-node completeness and revisit ranking (Phase B)?", + "Tier 2 sequencing is explicitly unresolved and awaiting external-user signal (GitHub Discussions #81): VS Code extension (accessibility) vs cost work vs architecture-first (backedge \u2192 SDK refactor \u2192 extension) \u2014 which growth lever matters more depends on unconfirmed audience weighting (research peers / paying customers / internal)", + "How to generalize beyond ML: what does the oracle framework mean for deliverables without a held-out metric (an API, a refactor, a report), and does the phase/gate structure survive translation to general software engineering?", + "Can agent-contract enforcement become systematic rather than incident-driven \u2014 i.e., a generic mechanism that verifies any spawn-prompt contract's artifacts at gates, instead of hand-wiring a hard gate after each observed violation?", + "Multi-provider worker pool: is the limited model (Claude Code lead + single-agent CodeX/OpenCode workers coordinating via filesystem JSONL) worth building, given full peer parity is off the table?", + "Memory at scale is unvalidated: do the v2 triggers (summary consolidation at 100+ sessions, SONA routing at 3+ concurrent projects, pattern libraries at 5+ same-domain projects) hold up, and does the full-rebuild semantic index remain adequate?", + "Self-evolution verification remains manual/informal: the protocol requires confirming an updated rule 'would have caught the original failure', but there is no mechanized regression test for rules \u2014 how should rule efficacy be tracked (the v2 evolution-confidence-scoring idea)?", + "The human experience between gates is polling-based: what is the right notification/wakeup channel (Slack, push, email) and does adding it change the v1 'no external integrations' constraint?", + "prod-001 is the only production validation vehicle and is paused at Phase 2 \u2014 does the platform's Phase 4/5 machinery (autonomous loop, training-checker, dead-end detection) hold up on a real non-toy dataset, and what priors does that run generate?" + ] + }, + "dives": [ + { + "repo": "oh-my-claudecode", + "lens": "orchestration", + "summary": "oh-my-claudecode (OMC, v4.15.7, MIT) is a very large, very active Claude Code plugin (~1,155 TS files / ~337K lines in src/, thousands of merged PRs, last commit the day of review) that turns a single Claude Code session into a multi-agent orchestration layer. Its core design pattern is a split between non-deterministic \"prompt protocols\" (19 agent persona .md files with model-tier frontmatter, ~45 skills as markdown workflow specs) and deterministic TypeScript state machines wired into every Claude Code hook event (UserPromptSubmit, Stop, PreToolUse, PostToolUse, SubagentStart/Stop, PreCompact, SessionStart/End). The hooks detect \"magic keywords\" in prompts, inject system-reminders that activate skill protocols, persist per-mode JSON state under .omc/state/ (session-scoped, atomically written, lock-protected), and \u2014 most distinctively \u2014 intercept Stop events to force continuation until file-based completion criteria are met.\n\nExecution modes compose as layers: ultrawork (parallel delegation protocol, no persistence) \u2282 ralph (PRD-driven persistence loop: auto-generated prd.json user stories with acceptance criteria, progress.txt cross-iteration memory, reviewer verification with anti-forgery approval tags before completion is accepted) \u2282 autopilot (5-phase pipeline: expansion \u2192 planning \u2192 execution \u2192 QA \u2192 validation with per-phase iteration caps and 3-perspective validation). Orthogonal modes: team (staged pipeline team-plan \u2192 team-prd \u2192 team-exec \u2192 team-verify \u2192 team-fix over either native Claude Code agent teams or a 27K-line tmux/CLI worker runtime with heartbeats, mailboxes, git-worktree isolation, and cross-provider workers \u2014 codex/gemini/antigravity/cursor), ralplan (3-agent consensus planning: planner/architect/critic), ultraqa (test-fix cycling with same-failure early exit), and autoresearch (evaluator-contract improvement loop \u2014 the closest analog to ZO's oracle).\n\nThe stop decision is the most engineered part of the system: a 2,564-line persistent-mode Stop hook resolves an authoritative workflow ledger (parent mode wins in nested runs), then applies ~10 circuit breakers learned from production failures (context-limit deadlocks #213, rate-limit retry loops #777, auth-error loops #1308, thinking-only streak detection, oversize tool-result redirects, SHA-256-authenticated cancel signals, PID-aware stale-state detection) before deciding to block a stop and re-inject a continuation prompt. Iterations are bounded per-mode (ralph default 10, autopilot per-phase caps) under a global security-config hard cap (500, 200 in strict mode).\n\nThe quality-measurement story is the weakest part: benchmark/ is a complete SWE-bench Verified vanilla-vs-OMC harness, but results are empty templates and the only committed run is a 5-instance smoke test where OMC failed 5/5; benchmarks/ (agent-prompt regression scoring with ground-truth findings) has all-zero placeholder baselines; geobench/ is not a quality benchmark at all but a marketing \"GEO visibility\" profile. Several sophisticated-looking subsystems (signal-based model routing engine, verification tier-selector, task-decomposer) are exported library code with no runtime callers \u2014 actual model routing is declarative prompt guidance, not code.", + "key_features": [ + { + "name": "Magic keyword detection with false-positive suppression and under-specification gating", + "what_it_is": "A UserPromptSubmit hook that detects mode-triggering keywords (ralph, autopilot, ulw/ultrawork, ralplan, tdd, ultrathink, deepsearch, ccg, cancelomc, etc., in English/Korean/Japanese/Chinese) and injects [MAGIC KEYWORD: ...] system-reminders that activate the corresponding skill.", + "why_special": "Not the regexes themselves but the guardrails around them: it strips code blocks, file paths, git diffs, quoted spans, pasted transcripts, and XML blocks before matching; suppresses activation for informational contexts ('what is ralph?'), diagnostic complaints ('ralph keeps looping'), and banter; classifies task size (<50 words = small) and suppresses heavy modes for small tasks; and applies a 'ralplan-first gate' that redirects underspecified execution prompts (no file paths, symbols, issue refs, or structure) to planning instead, with force:/! escape hatches. This is hundreds of lines of hard-won UX engineering that any keyword-triggered agent system will eventually need.", + "how_it_works": "src/hooks/keyword-detector/index.ts (1,114 lines): KEYWORD_PATTERNS + KEYWORD_PRIORITY, sanitizeForKeywordDetection(), isInformationalKeywordContext() with quoted-span exemptions and per-language diagnostic-intent regexes, getAllKeywordsWithSizeCheck() using classifyTaskSize() from src/hooks/task-size-detector/index.ts, applyRalplanGate() with WELL_SPECIFIED_SIGNALS. Wired via hooks/hooks.json UserPromptSubmit \u2192 scripts/keyword-detector.mjs; conflict resolution (cancel beats all, team beats autopilot) and detection results flow into src/hooks/bridge.ts.", + "zo_relevance": "Directly adoptable pattern: ZO's slash-command entry points (zo build/continue) avoid this problem, but if ZO ever adds natural-language triggers or auto-detects 'plan-edited' intent, the two useful ideas are (1) the underspecification gate \u2014 refuse to spawn a heavy agent team when the plan/prompt lacks concrete anchors, redirect to planning instead \u2014 and (2) task-size gating to prevent over-orchestration. ZO's oracle-first principle already implies a specification gate; OMC shows how to implement it as a deterministic pre-spawn check.", + "evidence_files": [ + "src/hooks/keyword-detector/index.ts", + "src/hooks/task-size-detector/index.ts", + "hooks/hooks.json", + "src/hooks/bridge.ts" + ] + }, + { + "name": "Stop-hook persistence engine (the 'when to stop' machinery)", + "what_it_is": "A Stop-event hook that decides whether Claude is allowed to stop. If a persistent mode (ralph/autopilot/team/ralplan/ultrawork/autoresearch) is active with incomplete work, it blocks the stop and injects a continuation prompt; a stack of circuit breakers prevents the blocking from becoming an infinite or harmful loop.", + "why_special": "This is the most battle-tested 'agent persistence' implementation I've seen in the Claude Code ecosystem. Every escape valve carries an issue number from a real production failure: never block context-limit stops (deadlock, #213), rate-limit stops (429 retry loop, #777), auth failures (#1308), user aborts, scheduled wakeups, oversize tool-result redirects (bounded window of 3), sessions with pending async work; a thinking-only streak guard releases the stop after N consecutive assistant turns with no tool_use (detects unproductive rumination by parsing the transcript); cancel signals are authenticated with SHA-256 digests of the target state + workflowRunId + 30s TTL so a stale or forged cancel cannot kill the wrong run; a workflow-slot ledger resolves nested modes so the authoritative parent (autopilot over ralph) does the stop-gating; global hard cap of 500 iterations (200 strict) from security config.", + "how_it_works": "src/hooks/persistent-mode/index.ts (2,564 lines): resolvePersistentModeBlock() runs the bypass checks then priority order (workflow-ledger authority \u2192 ralph/autopilot \u2192 autoresearch \u2192 ralplan \u2192 team \u2192 ultrawork \u2192 skill-active-state \u2192 todo-continuation, max 5 attempts); applyThinkingOnlyStreakGuard() classifies the last assistant turn from transcript JSONL; createHookOutput() returns continue:false to hard-block. Registered as Stop hook in hooks/hooks.json (persistent-mode.mjs, alongside context-guard-stop.mjs and workflow-drift-guard.mjs). Hard cap via getHardMaxIterations() in src/lib/security-config.ts.", + "zo_relevance": "Highest-value study target for ZO. ZO's spec (297adac added a watchdog/heartbeat anti-stall design spec) is heading exactly here. The lessons to steal wholesale: (1) enumerate stop-context types and never fight the platform on context-limit/rate-limit/auth stops; (2) bound every continuation loop at multiple levels (per-mode max, global hard cap, attempt counters with TTL); (3) detect 'thinking-only' non-progress from the transcript, not from wall-clock time; (4) authenticate cancellation against a state digest so stale signals can't kill live runs; (5) when modes nest (ZO: orchestrator \u2192 phase agents), the parent must own stop-gating via an authoritative ledger. ZO can implement this in its Claude Code hook layer with far less code since it has fewer modes.", + "evidence_files": [ + "src/hooks/persistent-mode/index.ts", + "src/hooks/todo-continuation/index.ts", + "src/lib/security-config.ts", + "hooks/hooks.json" + ] + }, + { + "name": "Ralph: PRD-driven persistence loop with anti-forgery completion verification", + "what_it_is": "The flagship 'keep working until done' mode. Startup force-generates a prd.json of user stories with acceptance criteria (model must refine generic scaffold criteria into task-specific ones); the loop picks the next passes:false story each iteration; completion of the whole run requires a reviewer agent (architect default, critic or external Codex via --critic=) to approve against the specific acceptance criteria.", + "why_special": "Two genuinely clever mechanisms. First, completion approval is an XML tag with a per-verification random UUID: VERIFIED_COMPLETE, and detectArchitectApproval() strips injected prompt examples before matching and requires the request-id (and story-id) to correlate \u2014 the executing model cannot self-approve by echoing text it saw in its own context. Second, progress.txt accumulates per-story implementation notes, files changed, learnings, and codebase patterns that get re-injected each iteration \u2014 cross-iteration memory that survives context resets. Verification is bounded (3 attempts then force-accept) and scoped per-story or per-completion.", + "how_it_works": "src/hooks/ralph/loop.ts (state, PRD startup gate, linked ultrawork auto-activation), prd.ts (story schema, scaffold generation, status), progress.ts (append-only learnings), verifier.ts (VerificationState, startVerification, getArchitectVerificationPrompt with correlated approval tag, detectArchitectApproval/Rejection). The skill prompt protocol is skills/ralph/SKILL.md; stop-hook integration in persistent-mode/index.ts checkRalphLoop; default 10 iterations.", + "zo_relevance": "Direct analog to ZO's oracle loop, but weaker and stronger in different places. Weaker: OMC's verifier is an LLM reviewer with regex-based rejection detection \u2014 ZO's hard, executable oracle metric is strictly better as ground truth. Stronger: (1) the request-id-correlated approval tag is a pattern ZO should adopt for any LLM-judged gate (gates:approve) to prevent an agent from forging gate passage from in-context examples; (2) prd.json's per-story acceptance criteria with passes flags is a finer-grained progress ledger than a phase-level plan \u2014 ZO subtasks could carry machine-checkable passes state; (3) progress.txt's 'learnings and patterns' feed is a lightweight in-run version of ZO's PRIORS.md worth mirroring at the iteration level.", + "evidence_files": [ + "src/hooks/ralph/loop.ts", + "src/hooks/ralph/verifier.ts", + "src/hooks/ralph/prd.ts", + "src/hooks/ralph/progress.ts", + "skills/ralph/SKILL.md" + ] + }, + { + "name": "Autopilot: 5-phase autonomous pipeline with multi-perspective validation and evidence-bound stage advancement", + "what_it_is": "Idea-to-working-code mode: expansion (analyst+architect spec) \u2192 planning (architect plan + critic validation) \u2192 execution (ralph+ultrawork) \u2192 QA (ultraqa cycling, max 5, early-exit if same error 3x) \u2192 validation (functional/security/quality reviewers must ALL approve, max 3 re-validation rounds). Also 'named workflow profiles' v1: user-configurable stage schedules ([ralplan, execution, ralph, qa] subsets) declared in omc.jsonc.", + "why_special": "The phase state machine is fully materialized in typed state (AutopilotState with per-phase sub-state, phase_durations, total_agents_spawned) rather than living only in the prompt, so the Stop hook can enforce phase-appropriate continuation and report progress. The named-workflow v1 goes further than anything comparable: an immutable SHA-256-hashed workflow descriptor, and Stop hooks that advance a stage only after an 'authorized assistant completion record' appears after the stage's persisted transcript boundary (Linux flock + no-follow fd traversal) \u2014 i.e., stage transitions require transcript evidence, rejecting stale, wrong-stage, or non-assistant output. Notably, the docs are candid about deferrals (no stageModels/model routing, Linux-only).", + "how_it_works": "src/hooks/autopilot/types.ts (phases, DEFAULT_CONFIG: maxQaCycles 5, maxValidationRounds 3, parallelExecutors 5, validationArchitects functional/security/quality), enforcement.ts (checkAutopilot: hard-max then per-state max iteration stops, phase-tagged continuation prompts), pipeline.ts/pipeline-types.ts (unified stage orchestrator), named-workflow-resume-validator.ts, state.ts; skill protocol skills/autopilot/SKILL.md (including artifact reuse: skip phases when a ralplan consensus plan or deep-interview spec already exists).", + "zo_relevance": "ZO's phase pipeline (specs/workflow.md) is the same shape, and ZO already does fresh-context phase transitions. Two adoptable ideas: (1) materialize phase state as typed, session-scoped JSON that hooks can enforce against \u2014 ZO's STATE.md is human-readable but not machine-enforced; a parallel state.json would let a ZO stop-hook verify 'phase N gate passed' deterministically; (2) transcript-evidence-bound stage advancement is the strongest anti-hallucination gate design available for 'the agent claims the phase is done' \u2014 overkill for v1 ZO but the right direction for unattended runs. The multi-perspective validation (3 reviewer types must all approve) maps to widening ZO's oracle gate with security/quality lanes.", + "evidence_files": [ + "src/hooks/autopilot/types.ts", + "src/hooks/autopilot/enforcement.ts", + "src/hooks/autopilot/pipeline.ts", + "skills/autopilot/SKILL.md", + "docs/adr/03487-named-autopilot-stage-profiles.md" + ] + }, + { + "name": "Team runtime: staged pipeline + tmux/CLI worker infrastructure with cross-provider workers", + "what_it_is": "Two team implementations: (a) native Claude Code implicit agent teams (Task tool with name= workers) driving a canonical staged pipeline team-plan \u2192 team-prd \u2192 team-exec \u2192 team-verify \u2192 team-fix with a bounded fix loop; (b) a 27,781-line tmux/CLI worker runtime (src/team, 79 modules) where workers can be Claude, Codex, Gemini, Antigravity, or Cursor CLIs.", + "why_special": "The tmux runtime is a serious distributed-systems build: per-worker heartbeat JSON files with freshness-based liveness (heartbeat.ts), append-only inbox/outbox JSONL mailboxes with rotation and cursors, git-worktree-per-worker isolation with a merge coordinator/orchestrator, epoch-based team ownership, worker health checks and restarts, a dispatch queue, an intent-inference role router (task text \u2192 implementation/verification/review/debug/design/docs/build-fix/cleanup lane \u2192 role), per-role provider/model routing via .claude/omc.jsonc team.roleRouting (e.g., codex critic, gemini reviewer), and audit logs. Also instructive: they DISABLED the 'team' magic keyword (never-match regex in keyword-detector) because Claude workers receiving prompts containing 'team' caused infinite recursive spawning \u2014 a production scar worth learning from.", + "how_it_works": "Pipeline state machine: src/hooks/team-pipeline/{types,state,transitions}.ts (phase history, fix_loop attempt/max_attempts, cancel with preserve_for_resume). Worker runtime: src/team/{heartbeat,inbox-outbox,tmux-session,git-worktree,merge-orchestrator,role-router,runtime-v2,scaling,worker-health,worker-restart,team-owner-epoch}.ts. Stage-agent routing table (which specialist agents at which model tier per stage) lives in skills/team/SKILL.md. Ralph composition: getTeamPhaseDirective() in ralph/loop.ts lets ralph's stop enforcement track team phases.", + "zo_relevance": "ZO's contract-first parallel spawning is philosophically similar but ZO relies on Claude Code's native subagents. The transferable pieces: (1) the team-verify/team-fix bounded loop is exactly ZO's oracle\u2192rework cycle \u2014 OMC's explicit fix_loop {attempt, max_attempts, last_failure_reason} state is a clean schema to copy; (2) heartbeat-file liveness + PID-aware ownership is the cheapest robust answer to ZO's watchdog/anti-stall spec for parallel agents; (3) per-role provider routing is a concrete design if ZO ever wants non-Claude verifiers (an external-model oracle reviewer is genuinely useful for adversarial verification); (4) the recursive-spawn scar argues for ZO keeping team spawning explicit/imperative, never keyword-triggered.", + "evidence_files": [ + "src/team/heartbeat.ts", + "src/team/inbox-outbox.ts", + "src/team/role-router.ts", + "src/team/runtime-v2.ts", + "src/team/merge-orchestrator.ts", + "src/hooks/team-pipeline/types.ts", + "skills/team/SKILL.md" + ] + }, + { + "name": "Model tiering: declarative agent frontmatter + prompt-driven routing (programmatic router is dead code)", + "what_it_is": "19 agent personas with model tiers in frontmatter (explore/writer=haiku; executor/debugger/verifier/tracer/qa-tester/etc=sonnet; analyst/planner/architect/critic/code-reviewer/code-simplifier=opus), read-only enforcement via disallowedTools on advisory agents, and skills that instruct the orchestrator to pass model= explicitly per delegation (haiku=lookup, sonnet=standard, opus=complex).", + "why_special": "The honest finding is what ISN'T wired: src/features/model-routing/ is a complete signal-extraction \u2192 complexity-scoring \u2192 tier-selection engine with escalation (routeTask, routeWithEscalation), and src/verification/tier-selector.ts scales verification effort (LIGHT/STANDARD/THOROUGH) from change metadata \u2014 but neither has any caller outside barrel exports and tests; no hook script bundles them. Actual routing is 100% prompt-convention: CLAUDE.md , per-skill Tool_Usage sections, and the team stage-routing table. This is a useful data point: OMC shipped and iterated on prompt-declared routing and never needed to wire the programmatic version.", + "how_it_works": "agents/*.md frontmatter (model:, level:, disallowedTools:); CLAUDE.md agent_catalog and model_routing sections; skills/ultrawork/SKILL.md and skills/team/SKILL.md routing tables; unwired engine at src/features/model-routing/{router,scorer,signals,rules}.ts and src/verification/tier-selector.ts (verified via grep: only re-exported from src/features/index.ts, absent from scripts/*.mjs bundles).", + "zo_relevance": "ZO already does frontmatter model routing per agent (specs/agents.md model tiers), so parity. The lesson is negative-space: don't build a complexity-scoring router; the prompt-declared tier tables plus a downgrade cost-mode rule ('opus\u2192sonnet where quality permits; verify never below sonnet') cover the need. The one gap worth copying is tier-selector's IDEA even if OMC didn't wire it: scale oracle/verification effort with change surface (files changed, security-sensitive paths) \u2014 ZO could implement this deterministically in its gate logic.", + "evidence_files": [ + "agents/executor.md", + "agents/architect.md", + "agents/critic.md", + "src/features/model-routing/router.ts", + "src/verification/tier-selector.ts", + "CLAUDE.md" + ] + }, + { + "name": "Autoresearch: evaluator-contract improvement loop (OMC's oracle analog)", + "what_it_is": "A stateful single-mission mode: a mission directory holds mission.md plus sandbox.md whose frontmatter declares an evaluator command that must emit JSON {pass: boolean, score?: number}, with keep_policy score_improvement or pass_only. The loop runs one experiment per iteration, runs the evaluator, persists per-iteration evaluation JSON and markdown decision logs, continues through failures, and stops only on max-runtime or explicit cancel.", + "why_special": "This is the only place OMC has a HARD, machine-verifiable success signal \u2014 everything else (ralph, autopilot validation) is LLM-judged. The contract is minimal and correct: structured evaluator output, keep-policy for hill-climbing vs. gating, durable per-iteration artifacts, and a wall-clock ceiling as the primary stop. The committed missions are thin (mission 'optimize omc' with evaluator 'npm run build'), showing it's early, but the contract design is sound.", + "how_it_works": "src/autoresearch/{contracts,runtime,setup-contract}.ts (frontmatter parsing, evaluator invocation, git-anchored mission dirs); skills/autoresearch/SKILL.md (artifact shape: .omc/autoresearch//runs//evaluations/iteration-NNNN.json + decision-log.md); missions/*/sandbox.md examples; stop-hook integration via checkAutoresearch in persistent-mode/index.ts; mission generation delegated to /deep-interview --autoresearch.", + "zo_relevance": "ZO's oracle-first principle is this exact idea but more mature (tiered criteria, drift detection per specs/oracle.md). Still worth borrowing: (1) the keep_policy distinction (score_improvement vs pass_only) cleanly separates hill-climbing experiments from pass/fail gates \u2014 useful for ZO's ML loops where val-metric improvement, not a binary gate, drives iteration; (2) per-iteration machine-readable evaluation JSON alongside a human decision log mirrors and validates ZO's DECISION_LOG pattern; (3) max-runtime as the primary hard stop for unattended loops is simpler and safer than iteration counts for ML workloads with variable step cost.", + "evidence_files": [ + "src/autoresearch/contracts.ts", + "src/autoresearch/runtime.ts", + "skills/autoresearch/SKILL.md", + "missions/prove-reliability-by-finding-and-fixing-flaky-te/sandbox.md" + ] + }, + { + "name": "Benchmark infrastructure: SWE-bench harness and agent-prompt regression scoring (both without real results)", + "what_it_is": "benchmark/: a Dockerized SWE-bench Verified comparison suite (run_vanilla.sh vs run_omc.sh, evaluate.py, compare_results.py, failure analysis). benchmarks/: an agent-prompt regression harness scoring agent outputs against fixtures with embedded flaws \u2014 ground-truth findings with severities and keyword matching, composite TP/FN scores, saved baselines for prompt-change regression testing. geobench/: a YAML profile for measuring LLM answer visibility/citations of OMC itself (marketing, not quality).", + "why_special": "The DESIGN of benchmarks/ is the special part: treating agent prompts as testable artifacts with ground-truth fixtures and regression baselines is the right way to evolve prompts safely, and the harsh-critic scorer (matchFindings/scoreFixture/aggregateScores) is reusable. But the evidence status is damning: benchmark/results/README.md is an all-placeholder template ('-%' everywhere), predictions/ contains only a 5-instance smoke run where OMC failed 5/5 (vanilla 5/5, 0 tokens recorded \u2014 likely harness debugging), and benchmarks/baselines contains explicit zero-filled placeholders ('run bench:prompts:save to populate'). No in-repo proof OMC outperforms vanilla Claude Code.", + "how_it_works": "benchmark/{run_benchmark.py,evaluate.py,compare_results.py,analyze_failures.py,Dockerfile}; benchmark/predictions/*/stats.json (the failed smoke run); benchmarks/shared/{types,scorer,runner,reporter}.ts re-exporting benchmarks/harsh-critic/scoring/scorer.ts; benchmarks/baselines/2026-03-08-consolidation.json (placeholders); geobench/oh-my-claudecode.yaml (GEO visibility profile).", + "zo_relevance": "Two takeaways. Cautionary: OMC demonstrates that orchestration frameworks accrete unverified self-improvement claims \u2014 ZO's oracle-first stance is the antidote, and ZO should never ship a mode without a completed benchmark run backing it. Adoptable: the agent-prompt regression pattern (fixtures with planted flaws + keyword-matched ground truth + baseline snapshots) is exactly what ZO needs for its own agent persona evolution \u2014 when the self-evolution protocol edits an agent's rules after a failure, a fixture regression run would verify the edit catches the original failure without degrading other behaviors, mechanizing ZO's 'verify the updated rule would have caught the original failure' step.", + "evidence_files": [ + "benchmark/README.md", + "benchmark/results/README.md", + "benchmark/predictions/omc/stats.json", + "benchmarks/shared/types.ts", + "benchmarks/shared/scorer.ts", + "benchmarks/baselines/2026-03-08-consolidation.json", + "geobench/oh-my-claudecode.yaml" + ] + }, + { + "name": "Cross-provider orchestration (ccg, omc ask, external critics)", + "what_it_is": "Structured use of non-Claude CLIs as advisors and workers: /ccg decomposes a request into a Codex prompt (architecture/backend/risk) and an Antigravity/Gemini prompt (UX/docs/alternatives), runs both via omc ask, and has Claude synthesize; team workers can be codex/gemini/antigravity/cursor; ralph's completion critic can be external Codex (--critic=codex).", + "why_special": "The role-shaped decomposition is more disciplined than 'ask another model': each provider gets a lane matched to its strengths, artifacts land under .omc/artifacts/ask/, and graceful degradation is specified when a CLI is missing. Using an external model as the completion critic is a real defense against same-model blind-spot correlation in verification.", + "how_it_works": "skills/ccg/SKILL.md (decompose \u2192 omc ask codex / omc ask antigravity \u2192 synthesize); src/team/cli-worker-contract.ts and cli-detection.ts for worker CLIs; ralph verifier codex mode in src/hooks/ralph/verifier.ts (getVerificationAgentStep 'codex' branch); per-role routing in omc.jsonc team.roleRouting.", + "zo_relevance": "Optional but interesting for ZO's oracle tier: an external-provider critic reviewing completion claims decorrelates verifier errors from executor errors (both Claude in ZO today). For ML projects this is lower value than ZO's executable metrics, but for the code-quality gates (phase reviews) a cheap cross-model second opinion is a genuine robustness upgrade. Low priority; adds CLI dependencies ZO's philosophy avoids.", + "evidence_files": [ + "skills/ccg/SKILL.md", + "src/hooks/ralph/verifier.ts", + "src/team/cli-worker-contract.ts" + ] + } + ], + "architecture_notes": "Core pattern: \"prompt protocols + deterministic hook-boundary state machines.\" Skills (markdown) define agent behavior; compiled TS hooks (scripts/*.mjs bundled from src/, loaded via hooks/hooks.json into every Claude Code hook event) enforce state transitions, block stops, and inject system-reminders. The two layers communicate through file-based JSON state under .omc/state/ with strict session scoping (.omc/state/sessions/{sessionId}/), atomic writes, advisory file locks, session-identity validation on every read (state.session_id !== sessionId \u2192 null), and worktree-root resolution (OMC_STATE_DIR > .omc-workspace marker > git root > cwd) for multi-repo setups. mode-registry does file-existence-based mode detection only (no imports from mode modules) to avoid circular dependencies. Modes compose as layers (autopilot \u2283 ralph \u2283 ultrawork; team \u00d7 ralph via getTeamPhaseDirective), with a skill-state workflow ledger resolving which mode is the stop-gating authority in nested runs. Kill switches everywhere: DISABLE_OMC, OMC_SKIP_HOOKS (per-hook granularity), OMC_TEAM_WORKER (workers exempt from persistence). Local-fork discipline: plugin loads dist/ not src/, so TS edits require npm run build \u2014 documented in CLAUDE.md with a reminder skill.\n\nDevelopment culture is regression-driven: nearly every guard clause cites a GitHub issue number (context-limit deadlock #213, rate-limit loop #777, auth loop #1308, over-orchestration #790, ralplan gate #997, skill-state blocking #1033, unified pipeline #1130), and the commit protocol mandates trailers (Constraint/Rejected/Directive/Confidence/Scope-risk/Not-tested) that preserve decision context in git history \u2014 functionally OMC's version of ZO's DECISION_LOG+PRIORS, but encoded in code comments, tests, and commit metadata rather than markdown memory files. The scale cost is real: 3,366-line bridge.ts, 2,564-line persistent-mode hook, 27,781-line team runtime; the system needs its own doctor command (omc-doctor), HUD statusline (src/hud with mission board, agent overlay, context/usage tracking), and setup/repair tooling to stay operable. Distribution is a Claude Code plugin (.claude-plugin/, agents/, skills/, commands/, hooks/) with 12 translated READMEs \u2014 a mass-market product posture, versus ZO's single-team platform posture.", + "weaknesses": [ + "Self-improvement claims are unverified in-repo: the SWE-bench vanilla-vs-OMC harness exists but results/README.md is an empty template, and the only committed run data is a 5-instance smoke test where OMC failed 5/5 (vanilla 5/5) \u2014 benchmark/predictions/omc/stats.json. Agent-prompt benchmark baselines are explicit zero placeholders.", + "Significant aspirational/dead code presented as capability: src/features/model-routing (signal-based complexity router with escalation), src/verification/tier-selector.ts, and src/features/task-decomposer are exported but have zero runtime callers \u2014 actual model routing and verification tiering are prompt-convention only.", + "Completion verification outside autoresearch is LLM-judged, not oracle-grade: detectArchitectRejection() matches rejection via brittle regexes over free text; approvals force-accept after 3 failed verification attempts, so a persistently failing verifier silently converts to a pass.", + "Complexity is at the edge of maintainability: 337K LOC of TS in src/, a 1,114-line keyword detector whose bulk is multilingual false-positive suppression (fundamental fragility of magic-keyword UX), and a stop-decision path whose correctness depends on ~10 interacting circuit breakers accreted from production incidents.", + "The stop-blocking design generated repeated production failure loops before the guards existed (context-limit deadlocks, rate-limit retry loops, auth loops) \u2014 evidence that hard-blocking Stop events is intrinsically hazardous and each new stop-context type is a new failure mode.", + "geobench/ is marketing tooling (LLM answer share-of-voice for the project itself) living in the repo under a name that suggests quality benchmarking.", + "Named autopilot workflow profiles (the most rigorously engineered stage-advancement path) are Linux-only (flock, no-follow fd traversal) and defer model routing, making the flagship v1 feature unavailable to macOS-default Claude Code users.", + "The 'team' magic keyword had to be permanently disabled after causing infinite recursive worker spawning \u2014 keyword-triggered heavy orchestration proved unsafe for any prompt text that can reach workers." + ], + "notable_files": [ + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/persistent-mode/index.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/keyword-detector/index.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/ralph/loop.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/ralph/verifier.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/ralph/prd.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/autopilot/types.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/autopilot/enforcement.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/team-pipeline/types.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/team/heartbeat.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/team/role-router.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/team/runtime-v2.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/hooks/task-size-detector/index.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/autoresearch/contracts.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/lib/security-config.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/ralph/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/autopilot/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/team/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/ultrawork/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/autoresearch/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/hooks/hooks.json", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/CLAUDE.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/benchmark/results/README.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/benchmarks/shared/types.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/agents/critic.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/agents/executor.md" + ] + }, + { + "repo": "oh-my-claudecode", + "lens": "components", + "summary": "OMC is a large (v4.15.7, ~3.7k GitHub PRs/issues referenced in commits) Claude Code plugin implementing multi-agent orchestration through four interlocking component types: 19 markdown agent personas, 41 skills, 28 slash commands, and lifecycle hooks, all backed by a TypeScript runtime (src/, compiled to dist/) that is dual-distributed as both an npm package (bin: omc) and a Claude Code marketplace plugin. The component taxonomy is real and deliberate: agents are organized into 4 \"lanes\" (Build/Analysis, Review, Domain, Coordination) with a canonical workflow (explore \u2192 analyst \u2192 planner \u2192 critic \u2192 executor \u2192 verifier); skills carry a 1\u20137 \"level\" tier in frontmatter and compose via an explicit inclusion algebra (ultrawork \u2282 ralph \u2282 autopilot) documented in every skill's Use_When/Do_Not_Use_When sections; commands are deliberately thin dispatch shims that exist purely to save context tokens.\n\nThe design philosophy is \"behavior injection over agent swapping\": skills modify how the orchestrator operates (an Execution layer + 0-N Enhancement layers + optional Guarantee layer like ralph's can't-stop loop), activated by three channels \u2014 slash commands, hook-detected magic keywords (\"ralph\", \"ultrawork\", \"autopilot\" in natural language), and a skill-injector hook that recursively loads user/project learned skills. The most sophisticated engineering is invisible in the README: a tested context-budget system (64KB total / 2KB per skill) that compacts full SKILL.md bodies into registry shims at plugin install time, machine-checked per-stage deliverable contracts enforced by a SubagentStop hook, hash-validated user-defined workflow profiles constrained to whitelisted stage sequences, and a mission/sandbox evaluator contract (JSON pass/score, sealed benchmark files) that is a close cousin of ZO's oracle concept.\n\nVerification of claims: the marketplace metadata (\"28 agents, 32 skills\") is stale \u2014 actual counts are 19 agent .md files and 41 SKILL.md dirs, and the README itself says 19. The LOW/MEDIUM/HIGH tier-variant agent system described in docs/agent-templates (executor-low etc.) is largely vestigial \u2014 real tiering now happens via a PreToolUse \"delegation enforcer\" hook that injects the model parameter into Task calls from agent definitions. The agent benchmark harness (fixtures + ground-truth + shared scorer) exists but is thin (3 ground-truth files for code-reviewer). Everything else inventoried here was verified in source.", + "key_features": [ + { + "name": "Structured agent persona schema with explicit non-responsibilities and handoff pointers", + "what_it_is": "All 19 agent .md files follow one pseudo-XML schema: Role (including 'You are NOT responsible for X (that's agent Y)'), Why_This_Matters, Success_Criteria, Constraints (with named handoff targets), Investigation_Protocol, Tool_Usage, Execution_Policy, Output_Format. Frontmatter carries name, description, model (haiku/sonnet/opus), level, and disallowedTools (review agents are hard-blocked from Write/Edit).", + "why_special": "Most agent libraries define personas by what they do; OMC defines them equally by what they must NOT do, with an explicit routing pointer for each exclusion ('hand off to critic for plan review'). Combined with a documented role-disambiguation table for the 4 opus-tier agents (architect/analyst/planner/critic), this makes 19 agents composable without overlap. disallowedTools in frontmatter is enforcement, not convention.", + "how_it_works": "agents/*.md are the source of truth; src/agents/definitions.ts loads them (esbuild injects prompts at build time via __AGENT_PROMPTS__, runtime file-read fallback), applies config-based model overrides, and exposes getAgentDefinitions() to the SDK. 10 deprecated agent names alias to current agents for backward compat. The lead orchestrator prompt (omcSystemPrompt in definitions.ts) carries the full roster with lane groupings.", + "zo_relevance": "Directly adoptable. ZO's specs/agents.md personas would get sharper contract-first boundaries by adding the 'not responsible for (agent X)' cross-reference pattern and Why_This_Matters rationale blocks. The disallowedTools frontmatter (read-only reviewers/oracle) is a mechanical guarantee ZO's oracle agent should have \u2014 the verifier that cannot edit is structurally more trustworthy.", + "evidence_files": [ + "agents/architect.md", + "agents/critic.md", + "agents/analyst.md", + "src/agents/definitions.ts", + "src/agents/utils.ts" + ] + }, + { + "name": "Skill composition algebra with level taxonomy (ultrawork \u2282 ralph \u2282 autopilot)", + "what_it_is": "Skills declare a level (1\u20137) in frontmatter and compose in documented layers: Execution skill + 0-N Enhancement skills + optional Guarantee layer. ultrawork is explicitly 'a component, not a standalone persistence mode'; ralph wraps ultrawork with a PRD-driven persistence loop and reviewer sign-off; autopilot wraps ralph with the full idea-to-code pipeline. Every skill's Do_Not_Use_When section names the neighboring skill to use instead.", + "why_special": "This is the cleanest answer I've seen to 'how do you keep 41 skills from being 41 overlapping monoliths': make inclusion relations explicit in both directions, so the model routing between skills is written into the skills themselves. Level distribution observed: 1=reminders, 2=utilities (cancel/hud/setup), 3=artifact workflows (release/ultraqa/ultragoal), 4=orchestration engines (autopilot/ralph/ultrawork/team/plan/ralplan/self-improve/autoresearch), 5=multi-model (ccg), 7=self-improving (learner/writer-memory).", + "how_it_works": "skills//SKILL.md with Purpose/Use_When/Do_Not_Use_When/Why_This_Exists/Execution_Policy sections. ARCHITECTURE.md documents the 3-layer formula. Activation via slash command, magic keyword (keyword-detector.mjs UserPromptSubmit hook with priority-ordered hardcoded + configurable triggers), or skill-injector.mjs (recursive discovery of learned skills in .claude/skills, .omc/skills, .agents/skills).", + "zo_relevance": "ZO's skill set (memory:*, gates:*, observe:*, project:*) is heading toward the same sprawl. Adopt: (1) mandatory Use_When/Do_Not_Use_When cross-links naming the alternative skill, (2) an explicit component-vs-workflow distinction so e.g. memory:recall is marked as a component that project:launch includes. Caveat: OMC never documents what the level numbers mean anywhere discoverable \u2014 adopt the idea, not the undocumented execution.", + "evidence_files": [ + "skills/ultrawork/SKILL.md", + "skills/ralph/SKILL.md", + "skills/autopilot/SKILL.md", + "docs/ARCHITECTURE.md", + "scripts/keyword-detector.mjs" + ] + }, + { + "name": "Context-budget engineering: compact skill shims + dispatch commands", + "what_it_is": "Two-tier defense against the context tax of a 41-skill library: (1) all 28 commands/*.md are ~15-line dispatch shims with empty descriptions that tell Claude to read the full SKILL.md on demand; (2) at plugin install, compactPluginSkillPayload() archives every full SKILL.md and replaces the registered copy with a ~2KB shim pointing at the archived body, enforced by a vitest gate: 64KB total / 2KB per-file budget across all registered skills.", + "why_special": "This is a genuinely hard-won insight most agent-library authors miss: every registered skill description is a permanent tax on every session's context window, so a large library must actively fight its own weight. OMC made the budget a CI-enforced invariant (plugin-skill-budget.test.ts references issues #2943/#2986), not a style guideline. The lazy-load indirection (shim \u2192 full body under a plugin-root-relative path) is ugly but measured.", + "how_it_works": "commands/*.md say 'read skills//SKILL.md and follow it, treating arguments as $ARGUMENTS'. src/installer/index.ts renderCompactPluginSkillShim() rewrites frontmatter (description preserved, omc-full-body path added) and writes a body instructing Claude to read the archived full skill. Test asserts plugin.json skills array exactly equals skills/ dirs AND total shim bytes under budget.", + "zo_relevance": "High. ZO already has ~25 skills registered and each description loads into every session. Adopt the budget-as-test idea directly: a CI check on total frontmatter-description bytes across .claude/skills and commands, plus thin-shim pattern for rarely-used skills. This is cheap to implement in ZO's validate-docs.sh cascade.", + "evidence_files": [ + "commands/verify.md", + "src/installer/index.ts", + "src/__tests__/plugin-skill-budget.test.ts", + "commands/autoresearch.md" + ] + }, + { + "name": "Machine-checked stage deliverable contracts (templates/deliverables.json + SubagentStop hook)", + "what_it_is": "A JSON contract declaring, per team-pipeline stage, what files the stage must produce with minimum size, required sections, and required regex patterns (e.g. team-plan must yield DESIGN.md \u2265500 bytes containing '## File Ownership' and '## Architecture'; team-verify must yield QA_REPORT.md matching \\b(PASS|FAIL)\\b). The verify-deliverables.mjs hook checks this on SubagentStop.", + "why_special": "This converts 'contract-first spawning' from a prompt-level promise into a mechanically enforced gate \u2014 the subagent literally cannot be considered finished if its artifact is missing, too small, or lacks required sections. It's a small file but it's the difference between asking for a deliverable and verifying one.", + "how_it_works": "hooks/hooks.json registers scripts/... verify-deliverables.mjs on SubagentStop; it reads templates/deliverables.json keyed by pipeline stage (team-plan/team-prd/team-exec/team-verify/team-fix) and validates the produced files.", + "zo_relevance": "Very high \u2014 this is ZO's contract-first principle, mechanized. ZO defines agent interfaces before spawning but (per its specs) verifies via the oracle at phase level. Adding a per-agent deliverable schema (files + requiredSections + patterns) checked by a SubagentStop hook would catch contract violations at spawn granularity, before the oracle phase gate. Trivially portable: it's one JSON file + one hook script.", + "evidence_files": [ + "templates/deliverables.json", + "hooks/hooks.json", + "scripts/verify-deliverables.mjs" + ] + }, + { + "name": "Mission/sandbox evaluator contract (autoresearch) \u2014 OMC's oracle analog", + "what_it_is": "Missions are mission.md (goal) + sandbox.md (YAML frontmatter declaring evaluator.command, evaluator.format=json, optional keep_policy of score_improvement|pass_only) pairs. The autoresearch skill runs a bounded single-mission improvement loop where evaluator output MUST be JSON with a required boolean `pass` and optional numeric `score`; non-passing iterations continue; stop conditions are explicit (max-runtime). Contract violations are hard errors parsed in src/autoresearch/contracts.ts. The sibling self-improve skill adds tournament selection across N executor candidates, sealed benchmark files (validate.sh prevents the loop from modifying its own evaluation), plateau detection, and circuit breakers.", + "why_special": "This is a strictly-typed, tamper-resistant version of 'hard verifiable success metric'. The sealed-files rule (the improvement loop cannot edit the benchmark) and keep_policy semantics (only keep changes that improve score) are exactly the anti-Goodhart mechanics an autonomous improvement loop needs, and they are enforced in code, not prose.", + "how_it_works": "src/autoresearch/contracts.ts validates sandbox.md frontmatter with specific error messages per violation; runtime keeps per-iteration evaluation JSON + markdown decision logs under .omc/autoresearch/. self-improve (skills/self-improve/SKILL.md) orchestrates research\u2192plan\u2192architect/critic review\u2192N parallel executors\u2192benchmark\u2192tournament merge via git-master, with state under .omc/self-improve/ (config/goal.md, harness.md guardrail rules H001-H003, iteration history, plan archive).", + "zo_relevance": "ZO's oracle is the same idea; what's worth stealing is the formalization: (1) evaluator output as a strict JSON schema {pass: bool, score?: number} rather than free-form verification, (2) sealed-files enforcement so agents can't touch oracle code \u2014 ZO's repo-separation partially covers this but not within the delivery repo, (3) keep_policy as an explicit merge criterion, (4) plateau/circuit-breaker stop conditions for ZO's build loops. The tournament-of-N-executors pattern is also a candidate for ZO's hardest subtasks.", + "evidence_files": [ + "skills/autoresearch/SKILL.md", + "src/autoresearch/contracts.ts", + "skills/self-improve/SKILL.md", + "missions/optimize-omc/sandbox.md" + ] + }, + { + "name": "Delegation Enforcer: hook-based model routing instead of prompt-trusted routing", + "what_it_is": "A PreToolUse hook (pre-tool-enforcer.mjs) that intercepts Task/Agent calls and auto-injects the model parameter from the agent's definition when the orchestrator omitted it, so model routing is guaranteed rather than dependent on the orchestrator remembering.", + "why_special": "Recognizes that Claude Code does not automatically apply per-agent model defaults on Task calls, and that trusting the orchestrator prompt to always pass model= is a silent cost/quality bug (forgotten params default to the expensive parent model). Turning routing policy into middleware is the correct architectural move. Complemented by a cross-provider Model \u00d7 Agent compatibility matrix doc encoding rules like 'planning/review = expensive, implementation = cheap (5-20x token weight difference)' and 'agent X breaks with GPT-family tool calling'.", + "how_it_works": "hooks/hooks.json wires scripts/pre-tool-enforcer.mjs on PreToolUse matcher *; agent default models come from agents/*.md frontmatter via the TS registry; docs/DELEGATION-ENFORCER.md describes the injection; scripts/lib/agent-model-config.mjs and model-routing-override-message.mjs support overrides.", + "zo_relevance": "ZO's specs/agents.md defines model tiers per agent but (as a spec) relies on the lead orchestrator honoring them. A PreToolUse hook that validates/injects model per agent \u2014 and blocks spawns violating tier policy \u2014 would make ZO's routing self-enforcing. Also adopt the matrix's budgeting rule of thumb: spend on rare decisive calls (planner/oracle), economize on high-volume executor calls.", + "evidence_files": [ + "docs/DELEGATION-ENFORCER.md", + "scripts/pre-tool-enforcer.mjs", + "docs/agents/model-compatibility.md", + "scripts/lib/agent-model-config.mjs" + ] + }, + { + "name": "Skillify: session-to-skill extraction with a quality gate", + "what_it_is": "A meta-skill that turns a workflow discovered during a session into a reusable skill draft, gated by three tests that ALL must pass: not Googleable in 5 minutes, specific to this codebase/workflow, and required real debugging/design effort to discover. Extracted skills are stored in user/project skill dirs and re-injected into future sessions by the skill-injector hook.", + "why_special": "The quality gate is the notable part \u2014 it prevents the failure mode where a self-improving system accumulates hundreds of trivial 'skills' that are really documentation. The learner skill (its predecessor) even separates a self-updatable Expertise section from a stable Workflow section, with explicit BAD/GOOD examples distinguishing principle-extraction from snippet-mimicking.", + "how_it_works": "skills/skillify/SKILL.md defines the gate and requires frontmatter-complete skill files written to flat file-backed paths; scripts/skill-injector.mjs (UserPromptSubmit) recursively discovers and injects learned skills with per-session caps (MAX_SKILLS_PER_SESSION, descriptor char limits).", + "zo_relevance": "Maps directly onto ZO's PRIORS.md self-evolution protocol. ZO's 'add a prior after every failure' rule has no quality gate \u2014 adopting skillify's three-question filter (non-Googleable / project-specific / hard-won) would keep PRIORS.md high-signal as it grows. The injection caps (max N learned items per session, char budgets) are also relevant to keeping ZO's memory-priming lean.", + "evidence_files": [ + "skills/skillify/SKILL.md", + "skills/learner/SKILL.md", + "scripts/skill-injector.mjs" + ] + }, + { + "name": "Whitelisted workflow profiles with hash-validated descriptors", + "what_it_is": "Users can define named autopilot workflows in .claude/omc.jsonc / user config, but stage sequences are constrained to exactly four approved compositions ([ralplan, execution], [ralplan, execution, ralph], [ralplan, execution, qa], [ralplan, execution, ralph, qa]); names are regex-validated with a reserved-name blacklist; the selected profile becomes a canonical-JSON sha256-hashed descriptor validated on every read; runtime support is gated (Linux + flock only).", + "why_special": "An unusually disciplined take on extensibility: instead of letting users compose arbitrary stage graphs (which would explode the test matrix), OMC whitelists the sequences it has actually verified. The tamper-evident descriptor hashing and the paranoid transcript reader (O_NOFOLLOW path walking, stat-before/after identity checks, bounded JSONL records) show state-integrity engineering rare in prompt-orchestration projects.", + "how_it_works": "scripts/lib/workflow-profile-runtime.mjs: SEQUENCES frozen whitelist, validateDefinitions() with reserved names, selectWorkflowProfile() producing hash-stamped descriptors, resolveWorkflowStagePrompt() only for hash-valid state; consumed by keyword-detector.mjs on /autopilot --workflow invocations.", + "zo_relevance": "ZO's workflow.md phases + gates are a fixed pipeline today. When ZO adds configurable pipelines (e.g., per-project phase subsets), copy the whitelist-plus-hash approach: enumerate approved phase sequences rather than allowing arbitrary DAGs, and stamp the chosen profile into STATE.md with a hash so mid-project tampering or drift is detectable \u2014 this aligns with ZO's oracle drift-detection goals.", + "evidence_files": [ + "scripts/lib/workflow-profile-runtime.mjs", + "scripts/lib/workflow-stage-prompts.mjs", + "scripts/keyword-detector.mjs" + ] + }, + { + "name": "Agent prompt benchmark harness (regression tests for personas)", + "what_it_is": "benchmarks/ contains per-agent benchmark suites (code-reviewer, debugger, executor, harsh-critic) with code fixtures, ground-truth JSON (e.g. known findings in code-sql-injection.json), a shared scorer (finding-matching + aggregation, harsh-critic scorer as reference implementation), runner, and baselines dir.", + "why_special": "Treats agent persona prompts as testable software: change the critic's prompt, re-run the benchmark, compare found-vs-ground-truth findings against a baseline. Almost nobody regression-tests their prompt library. Caveat: coverage is thin (3 ground-truth files for code-reviewer), so this is more proof-of-pattern than mature infrastructure.", + "how_it_works": "benchmarks/shared/{runner,scorer,parser,reporter}.ts + benchmarks//{fixtures,ground-truth,prompts,run-benchmark.ts}; run-all.ts orchestrates; baselines/ stores prior scores.", + "zo_relevance": "ZO evolves its own rules and agent specs after every failure (self-evolution protocol) but has no way to know whether a rule edit made agents better or worse. A ground-truth benchmark per critical agent (especially ZO's oracle and reviewer personas) would let the self-evolution protocol verify its own edits \u2014 closing the loop ZO's evolution.md aspires to. Start with the same shape: fixtures + expected-findings JSON + scorer.", + "evidence_files": [ + "benchmarks/shared/scorer.ts", + "benchmarks/code-reviewer/run-benchmark.ts", + "benchmarks/code-reviewer/ground-truth/code-sql-injection.json", + "benchmarks/run-all.ts" + ] + }, + { + "name": "Dual distribution with generated-closure verification and version sync", + "what_it_is": "One repo ships as an npm package (bin: omc/oh-my-claudecode, compiled dist/ + bridge/ bundles) and as a Claude Code plugin (.claude-plugin/plugin.json listing all 41 skill dirs, commands dir, and .mcp.json MCP server). scripts/sync-version.sh (npm version lifecycle hook) syncs the version into plugin.json, marketplace.json, and a docs/CLAUDE.md marker; scripts/plugin-shipping-surface.mjs computes the exact generated-file closure from entrypoints and CI commits 'authorize exact generated closure' for each PR; compose-docs.mjs assembles docs from {{INCLUDE:}} partials copied to docs/shared for skills to reference.", + "why_special": "The generated-closure verifier is the standout: because the plugin checkout must carry built artifacts, they made 'which generated files are legitimate' a computed, CI-authorized set starting from entrypoints \u2014 preventing both stale bundles and smuggled files. Version sync via lifecycle hook plus tests asserting plugin.json == skills/ dirs is the automated version of ZO's manual cascade rules.", + "how_it_works": "package.json files whitelist; sync-version.sh perl-patches satellite files and stages them into the version commit; plugin-shipping-surface.mjs resolves module graphs with the TS compiler API; src/__tests__/plugin-skill-budget.test.ts asserts registry completeness.", + "zo_relevance": "ZO's CLAUDE.md cascade chains (agent added \u2192 update 6 files) are enforced by validate-docs.sh + a commit-blocking hook, which is philosophically identical but manual-update-then-verify. OMC shows the next step: generate or sync satellites from a single source (version sync script) and assert registry==filesystem in tests, so most cascade steps become impossible to forget rather than checked after the fact. The count-drift OMC still suffers (marketplace says 28 agents/32 skills vs actual 19/41) is exactly the failure ZO's cascade discipline exists to prevent \u2014 evidence that verification must cover marketing metadata too.", + "evidence_files": [ + "scripts/sync-version.sh", + "scripts/plugin-shipping-surface.mjs", + ".claude-plugin/plugin.json", + ".claude-plugin/marketplace.json", + "scripts/compose-docs.mjs" + ] + }, + { + "name": "Full lifecycle-event hook lattice (11 events) with persistence and drift guards", + "what_it_is": "hooks/hooks.json wires node scripts to UserPromptSubmit (keyword detection, skill injection), SessionStart (memory load, setup/maintenance matchers), PreToolUse (delegation enforcement), PermissionRequest (bash permission handling), PostToolUse (+failure variant), SubagentStart/Stop (tracking, deliverable verification), PreCompact (notepad save, project-memory save), Stop (context-guard, workflow-drift-guard, persistent-mode 'the boulder never stops', optional auto code-simplifier), SessionEnd (async session summary, wiki update).", + "why_special": "OMC uses hooks as the enforcement plane for everything its prompts promise: persistence modes survive because a Stop hook refuses to let the session end; memory survives compaction because PreCompact hooks snapshot to .omc/notepad.md; workflow drift is caught by a dedicated Stop-time guard. The prompt says 'never stop', but the hook makes it true. Escape hatches exist (DISABLE_OMC=1, OMC_SKIP_HOOKS).", + "how_it_works": "All hooks route through scripts/run.cjs wrapper with per-hook timeouts; state lives under .omc/ split into control plane (.omc/state/**) vs data plane (plans/notepads/prompts) with an explicit artifact-descriptor + bounded-handoff rule for large payloads (documented in ARCHITECTURE.md).", + "zo_relevance": "ZO uses one PreToolUse hook (commit blocking on validate-docs.sh). The gap: ZO's 'AUTOMATIC memory protocol' (STATE.md at session end, priors after failures) is prompt-enforced only. Porting three hooks would mechanize it: PreCompact \u2192 snapshot STATE.md-relevant context; Stop \u2192 refuse stop if session summary/DECISION_LOG not updated; SubagentStop \u2192 verify contract deliverables. The control-plane/data-plane split with descriptors instead of inline payloads is also a good pattern for ZO's comms JSONL logs.", + "evidence_files": [ + "hooks/hooks.json", + "scripts/persistent-mode.mjs", + "scripts/pre-compact.mjs", + "scripts/workflow-drift-guard.mjs", + "docs/ARCHITECTURE.md" + ] + } + ], + "architecture_notes": "Component model: four types with distinct contracts. (1) Agents = markdown personas (agents/*.md, single source of truth) mirrored by a TS registry (src/agents/definitions.ts) that build-injects prompts via esbuild define (__AGENT_PROMPTS__) with runtime file-read fallback \u2014 so the same persona works in plugin mode, npm CLI mode, and SDK mode. (2) Skills = directories with SKILL.md, self-describing activation conditions (Use_When/Do_Not_Use_When), composition level in frontmatter. (3) Commands = pure dispatch shims to skills (token-cost indirection). (4) Hooks = the enforcement plane; ~25 node scripts on 11 lifecycle events, all routed through run.cjs with timeouts.\n\nLayering: the orchestrator lives in the main session (system prompt appended, ALL-CAPS persistence rhetoric \u2014 the older prompt generation), skills mutate its behavior, agents execute via Task with model injected by hook middleware. State is filesystem-first under .omc/ with an explicit control-plane (small JSON state) vs data-plane (plans, notepads, prompts, artifacts) split and a documented artifact-descriptor schema (kind/path/hash/producer/retention) for bounded handoffs \u2014 the same problem ZO's comms.md addresses.\n\nThere are visibly two generations of design in the repo: an older template-based tier-variant system (docs/agent-templates with {{TIER_INSTRUCTIONS}} injection, executor-low/-medium/-high naming, stale model names) that is now vestigial, and the current single-persona-plus-model-routing system. Deprecated names are kept as aliases everywhere (10 agent aliases, learner\u2192skillify, swarm removed with PR reference) \u2014 heavy backward-compat discipline consistent with a plugin that has thousands of external users. Cross-CLI escape hatches exist throughout: team workers can be Codex/Gemini/Antigravity CLIs, ralplan can route architect/critic passes to Codex (--architect codex), ccg fans out to three model vendors \u2014 the component system treats non-Claude models as pluggable workers within Claude-orchestrated pipelines.\n\nScale management is the meta-lesson: with 41 skills and 19 agents, OMC's biggest engineering investments are in (a) context-budget enforcement, (b) discoverability (omc-reference skill, ARCHITECTURE.md decision tables, magic keywords so users never memorize the taxonomy), and (c) registry==filesystem test gates. The taxonomy teaches that lanes (grouping by pipeline position) beat flat rosters, and inclusion algebra beats feature lists for overlapping workflow skills.", + "weaknesses": [ + "Metadata count drift: .claude-plugin/marketplace.json advertises '28 agents, 32 skills' while the repo actually contains 19 agent .md files and 41 SKILL.md dirs (README correctly says 19) \u2014 the marketing surface is not covered by the otherwise strict registry tests.", + "The skill 'level' (1\u20137) frontmatter taxonomy is undocumented anywhere discoverable; levels 5 and 6 are nearly/completely unused, and the meaning must be reverse-engineered from one sentence inside the deprecated learner skill ('Level 7 = self-improving').", + "The LOW/MEDIUM/HIGH tier-variant agent template system (docs/agent-templates/, executor-low examples, stale model IDs like claude-opus-4-8/claude-sonnet-4-5) is vestigial \u2014 actual routing moved to frontmatter model + delegation-enforcer hook, but the docs still teach the old flow.", + "Skill sprawl with overlapping persistence/looping modes (ralph vs ultragoal vs autopilot vs team+ralph vs self-improve vs autoresearch vs ultraqa): each pair is disambiguated in prose, but the cognitive load is high and the disambiguation burden falls on Do_Not_Use_When paragraphs rather than structural simplification.", + "missions/ in the repo root contains near-empty dogfooding artifacts (mission.md files with 2-3 words) committed to the public repo \u2014 the mission format is real (autoresearch contract) but these files are noise, and nothing in-repo consumes the missions/ directory itself.", + "Two generations of prompt style coexist: the orchestrator system prompt uses threat-style ALL-CAPS prompting ('VIOLATION IS FAILURE', 'saying complete without verification is a LIE') while the newer agent .md files use evidence-based structured personas \u2014 an unreconciled internal inconsistency.", + "Agent benchmarks are proof-of-pattern, not coverage: only 3 ground-truth fixtures for code-reviewer, 4 agent suites total for 19 agents; persona changes for the other 15 agents ship untested.", + "Duplication between templates/hooks/*.mjs and scripts/*.mjs hook implementations creates a second copy of hook logic to keep in sync.", + "Deep platform coupling for advanced features: workflow profiles hard-require Linux + /usr/bin/flock; several state-integrity paths depend on /proc/self/fd \u2014 degrading silently on macOS where much of the audience runs." + ], + "notable_files": [ + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/docs/ARCHITECTURE.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/agents/critic.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/agents/architect.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/agents/definitions.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/ralph/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/ultrawork/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/autopilot/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/self-improve/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/autoresearch/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/skills/skillify/SKILL.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/autoresearch/contracts.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/templates/deliverables.json", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/hooks/hooks.json", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/scripts/keyword-detector.mjs", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/scripts/lib/workflow-profile-runtime.mjs", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/installer/index.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/src/__tests__/plugin-skill-budget.test.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/docs/DELEGATION-ENFORCER.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/docs/agents/model-compatibility.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/docs/agent-templates/tier-instructions.md", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/benchmarks/shared/scorer.ts", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/scripts/sync-version.sh", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/scripts/plugin-shipping-surface.mjs", + "/Users/sam101fe4x/Documents/code/oh-my-claudecode/commands/verify.md" + ] + }, + { + "architecture_notes": "Delivery model: OMC is a Claude Code plugin + npm CLI (package `oh-my-claude-sisyphus`, v4.15.7). Runtime chain: hooks/hooks.json registers every Claude Code hook event -> scripts/run.cjs (cross-platform runner) -> thin scripts/*.mjs shims -> compiled TypeScript in dist/. run.cjs is itself a resilience layer: it launches hooks with process.execPath (no PATH dependence), self-heals a stale CLAUDE_PLUGIN_ROOT by scanning the plugin cache for the newest semver directory after plugin updates, and runs trusted UserPromptSubmit hooks in worker_threads so the runner owns the synchronous timeout boundary. Every hook fails open ({continue:true, suppressOutput:true} on any error), reads stdin with timeout protection, and honors kill switches (DISABLE_OMC, per-hook OMC_SKIP_HOOKS). State layout: per-project .omc/state with session-scoped subdirectories (state/sessions//...), plus a global config dir; all writes go through atomic-write + file-lock helpers; session IDs are regex-validated to block path traversal. Worktree-aware path resolution (resolveToWorktreeRoot, transcript path repair for git worktrees) appears everywhere. Hook events used: UserPromptSubmit, SessionStart (with matcher variants init/maintenance), PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, SubagentStart/Stop, PreCompact, Stop (4 chained hooks), SessionEnd (async). The development style is conspicuously issue-driven: the code cites dozens of GitHub issues inline (#213 compaction deadlock, #777 rate-limit infinite loop, #1308 auth-error loop, #1047 idle nudges, #3209 SubagentStop context reinjection), and each incident became a typed, tested escape hatch \u2014 the codebase is effectively a fossil record of every way blocking the Stop event can go wrong. Cost of this maturity: a 2,564-line Stop-hook module, ~30 interacting state files, and multi-MB bundled .cjs artifacts checked into bridge/ (cli.cjs 4MB, mcp-server.cjs 1.1MB).", + "key_features": [ + { + "name": "Persistent-mode Stop-hook engine (anti-stall core)", + "what_it_is": "A Stop-event interceptor that refuses to let the session go idle while work remains: Ralph loops, autopilot, ultrawork, team pipeline, active skills, and plain incomplete todos all block the stop and inject a continuation prompt, in a strict authority/priority order.", + "why_special": "Not the blocking itself (trivial) but the escape-hatch taxonomy hardened over ~4 years of issues: never block context-limit stops (compaction deadlock, #213), rate-limit stops (infinite 429 retry loop, #777), auth failures (#1308), user aborts, explicit /cancel (with cancel-race protection), scheduled wakeups, or oversize-tool-result redirect stops (bounded window of 3). Circuit breakers everywhere: max 5 todo-continuation attempts, a thinking-only streak guard that detects the model burning blocked stops on thinking-only turns and bails out, stop-breaker counters with TTLs, 2h stale-state thresholds, and a workflow-slot ledger with tombstones so stale mode files from crashed sessions cannot re-arm enforcement.", + "how_it_works": "hooks.json Stop event -> scripts/persistent-mode.mjs -> checkPersistentModes() in src/hooks/persistent-mode/index.ts (2,564 lines). Reads StopContext (stop_reason strings pattern-matched by isUserAbort/isContextLimitStop/isRateLimitStop/isAuthenticationError in src/hooks/todo-continuation/index.ts), consults a skill-active-state ledger (resolveAuthoritativeWorkflowSkill) so nested workflows (autopilot->ralph) escalate to the live parent, then returns {continue:false, message} to hard-block. applyThinkingOnlyStreakGuard() classifies the last assistant turn from the transcript and releases the stop after N thinking-only turns.", + "zo_relevance": "Directly actionable: ZO just committed a watchdog/heartbeat anti-stall design spec (297adac). Before implementing it, steal OMC's escape-hatch list wholesale \u2014 the categories of stops you must NEVER block (context-limit, rate-limit, auth, user-abort, cancel-in-progress) plus TTL'd circuit breakers and tombstoned state for crashed sessions. Each one is a production incident OMC already paid for. ZO's oracle-first framing pairs well: block the stop only while the oracle says the phase gate is unmet, with these same bypasses.", + "evidence_files": [ + "src/hooks/persistent-mode/index.ts", + "src/hooks/todo-continuation/index.ts", + "scripts/persistent-mode.mjs", + "hooks/hooks.json", + "src/hooks/persistent-mode/stop-hook-blocking.test.ts" + ] + }, + { + "name": "OMC HUD (statusline as operator dashboard)", + "what_it_is": "A full statusline program (`omc hud`) with ~30 composable element renderers: context %, todos with current item, active agent count, ralph/autopilot iteration and phase, background tasks, rate-limit buckets from the usage API, token usage, git repo/branch/status, thinking mode, last tool, a team-mode mission board, and an auto-generated session summary.", + "why_special": "This is the single biggest day-to-day UX differentiator: the operator sees orchestration state (which mode is active, which iteration, how many agents are alive, how close to compaction) at a glance without asking the model. Configurable presets (minimal/focused/full/dense/analytics/opencode), element ordering, maxWidth/wrap, and locale label packs (en, zh-CN). It even spawns a throttled background process to summarize the session for display, with PID-liveness guards against process accumulation.", + "how_it_works": "Claude Code statusline stdin JSON -> src/hud/index.ts -> parseTranscript + readHudState + omc-state readers (readRalphStateForHud, readAutopilotStateForHud) + usage-api.ts -> render.ts composes elements from src/hud/elements/*. Installer writes/repairs the statusLine entry in settings.json and tags it so non-OMC statuslines are preserved (isOmcStatusLine in src/installer/index.ts). Mission board state (src/hud/mission-board.ts) is fed by team/session events with atomic file writes.", + "zo_relevance": "High-value adopt. ZO's observe:watch is a pull-model command; a statusline showing {project alias, current phase, pending gate, oracle status, agents active, context %} would give Sam ambient awareness during long autonomous runs for near-zero cost. The element-renderer + preset architecture is worth copying; the ZO brand system even gives it a visual language. Start small: phase + gate + agent count + context bar.", + "evidence_files": [ + "src/hud/index.ts", + "src/hud/render.ts", + "src/hud/elements/", + "src/hud/mission-board.ts", + "src/installer/index.ts", + "docs/REFERENCE.md" + ] + }, + { + "name": "Two-way remote notifications (Discord/Telegram/Slack reply injection)", + "what_it_is": "Outbound notifications on session-start/stop/end/idle/ask-user-question/agent-call to Discord, Telegram, Slack (webhook and bot), generic webhooks, and tmux \u2014 plus a reply-listener daemon that receives human replies on those channels and injects them into the correct tmux pane, turning a phone into a remote control for an unattended session.", + "why_special": "Genuinely implemented two-way remote operation, not just fire-and-forget pings. The reply path is security-engineered: 0600 state files, bot tokens kept out of env, two-layer input sanitization, pane verification before injection, per-user authorization, rate limiting, and a hand-rolled Slack Socket Mode client with HMAC signature verification and replay-attack windows rather than a heavy SDK. Idle notifications have a cooldown so a stalled session pings you once, not sixty times.", + "how_it_works": "src/notifications/dispatcher.ts (all sends non-blocking with 10s/15s timeouts, failures swallowed), config.ts + presets.ts (including an OpenClaw gateway preset), template-engine.ts with redact.ts. Reply side: src/notifications/reply-listener.ts daemon polls Discord/Telegram and holds a Slack Socket Mode WebSocket (src/notifications/slack-socket.ts), maps message IDs to sessions via session-registry.ts, and injects via tmux send-keys. Idle-notification gating lives in persistent-mode (shouldSendIdleNotification/recordIdleNotificationSent).", + "zo_relevance": "Strong fit for ZO's unattended-run model: gate approvals are the obvious use case \u2014 when a phase gate goes pending, notify Slack/Telegram; the human replies 'approve'/'reject: reason' and the reply-listener injects /gates:approve into the session. The idle-notification-with-cooldown pattern also belongs in ZO's watchdog spec. Caveat: the injection path is tmux-only; ZO would need the same constraint or a different transport.", + "evidence_files": [ + "src/notifications/dispatcher.ts", + "src/notifications/reply-listener.ts", + "src/notifications/slack-socket.ts", + "src/notifications/session-registry.ts", + "src/notifications/presets.ts" + ] + }, + { + "name": "Rate-limit auto-resume daemon", + "what_it_is": "A background daemon that polls rate-limit status every minute, scans tmux panes for Claude Code sessions blocked on a rate limit, and sends the resume keystroke sequence when the limit resets \u2014 so an overnight run continues instead of sitting dead until morning.", + "why_special": "Solves the most common real-world killer of long autonomous runs (5-hour rate-limit windows) with zero human involvement. Complements the Stop-hook side, which deliberately refuses to loop-retry on 429 and instead pauses Ralph with a visible message.", + "how_it_works": "src/features/rate-limit-wait/daemon.ts (spawned detached, PID file + 0600 perms + 1MB log rotation), rate-limit-monitor.ts checks status, tmux-detector.ts scans panes for blocked prompts and sends resume sequences. Process liveness via src/platform process-identity checks (PID + start time) to avoid acting on recycled PIDs.", + "zo_relevance": "Adopt for ZO's long ML training/build phases. ZO's watchdog spec should distinguish 'stalled because stuck' (nudge/restart) from 'stalled because rate-limited' (wait for reset, then resume) \u2014 OMC implements exactly this split: persistent-mode pauses on 429, daemon resumes on reset.", + "evidence_files": [ + "src/features/rate-limit-wait/daemon.ts", + "src/features/rate-limit-wait/rate-limit-monitor.ts", + "src/features/rate-limit-wait/tmux-detector.ts" + ] + }, + { + "name": "Context-lifecycle guardrails (guard-stop, preemptive compaction, pre-compact persistence, notepad)", + "what_it_is": "A set of hooks that manage the context window as a first-class resource: a Stop hook that suggests session refresh above 75% usage (max 2 blocks, never blocks context-limit stops), PostToolUse warnings at 70%/90% with cooldowns and rapid-fire debounce for concurrent subagent floods, PreCompact hooks that persist project memory and wiki state before compaction destroys it, and a three-tier compaction-resilient notepad (Priority Context <=500 chars always reloaded; Working Memory auto-pruned after 7 days; MANUAL never pruned).", + "why_special": "Treats compaction as a survivable lifecycle event rather than a catastrophe. The notepad tiering is a clean, simple design for what survives context resets; the PreCompact hook point is the key mechanism ZO currently doesn't use at all.", + "how_it_works": "scripts/context-guard-stop.mjs (threshold via OMC_CONTEXT_GUARD_THRESHOLD, retry-guard file capping blocks at 2 per transcript, worktree-aware transcript path repair); src/hooks/preemptive-compaction/index.ts (500ms rapid-fire debounce, per-session warning state); hooks.json PreCompact -> pre-compact.mjs + project-memory-precompact.mjs + wiki-pre-compact.mjs; src/hooks/notepad/index.ts with file locks and atomic writes.", + "zo_relevance": "ZO's memory protocol (STATE.md at session start/end) has a blind spot: mid-session compaction. A PreCompact hook that flushes current phase/decisions to STATE.md before compaction would close it. The notepad's 'Priority Context always reloaded, size-capped' tier is a better-engineered version of what ZO wants STATE.md's header to be \u2014 adopt the size cap and auto-prune discipline.", + "evidence_files": [ + "scripts/context-guard-stop.mjs", + "src/hooks/preemptive-compaction/index.ts", + "src/hooks/notepad/index.ts", + "scripts/pre-compact.mjs", + "hooks/hooks.json" + ] + }, + { + "name": "Team-mode watchdog: heartbeats, idle nudges, worker restart sagas", + "what_it_is": "For multi-agent team mode (workers in tmux panes): each worker writes a heartbeat file every poll cycle; the lead checks freshness to detect dead workers; idle panes (prompt visible, no active task) get up to 3 tmux send-keys nudges after 30s ('Continue working... report concrete progress (not ACK-only)'); dead workers go through restart/recovery sagas with task checkpoints.", + "why_special": "This is a real distributed-systems treatment of agent liveness: atomic heartbeat writes, process-identity locks (PID + start-time so a recycled PID isn't mistaken for a live worker), owner epochs, recovery checkpoints, and a nudge tracker with per-pane budgets. Most agent frameworks have nothing between 'spawn' and 'hope'.", + "how_it_works": "src/team/heartbeat.ts (heartbeat files under .omc/state/team-bridge/{team}/), src/team/idle-nudge.ts (paneLooksReady && !paneHasActiveTask => nudge via tmux-session.ts), src/team/worker-health.ts, worker-restart.ts, recovery-saga.ts, task-recovery-checkpoint.ts, process-identity-lock.ts, team-owner-epoch.ts. Wired through the team MCP bridge (bridge/team-mcp.cjs, src/mcp/team-server.ts) during omc_run_team_wait polling.", + "zo_relevance": "This is the reference implementation for ZO's freshly-specced watchdog/heartbeat system (297adac). The specific patterns to port: heartbeat-file freshness as the liveness primitive (works with ZO's file-based memory philosophy), idle detection requiring BOTH 'ready prompt' AND 'no active task', bounded nudge budgets before escalating to restart, and process-identity (PID+start-time) checks before any kill/restart decision.", + "evidence_files": [ + "src/team/heartbeat.ts", + "src/team/idle-nudge.ts", + "src/team/worker-restart.ts", + "src/team/recovery-saga.ts", + "src/team/process-identity-lock.ts", + "src/team/worker-health.ts" + ] + }, + { + "name": "Verification-at-stop guards (workflow-drift-guard + verify-deliverables)", + "what_it_is": "Two cheap, deterministic 'did you actually finish?' checks: a Stop hook that blocks when the last assistant message claims completion ('done/fixed/ready to merge') while the diff contains .skip/.only tests, TODO-implement placeholders, or 'throw new Error(NotImplemented)'; and a SubagentStop hook that verifies completing agents actually produced their configured deliverable files with minimum content (advisory, non-blocking).", + "why_special": "Hook-level, zero-LLM-cost lie detection. It catches the classic failure mode \u2014 agent declares victory over stubs \u2014 before any expensive verification runs. Deliberately fails open on ambiguity and (after regression #3209) never emits additionalContext on SubagentStop because that context gets reinjected into the finishing subagent.", + "how_it_works": "scripts/workflow-drift-guard.mjs (regex COMPLETION_CLAIM_RE on last_assistant_message + BLOCKER_PATTERNS scan over changed code files via git, returns decision:'block' with evidence); scripts/verify-deliverables.mjs (loads .omc/deliverables.json or templates/deliverables.json, path-traversal-sanitized existence/size checks).", + "zo_relevance": "Perfect complement to ZO's oracle: the oracle is the expensive tier-N gate; these are tier-0 gates that run on every stop for free. ZO's contract-first spawning already defines agent deliverables \u2014 verify-deliverables is literally 'check the contract's output files exist', which ZO could wire into SubagentStop today. The drift guard maps to ZO's 'evolution' principle: encode each observed lie pattern as a regex.", + "evidence_files": [ + "scripts/workflow-drift-guard.mjs", + "scripts/verify-deliverables.mjs", + "templates/deliverables.json" + ] + }, + { + "name": "Tool-failure retry guidance loop", + "what_it_is": "PostToolUseFailure hook records every tool failure (tool name, input preview, error, retry count) to session-scoped state; the Stop hook reads it and injects targeted retry guidance instead of a generic 'continue' when re-blocking a stop.", + "why_special": "Turns the anti-stall loop from 'nag harder' into 'nag with a diagnosis'. Retry counts let guidance escalate, and the state is session-scoped so parallel sessions don't cross-contaminate.", + "how_it_works": "scripts/post-tool-use-failure.mjs writes .omc/state/sessions//last-tool-error-state.json (atomic, session-id validated); src/hooks/persistent-mode/index.ts readLastToolError()/getToolErrorRetryGuidance() folds it into the continuation message.", + "zo_relevance": "Feeds ZO's self-evolution protocol mechanically: PRIORS.md entries currently depend on the model remembering to write them; a PostToolUseFailure hook gives a guaranteed, structured failure feed that a session-end job can distill into priors. Adopt the session-scoped state file pattern verbatim.", + "evidence_files": [ + "scripts/post-tool-use-failure.mjs", + "src/hooks/persistent-mode/index.ts" + ] + }, + { + "name": "Auto-allow permission handler", + "what_it_is": "A PermissionRequest hook that auto-approves a conservative safe-list of read-only/build commands (git status|diff|log, npm/pnpm/yarn lint|build|typecheck, tsc, eslint, prettier, cargo check, ls) and defers everything else to the normal prompt.", + "why_special": "Reduces permission-prompt fatigue without opening injection holes: any command containing shell metacharacters (;&|`$()<> etc.) is refused auto-approval; cat/head/tail were deliberately removed (arbitrary file reads); heredocs only whitelisted for git commit/tag (issue #608: heredoc bodies were being persisted into settings.local.json); it also honors existing settings.json allowlists.", + "how_it_works": "hooks.json PermissionRequest matcher Bash -> scripts/permission-handler.mjs -> src/hooks/permission-handler/index.ts (SAFE_PATTERNS, DANGEROUS_SHELL_CHARS, SAFE_HEREDOC_PATTERNS, readPermissionStringEntries against settings files).", + "zo_relevance": "Directly reusable for ZO's autonomous phases where permission prompts stall unattended runs. The security posture (metacharacter rejection, no file-read commands, heredoc carve-outs) is the part worth copying rather than reinventing \u2014 a naive allowlist is how injection happens.", + "evidence_files": [ + "src/hooks/permission-handler/index.ts", + "scripts/permission-handler.mjs" + ] + }, + { + "name": "Magic-keyword mode activation", + "what_it_is": "UserPromptSubmit hook that pattern-matches user prompts for mode keywords (ralph, autopilot/'build me an app', ulw/ultrawork, tdd, code review, deepsearch, ask codex/gemini/cursor) \u2014 including Korean and Japanese variants \u2014 and injects the corresponding mode activation into context, plus task-size classification to auto-scale effort.", + "why_special": "Zero-ceremony mode entry ('just say ralph'). The scars are instructive: the 'team' keyword is a never-match placeholder because worker prompts containing the word 'team' caused infinite recursive spawning; code fences are stripped to prevent false positives; 'ralph' excludes 'Ralph Lauren' in three languages; explicit slash invocations are parsed separately with path-collision lookaheads.", + "how_it_works": "scripts/keyword-detector.mjs -> src/hooks/keyword-detector/index.ts (KEYWORD_PATTERNS, KEYWORD_PRIORITY, removeCodeBlocks, KEYWORD_SKIP_PREDICATES, parseExplicitWorkflowSlashInvocation) + src/hooks/task-size-detector.", + "zo_relevance": "Low priority for ZO (single sophisticated operator, explicit skills already exist), but the anti-footgun details matter if ZO ever adds NL triggers: strip code fences, never let keywords that can appear in agent-to-agent prompts trigger spawning (the 'team' incident is exactly the recursive-spawn bug ZO's orchestrator could hit).", + "evidence_files": [ + "src/hooks/keyword-detector/index.ts", + "scripts/keyword-detector.mjs", + "src/hooks/task-size-detector/" + ] + }, + { + "name": "Automatic cross-session memory (project-memory, wiki, boulder, friction report)", + "what_it_is": "Hook-enforced state persistence: project-memory auto-detects project environment at SessionStart and injects a summary (with rescan merging that preserves user directives and hot paths); an LLM wiki (self-maintained markdown KB with ingest/query/lint) hooks SessionStart/SessionEnd/PreCompact; boulder-state persists the active plan across sessions with appended session IDs; session-friction-report mines transcripts for friction signals (error rates >20%, idle gaps >45min, oversized messages) to tell the operator which sessions went badly.", + "why_special": "The persistence is hook-automatic, not protocol-dependent \u2014 the model cannot forget to do it, because SessionEnd/PreCompact hooks do it regardless. The friction report is a genuinely novel operator tool: retrospective UX telemetry over your own transcripts.", + "how_it_works": "scripts/project-memory-session.mjs / -posttool.mjs / -precompact.mjs -> src/hooks/project-memory/* (detector, hot-path-tracker, directive-detector, learner); src/hooks/wiki/* (storage with locks, ingest, lint); src/features/boulder-state/*; src/features/session-friction-report/index.ts scanning transcript JSONL.", + "zo_relevance": "ZO's CLAUDE.md declares memory updates 'AUTOMATIC (NON-NEGOTIABLE)' but enforcement is prompt-protocol plus one commit-blocking hook. OMC shows the stronger pattern: SessionEnd/PreCompact hooks that write state unconditionally. Port that to STATE.md/DECISION_LOG. The friction report concept maps to ZO's retrospectives \u2014 mine session transcripts for stall/error signals to feed PRIORS.md with evidence instead of recollection.", + "evidence_files": [ + "src/hooks/project-memory/index.ts", + "src/hooks/wiki/index.ts", + "src/features/boulder-state/index.ts", + "src/features/session-friction-report/index.ts", + "src/hooks/session-end/index.ts" + ] + } + ], + "lens": "runtime-ux", + "notable_files": [ + "hooks/hooks.json", + "scripts/run.cjs", + "src/hooks/persistent-mode/index.ts", + "src/hooks/todo-continuation/index.ts", + "scripts/context-guard-stop.mjs", + "scripts/workflow-drift-guard.mjs", + "scripts/verify-deliverables.mjs", + "scripts/post-tool-use-failure.mjs", + "src/hooks/permission-handler/index.ts", + "src/hooks/keyword-detector/index.ts", + "src/hud/index.ts", + "src/hud/render.ts", + "src/hud/mission-board.ts", + "src/notifications/reply-listener.ts", + "src/notifications/slack-socket.ts", + "src/notifications/dispatcher.ts", + "src/features/rate-limit-wait/daemon.ts", + "src/team/heartbeat.ts", + "src/team/idle-nudge.ts", + "src/team/recovery-saga.ts", + "src/team/process-identity-lock.ts", + "src/hooks/notepad/index.ts", + "src/hooks/preemptive-compaction/index.ts", + "src/hooks/session-end/index.ts", + "src/features/session-friction-report/index.ts", + "src/hooks/recovery/index.ts", + "src/hooks/thinking-block-validator/index.ts", + "docs/REFERENCE.md" + ], + "repo": "oh-my-claudecode", + "summary": "oh-my-claudecode (OMC, npm package `oh-my-claude-sisyphus` v4.15.7) is a large, mature Claude Code plugin providing multi-agent orchestration with an unusually deep runtime-UX layer. Through the runtime-ux lens, its design philosophy is: (1) the session must never silently stall \u2014 a Stop-hook engine blocks premature stops while work remains, with an extensive taxonomy of escape hatches learned from production incidents; (2) the operator should never wonder what's happening \u2014 a rich HUD statusline surfaces mode/iteration/agents/context/rate-limits, and multi-channel notifications (Discord/Telegram/Slack) with a two-way reply-injection daemon allow remote monitoring and control of unattended sessions; (3) state must survive every lifecycle boundary \u2014 compaction, session end, crashes, plugin updates \u2014 via hook-enforced persistence (project memory, wiki, notepad, boulder plan state) rather than trusting the model to follow a protocol.\n\nThe engineering quality of the guardrails is the standout. Every anti-stall mechanism carries circuit breakers (bounded retries, TTL'd counters, thinking-only-streak bailouts, tombstoned mode state from crashed sessions), and the code cites the specific GitHub issue each safeguard answers: compaction deadlock (#213), rate-limit infinite retry (#777), auth-failure loops (#1308), recursive team spawning (keyword disabled), SubagentStop context reinjection (#3209). Team mode gets a genuinely distributed-systems treatment: per-worker heartbeat files, freshness checks by the lead, bounded tmux idle nudges, process-identity locks (PID+start-time), and worker restart/recovery sagas. A rate-limit-wait daemon auto-resumes blocked sessions when limits reset \u2014 solving the single biggest killer of overnight autonomous runs.\n\nVerified as implemented: the entire hook chain in hooks/hooks.json wired through scripts/*.mjs to compiled TypeScript, the HUD with ~30 element renderers and installer integration, the notifications stack including a hand-rolled Slack Socket Mode client with HMAC verification, heartbeat/idle-nudge machinery, and the permission auto-allow handler. Flagged as aspirational/dead: src/hooks/recovery/ (context-window/session/edit-error recovery) and src/hooks/thinking-block-validator/ are ports from oh-my-opencode targeting hook points (onError, experimental.chat.messages.transform) that do not exist in Claude Code's hook system \u2014 they are exported as library code but wired to no hooks.json event; actual failure recovery flows through the PostToolUseFailure -> Stop-hook retry-guidance path instead. preemptive-compaction also self-describes as a 'simplified version' that only injects warnings versus the original's automatic summarization.", + "weaknesses": [ + "Extreme complexity budget: the Stop-hook module alone is 2,564 lines with ~10 interacting state files (mode files, skill ledgers, tombstones, stop-breakers, cancel signals); the sheer number of escape hatches documents how often hard-blocking Stop events backfired. ZO should treat this as evidence that stop-blocking is a last resort, not a foundation.", + "Brittle heuristics at the core: stop-reason classification (isRateLimitStop, isAuthenticationError, isContextLimitStop) is substring matching on undocumented stop_reason strings; workflow-drift-guard's completion-claim detection is regex-on-English. Upstream wording changes silently break the safety layer.", + "Dead/aspirational code presented alongside live code: src/hooks/recovery/ and thinking-block-validator are OpenCode ports wired to nonexistent Claude Code hook points; a reader (or LLM) auditing capabilities would overcount what actually runs.", + "Heavy tmux coupling: the best operator features (idle nudges, remote reply injection, rate-limit auto-resume, team panes) require tmux; outside it the runtime UX degrades to one-way notifications.", + "Anti-stall is prompt-nagging, not progress verification: continuation messages assert 'keep working' with only heuristic checks (todo counts, deliverable file existence, TODO regexes) that work happened \u2014 no semantic oracle. The thinking-only streak guard patches the worst case but is itself heuristic.", + "Multi-MB bundled .cjs artifacts (bridge/cli.cjs 4MB, mcp-server.cjs 1.1MB, team.js 0.7MB) checked into the repo, plus an npm-root-g NODE_PATH hack at bridge startup \u2014 fragile packaging that has clearly needed repair tooling (repair-plugin-cache.mjs, stale-plugin-root recovery in run.cjs).", + "Notification reply injection, though carefully sanitized, is still remote text-to-terminal injection gated on chat-platform identity (Discord user ID / Telegram chat ID / Slack channel); a compromised chat account becomes code execution on the host." + ] + }, + { + "repo": "ruflo", + "lens": "core-memory", + "summary": "ruflo (v3.38.0, successor of claude-flow) is overwhelmingly a TypeScript monorepo (~400k non-test lines across 24 packages under v3/@claude-flow/, with the CLI alone at 360 files / 173k lines), not a Rust system. The in-repo \"Rust core\" is 1,246 lines across two crates that are stubs by their own admission: crates/ruflo-agntcy/Cargo.toml literally documents \"The 'slim' feature currently compiles a STUB ONLY\" (no upstream crate exists), and ruflo-federation-peer ships a trait surface whose real transport/safety deps are behind an off-by-default `native` feature. The actual Rust/WASM engine lives in external npm packages from ruvnet's other repos (agentdb@3.0.0-alpha.17, @ruvector/core, @ruvector/sona, ruvector, @ruvector/rvf-wasm), all consumed via dynamic imports wrapped in try/catch with pure-TS fallbacks \u2014 so what most users actually execute is the TypeScript fallback tier.\n\nThe architectural truth of the system is stated bluntly in AGENTS.md: \"claude-flow = LEDGER (tracks state, stores memory, coordinates); Codex = EXECUTOR\". ruflo does not run agents \u2014 it is a memory/coordination sidecar for Claude Code/Codex, exposed via ~45 MCP tool modules and hooks. The memory package is the genuine core: a multi-backend IMemoryBackend abstraction (better-sqlite3, sql.js, agentdb, hybrid, RVF), a real multi-layer HNSW implemented in TypeScript, RRF+MMR hybrid retrieval, a memory consolidator, temporal-validity tiered memory, bidirectional sync with Claude Code's auto-memory markdown, and a cost-gated distillation service. Session continuity is comparatively mundane: JSON snapshots in .claude-flow/sessions/ plus a canonical .swarm/memory.db SQLite file, with a documented history of these paths drifting apart (bug #1945: CLI wrote to a different DB than the bridge read and \"reported success against the wrong file\").\n\nThe repo's design philosophy is best described as \"grand claims, later confessed and remediated under ADR discipline\". There are 175 ADR files (numbering to ADR-382), and the codebase is dense with unusually candid admissions of past vaporware: the memory README states earlier releases \"silently downgraded\" the hybrid backend and \"ADR-009's promise wasn't delivered until now\"; tiered-memory.ts documents that every hierarchical-store write used to be \"a silent no-op that still reported success\"; init.ts remediates a scaffold that copied repo bloat (including the root agentdb.rvf) into user projects. That root agentdb.rvf \u2014 the headline \"agent database\" \u2014 is a 162-byte empty header (magic SFVR from rvf-wasm), not a working database. Meanwhile the marketing surface still overstates: docstrings claim \"150x-12,500x faster\" vector search while the project's own CLAUDE.md admits \"measured ~1.9x\u20134.7x vs brute force above crossover\" and the committed benchmark baseline is 0.53ms/search at 1k\u00d7128-dim.", + "key_features": [ + { + "name": "AutoMemoryBridge: DB <-> Claude Code auto-memory markdown sync", + "what_it_is": "Bidirectional sync (ADR-048) between the vector memory backend and Claude Code's human-readable auto-memory files at ~/.claude/projects//memory/ \u2014 MEMORY.md as a line-budgeted index (default 180 lines, since Claude loads the first 200) plus category topic files.", + "why_special": "It treats the agent-visible markdown as a *projection* of a queryable database rather than the source of truth: insights are classified into categories (project-patterns, debugging, architecture, performance, security, preferences, swarm-results), formatted as one-line summaries, and pruned confidence-weighted to stay within the line budget. Also has an agent-scoped variant supporting Claude Code's project/local/user memory scopes with cross-agent knowledge transfer (min-confidence, max-entries, category filters). Fully implemented with tests, not aspirational.", + "how_it_works": "AutoMemoryBridge (EventEmitter, ~900 lines) hashes content, parses/emits markdown entries, classifies via classifyEntry(), prunes via pruneTopicFile(); sync modes on-write/on-session-end/periodic. AgentScopedMemoryBridge extends it per (agentName, scope). LearningBridge optionally forwards recorded insights into the neural trajectory system, no-op when unavailable.", + "evidence_files": [ + "v3/@claude-flow/memory/src/auto-memory-bridge.ts", + "v3/@claude-flow/memory/src/agent-memory-scope.ts", + "v3/@claude-flow/memory/src/learning-bridge.ts" + ], + "zo_relevance": "Directly maps to ZO's STATE.md/PRIORS.md/MEMORY.md files. ZO keeps markdown canonical and has no index; ruflo shows the inverse pattern and, more usefully, the middle path: keep ZO's markdown canonical but auto-generate a line-budgeted, confidence-pruned index plus a searchable store, so priors accumulate without bloating the context window. The category taxonomy + one-line insight format is stealable as-is for PRIORS.md." + }, + { + "name": "TieredMemoryStore with temporal validity (invalidate, never overwrite)", + "what_it_is": "Zep/Graphiti-style temporal knowledge semantics on the memory store: facts carry validFrom/validUntil; a conflicting fact `supersedes` an old one by stamping validUntil=now + supersededBy= and archiving it, keeping history queryable; recall() filters invalid entries by default with an includeExpired audit escape hatch.", + "why_special": "This is the most principled piece of memory design in the repo \u2014 contradiction handling with provenance instead of destructive updates. The docstring is also a landmark confession: agentdb dropped its HierarchicalMemory export at 3.0.0-alpha.17, so the previous in-memory stub made 'every such write a silent no-op that still reported success' \u2014 this module is the remediation, writing through to a tiered_memory SQLite table and exposing isDurable so callers can tell volatile from durable.", + "how_it_works": "TieredMemoryStore in v3/@claude-flow/memory/src/tiered-memory.ts (448 lines): store(key, value, tier, temporalOptions), recall(query, topK), getTierStats(); optional better-sqlite3 handle for durability, rehydrates on construction; deliberately avoids exposing getStats+promote together because that pair is the bridge's duck-type detection signal for the real agentdb API.", + "evidence_files": [ + "v3/@claude-flow/memory/src/tiered-memory.ts", + "v3/@claude-flow/cli/src/memory/memory-bridge.ts" + ], + "zo_relevance": "ZO's PRIORS.md and DECISION_LOG.md are append/edit markdown with no supersession semantics. Adopting invalidate-not-overwrite (a prior that proves wrong gets validUntil + supersededBy pointing at the new prior, never deleted) would give ZO's self-evolution protocol an audit trail and prevent silent loss of why rules changed \u2014 cheap to do even in markdown with structured front-matter." + }, + { + "name": "Real multi-layer HNSW + RRF/MMR hybrid retrieval, honestly benchmarked", + "what_it_is": "A genuine hierarchical HNSW index in pure TypeScript (random level assignment, top-down layer descent, binary min/max heaps, pre-normalized cosine), persistent across restart via sidecar snapshot files (.hnsw + .meta.json), plus SmartRetrieval implementing real Reciprocal Rank Fusion and Maximal Marginal Relevance rerank, and a MemoryConsolidator (sweepExpired/dedup/compactHnsw on a 6h timer).", + "why_special": "Verified implemented, not vendored: hnsw-index.ts has layers, getRandomLevel(), searchLayerOptimized \u2014 it is the real algorithm. And the committed benchmark is honest: baseline-20260519T212453Z.md records 0.53ms/search, 1889 ops/s at 1k\u00d7128-dim on Apple Silicon, while CLAUDE.md admits 'measured ~1.9x\u20134.7x vs brute force above crossover'. The catch: docstrings and CLI hints still parrot '150x-12,500x faster' \u2014 the marketing number and the measured number coexist in the same repo.", + "how_it_works": "v3/@claude-flow/memory/src/hnsw-index.ts (canonical, post-ADR-125); an intentionally-degraded HnswLite (greedy neighbor graph, not layered) is inlined privately in rvf-backend.ts for the fallback path; smart-retrieval.ts has reciprocalRankFusion() and mmrRerank() with mmr = lambda*score - (1-lambda)*maxOverlap; consolidator.ts + hnsw-persistence tests cover snapshot/restore.", + "evidence_files": [ + "v3/@claude-flow/memory/src/hnsw-index.ts", + "v3/@claude-flow/memory/src/smart-retrieval.ts", + "v3/@claude-flow/memory/src/consolidator.ts", + "v3/@claude-flow/memory/benchmarks/results/baseline-20260519T212453Z.md" + ], + "zo_relevance": "ZO's memory/recall skill is grep-over-markdown; at ZO's scale (one team, dozens of priors) brute-force cosine or FTS is honestly sufficient \u2014 ruflo's own numbers prove HNSW only pays off above a crossover ZO will rarely hit. The adoptable part is graceful retrieval: FTS/keyword fallback when no embedder is available, and RRF fusion of keyword+semantic results, both small and self-contained." + }, + { + "name": "RVF 'binary agent database' \u2014 mostly a format costume in-repo", + "what_it_is": "RVF (RuVector Format) is pitched (ADR-057) as a native binary storage backend replacing the 18MB sql.js dependency, with the repo-root agentdb.rvf as the flagship artifact. In-repo reality: RvfBackend's own persistence is a 4-byte magic + JSON header + length-prefixed JSON records; RvfEventLog is likewise 'RVFL' magic + uint32-length-prefixed JSON. The real binary format lives in external @ruvector packages.", + "why_special": "This is the flagship example of claim-vs-code divergence. The root agentdb.rvf is 162 bytes \u2014 an empty header (magic 'SFVR' from @ruvector/rvf-wasm), not a database of anything. RvfBackend tries dynamic import of '@ruvector/rvf', which is not even a declared dependency (only @ruvector/rvf-wasm is, as optional), so the code path virtually all users run is the pure-TS fallback: an in-memory Map + the degraded HnswLite + periodic JSON dumps. It works, but 'binary vector database' is JSON in a trenchcoat. Bonus irony: init.ts lists agentdb.rvf among 'bloat markers' after ADR-382 found the scaffold had been copying it into user projects.", + "how_it_works": "rvf-backend.ts: tryNativeInit() catch-all falls back to loadFromDisk/persistToDisk writing magic [0x52,0x56,0x46,0x00] + JSON.stringify per entry; shared/src/events/rvf-event-log.ts is the append-only event log variant (ADR-057 Phase 2) with snapshot .snap.rvf files; ADR-057 documents the aspiration.", + "evidence_files": [ + "v3/@claude-flow/memory/src/rvf-backend.ts", + "v3/@claude-flow/shared/src/events/rvf-event-log.ts", + "v3/implementation/adrs/ADR-057-rvf-native-storage-backend.md", + "agentdb.rvf", + "v3/@claude-flow/cli/src/commands/init.ts" + ], + "zo_relevance": "Anti-pattern to learn from, not adopt: ZO's plain-markdown memory is more honest than a bespoke 'binary format' that is JSON underneath. The one legitimate takeaway is the append-only event log with length-prefixed records and snapshot files \u2014 a zero-dependency durable log ZO could use for comms JSONL hardening, though JSONL already gives ZO 90% of it." + }, + { + "name": "Session continuity: JSON snapshots + fragmented storage roots", + "what_it_is": "session_save/session_restore/session_list MCP tools persist SessionRecord JSON ({sessionId, stats, data:{memory,tasks,agents}}) to .claude-flow/sessions/*.json, optionally encrypted at rest (ADR-096, magic-byte sniff for mixed plaintext/encrypted dirs); related stores are .claude-flow/{memory,tasks,agents}/store.json; the canonical vector DB is .swarm/memory.db; hive-mind keeps its own .hive-mind/sessions.", + "why_special": "Notable mostly as a cautionary tale: despite the AgentDB/HNSW narrative, cross-session continuity is plain JSON file snapshots \u2014 commodity. And the fragmentation across at least four storage roots produced real bugs the code documents: memory-bridge.ts #1945 \u2014 hooks configured data/memory/memory.db while bridgeStoreEntry() wrote .swarm/memory.db, so 'CLI store reported success against the wrong file'. The tool descriptions are well-written ('Use when native conversation memory is wrong because you need durable cross-session state'), and owner-only file perms + opt-in encryption show security attention.", + "how_it_works": "v3/@claude-flow/cli/src/mcp-tools/session-tools.ts: saveSession() via writeFileRestricted({encrypt:true}, honored only when CLAUDE_FLOW_ENCRYPT_AT_REST is set), loadRelatedStores() reads the three store.json files; session.ts CLI command delegates to these MCP tools; hive-mind.ts uses .hive-mind/sessions separately.", + "evidence_files": [ + "v3/@claude-flow/cli/src/mcp-tools/session-tools.ts", + "v3/@claude-flow/cli/src/commands/session.ts", + "v3/@claude-flow/cli/src/memory/memory-bridge.ts", + "v3/@claude-flow/cli/src/services/memory-distillation.ts" + ], + "zo_relevance": "Validates ZO's single-root memory/{project}/ design \u2014 ruflo's multi-root drift bugs are exactly what ZO's layout prevents. Worth borrowing: the explicit 'reported success against the wrong file' failure class belongs in ZO's PRIORS.md as a category (verify writes land where reads look), and owner-only perms + opt-in encryption for session files containing agent prompts is a cheap hardening ZO lacks." + }, + { + "name": "Learning stack: ReasoningBank, SONA, memory distillation with cost-gated judges", + "what_it_is": "A layered learning-from-experience system: ReasoningBank (hooks package) stores guidance patterns as 384-dim ONNX MiniLM vectors with quality/usage/success counts, short-term to long-term promotion, and historical-performance-based agent routing; PersistentSonaCoordinator keeps a pattern bank + trajectory buffer + EWC records persisted via RvfLearningStore; `memory distill` (ADR-174) dedups/clusters memory via greedy cosine clustering with a $0 'structural' judge, the LLM judge explicitly gated behind a budget flag and not enabled.", + "why_special": "The distillation service is the most honest component in the repo: provenance types are literally 'oracle:test-exec' | 'judge:fable' | 'proxy:structural', a code comment warns against 'laundering' structural summaries as genuine self-critique, and judge:fable hard-fails without a budget (ADR-172 cost gate). The SONA layer is more costume than claim: PersistentSonaCoordinator is 'intentionally decoupled from the ruvector SONA classes' \u2014 i.e., the persistent 'neural' learning is a brute-force cosine pattern bank with confidence decay (0.005/hr) and access boosts (0.03), while real @ruvector/sona is only statically imported in the neural package (external Rust/WASM, unverifiable in-repo). EWC 'tracking' is a stored lambda + records, not a training loop.", + "how_it_works": "hooks/src/reasoningbank/index.ts (dynamic imports of AgentDBAdapter/HNSWIndex/EmbeddingServiceImpl, degrades to no-op); memory/src/persistent-sona.ts + rvf-learning-store.ts; cli/src/services/memory-distillation.ts (runDistillation over .swarm/memory.db, greedy cosine clusters, embedding-coverage invariant before writes); neural/src/sona-integration.ts wraps @ruvector/sona.", + "evidence_files": [ + "v3/@claude-flow/hooks/src/reasoningbank/index.ts", + "v3/@claude-flow/memory/src/persistent-sona.ts", + "v3/@claude-flow/cli/src/services/memory-distillation.ts", + "v3/@claude-flow/neural/src/sona-integration.ts" + ], + "zo_relevance": "The distillation design is the piece ZO should copy: periodic consolidation of PRIORS/session summaries with explicit provenance tiers (test-verified > LLM-judged > structural) and a hard cost gate on LLM judging fits ZO's oracle-first philosophy perfectly. ReasoningBank's agent routing by historical success-rate per domain is a concrete upgrade path for ZO's model-tier routing. Skip the SONA/neural branding entirely \u2014 the working substance is cosine similarity over past patterns with confidence decay, which ZO can do in 200 lines." + }, + { + "name": "Guidance governance: signed rule-evolution pipeline + memory write gates", + "what_it_is": "The guidance package (~22.6k lines) implements governance over the agent system's own rules: evolution.ts turns every change to prompts/policies/tools into a signed ChangeProposal that goes propose -> simulate (replay golden traces baseline-vs-candidate) -> compare (divergence threshold) -> staged rollout (canary -> partial -> full) -> promote/rollback; memory-gate.ts adds per-agent authority scopes (queen/coordinator/worker/observer roles, allowed namespaces, writes-per-minute limits, delete rights) plus TTL/decay and contradiction tracking on memory writes.", + "why_special": "This is a mechanized, verifiable version of 'self-evolving rules' \u2014 rule changes must survive replay against golden traces before promotion, with HMAC/hash signing throughout. Caveat on realness: the pipeline machinery (types, hashing, staging logic, gates) is implemented and tested in-package, but end-to-end wiring into live agent traffic is hard to trace and largely depends on callers adopting it; treat it as a well-built library more than a proven production loop. Related: the separate verification/ system IS provably wired \u2014 Ed25519-signed witness manifests per documented fix, per-OS, with history.jsonl for bisecting regressions, and a CI job that blocks publish when a fix's load-bearing marker disappears.", + "how_it_works": "guidance/src/evolution.ts (ChangeProposalKind: rule-modify/add/remove/promote, policy-update, tool-config, budget-adjust; ProposalStatus lifecycle), memory-gate.ts (MemoryAuthority interface), gates.ts, truth-anchors.ts, ledger.ts; verification/README.md + witness-fixes.json + per-OS manifest.md.json describe the three-layer regression protection (smoke tests, witness manifest, temporal history).", + "evidence_files": [ + "v3/@claude-flow/guidance/src/evolution.ts", + "v3/@claude-flow/guidance/src/memory-gate.ts", + "verification/README.md", + "verification/witness-fixes.json" + ], + "zo_relevance": "ZO's self-evolution protocol ends with 'Verify the updated rule would have caught the original failure' \u2014 done manually by Claude. ruflo shows how to mechanize exactly that step: keep failure transcripts as golden traces, replay candidate rule changes against them, and only promote on non-divergence. The witness pattern is also directly adoptable for ZO's oracle: attest each fixed failure's load-bearing code with a hash+marker check so regressions of past PRIORS entries are caught automatically. Memory write-gating by agent role matters once ZO agents write memory concurrently." + }, + { + "name": "In-repo Rust crates: honest stubs, external Rust engine", + "what_it_is": "crates/ contains exactly two crates totaling 1,246 lines: ruflo-agntcy (CASA authorization envelope + SLIM transport surface, ADR-380) and ruflo-federation-peer (QUIC federation peer trait surface, ADR-120). The 'supercharged Rust-based AI engine' from the README is entirely external npm dependencies: agentdb, @ruvector/core, @ruvector/sona, @ruvector/router, ruvector, @ruvector/rvf-wasm.", + "why_special": "The Cargo.tomls are startlingly honest \u2014 ruflo-agntcy: 'The slim feature currently compiles a STUB ONLY... every plausible package name 404s; verified during ADR-380 scaffolding, not assumed', with methods returning Err(TransportError::Unavailable) 'rather than doing anything fake'; federation-peer keeps its real deps behind an off-by-default `native` feature so cargo check passes without them. So the repo's Rust story is: real Rust exists in ruvnet's *other* repos and arrives as npm binaries/WASM; this repo's crates are forward-scaffolding with explicit non-fake error surfaces. Every consumer of the external Rust wraps it in dynamic import + pure-TS fallback, meaning the fallback IS the product for most installs.", + "how_it_works": "crates/ruflo-agntcy/{Cargo.toml,src/envelope.rs,src/transport.rs}; crates/ruflo-federation-peer/src/lib.rs (623 lines, trait surface + 3-gate safety pipeline types); v3/crates is a copy of the same two crates; package.json declares the @ruvector/agentdb npm deps; agentdb-backend.ts/rvf-backend.ts/vector-db.ts all do await import(...) in try/catch with FallbackVectorDB/HnswLite/Map fallbacks.", + "evidence_files": [ + "crates/ruflo-agntcy/Cargo.toml", + "crates/ruflo-federation-peer/src/lib.rs", + "v3/@claude-flow/cli/src/ruvector/vector-db.ts", + "v3/@claude-flow/memory/src/agentdb-backend.ts", + "package.json" + ], + "zo_relevance": "Mostly a claims-calibration datapoint: when synthesizing 'ruflo has a Rust core', the correct statement is 'ruflo consumes ruvnet's external Rust/WASM packages behind optional imports; in-repo Rust is stub scaffolding'. For ZO the lesson is negative \u2014 ZO's pure-Python stack avoids the two-ecosystem drift that broke ruflo repeatedly (agentdb dropping exports out from under the TS layer). If ZO ever needs performance-critical components, vendoring or pinning with API-contract tests is mandatory; ruflo's tiered-memory incident shows what happens otherwise." + } + ], + "architecture_notes": "Execution model: ruflo is a coordination/memory LEDGER, not an executor \u2014 AGENTS.md states this explicitly (\"claude-flow = LEDGER... Codex = EXECUTOR... If you need something BUILT/EXECUTED, YOU do it, not claude-flow\"). All agent work happens inside Claude Code/Codex; ruflo surfaces ~45 MCP tool modules (v3/@claude-flow/cli/src/mcp-tools/) plus hooks (SessionStart worker autostart in hooks/src/workers/session-hook.ts) that read/write shared state. The swarm/queen/consensus/topology code in v3/@claude-flow/swarm coordinates records and messages, not OS processes. This is the same fundamental shape as ZO (Claude Code does the work; the platform provides memory + protocol), but ruflo pushes coordination into MCP tools while ZO pushes it into prompts/specs.\n\nLayering: v3/@claude-flow/* is a 24-package pnpm monorepo \u2014 shared (events, orchestrator, 23.5k lines), memory (19.2k), guidance (22.6k), hooks (10.7k), swarm (17.3k), neural (14.2k), cli (173k \u2014 the kitchen sink). The memory package is cleanly layered: IMemoryBackend interface -> {sqlite, sqljs, agentdb, hybrid, rvf} backends -> MemoryService facade -> bridges (AutoMemoryBridge, LearningBridge, MemoryGraph with PageRank/label-propagation community detection) -> ControllerRegistry wrapping agentdb's named controllers (reasoningBank, skills, reflexion, causalGraph, nightlyLearner, mutationGuard...). Everything optional is dynamically imported with graceful degradation; a \"6-level backend resolution\" display was added so users can tell which tier actually resolved \u2014 an admission that silent degradation was a real problem.\n\nStorage topology (fragmented): .claude-flow/sessions/*.json (session snapshots, opt-in encryption), .claude-flow/{memory,tasks,agents}/store.json, .swarm/memory.db (canonical better-sqlite3 vector/memory DB, defaultMemoryDbPath), .hive-mind/sessions, data/memory (historical), ~/.claude/projects/*/memory/*.md (Claude auto-memory, bridged). Multiple documented drift bugs between these roots (#1945).\n\nProcess discipline is the real differentiator: 175 ADR files in v3/docs/adr (numbering reaches ADR-382), plus implementation ADRs; a cryptographic witness verification system (verification/: Ed25519-signed per-fix marker attestation, per-OS manifests, temporal history.jsonl, CI publish blocking); committed benchmark baselines; and a pervasive culture of in-code confession where past silent failures are documented in docstrings at the fix site. The codebase reads like an archaeological record of overclaiming followed by rigorous remediation \u2014 the current code is substantially more trustworthy than the project's marketing, and the ADR/witness machinery appears to be how they dug out.", + "weaknesses": [ + "The 'Rust core' is not in this repo: crates/ is 1,246 lines of self-declared stubs (ruflo-agntcy Cargo.toml: 'compiles a STUB ONLY'); the real Rust arrives as external npm packages (agentdb, @ruvector/*) that have broken the TS layer before (agentdb dropped HierarchicalMemory at 3.0.0-alpha.17, silently no-op'ing every hierarchical-store write while reporting success \u2014 documented in tiered-memory.ts).", + "The flagship agentdb.rvf at repo root is a 162-byte empty header, and the in-repo RVF 'binary format' is length-prefixed JSON with a 4-byte magic; the native @ruvector/rvf module RvfBackend tries to load is not even a declared dependency, so users run the pure-TS fallback (in-memory Map + degraded greedy-graph 'HnswLite', not real HNSW).", + "Performance claims are internally inconsistent: '150x-12,500x faster' persists in ~10 docstrings and CLI hints while the project's own CLAUDE.md says 'measured ~1.9x\u20134.7x vs brute force above crossover' and the committed baseline is 0.53ms/search at just 1k vectors.", + "Storage fragmentation across at least four roots (.claude-flow/, .swarm/, .hive-mind/, data/) with a documented history of write-here-read-there bugs (#1945 'reported success against the wrong file'); session continuity is plain JSON snapshots despite the vector-DB narrative.", + "Pervasive graceful-degradation means the advertised capability tier and the executed capability tier routinely differ (HNSW->greedy graph, agentdb->Map, neural->no-op, encryption only with env flag); the 6-level resolution display exists precisely because users couldn't tell.", + "Enormous surface area \u2014 360 CLI source files, federation with WireGuard mesh, IoT plugin, browser automation, appliance/RVFA signing, business-pod tools, GAIA bench \u2014 breadth that historically outran verification (three regressions on one day, 2026-05-08, all passing unit tests, motivated the witness system).", + "The 'self-learning neural' stack's persistent substance is a brute-force cosine pattern bank with confidence decay; SONA/EWC branding substantially oversells it, and the guidance evolution pipeline, while well-built, is hard to confirm as wired into live agent traffic end-to-end.", + "Marketing artifacts inside the repo (22.2M+ 'ecosystem downloads' badge backed by self-generated clone-data 'proof' ledgers in data/) blur the line between engineering and promotion." + ], + "notable_files": [ + "v3/@claude-flow/memory/src/auto-memory-bridge.ts", + "v3/@claude-flow/memory/src/tiered-memory.ts", + "v3/@claude-flow/memory/src/hnsw-index.ts", + "v3/@claude-flow/memory/src/rvf-backend.ts", + "v3/@claude-flow/memory/src/smart-retrieval.ts", + "v3/@claude-flow/memory/src/agentdb-backend.ts", + "v3/@claude-flow/memory/src/controller-registry.ts", + "v3/@claude-flow/memory/src/persistent-sona.ts", + "v3/@claude-flow/memory/src/agent-memory-scope.ts", + "v3/@claude-flow/memory/README.md", + "v3/@claude-flow/memory/benchmarks/results/baseline-20260519T212453Z.md", + "v3/@claude-flow/shared/src/events/rvf-event-log.ts", + "v3/@claude-flow/cli/src/mcp-tools/session-tools.ts", + "v3/@claude-flow/cli/src/services/memory-distillation.ts", + "v3/@claude-flow/cli/src/memory/memory-bridge.ts", + "v3/@claude-flow/guidance/src/evolution.ts", + "v3/@claude-flow/guidance/src/memory-gate.ts", + "v3/@claude-flow/hooks/src/reasoningbank/index.ts", + "v3/@claude-flow/neural/src/sona-integration.ts", + "crates/ruflo-agntcy/Cargo.toml", + "crates/ruflo-federation-peer/src/lib.rs", + "v3/implementation/adrs/ADR-057-rvf-native-storage-backend.md", + "verification/README.md", + "AGENTS.md", + "CLAUDE.md" + ] + }, + { + "repo": "ruflo", + "lens": "swarm", + "summary": "Ruflo is the renamed claude-flow v3 by ruvnet (package.json still says \"claude-flow\", v3.38.0) \u2014 a ~122MB monorepo positioned as an \"agent meta-harness for Claude Code and Codex\": npm workspaces under v3/@claude-flow/*, 35 Claude Code plugins, 107 agent .md definitions, ~450 registered MCP tools, and 482 test files. Through the swarm lens, the single most important finding is that the \"swarm\" is a coordination LEDGER, not an execution engine. There are three distinct layers that must not be conflated: (1) a prompt layer \u2014 agent .md subagent definitions (queen-coordinator, byzantine-coordinator, mesh/hierarchical coordinators) and slash commands that instruct Claude to role-play coordination protocols; (2) a bookkeeping layer \u2014 MCP tools (swarm_init, agent_spawn, hive-mind_*, task_*) whose handlers write JSON state files under .claude-flow/ (swarm-state.json, agents/store.json) with real engineering (file locks, PID-liveness orphan reaping) but which spawn no processes and call no LLMs; and (3) an execution layer that is fully delegated \u2014 agent_spawn's own response text spells it out: \"(1) agent_execute \u2014 direct LLM call via Anthropic Messages API; (2) Claude Code Task tool \u2014 spawns a real subagent; (3) claude -p \u2014 headless background instance.\"\n\nThe paradox at the heart of the repo: a genuinely substantial 13k-line @claude-flow/swarm TypeScript library exists \u2014 QueenCoordinator (2,025 lines), UnifiedCoordinator (1,844), TopologyManager, Raft/Byzantine/Gossip consensus with a pluggable Ed25519-signed transport, task orchestrator with dependency resolution \u2014 and it is well-tested (10 test files including consensus failure-injection), but NOTHING in the CLI/MCP runtime imports it (verified by grep: only capability-brain.ts references the package, as metadata). The MCP handlers reimplement lightweight file-based versions instead. The transport module's own docstring admits the history: consensus messages \"never actually crossed a process or node boundary: a node 'sent' a message by emit'ting it locally and synthesizing the peer's reply inline.\"\n\nWhat redeems the repo \u2014 and is genuinely unusual \u2014 is a systematic, self-documented honesty retrofit. Issue-referenced comments throughout the code record where earlier versions lied (\"#1845: 'queued' was a lie\"; \"ADR-093 F2: stop returning status:'completed' for a worker that never ran\") and replace fake success with honest status enums ('no-daemon', 'queued', 'synthetic-completed'). A commissioned internal audit (docs/reviews/intelligence-system-audit-2026-05-29.md) empirically graded the platform's claims: the self-learning loop, Q-learning routing, and int8/RaBitQ quantization are real and measured; \"Flash Attention 2.49\u20137.47x\" was literally fabricated with Math.random() at runtime; \"HNSW 150x\u201312,500x\" measured 1.48x peak. A verification/ directory maintains cryptographic \"witness manifests\" (sha256 + source-marker checks per documented fix, per-OS performance JSONL baselines) so documented capabilities can be re-verified against the code. The converged practical doctrine \u2014 visible in the init-scaffolded CLAUDE.md \u2014 is candid: \"Ruflo is the coordination ledger and policy decision point. Claude Code is the executor,\" with multi-agent work done via native Task-tool agents that are named, spawned in one message with run_in_background, coordinate via SendMessage, and each get an isolated worktree with single-writer file ownership.", + "key_features": [ + { + "name": "File-based swarm coordination ledger (swarm_init / agent_spawn / task_* MCP tools)", + "what_it_is": "MCP tools that persist swarm topology, agent registry, and task assignments as JSON state under .claude-flow/ (swarm-state.json, agents/store.json, task store), with topology validation (hierarchical/mesh/ring/star/hybrid/adaptive/pheromone-adaptive), file locks, and PID-liveness orphan reconciliation (#1799: dead-host swarms auto-marked 'terminated').", + "why_special": "It is honest infrastructure for the thing that actually matters in Claude-Code-native swarms: durable shared state that any number of sessions/subagents can read and write. No process supervision pretense \u2014 agent_spawn's own response note admits execution happens elsewhere (agent_execute API call, native Task tool, or claude -p). The engineering around staleness (PID probes, 24h TTL reaping, atomic lock files) is real and battle-hardened by thousands of issues.", + "how_it_works": "swarm_init writes a SwarmState record (topology, maxAgents, strategy, consensusMechanism) to .claude-flow/swarm/swarm-state.json; agent_spawn writes an AgentRecord (with routed model, provider, optional copy-on-write memory branch) to .claude-flow/agents/store.json and cross-registers into the swarm's agents array (#2085); task_create/task_assign maintain a task store and flip agent status idle<->active. loadSwarmStore() runs reconcileOrphanSwarms() using process.kill(pid, 0) liveness probes.", + "evidence_files": [ + "v3/@claude-flow/cli/src/mcp-tools/swarm-tools.ts", + "v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts", + "v3/@claude-flow/cli/src/mcp-tools/task-tools.ts", + "v3/@claude-flow/cli/src/mcp-tools/agent-execute-core.ts" + ], + "zo_relevance": "ZO's STATE.md is prose-memory; ruflo shows the value of a parallel MACHINE-readable coordination store (JSON with schema, liveness fields, orphan reaping). ZO's new watchdog/heartbeat spec (commit 297adac) should steal the PID-probe + TTL reconciliation pattern and the principle that every async status must be provably derived (queue file on disk, PID checked) rather than asserted." + }, + { + "name": "Consensus-as-a-ledger (hive-mind_consensus with Raft/BFT/quorum semantics)", + "what_it_is": "A real vote-tallying state machine over the JSON hive state: propose/vote/status actions with three strategies \u2014 raft (one pending proposal per term, one vote per node per term, timeout re-proposal), bft (double-vote and cross-proposal conflict detection that excludes Byzantine voters), quorum (unanimous/majority/supermajority presets).", + "why_special": "This is the correct adaptation of consensus to LLM swarms: not distributed-systems consensus (there is no network partition to survive) but a structured, auditable DECISION PROTOCOL with anti-gaming rules (double-vote detection, term discipline) that multiple subagents can participate in through MCP calls. The catch \u2014 and it's fundamental \u2014 is voter independence: in the common single-session flow, one Claude role-plays every voter, making 'byzantine fault tolerance' theater. It only becomes meaningful when separate Task-tool subagents or headless instances each cast their own votes.", + "how_it_works": "hive-mind_init writes topology + consensusStrategy + queen record to hive state JSON; hive-mind_spawn appends worker records (pure metadata \u2014 status 'idle', no process); hive-mind_consensus 'propose' creates a proposal with required-vote thresholds computed from live worker count, 'vote' records per-voterId votes, detects conflicting votes (BFT: voter excluded and listed in byzantineVoters; raft: vote change rejected), and resolves via tryResolveProposal into a persisted history. Meanwhile the 1,674-line 'real' Raft/PBFT/Gossip library in @claude-flow/swarm/src/consensus/ (with Ed25519-signed transport) is dead code from the runtime's perspective.", + "evidence_files": [ + "v3/@claude-flow/cli/src/mcp-tools/hive-mind-tools.ts", + "v3/@claude-flow/swarm/src/consensus/raft.ts", + "v3/@claude-flow/swarm/src/consensus/byzantine.ts", + "v3/@claude-flow/swarm/src/consensus/transport.ts" + ], + "zo_relevance": "ZO's oracle is a single verifier; ruflo's ledger suggests a cheap complement: structured gate votes where reviewer/tester/security agents each file an explicit vote with recorded rationale into a file-based proposal, giving DECISION_LOG.md a machine-checkable substrate. Adopt the anti-gaming bookkeeping (one vote per agent per gate, conflict detection); reject the framing that this is fault tolerance \u2014 votes from agents sharing one context window are correlated, so ZO should require voters to be separately-spawned contexts." + }, + { + "name": "Hive-mind Queen launcher (hive-mind spawn --claude)", + "what_it_is": "CLI path that generates a large 'HIVE MIND COLLECTIVE INTELLIGENCE SYSTEM' prompt (queen persona, worker roster, consensus algorithm, per-tool coordination protocol) and launches a single `claude` process with it \u2014 interactive or headless (-p --output-format stream-json), with --mcp-config wired so the spawned session actually has the mcp__ruflo__* tools (#1748).", + "why_special": "This is the concrete answer to 'what is the runtime path of a swarm': ONE Claude Code session is the queen; 'workers' are JSON records the queen manipulates through MCP tools; the prompt explicitly forbids native Task/Agent tools for coordination (#1422) to keep all orchestration flowing through ruflo's ledger. It is prompt-level orchestration wearing an exoskeleton of real state tools \u2014 functional, but a single point of cognition, not a parallel swarm. Notably, the newer plugin skill (ruflo-swarm swarm-init) reverses doctrine: it tells Claude to use native Task with name:/run_in_background plus SendMessage after swarm_init \u2014 evidence the project itself concluded native subagents are the better execution substrate.", + "how_it_works": "generateHiveMindPrompt() assembles the queen persona + tool catalog + 4-phase execution protocol; spawnClaudeCodeInstance() resolves an MCP config (./.mcp.json \u2192 ~/.claude.json), builds claude args (--mcp-config=path, optional -p/--output-format stream-json, optional --dangerously-skip-permissions), and childSpawn's the claude binary with the prompt as final arg. Worker records were previously created by hive-mind_spawn MCP calls.", + "evidence_files": [ + "v3/@claude-flow/cli/src/commands/hive-mind.ts", + "plugins/ruflo-swarm/skills/swarm-init/SKILL.md", + ".claude/agents/hive-mind/queen-coordinator.md", + ".claude/agents/swarm/hierarchical-coordinator.md" + ], + "zo_relevance": "ZO's lead-orchestrator already is this pattern (one orchestrating session spawning native subagents), so nothing to copy in mechanism \u2014 but the #1748/#1780 bug archaeology (spawned workers silently lacking MCP tools; variadic --mcp-config slurping the prompt as a filename past PATH_MAX) is a checklist of failure modes ZO will hit if it ever launches headless claude workers. The doctrine reversal (their own newest skill returns to native Task + SendMessage) is strong evidence for ZO's Claude-Code-native architecture choice." + }, + { + "name": "Background worker daemon with real headless Claude execution", + "what_it_is": "A persistent daemon (daemon.ts, 1,813 lines) that polls a durable on-disk queue (.claude-flow/daemon-queue/*.json, written by the hooks_worker-dispatch MCP tool) every 5s and executes 12 worker types \u2014 8 'headless' ones (audit, optimize, testgaps, document, ultralearn, refactor, deepdive, predict) by actually spawning `claude --print --output-format json` subprocesses, and 4 local ones (map, consolidate, benchmark, preload) that run without AI.", + "why_special": "This is the one place in the repo where autonomous multi-process agent execution demonstrably happens: a bounded process pool, per-job dedup registry (ai-job-dedup), a global AI budget with quota-error detection, sandbox env profiles, structured-output parsing, and Windows CVE-aware spawning. Equally notable is the honesty scaffolding around it: dispatch returns 'no-daemon' when no daemon runs ('no actual work will run'), 'queued' only after the queue file provably hits disk, and 'synthetic-completed' when sync mode has no runner \u2014 each state a repaired lie documented by issue number.", + "how_it_works": "hooks_worker-dispatch checks .claude-flow/daemon.pid liveness via process.kill(pid,0), writes {workerId, trigger, context, priority} to daemon-queue/, and reports an honest status enum. The daemon (fork'ed Node child, lock-file dedup against double-starts) consumes the queue; headless-worker-executor.ts builds context from file globs, renders a prompt template, spawns claude --print with prompt on stdin (#1852), parses JSON output including usage, and enforces timeouts/budget/dedup.", + "evidence_files": [ + "v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts", + "v3/@claude-flow/cli/src/services/headless-worker-executor.ts", + "v3/@claude-flow/cli/src/commands/daemon.ts", + "v3/@claude-flow/cli/src/services/bounded-worker-pool.ts", + "v3/@claude-flow/cli/src/services/global-ai-budget.ts" + ], + "zo_relevance": "Directly relevant to ZO's anti-stall watchdog spec and any future 'ZO runs maintenance while Sam sleeps' ambition: the durable queue file + PID-checked daemon + honest status enum is the correct minimal architecture, and the global AI budget + job dedup are must-haves ZO lacks. Note the workers are single-shot claude --print calls (analysis/documentation flavored), not long agentic loops \u2014 a scope ZO should also start with." + }, + { + "name": "Scaffolded coordination doctrine: SendMessage-first named agents, worktree-per-writer", + "what_it_is": "The `ruflo init` CLAUDE.md generator emits a compact coordination doctrine for user projects: spawn ALL named agents in ONE message via the native Agent/Task tool with run_in_background:true, embed who-messages-whom in every prompt (pipeline/fan-out/supervisor patterns), coordinate via SendMessage not polling, give every writing agent an isolated worktree with non-overlapping file ownership, single integration owner for shared manifests/lockfiles, and children may only drop \u2014 never add \u2014 capabilities.", + "why_special": "This is the distilled, non-theatrical core of three years of claude-flow iteration: after building 450 MCP tools and a dead 13k-line coordination engine, the doctrine that survives is prompt-level contracts over Claude Code's native primitives. The 'Ruflo is the coordination ledger and policy decision point; Claude Code is the executor' framing is the project's most honest architectural statement, and the concurrency/authority rules (no two writers per worktree, lease\u2260authorization, self-improving systems cannot self-promote) read like hard-won incident postmortems.", + "how_it_works": "claudemd-generator.ts composes template sections (baseRules, agentComms, swarmConfig, routing table mapping task types to agent sets and topologies, 'When to Swarm' heuristics: 3+ files yes, single-file no) into the CLAUDE.md written by init; hooks in scaffolded settings.json route every UserPromptSubmit through hook-handler.cjs \u2192 a keyword-regex agent router (router.cjs) with learned-pattern pretensions but an 8-entry regex table in practice.", + "evidence_files": [ + "v3/@claude-flow/cli/src/init/claudemd-generator.ts", + ".claude/helpers/router.cjs", + ".claude/helpers/hook-handler.cjs", + ".claude/settings.json" + ], + "zo_relevance": "Highest-value direct adoption for ZO: ZO's contract-first spawning defines interfaces but the ruflo rules add the missing operational half \u2014 named addressable agents, comms topology embedded in spawn prompts, one-message batch spawning, worktree-per-writer with explicit file-scope ownership, and a single integration owner for lockfiles. These map cleanly onto ZO's agent contracts and would harden its parallel-spawn phase against write collisions." + }, + { + "name": "Witness-manifest self-verification + commissioned honesty audit", + "what_it_is": "Two platform-level truth mechanisms: (1) verification/ holds per-OS 'witness manifests' \u2014 sha256 + source-marker checks binding every documented fix/feature to code, re-runnable at any commit (latest run: 55/55 semantic pass, statuses PASS / PASS_DRIFT / MARKER_MISSING), plus performance.jsonl baselines to catch speed regressions; (2) docs/reviews/intelligence-system-audit-2026-05-29.md, a 6-auditor empirical audit that graded every marketed capability against measurements \u2014 confirming the learning loop, Q-routing, and quantization as real while exposing 'Flash Attention 2.49\u20137.47x' as Math.random() fabrication and 'HNSW 150x\u201312,500x' as 1.48x measured.", + "why_special": "Unique among agent frameworks: the project built an oracle for ITSELF. After years of inflated claims (their own audit's words: 'headline performance multipliers are largely hardcoded doc strings... one is fabricated at runtime'), they institutionalized claim-to-evidence binding \u2014 the scaffolded CLAUDE.md even mandates 'bind claims and evidence to exact source/build receipts.' The code is now littered with issue-numbered honesty repairs, and the attention-coordinator header itself carries 'speedup unverified' disclaimers pointing at the audit.", + "how_it_works": "plugins/ruflo-core/scripts/witness/ tooling issues a manifest at a commit (file hash + regex marker per fix); verify.mjs re-checks markers with source-fallback when dist isn't built; perf.mjs appends capability\u00d7duration JSONL rows with rolling-median deltas. The audit ran real measurements against built dist exports and MCP handlers, producing a CONFIRMED/PARTIAL/FABRICATED capability matrix.", + "evidence_files": [ + "verification/CAPABILITIES.md", + "verification/results.md", + "docs/reviews/intelligence-system-audit-2026-05-29.md", + "v3/@claude-flow/swarm/src/attention-coordinator.ts" + ], + "zo_relevance": "ZO's oracle verifies delivery-repo work; ruflo demonstrates the missing second oracle: one for the PLATFORM's own claims and self-evolution rules. Concretely: when ZO's evolution protocol adds a PRIORS rule, a witness marker could verify the enforcing code/hook actually exists and still fires \u2014 mechanizing ZO's 'verify the updated rule would have caught the original failure' step, which today is manual and unenforced." + }, + { + "name": "Learned task/model routing with honest tiering (+ pheromone-adaptive scheduling)", + "what_it_is": "A 3-tier routing stack for choosing agent type and model per task: Tier-1 deterministic codemods that skip the LLM entirely ($0, canSkipLLM in agent_spawn's response), keyword-complexity static scoring, and a persisted Thompson-sampling (Beta bandit) layer that shifts model choice from model-outcome feedback \u2014 independently audited as genuinely learning cross-process (Q-table argmax'd at inference, persisted to .swarm/q-learning-model.json). Plus 'pheromone-adaptive' swarm scheduling (APSC): per-agent, role-normalized EMA fitness from {taskSuccess, latency, consensusAlignment} outcomes producing bounded keep/suspend/reactivate decisions.", + "why_special": "The audit separates this from the hype: routing feedback measurably steers subsequent decisions across processes \u2014 a real, small, useful learning loop (with one documented critical bug: negative rewards silently inverted to positive). The deterministic-codemod tier is a pattern most frameworks miss: recognize when no LLM is needed. APSC is a defensible swarm mechanism \u2014 evidence-based agent eligibility gating \u2014 implemented as a pure, testable state machine rather than metaphor.", + "how_it_works": "agent_spawn \u2192 determineAgentModel() (ADR-026/143/148/149): explicit model > codemod detection > neural router (cost-optimal, can pick OpenRouter/Ollama models) > tier default; result recorded on the AgentRecord with modelRoutedBy provenance. swarm_pheromone_update records normalized outcome signals into ApscState inside swarm-state.json; isApscAgentEligible() gates dispatch. hooks pre-task/post-task CLI records task lifecycle for the learning loop.", + "evidence_files": [ + "v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts", + "v3/@claude-flow/cli/src/services/pheromone-adaptive.ts", + "v3/@claude-flow/cli/src/commands/hooks.ts", + "docs/reviews/intelligence-system-audit-2026-05-29.md" + ], + "zo_relevance": "ZO routes models statically via agent frontmatter. Worth adapting: (a) outcome-fed routing priors \u2014 PRIORS.md entries could carry win-rates per agent/model/task-type that the lead-orchestrator consults at spawn time; (b) a deterministic tier \u2014 ZO agents should recognize lint/rename/version-bump work needing zero LLM calls; (c) APSC-style eligibility from oracle outcomes (an agent config repeatedly failing gates gets suspended). Heed their inverted-reward bug: sign conventions in feedback loops need tests." + }, + { + "name": "The dead coordination engine (@claude-flow/swarm library)", + "what_it_is": "A 13,157-line, DDD-structured TypeScript package: QueenCoordinator with task analysis/delegation plans/ReasoningBank pattern matching, UnifiedCoordinator, TopologyManager with O(1) role indexes and partition/rebalance logic, AgentPool, MessageBus, AttentionCoordinator (multi-head/flash/MoE 'attention-based coordination'), FederationHub for ephemeral cross-swarm agents, full Raft/PBFT/Gossip with pluggable Ed25519-signed WS transport, and a CQRS application layer \u2014 all typed, all tested (10 test files incl. failure injection).", + "why_special": "Special as a cautionary exhibit: grep proves no CLI command or MCP handler instantiates any of it (sole import is capability-brain.ts using the package NAME as catalog metadata). The runtime reimplemented simpler file-based equivalents, leaving this as showcase code whose class names and 'performance targets' (task analysis <50ms) power the marketing narrative. Its consensus 'nodes' were, per the transport docstring, a single process synthesizing peers' replies inline; agents are domain entities in a repository, never processes. This is the largest and best-disguised gap between implemented-looking and actually-wired in the repo.", + "how_it_works": "Library-only: EventEmitter classes managing in-memory Maps of AgentState/TaskDefinition/TopologyNode; SpawnAgentCommandHandler saves an Agent entity to a repository interface; the ADR-095 G2 transport abstraction added real message serialization + signing but no runtime consumer materialized.", + "evidence_files": [ + "v3/@claude-flow/swarm/src/queen-coordinator.ts", + "v3/@claude-flow/swarm/src/unified-coordinator.ts", + "v3/@claude-flow/swarm/src/topology-manager.ts", + "v3/@claude-flow/swarm/src/application/commands/spawn-agent.command.ts", + "v3/@claude-flow/swarm/src/workers/worker-dispatch.ts" + ], + "zo_relevance": "Pure negative lesson, and an important one for ZO's self-evolution ambitions: coordination sophistication that isn't on the runtime path is marketing debt that eventually forces an embarrassing audit. ZO's discipline should be: no spec/agent/mechanism ships unless a workflow invokes it and the oracle can observe it firing \u2014 arguably worth encoding as a ZO platform prior." + } + ], + "architecture_notes": "Runtime path of a swarm, verified end-to-end: (1) `swarm_init` (MCP) or `ruflo swarm init` writes a JSON coordination record \u2014 the CLI start command prints it outright: \"Use Claude Code Task tool or hive-mind spawn --claude to drive actual agent execution. This command sets up the topology.\" (2) Agent 'spawning' = appending AgentRecords to .claude-flow/agents/store.json with model routing metadata. (3) Execution is one of: native Claude Code Task subagents (the doctrine in the scaffolded CLAUDE.md and newest plugin skills \u2014 named agents, run_in_background, SendMessage, worktrees); `agent_execute` = a single stateless Anthropic Messages API call with default max_tokens 1024 and NO tool use (a text completion, not an agent); or `claude --print` headless processes (hive-mind --claude launcher; worker daemon). (4) Consensus/broadcast/memory tools mutate shared JSON/SQLite state (.swarm/memory.db via sql.js/AgentDB with HNSW + ONNX embeddings; hive state JSON for votes). Hooks layer: Claude Code settings.json hooks route every prompt/edit/bash through hook-handler.cjs into learning/metrics/session persistence \u2014 coordination-by-side-effect around the native loop, cross-platform via Node (not bash). The three-generation stratigraphy is legible in-repo: v2 prompt theater (.claude/agents/*.md personas, emoji-laden hive prompts) \u2192 v3 aspirational engine (@claude-flow/swarm DDD library, unwired) \u2192 v3.x pragmatic ledger (file-state MCP tools + native Task doctrine + honesty enums). Scale: ~450 MCP tool registrations across ~40 tool files, 107 agent .md files, 35 plugins, 482 v3 test files; they built guidance_brain/capability-brain specifically because the model can't navigate their own tool sprawl \u2014 a self-inflicted discovery problem ZO avoids by staying small. The guidance package (CLAUDE.md compiled to enforced gates with cryptographic ledger) and federation plugin (A2A agent cards, WS transport with Ed25519 envelopes) are adjacent capabilities worth separate lenses.", + "weaknesses": [ + "Headline architecture is unwired: the 13k-line @claude-flow/swarm coordination engine (queen, topology manager, Raft/PBFT/Gossip consensus) is imported by nothing on the runtime path \u2014 MCP handlers use reimplemented JSON-file bookkeeping instead; 'fault-tolerant consensus' in marketing refers to library code whose nodes historically synthesized their own peers' replies in-process.", + "'Agents' from agent_execute are single-shot 1024-token text completions with no tools and no loop \u2014 calling the result a coordinated worker substantially overstates it; real agentic execution is delegated entirely to Claude Code's native Task tool or headless claude processes.", + "Consensus voter independence is unenforced: in the primary hive-mind flow one Claude session role-plays queen and all voters, so BFT/quorum outcomes are correlated model outputs wearing protocol bookkeeping \u2014 decision theater unless callers deliberately spawn independent contexts.", + "Documented history of fabricated metrics: the project's own 2026-05-29 audit found Flash Attention speedups generated by Math.random() at runtime, HNSW '150x\u201312,500x' measuring 1.48x, hardcoded 0.99 'recall' constants, and a critical inverted-reward bug that reinforces bad agents when users penalize them; trust requires reading their audit trail, not their README.", + "Extreme surface-area bloat: ~450 MCP tools, 35 plugins, 107 agent definitions, plus neural/quantum-adjacent naming (attention coordinators, pheromones, hive minds) that mostly wraps EMA counters and JSON files \u2014 enormous context/discovery burden and a maintenance treadmill visible in ~3,000 referenced issues.", + "Prompt-layer agent .md files (byzantine-coordinator, crdt-synchronizer, etc.) describe protocols the runtime cannot execute as described; they function as personas, and their embedded tool examples drift from actual tool names across versions (ADR-382 'scaffold drift remediation' is an entire release theme).", + "Coordination state is scattered across at least four stores (.claude-flow/swarm JSON, agents store.json, .swarm/memory.db, .hive-mind/ sessions) with known sync gaps patched case-by-case (#2085 agent/swarm store divergence), rather than one coherent state model." + ], + "notable_files": [ + "v3/@claude-flow/cli/src/mcp-tools/swarm-tools.ts", + "v3/@claude-flow/cli/src/mcp-tools/hive-mind-tools.ts", + "v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts", + "v3/@claude-flow/cli/src/mcp-tools/agent-execute-core.ts", + "v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts", + "v3/@claude-flow/cli/src/commands/hive-mind.ts", + "v3/@claude-flow/cli/src/commands/swarm.ts", + "v3/@claude-flow/cli/src/commands/daemon.ts", + "v3/@claude-flow/cli/src/services/headless-worker-executor.ts", + "v3/@claude-flow/cli/src/services/pheromone-adaptive.ts", + "v3/@claude-flow/cli/src/init/claudemd-generator.ts", + "v3/@claude-flow/swarm/src/queen-coordinator.ts", + "v3/@claude-flow/swarm/src/consensus/transport.ts", + "v3/@claude-flow/swarm/src/consensus/raft.ts", + "v3/@claude-flow/swarm/src/topology-manager.ts", + "docs/reviews/intelligence-system-audit-2026-05-29.md", + "verification/CAPABILITIES.md", + "verification/results.md", + "plugins/ruflo-swarm/skills/swarm-init/SKILL.md", + ".claude/agents/swarm/hierarchical-coordinator.md", + ".claude/agents/hive-mind/queen-coordinator.md", + ".claude/helpers/hook-handler.cjs", + ".claude/helpers/router.cjs", + ".claude/settings.json", + "v3/@claude-flow/guidance/README.md" + ] + }, + { + "repo": "ruflo", + "lens": "plugins-dx", + "summary": "Ruflo (formerly claude-flow, ruvnet) is a sprawling \"meta-harness\" for Claude Code/Codex: a fat MCP server + CLI (v3/@claude-flow/cli, ~48 mcp-tool modules, claimed 314 tools) surrounded by 38 thin Claude Code-native plugins under plugins/, each a standardized bundle of auto-discovered SKILL.md skills, command/agent markdown, real .mjs scripts, and a scripts/smoke.sh structural contract. A top-level marketplace.json makes the repo itself a Claude Code plugin marketplace, and skills.sh.json registers 134 skills in 34 groups with the external skills.sh installer. Adoption DX is unusually honest for this genre: the README leads with a two-path table (plugin install = slash-commands-only, zero workspace files, no MCP server; `npx ruflo init` = full loop with .claude/, hooks, daemon), plus `init --wizard/--preset`, `doctor --fix`, a discover-plugins skill with recommended plugin stacks, and an eject command.\n\nThrough this lens the genuinely differentiated material is the verification stack, and it is fully implemented, not aspirational. verification/ holds a three-layer regression-protection system: (1) ~55 CI jobs in v3-ci.yml, most of them behavioral smoke tests that assert user-visible failure modes (fresh npm install on real Node versions, hook stdin round-trips, MCP wire format, Windows shims) rather than code paths \u2014 motivated by three documented 2026-05-08 regressions that all passed unit tests; (2) a \"witness\" manifest attesting that every documented fix's load-bearing code substring (\"marker\") is still present, per-OS (linux/macos/windows), SHA-256 + Ed25519-signed, 117 fixes currently verified; (3) append-only JSONL temporal history that turns regression triage into a two-commit bisect window. The toolkit is deliberately portable (plugins/ruflo-core/scripts/witness/, single dependency, documented adoption tutorial). A related ratchet pattern (ADR-112) makes MCP tool-description quality a monotone-decreasing CI baseline.\n\nThe second differentiator is ADR-driven development at industrial intensity: 175 ADR files in v3/docs/adr (numbered to 381) plus per-plugin ADR dirs, cited 1,154 times across CLI source (99 unique ADR ids), with CI smoke jobs, witness fixes, release commits, and even source-file module boundaries named after ADR parts (\"ADR-382 Part B\", \"kept in a sibling module because migrate.ts is over the 500-line budget\"). ADRs carry Parts, enumerated Gaps, and acceptance-evidence sections; a ruflo-adr plugin manages lifecycle with tested scripts. Ironically, ADR-382 itself \u2014 the ADR the current release is named after \u2014 is referenced by three source files but absent from the repo, and the repo's self-description numbers drift (SKILL.md claims 267 skills vs 134 registered; the legacy top-level plugin/ dir still ships a v2.5.0 plugin.json pointing at claude-flow@alpha and flow-nexus). The project that built drift-guards for everything still exhibits drift in its own meta-layer; the guards it built for exactly this (smoke-init-scaffold-references.mjs) ship warn-only.", + "key_features": [ + { + "name": "Witness manifest: cryptographically-attested fix-marker regression tracking", + "what_it_is": "A signed per-OS manifest listing every documented fix as {file, sha256, distinctive marker substring}. If a refactor deletes the load-bearing line of a past fix, markerVerified flips false and CI blocks publish. JSONL temporal history pinpoints the introducing commit.", + "why_special": "Solves a real gap: regressions that pass unit tests because the tests never covered the fix. It machine-enforces 'the same mistake never happens twice' instead of documenting it. Marker-choice guidance (bad: 'function'/'TODO'; good: the exact swapped expression from the diff) is genuinely good craft. Drift-vs-regression distinction (hash changed but marker present = drift, not failure) suppresses false alarms. Per-OS bundles catch CRLF/path-separator drift. Fully implemented and running: 117/117 fixes verified in macos/manifest.md.json, witness-verify CI job at v3-ci.yml:2040 gates publish. Caveat: the Ed25519 seed is sha256(gitCommit + ':ruflo-witness/v1') \u2014 derived from public info, so anyone can forge a valid signature; it's tamper-evidence/reproducibility, not authentication, despite 'cryptographically-signed' branding.", + "how_it_works": "plugins/ruflo-core/scripts/witness/{init,regen,verify,history,perf,lib}.mjs (single dep: @noble/ed25519). Input verification/witness-fixes.json (OS-independent); regen.mjs writes verification//manifest.md.json + appends verification//history.jsonl; verify.mjs checks hash + marker + signature; history.mjs answers 'when did F12 regress' (lastPass..regressedAt window for git log). perf.mjs adds a parallel performance.jsonl baseline (install time, cold import, witness_verify itself). CI matrix job runs per-OS. A witness-curator agent and witness skill wrap the workflow for Claude.", + "zo_relevance": "Highest-value adoption candidate for ZO. ZO's PRIORS.md records 'rules learned + verified solution' as prose \u2014 the witness pattern makes each prior machine-checkable: every prior gets a marker in the code that embodies its fix, and a pre-commit/oracle gate verifies all markers still present. Directly implements ZO's self-evolution principle ('verify the updated rule would have caught the original failure') as a standing CI check instead of a one-time verification. The toolkit is portable by design (documented adoption tutorial, no ruflo assumptions in lib.mjs); ZO could vendor the 6 .mjs files or reimplement in Python in a day. Skip the Ed25519 layer (theater for ZO's threat model); keep marker + history.", + "evidence_files": [ + "verification/README.md", + "plugins/ruflo-core/scripts/witness/lib.mjs", + "verification/macos/manifest.md.json", + "verification/macos/history.jsonl", + "verification/witness-fixes.json", + ".github/workflows/v3-ci.yml" + ] + }, + { + "name": "Behavioral smoke-test CI philosophy (~55 jobs testing user-visible failure modes)", + "what_it_is": "CI layer that exercises real artifacts the way users hit them \u2014 fresh `npm install` of the packed tarball on multiple Node versions, plugin hooks.json invoked as a real subprocess with realistic stdin JSON, MCP wire-format round-trips, Windows-specific hook shim execution \u2014 instead of (only) unit-testing code paths.", + "why_special": "Grounded in a documented post-mortem: three 2026-05-08 regressions (#1859/#1862/#1867) each passed unit tests + typecheck on the broken commit but broke every user on first install (native-dep install failure, invalid hook flag, flag-parser positional preference). docs/validation/README.md analyzes exactly why CI passed while users broke, and each regression became a named CI job class. all-plugins-smoke.yml then generalizes it: every plugin ships scripts/smoke.sh (34/38 do) and a meta-runner executes all of them in parallel (~8s) as a required PR check \u2014 the workflow header even admits the smoke files existed unenforced for 30 plugins before iteration 74.", + "how_it_works": "v3-ci.yml declares ~55 jobs, majority named *-smoke, each tied to a regression class or ADR (smoke-install-no-bsqlite, plugin-hooks-smoke, mcp-protocol-smoke, windows-hook-shim-smoke, memory-import-smoke, tool-output-guardrail-smoke, wizard-init-regression-guard...). Plugin-level scripts live at plugins/*/scripts/{smoke.sh,test-hooks.mjs,test-mcp-protocol.mjs}. All gate the publish job.", + "zo_relevance": "ZO's oracle verifies delivery-repo metrics but ZO's own platform (setup.sh, hooks, validate-docs.sh, zo CLI) is exactly the kind of surface these regressions hit \u2014 subprocess flag parsing, fresh-clone setup, hook stdin. Adopt the doctrine: every ZO platform failure in PRIORS.md should spawn a smoke script that reproduces the user-visible symptom, plus a meta-runner so new smoke scripts are auto-enforced. The 'smoke.sh as structural contract per component' pattern maps cleanly onto ZO's agents/commands directories.", + "evidence_files": [ + "docs/validation/README.md", + ".github/workflows/v3-ci.yml", + ".github/workflows/all-plugins-smoke.yml", + "plugins/ruflo-core/scripts/test-hooks.mjs", + "plugins/ruflo-core/scripts/smoke.sh" + ] + }, + { + "name": "ADRs as the executable spine of development", + "what_it_is": "175 ADR files (v3/docs/adr, numbered to 381) that are not documentation-after-the-fact but the unit of work: ADRs have Parts (A/B/C) that map to separate PRs, enumerated Gaps, and 'Acceptance evidence' sections; code comments, CI job names, witness fix ids, and release commit subjects all cite ADR numbers.", + "why_special": "The cross-referencing density is the differentiator: 1,154 ADR citations across CLI source, 99 unique ADR ids \u2014 decisions are greppable from the code that implements them, and CI jobs (e.g. tool-descriptions-audit 'ADR-112') enforce specific ADRs mechanically. Recent ADRs are technically serious (ADR-381 does family-wise error control over an adaptive promotion stream with e-processes, \u03b1-spending ledger, governed reset epochs). ADR-382 shows how a bug becomes a multi-part remediation program: Part A (pin MCP launch), Part B (the migrate detection ADR-128 promised and never shipped \u2014 they call out their own broken promise in a code comment), Part C (dead-reference guard). BUT: the ADR-382 file itself is missing from the repo while three source files cite its path \u2014 and the ~37 'dream-cycle' ADRs (340-376) read like generated design-space exploration whose implementation status is unverifiable from the ADR alone.", + "how_it_works": "v3/docs/adr/*.md with Status/Date/Related/Prompted-by headers; per-plugin docs/adrs/ (e.g. plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md); ruflo-adr plugin provides create/index/reindex/verify skills backed by tested scripts (scripts/{import,reindex,verify}.mjs + __tests__/). Source files open with ADR provenance comments (migrate-agent-detection.ts). CI jobs and witness fixes carry ADR ids.", + "zo_relevance": "ZO's DECISION_LOG.md is an append-only flat log \u2014 fine for chronology, weak for retrieval and enforcement. Adopt: (1) numbered decision records with stable ids cited from code comments and gate definitions, so `grep ADR-NNN` reconstructs a decision's blast radius; (2) 'Prompted by' + 'Acceptance evidence' sections linking each decision to the failure that caused it and the test that proves it \u2014 a natural join with PRIORS.md. Avoid: ruflo's volume (175 ADRs is its own drift surface, as ADR-382's absence proves); ZO should keep the count small and gate that every code-cited decision id resolves to a file \u2014 a check ruflo itself lacks.", + "evidence_files": [ + "v3/docs/adr/ADR-381-sequential-promotion-evidence-governance.md", + "v3/docs/adr/ADR-102-plugin-hook-cli-flag-regression-ci-guard.md", + "v3/docs/adr/ADR-103-witness-temporal-history.md", + "v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts", + "plugins/ruflo-adr/scripts/reindex.mjs" + ] + }, + { + "name": "Monotone-decreasing quality ratchet (ADR-112 tool-description audit)", + "what_it_is": "A CI gate requiring every MCP tool description to contain discoverability guidance ('Use when...', 'Prefer X over Y', 'fall back...'), be \u226580 chars, and be unique \u2014 with the violation count stored as a baseline that may only decrease.", + "why_special": "The ratchet mechanic is the smart part: instead of demanding perfection immediately (which blocks) or warning forever (which is ignored), the baseline file (verification/mcp-tool-baseline.json) freezes current debt and fails CI on any increase, while --update-baseline (explicitly documented as 'do NOT use to mask regressions') lowers it after improvement PRs. It statically parses the same registry the MCP server assembles at startup, so the audit can't drift from runtime truth. Commodity idea (lint baselines exist), uncommonly applied to prompt/description quality for agent tool selection.", + "how_it_works": "scripts/audit-tool-descriptions.mjs regex-scans v3/@claude-flow/cli/src/mcp-tools/*.ts for name/description pairs, checks GUIDANCE_PATTERNS + length + uniqueness, exits non-zero if no-guidance count exceeds baseline. CI job tool-descriptions-audit in v3-ci.yml. Same ratchet idea reappears in smoke-init-scaffold-references.mjs's warn-only\u2192--strict migration plan.", + "zo_relevance": "Directly portable to ZO's agent definitions and spawn prompts: ZO's contract-first spawning depends on agents having crisp interface descriptions; a ratchet script asserting every agent .md has required frontmatter, a contract section, and description quality \u2014 with a monotone baseline \u2014 is a ~100-line Python script and closes the gap between ZO's validate-docs.sh (structural counts) and actual prompt quality.", + "evidence_files": [ + "scripts/audit-tool-descriptions.mjs", + "verification/mcp-tool-baseline.json", + "v3/docs/adr/ADR-112-mcp-tool-discoverability.md" + ] + }, + { + "name": "Standardized plugin anatomy + marketplace with completeness guards", + "what_it_is": "38 plugins under plugins/, each: .claude-plugin/plugin.json (metadata only \u2014 skills/commands/agents arrays are a validation ERROR because Claude Code auto-discovers), skills//SKILL.md, commands/*.md, agents/*.md, scripts/*.mjs (real implementations: 79 .mjs files, 24 test files), scripts/smoke.sh, README + REFERENCE. Registered in .claude-plugin/marketplace.json; CI guards that every plugins/ dir has a marketplace entry.", + "why_special": "The anatomy is enforced, not aspirational: validate-plugin skill encodes 10 concrete checks (including the counterintuitive 'no legacy arrays in plugin.json' rule learned from Claude Code rejecting plugins), plugin-package-audit + validate-marketplace CI jobs run structurally, and the marketplace-completeness check exists because three plugins actually shipped unlisted (ADR-382 Gap 4 \u2014 they turned the incident into a guard). Skills wrap deterministic scripts rather than being pure prompts: cost-health composes four subcheck scripts in parallel with max-exit-code semantics explicitly for CI gates. This is a coherent 'plugin = markdown interface + script implementation + smoke contract' discipline.", + "how_it_works": "plugins/*/; .claude-plugin/marketplace.json at repo root (repo doubles as a Claude Code marketplace via /plugin marketplace add ruvnet/ruflo); skills.sh.json exposes 134 skills in 34 groups to the external skills.sh installer (npx skills add ruvnet/ruflo); smoke-init-scaffold-references.mjs check 4 enforces marketplace completeness; scripts/smoke-all-plugins.mjs runs every plugin's smoke.sh.", + "zo_relevance": "ZO's .claude/agents + commands are one flat namespace with counts hand-maintained across 6 files (the cascade chain in CLAUDE.md). Ruflo's lesson: derive counts/rosters from the filesystem and guard with a completeness check, rather than hand-cascading \u2014 smoke-init-scaffold-references.mjs derives the canonical CLI name from package.json 'so this check tracks a future rename automatically', the exact upgrade path for ZO's EXPECTED_AGENTS array. The skill-wraps-script pattern also fits ZO: gates/approve etc. should delegate to deterministic scripts with exit codes, not prompt-only logic.", + "evidence_files": [ + "plugins/README.md", + ".claude-plugin/marketplace.json", + "plugins/ruflo-plugin-creator/skills/validate-plugin/SKILL.md", + "plugins/ruflo-cost-tracker/skills/cost-health/SKILL.md", + "skills.sh.json", + "scripts/smoke-init-scaffold-references.mjs" + ] + }, + { + "name": "Scaffold-drift remediation: treating init output as a versioned artifact (ADR-382)", + "what_it_is": "The init scaffold (what `npx ruflo init` writes into user projects) is guarded against content drift: dead CLI invocations, references to MCP tools that no longer exist in the live registry, unpinned npx launches in plugin .mcp.json, and marketplace gaps \u2014 plus a migrate path that detects agents deleted from the template and suggests the owning plugin.", + "why_special": "Most agent frameworks scaffold-and-forget; user projects then rot as the platform evolves. Ruflo statically parses mcp-client.ts's import list to derive the live tool registry 'without executing TypeScript', then diffs scaffold references against it \u2014 drift detection against the source of truth, not a hand-maintained list. migrate-agent-detection.ts reads Claude Code's actual global install registry (~/.claude/plugins/installed_plugins.json) to decide whether a missing agent is a gap or an intentional plugin migration. Honest engineering: ships warn-only with an explicit documented plan for when each check flips to --strict. Caveat: warn-only means it currently gates nothing, and the ADR describing the plan is the one missing from the repo.", + "how_it_works": "scripts/smoke-init-scaffold-references.mjs (4 static assertions, zero deps, warn-only vs --strict); v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts (9 removed-agent mappings \u2192 install suggestions); init pipeline in v3/@claude-flow/cli/src/init/ (executor.ts 2356 lines: .claude/ + .claude-flow/ trees, generated CLAUDE.md, settings merge, cross-platform hook command strings, helper stamping for upgrade detection); CI jobs init-bundle-invariants-smoke, init-scaffold-references-smoke, wizard-init-regression-guard.", + "zo_relevance": "ZO scaffolds project targets (project:connect, setup.sh) and will hit the same rot: plans and target configs referencing agents/commands that ZO later renames. Adopt the pattern: a drift script that derives ZO's live command/agent surface from the filesystem and asserts scaffolded/target files reference only live names; and an explicit upgrade command (ruflo's executeUpgradeWithMissing + helper stamp files) instead of ZO's current re-run-setup.sh approach.", + "evidence_files": [ + "scripts/smoke-init-scaffold-references.mjs", + "v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts", + "v3/@claude-flow/cli/src/init/executor.ts", + "v3/@claude-flow/cli/src/commands/init.ts" + ] + }, + { + "name": "Fail-open cross-platform hook shim", + "what_it_is": "Every plugin hook command is a single `node -e` bootstrap that resolves the plugin's ruflo-hook.cjs from CLAUDE_PLUGIN_ROOT inside Node (no shell variable expansion), so the identical command string runs on Windows/macOS/Linux; the shim prefers a local binary, falls back to npx --prefer-offline, and always exits 0 so a broken install never blocks the user's turn.", + "why_special": "Encodes two hard-won lessons visible in their own regression history (#1862: hooks erroring on every Write/Edit). Fail-open ('a CLI/install failure never surfaces an error or blocks a turn') is the right default for advisory hooks. The hooks.json description field even documents per-host verdict shape differences (Cursor wants {permission:'allow'}, Codex rejects it and wants exit-0 empty stdout) \u2014 real multi-host compatibility engineering, not claims.", + "how_it_works": "plugins/ruflo-core/hooks/hooks.json (PreToolUse/PostToolUse/PreCompact/Stop \u2192 node -e bootstraps); plugins/ruflo-core/scripts/ruflo-hook.cjs (resolver shim); windows-hook-shim-smoke / windows-hook-execution-smoke / pre-bash-hook-smoke CI jobs verify it as a subprocess.", + "zo_relevance": "Partial adopt. ZO's validate-docs pre-commit hook is deliberately fail-closed (it must block bad commits) \u2014 keep that. But ZO's advisory hooks (memory nudges, logging) should copy the fail-open + always-exit-0 discipline, and if ZO ever targets Windows contributors the node -e no-shell-expansion trick is the proven pattern. Low priority while ZO is single-platform/single-host.", + "evidence_files": [ + "plugins/ruflo-core/hooks/hooks.json", + "plugins/ruflo-core/scripts/ruflo-hook.cjs", + "plugin/hooks/hooks.json" + ] + }, + { + "name": "Adoption DX: honest two-path install + guided discovery", + "what_it_is": "README leads with a comparison table of the two install paths (Claude Code plugin = slash commands only, zero workspace files, NO MCP server, explicitly 'memory_store, swarm_init won't be callable'; npx ruflo init = full loop) \u2014 citing the issue (#1744) where users were confused. Onboarding is init --wizard/--preset \u2192 doctor --fix \u2192 discover-plugins, with per-use-case recommended plugin stacks and a repo-root SKILL.md that tells agents when NOT to suggest ruflo ('one-shot edits... orchestration overhead isn't worth it').", + "why_special": "The candor is rare in this ecosystem: the lite path's limitations are stated in bold in the first screen, and the enrollment funnel (ADR-302 Cognitum account prompt post-init) is one-time, TTY-only, --no-signup-skippable, CI-auto-skipped, and 'never affects init's exit code'. An eject command exists as an exit path. The counterweight: the total surface is enormous (38 plugins, 314 claimed MCP tools, 3 npm identities: ruflo/claude-flow/@claude-flow/cli, plus a legacy v2 plugin/ tree still shipping), so the DX story is 'excellent guided paths through an overwhelming system'.", + "how_it_works": "README.md quick-start table; plugins/ruflo-core/skills/{init-project,discover-plugins,ruflo-doctor}/SKILL.md; v3/@claude-flow/cli/src/commands/{init,doctor,eject,plugins}.ts; funnel/enrollment.ts; bin/cli.js proxies umbrella package \u2192 @claude-flow/cli.", + "zo_relevance": "Two takeaways for ZO: (1) the top-level SKILL.md that teaches an agent when to use \u2014 and when NOT to use \u2014 the system is a cheap, high-leverage artifact ZO lacks (ZO's CLAUDE.md addresses the builder, not an adopting agent); (2) the 'lite vs full' honesty table is the right template if ZO ever splits its plugin-style commands from the full platform. ZO should not copy the surface-area maximalism \u2014 ZO's constraint-driven small roster is a feature.", + "evidence_files": [ + "README.md", + "SKILL.md", + "plugins/ruflo-core/skills/discover-plugins/SKILL.md", + "v3/@claude-flow/cli/src/commands/init.ts", + "v3/@claude-flow/cli/src/commands/eject.ts" + ] + } + ], + "architecture_notes": "Monorepo with three concentric systems. (1) Core: v3/@claude-flow/* TypeScript workspaces \u2014 cli (26+ commands, ~48 mcp-tool modules forming one fat MCP server), memory (AgentDB/HNSW/better-sqlite3 with fallback), hooks, guidance ('governance control plane'), security, codex (dual-host support) \u2014 plus Rust crates/ and a separate ruflo/ appliance dir (docker-compose, own package.json). Published under three npm identities (ruflo thin wrapper, claude-flow umbrella, @claude-flow/cli implementation) via bin/cli.js proxies. (2) Distribution: plugins/ (38 Claude Code-native plugins, markdown + .mjs scripts, no build step) registered in root .claude-plugin/marketplace.json so the GitHub repo doubles as a marketplace; skills.sh.json bridges to the external skills.sh installer. The plugins are deliberately thin \u2014 the intelligence lives in the MCP server; a plugin is mostly an interface contract (skills/commands/agents) plus deterministic scripts with exit codes. (3) Verification: file-based, git-committed state under verification/ (per-OS signed manifests, JSONL history, performance baselines, monotone tool-description baseline) \u2014 the same 'plain files in git as database' philosophy as ZO's memory/, but for regression state rather than session memory. Governance is ADR-first: decisions get numbered files, code cites them (1,154 citations), CI jobs enforce them, and remediation programs are structured as ADR Parts mapped to PRs. Legacy debt is visible and acknowledged: top-level plugin/ still carries the v2.5.0 claude-flow plugin (74 agents, 38 more skills) alongside the v3 plugins/ tree, and code comments explicitly note the two coexisting plugin systems (Claude Code marketplace registry vs ruflo's own npm-package PluginManager). CI is the real spine: ~55 jobs in v3-ci.yml plus ~28 sibling workflows, nearly all behavioral smoke tests gating publish. Development is evidently heavily agent-driven (dream-cycle ADR series, iteration-numbered workflow comments), which explains both the extraordinary guard density \u2014 guards compensate for agent-generated churn \u2014 and the recurring pattern of docs/counts drifting ahead of reality.", + "weaknesses": [ + "ADR-382 \u2014 the ADR the current release (3.38.0) is named after and which three source files cite by path \u2014 does not exist in the repo (v3/docs/adr stops at ADR-381). The ADR-driven process has unguarded drift in its own meta-layer.", + "Self-description numbers are inflated or stale: SKILL.md claims '267 skills across all plugins' but skills.sh.json registers 134 (and 136 SKILL.md files exist under plugins/); agent counts vary between 60+/74+/98/100+ across README, plugin.json, and marketplace descriptions; root CLAUDE.md itself warns agents not to copy 'stale version or capability counts' \u2014 an admission the problem is chronic.", + "The witness layer's 'cryptographic signing' oversells: the Ed25519 seed is sha256(gitCommit + constant), derivable by anyone, so signatures prove nothing against a deliberate attacker \u2014 the real value is the marker-substring check and temporal history; the crypto is reproducibility dressing.", + "The flagship drift guard (smoke-init-scaffold-references.mjs) ships warn-only (always exit 0) with a promised --strict flip gated on backlog cleanup \u2014 currently it gates nothing.", + "Two overlapping plugin systems coexist (legacy top-level plugin/ at v2.5.0 whose root plugin.json still launches claude-flow@alpha and optional flow-nexus servers, vs v3 plugins/ marketplace; plus ruflo's separate npm-package PluginManager registry) \u2014 a confusing adoption surface the code comments themselves acknowledge.", + "Enormous cognitive surface: 38 plugins, claimed 314 MCP tools, 3 npm package identities, a rebrand (claude-flow\u2192ruflo) mid-flight, and ~37 'dream-cycle' ADRs (340-376) that read as generated design exploration with unverifiable implementation status \u2014 deep-verification of most subsystem claims (swarms, neural training, federation) is impractical and some are likely thinner than documented.", + "Marketing tone throughout (badge walls, '150x-12,500x faster', 'Brain AGI', ecosystem download counters) forces readers to verify every claim in code; the verified parts are good, but the signal-to-noise cost is real.", + "Unit-test coverage is thin relative to smoke coverage (207 test files in cli/__tests__ against a very large surface; plugins average <1 test file each) \u2014 the strategy leans almost entirely on behavioral smoke + witness markers, which catch presence and wiring but not logic-level correctness." + ], + "notable_files": [ + "/Users/sam101fe4x/Documents/code/ruflo/verification/README.md", + "/Users/sam101fe4x/Documents/code/ruflo/docs/validation/README.md", + "/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-core/scripts/witness/lib.mjs", + "/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-core/skills/witness/SKILL.md", + "/Users/sam101fe4x/Documents/code/ruflo/scripts/audit-tool-descriptions.mjs", + "/Users/sam101fe4x/Documents/code/ruflo/scripts/smoke-init-scaffold-references.mjs", + "/Users/sam101fe4x/Documents/code/ruflo/v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts", + "/Users/sam101fe4x/Documents/code/ruflo/v3/docs/adr/ADR-102-plugin-hook-cli-flag-regression-ci-guard.md", + "/Users/sam101fe4x/Documents/code/ruflo/v3/docs/adr/ADR-103-witness-temporal-history.md", + "/Users/sam101fe4x/Documents/code/ruflo/v3/docs/adr/ADR-112-mcp-tool-discoverability.md", + "/Users/sam101fe4x/Documents/code/ruflo/v3/docs/adr/ADR-381-sequential-promotion-evidence-governance.md", + "/Users/sam101fe4x/Documents/code/ruflo/.github/workflows/v3-ci.yml", + "/Users/sam101fe4x/Documents/code/ruflo/.github/workflows/all-plugins-smoke.yml", + "/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-plugin-creator/skills/validate-plugin/SKILL.md", + "/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-core/hooks/hooks.json", + "/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-cost-tracker/skills/cost-health/SKILL.md", + "/Users/sam101fe4x/Documents/code/ruflo/v3/@claude-flow/cli/src/init/executor.ts", + "/Users/sam101fe4x/Documents/code/ruflo/SKILL.md", + "/Users/sam101fe4x/Documents/code/ruflo/skills.sh.json", + "/Users/sam101fe4x/Documents/code/ruflo/.claude-plugin/marketplace.json", + "/Users/sam101fe4x/Documents/code/ruflo/plugins/README.md", + "/Users/sam101fe4x/Documents/code/ruflo/verification/CAPABILITIES.md" + ] + }, + { + "repo": "ralph", + "lens": "full", + "summary": "Ralph (snarktank/ralph, based on Geoffrey Huntley's \"Ralph Wiggum\" pattern) is a ~113-line bash loop plus two prompt files that turns a single-shot CLI coding agent (Amp or Claude Code) into a long-running autonomous builder. The entire technique: a human-authored PRD is converted (by a skill) into prd.json \u2014 a flat list of user stories, each with verifiable acceptanceCriteria, an integer priority, and a boolean `passes` flag. ralph.sh then loops up to MAX_ITERATIONS (default 10), each iteration spawning a COMPLETELY FRESH agent process (`claude --dangerously-skip-permissions --print < CLAUDE.md`, or `cat prompt.md | amp --dangerously-allow-all`) with zero conversational carryover. The prompt tells each fresh instance to: read prd.json, read progress.txt (Codebase Patterns section first), check out the PRD's branch, pick the highest-priority story with passes:false, implement ONLY that story, run the project's quality checks, commit `feat: [ID] - [Title]` only if green, flip passes:true, and append learnings to progress.txt. When the agent observes all stories pass, it emits the literal sentinel `COMPLETE`; the bash loop greps stdout for it and exits 0, else exits 1 at the iteration cap.\n\nThe design philosophy is the inverse of orchestration-heavy systems like ZO: instead of adding roles, contracts, and verification layers at runtime, Ralph pushes ALL intelligence to plan time (story slicing) and ALL state to disk (git history + prd.json + progress.txt + in-repo AGENTS.md files), so the runtime can be trivially dumb. The core insight \u2014 stated explicitly in skills/ralph/SKILL.md as \"The Number One Rule\" \u2014 is that each story must be completable within one context window, because the executor has no memory. Fresh context per story structurally eliminates the three classic long-agent failure modes: context rot (every iteration starts clean), state hallucination (all state is re-read from files each time, so confabulated state cannot persist), and compounding errors (each commit is a checkpoint gated by typecheck/tests; \"broken code compounds across iterations\" is the stated reason for the CI-green rule). That is why such a tiny system reportedly works: the loop IS the context-management strategy, and git IS the checkpoint system.\n\nWhat is genuinely implemented: the loop, dual-tool support, sentinel completion detection, archive-on-branch-change lifecycle, the append-only memory protocol, and two well-crafted skills (PRD generation with lettered-option clarifying questions; PRD\u2192prd.json conversion encoding sizing/ordering/verifiability rules). What is NOT implemented despite the framing: any independent verification. The harness never runs a test, never inspects a diff, never validates prd.json \u2014 the agent grades its own homework and self-asserts passes:true; the only harness-level check is a grep for a sentinel string. The \"dev-browser skill\" that browser verification depends on is referenced everywhere but not shipped in this repo (the Claude variant softens it to \"if available\"). The flowchart/ directory is a React Flow presentation deployed to GitHub Pages \u2014 real code, but marketing material, not system capability.", + "key_features": [ + { + "name": "Fresh-context iteration loop (the Ralph technique core)", + "what_it_is": "A bash for-loop that spawns a brand-new agent process per iteration with clean context, feeding the same static prompt file every time; the prompt makes the agent re-derive all state from disk.", + "why_special": "This is the load-bearing idea and it is genuinely contrarian: rather than keeping one long agent session alive (and fighting context rot, drift, and stale beliefs), it makes statelessness the default and forces all memory through files and git. Iteration N cannot inherit iteration N-1's hallucinations \u2014 only its commits and written notes. The runtime harness needs zero intelligence; total harness complexity is ~113 lines of bash.", + "how_it_works": "ralph.sh lines 84-108: `for i in $(seq 1 $MAX_ITERATIONS)`; per iteration runs `claude --dangerously-skip-permissions --print < CLAUDE.md` (prompt injected via stdin, --print = non-interactive single response) or `cat prompt.md | amp --dangerously-allow-all`, capturing output via `$(... 2>&1 | tee /dev/stderr) || true` so the user sees live streaming while the script greps the transcript. No --continue/--resume flag anywhere: fresh session is deliberate. `sleep 2` between iterations. `set -e` at top with `|| true` on the agent call so agent failures don't kill the loop.", + "evidence_files": [ + "ralph.sh", + "CLAUDE.md", + "prompt.md", + "AGENTS.md" + ], + "zo_relevance": "Directly adoptable as ZO's execution primitive. ZO already does fresh context at phase transitions; Ralph argues for fresh context per SUBTASK, with the plan file as the ledger. ZO's builder agents could be spawned per-plan-item in a loop rather than living across items, with STATE.md/plan.md as the re-read ground truth. This would also make ZO's watchdog/anti-stall problem (see ZO's recent watchdog spec) much smaller: a hung agent costs one iteration, not a session." + }, + { + "name": "prd.json as machine-checkable task ledger", + "what_it_is": "A flat JSON file of user stories, each with id, title, description, acceptanceCriteria[], integer priority, boolean passes, and a notes field; plus project-level branchName. The passes flags are the entire progress state machine.", + "why_special": "Boolean passes flags make resume, progress inspection, and completion detection mechanical (`jq '.userStories[] | {id, title, passes}'` is the documented debug command). Compare with markdown plans where 'what is done' is prose interpretation. The ledger doubles as the completion oracle input: 'all passes true' is a decidable predicate.", + "how_it_works": "prd.json.example shows the schema. CLAUDE.md/prompt.md step 4: 'Pick the highest priority user story where passes: false'; step 9: 'Update the PRD to set passes: true for the completed story'. ralph.sh reads only branchName from it (via jq) for archiving. Caveat: passes:true is SELF-ASSERTED by the agent after running whatever checks it chooses \u2014 no external process validates it. The notes field exists in the schema but no prompt ever instructs its use (vestigial).", + "evidence_files": [ + "prd.json.example", + "CLAUDE.md", + "prompt.md", + "ralph.sh", + "skills/ralph/SKILL.md" + ], + "zo_relevance": "High. ZO's plan.md (specs/plan.md) is markdown; adding a machine-readable per-subtask status ledger (or generating one from plan.md) would let ZO's continue/build auto-detection and gate logic work off decidable predicates instead of prose parsing. Unlike Ralph, ZO should keep the flag-flipping privilege with the oracle, not the builder \u2014 that single change fixes Ralph's biggest hole while keeping the ledger mechanics." + }, + { + "name": "Context-window-budgeted story sizing ('The Number One Rule')", + "what_it_is": "A hard planning constraint, enforced by the PRD-conversion skill, that every story must be completable by a fresh agent in ONE context window, with concrete right-sized/too-big examples and a 2-3-sentence rule of thumb.", + "why_special": "This is the real scaling law of the system and the most transferable insight: the unit of work is sized to the executor's memory, not to human sprint conventions. 'Add a DB column and migration' = right; 'Add authentication' = split into schema/middleware/login UI/session handling. It converts the vague art of task decomposition into a checkable planning rule, and it is WHY the dumb loop can work \u2014 oversized stories are named as the primary failure mode ('the LLM runs out of context before finishing and produces broken code').", + "how_it_works": "skills/ralph/SKILL.md sections 'Story Size: The Number One Rule', 'Story Ordering: Dependencies First' (schema \u2192 backend \u2192 UI, no forward dependencies since execution is strictly serial by priority), 'Acceptance Criteria: Must Be Verifiable' (good: 'Filter dropdown has options: All, Active, Completed'; bad: 'Works correctly'), plus mandatory 'Typecheck passes' on every story and a pre-save checklist. skills/prd/SKILL.md seeds the same structure at PRD-writing time and targets 'junior developer or AI agent' as the reader.", + "evidence_files": [ + "skills/ralph/SKILL.md", + "skills/prd/SKILL.md", + "README.md" + ], + "zo_relevance": "Directly adoptable into ZO's plan schema validation (specs/plan.md): add a validation rule that each plan subtask fits a single context window and has only machine-verifiable acceptance criteria, with Ralph's good/bad criterion examples as the lint spec. ZO's oracle-first principle already demands verifiable metrics at project level; Ralph shows how to push that discipline down to per-subtask granularity." + }, + { + "name": "Three-channel file memory: progress.txt + Codebase Patterns + in-repo AGENTS.md", + "what_it_is": "Cross-iteration memory via (1) an append-only progress.txt with per-story entries including a mandatory 'Learnings for future iterations' section, (2) a curated '## Codebase Patterns' section promoted to the TOP of progress.txt for general reusable knowledge, and (3) instructions to write directory-local learnings into AGENTS.md/CLAUDE.md files inside the target codebase itself.", + "why_special": "The two-tier split (raw append-only log vs. consolidated patterns at top, read-first) is a compact PRIORS.md. The genuinely clever third channel: putting learnings in per-directory AGENTS.md/CLAUDE.md means every future agent invocation auto-loads them contextually for free \u2014 the coding tool's own memory mechanism becomes the knowledge store, benefiting humans and agents alike, with explicit quality gates ('genuinely reusable knowledge' only; do NOT add story-specific details or debugging notes).", + "how_it_works": "CLAUDE.md/prompt.md 'Progress Report Format' (APPEND, never replace; date/story-id header; learnings subsection with patterns/gotchas/context), 'Consolidate Patterns' (promote general learnings to top section, read it FIRST each iteration per step 2 and the 'Important' footer), 'Update AGENTS.md Files' (identify edited dirs, find nearest AGENTS.md, add module conventions/gotchas/dependencies, with good/bad example lists). The Amp variant also logs the thread URL ($AMP_CURRENT_THREAD_ID) so future iterations can call read_thread on prior sessions.", + "evidence_files": [ + "prompt.md", + "CLAUDE.md", + "README.md", + "AGENTS.md" + ], + "zo_relevance": "ZO already has richer versions (PRIORS.md, DECISION_LOG.md, semantic index), so the log itself is not new. Two adoptable ideas: (a) the read-first consolidated-patterns section \u2014 ZO agents should load a small curated PRIORS digest, not the full log; (b) writing learnings into per-directory CLAUDE.md files IN THE DELIVERY REPO so they auto-load contextually. Note the tension with ZO's 'never commit ZO artefacts to target repos' rule \u2014 but codebase-convention CLAUDE.md files are arguably delivery-repo content, not ZO artefacts; worth an explicit carve-out decision." + }, + { + "name": "Sentinel-based completion + hard iteration cap", + "what_it_is": "Termination protocol: the agent emits the literal string COMPLETE only when ALL stories have passes:true; the bash loop greps each iteration's stdout for it (exit 0), otherwise stops at MAX_ITERATIONS (exit 1) pointing the user at progress.txt.", + "why_special": "It is the cheapest possible completion contract between an LLM and a shell script, and it is self-healing in one direction: if the agent finishes the last story but forgets the sentinel, the NEXT fresh iteration sees all passes:true and emits it. The iteration cap is the entire runaway/cost guardrail \u2014 a crude but effective bound on drift, loops, and spend.", + "how_it_works": "ralph.sh lines 98-104 (`grep -q \"COMPLETE\"` on captured OUTPUT) and 110-113 (cap exhaustion exit 1). CLAUDE.md/prompt.md 'Stop Condition' section defines the emit rule. Fragilities: grep can false-positive if the model quotes its own instructions (the sentinel appears verbatim in the prompt text); there is no timeout on the agent subprocess, so a hung CLI stalls the loop indefinitely; there is no per-story failure counter, so one impossible story silently burns every remaining iteration with no escalation.", + "evidence_files": [ + "ralph.sh", + "CLAUDE.md", + "prompt.md" + ], + "zo_relevance": "ZO just spec'd a watchdog/heartbeat anti-stall design; Ralph's cap is the degenerate-but-robust version worth keeping as an outer bound regardless of smarter watchdogs: a max-iterations circuit breaker per phase. The sentinel idea maps to ZO gates, but ZO should use structured output or oracle-side predicates ('all plan items verified') rather than grepping model prose \u2014 Ralph shows both the pattern and its failure modes." + }, + { + "name": "Archive-on-branch-change run lifecycle", + "what_it_is": "ralph.sh detects when prd.json's branchName differs from the last run's (persisted in a .last-branch dotfile), archives the old prd.json + progress.txt to archive/YYYY-MM-DD-/, and resets progress.txt to a fresh header before starting the new feature.", + "why_special": "Small but thoughtful: it prevents cross-feature memory contamination (stale Codebase Patterns from feature A polluting feature B's iterations) while keeping an auditable history of every run. It's the only lifecycle management in the system and it's fully automatic. The ralph skill mirrors the same rule for manual prd.json updates.", + "how_it_works": "ralph.sh lines 42-73: jq-extract branchName, compare to .last-branch, mkdir archive/$DATE-$(branch minus ralph/ prefix), cp both files, rewrite progress.txt header, update .last-branch. skills/ralph/SKILL.md 'Archiving Previous Runs' duplicates the protocol for the manual path. .gitignore treats prd.json/progress.txt/.last-branch as ephemeral working files.", + "evidence_files": [ + "ralph.sh", + "skills/ralph/SKILL.md", + ".gitignore" + ], + "zo_relevance": "ZO's memory/{project}/sessions/ already scopes memory per project, but Ralph's reset-on-new-feature is a useful sub-project idea: ZO could archive-and-reset phase-scoped scratch state when a plan's branch/phase changes, keeping only PRIORS (which are meant to generalize) live across features. Also a reminder that ZO's continue-mode auto-detection could key off a persisted last-branch/last-phase marker file \u2014 trivially cheap and robust." + }, + { + "name": "Tool-agnostic dual-prompt design (Amp / Claude Code)", + "what_it_is": "The same loop drives either Amp or Claude Code via --tool flag; the ONLY difference is which prompt file is piped in (prompt.md vs CLAUDE.md) and the tool's own permission-bypass flag. The two prompt files are near-identical hand-maintained copies.", + "why_special": "Proves the technique is model/tool-independent \u2014 the harness contract is just 'text in, text out, grep for sentinel'. That is a strong architecture statement: no SDK, no API coupling, no session management. But the duplication is a real maintenance hazard: the two prompts have already drifted (browser testing is 'Required' for Amp vs 'If Available' for Claude; Amp logs thread URLs, Claude doesn't; AGENTS.md vs CLAUDE.md as the learnings target).", + "how_it_works": "ralph.sh lines 11-35 (arg parsing/validation), 91-96 (the two invocations). Note the Claude prompt file is named CLAUDE.md and piped via stdin \u2014 a pun on Claude Code's memory-file convention, but mechanically it is just the stdin prompt for `--print` mode, not auto-loaded project memory. .claude-plugin/{marketplace.json,plugin.json} additionally package the two skills as a Claude Code marketplace plugin.", + "evidence_files": [ + "ralph.sh", + "CLAUDE.md", + "prompt.md", + ".claude-plugin/marketplace.json", + ".claude-plugin/plugin.json", + "README.md" + ], + "zo_relevance": "Low-to-moderate. ZO is committed to Claude Code, so multi-tool is not a goal; the transferable lesson is negative \u2014 do not maintain duplicated prompt variants by hand (generate them from one source). The marketplace plugin packaging of skills is a distribution pattern ZO could copy for its own skills." + }, + { + "name": "Mandatory browser verification for UI stories", + "what_it_is": "Every UI-touching story must carry 'Verify in browser using dev-browser skill' as an acceptance criterion, injected at PRD time by both skills; the Amp prompt declares 'A frontend story is NOT complete until browser verification passes.'", + "why_special": "It bakes an empirical feedback loop into the plan artifact itself rather than relying on the agent to remember to test visually \u2014 the criterion travels with the story. This is the closest Ralph gets to an oracle for the class of work (UI) where typecheck/tests are weakest. PARTIALLY ASPIRATIONAL: the dev-browser skill is referenced in prompt.md, both SKILL.md files, and README, but is NOT shipped in this repo; the Claude Code variant downgrades it to 'if you have browser testing tools configured... If no browser tools are available, note that manual browser verification is needed' \u2014 i.e., on Claude Code the guarantee silently degrades to a self-reported TODO.", + "how_it_works": "skills/prd/SKILL.md (UI stories template includes the criterion), skills/ralph/SKILL.md ('For stories that change UI, also include...'), prompt.md 'Browser Testing (Required for Frontend Stories)' vs CLAUDE.md 'Browser Testing (If Available)'. prd.json.example shows it on US-002 through US-004.", + "evidence_files": [ + "skills/prd/SKILL.md", + "skills/ralph/SKILL.md", + "prompt.md", + "CLAUDE.md", + "prd.json.example" + ], + "zo_relevance": "The pattern \u2014 verification method named INSIDE each acceptance criterion at plan time \u2014 is directly adoptable into ZO's plan.md schema and oracle spec: every subtask criterion should name its check command/tool, so the oracle can execute it mechanically. ZO should implement the actual browser-check tooling rather than inherit Ralph's unshipped dependency." + } + ], + "architecture_notes": "Total system = 1 bash script (113 lines) + 2 near-duplicate prompt files + 2 planning skills + 1 example JSON + docs. No Python, no SDK, no API calls, no orchestrator process, no agent roles, no model routing, no parallelism \u2014 strictly serial, one story per fresh single-agent invocation. Control flow: bash for-loop \u2192 spawn CLI agent with static stdin prompt in full-permission-bypass mode (`--dangerously-skip-permissions` / `--dangerously-allow-all`) \u2192 tee output for live viewing while capturing \u2192 grep for `COMPLETE` \u2192 exit 0 / sleep 2 / iterate \u2192 exit 1 at cap. State machine lives entirely on disk: prd.json (which stories are done, which branch), progress.txt (append-only learnings + consolidated Codebase Patterns section read first each iteration), .last-branch (run identity for archiving), git history (code checkpoints; each green commit is the recovery point), and AGENTS.md/CLAUDE.md files in the target codebase (auto-loaded contextual knowledge). Idempotency/recovery is implicit: because every iteration re-derives state from files, a crashed iteration is simply retried by the next fresh instance; the worst case is redoing a story whose commit landed but whose passes flag didn't get flipped. Trust model: total trust in the agent \u2014 the harness performs no verification of any kind (never runs tests, never inspects diffs, never validates JSON); quality gates (typecheck/test/browser) exist only as prompt instructions, and passes:true is self-asserted. Completion is agent-declared via sentinel with the iteration cap as backstop. The flowchart/ subdir (React 19 + @xyflow/react + Vite, deployed to GitHub Pages via .github/workflows/deploy.yml) is a click-through presentation of the loop \u2014 real, working, but explanatory material only. Repo history is tiny (~20 commits): initial Amp-only version, Claude Code support bolted on by a contributor (hence the prompt-file duplication), then marketplace packaging. The one-line philosophy: make the runtime dumb and the plan smart; use fresh context as the drift guardrail, files as the memory, git as the checkpoint, and feedback loops (typecheck/tests/CI) as the only selection pressure.", + "weaknesses": [ + "No independent verification anywhere: the agent grades its own homework \u2014 it runs whatever checks it chooses, flips passes:true itself, and the harness only greps for a sentinel string. The entire 'quality checks must pass' guarantee is a prompt instruction, not an enforced gate. This is the antithesis of ZO's oracle-first principle.", + "Sentinel detection is fragile: `COMPLETE` appears verbatim in the prompt text, so a model that quotes or paraphrases its own stop condition in output would falsely terminate the loop; conversely detection depends on exact string reproduction.", + "No per-story failure tracking or escalation: a story that repeatedly fails burns all remaining iterations silently retrying; the prd.json `notes` field that could carry failure context is defined in the schema but never referenced by any prompt (vestigial).", + "No subprocess timeout or stall detection: a hung CLI invocation blocks the loop forever; the only watchdog is the human reading the tee'd output.", + "Runs with all permission systems disabled by design (--dangerously-skip-permissions / --dangerously-allow-all), with no sandboxing, no command allowlist, and no guard against the agent touching files outside the feature scope.", + "prompt.md and CLAUDE.md are hand-maintained near-duplicates that have already semantically diverged (browser testing Required vs If Available; thread-URL logging Amp-only; AGENTS.md vs CLAUDE.md learning targets) \u2014 a template-generation problem left unsolved.", + "The dev-browser skill that UI verification depends on is referenced throughout but not shipped in this repo; on Claude Code the browser gate degrades to a self-reported 'manual verification needed' note.", + "The task ledger (prd.json) and memory (progress.txt) are gitignored as ephemeral working files, so run state is not versioned or recoverable from git \u2014 an interrupted machine loses the ledger while the prompt simultaneously says 'commit ALL changes', a mild contradiction.", + "No cost/token accounting or budget control beyond the iteration cap; no metrics on iteration success rate.", + "Serial-only execution with a single generalist agent: no way to parallelize independent stories, no model tiering (every story pays the same model cost regardless of difficulty), no reviewer/second-opinion role.", + "The self-improvement loop is shallow relative to ZO's evolution protocol: learnings are appended prose with no root-cause classification, no rule-update mechanism, and no check that a learning would have prevented the original failure." + ], + "notable_files": [ + "ralph.sh", + "prompt.md", + "CLAUDE.md", + "AGENTS.md", + "skills/ralph/SKILL.md", + "skills/prd/SKILL.md", + "prd.json.example", + "README.md", + ".claude-plugin/marketplace.json", + ".gitignore" + ] + } + ], + "synthesis": { + "executive_summary": "The three repos triangulate ZO's exact weaknesses from three directions. oh-my-claudecode (OMC) is the reference implementation for everything ZO's watchdog RFC and 'enforcement > aspiration' prior are groping toward: a deterministic hook plane (Stop/SubagentStop/PreCompact/PreToolUse) that mechanically enforces what prompts merely promise \u2014 stop-gating with a battle-tested taxonomy of never-block escape hatches, machine-checked deliverable contracts, hook-automatic memory persistence, heartbeat liveness, rate-limit auto-resume, and two-way remote control of unattended runs. ruflo is 90% cautionary tale (a 13k-line coordination engine nothing imports; fabricated benchmarks its own audit exposed) but its remediation machinery is genuinely novel and maps perfectly onto ZO's self-evolution protocol: witness manifests that machine-verify every documented fix's load-bearing code still exists, behavioral smoke tests born from named regressions, and monotone quality ratchets. ralph is 113 lines of bash that solves context rot, state hallucination, and stall blast-radius structurally \u2014 fresh agent per context-window-sized story, all state on disk, git as checkpoint \u2014 the strongest available argument for what ZO's post-tmux execution substrate should look like. The synthesis: ZO's oracle discipline and honest empirical culture are already best-in-class among these four systems; what ZO lacks is a deterministic enforcement plane beneath its prompts, a machine-readable control-plane state beside its markdown, a mechanized regression loop for its own rules, and an execution substrate whose failure unit is one iteration rather than one 38-hour session. Every P0 below is implementable in ZO's existing hook layer without waiting for the SDK refactor \u2014 and several make that refactor smaller.", + "per_repo_verdicts": [ + { + "repo": "oh-my-claudecode", + "one_liner": "A 337K-line Claude Code plugin that turns prompt promises into hook-enforced guarantees \u2014 the most battle-tested agent-persistence and lifecycle machinery in the ecosystem, wrapped around unverified self-improvement claims.", + "what_makes_it_special": "The deterministic hook lattice: every one of its ~10 stop-blocking circuit breakers, deliverable checks, and memory-persistence hooks carries a GitHub issue number from a real production failure. It is a paid-for catalog of every way autonomous-loop enforcement goes wrong (context-limit deadlocks, rate-limit retry loops, recursive keyword spawning, forged approvals) and the working fix for each. Its operator layer (HUD statusline, two-way Discord/Telegram/Slack reply injection, rate-limit auto-resume daemon) is the best answer anywhere to 'what does the human see during a 12-hour unattended run'.", + "maturity": "High on the enforcement/runtime plane (thousands of users, issue-driven hardening, real tests); low on quality evidence (SWE-bench harness has empty results, the only committed run failed 5/5, agent benchmarks are zero-filled placeholders) and carries significant dead code presented as capability (model-routing engine, verification tier-selector, recovery hooks wired to nonexistent events)." + }, + { + "repo": "ruflo", + "one_liner": "A ~400K-line coordination LEDGER for Claude Code (not an executor) whose headline swarm/neural/Rust claims are largely theater, but whose self-verification machinery \u2014 built to dig itself out of documented fabrication \u2014 is uniquely valuable.", + "what_makes_it_special": "It built an oracle for itself: witness manifests binding 117 documented fixes to code markers with per-OS CI verification and bisectable temporal history; a commissioned internal audit that graded its own marketing (exposing Math.random()-fabricated speedups); ~55 behavioral smoke-test CI jobs each born from a named regression that passed unit tests; monotone-decreasing quality ratchets. Also the best distilled coordination doctrine in the set (worktree-per-writer, named agents spawned in one message, SendMessage over polling) \u2014 arrived at after abandoning its own 13k-line consensus engine.", + "maturity": "Bimodal. The verification stack, memory package (real HNSW, honest benchmarks, temporal-validity supersession), and ADR discipline are mature and running in CI. The swarm layer is prompt theater over JSON bookkeeping; consensus voters are one model role-playing; 'agents' from agent_execute are 1024-token toolless completions; in-repo Rust is self-declared stubs. Trust the audited parts, not the README." + }, + { + "repo": "ralph", + "one_liner": "113 lines of bash + two prompts that make statelessness the architecture: fresh agent per context-window-sized story, all state on disk, git as the checkpoint system \u2014 maximum insight-per-line of any repo reviewed.", + "what_makes_it_special": "The inversion: push all intelligence to plan time (story sizing 'The Number One Rule': every task must fit one context window, with verifiable acceptance criteria) and all state to files (prd.json passes flags, append-only progress.txt with a read-first consolidated-patterns section, per-directory AGENTS.md learnings), so the runtime can be trivially dumb. Fresh context per iteration structurally eliminates context rot, persisted hallucination, and compounding errors \u2014 and caps stall blast-radius at one iteration.", + "maturity": "Proof-of-pattern, not a platform. Zero independent verification (the agent flips its own passes flags; the harness greps for a sentinel string), no timeouts, no failure escalation, hand-duplicated prompts already diverged, and its browser-verification dependency isn't shipped. Adopt the technique, not the code." + } + ], + "top_features_to_adopt": [ + { + "feature": "Machine-checked deliverable contracts at SubagentStop (generic contract-enforcement layer)", + "source_repo": "oh-my-claudecode", + "why": "This is the systematic answer to ZO's #1 recurring failure mode ('aspirational contracts get ignored', PR-035) and its open question about replacing incident-driven hard gates with a generic mechanism. OMC's templates/deliverables.json declares per-stage required files, minimum sizes, required sections, and regex patterns; a SubagentStop hook verifies them mechanically. ZO already writes produced/consumed contracts into every spawn prompt \u2014 this makes them enforceable instead of aspirational, at agent granularity, before the phase-level oracle gate. Pair with OMC's workflow-drift-guard (regex 'completion claim + stub/TODO in diff' lie detector) as a zero-LLM-cost tier-0 check on every stop.", + "how_zo_would_adopt": "Extend ZO's spawn-contract schema so each agent contract emits a deliverables entry (files, required sections, patterns) into a per-project contracts.json at spawn time; add a SubagentStop hook (ZO currently uses only one PreToolUse hook) that validates artifacts against it and blocks/flags on violation; port the drift-guard regexes as a Stop-time check. One JSON schema + two hook scripts, in Python.", + "effort": "small", + "priority": "P0" + }, + { + "feature": "Watchdog built from proven parts: heartbeat-file liveness + stop-gating with the never-block escape-hatch taxonomy + rate-limit auto-resume", + "source_repo": "oh-my-claudecode (+ ruflo PID-probe orphan reaping)", + "why": "ZO's watchdog spec (297adac) is an RFC written after a real 38-hour silent stall; OMC has already paid for every design mistake ZO is about to make. The transferable core: (1) heartbeat files with freshness checks as the liveness primitive (fits ZO's file-based philosophy); (2) idle detection requiring BOTH ready-state AND no-active-task, with bounded nudge budgets before escalation; (3) the taxonomy of stops you must NEVER fight \u2014 context-limit (#213 deadlock), rate-limit (#777 retry loop), auth errors (#1308), user aborts; (4) thinking-only-streak detection from the transcript rather than wall-clock; (5) distinguishing 'stalled because stuck' (nudge/restart) from 'stalled because rate-limited' (daemon waits for reset and resumes \u2014 the single biggest killer of overnight runs); (6) ruflo's PID+start-time identity checks and TTL orphan reaping so the watchdog never acts on recycled PIDs or stale state.", + "how_zo_would_adopt": "Implement the RFC as: per-agent heartbeat JSON under the project state dir written on activity; a small external checker (cron or the LifecycleWrapper's poll loop, NOT a monitor agent \u2014 avoiding the single-point-of-failure ZO already identified) that compares freshness, applies the escape-hatch checks before any intervention, nudges with a bounded budget, and escalates to iteration restart. Add a rate-limit-wait mode that pauses rather than retries and resumes on reset. Multi-level caps everywhere: per-phase max iterations plus a global hard cap (OMC: 500).", + "effort": "medium", + "priority": "P0" + }, + { + "feature": "Hook-enforced memory protocol (PreCompact + SessionEnd + PostToolUseFailure)", + "source_repo": "oh-my-claudecode", + "why": "ZO's CLAUDE.md declares memory updates 'AUTOMATIC (NON-NEGOTIABLE)' but enforcement is prompt-protocol plus one commit hook \u2014 the model can forget, and mid-session compaction is a total blind spot (STATE.md checkpoints at session boundaries only). OMC's pattern is strictly stronger: hooks persist state unconditionally at lifecycle boundaries, so the model cannot forget because the model isn't asked. PostToolUseFailure additionally gives ZO's self-evolution protocol a guaranteed structured failure feed instead of depending on the model remembering to write priors.", + "how_zo_would_adopt": "Three hooks: PreCompact flushes current phase/decisions/blockers to STATE.md before compaction destroys them; SessionEnd verifies (or writes) the session summary and DECISION_LOG entries, closing deferred audit items #15/#16; PostToolUseFailure appends structured failure records (tool, input, error, retry count) to a session-scoped JSONL that the retrospective/priors pipeline distills. Directly mechanizes the 'AUTOMATIC protocol' that is currently prose.", + "effort": "small", + "priority": "P0" + }, + { + "feature": "Machine-readable per-subtask ledger with oracle-owned pass flags", + "source_repo": "ralph (+ oh-my-claudecode ralph-mode prd.json)", + "why": "ralph's prd.json proves that boolean passes flags per story make resume, progress, and completion mechanically decidable \u2014 'what is done' becomes a jq query, not prose interpretation of plan.md. OMC independently converged on the same schema (stories + acceptance criteria + passes + fix_loop {attempt, max_attempts, last_failure_reason} state). ZO's continue/build auto-detection, gate logic, and the watchdog's 'is there work remaining' predicate all get cheaper and more reliable on a decidable ledger. The one critical fix over both sources: only the oracle may flip passes:true \u2014 ralph's fatal flaw is builder self-assertion.", + "how_zo_would_adopt": "Generate a plan-ledger.json from plan.md at build start (subtask id, acceptance criteria, verification command, passes, attempts, last_failure); builders read it, only oracle-qa writes the passes field (enforced by the deliverable-contract hook); gates and the loop evaluator consume it. Extend specs/plan.md validation with ralph's sizing lint: every subtask must fit one context window and carry machine-verifiable criteria with the check command named inline (ralph's good/bad criterion examples are the lint spec).", + "effort": "medium", + "priority": "P0" + }, + { + "feature": "Witness manifests + golden-trace/fixture regression: mechanize self-evolution verification", + "source_repo": "ruflo (+ oh-my-claudecode benchmark harness pattern)", + "why": "ZO's protocol requires verifying 'the updated rule would have caught the original failure' \u2014 today that verification is manual, informal, and unenforced (an explicit ZO open question). ruflo's witness system is exactly this, mechanized: each documented fix binds to a file + hash + distinctive code-marker substring; CI verifies all markers still present per-OS, with append-only JSONL history that turns any regression into a two-commit bisect. OMC's agent-prompt benchmark shape (fixtures with planted flaws + ground-truth findings + baseline snapshots) covers the other half: when self-evolution edits an agent persona or rule, a fixture run proves the edit catches the original failure without degrading other behavior.", + "how_zo_would_adopt": "Add a marker field to PRIORS.md entries pointing at the load-bearing code/hook of each verified fix; a ~day-of-work Python reimplementation of ruflo's witness verify (skip the Ed25519 theater \u2014 its seed derives from public info anyway) runs in validate-docs.sh and CI. For prompt-level rules, keep the failure's transcript/fixture and re-run it against edited personas before promotion, starting with oracle-qa and code-reviewer only.", + "effort": "medium", + "priority": "P1" + }, + { + "feature": "Fresh-context-per-subtask execution loop as the substrate direction", + "source_repo": "ralph (+ oh-my-claudecode autopilot phase-state)", + "why": "ralph demonstrates that fresh process + all-state-on-disk structurally eliminates context rot, persisted hallucination, and compounding errors \u2014 and shrinks ZO's stall blast-radius from '38 silent hours' to 'one lost iteration'. ZO already does fresh context at phase transitions; pushing it to subtask granularity (spawn per plan-ledger item, re-derive state from ledger + STATE.md + git) makes the fragile long-lived tmux session less load-bearing and makes the eventual SDK refactor smaller: a stateless spawn-per-item loop is trivially portable to headless/SDK invocation, while a long interactive session is not.", + "how_zo_would_adopt": "For Phase 4 first (where the experiment loop already provides the per-iteration structure): experiment_loop.py spawns a fresh builder per iteration with a static prompt that re-reads exp lineage + ledger + a read-first consolidated-priors digest (ralph's Codebase Patterns tier), commits as checkpoint, oracle flips flags. Keep hard caps as the outer bound. Extend to other phases' subtask execution if Phase 4 validates it on prod-001.", + "effort": "large", + "priority": "P1" + }, + { + "feature": "Anti-forgery correlated approval tags for every LLM-judged gate", + "source_repo": "oh-my-claudecode", + "why": "OMC's ralph verifier requires approvals as an XML tag carrying a per-verification random request-id UUID, strips prompt-injected examples before matching, and correlates story-id \u2014 so an executing agent cannot forge gate passage by echoing text it saw in context. ZO's numeric oracle gates are immune, but its human-checkpoint gates, adversarial cross-review, and any reviewer-judged phase sign-off are exactly the surface this protects. Given ZO's documented history of a Sonnet lead silently ignoring contracts, assuming agents won't echo approval strings is naive.", + "how_zo_would_adopt": "gates:approve and the four-stage validation loop generate a nonce per verification request; approval is only valid as a structured tag containing that nonce plus the gate/subtask id, validated by the gate code after stripping any quoted/example spans. A few dozen lines in the gate logic.", + "effort": "small", + "priority": "P1" + }, + { + "feature": "Two-way gate notifications (Slack/Telegram) with reply injection and idle-cooldown", + "source_repo": "oh-my-claudecode", + "why": "ZO's human experience between gates is polling DECISION_LOG \u2014 an acknowledged gap and open question. OMC ships the complete pattern: outbound notifications on gate-pending/stall/session-end, and a reply-listener daemon that maps channel replies back to the session and injects them (per-user authorization, sanitization, pane verification, rate limits, idle pings with cooldown so a stall notifies once, not sixty times). For a solo operator running multi-hour autonomous ML phases, 'phone as remote gate approver' is the single biggest quality-of-life unlock.", + "how_zo_would_adopt": "Phase 1 (small): outbound-only \u2014 gate-pending, TARGET_HIT/PLATEAU/DEAD_END verdicts, and watchdog stall alerts to a Slack/Telegram webhook, with cooldowns. Phase 2 (medium): reply listener mapping 'approve'/'reject: reason' to gates:approve/reject injection via the existing tmux layer, copying OMC's authorization and sanitization posture wholesale. Revisits the v1 no-integrations constraint, but the evidence says notification is where that constraint costs the most.", + "effort": "medium", + "priority": "P1" + }, + { + "feature": "Structurally trustworthy verifiers: disallowedTools read-only oracle + evaluator JSON contract + sealed oracle files", + "source_repo": "oh-my-claudecode", + "why": "Three small formalizations that harden ZO's already-strong oracle: (1) frontmatter disallowedTools on oracle-qa/reviewers (OMC hard-blocks Write/Edit on advisory agents) \u2014 a verifier that cannot edit is mechanically more trustworthy than one instructed not to; (2) autoresearch's strict evaluator contract ({pass: bool, score?: number} JSON, with keep_policy distinguishing hill-climbing from pass/fail) formalizes what ZO's oracle emits and cleanly serves Phase 4's metric-improvement loops vs binary gates; (3) sealed-files enforcement \u2014 the improvement loop cannot modify its own evaluation code \u2014 is the anti-Goodhart rule ZO's repo separation covers across repos but not within the delivery repo, where an agent could still edit the eval script.", + "how_zo_would_adopt": "Add disallowedTools to oracle-qa and reviewer frontmatter with a PreToolUse check; specify oracle output as the strict JSON schema in specs/oracle.md and result.md; add oracle/eval paths to a per-project sealed list enforced by the same PreToolUse hook (mirror of zo_only_paths, pointing inward).", + "effort": "small", + "priority": "P1" + }, + { + "feature": "Ambient observability: ZO statusline HUD", + "source_repo": "oh-my-claudecode", + "why": "OMC's biggest day-to-day UX differentiator: the operator sees mode/iteration/agents-alive/context-% at a glance without asking the model. ZO's monitoring is pull-only (observe:watch, watch-training). A statusline showing {project alias, phase, pending gate, oracle status, experiment iteration, agents active, context %} gives ambient awareness during long runs for near-zero cost, and ZO's brand system gives it a visual language.", + "how_zo_would_adopt": "A zo hud command reading STATE.md + plan-ledger.json + experiment training_status.json + heartbeat files, registered as Claude Code's statusLine. Copy OMC's element-renderer + preset composition; start with four elements (phase, gate, agent count, context bar).", + "effort": "small", + "priority": "P2" + }, + { + "feature": "Platform CI doctrine: behavioral smoke tests per prior + monotone quality ratchets + registry==filesystem generation", + "source_repo": "ruflo (+ oh-my-claudecode budget tests)", + "why": "ruflo's documented post-mortem \u2014 three same-day regressions that all passed unit tests but broke every user on first install \u2014 produced the doctrine ZO's platform layer needs: every user-visible platform failure in PRIORS.md spawns a smoke script reproducing the symptom (fresh-clone setup.sh, hook stdin round-trips, CLI flag parsing), auto-enforced by a meta-runner. The ratchet pattern (freeze current debt as a baseline that may only decrease) applies to ZO's agent-definition/spawn-prompt quality. And both repos' count-drift failures (marketplace '28 agents' vs actual 19; ruflo's 267-vs-134 skills) prove ZO's hand-maintained cascade chain should be replaced by derive-from-filesystem generation plus an assertion test \u2014 making cascade steps impossible to forget rather than checked after the fact.", + "how_zo_would_adopt": "Add a smoke/ dir with per-prior reproduction scripts and a meta-runner in CI; a ratchet script asserting agent .md frontmatter/contract-section completeness with a committed baseline; generate the counts in README/setup.sh/specs from the filesystem in validate-docs.sh instead of hand-editing six files.", + "effort": "medium", + "priority": "P2" + }, + { + "feature": "PRIORS.md upgrades: supersession semantics, quality gate, read-first digest, context budget", + "source_repo": "ruflo + oh-my-claudecode + ralph", + "why": "Four cheap, convergent memory refinements: (1) ruflo's invalidate-never-overwrite temporal semantics \u2014 a refuted prior gets validUntil + supersededBy pointing at its replacement, preserving why rules changed (ZO's superseded-only rule, given real structure); (2) OMC skillify's three-question quality gate (not Googleable / project-specific / hard-won) prevents PRIORS.md degrading into trivia as it grows \u2014 ZO's 'add a prior after every failure' currently has no filter; (3) ralph's two-tier read-first pattern \u2014 inject a small curated digest, not the full log (ZO already caps at 8 injected priors; formalize the curation); (4) OMC's CI-enforced context budget (64KB total/2KB per skill) applied to ZO's ~25 skill descriptions, which tax every session.", + "how_zo_would_adopt": "Structured front-matter on prior entries (id, status, supersededBy, marker); the three-question gate written into the evolution protocol and EvolutionEngine; a generated PRIORS-digest section maintained at consolidation time; a byte-budget assertion on .claude/skills+commands frontmatter added to validate-docs.sh.", + "effort": "small", + "priority": "P2" + } + ], + "rearchitecture_themes": [ + "ENFORCEMENT PLANE BELOW THE PROMPT PLANE: The single loudest signal across all three repos. OMC's core pattern \u2014 markdown defines behavior, deterministic hooks on every lifecycle event (Stop, SubagentStop, PreCompact, PreToolUse, PostToolUseFailure) enforce it \u2014 is the systematic version of ZO's own hardest-won prior ('enforcement > aspiration'). ZO currently uses one hook; every recurring 'agents ignored the contract' incident has been patched with a bespoke hard gate. V2 should treat the Claude Code hook lattice as a first-class architectural layer: contracts compile to machine-checkable deliverable schemas, memory protocol runs in hooks not prompts, gates verify artifacts and nonce-correlated approvals deterministically. This converts ZO's remaining prompt-trust surface into checked invariants without any SDK dependency.", + "FRESH-CONTEXT, DISK-STATE EXECUTION SUBSTRATE: ralph proves the runtime can be nearly stateless if the plan is context-window-sized and all state lives in files + git; OMC's production scars prove long-lived stop-blocked sessions accrete circuit breakers forever. ZO's fragile tmux layer and 38-hour stall both stem from betting on one long-lived session. The structural direction: per-subtask/per-iteration fresh spawns that re-derive state from a machine-readable ledger, with git commits as checkpoints. This caps stall blast-radius at one iteration, makes the watchdog's job trivial (kill and respawn beats nudge and pray), and \u2014 because a stateless spawn loop ports cleanly to headless/SDK invocation \u2014 is the cheapest on-ramp to the deferred SDK refactor rather than a competitor to it.", + "DUAL-PLANE STATE: MACHINE CONTROL PLANE + HUMAN PROJECTION: ZO's markdown memory is its greatest asset for auditability and its most fragile interface for code (hand-edited STATE.md crashed the orchestrator; 'what is done' requires prose interpretation). OMC materializes typed session-scoped JSON state that hooks enforce against; ralph's passes flags make progress decidable; ruflo's write-here-read-there bugs (#1945) show the cost of fragmented roots. V2 direction: one machine-readable control plane per project (plan-ledger.json, gate state, heartbeats, contracts) under a single root, with STATE.md/DECISION_LOG.md retained as the human-readable projection \u2014 generated or validated from it, never the parse target for control decisions.", + "AN ORACLE FOR THE PLATFORM ITSELF: ZO applies oracle discipline to delivery work but its self-evolution loop is verified manually. ruflo \u2014 after documented fabrication \u2014 built the missing second oracle: witness markers binding every fix to code with CI verification, behavioral smoke tests per regression, golden-trace replay before rule promotion, monotone quality ratchets. OMC's fixture-based agent-prompt benchmarks complete the picture for prompt-level rules. V2 should close ZO's loop: every prior carries a marker or a reproduction fixture, and 'the updated rule would have caught the original failure' becomes a standing CI check instead of a one-time claim. This also directly answers ZO's open question on evolution-confidence scoring.", + "OPERATOR EXPERIENCE AS AN ARCHITECTURAL LAYER, NOT A ROADMAP ITEM: ZO's human sits between gates polling files. OMC demonstrates that for unattended autonomous systems, the observe/notify/control loop is load-bearing infrastructure: ambient HUD, two-way notifications with reply injection, idle pings with cooldowns, rate-limit auto-resume. The watchdog theme and this one are the same investment viewed from machine and human sides \u2014 the 38-hour stall was simultaneously a liveness failure and a notification failure. V2 should design them together: heartbeat state feeds both the automated checker and the operator surface.", + "NOTHING SHIPS UNWIRED: ruflo's 13k-line dead coordination engine and OMC's uncalled routing/verification engines show how orchestration frameworks accrete capability-shaped marketing debt that eventually forces an embarrassing audit. ZO's small honest surface is a competitive asset. Encode it as a platform prior with teeth: no spec, agent, or mechanism merges unless a workflow invokes it and a test or witness marker can observe it firing \u2014 and no self-improvement claim (cost, quality, autonomy) ships without a completed benchmark run in-repo, which ZO's cost-savings refutation shows it already knows how to do." + ], + "anti_patterns_to_avoid": [ + "Dead code presented as capability: OMC exports a complete model-routing engine, verification tier-selector, and recovery hooks with zero runtime callers; ruflo's flagship 13k-line swarm/consensus library is imported by nothing on the runtime path. Both inflate perceived capability and force expensive audits later. ZO rule: runtime-caller-or-it-doesn't-merge.", + "Unverified self-improvement claims: OMC's SWE-bench harness has empty result templates and a 5/5-failure smoke run as its only data; ruflo shipped '150x-12,500x faster' (measured: 1.48x-4.7x) and Flash Attention speedups literally generated by Math.random(). ZO's measured refutation of its own 70-80% cost claim is the antidote culture \u2014 never regress from it.", + "Hard-blocking Stop as the persistence foundation: OMC's 2,564-line stop hook with ~10 interacting circuit breakers is the fossil record of every way fighting the platform's lifecycle goes wrong (compaction deadlocks, 429 retry loops, auth loops). Blocking stops is a last-resort backstop with exhaustive escape hatches \u2014 fresh-spawn loops with hard caps are the foundation.", + "Keyword-triggered heavy orchestration: OMC permanently disabled its 'team' keyword after prompts containing the word caused infinite recursive worker spawning, and needed 1,114 lines of multilingual false-positive suppression for the rest. ZO team spawning stays explicit and imperative; no string that can appear in agent-to-agent prompts may ever trigger spawning.", + "Self-asserted completion: ralph's agent runs its own checks, flips its own passes flags, and the harness greps for a sentinel the prompt itself contains verbatim. Ledger mechanics yes; grading privilege stays with the oracle, and completion predicates are structured state, never greps over model prose.", + "Fragmented state roots: ruflo scattered coordination state across four-plus directories and shipped write-here-read-there bugs where 'the CLI reported success against the wrong file' (#1945). ZO's single memory root is correct \u2014 the plan-ledger/control-plane additions must live under it, and 'verify writes land where reads look' belongs in PRIORS as a failure class.", + "Surface-area maximalism: ruflo's ~450 MCP tools, 38 plugins, and 107 agent .md files required building discovery AI (capability-brain) just to navigate itself; OMC's 41 overlapping skills need paragraph-length disambiguation prose per pair. ZO's 21-agent, ~25-skill roster is a feature; growth should require retiring or merging, not just adding.", + "Hand-maintained duplication and count drift: OMC's marketplace advertises 28 agents (actual: 19); ruflo claims 267 skills (registered: 134) and its current release is named after an ADR that doesn't exist in the repo; ralph's two prompt files semantically diverged within ~20 commits. Every one of these had verification tooling that didn't cover the drifting surface. Generate from a single source and assert registry==filesystem; never maintain parallel copies by hand.", + "Security/verification theater: ruflo's 'cryptographically-signed' witness manifests derive the Ed25519 seed from sha256(public git commit + constant) \u2014 anyone can forge signatures; its BFT 'consensus' tallies votes from one model role-playing every voter. Adopt the substance (markers, history, vote bookkeeping with independence requirements), never the costume \u2014 a mislabeled guarantee is worse than none.", + "Prompt-persona theater describing protocols the runtime can't execute: ruflo's byzantine-coordinator/crdt-synchronizer agent files describe distributed algorithms that are actually one session writing JSON, and their embedded tool examples drifted from real tool names across versions. ZO agent definitions must describe only what the agent mechanically does, with contract references that validate against the live system.", + "Fail-open where the guarantee is the point: ralph runs with all permission systems disabled, no timeouts, no failure escalation \u2014 one impossible story silently burns every remaining iteration. ZO's hard gates and enforce_isolation are the right call; adopt fail-open only for advisory hooks (logging, nudges), never for gates, contracts, or confidentiality enforcement." + ] + } +} \ No newline at end of file diff --git a/memory/zo-platform/research/2026-08-12-repo-reviews/ruflo.md b/memory/zo-platform/research/2026-08-12-repo-reviews/ruflo.md new file mode 100644 index 0000000..03cc8f6 --- /dev/null +++ b/memory/zo-platform/research/2026-08-12-repo-reviews/ruflo.md @@ -0,0 +1,360 @@ +# ruflo — Deep Dive Findings (2026-08-12) + +## Lens: core-memory + +### Summary + +ruflo (v3.38.0, successor of claude-flow) is overwhelmingly a TypeScript monorepo (~400k non-test lines across 24 packages under v3/@claude-flow/, with the CLI alone at 360 files / 173k lines), not a Rust system. The in-repo "Rust core" is 1,246 lines across two crates that are stubs by their own admission: crates/ruflo-agntcy/Cargo.toml literally documents "The 'slim' feature currently compiles a STUB ONLY" (no upstream crate exists), and ruflo-federation-peer ships a trait surface whose real transport/safety deps are behind an off-by-default `native` feature. The actual Rust/WASM engine lives in external npm packages from ruvnet's other repos (agentdb@3.0.0-alpha.17, @ruvector/core, @ruvector/sona, ruvector, @ruvector/rvf-wasm), all consumed via dynamic imports wrapped in try/catch with pure-TS fallbacks — so what most users actually execute is the TypeScript fallback tier. + +The architectural truth of the system is stated bluntly in AGENTS.md: "claude-flow = LEDGER (tracks state, stores memory, coordinates); Codex = EXECUTOR". ruflo does not run agents — it is a memory/coordination sidecar for Claude Code/Codex, exposed via ~45 MCP tool modules and hooks. The memory package is the genuine core: a multi-backend IMemoryBackend abstraction (better-sqlite3, sql.js, agentdb, hybrid, RVF), a real multi-layer HNSW implemented in TypeScript, RRF+MMR hybrid retrieval, a memory consolidator, temporal-validity tiered memory, bidirectional sync with Claude Code's auto-memory markdown, and a cost-gated distillation service. Session continuity is comparatively mundane: JSON snapshots in .claude-flow/sessions/ plus a canonical .swarm/memory.db SQLite file, with a documented history of these paths drifting apart (bug #1945: CLI wrote to a different DB than the bridge read and "reported success against the wrong file"). + +The repo's design philosophy is best described as "grand claims, later confessed and remediated under ADR discipline". There are 175 ADR files (numbering to ADR-382), and the codebase is dense with unusually candid admissions of past vaporware: the memory README states earlier releases "silently downgraded" the hybrid backend and "ADR-009's promise wasn't delivered until now"; tiered-memory.ts documents that every hierarchical-store write used to be "a silent no-op that still reported success"; init.ts remediates a scaffold that copied repo bloat (including the root agentdb.rvf) into user projects. That root agentdb.rvf — the headline "agent database" — is a 162-byte empty header (magic SFVR from rvf-wasm), not a working database. Meanwhile the marketing surface still overstates: docstrings claim "150x-12,500x faster" vector search while the project's own CLAUDE.md admits "measured ~1.9x–4.7x vs brute force above crossover" and the committed benchmark baseline is 0.53ms/search at 1k×128-dim. + +### Key Features + +#### AutoMemoryBridge: DB <-> Claude Code auto-memory markdown sync + +- **What:** Bidirectional sync (ADR-048) between the vector memory backend and Claude Code's human-readable auto-memory files at ~/.claude/projects//memory/ — MEMORY.md as a line-budgeted index (default 180 lines, since Claude loads the first 200) plus category topic files. +- **Why special:** It treats the agent-visible markdown as a *projection* of a queryable database rather than the source of truth: insights are classified into categories (project-patterns, debugging, architecture, performance, security, preferences, swarm-results), formatted as one-line summaries, and pruned confidence-weighted to stay within the line budget. Also has an agent-scoped variant supporting Claude Code's project/local/user memory scopes with cross-agent knowledge transfer (min-confidence, max-entries, category filters). Fully implemented with tests, not aspirational. +- **How it works:** AutoMemoryBridge (EventEmitter, ~900 lines) hashes content, parses/emits markdown entries, classifies via classifyEntry(), prunes via pruneTopicFile(); sync modes on-write/on-session-end/periodic. AgentScopedMemoryBridge extends it per (agentName, scope). LearningBridge optionally forwards recorded insights into the neural trajectory system, no-op when unavailable. +- **ZO relevance:** Directly maps to ZO's STATE.md/PRIORS.md/MEMORY.md files. ZO keeps markdown canonical and has no index; ruflo shows the inverse pattern and, more usefully, the middle path: keep ZO's markdown canonical but auto-generate a line-budgeted, confidence-pruned index plus a searchable store, so priors accumulate without bloating the context window. The category taxonomy + one-line insight format is stealable as-is for PRIORS.md. +- **Evidence:** `v3/@claude-flow/memory/src/auto-memory-bridge.ts`, `v3/@claude-flow/memory/src/agent-memory-scope.ts`, `v3/@claude-flow/memory/src/learning-bridge.ts` + +#### TieredMemoryStore with temporal validity (invalidate, never overwrite) + +- **What:** Zep/Graphiti-style temporal knowledge semantics on the memory store: facts carry validFrom/validUntil; a conflicting fact `supersedes` an old one by stamping validUntil=now + supersededBy= and archiving it, keeping history queryable; recall() filters invalid entries by default with an includeExpired audit escape hatch. +- **Why special:** This is the most principled piece of memory design in the repo — contradiction handling with provenance instead of destructive updates. The docstring is also a landmark confession: agentdb dropped its HierarchicalMemory export at 3.0.0-alpha.17, so the previous in-memory stub made 'every such write a silent no-op that still reported success' — this module is the remediation, writing through to a tiered_memory SQLite table and exposing isDurable so callers can tell volatile from durable. +- **How it works:** TieredMemoryStore in v3/@claude-flow/memory/src/tiered-memory.ts (448 lines): store(key, value, tier, temporalOptions), recall(query, topK), getTierStats(); optional better-sqlite3 handle for durability, rehydrates on construction; deliberately avoids exposing getStats+promote together because that pair is the bridge's duck-type detection signal for the real agentdb API. +- **ZO relevance:** ZO's PRIORS.md and DECISION_LOG.md are append/edit markdown with no supersession semantics. Adopting invalidate-not-overwrite (a prior that proves wrong gets validUntil + supersededBy pointing at the new prior, never deleted) would give ZO's self-evolution protocol an audit trail and prevent silent loss of why rules changed — cheap to do even in markdown with structured front-matter. +- **Evidence:** `v3/@claude-flow/memory/src/tiered-memory.ts`, `v3/@claude-flow/cli/src/memory/memory-bridge.ts` + +#### Real multi-layer HNSW + RRF/MMR hybrid retrieval, honestly benchmarked + +- **What:** A genuine hierarchical HNSW index in pure TypeScript (random level assignment, top-down layer descent, binary min/max heaps, pre-normalized cosine), persistent across restart via sidecar snapshot files (.hnsw + .meta.json), plus SmartRetrieval implementing real Reciprocal Rank Fusion and Maximal Marginal Relevance rerank, and a MemoryConsolidator (sweepExpired/dedup/compactHnsw on a 6h timer). +- **Why special:** Verified implemented, not vendored: hnsw-index.ts has layers, getRandomLevel(), searchLayerOptimized — it is the real algorithm. And the committed benchmark is honest: baseline-20260519T212453Z.md records 0.53ms/search, 1889 ops/s at 1k×128-dim on Apple Silicon, while CLAUDE.md admits 'measured ~1.9x–4.7x vs brute force above crossover'. The catch: docstrings and CLI hints still parrot '150x-12,500x faster' — the marketing number and the measured number coexist in the same repo. +- **How it works:** v3/@claude-flow/memory/src/hnsw-index.ts (canonical, post-ADR-125); an intentionally-degraded HnswLite (greedy neighbor graph, not layered) is inlined privately in rvf-backend.ts for the fallback path; smart-retrieval.ts has reciprocalRankFusion() and mmrRerank() with mmr = lambda*score - (1-lambda)*maxOverlap; consolidator.ts + hnsw-persistence tests cover snapshot/restore. +- **ZO relevance:** ZO's memory/recall skill is grep-over-markdown; at ZO's scale (one team, dozens of priors) brute-force cosine or FTS is honestly sufficient — ruflo's own numbers prove HNSW only pays off above a crossover ZO will rarely hit. The adoptable part is graceful retrieval: FTS/keyword fallback when no embedder is available, and RRF fusion of keyword+semantic results, both small and self-contained. +- **Evidence:** `v3/@claude-flow/memory/src/hnsw-index.ts`, `v3/@claude-flow/memory/src/smart-retrieval.ts`, `v3/@claude-flow/memory/src/consolidator.ts`, `v3/@claude-flow/memory/benchmarks/results/baseline-20260519T212453Z.md` + +#### RVF 'binary agent database' — mostly a format costume in-repo + +- **What:** RVF (RuVector Format) is pitched (ADR-057) as a native binary storage backend replacing the 18MB sql.js dependency, with the repo-root agentdb.rvf as the flagship artifact. In-repo reality: RvfBackend's own persistence is a 4-byte magic + JSON header + length-prefixed JSON records; RvfEventLog is likewise 'RVFL' magic + uint32-length-prefixed JSON. The real binary format lives in external @ruvector packages. +- **Why special:** This is the flagship example of claim-vs-code divergence. The root agentdb.rvf is 162 bytes — an empty header (magic 'SFVR' from @ruvector/rvf-wasm), not a database of anything. RvfBackend tries dynamic import of '@ruvector/rvf', which is not even a declared dependency (only @ruvector/rvf-wasm is, as optional), so the code path virtually all users run is the pure-TS fallback: an in-memory Map + the degraded HnswLite + periodic JSON dumps. It works, but 'binary vector database' is JSON in a trenchcoat. Bonus irony: init.ts lists agentdb.rvf among 'bloat markers' after ADR-382 found the scaffold had been copying it into user projects. +- **How it works:** rvf-backend.ts: tryNativeInit() catch-all falls back to loadFromDisk/persistToDisk writing magic [0x52,0x56,0x46,0x00] + JSON.stringify per entry; shared/src/events/rvf-event-log.ts is the append-only event log variant (ADR-057 Phase 2) with snapshot .snap.rvf files; ADR-057 documents the aspiration. +- **ZO relevance:** Anti-pattern to learn from, not adopt: ZO's plain-markdown memory is more honest than a bespoke 'binary format' that is JSON underneath. The one legitimate takeaway is the append-only event log with length-prefixed records and snapshot files — a zero-dependency durable log ZO could use for comms JSONL hardening, though JSONL already gives ZO 90% of it. +- **Evidence:** `v3/@claude-flow/memory/src/rvf-backend.ts`, `v3/@claude-flow/shared/src/events/rvf-event-log.ts`, `v3/implementation/adrs/ADR-057-rvf-native-storage-backend.md`, `agentdb.rvf`, `v3/@claude-flow/cli/src/commands/init.ts` + +#### Session continuity: JSON snapshots + fragmented storage roots + +- **What:** session_save/session_restore/session_list MCP tools persist SessionRecord JSON ({sessionId, stats, data:{memory,tasks,agents}}) to .claude-flow/sessions/*.json, optionally encrypted at rest (ADR-096, magic-byte sniff for mixed plaintext/encrypted dirs); related stores are .claude-flow/{memory,tasks,agents}/store.json; the canonical vector DB is .swarm/memory.db; hive-mind keeps its own .hive-mind/sessions. +- **Why special:** Notable mostly as a cautionary tale: despite the AgentDB/HNSW narrative, cross-session continuity is plain JSON file snapshots — commodity. And the fragmentation across at least four storage roots produced real bugs the code documents: memory-bridge.ts #1945 — hooks configured data/memory/memory.db while bridgeStoreEntry() wrote .swarm/memory.db, so 'CLI store reported success against the wrong file'. The tool descriptions are well-written ('Use when native conversation memory is wrong because you need durable cross-session state'), and owner-only file perms + opt-in encryption show security attention. +- **How it works:** v3/@claude-flow/cli/src/mcp-tools/session-tools.ts: saveSession() via writeFileRestricted({encrypt:true}, honored only when CLAUDE_FLOW_ENCRYPT_AT_REST is set), loadRelatedStores() reads the three store.json files; session.ts CLI command delegates to these MCP tools; hive-mind.ts uses .hive-mind/sessions separately. +- **ZO relevance:** Validates ZO's single-root memory/{project}/ design — ruflo's multi-root drift bugs are exactly what ZO's layout prevents. Worth borrowing: the explicit 'reported success against the wrong file' failure class belongs in ZO's PRIORS.md as a category (verify writes land where reads look), and owner-only perms + opt-in encryption for session files containing agent prompts is a cheap hardening ZO lacks. +- **Evidence:** `v3/@claude-flow/cli/src/mcp-tools/session-tools.ts`, `v3/@claude-flow/cli/src/commands/session.ts`, `v3/@claude-flow/cli/src/memory/memory-bridge.ts`, `v3/@claude-flow/cli/src/services/memory-distillation.ts` + +#### Learning stack: ReasoningBank, SONA, memory distillation with cost-gated judges + +- **What:** A layered learning-from-experience system: ReasoningBank (hooks package) stores guidance patterns as 384-dim ONNX MiniLM vectors with quality/usage/success counts, short-term to long-term promotion, and historical-performance-based agent routing; PersistentSonaCoordinator keeps a pattern bank + trajectory buffer + EWC records persisted via RvfLearningStore; `memory distill` (ADR-174) dedups/clusters memory via greedy cosine clustering with a $0 'structural' judge, the LLM judge explicitly gated behind a budget flag and not enabled. +- **Why special:** The distillation service is the most honest component in the repo: provenance types are literally 'oracle:test-exec' | 'judge:fable' | 'proxy:structural', a code comment warns against 'laundering' structural summaries as genuine self-critique, and judge:fable hard-fails without a budget (ADR-172 cost gate). The SONA layer is more costume than claim: PersistentSonaCoordinator is 'intentionally decoupled from the ruvector SONA classes' — i.e., the persistent 'neural' learning is a brute-force cosine pattern bank with confidence decay (0.005/hr) and access boosts (0.03), while real @ruvector/sona is only statically imported in the neural package (external Rust/WASM, unverifiable in-repo). EWC 'tracking' is a stored lambda + records, not a training loop. +- **How it works:** hooks/src/reasoningbank/index.ts (dynamic imports of AgentDBAdapter/HNSWIndex/EmbeddingServiceImpl, degrades to no-op); memory/src/persistent-sona.ts + rvf-learning-store.ts; cli/src/services/memory-distillation.ts (runDistillation over .swarm/memory.db, greedy cosine clusters, embedding-coverage invariant before writes); neural/src/sona-integration.ts wraps @ruvector/sona. +- **ZO relevance:** The distillation design is the piece ZO should copy: periodic consolidation of PRIORS/session summaries with explicit provenance tiers (test-verified > LLM-judged > structural) and a hard cost gate on LLM judging fits ZO's oracle-first philosophy perfectly. ReasoningBank's agent routing by historical success-rate per domain is a concrete upgrade path for ZO's model-tier routing. Skip the SONA/neural branding entirely — the working substance is cosine similarity over past patterns with confidence decay, which ZO can do in 200 lines. +- **Evidence:** `v3/@claude-flow/hooks/src/reasoningbank/index.ts`, `v3/@claude-flow/memory/src/persistent-sona.ts`, `v3/@claude-flow/cli/src/services/memory-distillation.ts`, `v3/@claude-flow/neural/src/sona-integration.ts` + +#### Guidance governance: signed rule-evolution pipeline + memory write gates + +- **What:** The guidance package (~22.6k lines) implements governance over the agent system's own rules: evolution.ts turns every change to prompts/policies/tools into a signed ChangeProposal that goes propose -> simulate (replay golden traces baseline-vs-candidate) -> compare (divergence threshold) -> staged rollout (canary -> partial -> full) -> promote/rollback; memory-gate.ts adds per-agent authority scopes (queen/coordinator/worker/observer roles, allowed namespaces, writes-per-minute limits, delete rights) plus TTL/decay and contradiction tracking on memory writes. +- **Why special:** This is a mechanized, verifiable version of 'self-evolving rules' — rule changes must survive replay against golden traces before promotion, with HMAC/hash signing throughout. Caveat on realness: the pipeline machinery (types, hashing, staging logic, gates) is implemented and tested in-package, but end-to-end wiring into live agent traffic is hard to trace and largely depends on callers adopting it; treat it as a well-built library more than a proven production loop. Related: the separate verification/ system IS provably wired — Ed25519-signed witness manifests per documented fix, per-OS, with history.jsonl for bisecting regressions, and a CI job that blocks publish when a fix's load-bearing marker disappears. +- **How it works:** guidance/src/evolution.ts (ChangeProposalKind: rule-modify/add/remove/promote, policy-update, tool-config, budget-adjust; ProposalStatus lifecycle), memory-gate.ts (MemoryAuthority interface), gates.ts, truth-anchors.ts, ledger.ts; verification/README.md + witness-fixes.json + per-OS manifest.md.json describe the three-layer regression protection (smoke tests, witness manifest, temporal history). +- **ZO relevance:** ZO's self-evolution protocol ends with 'Verify the updated rule would have caught the original failure' — done manually by Claude. ruflo shows how to mechanize exactly that step: keep failure transcripts as golden traces, replay candidate rule changes against them, and only promote on non-divergence. The witness pattern is also directly adoptable for ZO's oracle: attest each fixed failure's load-bearing code with a hash+marker check so regressions of past PRIORS entries are caught automatically. Memory write-gating by agent role matters once ZO agents write memory concurrently. +- **Evidence:** `v3/@claude-flow/guidance/src/evolution.ts`, `v3/@claude-flow/guidance/src/memory-gate.ts`, `verification/README.md`, `verification/witness-fixes.json` + +#### In-repo Rust crates: honest stubs, external Rust engine + +- **What:** crates/ contains exactly two crates totaling 1,246 lines: ruflo-agntcy (CASA authorization envelope + SLIM transport surface, ADR-380) and ruflo-federation-peer (QUIC federation peer trait surface, ADR-120). The 'supercharged Rust-based AI engine' from the README is entirely external npm dependencies: agentdb, @ruvector/core, @ruvector/sona, @ruvector/router, ruvector, @ruvector/rvf-wasm. +- **Why special:** The Cargo.tomls are startlingly honest — ruflo-agntcy: 'The slim feature currently compiles a STUB ONLY... every plausible package name 404s; verified during ADR-380 scaffolding, not assumed', with methods returning Err(TransportError::Unavailable) 'rather than doing anything fake'; federation-peer keeps its real deps behind an off-by-default `native` feature so cargo check passes without them. So the repo's Rust story is: real Rust exists in ruvnet's *other* repos and arrives as npm binaries/WASM; this repo's crates are forward-scaffolding with explicit non-fake error surfaces. Every consumer of the external Rust wraps it in dynamic import + pure-TS fallback, meaning the fallback IS the product for most installs. +- **How it works:** crates/ruflo-agntcy/{Cargo.toml,src/envelope.rs,src/transport.rs}; crates/ruflo-federation-peer/src/lib.rs (623 lines, trait surface + 3-gate safety pipeline types); v3/crates is a copy of the same two crates; package.json declares the @ruvector/agentdb npm deps; agentdb-backend.ts/rvf-backend.ts/vector-db.ts all do await import(...) in try/catch with FallbackVectorDB/HnswLite/Map fallbacks. +- **ZO relevance:** Mostly a claims-calibration datapoint: when synthesizing 'ruflo has a Rust core', the correct statement is 'ruflo consumes ruvnet's external Rust/WASM packages behind optional imports; in-repo Rust is stub scaffolding'. For ZO the lesson is negative — ZO's pure-Python stack avoids the two-ecosystem drift that broke ruflo repeatedly (agentdb dropping exports out from under the TS layer). If ZO ever needs performance-critical components, vendoring or pinning with API-contract tests is mandatory; ruflo's tiered-memory incident shows what happens otherwise. +- **Evidence:** `crates/ruflo-agntcy/Cargo.toml`, `crates/ruflo-federation-peer/src/lib.rs`, `v3/@claude-flow/cli/src/ruvector/vector-db.ts`, `v3/@claude-flow/memory/src/agentdb-backend.ts`, `package.json` + +### Architecture Notes + +Execution model: ruflo is a coordination/memory LEDGER, not an executor — AGENTS.md states this explicitly ("claude-flow = LEDGER... Codex = EXECUTOR... If you need something BUILT/EXECUTED, YOU do it, not claude-flow"). All agent work happens inside Claude Code/Codex; ruflo surfaces ~45 MCP tool modules (v3/@claude-flow/cli/src/mcp-tools/) plus hooks (SessionStart worker autostart in hooks/src/workers/session-hook.ts) that read/write shared state. The swarm/queen/consensus/topology code in v3/@claude-flow/swarm coordinates records and messages, not OS processes. This is the same fundamental shape as ZO (Claude Code does the work; the platform provides memory + protocol), but ruflo pushes coordination into MCP tools while ZO pushes it into prompts/specs. + +Layering: v3/@claude-flow/* is a 24-package pnpm monorepo — shared (events, orchestrator, 23.5k lines), memory (19.2k), guidance (22.6k), hooks (10.7k), swarm (17.3k), neural (14.2k), cli (173k — the kitchen sink). The memory package is cleanly layered: IMemoryBackend interface -> {sqlite, sqljs, agentdb, hybrid, rvf} backends -> MemoryService facade -> bridges (AutoMemoryBridge, LearningBridge, MemoryGraph with PageRank/label-propagation community detection) -> ControllerRegistry wrapping agentdb's named controllers (reasoningBank, skills, reflexion, causalGraph, nightlyLearner, mutationGuard...). Everything optional is dynamically imported with graceful degradation; a "6-level backend resolution" display was added so users can tell which tier actually resolved — an admission that silent degradation was a real problem. + +Storage topology (fragmented): .claude-flow/sessions/*.json (session snapshots, opt-in encryption), .claude-flow/{memory,tasks,agents}/store.json, .swarm/memory.db (canonical better-sqlite3 vector/memory DB, defaultMemoryDbPath), .hive-mind/sessions, data/memory (historical), ~/.claude/projects/*/memory/*.md (Claude auto-memory, bridged). Multiple documented drift bugs between these roots (#1945). + +Process discipline is the real differentiator: 175 ADR files in v3/docs/adr (numbering reaches ADR-382), plus implementation ADRs; a cryptographic witness verification system (verification/: Ed25519-signed per-fix marker attestation, per-OS manifests, temporal history.jsonl, CI publish blocking); committed benchmark baselines; and a pervasive culture of in-code confession where past silent failures are documented in docstrings at the fix site. The codebase reads like an archaeological record of overclaiming followed by rigorous remediation — the current code is substantially more trustworthy than the project's marketing, and the ADR/witness machinery appears to be how they dug out. + +### Weaknesses + +- The 'Rust core' is not in this repo: crates/ is 1,246 lines of self-declared stubs (ruflo-agntcy Cargo.toml: 'compiles a STUB ONLY'); the real Rust arrives as external npm packages (agentdb, @ruvector/*) that have broken the TS layer before (agentdb dropped HierarchicalMemory at 3.0.0-alpha.17, silently no-op'ing every hierarchical-store write while reporting success — documented in tiered-memory.ts). +- The flagship agentdb.rvf at repo root is a 162-byte empty header, and the in-repo RVF 'binary format' is length-prefixed JSON with a 4-byte magic; the native @ruvector/rvf module RvfBackend tries to load is not even a declared dependency, so users run the pure-TS fallback (in-memory Map + degraded greedy-graph 'HnswLite', not real HNSW). +- Performance claims are internally inconsistent: '150x-12,500x faster' persists in ~10 docstrings and CLI hints while the project's own CLAUDE.md says 'measured ~1.9x–4.7x vs brute force above crossover' and the committed baseline is 0.53ms/search at just 1k vectors. +- Storage fragmentation across at least four roots (.claude-flow/, .swarm/, .hive-mind/, data/) with a documented history of write-here-read-there bugs (#1945 'reported success against the wrong file'); session continuity is plain JSON snapshots despite the vector-DB narrative. +- Pervasive graceful-degradation means the advertised capability tier and the executed capability tier routinely differ (HNSW->greedy graph, agentdb->Map, neural->no-op, encryption only with env flag); the 6-level resolution display exists precisely because users couldn't tell. +- Enormous surface area — 360 CLI source files, federation with WireGuard mesh, IoT plugin, browser automation, appliance/RVFA signing, business-pod tools, GAIA bench — breadth that historically outran verification (three regressions on one day, 2026-05-08, all passing unit tests, motivated the witness system). +- The 'self-learning neural' stack's persistent substance is a brute-force cosine pattern bank with confidence decay; SONA/EWC branding substantially oversells it, and the guidance evolution pipeline, while well-built, is hard to confirm as wired into live agent traffic end-to-end. +- Marketing artifacts inside the repo (22.2M+ 'ecosystem downloads' badge backed by self-generated clone-data 'proof' ledgers in data/) blur the line between engineering and promotion. + +### Notable Files + +- `v3/@claude-flow/memory/src/auto-memory-bridge.ts` +- `v3/@claude-flow/memory/src/tiered-memory.ts` +- `v3/@claude-flow/memory/src/hnsw-index.ts` +- `v3/@claude-flow/memory/src/rvf-backend.ts` +- `v3/@claude-flow/memory/src/smart-retrieval.ts` +- `v3/@claude-flow/memory/src/agentdb-backend.ts` +- `v3/@claude-flow/memory/src/controller-registry.ts` +- `v3/@claude-flow/memory/src/persistent-sona.ts` +- `v3/@claude-flow/memory/src/agent-memory-scope.ts` +- `v3/@claude-flow/memory/README.md` +- `v3/@claude-flow/memory/benchmarks/results/baseline-20260519T212453Z.md` +- `v3/@claude-flow/shared/src/events/rvf-event-log.ts` +- `v3/@claude-flow/cli/src/mcp-tools/session-tools.ts` +- `v3/@claude-flow/cli/src/services/memory-distillation.ts` +- `v3/@claude-flow/cli/src/memory/memory-bridge.ts` +- `v3/@claude-flow/guidance/src/evolution.ts` +- `v3/@claude-flow/guidance/src/memory-gate.ts` +- `v3/@claude-flow/hooks/src/reasoningbank/index.ts` +- `v3/@claude-flow/neural/src/sona-integration.ts` +- `crates/ruflo-agntcy/Cargo.toml` +- `crates/ruflo-federation-peer/src/lib.rs` +- `v3/implementation/adrs/ADR-057-rvf-native-storage-backend.md` +- `verification/README.md` +- `AGENTS.md` +- `CLAUDE.md` + +## Lens: swarm + +### Summary + +Ruflo is the renamed claude-flow v3 by ruvnet (package.json still says "claude-flow", v3.38.0) — a ~122MB monorepo positioned as an "agent meta-harness for Claude Code and Codex": npm workspaces under v3/@claude-flow/*, 35 Claude Code plugins, 107 agent .md definitions, ~450 registered MCP tools, and 482 test files. Through the swarm lens, the single most important finding is that the "swarm" is a coordination LEDGER, not an execution engine. There are three distinct layers that must not be conflated: (1) a prompt layer — agent .md subagent definitions (queen-coordinator, byzantine-coordinator, mesh/hierarchical coordinators) and slash commands that instruct Claude to role-play coordination protocols; (2) a bookkeeping layer — MCP tools (swarm_init, agent_spawn, hive-mind_*, task_*) whose handlers write JSON state files under .claude-flow/ (swarm-state.json, agents/store.json) with real engineering (file locks, PID-liveness orphan reaping) but which spawn no processes and call no LLMs; and (3) an execution layer that is fully delegated — agent_spawn's own response text spells it out: "(1) agent_execute — direct LLM call via Anthropic Messages API; (2) Claude Code Task tool — spawns a real subagent; (3) claude -p — headless background instance." + +The paradox at the heart of the repo: a genuinely substantial 13k-line @claude-flow/swarm TypeScript library exists — QueenCoordinator (2,025 lines), UnifiedCoordinator (1,844), TopologyManager, Raft/Byzantine/Gossip consensus with a pluggable Ed25519-signed transport, task orchestrator with dependency resolution — and it is well-tested (10 test files including consensus failure-injection), but NOTHING in the CLI/MCP runtime imports it (verified by grep: only capability-brain.ts references the package, as metadata). The MCP handlers reimplement lightweight file-based versions instead. The transport module's own docstring admits the history: consensus messages "never actually crossed a process or node boundary: a node 'sent' a message by emit'ting it locally and synthesizing the peer's reply inline." + +What redeems the repo — and is genuinely unusual — is a systematic, self-documented honesty retrofit. Issue-referenced comments throughout the code record where earlier versions lied ("#1845: 'queued' was a lie"; "ADR-093 F2: stop returning status:'completed' for a worker that never ran") and replace fake success with honest status enums ('no-daemon', 'queued', 'synthetic-completed'). A commissioned internal audit (docs/reviews/intelligence-system-audit-2026-05-29.md) empirically graded the platform's claims: the self-learning loop, Q-learning routing, and int8/RaBitQ quantization are real and measured; "Flash Attention 2.49–7.47x" was literally fabricated with Math.random() at runtime; "HNSW 150x–12,500x" measured 1.48x peak. A verification/ directory maintains cryptographic "witness manifests" (sha256 + source-marker checks per documented fix, per-OS performance JSONL baselines) so documented capabilities can be re-verified against the code. The converged practical doctrine — visible in the init-scaffolded CLAUDE.md — is candid: "Ruflo is the coordination ledger and policy decision point. Claude Code is the executor," with multi-agent work done via native Task-tool agents that are named, spawned in one message with run_in_background, coordinate via SendMessage, and each get an isolated worktree with single-writer file ownership. + +### Key Features + +#### File-based swarm coordination ledger (swarm_init / agent_spawn / task_* MCP tools) + +- **What:** MCP tools that persist swarm topology, agent registry, and task assignments as JSON state under .claude-flow/ (swarm-state.json, agents/store.json, task store), with topology validation (hierarchical/mesh/ring/star/hybrid/adaptive/pheromone-adaptive), file locks, and PID-liveness orphan reconciliation (#1799: dead-host swarms auto-marked 'terminated'). +- **Why special:** It is honest infrastructure for the thing that actually matters in Claude-Code-native swarms: durable shared state that any number of sessions/subagents can read and write. No process supervision pretense — agent_spawn's own response note admits execution happens elsewhere (agent_execute API call, native Task tool, or claude -p). The engineering around staleness (PID probes, 24h TTL reaping, atomic lock files) is real and battle-hardened by thousands of issues. +- **How it works:** swarm_init writes a SwarmState record (topology, maxAgents, strategy, consensusMechanism) to .claude-flow/swarm/swarm-state.json; agent_spawn writes an AgentRecord (with routed model, provider, optional copy-on-write memory branch) to .claude-flow/agents/store.json and cross-registers into the swarm's agents array (#2085); task_create/task_assign maintain a task store and flip agent status idle<->active. loadSwarmStore() runs reconcileOrphanSwarms() using process.kill(pid, 0) liveness probes. +- **ZO relevance:** ZO's STATE.md is prose-memory; ruflo shows the value of a parallel MACHINE-readable coordination store (JSON with schema, liveness fields, orphan reaping). ZO's new watchdog/heartbeat spec (commit 297adac) should steal the PID-probe + TTL reconciliation pattern and the principle that every async status must be provably derived (queue file on disk, PID checked) rather than asserted. +- **Evidence:** `v3/@claude-flow/cli/src/mcp-tools/swarm-tools.ts`, `v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts`, `v3/@claude-flow/cli/src/mcp-tools/task-tools.ts`, `v3/@claude-flow/cli/src/mcp-tools/agent-execute-core.ts` + +#### Consensus-as-a-ledger (hive-mind_consensus with Raft/BFT/quorum semantics) + +- **What:** A real vote-tallying state machine over the JSON hive state: propose/vote/status actions with three strategies — raft (one pending proposal per term, one vote per node per term, timeout re-proposal), bft (double-vote and cross-proposal conflict detection that excludes Byzantine voters), quorum (unanimous/majority/supermajority presets). +- **Why special:** This is the correct adaptation of consensus to LLM swarms: not distributed-systems consensus (there is no network partition to survive) but a structured, auditable DECISION PROTOCOL with anti-gaming rules (double-vote detection, term discipline) that multiple subagents can participate in through MCP calls. The catch — and it's fundamental — is voter independence: in the common single-session flow, one Claude role-plays every voter, making 'byzantine fault tolerance' theater. It only becomes meaningful when separate Task-tool subagents or headless instances each cast their own votes. +- **How it works:** hive-mind_init writes topology + consensusStrategy + queen record to hive state JSON; hive-mind_spawn appends worker records (pure metadata — status 'idle', no process); hive-mind_consensus 'propose' creates a proposal with required-vote thresholds computed from live worker count, 'vote' records per-voterId votes, detects conflicting votes (BFT: voter excluded and listed in byzantineVoters; raft: vote change rejected), and resolves via tryResolveProposal into a persisted history. Meanwhile the 1,674-line 'real' Raft/PBFT/Gossip library in @claude-flow/swarm/src/consensus/ (with Ed25519-signed transport) is dead code from the runtime's perspective. +- **ZO relevance:** ZO's oracle is a single verifier; ruflo's ledger suggests a cheap complement: structured gate votes where reviewer/tester/security agents each file an explicit vote with recorded rationale into a file-based proposal, giving DECISION_LOG.md a machine-checkable substrate. Adopt the anti-gaming bookkeeping (one vote per agent per gate, conflict detection); reject the framing that this is fault tolerance — votes from agents sharing one context window are correlated, so ZO should require voters to be separately-spawned contexts. +- **Evidence:** `v3/@claude-flow/cli/src/mcp-tools/hive-mind-tools.ts`, `v3/@claude-flow/swarm/src/consensus/raft.ts`, `v3/@claude-flow/swarm/src/consensus/byzantine.ts`, `v3/@claude-flow/swarm/src/consensus/transport.ts` + +#### Hive-mind Queen launcher (hive-mind spawn --claude) + +- **What:** CLI path that generates a large 'HIVE MIND COLLECTIVE INTELLIGENCE SYSTEM' prompt (queen persona, worker roster, consensus algorithm, per-tool coordination protocol) and launches a single `claude` process with it — interactive or headless (-p --output-format stream-json), with --mcp-config wired so the spawned session actually has the mcp__ruflo__* tools (#1748). +- **Why special:** This is the concrete answer to 'what is the runtime path of a swarm': ONE Claude Code session is the queen; 'workers' are JSON records the queen manipulates through MCP tools; the prompt explicitly forbids native Task/Agent tools for coordination (#1422) to keep all orchestration flowing through ruflo's ledger. It is prompt-level orchestration wearing an exoskeleton of real state tools — functional, but a single point of cognition, not a parallel swarm. Notably, the newer plugin skill (ruflo-swarm swarm-init) reverses doctrine: it tells Claude to use native Task with name:/run_in_background plus SendMessage after swarm_init — evidence the project itself concluded native subagents are the better execution substrate. +- **How it works:** generateHiveMindPrompt() assembles the queen persona + tool catalog + 4-phase execution protocol; spawnClaudeCodeInstance() resolves an MCP config (./.mcp.json → ~/.claude.json), builds claude args (--mcp-config=path, optional -p/--output-format stream-json, optional --dangerously-skip-permissions), and childSpawn's the claude binary with the prompt as final arg. Worker records were previously created by hive-mind_spawn MCP calls. +- **ZO relevance:** ZO's lead-orchestrator already is this pattern (one orchestrating session spawning native subagents), so nothing to copy in mechanism — but the #1748/#1780 bug archaeology (spawned workers silently lacking MCP tools; variadic --mcp-config slurping the prompt as a filename past PATH_MAX) is a checklist of failure modes ZO will hit if it ever launches headless claude workers. The doctrine reversal (their own newest skill returns to native Task + SendMessage) is strong evidence for ZO's Claude-Code-native architecture choice. +- **Evidence:** `v3/@claude-flow/cli/src/commands/hive-mind.ts`, `plugins/ruflo-swarm/skills/swarm-init/SKILL.md`, `.claude/agents/hive-mind/queen-coordinator.md`, `.claude/agents/swarm/hierarchical-coordinator.md` + +#### Background worker daemon with real headless Claude execution + +- **What:** A persistent daemon (daemon.ts, 1,813 lines) that polls a durable on-disk queue (.claude-flow/daemon-queue/*.json, written by the hooks_worker-dispatch MCP tool) every 5s and executes 12 worker types — 8 'headless' ones (audit, optimize, testgaps, document, ultralearn, refactor, deepdive, predict) by actually spawning `claude --print --output-format json` subprocesses, and 4 local ones (map, consolidate, benchmark, preload) that run without AI. +- **Why special:** This is the one place in the repo where autonomous multi-process agent execution demonstrably happens: a bounded process pool, per-job dedup registry (ai-job-dedup), a global AI budget with quota-error detection, sandbox env profiles, structured-output parsing, and Windows CVE-aware spawning. Equally notable is the honesty scaffolding around it: dispatch returns 'no-daemon' when no daemon runs ('no actual work will run'), 'queued' only after the queue file provably hits disk, and 'synthetic-completed' when sync mode has no runner — each state a repaired lie documented by issue number. +- **How it works:** hooks_worker-dispatch checks .claude-flow/daemon.pid liveness via process.kill(pid,0), writes {workerId, trigger, context, priority} to daemon-queue/, and reports an honest status enum. The daemon (fork'ed Node child, lock-file dedup against double-starts) consumes the queue; headless-worker-executor.ts builds context from file globs, renders a prompt template, spawns claude --print with prompt on stdin (#1852), parses JSON output including usage, and enforces timeouts/budget/dedup. +- **ZO relevance:** Directly relevant to ZO's anti-stall watchdog spec and any future 'ZO runs maintenance while Sam sleeps' ambition: the durable queue file + PID-checked daemon + honest status enum is the correct minimal architecture, and the global AI budget + job dedup are must-haves ZO lacks. Note the workers are single-shot claude --print calls (analysis/documentation flavored), not long agentic loops — a scope ZO should also start with. +- **Evidence:** `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts`, `v3/@claude-flow/cli/src/services/headless-worker-executor.ts`, `v3/@claude-flow/cli/src/commands/daemon.ts`, `v3/@claude-flow/cli/src/services/bounded-worker-pool.ts`, `v3/@claude-flow/cli/src/services/global-ai-budget.ts` + +#### Scaffolded coordination doctrine: SendMessage-first named agents, worktree-per-writer + +- **What:** The `ruflo init` CLAUDE.md generator emits a compact coordination doctrine for user projects: spawn ALL named agents in ONE message via the native Agent/Task tool with run_in_background:true, embed who-messages-whom in every prompt (pipeline/fan-out/supervisor patterns), coordinate via SendMessage not polling, give every writing agent an isolated worktree with non-overlapping file ownership, single integration owner for shared manifests/lockfiles, and children may only drop — never add — capabilities. +- **Why special:** This is the distilled, non-theatrical core of three years of claude-flow iteration: after building 450 MCP tools and a dead 13k-line coordination engine, the doctrine that survives is prompt-level contracts over Claude Code's native primitives. The 'Ruflo is the coordination ledger and policy decision point; Claude Code is the executor' framing is the project's most honest architectural statement, and the concurrency/authority rules (no two writers per worktree, lease≠authorization, self-improving systems cannot self-promote) read like hard-won incident postmortems. +- **How it works:** claudemd-generator.ts composes template sections (baseRules, agentComms, swarmConfig, routing table mapping task types to agent sets and topologies, 'When to Swarm' heuristics: 3+ files yes, single-file no) into the CLAUDE.md written by init; hooks in scaffolded settings.json route every UserPromptSubmit through hook-handler.cjs → a keyword-regex agent router (router.cjs) with learned-pattern pretensions but an 8-entry regex table in practice. +- **ZO relevance:** Highest-value direct adoption for ZO: ZO's contract-first spawning defines interfaces but the ruflo rules add the missing operational half — named addressable agents, comms topology embedded in spawn prompts, one-message batch spawning, worktree-per-writer with explicit file-scope ownership, and a single integration owner for lockfiles. These map cleanly onto ZO's agent contracts and would harden its parallel-spawn phase against write collisions. +- **Evidence:** `v3/@claude-flow/cli/src/init/claudemd-generator.ts`, `.claude/helpers/router.cjs`, `.claude/helpers/hook-handler.cjs`, `.claude/settings.json` + +#### Witness-manifest self-verification + commissioned honesty audit + +- **What:** Two platform-level truth mechanisms: (1) verification/ holds per-OS 'witness manifests' — sha256 + source-marker checks binding every documented fix/feature to code, re-runnable at any commit (latest run: 55/55 semantic pass, statuses PASS / PASS_DRIFT / MARKER_MISSING), plus performance.jsonl baselines to catch speed regressions; (2) docs/reviews/intelligence-system-audit-2026-05-29.md, a 6-auditor empirical audit that graded every marketed capability against measurements — confirming the learning loop, Q-routing, and quantization as real while exposing 'Flash Attention 2.49–7.47x' as Math.random() fabrication and 'HNSW 150x–12,500x' as 1.48x measured. +- **Why special:** Unique among agent frameworks: the project built an oracle for ITSELF. After years of inflated claims (their own audit's words: 'headline performance multipliers are largely hardcoded doc strings... one is fabricated at runtime'), they institutionalized claim-to-evidence binding — the scaffolded CLAUDE.md even mandates 'bind claims and evidence to exact source/build receipts.' The code is now littered with issue-numbered honesty repairs, and the attention-coordinator header itself carries 'speedup unverified' disclaimers pointing at the audit. +- **How it works:** plugins/ruflo-core/scripts/witness/ tooling issues a manifest at a commit (file hash + regex marker per fix); verify.mjs re-checks markers with source-fallback when dist isn't built; perf.mjs appends capability×duration JSONL rows with rolling-median deltas. The audit ran real measurements against built dist exports and MCP handlers, producing a CONFIRMED/PARTIAL/FABRICATED capability matrix. +- **ZO relevance:** ZO's oracle verifies delivery-repo work; ruflo demonstrates the missing second oracle: one for the PLATFORM's own claims and self-evolution rules. Concretely: when ZO's evolution protocol adds a PRIORS rule, a witness marker could verify the enforcing code/hook actually exists and still fires — mechanizing ZO's 'verify the updated rule would have caught the original failure' step, which today is manual and unenforced. +- **Evidence:** `verification/CAPABILITIES.md`, `verification/results.md`, `docs/reviews/intelligence-system-audit-2026-05-29.md`, `v3/@claude-flow/swarm/src/attention-coordinator.ts` + +#### Learned task/model routing with honest tiering (+ pheromone-adaptive scheduling) + +- **What:** A 3-tier routing stack for choosing agent type and model per task: Tier-1 deterministic codemods that skip the LLM entirely ($0, canSkipLLM in agent_spawn's response), keyword-complexity static scoring, and a persisted Thompson-sampling (Beta bandit) layer that shifts model choice from model-outcome feedback — independently audited as genuinely learning cross-process (Q-table argmax'd at inference, persisted to .swarm/q-learning-model.json). Plus 'pheromone-adaptive' swarm scheduling (APSC): per-agent, role-normalized EMA fitness from {taskSuccess, latency, consensusAlignment} outcomes producing bounded keep/suspend/reactivate decisions. +- **Why special:** The audit separates this from the hype: routing feedback measurably steers subsequent decisions across processes — a real, small, useful learning loop (with one documented critical bug: negative rewards silently inverted to positive). The deterministic-codemod tier is a pattern most frameworks miss: recognize when no LLM is needed. APSC is a defensible swarm mechanism — evidence-based agent eligibility gating — implemented as a pure, testable state machine rather than metaphor. +- **How it works:** agent_spawn → determineAgentModel() (ADR-026/143/148/149): explicit model > codemod detection > neural router (cost-optimal, can pick OpenRouter/Ollama models) > tier default; result recorded on the AgentRecord with modelRoutedBy provenance. swarm_pheromone_update records normalized outcome signals into ApscState inside swarm-state.json; isApscAgentEligible() gates dispatch. hooks pre-task/post-task CLI records task lifecycle for the learning loop. +- **ZO relevance:** ZO routes models statically via agent frontmatter. Worth adapting: (a) outcome-fed routing priors — PRIORS.md entries could carry win-rates per agent/model/task-type that the lead-orchestrator consults at spawn time; (b) a deterministic tier — ZO agents should recognize lint/rename/version-bump work needing zero LLM calls; (c) APSC-style eligibility from oracle outcomes (an agent config repeatedly failing gates gets suspended). Heed their inverted-reward bug: sign conventions in feedback loops need tests. +- **Evidence:** `v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts`, `v3/@claude-flow/cli/src/services/pheromone-adaptive.ts`, `v3/@claude-flow/cli/src/commands/hooks.ts`, `docs/reviews/intelligence-system-audit-2026-05-29.md` + +#### The dead coordination engine (@claude-flow/swarm library) + +- **What:** A 13,157-line, DDD-structured TypeScript package: QueenCoordinator with task analysis/delegation plans/ReasoningBank pattern matching, UnifiedCoordinator, TopologyManager with O(1) role indexes and partition/rebalance logic, AgentPool, MessageBus, AttentionCoordinator (multi-head/flash/MoE 'attention-based coordination'), FederationHub for ephemeral cross-swarm agents, full Raft/PBFT/Gossip with pluggable Ed25519-signed WS transport, and a CQRS application layer — all typed, all tested (10 test files incl. failure injection). +- **Why special:** Special as a cautionary exhibit: grep proves no CLI command or MCP handler instantiates any of it (sole import is capability-brain.ts using the package NAME as catalog metadata). The runtime reimplemented simpler file-based equivalents, leaving this as showcase code whose class names and 'performance targets' (task analysis <50ms) power the marketing narrative. Its consensus 'nodes' were, per the transport docstring, a single process synthesizing peers' replies inline; agents are domain entities in a repository, never processes. This is the largest and best-disguised gap between implemented-looking and actually-wired in the repo. +- **How it works:** Library-only: EventEmitter classes managing in-memory Maps of AgentState/TaskDefinition/TopologyNode; SpawnAgentCommandHandler saves an Agent entity to a repository interface; the ADR-095 G2 transport abstraction added real message serialization + signing but no runtime consumer materialized. +- **ZO relevance:** Pure negative lesson, and an important one for ZO's self-evolution ambitions: coordination sophistication that isn't on the runtime path is marketing debt that eventually forces an embarrassing audit. ZO's discipline should be: no spec/agent/mechanism ships unless a workflow invokes it and the oracle can observe it firing — arguably worth encoding as a ZO platform prior. +- **Evidence:** `v3/@claude-flow/swarm/src/queen-coordinator.ts`, `v3/@claude-flow/swarm/src/unified-coordinator.ts`, `v3/@claude-flow/swarm/src/topology-manager.ts`, `v3/@claude-flow/swarm/src/application/commands/spawn-agent.command.ts`, `v3/@claude-flow/swarm/src/workers/worker-dispatch.ts` + +### Architecture Notes + +Runtime path of a swarm, verified end-to-end: (1) `swarm_init` (MCP) or `ruflo swarm init` writes a JSON coordination record — the CLI start command prints it outright: "Use Claude Code Task tool or hive-mind spawn --claude to drive actual agent execution. This command sets up the topology." (2) Agent 'spawning' = appending AgentRecords to .claude-flow/agents/store.json with model routing metadata. (3) Execution is one of: native Claude Code Task subagents (the doctrine in the scaffolded CLAUDE.md and newest plugin skills — named agents, run_in_background, SendMessage, worktrees); `agent_execute` = a single stateless Anthropic Messages API call with default max_tokens 1024 and NO tool use (a text completion, not an agent); or `claude --print` headless processes (hive-mind --claude launcher; worker daemon). (4) Consensus/broadcast/memory tools mutate shared JSON/SQLite state (.swarm/memory.db via sql.js/AgentDB with HNSW + ONNX embeddings; hive state JSON for votes). Hooks layer: Claude Code settings.json hooks route every prompt/edit/bash through hook-handler.cjs into learning/metrics/session persistence — coordination-by-side-effect around the native loop, cross-platform via Node (not bash). The three-generation stratigraphy is legible in-repo: v2 prompt theater (.claude/agents/*.md personas, emoji-laden hive prompts) → v3 aspirational engine (@claude-flow/swarm DDD library, unwired) → v3.x pragmatic ledger (file-state MCP tools + native Task doctrine + honesty enums). Scale: ~450 MCP tool registrations across ~40 tool files, 107 agent .md files, 35 plugins, 482 v3 test files; they built guidance_brain/capability-brain specifically because the model can't navigate their own tool sprawl — a self-inflicted discovery problem ZO avoids by staying small. The guidance package (CLAUDE.md compiled to enforced gates with cryptographic ledger) and federation plugin (A2A agent cards, WS transport with Ed25519 envelopes) are adjacent capabilities worth separate lenses. + +### Weaknesses + +- Headline architecture is unwired: the 13k-line @claude-flow/swarm coordination engine (queen, topology manager, Raft/PBFT/Gossip consensus) is imported by nothing on the runtime path — MCP handlers use reimplemented JSON-file bookkeeping instead; 'fault-tolerant consensus' in marketing refers to library code whose nodes historically synthesized their own peers' replies in-process. +- 'Agents' from agent_execute are single-shot 1024-token text completions with no tools and no loop — calling the result a coordinated worker substantially overstates it; real agentic execution is delegated entirely to Claude Code's native Task tool or headless claude processes. +- Consensus voter independence is unenforced: in the primary hive-mind flow one Claude session role-plays queen and all voters, so BFT/quorum outcomes are correlated model outputs wearing protocol bookkeeping — decision theater unless callers deliberately spawn independent contexts. +- Documented history of fabricated metrics: the project's own 2026-05-29 audit found Flash Attention speedups generated by Math.random() at runtime, HNSW '150x–12,500x' measuring 1.48x, hardcoded 0.99 'recall' constants, and a critical inverted-reward bug that reinforces bad agents when users penalize them; trust requires reading their audit trail, not their README. +- Extreme surface-area bloat: ~450 MCP tools, 35 plugins, 107 agent definitions, plus neural/quantum-adjacent naming (attention coordinators, pheromones, hive minds) that mostly wraps EMA counters and JSON files — enormous context/discovery burden and a maintenance treadmill visible in ~3,000 referenced issues. +- Prompt-layer agent .md files (byzantine-coordinator, crdt-synchronizer, etc.) describe protocols the runtime cannot execute as described; they function as personas, and their embedded tool examples drift from actual tool names across versions (ADR-382 'scaffold drift remediation' is an entire release theme). +- Coordination state is scattered across at least four stores (.claude-flow/swarm JSON, agents store.json, .swarm/memory.db, .hive-mind/ sessions) with known sync gaps patched case-by-case (#2085 agent/swarm store divergence), rather than one coherent state model. + +### Notable Files + +- `v3/@claude-flow/cli/src/mcp-tools/swarm-tools.ts` +- `v3/@claude-flow/cli/src/mcp-tools/hive-mind-tools.ts` +- `v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts` +- `v3/@claude-flow/cli/src/mcp-tools/agent-execute-core.ts` +- `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts` +- `v3/@claude-flow/cli/src/commands/hive-mind.ts` +- `v3/@claude-flow/cli/src/commands/swarm.ts` +- `v3/@claude-flow/cli/src/commands/daemon.ts` +- `v3/@claude-flow/cli/src/services/headless-worker-executor.ts` +- `v3/@claude-flow/cli/src/services/pheromone-adaptive.ts` +- `v3/@claude-flow/cli/src/init/claudemd-generator.ts` +- `v3/@claude-flow/swarm/src/queen-coordinator.ts` +- `v3/@claude-flow/swarm/src/consensus/transport.ts` +- `v3/@claude-flow/swarm/src/consensus/raft.ts` +- `v3/@claude-flow/swarm/src/topology-manager.ts` +- `docs/reviews/intelligence-system-audit-2026-05-29.md` +- `verification/CAPABILITIES.md` +- `verification/results.md` +- `plugins/ruflo-swarm/skills/swarm-init/SKILL.md` +- `.claude/agents/swarm/hierarchical-coordinator.md` +- `.claude/agents/hive-mind/queen-coordinator.md` +- `.claude/helpers/hook-handler.cjs` +- `.claude/helpers/router.cjs` +- `.claude/settings.json` +- `v3/@claude-flow/guidance/README.md` + +## Lens: plugins-dx + +### Summary + +Ruflo (formerly claude-flow, ruvnet) is a sprawling "meta-harness" for Claude Code/Codex: a fat MCP server + CLI (v3/@claude-flow/cli, ~48 mcp-tool modules, claimed 314 tools) surrounded by 38 thin Claude Code-native plugins under plugins/, each a standardized bundle of auto-discovered SKILL.md skills, command/agent markdown, real .mjs scripts, and a scripts/smoke.sh structural contract. A top-level marketplace.json makes the repo itself a Claude Code plugin marketplace, and skills.sh.json registers 134 skills in 34 groups with the external skills.sh installer. Adoption DX is unusually honest for this genre: the README leads with a two-path table (plugin install = slash-commands-only, zero workspace files, no MCP server; `npx ruflo init` = full loop with .claude/, hooks, daemon), plus `init --wizard/--preset`, `doctor --fix`, a discover-plugins skill with recommended plugin stacks, and an eject command. + +Through this lens the genuinely differentiated material is the verification stack, and it is fully implemented, not aspirational. verification/ holds a three-layer regression-protection system: (1) ~55 CI jobs in v3-ci.yml, most of them behavioral smoke tests that assert user-visible failure modes (fresh npm install on real Node versions, hook stdin round-trips, MCP wire format, Windows shims) rather than code paths — motivated by three documented 2026-05-08 regressions that all passed unit tests; (2) a "witness" manifest attesting that every documented fix's load-bearing code substring ("marker") is still present, per-OS (linux/macos/windows), SHA-256 + Ed25519-signed, 117 fixes currently verified; (3) append-only JSONL temporal history that turns regression triage into a two-commit bisect window. The toolkit is deliberately portable (plugins/ruflo-core/scripts/witness/, single dependency, documented adoption tutorial). A related ratchet pattern (ADR-112) makes MCP tool-description quality a monotone-decreasing CI baseline. + +The second differentiator is ADR-driven development at industrial intensity: 175 ADR files in v3/docs/adr (numbered to 381) plus per-plugin ADR dirs, cited 1,154 times across CLI source (99 unique ADR ids), with CI smoke jobs, witness fixes, release commits, and even source-file module boundaries named after ADR parts ("ADR-382 Part B", "kept in a sibling module because migrate.ts is over the 500-line budget"). ADRs carry Parts, enumerated Gaps, and acceptance-evidence sections; a ruflo-adr plugin manages lifecycle with tested scripts. Ironically, ADR-382 itself — the ADR the current release is named after — is referenced by three source files but absent from the repo, and the repo's self-description numbers drift (SKILL.md claims 267 skills vs 134 registered; the legacy top-level plugin/ dir still ships a v2.5.0 plugin.json pointing at claude-flow@alpha and flow-nexus). The project that built drift-guards for everything still exhibits drift in its own meta-layer; the guards it built for exactly this (smoke-init-scaffold-references.mjs) ship warn-only. + +### Key Features + +#### Witness manifest: cryptographically-attested fix-marker regression tracking + +- **What:** A signed per-OS manifest listing every documented fix as {file, sha256, distinctive marker substring}. If a refactor deletes the load-bearing line of a past fix, markerVerified flips false and CI blocks publish. JSONL temporal history pinpoints the introducing commit. +- **Why special:** Solves a real gap: regressions that pass unit tests because the tests never covered the fix. It machine-enforces 'the same mistake never happens twice' instead of documenting it. Marker-choice guidance (bad: 'function'/'TODO'; good: the exact swapped expression from the diff) is genuinely good craft. Drift-vs-regression distinction (hash changed but marker present = drift, not failure) suppresses false alarms. Per-OS bundles catch CRLF/path-separator drift. Fully implemented and running: 117/117 fixes verified in macos/manifest.md.json, witness-verify CI job at v3-ci.yml:2040 gates publish. Caveat: the Ed25519 seed is sha256(gitCommit + ':ruflo-witness/v1') — derived from public info, so anyone can forge a valid signature; it's tamper-evidence/reproducibility, not authentication, despite 'cryptographically-signed' branding. +- **How it works:** plugins/ruflo-core/scripts/witness/{init,regen,verify,history,perf,lib}.mjs (single dep: @noble/ed25519). Input verification/witness-fixes.json (OS-independent); regen.mjs writes verification//manifest.md.json + appends verification//history.jsonl; verify.mjs checks hash + marker + signature; history.mjs answers 'when did F12 regress' (lastPass..regressedAt window for git log). perf.mjs adds a parallel performance.jsonl baseline (install time, cold import, witness_verify itself). CI matrix job runs per-OS. A witness-curator agent and witness skill wrap the workflow for Claude. +- **ZO relevance:** Highest-value adoption candidate for ZO. ZO's PRIORS.md records 'rules learned + verified solution' as prose — the witness pattern makes each prior machine-checkable: every prior gets a marker in the code that embodies its fix, and a pre-commit/oracle gate verifies all markers still present. Directly implements ZO's self-evolution principle ('verify the updated rule would have caught the original failure') as a standing CI check instead of a one-time verification. The toolkit is portable by design (documented adoption tutorial, no ruflo assumptions in lib.mjs); ZO could vendor the 6 .mjs files or reimplement in Python in a day. Skip the Ed25519 layer (theater for ZO's threat model); keep marker + history. +- **Evidence:** `verification/README.md`, `plugins/ruflo-core/scripts/witness/lib.mjs`, `verification/macos/manifest.md.json`, `verification/macos/history.jsonl`, `verification/witness-fixes.json`, `.github/workflows/v3-ci.yml` + +#### Behavioral smoke-test CI philosophy (~55 jobs testing user-visible failure modes) + +- **What:** CI layer that exercises real artifacts the way users hit them — fresh `npm install` of the packed tarball on multiple Node versions, plugin hooks.json invoked as a real subprocess with realistic stdin JSON, MCP wire-format round-trips, Windows-specific hook shim execution — instead of (only) unit-testing code paths. +- **Why special:** Grounded in a documented post-mortem: three 2026-05-08 regressions (#1859/#1862/#1867) each passed unit tests + typecheck on the broken commit but broke every user on first install (native-dep install failure, invalid hook flag, flag-parser positional preference). docs/validation/README.md analyzes exactly why CI passed while users broke, and each regression became a named CI job class. all-plugins-smoke.yml then generalizes it: every plugin ships scripts/smoke.sh (34/38 do) and a meta-runner executes all of them in parallel (~8s) as a required PR check — the workflow header even admits the smoke files existed unenforced for 30 plugins before iteration 74. +- **How it works:** v3-ci.yml declares ~55 jobs, majority named *-smoke, each tied to a regression class or ADR (smoke-install-no-bsqlite, plugin-hooks-smoke, mcp-protocol-smoke, windows-hook-shim-smoke, memory-import-smoke, tool-output-guardrail-smoke, wizard-init-regression-guard...). Plugin-level scripts live at plugins/*/scripts/{smoke.sh,test-hooks.mjs,test-mcp-protocol.mjs}. All gate the publish job. +- **ZO relevance:** ZO's oracle verifies delivery-repo metrics but ZO's own platform (setup.sh, hooks, validate-docs.sh, zo CLI) is exactly the kind of surface these regressions hit — subprocess flag parsing, fresh-clone setup, hook stdin. Adopt the doctrine: every ZO platform failure in PRIORS.md should spawn a smoke script that reproduces the user-visible symptom, plus a meta-runner so new smoke scripts are auto-enforced. The 'smoke.sh as structural contract per component' pattern maps cleanly onto ZO's agents/commands directories. +- **Evidence:** `docs/validation/README.md`, `.github/workflows/v3-ci.yml`, `.github/workflows/all-plugins-smoke.yml`, `plugins/ruflo-core/scripts/test-hooks.mjs`, `plugins/ruflo-core/scripts/smoke.sh` + +#### ADRs as the executable spine of development + +- **What:** 175 ADR files (v3/docs/adr, numbered to 381) that are not documentation-after-the-fact but the unit of work: ADRs have Parts (A/B/C) that map to separate PRs, enumerated Gaps, and 'Acceptance evidence' sections; code comments, CI job names, witness fix ids, and release commit subjects all cite ADR numbers. +- **Why special:** The cross-referencing density is the differentiator: 1,154 ADR citations across CLI source, 99 unique ADR ids — decisions are greppable from the code that implements them, and CI jobs (e.g. tool-descriptions-audit 'ADR-112') enforce specific ADRs mechanically. Recent ADRs are technically serious (ADR-381 does family-wise error control over an adaptive promotion stream with e-processes, α-spending ledger, governed reset epochs). ADR-382 shows how a bug becomes a multi-part remediation program: Part A (pin MCP launch), Part B (the migrate detection ADR-128 promised and never shipped — they call out their own broken promise in a code comment), Part C (dead-reference guard). BUT: the ADR-382 file itself is missing from the repo while three source files cite its path — and the ~37 'dream-cycle' ADRs (340-376) read like generated design-space exploration whose implementation status is unverifiable from the ADR alone. +- **How it works:** v3/docs/adr/*.md with Status/Date/Related/Prompted-by headers; per-plugin docs/adrs/ (e.g. plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md); ruflo-adr plugin provides create/index/reindex/verify skills backed by tested scripts (scripts/{import,reindex,verify}.mjs + __tests__/). Source files open with ADR provenance comments (migrate-agent-detection.ts). CI jobs and witness fixes carry ADR ids. +- **ZO relevance:** ZO's DECISION_LOG.md is an append-only flat log — fine for chronology, weak for retrieval and enforcement. Adopt: (1) numbered decision records with stable ids cited from code comments and gate definitions, so `grep ADR-NNN` reconstructs a decision's blast radius; (2) 'Prompted by' + 'Acceptance evidence' sections linking each decision to the failure that caused it and the test that proves it — a natural join with PRIORS.md. Avoid: ruflo's volume (175 ADRs is its own drift surface, as ADR-382's absence proves); ZO should keep the count small and gate that every code-cited decision id resolves to a file — a check ruflo itself lacks. +- **Evidence:** `v3/docs/adr/ADR-381-sequential-promotion-evidence-governance.md`, `v3/docs/adr/ADR-102-plugin-hook-cli-flag-regression-ci-guard.md`, `v3/docs/adr/ADR-103-witness-temporal-history.md`, `v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts`, `plugins/ruflo-adr/scripts/reindex.mjs` + +#### Monotone-decreasing quality ratchet (ADR-112 tool-description audit) + +- **What:** A CI gate requiring every MCP tool description to contain discoverability guidance ('Use when...', 'Prefer X over Y', 'fall back...'), be ≥80 chars, and be unique — with the violation count stored as a baseline that may only decrease. +- **Why special:** The ratchet mechanic is the smart part: instead of demanding perfection immediately (which blocks) or warning forever (which is ignored), the baseline file (verification/mcp-tool-baseline.json) freezes current debt and fails CI on any increase, while --update-baseline (explicitly documented as 'do NOT use to mask regressions') lowers it after improvement PRs. It statically parses the same registry the MCP server assembles at startup, so the audit can't drift from runtime truth. Commodity idea (lint baselines exist), uncommonly applied to prompt/description quality for agent tool selection. +- **How it works:** scripts/audit-tool-descriptions.mjs regex-scans v3/@claude-flow/cli/src/mcp-tools/*.ts for name/description pairs, checks GUIDANCE_PATTERNS + length + uniqueness, exits non-zero if no-guidance count exceeds baseline. CI job tool-descriptions-audit in v3-ci.yml. Same ratchet idea reappears in smoke-init-scaffold-references.mjs's warn-only→--strict migration plan. +- **ZO relevance:** Directly portable to ZO's agent definitions and spawn prompts: ZO's contract-first spawning depends on agents having crisp interface descriptions; a ratchet script asserting every agent .md has required frontmatter, a contract section, and description quality — with a monotone baseline — is a ~100-line Python script and closes the gap between ZO's validate-docs.sh (structural counts) and actual prompt quality. +- **Evidence:** `scripts/audit-tool-descriptions.mjs`, `verification/mcp-tool-baseline.json`, `v3/docs/adr/ADR-112-mcp-tool-discoverability.md` + +#### Standardized plugin anatomy + marketplace with completeness guards + +- **What:** 38 plugins under plugins/, each: .claude-plugin/plugin.json (metadata only — skills/commands/agents arrays are a validation ERROR because Claude Code auto-discovers), skills//SKILL.md, commands/*.md, agents/*.md, scripts/*.mjs (real implementations: 79 .mjs files, 24 test files), scripts/smoke.sh, README + REFERENCE. Registered in .claude-plugin/marketplace.json; CI guards that every plugins/ dir has a marketplace entry. +- **Why special:** The anatomy is enforced, not aspirational: validate-plugin skill encodes 10 concrete checks (including the counterintuitive 'no legacy arrays in plugin.json' rule learned from Claude Code rejecting plugins), plugin-package-audit + validate-marketplace CI jobs run structurally, and the marketplace-completeness check exists because three plugins actually shipped unlisted (ADR-382 Gap 4 — they turned the incident into a guard). Skills wrap deterministic scripts rather than being pure prompts: cost-health composes four subcheck scripts in parallel with max-exit-code semantics explicitly for CI gates. This is a coherent 'plugin = markdown interface + script implementation + smoke contract' discipline. +- **How it works:** plugins/*/; .claude-plugin/marketplace.json at repo root (repo doubles as a Claude Code marketplace via /plugin marketplace add ruvnet/ruflo); skills.sh.json exposes 134 skills in 34 groups to the external skills.sh installer (npx skills add ruvnet/ruflo); smoke-init-scaffold-references.mjs check 4 enforces marketplace completeness; scripts/smoke-all-plugins.mjs runs every plugin's smoke.sh. +- **ZO relevance:** ZO's .claude/agents + commands are one flat namespace with counts hand-maintained across 6 files (the cascade chain in CLAUDE.md). Ruflo's lesson: derive counts/rosters from the filesystem and guard with a completeness check, rather than hand-cascading — smoke-init-scaffold-references.mjs derives the canonical CLI name from package.json 'so this check tracks a future rename automatically', the exact upgrade path for ZO's EXPECTED_AGENTS array. The skill-wraps-script pattern also fits ZO: gates/approve etc. should delegate to deterministic scripts with exit codes, not prompt-only logic. +- **Evidence:** `plugins/README.md`, `.claude-plugin/marketplace.json`, `plugins/ruflo-plugin-creator/skills/validate-plugin/SKILL.md`, `plugins/ruflo-cost-tracker/skills/cost-health/SKILL.md`, `skills.sh.json`, `scripts/smoke-init-scaffold-references.mjs` + +#### Scaffold-drift remediation: treating init output as a versioned artifact (ADR-382) + +- **What:** The init scaffold (what `npx ruflo init` writes into user projects) is guarded against content drift: dead CLI invocations, references to MCP tools that no longer exist in the live registry, unpinned npx launches in plugin .mcp.json, and marketplace gaps — plus a migrate path that detects agents deleted from the template and suggests the owning plugin. +- **Why special:** Most agent frameworks scaffold-and-forget; user projects then rot as the platform evolves. Ruflo statically parses mcp-client.ts's import list to derive the live tool registry 'without executing TypeScript', then diffs scaffold references against it — drift detection against the source of truth, not a hand-maintained list. migrate-agent-detection.ts reads Claude Code's actual global install registry (~/.claude/plugins/installed_plugins.json) to decide whether a missing agent is a gap or an intentional plugin migration. Honest engineering: ships warn-only with an explicit documented plan for when each check flips to --strict. Caveat: warn-only means it currently gates nothing, and the ADR describing the plan is the one missing from the repo. +- **How it works:** scripts/smoke-init-scaffold-references.mjs (4 static assertions, zero deps, warn-only vs --strict); v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts (9 removed-agent mappings → install suggestions); init pipeline in v3/@claude-flow/cli/src/init/ (executor.ts 2356 lines: .claude/ + .claude-flow/ trees, generated CLAUDE.md, settings merge, cross-platform hook command strings, helper stamping for upgrade detection); CI jobs init-bundle-invariants-smoke, init-scaffold-references-smoke, wizard-init-regression-guard. +- **ZO relevance:** ZO scaffolds project targets (project:connect, setup.sh) and will hit the same rot: plans and target configs referencing agents/commands that ZO later renames. Adopt the pattern: a drift script that derives ZO's live command/agent surface from the filesystem and asserts scaffolded/target files reference only live names; and an explicit upgrade command (ruflo's executeUpgradeWithMissing + helper stamp files) instead of ZO's current re-run-setup.sh approach. +- **Evidence:** `scripts/smoke-init-scaffold-references.mjs`, `v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts`, `v3/@claude-flow/cli/src/init/executor.ts`, `v3/@claude-flow/cli/src/commands/init.ts` + +#### Fail-open cross-platform hook shim + +- **What:** Every plugin hook command is a single `node -e` bootstrap that resolves the plugin's ruflo-hook.cjs from CLAUDE_PLUGIN_ROOT inside Node (no shell variable expansion), so the identical command string runs on Windows/macOS/Linux; the shim prefers a local binary, falls back to npx --prefer-offline, and always exits 0 so a broken install never blocks the user's turn. +- **Why special:** Encodes two hard-won lessons visible in their own regression history (#1862: hooks erroring on every Write/Edit). Fail-open ('a CLI/install failure never surfaces an error or blocks a turn') is the right default for advisory hooks. The hooks.json description field even documents per-host verdict shape differences (Cursor wants {permission:'allow'}, Codex rejects it and wants exit-0 empty stdout) — real multi-host compatibility engineering, not claims. +- **How it works:** plugins/ruflo-core/hooks/hooks.json (PreToolUse/PostToolUse/PreCompact/Stop → node -e bootstraps); plugins/ruflo-core/scripts/ruflo-hook.cjs (resolver shim); windows-hook-shim-smoke / windows-hook-execution-smoke / pre-bash-hook-smoke CI jobs verify it as a subprocess. +- **ZO relevance:** Partial adopt. ZO's validate-docs pre-commit hook is deliberately fail-closed (it must block bad commits) — keep that. But ZO's advisory hooks (memory nudges, logging) should copy the fail-open + always-exit-0 discipline, and if ZO ever targets Windows contributors the node -e no-shell-expansion trick is the proven pattern. Low priority while ZO is single-platform/single-host. +- **Evidence:** `plugins/ruflo-core/hooks/hooks.json`, `plugins/ruflo-core/scripts/ruflo-hook.cjs`, `plugin/hooks/hooks.json` + +#### Adoption DX: honest two-path install + guided discovery + +- **What:** README leads with a comparison table of the two install paths (Claude Code plugin = slash commands only, zero workspace files, NO MCP server, explicitly 'memory_store, swarm_init won't be callable'; npx ruflo init = full loop) — citing the issue (#1744) where users were confused. Onboarding is init --wizard/--preset → doctor --fix → discover-plugins, with per-use-case recommended plugin stacks and a repo-root SKILL.md that tells agents when NOT to suggest ruflo ('one-shot edits... orchestration overhead isn't worth it'). +- **Why special:** The candor is rare in this ecosystem: the lite path's limitations are stated in bold in the first screen, and the enrollment funnel (ADR-302 Cognitum account prompt post-init) is one-time, TTY-only, --no-signup-skippable, CI-auto-skipped, and 'never affects init's exit code'. An eject command exists as an exit path. The counterweight: the total surface is enormous (38 plugins, 314 claimed MCP tools, 3 npm identities: ruflo/claude-flow/@claude-flow/cli, plus a legacy v2 plugin/ tree still shipping), so the DX story is 'excellent guided paths through an overwhelming system'. +- **How it works:** README.md quick-start table; plugins/ruflo-core/skills/{init-project,discover-plugins,ruflo-doctor}/SKILL.md; v3/@claude-flow/cli/src/commands/{init,doctor,eject,plugins}.ts; funnel/enrollment.ts; bin/cli.js proxies umbrella package → @claude-flow/cli. +- **ZO relevance:** Two takeaways for ZO: (1) the top-level SKILL.md that teaches an agent when to use — and when NOT to use — the system is a cheap, high-leverage artifact ZO lacks (ZO's CLAUDE.md addresses the builder, not an adopting agent); (2) the 'lite vs full' honesty table is the right template if ZO ever splits its plugin-style commands from the full platform. ZO should not copy the surface-area maximalism — ZO's constraint-driven small roster is a feature. +- **Evidence:** `README.md`, `SKILL.md`, `plugins/ruflo-core/skills/discover-plugins/SKILL.md`, `v3/@claude-flow/cli/src/commands/init.ts`, `v3/@claude-flow/cli/src/commands/eject.ts` + +### Architecture Notes + +Monorepo with three concentric systems. (1) Core: v3/@claude-flow/* TypeScript workspaces — cli (26+ commands, ~48 mcp-tool modules forming one fat MCP server), memory (AgentDB/HNSW/better-sqlite3 with fallback), hooks, guidance ('governance control plane'), security, codex (dual-host support) — plus Rust crates/ and a separate ruflo/ appliance dir (docker-compose, own package.json). Published under three npm identities (ruflo thin wrapper, claude-flow umbrella, @claude-flow/cli implementation) via bin/cli.js proxies. (2) Distribution: plugins/ (38 Claude Code-native plugins, markdown + .mjs scripts, no build step) registered in root .claude-plugin/marketplace.json so the GitHub repo doubles as a marketplace; skills.sh.json bridges to the external skills.sh installer. The plugins are deliberately thin — the intelligence lives in the MCP server; a plugin is mostly an interface contract (skills/commands/agents) plus deterministic scripts with exit codes. (3) Verification: file-based, git-committed state under verification/ (per-OS signed manifests, JSONL history, performance baselines, monotone tool-description baseline) — the same 'plain files in git as database' philosophy as ZO's memory/, but for regression state rather than session memory. Governance is ADR-first: decisions get numbered files, code cites them (1,154 citations), CI jobs enforce them, and remediation programs are structured as ADR Parts mapped to PRs. Legacy debt is visible and acknowledged: top-level plugin/ still carries the v2.5.0 claude-flow plugin (74 agents, 38 more skills) alongside the v3 plugins/ tree, and code comments explicitly note the two coexisting plugin systems (Claude Code marketplace registry vs ruflo's own npm-package PluginManager). CI is the real spine: ~55 jobs in v3-ci.yml plus ~28 sibling workflows, nearly all behavioral smoke tests gating publish. Development is evidently heavily agent-driven (dream-cycle ADR series, iteration-numbered workflow comments), which explains both the extraordinary guard density — guards compensate for agent-generated churn — and the recurring pattern of docs/counts drifting ahead of reality. + +### Weaknesses + +- ADR-382 — the ADR the current release (3.38.0) is named after and which three source files cite by path — does not exist in the repo (v3/docs/adr stops at ADR-381). The ADR-driven process has unguarded drift in its own meta-layer. +- Self-description numbers are inflated or stale: SKILL.md claims '267 skills across all plugins' but skills.sh.json registers 134 (and 136 SKILL.md files exist under plugins/); agent counts vary between 60+/74+/98/100+ across README, plugin.json, and marketplace descriptions; root CLAUDE.md itself warns agents not to copy 'stale version or capability counts' — an admission the problem is chronic. +- The witness layer's 'cryptographic signing' oversells: the Ed25519 seed is sha256(gitCommit + constant), derivable by anyone, so signatures prove nothing against a deliberate attacker — the real value is the marker-substring check and temporal history; the crypto is reproducibility dressing. +- The flagship drift guard (smoke-init-scaffold-references.mjs) ships warn-only (always exit 0) with a promised --strict flip gated on backlog cleanup — currently it gates nothing. +- Two overlapping plugin systems coexist (legacy top-level plugin/ at v2.5.0 whose root plugin.json still launches claude-flow@alpha and optional flow-nexus servers, vs v3 plugins/ marketplace; plus ruflo's separate npm-package PluginManager registry) — a confusing adoption surface the code comments themselves acknowledge. +- Enormous cognitive surface: 38 plugins, claimed 314 MCP tools, 3 npm package identities, a rebrand (claude-flow→ruflo) mid-flight, and ~37 'dream-cycle' ADRs (340-376) that read as generated design exploration with unverifiable implementation status — deep-verification of most subsystem claims (swarms, neural training, federation) is impractical and some are likely thinner than documented. +- Marketing tone throughout (badge walls, '150x-12,500x faster', 'Brain AGI', ecosystem download counters) forces readers to verify every claim in code; the verified parts are good, but the signal-to-noise cost is real. +- Unit-test coverage is thin relative to smoke coverage (207 test files in cli/__tests__ against a very large surface; plugins average <1 test file each) — the strategy leans almost entirely on behavioral smoke + witness markers, which catch presence and wiring but not logic-level correctness. + +### Notable Files + +- `/Users/sam101fe4x/Documents/code/ruflo/verification/README.md` +- `/Users/sam101fe4x/Documents/code/ruflo/docs/validation/README.md` +- `/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-core/scripts/witness/lib.mjs` +- `/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-core/skills/witness/SKILL.md` +- `/Users/sam101fe4x/Documents/code/ruflo/scripts/audit-tool-descriptions.mjs` +- `/Users/sam101fe4x/Documents/code/ruflo/scripts/smoke-init-scaffold-references.mjs` +- `/Users/sam101fe4x/Documents/code/ruflo/v3/@claude-flow/cli/src/commands/migrate-agent-detection.ts` +- `/Users/sam101fe4x/Documents/code/ruflo/v3/docs/adr/ADR-102-plugin-hook-cli-flag-regression-ci-guard.md` +- `/Users/sam101fe4x/Documents/code/ruflo/v3/docs/adr/ADR-103-witness-temporal-history.md` +- `/Users/sam101fe4x/Documents/code/ruflo/v3/docs/adr/ADR-112-mcp-tool-discoverability.md` +- `/Users/sam101fe4x/Documents/code/ruflo/v3/docs/adr/ADR-381-sequential-promotion-evidence-governance.md` +- `/Users/sam101fe4x/Documents/code/ruflo/.github/workflows/v3-ci.yml` +- `/Users/sam101fe4x/Documents/code/ruflo/.github/workflows/all-plugins-smoke.yml` +- `/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-plugin-creator/skills/validate-plugin/SKILL.md` +- `/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-core/hooks/hooks.json` +- `/Users/sam101fe4x/Documents/code/ruflo/plugins/ruflo-cost-tracker/skills/cost-health/SKILL.md` +- `/Users/sam101fe4x/Documents/code/ruflo/v3/@claude-flow/cli/src/init/executor.ts` +- `/Users/sam101fe4x/Documents/code/ruflo/SKILL.md` +- `/Users/sam101fe4x/Documents/code/ruflo/skills.sh.json` +- `/Users/sam101fe4x/Documents/code/ruflo/.claude-plugin/marketplace.json` +- `/Users/sam101fe4x/Documents/code/ruflo/plugins/README.md` +- `/Users/sam101fe4x/Documents/code/ruflo/verification/CAPABILITIES.md` diff --git a/memory/zo-platform/research/2026-08-12-repo-reviews/synthesis.md b/memory/zo-platform/research/2026-08-12-repo-reviews/synthesis.md new file mode 100644 index 0000000..626e919 --- /dev/null +++ b/memory/zo-platform/research/2026-08-12-repo-reviews/synthesis.md @@ -0,0 +1,110 @@ +# Synthesis — Cross-Repo Comparison & ZO Gap Analysis (2026-08-12) + +## Executive Summary + +The three repos triangulate ZO's exact weaknesses from three directions. oh-my-claudecode (OMC) is the reference implementation for everything ZO's watchdog RFC and 'enforcement > aspiration' prior are groping toward: a deterministic hook plane (Stop/SubagentStop/PreCompact/PreToolUse) that mechanically enforces what prompts merely promise — stop-gating with a battle-tested taxonomy of never-block escape hatches, machine-checked deliverable contracts, hook-automatic memory persistence, heartbeat liveness, rate-limit auto-resume, and two-way remote control of unattended runs. ruflo is 90% cautionary tale (a 13k-line coordination engine nothing imports; fabricated benchmarks its own audit exposed) but its remediation machinery is genuinely novel and maps perfectly onto ZO's self-evolution protocol: witness manifests that machine-verify every documented fix's load-bearing code still exists, behavioral smoke tests born from named regressions, and monotone quality ratchets. ralph is 113 lines of bash that solves context rot, state hallucination, and stall blast-radius structurally — fresh agent per context-window-sized story, all state on disk, git as checkpoint — the strongest available argument for what ZO's post-tmux execution substrate should look like. The synthesis: ZO's oracle discipline and honest empirical culture are already best-in-class among these four systems; what ZO lacks is a deterministic enforcement plane beneath its prompts, a machine-readable control-plane state beside its markdown, a mechanized regression loop for its own rules, and an execution substrate whose failure unit is one iteration rather than one 38-hour session. Every P0 below is implementable in ZO's existing hook layer without waiting for the SDK refactor — and several make that refactor smaller. + +## Per-Repo Verdicts + +### oh-my-claudecode + +- **One-liner:** A 337K-line Claude Code plugin that turns prompt promises into hook-enforced guarantees — the most battle-tested agent-persistence and lifecycle machinery in the ecosystem, wrapped around unverified self-improvement claims. +- **What makes it special:** The deterministic hook lattice: every one of its ~10 stop-blocking circuit breakers, deliverable checks, and memory-persistence hooks carries a GitHub issue number from a real production failure. It is a paid-for catalog of every way autonomous-loop enforcement goes wrong (context-limit deadlocks, rate-limit retry loops, recursive keyword spawning, forged approvals) and the working fix for each. Its operator layer (HUD statusline, two-way Discord/Telegram/Slack reply injection, rate-limit auto-resume daemon) is the best answer anywhere to 'what does the human see during a 12-hour unattended run'. +- **Maturity:** High on the enforcement/runtime plane (thousands of users, issue-driven hardening, real tests); low on quality evidence (SWE-bench harness has empty results, the only committed run failed 5/5, agent benchmarks are zero-filled placeholders) and carries significant dead code presented as capability (model-routing engine, verification tier-selector, recovery hooks wired to nonexistent events). + +### ruflo + +- **One-liner:** A ~400K-line coordination LEDGER for Claude Code (not an executor) whose headline swarm/neural/Rust claims are largely theater, but whose self-verification machinery — built to dig itself out of documented fabrication — is uniquely valuable. +- **What makes it special:** It built an oracle for itself: witness manifests binding 117 documented fixes to code markers with per-OS CI verification and bisectable temporal history; a commissioned internal audit that graded its own marketing (exposing Math.random()-fabricated speedups); ~55 behavioral smoke-test CI jobs each born from a named regression that passed unit tests; monotone-decreasing quality ratchets. Also the best distilled coordination doctrine in the set (worktree-per-writer, named agents spawned in one message, SendMessage over polling) — arrived at after abandoning its own 13k-line consensus engine. +- **Maturity:** Bimodal. The verification stack, memory package (real HNSW, honest benchmarks, temporal-validity supersession), and ADR discipline are mature and running in CI. The swarm layer is prompt theater over JSON bookkeeping; consensus voters are one model role-playing; 'agents' from agent_execute are 1024-token toolless completions; in-repo Rust is self-declared stubs. Trust the audited parts, not the README. + +### ralph + +- **One-liner:** 113 lines of bash + two prompts that make statelessness the architecture: fresh agent per context-window-sized story, all state on disk, git as the checkpoint system — maximum insight-per-line of any repo reviewed. +- **What makes it special:** The inversion: push all intelligence to plan time (story sizing 'The Number One Rule': every task must fit one context window, with verifiable acceptance criteria) and all state to files (prd.json passes flags, append-only progress.txt with a read-first consolidated-patterns section, per-directory AGENTS.md learnings), so the runtime can be trivially dumb. Fresh context per iteration structurally eliminates context rot, persisted hallucination, and compounding errors — and caps stall blast-radius at one iteration. +- **Maturity:** Proof-of-pattern, not a platform. Zero independent verification (the agent flips its own passes flags; the harness greps for a sentinel string), no timeouts, no failure escalation, hand-duplicated prompts already diverged, and its browser-verification dependency isn't shipped. Adopt the technique, not the code. + +## Top Features to Adopt (ranked) + +### 1. Machine-checked deliverable contracts at SubagentStop (generic contract-enforcement layer) `P0` · small · from oh-my-claudecode + +- **Why:** This is the systematic answer to ZO's #1 recurring failure mode ('aspirational contracts get ignored', PR-035) and its open question about replacing incident-driven hard gates with a generic mechanism. OMC's templates/deliverables.json declares per-stage required files, minimum sizes, required sections, and regex patterns; a SubagentStop hook verifies them mechanically. ZO already writes produced/consumed contracts into every spawn prompt — this makes them enforceable instead of aspirational, at agent granularity, before the phase-level oracle gate. Pair with OMC's workflow-drift-guard (regex 'completion claim + stub/TODO in diff' lie detector) as a zero-LLM-cost tier-0 check on every stop. +- **How ZO adopts it:** Extend ZO's spawn-contract schema so each agent contract emits a deliverables entry (files, required sections, patterns) into a per-project contracts.json at spawn time; add a SubagentStop hook (ZO currently uses only one PreToolUse hook) that validates artifacts against it and blocks/flags on violation; port the drift-guard regexes as a Stop-time check. One JSON schema + two hook scripts, in Python. + +### 2. Watchdog built from proven parts: heartbeat-file liveness + stop-gating with the never-block escape-hatch taxonomy + rate-limit auto-resume `P0` · medium · from oh-my-claudecode (+ ruflo PID-probe orphan reaping) + +- **Why:** ZO's watchdog spec (297adac) is an RFC written after a real 38-hour silent stall; OMC has already paid for every design mistake ZO is about to make. The transferable core: (1) heartbeat files with freshness checks as the liveness primitive (fits ZO's file-based philosophy); (2) idle detection requiring BOTH ready-state AND no-active-task, with bounded nudge budgets before escalation; (3) the taxonomy of stops you must NEVER fight — context-limit (#213 deadlock), rate-limit (#777 retry loop), auth errors (#1308), user aborts; (4) thinking-only-streak detection from the transcript rather than wall-clock; (5) distinguishing 'stalled because stuck' (nudge/restart) from 'stalled because rate-limited' (daemon waits for reset and resumes — the single biggest killer of overnight runs); (6) ruflo's PID+start-time identity checks and TTL orphan reaping so the watchdog never acts on recycled PIDs or stale state. +- **How ZO adopts it:** Implement the RFC as: per-agent heartbeat JSON under the project state dir written on activity; a small external checker (cron or the LifecycleWrapper's poll loop, NOT a monitor agent — avoiding the single-point-of-failure ZO already identified) that compares freshness, applies the escape-hatch checks before any intervention, nudges with a bounded budget, and escalates to iteration restart. Add a rate-limit-wait mode that pauses rather than retries and resumes on reset. Multi-level caps everywhere: per-phase max iterations plus a global hard cap (OMC: 500). + +### 3. Hook-enforced memory protocol (PreCompact + SessionEnd + PostToolUseFailure) `P0` · small · from oh-my-claudecode + +- **Why:** ZO's CLAUDE.md declares memory updates 'AUTOMATIC (NON-NEGOTIABLE)' but enforcement is prompt-protocol plus one commit hook — the model can forget, and mid-session compaction is a total blind spot (STATE.md checkpoints at session boundaries only). OMC's pattern is strictly stronger: hooks persist state unconditionally at lifecycle boundaries, so the model cannot forget because the model isn't asked. PostToolUseFailure additionally gives ZO's self-evolution protocol a guaranteed structured failure feed instead of depending on the model remembering to write priors. +- **How ZO adopts it:** Three hooks: PreCompact flushes current phase/decisions/blockers to STATE.md before compaction destroys them; SessionEnd verifies (or writes) the session summary and DECISION_LOG entries, closing deferred audit items #15/#16; PostToolUseFailure appends structured failure records (tool, input, error, retry count) to a session-scoped JSONL that the retrospective/priors pipeline distills. Directly mechanizes the 'AUTOMATIC protocol' that is currently prose. + +### 4. Machine-readable per-subtask ledger with oracle-owned pass flags `P0` · medium · from ralph (+ oh-my-claudecode ralph-mode prd.json) + +- **Why:** ralph's prd.json proves that boolean passes flags per story make resume, progress, and completion mechanically decidable — 'what is done' becomes a jq query, not prose interpretation of plan.md. OMC independently converged on the same schema (stories + acceptance criteria + passes + fix_loop {attempt, max_attempts, last_failure_reason} state). ZO's continue/build auto-detection, gate logic, and the watchdog's 'is there work remaining' predicate all get cheaper and more reliable on a decidable ledger. The one critical fix over both sources: only the oracle may flip passes:true — ralph's fatal flaw is builder self-assertion. +- **How ZO adopts it:** Generate a plan-ledger.json from plan.md at build start (subtask id, acceptance criteria, verification command, passes, attempts, last_failure); builders read it, only oracle-qa writes the passes field (enforced by the deliverable-contract hook); gates and the loop evaluator consume it. Extend specs/plan.md validation with ralph's sizing lint: every subtask must fit one context window and carry machine-verifiable criteria with the check command named inline (ralph's good/bad criterion examples are the lint spec). + +### 5. Witness manifests + golden-trace/fixture regression: mechanize self-evolution verification `P1` · medium · from ruflo (+ oh-my-claudecode benchmark harness pattern) + +- **Why:** ZO's protocol requires verifying 'the updated rule would have caught the original failure' — today that verification is manual, informal, and unenforced (an explicit ZO open question). ruflo's witness system is exactly this, mechanized: each documented fix binds to a file + hash + distinctive code-marker substring; CI verifies all markers still present per-OS, with append-only JSONL history that turns any regression into a two-commit bisect. OMC's agent-prompt benchmark shape (fixtures with planted flaws + ground-truth findings + baseline snapshots) covers the other half: when self-evolution edits an agent persona or rule, a fixture run proves the edit catches the original failure without degrading other behavior. +- **How ZO adopts it:** Add a marker field to PRIORS.md entries pointing at the load-bearing code/hook of each verified fix; a ~day-of-work Python reimplementation of ruflo's witness verify (skip the Ed25519 theater — its seed derives from public info anyway) runs in validate-docs.sh and CI. For prompt-level rules, keep the failure's transcript/fixture and re-run it against edited personas before promotion, starting with oracle-qa and code-reviewer only. + +### 6. Fresh-context-per-subtask execution loop as the substrate direction `P1` · large · from ralph (+ oh-my-claudecode autopilot phase-state) + +- **Why:** ralph demonstrates that fresh process + all-state-on-disk structurally eliminates context rot, persisted hallucination, and compounding errors — and shrinks ZO's stall blast-radius from '38 silent hours' to 'one lost iteration'. ZO already does fresh context at phase transitions; pushing it to subtask granularity (spawn per plan-ledger item, re-derive state from ledger + STATE.md + git) makes the fragile long-lived tmux session less load-bearing and makes the eventual SDK refactor smaller: a stateless spawn-per-item loop is trivially portable to headless/SDK invocation, while a long interactive session is not. +- **How ZO adopts it:** For Phase 4 first (where the experiment loop already provides the per-iteration structure): experiment_loop.py spawns a fresh builder per iteration with a static prompt that re-reads exp lineage + ledger + a read-first consolidated-priors digest (ralph's Codebase Patterns tier), commits as checkpoint, oracle flips flags. Keep hard caps as the outer bound. Extend to other phases' subtask execution if Phase 4 validates it on prod-001. + +### 7. Anti-forgery correlated approval tags for every LLM-judged gate `P1` · small · from oh-my-claudecode + +- **Why:** OMC's ralph verifier requires approvals as an XML tag carrying a per-verification random request-id UUID, strips prompt-injected examples before matching, and correlates story-id — so an executing agent cannot forge gate passage by echoing text it saw in context. ZO's numeric oracle gates are immune, but its human-checkpoint gates, adversarial cross-review, and any reviewer-judged phase sign-off are exactly the surface this protects. Given ZO's documented history of a Sonnet lead silently ignoring contracts, assuming agents won't echo approval strings is naive. +- **How ZO adopts it:** gates:approve and the four-stage validation loop generate a nonce per verification request; approval is only valid as a structured tag containing that nonce plus the gate/subtask id, validated by the gate code after stripping any quoted/example spans. A few dozen lines in the gate logic. + +### 8. Two-way gate notifications (Slack/Telegram) with reply injection and idle-cooldown `P1` · medium · from oh-my-claudecode + +- **Why:** ZO's human experience between gates is polling DECISION_LOG — an acknowledged gap and open question. OMC ships the complete pattern: outbound notifications on gate-pending/stall/session-end, and a reply-listener daemon that maps channel replies back to the session and injects them (per-user authorization, sanitization, pane verification, rate limits, idle pings with cooldown so a stall notifies once, not sixty times). For a solo operator running multi-hour autonomous ML phases, 'phone as remote gate approver' is the single biggest quality-of-life unlock. +- **How ZO adopts it:** Phase 1 (small): outbound-only — gate-pending, TARGET_HIT/PLATEAU/DEAD_END verdicts, and watchdog stall alerts to a Slack/Telegram webhook, with cooldowns. Phase 2 (medium): reply listener mapping 'approve'/'reject: reason' to gates:approve/reject injection via the existing tmux layer, copying OMC's authorization and sanitization posture wholesale. Revisits the v1 no-integrations constraint, but the evidence says notification is where that constraint costs the most. + +### 9. Structurally trustworthy verifiers: disallowedTools read-only oracle + evaluator JSON contract + sealed oracle files `P1` · small · from oh-my-claudecode + +- **Why:** Three small formalizations that harden ZO's already-strong oracle: (1) frontmatter disallowedTools on oracle-qa/reviewers (OMC hard-blocks Write/Edit on advisory agents) — a verifier that cannot edit is mechanically more trustworthy than one instructed not to; (2) autoresearch's strict evaluator contract ({pass: bool, score?: number} JSON, with keep_policy distinguishing hill-climbing from pass/fail) formalizes what ZO's oracle emits and cleanly serves Phase 4's metric-improvement loops vs binary gates; (3) sealed-files enforcement — the improvement loop cannot modify its own evaluation code — is the anti-Goodhart rule ZO's repo separation covers across repos but not within the delivery repo, where an agent could still edit the eval script. +- **How ZO adopts it:** Add disallowedTools to oracle-qa and reviewer frontmatter with a PreToolUse check; specify oracle output as the strict JSON schema in specs/oracle.md and result.md; add oracle/eval paths to a per-project sealed list enforced by the same PreToolUse hook (mirror of zo_only_paths, pointing inward). + +### 10. Ambient observability: ZO statusline HUD `P2` · small · from oh-my-claudecode + +- **Why:** OMC's biggest day-to-day UX differentiator: the operator sees mode/iteration/agents-alive/context-% at a glance without asking the model. ZO's monitoring is pull-only (observe:watch, watch-training). A statusline showing {project alias, phase, pending gate, oracle status, experiment iteration, agents active, context %} gives ambient awareness during long runs for near-zero cost, and ZO's brand system gives it a visual language. +- **How ZO adopts it:** A zo hud command reading STATE.md + plan-ledger.json + experiment training_status.json + heartbeat files, registered as Claude Code's statusLine. Copy OMC's element-renderer + preset composition; start with four elements (phase, gate, agent count, context bar). + +### 11. Platform CI doctrine: behavioral smoke tests per prior + monotone quality ratchets + registry==filesystem generation `P2` · medium · from ruflo (+ oh-my-claudecode budget tests) + +- **Why:** ruflo's documented post-mortem — three same-day regressions that all passed unit tests but broke every user on first install — produced the doctrine ZO's platform layer needs: every user-visible platform failure in PRIORS.md spawns a smoke script reproducing the symptom (fresh-clone setup.sh, hook stdin round-trips, CLI flag parsing), auto-enforced by a meta-runner. The ratchet pattern (freeze current debt as a baseline that may only decrease) applies to ZO's agent-definition/spawn-prompt quality. And both repos' count-drift failures (marketplace '28 agents' vs actual 19; ruflo's 267-vs-134 skills) prove ZO's hand-maintained cascade chain should be replaced by derive-from-filesystem generation plus an assertion test — making cascade steps impossible to forget rather than checked after the fact. +- **How ZO adopts it:** Add a smoke/ dir with per-prior reproduction scripts and a meta-runner in CI; a ratchet script asserting agent .md frontmatter/contract-section completeness with a committed baseline; generate the counts in README/setup.sh/specs from the filesystem in validate-docs.sh instead of hand-editing six files. + +### 12. PRIORS.md upgrades: supersession semantics, quality gate, read-first digest, context budget `P2` · small · from ruflo + oh-my-claudecode + ralph + +- **Why:** Four cheap, convergent memory refinements: (1) ruflo's invalidate-never-overwrite temporal semantics — a refuted prior gets validUntil + supersededBy pointing at its replacement, preserving why rules changed (ZO's superseded-only rule, given real structure); (2) OMC skillify's three-question quality gate (not Googleable / project-specific / hard-won) prevents PRIORS.md degrading into trivia as it grows — ZO's 'add a prior after every failure' currently has no filter; (3) ralph's two-tier read-first pattern — inject a small curated digest, not the full log (ZO already caps at 8 injected priors; formalize the curation); (4) OMC's CI-enforced context budget (64KB total/2KB per skill) applied to ZO's ~25 skill descriptions, which tax every session. +- **How ZO adopts it:** Structured front-matter on prior entries (id, status, supersededBy, marker); the three-question gate written into the evolution protocol and EvolutionEngine; a generated PRIORS-digest section maintained at consolidation time; a byte-budget assertion on .claude/skills+commands frontmatter added to validate-docs.sh. + +## Rearchitecture Themes + +- ENFORCEMENT PLANE BELOW THE PROMPT PLANE: The single loudest signal across all three repos. OMC's core pattern — markdown defines behavior, deterministic hooks on every lifecycle event (Stop, SubagentStop, PreCompact, PreToolUse, PostToolUseFailure) enforce it — is the systematic version of ZO's own hardest-won prior ('enforcement > aspiration'). ZO currently uses one hook; every recurring 'agents ignored the contract' incident has been patched with a bespoke hard gate. V2 should treat the Claude Code hook lattice as a first-class architectural layer: contracts compile to machine-checkable deliverable schemas, memory protocol runs in hooks not prompts, gates verify artifacts and nonce-correlated approvals deterministically. This converts ZO's remaining prompt-trust surface into checked invariants without any SDK dependency. +- FRESH-CONTEXT, DISK-STATE EXECUTION SUBSTRATE: ralph proves the runtime can be nearly stateless if the plan is context-window-sized and all state lives in files + git; OMC's production scars prove long-lived stop-blocked sessions accrete circuit breakers forever. ZO's fragile tmux layer and 38-hour stall both stem from betting on one long-lived session. The structural direction: per-subtask/per-iteration fresh spawns that re-derive state from a machine-readable ledger, with git commits as checkpoints. This caps stall blast-radius at one iteration, makes the watchdog's job trivial (kill and respawn beats nudge and pray), and — because a stateless spawn loop ports cleanly to headless/SDK invocation — is the cheapest on-ramp to the deferred SDK refactor rather than a competitor to it. +- DUAL-PLANE STATE: MACHINE CONTROL PLANE + HUMAN PROJECTION: ZO's markdown memory is its greatest asset for auditability and its most fragile interface for code (hand-edited STATE.md crashed the orchestrator; 'what is done' requires prose interpretation). OMC materializes typed session-scoped JSON state that hooks enforce against; ralph's passes flags make progress decidable; ruflo's write-here-read-there bugs (#1945) show the cost of fragmented roots. V2 direction: one machine-readable control plane per project (plan-ledger.json, gate state, heartbeats, contracts) under a single root, with STATE.md/DECISION_LOG.md retained as the human-readable projection — generated or validated from it, never the parse target for control decisions. +- AN ORACLE FOR THE PLATFORM ITSELF: ZO applies oracle discipline to delivery work but its self-evolution loop is verified manually. ruflo — after documented fabrication — built the missing second oracle: witness markers binding every fix to code with CI verification, behavioral smoke tests per regression, golden-trace replay before rule promotion, monotone quality ratchets. OMC's fixture-based agent-prompt benchmarks complete the picture for prompt-level rules. V2 should close ZO's loop: every prior carries a marker or a reproduction fixture, and 'the updated rule would have caught the original failure' becomes a standing CI check instead of a one-time claim. This also directly answers ZO's open question on evolution-confidence scoring. +- OPERATOR EXPERIENCE AS AN ARCHITECTURAL LAYER, NOT A ROADMAP ITEM: ZO's human sits between gates polling files. OMC demonstrates that for unattended autonomous systems, the observe/notify/control loop is load-bearing infrastructure: ambient HUD, two-way notifications with reply injection, idle pings with cooldowns, rate-limit auto-resume. The watchdog theme and this one are the same investment viewed from machine and human sides — the 38-hour stall was simultaneously a liveness failure and a notification failure. V2 should design them together: heartbeat state feeds both the automated checker and the operator surface. +- NOTHING SHIPS UNWIRED: ruflo's 13k-line dead coordination engine and OMC's uncalled routing/verification engines show how orchestration frameworks accrete capability-shaped marketing debt that eventually forces an embarrassing audit. ZO's small honest surface is a competitive asset. Encode it as a platform prior with teeth: no spec, agent, or mechanism merges unless a workflow invokes it and a test or witness marker can observe it firing — and no self-improvement claim (cost, quality, autonomy) ships without a completed benchmark run in-repo, which ZO's cost-savings refutation shows it already knows how to do. + +## Anti-Patterns to Avoid + +- Dead code presented as capability: OMC exports a complete model-routing engine, verification tier-selector, and recovery hooks with zero runtime callers; ruflo's flagship 13k-line swarm/consensus library is imported by nothing on the runtime path. Both inflate perceived capability and force expensive audits later. ZO rule: runtime-caller-or-it-doesn't-merge. +- Unverified self-improvement claims: OMC's SWE-bench harness has empty result templates and a 5/5-failure smoke run as its only data; ruflo shipped '150x-12,500x faster' (measured: 1.48x-4.7x) and Flash Attention speedups literally generated by Math.random(). ZO's measured refutation of its own 70-80% cost claim is the antidote culture — never regress from it. +- Hard-blocking Stop as the persistence foundation: OMC's 2,564-line stop hook with ~10 interacting circuit breakers is the fossil record of every way fighting the platform's lifecycle goes wrong (compaction deadlocks, 429 retry loops, auth loops). Blocking stops is a last-resort backstop with exhaustive escape hatches — fresh-spawn loops with hard caps are the foundation. +- Keyword-triggered heavy orchestration: OMC permanently disabled its 'team' keyword after prompts containing the word caused infinite recursive worker spawning, and needed 1,114 lines of multilingual false-positive suppression for the rest. ZO team spawning stays explicit and imperative; no string that can appear in agent-to-agent prompts may ever trigger spawning. +- Self-asserted completion: ralph's agent runs its own checks, flips its own passes flags, and the harness greps for a sentinel the prompt itself contains verbatim. Ledger mechanics yes; grading privilege stays with the oracle, and completion predicates are structured state, never greps over model prose. +- Fragmented state roots: ruflo scattered coordination state across four-plus directories and shipped write-here-read-there bugs where 'the CLI reported success against the wrong file' (#1945). ZO's single memory root is correct — the plan-ledger/control-plane additions must live under it, and 'verify writes land where reads look' belongs in PRIORS as a failure class. +- Surface-area maximalism: ruflo's ~450 MCP tools, 38 plugins, and 107 agent .md files required building discovery AI (capability-brain) just to navigate itself; OMC's 41 overlapping skills need paragraph-length disambiguation prose per pair. ZO's 21-agent, ~25-skill roster is a feature; growth should require retiring or merging, not just adding. +- Hand-maintained duplication and count drift: OMC's marketplace advertises 28 agents (actual: 19); ruflo claims 267 skills (registered: 134) and its current release is named after an ADR that doesn't exist in the repo; ralph's two prompt files semantically diverged within ~20 commits. Every one of these had verification tooling that didn't cover the drifting surface. Generate from a single source and assert registry==filesystem; never maintain parallel copies by hand. +- Security/verification theater: ruflo's 'cryptographically-signed' witness manifests derive the Ed25519 seed from sha256(public git commit + constant) — anyone can forge signatures; its BFT 'consensus' tallies votes from one model role-playing every voter. Adopt the substance (markers, history, vote bookkeeping with independence requirements), never the costume — a mislabeled guarantee is worse than none. +- Prompt-persona theater describing protocols the runtime can't execute: ruflo's byzantine-coordinator/crdt-synchronizer agent files describe distributed algorithms that are actually one session writing JSON, and their embedded tool examples drifted from real tool names across versions. ZO agent definitions must describe only what the agent mechanically does, with contract references that validate against the live system. +- Fail-open where the guarantee is the point: ralph runs with all permission systems disabled, no timeouts, no failure escalation — one impossible story silently burns every remaining iteration. ZO's hard gates and enforce_isolation are the right call; adopt fail-open only for advisory hooks (logging, nudges), never for gates, contracts, or confidentiality enforcement. diff --git a/memory/zo-platform/research/2026-08-12-repo-reviews/zo-baseline.md b/memory/zo-platform/research/2026-08-12-repo-reviews/zo-baseline.md new file mode 100644 index 0000000..a78b47c --- /dev/null +++ b/memory/zo-platform/research/2026-08-12-repo-reviews/zo-baseline.md @@ -0,0 +1,64 @@ +# ZO Baseline — Current Architecture Map (2026-08-12) + +## Summary + +Zero Operators (ZO) is a plan-driven autonomous AI research/ML engineering team built on Claude Code. A human writes/approves plan.md; a Lead Orchestrator (Opus) decomposes it into a 6-phase gated ML workflow and spawns a contract-first team of 21 defined agents; a hard oracle (numeric, tiered must/should/could thresholds) gates every phase; per-project markdown memory (STATE/DECISION_LOG/PRIORS + fastembed/SQLite semantic index) provides cross-session continuity; a post-mortem/self-evolution protocol turns every failure into a rule update. v1 is complete (854 platform tests, all 8 PRD acceptance criteria met), validated on MNIST (99.66%) and CIFAR-10 demos plus one production project (prod-001, currently at Phase 2). Its strongest assets are oracle discipline that is enforced in code rather than in prompts, a genuinely wired learning loop, and an unusually honest empirical culture (it refuted its own 70-80% cost-savings claim down to a measured ~30%). Its biggest weaknesses are the fragile tmux/CLI-subprocess execution substrate, a still-unimplemented anti-stall watchdog (a real 38-hour silent stall occurred), a rigid linear ML-only workflow DAG, a structural cost ceiling without an SDK refactor, and a recurring pattern where agent contracts are ignored unless hard-enforced — enforcement coverage remains incomplete. + +## Current Architecture + +TWO-REPO MODEL ("surgeon and patient"): The ZO repo holds all infrastructure (specs/, .claude/agents/, memory/, plans/, targets/, logs/); delivery repos receive only clean project artifacts. A target file (targets/{project}.target.md) bridges them: target repo path, branch, per-agent working dirs, a zo_only_paths blocklist, and enforce_isolation. Projects can optionally carry portable state in a .zo/ directory inside the delivery repo (config.yaml, memory/, plans/, experiments/), making projects movable via git pull; `zo migrate` copies state over and `zo continue`/`zo status` auto-detect from .zo/config.yaml. Platform memory (memory/zo-platform/) always stays in the ZO repo, with a hard confidentiality regime: client info never in tracked files, sequential aliases (prod-001, demo-mnist), gitignored plans/targets/memory, and a fail-closed blocklist for promoting learnings. + +OPERATING MODES / CLI: Two user-facing modes — Build (input plan → spawn team → produce code; auto-detects fresh/continue/plan-edited) and Continue (thin alias for build). The `zo` CLI (src/zo/cli.py, ~3,400 lines; whole package ~15.8k lines across 33 modules) exposes: build, continue, init (conversational Init Architect or headless with --dry-run/--reset), draft (Plan Architect + Data Scout draft plan.md conversationally from docs/data), preflight (10 validation checks), status, migrate, gates set (supervised/auto/full-auto mid-session), experiments list/show/diff, learnings promote, watch-training (Rich Live dashboard), report and consolidate (concurrent Opus report session in an isolated git worktree alongside a live model session, with delta-memory consolidation back to canonical memory), plus 24 slash commands in 8 categories (.claude/commands/: agents, document, gates, memory, observe, project, commit, zo-dev). Execution substrate: a LifecycleWrapper (wrapper.py) launches the Claude Code CLI as a subprocess in tmux (interactive, paste-buffer prompt injection, liveness polling with startup grace/debounce) or headless (--no-tmux with --dangerously-skip-permissions); a permissions overlay writes bypassPermissions into settings.local.json with backup/restore for unattended runs. Extension points (PR #99) allow workflow resolution overrides, orchestrator subclassing, and zo.commands entry-point CLI plugins. A --low-token preset swaps the lead to Sonnet, caps iterations, and trims agents (measured ~30% savings). + +AGENTS: 21 agent definitions in .claude/agents/ (md files with YAML frontmatter: name, model, role, tier, team), in four teams — Project Delivery (12): lead-orchestrator (Opus), data-engineer, model-builder (Opus), oracle-qa, code-reviewer, test-engineer, research-scout (Opus), plus phase-in xai-agent, domain-evaluator (Opus), ml-engineer, infra-engineer (Haiku), training-checker (per-run live training monitor); Platform Build (6): software-architect, backend-engineer, frontend-engineer, platform-test-engineer, platform-code-reviewer, documentation-agent; Draft Scouts (2): plan-architect + data-scout; Init (1): init-architect. Model routing is static per agent (Haiku=glue, Sonnet=analysis/iteration, Opus=architecture/orchestration). Coordination uses Claude Code native agent teams (TeamCreate + Agent + SendMessage, peer-to-peer), with contract-first spawning: every spawn prompt specifies ownership, off-limits paths, produced/consumed contracts, coordination rules, and a validation checklist. Projects can add custom agents via a plan.md block (written to .claude/agents/custom/) and per-project agent adaptations injected at spawn time. + +WORKFLOW: Six gated phases (+ Phase 0 literature review in research mode) encoded in specs/workflow.md and the ml-workflow skill: 1 Data Review (13 subtasks, sequential), 2 Feature Engineering/representation design, 3 Model Design (parallel: architecture, loss, training strategy, oracle setup, tracking), 4 Training & Iteration (autonomous loop), 5 Analysis & Validation (SHAP/explainability, error analysis, ablations, significance, reproducibility), 6 Packaging (parallel: inference pipeline, model card, validation report, drift detection, tests). Three workflow modes (classical_ml, deep_learning, research) selected from plan.md. Human checkpoints at Gate 2 (feature/representation approval) and Gate 4 (model approval); Gate 3 is the automated oracle threshold. Phase 4 runs inside an experiment capture layer: each iteration gets .zo/experiments/exp-NNN/ (hypothesis.md, config.yaml, metrics.jsonl + training_status.json via a mandatory ZOTrainingCallback — hard-gated, the Phase 4 gate fails if the artifacts are missing —, result.md from Oracle, diagnosis.md, next.md) with parent_id lineage and an auto-maintained CHECKLIST.md. In auto/full-auto gate modes an autonomous loop evaluator (experiment_loop.py) issues verdicts: TARGET_HIT / BUDGET_EXHAUSTED / PLATEAU / DEAD_END (Jaccard-similar hypotheses = builder stuck rephrasing) / CONTINUE, with policy defaults (max_iterations=10, plateau_epsilon=0.01) overridable via a plan ## Experiment Loop block. + +MEMORY: Four markdown files per project — STATE.md (checkpoint: mode, phase, blockers, next steps, git_head; validated at parse time), DECISION_LOG.md (append-only audit trail with rationale/alternatives/outcome), PRIORS.md (domain knowledge, never deleted, superseded-only), session summaries — plus a fastembed+SQLite semantic index (cosine similarity, full rebuild at session end, no incremental indexing). Session lifecycle: read STATE + query index + read recent summaries + verify git HEAD at start; write summary + update STATE + append decisions + reindex at end, with periodic checkpoints via hooks for interrupt recovery. Context Reset Protocol: phase transitions open fresh conversations loading only prior-phase artifacts as files. Memory is strictly per-project; platform memory is separate. + +ORACLE: Every plan must declare primary metric, ground-truth source, evaluation method, target threshold, evaluation frequency before work begins. Tiered criteria (Tier 1 must-pass blocks progression; Tiers 2/3 informational by default). Explicit anti-patterns: no soft signals ("tests pass" is not an oracle), no post-hoc threshold adjustment. Four-stage validation loop after any "work complete": self-checklist → oracle → adversarial cross-review → integration validation. + +SELF-EVOLUTION: Post-mortem protocol on every failure — document in DECISION_LOG, root-cause into missing_rule/incomplete_rule/ignored_rule/novel_case/regression, fix, update the corresponding document (PRIORS/spec/agent definition), verify the updated rule would have caught the original failure. Since session 035 this is wired into code: plan domain_priors seed project PRIORS on first run, up to 8 priors are injected into lead prompts, an EvolutionEngine records auto-learning priors on loop DEAD_END/PLATEAU verdicts, and `zo learnings promote` does fail-closed sanitized promotion of generic learnings to platform memory. A retrospective protocol and evolution metrics (regression rate, coverage growth) are specified. Platform-side, the same protocol runs on ZO itself via CLAUDE.md's non-negotiable memory/docs cascade (validate-docs.sh hook blocks commits on doc drift). + +## Strengths + +- Oracle-first discipline that is enforced in code, not prose: gates check for actual artifacts (ZOTrainingCallback's metrics.jsonl/training_status.json, Oracle's result.md), a lesson learned after a Sonnet lead silently ignored aspirational contracts (PRIORS PR-035: 'enforcement > aspiration') +- Genuinely wired self-evolution loop (as of session 035): plan priors seed project memory, priors are injected into prompts, dead-ends/plateaus persist auto-learning priors, and a fail-closed sanitized promotion path moves generic learnings to platform memory without confidentiality risk +- Unusually honest empirical culture: the platform refuted its own 70-80% cost-savings claim with a measured benchmark (~30%, $7.75 MNIST run), documented the structural reason, and cascaded corrections through all docs — STATE.md and PRIORS read like a real lab notebook of verified fixes and refuted hypotheses +- Contract-first spawning with explicit ownership/off-limits/produced/consumed contracts per agent, preventing silent integration failures in parallel work +- Strong auditability and session recovery: append-only DECISION_LOG, STATE.md checkpointing with git_head verification, proven interrupt-resume (ACTIVE-phase resume bug found and fixed via a real prod-001 incident), portable .zo/ memory for cross-machine continuity +- The Phase 4 experiment capture layer + autonomous loop is a differentiated capability: hypothesis→config→metrics→result→next lineage with parent_id, dead-end detection via hypothesis similarity, plateau/budget stopping, and an auto-maintained checklist — closing the loop without human input in auto modes +- Rigorous confidentiality architecture for a public repo operating on private client projects: alias convention, gitignore enforcement, client-term blocklist, block-not-strip promotion +- Novel concurrent report sessions (surrogate model): an Opus report-lead runs in an isolated git worktree alongside a live model session with per-PID liveness locks and safe delta-memory consolidation — real multi-session concurrency on one project +- Strong platform engineering hygiene: 854 tests green on Python 3.11 and 3.12, ruff clean, a PreToolUse hook that blocks commits when docs drift from code, and documented cascade rules for every interface change +- Extension points (workflow resolution, orchestrator subclass, CLI entry-point plugins) already exercised by a real downstream plugin +- Comprehensive, opinionated ML workflow spec (60+ subtasks across 6 phases, 3 modes) encoding real research discipline: leakage denylists, purge-gap temporal splits, ablations, statistical significance, reproducibility verification + +## Gaps + +- No anti-stall mechanism implemented: specs/watchdog.md is an RFC only, written after a real ~38-hour silent stall in a long autonomous run — the event-driven orchestrator has a silent-death hole (all-idle team emits no wake signal; absence of errors read as progress), and a dedicated monitor agent would itself be a single point of failure +- Fragile execution substrate: ZO drives the Claude Code CLI as a tmux subprocess with paste-buffer prompt injection, pane-liveness polling, and a settings.local.json permissions overlay — multiple sessions were consumed fixing races in this layer (15ms premature teardown, TUI-ready misdetection selecting 'No, exit' on a consent dialog, cold-start paste timing), and the watcher was at one point 'more fragile than the thing it watches' +- Structural cost ceiling (~25-30% savings) without an SDK refactor: sub-agents are already on Sonnet, so --low-token only touches the lead's share; prompt caching, Batch API, and Files API are all unreachable from the CLI-launcher architecture and the refactor is deferred as a multi-week effort +- Recurring 'aspirational contracts get ignored' failure mode with incomplete enforcement coverage: known deferred items include semantic reindex at session end, an agent failure-reporting protocol, end_session DECISION_LOG/PRIORS integration, and a zo retrospective CLI (audit items #13/#15/#16/#17) — each past incident was hard-gated individually rather than via a systematic enforcement layer +- Workflow is a rigid linear DAG: no cross-phase backedges (RETURN_TO_PHASE primitive and weighted-graph refactor are roadmap items F3 Phase A/B only), so discovering mid-Phase-4 that features are wrong has no first-class path back to Phase 2 short of human intervention +- ML/research-specific: the entire workflow, agent roster, and oracle framing assume an ML/data pipeline; general software-engineering delivery is unproven (the planned software-engineer agent and optimization audit, Batch D, are not done), and oracles for non-quantifiable deliverables are unaddressed +- Thin validation base: two toy demos (MNIST, CIFAR-10) and one production project (prod-001), which is still at Phase 2 awaiting GPU work — memory-scale features (session-summary consolidation, incremental indexing, cross-project rule propagation, SONA routing) are all untested v2 triggers gated on 3-5+ projects that don't exist yet +- Single-project-per-session, no dashboard, no external integrations: monitoring is terminal-only (tmux + watch-training), human checkpoints require polling DECISION_LOG rather than notifications (Slack/GitHub integration is v2), and the VS Code extension is roadmap only +- Hard dependency on Claude Code's proprietary agent-teams capabilities (TeamCreate/Agent/SendMessage): multi-provider support was assessed and reframed to a limited worker-pool model because full peer-to-peer parity would require rebuilding that infrastructure on bare APIs +- Onboarding friction acknowledged but unaddressed: setup requires uv + Claude CLI + tmux + setup.sh; the planned one-line installer, Homebrew formula, and zo doctor command (Tier 1 'onboarding hardening') remain queued +- ZO violates its own coding conventions in its core: cli.py is ~3,400 lines against the stated 'files under 500 lines' rule, indicating the platform build has outgrown its module structure +- STATE.md and other memory files are hand-editable markdown parsed by code — a hand-edited invalid status previously crashed the orchestrator deep in restore (now validated at parse time, but the format remains a fragile human/machine dual-use interface) + +## Open Questions + +- When (and whether) to do the SDK refactor: switching from CLI-subprocess launching to the Anthropic SDK unlocks prompt caching, Batch API, Files API (70-80% cost target) and programmatic control that would eliminate the fragile tmux layer — but sacrifices the interactive tmux experience and Claude Code's native agent-teams; the roadmap sequences it after cost quick-wins but the substrate fragility argues for sooner +- How to implement the watchdog: the RFC requires an active wall-clock heartbeat independent of teammate messages plus liveness-by-evidence and auto-remediation — but where does the heartbeat live (orchestrator wrapper? cron? external process?) so it isn't itself a silent single point of failure? +- Is the RETURN_TO_PHASE backedge primitive (F3 Phase A) enough to validate cross-phase autonomy cheaply, or does credible autonomy require the full weighted-graph refactor with per-node completeness and revisit ranking (Phase B)? +- Tier 2 sequencing is explicitly unresolved and awaiting external-user signal (GitHub Discussions #81): VS Code extension (accessibility) vs cost work vs architecture-first (backedge → SDK refactor → extension) — which growth lever matters more depends on unconfirmed audience weighting (research peers / paying customers / internal) +- How to generalize beyond ML: what does the oracle framework mean for deliverables without a held-out metric (an API, a refactor, a report), and does the phase/gate structure survive translation to general software engineering? +- Can agent-contract enforcement become systematic rather than incident-driven — i.e., a generic mechanism that verifies any spawn-prompt contract's artifacts at gates, instead of hand-wiring a hard gate after each observed violation? +- Multi-provider worker pool: is the limited model (Claude Code lead + single-agent CodeX/OpenCode workers coordinating via filesystem JSONL) worth building, given full peer parity is off the table? +- Memory at scale is unvalidated: do the v2 triggers (summary consolidation at 100+ sessions, SONA routing at 3+ concurrent projects, pattern libraries at 5+ same-domain projects) hold up, and does the full-rebuild semantic index remain adequate? +- Self-evolution verification remains manual/informal: the protocol requires confirming an updated rule 'would have caught the original failure', but there is no mechanized regression test for rules — how should rule efficacy be tracked (the v2 evolution-confidence-scoring idea)? +- The human experience between gates is polling-based: what is the right notification/wakeup channel (Slack, push, email) and does adding it change the v1 'no external integrations' constraint? +- prod-001 is the only production validation vehicle and is paused at Phase 2 — does the platform's Phase 4/5 machinery (autonomous loop, training-checker, dead-end detection) hold up on a real non-toy dataset, and what priors does that run generate? diff --git a/memory/zo-platform/sessions/session-040-2026-08-12.md b/memory/zo-platform/sessions/session-040-2026-08-12.md new file mode 100644 index 0000000..8850205 --- /dev/null +++ b/memory/zo-platform/sessions/session-040-2026-08-12.md @@ -0,0 +1,65 @@ +# Session 040 — 2026-08-12 — Repo Deep-Dive Research (pre-rearchitecture) + +**Type:** Research session (no platform code changes, no commits) + +## What happened + +Sam requested a thorough review of three agent-orchestration repos to inform a +potential ZO rearchitecture. Cloned to `~/Documents/code/`: + +1. **oh-my-claudecode** (yeachan-heo) — 337K-line Claude Code plugin: hook-enforced + persistence modes, HUD, notifications, deliverable contracts +2. **ruflo** (ruvnet, claude-flow successor) — ~400K-line coordination ledger: + witness manifests, smoke-test CI, temporal memory; swarm layer largely theater +3. **ralph** (snarktank) — 113-line bash loop: fresh-context-per-story technique, + prd.json ledger, file-based memory + +Ran a 9-agent workflow (7 repo lenses + ZO baseline map + adversarial synthesis), +~1.06M tokens, 342 tool calls. All findings persisted to +`memory/zo-platform/research/2026-08-12-repo-reviews/` (per-repo markdown, +zo-baseline.md, synthesis.md, raw-findings.json). + +## Headline conclusions (full detail in research dir) + +- The three repos triangulate ZO's known weaknesses: missing deterministic + enforcement plane (OMC), unverified self-evolution loop (ruflo's witness + manifests fix this), fragile long-lived-session substrate (ralph's fresh-context + loop fixes this). +- 12 ranked adoption candidates; P0s: machine-checked deliverable contracts at + SubagentStop, watchdog from proven parts (heartbeat + never-block taxonomy + + rate-limit auto-resume), hook-enforced memory protocol, machine-readable + plan-ledger with oracle-owned pass flags. +- 6 rearchitecture themes; loudest: "enforcement plane below the prompt plane" + and "fresh-context, disk-state execution substrate". +- 11 anti-patterns to avoid (dead code as capability, self-asserted completion, + keyword-triggered orchestration, surface-area maximalism, verification theater). + +## Decision (same session) + +Sam reviewed the findings and decided: **adopt all 12 features.** Confirmed the +three pillars wanted: ralph's context management, ruflo's self-learning + +memory layer, OMC's execution power. Work organized into five layer-based +workstreams (enforcement plane / control plane / execution substrate / +self-learning & platform oracle / operator experience) rather than source-repo +categories — features from different repos interlock into single mechanisms. + +Shipped: +- `plans/zo-v2-rearchitecture.md` — 6 gated phases, 20-check tiered oracle, + anti-scope from the review's anti-pattern list (+ .gitignore exception) +- `docs/reference/v2-rearchitecture.mdx` — all 12 features, provenance, repo + links; added to mint.json Reference nav +- `docs/roadmap.mdx` — v2 section (4 pillars, repo credits, link to reference page) +- Website §11 "What's next" — 3 repo credit cards (compare/col pattern), + quick start renumbered §12, mobile drawer updated +- STATE.md session 040 entry, DECISION_LOG v2 decision, research README status + +Verification: HTML balance-checked + DOM-inspected via static server (no +Node.js on this machine — Astro build deferred to CI/deploy). validate-docs +pre-commit. + +## Next session + +Begin v2 Phase 1 (WS-A enforcement foundations) per plans/zo-v2-rearchitecture.md: +contracts.json emission at spawn, SubagentStop validation hook, drift-guard +regexes, PreCompact/SessionEnd/PostToolUseFailure memory hooks, disallowedTools +on verifiers, nonce approvals. diff --git a/plans/zo-v2-rearchitecture.md b/plans/zo-v2-rearchitecture.md new file mode 100644 index 0000000..55a49e8 --- /dev/null +++ b/plans/zo-v2-rearchitecture.md @@ -0,0 +1,160 @@ +# Zero Operators v2 Rearchitecture Plan + +--- +project_name: "zo-v2-rearchitecture" +version: "1.0" +created: "2026-08-12" +last_modified: "2026-08-12" +status: active +owner: "Sam" +--- + +## Objective + +Rearchitect Zero Operators around the four structural upgrades identified by the +2026-08-12 deep-dive review of three reference systems (see +`memory/zo-platform/research/2026-08-12-repo-reviews/`): + +1. **A deterministic enforcement plane below the prompt plane** — hooks that + mechanically guarantee what spawn prompts currently only promise + (influence: [oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode)) +2. **A machine-readable control plane beside the markdown memory** — progress, + gates, and completion become decidable state, with STATE.md/DECISION_LOG.md + as the human projection (influence: [ralph](https://github.com/snarktank/ralph)) +3. **A fresh-context, disk-state execution substrate** — the failure unit becomes + one iteration, not one 38-hour session (influence: ralph, hardened with + oh-my-claudecode's production scar tissue) +4. **An oracle for the platform itself** — the self-evolution loop's "this rule + would have caught the original failure" becomes a standing CI check + (influence: [ruflo](https://github.com/ruvnet/ruflo)) + +All 12 features from the review synthesis ship. Work is organized into five +**layer-based workstreams** (not source-repo categories — features from +different repos interlock into single mechanisms; the repo of origin is +provenance, not architecture). + +## Oracle + +**Primary metric:** All 12 features land with their per-feature acceptance +criteria passing, and a full demo project (demo-cifar10 rerun) executes +end-to-end with every new mechanism observably firing. + +**Ground truth source:** Per-feature seeded-failure tests (each enforcement +mechanism must catch a deliberately planted violation), the platform test +suite, and one full demo run + one production phase (prod-001) on the new +substrate. + +**Evaluation method — verification checks:** +1. A seeded contract violation (missing deliverable file) is blocked at SubagentStop +2. A seeded "completion claim + TODO stub in diff" is flagged by the drift guard +3. PreCompact hook flushes state before a forced compaction; STATE.md reflects it +4. PostToolUseFailure produces structured JSONL consumed by the priors pipeline +5. A forged gate approval (echoed tag without nonce) is rejected; a genuine nonce-tagged approval passes +6. oracle-qa/reviewers mechanically cannot Write/Edit (disallowedTools + PreToolUse); a seeded write attempt is blocked +7. A seeded edit to a sealed eval file is blocked +8. plan-ledger.json generated from plan.md; `zo status` renders from the ledger, not prose parsing +9. A builder attempt to flip `passes: true` is blocked; only oracle-qa's flip lands +10. Plan validation rejects a story with non-verifiable acceptance criteria (sizing lint) +11. An induced 10-minute stall in a test harness is detected by the watchdog and escalated within one poll cycle; a rate-limited session is NOT nudged (never-block taxonomy respected) +12. A rate-limit pause auto-resumes on reset in a controlled test +13. Phase 4 on the fresh-context loop completes demo-cifar10 with results ≥ v1 baseline (91.62%) and total cost ≤ 1.15× v1 baseline +14. Deleting a witness marker from code turns witness-verify red in CI +15. A seeded regression reproducing a PRIORS entry symptom turns its smoke script red +16. README/setup.sh/spec counts are generated from the filesystem; hand-editing a count without the source change turns validate-docs red +17. A refuted prior gets supersededBy front-matter; the digest regenerates; the full PRIORS file is NOT injected at session start (budget check) +18. A pending gate produces exactly one Slack/Telegram notification (cooldown respected); an "approve" reply round-trips into gate passage in a live session +19. `zo hud` renders phase/gate/agents/context from control-plane files only +20. Full demo project end-to-end with all mechanisms enabled: zero regressions in the 854-test platform suite, all new hooks observed firing in comms logs + +**Target threshold:** +- Tier 1 (must): checks 1–13 and 20 pass; platform suite green on 3.11 + 3.12; ruff clean; validate-docs 0 failures +- Tier 2 (should): checks 14–17 pass (platform oracle mechanized) +- Tier 3 (could): checks 18–19 pass (operator experience layer) + +**Evaluation frequency:** per-feature on PR (seeded-failure test required to +merge — "nothing ships unwired"); per-phase gate review; end-to-end at Phase 6. + +**Statistical significance:** Not applicable (deterministic system tests), +except check 13 which compares demo metrics against the recorded v1 baseline. + +## Workstreams (layer-based) + +| WS | Layer | Features (review rank) | Primary influence | +|----|-------|------------------------|-------------------| +| A | Enforcement plane | Deliverable contracts @ SubagentStop (#1) · Hook-enforced memory (#3) · Nonce approvals (#7) · Trustworthy verifiers (#9) | oh-my-claudecode | +| B | Control plane | plan-ledger.json + oracle-owned pass flags + context-window sizing lint (#4) | ralph + oh-my-claudecode | +| C | Execution substrate | Watchdog from proven parts (#2) · Fresh-context per-subtask loop (#6) | ralph + oh-my-claudecode + ruflo | +| D | Self-learning & platform oracle | Witness manifests + fixture regression (#5) · Smoke tests/ratchets/generated counts (#11) · PRIORS temporal semantics, quality gate, digest, budget (#12) | ruflo | +| E | Operator experience | Two-way notifications (#8) · ZO HUD (#10) | oh-my-claudecode | + +## Workflow + +**Mode:** platform build (same adapted structure as zero-operators-build.md) + +**Phase 1 — Enforcement foundations (WS-A, ~1–2 weeks)** +Contracts compile to `contracts.json` at spawn; SubagentStop validation hook; +workflow-drift-guard regexes; PreCompact/SessionEnd/PostToolUseFailure memory +hooks; disallowedTools on verifiers + sealed-paths PreToolUse check; nonce-tagged +gate approvals. Small, independent, and they de-risk every later phase. +*Gate: verification checks 1–7 pass.* + +**Phase 2 — Control plane (WS-B, ~1 week)** +Ledger generator from plan.md; oracle-owned write path; sizing lint in plan +validation; `zo status`/gates/loop-evaluator consume the ledger. STATE.md becomes +a projection for humans, never the parse target for control decisions. +*Gate: checks 8–10 pass.* + +**Phase 3 — Execution substrate (WS-C, ~2–3 weeks)** +Watchdog first (heartbeat JSON per agent + external checker in the +LifecycleWrapper poll loop, never-block taxonomy, bounded nudges, rate-limit +wait-and-resume, PID+start-time identity). Then the fresh-context loop for +Phase 4 of the ML workflow: experiment_loop.py spawns a fresh builder per +iteration re-deriving state from ledger + lineage + priors digest; git commit +as checkpoint; validated on demo-cifar10, then prod-001. +*Gate: checks 11–13 pass. Check 13 is the go/no-go for extending fresh-context +to other phases.* + +**Phase 4 — Self-learning & platform oracle (WS-D, ~2 weeks)** +PRIORS front-matter (id, status, supersededBy, marker) + three-question quality +gate + generated read-first digest + injection budget; witness-verify (Python, +no signature theater) wired into validate-docs.sh and CI; smoke/ dir with +per-prior reproduction scripts + meta-runner; frontmatter-completeness ratchet; +filesystem-derived counts replacing the hand-maintained cascade numbers. +*Gate: checks 14–17 pass.* + +**Phase 5 — Operator experience (WS-E, ~1–2 weeks)** +Outbound notifications (gate-pending, loop verdicts, watchdog alerts; cooldowns) +→ reply-listener with authorization/sanitization copied from OMC's posture → +`zo hud` statusline reading control-plane files. +*Gate: checks 18–19 pass.* + +**Phase 6 — Integration validation & retrospective (~1 week)** +Full demo end-to-end with everything enabled; 854-suite + new tests green on +3.11/3.12; retrospective feeding PRIORS; docs cascade. +*Gate: check 20 + Tier 1 threshold.* + +## Sequencing rationale + +Phases 1–2 are pure additions with no substrate risk and make every later phase +safer (contracts + ledger are what the watchdog and fresh-loop read). Phase 3 is +the only structural change and lands behind a demo-validated gate. Phase 4 is +independent of 3 and can run in parallel if capacity allows. Phase 5 is +deliberately last — it decorates state the earlier phases materialize. + +## Anti-scope (from the review's anti-pattern list) + +- No keyword-triggered orchestration; spawning stays explicit and imperative +- No hard-blocking Stop as the persistence foundation (fresh spawns + caps instead) +- No mechanism merges without a runtime caller and an observable test ("nothing ships unwired") +- No self-asserted completion anywhere: grading privilege is the oracle's +- No "cryptographic" labels on non-cryptographic guarantees +- Control-plane files live under the existing per-project memory root — no new state roots + +## Reference repositories + +- **oh-my-claudecode** — https://github.com/yeachan-heo/oh-my-claudecode (enforcement plane, watchdog parts, operator UX) +- **ruflo** — https://github.com/ruvnet/ruflo (witness manifests, smoke-test CI doctrine, temporal memory semantics) +- **ralph** — https://github.com/snarktank/ralph (fresh-context loop, task ledger, story sizing rule) + +Full findings: `memory/zo-platform/research/2026-08-12-repo-reviews/` (63 +features catalogued with evidence file paths, per-repo verdicts, synthesis). diff --git a/website/src/pages/index.html b/website/src/pages/index.html index 8a1d8ba..82ba2bf 100644 --- a/website/src/pages/index.html +++ b/website/src/pages/index.html @@ -68,7 +68,8 @@ 08Oracle & memory 09Different 10Where this came from - 11Quick start + 11What's next + 12Quick start
Docs → @@ -984,12 +985,69 @@

Where this came from.

+
+
+
+ 11What's next +

+ v2: the same oracle discipline,
+ on a harder substrate. +

+

+ We read the source of three open agent-orchestration systems end to end and + catalogued 63 features. Twelve are coming to ZO v2: a deterministic + enforcement plane under the prompts, a machine-readable control + plane beside the markdown memory, a fresh-context execution + substrate, and an oracle for the platform itself. The full + feature list and how each ships lives in the + v2 rearchitecture docs ↗. +

+
+ +
+
+ Execution power +

oh-my-claudecode

+
    +
  • Adoptinghook-enforced deliverable contracts & memory
    • +
  • Pluswatchdog parts: heartbeats, rate-limit auto-resume
    • +
  • Andtwo-way gate notifications, statusline HUD
    • +
  • Sourcegithub.com/yeachan-heo ↗
    • +
+
+
+ Self-learning & memory +

ruflo

+
    +
  • Adoptingwitness manifests: learned rules verified in CI
    • +
  • Plustemporal memory: supersede, never overwrite
    • +
  • Andsmoke tests born from real regressions
    • +
  • Sourcegithub.com/ruvnet ↗
    • +
+
+
+ Context management +

ralph

+
    +
  • Adoptingfresh context per iteration, state on disk
    • +
  • Plusa plan ledger with oracle-owned pass flags
    • +
  • Andevery task sized to one context window
    • +
  • Sourcegithub.com/snarktank ↗
    • +
+
+
+
+
+ +
- 11Quick start + 12Quick start

Four commands. Then walk away.