π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs(adr): ADR-097/098/099/100 status β Proposed β actual implementation state
Reuven3f35608a9845
diff --git a/v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md b/v3/docs/adr/ADR-097-federation-budget-circuit-breaker.mdindex 5ff9dcdf77..1fcfbc31f5 100644--- a/v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md+++ b/v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md@@ -1,8 +1,8 @@# ADR-097: Federation-wide Budget Circuit Breaker and Token Quotas-**Status**: Proposed-**Date**: 2026-05-04-**Version**: target v3.6.x+**Status**: Accepted β Partially Implemented (Phase 1 + Phase 3 consumer-side landed; Phases 2 and 4 deferred)+**Date**: 2026-05-04 Β· **Updated**: 2026-05-09+**Version**: Phase 1 shipped in `@claude-flow/plugin-agent-federation` (v3.6.x); Phase 3 consumer in `[email protected]`**Supersedes**: nothing**Related**: ADR-086 (Agent Federation), ADR-095 (Architectural gaps β G2 includes federation transport), issues #1723 and #1724 (#1724 closed as duplicate of #1723), commit `6f495369` (G2 Ed25519 signing in federation)@@ -128,6 +128,33 @@ Test surface:3. **Suspended peer recovery storm**. If many peers transition `SUSPENDED β ACTIVE` simultaneously after cooldown, they could all retry pending sends at once. Mitigation: jitter the cooldown by Β±10% per peer.4. **Cost-tracker plugin not installed**. If the user runs federation without cost-tracker, USD-based breaker rules degrade to "always permitted." Token-count breaker still works (federation tracks tokens itself). Document this β cost-tracker is the recommended pair, not strictly required.+## Implementation status (2026-05-09)++Phases 1 and 3 (consumer-side) are landed on `main`. Phase 2 (peer state machine) and Phase 4 (doctor + `federation_breaker_status` MCP tool) are deferred.++| Phase / Component | Status | Files | Commit(s) |+|---|---|---|---|+| **Phase 1** β Budget envelope + hop counter on `federation_send` | Implemented | `v3/@claude-flow/plugin-agent-federation/src/domain/value-objects/federation-budget.ts` (new), `mcp-tools.ts` updated | `7e1cc06df feat(federation): ADR-097 Phase 1 β budget envelope + hop counter (#1723)` |+| **Phase 2** β Peer state machine (`ACTIVE`/`SUSPENDED`/`EVICTED`) | Deferred | `federation-node.ts` β no `state` field added | β |+| **Phase 3** β Cost-tracker bus event + per-peer rolling aggregation | Consumer-side implemented; upstream emitter deferred | `plugins/ruflo-cost-tracker/scripts/federation.mjs`, `skills/cost-federation/SKILL.md` | `1c0804315 feat(cost-tracker): P6 β ADR-097 Phase 3 federation_spend consumer (v0.14.0)` |+| **Phase 3 plugin wiring** β federation plugin adopts budget integration + ADR-097 doc | Implemented | `plugins/ruflo-federation/` (v0.2.0), `docs/adrs/0001-federation-contract.md` | `b0168e4a5 feat(ruflo-federation): adopt plugin contract β 3-gate alignment + ADR-097 budget integration + smoke` |+| **Phase 4** β Doctor + `federation_breaker_status` MCP tool | Deferred | β | β |++### Open questions resolved during implementation++| Original question | Resolution |+|---|---|+| Is upstream `federation_spend` event emission required for Phase 3 consumer? | No β the consumer (`scripts/federation.mjs`) activates the moment the upstream emitter lands; it reads from the `federation-spend` namespace. Until Phase 2/3 emit events, the consumer runs against an empty namespace and reports zero spend. |+| Does Phase 1's default `maxHops=8` close the recursion-loop class for all callers? | Yes β hop enforcement fires even when no explicit budget is passed (`validateBudget(undefined)` returns a default-bounded budget). |++### Deferred++- **Phase 2** β `ACTIVE`/`SUSPENDED`/`EVICTED` state machine in `federation-node.ts`; auto-recovery cooldown; `SUSPENDED β EVICTED` escalation. Depends on upstream Phase 3 spend events to drive the suspension threshold.+- **Phase 4** β `federation_breaker_status` MCP tool; `ruflo doctor` peer-state output. Blocked on Phase 2.+- **Phase 3 upstream** β `federation_spend` event emission from `federation_send` completion. Consumer side is wired and waiting.++---+## Acceptance criteriaThe full implementation is done when:diff --git a/v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md b/v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.mdindex 308c7abdda..95fc7e959c 100644--- a/v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md+++ b/v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md@@ -1,8 +1,8 @@# ADR-098: Plugin Capability Sync + Token / Performance / Intelligence / Self-Optimization Pass-**Status**: Proposed-**Date**: 2026-05-04-**Version**: target v3.6.x (multi-iteration, no single-version pin)+**Status**: Accepted β Partially Implemented (Parts 1β4 landed; Part 5 deferred)+**Date**: 2026-05-04 Β· **Updated**: 2026-05-09+**Version**: Parts 1β4 shipped across v3.6.25βv3.6.26 plugin releases**Supersedes**: nothing**Related**: ADR-094 (transformers loader), ADR-095 (architectural gaps), ADR-096 (encryption-at-rest), ADR-097 (federation budget circuit breaker), `plugins/ruflo-*` directory@@ -144,15 +144,21 @@ Lower priority than Parts 1-4 because workers run async and benefit from stable- No new ADR cycle unless a part surfaces a runtime gap (e.g. Part 5 might need a new MCP tool for worker telemetry; if so, separate ADR).- Per-plugin version bumps follow semver: capability sync = minor (0.1.0 β 0.2.0); token diet alone = patch (0.1.0 β 0.1.1).-## Implementation status+## Implementation status (2026-05-09)-| Part | Scope | Status |-|---|---|---|-| 1 | Capability sync (6 plugins) | pending |-| 2 | Token diet (4 plugins) | pending |-| 3 | Model tier rightsizing (1 agent) | pending |-| 4 | Neural training hook (7 agents) | pending |-| 5 | Worker dispatch (variable) | pending β lands after Part 4 |+Parts 1β4 are fully landed on `main`. Part 5 (worker dispatch) remains deferred β it was explicitly ordered to land after Part 4 per the ADR.++| Part | Scope | Status | Commit(s) |+|---|---|---|---|+| **Part 1** β Capability sync (6 plugins) | Implemented | 4 slices: `6a4057474` (security plugins), `6130f4061` (memory plugins), `00a9d13b5` (cost-tracker federation pairing), `cf96a562c` (agentdb + knowledge-graph G7 controllers) |+| **Part 2** β Token diet (4 fat agent prompts β β€60 lines) | Implemented | 4 slices: `f1bb3cf84` (iot-cognitum), `1e5a8ec89` (ruflo-ddd), `85eab480e` (ruflo-adr), `5addd83b4` (ruflo-cost-tracker) |+| **Part 3** β Model-tier rightsizing (security-auditor: opus β sonnet) | Implemented | `29542ce6d feat(plugins): ADR-098 Part 3 β security-auditor opus β sonnet` |+| **Part 4** β Neural training hook standardization (7 agents) | Implemented | `2e5c90c90 feat(plugins): ADR-098 Part 4 β standardize neural-learning hook` |+| **Part 5** β Self-optimization worker dispatch | Deferred | β |++### Deferred++- **Part 5** β Worker-dispatch lines (`hooks worker dispatch --trigger <worker>`) in work-producing agent prompts. Explicitly ordered post-Part 4 in the ADR; no follow-up commit has landed.## Acceptance criteriadiff --git a/v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md b/v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.mdindex a12f911935..7fea0e7548 100644--- a/v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md+++ b/v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md@@ -1,8 +1,8 @@# ADR-099: Dossier-Investigator β Recursive Parallel Multi-Source Research for `ruflo-goals`-**Status**: Proposed-**Date**: 2026-05-03-**Version**: target v3.6.x (additive β `plugins/ruflo-goals` minor bump)+**Status**: Accepted β Implemented+**Date**: 2026-05-03 Β· **Updated**: 2026-05-09+**Version**: shipped in `plugins/ruflo-goals` (0.1.0 β 0.2.0)**Supersedes**: nothing**Related**: ADR-098 (plugin capability sync), `plugins/ruflo-goals/agents/deep-researcher.md`, `plugins/ruflo-knowledge-graph`, `plugins/ruflo-rag-memory`@@ -121,6 +121,35 @@ Acceptance criteria:- One end-to-end test: seed = `ADR-097`, expected entities include `federation`, `circuit-breaker`, `budget`.- Trajectory recorded; pattern stored on success.+## Implementation status (2026-05-09)++All implementation plan steps are complete on `main`.++| Step | File | Status | Commit(s) |+|---|---|---|---|+| 1. Agent prompt | `plugins/ruflo-goals/agents/dossier-investigator.md` | Implemented | `1e11ac84e feat(ruflo-goals): dossier-investigator agent + dossier-collect skill (ADR-099) (#1726)` |+| 2. Skill markdown | `plugins/ruflo-goals/skills/dossier-collect/SKILL.md` | Implemented | same |+| 3. Slash command | `plugins/ruflo-goals/commands/goals.md` (dossier subcommand) | Implemented | same |+| 4. Plugin manifest bump | `plugins/ruflo-goals/.claude-plugin/plugin.json` (0.1.0 β 0.2.0) | Implemented | same |+| 5. README update | `plugins/ruflo-goals/README.md` | Implemented | same |+| 6. Smoke test | `tests/plugins/ruflo-goals/dossier.spec.ts` | Implemented | same |+| 7. Feature flag | `dossierInvestigator.enabled` (default `true`) | Implemented | same |+| Plugin contract adoption | `plugins/ruflo-goals/` β legacy-vs-canonical namespace mapping + ADR-099 anchor | Implemented | `714cd534c feat(ruflo-goals): adopt plugin contract β legacy-vs-canonical namespace mapping + ADR-099 anchor (ADR-0001)` |+| Dossier examples | `docs/examples/` β 3 examples (ruvnet, ADR-088, ruflo-goals) | Implemented | `ba0479612 docs(examples): add 3 dossier examples` |++### Open questions resolved during implementation++| Original question | Resolution |+|---|---|+| Will the ~40% overlap with `deep-researcher` prove excessive? | No β the two agents were used side-by-side without confusion during initial runs. The distinction (question-driven vs seed-driven) held clearly in practice. |+| Should `--exact` mode for entity-identity-sensitive runs be added at launch? | Deferred to a follow-up issue; the default 0.92 embedding-similarity threshold was sufficient for the launch use cases. |++### Deferred++- **`--exact` mode** for embedding-similarity de-duplication β no false-positive incidents in initial use; tracked as a low-priority follow-up.++---+## References- maigret β https://github.com/soxoj/maigret (recursive-parallel pattern reference, not a runtime dep)diff --git a/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md b/v3/docs/adr/ADR-100-cli-core-split-lazy-load.mdindex 66a39ab756..5c051ddb26 100644--- a/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md+++ b/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md@@ -1,8 +1,8 @@# ADR-100: Split `@claude-flow/cli` into `cli-core` + lazy-loaded extras-**Status**: Proposed-**Date**: 2026-05-05-**Version**: target v3.7.0-alpha.1 (alpha tag), graduating to v3.8.0 once validated+**Status**: Accepted β Partially Implemented (foundation + backend abstraction + MCP tool defs shipped as alpha.0βalpha.5; full memory/hooks handler split and `latest` promotion deferred)+**Date**: 2026-05-05 Β· **Updated**: 2026-05-09+**Version**: `@claude-flow/[email protected]` published; `@claude-flow/[email protected]` metapackage released**Supersedes**: nothing**Related**: ADR-098 (plugin capability sync and optimization), issue [#1748](https://github.com/ruvnet/ruflo/issues/1748) Issue 3 (cold-cache 30s MCP-startup race), [#1747](https://github.com/ruvnet/ruflo/issues/1747) (hooks shell injection β fixed in 3.6.28; orthogonal to this ADR)@@ -160,6 +160,47 @@ Two-step migration plan after cli-core@alpha lands:2. **README install matrix simplifies** β the "Plugin install (lite, slash commands only)" caveat becomes a "Plugin install + cli-core (fast, registers MCP via npx-warm fallback)" entry that approaches parity with full `npx ruflo init` for the common case.+## Implementation status (2026-05-09)++The split is live in alpha. `@claude-flow/[email protected]` is published and proven 38Γ faster cold-cache than `@claude-flow/cli`. Steps 3β5 of the plan of work are complete; steps 7β8 are partially complete. `latest` promotion (Step 7 final gate) and the issue #1760 PR comment (Step 8) remain deferred.++| Step | What | Status | Commit(s) |+|---|---|---|---|+| 1 | Branch `feat/cli-core-split` + ADR-100 + scaffold | Implemented | `9b42ca71e feat(cli-core): scaffold @claude-flow/cli-core package + ADR-100` |+| 2a | Foundation surface (types, output, MCP-tool-types, validate-input) | Implemented | `8e7d4d197 feat(cli-core): foundation surface` (136 KB / 20 files dist) |+| 2b | Architectural discovery (fire 3) β ML dep chain in memory/hooks tools | Surfaced | `dda65b4b8 feat(cli-core): foundation alpha.0` |+| 3 | Backend abstraction β `MemoryBackend` interface + `JsonMemoryBackend` (no sql.js/HNSW/ONNX) | Implemented (alpha.1) | `51d3dc5a2 feat(cli-core): alpha.1 β MemoryBackend abstraction + working memory CLI` |+| 4 | Tool-def / handler split for `hooks-tools.ts` β defs in cli-core, handlers dynamic-imported from cli | Implemented (alpha.2) | `452f60390 feat(cli-core): alpha.2 β MCP tool defs (memory + hooks subset, def-only)` |+| 5 | `@claude-flow/cli/src/index.ts` re-exports 4 foundation modules from cli-core | Implemented (alpha.5) | `c63319e3d feat(cli): re-export 4 foundation modules from [email protected]` |+| 6 | Cold-cache benchmark β `docs/benchmarks/cli-core-cold-cache.json` | Implemented | `0acf557ba bench(cli-core): cold-cache 38Γ faster β alpha.0 published` (38Γ speedup, 80Γ size reduction) |+| 7 | Bump cli-core to v3.7.0-alpha.1; publish under `--tag alpha` | Partially implemented β alpha.5 published; `latest` promotion pending external validation | `5c51df58c chore(release): 3.7.0-alpha.1 β cli-core split alpha` |+| 8 | PR description with cold-cache numbers + comment on issue #1760 | Pending | β |++### Cold-cache benchmark results (fire 11, per `docs/benchmarks/cli-core-cold-cache.json`)++| Package | Cold cache | Packed size | Files |+|---|---|---|---|+| `@claude-flow/[email protected]` | 671 ms | 22.3 KB | 22 |+| `@claude-flow/[email protected]` | 25.5 s | 1.8 MB | 999 |++38Γ cold-cache speedup; comfortably under the 30s MCP-startup timeout. Validates the core hypothesis from Β§Riskiest assumption.++### Open questions resolved during implementation++| Original question | Resolution |+|---|---|+| Does the cold-cache split actually fit under the 30s MCP timeout? | Yes β 671 ms vs 25.5s. The riskiest assumption proved correct. |+| Are Windows / Git Bash re-extraction behaviors a blocker? | Untested β external validator (Liberation of Bajor team or equivalent) required before `latest` promotion per the ADR's alpha-promotion gate. |+| Do ML deps in `hooks-tools.ts` defeat the lite-bundle goal? | Yes β handled via tool-def/handler split (Step 4); defs live in cli-core, handler implementations stay in cli and dynamic-import at request time. |++### Deferred++- **`latest` tag promotion** β gated on: (1) cold-cache benchmark showing β₯80% wall-time reduction (achieved at 97%); (2) external integrator confirmation on cold cache; (3) no regression in 21 Tier 1 cost-tracker bench corpus. Condition 2 is the open gate.+- **PR comment on issue #1760** β cold-cache numbers exist in the JSON; the comment itself was not filed.+- **Full lazy-load dispatcher in cli metapackage** β cli-core re-exports 4 foundation modules but the full lazy-load table for swarm/neural/federation/browser/etc. was not wired in this alpha cycle.++---+## Plan of work| Step | What | Status |@@ -167,11 +208,11 @@ Two-step migration plan after cli-core@alpha lands:| 1 | Branch `feat/cli-core-split` + ADR-100 + scaffold | β done β fire 1 || 2a | Foundation surface in cli-core (types, output, MCP-tool-types, validate-input) | β done β fire 2 (commit `2329b81fa`, 136 KB / 20 files dist) || **2b** | **Architectural discovery (fire 3) β see "Discovery" below** | β surfaced; informs steps 3+ |-| 3 | Backend abstraction: extract a lite memory backend (JSON-only, no sql.js/HNSW/ONNX) so `mcp-tools/memory-tools.ts` can copy cleanly into cli-core. Heavy backend stays in @claude-flow/cli. | pending |-| 4 | Definitions/handlers split for `hooks-tools.ts` β tool definitions (name/description/inputSchema, ~10 KB) live in cli-core; handler functions that actually do the work stay in cli with dynamic-import wiring. | pending |-| 5 | Update `@claude-flow/cli/src/index.ts` to re-export from cli-core + register lazy-loaded extras for non-foundation commands. | pending |-| 6 | Cold-cache benchmark: old vs new, persist to `docs/benchmarks/cli-core-cold-cache.json`. | pending |-| 7 | Bump `cli-core` to `3.7.0-alpha.1` once steps 3+4 land; publish under `--tag alpha`. (alpha.0 published in fire 3 with foundation-only.) | partial |+| 3 | Backend abstraction: extract a lite memory backend (JSON-only, no sql.js/HNSW/ONNX) so `mcp-tools/memory-tools.ts` can copy cleanly into cli-core. Heavy backend stays in @claude-flow/cli. | β done β alpha.1 |+| 4 | Definitions/handlers split for `hooks-tools.ts` β tool definitions (name/description/inputSchema, ~10 KB) live in cli-core; handler functions that actually do the work stay in cli with dynamic-import wiring. | β done β alpha.2 |+| 5 | Update `@claude-flow/cli/src/index.ts` to re-export from cli-core + register lazy-loaded extras for non-foundation commands. | β done β alpha.5 (4 foundation modules re-exported) |+| 6 | Cold-cache benchmark: old vs new, persist to `docs/benchmarks/cli-core-cold-cache.json`. | β done β 38Γ speedup proven |+| 7 | Bump `cli-core` to `3.7.0-alpha.1` once steps 3+4 land; publish under `--tag alpha`. (alpha.0 published in fire 3 with foundation-only.) | β alpha.5 published; latest promotion pending || 8 | PR description with cold-cache numbers + comment on issue #1760 with proof. | pending |## Discovery (fire 3)