@kody-ade/kody-engine 0.3.0 → 0.3.2

package/dist/executables/fix/profile.json

@@ -15,6 +15,7 @@
       "flag": "--feedback",
       "type": "string",
       "required": false,
+      "bindsCommentRest": true,
       "describe": "Inline override. If absent, the flow reads the latest PR review comment."
     }
   ],
@@ -36,9 +37,26 @@
     "commands": [],
     "subagents": [],
     "plugins": [],
-    "mcpServers": []
+    "mcpServers": [
+      {
+        "name": "playwright",
+        "command": "npx",
+        "args": ["-y", "@playwright/mcp@latest"]
+      }
+    ]
   },
-  "cliTools": [],
+  "cliTools": [
+    {
+      "name": "playwright",
+      "install": {
+        "required": false,
+        "checkCommand": "ls \"$HOME/.cache/ms-playwright\" 2>/dev/null | grep -q '^chromium'",
+        "installCommand": "npx --yes playwright install --with-deps chromium"
+      },
+      "verify": "ls \"$HOME/.cache/ms-playwright\" 2>/dev/null | grep -q '^chromium'",
+      "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/types.ts

@@ -97,6 +97,13 @@ export interface InputSpec {
    * e.g. `{ mode: "run" }` or `{ mode: ["fix", "fix-ci", "resolve"] }`.
    */
   requiredWhen?: Record<string, string | string[]>
+  /**
+   * When true, this input collects any free-text left over from comment
+   * dispatch after flag/enum/bool parsing. Only one input per profile may
+   * set this. Used by e.g. `fix.feedback` so `@kody please change X` lands
+   * "please change X" in `feedback` without hardcoding that in the router.
+   */
+  bindsCommentRest?: boolean
   describe: string
 }
 

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.2",
   "description": "kody — autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   "license": "MIT",
   "type": "module",