@kody-ade/kody-engine 0.3.0 → 0.3.1

package/dist/bin/kody.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.3.0",
+  version: "0.3.1",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",
@@ -366,7 +366,14 @@ async function runAgent(opts) {
       env
     };
     if (opts.mcpServers && opts.mcpServers.length > 0) {
-      queryOptions.mcpServers = opts.mcpServers;
+      queryOptions.mcpServers = Object.fromEntries(
+        opts.mcpServers.map((s) => {
+          const cfg = { command: s.command };
+          if (s.args) cfg.args = s.args;
+          if (s.env) cfg.env = s.env;
+          return [s.name, cfg];
+        })
+      );
     }
     if (opts.pluginPaths && opts.pluginPaths.length > 0) {
       queryOptions.plugins = opts.pluginPaths.map((p) => ({ type: "local", path: p }));
@@ -1428,6 +1435,7 @@ function parseAgentResult(finalText) {
       prSummary: "",
       feedbackActions: "",
       planDeviations: "",
+      priorArt: "",
       failureReason: "agent produced no final message"
     };
   const failedMatch = text.match(/(?:^|\n)\s*FAILED\s*:\s*(.+?)\s*$/s);
@@ -1438,6 +1446,7 @@ function parseAgentResult(finalText) {
       prSummary: "",
       feedbackActions: "",
       planDeviations: "",
+      priorArt: "",
       failureReason: failedMatch[1].trim()
     };
   }
@@ -1450,6 +1459,7 @@ function parseAgentResult(finalText) {
       prSummary: "",
       feedbackActions: "",
       planDeviations: "",
+      priorArt: "",
       failureReason: "no DONE or FAILED marker in agent output"
     };
   }
@@ -1458,24 +1468,27 @@ function parseAgentResult(finalText) {
   const feedbackActions = extractBlock(
     text,
     /(?:^|\n)[ \t]*FEEDBACK_ACTIONS\s*:[ \t]*\n/i,
-    /(?:^|\n)[ \t]*(?:PLAN_DEVIATIONS|COMMIT_MSG|PR_SUMMARY)\s*:/i
+    /(?:^|\n)[ \t]*(?:PLAN_DEVIATIONS|COMMIT_MSG|PR_SUMMARY|PRIOR_ART)\s*:/i
   );
   let planDeviations = extractBlock(
     text,
     /(?:^|\n)[ \t]*PLAN_DEVIATIONS\s*:[ \t]*\n/i,
-    /(?:^|\n)[ \t]*(?:COMMIT_MSG|PR_SUMMARY|FEEDBACK_ACTIONS)\s*:/i
+    /(?:^|\n)[ \t]*(?:COMMIT_MSG|PR_SUMMARY|FEEDBACK_ACTIONS|PRIOR_ART)\s*:/i
   );
   if (!planDeviations) {
     const inline = text.match(/(?:^|\n)[ \t]*PLAN_DEVIATIONS\s*:[ \t]*(.+?)[ \t]*(?:\n|$)/i);
     if (inline) planDeviations = inline[1].trim();
   }
+  let priorArt = "";
+  const priorArtInline = text.match(/(?:^|\n)[ \t]*PRIOR_ART\s*:[ \t]*(.+?)[ \t]*(?:\n|$)/i);
+  if (priorArtInline) priorArt = priorArtInline[1].trim();
   const summaryStart = text.search(/(^|\n)[ \t]*PR_SUMMARY\s*:[ \t]*\n/i);
   let prSummary = "";
   if (summaryStart !== -1) {
     const afterMarker = text.slice(summaryStart).replace(/^[\s\S]*?PR_SUMMARY\s*:[ \t]*\n/i, "");
     prSummary = afterMarker.replace(/\n\s*```\s*$/g, "").replace(/```\s*$/g, "").trim();
   }
-  return { done: true, commitMessage, prSummary, feedbackActions, planDeviations, failureReason: "" };
+  return { done: true, commitMessage, prSummary, feedbackActions, planDeviations, priorArt, failureReason: "" };
 }
 function extractBlock(text, startMarker, endMarker) {
   const startIdx = text.search(startMarker);
@@ -3600,6 +3613,97 @@ var loadIssueContext = async (ctx) => {
   ctx.data.commentTargetNumber = issueNumber;
 };
 
+// src/scripts/loadPriorArt.ts
+var PER_PR_DIFF_MAX_BYTES = 8e3;
+var TOTAL_MAX_BYTES = 3e4;
+var TRUNCATED_SUFFIX = "\n\n\u2026 (truncated)";
+var loadPriorArt = async (ctx, _profile, args) => {
+  const artifactName = typeof args?.artifactName === "string" ? args.artifactName : "priorArt";
+  const state = ctx.data.taskState;
+  const artifact = state?.artifacts?.[artifactName];
+  const prNumbers = parsePrNumbers(artifact?.content);
+  if (prNumbers.length === 0) {
+    ctx.data.priorArt = "";
+    return;
+  }
+  const blocks = [];
+  for (const n of prNumbers) {
+    const block = fetchPrBlock(n, ctx.cwd);
+    if (block) blocks.push(block);
+  }
+  const joined = blocks.join("\n\n---\n\n");
+  ctx.data.priorArt = joined.length > TOTAL_MAX_BYTES ? joined.slice(0, TOTAL_MAX_BYTES) + TRUNCATED_SUFFIX : joined;
+};
+function parsePrNumbers(raw) {
+  if (!raw) return [];
+  const trimmed = raw.trim();
+  if (!trimmed) return [];
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((n) => typeof n === "number" && Number.isInteger(n) && n > 0);
+  } catch {
+    return [];
+  }
+}
+function fetchPrBlock(prNumber, cwd) {
+  try {
+    const metaRaw = gh2(["pr", "view", String(prNumber), "--json", "title,state,url,mergedAt,closedAt"], { cwd });
+    const meta = JSON.parse(metaRaw);
+    const diff = truncate3(safeGh(["pr", "diff", String(prNumber)], cwd), PER_PR_DIFF_MAX_BYTES);
+    const commentsRaw = safeGh(["pr", "view", String(prNumber), "--json", "comments,reviews"], cwd);
+    const commentsBlock = formatReviewComments(commentsRaw);
+    const lines = [
+      `## Prior art: PR #${prNumber} \u2014 ${meta.title ?? "(no title)"} [${meta.state ?? "unknown"}]`,
+      meta.url ? meta.url : "",
+      "",
+      "### Diff",
+      "```diff",
+      diff || "(empty)",
+      "```"
+    ];
+    if (commentsBlock) {
+      lines.push("");
+      lines.push("### Review comments");
+      lines.push(commentsBlock);
+    }
+    return lines.filter((l) => l !== "").join("\n");
+  } catch (err) {
+    return `## Prior art: PR #${prNumber}
+_Could not fetch \u2014 ${err instanceof Error ? err.message : String(err)}_`;
+  }
+}
+function safeGh(args, cwd) {
+  try {
+    return gh2(args, { cwd });
+  } catch {
+    return "";
+  }
+}
+function truncate3(s, max) {
+  return s.length <= max ? s : s.slice(0, max) + TRUNCATED_SUFFIX;
+}
+function formatReviewComments(raw) {
+  if (!raw) return "";
+  try {
+    const parsed = JSON.parse(raw);
+    const out = [];
+    for (const c of parsed.comments ?? []) {
+      if (!c.body) continue;
+      out.push(`- **${c.author?.login ?? "unknown"}**: ${c.body.replace(/\n/g, " ").slice(0, 500)}`);
+    }
+    for (const r of parsed.reviews ?? []) {
+      if (!r.body && !r.state) continue;
+      const state = r.state ? ` (${r.state})` : "";
+      const body = r.body ? `: ${r.body.replace(/\n/g, " ").slice(0, 500)}` : "";
+      out.push(`- **${r.author?.login ?? "unknown"}**${state}${body}`);
+    }
+    return out.join("\n");
+  } catch {
+    return "";
+  }
+}
+
 // src/scripts/loadTaskState.ts
 var loadTaskState = async (ctx) => {
   const target = ctx.data.commentTargetType;
@@ -3656,6 +3760,7 @@ var parseAgentResult2 = async (ctx, profile, agentResult) => {
   ctx.data.prSummary = parsed.prSummary;
   ctx.data.feedbackActions = parsed.feedbackActions;
   ctx.data.planDeviations = parsed.planDeviations;
+  ctx.data.priorArt = parsed.priorArt;
   ctx.data.agentFailureReason = parsed.failureReason;
   ctx.data.agentOutcome = agentResult.outcome;
   ctx.data.agentError = agentResult.error;
@@ -4924,6 +5029,7 @@ var preflightScripts = {
   loadIssueContext,
   loadConventions,
   loadCoverageRules,
+  loadPriorArt,
   loadQaGuide,
   buildSyntheticPlugin,
   resolveArtifacts,
@@ -5079,7 +5185,7 @@ async function runExecutable(profileName, input) {
       ndjsonDir,
       allowedToolsOverride: profile.claudeCode.tools,
       permissionModeOverride: profile.claudeCode.permissionMode,
-      mcpServers: profile.claudeCode.mcpServers,
+      mcpServers: profile.claudeCode.mcpServers.length > 0 ? profile.claudeCode.mcpServers : void 0,
       pluginPaths: pluginPaths.length > 0 ? pluginPaths : void 0,
       maxTurns: profile.claudeCode.maxTurns,
       maxThinkingTokens: profile.claudeCode.maxThinkingTokens,

package/dist/executables/fix/profile.json

@@ -36,9 +36,26 @@
     "commands": [],
     "subagents": [],
     "plugins": [],
-    "mcpServers": []
+    "mcpServers": [
+      {
+        "name": "playwright",
+        "command": "npx",
+        "args": ["-y", "@playwright/mcp@latest"]
+      }
+    ]
   },
-  "cliTools": [],
+  "cliTools": [
+    {
+      "name": "playwright",
+      "install": {
+        "required": false,
+        "checkCommand": "npx --no-install playwright --version",
+        "installCommand": "npx --yes playwright install --with-deps chromium"
+      },
+      "verify": "npx --no-install playwright --version",
+      "usage": ""
+    }
+  ],
   "scripts": {
     "preflight": [
       {

package/dist/executables/plan/profile.json

@@ -27,9 +27,26 @@
     "commands": [],
     "subagents": [],
     "plugins": [],
-    "mcpServers": []
+    "mcpServers": [
+      {
+        "name": "playwright",
+        "command": "npx",
+        "args": ["-y", "@playwright/mcp@latest"]
+      }
+    ]
   },
-  "cliTools": [],
+  "cliTools": [
+    {
+      "name": "playwright",
+      "install": {
+        "required": false,
+        "checkCommand": "npx --no-install playwright --version",
+        "installCommand": "npx --yes playwright install --with-deps chromium"
+      },
+      "verify": "npx --no-install playwright --version",
+      "usage": ""
+    }
+  ],
   "scripts": {
     "preflight": [
       {
@@ -49,6 +66,9 @@
       {
         "script": "loadConventions"
       },
+      {
+        "script": "loadPriorArt"
+      },
       {
         "script": "composePrompt"
       }

package/dist/executables/plan/prompt.md

@@ -1,6 +1,6 @@
-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:
+You are a senior engineer producing a **deep, detailed implementation plan** for the GitHub issue below. The plan must be thorough enough that another engineer can implement the feature without re-doing research — file locations, function signatures, algorithms, edge cases, and tests are all specified. You will NOT write code. You will NOT run git or gh commands. You will NOT modify files.
 
-1. Use Read / Grep / Glob / Bash (read-only) to study the codebase as much as needed.
+1. Use Read / Grep / Glob / Bash (read-only) to study the codebase as much as needed. Depth matters more than speed — invest turns in understanding before writing.
 2. Emit a final message with the plan wrapped in the required markers (see "Required output").
 
 ---
@@ -17,6 +17,43 @@ Recent comments (most recent first, truncated):
 
 {{conventionsBlock}}
 
+{{priorArt}}
+
+---
+
+# Delta mode — if a prior plan comment exists
+
+Before writing the plan, scan the "Recent comments" block above for a previous
+comment whose body starts with `## Plan for issue`. If one exists, you are in
+**delta mode**:
+
+1. Treat the prior plan as the baseline. Do NOT regenerate unchanged sections
+   from scratch.
+2. Integrate the signal from comments posted AFTER the prior plan: user
+   answers, correction directives, new clarifying info, closed/merged PRs that
+   appeared since.
+3. In each section, mark changed bullets with `(updated)`, new bullets with
+   `(new)`, and removed items with `(removed — <reason>)`. Preserve unchanged
+   bullets verbatim so reviewers can diff.
+4. If nothing material has changed since the prior plan, output
+   `FAILED: no new information since last plan` instead of a duplicate.
+
+If no prior `## Plan for issue` comment exists, produce a full first-pass
+plan under the Required output structure below.
+
+---
+
+# Research floor (MUST be done before writing the plan)
+
+Before producing the final plan, you MUST have read:
+
+- Every file you intend to change (the full file, not just a grep hit).
+- The tests for each file you intend to change, if tests exist for that module.
+- At least one sibling module that already implements the same pattern you're about to follow (reference implementations).
+- The full prior-art diffs above (if any) — not just titles. Those represent failed solutions; understanding why they failed is part of the plan.
+
+If a file you need to read does not exist, say so explicitly in the plan under "Ambiguities" — do NOT guess at its contents.
+
 ---
 
 # Required output
@@ -27,16 +64,87 @@ 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.>
+<A deep, detailed implementation plan in markdown with the following sections, in order. Omit a section only if its trigger condition is not met — do not leave placeholders. Depth is expected; brevity for its own sake is not a goal.
+
+## Existing patterns found
+For each major part of the change, name the sibling module in this repo that
+already solves a similar problem and state how this plan reuses it.
+ - Pattern: <what kind of pattern — e.g. "admin field with custom React component", "fetch-then-group client hook", "JSON strings module">
+ - Reference: <exact path in this repo, e.g. `src/ui/admin/LessonBlocksField/index.tsx`>
+ - Reuse: <how this plan follows it — which hooks/APIs/idioms are mirrored, what deviates and why>
+If you searched and found nothing applicable, say so explicitly: "Searched
+for X / Y / Z — no existing pattern; proposing new convention because …".
+Proposing a new pattern when an existing one covers the use case is a
+planning failure — fall back to reuse unless you name a concrete reason.
+
+## Changes (per file)
+For EACH file you will change or create, include:
+ - Path (exact).
+ - Why this file — one sentence tying the change to the issue.
+ - Current state — what's there today (function/class/export names, relevant line ranges). Skip for new files.
+ - Target state — what will be there after the change, at the same level of specificity.
+ - Exact locations of edits (function name, line range if stable, or anchor like "after the `meta` group field, before the closing `fields: []`").
+ - For new files: rough shape including exports, key functions with signatures, and top-level module comment.
+ - Dependencies touched (imports added/removed, new packages) — call out if anything needs installing.
+
+## Algorithms & pseudocode
+REQUIRED for any non-trivial logic (sorting, diffing, state transitions, concurrency, batching, caching, conflict resolution).
+ - Write pseudocode (not production code) showing the actual algorithm — inputs, steps, outputs.
+ - Call out invariants the algorithm preserves.
+ - Call out complexity (N swaps vs N-squared recalc vs single-batch write).
+ - If there's a choice between two algorithms, explain why you picked this one.
+
+## How clarifying answers shape the plan
+REQUIRED if research asked clarifying questions and the issue comments contain user answers.
+ - For each answered question: name the concrete design choice the answer forces — not a restatement of the answer.
+ - "Answer: yes → init orders 10/20/30 on first interaction" → spell out: which function performs the init, when it runs (mount vs first-swap), how it detects the "first use" state, what happens on re-entry.
+
+## Why this will work
+REQUIRED if research cites a prior failed attempt (closed PR, reverted commit, previous run that didn't land), or if prior-art above contains a diff.
+ - Root-cause hypothesis — what specifically went wrong in the prior attempt (cite lines from the prior diff above).
+ - The specific change in THIS plan that addresses the root cause — name the file/line/hook/config that differs from the prior attempt.
+ - How you will verify the fix works — a concrete behavioral check (URL + action + expected UI, or API call + expected response, or a test case). Not "typecheck passes."
+
+## API surface verification
+REQUIRED for every hook, import, SDK method, framework primitive, or config key the plan names.
+ - Build a table or list. For each named symbol: the file path where it's defined, or the exact package + export (with a `node_modules/...` path you actually read), or the mark `UNVERIFIED`.
+ - Do not guess. If you could not find it with Read / Grep / Glob, it is UNVERIFIED. Do not rely on UNVERIFIED symbols in the plan — flag them as blockers.
+ - Include negative evidence too: "Searched for `useXxx` in `@payloadcms/ui` exports — not found; planner assumed `useDocumentInfo` instead."
+
+## Initial data state → transition → steady state
+REQUIRED if the feature mutates existing data (reorder, migrate, backfill, rename, enable).
+ - Initial state: describe the data as it is in production today, including edge cases (rows with NULL, rows with default zero, orphan rows, etc).
+ - Transition: the exact step(s) that move data from initial → steady, including who triggers them (user action, migration script, on-mount hook), idempotency, and rollback behavior.
+ - Steady state: what invariants hold after transition.
+ - Failure modes during transition: partial-apply, race conditions, concurrent writers.
+
+## Error paths & failure handling
+For each external call or mutation in the plan (API request, DB write, file op, SDK call), enumerate:
+ - What can fail (network, validation, auth, not-found, conflict, rate limit).
+ - What the UI/caller does on each failure — retry, surface error, rollback, log-and-continue.
+ - What state the system is left in if the op fails mid-way.
+
+## Test plan
+ - Specific test cases by name, with inputs and expected outputs. Not "add unit tests."
+ - Unit tests: one line per test naming what it asserts.
+ - Integration / behavioral tests: one line each, naming the flow covered and the assertion.
+ - Regression tests for the prior-art failure mode (if applicable) — a test that would have caught the prior bug.
+ - Manual verification steps: URL + click sequence + expected UI, or API call + expected response.
+
+## Ambiguities & assumptions
+ - List anything still unresolved that needs human input before implementation.
+ - List every assumption the plan makes that was NOT confirmed by the issue, comments, or code (e.g. "assumed `usePayload` hook exists — UNVERIFIED").
+
+## Verification checklist
+ - Build / typecheck / test / lint commands expected to pass after implementation.
+ - Each concrete behavioral check from "Test plan" restated as a pass/fail gate.
+
+No filler. No marketing language. Depth over brevity.>
 ```
 
 # 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.
+- No speculative scope — plan only what the issue asks for, but plan it THOROUGHLY.
 - If the issue is ambiguous and you cannot make progress without input, output `FAILED: <what's unclear>` instead of a plan.
+- If the Research floor cannot be met because required files are missing or unreadable, output `FAILED: <what could not be read>` instead of a half-blind plan.

package/dist/executables/research/profile.json

@@ -27,9 +27,26 @@
     "commands": [],
     "subagents": [],
     "plugins": [],
-    "mcpServers": []
+    "mcpServers": [
+      {
+        "name": "playwright",
+        "command": "npx",
+        "args": ["-y", "@playwright/mcp@latest"]
+      }
+    ]
   },
-  "cliTools": [],
+  "cliTools": [
+    {
+      "name": "playwright",
+      "install": {
+        "required": false,
+        "checkCommand": "npx --no-install playwright --version",
+        "installCommand": "npx --yes playwright install --with-deps chromium"
+      },
+      "verify": "npx --no-install playwright --version",
+      "usage": ""
+    }
+  ],
   "scripts": {
     "preflight": [
       {
@@ -84,6 +101,11 @@
         "name": "research",
         "format": "markdown",
         "from": "prSummary"
+      },
+      {
+        "name": "priorArt",
+        "format": "json",
+        "from": "priorArt"
       }
     ]
   }

package/dist/executables/research/prompt.md

@@ -25,6 +25,7 @@ Your FINAL message must be exactly this shape (no extra text before or after):
 ```
 DONE
 COMMIT_MSG: research: <very short title>
+PRIOR_ART: <JSON array of closed or merged PR numbers from this repo that are prior attempts at THIS issue, or [] if none. Include only PRs that actually touched the same feature/area — not every PR your research happens to mention. Example: [1086] or []. Must be valid JSON parseable as number[].>
 PR_SUMMARY:
 <A research doc in markdown with EXACTLY these sections, in order:
 
@@ -82,6 +83,9 @@ Gaps & assumptions — they live in the prior comment. Keep the whole delta
 under 25 lines. If nothing has changed since the prior research, output
 `FAILED: no new information since last research` instead.
 
+`PRIOR_ART:` is still required in delta mode (carry forward the prior list,
+or update it if new PRs became relevant since).
+
 If no prior `## Research for issue` comment exists in the thread, produce
 the full first-pass structure below.
 

package/dist/executables/review/profile.json

@@ -28,9 +28,26 @@
     "commands": [],
     "subagents": [],
     "plugins": [],
-    "mcpServers": []
+    "mcpServers": [
+      {
+        "name": "playwright",
+        "command": "npx",
+        "args": ["-y", "@playwright/mcp@latest"]
+      }
+    ]
   },
-  "cliTools": [],
+  "cliTools": [
+    {
+      "name": "playwright",
+      "install": {
+        "required": false,
+        "checkCommand": "npx --no-install playwright --version",
+        "installCommand": "npx --yes playwright install --with-deps chromium"
+      },
+      "verify": "npx --no-install playwright --version",
+      "usage": ""
+    }
+  ],
   "scripts": {
     "preflight": [
       {

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

@@ -38,7 +38,13 @@
     "commands": [],
     "subagents": [],
     "plugins": [],
-    "mcpServers": []
+    "mcpServers": [
+      {
+        "name": "playwright",
+        "command": "npx",
+        "args": ["-y", "@playwright/mcp@latest"]
+      }
+    ]
   },
   "cliTools": [
     {

package/package.json

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