@kody-ade/kody-engine 0.2.7 → 0.2.9

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.7",
+  version: "0.2.9",
   description: "kody2 \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -108,6 +108,7 @@ function loadConfig(projectDir = process.cwd()) {
     },
     issueContext: parseIssueContext(raw.issueContext),
     testRequirements: parseTestRequirements(raw.testRequirements),
+    defaultExecutable: typeof raw.defaultExecutable === "string" && raw.defaultExecutable.length > 0 ? raw.defaultExecutable : void 0,
     release: parseReleaseConfig(raw.release)
   };
 }
@@ -1962,10 +1963,201 @@ var loadCoverageRules = async (ctx) => {
   ctx.data.coverageRules = ctx.config.testRequirements ?? [];
 };
 
+// src/state.ts
+import { execFileSync as execFileSync10 } from "child_process";
+var STATE_BEGIN = "<!-- kody2:state:v1:begin -->";
+var STATE_END = "<!-- kody2:state:v1:end -->";
+var HISTORY_MAX_ENTRIES = 20;
+var API_TIMEOUT_MS2 = 3e4;
+function emptyState() {
+  return {
+    schemaVersion: 1,
+    core: {
+      phase: "idle",
+      status: "pending",
+      currentExecutable: null,
+      lastOutcome: null,
+      attempts: {}
+    },
+    executables: {},
+    history: []
+  };
+}
+function ghToken3() {
+  return process.env.GH_PAT?.trim() || process.env.GH_TOKEN;
+}
+function gh3(args, input, cwd) {
+  const token = ghToken3();
+  const env = token ? { ...process.env, GH_TOKEN: token } : { ...process.env };
+  return execFileSync10("gh", args, {
+    encoding: "utf-8",
+    timeout: API_TIMEOUT_MS2,
+    cwd,
+    env,
+    input,
+    stdio: input ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"]
+  }).trim();
+}
+function findStateComment(target, number, cwd) {
+  const apiPath = target === "issue" ? `repos/{owner}/{repo}/issues/${number}/comments` : `repos/{owner}/{repo}/issues/${number}/comments`;
+  try {
+    const raw = gh3(["api", "--paginate", apiPath], void 0, cwd);
+    const list = JSON.parse(raw);
+    for (const c of list) {
+      if (c.body?.includes(STATE_BEGIN)) {
+        return { id: String(c.id), body: c.body };
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function parseStateComment(body) {
+  const beginIdx = body.indexOf(STATE_BEGIN);
+  const endIdx = body.indexOf(STATE_END, beginIdx + 1);
+  if (beginIdx < 0 || endIdx < 0) return emptyState();
+  const between = body.slice(beginIdx + STATE_BEGIN.length, endIdx);
+  const fenceMatch = between.match(/```json\s*([\s\S]*?)\s*```/);
+  if (!fenceMatch) return emptyState();
+  try {
+    const parsed = JSON.parse(fenceMatch[1]);
+    if (parsed?.schemaVersion !== 1) return emptyState();
+    return {
+      schemaVersion: 1,
+      core: { ...emptyState().core, ...parsed.core },
+      executables: parsed.executables ?? {},
+      history: Array.isArray(parsed.history) ? parsed.history : []
+    };
+  } catch {
+    return emptyState();
+  }
+}
+function reduce(state, executable, action) {
+  if (!action) return state;
+  const newAttempts = { ...state.core.attempts, [executable]: (state.core.attempts[executable] ?? 0) + 1 };
+  const newExecutables = {
+    ...state.executables,
+    [executable]: { ...state.executables[executable] ?? { lastAction: null }, lastAction: action }
+  };
+  const newHistory = [
+    ...state.history,
+    { timestamp: action.timestamp, executable, action: action.type, note: noteFromAction(action) }
+  ].slice(-HISTORY_MAX_ENTRIES);
+  return {
+    schemaVersion: 1,
+    core: {
+      ...state.core,
+      attempts: newAttempts,
+      lastOutcome: action,
+      currentExecutable: executable,
+      status: statusFromAction(action),
+      phase: phaseFromAction(executable, action)
+    },
+    executables: newExecutables,
+    history: newHistory
+  };
+}
+function statusFromAction(action) {
+  if (/FAILED$|ERROR$|MISSING$|REJECTED$/i.test(action.type)) return "failed";
+  if (/COMPLETED$|SHIPPED$|MERGED$|SUCCESS$/i.test(action.type)) return "succeeded";
+  return "running";
+}
+function phaseFromAction(executable, action) {
+  if (/FAILED$|ERROR$|REJECTED$/i.test(action.type)) return "failed";
+  if (executable === "build") return statusFromAction(action) === "succeeded" ? "implementing" : "implementing";
+  if (executable === "review") return "reviewing";
+  if (executable === "release") return "shipped";
+  return "idle";
+}
+function noteFromAction(action) {
+  const p = action.payload;
+  if (typeof p?.prUrl === "string") return p.prUrl;
+  if (typeof p?.reason === "string") return p.reason.slice(0, 120);
+  if (typeof p?.commitMessage === "string") return p.commitMessage.slice(0, 120);
+  return void 0;
+}
+function renderStateComment(state) {
+  const lines = [];
+  lines.push(STATE_BEGIN);
+  lines.push("");
+  lines.push("```json");
+  lines.push(JSON.stringify(
+    { schemaVersion: state.schemaVersion, core: state.core, executables: state.executables, history: state.history },
+    null,
+    2
+  ));
+  lines.push("```");
+  lines.push("");
+  lines.push(STATE_END);
+  lines.push("");
+  lines.push("## kody2 task state");
+  lines.push("");
+  lines.push(`- **Phase:** \`${state.core.phase}\`  **Status:** \`${state.core.status}\``);
+  if (state.core.currentExecutable) {
+    lines.push(`- **Last executable:** \`${state.core.currentExecutable}\``);
+  }
+  if (state.core.lastOutcome) {
+    lines.push(`- **Last action:** \`${state.core.lastOutcome.type}\``);
+  }
+  const attempts = Object.entries(state.core.attempts).map(([k, v]) => `${k}:${v}`).join(", ");
+  if (attempts) lines.push(`- **Attempts:** ${attempts}`);
+  if (state.core.prUrl) lines.push(`- **PR:** ${state.core.prUrl}`);
+  if (state.core.runUrl) lines.push(`- **Run:** ${state.core.runUrl}`);
+  lines.push("");
+  if (state.history.length > 0) {
+    lines.push("### Recent history");
+    lines.push("");
+    const recent = state.history.slice(-10).reverse();
+    for (const h of recent) {
+      const note = h.note ? ` \u2014 ${h.note}` : "";
+      lines.push(`- \`${h.timestamp}\` **${h.executable}** \u2192 \`${h.action}\`${note}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function readTaskState(target, number, cwd) {
+  const existing = findStateComment(target, number, cwd);
+  return existing ? parseStateComment(existing.body) : emptyState();
+}
+function writeTaskState(target, number, state, cwd) {
+  const body = renderStateComment(state);
+  const existing = findStateComment(target, number, cwd);
+  try {
+    if (existing) {
+      gh3(
+        ["api", `repos/{owner}/{repo}/issues/comments/${existing.id}`, "-X", "PATCH", "-F", "body=@-"],
+        body,
+        cwd
+      );
+    } else {
+      const sub = target === "issue" ? "issue" : "pr";
+      gh3([sub, "comment", String(number), "--body-file", "-"], body, cwd);
+    }
+  } catch (err) {
+    process.stderr.write(
+      `[kody2 state] failed to write state on ${target} #${number}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+  }
+}
+
+// src/scripts/loadTaskState.ts
+var loadTaskState = async (ctx) => {
+  const target = ctx.data.commentTargetType;
+  const number = ctx.data.commentTargetNumber;
+  if (!target || !number) {
+    ctx.data.taskState = emptyState();
+    return;
+  }
+  ctx.data.taskState = readTaskState(target, number, ctx.cwd);
+};
+
 // src/scripts/parseAgentResult.ts
-var parseAgentResult2 = async (ctx, _profile, agentResult) => {
+var parseAgentResult2 = async (ctx, profile, agentResult) => {
   if (!agentResult) {
     ctx.data.agentDone = false;
+    ctx.data.action = makeAction("AGENT_NOT_RUN", { reason: "no agent result" });
     return;
   }
   const parsed = parseAgentResult(agentResult.finalText);
@@ -1975,7 +2167,21 @@ var parseAgentResult2 = async (ctx, _profile, agentResult) => {
   ctx.data.agentFailureReason = parsed.failureReason;
   ctx.data.agentOutcome = agentResult.outcome;
   ctx.data.agentError = agentResult.error;
+  const modeSeg = (ctx.args.mode ?? profile.name).replace(/-/g, "_").toUpperCase();
+  if (parsed.done) {
+    ctx.data.action = makeAction(`${modeSeg}_COMPLETED`, {
+      commitMessage: parsed.commitMessage,
+      prSummary: parsed.prSummary
+    });
+  } else {
+    ctx.data.action = makeAction(`${modeSeg}_FAILED`, {
+      reason: parsed.failureReason || agentResult.error || "unknown failure"
+    });
+  }
 };
+function makeAction(type, payload) {
+  return { type, payload, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+}
 
 // src/scripts/postIssueComment.ts
 var postIssueComment2 = async (ctx) => {
@@ -2079,7 +2285,7 @@ REVIEW_POSTED=https://github.com/${ctx.config.github.owner}/${ctx.config.github.
 };
 
 // src/scripts/releaseFlow.ts
-import { execFileSync as execFileSync10, spawnSync } from "child_process";
+import { execFileSync as execFileSync11, spawnSync } from "child_process";
 import * as fs11 from "fs";
 import * as path10 from "path";
 function bumpVersion(current, bump) {
@@ -2109,7 +2315,7 @@ function generateChangelog(cwd, newVersion, lastTag) {
   const range = lastTag ? `${lastTag}..HEAD` : "HEAD";
   let log = "";
   try {
-    log = execFileSync10("git", ["log", range, "--pretty=format:%s||%h", "--no-merges"], {
+    log = execFileSync11("git", ["log", range, "--pretty=format:%s||%h", "--no-merges"], {
       cwd,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "pipe"]
@@ -2166,7 +2372,7 @@ ${entry}${prior.slice(idx + 1)}`);
   }
 }
 function git3(args, cwd, timeout = 6e4) {
-  return execFileSync10("git", args, {
+  return execFileSync11("git", args, {
     encoding: "utf-8",
     timeout,
     cwd,
@@ -2381,7 +2587,7 @@ ${truncate2(r.stderr, 2e3)}
 }
 
 // src/scripts/resolveFlow.ts
-import { execFileSync as execFileSync11 } from "child_process";
+import { execFileSync as execFileSync12 } from "child_process";
 var CONFLICT_DIFF_MAX_BYTES = 4e4;
 var resolveFlow = async (ctx) => {
   const prNumber = ctx.args.pr;
@@ -2433,7 +2639,7 @@ var resolveFlow = async (ctx) => {
 };
 function getConflictedFiles(cwd) {
   try {
-    const out = execFileSync11("git", ["diff", "--name-only", "--diff-filter=U"], {
+    const out = execFileSync12("git", ["diff", "--name-only", "--diff-filter=U"], {
       encoding: "utf-8",
       cwd,
       env: { ...process.env, HUSKY: "0" }
@@ -2448,7 +2654,7 @@ function getConflictMarkersPreview(files, cwd, maxBytes = CONFLICT_DIFF_MAX_BYTE
   let total = 0;
   for (const f of files) {
     try {
-      const content = execFileSync11("cat", [f], { encoding: "utf-8", cwd }).toString();
+      const content = execFileSync12("cat", [f], { encoding: "utf-8", cwd }).toString();
       const snippet = `### ${f}
 
 \`\`\`
@@ -2528,6 +2734,35 @@ function tryPost(issueNumber, body, cwd) {
   }
 }
 
+// src/scripts/saveTaskState.ts
+var saveTaskState = async (ctx, profile) => {
+  const target = ctx.data.commentTargetType;
+  const number = ctx.data.commentTargetNumber;
+  const state = ctx.data.taskState;
+  if (!target || !number || !state) return;
+  const executable = profile.name;
+  const action = ctx.data.action ?? synthesizeAction(ctx);
+  if (ctx.output.prUrl && !state.core.prUrl) state.core.prUrl = ctx.output.prUrl;
+  if (typeof ctx.data.runUrl === "string") state.core.runUrl = ctx.data.runUrl;
+  const next = reduce(state, executable, action);
+  if (ctx.output.prUrl) next.core.prUrl = ctx.output.prUrl;
+  if (typeof ctx.data.runUrl === "string") next.core.runUrl = ctx.data.runUrl;
+  writeTaskState(target, number, next, ctx.cwd);
+  ctx.data.taskStateRendered = renderStateComment(next);
+};
+function synthesizeAction(ctx) {
+  const ok = ctx.output.exitCode === 0;
+  return {
+    type: ok ? "RUN_COMPLETED" : "RUN_FAILED",
+    payload: {
+      exitCode: ctx.output.exitCode,
+      reason: ctx.output.reason,
+      prUrl: ctx.output.prUrl
+    },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
 // src/verify.ts
 import { spawn as spawn2 } from "child_process";
 var TAIL_CHARS = 4e3;
@@ -2730,6 +2965,7 @@ var preflightScripts = {
   initFlow,
   releaseFlow,
   watchStalePrsFlow,
+  loadTaskState,
   loadConventions,
   loadCoverageRules,
   composePrompt
@@ -2742,7 +2978,8 @@ var postflightScripts = {
   ensurePr: ensurePr2,
   postIssueComment: postIssueComment2,
   postReviewResult,
-  writeRunSummary
+  writeRunSummary,
+  saveTaskState
 };
 var allScriptNames = /* @__PURE__ */ new Set([
   ...Object.keys(preflightScripts),
@@ -2750,7 +2987,7 @@ var allScriptNames = /* @__PURE__ */ new Set([
 ]);
 
 // src/tools.ts
-import { execFileSync as execFileSync12 } from "child_process";
+import { execFileSync as execFileSync13 } from "child_process";
 function verifyCliTools(tools, cwd) {
   const out = [];
   for (const t of tools) out.push(verifyOne(t, cwd));
@@ -2783,7 +3020,7 @@ function verifyOne(tool, cwd) {
 }
 function runShell2(cmd, cwd, timeoutMs = 3e4) {
   try {
-    execFileSync12("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
+    execFileSync13("sh", ["-c", cmd], { cwd, stdio: "pipe", timeout: timeoutMs });
     return true;
   } catch {
     return false;
@@ -2981,17 +3218,19 @@ function finish(out) {
 }
 
 // src/kody2-cli.ts
-import { execFileSync as execFileSync13 } from "child_process";
+import { execFileSync as execFileSync14 } from "child_process";
 import * as fs15 from "fs";
 import * as path12 from "path";
 
 // src/dispatch.ts
 import * as fs14 from "fs";
-function autoDispatch(explicit) {
-  if (explicit?.mode && explicit.target) {
+function autoDispatch(opts) {
+  const explicit = opts?.explicit;
+  if (explicit?.issueNumber && explicit.issueNumber > 0) {
     return {
-      mode: explicit.mode,
-      target: explicit.target
+      executable: "build",
+      cliArgs: { mode: "run", issue: explicit.issueNumber },
+      target: explicit.issueNumber
     };
   }
   const eventName = process.env.GITHUB_EVENT_NAME;
@@ -3005,30 +3244,60 @@ function autoDispatch(explicit) {
   }
   if (eventName === "workflow_dispatch") {
     const n = parseInt(String(event.inputs?.issue_number ?? ""), 10);
-    if (!Number.isNaN(n) && n > 0) return { mode: "run", target: n };
+    if (!Number.isNaN(n) && n > 0) {
+      return { executable: "build", cliArgs: { mode: "run", issue: n }, target: n };
+    }
     return null;
   }
-  if (eventName === "issue_comment") {
-    const body = String(event.comment?.body ?? "").toLowerCase();
-    const issueNum = Number(event.issue?.number ?? 0);
-    const isPr = !!event.issue?.pull_request;
-    if (!issueNum) return null;
-    const afterTag = extractAfterTag(body);
-    if (isPr) {
-      if (/\bfix-ci\b/.test(afterTag)) return { mode: "fix-ci", target: issueNum };
-      if (/\bresolve\b/.test(afterTag)) return { mode: "resolve", target: issueNum };
-      const feedbackText = extractFeedback(afterTag);
-      return { mode: "fix", target: issueNum, feedback: feedbackText };
+  if (eventName !== "issue_comment") return null;
+  const body = String(event.comment?.body ?? "").toLowerCase();
+  const targetNum = Number(event.issue?.number ?? 0);
+  const isPr = !!event.issue?.pull_request;
+  if (!targetNum) return null;
+  const afterTag = extractAfterTag(body);
+  if (isPr) {
+    if (/\bfix-ci\b/.test(afterTag)) {
+      return { executable: "build", cliArgs: { mode: "fix-ci", pr: targetNum }, target: targetNum };
     }
-    return { mode: "run", target: issueNum };
+    if (/\bresolve\b/.test(afterTag)) {
+      return { executable: "build", cliArgs: { mode: "resolve", pr: targetNum }, target: targetNum };
+    }
+    const feedback = extractFeedback(afterTag);
+    return {
+      executable: "build",
+      cliArgs: { mode: "fix", pr: targetNum, ...feedback ? { feedback } : {} },
+      target: targetNum
+    };
   }
-  return null;
+  const sub = extractSubcommand(afterTag);
+  const defaultExec = opts?.config?.defaultExecutable ?? "build";
+  if (!sub) {
+    return asDispatch(defaultExec, targetNum);
+  }
+  if (sub === "build") {
+    return { executable: "build", cliArgs: { mode: "run", issue: targetNum }, target: targetNum };
+  }
+  if (sub === "orchestrate" || sub === "orchestrator") {
+    return { executable: "orchestrator", cliArgs: { issue: targetNum }, target: targetNum };
+  }
+  return asDispatch(sub, targetNum);
+}
+function asDispatch(executable, target) {
+  if (executable === "build") {
+    return { executable, cliArgs: { mode: "run", issue: target }, target };
+  }
+  return { executable, cliArgs: { issue: target }, target };
 }
 function extractAfterTag(body) {
   const idx = body.indexOf("@kody2");
   if (idx === -1) return body;
   return body.slice(idx + "@kody2".length).trim();
 }
+function extractSubcommand(afterTag) {
+  const match = afterTag.match(/^([a-z][a-z0-9-]{1,40})\b/);
+  if (!match) return null;
+  return match[1];
+}
 function extractFeedback(afterTag) {
   const cleaned = afterTag.replace(/^(fix|please|kindly)[\s:,.-]+/i, "").trim();
   return cleaned.length > 0 ? cleaned : void 0;
@@ -3126,7 +3395,7 @@ function detectPackageManager2(cwd) {
 }
 function shellOut(cmd, args, cwd, stream = true) {
   try {
-    execFileSync13(cmd, args, {
+    execFileSync14(cmd, args, {
       cwd,
       stdio: stream ? "inherit" : "pipe",
       env: { ...process.env, HUSKY: "0", SKIP_HOOKS: "1", CI: process.env.CI ?? "1" }
@@ -3139,7 +3408,7 @@ function shellOut(cmd, args, cwd, stream = true) {
 }
 function isOnPath(bin) {
   try {
-    execFileSync13("which", [bin], { stdio: "pipe" });
+    execFileSync14("which", [bin], { stdio: "pipe" });
     return true;
   } catch {
     return false;
@@ -3173,7 +3442,7 @@ function installLitellmIfNeeded(cwd) {
   } catch {
   }
   try {
-    execFileSync13("python3", ["-c", "import litellm"], { stdio: "pipe" });
+    execFileSync14("python3", ["-c", "import litellm"], { stdio: "pipe" });
     process.stdout.write("\u2192 kody2: litellm already installed\n");
     return 0;
   } catch {
@@ -3183,16 +3452,16 @@ function installLitellmIfNeeded(cwd) {
 }
 function configureGitIdentity(cwd) {
   try {
-    const name = execFileSync13("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
+    const name = execFileSync14("git", ["config", "user.name"], { cwd, stdio: "pipe", encoding: "utf-8" }).trim();
     if (name) return;
   } catch {
   }
   try {
-    execFileSync13("git", ["config", "user.name", "kody2-bot"], { cwd, stdio: "pipe" });
+    execFileSync14("git", ["config", "user.name", "kody2-bot"], { cwd, stdio: "pipe" });
   } catch {
   }
   try {
-    execFileSync13("git", ["config", "user.email", "kody2-bot@users.noreply.github.com"], { cwd, stdio: "pipe" });
+    execFileSync14("git", ["config", "user.email", "kody2-bot@users.noreply.github.com"], { cwd, stdio: "pipe" });
   } catch {
   }
 }
@@ -3227,7 +3496,13 @@ async function runCi(argv) {
     return 0;
   }
   const args = parseCiArgs(argv);
-  const autoFallback = !args.issueNumber ? autoDispatch() : null;
+  const cwd = args.cwd ? path12.resolve(args.cwd) : process.cwd();
+  let earlyConfig;
+  try {
+    earlyConfig = loadConfig(cwd);
+  } catch {
+  }
+  const autoFallback = !args.issueNumber ? autoDispatch({ config: earlyConfig }) : null;
   if (!args.issueNumber && !autoFallback) {
   } else {
     args.errors = args.errors.filter((e) => !e.includes("--issue"));
@@ -3239,14 +3514,13 @@ async function runCi(argv) {
 ${CI_HELP}`);
     return 64;
   }
-  const cwd = args.cwd ? path12.resolve(args.cwd) : process.cwd();
   const dispatch = autoFallback ?? {
-    mode: "run",
-    target: args.issueNumber,
-    feedback: void 0
+    executable: "build",
+    cliArgs: { mode: "run", issue: args.issueNumber },
+    target: args.issueNumber
   };
   const issueNumber = dispatch.target;
-  process.stdout.write(`\u2192 kody2 preflight (cwd=${cwd}, mode=${dispatch.mode}, target=${issueNumber})
+  process.stdout.write(`\u2192 kody2 preflight (cwd=${cwd}, executable=${dispatch.executable}, target=${issueNumber})
 `);
   try {
     const n = unpackAllSecrets();
@@ -3283,17 +3557,13 @@ ${CI_HELP}`);
     postFailureTail(issueNumber, cwd, `preflight crashed: ${msg}`);
     return 99;
   }
-  process.stdout.write(`\u2192 kody2: preflight done, handing off to kody2 ${dispatch.mode}
+  process.stdout.write(`\u2192 kody2: preflight done, handing off to kody2 ${dispatch.executable}
 
 `);
   try {
-    const config = loadConfig(cwd);
-    const cliArgs = { mode: dispatch.mode };
-    if (dispatch.mode === "run") cliArgs.issue = issueNumber;
-    else cliArgs.pr = issueNumber;
-    if (dispatch.feedback) cliArgs.feedback = dispatch.feedback;
-    const result = await runExecutable("build", {
-      cliArgs,
+    const config = earlyConfig ?? loadConfig(cwd);
+    const result = await runExecutable(dispatch.executable, {
+      cliArgs: dispatch.cliArgs,
       cwd,
       config,
       verbose: args.verbose,

package/dist/executables/build/profile.json

@@ -67,6 +67,7 @@
       { "script": "fixFlow",     "runWhen": { "args.mode": "fix" } },
       { "script": "fixCiFlow",   "runWhen": { "args.mode": "fix-ci" } },
       { "script": "resolveFlow", "runWhen": { "args.mode": "resolve" } },
+      { "script": "loadTaskState" },
       { "script": "loadConventions" },
       { "script": "loadCoverageRules" },
       { "script": "composePrompt" }
@@ -78,7 +79,21 @@
       { "script": "commitAndPush" },
       { "script": "ensurePr" },
       { "script": "postIssueComment" },
-      { "script": "writeRunSummary" }
+      { "script": "writeRunSummary" },
+      { "script": "saveTaskState" }
+    ]
+  },
+  "output": {
+    "actionTypes": [
+      "RUN_COMPLETED",
+      "RUN_FAILED",
+      "FIX_COMPLETED",
+      "FIX_FAILED",
+      "FIX_CI_COMPLETED",
+      "FIX_CI_FAILED",
+      "RESOLVE_COMPLETED",
+      "RESOLVE_FAILED",
+      "AGENT_NOT_RUN"
     ]
   }
 }

package/dist/executables/orchestrator/profile.json

@@ -0,0 +1,55 @@
+{
+  "name": "orchestrator",
+  "describe": "Drive a chain of kody2 executables by posting @kody2 subcommand comments and polling the task-state comment. Atomic — one orchestrator run fires one flow.",
+
+  "inputs": [
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub issue number to drive."
+    },
+    {
+      "name": "flow",
+      "flag": "--flow",
+      "type": "string",
+      "required": false,
+      "describe": "Named flow to run (e.g. 'plan-then-build'). Defaults to plan-then-build."
+    }
+  ],
+
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": null,
+    "systemPromptAppend": null,
+    "tools": ["Bash", "Read"],
+    "hooks": { "PreToolUse": [], "PostToolUse": [], "Stop": [] },
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+
+  "cliTools": [],
+
+  "scripts": {
+    "preflight": [
+      { "script": "runFlow" },
+      { "script": "loadTaskState" },
+      { "script": "composePrompt" }
+    ],
+    "postflight": [
+      { "script": "parseAgentResult" },
+      { "script": "postIssueComment" },
+      { "script": "writeRunSummary" },
+      { "script": "saveTaskState" }
+    ]
+  },
+
+  "output": {
+    "actionTypes": ["ORCHESTRATION_COMPLETED", "ORCHESTRATION_FAILED"]
+  }
+}

package/dist/executables/orchestrator/prompts/orchestrator.md

@@ -0,0 +1,56 @@
+You are the **kody2 orchestrator** for issue #{{issue.number}} on {{repoOwner}}/{{repoName}}.
+
+Your job: drive a 2-step flow **plan → build** by posting `@kody2 <subcommand>` comments on the issue and watching the state-comment for completion signals. You do NOT edit files. You do NOT run git. You use `gh` (via Bash) only to post comments and read the state-comment.
+
+---
+
+# Issue #{{issue.number}}: {{issue.title}}
+
+{{issue.body}}
+
+# Required flow (plan-then-build)
+
+1. **Kick off plan.** Post an issue comment with EXACTLY this body:
+   ```
+   @kody2 plan
+   ```
+   Use: `gh issue comment {{issue.number}} --body "@kody2 plan"` (in the cwd).
+2. **Wait for plan to complete.** Poll the issue's state-comment every ~30s. The state-comment is the one whose body starts with `<!-- kody2:state:v1:begin -->`. Fetch it with:
+   ```
+   gh api repos/{{repoOwner}}/{{repoName}}/issues/{{issue.number}}/comments --paginate --jq '.[] | select(.body | contains("kody2:state:v1:begin")) | .body'
+   ```
+   Parse the JSON block inside the sentinels. Look for `core.lastOutcome.type == "PLAN_COMPLETED"`.
+   If `core.lastOutcome.type == "PLAN_FAILED"` OR if 10 minutes pass without completion → abort with:
+   ```
+   FAILED: plan did not complete (<reason from state or "timeout">)
+   ```
+3. **Kick off build.** Post:
+   ```
+   @kody2 build
+   ```
+   Same `gh issue comment` command.
+4. **Wait for build to complete.** Same poll technique. Look for `core.lastOutcome.type == "RUN_COMPLETED"` (build's success marker) or `RUN_FAILED`. If `RUN_FAILED` or 30 minutes pass → abort with `FAILED: build did not complete (...)`.
+5. **Emit final summary.**
+
+# Required final output
+
+On success:
+
+```
+DONE
+COMMIT_MSG: chore(orchestrator): plan-then-build for #{{issue.number}}
+PR_SUMMARY:
+- Posted `@kody2 plan` and observed PLAN_COMPLETED.
+- Posted `@kody2 build` and observed RUN_COMPLETED.
+- Final PR: <prUrl from state>
+```
+
+On failure, a single line: `FAILED: <concrete reason>`.
+
+# Rules
+
+- NEVER edit files. Read-only flow.
+- NEVER run git. Only `gh` via Bash for comment posting and state polling.
+- Between polls, sleep ~30 seconds. Do NOT poll faster than once every 30 seconds.
+- Hard cap: 40 turns total across the whole flow. If you're approaching the cap, fail early with `FAILED: turn budget exhausted`.
+- If you post an `@kody2` comment and the state-comment does NOT update within the poll window, the child executable likely didn't run — check the GitHub Actions runs tab URL via `gh run list --limit 5 --json conclusion,status,url` to diagnose, then fail with a concrete reason.

package/dist/executables/plan/profile.json

@@ -0,0 +1,49 @@
+{
+  "name": "plan",
+  "describe": "Research an issue and produce a concrete implementation plan as a comment. Read-only — no branches, no commits.",
+
+  "inputs": [
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub issue number to plan."
+    }
+  ],
+
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": null,
+    "systemPromptAppend": null,
+    "tools": ["Read", "Grep", "Glob", "Bash"],
+    "hooks": { "PreToolUse": [], "PostToolUse": [], "Stop": [] },
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+
+  "cliTools": [],
+
+  "scripts": {
+    "preflight": [
+      { "script": "runFlow" },
+      { "script": "loadTaskState" },
+      { "script": "loadConventions" },
+      { "script": "composePrompt" }
+    ],
+    "postflight": [
+      { "script": "parseAgentResult" },
+      { "script": "postIssueComment" },
+      { "script": "writeRunSummary" },
+      { "script": "saveTaskState" }
+    ]
+  },
+
+  "output": {
+    "actionTypes": ["PLAN_COMPLETED", "PLAN_FAILED"]
+  }
+}

package/dist/executables/plan/prompts/plan.md

@@ -0,0 +1,42 @@
+You are a senior engineer producing an **implementation plan** for the GitHub issue below. You will NOT write code. You will NOT run git or gh commands. You will NOT modify files. Your only outputs are:
+
+1. Use Read / Grep / Glob / Bash (read-only) to study the codebase as much as needed.
+2. Emit a final message with the plan wrapped in the required markers (see "Required output").
+
+---
+
+# Repo
+- {{repoOwner}}/{{repoName}}, default branch: {{defaultBranch}}
+
+# Issue #{{issue.number}}: {{issue.title}}
+
+{{issue.body}}
+
+Recent comments (most recent first, truncated):
+{{issue.commentsFormatted}}
+
+{{conventionsBlock}}
+
+---
+
+# Required output
+
+Your FINAL message must be exactly this shape (no extra text before or after):
+
+```
+DONE
+COMMIT_MSG: plan: <very short title>
+PR_SUMMARY:
+<A concrete implementation plan in markdown. Include:
+ - Files to change (with paths), and the change in each.
+ - New files to create, with their purpose and rough shape.
+ - Any ambiguities that need the human to resolve first.
+ - Verification checklist (typecheck / tests / lint expectations).
+ Keep to ~60 lines or less. No filler. No marketing language.>
+```
+
+# Rules
+- Read-only. Do NOT modify any file.
+- Do NOT run git or gh commands.
+- No speculative scope — plan only what the issue asks for.
+- If the issue is ambiguous and you cannot make progress without input, output `FAILED: <what's unclear>` instead of a plan.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kody-ade/kody-engine",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "kody2 — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",