@kody-ade/kody-engine 0.2.51 → 0.2.53

package/README.md

@@ -31,17 +31,42 @@ Every top-level command is its own auto-discovered executable (`run`, `fix`, `fi
 ## Commands
 
 ```
-kody2 run     --issue <N>                   # implement an issue
-kody2 plan    --issue <N>                   # produce a plan artifact for run
-kody2 fix     --pr    <N> [--feedback ...]  # apply PR review feedback
-kody2 fix-ci  --pr    <N> [--run-id <ID>]   # fix failing CI
-kody2 resolve --pr    <N>                   # merge default branch in, resolve conflicts
-kody2 sync    --pr    <N>                   # merge default branch into PR branch (no agent)
-kody2 review  --pr    <N>                   # read-only structured PR review
-kody2 ci      --issue <N>                   # CI preflight + run (issue/PR automation)
-kody2 chat    [--session <id>]              # dashboard-driven chat session
+# issue-triggered, agent writes code
+kody2 run       --issue <N>                              # implement an issue end-to-end (branch, code, PR)
+
+# issue-triggered, agent read-only (no commits)
+kody2 plan      --issue <N>                              # produce a plan artifact for run
+kody2 research  --issue <N>                              # map repo context, surface questions/gaps
+
+# PR-triggered, agent writes code
+kody2 fix       --pr    <N> [--feedback ...]             # apply PR review feedback
+kody2 fix-ci    --pr    <N> [--run-id <ID>]              # fix failing CI
+kody2 resolve   --pr    <N>                              # merge default branch in, resolve conflicts
+
+# PR-triggered, agent read-only
+kody2 review    --pr    <N>                              # structured diff review (fast, diff only)
+kody2 ui-review --pr    <N> [--preview-url <URL>]        # UI/UX review — browses preview via Playwright
+
+# no agent (deterministic)
+kody2 sync      --pr    <N>                              # merge default branch into PR branch
+kody2 release   --mode  prepare|finalize [--bump patch|minor|major] [--dry-run]
+kody2 init      [--force]                                # scaffold consumer repo
+kody2 orchestrate --issue <N> [--flow plan-build-review] # chain plan → run → review → fix
+
+# engine entrypoints
+kody2 ci        --issue <N>                              # CI preflight + auto-dispatch from GHA event
+kody2 chat      [--session <id>]                         # dashboard-driven chat session
 ```
 
+### `ui-review`
+
+`ui-review` adds UI/UX verification to the review surface. It runs the usual diff-based review AND drives the running preview deployment via the Playwright CLI — writing a throwaway spec under `.kody2/ui-review/`, running it, capturing screenshots, and folding the observed behavior into the review verdict.
+
+- Preview URL resolution: `--preview-url` flag → `$PREVIEW_URL` → `http://localhost:3000`.
+- Credentials: committed in `.kody2/qa-guide.md` (scaffolded by `kody2 init` when a UI is detected, with `CHANGE_ME` placeholders). The agent reads the guide and uses any credentials it finds.
+- Auto-discovery: routes, roles, login page, admin path, Payload CMS collections, API routes, env vars — fed to the agent so it knows *what* to browse without you spelling it out.
+- Falls back to a diff-only review when the preview URL is unreachable.
+
 `kody2 chat` reads `.kody/sessions/<id>.jsonl`, runs one agent turn, appends
 the reply, and writes `chat.message` + `chat.done` events to
 `.kody/events/<id>.jsonl` (plus optional HTTP push to a dashboard ingest URL).

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.51",
+  version: "0.2.53",
   description: "kody2 \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -593,24 +593,12 @@ function autoDispatch(opts) {
   if (!sub) {
     return asDispatch(defaultExec, targetNum);
   }
-  if (sub === "orchestrate" || sub === "orchestrator") {
-    const flow = extractFlowName(afterTag);
-    if (flow) {
-      return {
-        executable: `orchestrator-${flow}`,
-        cliArgs: { issue: targetNum, flow },
-        target: targetNum
-      };
-    }
-    return {
-      executable: "orchestrator-plan-build-review",
-      cliArgs: { issue: targetNum, flow: "plan-build-review" },
-      target: targetNum
-    };
-  }
   if (sub === "build") {
     return { executable: "run", cliArgs: { issue: targetNum }, target: targetNum };
   }
+  if (sub === "orchestrate" || sub === "orchestrator") {
+    return { executable: "bug", cliArgs: { issue: targetNum }, target: targetNum };
+  }
   return asDispatch(sub, targetNum);
 }
 function asDispatch(executable, target) {
@@ -626,10 +614,6 @@ function extractSubcommand(afterTag) {
   if (!match) return null;
   return match[1];
 }
-function extractFlowName(afterTag) {
-  const match = afterTag.match(/--flow[=\s]+([a-z][a-z0-9-]{0,60})/);
-  return match ? match[1] : null;
-}
 function extractFeedback(afterTag) {
   const cleaned = afterTag.replace(/^(fix|please|kindly)(?:[\s:,.-]+|$)/i, "").trim();
   return cleaned.length > 0 ? cleaned : void 0;
@@ -1209,7 +1193,7 @@ var advanceFlow = async (ctx, profile) => {
       );
     }
   }
-  const body = "@kody2 orchestrate";
+  const body = `@kody2 ${flow.name}`;
   try {
     execFileSync3("gh", ["issue", "comment", String(flow.issueNumber), "--body", body], {
       timeout: API_TIMEOUT_MS2,
@@ -2651,6 +2635,188 @@ function computeFailureReason(ctx) {
 
 // src/scripts/finishFlow.ts
 import { execFileSync as execFileSync9 } from "child_process";
+
+// src/registry.ts
+import * as fs14 from "fs";
+import * as path13 from "path";
+function getExecutablesRoot() {
+  const here = path13.dirname(new URL(import.meta.url).pathname);
+  const candidates = [
+    path13.join(here, "executables"),
+    // dev: src/
+    path13.join(here, "..", "executables"),
+    // built: dist/bin → dist/executables
+    path13.join(here, "..", "src", "executables")
+    // fallback
+  ];
+  for (const c of candidates) {
+    if (fs14.existsSync(c) && fs14.statSync(c).isDirectory()) return c;
+  }
+  return candidates[0];
+}
+function listExecutables(root = getExecutablesRoot()) {
+  if (!fs14.existsSync(root)) return [];
+  const entries = fs14.readdirSync(root, { withFileTypes: true });
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const profilePath = path13.join(root, ent.name, "profile.json");
+    if (fs14.existsSync(profilePath) && fs14.statSync(profilePath).isFile()) {
+      out.push({ name: ent.name, profilePath });
+    }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+function hasExecutable(name, root = getExecutablesRoot()) {
+  if (!isSafeName(name)) return false;
+  const profilePath = path13.join(root, name, "profile.json");
+  return fs14.existsSync(profilePath) && fs14.statSync(profilePath).isFile();
+}
+function isSafeName(name) {
+  return /^[a-z][a-z0-9-]*$/.test(name) && !name.includes("..");
+}
+function parseGenericFlags(argv) {
+  const args = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    const value = next !== void 0 && !next.startsWith("--") ? (i++, next) : true;
+    args[key] = value;
+    if (key.includes("-")) {
+      const camel = key.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+      if (camel !== key && args[camel] === void 0) args[camel] = value;
+    }
+  }
+  if (positional.length > 0) args._ = positional;
+  return args;
+}
+
+// src/lifecycleLabels.ts
+var KODY_LABEL_PREFIX = "kody:";
+function collectProfileLabels() {
+  const byLabel = /* @__PURE__ */ new Map();
+  for (const exe of listExecutables()) {
+    let profile;
+    try {
+      profile = loadProfile(exe.profilePath);
+    } catch {
+      continue;
+    }
+    for (const entry of [...profile.scripts.preflight, ...profile.scripts.postflight]) {
+      const spec = extractLabelSpec(entry);
+      if (spec) byLabel.set(spec.label, spec);
+    }
+  }
+  return [...byLabel.values()];
+}
+function extractLabelSpec(entry) {
+  const w = entry.with;
+  if (!w) return null;
+  const label = typeof w.label === "string" ? w.label : null;
+  if (!label || !label.startsWith(KODY_LABEL_PREFIX)) return null;
+  return {
+    label,
+    color: typeof w.color === "string" ? w.color : void 0,
+    description: typeof w.description === "string" ? w.description : void 0
+  };
+}
+function ensureLabels(cwd) {
+  const result = { created: [], failed: [] };
+  for (const spec of collectProfileLabels()) {
+    try {
+      createLabelInRepo(spec, cwd);
+      result.created.push(spec.label);
+    } catch (err) {
+      result.failed.push({ label: spec.label, reason: errMsg(err) });
+    }
+  }
+  return result;
+}
+function getIssueLabels(issueNumber, cwd) {
+  try {
+    const output = gh2(
+      ["issue", "view", String(issueNumber), "--json", "labels", "--jq", ".labels[].name"],
+      { cwd }
+    );
+    return output.split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+function addLabel(issueNumber, label, cwd) {
+  gh2(["issue", "edit", String(issueNumber), "--add-label", label], { cwd });
+}
+function removeLabel(issueNumber, label, cwd) {
+  try {
+    gh2(["issue", "edit", String(issueNumber), "--remove-label", label], { cwd });
+  } catch {
+  }
+}
+function createLabelInRepo(spec, cwd) {
+  const args = ["label", "create", spec.label, "--force"];
+  if (spec.color) args.push("--color", spec.color);
+  if (spec.description) args.push("--description", spec.description);
+  gh2(args, { cwd });
+}
+function setKodyLabel(issueNumber, spec, cwd) {
+  const target = spec.label;
+  if (!target.startsWith(KODY_LABEL_PREFIX)) {
+    process.stderr.write(
+      `[kody2] setKodyLabel: refusing to set non-kody label "${target}"
+`
+    );
+    return;
+  }
+  const present = getIssueLabels(issueNumber, cwd);
+  for (const label of present) {
+    if (label !== target && label.startsWith(KODY_LABEL_PREFIX)) {
+      removeLabel(issueNumber, label, cwd);
+    }
+  }
+  try {
+    addLabel(issueNumber, target, cwd);
+  } catch (err) {
+    if (looksLikeMissingLabel(err)) {
+      try {
+        createLabelInRepo(spec, cwd);
+        addLabel(issueNumber, target, cwd);
+        return;
+      } catch (retryErr) {
+        process.stderr.write(
+          `[kody2] setKodyLabel: create+retry failed for ${target} on #${issueNumber}: ${errMsg(retryErr)}
+`
+        );
+        return;
+      }
+    }
+    process.stderr.write(
+      `[kody2] setKodyLabel: failed to add ${target} on #${issueNumber}: ${errMsg(err)}
+`
+    );
+  }
+}
+function looksLikeMissingLabel(err) {
+  const msg = errMsg(err).toLowerCase();
+  return msg.includes("not found") || msg.includes("could not add label") || msg.includes("could not resolve to a label");
+}
+function errMsg(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "object" && err !== null) {
+    const e = err;
+    const stderr = e.stderr?.toString().trim();
+    if (stderr) return stderr;
+    if (e.message) return e.message;
+  }
+  return String(err);
+}
+
+// src/scripts/finishFlow.ts
 var API_TIMEOUT_MS5 = 3e4;
 var STATUS_ICON = {
   "review-passed": "\u2705",
@@ -2665,6 +2831,18 @@ var finishFlow = async (ctx, _profile, _agentResult, args) => {
   const flowName = state?.flow?.name ?? "(unknown flow)";
   if (state) state.flow = void 0;
   if (!issueNumber) return;
+  const label = typeof args?.label === "string" ? args.label : void 0;
+  if (label && label.startsWith(KODY_LABEL_PREFIX)) {
+    setKodyLabel(
+      issueNumber,
+      {
+        label,
+        color: typeof args?.color === "string" ? args.color : void 0,
+        description: typeof args?.description === "string" ? args.description : void 0
+      },
+      ctx.cwd
+    );
+  }
   const icon = STATUS_ICON[reason] ?? "\u2139\uFE0F";
   const prSuffix = state?.core.prUrl ? `
 
@@ -2788,7 +2966,7 @@ function ensureFeatureBranch(issueNumber, title, defaultBranch, cwd) {
 
 // src/gha.ts
 import { execFileSync as execFileSync11 } from "child_process";
-import * as fs14 from "fs";
+import * as fs15 from "fs";
 function getRunUrl() {
   const server = process.env.GITHUB_SERVER_URL;
   const repo = process.env.GITHUB_REPOSITORY;
@@ -2799,10 +2977,10 @@ function getRunUrl() {
 function reactToTriggerComment(cwd) {
   if (process.env.GITHUB_EVENT_NAME !== "issue_comment") return;
   const eventPath = process.env.GITHUB_EVENT_PATH;
-  if (!eventPath || !fs14.existsSync(eventPath)) return;
+  if (!eventPath || !fs15.existsSync(eventPath)) return;
   let event = null;
   try {
-    event = JSON.parse(fs14.readFileSync(eventPath, "utf-8"));
+    event = JSON.parse(fs15.readFileSync(eventPath, "utf-8"));
   } catch {
     return;
   }
@@ -3045,67 +3223,6 @@ import { execFileSync as execFileSync13 } from "child_process";
 import * as fs17 from "fs";
 import * as path15 from "path";
 
-// src/registry.ts
-import * as fs15 from "fs";
-import * as path13 from "path";
-function getExecutablesRoot() {
-  const here = path13.dirname(new URL(import.meta.url).pathname);
-  const candidates = [
-    path13.join(here, "executables"),
-    // dev: src/
-    path13.join(here, "..", "executables"),
-    // built: dist/bin → dist/executables
-    path13.join(here, "..", "src", "executables")
-    // fallback
-  ];
-  for (const c of candidates) {
-    if (fs15.existsSync(c) && fs15.statSync(c).isDirectory()) return c;
-  }
-  return candidates[0];
-}
-function listExecutables(root = getExecutablesRoot()) {
-  if (!fs15.existsSync(root)) return [];
-  const entries = fs15.readdirSync(root, { withFileTypes: true });
-  const out = [];
-  for (const ent of entries) {
-    if (!ent.isDirectory()) continue;
-    const profilePath = path13.join(root, ent.name, "profile.json");
-    if (fs15.existsSync(profilePath) && fs15.statSync(profilePath).isFile()) {
-      out.push({ name: ent.name, profilePath });
-    }
-  }
-  return out.sort((a, b) => a.name.localeCompare(b.name));
-}
-function hasExecutable(name, root = getExecutablesRoot()) {
-  if (!isSafeName(name)) return false;
-  const profilePath = path13.join(root, name, "profile.json");
-  return fs15.existsSync(profilePath) && fs15.statSync(profilePath).isFile();
-}
-function isSafeName(name) {
-  return /^[a-z][a-z0-9-]*$/.test(name) && !name.includes("..");
-}
-function parseGenericFlags(argv) {
-  const args = {};
-  const positional = [];
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (!arg.startsWith("--")) {
-      positional.push(arg);
-      continue;
-    }
-    const key = arg.slice(2);
-    const next = argv[i + 1];
-    const value = next !== void 0 && !next.startsWith("--") ? (i++, next) : true;
-    args[key] = value;
-    if (key.includes("-")) {
-      const camel = key.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
-      if (camel !== key && args[camel] === void 0) args[camel] = value;
-    }
-  }
-  if (positional.length > 0) args._ = positional;
-  return args;
-}
-
 // src/scripts/loadQaGuide.ts
 import * as fs16 from "fs";
 import * as path14 from "path";
@@ -3297,7 +3414,13 @@ function performInit(cwd, force) {
     fs17.writeFileSync(target, renderScheduledWorkflow(exe.name, profile.schedule));
     wrote.push(`.github/workflows/kody2-${exe.name}.yml`);
   }
-  return { wrote, skipped };
+  let labels;
+  try {
+    labels = ensureLabels(cwd);
+  } catch {
+    labels = void 0;
+  }
+  return { wrote, skipped, labels };
 }
 function renderScheduledWorkflow(name, cron) {
   return `# Scheduled kody2 executable: ${name}
@@ -3334,12 +3457,24 @@ jobs:
 var initFlow = async (ctx) => {
   const force = ctx.args.force === true;
   const cwd = ctx.cwd;
-  const { wrote, skipped } = performInit(cwd, force);
+  const { wrote, skipped, labels } = performInit(cwd, force);
   process.stdout.write("\u2192 kody2 init\n");
   for (const f of wrote) process.stdout.write(`  wrote    ${f}
 `);
   for (const f of skipped) process.stdout.write(`  skipped  ${f} (already exists; pass --force to overwrite)
 `);
+  if (labels) {
+    if (labels.created.length > 0) {
+      process.stdout.write(`  labels   ensured ${labels.created.length} lifecycle label(s)
+`);
+    }
+    if (labels.failed.length > 0) {
+      process.stdout.write(
+        `  labels   ${labels.failed.length} failed (gh auth missing? will self-heal on first run)
+`
+      );
+    }
+  }
   process.stdout.write(
     wrote.length > 0 ? `
 Done. Edit kody.config.json to pick your model, then push the workflow file.
@@ -4261,6 +4396,36 @@ function synthesizeAction(ctx) {
   };
 }
 
+// src/scripts/setLifecycleLabel.ts
+var setLifecycleLabel = async (ctx, _profile, args) => {
+  const label = args?.label;
+  if (typeof label !== "string" || !label.startsWith(KODY_LABEL_PREFIX)) {
+    process.stderr.write(
+      `[kody2] setLifecycleLabel: missing or invalid "label" arg (must start with "${KODY_LABEL_PREFIX}"): ${String(label)}
+`
+    );
+    return;
+  }
+  const issueNumber = resolveTargetNumber(ctx.args);
+  if (issueNumber === void 0) return;
+  setKodyLabel(
+    issueNumber,
+    {
+      label,
+      color: typeof args?.color === "string" ? args.color : void 0,
+      description: typeof args?.description === "string" ? args.description : void 0
+    },
+    ctx.cwd
+  );
+};
+function resolveTargetNumber(args) {
+  const issue = args.issue;
+  if (typeof issue === "number" && Number.isFinite(issue)) return issue;
+  const pr = args.pr;
+  if (typeof pr === "number" && Number.isFinite(pr)) return pr;
+  return void 0;
+}
+
 // src/scripts/skipAgent.ts
 var skipAgent = async (ctx) => {
   ctx.skipAgent = true;
@@ -4269,14 +4434,14 @@ var skipAgent = async (ctx) => {
 // src/scripts/startFlow.ts
 import { execFileSync as execFileSync16 } from "child_process";
 var API_TIMEOUT_MS6 = 3e4;
-var startFlow = async (ctx, _profile, _agentResult, args) => {
+var startFlow = async (ctx, profile, _agentResult, args) => {
   const entry = args?.entry;
   if (!entry) {
     process.stderr.write("[kody2 startFlow] missing `with.entry` \u2014 skipping\n");
     return;
   }
   const target = args?.target ?? "issue";
-  const flowName = ctx.args.flow ?? "default";
+  const flowName = profile.name;
   const issueNumber = ctx.args.issue;
   if (!issueNumber) {
     process.stderr.write("[kody2 startFlow] no --issue arg \u2014 skipping\n");
@@ -4607,6 +4772,7 @@ var preflightScripts = {
   discoverQaContext,
   resolvePreviewUrl,
   composePrompt,
+  setLifecycleLabel,
   skipAgent
 };
 var postflightScripts = {

package/dist/executables/{orchestrator-plan-build-review → bug}/profile.json

@@ -1,6 +1,6 @@
 {
-  "name": "orchestrator-plan-build-review",
-  "describe": "Deterministic orchestrator for the plan → build → review (→ fix on concerns/fail) flow. No agent — the postflight entries ARE the transition table, evaluated top-to-bottom via runWhen.",
+  "name": "bug",
+  "describe": "Sub-orchestrator for bug / enhancement issues — plan → run → review (→ fix on concerns/fail). No agent — the postflight entries ARE the transition table, evaluated top-to-bottom via runWhen.",
   "inputs": [
     {
       "name": "issue",
@@ -8,13 +8,6 @@
       "type": "int",
       "required": true,
       "describe": "GitHub issue number to drive the flow on."
-    },
-    {
-      "name": "flow",
-      "flag": "--flow",
-      "type": "string",
-      "required": false,
-      "describe": "Flow name (cosmetic — recorded in state.flow.name)."
     }
   ],
   "claudeCode": {
@@ -34,6 +27,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:orchestrating",
+          "color": "1d76db",
+          "description": "kody2: orchestrating a multi-stage flow"
+        }
+      },
       { "script": "loadIssueContext" },
       { "script": "loadTaskState" },
       { "script": "skipAgent" }
@@ -48,19 +49,23 @@
       { "script": "dispatch", "with": { "next": "review", "target": "pr" },
         "runWhen": { "data.taskState.core.lastOutcome.type": "RUN_COMPLETED" } },
 
-      { "script": "finishFlow", "with": { "reason": "review-passed" },
+      { "script": "finishFlow",
+        "with": { "reason": "review-passed", "label": "kody:done", "color": "0e8a16", "description": "kody2: PR ready for human review/merge" },
         "runWhen": { "data.taskState.core.lastOutcome.type": "REVIEW_PASS" } },
 
       { "script": "dispatch", "with": { "next": "fix", "target": "pr" },
         "runWhen": { "data.taskState.core.lastOutcome.type": ["REVIEW_CONCERNS", "REVIEW_FAIL"] } },
 
-      { "script": "finishFlow", "with": { "reason": "review-failed" },
+      { "script": "finishFlow",
+        "with": { "reason": "review-failed", "label": "kody:failed", "color": "e11d21", "description": "kody2: flow failed" },
         "runWhen": { "data.taskState.core.lastOutcome.type": "REVIEW_FAILED" } },
 
-      { "script": "finishFlow", "with": { "reason": "fix-applied" },
+      { "script": "finishFlow",
+        "with": { "reason": "fix-applied", "label": "kody:done", "color": "0e8a16", "description": "kody2: PR ready for human review/merge" },
         "runWhen": { "data.taskState.core.lastOutcome.type": "FIX_COMPLETED" } },
 
-      { "script": "finishFlow", "with": { "reason": "aborted" },
+      { "script": "finishFlow",
+        "with": { "reason": "aborted", "label": "kody:failed", "color": "e11d21", "description": "kody2: flow failed" },
         "runWhen": { "data.taskState.core.lastOutcome.type": ["PLAN_FAILED", "RUN_FAILED", "FIX_FAILED", "AGENT_NOT_RUN"] } },
 
       { "script": "persistFlowState" }

package/dist/executables/chore/profile.json

@@ -0,0 +1,78 @@
+{
+  "name": "chore",
+  "describe": "Sub-orchestrator for chore / docs / dep-bump issues — run → review (→ fix on concerns/fail). Skips planning entirely. No agent.",
+  "inputs": [
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub issue number to drive the flow on."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:orchestrating",
+          "color": "1d76db",
+          "description": "kody2: orchestrating a multi-stage flow"
+        }
+      },
+      { "script": "loadIssueContext" },
+      { "script": "loadTaskState" },
+      { "script": "skipAgent" }
+    ],
+    "postflight": [
+      { "script": "startFlow", "with": { "entry": "run", "target": "issue" },
+        "runWhen": { "data.taskState.core.lastOutcome": null } },
+
+      { "script": "dispatch", "with": { "next": "review", "target": "pr" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "RUN_COMPLETED" } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "review-passed", "label": "kody:done", "color": "0e8a16", "description": "kody2: PR ready for human review/merge" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "REVIEW_PASS" } },
+
+      { "script": "dispatch", "with": { "next": "fix", "target": "pr" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": ["REVIEW_CONCERNS", "REVIEW_FAIL"] } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "review-failed", "label": "kody:failed", "color": "e11d21", "description": "kody2: flow failed" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "REVIEW_FAILED" } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "fix-applied", "label": "kody:done", "color": "0e8a16", "description": "kody2: PR ready for human review/merge" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "FIX_COMPLETED" } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "aborted", "label": "kody:failed", "color": "e11d21", "description": "kody2: flow failed" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": ["RUN_FAILED", "FIX_FAILED", "AGENT_NOT_RUN"] } },
+
+      { "script": "persistFlowState" }
+    ]
+  },
+  "output": {
+    "actionTypes": [
+      "FLOW_STARTED",
+      "FLOW_COMPLETED",
+      "FLOW_ABORTED"
+    ]
+  }
+}

package/dist/executables/chore/prompt.md

@@ -0,0 +1,5 @@
+<!--
+Placeholder. The chore sub-orchestrator runs with maxTurns: 0 and a
+`skipAgent` preflight, so this prompt is never sent to Claude. The
+transition logic lives entirely in profile.json's postflight entries.
+-->

package/dist/executables/feature/profile.json

@@ -0,0 +1,84 @@
+{
+  "name": "feature",
+  "describe": "Sub-orchestrator for feature / refactor issues — research → plan → run → review (→ fix on concerns/fail). No agent — the postflight entries ARE the transition table, evaluated top-to-bottom via runWhen.",
+  "inputs": [
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub issue number to drive the flow on."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:orchestrating",
+          "color": "1d76db",
+          "description": "kody2: orchestrating a multi-stage flow"
+        }
+      },
+      { "script": "loadIssueContext" },
+      { "script": "loadTaskState" },
+      { "script": "skipAgent" }
+    ],
+    "postflight": [
+      { "script": "startFlow", "with": { "entry": "research", "target": "issue" },
+        "runWhen": { "data.taskState.core.lastOutcome": null } },
+
+      { "script": "dispatch", "with": { "next": "plan", "target": "issue" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "RESEARCH_COMPLETED" } },
+
+      { "script": "dispatch", "with": { "next": "run", "target": "issue" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "PLAN_COMPLETED" } },
+
+      { "script": "dispatch", "with": { "next": "review", "target": "pr" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "RUN_COMPLETED" } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "review-passed", "label": "kody:done", "color": "0e8a16", "description": "kody2: PR ready for human review/merge" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "REVIEW_PASS" } },
+
+      { "script": "dispatch", "with": { "next": "fix", "target": "pr" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": ["REVIEW_CONCERNS", "REVIEW_FAIL"] } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "review-failed", "label": "kody:failed", "color": "e11d21", "description": "kody2: flow failed" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "REVIEW_FAILED" } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "fix-applied", "label": "kody:done", "color": "0e8a16", "description": "kody2: PR ready for human review/merge" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "FIX_COMPLETED" } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "aborted", "label": "kody:failed", "color": "e11d21", "description": "kody2: flow failed" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": ["RESEARCH_FAILED", "PLAN_FAILED", "RUN_FAILED", "FIX_FAILED", "AGENT_NOT_RUN"] } },
+
+      { "script": "persistFlowState" }
+    ]
+  },
+  "output": {
+    "actionTypes": [
+      "FLOW_STARTED",
+      "FLOW_COMPLETED",
+      "FLOW_ABORTED"
+    ]
+  }
+}

package/dist/executables/feature/prompt.md

@@ -0,0 +1,5 @@
+<!--
+Placeholder. The feature sub-orchestrator runs with maxTurns: 0 and a
+`skipAgent` preflight, so this prompt is never sent to Claude. The
+transition logic lives entirely in profile.json's postflight entries.
+-->

package/dist/executables/fix/profile.json

@@ -40,6 +40,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:fixing",
+          "color": "e99695",
+          "description": "kody2: applying review feedback"
+        }
+      },
       {
         "script": "fixFlow"
       },

package/dist/executables/fix-ci/profile.json

@@ -40,6 +40,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:fixing",
+          "color": "e99695",
+          "description": "kody2: applying review feedback"
+        }
+      },
       {
         "script": "fixCiFlow"
       },

package/dist/executables/plan/profile.json

@@ -31,6 +31,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:planning",
+          "color": "5319e7",
+          "description": "kody2: producing an implementation plan"
+        }
+      },
       {
         "script": "loadIssueContext"
       },

package/dist/executables/research/profile.json

@@ -31,6 +31,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:researching",
+          "color": "1d76db",
+          "description": "kody2: researching the issue"
+        }
+      },
       {
         "script": "loadIssueContext"
       },

package/dist/executables/resolve/profile.json

@@ -33,6 +33,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:resolving",
+          "color": "b60205",
+          "description": "kody2: resolving merge conflicts"
+        }
+      },
       {
         "script": "resolveFlow"
       },

package/dist/executables/review/profile.json

@@ -31,6 +31,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:reviewing",
+          "color": "d93f0b",
+          "description": "kody2: reviewing a PR"
+        }
+      },
       {
         "script": "reviewFlow"
       },

package/dist/executables/run/profile.json

@@ -33,6 +33,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:running",
+          "color": "fbca04",
+          "description": "kody2: implementing the change"
+        }
+      },
       {
         "script": "runFlow"
       },

package/dist/executables/spec/profile.json

@@ -0,0 +1,67 @@
+{
+  "name": "spec",
+  "describe": "Sub-orchestrator for spec / RFC / design-doc issues — research → plan (stop). Terminates at the plan artifact; no run, no PR. No agent.",
+  "inputs": [
+    {
+      "name": "issue",
+      "flag": "--issue",
+      "type": "int",
+      "required": true,
+      "describe": "GitHub issue number to drive the flow on."
+    }
+  ],
+  "claudeCode": {
+    "model": "inherit",
+    "permissionMode": "default",
+    "maxTurns": 0,
+    "maxThinkingTokens": null,
+    "systemPromptAppend": null,
+    "tools": [],
+    "hooks": [],
+    "skills": [],
+    "commands": [],
+    "subagents": [],
+    "plugins": [],
+    "mcpServers": []
+  },
+  "cliTools": [],
+  "scripts": {
+    "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:orchestrating",
+          "color": "1d76db",
+          "description": "kody2: orchestrating a multi-stage flow"
+        }
+      },
+      { "script": "loadIssueContext" },
+      { "script": "loadTaskState" },
+      { "script": "skipAgent" }
+    ],
+    "postflight": [
+      { "script": "startFlow", "with": { "entry": "research", "target": "issue" },
+        "runWhen": { "data.taskState.core.lastOutcome": null } },
+
+      { "script": "dispatch", "with": { "next": "plan", "target": "issue" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "RESEARCH_COMPLETED" } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "spec-ready", "label": "kody:done", "color": "0e8a16", "description": "kody2: spec/plan artifact ready" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": "PLAN_COMPLETED" } },
+
+      { "script": "finishFlow",
+        "with": { "reason": "aborted", "label": "kody:failed", "color": "e11d21", "description": "kody2: flow failed" },
+        "runWhen": { "data.taskState.core.lastOutcome.type": ["RESEARCH_FAILED", "PLAN_FAILED", "AGENT_NOT_RUN"] } },
+
+      { "script": "persistFlowState" }
+    ]
+  },
+  "output": {
+    "actionTypes": [
+      "FLOW_STARTED",
+      "FLOW_COMPLETED",
+      "FLOW_ABORTED"
+    ]
+  }
+}

package/dist/executables/spec/prompt.md

@@ -0,0 +1,5 @@
+<!--
+Placeholder. The spec sub-orchestrator runs with maxTurns: 0 and a
+`skipAgent` preflight, so this prompt is never sent to Claude. The
+transition logic lives entirely in profile.json's postflight entries.
+-->

package/dist/executables/sync/profile.json

@@ -26,6 +26,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody:syncing",
+          "color": "c5def5",
+          "description": "kody2: syncing PR with base"
+        }
+      },
       {
         "script": "syncFlow"
       }

package/dist/executables/ui-review/profile.json

@@ -59,6 +59,7 @@
   "outputArtifacts": [],
   "scripts": {
     "preflight": [
+      { "script": "setLifecycleLabel", "with": { "label": "kody:reviewing", "color": "d93f0b", "description": "kody2: reviewing a PR" } },
       { "script": "reviewFlow" },
       { "script": "loadTaskState" },
       { "script": "loadConventions" },

package/package.json

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