executant 1.19.0 → 1.20.0

package/README.md

@@ -119,7 +119,6 @@ steps:
 
 - **`llm_as_judge: true`** — after a step completes, Claude evaluates the output; retries with feedback on FAIL, up to 5×
 - **`self_healing: true`** — on script failure, Claude diagnoses and repairs the command, then re-runs it, up to 5×
-- **`self_improve: true`** — after the workflow finishes, Claude analyzes execution highlights and saves an improved YAML to `tasks/backlog/`
 
 ## Interjection
 
@@ -148,19 +147,22 @@ press i  →  ▷ don't delete that file, use git revert▌  esc to cancel
 | `logging-demo.yaml` | Log steps, self-healing, judge |
 | `git-status-summary.yaml` | Real-world git workflow |
 | `repeat-demo.yaml` | Running a step N times with `repeat` |
+| `file-demo.yaml` | File operations |
+| `from-step-test.yaml` | Using `--from-step` to resume mid-workflow |
 
 See the [`examples/`](examples/) directory.
 
 ## CLI
 
 ```bash
-executant plan "description"          # generate a workflow YAML (auto-detects fast path)
-executant plan -q "description"       # skip research pass (fast path)
-executant workflow.yaml               # run a workflow
-executant --ci workflow.yaml          # headless, NDJSON to stdout
-executant --step <name|n> wf.yaml     # run one step by name or index
-executant --from-step <n> wf.yaml     # resume from step n
-executant update                      # upgrade to latest version
+executant plan "description"                    # generate a workflow YAML (auto-detects fast path)
+executant plan -q "description"                 # skip research pass (fast path)
+executant refine workflow.yaml "instructions"   # refine an existing workflow YAML
+executant workflow.yaml                         # run a workflow
+executant --ci workflow.yaml                    # headless, NDJSON to stdout
+executant --step <name|n> wf.yaml              # run one step by name or index
+executant --from-step <n> wf.yaml              # resume from step n
+executant update                                # upgrade to latest version
 ```
 
 ## Development

package/dist/index.js

@@ -52,8 +52,8 @@ var init_update = __esm({
 // src/index.ts
 import React3 from "react";
 import { render } from "ink";
-import { readFileSync as readFileSync7 } from "node:fs";
-import { dirname as dirname5, join as join5 } from "node:path";
+import { readFileSync as readFileSync6 } from "node:fs";
+import { dirname as dirname4, join as join4 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/load-workflow.ts
@@ -160,8 +160,7 @@ var RawStepSchema = z.lazy(
 var RawWorkflowSchema = z.object({
   goal: z.string(),
   steps: z.array(RawStepSchema),
-  vars: z.record(z.string(), z.string()).optional(),
-  self_improve: z.boolean().optional()
+  vars: z.record(z.string(), z.string()).optional()
 });
 function loadWorkflow(filePath2) {
   let raw;
@@ -193,7 +192,6 @@ ${detail}`);
   return {
     goal: doc.goal,
     vars,
-    selfImprove: doc.self_improve,
     tasks: doc.steps.map((step) => convertStep(step, vars))
   };
 }
@@ -334,8 +332,8 @@ var AsyncQueue = class {
   }
   next() {
     if (this.buf.length > 0) return Promise.resolve(this.buf.shift());
-    return new Promise((resolve4) => {
-      this.waiter = resolve4;
+    return new Promise((resolve3) => {
+      this.waiter = resolve3;
     });
   }
   async *[Symbol.asyncIterator]() {
@@ -371,8 +369,8 @@ async function* mergeStreamsToLines(...streams) {
   yield* q;
 }
 function waitForExit(proc) {
-  return new Promise((resolve4, reject) => {
-    proc.on("close", (code) => resolve4(code ?? 0));
+  return new Promise((resolve3, reject) => {
+    proc.on("close", (code) => resolve3(code ?? 0));
     proc.on("error", reject);
   });
 }
@@ -1620,8 +1618,7 @@ var TOTAL_PLAN_STAGES = 3;
 var WorkflowSchema = z3.object({
   goal: z3.string(),
   steps: z3.array(RawStepSchema).min(1),
-  vars: z3.record(z3.string()).optional(),
-  self_improve: z3.boolean().optional()
+  vars: z3.record(z3.string()).optional()
 });
 var PlanJudgeOutputSchema = z3.object({
   pass: z3.boolean(),
@@ -2328,13 +2325,7 @@ function PlanApp({ description, events: events2 }) {
 }
 
 // src/logger.ts
-import {
-  appendFileSync,
-  existsSync as existsSync3,
-  mkdirSync as mkdirSync3,
-  readdirSync,
-  writeFileSync as writeFileSync3
-} from "node:fs";
+import { appendFileSync, existsSync as existsSync3, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname3, join as join3, resolve as resolve2 } from "node:path";
 function findExecutantLocalDir(startDir) {
   let dir = resolve2(startDir);
@@ -2355,22 +2346,13 @@ var INIT_STATE = {
   logFile: "",
   stepIndex: -1,
   stepName: "",
-  stepStartMs: 0,
-  toolCount: 0,
-  complexSequenceFile: "",
-  selfHealingFile: "",
-  judgeAttempt: 0,
-  recentOutput: []
+  stepStartMs: 0
 };
 function appendLog(logFile, text) {
   if (logFile) appendFileSync(logFile, text + "\n");
 }
-function highlightPath(ctx, stepIndex, suffix) {
-  return join3(ctx.highlightsDir, `${ctx.ts}_step${stepIndex + 1}_${suffix}.md`);
-}
 function onWorkflowStart(ctx, s) {
   mkdirSync3(ctx.logDir, { recursive: true });
-  mkdirSync3(ctx.highlightsDir, { recursive: true });
   const logFile = join3(ctx.logDir, `${ctx.ts}_${ctx.slug}.log`);
   writeFileSync3(
     logFile,
@@ -2402,20 +2384,6 @@ ${"\u2501".repeat(51)}
   );
   return next;
 }
-function finalizeComplexSequence(s) {
-  if (s.toolCount >= 3 && s.complexSequenceFile) {
-    appendFileSync(
-      s.complexSequenceFile,
-      `
----
-
-*Total tools used: ${s.toolCount}*
-
-*Captured by Executant Logger*
-`
-    );
-  }
-}
 function onStepComplete(s) {
   appendLog(
     s.logFile,
@@ -2423,131 +2391,21 @@ function onStepComplete(s) {
 Step completed in ${((Date.now() - s.stepStartMs) / 1e3).toFixed(1)}s
 `
   );
-  finalizeComplexSequence(s);
   return s;
 }
 function onStepError(s, error) {
   appendLog(s.logFile, `
 Step failed: ${error.message}
 `);
-  finalizeComplexSequence(s);
   return s;
 }
-function buildHighlightHeader(ctx, s, title, extra = []) {
-  return [
-    `# ${title}`,
-    "",
-    `**Task:** ${ctx.slug}`,
-    `**Step:** ${s.stepName}`,
-    ...extra,
-    `**Timestamp:** ${(/* @__PURE__ */ new Date()).toISOString()}`,
-    "",
-    "---",
-    ""
-  ].join("\n") + "\n";
-}
-function complexSequenceHeader(ctx, s) {
-  return buildHighlightHeader(ctx, s, "Complex Tool Sequence") + "## Claude's Tool Orchestration\n\nClaude used multiple tools to complete this step:\n\n";
-}
-function createComplexSequenceFile(ctx, s) {
-  const path = highlightPath(ctx, s.stepIndex, "complex_sequence");
-  writeFileSync3(path, complexSequenceHeader(ctx, s));
-  return path;
-}
-function onTool(ctx, s, tool, input) {
-  const desc = getToolArg(tool, input);
-  appendLog(s.logFile, `   [${tool}] ${desc}`);
-  const toolCount = s.toolCount + 1;
-  const complexSequenceFile = toolCount === 3 ? createComplexSequenceFile(ctx, s) : s.complexSequenceFile;
-  if (toolCount >= 3 && complexSequenceFile) {
-    appendFileSync(
-      complexSequenceFile,
-      `${toolCount}. **${tool}** - ${desc}
-`
-    );
-  }
-  return { ...s, toolCount, complexSequenceFile };
-}
-function saveJudgeHighlight(ctx, s, verdict, text) {
-  writeFileSync3(
-    highlightPath(ctx, s.stepIndex, `judge_${verdict}`),
-    buildHighlightHeader(ctx, s, `Judge Verdict: ${verdict}`, [
-      `**Attempt:** ${s.judgeAttempt}`
-    ]) + [text, "", "---", "", "*Auto-captured*", ""].join("\n")
-  );
+function onTool(s, tool, input) {
+  appendLog(s.logFile, `   [${tool}] ${getToolArg(tool, input)}`);
+  return s;
 }
-var LOG_MATCHERS = [
-  {
-    pattern: /\[judge\]\s+(PASS|FAIL)/i,
-    apply: (ctx, s, text, match) => {
-      const verdict = match[1].toUpperCase();
-      const judgeAttempt = s.judgeAttempt + 1;
-      saveJudgeHighlight(ctx, { ...s, judgeAttempt }, verdict, text);
-      return { ...s, judgeAttempt };
-    }
-  },
-  {
-    pattern: /\[self-healing\].*failed.*exit\s+(\d+)/i,
-    apply: (ctx, s, _text, match) => {
-      const selfHealingFile = highlightPath(ctx, s.stepIndex, "self_healing");
-      writeFileSync3(
-        selfHealingFile,
-        buildHighlightHeader(ctx, s, "Self-Healing Activation") + [
-          "## \u274C Failure Detected",
-          "",
-          `**Exit Code:** ${match[1]}`,
-          "",
-          "**Recent Output:**",
-          "```",
-          s.recentOutput.join("\n"),
-          "```",
-          "",
-          "---",
-          "",
-          "## \u{1F527} Claude's Healing Process",
-          ""
-        ].join("\n")
-      );
-      return { ...s, selfHealingFile, recentOutput: [] };
-    }
-  },
-  {
-    pattern: /\[self-healing\].*Re-running/i,
-    apply: (_ctx, s) => {
-      if (!s.selfHealingFile) return s;
-      appendFileSync(
-        s.selfHealingFile,
-        [
-          "",
-          "*(See full log for Claude's diagnostic process)*",
-          "",
-          "---",
-          "",
-          "## \u2705 Resolution Applied",
-          "",
-          "The self-healing process completed. Check the full execution log to see Claude's analysis and fix.",
-          "",
-          "---",
-          "",
-          "*Auto-captured*",
-          ""
-        ].join("\n")
-      );
-      return { ...s, selfHealingFile: "" };
-    }
-  }
-];
-function onLogMessage(ctx, s, level, text) {
+function onLogMessage(s, level, text) {
   appendLog(s.logFile, `[${level}] ${text}`);
-  let state = s;
-  for (const { pattern, apply } of LOG_MATCHERS) {
-    const m = pattern.exec(text);
-    if (m) {
-      state = apply(ctx, state, text, m);
-      break;
-    }
-  }
-  return state;
+  return s;
 }
 function onWorkflowComplete(ctx, s) {
   appendLog(
@@ -2559,37 +2417,8 @@ Finished: ${(/* @__PURE__ */ new Date()).toISOString()}
 ${"\u2501".repeat(51)}
 `
   );
-  const indexFile = join3(ctx.highlightsDir, "README.md");
-  if (!existsSync3(indexFile)) {
-    writeFileSync3(
-      indexFile,
-      [
-        "# Execution Highlights",
-        "",
-        "This directory contains automatically extracted highlight moments from task executions.",
-        "",
-        "## Latest Highlights",
-        ""
-      ].join("\n")
-    );
-  }
-  const highlights = readdirSync(ctx.highlightsDir).filter((f) => f.startsWith(ctx.ts) && f.endsWith(".md")).sort();
-  if (highlights.length > 0) {
-    const entries = highlights.map((f) => `- [${f.replace(/\.md$/, "")}](./${f})`).join("\n");
-    appendFileSync(
-      indexFile,
-      `
-### ${ctx.slug} (${(/* @__PURE__ */ new Date()).toISOString()})
-${entries}
-`
-    );
-  }
   return s;
 }
-function onOutputText(s, text) {
-  appendLog(s.logFile, text);
-  return { ...s, recentOutput: [...s.recentOutput, text] };
-}
 function reduce(ctx, s, event) {
   switch (event.type) {
     case "workflow:start":
@@ -2614,11 +2443,12 @@ function reduce(ctx, s, event) {
       );
       return s;
     case "output:text":
-      return onOutputText(s, event.text);
+      appendLog(s.logFile, event.text);
+      return s;
     case "output:tool":
-      return onTool(ctx, s, event.tool, event.input);
+      return onTool(s, event.tool, event.input);
     case "log":
-      return onLogMessage(ctx, s, event.level, event.text);
+      return onLogMessage(s, event.level, event.text);
     case "workflow:complete":
       return onWorkflowComplete(ctx, s);
     default:
@@ -2628,15 +2458,12 @@ function reduce(ctx, s, event) {
 function createLogger(logDir, taskName) {
   const ctx = {
     logDir,
-    highlightsDir: join3(logDir, "highlights"),
     ts: formatTimestamp(/* @__PURE__ */ new Date()),
     slug: slugify(taskName, 40) || "task"
   };
   const enabled = process.env["EXECUTANT_LOG"] !== "0";
   let state = INIT_STATE;
   return {
-    getHighlightsDir: () => ctx.highlightsDir,
-    getTimestamp: () => ctx.ts,
     observe(event) {
       if (!enabled) return;
       try {
@@ -2654,176 +2481,6 @@ async function* withLogger(gen, logger2) {
   }
 }
 
-// src/retrospective.ts
-import {
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync4,
-  readdirSync as readdirSync2,
-  readFileSync as readFileSync6,
-  writeFileSync as writeFileSync4
-} from "node:fs";
-import { basename as basename2, dirname as dirname4, join as join4, resolve as resolve3 } from "node:path";
-import { spawnSync } from "node:child_process";
-import { load as parseYaml2 } from "js-yaml";
-import { z as z4 } from "zod";
-var RetrospectiveOutputSchema = z4.object({
-  improved_yaml: z4.string(),
-  changelog: z4.string()
-});
-var RETROSPECTIVE_PROMPT = loadPrompt("retrospective-analysis");
-async function runRetrospective(workflowFilePath, workflow2, highlightsDir, runTimestamp) {
-  try {
-    await doRetrospective(
-      workflowFilePath,
-      workflow2,
-      highlightsDir,
-      runTimestamp
-    );
-  } catch (err) {
-    console.warn(
-      `
-Self-improvement: retrospective failed: ${getErrorMessage(err)}`
-    );
-  }
-}
-async function doRetrospective(workflowFilePath, workflow2, highlightsDir, runTimestamp) {
-  if (!existsSync4(highlightsDir)) {
-    console.log("\nSelf-improvement: no highlights directory found, skipping.");
-    return;
-  }
-  const allFiles = readdirSync2(highlightsDir);
-  const runHighlights = allFiles.filter((f) => f.startsWith(runTimestamp) && f.endsWith(".md")).sort();
-  if (runHighlights.length === 0) {
-    console.log(
-      "\nSelf-improvement: no highlights for this run \u2014 task completed without issues, skipping."
-    );
-    return;
-  }
-  const divider = "\u2501".repeat(51);
-  console.log(`
-${divider}`);
-  console.log(
-    "Self-Improvement: Analyzing execution and generating improvements..."
-  );
-  console.log(`${divider}
-`);
-  console.log(`Found ${runHighlights.length} highlight(s) to analyze`);
-  const countByPattern = (pat) => runHighlights.filter((f) => f.includes(pat)).length;
-  const judgeFailures = countByPattern("_judge_FAIL");
-  const selfHealingCount = countByPattern("_self_healing");
-  const complexSequences = countByPattern("_complex_sequence");
-  const metrics = [
-    `- Judge Failures: ${judgeFailures}`,
-    `- Self-Healing Activations: ${selfHealingCount}`,
-    `- Complex Tool Sequences: ${complexSequences}`,
-    `- Total Highlights: ${runHighlights.length}`
-  ].join("\n");
-  console.log(`
-Execution Metrics:
-${metrics}
-`);
-  console.log("Analyzing execution and generating improvements...\n");
-  const highlightContents = runHighlights.map((f) => {
-    const content = readFileSync6(join4(highlightsDir, f), "utf8");
-    return `### ${f}
-
-${content}`;
-  }).join("\n\n---\n\n");
-  const originalYaml = readFileSync6(workflowFilePath, "utf8");
-  const taskName = basename2(workflowFilePath, ".yaml");
-  const prompt = fillTemplate(RETROSPECTIVE_PROMPT, {
-    TASK_NAME: taskName,
-    ORIGINAL_GOAL: workflow2.goal,
-    ORIGINAL_YAML: originalYaml,
-    HIGHLIGHTS: highlightContents,
-    METRICS: metrics
-  });
-  const result = spawnSync(
-    "claude",
-    [
-      "-p",
-      prompt,
-      "--allowedTools",
-      "Read",
-      "--permission-mode",
-      "bypassPermissions",
-      "--output-format",
-      "text"
-    ],
-    {
-      encoding: "utf8",
-      maxBuffer: 10 * 1024 * 1024,
-      stdio: ["ignore", "pipe", "pipe"]
-    }
-  );
-  if (result.error) {
-    console.warn(
-      `Self-improvement: failed to run claude: ${result.error.message}`
-    );
-    return;
-  }
-  if (result.status !== 0) {
-    const stderr = result.stderr ?? "";
-    console.warn(
-      `Self-improvement: claude exited with code ${result.status}${stderr ? ": " + stderr : ""}`
-    );
-    return;
-  }
-  const response = result.stdout ?? "";
-  let parsed;
-  try {
-    parsed = JSON.parse(extractJson(response));
-  } catch {
-    console.warn(
-      `Self-improvement: could not parse Claude response as JSON.
-Response: ${response.trim()}`
-    );
-    return;
-  }
-  const zodResult = RetrospectiveOutputSchema.safeParse(parsed);
-  if (!zodResult.success) {
-    console.warn(
-      "Self-improvement: response schema mismatch \u2014 improved YAML not saved."
-    );
-    return;
-  }
-  const improvedYaml = zodResult.data.improved_yaml.trim();
-  const changelog = zodResult.data.changelog.trim() || "No changelog generated.";
-  try {
-    parseYaml2(improvedYaml);
-  } catch (err) {
-    console.warn(
-      `Self-improvement: generated YAML is invalid (${getErrorMessage(err)}), skipping save.`
-    );
-    return;
-  }
-  const startDir = dirname4(resolve3(workflowFilePath));
-  const executantLocal = findExecutantLocalDir(startDir);
-  const backlogDir = executantLocal ? join4(executantLocal, "tasks", "backlog") : join4(startDir, "..", "backlog");
-  mkdirSync4(backlogDir, { recursive: true });
-  const ts = formatTimestamp(/* @__PURE__ */ new Date());
-  const slug = slugify(taskName, 40);
-  const improvedFile = join4(backlogDir, `${ts}-${slug}-improved.yaml`);
-  const changelogFile = join4(backlogDir, `${ts}-${slug}-changelog.md`);
-  writeFileSync4(improvedFile, improvedYaml + "\n", "utf8");
-  writeFileSync4(changelogFile, changelog + "\n", "utf8");
-  console.log(`\u2705 Improved task saved: ${improvedFile}`);
-  console.log(`\u2705 Changelog saved: ${changelogFile}`);
-  console.log(`
-${divider}`);
-  console.log("Improvement Summary");
-  console.log(`${divider}
-`);
-  console.log(changelog);
-}
-function extractJson(text) {
-  const start = text.indexOf("{");
-  const end = text.lastIndexOf("}");
-  if (start === -1 || end === -1 || end <= start)
-    throw new Error("no JSON object found in response");
-  return text.slice(start, end + 1);
-}
-
 // src/types.ts
 var InterjectChannel = class {
   _queue = [];
@@ -2841,8 +2498,8 @@ var InterjectChannel = class {
 
 // src/index.ts
 var CURRENT_VERSION = JSON.parse(
-  readFileSync7(
-    join5(dirname5(fileURLToPath2(import.meta.url)), "../package.json"),
+  readFileSync6(
+    join4(dirname4(fileURLToPath2(import.meta.url)), "../package.json"),
     "utf-8"
   )
 ).version;
@@ -3020,36 +2677,17 @@ function errorReplacer(_key, value) {
   }
   return value;
 }
-async function maybeRunRetrospective(filePath2, workflow2, logger2) {
-  if (!logger2) return;
-  try {
-    await runRetrospective(
-      filePath2,
-      workflow2,
-      logger2.getHighlightsDir(),
-      logger2.getTimestamp()
-    );
-  } catch (err) {
-    console.warn(
-      "[executant] retrospective failed (non-fatal):",
-      getErrorMessage(err)
-    );
-  }
-}
 if (ciMode) {
   (async () => {
     for await (const event of events) {
       process.stdout.write(JSON.stringify(event, errorReplacer) + "\n");
     }
-    if (workflow.selfImprove) {
-      await maybeRunRetrospective(filePath, workflow, logger);
-    }
   })().catch((err) => {
     console.error(err);
     process.exit(1);
   });
 } else {
-  const inkApp = render(
+  render(
     React3.createElement(App, {
       workflow,
       events,
@@ -3058,8 +2696,4 @@ if (ciMode) {
       interjectChannel: channel
     })
   );
-  if (workflow.selfImprove) {
-    inkApp.waitUntilExit().then(() => maybeRunRetrospective(filePath, workflow, logger)).catch(() => {
-    });
-  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executant",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "Harness for YAML-defined workflows that enables stepping through Claude sessions and bash commands",
   "repository": {
     "type": "git",

package/dist/prompts/retrospective-analysis.txt

@@ -1,304 +0,0 @@
-# ============================================================================
-# RETROSPECTIVE ANALYSIS PROMPT
-# ============================================================================
-# Purpose: Analyzes task execution highlights and generates improved task YAML
-# Used by: src/retrospective.ts runRetrospective()
-# Triggered when: A task completes with self_improve: true and has highlights
-#
-# Placeholders:
-#   {{TASK_NAME}} - Name of the task that was executed
-#   {{ORIGINAL_GOAL}} - The original goal statement (must be preserved)
-#   {{ORIGINAL_YAML}} - Complete original task YAML for reference
-#   {{HIGHLIGHTS}} - Aggregated highlight markdown files from execution
-#   {{METRICS}} - Execution metrics summary (failures, retries, etc.)
-# ============================================================================
-
-You are analyzing the execution of an Executant task to identify improvement opportunities.
-
-# Task Information
-
-**Task Name:** {{TASK_NAME}}
-
-**Original Goal:** {{ORIGINAL_GOAL}}
-
-# Execution Metrics
-
-{{METRICS}}
-
-# Execution Highlights
-
-The following highlights were captured during execution. Each highlight represents a moment where the system encountered challenges:
-
-{{HIGHLIGHTS}}
-
-# Original Task YAML
-
-```yaml
-{{ORIGINAL_YAML}}
-```
-
-# Your Task
-
-Analyze the execution highlights and generate an improved version of the task YAML that addresses the problems encountered during execution.
-
-## Analysis Guidelines
-
-### Interpreting Judge Failures (llm_as_judge: true)
-
-Judge failures indicate that Claude's output didn't meet quality standards. Common causes:
-
-**Unclear prompts** - The step instructions were too vague
-- Fix: Add specific numbered sub-steps
-- Fix: Define clear success criteria
-- Fix: Specify what to check and how to verify it
-
-**Missing criteria** - The prompt didn't explain what "good" looks like
-- Fix: Add examples of expected output
-- Fix: Specify quality thresholds (test coverage %, file count, etc.)
-- Fix: Include validation steps
-
-**Steps too large** - One step tried to do too much
-- Fix: Break into smaller, focused steps
-- Fix: Each step should have one clear objective
-
-**Example Fix:**
-```
-BEFORE:
-  - name: "validate results"
-    llm_as_judge: true
-    prompt: "Validate the conversion results"
-
-AFTER:
-  - name: "validate results"
-    llm_as_judge: true
-    prompt: |
-      Validate the TypeScript conversion by checking:
-      1. Read the generated .ts file
-      2. Verify all functions have type annotations
-      3. Check that tests pass (npm test)
-      4. Confirm no compilation errors (tsc --noEmit)
-
-      Success criteria: All 4 checks pass without errors.
-```
-
-### Interpreting Self-Healing Events (self_healing: true)
-
-Self-healing activations indicate brittle script steps that failed during execution. Common causes:
-
-**Missing dependencies** - Command not found, package not installed
-- Fix: Add a script step to install/check dependencies first
-- Fix: Use explicit paths instead of assuming commands are in PATH
-
-**Wrong assumptions** - Script assumed files/directories exist
-- Fix: Add checks or create directories in the script
-- Fix: Use `mkdir -p` instead of `mkdir`
-- Fix: Check file existence before operating on it
-
-**Environment issues** - PWD, env vars, or paths incorrect
-- Fix: Use absolute paths instead of relative
-- Fix: cd to correct directory in the script
-- Fix: Set required environment variables
-
-**Race conditions** - Script ran before previous step completed
-- Fix: Add wait/check logic
-- Fix: Combine dependent commands with && in one script step
-
-**Example Fix:**
-```
-BEFORE:
-  - name: "run tests"
-    type: script
-    self_healing: true
-    command: npm test
-
-AFTER:
-  - name: "install dependencies"
-    type: script
-    command: npm install
-
-  - name: "run tests"
-    type: script
-    self_healing: true
-    command: npm test
-```
-
-### Interpreting Complex Tool Sequences
-
-Complex tool sequences (3+ tools) indicate that Claude had to work hard to complete a step. Common causes:
-
-**Vague instructions** - Step didn't specify what files to operate on
-- Fix: List specific file paths to read/edit
-- Fix: Specify glob patterns for file discovery
-- Fix: Break discovery and operation into separate steps
-
-**Exploratory work needed** - Claude had to search to understand the codebase
-- Fix: Add a separate discovery/analysis step first
-- Fix: Provide file paths in the prompt
-- Fix: Include relevant code snippets in the prompt
-
-**Multi-phase operations** - One step tried to do research + implementation
-- Fix: Split into "research" step and "implementation" step
-- Fix: First step outputs findings, second step acts on them
-
-**Example Fix:**
-```
-BEFORE:
-  - name: "update imports"
-    prompt: "Update all imports to use the new module structure"
-
-AFTER:
-  - name: "analyze imports"
-    prompt: |
-      Search the codebase for all import statements:
-      1. Use grep to find all imports in src/
-      2. List files that import from old modules
-      3. Create a plan for updating each file
-
-  - name: "update imports"
-    prompt: |
-      Update imports in the following files based on the analysis:
-      - src/components/Button.tsx
-      - src/utils/helpers.ts
-      - src/services/api.ts
-
-      Change: import from './old/' to import from '@/new/'
-```
-
-## Improvement Principles
-
-1. **Preserve the original goal** - The task succeeded, so the goal is correct
-2. **Fix problems shown in highlights** - Only address issues that actually occurred
-3. **Be specific** - Add numbered steps, file paths, and clear criteria
-4. **Break down large steps** - If a step caused many retries or complex tool sequences
-5. **Add prerequisite steps** - If self-healing had to install deps or create files
-6. **Keep self_improve: true** - Allow recursive improvement in future runs
-7. **Document changes** - Explain what you changed and why in the changelog
-
-## Improvement Patterns
-
-### Pattern: Split Vague Prompt into Specific Sub-Steps
-
-When a judge fails or complex tools are needed, make the prompt more specific:
-
-```yaml
-# BEFORE: Vague, requires exploration
-- name: "refactor authentication"
-  llm_as_judge: true
-  prompt: "Refactor the authentication code"
-
-# AFTER: Specific numbered steps
-- name: "refactor authentication"
-  llm_as_judge: true
-  prompt: |
-    Refactor authentication by:
-    1. Reading src/auth/login.ts and src/auth/session.ts
-    2. Extracting common logic into src/auth/helpers.ts
-    3. Updating imports in both files
-    4. Running tests to verify: npm test src/auth/
-
-    Success: Tests pass, no code duplication between login.ts and session.ts
-```
-
-### Pattern: Add Prerequisite Step
-
-When self-healing installs deps or fixes environment:
-
-```yaml
-# BEFORE: Brittle, assumes deps installed
-steps:
-  - name: "build"
-    type: script
-    self_healing: true
-    command: npm run build
-
-# AFTER: Explicit dependency step
-steps:
-  - name: "install dependencies"
-    type: script
-    command: npm install
-
-  - name: "build"
-    type: script
-    command: npm run build
-```
-
-### Pattern: Split Research from Implementation
-
-When complex tool sequences suggest exploratory work:
-
-```yaml
-# BEFORE: Combined research + work
-- name: "fix bugs"
-  prompt: "Find and fix all bugs in the payment flow"
-
-# AFTER: Separated discovery and fixing
-- name: "identify payment bugs"
-  prompt: |
-    Analyze the payment flow for bugs:
-    1. Read src/payment/*.ts files
-    2. Check for error handling gaps
-    3. List files that need fixes
-
-- name: "fix payment bugs"
-  llm_as_judge: true
-  prompt: |
-    Fix bugs identified in previous step:
-    - Add error handling in src/payment/checkout.ts
-    - Validate input in src/payment/process.ts
-    - Update tests in src/payment/__tests__/
-
-    Success: All payment tests pass
-```
-
-### Pattern: Add Explicit Success Criteria
-
-When judge fails due to unclear expectations:
-
-```yaml
-# BEFORE: No clear success criteria
-- name: "improve test coverage"
-  llm_as_judge: true
-  prompt: "Improve test coverage for the API module"
-
-# AFTER: Explicit threshold and verification
-- name: "improve test coverage"
-  llm_as_judge: true
-  prompt: |
-    Improve test coverage for src/api/ to at least 80%:
-    1. Run: npm test -- --coverage src/api/
-    2. Identify files with <80% coverage
-    3. Write tests for uncovered code paths
-    4. Re-run coverage and verify ≥80%
-
-    Success criteria: Coverage report shows ≥80% for all files in src/api/
-```
-
-# Output Format
-
-Respond with a single JSON object:
-{
-  "improved_yaml": "<complete improved task YAML — no markdown fences, raw YAML only>",
-  "changelog": "<markdown: Problems Identified / Changes Applied / Expected Impact>"
-}
-
-Output only the JSON object — no prose before or after.
-
-# Important Requirements
-
-1. **Always preserve the original goal** - Do not change the goal statement
-2. **Keep self_improve: true** - This enables recursive improvement
-3. **Only fix problems shown in highlights** - Don't add unnecessary changes
-4. **Be specific in improvements** - Vague fixes won't help
-5. **Generate valid YAML** - The improved task must be parseable
-6. **Explain all changes** - The changelog should justify each modification
-
-# Example Response
-
-```json
-{
-  "improved_yaml": "goal: \"Convert CoffeeScript to TypeScript with validation\"\nself_improve: true\n\nsteps:\n  - name: \"install dependencies\"\n    type: script\n    command: npm install\n\n  - name: \"convert to TypeScript\"\n    type: script\n    command: coffee2ts convert app.coffee\n\n  - name: \"validate conversion\"\n    llm_as_judge: true\n    prompt: |\n      Validate the TypeScript conversion by:\n      1. Reading app.ts and checking all functions have type annotations\n      2. Running: tsc --noEmit to check for type errors\n      3. Running: npm test to verify functionality\n\n      Success criteria: No type errors, all tests pass",
-  "changelog": "## Problems Identified\n- Judge failure in \"validate conversion\": Instructions were too vague\n- Self-healing activation: npm dependencies were missing\n\n## Changes Applied\n\n### Step 1: install dependencies (NEW)\n- Before: Not present\n- After: Added explicit npm install step\n- Rationale: Self-healing had to install deps, do it upfront\n\n### Step 3: validate conversion (MODIFIED)\n- Before: \"Validate the results\"\n- After: Specific 3-step validation with success criteria\n- Rationale: Judge failed because unclear what to validate and how\n\n## Expected Impact\n- Judge retries: 1 → 0 (clearer validation steps)\n- Self-healing activations: 1 → 0 (deps installed first)"
-}
-```
-
-Now analyze the highlights and generate the improved task YAML with detailed changelog.