π 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: add comprehensive user documentation with guides, tutorials, and diagrams
Claudee5ca9411cd26
diff --git a/v3/@claude-flow/guidance/README.md b/v3/@claude-flow/guidance/README.mdindex 4aed940854..505939ce49 100644--- a/v3/@claude-flow/guidance/README.md+++ b/v3/@claude-flow/guidance/README.md@@ -1,10 +1,38 @@# @claude-flow/guidance-An operating system for agent autonomy. Not more prompt rules β a governance substrate that makes long-running AI agents safe, auditable, and self-correcting.+A governance control plane for Claude Code agents built on top of the memory system Claude Code already uses: `CLAUDE.md` and `CLAUDE.local.md`.-The guidance control plane sits *beside* Claude Code (not inside it). It compiles policy from CLAUDE.md, retrieves the right rules at the right time, enforces them through unavoidable gates, proves every decision cryptographically, and evolves the rule set through simulation and staged rollout. The result: agents that can operate for days instead of minutes, because the system removes the reasons autonomy must be limited.+## How Claude Code Memory Works-Most agent frameworks make models smarter. This makes autonomy survivable.+In Claude Code, both `CLAUDE.md` and `CLAUDE.local.md` are "memory" β text files that get loaded into the agent's working context at session start. They serve different audiences:++| File | Scope | Purpose |+|------|-------|---------|+| **CLAUDE.md** | Team / repo | Shared guidance: architecture, workflows, build commands, coding standards, domain rules. Lives at `./CLAUDE.md` or `./.claude/CLAUDE.md`. Committed to git. |+| **CLAUDE.local.md** | Individual / machine | Private notes: local sandbox URLs, test data, machine quirks, personal preferences. Auto-added to `.gitignore` by Claude Code. Stays local. |++**How they get loaded:** Claude Code searches upward from the current working directory and loads every `CLAUDE.md` and `CLAUDE.local.md` it finds on the path. In monorepos and nested projects, child directories can have their own files that layer on top of parent ones. It also discovers additional `CLAUDE.md` files in subtrees as it reads files there.++**The @import pattern:** For "local" instructions that work cleanly across multiple git worktrees, you can use `@` imports inside `CLAUDE.md` that point to a file in each developer's home directory:++```markdown+# Individual Preferences+@~/.claude/my_project_instructions.md+```++**Verification:** Run `/memory` in Claude Code to see which files were loaded. You can test by placing a unique rule in each file and asking Claude to restate both.++## What This Package Does++The guidance control plane takes these plain-text memory files and turns them into a structured, enforceable, auditable governance system:++1. **Compiles** `CLAUDE.md` + `CLAUDE.local.md` into a typed policy bundle β a constitution (always-loaded invariants) plus task-scoped rule shards+2. **Retrieves** the right subset of rules at task start, based on intent classification+3. **Enforces** rules through gates that cannot be bypassed β the model can forget a rule; the gate does not+4. **Proves** every decision cryptographically with hash-chained envelopes+5. **Evolves** the rule set through simulation, staged rollout, and automatic promotion of winning experiments from `CLAUDE.local.md` to root `CLAUDE.md`++The result: agents that can operate for days instead of minutes, because the system removes the reasons autonomy must be limited.## Architecture@@ -71,9 +99,49 @@ graph TBstyle Evolve fill:#2d6a4f,stroke:#52b788,color:#e8e8e8```+## How CLAUDE.md Becomes Enforceable Policy++```mermaid+graph LR+ subgraph "Your repo"+ A["CLAUDE.md<br/>(team rules)"]+ B["CLAUDE.local.md<br/>(your overrides)"]+ end++ subgraph "Compile (once per session)"+ A --> C[GuidanceCompiler]+ B --> C+ C --> D["Constitution<br/>(always-loaded invariants)"]+ C --> E["Shards<br/>(task-scoped rules)"]+ C --> F["Manifest<br/>(machine-readable index)"]+ end++ subgraph "Run (per task)"+ G[Task description] --> H[ShardRetriever]+ E --> H+ D --> H+ H --> I["Inject into agent context"]+ I --> J[EnforcementGates]+ J --> K{allow / deny / warn}+ end++ subgraph "Evolve (periodic)"+ L[RunLedger] --> M[Optimizer]+ M -->|promote| A+ M -->|demote| A+ end+```++The compiler splits `CLAUDE.md` into two parts:++- **Constitution** β The first ~30-60 lines of always-loaded invariants. These are injected into every task regardless of intent.+- **Shards** β Task-scoped rules tagged by intent (bug-fix, feature, refactor), risk class, domain, and tool class. Only relevant shards are retrieved per task, keeping context lean.++`CLAUDE.local.md` overlays the root. The optimizer watches which local experiments reduce violations and promotes winners to root `CLAUDE.md`, generating an ADR for each change.+## What It Does-28 modules across 7 layers:+29 modules across 7 layers:| Layer | Component | Purpose ||-------|-----------|---------|@@ -145,6 +213,51 @@ const results = kernel.batchProcess([| Secret scan (clean) | 402k/s | 676k/s | 1.68x || Secret scan (dirty) | 185k/s | 362k/s | 1.96x |+## CLAUDE.md vs. CLAUDE.local.md β What Goes Where++### CLAUDE.md (team shared, committed to git)++```markdown+# Architecture+This project uses a layered architecture. See docs/architecture.md.++# Build & Test+Always run `npm test` before committing. Use `npm run build` to type-check.++# Coding Standards+- No `any` types. Use `unknown` if the type is truly unknown.+- All public functions require JSDoc.+- Prefer `const` over `let`. Never use `var`.++# Domain Rules+- Never write to the `users` table without a migration.+- API responses must include `requestId` for tracing.+```++### CLAUDE.local.md (personal, stays local)++```markdown+# My Environment+- Local API: http://localhost:3001+- Test DB: postgres://localhost:5432/myapp_test+- I use pnpm, not npm++# Preferences+- I prefer tabs over spaces (don't enforce on the team)+- Show me git diffs before committing+```++### The @import alternative++If you use multiple git worktrees, `CLAUDE.local.md` gets awkward because each worktree needs its own copy. Use `@` imports instead:++```markdown+# In your committed CLAUDE.md:+@~/.claude/my_project_instructions.md+```++Each developer's personal file lives in their home directory and works across all worktrees.+## Why This Is Not a FeatureThe gains are not "better answers." They are less rework, fewer runaway loops, and higher uptime autonomy. You are not improving output quality. You are removing the reasons autonomy must be limited. That creates compounding gains.@@ -689,7 +802,7 @@ Lead with deterministic tools + replay + continue gate. Sell memory governance a## Test Suite-1,008 tests across 21 test files.+1,088 tests across 24 test files.```bashnpm test # run all tests@@ -717,9 +830,12 @@ npm run test:coverage # with coverage| manifest-validator | 59 | Fails-closed admission, risk scoring, lane selection || conformance-kit | 42 | Memory Clerk test, replay verification, proof integrity || trust | 99 | Accumulation, decay, tiers, rate multipliers, ledger export/import |-| truth-anchors | 61 | Anchor signing, verification, supersession, conflict resolution |-| uncertainty | 74 | Belief status, evidence tracking, decay, aggregation, inference chains |+| truth-anchors | 89 | Anchor signing, verification, supersession, conflict resolution |+| uncertainty | 83 | Belief status, evidence tracking, decay, aggregation, inference chains || temporal | 98 | Bitemporal windows, supersession, retraction, reasoning, timelines |+| continue-gate | 42 | Decision paths, cooldown bypass, budget slope, rework ratio |+| wasm-kernel | 15 | Output parity JS/WASM, 10k event throughput, batch API |+| benchmark | 23 | Performance benchmarks across 11 modules |## ADR Indexdiff --git a/v3/@claude-flow/guidance/docs/guides/architecture-overview.md b/v3/@claude-flow/guidance/docs/guides/architecture-overview.mdindex 29783748f1..dd95cd96e7 100644--- a/v3/@claude-flow/guidance/docs/guides/architecture-overview.md+++ b/v3/@claude-flow/guidance/docs/guides/architecture-overview.md@@ -1,6 +1,37 @@# Architecture Overview-The Guidance Control Plane is organized into 7 layers plus a WASM acceleration kernel. Each layer depends only on the layers below it.+## Starting Point: CLAUDE.md as Memory++In Claude Code, `CLAUDE.md` and `CLAUDE.local.md` are loaded into the agent's working context as raw text. The agent reads them and tries to follow them. This works for simple rules but breaks down at scale:++- The agent can forget rules mid-session+- There's no enforcement β violations are silent+- There's no audit trail β you can't prove what happened+- Rules don't evolve β stale guidance accumulates+- In multi-agent systems, there's no access control over shared memory++The Guidance Control Plane takes these files and turns them into structured, enforceable policy with 7 layers of protection.++## How Guidance Files Are Discovered++```mermaid+graph TD+ CWD["Working directory<br/>/repo/packages/api"] -->|search upward| P1["./CLAUDE.md"]+ CWD -->|search upward| P2["./CLAUDE.local.md"]+ P1 -->|parent| P3["/repo/packages/CLAUDE.md"]+ P3 -->|parent| P4["/repo/CLAUDE.md"]+ P4 -->|"@ import"| P5["~/.claude/my_instructions.md"]++ P4 --> Compiler+ P3 --> Compiler+ P1 --> Compiler+ P2 --> Compiler+ P5 --> Compiler++ Compiler --> Bundle["PolicyBundle<br/>(constitution + shards + manifest)"]+```++Claude Code searches upward from the current directory. Each level can add or override rules. `CLAUDE.local.md` overlays at the same level. The `@import` pattern pulls in files from outside the repo.## Layer Diagram@@ -189,9 +220,9 @@ These modules operate across all layers:```mermaidgraph LR- subgraph "Compile Time (once)"- MD[CLAUDE.md] --> C[Compiler]- LMD[CLAUDE.local.md] --> C+ subgraph "Compile Time (once per session)"+ MD["CLAUDE.md<br/>(team rules)"] --> C[Compiler]+ LMD["CLAUDE.local.md<br/>(your overrides)"] --> CC --> PB[PolicyBundle]PB --> R[Retriever: load shards]PB --> G[Gates: set active rules]@@ -207,11 +238,13 @@ graph LRsubgraph "Evolution (periodic)"L[Ledger events] --> O[Optimizer]- O --> P[Promote/demote rules]- P --> MD+ O -->|promote local winners| MD+ O -->|demote ineffective rules| MDend```+The key lifecycle: `CLAUDE.md` is compiled once at session start. Rules are retrieved per task. The optimizer watches run outcomes and proposes changes back to `CLAUDE.md`, generating an ADR for each change. `CLAUDE.local.md` experiments that consistently reduce violations get promoted to the shared root.+## ADR Index| ADR | Title |diff --git a/v3/@claude-flow/guidance/docs/guides/getting-started.md b/v3/@claude-flow/guidance/docs/guides/getting-started.mdindex 90f409e23b..2fb8903ac7 100644--- a/v3/@claude-flow/guidance/docs/guides/getting-started.md+++ b/v3/@claude-flow/guidance/docs/guides/getting-started.md@@ -1,6 +1,26 @@# Getting Started with @claude-flow/guidance-The Guidance Control Plane sits beside Claude Code (not inside it) to compile, retrieve, enforce, and evolve the rules that govern agent behavior.+## Background: How Claude Code Uses Memory Files++In Claude Code, `CLAUDE.md` and `CLAUDE.local.md` are loaded into the agent's working context at session start. They are the primary mechanism for telling Claude Code how to behave on your project:++| File | Who it's for | Committed? |+|------|-------------|-----------|+| `CLAUDE.md` | The whole team | Yes |+| `CLAUDE.local.md` | You, on this machine | No (auto-gitignored) |++Claude Code searches **upward** from the current directory and loads every instance it finds. In a monorepo, a child directory's `CLAUDE.md` layers on top of the root's. Run `/memory` in Claude Code to see which files were loaded.++The `@import` pattern offers an alternative to `CLAUDE.local.md` for developers using multiple git worktrees:++```markdown+# In CLAUDE.md (committed):+@~/.claude/my_project_instructions.md+```++## What This Package Adds++The Guidance Control Plane takes these plain-text files and turns them into structured, enforceable, auditable policy. Without it, Claude Code loads `CLAUDE.md` as raw text and relies on the model to follow it. With it, rules become typed objects with gates that block violations before they execute.## Installation@@ -17,18 +37,20 @@ import { createGuidanceControlPlane } from '@claude-flow/guidance';const plane = createGuidanceControlPlane({rootGuidancePath: './CLAUDE.md',+ localGuidancePath: './CLAUDE.local.md', // optional, your personal overrides});await plane.initialize();```-This reads your `CLAUDE.md`, compiles it into a policy bundle (constitution + rule shards + manifest), and prepares all subsystems.+This reads both files, compiles them into a policy bundle (constitution + rule shards + manifest), and prepares all subsystems.## What Happens at Initialization-1. **Compile** β `CLAUDE.md` is parsed into structured rules. Each rule gets an ID, risk class, domain tags, tool class tags, and intent tags.-2. **Shard** β Rules are broken into task-scoped shards. The always-loaded invariants form the constitution (first ~30-60 lines). Everything else becomes retrievable shards.-3. **Index** β Shards are loaded into the retriever for similarity-based lookup.-4. **Activate gates** β Enforcement gates are configured from the compiled rules.+1. **Load** β `CLAUDE.md` is read as the root guidance. `CLAUDE.local.md` (if present) is read as an overlay. Local rules supplement or override root rules.+2. **Compile** β Both files are parsed into structured rules. Each rule gets an ID, risk class, domain tags, tool class tags, and intent tags.+3. **Shard** β Rules are broken into task-scoped shards. The always-loaded invariants form the constitution (first ~30-60 lines of the root file). Everything else becomes retrievable shards.+4. **Index** β Shards are loaded into the retriever for similarity-based lookup.+5. **Activate gates** β Enforcement gates are configured from the compiled rules.## Core Loop@@ -78,15 +100,59 @@ const trust = createTrustSystem();All 20 modules are available as separate entry points. See the [API Reference](../reference/api-quick-reference.md) for the full list.-## Local Overrides+## CLAUDE.md vs. CLAUDE.local.md++### What goes in CLAUDE.md (shared, committed)++Team-level guidance everyone benefits from:++```markdown+# Build & Test+Run `npm test` before committing. Run `npm run build` to type-check.++# Coding Standards+- No `any` types. Use `unknown` when the type is truly unknown.+- All public functions require JSDoc.++# Architecture+This project uses a layered architecture. See docs/architecture.md.++# Domain Rules+- Never write to the `users` table without a migration.+- API responses must include `requestId` for tracing.+```++### What goes in CLAUDE.local.md (private, not committed)++Machine-specific or personal notes:++```markdown+# My Environment+- Local API: http://localhost:3001+- Test DB: postgres://localhost:5432/myapp_test++# Preferences+- Show git diffs before committing+- I prefer verbose error messages+```++### The @import alternative for worktrees-`CLAUDE.local.md` acts as an experiment sandbox. Rules defined there overlay the root constitution and can be promoted to root by the optimizer:+If you use multiple git worktrees, `CLAUDE.local.md` is awkward because each worktree needs its own copy. The `@` import pattern inside `CLAUDE.md` points to a shared file in your home directory:++```markdown+@~/.claude/my_project_instructions.md+```++### How the optimizer uses both files++The optimizer watches which `CLAUDE.local.md` experiments reduce violations. When a local rule consistently outperforms the root, the optimizer proposes promoting it to `CLAUDE.md` with an ADR:```ts-const plane = createGuidanceControlPlane({- rootGuidancePath: './CLAUDE.md',- localGuidancePath: './CLAUDE.local.md',-});+const optimized = await plane.optimize();+// optimized.promoted β rules moved from local to root+// optimized.demoted β ineffective root rules flagged+// optimized.adrsCreated β decision records```## WASM Acceleration@@ -139,6 +205,28 @@ No configuration needed. The bridge detects WASM availability at load time.adrs/ # Architecture Decision Records (G001-G025)```+## Verification++To confirm both files are being loaded and enforced:++1. Add a unique rule to `CLAUDE.md`: `# Test: Always respond in English`+2. Add a different rule to `CLAUDE.local.md`: `# Test: Prefer bullet points`+3. Start Claude Code and run `/memory` β both files should appear as loaded+4. Ask Claude to restate each unique rule to confirm both were applied++Then, initialize the guidance control plane and confirm:++```ts+const plane = createGuidanceControlPlane({+ rootGuidancePath: './CLAUDE.md',+ localGuidancePath: './CLAUDE.local.md',+});+await plane.initialize();+const bundle = plane.getBundle();+console.log(bundle.constitution.length); // > 0+console.log(bundle.shards.length); // > 0+```+## Next Steps- [Architecture Overview](./architecture-overview.md) β How the 7 layers connect