#!/usr/bin/env node

/**

* GEPA Optimizer

*

* Genetic Eval-driven Prompt Algorithm for optimizing CLAUDE.md

*

* Usage:

* node optimize.js init # Initialize with current CLAUDE.md

* node optimize.js mutate # Generate new variants

* node optimize.js eval [variant] # Run evals on variant(s)

* node optimize.js score [--auto-apply] # Score all variants in generation

* node optimize.js select # Select best, advance generation

* node optimize.js run [gens] [--auto-apply] # Full optimization loop

* node optimize.js status # Show current status

* node optimize.js diff [a] [b] # Compare two variants

*

* Flags:

* --auto-apply Apply winning variant to target file automatically

* --no-cache Bypass eval response cache (force fresh eval)

* --target <name> Optimize a specific target from config.targets[]

* --phase <name> Phase-scoped mutation for conductor prompts

* --auto-phase Auto-detect worst phase from outcomes.jsonl

*/

import fs from 'fs';

import path from 'path';

import { fileURLToPath } from 'url';

import { spawn, execSync } from 'child_process';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const PROJECT_ROOT = path.resolve(__dirname, '../..');

// Load .env from project root

const envPath = path.join(PROJECT_ROOT, '.env');

if (fs.existsSync(envPath)) {

for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {

const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);

if (match && !process.env[match[1]]) {

process.env[match[1]] = match[2].replace(/^["']|["']$/g, '');

}

}

}

// Configuration

const CONFIG_PATH = path.join(__dirname, 'config.json');

const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));

// --target <name> selects from targets[] array (multi-target mode)

const targetIdx = process.argv.indexOf('--target');

const targetName = targetIdx !== -1 ? process.argv[targetIdx + 1] : null;

if (targetIdx !== -1) process.argv.splice(targetIdx, 2);

if (targetName && config.targets) {

const target = config.targets.find((t) => t.name === targetName);

if (!target) {

console.error(

`Error: Unknown target "${targetName}". Available: ${config.targets.map((t) => t.name).join(', ')}`

);

process.exit(1);

}

config.target.file = target.file;

if (target.evals) config.evals.files = target.evals;

console.log(`Target: ${targetName} (${target.description || target.file})`);

}

// --profile <name> overrides config sections (legacy single-target mode)

const profileIdx = process.argv.indexOf('--profile');

const profileName = profileIdx !== -1 ? process.argv[profileIdx + 1] : null;

if (profileIdx !== -1) process.argv.splice(profileIdx, 2);

if (profileName) {

const profiles = config.profiles || {};

if (!profiles[profileName]) {

console.error(

`Error: Unknown profile "${profileName}". Available: ${Object.keys(profiles).join(', ')}`

);

process.exit(1);

}

const profile = profiles[profileName];

// Merge profile overrides into config

if (profile.target) {

Object.assign(config.target, profile.target);

}

if (profile.evolution?.mutationStrategies) {

config.evolution.mutationStrategies = profile.evolution.mutationStrategies;

}

if (profile.evals?.files) {

config.evals.files = profile.evals.files;

}

console.log(`Using profile: ${profileName}`);

}

const GEPA_DIR = process.env.GEPA_DIR || __dirname;

const GENERATIONS_DIR = path.join(GEPA_DIR, 'generations');

const RESULTS_DIR = path.join(GEPA_DIR, 'results');

const EVALS_DIR = path.join(GEPA_DIR, 'evals');

// --phase <name> scopes optimization to a single conductor phase file

const phaseIdx = process.argv.indexOf('--phase');

const phaseName = phaseIdx !== -1 ? process.argv[phaseIdx + 1] : null;

if (phaseIdx !== -1) process.argv.splice(phaseIdx, 2);

// --auto-apply: automatically apply winning variant when threshold is reached

const autoApply = process.argv.includes('--auto-apply');

if (autoApply) process.argv.splice(process.argv.indexOf('--auto-apply'), 1);

const CONDUCTOR_PROMPTS_DIR = path.join(

process.env.HOME || '',

'.stackmemory',

'conductor',

'prompts'

);

// Eval response cache — deterministic baselines via record/replay

const EVAL_CACHE_DIR = path.join(GEPA_DIR, 'cache');

if (!fs.existsSync(EVAL_CACHE_DIR))

fs.mkdirSync(EVAL_CACHE_DIR, { recursive: true });

import { createHash } from 'crypto';

function evalCacheKey(taskId, variantContent) {

return createHash('sha256')

.update(`${taskId}:${variantContent.slice(0, 500)}`)

.digest('hex')

.slice(0, 16);

}

function getCachedEvalResult(taskId, variantContent) {

if (process.argv.includes('--no-cache')) return null;

const key = evalCacheKey(taskId, variantContent);

const cachePath = path.join(EVAL_CACHE_DIR, `${key}.json`);

if (fs.existsSync(cachePath)) {

try {

return JSON.parse(fs.readFileSync(cachePath, 'utf8'));

} catch {

return null;

}

}

return null;

}

function setCachedEvalResult(taskId, variantContent, result) {

const key = evalCacheKey(taskId, variantContent);

const cachePath = path.join(EVAL_CACHE_DIR, `${key}.json`);

fs.writeFileSync(cachePath, JSON.stringify(result));

}

/**

* Skill-aware optimization: read usage data from skill-audit.jsonl

* and build context for skill-scoped mutations.

*/

function getSkillAuditContext(skillName) {

const auditPath = path.join(

process.env.HOME || '',

'.stackmemory',

'skill-audit.jsonl'

);

if (!fs.existsSync(auditPath)) return '';

try {

const lines = fs

.readFileSync(auditPath, 'utf8')

.split('\n')

.filter(Boolean);

const entries = lines.map((l) => JSON.parse(l));

// Filter to this skill

const skillEntries = entries.filter((e) => e.skill === skillName);

if (skillEntries.length === 0) return '';

const total = skillEntries.length;

const errors = skillEntries.filter((e) => e.error).length;

const errorRate = ((errors / total) * 100).toFixed(1);

// Common args patterns

const argCounts = {};

for (const e of skillEntries) {

const arg = e.args || '(none)';

argCounts[arg] = (argCounts[arg] || 0) + 1;

}

const topArgs = Object.entries(argCounts)

.sort((a, b) => b[1] - a[1])

.slice(0, 5)

.map(([arg, count]) => ` - "${arg}": ${count}x`)

.join('\n');

// Recent errors

const recentErrors = skillEntries

.filter((e) => e.error)

.slice(-5)

.map((e) => ` - ${e.ts}: args="${e.args}"`)

.join('\n');

let ctx = `\n## Skill usage data for "${skillName}" (${total} invocations, ${errorRate}% error rate):\n`;

ctx += `\nMost common args:\n${topArgs}\n`;

if (recentErrors) {

ctx += `\nRecent errors:\n${recentErrors}\n`;

}

return ctx;

} catch {

return '';

}

}

/**

* Phase-aware optimization: read failure data from outcomes.jsonl

* and build context for phase-scoped mutations.

*/

function getPhaseFailureContext(phase) {

const outcomesPath = path.join(

process.env.HOME || '',

'.stackmemory',

'conductor',

'outcomes.jsonl'

);

if (!fs.existsSync(outcomesPath)) return '';

try {

const lines = fs

.readFileSync(outcomesPath, 'utf8')

.split('\n')

.filter(Boolean);

const recent = lines.slice(-100).map((l) => JSON.parse(l));

const phaseFailures = recent.filter(

(o) => o.outcome === 'failure' && o.phase === phase

);

if (phaseFailures.length === 0) return '';

const examples = phaseFailures.slice(-10).map((f) => {

const err = f.errorTail || 'unknown error';

return `- ${f.issue} (attempt ${f.attempt}): ${err.slice(0, 200)}`;

});

return `\n## Recent failures in "${phase}" phase (${phaseFailures.length} of last ${recent.length} runs):\n${examples.join('\n')}\n`;

} catch {

return '';

}

}

/**

* Auto-detect worst phase from outcomes for targeted optimization

*/

function detectWorstPhase() {

const outcomesPath = path.join(

process.env.HOME || '',

'.stackmemory',

'conductor',

'outcomes.jsonl'

);

if (!fs.existsSync(outcomesPath)) return null;

try {

const lines = fs

.readFileSync(outcomesPath, 'utf8')

.split('\n')

.filter(Boolean);

const recent = lines.slice(-50).map((l) => JSON.parse(l));

const failures = recent.filter((o) => o.outcome === 'failure');

if (failures.length === 0) return null;

// Group by phase, find worst

const byPhase = {};

for (const f of failures) {

const p = mapAgentPhaseToPromptPhase(f.phase);

byPhase[p] = (byPhase[p] || 0) + 1;

}

const sorted = Object.entries(byPhase).sort((a, b) => b[1] - a[1]);

return sorted[0]?.[0] || null;

} catch {

return null;

}

}

/** Map conductor AgentPhase names to prompt phase file names */

function mapAgentPhaseToPromptPhase(agentPhase) {

const map = {

reading: 'understand',

planning: 'understand',

implementing: 'implement',

testing: 'validate',

linting: 'validate',

building: 'validate',

committing: 'deliver',

};

return map[agentPhase] || 'implement';

}

// Ensure directories

[GENERATIONS_DIR, RESULTS_DIR, EVALS_DIR].forEach((dir) => {

if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });

});

/**

* State management

*/

function getState() {

const statePath = path.join(GEPA_DIR, 'state.json');

if (fs.existsSync(statePath)) {

return JSON.parse(fs.readFileSync(statePath, 'utf8'));

}

return {

currentGeneration: 0,

bestVariant: null,

bestScore: 0,

history: [],

};

}

function saveState(state) {

fs.writeFileSync(

path.join(GEPA_DIR, 'state.json'),

JSON.stringify(state, null, 2)

);

}

/**

* Get path for a generation/variant

*/

function getGenPath(gen, variant = null) {

const genDir = path.join(

GENERATIONS_DIR,

`gen-${String(gen).padStart(3, '0')}`

);

if (!fs.existsSync(genDir)) fs.mkdirSync(genDir, { recursive: true });

return variant ? path.join(genDir, `${variant}.md`) : genDir;

}

/**

* Initialize GEPA with current CLAUDE.md

*/

async function init(targetPath) {

const resolvedTarget = targetPath || config.target.file || 'CLAUDE.md';

const claudeMdPath = resolvedTarget.startsWith('~')

? path.join(process.env.HOME, resolvedTarget.slice(1))

: path.resolve(resolvedTarget);

if (!fs.existsSync(claudeMdPath)) {

console.error(`Error: ${claudeMdPath} not found`);

process.exit(1);

}

const content = fs.readFileSync(claudeMdPath, 'utf8');

const genPath = getGenPath(0, 'baseline');

fs.writeFileSync(genPath, content);

const state = {

currentGeneration: 0,

bestVariant: 'baseline',

bestScore: 0,

targetPath: claudeMdPath,

history: [

{

generation: 0,

variant: 'baseline',

action: 'init',

timestamp: new Date().toISOString(),

},

],

};

saveState(state);

console.log(`Initialized GEPA with ${claudeMdPath}`);

console.log(`Baseline saved to ${genPath}`);

}

/**

* Generate mutations of the current best variant

*/

async function mutate() {

const state = getState();

const nextGen = state.currentGeneration + 1;

const currentBest = fs.readFileSync(

getGenPath(state.currentGeneration, state.bestVariant),

'utf8'

);

console.log(

`Generating ${config.evolution.populationSize} variants for generation ${nextGen}...`

);

const mutations = config.evolution.mutationStrategies;

const variants = [];

for (let i = 0; i < config.evolution.populationSize; i++) {

const strategy = mutations[i % mutations.length];

const variantName = `variant-${String.fromCharCode(97 + i)}`; // a, b, c, d...

console.log(` Creating ${variantName} using strategy: ${strategy}`);

const mutatedContent = await generateMutation(currentBest, strategy, state);

const variantPath = getGenPath(nextGen, variantName);

fs.writeFileSync(variantPath, mutatedContent);

variants.push({ name: variantName, strategy, path: variantPath });

}

// Also copy baseline for comparison

fs.writeFileSync(getGenPath(nextGen, 'baseline'), currentBest);

state.history.push({

generation: nextGen,

action: 'mutate',

variants: variants.map((v) => v.name),

timestamp: new Date().toISOString(),

});

saveState(state);

console.log(

`\nGenerated ${variants.length} variants in gen-${String(nextGen).padStart(3, '0')}/`

);

// Generate crossover children from previous generation's top variants

const crossoverCount = config.evolution.crossoverCount || 0;

if (crossoverCount > 0 && state.history.length > 0) {

const lastSelect = [...state.history]

.reverse()

.find((h) => h.action === 'select' && h.scores?.length >= 2);

if (lastSelect) {

const topTwo = lastSelect.scores.slice(0, 2);

const parentAPath = getGenPath(

state.currentGeneration,

topTwo[0].variant

);

const parentBPath = getGenPath(

state.currentGeneration,

topTwo[1].variant

);

if (fs.existsSync(parentAPath) && fs.existsSync(parentBPath)) {

const parentA = fs.readFileSync(parentAPath, 'utf8');

const parentB = fs.readFileSync(parentBPath, 'utf8');

for (let c = 0; c < crossoverCount; c++) {

const child = crossover(parentA, parentB);

const childName = `crossover-${String.fromCharCode(97 + c)}`;

fs.writeFileSync(getGenPath(nextGen, childName), child);

variants.push({

name: childName,

strategy: 'crossover',

path: getGenPath(nextGen, childName),

});

console.log(` Created ${childName} using strategy: crossover`);

}

}

}

}

return variants;

}

/**

* Crossover: combine sections from two parent variants.

* For each markdown section, randomly pick from parent A or B.

*/

function crossover(parentA, parentB) {

const sectionsA = parseSections(parentA.split('\n'));

const sectionsB = parseSections(parentB.split('\n'));

const allKeys = [

...new Set([...Object.keys(sectionsA), ...Object.keys(sectionsB)]),

];

const result = [];

for (const key of allKeys) {

const hasA = key in sectionsA && sectionsA[key].trim();

const hasB = key in sectionsB && sectionsB[key].trim();

// Randomly pick source, preferring the one that has content

let content;

if (hasA && hasB) {

content = Math.random() < 0.5 ? sectionsA[key] : sectionsB[key];

} else {

content = hasA ? sectionsA[key] : sectionsB[key];

}

if (key !== '__preamble__') {

// Reconstruct heading — find depth from original

const depthA = parentA.match(

new RegExp(

`^(#{1,4})\\s+${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,

'm'

)

);

const prefix = depthA ? depthA[1] : '##';

result.push(`${prefix} ${key}`);

}

if (content) result.push(content);

result.push('');

}

return result.join('\n').trim();

}

/**

* Phase-scoped mutation: optimize a single conductor phase file

* using failure data from outcomes.jsonl.

*/

async function mutatePhase(phase) {

const phasePath = path.join(CONDUCTOR_PROMPTS_DIR, `${phase}.md`);

if (!fs.existsSync(phasePath)) {

console.error(`[GEPA] Phase file not found: ${phasePath}`);

return;

}

const current = fs.readFileSync(phasePath, 'utf8');

const failureContext = getPhaseFailureContext(phase);

const state = getState();

const nextGen = state.currentGeneration + 1;

console.log(`[GEPA] Phase-scoped optimization: ${phase}`);

if (failureContext) {

console.log(`[GEPA] Including failure context from outcomes.jsonl`);

}

const genDir = getGenPath(nextGen);

if (!fs.existsSync(genDir)) fs.mkdirSync(genDir, { recursive: true });

// Generate 2 variants (smaller population for phase-level)

const mutations = config.evolution.mutationStrategies;

const variants = [];

for (let i = 0; i < 2; i++) {

const strategy =

mutations[(state.currentGeneration + i) % mutations.length];

const variantName = `phase-${phase}-${String.fromCharCode(97 + i)}`;

console.log(` Creating ${variantName} using strategy: ${strategy}`);

// Inject phase-specific context into mutation prompt

const phaseAugmented = `${current}\n${failureContext}`;

const mutatedContent = await generateMutation(

phaseAugmented,

strategy,

state

);

const variantPath = path.join(genDir, `${variantName}.md`);

fs.writeFileSync(variantPath, mutatedContent);

variants.push({ name: variantName, strategy, path: variantPath, phase });

}

// Save baseline

fs.writeFileSync(path.join(genDir, `phase-${phase}-baseline.md`), current);

state.history.push({

generation: nextGen,

action: 'mutate-phase',

phase,

variants: variants.map((v) => v.name),

timestamp: new Date().toISOString(),

});

saveState(state);

console.log(

`\n[GEPA] Generated ${variants.length} phase variants for ${phase}`

);

return variants;

}

/**

* Strategy definitions: prompt, motivation, and example for each mutation type.

* Motivation helps Claude generalize the intent (per Anthropic best practices).

* Examples give few-shot grounding so mutations are concrete, not vague.

*/

const STRATEGIES = {

rephrase: {

prompt: `Rephrase instructions for clarity without changing meaning. Make them more direct and actionable.`,

motivation: `Claude responds best to clear, explicit instructions. Vague phrasing causes the model to infer intent, leading to inconsistent behavior across sessions.`,

example: {

before: `NEVER use ellipses`,

after: `Your response will be read aloud by a TTS engine, so never use ellipses since TTS cannot pronounce them.`,

why: `Adding motivation helps Claude generalize — it now avoids other TTS-unfriendly patterns too.`,

},

},

add_examples: {

prompt: `Add concrete examples where instructions are abstract. Wrap examples in <example> tags so Claude distinguishes them from instructions.`,

motivation: `Examples are the most reliable way to steer output format, tone, and structure. 3-5 well-crafted examples dramatically improve accuracy. Abstract rules without examples leave too much room for interpretation.`,

example: {

before: `Use clean commit messages`,

after: `Use clean commit messages following conventional commits:\n<example>\nfeat(auth): add OAuth2 PKCE flow\nfix(api): prevent null tenant_id in query route\nchore: update dependencies\n</example>`,

why: `Concrete examples eliminate ambiguity about what "clean" means in this codebase.`,

},

},

remove_redundancy: {

prompt: `Remove redundant or repetitive instructions. Consolidate similar rules. Keep it DRY.`,

motivation: `Redundant instructions waste token budget and can cause conflicting interpretations when the same rule is phrased differently in two places. Consolidation also improves scannability.`,

example: {

before: `Don't create unnecessary files.\n...\nAvoid creating new files unless needed.\n...\nPrefer editing existing files over creating new ones.`,

after: `Prefer editing existing files. Only create new files when the task explicitly requires it.`,

why: `Three scattered rules consolidated into one clear directive — fewer tokens, less ambiguity.`,

},

},

restructure: {

prompt: `Reorganize sections for better flow. Group related instructions. Improve hierarchy. Put critical constraints early.`,

motivation: `Queries and critical instructions placed after long content blocks can improve response quality by up to 30%. Grouping related rules reduces misinterpretation when Claude scans for relevant instructions.`,

example: {

before: `## Commands\n...\n## Testing\n...\n## Git\n...\n## Testing Rules\n...`,

after: `## Commands\n...\n## Testing\n### Running Tests\n...\n### Testing Rules\n...\n## Git\n...`,

why: `Testing rules grouped under Testing header — Claude finds them together instead of scattered.`,

},

},

add_constraints: {

prompt: `Add specific constraints and guardrails based on common failure modes. Be precise about what NOT to do. Frame as "do X instead of Y" rather than just "don't do Y".`,

motivation: `Claude follows "do X instead of Y" better than bare prohibitions. Telling Claude what to do instead gives it a clear action path. Bare "don't" rules leave it guessing what the alternative is.`,

example: {

before: `Don't use markdown in responses`,

after: `Your response should be composed of smoothly flowing prose paragraphs. Reserve markdown for inline code, code blocks, and simple headings only.`,

why: `Positive framing ("do this") outperforms negative framing ("don't do that") — Claude has a clear target.`,

},

},

simplify: {

prompt: `Simplify complex instructions. Break down multi-step rules into sequential steps. Use numbered lists when order matters.`,

motivation: `Complex compound instructions are often partially followed. Breaking them into numbered steps ensures each step is executed. Sequential steps as numbered lists signal that order and completeness matter.`,

example: {

before: `Before committing, make sure to lint, test, check for secrets, and verify the build passes`,

after: `Before committing:\n1. Run lint: \`npm run lint\`\n2. Run tests: \`npm test\`\n3. Verify no secrets in staged files\n4. Verify build: \`npm run build\``,

why: `Each step is independently verifiable — Claude can check them off rather than interpreting a run-on sentence.`,

},

},

add_xml_structure: {

prompt: `Wrap distinct sections of the prompt in descriptive XML tags (e.g. <instructions>, <constraints>, <context>, <examples>). Use nested tags when content has natural hierarchy. Keep tag names consistent and descriptive.`,

motivation: `XML tags help Claude parse complex prompts unambiguously. When a prompt mixes instructions, context, examples, and variable inputs, tags prevent misinterpretation of which content serves which purpose.`,

example: {

before: `## Security\nNEVER commit secrets. Always validate input. Use parameterized queries.`,

after: `<security_constraints>\n## Security\nNEVER commit secrets. Always validate input. Use parameterized queries.\n</security_constraints>`,

why: `XML boundary makes it unambiguous that these are hard constraints, not suggestions. Claude weights tagged constraints more reliably.`,

},

},

add_role: {

prompt: `Add or refine a role definition at the top of the prompt. Even a single sentence focusing Claude's behavior and expertise makes a measurable difference. The role should match the actual use case.`,

motivation: `Setting a role in the system prompt focuses Claude's behavior and tone. A coding assistant role primes different behavior than a general assistant. Role + domain expertise = more targeted responses.`,

example: {

before: `# CLAUDE.md\n\n## Project Overview\nThis is a Node/Express API...`,

after: `# CLAUDE.md\n\nYou are a senior full-stack engineer working on this Node/Express/PostgreSQL monolith. Prioritize working code over explanations.\n\n## Project Overview\nThis is a Node/Express API...`,

why: `Role primes Claude to write code directly rather than explaining concepts — matches the actual use case.`,

},

},

add_motivation: {

prompt: `For existing rules that lack context, add a brief "why" explanation. Claude generalizes better from motivated rules — it can apply the spirit of the rule to edge cases the rule doesn't explicitly cover.`,

motivation: `Providing context or motivation behind instructions helps Claude understand goals and deliver more targeted responses. A rule with a reason is followed more reliably than a bare directive.`,

example: {

before: `Run npm test in a sub-agent, not inline`,

after: `Run npm test in a sub-agent, not inline — tests are long-running (3 parallel Jest suites) and their output pollutes the conversation context, making it harder to track the actual task.`,

why: `Now Claude understands it's about context pollution, so it applies the same logic to other long-running commands.`,

},

},

calibrate_tool_usage: {

prompt: `Review tool-triggering language in the prompt. Replace aggressive phrasing ("CRITICAL: You MUST use this tool", "ALWAYS use", "If in doubt, use") with proportionate guidance ("Use this tool when..."). Opus 4.6 overtriggers on language that was needed for previous models.`,

motivation: `Claude Opus 4.6 is significantly more proactive than previous models. Instructions designed to prevent undertriggering now cause overtriggering — spawning subagents for simple greps, using tools when direct action suffices. Dial back aggressive language to match current model capability.`,

example: {

before: `CRITICAL: You MUST always use the Bash tool to run tests. NEVER skip this step.`,

after: `Use the Bash tool to run tests when you've made code changes that could affect behavior.`,

why: `Removes over-prompting that causes the model to run tests even for documentation-only changes.`,

},

},

add_self_check: {

prompt: `Add verification/self-check instructions at key decision points. Ask Claude to verify its work against specific criteria before finalizing. This catches errors reliably for coding and math tasks.`,

motivation: `"Before you finish, verify your answer against [criteria]" is one of the most reliable error-reduction techniques. It works because Claude can catch its own mistakes when explicitly prompted to review.`,

example: {

before: `Write tests for new features`,

after: `Write tests for new features. Before marking the task complete, verify:\n- All new code paths have test coverage\n- Tests actually assert behavior (not just that functions exist)\n- Edge cases from the requirements are covered`,

why: `Self-check criteria turn a vague instruction into a concrete checklist Claude can verify against.`,

},

},

reduce_overengineering: {

prompt: `Add anti-overengineering constraints. Claude Opus 4.5/4.6 tend to create extra files, add unnecessary abstractions, and build flexibility that wasn't requested. Add specific guidance to keep solutions minimal and focused.`,

motivation: `Without constraints, Claude overengineers: extra config files, unnecessary abstraction layers, defensive coding for impossible scenarios, helpers for one-time operations. The right amount of complexity is the minimum needed for the current task.`,

example: {

before: `(no overengineering guidance)`,

after: `<avoid_overengineering>\nOnly make changes directly requested or clearly necessary. Don't add features, refactor surrounding code, or create abstractions for one-time operations. Three similar lines of code is better than a premature abstraction. Don't add error handling for scenarios that can't happen.\n</avoid_overengineering>`,

why: `Explicit constraint with XML tag boundary — Claude treats this as a hard rule, not a suggestion.`,

},

},

add_guardrails: {

prompt: `Add guardrails for common agent failure modes: forgetting to run tests, wrong commit format, not reading prior context on retries, not handling empty fields. Add explicit "DO NOT" rules where agents commonly go wrong.`,

motivation: `Agentic workflows fail at predictable points. Explicit guardrails at these failure points prevent the most common errors without requiring the agent to learn from experience.`,

example: {

before: `Run tests before committing`,

after: `<guardrails>\nBefore committing:\n1. Run the full test suite — do not skip even if "only docs changed"\n2. If tests fail, fix the issue and re-run — do not commit with failing tests\n3. If a test is flaky, note it but do not delete or skip it\n</guardrails>`,

why: `Numbered guardrails with XML boundary — each failure mode has an explicit prevention rule.`,

},

},

improve_error_handling: {

prompt: `Improve how the prompt handles edge cases and errors: empty descriptions, missing labels, retry attempts, urgent priorities. Add conditional sections and fallback instructions for when data is incomplete.`,

motivation: `Agent prompts often assume happy-path inputs. Real-world usage includes empty fields, missing context, retries after failures, and incomplete data. Fallback instructions prevent the agent from stalling or hallucinating.`,

example: {

before: `Use the ticket description to understand the task`,

after: `Use the ticket description to understand the task. If the description is empty or unclear, check the ticket comments and linked PRs for context. If still unclear, ask the user for clarification rather than guessing.`,

why: `Fallback chain prevents the agent from hallucinating context when the primary source is empty.`,

},

},

};

/**

* Generate a mutation using AI, with optional self-review refinement.

*/

async function generateMutation(content, strategy, state) {

const strat = STRATEGIES[strategy];

if (!strat) {

console.warn(` Unknown strategy: ${strategy}, falling back to rephrase`);

return generateMutation(content, 'rephrase', state);

}

// Detect if optimizing a skill .md file

const isSkillTarget = targetName && targetName.startsWith('skill:');

const skillAuditCtx = isSkillTarget

? getSkillAuditContext(targetName.replace('skill:', ''))

: '';

const targetDescription = isSkillTarget

? 'a Claude Code slash command (skill) .md file that instructs an AI coding agent what to do when the user invokes the command'

: 'a CLAUDE.md system prompt for an AI coding agent (Claude Opus 4.6)';

const prompt = `You are an expert prompt engineer optimizing ${targetDescription}.

<current_prompt>

${content}

</current_prompt>

<strategy>

OPTIMIZATION STRATEGY: ${strategy}

${strat.prompt}

WHY THIS MATTERS:

${strat.motivation}

EXAMPLE OF A GOOD MUTATION:

<example>

Before: ${strat.example.before}

After: ${strat.example.after}

Why better: ${strat.example.why}

</example>

</strategy>

<context>

EVALUATION FEEDBACK FROM PREVIOUS GENERATIONS:

${getRecentFeedback(state)}

REFLECTION INSIGHTS (from failure pattern analysis):

${getReflectionInsights()}

${skillAuditCtx}

</context>

<requirements>

1. Output ONLY the improved markdown content — no commentary, no fences

2. Preserve all critical instructions and constraints

3. Keep the same overall structure unless using restructure strategy

4. Apply the strategy thoughtfully — targeted changes, not wholesale rewrites

5. Target <8000 tokens total length

6. Ensure every rule has clear, actionable language

</requirements>

OUTPUT THE IMPROVED CLAUDE.MD:`;

const draft = await callClaude(prompt);

// Self-review step: generate → review → refine

if (config.evolution.selfReview !== false) {

return await selfReview(draft.trim(), content, strategy, strat);

}

return draft.trim();

}

/**

* Self-review: have Claude review its own mutation against criteria, then refine.

* This catches errors before burning eval budget (per Anthropic best practices:

* "generate a draft → review against criteria → refine based on review").

*/

async function selfReview(draft, original, strategy, strat) {

const reviewPrompt = `You are reviewing a CLAUDE.md mutation before it goes to evaluation.

<original_prompt>

${original.slice(0, 3000)}

</original_prompt>

<mutated_prompt>

${draft.slice(0, 5000)}

</mutated_prompt>

<review_criteria>

Strategy applied: ${strategy} — ${strat.prompt}

Check the mutation against these criteria:

1. PRESERVATION: Are all critical instructions from the original still present?

2. COHERENCE: Do the changes make the prompt more internally consistent, not less?

3. SPECIFICITY: Are new/changed instructions actionable (not vague)?

4. TOKEN BUDGET: Is the result under ~8000 tokens? If over, what can be trimmed?

5. NO DRIFT: Does the mutation stay within the strategy's scope (not rewriting unrelated sections)?

6. NO CONFLICTS: Do new instructions contradict existing ones?

7. OVERENGINEERING: Did the mutation add unnecessary complexity to the prompt itself?

</review_criteria>

If the mutation passes all criteria, output it unchanged.

If it fails any criteria, output a refined version that fixes the issues.

Output ONLY the final prompt content — no commentary, no review notes, no fences.`;

const refined = await callClaude(reviewPrompt);

return refined.trim();

}

/**

* Get recent evaluation feedback for context (session scores + ASI judge feedback)

*/

function getRecentFeedback(state) {

const parts = [];

// Session scores

const scoresPath = path.join(RESULTS_DIR, 'scores.jsonl');

if (fs.existsSync(scoresPath)) {

const lines = fs

.readFileSync(scoresPath, 'utf8')

.trim()

.split('\n')

.slice(-20);

const scores = lines.map((l) => JSON.parse(l));

const summary = scores.reduce((acc, s) => {

if (!acc[s.variant]) acc[s.variant] = { total: 0, count: 0, errors: 0 };

acc[s.variant].total += s.metrics?.successfulToolCalls || 0;

acc[s.variant].count++;

acc[s.variant].errors += s.metrics?.errorCount || 0;

return acc;

}, {});

parts.push(

Object.entries(summary)

.map(

([v, s]) =>

`${v}: ${s.count} sessions, ${s.errors} errors, avg success: ${(s.total / s.count).toFixed(1)}`

)

.join('\n')

);

}

// ASI feedback from most recent generation's judge

const feedbackFiles = fs.existsSync(RESULTS_DIR)

? fs

.readdirSync(RESULTS_DIR)

.filter((f) => f.startsWith('feedback-') && f.endsWith('.json'))

.sort()

.reverse()

: [];

if (feedbackFiles.length > 0) {

try {

const feedback = JSON.parse(

fs.readFileSync(path.join(RESULTS_DIR, feedbackFiles[0]), 'utf8')

);

const feedbackLines = [];

for (const [criterion, entries] of Object.entries(feedback)) {

// Deduplicate feedback messages

const unique = [...new Set(entries.map((e) => e.feedback))].slice(0, 2);

for (const msg of unique) {

feedbackLines.push(`- ${criterion}: ${msg}`);

}

}

if (feedbackLines.length > 0) {

parts.push(

`\nJUDGE FEEDBACK (areas to improve):\n${feedbackLines.slice(0, 10).join('\n')}`

);

}

} catch {

// ignore malformed feedback files

}

}

return parts.length > 0 ? parts.join('\n') : 'No previous evaluations.';

}

/**

* Load most recent reflection insights for mutation context

*/

function getReflectionInsights() {

const reflectionFiles = fs.existsSync(RESULTS_DIR)

? fs

.readdirSync(RESULTS_DIR)

.filter((f) => f.startsWith('reflection-') && f.endsWith('.json'))

: [];

if (reflectionFiles.length === 0) return 'No reflection data yet.';

// Pick the most recent reflection file

reflectionFiles.sort().reverse();

const latest = JSON.parse(

fs.readFileSync(path.join(RESULTS_DIR, reflectionFiles[0]), 'utf8')

);

const insights = latest.insights;

if (!insights) return 'No reflection insights available.';

const parts = [];

if (insights.failureModes?.length) {

parts.push(`Failure modes: ${insights.failureModes.join('; ')}`);

}

if (insights.missingInstructions?.length) {

parts.push(

`Missing instructions: ${insights.missingInstructions.join('; ')}`

);

}

if (insights.unclearInstructions?.length) {

parts.push(

`Unclear instructions: ${insights.unclearInstructions.join('; ')}`

);

}

if (insights.priorityMutations?.length) {

parts.push(

`Priority changes:\n${insights.priorityMutations

.map((m) => ` - [${m.type}] ${m.section}: ${m.change}`)

.join('\n')}`

);

}

return parts.join('\n') || 'No actionable insights.';

}

/**

* Call Claude CLI via spawn (stdin pipe, no shell interpolation)

*/

function spawnClaude(prompt, { cwd, timeoutMs } = {}) {

return new Promise((resolve, reject) => {

const args = ['--print'];

const child = spawn('claude', args, {

cwd,

stdio: ['pipe', 'pipe', 'pipe'],

env: { ...process.env },

});

let stdout = '';

let stderr = '';

let killed = false;

const timer = timeoutMs

? setTimeout(() => {

killed = true;

child.kill('SIGTERM');

}, timeoutMs)

: null;

child.stdout.on('data', (d) => (stdout += d));

child.stderr.on('data', (d) => (stderr += d));

child.on('close', (code) => {

if (timer) clearTimeout(timer);

if (killed)

return reject(new Error(`claude timed out after ${timeoutMs}ms`));

if (code !== 0 && !stdout)

return reject(new Error(stderr || `claude exited ${code}`));

resolve(stdout);

});

child.on('error', (err) => {

if (timer) clearTimeout(timer);

reject(err);

});

child.stdin.write(prompt);

child.stdin.end();

});

}

/**

* Call Claude API for mutation generation

*/

async function callClaude(prompt) {

// Try using claude CLI first (stdin pipe, no shell injection)

try {

return await spawnClaude(prompt);

} catch (e) {

// Fallback to API

const apiKey = process.env.ANTHROPIC_API_KEY;

if (!apiKey) {

console.error('Error: ANTHROPIC_API_KEY not set and claude CLI failed');

process.exit(1);

}

const response = await fetch('https://api.anthropic.com/v1/messages', {

method: 'POST',

headers: {

'Content-Type': 'application/json',

'x-api-key': apiKey,

'anthropic-version': '2023-06-01',

},

body: JSON.stringify({

model: config.mutation?.model || 'claude-sonnet-4-6',