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

feat: add CLAUDE.md generators, analyzer, and auto-optimizer

Claudee06f273a1ba4
diff --git a/v3/@claude-flow/guidance/docs/reports/claude-md-analysis.md b/v3/@claude-flow/guidance/docs/reports/claude-md-analysis.md
new file mode 100644
index 0000000000..dd43847072
--- /dev/null
+++ b/v3/@claude-flow/guidance/docs/reports/claude-md-analysis.md
@@ -0,0 +1,121 @@
+# CLAUDE.md Analysis Report
+
+Generated: 2026-02-01 by `@claude-flow/guidance/analyzer`
+
+## Root CLAUDE.md (`/CLAUDE.md`)
+
+### Composite Score: 73/100 (Grade C)
+
+| Dimension | Score | Weight | Description |
+|-----------|-------|--------|-------------|
+| Structure | 55/100 | 20% | File is 648 lines; longest section is 153 lines (too long for reliable shard retrieval); constitution section exceeds recommended 60 lines |
+| Coverage | 80/100 | 20% | Has build, test, and security content but missing a dedicated Architecture/Structure section |
+| Enforceability | 60/100 | 25% | 28 enforcement statements (NEVER/ALWAYS/MUST) but only 1 formal rule statement; very low rule density |
+| Compilability | 80/100 | 15% | Compiles to a valid PolicyBundle with shards and manifest, but constitution has no parsed rules |
+| Clarity | 85/100 | 10% | 16 code blocks with good examples; mentions npm and git |
+| Completeness | 100/100 | 10% | Covers all 10 expected topics (build, security, standards, errors, git, files, deps, docs, performance, deployment) |
+
+### Key Metrics
+
+| Metric | Value |
+|--------|-------|
+| Total lines | 648 |
+| Content lines | 513 |
+| H2 sections | 17 |
+| Formal rules | 1 |
+| Enforcement statements | 28 |
+| Code blocks | 16 |
+| Estimated shards | 17 |
+| Constitution lines | 156 |
+| Longest section | 153 lines |
+
+### Findings
+
+**Structure:**
+- Constitution (top section) is 156 lines, well above the recommended 10-60 line range. The GuidanceCompiler treats the first ~60 lines as always-loaded invariants; the rest falls into shard retrieval. Exceeding 60 lines means invariants may be diluted.
+- Longest section (Automatic Swarm Orchestration) is 153 lines. Sections over 50 lines reduce shard retrieval precision because the retriever treats each section as a single shard.
+
+**Coverage:**
+- Missing a dedicated `## Architecture` or `## Project Structure` section. The file describes many features but does not map out the directory layout or module boundaries.
+
+**Enforceability:**
+- While the file has 28 NEVER/ALWAYS/MUST statements, they appear in narrative prose rather than as bullet-point rules. The compiler's rule parser looks for imperative list items (e.g., `- NEVER commit secrets`), and finds only 1 matching statement. Converting the prose enforcement into list-format rules would significantly improve enforceability scoring and gate activation.
+
+**Compilability:**
+- The GuidanceCompiler successfully produces a PolicyBundle with 17 shards, but the constitution object has no parsed rules because the top section uses headers and code blocks rather than imperative list items.
+
+### Suggestions Applied by Auto-Optimizer
+
+| # | Action | Description | Impact |
+|---|--------|-------------|--------|
+| 1 | Add | Architecture/Structure section with directory layout | +4 to Coverage, now 100/100 |
+
+### After Optimization: 77/100 (Grade C)
+
+The auto-optimizer added the missing Architecture section, improving Coverage from 80 to 100. The remaining improvement opportunities require manual restructuring:
+
+1. **Split the 153-line Swarm Orchestration section** into 3-4 subsections (e.g., "Swarm Init", "Agent Routing", "Complexity Detection", "Anti-Drift Config")
+2. **Convert enforcement prose to list-format rules** β€” change `**MCP alone does NOT execute work**` to `- NEVER rely on MCP alone β€” always use Task tool for execution`
+3. **Shorten the constitution** β€” move detailed configuration tables to later sections so the compiler captures core invariants
+
+---
+
+## v3/CLAUDE.md (`/v3/CLAUDE.md`)
+
+### Composite Score: 64/100 (Grade D)
+
+| Dimension | Score | Weight | Description |
+|-----------|-------|--------|-------------|
+| Structure | 65/100 | 20% | 15 sections, reasonable length, but longest section is 77 lines |
+| Coverage | 60/100 | 20% | Missing Security and Architecture sections |
+| Enforceability | 50/100 | 25% | 18 enforcement statements but 0 formal rules; very low rule density |
+| Compilability | 80/100 | 15% | Compiles cleanly |
+| Clarity | 85/100 | 10% | Good code blocks and formatting |
+| Completeness | 60/100 | 10% | Missing security rules, coding standards, error handling |
+
+### Suggestions Applied by Auto-Optimizer
+
+| # | Action | Description | Impact |
+|---|--------|-------------|--------|
+| 1 | Add | Security section with concrete rules | +8 pts |
+| 2 | Add | Architecture/Structure section | +6 pts |
+
+### After Optimization: 78/100 (Grade C, +14 improvement)
+
+The v3/CLAUDE.md benefited more from auto-optimization because it was missing both Security and Architecture sections. Adding these brought Coverage from 60 to 100, Enforceability from 50 to 60, and Compilability from 80 to 100.
+
+---
+
+## How to Run This Analysis
+
+```bash
+# From the guidance package directory
+cd v3/@claude-flow/guidance
+
+# Run the analysis script
+npx tsx scripts/analyze-claude-md.ts
+
+# Or use the API programmatically
+import { analyze, autoOptimize, formatReport } from '@claude-flow/guidance/analyzer';
+
+const result = analyze(claudeMdContent);
+console.log(formatReport(result));
+
+const optimized = autoOptimize(claudeMdContent);
+console.log(optimized.benchmark.delta); // score improvement
+```
+
+## Scoring Methodology
+
+The analyzer scores 6 dimensions, each 0-100, with weighted composition:
+
+| Dimension | Weight | What It Measures |
+|-----------|--------|------------------|
+| **Structure** | 20% | H1 title, H2 sections (3-5+), content length (20-200 lines), section length (<50 lines), constitution (10-60 lines) |
+| **Coverage** | 20% | Build command, test command, security section, architecture section, domain rules (3+) |
+| **Enforceability** | 25% | NEVER/ALWAYS/MUST count (5+), rule statements (10+), absence of vague language, rule density (>15%) |
+| **Compilability** | 15% | Compiles without error, constitution has rules, produces shards (3+), valid manifest, local overlay works |
+| **Clarity** | 10% | Code blocks (3+), tool mentions (3+), tables, average line length (20-100 chars) |
+| **Completeness** | 10% | 10 topic checks: build/test, security, standards, errors, git, files, deps, docs, performance, deployment |
+
+Grades: A (90+), B (80-89), C (70-79), D (60-69), F (<60)
diff --git a/v3/@claude-flow/guidance/package.json b/v3/@claude-flow/guidance/package.json
index b7f1c35dfa..af2d07feb6 100644
--- a/v3/@claude-flow/guidance/package.json
+++ b/v3/@claude-flow/guidance/package.json
@@ -117,6 +117,14 @@
"./wasm-kernel": {
"types": "./dist/wasm-kernel.d.ts",
"import": "./dist/wasm-kernel.js"
+ },
+ "./generators": {
+ "types": "./dist/generators.d.ts",
+ "import": "./dist/generators.js"
+ },
+ "./analyzer": {
+ "types": "./dist/analyzer.d.ts",
+ "import": "./dist/analyzer.js"
}
},
"files": [
diff --git a/v3/@claude-flow/guidance/scripts/analyze-claude-md.ts b/v3/@claude-flow/guidance/scripts/analyze-claude-md.ts
new file mode 100644
index 0000000000..3f8c8763cf
--- /dev/null
+++ b/v3/@claude-flow/guidance/scripts/analyze-claude-md.ts
@@ -0,0 +1,174 @@
+#!/usr/bin/env npx tsx
+/**
+ * Analyze and auto-optimize the project's CLAUDE.md
+ *
+ * Produces:
+ * 1. A detailed before-analysis report
+ * 2. Auto-optimized content
+ * 3. A before/after benchmark
+ * 4. The optimized CLAUDE.md content
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { analyze, benchmark, autoOptimize, formatReport, formatBenchmark } from '../src/analyzer.js';
+
+// Analyze both the root CLAUDE.md and v3/CLAUDE.md
+const ROOT_CLAUDE_MD = resolve(import.meta.dirname!, '../../../../CLAUDE.md');
+const V3_CLAUDE_MD = resolve(import.meta.dirname!, '../../../CLAUDE.md');
+
+const CLAUDE_MD_PATH = ROOT_CLAUDE_MD;
+
+// Read the current file
+const original = readFileSync(CLAUDE_MD_PATH, 'utf-8');
+
+console.log('='.repeat(80));
+console.log(' CLAUDE.md ANALYSIS & OPTIMIZATION REPORT');
+console.log(' Target: ' + CLAUDE_MD_PATH);
+console.log(' Date: ' + new Date().toISOString());
+console.log('='.repeat(80));
+console.log();
+
+// ── Before Analysis ──────────────────────────────────────────────────────────
+console.log('β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”');
+console.log('β”‚ PHASE 1: BEFORE ANALYSIS β”‚');
+console.log('β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜');
+console.log();
+
+const beforeResult = analyze(original);
+console.log(formatReport(beforeResult));
+console.log();
+
+// ── Detailed Findings ────────────────────────────────────────────────────────
+console.log('β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”');
+console.log('β”‚ PHASE 2: DETAILED FINDINGS β”‚');
+console.log('β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜');
+console.log();
+
+for (const dim of beforeResult.dimensions) {
+ if (dim.findings.length > 0) {
+ console.log(` ${dim.name} (${dim.score}/${dim.max}):`);
+ for (const f of dim.findings) {
+ console.log(` - ${f}`);
+ }
+ console.log();
+ }
+}
+
+// ── Auto-Optimize ────────────────────────────────────────────────────────────
+console.log('β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”');
+console.log('β”‚ PHASE 3: AUTO-OPTIMIZATION β”‚');
+console.log('β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜');
+console.log();
+
+const optimized = autoOptimize(original, undefined, 5);
+
+console.log(`Applied ${optimized.appliedSuggestions.length} suggestions:`);
+for (const s of optimized.appliedSuggestions) {
+ console.log(` [${s.priority.toUpperCase()}] ${s.action}: ${s.description} (+${s.estimatedImprovement} pts)`);
+}
+console.log();
+
+// ── Benchmark ────────────────────────────────────────────────────────────────
+console.log('β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”');
+console.log('β”‚ PHASE 4: BEFORE/AFTER BENCHMARK β”‚');
+console.log('β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜');
+console.log();
+
+console.log(formatBenchmark(optimized.benchmark));
+console.log();
+
+// ── After Analysis ───────────────────────────────────────────────────────────
+console.log('β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”');
+console.log('β”‚ PHASE 5: AFTER ANALYSIS β”‚');
+console.log('β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜');
+console.log();
+
+const afterResult = analyze(optimized.optimized);
+console.log(formatReport(afterResult));
+console.log();
+
+// ── Metrics Comparison Table ─────────────────────────────────────────────────
+console.log('β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”');
+console.log('β”‚ PHASE 6: METRICS COMPARISON β”‚');
+console.log('β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜');
+console.log();
+
+const bm = beforeResult.metrics;
+const am = afterResult.metrics;
+
+function delta(before: number, after: number): string {
+ const d = after - before;
+ return d >= 0 ? '+' + d : String(d);
+}
+
+function row(label: string, before: number | boolean, after: number | boolean, showDelta = true): string {
+ const b = String(before).padStart(6);
+ const a = String(after).padStart(6);
+ const d = showDelta && typeof before === 'number' && typeof after === 'number'
+ ? ' ' + delta(before as number, after as number)
+ : '';
+ return ' ' + label.padEnd(24) + b + ' ' + a + d;
+}
+
+console.log(' Metric Before After Delta');
+console.log(' ─────────────────────────────────────────────────────');
+console.log(row('Total lines', bm.totalLines, am.totalLines));
+console.log(row('Content lines', bm.contentLines, am.contentLines));
+console.log(row('Sections (H2)', bm.sectionCount, am.sectionCount));
+console.log(row('Rules', bm.ruleCount, am.ruleCount));
+console.log(row('Enforcement stmts', bm.enforcementStatements, am.enforcementStatements));
+console.log(row('Code blocks', bm.codeBlockCount, am.codeBlockCount));
+console.log(row('Estimated shards', bm.estimatedShards, am.estimatedShards));
+console.log(row('Tool mentions', bm.toolMentions, am.toolMentions));
+console.log(row('Domain rules', bm.domainRuleCount, am.domainRuleCount));
+console.log(row('Has build command', bm.hasBuildCommand, am.hasBuildCommand, false));
+console.log(row('Has test command', bm.hasTestCommand, am.hasTestCommand, false));
+console.log(row('Has security section', bm.hasSecuritySection, am.hasSecuritySection, false));
+console.log(row('Has architecture', bm.hasArchitectureSection, am.hasArchitectureSection, false));
+console.log(row('Constitution lines', bm.constitutionLines, am.constitutionLines));
+console.log(row('Longest section', bm.longestSectionLines, am.longestSectionLines));
+console.log();
+
+// ── Summary ──────────────────────────────────────────────────────────────────
+console.log('='.repeat(80));
+console.log(' SUMMARY');
+console.log('='.repeat(80));
+console.log();
+const scoreDelta = afterResult.compositeScore - beforeResult.compositeScore;
+const sign = scoreDelta >= 0 ? '+' : '';
+console.log(' Composite Score: ' + beforeResult.compositeScore + ' -> ' + afterResult.compositeScore + ' (' + sign + scoreDelta + ')');
+console.log(' Grade: ' + beforeResult.grade + ' -> ' + afterResult.grade);
+console.log(' Suggestions Applied: ' + optimized.appliedSuggestions.length);
+console.log(' Dimensions Improved: ' + optimized.benchmark.improvements.length);
+console.log(' Dimensions Regressed: ' + optimized.benchmark.regressions.length);
+console.log();
+
+// Save the optimized content
+const outputPath = CLAUDE_MD_PATH.replace('.md', '.optimized.md');
+writeFileSync(outputPath, optimized.optimized, 'utf-8');
+console.log(' Optimized file saved to: ' + outputPath);
+console.log();
+
+// Also analyze v3/CLAUDE.md if it exists
+try {
+ const v3Content = readFileSync(V3_CLAUDE_MD, 'utf-8');
+ console.log('='.repeat(80));
+ console.log(' BONUS: v3/CLAUDE.md ANALYSIS');
+ console.log(' Target: ' + V3_CLAUDE_MD);
+ console.log('='.repeat(80));
+ console.log();
+ const v3Result = analyze(v3Content);
+ console.log(formatReport(v3Result));
+ console.log();
+
+ const v3Optimized = autoOptimize(v3Content, undefined, 5);
+ console.log(formatBenchmark(v3Optimized.benchmark));
+ console.log();
+
+ const v3OutputPath = V3_CLAUDE_MD.replace('.md', '.optimized.md');
+ writeFileSync(v3OutputPath, v3Optimized.optimized, 'utf-8');
+ console.log(' v3 optimized file saved to: ' + v3OutputPath);
+} catch {
+ // v3/CLAUDE.md may not exist
+}
diff --git a/v3/@claude-flow/guidance/src/analyzer.ts b/v3/@claude-flow/guidance/src/analyzer.ts
new file mode 100644
index 0000000000..85466fcd13
--- /dev/null
+++ b/v3/@claude-flow/guidance/src/analyzer.ts
@@ -0,0 +1,736 @@
+/**
+ * CLAUDE.md Analyzer & Auto-Optimizer
+ *
+ * Quantifiable, verifiable analysis of CLAUDE.md files.
+ * Measures structure quality, coverage, enforceability, and produces
+ * a numeric score (0-100) that can be tracked over time.
+ *
+ * The auto-optimizer takes analysis results and produces a concrete
+ * list of changes that would improve the score. Changes can be applied
+ * programmatically and the score re-measured to verify improvement.
+ *
+ * @module @claude-flow/guidance/analyzer
+ */
+
+import { createCompiler } from './compiler.js';
+import { createGates } from './gates.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Score breakdown for a single dimension (0-100 each) */
+export interface DimensionScore {
+ /** Dimension name */
+ name: string;
+ /** Score 0-100 */
+ score: number;
+ /** Maximum possible score */
+ max: number;
+ /** Weight in composite calculation */
+ weight: number;
+ /** Human-readable findings */
+ findings: string[];
+}
+
+/** Complete analysis result */
+export interface AnalysisResult {
+ /** Composite score 0-100 */
+ compositeScore: number;
+ /** Letter grade A-F */
+ grade: string;
+ /** Per-dimension scores */
+ dimensions: DimensionScore[];
+ /** Structural metrics */
+ metrics: AnalysisMetrics;
+ /** Actionable improvement suggestions */
+ suggestions: Suggestion[];
+ /** Timestamp */
+ analyzedAt: number;
+}
+
+/** Raw metrics extracted from the file */
+export interface AnalysisMetrics {
+ /** Total lines */
+ totalLines: number;
+ /** Non-blank, non-comment lines */
+ contentLines: number;
+ /** Number of markdown headings */
+ headingCount: number;
+ /** Number of H2 sections */
+ sectionCount: number;
+ /** Estimated constitution lines (first section block) */
+ constitutionLines: number;
+ /** Number of rule-like statements (imperative sentences) */
+ ruleCount: number;
+ /** Number of code blocks */
+ codeBlockCount: number;
+ /** Number of NEVER/ALWAYS/MUST statements */
+ enforcementStatements: number;
+ /** Number of framework/tool mentions */
+ toolMentions: number;
+ /** Estimated shard count after compilation */
+ estimatedShards: number;
+ /** Has build command */
+ hasBuildCommand: boolean;
+ /** Has test command */
+ hasTestCommand: boolean;
+ /** Has security section */
+ hasSecuritySection: boolean;
+ /** Has architecture section */
+ hasArchitectureSection: boolean;
+ /** Lines in longest section */
+ longestSectionLines: number;
+ /** Has @import directives */
+ hasImports: boolean;
+ /** Number of domain-specific rules */
+ domainRuleCount: number;
+}
+
+/** A concrete improvement suggestion */
+export interface Suggestion {
+ /** What to change */
+ action: 'add' | 'remove' | 'restructure' | 'split' | 'strengthen';
+ /** Priority */
+ priority: 'high' | 'medium' | 'low';
+ /** Which dimension this improves */
+ dimension: string;
+ /** Human-readable description */
+ description: string;
+ /** Estimated score improvement */
+ estimatedImprovement: number;
+ /** Concrete text to add/modify (if applicable) */
+ patch?: string;
+}
+
+/** Before/after benchmark result */
+export interface BenchmarkResult {
+ before: AnalysisResult;
+ after: AnalysisResult;
+ delta: number;
+ improvements: DimensionDelta[];
+ regressions: DimensionDelta[];
+}
+
+interface DimensionDelta {
+ dimension: string;
+ before: number;
+ after: number;
+ delta: number;
+}
+
+// ============================================================================
+// Analyzer
+// ============================================================================
+
+/**
+ * Analyze a CLAUDE.md file and produce quantifiable scores.
+ *
+ * Scores 6 dimensions (0-100 each), weighted into a composite:
+ * - Structure (20%): headings, sections, length, organization
+ * - Coverage (20%): build/test/security/architecture/domain
+ * - Enforceability (25%): NEVER/ALWAYS statements, concrete rules
+ * - Compilability (15%): how well it compiles to constitution + shards
+ * - Clarity (10%): code blocks, examples, specificity
+ * - Completeness (10%): missing common sections
+ */
+export function analyze(content: string, localContent?: string): AnalysisResult {
+ const metrics = extractMetrics(content);
+ const dimensions: DimensionScore[] = [];
+
+ // 1. Structure (20%)
+ dimensions.push(scoreStructure(metrics, content));
+
+ // 2. Coverage (20%)
+ dimensions.push(scoreCoverage(metrics, content));
+
+ // 3. Enforceability (25%)
+ dimensions.push(scoreEnforceability(metrics, content));
+
+ // 4. Compilability (15%)
+ dimensions.push(scoreCompilability(content, localContent));
+
+ // 5. Clarity (10%)
+ dimensions.push(scoreClarity(metrics, content));
+
+ // 6. Completeness (10%)
+ dimensions.push(scoreCompleteness(metrics, content));
+
+ // Composite
+ const compositeScore = Math.round(
+ dimensions.reduce((sum, d) => sum + (d.score / d.max) * d.weight * 100, 0)
+ );
+
+ // Grade
+ const grade = compositeScore >= 90 ? 'A' :
+ compositeScore >= 80 ? 'B' :
+ compositeScore >= 70 ? 'C' :
+ compositeScore >= 60 ? 'D' : 'F';
+
+ // Suggestions
+ const suggestions = generateSuggestions(dimensions, metrics, content);
+
+ return {
+ compositeScore,
+ grade,
+ dimensions,
+ metrics,
+ suggestions,
+ analyzedAt: Date.now(),
+ };
+}
+
+/**
+ * Run a before/after benchmark.
+ * Returns the delta and per-dimension changes.
+ */
+export function benchmark(before: string, after: string, localContent?: string): BenchmarkResult {
+ const beforeResult = analyze(before, localContent);
+ const afterResult = analyze(after, localContent);
+
+ const improvements: DimensionDelta[] = [];
+ const regressions: DimensionDelta[] = [];
+
+ for (let i = 0; i < beforeResult.dimensions.length; i++) {
+ const b = beforeResult.dimensions[i];
+ const a = afterResult.dimensions[i];
+ const delta = a.score - b.score;
+
+ const entry = { dimension: b.name, before: b.score, after: a.score, delta };
+ if (delta > 0) improvements.push(entry);
+ else if (delta < 0) regressions.push(entry);
+ }
+
+ return {
+ before: beforeResult,
+ after: afterResult,
+ delta: afterResult.compositeScore - beforeResult.compositeScore,
+ improvements,
+ regressions,
+ };
+}
+
+/**
+ * Auto-optimize a CLAUDE.md file by applying high-priority suggestions.
+ * Returns the optimized content and the benchmark result.
+ */
+export function autoOptimize(
+ content: string,
+ localContent?: string,
+ maxIterations = 3,
+): { optimized: string; benchmark: BenchmarkResult; appliedSuggestions: Suggestion[] } {
+ let current = content;
+ const applied: Suggestion[] = [];
+
+ for (let i = 0; i < maxIterations; i++) {
+ const result = analyze(current, localContent);
+
+ // Get high-priority suggestions with patches
+ const actionable = result.suggestions
+ .filter(s => s.priority === 'high' && s.patch)
+ .sort((a, b) => b.estimatedImprovement - a.estimatedImprovement);
+
+ if (actionable.length === 0) break;
+
+ // Apply top suggestion
+ const suggestion = actionable[0];
+ if (suggestion.action === 'add' && suggestion.patch) {
+ current = current.trimEnd() + '\n\n' + suggestion.patch + '\n';
+ applied.push(suggestion);
+ } else if (suggestion.action === 'strengthen' && suggestion.patch) {
+ current = current.trimEnd() + '\n\n' + suggestion.patch + '\n';
+ applied.push(suggestion);
+ }
+ }
+
+ const benchmarkResult = benchmark(content, current, localContent);
+
+ return {
+ optimized: current,
+ benchmark: benchmarkResult,
+ appliedSuggestions: applied,
+ };
+}
+
+/**
+ * Format analysis result as a human-readable report.
+ */
+export function formatReport(result: AnalysisResult): string {
+ const lines: string[] = [];
+
+ lines.push(`CLAUDE.md Analysis Report`);
+ lines.push(`========================`);
+ lines.push(``);
+ lines.push(`Composite Score: ${result.compositeScore}/100 (${result.grade})`);
+ lines.push(``);
+
+ lines.push(`Dimensions:`);
+ for (const d of result.dimensions) {
+ const bar = 'β–ˆ'.repeat(Math.round(d.score / 5)) + 'β–‘'.repeat(20 - Math.round(d.score / 5));
+ lines.push(` ${d.name.padEnd(16)} ${bar} ${d.score}/${d.max} (${d.weight * 100}%)`);
+ }
+ lines.push(``);
+
+ lines.push(`Metrics:`);
+ lines.push(` Lines: ${result.metrics.totalLines} (${result.metrics.contentLines} content)`);
+ lines.push(` Sections: ${result.metrics.sectionCount}`);
+ lines.push(` Rules: ${result.metrics.ruleCount}`);
+ lines.push(` Enforcement statements: ${result.metrics.enforcementStatements}`);
+ lines.push(` Estimated shards: ${result.metrics.estimatedShards}`);
+ lines.push(` Code blocks: ${result.metrics.codeBlockCount}`);
+ lines.push(``);
+
+ if (result.suggestions.length > 0) {
+ lines.push(`Suggestions (${result.suggestions.length}):`);
+ for (const s of result.suggestions.slice(0, 10)) {
+ const icon = s.priority === 'high' ? '[!]' : s.priority === 'medium' ? '[~]' : '[ ]';
+ lines.push(` ${icon} ${s.description} (+${s.estimatedImprovement} pts)`);
+ }
+ }
+
+ return lines.join('\n');
+}
+
+/**
+ * Format benchmark result as a comparison table.
+ */
+export function formatBenchmark(result: BenchmarkResult): string {
+ const lines: string[] = [];
+
+ lines.push(`Before/After Benchmark`);
+ lines.push(`======================`);
+ lines.push(``);
+ lines.push(`Score: ${result.before.compositeScore} β†’ ${result.after.compositeScore} (${result.delta >= 0 ? '+' : ''}${result.delta})`);
+ lines.push(`Grade: ${result.before.grade} β†’ ${result.after.grade}`);
+ lines.push(``);
+
+ if (result.improvements.length > 0) {
+ lines.push(`Improvements:`);
+ for (const d of result.improvements) {
+ lines.push(` ${d.dimension}: ${d.before} β†’ ${d.after} (+${d.delta})`);
+ }
+ }
+
+ if (result.regressions.length > 0) {
+ lines.push(`Regressions:`);
+ for (const d of result.regressions) {
+ lines.push(` ${d.dimension}: ${d.before} β†’ ${d.after} (${d.delta})`);
+ }
+ }
+
+ return lines.join('\n');
+}
+
+// ============================================================================
+// Metric Extraction
+// ============================================================================
+
+function extractMetrics(content: string): AnalysisMetrics {
+ const lines = content.split('\n');
+ const totalLines = lines.length;
+ const contentLines = lines.filter(l => l.trim().length > 0).length;
+
+ const headings = lines.filter(l => /^#+\s/.test(l));
+ const headingCount = headings.length;
+ const sectionCount = lines.filter(l => /^##\s/.test(l)).length;
+
+ // Constitution: lines before second H2 (or first 60 lines)
+ let constitutionLines = 0;
+ let h2Count = 0;
+ for (let i = 0; i < lines.length; i++) {
+ if (/^##\s/.test(lines[i])) {
+ h2Count++;
+ if (h2Count === 2) {
+ constitutionLines = i;
+ break;
+ }
+ }
+ }
+ if (constitutionLines === 0) constitutionLines = Math.min(totalLines, 60);
+
+ // Rules: lines starting with - that contain imperative verbs or constraints
+ const rulePattern = /^[\s]*[-*]\s+((?:NEVER|ALWAYS|MUST|Do not|Never|Always|Prefer|Avoid|Use|Run|Ensure|Follow|No\s|All\s|Keep)\b.*)/;
+ const ruleCount = lines.filter(l => rulePattern.test(l)).length;
+
+ // Code blocks
+ const codeBlockCount = (content.match(/```/g) || []).length / 2;
+
+ // Enforcement statements
+ const enforcementPattern = /\b(NEVER|ALWAYS|MUST|REQUIRED|FORBIDDEN|DO NOT|SHALL NOT)\b/gi;
+ const enforcementStatements = (content.match(enforcementPattern) || []).length;
+
+ // Tool mentions
+ const toolPattern = /\b(npm|pnpm|yarn|bun|docker|git|make|cargo|go|pip|poetry)\b/gi;
+ const toolMentions = new Set((content.match(toolPattern) || []).map(m => m.toLowerCase())).size;
+
+ // Estimated shards = number of H2 sections
+ const estimatedShards = Math.max(1, sectionCount);
+
+ // Boolean features
+ const lower = content.toLowerCase();
+ const hasBuildCommand = /\b(build|compile|tsc|webpack|vite|rollup)\b/i.test(content);
+ const hasTestCommand = /\b(test|vitest|jest|pytest|mocha|cargo test)\b/i.test(content);
+ const hasSecuritySection = /^##.*security/im.test(content);
+ const hasArchitectureSection = /^##.*(architecture|structure|design)/im.test(content);
+ const hasImports = /@[~\/]/.test(content);
+
+ // Longest section
+ let longestSectionLines = 0;
+ let currentSectionLength = 0;
+ for (const line of lines) {
+ if (/^##\s/.test(line)) {
+ longestSectionLines = Math.max(longestSectionLines, currentSectionLength);
+ currentSectionLength = 0;
+ } else {
+ currentSectionLength++;
+ }
+ }
+ longestSectionLines = Math.max(longestSectionLines, currentSectionLength);
+
+ // Domain rules
+ const domainRuleCount = lines.filter(l =>
+ /^[\s]*[-*]\s/.test(l) && !/^[\s]*[-*]\s+(NEVER|ALWAYS|MUST|Prefer|Use|No\s|All\s)/i.test(l) &&
+ l.length > 20
+ ).length;
+
+ return {
+ totalLines,
+ contentLines,
+ headingCount,
+ sectionCount,
+ constitutionLines,
+ ruleCount,
+ codeBlockCount,
+ enforcementStatements,
+ toolMentions,
+ estimatedShards,
+ hasBuildCommand,
+ hasTestCommand,
+ hasSecuritySection,
+ hasArchitectureSection,
+ longestSectionLines,
+ hasImports,
+ domainRuleCount,
+ };
+}
+
+// ============================================================================
+// Scoring Functions
+// ============================================================================
+
+function scoreStructure(metrics: AnalysisMetrics, content: string): DimensionScore {
+ let score = 0;
+ const findings: string[] = [];
+
+ // Has H1 title (10 pts)
+ if (/^# /.test(content)) { score += 10; }
+ else { findings.push('Missing H1 title'); }
+
+ // Has at least 3 H2 sections (20 pts)
+ if (metrics.sectionCount >= 5) { score += 20; }
+ else if (metrics.sectionCount >= 3) { score += 15; findings.push('Consider adding more sections'); }
+ else if (metrics.sectionCount >= 1) { score += 5; findings.push('Too few sections'); }
+ else { findings.push('No H2 sections found'); }
+
+ // Content length: 20-200 lines ideal (20 pts)
+ if (metrics.contentLines >= 20 && metrics.contentLines <= 200) { score += 20; }
+ else if (metrics.contentLines >= 10) { score += 10; findings.push('File is short β€” add more guidance'); }
+ else if (metrics.contentLines > 200) { score += 15; findings.push('File is long β€” consider splitting'); }
+ else { findings.push('File is very short'); }
+
+ // No section longer than 50 lines (20 pts)
+ if (metrics.longestSectionLines <= 50) { score += 20; }
+ else if (metrics.longestSectionLines <= 80) { score += 10; findings.push('Longest section is over 50 lines β€” consider splitting'); }
+ else { findings.push(`Longest section is ${metrics.longestSectionLines} lines β€” too long for reliable retrieval`); }
+
+ // Constitution section exists and is reasonable length (30 pts)
+ if (metrics.constitutionLines >= 10 && metrics.constitutionLines <= 60) { score += 30; }
+ else if (metrics.constitutionLines > 0) { score += 15; findings.push('Constitution (top section) should be 10-60 lines'); }
+ else { findings.push('No clear constitution section'); }
+
+ return { name: 'Structure', score: Math.min(score, 100), max: 100, weight: 0.20, findings };
+}
+
+function scoreCoverage(metrics: AnalysisMetrics, content: string): DimensionScore {
+ let score = 0;
+ const findings: string[] = [];
+
+ // Has build command (20 pts)
+ if (metrics.hasBuildCommand) { score += 20; }
+ else { findings.push('No build command found'); }
+
+ // Has test command (20 pts)
+ if (metrics.hasTestCommand) { score += 20; }
+ else { findings.push('No test command found'); }
+
+ // Has security section (20 pts)
+ if (metrics.hasSecuritySection) { score += 20; }
+ else { findings.push('No security section'); }
+
+ // Has architecture section (20 pts)
+ if (metrics.hasArchitectureSection) { score += 20; }
+ else { findings.push('No architecture/structure section'); }
+
+ // Has domain rules (20 pts)
+ if (metrics.domainRuleCount >= 3) { score += 20; }
+ else if (metrics.domainRuleCount >= 1) { score += 10; findings.push('Add more domain-specific rules'); }
+ else { findings.push('No domain-specific rules'); }
+
+ return { name: 'Coverage', score: Math.min(score, 100), max: 100, weight: 0.20, findings };
+}
+
+function scoreEnforceability(metrics: AnalysisMetrics, content: string): DimensionScore {
+ let score = 0;
+ const findings: string[] = [];
+
+ // Has enforcement statements NEVER/ALWAYS/MUST (30 pts)
+ if (metrics.enforcementStatements >= 5) { score += 30; }
+ else if (metrics.enforcementStatements >= 2) { score += 15; findings.push('Add more NEVER/ALWAYS/MUST statements for stronger enforcement'); }
+ else { findings.push('No enforcement statements (NEVER/ALWAYS/MUST)'); }
+
+ // Has rule-like statements (30 pts)
+ if (metrics.ruleCount >= 10) { score += 30; }
+ else if (metrics.ruleCount >= 5) { score += 20; findings.push('Add more concrete rules'); }
+ else if (metrics.ruleCount >= 1) { score += 10; findings.push('Too few concrete rules'); }
+ else { findings.push('No actionable rules found'); }
+
+ // Rules are specific, not vague (20 pts) β€” check for vague words
+ const vaguePatterns = /\b(try to|should probably|might want to|consider|if possible|when appropriate)\b/gi;
+ const vagueCount = (content.match(vaguePatterns) || []).length;
+ if (vagueCount === 0) { score += 20; }
+ else if (vagueCount <= 3) { score += 10; findings.push(`${vagueCount} vague statements β€” make rules concrete`); }
+ else { findings.push(`${vagueCount} vague statements undermine enforceability`); }
+
+ // Ratio of rules to total content (20 pts)
+ const ruleRatio = metrics.contentLines > 0 ? metrics.ruleCount / metrics.contentLines : 0;
+ if (ruleRatio >= 0.15) { score += 20; }
+ else if (ruleRatio >= 0.08) { score += 10; findings.push('Low rule density β€” add more actionable statements'); }
+ else { findings.push('Very low rule density'); }
+
+ return { name: 'Enforceability', score: Math.min(score, 100), max: 100, weight: 0.25, findings };
+}
+
+function scoreCompilability(content: string, localContent?: string): DimensionScore {
+ let score = 0;
+ const findings: string[] = [];
+
+ try {
+ const compiler = createCompiler();
+ const bundle = compiler.compile(content, localContent);
+
+ // Successfully compiles (30 pts)
+ score += 30;
+
+ // Has constitution (20 pts)
+ if (bundle.constitution.rules.length > 0) { score += 20; }
+ else { findings.push('Constitution compiled but has no rules'); }
+
+ // Has shards (20 pts)
+ if (bundle.shards.length >= 3) { score += 20; }
+ else if (bundle.shards.length >= 1) { score += 10; findings.push('Few shards β€” add more sections'); }
+ else { findings.push('No shards produced'); }
+
+ // Has valid manifest (15 pts)
+ if (bundle.manifest && bundle.manifest.rules.length > 0) { score += 15; }
+ else { findings.push('Manifest is empty'); }
+
+ // Local overlay compiles cleanly (15 pts)
+ if (localContent) {
+ if (bundle.shards.length > 0) { score += 15; }
+ } else {
+ score += 15; // No local = no issue
+ }
+ } catch (e) {
+ findings.push(`Compilation failed: ${(e as Error).message}`);
+ }
+
+ return { name: 'Compilability', score: Math.min(score, 100), max: 100, weight: 0.15, findings };
+}
+
+function scoreClarity(metrics: AnalysisMetrics, content: string): DimensionScore {
+ let score = 0;
+ const findings: string[] = [];
+
+ // Has code blocks with examples (30 pts)
+ if (metrics.codeBlockCount >= 3) { score += 30; }
+ else if (metrics.codeBlockCount >= 1) { score += 15; findings.push('Add more code examples'); }
+ else { findings.push('No code examples'); }
+
+ // Mentions specific tools (30 pts)
+ if (metrics.toolMentions >= 3) { score += 30; }
+ else if (metrics.toolMentions >= 1) { score += 15; findings.push('Mention specific tools and commands'); }
+ else { findings.push('No specific tool references'); }
+
+ // Uses tables or structured formatting (20 pts)
+ if (/\|.*\|.*\|/.test(content)) { score += 20; }
+ else { findings.push('Consider using tables for structured data'); }
+
+ // Average line length is reasonable (20 pts)
+ const lines = content.split('\n').filter(l => l.trim().length > 0);
+ const avgLen = lines.reduce((s, l) => s + l.length, 0) / (lines.length || 1);
+ if (avgLen >= 20 && avgLen <= 100) { score += 20; }
+ else if (avgLen > 100) { score += 10; findings.push('Lines are very long β€” break into shorter statements'); }
+ else { score += 10; }
+
+ return { name: 'Clarity', score: Math.min(score, 100), max: 100, weight: 0.10, findings };
+}
+
+function scoreCompleteness(metrics: AnalysisMetrics, content: string): DimensionScore {
+ let score = 0;
+ const findings: string[] = [];
+ const lower = content.toLowerCase();
+
+ // Checks for common sections
+ const checks: Array<[string, RegExp, number]> = [
+ ['Build/Test commands', /\b(build|test|lint)\b/i, 15],
+ ['Security rules', /\b(secret|credential|injection|xss)\b/i, 15],
+ ['Coding standards', /\b(style|convention|standard|format)\b/i, 15],
+ ['Error handling', /\b(error|exception|catch|throw)\b/i, 10],
+ ['Git/VCS practices', /\b(commit|branch|merge|pull request|pr)\b/i, 10],
+ ['File organization', /\b(directory|folder|structure|organize)\b/i, 10],
+ ['Dependencies', /\b(dependency|package|import|require)\b/i, 10],
+ ['Documentation', /\b(doc|comment|jsdoc|readme)\b/i, 5],
+ ['Performance', /\b(performance|optimize|cache|lazy)\b/i, 5],
+ ['Deployment', /\b(deploy|production|staging|ci\/cd)\b/i, 5],
+ ];
+
+ for (const [name, pattern, points] of checks) {
+ if (pattern.test(content)) {
+ score += points;
+ } else {
+ findings.push(`Missing topic: ${name}`);
+ }
+ }
+
+ return { name: 'Completeness', score: Math.min(score, 100), max: 100, weight: 0.10, findings };
+}
+
+// ============================================================================
+// Suggestion Generation
+// ============================================================================
+
+function generateSuggestions(
+ dimensions: DimensionScore[],
+ metrics: AnalysisMetrics,
+ content: string,
+): Suggestion[] {
+ const suggestions: Suggestion[] = [];
+
+ // Structure suggestions
+ if (!metrics.hasSecuritySection) {
+ suggestions.push({
+ action: 'add',
+ priority: 'high',
+ dimension: 'Coverage',
+ description: 'Add a Security section with concrete rules',
+ estimatedImprovement: 8,
+ patch: [
+ '## Security',
+ '',
+ '- Never commit secrets, API keys, or credentials to git',
+ '- Never run destructive commands without explicit confirmation',
+ '- Validate all external input at system boundaries',
+ '- Use parameterized queries for database operations',
+ ].join('\n'),
+ });
+ }
+
+ if (!metrics.hasArchitectureSection) {
+ suggestions.push({
+ action: 'add',
+ priority: 'high',
+ dimension: 'Coverage',
+ description: 'Add an Architecture/Structure section',
+ estimatedImprovement: 6,
+ patch: [
+ '## Project Structure',
+ '',
+ '- `src/` β€” Source code',
+ '- `tests/` β€” Test files',
+ '- `docs/` β€” Documentation',
+ ].join('\n'),
+ });
+ }
+
+ if (!metrics.hasBuildCommand) {
+ suggestions.push({
+ action: 'add',
+ priority: 'high',
+ dimension: 'Coverage',
+ description: 'Add Build & Test commands',
+ estimatedImprovement: 6,
+ patch: [
+ '## Build & Test',
+ '',
+ 'Build: `npm run build`',
+ 'Test: `npm test`',
+ '',
+ 'Run tests before committing. Run the build to catch type errors.',
+ ].join('\n'),
+ });
+ }
+
+ if (metrics.enforcementStatements < 3) {
+ suggestions.push({
+ action: 'strengthen',
+ priority: 'high',
+ dimension: 'Enforceability',
+ description: 'Add NEVER/ALWAYS enforcement statements',
+ estimatedImprovement: 8,
+ patch: [
+ '## Enforcement Rules',
+ '',
+ '- NEVER commit files containing secrets or API keys',
+ '- NEVER use `any` type (use `unknown` instead)',
+ '- ALWAYS run tests before committing',
+ '- ALWAYS handle errors explicitly (no silent catches)',
+ '- MUST include error messages in all thrown exceptions',
+ ].join('\n'),
+ });
+ }
+
+ if (metrics.codeBlockCount === 0) {
+ suggestions.push({
+ action: 'add',
+ priority: 'medium',
+ dimension: 'Clarity',
+ description: 'Add code examples showing correct patterns',
+ estimatedImprovement: 4,
+ });
+ }
+
+ if (metrics.sectionCount < 3) {
+ suggestions.push({
+ action: 'restructure',
+ priority: 'medium',
+ dimension: 'Structure',
+ description: 'Split content into more H2 sections for better shard retrieval',
+ estimatedImprovement: 5,
+ });
+ }
+
+ if (metrics.longestSectionLines > 50) {
+ suggestions.push({
+ action: 'split',
+ priority: 'medium',
+ dimension: 'Structure',
+ description: `Split the longest section (${metrics.longestSectionLines} lines) into subsections`,
+ estimatedImprovement: 4,
+ });
+ }
+
+ if (metrics.domainRuleCount < 3) {
+ suggestions.push({
+ action: 'add',
+ priority: 'medium',
+ dimension: 'Coverage',
+ description: 'Add domain-specific rules unique to this project',
+ estimatedImprovement: 4,
+ });
+ }
+
+ // Sort by estimated improvement
+ suggestions.sort((a, b) => b.estimatedImprovement - a.estimatedImprovement);
+
+ return suggestions;
+}
diff --git a/v3/@claude-flow/guidance/src/generators.ts b/v3/@claude-flow/guidance/src/generators.ts
new file mode 100644
index 0000000000..1c18b1e7d8
--- /dev/null
+++ b/v3/@claude-flow/guidance/src/generators.ts
@@ -0,0 +1,894 @@
+/**
+ * CLAUDE.md Generator
+ *
+ * Generates a structured CLAUDE.md file optimized for the Guidance Control Plane.
+ * The output is designed so that when compiled by GuidanceCompiler, it produces
+ * a clean constitution (always-loaded invariants) and well-tagged shards
+ * (task-scoped rules retrievable by intent).
+ *
+ * Structure conventions:
+ * - Lines 1-60: Constitution (always loaded into every task)
+ * - Remaining: Tagged shards (retrieved by intent classification)
+ * - Headings map to shard boundaries
+ * - Keywords in headings drive intent tagging: "test", "build", "security", etc.
+ *
+ * @module @claude-flow/guidance/generators
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ProjectProfile {
+ /** Project name */
+ name: string;
+ /** Short description */
+ description?: string;
+ /** Primary language(s) */
+ languages: string[];
+ /** Frameworks in use */
+ frameworks?: string[];
+ /** Package manager */
+ packageManager?: 'npm' | 'pnpm' | 'yarn' | 'bun';
+ /** Monorepo? */
+ monorepo?: boolean;
+ /** Build command */
+ buildCommand?: string;
+ /** Test command */
+ testCommand?: string;
+ /** Lint command */
+ lintCommand?: string;
+ /** Source directory */
+ srcDir?: string;
+ /** Test directory */
+ testDir?: string;
+ /** Domain-specific rules */
+ domainRules?: string[];
+ /** Architecture notes */
+ architecture?: string;
+ /** Team conventions */
+ conventions?: string[];
+ /** Forbidden patterns */
+ forbidden?: string[];
+ /** Required patterns */
+ required?: string[];
+ /** Import paths for personal instructions */
+ imports?: string[];
+ /** Enable guidance control plane integration */
+ guidanceControlPlane?: boolean;
+ /** Enable WASM kernel for hot paths */
+ wasmKernel?: boolean;
+ /** Agent swarm configuration */
+ swarm?: {
+ topology?: 'hierarchical' | 'mesh' | 'adaptive';
+ maxAgents?: number;
+ strategy?: 'specialized' | 'balanced';
+ };
+}
+
+export interface LocalProfile {
+ /** Developer name or identifier */
+ developer?: string;
+ /** Local API URLs */
+ localUrls?: Record<string, string>;
+ /** Local database connection strings */
+ databases?: Record<string, string>;
+ /** Personal preferences */
+ preferences?: string[];
+ /** Machine-specific notes */
+ machineNotes?: string[];
+ /** Editor / IDE */
+ editor?: string;
+ /** OS */
+ os?: string;
+ /** Custom environment variables */
+ envVars?: Record<string, string>;
+ /** Debug settings */
+ debug?: string[];
+}
+
+export interface SkillDefinition {
+ /** Skill name (kebab-case) */
+ name: string;
+ /** Version */
+ version?: string;
+ /** Description */
+ description: string;
+ /** Category */
+ category: 'core' | 'github' | 'testing' | 'security' | 'deployment' | 'analysis' | 'custom';
+ /** Tags */
+ tags?: string[];
+ /** Required tools */
+ requires?: string[];
+ /** Capabilities list */
+ capabilities?: string[];
+ /** Skill instructions (markdown body) */
+ instructions: string;
+}
+
+export interface AgentDefinition {
+ /** Agent name (kebab-case) */
+ name: string;
+ /** Agent type */
+ type: 'coordinator' | 'developer' | 'tester' | 'reviewer' | 'security-specialist' | 'researcher' | 'architect' | 'devops' | 'custom';
+ /** Description */
+ description: string;
+ /** Category subdirectory */
+ category?: string;
+ /** Color for UI */
+ color?: string;
+ /** Capabilities */
+ capabilities?: string[];
+ /** Focus areas */
+ focus?: string[];
+ /** Temperature (0.0-1.0) */
+ temperature?: number;
+ /** Priority */
+ priority?: 'high' | 'medium' | 'low';
+ /** System prompt */
+ systemPrompt?: string;
+ /** Pre-execution hook */
+ preHook?: string;
+ /** Post-execution hook */
+ postHook?: string;
+ /** Detailed instructions (markdown body) */
+ instructions?: string;
+}
+
+// ============================================================================
+// CLAUDE.md Generator
+// ============================================================================
+
+export function generateClaudeMd(profile: ProjectProfile): string {
+ const sections: string[] = [];
+
+ // --- Constitution (lines 1-60, always loaded) ---
+ sections.push(`# ${profile.name}`);
+ sections.push('');
+ if (profile.description) {
+ sections.push(profile.description);
+ sections.push('');
+ }
+
+ // Core invariants
+ sections.push('## Core Invariants');
+ sections.push('');
+ sections.push('These rules are always active regardless of task type.');
+ sections.push('');
+
+ // Language-specific invariants
+ for (const lang of profile.languages) {
+ const invariants = getLanguageInvariants(lang);
+ if (invariants.length > 0) {
+ for (const inv of invariants) {
+ sections.push(`- ${inv}`);
+ }
+ }
+ }
+
+ // Forbidden patterns
+ if (profile.forbidden && profile.forbidden.length > 0) {
+ sections.push('');
+ for (const f of profile.forbidden) {
+ sections.push(`- NEVER: ${f}`);
+ }
+ }
+
+ // Required patterns
+ if (profile.required && profile.required.length > 0) {
+ for (const r of profile.required) {
+ sections.push(`- ALWAYS: ${r}`);
+ }
+ }
+
+ sections.push('');
+
+ // --- Build & Test (tagged shard) ---
+ sections.push('## Build & Test');
+ sections.push('');
+ const pm = profile.packageManager || 'npm';
+ if (profile.buildCommand) {
+ sections.push(`Build: \`${profile.buildCommand}\``);
+ } else {
+ sections.push(`Build: \`${pm} run build\``);
+ }
+ if (profile.testCommand) {
+ sections.push(`Test: \`${profile.testCommand}\``);
+ } else {
+ sections.push(`Test: \`${pm} test\``);
+ }
+ if (profile.lintCommand) {
+ sections.push(`Lint: \`${profile.lintCommand}\``);
+ }
+ sections.push('');
+ sections.push('Run tests before committing. Run the build to catch type errors.');
+ sections.push('');
+
+ // --- Project Structure ---
+ sections.push('## Project Structure');
+ sections.push('');
+ if (profile.monorepo) {
+ sections.push('This is a monorepo. Each package has its own CLAUDE.md that layers on top of this root file.');
+ }
+ if (profile.srcDir) {
+ sections.push(`Source code: \`${profile.srcDir}/\``);
+ }
+ if (profile.testDir) {
+ sections.push(`Tests: \`${profile.testDir}/\``);
+ }
+ if (profile.architecture) {
+ sections.push('');
+ sections.push(profile.architecture);
+ }
+ sections.push('');
+
+ // --- Coding Standards ---
+ if (profile.conventions && profile.conventions.length > 0) {
+ sections.push('## Coding Standards');
+ sections.push('');
+ for (const c of profile.conventions) {
+ sections.push(`- ${c}`);
+ }
+ sections.push('');
+ }
+
+ // --- Domain Rules ---
+ if (profile.domainRules && profile.domainRules.length > 0) {
+ sections.push('## Domain Rules');
+ sections.push('');
+ for (const rule of profile.domainRules) {
+ sections.push(`- ${rule}`);
+ }
+ sections.push('');
+ }
+
+ // --- Framework-specific shards ---
+ if (profile.frameworks && profile.frameworks.length > 0) {
+ for (const fw of profile.frameworks) {
+ const fwRules = getFrameworkRules(fw);
+ if (fwRules.length > 0) {
+ sections.push(`## ${fw} Conventions`);
+ sections.push('');
+ for (const rule of fwRules) {
+ sections.push(`- ${rule}`);
+ }
+ sections.push('');
+ }
+ }
+ }
+
+ // --- Security ---
+ sections.push('## Security');
+ sections.push('');
+ sections.push('- Never commit secrets, API keys, or credentials to git');
+ sections.push('- Never run destructive commands (`rm -rf /`, `DROP TABLE`, `git push --force`) without explicit confirmation');
+ sections.push('- Validate all external input at system boundaries');
+ sections.push('- Use parameterized queries for database operations');
+ sections.push('');
+
+ // --- Guidance Control Plane integration ---
+ if (profile.guidanceControlPlane) {
+ sections.push('## Guidance Control Plane');
+ sections.push('');
+ sections.push('This project uses `@claude-flow/guidance` to enforce these rules programmatically.');
+ sections.push('The constitution (this section and above) is always loaded. Sections below are');
+ sections.push('retrieved by intent classification β€” only relevant rules are injected per task.');
+ sections.push('');
+ sections.push('Gates enforce: destructive ops, secrets detection, diff size limits, tool allowlist.');
+ sections.push('The optimizer watches violations and promotes winning CLAUDE.local.md experiments here.');
+ sections.push('');
+ if (profile.wasmKernel) {
+ sections.push('WASM kernel: hot-path operations (hashing, secret scanning) use the Rust WASM kernel');
+ sections.push('for 1.25-1.96x speedup. Falls back to JS automatically if WASM is unavailable.');
+ sections.push('');
+ }
+ }
+
+ // --- Swarm configuration ---
+ if (profile.swarm) {
+ sections.push('## Swarm Configuration');
+ sections.push('');
+ sections.push(`Topology: ${profile.swarm.topology || 'hierarchical'}`);
+ sections.push(`Max agents: ${profile.swarm.maxAgents || 8}`);
+ sections.push(`Strategy: ${profile.swarm.strategy || 'specialized'}`);
+ sections.push('');
+ }
+
+ // --- Imports ---
+ if (profile.imports && profile.imports.length > 0) {
+ sections.push('## Individual Preferences');
+ sections.push('');
+ for (const imp of profile.imports) {
+ sections.push(`@${imp}`);
+ }
+ sections.push('');
+ }
+
+ return sections.join('\n');
+}
+
+// ============================================================================
+// CLAUDE.local.md Generator
+// ============================================================================
+
+export function generateClaudeLocalMd(local: LocalProfile): string {
+ const sections: string[] = [];
+
+ sections.push('# Local Development Notes');
+ sections.push('');
+ sections.push('> This file is auto-gitignored by Claude Code. It stays on this machine only.');
+ sections.push('');
+
+ if (local.developer) {
+ sections.push(`Developer: ${local.developer}`);
+ sections.push('');
+ }
+
+ // Local URLs
+ if (local.localUrls && Object.keys(local.localUrls).length > 0) {
+ sections.push('## Local URLs');
+ sections.push('');
+ for (const [name, url] of Object.entries(local.localUrls)) {
+ sections.push(`- ${name}: ${url}`);
+ }
+ sections.push('');
+ }
+
+ // Databases
+ if (local.databases && Object.keys(local.databases).length > 0) {
+ sections.push('## Local Databases');
+ sections.push('');
+ for (const [name, conn] of Object.entries(local.databases)) {
+ sections.push(`- ${name}: \`${conn}\``);
+ }
+ sections.push('');
+ }
+
+ // Environment
+ if (local.envVars && Object.keys(local.envVars).length > 0) {
+ sections.push('## Environment Variables');
+ sections.push('');
+ sections.push('```bash');
+ for (const [key, val] of Object.entries(local.envVars)) {
+ sections.push(`export ${key}="${val}"`);
+ }
+ sections.push('```');
+ sections.push('');
+ }
+
+ // Preferences
+ if (local.preferences && local.preferences.length > 0) {
+ sections.push('## Preferences');
+ sections.push('');
+ for (const p of local.preferences) {
+ sections.push(`- ${p}`);
+ }
+ sections.push('');
+ }
+
+ // Machine notes
+ if (local.machineNotes && local.machineNotes.length > 0) {
+ sections.push('## Machine Notes');
+ sections.push('');
+ if (local.os) {
+ sections.push(`OS: ${local.os}`);
+ }
+ if (local.editor) {
+ sections.push(`Editor: ${local.editor}`);
+ }
+ for (const note of local.machineNotes) {
+ sections.push(`- ${note}`);
+ }
+ sections.push('');
+ }
+
+ // Debug
+ if (local.debug && local.debug.length > 0) {
+ sections.push('## Debug Settings');
+ sections.push('');
+ for (const d of local.debug) {
+ sections.push(`- ${d}`);
+ }
+ sections.push('');
+ }
+
+ return sections.join('\n');
+}
+
+// ============================================================================
+// Skills Generator
+// ============================================================================
+
+export function generateSkillMd(skill: SkillDefinition): string {
+ const lines: string[] = [];
+
+ // YAML frontmatter
+ lines.push('---');
+ lines.push(`name: ${skill.name}`);
+ lines.push(`version: ${skill.version || '1.0.0'}`);
+ lines.push(`description: ${skill.description}`);
+ lines.push(`category: ${skill.category}`);
+ if (skill.tags && skill.tags.length > 0) {
+ lines.push(`tags: [${skill.tags.join(', ')}]`);
+ }
+ if (skill.requires && skill.requires.length > 0) {
+ lines.push('requires:');
+ for (const r of skill.requires) {
+ lines.push(` - ${r}`);
+ }
+ }
+ if (skill.capabilities && skill.capabilities.length > 0) {
+ lines.push('capabilities:');
+ for (const c of skill.capabilities) {
+ lines.push(` - ${c}`);
+ }
+ }
+ lines.push('---');
+ lines.push('');
+
+ // Skill title and instructions
+ lines.push(`# ${formatTitle(skill.name)} Skill`);
+ lines.push('');
+ lines.push(skill.instructions);
+
+ return lines.join('\n');
+}
+
+// ============================================================================
+// Agent Definition Generator
+// ============================================================================
+
+export function generateAgentMd(agent: AgentDefinition): string {
+ const lines: string[] = [];
+
+ // YAML frontmatter
+ lines.push('---');
+ lines.push(`name: ${agent.name}`);
+ lines.push(`type: ${agent.type}`);
+ if (agent.color) {
+ lines.push(`color: "${agent.color}"`);
+ }
+ lines.push(`description: ${agent.description}`);
+ if (agent.capabilities && agent.capabilities.length > 0) {
+ lines.push('capabilities:');
+ for (const c of agent.capabilities) {
+ lines.push(` - ${c}`);
+ }
+ }
+ if (agent.focus && agent.focus.length > 0) {
+ lines.push('focus:');
+ for (const f of agent.focus) {
+ lines.push(` - ${f}`);
+ }
+ }
+ lines.push(`temperature: ${agent.temperature ?? 0.2}`);
+ if (agent.priority) {
+ lines.push(`priority: ${agent.priority}`);
+ }
+ if (agent.preHook || agent.postHook) {
+ lines.push('hooks:');
+ if (agent.preHook) {
+ lines.push(' pre: |');
+ lines.push(` ${agent.preHook}`);
+ }
+ if (agent.postHook) {
+ lines.push(' post: |');
+ lines.push(` ${agent.postHook}`);
+ }
+ }
+ lines.push('---');
+ lines.push('');
+
+ // Agent title
+ lines.push(`# ${formatTitle(agent.name)} Agent`);
+ lines.push('');
+ lines.push(agent.description);
+ lines.push('');
+
+ // System prompt
+ if (agent.systemPrompt) {
+ lines.push('## System Prompt');
+ lines.push('');
+ lines.push(agent.systemPrompt);
+ lines.push('');
+ }
+
+ // Instructions
+ if (agent.instructions) {
+ lines.push('## Instructions');
+ lines.push('');
+ lines.push(agent.instructions);
+ lines.push('');
+ }
+
+ return lines.join('\n');
+}
+
+// ============================================================================
+// Agent Index Generator
+// ============================================================================
+
+export function generateAgentIndex(agents: AgentDefinition[]): string {
+ const lines: string[] = [];
+ lines.push('# Generated Agent Index');
+ lines.push('');
+ lines.push('agents:');
+ for (const a of agents) {
+ lines.push(` - ${a.name}`);
+ }
+ lines.push('');
+
+ // Group by type
+ const byType = new Map<string, string[]>();
+ for (const a of agents) {
+ const list = byType.get(a.type) || [];
+ list.push(a.name);
+ byType.set(a.type, list);
+ }
+
+ lines.push('types:');
+ for (const [type, names] of byType) {
+ lines.push(` ${type}:`);
+ for (const n of names) {
+ lines.push(` - ${n}`);
+ }
+ }
+
+ return lines.join('\n');
+}
+
+// ============================================================================
+// Scaffold Generator (creates full .claude/ directory structure)
+// ============================================================================
+
+export interface ScaffoldOptions {
+ /** Project profile for CLAUDE.md */
+ project: ProjectProfile;
+ /** Local profile for CLAUDE.local.md (optional) */
+ local?: LocalProfile;
+ /** Skills to generate */
+ skills?: SkillDefinition[];
+ /** Agents to generate */
+ agents?: AgentDefinition[];
+ /** Include default agents based on project profile */
+ includeDefaultAgents?: boolean;
+ /** Include default skills based on project profile */
+ includeDefaultSkills?: boolean;
+}
+
+export interface ScaffoldResult {
+ /** Map of relative file path β†’ content */
+ files: Map<string, string>;
+}
+
+export function scaffold(options: ScaffoldOptions): ScaffoldResult {
+ const files = new Map<string, string>();
+
+ // CLAUDE.md
+ files.set('CLAUDE.md', generateClaudeMd(options.project));
+
+ // CLAUDE.local.md
+ if (options.local) {
+ files.set('CLAUDE.local.md', generateClaudeLocalMd(options.local));
+ }
+
+ // Default agents based on project
+ const agents = [...(options.agents || [])];
+ if (options.includeDefaultAgents) {
+ agents.push(...getDefaultAgents(options.project));
+ }
+
+ // Default skills based on project
+ const skills = [...(options.skills || [])];
+ if (options.includeDefaultSkills) {
+ skills.push(...getDefaultSkills(options.project));
+ }
+
+ // Generate agent files
+ for (const agent of agents) {
+ const category = agent.category || 'core';
+ const path = `.claude/agents/${category}/${agent.name}.md`;
+ files.set(path, generateAgentMd(agent));
+ }
+
+ // Generate agent index
+ if (agents.length > 0) {
+ files.set('.claude/agents/index.yaml', generateAgentIndex(agents));
+ }
+
+ // Generate skill files
+ for (const skill of skills) {
+ const path = `.claude/skills/${skill.name}/SKILL.md`;
+ files.set(path, generateSkillMd(skill));
+ }
+
+ return { files };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function formatTitle(kebab: string): string {
+ return kebab
+ .split('-')
+ .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+ .join(' ');
+}
+
+function getLanguageInvariants(lang: string): string[] {
+ const lower = lang.toLowerCase();
+ const map: Record<string, string[]> = {
+ typescript: [
+ 'No `any` types. Use `unknown` if the type is truly unknown.',
+ 'Prefer `const` over `let`. Never use `var`.',
+ 'All public functions and exported types require JSDoc.',
+ 'Use strict TypeScript (`strict: true` in tsconfig).',
+ ],
+ javascript: [
+ 'Prefer `const` over `let`. Never use `var`.',
+ 'Use strict mode (`"use strict"` or ES modules).',
+ ],
+ python: [
+ 'Follow PEP 8 style guide.',
+ 'Use type hints for all function signatures.',
+ 'Prefer f-strings over `.format()` or `%` formatting.',
+ ],
+ rust: [
+ 'Run `cargo clippy` before committing.',
+ 'No `unwrap()` in production code. Use `?` or proper error handling.',
+ 'All public items require doc comments (`///`).',
+ ],
+ go: [
+ 'Run `go vet` and `golangci-lint` before committing.',
+ 'Always handle errors. Never use `_` for error returns.',
+ 'Follow Effective Go conventions.',
+ ],
+ java: [
+ 'Follow Google Java Style Guide.',
+ 'All public classes and methods require Javadoc.',
+ 'Prefer immutable objects where possible.',
+ ],
+ };
+ return map[lower] || [`Follow established ${lang} conventions.`];
+}
+
+function getFrameworkRules(framework: string): string[] {
+ const lower = framework.toLowerCase();
+ const map: Record<string, string[]> = {
+ react: [
+ 'Prefer functional components with hooks over class components.',
+ 'Use `useMemo`/`useCallback` only when profiling shows a need.',
+ 'Keep components small and focused. Extract custom hooks for shared logic.',
+ ],
+ nextjs: [
+ 'Use the App Router unless there is a specific reason for Pages Router.',
+ 'Prefer Server Components by default. Add `"use client"` only when needed.',
+ 'Use `next/image` for all images.',
+ ],
+ express: [
+ 'Use async error handling middleware.',
+ 'Validate all request bodies with a schema validator (zod, joi, etc.).',
+ 'Never expose stack traces in production error responses.',
+ ],
+ fastify: [
+ 'Use JSON Schema for request/response validation.',
+ 'Register plugins in a consistent order.',
+ ],
+ django: [
+ 'Use class-based views for CRUD, function-based for custom logic.',
+ 'Always use the ORM. Never write raw SQL unless performance-critical.',
+ 'Run `manage.py check` before deploying.',
+ ],
+ flask: [
+ 'Use blueprints for modular organization.',
+ 'Never use `app.run()` in production.',
+ ],
+ prisma: [
+ 'Run `prisma generate` after schema changes.',
+ 'Never edit generated client code.',
+ 'Use transactions for multi-table operations.',
+ ],
+ vitest: [
+ 'Use `describe` blocks to group related tests.',
+ 'Prefer `expect().toBe()` for primitives, `expect().toEqual()` for objects.',
+ 'Use `beforeEach` for shared setup, not `beforeAll` (test isolation).',
+ ],
+ jest: [
+ 'Use `describe` blocks to group related tests.',
+ 'Prefer `expect().toBe()` for primitives, `expect().toEqual()` for objects.',
+ 'Mock external dependencies, never internal implementation details.',
+ ],
+ };
+ return map[lower] || [];
+}
+
+function getDefaultAgents(profile: ProjectProfile): AgentDefinition[] {
+ const agents: AgentDefinition[] = [];
+
+ // Every project gets a coordinator and coder
+ agents.push({
+ name: 'coordinator',
+ type: 'coordinator',
+ description: `Coordinates multi-agent workflows for ${profile.name}`,
+ category: 'core',
+ color: '#4A90D9',
+ capabilities: ['task-decomposition', 'agent-routing', 'context-management', 'progress-tracking'],
+ temperature: 0.2,
+ priority: 'high',
+ instructions: [
+ 'Break complex tasks into subtasks and assign to specialized agents.',
+ 'Track progress across all active agents.',
+ 'Resolve conflicts when agents produce contradictory outputs.',
+ 'Ensure all subtasks align with the original goal.',
+ ].join('\n'),
+ });
+
+ agents.push({
+ name: 'coder',
+ type: 'developer',
+ description: `Implementation specialist for ${profile.name}`,
+ category: 'core',
+ color: '#FF6B35',
+ capabilities: ['code-generation', 'refactoring', 'optimization', 'api-design', 'error-handling'],
+ focus: profile.languages,
+ temperature: 0.2,
+ priority: 'high',
+ instructions: [
+ `Write clean, idiomatic ${profile.languages.join('/')} code.`,
+ 'Follow the coding standards defined in CLAUDE.md.',
+ 'Prefer editing existing files over creating new ones.',
+ 'Run tests after making changes.',
+ ].join('\n'),
+ });
+
+ agents.push({
+ name: 'tester',
+ type: 'tester',
+ description: `Test specialist for ${profile.name}`,
+ category: 'core',
+ color: '#2ECC71',
+ capabilities: ['unit-testing', 'integration-testing', 'test-coverage', 'edge-cases'],
+ temperature: 0.2,
+ priority: 'high',
+ instructions: [
+ 'Write tests that cover the happy path and meaningful edge cases.',
+ 'Use descriptive test names that explain the expected behavior.',
+ 'Keep tests isolated β€” no shared mutable state between tests.',
+ `Run: \`${profile.testCommand || (profile.packageManager || 'npm') + ' test'}\``,
+ ].join('\n'),
+ });
+
+ agents.push({
+ name: 'reviewer',
+ type: 'reviewer',
+ description: `Code review specialist for ${profile.name}`,
+ category: 'core',
+ color: '#9B59B6',
+ capabilities: ['code-review', 'quality-analysis', 'security-review', 'performance-review'],
+ temperature: 0.3,
+ priority: 'medium',
+ instructions: [
+ 'Review for correctness, readability, and maintainability.',
+ 'Check for security issues: injection, XSS, hardcoded secrets.',
+ 'Flag unnecessary complexity and suggest simpler alternatives.',
+ 'Verify test coverage for changed code.',
+ ].join('\n'),
+ });
+
+ // Security agent if guidance control plane is enabled
+ if (profile.guidanceControlPlane) {
+ agents.push({
+ name: 'security-auditor',
+ type: 'security-specialist',
+ description: 'Security analysis integrated with guidance control plane',
+ category: 'security',
+ color: '#E74C3C',
+ capabilities: ['threat-detection', 'secret-scanning', 'input-validation', 'dependency-audit'],
+ temperature: 0.1,
+ priority: 'high',
+ instructions: [
+ 'Scan all code changes for secrets and credentials.',
+ 'Check for OWASP Top 10 vulnerabilities.',
+ 'Validate that enforcement gates are wired for all external inputs.',
+ 'Report findings through the guidance proof chain for audit trail.',
+ ].join('\n'),
+ });
+ }
+
+ return agents;
+}
+
+function getDefaultSkills(profile: ProjectProfile): SkillDefinition[] {
+ const skills: SkillDefinition[] = [];
+
+ // Build & test skill
+ skills.push({
+ name: 'build-and-test',
+ description: `Build and test ${profile.name}`,
+ category: 'core',
+ tags: ['build', 'test', 'ci'],
+ capabilities: ['Run build', 'Run tests', 'Fix build errors', 'Fix test failures'],
+ instructions: [
+ `## Build`,
+ '',
+ '```bash',
+ profile.buildCommand || `${profile.packageManager || 'npm'} run build`,
+ '```',
+ '',
+ '## Test',
+ '',
+ '```bash',
+ profile.testCommand || `${profile.packageManager || 'npm'} test`,
+ '```',
+ '',
+ '## Workflow',
+ '',
+ '1. Run the build first to catch type errors',
+ '2. Run tests to verify correctness',
+ '3. If either fails, fix the issue and re-run',
+ '4. Never commit with failing tests or build errors',
+ ].join('\n'),
+ });
+
+ // Code review skill
+ skills.push({
+ name: 'code-review',
+ description: 'Review code for quality, security, and correctness',
+ category: 'core',
+ tags: ['review', 'quality', 'security'],
+ capabilities: ['Security scanning', 'Quality analysis', 'Performance review', 'Style checking'],
+ instructions: [
+ '## Review Checklist',
+ '',
+ '1. **Correctness**: Does the code do what it claims?',
+ '2. **Security**: Any secrets, injection vectors, or unsafe patterns?',
+ '3. **Tests**: Are changes covered by tests?',
+ '4. **Readability**: Can another developer understand this without context?',
+ '5. **Performance**: Any obvious O(n^2) loops or unnecessary allocations?',
+ '6. **Style**: Does it follow the project coding standards?',
+ ].join('\n'),
+ });
+
+ // Guidance control plane skill
+ if (profile.guidanceControlPlane) {
+ skills.push({
+ name: 'guidance-enforcement',
+ description: 'Enforce guidance rules through the control plane',
+ category: 'security',
+ tags: ['guidance', 'enforcement', 'gates', 'policy'],
+ requires: ['@claude-flow/guidance'],
+ capabilities: [
+ 'Gate enforcement for commands, edits, and tool calls',
+ 'Proof chain generation for audit trails',
+ 'Memory write authorization',
+ 'Trust score tracking',
+ ],
+ instructions: [
+ '## Guidance Control Plane',
+ '',
+ 'This project uses `@claude-flow/guidance` to enforce CLAUDE.md rules programmatically.',
+ '',
+ '### Before executing commands:',
+ '```typescript',
+ "const results = plane.evaluateCommand('rm -rf /tmp/build');",
+ "if (results.some(r => r.decision === 'deny')) { /* blocked */ }",
+ '```',
+ '',
+ '### Before editing files:',
+ '```typescript',
+ "const results = plane.evaluateEdit('config.ts', content, lineCount);",
+ '```',
+ '',
+ '### Track every run:',
+ '```typescript',
+ "const event = plane.startRun('task-id', 'feature');",
+ '// ... work ...',
+ 'await plane.finalizeRun(event);',
+ '```',
+ ].join('\n'),
+ });
+ }
+
+ return skills;
+}
diff --git a/v3/@claude-flow/guidance/src/index.ts b/v3/@claude-flow/guidance/src/index.ts
index 0655038965..4d18423025 100644
--- a/v3/@claude-flow/guidance/src/index.ts
+++ b/v3/@claude-flow/guidance/src/index.ts
@@ -287,6 +287,36 @@ export type {
BatchOp,
BatchResult,
} from './wasm-kernel.js';
+export {
+ generateClaudeMd,
+ generateClaudeLocalMd,
+ generateSkillMd,
+ generateAgentMd,
+ generateAgentIndex,
+ scaffold,
+} from './generators.js';
+export type {
+ ProjectProfile,
+ LocalProfile,
+ SkillDefinition,
+ AgentDefinition,
+ ScaffoldOptions,
+ ScaffoldResult,
+} from './generators.js';
+export {
+ analyze,
+ benchmark,
+ autoOptimize,
+ formatReport,
+ formatBenchmark,
+} from './analyzer.js';
+export type {
+ AnalysisResult,
+ AnalysisMetrics,
+ DimensionScore,
+ Suggestion,
+ BenchmarkResult,
+} from './analyzer.js';
export {
TrustAccumulator,
diff --git a/v3/@claude-flow/guidance/tests/analyzer.test.ts b/v3/@claude-flow/guidance/tests/analyzer.test.ts
new file mode 100644
index 0000000000..b12ded557f
--- /dev/null
+++ b/v3/@claude-flow/guidance/tests/analyzer.test.ts
@@ -0,0 +1,633 @@
+import { describe, it, expect } from 'vitest';
+import {
+ analyze,
+ benchmark,
+ autoOptimize,
+ formatReport,
+ formatBenchmark,
+} from '../src/analyzer.js';
+import type {
+ AnalysisResult,
+ BenchmarkResult,
+} from '../src/analyzer.js';
+
+// ============================================================================
+// Test Fixtures
+// ============================================================================
+
+const MINIMAL_CLAUDE_MD = `# My Project
+
+Some basic info about the project.
+`;
+
+const WELL_STRUCTURED_CLAUDE_MD = `# My Project
+
+This project uses TypeScript and follows strict conventions.
+
+## Build & Test
+
+Build: \`npm run build\`
+Test: \`npm test\`
+Lint: \`npm run lint\`
+
+Run tests before committing. Run the build to catch type errors.
+
+## Coding Standards
+
+- NEVER use \`any\` type β€” use \`unknown\` when type is truly unknown
+- ALWAYS add JSDoc to public functions
+- ALWAYS handle errors explicitly β€” no silent catches
+- Prefer composition over inheritance
+- Use readonly arrays and objects where possible
+- No console.log in production code
+
+## Architecture
+
+This project follows a layered architecture:
+
+- \`src/\` β€” Source code
+- \`tests/\` β€” Test files
+- \`docs/\` β€” Documentation
+
+Use barrel exports from each module.
+
+## Security
+
+- NEVER commit secrets, API keys, or credentials
+- NEVER run destructive commands without confirmation
+- Validate all external input at system boundaries
+- Use parameterized queries for database operations
+- Avoid eval() and dynamic code execution
+
+## Git Practices
+
+- MUST write descriptive commit messages
+- MUST create a branch for each feature
+- Run tests before creating a pull request
+- Keep commits focused and atomic
+
+## Domain Rules
+
+- All API responses must include a requestId for tracing
+- Database migrations must be backward-compatible
+- Cache keys must include a version prefix
+- Rate limiting is required on all public endpoints
+`;
+
+const POOR_CLAUDE_MD = `some rules
+dont do bad stuff
+be good
+`;
+
+const LOCAL_OVERLAY = `# Local Dev
+
+- My API: http://localhost:3001
+- Test DB: postgres://localhost:5432/mydb_test
+
+## Preferences
+
+- Prefer verbose error messages
+- Show git diffs before committing
+`;
+
+// ============================================================================
+// analyze()
+// ============================================================================
+
+describe('analyze', () => {
+ describe('compositeScore', () => {
+ it('returns a score between 0 and 100', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.compositeScore).toBeGreaterThanOrEqual(0);
+ expect(result.compositeScore).toBeLessThanOrEqual(100);
+ });
+
+ it('scores a well-structured file higher than a poor one', () => {
+ const good = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const bad = analyze(POOR_CLAUDE_MD);
+ expect(good.compositeScore).toBeGreaterThan(bad.compositeScore);
+ });
+
+ it('scores a minimal file in the middle range', () => {
+ const result = analyze(MINIMAL_CLAUDE_MD);
+ expect(result.compositeScore).toBeLessThan(analyze(WELL_STRUCTURED_CLAUDE_MD).compositeScore);
+ expect(result.compositeScore).toBeGreaterThan(analyze(POOR_CLAUDE_MD).compositeScore);
+ });
+ });
+
+ describe('grade', () => {
+ it('assigns A grade for score >= 90', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ if (result.compositeScore >= 90) {
+ expect(result.grade).toBe('A');
+ }
+ });
+
+ it('assigns F grade for very poor content', () => {
+ const result = analyze(POOR_CLAUDE_MD);
+ expect(result.grade).toBe('F');
+ });
+
+ it('grade is one of A, B, C, D, F', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(['A', 'B', 'C', 'D', 'F']).toContain(result.grade);
+ });
+ });
+
+ describe('dimensions', () => {
+ it('returns exactly 6 dimensions', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.dimensions).toHaveLength(6);
+ });
+
+ it('includes Structure, Coverage, Enforceability, Compilability, Clarity, Completeness', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const names = result.dimensions.map(d => d.name);
+ expect(names).toContain('Structure');
+ expect(names).toContain('Coverage');
+ expect(names).toContain('Enforceability');
+ expect(names).toContain('Compilability');
+ expect(names).toContain('Clarity');
+ expect(names).toContain('Completeness');
+ });
+
+ it('each dimension has score, max, weight, and findings', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ for (const d of result.dimensions) {
+ expect(d.score).toBeGreaterThanOrEqual(0);
+ expect(d.max).toBe(100);
+ expect(d.weight).toBeGreaterThan(0);
+ expect(d.weight).toBeLessThanOrEqual(1);
+ expect(Array.isArray(d.findings)).toBe(true);
+ }
+ });
+
+ it('weights sum to 1.0', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const totalWeight = result.dimensions.reduce((sum, d) => sum + d.weight, 0);
+ expect(totalWeight).toBeCloseTo(1.0);
+ });
+
+ it('Structure scores high for well-organized content', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const structure = result.dimensions.find(d => d.name === 'Structure')!;
+ expect(structure.score).toBeGreaterThanOrEqual(50);
+ });
+
+ it('Coverage scores high when build, test, security, architecture present', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const coverage = result.dimensions.find(d => d.name === 'Coverage')!;
+ expect(coverage.score).toBeGreaterThanOrEqual(80);
+ });
+
+ it('Enforceability scores high with NEVER/ALWAYS/MUST statements', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const enforceability = result.dimensions.find(d => d.name === 'Enforceability')!;
+ expect(enforceability.score).toBeGreaterThanOrEqual(50);
+ });
+
+ it('Compilability scores high for content that compiles to a valid bundle', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const compilability = result.dimensions.find(d => d.name === 'Compilability')!;
+ expect(compilability.score).toBeGreaterThanOrEqual(50);
+ });
+
+ it('Clarity scores based on code blocks, tool mentions, and formatting', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const clarity = result.dimensions.find(d => d.name === 'Clarity')!;
+ // Fixture has inline code + tool mentions (npm, git) but no fenced code blocks or tables
+ expect(clarity.score).toBeGreaterThanOrEqual(30);
+ });
+
+ it('Completeness scores low when missing many topics', () => {
+ const result = analyze(POOR_CLAUDE_MD);
+ const completeness = result.dimensions.find(d => d.name === 'Completeness')!;
+ expect(completeness.score).toBeLessThanOrEqual(30);
+ });
+ });
+
+ describe('metrics', () => {
+ it('counts total lines correctly', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.totalLines).toBeGreaterThan(10);
+ });
+
+ it('counts content lines (non-blank)', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.contentLines).toBeLessThan(result.metrics.totalLines);
+ expect(result.metrics.contentLines).toBeGreaterThan(0);
+ });
+
+ it('counts headings', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.headingCount).toBeGreaterThanOrEqual(6); // H1 + H2s
+ });
+
+ it('counts H2 sections', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.sectionCount).toBeGreaterThanOrEqual(5);
+ });
+
+ it('estimates constitution lines', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.constitutionLines).toBeGreaterThan(0);
+ expect(result.metrics.constitutionLines).toBeLessThan(result.metrics.totalLines);
+ });
+
+ it('counts rule statements', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.ruleCount).toBeGreaterThan(5);
+ });
+
+ it('counts code blocks', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.codeBlockCount).toBeGreaterThanOrEqual(0);
+ });
+
+ it('counts enforcement statements', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.enforcementStatements).toBeGreaterThan(3);
+ });
+
+ it('detects build command', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.hasBuildCommand).toBe(true);
+ });
+
+ it('detects test command', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.hasTestCommand).toBe(true);
+ });
+
+ it('detects security section', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.hasSecuritySection).toBe(true);
+ });
+
+ it('detects architecture section', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.hasArchitectureSection).toBe(true);
+ });
+
+ it('detects @import directives', () => {
+ const withImport = WELL_STRUCTURED_CLAUDE_MD + '\n@~/.claude/my_instructions.md\n';
+ const result = analyze(withImport);
+ expect(result.metrics.hasImports).toBe(true);
+ });
+
+ it('reports no imports when absent', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.hasImports).toBe(false);
+ });
+
+ it('counts estimated shards', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.metrics.estimatedShards).toBeGreaterThanOrEqual(5);
+ });
+ });
+
+ describe('suggestions', () => {
+ it('returns actionable suggestions for poor content', () => {
+ const result = analyze(POOR_CLAUDE_MD);
+ expect(result.suggestions.length).toBeGreaterThan(0);
+ });
+
+ it('returns fewer suggestions for well-structured content', () => {
+ const good = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const bad = analyze(POOR_CLAUDE_MD);
+ expect(good.suggestions.length).toBeLessThanOrEqual(bad.suggestions.length);
+ });
+
+ it('each suggestion has action, priority, dimension, description', () => {
+ const result = analyze(POOR_CLAUDE_MD);
+ for (const s of result.suggestions) {
+ expect(['add', 'remove', 'restructure', 'split', 'strengthen']).toContain(s.action);
+ expect(['high', 'medium', 'low']).toContain(s.priority);
+ expect(s.dimension).toBeTruthy();
+ expect(s.description).toBeTruthy();
+ expect(s.estimatedImprovement).toBeGreaterThan(0);
+ }
+ });
+
+ it('high-priority suggestions include patches when possible', () => {
+ const result = analyze(POOR_CLAUDE_MD);
+ const highPriority = result.suggestions.filter(s => s.priority === 'high');
+ const withPatch = highPriority.filter(s => s.patch);
+ expect(withPatch.length).toBeGreaterThan(0);
+ });
+
+ it('suggestions are sorted by estimated improvement descending', () => {
+ const result = analyze(POOR_CLAUDE_MD);
+ for (let i = 1; i < result.suggestions.length; i++) {
+ expect(result.suggestions[i].estimatedImprovement)
+ .toBeLessThanOrEqual(result.suggestions[i - 1].estimatedImprovement);
+ }
+ });
+ });
+
+ describe('local content overlay', () => {
+ it('accepts optional local content', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD, LOCAL_OVERLAY);
+ expect(result.compositeScore).toBeGreaterThan(0);
+ });
+
+ it('compilability dimension uses local overlay', () => {
+ const withLocal = analyze(WELL_STRUCTURED_CLAUDE_MD, LOCAL_OVERLAY);
+ const withoutLocal = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ // Both should compile; scores may differ slightly
+ const compWithLocal = withLocal.dimensions.find(d => d.name === 'Compilability')!;
+ const compWithoutLocal = withoutLocal.dimensions.find(d => d.name === 'Compilability')!;
+ expect(compWithLocal.score).toBeGreaterThanOrEqual(30); // compiles
+ expect(compWithoutLocal.score).toBeGreaterThanOrEqual(30); // compiles
+ });
+ });
+
+ describe('timestamp', () => {
+ it('includes analyzedAt timestamp', () => {
+ const before = Date.now();
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const after = Date.now();
+ expect(result.analyzedAt).toBeGreaterThanOrEqual(before);
+ expect(result.analyzedAt).toBeLessThanOrEqual(after);
+ });
+ });
+});
+
+// ============================================================================
+// benchmark()
+// ============================================================================
+
+describe('benchmark', () => {
+ it('computes delta between before and after', () => {
+ const result = benchmark(POOR_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.delta).toBeGreaterThan(0);
+ });
+
+ it('returns before and after analysis results', () => {
+ const result = benchmark(POOR_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.before.compositeScore).toBeDefined();
+ expect(result.after.compositeScore).toBeDefined();
+ expect(result.after.compositeScore).toBeGreaterThan(result.before.compositeScore);
+ });
+
+ it('identifies improvements by dimension', () => {
+ const result = benchmark(POOR_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.improvements.length).toBeGreaterThan(0);
+ for (const imp of result.improvements) {
+ expect(imp.delta).toBeGreaterThan(0);
+ expect(imp.after).toBeGreaterThan(imp.before);
+ }
+ });
+
+ it('reports regressions when going from good to bad', () => {
+ const result = benchmark(WELL_STRUCTURED_CLAUDE_MD, POOR_CLAUDE_MD);
+ expect(result.delta).toBeLessThan(0);
+ expect(result.regressions.length).toBeGreaterThan(0);
+ });
+
+ it('shows zero delta for identical content', () => {
+ const result = benchmark(WELL_STRUCTURED_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.delta).toBe(0);
+ expect(result.improvements).toHaveLength(0);
+ expect(result.regressions).toHaveLength(0);
+ });
+
+ it('accepts optional local content', () => {
+ const result = benchmark(POOR_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD, LOCAL_OVERLAY);
+ expect(result.delta).toBeGreaterThan(0);
+ });
+
+ it('each dimension delta has correct fields', () => {
+ const result = benchmark(POOR_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD);
+ for (const d of [...result.improvements, ...result.regressions]) {
+ expect(d.dimension).toBeTruthy();
+ expect(typeof d.before).toBe('number');
+ expect(typeof d.after).toBe('number');
+ expect(d.delta).toBe(d.after - d.before);
+ }
+ });
+});
+
+// ============================================================================
+// autoOptimize()
+// ============================================================================
+
+describe('autoOptimize', () => {
+ it('improves the score of poor content', () => {
+ const result = autoOptimize(POOR_CLAUDE_MD);
+ expect(result.benchmark.delta).toBeGreaterThan(0);
+ });
+
+ it('returns the optimized content', () => {
+ const result = autoOptimize(POOR_CLAUDE_MD);
+ expect(result.optimized).toBeTruthy();
+ expect(result.optimized.length).toBeGreaterThan(POOR_CLAUDE_MD.length);
+ });
+
+ it('tracks applied suggestions', () => {
+ const result = autoOptimize(POOR_CLAUDE_MD);
+ expect(result.appliedSuggestions.length).toBeGreaterThan(0);
+ for (const s of result.appliedSuggestions) {
+ expect(s.patch).toBeTruthy();
+ }
+ });
+
+ it('respects maxIterations', () => {
+ const onePass = autoOptimize(POOR_CLAUDE_MD, undefined, 1);
+ const threePasses = autoOptimize(POOR_CLAUDE_MD, undefined, 3);
+ expect(threePasses.appliedSuggestions.length).toBeGreaterThanOrEqual(
+ onePass.appliedSuggestions.length
+ );
+ });
+
+ it('does not regress well-structured content', () => {
+ const result = autoOptimize(WELL_STRUCTURED_CLAUDE_MD);
+ expect(result.benchmark.delta).toBeGreaterThanOrEqual(0);
+ });
+
+ it('produces valid markdown', () => {
+ const result = autoOptimize(POOR_CLAUDE_MD);
+ // Should still start with original content
+ expect(result.optimized).toContain('some rules');
+ // Should have added sections
+ expect(result.optimized).toContain('##');
+ });
+
+ it('auto-adds security section when missing', () => {
+ const noSecurity = `# My Project\n\n## Build & Test\n\nBuild: \`npm run build\`\nTest: \`npm test\`\n`;
+ const result = autoOptimize(noSecurity);
+ const afterMetrics = analyze(result.optimized);
+ // Should have added security-related content
+ expect(result.optimized.toLowerCase()).toMatch(/security|secret|credential/);
+ });
+
+ it('auto-adds enforcement rules when few exist', () => {
+ const weak = `# My Project\n\n## Guidelines\n\n- Try to write good code\n- Consider testing\n`;
+ const result = autoOptimize(weak);
+ expect(result.optimized).toMatch(/NEVER|ALWAYS|MUST/);
+ });
+
+ it('accepts local content overlay', () => {
+ const result = autoOptimize(POOR_CLAUDE_MD, LOCAL_OVERLAY);
+ expect(result.benchmark.delta).toBeGreaterThan(0);
+ });
+});
+
+// ============================================================================
+// formatReport()
+// ============================================================================
+
+describe('formatReport', () => {
+ it('includes composite score and grade', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const report = formatReport(result);
+ expect(report).toContain('Composite Score:');
+ expect(report).toContain(`${result.compositeScore}/100`);
+ expect(report).toContain(`(${result.grade})`);
+ });
+
+ it('includes all 6 dimensions', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const report = formatReport(result);
+ expect(report).toContain('Structure');
+ expect(report).toContain('Coverage');
+ expect(report).toContain('Enforceability');
+ expect(report).toContain('Compilability');
+ expect(report).toContain('Clarity');
+ expect(report).toContain('Completeness');
+ });
+
+ it('includes metrics section', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const report = formatReport(result);
+ expect(report).toContain('Metrics:');
+ expect(report).toContain('Lines:');
+ expect(report).toContain('Sections:');
+ expect(report).toContain('Rules:');
+ expect(report).toContain('Enforcement statements:');
+ expect(report).toContain('Estimated shards:');
+ });
+
+ it('includes suggestions for poor content', () => {
+ const result = analyze(POOR_CLAUDE_MD);
+ const report = formatReport(result);
+ expect(report).toContain('Suggestions');
+ expect(report).toContain('[!]'); // high priority marker
+ });
+
+ it('uses visual bars for dimension scores', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const report = formatReport(result);
+ // Visual bars use β–ˆ and β–‘ characters
+ expect(report).toMatch(/[β–ˆβ–‘]/);
+ });
+
+ it('shows weight percentages', () => {
+ const result = analyze(WELL_STRUCTURED_CLAUDE_MD);
+ const report = formatReport(result);
+ expect(report).toContain('20%');
+ expect(report).toContain('25%');
+ expect(report).toContain('15%');
+ expect(report).toContain('10%');
+ });
+});
+
+// ============================================================================
+// formatBenchmark()
+// ============================================================================
+
+describe('formatBenchmark', () => {
+ it('shows before and after scores', () => {
+ const result = benchmark(POOR_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD);
+ const report = formatBenchmark(result);
+ expect(report).toContain(`${result.before.compositeScore}`);
+ expect(report).toContain(`${result.after.compositeScore}`);
+ expect(report).toContain('β†’');
+ });
+
+ it('shows grade transition', () => {
+ const result = benchmark(POOR_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD);
+ const report = formatBenchmark(result);
+ expect(report).toContain(result.before.grade);
+ expect(report).toContain(result.after.grade);
+ });
+
+ it('lists improvements', () => {
+ const result = benchmark(POOR_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD);
+ const report = formatBenchmark(result);
+ expect(report).toContain('Improvements:');
+ });
+
+ it('lists regressions when applicable', () => {
+ const result = benchmark(WELL_STRUCTURED_CLAUDE_MD, POOR_CLAUDE_MD);
+ const report = formatBenchmark(result);
+ expect(report).toContain('Regressions:');
+ });
+
+ it('shows delta with sign', () => {
+ const result = benchmark(POOR_CLAUDE_MD, WELL_STRUCTURED_CLAUDE_MD);
+ const report = formatBenchmark(result);
+ expect(report).toContain('+'); // positive delta
+ });
+});
+
+// ============================================================================
+// Edge Cases
+// ============================================================================
+
+describe('edge cases', () => {
+ it('handles empty string', () => {
+ const result = analyze('');
+ // Empty string still gets some base points from compiler succeeding and no-vague bonus
+ expect(result.compositeScore).toBeLessThanOrEqual(30);
+ expect(result.grade).toBe('F');
+ });
+
+ it('handles single line', () => {
+ const result = analyze('# Title');
+ expect(result.compositeScore).toBeGreaterThanOrEqual(0);
+ expect(result.dimensions).toHaveLength(6);
+ });
+
+ it('handles content with only code blocks', () => {
+ const md = '# Project\n\n```ts\nconst x = 1;\n```\n\n```ts\nconst y = 2;\n```\n\n```ts\nconst z = 3;\n```\n';
+ const result = analyze(md);
+ const clarity = result.dimensions.find(d => d.name === 'Clarity')!;
+ expect(clarity.score).toBeGreaterThan(0); // code blocks boost clarity
+ });
+
+ it('handles very long content', () => {
+ const lines = ['# Big Project\n'];
+ for (let i = 0; i < 20; i++) {
+ lines.push(`\n## Section ${i}\n`);
+ for (let j = 0; j < 10; j++) {
+ lines.push(`- ALWAYS follow rule ${i}-${j}`);
+ }
+ }
+ const md = lines.join('\n');
+ const result = analyze(md);
+ expect(result.compositeScore).toBeGreaterThan(0);
+ expect(result.metrics.sectionCount).toBe(20);
+ });
+
+ it('handles content with vague language', () => {
+ const md = `# Project\n\n## Rules\n\n- Try to keep code clean\n- Should probably test things\n- Consider using types if possible\n- Might want to add docs when appropriate\n`;
+ const result = analyze(md);
+ const enforceability = result.dimensions.find(d => d.name === 'Enforceability')!;
+ expect(enforceability.findings.some(f => f.includes('vague'))).toBe(true);
+ });
+
+ it('benchmark handles identical content correctly', () => {
+ const result = benchmark(MINIMAL_CLAUDE_MD, MINIMAL_CLAUDE_MD);
+ expect(result.delta).toBe(0);
+ expect(result.improvements).toHaveLength(0);
+ expect(result.regressions).toHaveLength(0);
+ });
+
+ it('autoOptimize handles already-optimal content gracefully', () => {
+ // Even if content is already good, should not crash or regress
+ const result = autoOptimize(WELL_STRUCTURED_CLAUDE_MD, undefined, 5);
+ expect(result.benchmark.delta).toBeGreaterThanOrEqual(0);
+ expect(result.optimized.length).toBeGreaterThanOrEqual(WELL_STRUCTURED_CLAUDE_MD.length);
+ });
+});
diff --git a/v3/@claude-flow/guidance/tests/generators.test.ts b/v3/@claude-flow/guidance/tests/generators.test.ts
new file mode 100644
index 0000000000..b0f09766f2
--- /dev/null
+++ b/v3/@claude-flow/guidance/tests/generators.test.ts
@@ -0,0 +1,733 @@
+import { describe, it, expect } from 'vitest';
+import {
+ generateClaudeMd,
+ generateClaudeLocalMd,
+ generateSkillMd,
+ generateAgentMd,
+ generateAgentIndex,
+ scaffold,
+} from '../src/generators.js';
+import type {
+ ProjectProfile,
+ LocalProfile,
+ SkillDefinition,
+ AgentDefinition,
+} from '../src/generators.js';
+
+// ============================================================================
+// CLAUDE.md Generator
+// ============================================================================
+
+describe('generateClaudeMd', () => {
+ const minimal: ProjectProfile = {
+ name: 'my-app',
+ languages: ['typescript'],
+ };
+
+ it('generates valid markdown with project name as heading', () => {
+ const md = generateClaudeMd(minimal);
+ expect(md).toMatch(/^# my-app\n/);
+ });
+
+ it('includes language-specific invariants', () => {
+ const md = generateClaudeMd(minimal);
+ expect(md).toContain('No `any` types');
+ expect(md).toContain('Prefer `const` over `let`');
+ });
+
+ it('includes build and test section', () => {
+ const md = generateClaudeMd(minimal);
+ expect(md).toContain('## Build & Test');
+ expect(md).toContain('npm run build');
+ expect(md).toContain('npm test');
+ });
+
+ it('uses custom package manager', () => {
+ const md = generateClaudeMd({ ...minimal, packageManager: 'pnpm' });
+ expect(md).toContain('pnpm run build');
+ expect(md).toContain('pnpm test');
+ });
+
+ it('uses custom build and test commands', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ buildCommand: 'make build',
+ testCommand: 'make test',
+ });
+ expect(md).toContain('`make build`');
+ expect(md).toContain('`make test`');
+ });
+
+ it('includes lint command when provided', () => {
+ const md = generateClaudeMd({ ...minimal, lintCommand: 'npm run lint' });
+ expect(md).toContain('`npm run lint`');
+ });
+
+ it('includes description when provided', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ description: 'A web application for managing tasks',
+ });
+ expect(md).toContain('A web application for managing tasks');
+ });
+
+ it('includes monorepo note', () => {
+ const md = generateClaudeMd({ ...minimal, monorepo: true });
+ expect(md).toContain('monorepo');
+ });
+
+ it('includes source and test directories', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ srcDir: 'src',
+ testDir: 'tests',
+ });
+ expect(md).toContain('`src/`');
+ expect(md).toContain('`tests/`');
+ });
+
+ it('includes domain rules', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ domainRules: [
+ 'Never write to the users table without a migration',
+ 'API responses must include requestId',
+ ],
+ });
+ expect(md).toContain('## Domain Rules');
+ expect(md).toContain('Never write to the users table');
+ expect(md).toContain('requestId');
+ });
+
+ it('includes forbidden patterns', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ forbidden: ['Use eval()', 'Commit .env files'],
+ });
+ expect(md).toContain('NEVER: Use eval()');
+ expect(md).toContain('NEVER: Commit .env files');
+ });
+
+ it('includes required patterns', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ required: ['Run tests before committing'],
+ });
+ expect(md).toContain('ALWAYS: Run tests before committing');
+ });
+
+ it('includes conventions', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ conventions: ['Use semantic commit messages', 'Keep functions under 30 lines'],
+ });
+ expect(md).toContain('## Coding Standards');
+ expect(md).toContain('Use semantic commit messages');
+ });
+
+ it('includes framework rules', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ frameworks: ['React', 'Prisma'],
+ });
+ expect(md).toContain('## React Conventions');
+ expect(md).toContain('functional components');
+ expect(md).toContain('## Prisma Conventions');
+ expect(md).toContain('prisma generate');
+ });
+
+ it('always includes security section', () => {
+ const md = generateClaudeMd(minimal);
+ expect(md).toContain('## Security');
+ expect(md).toContain('Never commit secrets');
+ expect(md).toContain('destructive commands');
+ });
+
+ it('includes guidance control plane section when enabled', () => {
+ const md = generateClaudeMd({ ...minimal, guidanceControlPlane: true });
+ expect(md).toContain('## Guidance Control Plane');
+ expect(md).toContain('@claude-flow/guidance');
+ expect(md).toContain('Gates enforce');
+ });
+
+ it('includes WASM kernel note when enabled', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ guidanceControlPlane: true,
+ wasmKernel: true,
+ });
+ expect(md).toContain('WASM kernel');
+ expect(md).toContain('1.25-1.96x');
+ });
+
+ it('includes swarm configuration', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ swarm: { topology: 'hierarchical', maxAgents: 6, strategy: 'specialized' },
+ });
+ expect(md).toContain('## Swarm Configuration');
+ expect(md).toContain('hierarchical');
+ expect(md).toContain('6');
+ });
+
+ it('includes @imports', () => {
+ const md = generateClaudeMd({
+ ...minimal,
+ imports: ['~/.claude/my_instructions.md'],
+ });
+ expect(md).toContain('## Individual Preferences');
+ expect(md).toContain('@~/.claude/my_instructions.md');
+ });
+
+ it('handles Python language', () => {
+ const md = generateClaudeMd({ name: 'pyapp', languages: ['python'] });
+ expect(md).toContain('PEP 8');
+ expect(md).toContain('type hints');
+ });
+
+ it('handles Rust language', () => {
+ const md = generateClaudeMd({ name: 'rustapp', languages: ['rust'] });
+ expect(md).toContain('cargo clippy');
+ expect(md).toContain('unwrap()');
+ });
+
+ it('handles Go language', () => {
+ const md = generateClaudeMd({ name: 'goapp', languages: ['go'] });
+ expect(md).toContain('go vet');
+ expect(md).toContain('handle errors');
+ });
+
+ it('handles unknown language with generic rule', () => {
+ const md = generateClaudeMd({ name: 'app', languages: ['elixir'] });
+ expect(md).toContain('established elixir conventions');
+ });
+
+ it('handles multiple languages', () => {
+ const md = generateClaudeMd({
+ name: 'fullstack',
+ languages: ['typescript', 'python'],
+ });
+ expect(md).toContain('No `any` types');
+ expect(md).toContain('PEP 8');
+ });
+
+ it('generates constitution-friendly structure (invariants near top)', () => {
+ const md = generateClaudeMd(minimal);
+ const lines = md.split('\n');
+ // Core Invariants should appear in first 20 lines
+ const invariantLine = lines.findIndex(l => l.includes('Core Invariants'));
+ expect(invariantLine).toBeGreaterThan(-1);
+ expect(invariantLine).toBeLessThan(20);
+ });
+});
+
+// ============================================================================
+// CLAUDE.local.md Generator
+// ============================================================================
+
+describe('generateClaudeLocalMd', () => {
+ it('generates markdown with local development header', () => {
+ const md = generateClaudeLocalMd({});
+ expect(md).toContain('# Local Development Notes');
+ expect(md).toContain('auto-gitignored');
+ });
+
+ it('includes developer name', () => {
+ const md = generateClaudeLocalMd({ developer: 'Alice' });
+ expect(md).toContain('Developer: Alice');
+ });
+
+ it('includes local URLs', () => {
+ const md = generateClaudeLocalMd({
+ localUrls: {
+ API: 'http://localhost:3001',
+ Frontend: 'http://localhost:3000',
+ },
+ });
+ expect(md).toContain('## Local URLs');
+ expect(md).toContain('API: http://localhost:3001');
+ expect(md).toContain('Frontend: http://localhost:3000');
+ });
+
+ it('includes database connections', () => {
+ const md = generateClaudeLocalMd({
+ databases: {
+ dev: 'postgres://localhost:5432/myapp_dev',
+ },
+ });
+ expect(md).toContain('## Local Databases');
+ expect(md).toContain('postgres://localhost:5432/myapp_dev');
+ });
+
+ it('includes environment variables as bash exports', () => {
+ const md = generateClaudeLocalMd({
+ envVars: { NODE_ENV: 'development', DEBUG: 'true' },
+ });
+ expect(md).toContain('## Environment Variables');
+ expect(md).toContain('export NODE_ENV="development"');
+ expect(md).toContain('export DEBUG="true"');
+ });
+
+ it('includes preferences', () => {
+ const md = generateClaudeLocalMd({
+ preferences: ['Show git diffs before committing', 'Verbose error messages'],
+ });
+ expect(md).toContain('## Preferences');
+ expect(md).toContain('Show git diffs');
+ });
+
+ it('includes machine notes with OS and editor', () => {
+ const md = generateClaudeLocalMd({
+ os: 'macOS 15',
+ editor: 'VS Code',
+ machineNotes: ['16GB RAM', 'M2 chip'],
+ });
+ expect(md).toContain('## Machine Notes');
+ expect(md).toContain('OS: macOS 15');
+ expect(md).toContain('Editor: VS Code');
+ expect(md).toContain('16GB RAM');
+ });
+
+ it('includes debug settings', () => {
+ const md = generateClaudeLocalMd({
+ debug: ['Enable verbose logging', 'Skip rate limiting'],
+ });
+ expect(md).toContain('## Debug Settings');
+ expect(md).toContain('Enable verbose logging');
+ });
+});
+
+// ============================================================================
+// Skill Generator
+// ============================================================================
+
+describe('generateSkillMd', () => {
+ const skill: SkillDefinition = {
+ name: 'deploy-to-staging',
+ description: 'Deploy the application to the staging environment',
+ category: 'deployment',
+ tags: ['deploy', 'staging', 'ci-cd'],
+ requires: ['docker', 'kubectl'],
+ capabilities: ['Build Docker image', 'Push to registry', 'Apply k8s manifests'],
+ instructions: '## Steps\n\n1. Build the Docker image\n2. Push to registry\n3. Apply manifests',
+ };
+
+ it('generates valid YAML frontmatter', () => {
+ const md = generateSkillMd(skill);
+ expect(md).toMatch(/^---\n/);
+ expect(md).toContain('name: deploy-to-staging');
+ expect(md).toContain('version: 1.0.0');
+ expect(md).toContain('description: Deploy the application');
+ expect(md).toContain('category: deployment');
+ });
+
+ it('includes tags as array', () => {
+ const md = generateSkillMd(skill);
+ expect(md).toContain('tags: [deploy, staging, ci-cd]');
+ });
+
+ it('includes requires list', () => {
+ const md = generateSkillMd(skill);
+ expect(md).toContain('requires:');
+ expect(md).toContain(' - docker');
+ expect(md).toContain(' - kubectl');
+ });
+
+ it('includes capabilities list', () => {
+ const md = generateSkillMd(skill);
+ expect(md).toContain('capabilities:');
+ expect(md).toContain(' - Build Docker image');
+ });
+
+ it('includes skill title in title case', () => {
+ const md = generateSkillMd(skill);
+ expect(md).toContain('# Deploy To Staging Skill');
+ });
+
+ it('includes instructions body', () => {
+ const md = generateSkillMd(skill);
+ expect(md).toContain('## Steps');
+ expect(md).toContain('1. Build the Docker image');
+ });
+
+ it('uses custom version', () => {
+ const md = generateSkillMd({ ...skill, version: '2.0.0-beta.1' });
+ expect(md).toContain('version: 2.0.0-beta.1');
+ });
+
+ it('omits optional fields when not provided', () => {
+ const md = generateSkillMd({
+ name: 'simple',
+ description: 'A simple skill',
+ category: 'core',
+ instructions: 'Do the thing.',
+ });
+ expect(md).not.toContain('tags:');
+ expect(md).not.toContain('requires:');
+ expect(md).not.toContain('capabilities:');
+ });
+});
+
+// ============================================================================
+// Agent Generator
+// ============================================================================
+
+describe('generateAgentMd', () => {
+ const agent: AgentDefinition = {
+ name: 'security-auditor',
+ type: 'security-specialist',
+ description: 'Audits code for security vulnerabilities',
+ category: 'security',
+ color: '#E74C3C',
+ capabilities: ['secret-scanning', 'dependency-audit', 'sast'],
+ focus: ['authentication', 'authorization', 'input-validation'],
+ temperature: 0.1,
+ priority: 'high',
+ systemPrompt: 'You are a security specialist. Report all findings with severity levels.',
+ instructions: 'Scan all changed files for OWASP Top 10 vulnerabilities.',
+ };
+
+ it('generates valid YAML frontmatter', () => {
+ const md = generateAgentMd(agent);
+ expect(md).toMatch(/^---\n/);
+ expect(md).toContain('name: security-auditor');
+ expect(md).toContain('type: security-specialist');
+ expect(md).toContain('color: "#E74C3C"');
+ expect(md).toContain('temperature: 0.1');
+ expect(md).toContain('priority: high');
+ });
+
+ it('includes capabilities list', () => {
+ const md = generateAgentMd(agent);
+ expect(md).toContain('capabilities:');
+ expect(md).toContain(' - secret-scanning');
+ expect(md).toContain(' - dependency-audit');
+ });
+
+ it('includes focus areas', () => {
+ const md = generateAgentMd(agent);
+ expect(md).toContain('focus:');
+ expect(md).toContain(' - authentication');
+ });
+
+ it('includes system prompt section', () => {
+ const md = generateAgentMd(agent);
+ expect(md).toContain('## System Prompt');
+ expect(md).toContain('security specialist');
+ });
+
+ it('includes instructions section', () => {
+ const md = generateAgentMd(agent);
+ expect(md).toContain('## Instructions');
+ expect(md).toContain('OWASP Top 10');
+ });
+
+ it('includes agent title in title case', () => {
+ const md = generateAgentMd(agent);
+ expect(md).toContain('# Security Auditor Agent');
+ });
+
+ it('includes hooks when provided', () => {
+ const md = generateAgentMd({
+ ...agent,
+ preHook: 'echo "Starting security audit"',
+ postHook: 'echo "Audit complete"',
+ });
+ expect(md).toContain('hooks:');
+ expect(md).toContain('pre: |');
+ expect(md).toContain('Starting security audit');
+ expect(md).toContain('post: |');
+ expect(md).toContain('Audit complete');
+ });
+
+ it('defaults temperature to 0.2', () => {
+ const md = generateAgentMd({
+ name: 'basic',
+ type: 'developer',
+ description: 'Basic agent',
+ });
+ expect(md).toContain('temperature: 0.2');
+ });
+
+ it('omits optional fields when not provided', () => {
+ const md = generateAgentMd({
+ name: 'minimal',
+ type: 'custom',
+ description: 'Minimal agent',
+ });
+ expect(md).not.toContain('color:');
+ expect(md).not.toContain('priority:');
+ expect(md).not.toContain('hooks:');
+ expect(md).not.toContain('## System Prompt');
+ expect(md).not.toContain('## Instructions');
+ });
+});
+
+// ============================================================================
+// Agent Index Generator
+// ============================================================================
+
+describe('generateAgentIndex', () => {
+ const agents: AgentDefinition[] = [
+ { name: 'coordinator', type: 'coordinator', description: 'Coordinates work' },
+ { name: 'coder', type: 'developer', description: 'Writes code' },
+ { name: 'tester', type: 'tester', description: 'Writes tests' },
+ { name: 'auditor', type: 'security-specialist', description: 'Audits security' },
+ ];
+
+ it('lists all agents', () => {
+ const yaml = generateAgentIndex(agents);
+ expect(yaml).toContain(' - coordinator');
+ expect(yaml).toContain(' - coder');
+ expect(yaml).toContain(' - tester');
+ expect(yaml).toContain(' - auditor');
+ });
+
+ it('groups agents by type', () => {
+ const yaml = generateAgentIndex(agents);
+ expect(yaml).toContain('types:');
+ expect(yaml).toContain(' coordinator:');
+ expect(yaml).toContain(' developer:');
+ expect(yaml).toContain(' tester:');
+ expect(yaml).toContain(' security-specialist:');
+ });
+
+ it('handles empty list', () => {
+ const yaml = generateAgentIndex([]);
+ expect(yaml).toContain('agents:');
+ expect(yaml).toContain('types:');
+ });
+});
+
+// ============================================================================
+// Scaffold (Full .claude/ Structure)
+// ============================================================================
+
+describe('scaffold', () => {
+ it('generates CLAUDE.md', () => {
+ const result = scaffold({
+ project: { name: 'test-app', languages: ['typescript'] },
+ });
+ expect(result.files.has('CLAUDE.md')).toBe(true);
+ expect(result.files.get('CLAUDE.md')).toContain('# test-app');
+ });
+
+ it('generates CLAUDE.local.md when local profile provided', () => {
+ const result = scaffold({
+ project: { name: 'test-app', languages: ['typescript'] },
+ local: { developer: 'Alice', preferences: ['Verbose output'] },
+ });
+ expect(result.files.has('CLAUDE.local.md')).toBe(true);
+ expect(result.files.get('CLAUDE.local.md')).toContain('Alice');
+ });
+
+ it('does not generate CLAUDE.local.md when not provided', () => {
+ const result = scaffold({
+ project: { name: 'test-app', languages: ['typescript'] },
+ });
+ expect(result.files.has('CLAUDE.local.md')).toBe(false);
+ });
+
+ it('generates custom agents in correct paths', () => {
+ const result = scaffold({
+ project: { name: 'test-app', languages: ['typescript'] },
+ agents: [
+ {
+ name: 'my-agent',
+ type: 'custom',
+ description: 'A custom agent',
+ category: 'custom',
+ },
+ ],
+ });
+ expect(result.files.has('.claude/agents/custom/my-agent.md')).toBe(true);
+ expect(result.files.has('.claude/agents/index.yaml')).toBe(true);
+ });
+
+ it('generates custom skills in correct paths', () => {
+ const result = scaffold({
+ project: { name: 'test-app', languages: ['typescript'] },
+ skills: [
+ {
+ name: 'my-skill',
+ description: 'A custom skill',
+ category: 'custom',
+ instructions: 'Do the thing',
+ },
+ ],
+ });
+ expect(result.files.has('.claude/skills/my-skill/SKILL.md')).toBe(true);
+ });
+
+ it('includes default agents when requested', () => {
+ const result = scaffold({
+ project: { name: 'test-app', languages: ['typescript'] },
+ includeDefaultAgents: true,
+ });
+ expect(result.files.has('.claude/agents/core/coordinator.md')).toBe(true);
+ expect(result.files.has('.claude/agents/core/coder.md')).toBe(true);
+ expect(result.files.has('.claude/agents/core/tester.md')).toBe(true);
+ expect(result.files.has('.claude/agents/core/reviewer.md')).toBe(true);
+ expect(result.files.has('.claude/agents/index.yaml')).toBe(true);
+ });
+
+ it('includes security agent when guidance control plane is enabled', () => {
+ const result = scaffold({
+ project: {
+ name: 'test-app',
+ languages: ['typescript'],
+ guidanceControlPlane: true,
+ },
+ includeDefaultAgents: true,
+ });
+ expect(result.files.has('.claude/agents/security/security-auditor.md')).toBe(true);
+ });
+
+ it('includes default skills when requested', () => {
+ const result = scaffold({
+ project: { name: 'test-app', languages: ['typescript'] },
+ includeDefaultSkills: true,
+ });
+ expect(result.files.has('.claude/skills/build-and-test/SKILL.md')).toBe(true);
+ expect(result.files.has('.claude/skills/code-review/SKILL.md')).toBe(true);
+ });
+
+ it('includes guidance skill when control plane is enabled', () => {
+ const result = scaffold({
+ project: {
+ name: 'test-app',
+ languages: ['typescript'],
+ guidanceControlPlane: true,
+ },
+ includeDefaultSkills: true,
+ });
+ expect(result.files.has('.claude/skills/guidance-enforcement/SKILL.md')).toBe(true);
+ });
+
+ it('merges custom and default agents', () => {
+ const result = scaffold({
+ project: { name: 'test-app', languages: ['typescript'] },
+ agents: [{ name: 'custom-bot', type: 'custom', description: 'Custom' }],
+ includeDefaultAgents: true,
+ });
+ // Custom agent
+ expect(result.files.has('.claude/agents/core/custom-bot.md')).toBe(true);
+ // Default agents
+ expect(result.files.has('.claude/agents/core/coordinator.md')).toBe(true);
+ // Index includes all
+ const index = result.files.get('.claude/agents/index.yaml')!;
+ expect(index).toContain('custom-bot');
+ expect(index).toContain('coordinator');
+ });
+
+ it('generates a full project scaffold with all features', () => {
+ const result = scaffold({
+ project: {
+ name: 'enterprise-app',
+ description: 'An enterprise SaaS application',
+ languages: ['typescript', 'python'],
+ frameworks: ['React', 'Express', 'Prisma'],
+ packageManager: 'pnpm',
+ monorepo: true,
+ srcDir: 'packages/*/src',
+ testDir: 'packages/*/tests',
+ buildCommand: 'pnpm -r build',
+ testCommand: 'pnpm -r test',
+ lintCommand: 'pnpm -r lint',
+ domainRules: ['All API endpoints require authentication'],
+ conventions: ['Use conventional commits'],
+ forbidden: ['console.log in production code'],
+ required: ['Error boundary on every page'],
+ guidanceControlPlane: true,
+ wasmKernel: true,
+ swarm: { topology: 'hierarchical', maxAgents: 8, strategy: 'specialized' },
+ imports: ['~/.claude/my_prefs.md'],
+ },
+ local: {
+ developer: 'Alice',
+ localUrls: { API: 'http://localhost:4000' },
+ databases: { dev: 'postgres://localhost/dev' },
+ preferences: ['Dark mode', 'Verbose output'],
+ editor: 'Cursor',
+ os: 'macOS 15',
+ machineNotes: ['Apple Silicon M2'],
+ },
+ includeDefaultAgents: true,
+ includeDefaultSkills: true,
+ });
+
+ // Count files
+ expect(result.files.size).toBeGreaterThanOrEqual(10);
+
+ // CLAUDE.md has all sections
+ const claudeMd = result.files.get('CLAUDE.md')!;
+ expect(claudeMd).toContain('# enterprise-app');
+ expect(claudeMd).toContain('SaaS application');
+ expect(claudeMd).toContain('PEP 8');
+ expect(claudeMd).toContain('No `any` types');
+ expect(claudeMd).toContain('## React Conventions');
+ expect(claudeMd).toContain('## Prisma Conventions');
+ expect(claudeMd).toContain('## Domain Rules');
+ expect(claudeMd).toContain('authentication');
+ expect(claudeMd).toContain('NEVER: console.log');
+ expect(claudeMd).toContain('ALWAYS: Error boundary');
+ expect(claudeMd).toContain('## Guidance Control Plane');
+ expect(claudeMd).toContain('WASM kernel');
+ expect(claudeMd).toContain('## Swarm Configuration');
+ expect(claudeMd).toContain('@~/.claude/my_prefs.md');
+
+ // CLAUDE.local.md
+ const localMd = result.files.get('CLAUDE.local.md')!;
+ expect(localMd).toContain('Alice');
+ expect(localMd).toContain('http://localhost:4000');
+ expect(localMd).toContain('postgres://localhost/dev');
+ expect(localMd).toContain('Cursor');
+ });
+});
+
+// ============================================================================
+// Edge cases
+// ============================================================================
+
+describe('edge cases', () => {
+ it('handles empty arrays gracefully', () => {
+ const md = generateClaudeMd({
+ name: 'app',
+ languages: [],
+ });
+ expect(md).toContain('# app');
+ // Should not crash even with empty languages
+ });
+
+ it('handles all framework types', () => {
+ const frameworks = ['react', 'nextjs', 'express', 'fastify', 'django', 'flask', 'prisma', 'vitest', 'jest'];
+ for (const fw of frameworks) {
+ const md = generateClaudeMd({
+ name: 'test',
+ languages: ['typescript'],
+ frameworks: [fw],
+ });
+ expect(md).toContain(`## ${fw} Conventions`);
+ }
+ });
+
+ it('handles unknown framework gracefully', () => {
+ const md = generateClaudeMd({
+ name: 'test',
+ languages: ['typescript'],
+ frameworks: ['svelte'],
+ });
+ // Unknown framework should not produce a section (no rules to add)
+ expect(md).not.toContain('## svelte Conventions');
+ });
+
+ it('agent index correctly groups multiple agents of same type', () => {
+ const yaml = generateAgentIndex([
+ { name: 'frontend-dev', type: 'developer', description: 'Frontend' },
+ { name: 'backend-dev', type: 'developer', description: 'Backend' },
+ ]);
+ expect(yaml).toContain(' developer:');
+ expect(yaml).toContain(' - frontend-dev');
+ expect(yaml).toContain(' - backend-dev');
+ });
+});