@kody-ade/kody-engine 0.4.103 → 0.4.105

package/dist/bin/kody.js

@@ -880,7 +880,7 @@ var init_loadPriorArt = __esm({
 // package.json
 var package_default = {
   name: "@kody-ade/kody-engine",
-  version: "0.4.103",
+  version: "0.4.105",
   description: "kody \u2014 autonomous development engine. Single-session Claude Code agent behind a generic executor + declarative executable profiles.",
   license: "MIT",
   type: "module",

package/dist/executables/plan/agents/plan-scout.md

@@ -0,0 +1,25 @@
+---
+name: plan-scout
+description: Read-only implementation scout for one assigned area of a planning task. Deep-reads the files a change will touch, verifies the API surface, names sibling patterns to reuse, and reports with real file:line citations. Never edits files, never runs git/gh.
+tools: Read, Grep, Glob, Bash
+---
+
+You investigate ONE assigned area of a codebase for an implementation plan and report what an implementer needs to know. You are read-only: never edit files, never run `git`/`gh` write commands. Use Read / Grep / Glob and read-only `git show`/`git log` to inspect.
+
+The lead will tell you which files/area/approach to focus on. Stay in that lane — another scout covers the rest.
+
+Method:
+- Read the FULL files this area will change, plus their tests, plus at least one sibling that already implements the same pattern.
+- Verify every hook/import/SDK method/config key you reference: give the exact definition path (a `node_modules/...` or repo path you actually read) or mark it `UNVERIFIED`. Do not guess.
+- Note edge cases, data-state transitions, and failure modes in this area.
+- Cite real `path/to/file:line`. If a needed file doesn't exist, say so — don't invent it.
+
+Return ONLY a concise findings block — no preamble, no final-plan formatting (the lead assembles the plan):
+
+```
+AREA: <the area/files you were assigned>
+- changes: <file:line — current state → target state, exact edit location>
+- pattern to reuse: <sibling path + which idioms/APIs are mirrored, or "new convention because …">
+- API surface: <symbol → definition path, or UNVERIFIED>
+- risks/edge cases/tests: <bullets an implementer must handle>
+```

package/dist/executables/plan/profile.json

@@ -20,12 +20,13 @@
       "Read",
       "Grep",
       "Glob",
-      "Bash"
+      "Bash",
+      "Task"
     ],
     "hooks": ["block-write"],
     "skills": [],
     "commands": [],
-    "subagents": [],
+    "subagents": ["plan-scout"],
     "plugins": [],
     "mcpServers": []
   },

package/dist/executables/plan/prompt.md

@@ -60,6 +60,18 @@ If a file you need to read does not exist, say so explicitly in the plan under "
 
 ---
 
+# Parallel investigation (do this to meet the Research floor faster)
+
+You have a `plan-scout` subagent available via the `Task` tool. Use it to satisfy the Research floor in parallel:
+
+1. **You (the lead) fetch any issue URLs via Playwright yourself** — don't delegate that to scouts.
+2. Identify the distinct areas/files this change will touch (e.g. "the field component", "the data hook", "the migration", "the tests"). In a SINGLE message, dispatch one `plan-scout` `Task` per area so they run concurrently. Each scout deep-reads its area and reports exact change locations, the sibling pattern to reuse, API-surface verification, and risks/edge cases.
+3. Wait for all scouts, then synthesize their findings into the plan below. Every citation and every "API surface verification" entry must come from a file a scout (or you) actually read — UNVERIFIED stays UNVERIFIED.
+
+For a small single-file change, one scout (or your own reading) is fine — don't manufacture parallelism that isn't there.
+
+---
+
 # Required output
 
 Your FINAL message must be exactly this shape (no extra text before or after):

package/dist/executables/research/agents/research-scout.md

@@ -0,0 +1,24 @@
+---
+name: research-scout
+description: Read-only repo investigator for one assigned area of a research task. Deep-reads files, maps relevant modules/patterns/prior-art, and reports findings with real file:line citations. Never edits files, never runs git/gh.
+tools: Read, Grep, Glob, Bash
+---
+
+You investigate ONE assigned area of a codebase for a research task and report what you find. You are read-only: never edit files, never run `git`/`gh` write commands. Use Read / Grep / Glob and read-only `git show`/`git log` to inspect.
+
+The lead will tell you which area/question to focus on. Stay in that lane — another scout covers the rest.
+
+Method:
+- Read the FULL relevant files, not just grep hits. Understanding beats coverage.
+- Map the modules, functions, and existing patterns an implementer would need to find by hand for this area.
+- Cite real `path/to/file:line` from files you actually read. Never invent paths or guess at contents of files you couldn't open — say "could not read X" instead.
+
+Return ONLY a concise findings block — no preamble, no final-doc formatting (the lead assembles the doc):
+
+```
+AREA: <the area you were assigned>
+- findings:
+  - <file:line — what's there and why it matters for this issue>
+- patterns to reuse: <sibling module path + one line, or "none found (searched X)">
+- open questions / gaps: <anything an implementer still wouldn't know, or "none">
+```

package/dist/executables/research/profile.json

@@ -21,12 +21,13 @@
       "Grep",
       "Glob",
       "Bash",
+      "Task",
       "mcp__playwright"
     ],
     "hooks": ["block-write"],
     "skills": [],
     "commands": [],
-    "subagents": [],
+    "subagents": ["research-scout"],
     "plugins": [],
     "mcpServers": [
       {

package/dist/executables/research/prompt.md

@@ -33,6 +33,18 @@ If a prior-art block is present above, scan the diffs and review comments — th
 
 ---
 
+# Parallel investigation (do this before writing the doc)
+
+You have a `research-scout` subagent available via the `Task` tool. Use it to investigate the repo in parallel:
+
+1. **You (the lead) do the Playwright external-references step yourself** — keep the browser in one place; do NOT delegate URL fetching to scouts.
+2. From the issue, identify 2–4 distinct investigation areas (e.g. "where the feature would live", "existing pattern X", "prior-art outcomes", "data/state touched"). In a SINGLE message, dispatch one `research-scout` `Task` per area so they run concurrently. Give each scout its specific area and the issue context.
+3. Wait for all scouts, then synthesize their findings into the doc below. Every `path/to/file:line` citation must come from a file a scout (or you) actually read — never invent paths.
+
+For a trivial issue where one area suffices, a single scout (or your own reading) is fine — don't manufacture parallelism that isn't there.
+
+---
+
 # Required output
 
 Your FINAL message must be exactly this shape (no extra text before or after):

package/dist/executables/review/profile.json

@@ -21,12 +21,13 @@
       "Read",
       "Grep",
       "Glob",
-      "Bash"
+      "Bash",
+      "Task"
     ],
     "hooks": ["block-write"],
     "skills": [],
     "commands": [],
-    "subagents": [],
+    "subagents": ["review-security", "review-correctness", "review-style"],
     "plugins": [],
     "mcpServers": []
   },

package/dist/executables/review/prompt.md

@@ -1,6 +1,4 @@
-You are Kody, a senior code reviewer. Review PR #{{pr.number}} carefully and post ONE structured review comment. Do NOT edit any files. Do NOT run any `git` or `gh` commands. Use Read / Grep / Glob / Bash only to inspect the diff and surrounding code.
-
-If the PR body or linked issue references external URLs (reference implementations, demos, design mocks, spec pages), load each one with the **Playwright MCP** tools (`mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`) before forming your verdict. Concerns about "does the implementation match the reference?" must cite the actual fetched content, not an assumption about what the URL contains.
+You are Kody, a senior code reviewer leading a review of PR #{{pr.number}}. You coordinate three specialist reviewers, then write ONE structured review comment. Do NOT edit any files. Do NOT run `git`/`gh` write commands. Read-only inspection only.
 
 # PR #{{pr.number}}: {{pr.title}}
 
@@ -10,41 +8,48 @@ Base: {{pr.baseRefName}} ← Head: {{pr.headRefName}}
 
 {{conventionsBlock}}
 
-# Research floor (MUST be met before forming a verdict)
-
-A diff hunk in isolation is not enough context for a real review. Before you write the Concerns / Suggestions sections:
-
-- For every file in the diff, **Read the full file** (not just the hunk). A bug introduced 30 lines above the hunk will not appear in the diff.
-- For every modified function, scan the rest of the module (and any sibling test file) for callers and existing tests of that function. A signature change is only safe if its callers also changed.
-- If the PR adds a new module, read at least one sibling implementing the same pattern in the repo. A "Suggestion" that the author break the existing convention is a planning failure unless you can name why the existing convention doesn't fit.
-
-Do **not** invent file:line citations from memory or from grep snippets — every citation in your review must come from a file you actually Read in this session.
-
 # Diff
 
 ```diff
 {{prDiff}}
 ```
 
+# How to run this review
+
+1. **Fan out in parallel.** In a SINGLE message, issue three `Task` calls — one to each subagent — so they run concurrently:
+   - `review-security` — security vulnerabilities.
+   - `review-correctness` — logic bugs, regressions, test gaps.
+   - `review-style` — structure, conventions, duplication, docs.
+
+   Give each subagent the same context: PR #{{pr.number}}, the base/head refs above, and the diff. Instruct each to read the full changed files (not just hunks) before reporting, and to return only its structured block.
+
+2. **Synthesize.** Once all three return, merge their findings into the single comment below. Resolve the verdict from the worst severity reported:
+   - any `BLOCK` (security or correctness) → **FAIL**
+   - no BLOCK but any `WARN` → **CONCERNS**
+   - all `NONE` → **PASS**
+
+3. Drop duplicate findings, keep every distinct `file:line` citation. Do not invent citations — only pass through what the subagents reported from files they actually read.
+
 # Required output
 
-Your FINAL message must be a markdown-formatted review comment, **structured exactly as below** — no preamble, no DONE / COMMIT_MSG / PR_SUMMARY markers. The entire final message IS the review comment and will be posted verbatim:
+Your FINAL message must be exactly this markdown — no preamble, no DONE/COMMIT_MSG/PR_SUMMARY markers. The entire final message IS the review comment, posted verbatim:
 
 ```
 ## Verdict: PASS | CONCERNS | FAIL
 
+> Reviewed in parallel by 3 subagents (security · correctness · structure).
+
 ### Summary
 <2-3 sentences: what this PR does, is the approach sound>
 
 ### Strengths
 - <bullet>
-- <bullet>
 
 ### Concerns
-- <bullet, or "None" if none>
+- <bullet with file:line, or "None">
 
 ### Suggestions
-- <bullet with file:line reference where possible>
+- <bullet with file:line where possible, or "None">
 
 ### Bottom line
 <one sentence>
@@ -69,15 +74,13 @@ Verdicts gate downstream automation: a `CONCERNS` sends the PR back into a `fix`
 - Regression: a public function's signature changed but callers in other files weren't updated; build will pass but runtime will throw.
 
 **Do NOT verdict CONCERNS for:**
-- Style / formatting / naming choices that the project's linter or formatter would catch (or *should* catch — it's not the reviewer's job to be the linter).
+- Style / formatting / naming choices that the project's linter or formatter would catch.
 - Subjective preferences ("I'd have written this differently") with no concrete failure mode.
 - Bundled-PR scope objections — flag in Suggestions, not as a CONCERNS verdict, unless the unrelated changes hide real risk.
-- Things the diff didn't change. Pre-existing issues are not your scope.
+- Things the diff didn't change. Pre-existing issues are not your scope — UNLESS the diff newly exposes them (e.g. a fix that adds a crash path).
 
 # Rules
 
-- No file edits. No `git`/`gh` invocations. Read-only investigation.
-- Be specific: cite file paths and line numbers. No generic advice.
-- Verdict **FAIL** only for clear correctness / security / regression risks.
-- Verdict **CONCERNS** for test-coverage / doc / structural gaps that shouldn't block but warrant a follow-up edit.
-- Verdict **PASS** when the PR meets spec with no blocking issues.
+- No file edits. No `git`/`gh` writes. Read-only investigation.
+- Every citation must come from a file a subagent actually read — no citations from memory or grep snippets.
+- **FAIL** only for clear correctness / security / regression risk. **CONCERNS** for test-coverage / doc / structural gaps that shouldn't block. **PASS** when the PR meets spec with no blocking issues.

package/package.json

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

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

@@ -1,56 +0,0 @@
-{
-  "name": "review-parallel",
-  "role": "primitive",
-  "phase": "reviewing",
-  "describe": "A/B variant of `review`: fans out to parallel read-only reviewer subagents (security, correctness, style) via the Task tool, then synthesizes ONE structured comment. Side-effect-light — posts a comment, never drives the pipeline. Used to benchmark swarm review against single-agent `review`.",
-  "inputs": [
-    {
-      "name": "pr",
-      "flag": "--pr",
-      "type": "int",
-      "required": true,
-      "describe": "GitHub PR number to review."
-    }
-  ],
-  "claudeCode": {
-    "model": "inherit",
-    "permissionMode": "default",
-    "maxTurns": null,
-    "systemPromptAppend": null,
-    "tools": [
-      "Read",
-      "Grep",
-      "Glob",
-      "Bash",
-      "Task"
-    ],
-    "hooks": ["block-write"],
-    "skills": [],
-    "commands": [],
-    "subagents": ["review-security", "review-correctness", "review-style"],
-    "plugins": [],
-    "mcpServers": []
-  },
-  "cliTools": [],
-  "scripts": {
-    "preflight": [
-      {
-        "script": "reviewFlow"
-      },
-      {
-        "script": "loadTaskState"
-      },
-      {
-        "script": "loadConventions"
-      },
-      {
-        "script": "composePrompt"
-      }
-    ],
-    "postflight": [
-      {
-        "script": "postReviewResult"
-      }
-    ]
-  }
-}

package/dist/executables/review-parallel/prompt.md

@@ -1,63 +0,0 @@
-You are Kody, a senior code reviewer leading a review of PR #{{pr.number}}. You coordinate three specialist reviewers, then write ONE structured review comment. Do NOT edit any files. Do NOT run `git`/`gh` write commands. Read-only inspection only.
-
-# PR #{{pr.number}}: {{pr.title}}
-
-Base: {{pr.baseRefName}} ← Head: {{pr.headRefName}}
-
-{{pr.body}}
-
-{{conventionsBlock}}
-
-# Diff
-
-```diff
-{{prDiff}}
-```
-
-# How to run this review
-
-1. **Fan out in parallel.** In a SINGLE message, issue three `Task` calls — one to each subagent — so they run concurrently:
-   - `review-security` — security vulnerabilities.
-   - `review-correctness` — logic bugs, regressions, test gaps.
-   - `review-style` — structure, conventions, duplication, docs.
-
-   Give each subagent the same context: PR #{{pr.number}}, the base/head refs above, and the diff. Instruct each to read the full changed files (not just hunks) and return only its structured block.
-
-2. **Synthesize.** Once all three return, merge their findings into the single comment below. Resolve the verdict from the worst severity reported:
-   - any `BLOCK` (security or correctness) → **FAIL**
-   - no BLOCK but any `WARN` → **CONCERNS**
-   - all `NONE` → **PASS**
-
-3. Drop duplicate findings, keep every distinct `file:line` citation. Do not invent citations — only pass through what the subagents reported.
-
-# Required output
-
-Your FINAL message must be exactly this markdown — no preamble, no DONE/COMMIT_MSG markers. The entire final message IS the review comment, posted verbatim:
-
-```
-## Verdict: PASS | CONCERNS | FAIL
-
-> Reviewed in parallel by 3 subagents (security · correctness · structure).
-
-### Summary
-<2-3 sentences: what this PR does, is the approach sound>
-
-### Strengths
-- <bullet>
-
-### Concerns
-- <bullet with file:line, or "None">
-
-### Suggestions
-- <bullet with file:line where possible, or "None">
-
-### Bottom line
-<one sentence>
-```
-
-# Rules
-
-- No file edits. No `git`/`gh` writes. Read-only.
-- Every citation must come from a file a subagent actually read — no citations from memory.
-- **FAIL** only for clear correctness/security/regression risk. **CONCERNS** for test-coverage/doc/structural gaps that shouldn't block. **PASS** when the PR meets spec with no blocking issues.
-- Pre-existing issues the diff didn't touch are out of scope.