@flumecode/runner 0.14.0 → 0.16.0

package/dist/cli.js

@@ -27,7 +27,7 @@ function writeConfig(config) {
 
 // src/run.ts
 import { existsSync as existsSync4 } from "node:fs";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 
 // src/version.ts
 import { readFileSync as readFileSync2 } from "node:fs";
@@ -182,6 +182,8 @@ async function safeText(res) {
 
 // src/plugins/socket.ts
 import { exec as execCb } from "node:child_process";
+import { readFile as readFile2 } from "node:fs/promises";
+import { join as join4 } from "node:path";
 import { promisify as promisify2 } from "node:util";
 
 // src/workspace.ts
@@ -612,7 +614,12 @@ function parseManifest(raw) {
   if (typeof r.key !== "string" || !r.key) return null;
   if (r.socket !== "pre-commit") return null;
   if (typeof r.run !== "string" || !r.run) return null;
-  return { key: r.key, socket: r.socket, run: r.run };
+  let report;
+  const rep = r.report;
+  if (rep && typeof rep.file === "string" && rep.file && rep.format === "jest") {
+    report = { file: rep.file, format: "jest" };
+  }
+  return { key: r.key, socket: r.socket, run: r.run, ...report ? { report } : {} };
 }
 
 // src/plugins/socket.ts
@@ -633,15 +640,40 @@ async function runSocket(socketName, dir) {
   const results = [];
   for (const plugin of plugins) {
     const result = await runPluginCommand(plugin.run, dir);
+    const metrics = await readMetrics(plugin.report, dir);
     if (result.exitCode !== 0) {
-      results.push({ key: plugin.key, status: "failed", output: cap(result.output) });
+      results.push({
+        key: plugin.key,
+        status: "failed",
+        output: cap(result.output),
+        ...metrics ? { metrics } : {}
+      });
       lastSocketResults = results;
       throw new PreCommitError(`[plugin:${plugin.key}] ${result.output}`);
     }
-    results.push({ key: plugin.key, status: "passed", output: cap(result.output) });
+    results.push({
+      key: plugin.key,
+      status: "passed",
+      output: cap(result.output),
+      ...metrics ? { metrics } : {}
+    });
   }
   lastSocketResults = results;
 }
+async function readMetrics(report, dir) {
+  if (!report) return void 0;
+  try {
+    const raw = JSON.parse(await readFile2(join4(dir, report.file), "utf8"));
+    if (report.format === "jest") {
+      return {
+        testsRun: Number(raw.numTotalTests) || 0,
+        testsFailed: Number(raw.numFailedTests) || 0
+      };
+    }
+  } catch {
+  }
+  return void 0;
+}
 async function runPluginCommand(command2, cwd) {
   try {
     const result = await exec2(command2, { cwd, maxBuffer: 1 << 24 });
@@ -746,7 +778,9 @@ var pseudoCodeEntrySchema = z2.object({
 });
 var stepSchema = z2.object({
   title: z2.string().min(1).describe("A concise imperative title for this step."),
-  description: z2.string().min(1).describe("What changes and why \u2014 the rationale for this step. " + INLINE_CODE_HINT),
+  description: z2.array(z2.string().min(1)).min(1).describe(
+    "Bullet points that explain this step's change so a reviewer can judge whether the design is correct. Each array item is one short, self-contained bullet \u2014 not a single paragraph, and not a restatement of the pseudo code. " + INLINE_CODE_HINT
+  ),
   pseudoCode: z2.array(pseudoCodeEntrySchema).optional().describe(
     "Per-file pseudo code. Provide an entry for every non-documentation file this step touches. Each entry contains the file path and pseudo code describing the changes to that file."
   )
@@ -758,6 +792,9 @@ var planInputSchema = {
   scope: z2.enum(["feat", "fix", "chore", "docs", "test", "refactor"]).describe("The primary intent of the change."),
   goal: z2.string().min(1).describe("One or two sentences stating the outcome. " + INLINE_CODE_HINT),
   assumptions: z2.array(z2.string()).describe("Anything decided during planning, including unanswered defaults."),
+  requirements: z2.array(z2.string().min(1)).min(1).describe(
+    "Required, human-readable statements of what this change must accomplish and why, in plain language a non-technical reader can follow. Distinct from acceptanceCriteria: requirements explain intent/rationale; acceptance criteria are the machine-checkable proof. At least 1 required. " + INLINE_CODE_HINT
+  ),
   steps: z2.array(stepSchema).min(1).describe("Ordered list of changes. Each step says what and why, with file references."),
   acceptanceCriteria: z2.array(z2.string().min(1)).min(2).describe(
     "Concrete, deterministically-checkable conditions that together define done. Each names a trigger/precondition and the exact observable result (run X -> output Y; file Z contains W; f(a) returns b) \u2014 no vague adjectives, not a restatement of a step. The set must collectively cover every step's change. At least 2 required. " + INLINE_CODE_HINT
@@ -781,12 +818,19 @@ function renderPlan(plan) {
     }
   }
   lines2.push("");
+  lines2.push("## Requirements");
+  for (const requirement of plan.requirements) {
+    lines2.push(`- ${requirement}`);
+  }
+  lines2.push("");
   lines2.push("## Steps");
   for (const [i, step] of plan.steps.entries()) {
     lines2.push("");
     lines2.push(`### ${i + 1}. ${step.title}`);
     lines2.push("");
-    lines2.push(step.description);
+    for (const bullet of step.description) {
+      lines2.push(`- ${bullet}`);
+    }
     if (step.pseudoCode && step.pseudoCode.length > 0) {
       for (const entry of step.pseudoCode) {
         lines2.push("");
@@ -835,7 +879,7 @@ function createPlanTooling() {
   let renderedPlans = null;
   const submitPlan = tool2(
     SUBMIT_PLAN,
-    "Submit ALL your plans in a single call \u2014 one entry per plan; each becomes its own independently-acceptable Accept-as-plan draft. Do NOT call submit_plan more than once. acceptanceCriteria is required in each plan and must contain at least 2 observable, verifiable conditions. The 'title' field names each specific plan \u2014 make it concise and distinct from the request title and from sibling plan titles.",
+    "Submit ALL your plans in a single call \u2014 one entry per plan; each becomes its own independently-acceptable Accept-as-plan draft. Do NOT call submit_plan more than once. acceptanceCriteria is required in each plan and must contain at least 2 observable, verifiable conditions. The 'title' field names each specific plan \u2014 make it concise and distinct from the request title and from sibling plan titles. requirements is required in each plan: at least 1 plain-language statement of what the change must accomplish and why (human-readable intent), separate from the machine-checkable acceptanceCriteria. ",
     submitPlanInputSchema,
     async (args) => {
       const parsed = submitPlanSchema.parse(args);
@@ -907,8 +951,11 @@ var reportInputSchema = {
   caveats: z3.string().min(1).describe(
     "Markdown: anything deferred, unmet, or worth a human's eyes, incl. diff hunks that map to no plan AC. Write 'None.' if nothing. Rendered under '## Caveats / follow-ups'. " + INLINE_CODE_HINT
   ),
-  acceptanceCriteria: z3.array(acVerdictSchema).min(1).describe(
-    "One entry per acceptance criterion from the plan, in plan order, each with a verdict and the diff evidence behind it."
+  acceptanceCriteria: z3.array(acVerdictSchema).describe(
+    "One entry per acceptance criterion from the plan, in plan order, each with a verdict and the diff evidence behind it. May be empty for resolve runs (no plan to verify)."
+  ),
+  conflictResolution: z3.string().optional().describe(
+    "Markdown: present ONLY when a merge conflict was actually resolved. Explain, per conflicted file, how ours/theirs were integrated. Rendered under '## Conflict resolution'. Omit entirely when no conflict occurred."
   )
 };
 var reportSchema = z3.object(reportInputSchema);
@@ -916,21 +963,26 @@ function renderReport(report) {
   const lines2 = [];
   lines2.push(report.summary.trim());
   lines2.push("", "## Files changed", "", report.filesChanged.trim());
-  lines2.push("", "## Acceptance criteria");
-  for (const ac of report.acceptanceCriteria) {
-    lines2.push("");
-    lines2.push(`### ${STATUS_ICON[ac.status]} ${ac.criterion}`);
-    lines2.push("");
-    lines2.push(ac.rationale.trim());
-    for (const ev of ac.evidence) {
+  if (report.acceptanceCriteria.length > 0) {
+    lines2.push("", "## Acceptance criteria");
+    for (const ac of report.acceptanceCriteria) {
       lines2.push("");
-      lines2.push(ev.note ? `\`${ev.file}\` \u2014 ${ev.note}` : `\`${ev.file}\``);
+      lines2.push(`### ${STATUS_ICON[ac.status]} ${ac.criterion}`);
       lines2.push("");
-      lines2.push("```diff");
-      lines2.push(ev.hunk.replace(/\n+$/, ""));
-      lines2.push("```");
+      lines2.push(ac.rationale.trim());
+      for (const ev of ac.evidence) {
+        lines2.push("");
+        lines2.push(ev.note ? `\`${ev.file}\` \u2014 ${ev.note}` : `\`${ev.file}\``);
+        lines2.push("");
+        lines2.push("```diff");
+        lines2.push(ev.hunk.replace(/\n+$/, ""));
+        lines2.push("```");
+      }
     }
   }
+  if (report.conflictResolution?.trim()) {
+    lines2.push("", "## Conflict resolution", "", report.conflictResolution.trim());
+  }
   lines2.push("", "## Code quality", "", report.codeQuality.trim());
   lines2.push("", "## Caveats / follow-ups", "", report.caveats.trim());
   return lines2.join("\n");
@@ -1110,11 +1162,11 @@ function errorMessage(err) {
 
 // src/rules.ts
 import { readFileSync as readFileSync3 } from "node:fs";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 var RULES_DIR = fileURLToPath3(new URL("../skills-plugin/rules", import.meta.url));
 function loadRule(name) {
-  const raw = readFileSync3(join4(RULES_DIR, `${name}.md`), "utf8");
+  const raw = readFileSync3(join5(RULES_DIR, `${name}.md`), "utf8");
   return stripFrontMatter(raw).trim();
 }
 function stripFrontMatter(raw) {
@@ -1355,6 +1407,7 @@ async function pushAndOpenPr(ctx, dir, config, abort, opts = { rebase: true }) {
   const committed = await commitWithRepair(ctx, dir, abort);
   if (!committed) return { outcome: { kind: "none" }, autoMerged: false };
   let autoMerged = false;
+  let conflictResolution;
   if (opts.rebase) {
     try {
       await rebaseOntoMergeBranch(ctx, dir);
@@ -1364,14 +1417,15 @@ async function pushAndOpenPr(ctx, dir, config, abort, opts = { rebase: true }) {
       console.warn(
         `  rebase onto ${ctx.repo.mergeBranch} conflicted \u2014 merging it in and resolving with the agent\u2026`
       );
-      await mergeAndResolveConflicts(ctx, dir, config, abort);
+      const { report: mergeReport } = await mergeAndResolveConflicts(ctx, dir, config, abort);
+      conflictResolution = mergeReport?.conflictResolution;
       await commitWithRepair(ctx, dir, abort, { skipSocket: true });
       autoMerged = true;
     }
   }
   await pushBranch(ctx, dir);
   const pr = await openPullRequest(ctx);
-  return { outcome: pr ? { kind: "pr", pr } : { kind: "pushed" }, autoMerged };
+  return { outcome: pr ? { kind: "pr", pr } : { kind: "pushed" }, autoMerged, conflictResolution };
 }
 async function mergeAndResolveConflicts(ctx, dir, config, abort) {
   const { conflicted } = await mergeInMergeBranch(ctx, dir);
@@ -1397,7 +1451,7 @@ async function mergeAndResolveConflicts(ctx, dir, config, abort) {
       `Could not fully resolve the merge \u2014 ${unresolved.length} file(s) still contain conflict markers: ${unresolved.join(", ")}`
     );
   }
-  return { resolved: true, text: result.text.trim() || null };
+  return { resolved: true, text: result.text.trim() || null, report: result.report ?? void 0 };
 }
 async function commitWithRepair(ctx, dir, abort, opts = {}) {
   for (let attempt = 1; ; attempt++) {
@@ -1527,7 +1581,7 @@ async function processChatJob(ctx, dir, config, abort) {
     console.log(`  \u2026job ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
     return { text: reply, widgets: result.widgets };
   }
-  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync4(join6(dir, ".flumecode", "wiki"));
   let documented = false;
   if (ctx.permissionMode !== "plan" && wikiExists && await hasChanges(dir)) {
     try {
@@ -1616,7 +1670,7 @@ ${reply}`;
 
 > \u26A0\uFE0F Dependencies failed to install (\`${installResult.manager}\`); tests may not have run.`;
   }
-  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync4(join6(dir, ".flumecode", "wiki"));
   let documented = false;
   if (wikiExists && await hasChanges(dir)) {
     try {
@@ -1636,12 +1690,13 @@ ${reply}`;
   } else if (!wikiExists) {
     console.log(`  no .flumecode/wiki \u2014 skipping wiki reconcile for ${ctx.jobId}`);
   }
-  const { outcome, autoMerged } = await pushAndOpenPr(ctx, dir, config, abort, {
+  const { outcome, autoMerged, conflictResolution } = await pushAndOpenPr(ctx, dir, config, abort, {
     rebase: !resumed
   });
   reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented, autoMerged });
   const lintPlugins = getSocketResults();
-  const finalReport = report && lintPlugins.length ? { ...report, lint: { plugins: lintPlugins } } : report;
+  const reportWithConflict = report && conflictResolution ? { ...report, conflictResolution } : report;
+  const finalReport = reportWithConflict && lintPlugins.length ? { ...reportWithConflict, lint: { plugins: lintPlugins } } : reportWithConflict;
   return {
     text: reply,
     widgets: [],
@@ -1661,8 +1716,8 @@ async function processReviseJob(ctx, dir, resumed, config, abort) {
     maxTurns: ORCHESTRATOR_MAX_TURNS,
     abortController: abort
   });
-  const summary = result.text.trim();
-  let reply = summary || "(the agent produced no reply)";
+  const report = result.report ?? void 0;
+  let reply = (report ? renderReport(report) : result.text.trim()) || "(the agent produced no reply)";
   if (result.plans?.length) reply = result.plans[0] ?? reply;
   if (installResult.status === "failed") {
     reply += `
@@ -1673,7 +1728,7 @@ async function processReviseJob(ctx, dir, resumed, config, abort) {
     console.log(`  \u2026revise ${ctx.jobId} posted ${result.widgets.length} widget(s); awaiting reply`);
     return { text: reply, widgets: result.widgets };
   }
-  const wikiExists = existsSync4(join5(dir, ".flumecode", "wiki"));
+  const wikiExists = existsSync4(join6(dir, ".flumecode", "wiki"));
   let documented = false;
   if (wikiExists && await hasChanges(dir)) {
     try {
@@ -1693,15 +1748,19 @@ async function processReviseJob(ctx, dir, resumed, config, abort) {
   } else if (!wikiExists) {
     console.log(`  no .flumecode/wiki \u2014 skipping wiki reconcile for ${ctx.jobId}`);
   }
-  const { outcome, autoMerged } = await pushAndOpenPr(ctx, dir, config, abort, {
+  const { outcome, autoMerged, conflictResolution } = await pushAndOpenPr(ctx, dir, config, abort, {
     rebase: !resumed
   });
   if (outcome.kind !== "none") {
     reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch, documented, autoMerged });
   }
+  const lintPlugins = getSocketResults();
+  const reportWithConflict = report && conflictResolution ? { ...report, conflictResolution } : report;
+  const finalReport = reportWithConflict && lintPlugins.length ? { ...reportWithConflict, lint: { plugins: lintPlugins } } : reportWithConflict;
   return {
     text: reply,
     widgets: [],
+    ...finalReport ? { report: finalReport } : {},
     ...outcome.kind === "pr" ? { pr: outcome.pr } : {},
     ...result.plans?.length ? { plans: result.plans } : {}
   };
@@ -1710,8 +1769,13 @@ async function processResolveJob(ctx, dir, config, abort) {
   console.log(`
 \u25B6 Resolve ${ctx.jobId} \u2014 ${ctx.repo.fullName}: "${jobTitle(ctx)}"`);
   const installResult = await installDependencies(dir);
-  const { resolved, text } = await mergeAndResolveConflicts(ctx, dir, config, abort);
-  let reply = resolved ? text || "(the agent produced no report)" : `Merged \`${ctx.repo.mergeBranch ?? "the merge branch"}\` into \`${ctx.repo.checkoutBranch}\` cleanly \u2014 there were no conflicts to resolve.`;
+  const { resolved, text, report } = await mergeAndResolveConflicts(ctx, dir, config, abort);
+  let reply;
+  if (resolved) {
+    reply = report ? renderReport(report) : text || "(the agent produced no report)";
+  } else {
+    reply = `Merged \`${ctx.repo.mergeBranch ?? "the merge branch"}\` into \`${ctx.repo.checkoutBranch}\` cleanly \u2014 there were no conflicts to resolve.`;
+  }
   if (installResult.status === "failed") {
     reply += `
 
@@ -1723,7 +1787,7 @@ async function processResolveJob(ctx, dir, config, abort) {
   const pr = await openPullRequest(ctx);
   const outcome = pr ? { kind: "pr", pr } : { kind: "pushed" };
   reply += outcomeBanner(outcome, { branch: ctx.repo.checkoutBranch });
-  return { text: reply, widgets: [], ...pr ? { pr } : {} };
+  return { text: reply, widgets: [], ...report ? { report } : {}, ...pr ? { pr } : {} };
 }
 async function processReleaseJob(ctx, dir, resumed, config, abort) {
   console.log(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumecode/runner",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "type": "module",
   "description": "FlumeCode local runner — claims jobs and drives your local Claude Code against a real checkout.",
   "bin": {

package/skills-plugin/skills/format-code-plugin-generator/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: format-code-plugin-generator
+description: >-
+  Generate a concrete plan to install the FlumeCode Format plugin for THIS repo —
+  a .flumecode/plugins/format-code/ manifest wired to the pre-commit socket that
+  auto-formats code (prettier --write) so changes ride into the commit.
+---
+
+# format-code-plugin-generator
+
+You generate a concrete, repo-specific plan to install the FlumeCode Format
+plugin. You work **read-only**: inspect the repo and produce a plan via
+`submit_plan`; never edit files.
+
+## Orient yourself first
+
+Before producing the plan, inspect:
+
+1. `.flumecode/wiki/README.md` and `components/plugins.md` (if present) for context.
+2. `package.json` `scripts` — look for `format`, `format:write`, `prettier` references.
+3. `.prettierrc*` — confirm Prettier is configured.
+4. `.husky/pre-commit` — find the existing formatting step this plugin replaces.
+
+From this, determine the **exact shell command** the `run` script should execute
+(e.g. `pnpm format`). Do not hard-code — derive from the repo.
+
+## Produce the plan
+
+Call `submit_plan` **once**, passing a `plans` array with one entry whose steps
+instruct the implementer to create:
+
+### Artifact — `.flumecode/plugins/format-code/plugin.json`
+
+```json
+{
+  "key": "format-code",
+  "socket": "pre-commit",
+  "run": "<detected format write command>"
+}
+```
+
+Derive `run` from the repo's detected commands (e.g. `pnpm format`). Do not hard-code — include the actual commands discovered in the Orient step.
+
+### Manifest shape
+
+The manifest `plugin.json` must have exactly these fields:
+
+```
+{ key, socket, run }
+```
+
+This is the shape the FlumeCode plugin loader expects.
+
+### Acceptance criteria the plan must include
+
+- `.flumecode/plugins/format-code/plugin.json` exists with `key: "format-code"`, `socket: "pre-commit"`, and `run` set to the detected write-format command.
+- The `run` command reformats files in place and exits 0; reformatted files are staged and included in the commit.
+
+## Always
+
+- Stay read-only. Produce the plan via `submit_plan`; never edit files.
+- The plan must be specific enough for an `implement-plan` run to execute
+  without re-deriving the commands — include the actual detected commands in
+  the step descriptions and artifact content.

package/skills-plugin/skills/request-to-plan/SKILL.md

@@ -66,9 +66,10 @@ Field-by-field guidance:
   and nothing more.
 - **`assumptions`** — anything you decided during investigation (including
   unanswered defaults from Phase 1).
+- **`requirements`** — **required; at least 1 item.** Plain-language statements of what this change must accomplish and why, written so a non-technical reader can follow them. Distinct from `acceptanceCriteria`: requirements explain intent and rationale; acceptance criteria are the machine-checkable proof. At least 1 item required.
 - **`steps`** — an ordered list. For each step provide:
   - **`title`** — a concise imperative phrase naming the step (e.g. "Add submit_plan schema to plan.ts").
-  - **`description`** — what changes and why: the concrete change being made and the rationale for it. Use concrete file references (`path/to/file.ts`) and name the functions/symbols involved.
+  - **`description`** — an array of bullet points that help the reviewer understand the upcoming `pseudoCode` and decide whether the plan and design are correct. Each item is a distinct, self-contained point about what is changing and why — not a single paragraph, and not a line-by-line restatement of the pseudo code. Use concrete file references (`path/to/file.ts`) and name the functions/symbols involved. Apply inline-code formatting to all identifiers.
   - **`pseudoCode`** — an array of `{ file, pseudoCode }` entries. Provide an entry for every file the step touches **except** documentation files (SKILL.md, README.md, wiki pages, etc.). `pseudoCode` is optional in the schema but expected for all non-documentation files. Each entry names the file path and contains pseudo code that precisely describes the changes to make in that file.
 - **`acceptanceCriteria`** — **required; at least 2 items.** Each criterion must
   be a concrete, deterministically-checkable condition that a third party can verify

package/skills-plugin/skills/resolve-merge-conflict/SKILL.md

@@ -93,8 +93,16 @@ before you finish. (You don't need to `git add`; the runner stages and commits f
 
 ## Your final reply
 
-Your last message **is** the report posted to the session thread. Write it for the
-user: list which files conflicted and, briefly, how you resolved each, plus how you
-verified (build/tests). Wrap conflicted file names and code identifiers in inline
-backticks per the `# Technical Writing` section. The runner appends the pull-request
-link, so don't add one.
+Call **`submit_report`** with the structured report. Fields:
+
+- `summary`: one or two sentences on what the resolve run did.
+- `filesChanged`: markdown list of files changed (from `git --no-pager diff --stat`).
+- `codeQuality`: markdown: whether build/tests passed, any quality observations.
+- `caveats`: markdown: anything deferred, risky, or worth the user's attention. Write `None.` if nothing.
+- `acceptanceCriteria`: **leave this empty (`[]`)** — there is no plan to verify for a resolve run.
+- `conflictResolution`: **required** — a markdown section, one paragraph or bullet per conflicted
+  file, explaining which side you kept and why (or how you merged both intents). Wrap file names
+  and code identifiers in inline backticks. This is what the user reads to understand how each
+  conflict was integrated.
+
+The runner renders the report and appends the pull-request link — do not add one yourself.

package/skills-plugin/skills/revise-implementation/SKILL.md

@@ -41,7 +41,7 @@ actual code. Pick exactly one:
 - **Re-plan** — the request meaningfully changes scope or direction, enough that a
   fresh plan should be agreed before building. Call **`submit_plan`** with a `plans[]` array
   containing the revised structured fields (same per-plan shape as the request-to-plan skill:
-  `scope`, `goal`, `assumptions`, `steps`, `acceptanceCriteria` — at least 2 —, `risks`,
+  `scope`, `goal`, `assumptions`, `requirements` — at least 1 —, `steps`, `acceptanceCriteria` — at least 2 —, `risks`,
   `outOfScope`). Include only one entry for a revise turn. The runner posts it as a revision
   the user can accept; make no code changes this turn.
 - **Implement** — the request is clear and reasonable. Make the change (via
@@ -80,13 +80,13 @@ essentials:
 Your last message **is** the comment posted to the plan thread — write it for the
 user:
 
-- **Implemented:** a short report — what you changed and why, which files, and the
-  verification results: list each build/test command that was run and its final
-  pass/fail result (or note that no build/test setup was found). Base "what changed"
-  and "which files" on the actual `git --no-pager diff` (`--stat` for the file
-  list), not on what a subagent claimed; if the diff is empty, say nothing was
-  changed rather than describing edits that aren't there. The runner appends the
-  pull-request link, so don't add one.
+- **Implemented:** call **`submit_report`** with the structured report, exactly as
+  `implement-plan` does. Include one `acceptanceCriteria` entry per plan AC (with a
+  met / not_met / unclear verdict and the diff hunk(s) that prove it), plus the four
+  required markdown sections (`summary`, `filesChanged`, `codeQuality`, `caveats`).
+  Base `filesChanged` and evidence on the actual `git --no-pager diff`, not on what
+  a subagent claimed; if the diff is empty, say nothing was changed. The runner
+  renders the report and appends the pull-request link — do not add one yourself.
 - **Clarify / push back:** your question or reasoning, as prose (plus any widget).
 - **Re-plan:** you called `submit_plan`; the rendered plan is posted automatically,
   so keep any extra reply text minimal.

package/skills-plugin/skills/unit-test-plugin-generator/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: unit-test-plugin-generator
+description: >-
+  Generate a concrete plan to install the FlumeCode Unit Test plugin for THIS repo —
+  a .flumecode/plugins/unit-test/ manifest wired to the pre-commit socket that runs
+  the repo's unit tests and emits a JSON report the runner parses into pass/fail counts.
+---
+
+# unit-test-plugin-generator
+
+You generate a concrete, repo-specific plan to install the FlumeCode Unit Test
+plugin. You work **read-only**: inspect the repo and produce a plan via
+`submit_plan`; never edit files.
+
+## Orient yourself first
+
+Before producing the plan, inspect:
+
+1. `.flumecode/wiki/README.md` and `components/plugins.md` (if present) for context.
+2. `package.json` `scripts` — look for `test`, `test:unit`, or similar test commands.
+3. `vitest.config.*` — to detect Vitest as the test runner.
+4. `jest.config.*` — to detect Jest as the test runner.
+
+From this, determine:
+
+- Which test runner is in use (Vitest or Jest).
+- The **exact shell command** that runs the tests and writes a JSON report file (e.g. `pnpm vitest run --reporter=json --outputFile=.flumecode/tmp/unit-test-report.json`). Do not hard-code — derive from the repo.
+
+## Produce the plan
+
+Call `submit_plan` **once**, passing a `plans` array with one entry whose steps
+instruct the implementer to:
+
+### Artifact 1 — `.flumecode/plugins/unit-test/plugin.json`
+
+```json
+{
+  "key": "unit-test",
+  "socket": "pre-commit",
+  "run": "<detected command, e.g. pnpm vitest run --reporter=json --outputFile=.flumecode/tmp/unit-test-report.json>",
+  "report": { "file": ".flumecode/tmp/unit-test-report.json", "format": "jest" }
+}
+```
+
+Derive `run` from the repo's detected test runner and scripts. Do not hard-code —
+include the actual commands discovered in the Orient step.
+
+### Artifact 2 — `.gitignore` update
+
+Add `.flumecode/tmp/` to `.gitignore` so the transient JSON report file is never committed.
+
+### Manifest shape
+
+The manifest `plugin.json` must have exactly these fields:
+
+```
+{ key, socket, run, report }
+```
+
+where `report.file` points to the JSON report output path (repo-relative) and
+`report.format` is `"jest"` (Vitest's JSON reporter uses the same schema).
+
+### Acceptance criteria the plan must include
+
+- `.flumecode/plugins/unit-test/plugin.json` exists with `key: "unit-test"`, `socket: "pre-commit"`, `run` set to the detected test command that writes a JSON report, and `report` set to `{ "file": ".flumecode/tmp/unit-test-report.json", "format": "jest" }`.
+- The `run` command exits non-zero on any test failure and writes the JSON report file.
+- `.flumecode/tmp/` is present in `.gitignore`.
+
+## Always
+
+- Stay read-only. Produce the plan via `submit_plan`; never edit files.
+- The plan must be specific enough for an `implement-plan` run to execute
+  without re-deriving the commands — include the actual detected commands in
+  the step descriptions and artifact content.