🌊 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: update README and API reference with generators, analyzer, and validation suite
Claude2810c8bdc452
diff --git a/v3/@claude-flow/guidance/README.md b/v3/@claude-flow/guidance/README.mdindex 505939ce49..3a23431431 100644--- a/v3/@claude-flow/guidance/README.md+++ b/v3/@claude-flow/guidance/README.md@@ -141,7 +141,7 @@ The compiler splits `CLAUDE.md` into two parts:## What It Does-29 modules across 7 layers:+31 modules across 9 layers:| Layer | Component | Purpose ||-------|-----------|---------|@@ -173,6 +173,15 @@ The compiler splits `CLAUDE.md` into two parts:| **Bridge** | `RuvBotGuidanceBridge` | Wires ruvbot events to guidance hooks, AIDefence gate, memory adapter || **WASM Kernel** | `guidance-kernel` | Rust→WASM policy kernel: SHA-256, HMAC, secret scanning, shard scoring || | `WasmKernel` bridge | Auto-fallback host bridge with batch API for minimal boundary crossings |+| **Generate** | `generateClaudeMd` | Scaffold CLAUDE.md from a project profile |+| | `generateClaudeLocalMd` | Scaffold CLAUDE.local.md from a local profile |+| | `generateSkillMd` / `generateAgentMd` | Scaffold skill definitions and agent manifests |+| | `scaffold` | Full project scaffolding with CLAUDE.md, agents, and skills |+| **Analyze** | `analyze` | 6-dimension scoring: Structure, Coverage, Enforceability, Compilability, Clarity, Completeness |+| | `autoOptimize` | Iterative score improvement with patch application |+| | `optimizeForSize` | Context-size-aware optimization (compact / standard / full) |+| | `headlessBenchmark` | Headless `claude -p` benchmarking with proof chain |+| | `validateEffect` | Empirical behavioral validation with Pearson r, Spearman ρ, Cohen's d |## WASM Policy Kernel@@ -756,6 +765,144 @@ if (rollout.currentStage === 'full' && rollout.divergence < 0.01) {</details>+### Generators (CLAUDE.md Scaffolding)++```typescript+import {+ generateClaudeMd,+ generateClaudeLocalMd,+ generateSkillMd,+ generateAgentMd,+ generateAgentIndex,+ scaffold,+} from '@claude-flow/guidance/generators';++// Generate a CLAUDE.md from a project profile+const claudeMd = generateClaudeMd({+ name: 'my-api',+ stack: ['TypeScript', 'Node.js', 'PostgreSQL'],+ buildCommand: 'npm run build',+ testCommand: 'npm test',+ lintCommand: 'npm run lint',+ architecture: 'layered',+ securityRules: ['No hardcoded secrets', 'Validate all input'],+ domainRules: ['All API responses include requestId'],+});++// Generate a CLAUDE.local.md for local dev+const localMd = generateClaudeLocalMd({+ name: 'Alice',+ localApiUrl: 'http://localhost:3001',+ testDbUrl: 'postgres://localhost:5432/mydb_test',+ preferences: ['Prefer verbose errors', 'Show git diffs'],+});++// Full project scaffolding+const result = scaffold({+ profile: myProjectProfile,+ agents: [{ name: 'coder', role: 'Implementation' }],+ skills: [{ name: 'typescript', description: 'TypeScript patterns' }],+ outputDir: './scaffold-output',+});+```++### Analyzer (Scoring, Optimization, Validation)++The analyzer provides a 6-dimension scoring system, automatic optimization, and empirical behavioral validation:++| Dimension | Weight | What It Measures |+|-----------|--------|------------------|+| **Structure** | 20% | Headings, sections, hierarchy, organization |+| **Coverage** | 20% | Build, test, security, architecture, domain rules |+| **Enforceability** | 25% | NEVER/ALWAYS/MUST statements, absence of vague language |+| **Compilability** | 15% | Can be parsed into a valid PolicyBundle |+| **Clarity** | 10% | Code blocks, tables, tool mentions, formatting |+| **Completeness** | 10% | Breadth of topic coverage across standard areas |++```typescript+import {+ analyze, benchmark, autoOptimize, optimizeForSize,+ headlessBenchmark, validateEffect,+ formatReport, formatBenchmark,+} from '@claude-flow/guidance/analyzer';++// 1. Score a CLAUDE.md file+const result = analyze(claudeMdContent);+console.log(result.compositeScore); // 0-100+console.log(result.grade); // A/B/C/D/F+console.log(result.dimensions); // 6 dimension scores+console.log(result.suggestions); // actionable improvements+console.log(formatReport(result)); // formatted report++// 2. Compare before/after+const bench = benchmark(originalContent, optimizedContent);+console.log(bench.delta); // score improvement+console.log(bench.improvements); // dimensions that improved+console.log(formatBenchmark(bench));++// 3. Auto-optimize with iterative patches+const optimized = autoOptimize(poorContent);+console.log(optimized.optimized); // improved content+console.log(optimized.appliedSuggestions); // patches applied+console.log(optimized.benchmark.delta); // score gain++// 4. Context-size-aware optimization (compact/standard/full)+const sized = optimizeForSize(content, {+ contextSize: 'compact', // 80 lines | 'standard' (200) | 'full' (500)+ targetScore: 90,+ maxIterations: 10,+ proofKey: 'audit-key', // optional proof chain+});+console.log(sized.optimized); // fits within line budget+console.log(sized.appliedSteps); // optimization steps taken+console.log(sized.proof); // proof envelopes (if proofKey set)++// 5. Headless Claude benchmarking (claude -p integration)+const headless = await headlessBenchmark(originalMd, optimizedMd, {+ executor: myExecutor, // or uses real `claude -p` by default+ proofKey: 'bench-key',+});+console.log(headless.before.suitePassRate);+console.log(headless.after.suitePassRate);+console.log(headless.delta);++// 6. Empirical behavioral validation+// Proves that higher scores produce better agent behavior+const validation = await validateEffect(originalMd, optimizedMd, {+ executor: myContentAwareExecutor, // varies behavior per CLAUDE.md+ trials: 3, // multi-run averaging+ proofKey: 'validation-key', // tamper-evident audit trail+});+console.log(validation.correlation.pearsonR); // score-behavior correlation+console.log(validation.correlation.spearmanRho); // rank correlation+console.log(validation.correlation.cohensD); // effect size+console.log(validation.correlation.effectSizeLabel); // negligible/small/medium/large+console.log(validation.correlation.verdict); // positive-effect / negative-effect / no-effect / inconclusive+console.log(validation.before.adherenceRate); // behavioral compliance (0-1)+console.log(validation.after.adherenceRate); // improved compliance+console.log(validation.report); // full formatted report+```++**Content-aware executors** implement `IContentAwareExecutor` — they receive the CLAUDE.md content via `setContext()` before each validation phase, allowing their responses to vary based on the quality of guidance loaded. This is what makes the empirical proof meaningful.++```typescript+import type { IContentAwareExecutor } from '@claude-flow/guidance/analyzer';++class MyExecutor implements IContentAwareExecutor {+ private rules: string[] = [];++ setContext(claudeMdContent: string): void {+ // Parse loaded CLAUDE.md to determine how to behave+ this.rules = claudeMdContent.match(/\b(NEVER|ALWAYS|MUST)\b.+/g) || [];+ }++ async execute(prompt: string, workDir: string) {+ // Vary response quality based on loaded rules+ // ...+ }+}+```+## Per-Module Impact| # | Module | Key Metric | Improvement |@@ -802,7 +949,7 @@ Lead with deterministic tools + replay + continue gate. Sell memory governance a## Test Suite-1,088 tests across 24 test files.+1,290 tests across 26 test files.```bashnpm test # run all tests@@ -836,6 +983,8 @@ npm run test:coverage # with coverage| 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 |+| generators | 68 | CLAUDE.md scaffolding, profiles, skills, agents, full scaffold |+| analyzer | 134 | 6-dimension scoring, optimization, headless benchmarking, empirical validation, Pearson/Spearman/Cohen's d, content-aware executors, proof chains |## ADR Indexdiff --git a/v3/@claude-flow/guidance/docs/reference/api-quick-reference.md b/v3/@claude-flow/guidance/docs/reference/api-quick-reference.mdindex ba1e25d01a..ace5e6226f 100644--- a/v3/@claude-flow/guidance/docs/reference/api-quick-reference.md+++ b/v3/@claude-flow/guidance/docs/reference/api-quick-reference.md@@ -34,6 +34,8 @@ All exports from `@claude-flow/guidance`. Each module is also available as a sta| `@claude-flow/guidance/authority` | `AuthorityGate`, `IrreversibilityClassifier`, `createAuthorityGate`, `createIrreversibilityClassifier`, `isHigherAuthority`, `getAuthorityHierarchy` || `@claude-flow/guidance/continue-gate` | `ContinueGate`, `createContinueGate` || `@claude-flow/guidance/wasm-kernel` | `getKernel`, `isWasmAvailable`, `resetKernel` |+| `@claude-flow/guidance/generators` | `generateClaudeMd`, `generateClaudeLocalMd`, `generateSkillMd`, `generateAgentMd`, `generateAgentIndex`, `scaffold` |+| `@claude-flow/guidance/analyzer` | `analyze`, `benchmark`, `autoOptimize`, `optimizeForSize`, `headlessBenchmark`, `validateEffect`, `formatReport`, `formatBenchmark` |---@@ -354,3 +356,93 @@ const k = getKernel()|--------|---------|-------------|| `isWasmAvailable()` | `boolean` | Check without loading || `resetKernel()` | `void` | Force re-detection on next `getKernel()` |++---++## Generators++```ts+import { generateClaudeMd, scaffold } from '@claude-flow/guidance/generators';+```++| Function | Returns | Description |+|----------|---------|-------------|+| `generateClaudeMd(profile)` | `string` | Generate CLAUDE.md from a `ProjectProfile` |+| `generateClaudeLocalMd(profile)` | `string` | Generate CLAUDE.local.md from a `LocalProfile` |+| `generateSkillMd(skill)` | `string` | Generate a skill definition markdown |+| `generateAgentMd(agent)` | `string` | Generate an agent manifest markdown |+| `generateAgentIndex(agents)` | `string` | Generate an agent index file |+| `scaffold(options)` | `ScaffoldResult` | Full project scaffolding |++**Key types**: `ProjectProfile`, `LocalProfile`, `SkillDefinition`, `AgentDefinition`, `ScaffoldOptions`, `ScaffoldResult`++---++## Analyzer++```ts+import { analyze, validateEffect } from '@claude-flow/guidance/analyzer';+```++### Scoring & Reporting++| Function | Returns | Description |+|----------|---------|-------------|+| `analyze(content, localContent?)` | `AnalysisResult` | 6-dimension analysis with composite score (0-100) and grade (A-F) |+| `benchmark(before, after, local?)` | `BenchmarkResult` | Compare two CLAUDE.md versions |+| `formatReport(result)` | `string` | Formatted analysis report |+| `formatBenchmark(result)` | `string` | Formatted benchmark comparison |++**AnalysisResult**: `{ compositeScore, grade, dimensions[], metrics, suggestions[], analyzedAt }`++**6 Dimensions**: Structure (20%), Coverage (20%), Enforceability (25%), Compilability (15%), Clarity (10%), Completeness (10%)++### Optimization++| Function | Returns | Description |+|----------|---------|-------------|+| `autoOptimize(content, local?, maxIter?)` | `{ optimized, benchmark, appliedSuggestions }` | Iterative score improvement |+| `optimizeForSize(content, options)` | `{ optimized, benchmark, appliedSteps, proof }` | Context-size-aware optimization |++**OptimizeOptions**: `{ contextSize: 'compact'|'standard'|'full', targetScore?, maxIterations?, proofKey? }`++| Context Size | Line Budget | Use Case |+|-------------|-------------|----------|+| `compact` | 80 lines | Small context windows, cost optimization |+| `standard` | 200 lines | Default for most projects |+| `full` | 500 lines | Large context windows, maximum coverage |++### Headless Benchmarking++| Function | Returns | Description |+|----------|---------|-------------|+| `headlessBenchmark(original, optimized, options?)` | `Promise<HeadlessBenchmarkResult>` | Run compliance tasks via `claude -p` |++**Options**: `{ executor?, proofKey?, workDir? }`++Accepts an `IHeadlessExecutor` for testing without the real CLI.++### Empirical Behavioral Validation++| Function | Returns | Description |+|----------|---------|-------------|+| `validateEffect(original, optimized, options?)` | `Promise<ValidationReport>` | Prove score improvements produce behavioral improvements |++**Options**: `{ executor?, tasks?, proofKey?, workDir?, trials? }`++**ValidationReport fields**:++| Field | Type | Description |+|-------|------|-------------|+| `before` / `after` | `ValidationRun` | Analysis + task results + adherence per phase |+| `correlation.pearsonR` | `number` | Linear correlation (-1 to 1) |+| `correlation.spearmanRho` | `number` | Rank correlation (-1 to 1) |+| `correlation.cohensD` | `number \| null` | Effect size magnitude |+| `correlation.effectSizeLabel` | `string` | negligible / small / medium / large |+| `correlation.verdict` | `string` | positive-effect / negative-effect / no-effect / inconclusive |+| `proofChain` | `ProofEnvelope[]` | Tamper-evident audit trail |+| `report` | `string` | Full formatted evidence report |++**IContentAwareExecutor**: Extends `IHeadlessExecutor` with `setContext(claudeMdContent)` — called before each phase so the executor can vary behavior based on guidance quality.++**15 default validation tasks** cover all 6 dimensions: secret handling, force push prevention, type safety, test-before-commit, build/test awareness, security rules, architecture knowledge, destructive action blocking, code style, error handling, deployment, and environment variables.