@kody-ade/kody-engine 0.2.8 → 0.2.10

package/dist/bin/kody2.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.2.8",
+  version: "0.2.10",
   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,6 +1963,27 @@ var loadCoverageRules = async (ctx) => {
   ctx.data.coverageRules = ctx.config.testRequirements ?? [];
 };
 
+// src/scripts/loadIssueContext.ts
+var DEFAULT_COMMENT_LIMIT = 12;
+var DEFAULT_COMMENT_MAX_BYTES = 4e3;
+var loadIssueContext = async (ctx) => {
+  const issueNumber = ctx.args.issue;
+  if (typeof issueNumber !== "number" || issueNumber <= 0) {
+    throw new Error("loadIssueContext: ctx.args.issue (positive integer) is required");
+  }
+  const issue = getIssue(issueNumber, ctx.cwd);
+  const cfgCtx = ctx.config.issueContext ?? {};
+  const limit = cfgCtx.commentLimit ?? DEFAULT_COMMENT_LIMIT;
+  const maxBytes = cfgCtx.commentMaxBytes ?? DEFAULT_COMMENT_MAX_BYTES;
+  const sorted = [...issue.comments].sort((a, b) => a.createdAt < b.createdAt ? 1 : -1);
+  const kept = sorted.slice(0, limit);
+  const commentsFormatted = kept.length === 0 ? "(no comments yet)" : kept.map((c) => `- **${c.author}** (${c.createdAt}):
+  ${truncate2(c.body, maxBytes).replace(/\n/g, "\n  ")}`).join("\n\n");
+  ctx.data.issue = { ...issue, commentsFormatted };
+  ctx.data.commentTargetType = "issue";
+  ctx.data.commentTargetNumber = issueNumber;
+};
+
 // src/state.ts
 import { execFileSync as execFileSync10 } from "child_process";
 var STATE_BEGIN = "<!-- kody2:state:v1:begin -->";
@@ -2965,6 +2987,7 @@ var preflightScripts = {
   releaseFlow,
   watchStalePrsFlow,
   loadTaskState,
+  loadIssueContext,
   loadConventions,
   loadCoverageRules,
   composePrompt
@@ -3223,11 +3246,13 @@ 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;
@@ -3241,30 +3266,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 };
+    }
+    if (/\bresolve\b/.test(afterTag)) {
+      return { executable: "build", cliArgs: { mode: "resolve", pr: targetNum }, target: targetNum };
     }
-    return { mode: "run", target: issueNum };
+    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;
@@ -3463,7 +3518,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"));
@@ -3475,14 +3536,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();
@@ -3519,17 +3579,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/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": "loadIssueContext" },
+      { "script": "loadTaskState" },
+      { "script": "composePrompt" }
+    ],
+    "postflight": [
+      { "script": "parseAgentResult" },
+      { "script": "postIssueComment" },
+      { "script": "writeRunSummary" },
+      { "script": "saveTaskState" }
+    ]
+  },
+
+  "output": {
+    "actionTypes": ["ORCHESTRATION_COMPLETED", "ORCHESTRATION_FAILED"]
+  }
+}

package/dist/executables/orchestrator/prompt.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/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": "loadIssueContext" },
+      { "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/prompt.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/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.8",
+  "version": "0.2.10",
   "description": "kody2 — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",