@kody-ade/kody-engine 0.2.52 → 0.2.54

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.52",
+  version: "0.2.54",
   description: "kody2 \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -738,6 +738,7 @@ import * as fs7 from "fs";
 import * as path6 from "path";
 var VALID_INPUT_TYPES = /* @__PURE__ */ new Set(["int", "string", "bool", "enum"]);
 var VALID_PERMISSION_MODES = /* @__PURE__ */ new Set(["default", "acceptEdits", "plan", "bypassPermissions"]);
+var VALID_ROLES = /* @__PURE__ */ new Set(["primitive", "orchestrator", "watch", "utility"]);
 var ProfileError = class extends Error {
   constructor(profilePath, message) {
     super(`Invalid profile at ${profilePath}:
@@ -765,9 +766,17 @@ function loadProfile(profilePath) {
   if (kind === "scheduled" && typeof r.schedule !== "string") {
     throw new ProfileError(profilePath, `kind: "scheduled" requires a "schedule" cron string`);
   }
+  if (typeof r.role !== "string" || !VALID_ROLES.has(r.role)) {
+    throw new ProfileError(
+      profilePath,
+      `"role" is required and must be one of: ${[...VALID_ROLES].join(" | ")}`
+    );
+  }
+  const role = r.role;
   const profile = {
     name: requireString(profilePath, r, "name"),
     describe: typeof r.describe === "string" ? r.describe : "",
+    role,
     kind,
     schedule: typeof r.schedule === "string" ? r.schedule : void 0,
     inputs: parseInputs(profilePath, r.inputs),
@@ -2373,9 +2382,12 @@ function getIssue(issueNumber, cwd) {
     }))
   };
 }
+function stripKody2Mentions(body) {
+  return body.replace(/(@)(kody2)/gi, "$1\u200B$2");
+}
 function postIssueComment(issueNumber, body, cwd) {
   try {
-    gh2(["issue", "comment", String(issueNumber), "--body-file", "-"], { input: body, cwd });
+    gh2(["issue", "comment", String(issueNumber), "--body-file", "-"], { input: stripKody2Mentions(body), cwd });
   } catch (err) {
     process.stderr.write(
       `[kody2] failed to post comment on #${issueNumber}: ${err instanceof Error ? err.message : String(err)}
@@ -2460,7 +2472,7 @@ function getPrLatestReviewBody(prNumber, cwd) {
 }
 function postPrReviewComment(prNumber, body, cwd) {
   try {
-    gh2(["pr", "comment", String(prNumber), "--body-file", "-"], { input: body, cwd });
+    gh2(["pr", "comment", String(prNumber), "--body-file", "-"], { input: stripKody2Mentions(body), cwd });
   } catch (err) {
     process.stderr.write(
       `[kody2] failed to post review comment on PR #${prNumber}: ${err instanceof Error ? err.message : String(err)}
@@ -2698,7 +2710,11 @@ function parseGenericFlags(argv) {
 }
 
 // src/lifecycleLabels.ts
-var KODY_LABEL_PREFIX = "kody:";
+var KODY_NAMESPACE = "kody";
+function groupOf(label) {
+  const idx = label.indexOf(":");
+  return idx === -1 ? label : label.slice(0, idx + 1);
+}
 function collectProfileLabels() {
   const byLabel = /* @__PURE__ */ new Map();
   for (const exe of listExecutables()) {
@@ -2719,7 +2735,7 @@ 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;
+  if (!label || !label.startsWith(KODY_NAMESPACE)) return null;
   return {
     label,
     color: typeof w.color === "string" ? w.color : void 0,
@@ -2766,16 +2782,17 @@ function createLabelInRepo(spec, cwd) {
 }
 function setKodyLabel(issueNumber, spec, cwd) {
   const target = spec.label;
-  if (!target.startsWith(KODY_LABEL_PREFIX)) {
+  if (!target.startsWith(KODY_NAMESPACE)) {
     process.stderr.write(
       `[kody2] setKodyLabel: refusing to set non-kody label "${target}"
 `
     );
     return;
   }
+  const targetGroup = groupOf(target);
   const present = getIssueLabels(issueNumber, cwd);
   for (const label of present) {
-    if (label !== target && label.startsWith(KODY_LABEL_PREFIX)) {
+    if (label !== target && label.startsWith(KODY_NAMESPACE) && groupOf(label) === targetGroup) {
       removeLabel(issueNumber, label, cwd);
     }
   }
@@ -2832,7 +2849,7 @@ var finishFlow = async (ctx, _profile, _agentResult, args) => {
   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)) {
+  if (label && label.startsWith(KODY_NAMESPACE)) {
     setKodyLabel(
       issueNumber,
       {
@@ -4399,9 +4416,9 @@ 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)) {
+  if (typeof label !== "string" || !label.startsWith(KODY_NAMESPACE)) {
     process.stderr.write(
-      `[kody2] setLifecycleLabel: missing or invalid "label" arg (must start with "${KODY_LABEL_PREFIX}"): ${String(label)}
+      `[kody2] setLifecycleLabel: missing or invalid "label" arg (must start with "${KODY_NAMESPACE}"): ${String(label)}
 `
     );
     return;
@@ -4434,14 +4451,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");

package/dist/executables/bug/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "bug",
+  "role": "orchestrator",
   "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": [
     {
@@ -27,6 +28,14 @@
   "cliTools": [],
   "scripts": {
     "preflight": [
+      {
+        "script": "setLifecycleLabel",
+        "with": {
+          "label": "kody-flow:bug",
+          "color": "d73a4a",
+          "description": "kody2 flow: bug / enhancement"
+        }
+      },
       {
         "script": "setLifecycleLabel",
         "with": {

package/dist/executables/chore/profile.json

@@ -0,0 +1,87 @@
+{
+  "name": "chore",
+  "role": "orchestrator",
+  "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-flow:chore",
+          "color": "c5def5",
+          "description": "kody2 flow: chore / docs / dep-bump"
+        }
+      },
+      {
+        "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,93 @@
+{
+  "name": "feature",
+  "role": "orchestrator",
+  "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-flow:feature",
+          "color": "a2eeef",
+          "description": "kody2 flow: feature / refactor"
+        }
+      },
+      {
+        "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

@@ -1,5 +1,6 @@
 {
   "name": "fix",
+  "role": "primitive",
   "describe": "Apply review feedback to an existing PR branch.",
   "inputs": [
     {

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

@@ -1,5 +1,6 @@
 {
   "name": "fix-ci",
+  "role": "primitive",
   "describe": "Fix a failing CI workflow on an existing PR.",
   "inputs": [
     {

package/dist/executables/init/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "init",
+  "role": "utility",
   "describe": "Scaffold a consumer repo with kody.config.json and the @kody2 workflow. No agent.",
   "inputs": [
     {

package/dist/executables/plan/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "plan",
+  "role": "primitive",
   "describe": "Research an issue and produce a concrete implementation plan as a comment. Read-only \u2014 no branches, no commits.",
   "inputs": [
     {

package/dist/executables/plan-verify/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "plan-verify",
+  "role": "utility",
   "describe": "Live-test executable. Loads kody-live-marker skill, /kody-live-probe command, kody-live-trace hook, and the bundled test-plugin. Asks the agent to emit confirmation tokens for each feature so Kody2 can validate plugin wiring end-to-end.",
   "inputs": [
     { "name": "issue", "flag": "--issue", "type": "int", "required": true, "describe": "GitHub issue number to verify against." }

package/dist/executables/release/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "release",
+  "role": "utility",
   "describe": "Version bump + changelog + release PR (prepare), or tag + publish + GH release (finalize). No agent.",
   "inputs": [
     {

package/dist/executables/research/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "research",
+  "role": "primitive",
   "describe": "Research an issue: understand the ask, map relevant repo context, and surface clarifying questions + gaps. Read-only — no branches, no commits, no prescribed next steps.",
   "inputs": [
     {
@@ -67,6 +68,9 @@
       },
       {
         "script": "saveTaskState"
+      },
+      {
+        "script": "advanceFlow"
       }
     ]
   },

package/dist/executables/resolve/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "resolve",
+  "role": "primitive",
   "describe": "Resolve merge conflicts between a PR branch and the default branch.",
   "inputs": [
     {

package/dist/executables/review/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "review",
+  "role": "primitive",
   "describe": "Read-only structured review of an open PR. Posts one comment, never commits.",
   "inputs": [
     {

package/dist/executables/run/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "run",
+  "role": "primitive",
   "describe": "Implement a GitHub issue end-to-end: branch, code, commit, open PR.",
   "inputs": [
     {

package/dist/executables/spec/profile.json

@@ -0,0 +1,76 @@
+{
+  "name": "spec",
+  "role": "orchestrator",
+  "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-flow:spec",
+          "color": "7057ff",
+          "description": "kody2 flow: spec / RFC / design-doc"
+        }
+      },
+      {
+        "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

@@ -1,5 +1,6 @@
 {
   "name": "sync",
+  "role": "primitive",
   "describe": "Merge the default (base) branch into a PR branch and push. No agent.",
   "inputs": [
     {

package/dist/executables/types.ts

@@ -18,7 +18,19 @@ export interface Profile {
   name: string
   describe: string
   /**
-   * Execution model. `oneshot` (default): single invocation on demand.
+   * Semantic role — what this executable IS, not when it runs.
+   *   - primitive:    single-step agent executor (flow → agent → verify → commit → PR).
+   *   - orchestrator: no-agent, drives primitives via a postflight transition table.
+   *   - watch:        scheduled observer that inspects repo state and may trigger other executables.
+   *   - utility:      no-agent, one-off administrative work (scaffolding, release, etc.).
+   *
+   * Roles enforce shape at profile-load time and let help/dispatch treat
+   * executables differently by category.
+   */
+  role: "primitive" | "orchestrator" | "watch" | "utility"
+  /**
+   * Execution model — orthogonal to `role`.
+   * `oneshot` (default): single invocation on demand.
    * `scheduled`: fires periodically via an external cron (typically GHA
    * `schedule:`). Scheduled profiles must declare a `schedule` cron string.
    */

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

@@ -1,5 +1,6 @@
 {
   "name": "ui-review",
+  "role": "primitive",
   "describe": "UI/UX review of an open PR: browses the running preview with Playwright, compares behavior to diff intent, posts one structured review comment. Read-only on the repo (no commits); writes a throwaway Playwright spec under .kody2/.",
   "kind": "oneshot",
   "inputs": [

package/dist/executables/watch-stale-prs/profile.json

@@ -1,5 +1,6 @@
 {
   "name": "watch-stale-prs",
+  "role": "watch",
   "describe": "Scheduled: list open PRs untouched for N days and report. No agent invocation.",
   "kind": "scheduled",
   "schedule": "0 8 * * MON",

package/package.json

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