Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.md
index 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.
```bash
npm 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 Index
diff --git a/v3/@claude-flow/guidance/docs/reference/api-quick-reference.md b/v3/@claude-flow/guidance/docs/reference/api-quick-reference.md
index 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.