executant 1.7.0 → 1.8.0

package/README.md

@@ -87,6 +87,24 @@ steps:
     command: npx eslint src/{{item}}
 ```
 
+Use `steps:` inside a `forEach` or `repeat` to run **multiple child steps per iteration**:
+
+```yaml
+steps:
+  - name: verify each package
+    forEach: [packages/api, packages/web, packages/shared]
+    steps:
+      - name: lint {{item}}
+        type: script
+        command: npm run lint --workspace={{item}}
+      - name: test {{item}}
+        type: script
+        command: npm test --workspace={{item}}
+      - name: build {{item}}
+        type: script
+        command: npm run build --workspace={{item}}
+```
+
 Use `repeat: N` as shorthand when there is no meaningful list — just a count. `{{item}}` is the 1-based iteration number:
 
 ```yaml
@@ -110,6 +128,7 @@ steps:
 | `hello-world.yaml` | Simple prompt steps |
 | `mixed-workflow.yaml` | Script + prompt steps together |
 | `foreach-demo.yaml` | Inline lists and shell command iteration |
+| `nested-steps-demo.yaml` | Multiple child steps per forEach / repeat iteration |
 | `vars-demo.yaml` | Variable substitution |
 | `judge-demo.yaml` | LLM-as-judge retry loop |
 | `logging-demo.yaml` | Log steps, self-healing, judge |

package/dist/index.js

@@ -113,22 +113,25 @@ function timestamp() {
 
 // src/load-workflow.ts
 import { z } from "zod";
-var RawStepSchema = z.object({
-  name: z.string(),
-  type: z.enum(["prompt", "script", "log", "command"]).optional(),
-  prompt: z.string().optional(),
-  command: z.string().optional(),
-  message: z.string().optional(),
-  continue_on_error: z.boolean().optional(),
-  self_healing: z.boolean().optional(),
-  max_healing_attempts: z.number().int().positive().optional(),
-  output: z.string().optional(),
-  llm_as_judge: z.boolean().optional(),
-  allowed_tools: z.array(z.string()).optional(),
-  forEach: z.union([z.array(z.string()), z.string()]).optional(),
-  repeat: z.number().int().positive().optional(),
-  context: z.array(z.string()).optional()
-});
+var RawStepSchema = z.lazy(
+  () => z.object({
+    name: z.string(),
+    type: z.enum(["prompt", "script", "log", "command"]).optional(),
+    prompt: z.string().optional(),
+    command: z.string().optional(),
+    message: z.string().optional(),
+    continue_on_error: z.boolean().optional(),
+    self_healing: z.boolean().optional(),
+    max_healing_attempts: z.number().int().positive().optional(),
+    output: z.string().optional(),
+    llm_as_judge: z.boolean().optional(),
+    allowed_tools: z.array(z.string()).optional(),
+    forEach: z.union([z.array(z.string()), z.string()]).optional(),
+    repeat: z.number().int().positive().optional(),
+    context: z.array(z.string()).optional(),
+    steps: z.array(RawStepSchema).min(1).optional()
+  })
+);
 var RawWorkflowSchema = z.object({
   goal: z.string(),
   steps: z.array(RawStepSchema),
@@ -140,7 +143,9 @@ function loadWorkflow(filePath2) {
   try {
     raw = readFileSync2(filePath2, "utf8");
   } catch (err) {
-    throw new Error(`Cannot read workflow file "${filePath2}": ${getErrorMessage(err)}`);
+    throw new Error(
+      `Cannot read workflow file "${filePath2}": ${getErrorMessage(err)}`
+    );
   }
   let doc;
   try {
@@ -164,16 +169,30 @@ function convertStep(step, vars) {
     throw new Error(`Step "${name}" cannot have both repeat and forEach`);
   }
   if (step.repeat !== void 0 || step.forEach !== void 0) {
+    if (step.steps && (step.command || step.prompt || step.message)) {
+      throw new Error(
+        `Step "${name}" cannot have both steps and command/prompt/message`
+      );
+    }
     const forEachValue = step.repeat !== void 0 ? Array.from({ length: step.repeat }, (_, i) => String(i + 1)) : step.forEach;
-    const { repeat: _r, forEach: _f, ...innerStep } = step;
+    const stepWithoutLoop = {
+      ...step,
+      repeat: void 0,
+      forEach: void 0,
+      steps: void 0
+    };
+    const inner = step.steps ? step.steps.map((s) => convertStep(s, vars)) : [convertInnerStep(stepWithoutLoop, vars, name, continueOnError)];
     return {
       type: "forEach",
       name,
       continueOnError,
       forEach: forEachValue,
-      inner: convertInnerStep(innerStep, vars, name, continueOnError)
+      inner
     };
   }
+  if (step.steps) {
+    throw new Error(`Step "${name}" has steps but no forEach or repeat`);
+  }
   return convertInnerStep(step, vars, name, continueOnError);
 }
 function convertInnerStep(step, vars, name, continueOnError) {
@@ -181,7 +200,8 @@ function convertInnerStep(step, vars, name, continueOnError) {
   switch (effectiveType) {
     case "script":
     case "command": {
-      if (!step.command) throw new Error(`Step "${name}" has type script but no command`);
+      if (!step.command)
+        throw new Error(`Step "${name}" has type script but no command`);
       return {
         type: "command",
         name,
@@ -189,7 +209,9 @@ function convertInnerStep(step, vars, name, continueOnError) {
         continueOnError,
         selfHealing: step.self_healing === true,
         maxHealingAttempts: step.max_healing_attempts,
-        ...step.output && { output: resolveOutputFile(step.output, vars, name) }
+        ...step.output && {
+          output: resolveOutputFile(step.output, vars, name)
+        }
       };
     }
     case "log": {
@@ -202,7 +224,8 @@ function convertInnerStep(step, vars, name, continueOnError) {
       };
     }
     case "prompt": {
-      if (!step.prompt) throw new Error(`Step "${name}" has type prompt but no prompt field`);
+      if (!step.prompt)
+        throw new Error(`Step "${name}" has type prompt but no prompt field`);
       const contextFiles = resolveContextFiles(step.context, vars, name);
       return {
         type: "claude",
@@ -225,13 +248,17 @@ function inferType(step) {
 }
 function resolveVarPath(varName, vars, stepName, label) {
   if (!(varName in vars)) {
-    throw new Error(`Step "${stepName}" ${label} references undefined var "${varName}" \u2014 add it to the vars section`);
+    throw new Error(
+      `Step "${stepName}" ${label} references undefined var "${varName}" \u2014 add it to the vars section`
+    );
   }
   return vars[varName];
 }
 function resolveContextFiles(contextVarNames, vars, stepName) {
   if (!contextVarNames || contextVarNames.length === 0) return [];
-  return contextVarNames.map((varName) => resolveVarPath(varName, vars, stepName, "context"));
+  return contextVarNames.map(
+    (varName) => resolveVarPath(varName, vars, stepName, "context")
+  );
 }
 function resolveOutputFile(varName, vars, stepName) {
   return resolveVarPath(varName, vars, stepName, "output");
@@ -507,7 +534,7 @@ async function* runWorkflow(workflow2, options2 = {}) {
     yield { type: "step:start", index: i, name: task.name };
     try {
       for await (const event of runStep(task)) {
-        if (event.type === "step:iteration" || event.type === "output:text" || event.type === "output:tool") {
+        if (event.type === "step:iteration" || event.type === "step:inner" || event.type === "output:text" || event.type === "output:tool") {
           yield { ...event, index: i };
         } else {
           yield event;
@@ -568,20 +595,55 @@ async function* runLog(task) {
 async function* runForEach(task) {
   const items = await resolveItems(task.forEach);
   const total = items.length;
+  const innerTotal = task.inner.length;
   for (const [i, item] of items.entries()) {
     yield { type: "step:iteration", index: -1, item, iteration: i + 1, total };
-    const substituted = substituteItem(task.inner, item);
-    yield* runStep(substituted);
+    for (const [j, innerTask] of task.inner.entries()) {
+      const substituted = substituteItem(innerTask, item);
+      if (innerTotal > 1) {
+        yield {
+          type: "step:inner",
+          index: -1,
+          iteration: i + 1,
+          innerIndex: j,
+          innerTotal,
+          name: substituted.name
+        };
+      }
+      try {
+        yield* runStep(substituted);
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (!substituted.continueOnError) {
+          yield {
+            type: "log",
+            level: "warn",
+            text: `[forEach] Step "${substituted.name}" failed \u2014 aborting remaining children and iterations`
+          };
+          throw error;
+        }
+        yield {
+          type: "log",
+          level: "warn",
+          text: `[forEach] Step "${substituted.name}" failed (continuing): ${error.message}`
+        };
+      }
+    }
   }
 }
 async function resolveItems(forEach) {
   if (Array.isArray(forEach)) return forEach.filter(Boolean);
   try {
-    const { stdout } = await execPromise(forEach, { shell: "/bin/sh", timeout: 3e4 });
+    const { stdout } = await execPromise(forEach, {
+      shell: "/bin/sh",
+      timeout: 3e4
+    });
     return stdout.split("\n").filter((l) => l.trim().length > 0);
   } catch (err) {
-    throw new Error(`forEach shell command failed: ${getErrorMessage(err)}
-Command: ${forEach}`);
+    throw new Error(
+      `forEach shell command failed: ${getErrorMessage(err)}
+Command: ${forEach}`
+    );
   }
 }
 function substituteItem(task, item) {
@@ -590,12 +652,24 @@ function substituteItem(task, item) {
     case "command":
       return { ...task, name: sub(task.name), command: sub(task.command) };
     case "claude":
-      return { ...task, name: sub(task.name), prompt: sub(task.prompt), allowedTools: task.allowedTools?.map(sub) };
+      return {
+        ...task,
+        name: sub(task.name),
+        prompt: sub(task.prompt),
+        allowedTools: task.allowedTools?.map(sub)
+      };
     case "log":
       return { ...task, name: sub(task.name), message: sub(task.message) };
+    case "forEach":
+      return {
+        ...task,
+        name: sub(task.name),
+        forEach: Array.isArray(task.forEach) ? task.forEach : sub(task.forEach),
+        inner: task.inner.map((t) => substituteItem(t, item))
+      };
     default: {
       const _ = task;
-      throw new Error(`Unknown inner task type: ${JSON.stringify(_)}`);
+      throw new Error(`Unknown task type: ${JSON.stringify(_)}`);
     }
   }
 }
@@ -607,7 +681,11 @@ async function* runCommandWithHealing(task) {
     try {
       yield* collectLines(runCommand(task), lines);
       if (attempt > 0) {
-        yield { type: "log", level: "info", text: `[self-healing] Command passed after ${attempt + 1} attempts` };
+        yield {
+          type: "log",
+          level: "info",
+          text: `[self-healing] Command passed after ${attempt + 1} attempts`
+        };
       }
       return;
     } catch (err) {
@@ -615,7 +693,11 @@ async function* runCommandWithHealing(task) {
       const output = lines.join("\n");
       const remaining = maxAttempts - attempt - 1;
       if (remaining === 0) {
-        yield { type: "log", level: "warn", text: `[self-healing] Exhausted ${maxAttempts} attempts` };
+        yield {
+          type: "log",
+          level: "warn",
+          text: `[self-healing] Exhausted ${maxAttempts} attempts`
+        };
         throw new Error(
           `Step "${task.name}" failed after ${maxAttempts} self-healing attempts (last exit code: ${exitCode})`
         );
@@ -626,7 +708,12 @@ async function* runCommandWithHealing(task) {
         text: `[self-healing] Attempt ${attempt + 1}/${maxAttempts} failed (exit ${exitCode}), invoking Claude to fix\u2026`
       };
       const historyBlock = buildAttemptHistory(attemptHistory);
-      const healPrompt = buildHealingPrompt(task.command, exitCode, output, historyBlock);
+      const healPrompt = buildHealingPrompt(
+        task.command,
+        exitCode,
+        output,
+        historyBlock
+      );
       const healTask = {
         type: "claude",
         name: `${task.name}:heal-${attempt + 1}`,
@@ -637,7 +724,8 @@ async function* runCommandWithHealing(task) {
       const claudeLines = [];
       for await (const event of runClaude(healTask)) {
         if (event.type === "output:text") claudeLines.push(event.text);
-        else if (event.type === "output:tool") toolCalls.push(formatToolCall(event.tool, event.input));
+        else if (event.type === "output:tool")
+          toolCalls.push(formatToolCall(event.tool, event.input));
         yield event;
       }
       attemptHistory.push({
@@ -645,7 +733,11 @@ async function* runCommandWithHealing(task) {
         exitCode,
         cmdOutput: output
       });
-      yield { type: "log", level: "info", text: `[self-healing] Re-running command (${remaining} attempt(s) left)\u2026` };
+      yield {
+        type: "log",
+        level: "info",
+        text: `[self-healing] Re-running command (${remaining} attempt(s) left)\u2026`
+      };
     }
   }
 }
@@ -657,21 +749,37 @@ async function* runClaudeWithJudge(task) {
 ${fillTemplate(JUDGE_RETRY_CONTEXT, { FEEDBACK: judgeContext })}`;
     const lines = [];
     yield* collectLines(runClaude({ ...task, prompt }), lines);
-    yield { type: "log", level: "info", text: `[judge] Evaluating "${task.name}"\u2026` };
-    const verdict = await evaluateWithJudge(task.name, task.prompt, lines.join("\n"));
+    yield {
+      type: "log",
+      level: "info",
+      text: `[judge] Evaluating "${task.name}"\u2026`
+    };
+    const verdict = await evaluateWithJudge(
+      task.name,
+      task.prompt,
+      lines.join("\n")
+    );
     if (verdict.pass) {
       yield { type: "log", level: "info", text: "[judge] PASS" };
       return;
     }
     judgeContext = verdict.feedback;
-    yield { type: "log", level: "warn", text: `[judge] FAIL \u2014 ${verdict.feedback}` };
+    yield {
+      type: "log",
+      level: "warn",
+      text: `[judge] FAIL \u2014 ${verdict.feedback}`
+    };
     const remaining = MAX_JUDGE_RETRIES - attempt - 1;
     if (remaining === 0) {
       throw new Error(
         `Step "${task.name}" failed judge evaluation after ${MAX_JUDGE_RETRIES} attempts`
       );
     }
-    yield { type: "log", level: "info", text: `[judge] Retrying (${remaining} attempt(s) left)\u2026` };
+    yield {
+      type: "log",
+      level: "info",
+      text: `[judge] Retrying (${remaining} attempt(s) left)\u2026`
+    };
   }
 }
 async function evaluateWithJudge(stepName, stepInstructions, output) {
@@ -698,7 +806,9 @@ function readContextFile(filePath2) {
   try {
     return readFileSync3(filePath2, "utf8");
   } catch (err) {
-    throw new Error(`Context file "${filePath2}" could not be read: ${getErrorMessage(err)}`);
+    throw new Error(
+      `Context file "${filePath2}" could not be read: ${getErrorMessage(err)}`
+    );
   }
 }
 function expandContext(task) {
@@ -712,13 +822,23 @@ ${readContextFile(fp)}
 ${task.prompt}` };
 }
 function buildHealingPrompt(command, exitCode, output, attemptHistory) {
-  return fillTemplate(SELF_HEALING_PROMPT, { COMMAND: command, EXIT_CODE: String(exitCode), OUTPUT: output, ATTEMPT_HISTORY: attemptHistory });
+  return fillTemplate(SELF_HEALING_PROMPT, {
+    COMMAND: command,
+    EXIT_CODE: String(exitCode),
+    OUTPUT: output,
+    ATTEMPT_HISTORY: attemptHistory
+  });
 }
 function buildJudgePrompt(stepName, instructions, output) {
-  return fillTemplate(JUDGE_EVALUATION_PROMPT, { STEP_NAME: stepName, STEP_INSTRUCTIONS: instructions, OUTPUT: output });
+  return fillTemplate(JUDGE_EVALUATION_PROMPT, {
+    STEP_NAME: stepName,
+    STEP_INSTRUCTIONS: instructions,
+    OUTPUT: output
+  });
 }
 function formatToolCall(tool, input) {
-  if (tool === "Edit" || tool === "Write") return `${tool}(${String(input["file_path"] ?? "")})`;
+  if (tool === "Edit" || tool === "Write")
+    return `${tool}(${String(input["file_path"] ?? "")})`;
   if (tool === "Bash") return `Bash(${String(input["command"] ?? "")})`;
   return tool;
 }
@@ -835,7 +955,20 @@ function reducer(state, event) {
       };
     case "step:iteration":
       return updateTask(state, event.index, {
-        iteration: { current: event.iteration, total: event.total, item: event.item }
+        iteration: {
+          current: event.iteration,
+          total: event.total,
+          item: event.item
+        },
+        inner: void 0
+      });
+    case "step:inner":
+      return updateTask(state, event.index, {
+        inner: {
+          index: event.innerIndex,
+          total: event.innerTotal,
+          name: event.name
+        }
       });
     case "output:text": {
       const idx = event.index;
@@ -848,7 +981,10 @@ function reducer(state, event) {
       const formatted = formatToolCall2(event.tool, event.input);
       const next = formatted ? appendLine(state, idx, formatted) : state;
       if (event.tool === "Write" && typeof event.input["file_path"] === "string") {
-        return { ...next, writtenFiles: [...next.writtenFiles, event.input["file_path"]] };
+        return {
+          ...next,
+          writtenFiles: [...next.writtenFiles, event.input["file_path"]]
+        };
       }
       return next;
     }
@@ -871,7 +1007,9 @@ function reducer(state, event) {
   }
 }
 function updateTask(state, index, patch) {
-  const tasks = state.tasks.map((t, i) => i === index ? { ...t, ...patch } : t);
+  const tasks = state.tasks.map(
+    (t, i) => i === index ? { ...t, ...patch } : t
+  );
   return { ...state, tasks };
 }
 function appendLine(state, index, line) {
@@ -936,7 +1074,8 @@ function TaskRow({ taskState, isActive, index, tick }) {
   const color = statusColor(status, isActive);
   const elapsed = formatTaskElapsed(startTime, endTime, status);
   const iterInfo = taskState.iteration ? ` (${taskState.iteration.current}/${taskState.iteration.total}) ${taskState.iteration.item}` : "";
-  const label = `${index + 1}. ${task.name}${iterInfo}`;
+  const innerInfo = taskState.inner ? ` \u2014 ${taskState.inner.name} [${taskState.inner.index + 1}/${taskState.inner.total}]` : "";
+  const label = `${index + 1}. ${task.name}${iterInfo}${innerInfo}`;
   return /* @__PURE__ */ jsxs(Box, { children: [
     /* @__PURE__ */ jsxs(Text, { color, children: [
       icon,
@@ -1146,25 +1285,9 @@ var PLAN_RETRY_SCHEMA_ERROR = loadPrompt("plan-retry-schema-error");
 var PLAN_RETRY_JUDGE = loadPrompt("plan-retry-judge");
 var MAX_PLAN_RETRIES = 3;
 var TOTAL_PLAN_STAGES = 3;
-var StepSchema = z3.object({
-  name: z3.string(),
-  type: z3.enum(["prompt", "script", "log"]).optional(),
-  prompt: z3.string().optional(),
-  command: z3.string().optional(),
-  message: z3.string().optional(),
-  continue_on_error: z3.boolean().optional(),
-  self_healing: z3.boolean().optional(),
-  max_healing_attempts: z3.number().int().positive().optional(),
-  output: z3.string().optional(),
-  llm_as_judge: z3.boolean().optional(),
-  allowed_tools: z3.array(z3.string()).optional(),
-  forEach: z3.union([z3.array(z3.string()), z3.string()]).optional(),
-  repeat: z3.number().int().positive().optional(),
-  context: z3.array(z3.string()).optional()
-});
 var WorkflowSchema = z3.object({
   goal: z3.string(),
-  steps: z3.array(StepSchema).min(1),
+  steps: z3.array(RawStepSchema).min(1),
   vars: z3.record(z3.string()).optional(),
   self_improve: z3.boolean().optional()
 });
@@ -1184,7 +1307,10 @@ function walkUp(startDir, check) {
   }
 }
 function findGitRoot(startDir) {
-  return walkUp(startDir, (dir) => existsSync(join2(dir, ".git")) ? dir : null);
+  return walkUp(
+    startDir,
+    (dir) => existsSync(join2(dir, ".git")) ? dir : null
+  );
 }
 function findProjectRoot(startDir) {
   return walkUp(startDir, (dir) => {
@@ -1335,34 +1461,27 @@ function normalizeWorkflow(workflow2) {
   return { ...workflow2, steps: collapseSequentialSteps(steps) };
 }
 function collapseSequentialSteps(steps) {
-  const result = [];
-  let i = 0;
-  while (i < steps.length) {
-    const step = steps[i];
-    if (step.forEach !== void 0 || step.repeat !== void 0) {
-      result.push(step);
-      i++;
-      continue;
-    }
-    const m = step.name.match(/^(.+?)_1$/);
-    if (!m) {
-      result.push(step);
-      i++;
-      continue;
-    }
-    const prefix = m[1];
-    let n = 1;
-    while (i + n < steps.length && steps[i + n].name === `${prefix}_${n + 1}`) n++;
-    if (n < 2) {
-      result.push(step);
-      i++;
-      continue;
-    }
-    const { name: _name, ...rest } = step;
-    result.push({ ...rest, name: `${prefix}_{{item}}`, repeat: n });
-    i += n;
-  }
-  return result;
+  return steps.reduce(
+    ({ out, skip }, step, i, arr) => {
+      if (skip > 0) return { out, skip: skip - 1 };
+      if (step.forEach !== void 0 || step.repeat !== void 0 || step.steps !== void 0) {
+        return { out: [...out, step], skip: 0 };
+      }
+      const m = step.name.match(/^(.+?)_1$/);
+      if (!m) return { out: [...out, step], skip: 0 };
+      const prefix = m[1];
+      let n = 1;
+      while (i + n < arr.length && arr[i + n].name === `${prefix}_${n + 1}`)
+        n++;
+      if (n < 2) return { out: [...out, step], skip: 0 };
+      const { name: _name, ...rest } = step;
+      return {
+        out: [...out, { ...rest, name: `${prefix}_{{item}}`, repeat: n }],
+        skip: n - 1
+      };
+    },
+    { out: [], skip: 0 }
+  ).out;
 }
 async function* streamPlan(args) {
   const { description, taskFile } = args;
@@ -1373,14 +1492,24 @@ async function* streamPlan(args) {
     yield { type: "plan:stages", names: ["Decompose to Steps", "Validate"] };
     researchDoc = "No codebase research performed \u2014 the task is self-contained. Work directly from the user's original goal.";
   } else {
-    yield { type: "plan:stages", names: ["Research & Planning", "Decompose to Steps", "Validate"] };
-    yield { type: "plan:stage", stage: 1, total: TOTAL_PLAN_STAGES, name: "Research & Planning" };
+    yield {
+      type: "plan:stages",
+      names: ["Research & Planning", "Decompose to Steps", "Validate"]
+    };
+    yield {
+      type: "plan:stage",
+      stage: 1,
+      total: TOTAL_PLAN_STAGES,
+      name: "Research & Planning"
+    };
     const researchLines = [];
     try {
       const researchTask = {
         type: "claude",
         name: "plan:research",
-        prompt: fillTemplate(PLAN_RESEARCH_PROMPT, { DESCRIPTION: description }),
+        prompt: fillTemplate(PLAN_RESEARCH_PROMPT, {
+          DESCRIPTION: description
+        }),
         allowedTools: ["Read", "Glob", "Grep"],
         permissionMode: "bypassPermissions",
         model: "opus"
@@ -1394,17 +1523,28 @@ async function* streamPlan(args) {
         }
       }
     } catch (err) {
-      yield { type: "plan:error", message: `Research pass failed: ${getErrorMessage(err)}` };
+      yield {
+        type: "plan:error",
+        message: `Research pass failed: ${getErrorMessage(err)}`
+      };
       return;
     }
     researchDoc = researchLines.join("\n");
     if (!researchDoc.trim()) {
-      yield { type: "plan:error", message: "Research pass produced no output \u2014 cannot decompose" };
+      yield {
+        type: "plan:error",
+        message: "Research pass produced no output \u2014 cannot decompose"
+      };
       return;
     }
   }
   const stages = skipResearch ? { decompose: 1, validate: 2, total: 2 } : { decompose: 2, validate: 3, total: TOTAL_PLAN_STAGES };
-  yield { type: "plan:stage", stage: stages.decompose, total: stages.total, name: "Decompose to Steps" };
+  yield {
+    type: "plan:stage",
+    stage: stages.decompose,
+    total: stages.total,
+    name: "Decompose to Steps"
+  };
   let retryPrefix = "";
   for (let attempt = 0; attempt < MAX_PLAN_RETRIES; attempt++) {
     if (attempt > 0) {
@@ -1414,9 +1554,17 @@ async function* streamPlan(args) {
         maxAttempts: MAX_PLAN_RETRIES,
         reason: retryPrefix.replace(/\n/g, " ")
       };
-      yield { type: "plan:stage", stage: stages.decompose, total: stages.total, name: "Decompose to Steps" };
+      yield {
+        type: "plan:stage",
+        stage: stages.decompose,
+        total: stages.total,
+        name: "Decompose to Steps"
+      };
     }
-    const basePrompt = fillTemplate(PLAN_DECOMPOSE_PROMPT, { DESCRIPTION: description, RESEARCH_DOC: researchDoc });
+    const basePrompt = fillTemplate(PLAN_DECOMPOSE_PROMPT, {
+      DESCRIPTION: description,
+      RESEARCH_DOC: researchDoc
+    });
     const decomposeTask = {
       type: "claude",
       name: "plan:decompose",
@@ -1448,7 +1596,10 @@ ${basePrompt}` : basePrompt,
         yield { type: "plan:error", message: msg };
         return;
       }
-      retryPrefix = fillTemplate(PLAN_RETRY_PARSE_ERROR, { ERROR: msg, EXCERPT: decomposeTextLines.join("\n") });
+      retryPrefix = fillTemplate(PLAN_RETRY_PARSE_ERROR, {
+        ERROR: msg,
+        EXCERPT: decomposeTextLines.join("\n")
+      });
       continue;
     }
     if (structuredOutput === void 0) {
@@ -1464,24 +1615,40 @@ ${basePrompt}` : basePrompt,
     if (!zodResult.success) {
       const issues = formatZodIssues(zodResult.error.issues);
       if (attempt === MAX_PLAN_RETRIES - 1) {
-        yield { type: "plan:error", message: `Plan did not match expected schema:
-${issues}` };
+        yield {
+          type: "plan:error",
+          message: `Plan did not match expected schema:
+${issues}`
+        };
         return;
       }
       retryPrefix = fillTemplate(PLAN_RETRY_SCHEMA_ERROR, { ISSUES: issues });
       continue;
     }
-    yield { type: "plan:stage", stage: stages.validate, total: stages.total, name: "Validate" };
+    yield {
+      type: "plan:stage",
+      stage: stages.validate,
+      total: stages.total,
+      name: "Validate"
+    };
     const judgeResult = await runPass3Judge(description, zodResult.data);
     if (judgeResult.skipped) {
-      yield { type: "plan:warn", message: "Judge skipped due to error \u2014 proceeding without validation" };
+      yield {
+        type: "plan:warn",
+        message: "Judge skipped due to error \u2014 proceeding without validation"
+      };
     }
     if (!judgeResult.pass && attempt < MAX_PLAN_RETRIES - 1) {
-      retryPrefix = fillTemplate(PLAN_RETRY_JUDGE, { FEEDBACK: judgeResult.feedback });
+      retryPrefix = fillTemplate(PLAN_RETRY_JUDGE, {
+        FEEDBACK: judgeResult.feedback
+      });
       continue;
     }
     if (!judgeResult.pass) {
-      yield { type: "plan:warn", message: `Judge rejected plan but retries exhausted: ${judgeResult.feedback}` };
+      yield {
+        type: "plan:warn",
+        message: `Judge rejected plan but retries exhausted: ${judgeResult.feedback}`
+      };
     }
     const { goal, vars, steps, ...rest } = normalizeWorkflow(zodResult.data);
     const ordered = { goal, ...vars && { vars }, steps, ...rest };
@@ -1497,7 +1664,10 @@ ${issues}` };
     yield { type: "plan:complete", taskFile, preview };
     return;
   }
-  yield { type: "plan:error", message: "Plan generation failed after maximum retries" };
+  yield {
+    type: "plan:error",
+    message: "Plan generation failed after maximum retries"
+  };
 }
 
 // src/ui/PlanApp.tsx
@@ -1724,39 +1894,57 @@ 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, `# Execution Log
+  writeFileSync3(
+    logFile,
+    `# Execution Log
 Task: ${ctx.slug}
 Started: ${(/* @__PURE__ */ new Date()).toISOString()}
 ${"\u2501".repeat(51)}
 
-`);
+`
+  );
   return { ...s, logFile };
 }
 function onStepStart(ctx, s, index, name) {
-  const next = { ...INIT_STATE, logFile: s.logFile, stepIndex: index, stepName: name, stepStartMs: Date.now() };
-  appendLog(next.logFile, `
+  const next = {
+    ...INIT_STATE,
+    logFile: s.logFile,
+    stepIndex: index,
+    stepName: name,
+    stepStartMs: Date.now()
+  };
+  appendLog(
+    next.logFile,
+    `
 ${"\u2501".repeat(51)}
 Step ${index + 1}: ${name}
 Started: ${(/* @__PURE__ */ new Date()).toISOString()}
 ${"\u2501".repeat(51)}
-`);
+`
+  );
   return next;
 }
 function finalizeComplexSequence(s) {
   if (s.toolCount >= 3 && s.complexSequenceFile) {
-    appendFileSync(s.complexSequenceFile, `
+    appendFileSync(
+      s.complexSequenceFile,
+      `
 ---
 
 *Total tools used: ${s.toolCount}*
 
 *Captured by Executant Logger*
-`);
+`
+    );
   }
 }
 function onStepComplete(s) {
-  appendLog(s.logFile, `
+  appendLog(
+    s.logFile,
+    `
 Step completed in ${((Date.now() - s.stepStartMs) / 1e3).toFixed(1)}s
-`);
+`
+  );
   finalizeComplexSequence(s);
   return s;
 }
@@ -1794,29 +1982,35 @@ function onTool(ctx, s, tool, input) {
   const toolCount = s.toolCount + 1;
   const complexSequenceFile = toolCount === 3 ? createComplexSequenceFile(ctx, s) : s.complexSequenceFile;
   if (toolCount >= 3 && complexSequenceFile) {
-    appendFileSync(complexSequenceFile, `${toolCount}. **${tool}** - ${desc}
-`);
+    appendFileSync(
+      complexSequenceFile,
+      `${toolCount}. **${tool}** - ${desc}
+`
+    );
   }
   return { ...s, toolCount, complexSequenceFile };
 }
 function saveJudgeHighlight(ctx, s, verdict, text) {
-  writeFileSync3(highlightPath(ctx, s.stepIndex, `judge_${verdict}`), [
-    `# Judge Verdict: ${verdict}`,
-    "",
-    `**Task:** ${ctx.slug}`,
-    `**Step:** ${s.stepName}`,
-    `**Attempt:** ${s.judgeAttempt}`,
-    `**Timestamp:** ${(/* @__PURE__ */ new Date()).toISOString()}`,
-    "",
-    "---",
-    "",
-    text,
-    "",
-    "---",
-    "",
-    "*Auto-captured*",
-    ""
-  ].join("\n"));
+  writeFileSync3(
+    highlightPath(ctx, s.stepIndex, `judge_${verdict}`),
+    [
+      `# Judge Verdict: ${verdict}`,
+      "",
+      `**Task:** ${ctx.slug}`,
+      `**Step:** ${s.stepName}`,
+      `**Attempt:** ${s.judgeAttempt}`,
+      `**Timestamp:** ${(/* @__PURE__ */ new Date()).toISOString()}`,
+      "",
+      "---",
+      "",
+      text,
+      "",
+      "---",
+      "",
+      "*Auto-captured*",
+      ""
+    ].join("\n")
+  );
 }
 var LOG_MATCHERS = [
   {
@@ -1832,29 +2026,32 @@ var LOG_MATCHERS = [
     pattern: /\[self-healing\].*failed.*exit\s+(\d+)/i,
     apply: (ctx, s, text, match) => {
       const selfHealingFile = highlightPath(ctx, s.stepIndex, "self_healing");
-      writeFileSync3(selfHealingFile, [
-        "# Self-Healing Activation",
-        "",
-        `**Task:** ${ctx.slug}`,
-        `**Step:** ${s.stepName}`,
-        `**Timestamp:** ${(/* @__PURE__ */ new Date()).toISOString()}`,
-        "",
-        "---",
-        "",
-        "## \u274C Failure Detected",
-        "",
-        `**Exit Code:** ${match[1]}`,
-        "",
-        "**Recent Output:**",
-        "```",
-        s.recentOutput.join("\n"),
-        "```",
-        "",
-        "---",
-        "",
-        "## \u{1F527} Claude's Healing Process",
-        ""
-      ].join("\n"));
+      writeFileSync3(
+        selfHealingFile,
+        [
+          "# Self-Healing Activation",
+          "",
+          `**Task:** ${ctx.slug}`,
+          `**Step:** ${s.stepName}`,
+          `**Timestamp:** ${(/* @__PURE__ */ new Date()).toISOString()}`,
+          "",
+          "---",
+          "",
+          "## \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: [] };
     }
   },
@@ -1862,21 +2059,24 @@ var LOG_MATCHERS = [
     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"));
+      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: "" };
     }
   }
@@ -1893,30 +2093,39 @@ function onLogMessage(ctx, s, level, text) {
   ).state;
 }
 function onWorkflowComplete(ctx, s) {
-  appendLog(s.logFile, `
+  appendLog(
+    s.logFile,
+    `
 ${"\u2501".repeat(51)}
 Task Complete: ${ctx.slug}
 Finished: ${(/* @__PURE__ */ new Date()).toISOString()}
 ${"\u2501".repeat(51)}
-`);
+`
+  );
   const indexFile = join3(ctx.highlightsDir, "README.md");
   if (!existsSync2(indexFile)) {
-    writeFileSync3(indexFile, [
-      "# Execution Highlights",
-      "",
-      "This directory contains automatically extracted highlight moments from task executions.",
-      "",
-      "## Latest Highlights",
-      ""
-    ].join("\n"));
+    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, `
+    appendFileSync(
+      indexFile,
+      `
 ### ${ctx.slug} (${(/* @__PURE__ */ new Date()).toISOString()})
 ${entries}
-`);
+`
+    );
   }
   return s;
 }
@@ -1934,6 +2143,19 @@ function reduce(ctx, s, event) {
       return onStepComplete(s);
     case "step:error":
       return onStepError(s, event.error);
+    case "step:iteration":
+      appendLog(
+        s.logFile,
+        `
+\u2500\u2500 iteration ${event.iteration}/${event.total}: ${event.item}`
+      );
+      return s;
+    case "step:inner":
+      appendLog(
+        s.logFile,
+        `   \u21B3 [${event.innerIndex + 1}/${event.innerTotal}] ${event.name}`
+      );
+      return s;
     case "output:text":
       return onOutputText(s, event.text);
     case "output:tool":
@@ -2115,16 +2337,21 @@ function extractJson(text) {
 
 // src/index.ts
 var CURRENT_VERSION = JSON.parse(
-  readFileSync6(join5(dirname5(fileURLToPath2(import.meta.url)), "../package.json"), "utf-8")
+  readFileSync6(
+    join5(dirname5(fileURLToPath2(import.meta.url)), "../package.json"),
+    "utf-8"
+  )
 ).version;
 var rawArgs = process.argv.slice(2);
 if (rawArgs[0] === "plan") {
   const planArgs = parsePlanArgs(rawArgs.slice(1));
   const planEvents = streamPlan(planArgs);
-  const inkApp = render(React3.createElement(PlanApp, {
-    description: planArgs.description,
-    events: planEvents
-  }));
+  const inkApp = render(
+    React3.createElement(PlanApp, {
+      description: planArgs.description,
+      events: planEvents
+    })
+  );
   try {
     await inkApp.waitUntilExit();
   } catch {
@@ -2173,7 +2400,15 @@ YAML \u2014 step fields (all step types):
   forEach           string or list
                     Inline YAML array OR a shell command whose newline-split
                     stdout provides the items. {{item}} is substituted per
-                    iteration in the inner step's prompt or command.
+                    iteration in every child step's name, command, and prompt.
+  repeat            int     Run this step N times; {{item}} is the 1-based
+                    iteration number. Mutually exclusive with forEach.
+  steps             list    Multiple child steps to run per forEach/repeat
+                    iteration. Mutually exclusive with command/prompt on the
+                    parent step. Requires forEach or repeat.
+  context           list    Var names whose file-path values are prepended to
+                    a prompt step's content at runtime.
+  output            string  Var name; captures script stdout to that file path.
 
 YAML \u2014 prompt step fields (type: prompt, or inferred when prompt is present):
   prompt            string  (required) Instructions sent to Claude
@@ -2185,7 +2420,7 @@ YAML \u2014 prompt step fields (type: prompt, or inferred when prompt is present
 YAML \u2014 script step fields (type: script | command, or inferred when command is present):
   command           string  (required) Bash command to execute
   self_healing      bool    On failure, Claude diagnoses and fixes iteratively
-                            up to 5 attempts with accumulated context (default: true)
+                            up to 5 attempts with accumulated context (default: false)
   max_healing_attempts  int   Override max self-healing retries (default: 5)
 
 YAML \u2014 log step fields (type: log, or inferred when message is present and prompt is absent):
@@ -2263,9 +2498,17 @@ function errorReplacer(_key, value) {
 async function maybeRunRetrospective(filePath2, workflow2, logger2) {
   if (!logger2) return;
   try {
-    await runRetrospective(filePath2, workflow2, logger2.getHighlightsDir(), logger2.getTimestamp());
+    await runRetrospective(
+      filePath2,
+      workflow2,
+      logger2.getHighlightsDir(),
+      logger2.getTimestamp()
+    );
   } catch (err) {
-    console.warn("[executant] retrospective failed (non-fatal):", getErrorMessage(err));
+    console.warn(
+      "[executant] retrospective failed (non-fatal):",
+      getErrorMessage(err)
+    );
   }
 }
 if (ciMode) {
@@ -2281,7 +2524,9 @@ if (ciMode) {
     process.exit(1);
   });
 } else {
-  const inkApp = render(React3.createElement(App, { workflow, events, options, updateCheck }));
+  const inkApp = render(
+    React3.createElement(App, { workflow, events, options, updateCheck })
+  );
   if (workflow.selfImprove) {
     inkApp.waitUntilExit().then(() => maybeRunRetrospective(filePath, workflow, logger)).catch(() => {
     });

package/dist/prompts/plan-decompose.txt

@@ -52,10 +52,27 @@ Complete structure with all available options:
       "forEach": "git diff --name-only HEAD~1",
       "prompt": "Review {{item}} for issues and suggest improvements."
     },
+    {
+      "name": "foreach_multi_step",
+      "forEach": ["pkg/api", "pkg/web"],
+      "steps": [
+        { "name": "lint {{item}}", "type": "script", "command": "cd {{item}} && npm run lint" },
+        { "name": "test {{item}}", "type": "script", "command": "cd {{item}} && npm test" },
+        { "name": "review {{item}}", "prompt": "Review the test results for {{item}} and summarize any issues." }
+      ]
+    },
     {
       "name": "repeated_audit",
       "repeat": 20,
       "prompt": "Review the codebase for issues. This is pass {{item}} of 20."
+    },
+    {
+      "name": "repeated_multi_step",
+      "repeat": 3,
+      "steps": [
+        { "name": "build pass {{item}}", "type": "script", "command": "npm run build" },
+        { "name": "test pass {{item}}", "type": "script", "command": "npm test" }
+      ]
     }
   ]
 }
@@ -94,6 +111,9 @@ or commands.
 
 **Pre-Output Self-Review — Vars (MANDATORY):**
 Before finalising your JSON, scan every `prompt` and `command` field you wrote — every sentence, every numbered instruction, every parenthetical.
+
+**`{{item}}` is NOT a path — never extract it to `vars`.** It is a runtime placeholder that the runner substitutes per iteration. Only treat actual string literals as paths requiring `vars` extraction.
+
 For each field, identify ALL occurrences of paths, including:
 - Direct path references (e.g., `src/middleware/rate-limit.ts`)
 - Paths mentioned in narrative context (e.g., "match the style of tests in `src/tests/`")
@@ -158,11 +178,30 @@ Use the EXACT commands from the research document. Only skip a category if the r
 
 **REQUIRED: Always use `forEach` instead of enumerating items inline in a prompt.**
 
+**Use nested `steps:` inside `forEach` or `repeat` when:**
+- Each iteration requires **two or more** distinct actions (e.g., lint THEN test THEN review) — if there is only one action per item, use `command` or `prompt` directly on the forEach step instead
+- Replace `command`/`prompt` on the forEach step with a `steps` array of child steps
+- Child steps support all standard step fields (`type`, `command`, `prompt`, `llm_as_judge`, etc.)
+- `{{item}}` substitution applies to all child step `name`, `command`, and `prompt` fields
+- Mutually exclusive with `command`/`prompt` on the parent step
+
+```json
+{
+  "name": "process each package",
+  "forEach": ["pkg/api", "pkg/web"],
+  "steps": [
+    { "name": "lint {{item}}", "type": "script", "command": "cd {{item}} && npm run lint" },
+    { "name": "test {{item}}", "type": "script", "command": "cd {{item}} && npm test" }
+  ]
+}
+```
+
 **Use `repeat: N` when:**
 - The user asks to run the same prompt or command multiple times ("do this 20 times", "repeat 5 times", "run N iterations")
 - The step is identical each time — only the iteration number ({{item}}) differs
 - Prefer `repeat` over `forEach` when there is no meaningful list of items — just a count
 - NEVER expand "do X N times" into N separate steps — always use `repeat: N`
+- Combine with nested `steps:` when each iteration needs multiple sub-steps
 
 ## Atomicity (MANDATORY)
 
@@ -231,6 +270,7 @@ Generate a JSON object that:
 10. Uses `output:` + `context:` to pass script step results to downstream prompt steps
 11. Declares ALL file paths in `vars` — no hardcoded paths in prompts or commands, including paths in narrative or example context
 12. Places `vars` before `steps` in the JSON output
+13. Uses nested `steps:` inside `forEach`/`repeat` when each iteration needs multiple sequential actions
 
 ## Critical Rules
 

package/dist/prompts/plan-judge.txt

@@ -35,6 +35,7 @@ Does the workflow contain at least one of: a lint step, a test step, or a build
 
 - Look for `type: "script"` steps whose `command` runs a linter, test runner, or build tool
   (e.g., `npm run lint`, `npm test`, `npm run build`, `pytest`, `tsc --noEmit`, `go test`, etc.)
+- **This includes script steps nested inside a `forEach` or `repeat`'s `steps:` array** — a lint/test/build step inside a loop's child steps satisfies the verification requirement
 - A workflow with ZERO verification steps automatically FAILS regardless of other criteria
 - A visual check prompt step with `llm_as_judge: true` as the final step is acceptable if no
   lint/test/build commands exist in the project
@@ -45,6 +46,7 @@ Are steps focused on a single concern?
 - Does any step do more than one distinct thing (e.g., "implement AND test")?
 - Could any step be meaningfully split into two smaller steps?
 - Steps that combine unrelated operations are too large
+- **Exception**: A `forEach`/`repeat` step with a nested `steps:` array is NOT an atomicity violation — each child step should itself be atomic, and the parent is a loop container, not a combined action
 
 ### 3. Goal Coverage
 Do the steps collectively accomplish the stated goal?
@@ -83,7 +85,7 @@ or
 ```
 
 Rules:
-- `pass` is `true` only if ALL four criteria above are met
+- `pass` is `true` only if ALL five criteria above are met
 - `feedback` is an empty string when `pass` is `true`
 - `feedback` must be specific and actionable when `pass` is `false` — say EXACTLY what is wrong
   and what the decomposer must do to fix it

package/package.json

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