@quinteroac/agents-coding-toolkit 0.1.0-preview → 0.2.0

package/src/commands/create-prototype.ts

@@ -1,59 +1,142 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { $ as dollar } from "bun";
-import { z } from "zod";
 
 import { PrdSchema } from "../../scaffold/schemas/tmpl_prd";
+import {
+  PrototypeProgressSchema,
+  type PrototypeProgress,
+} from "../../scaffold/schemas/tmpl_prototype-progress";
 import {
   buildPrompt,
   invokeAgent,
   loadSkill,
+  type AgentInvokeOptions,
   type AgentProvider,
+  type AgentResult,
 } from "../agent";
+import { assertGuardrail } from "../guardrail";
+import { defaultReadLine } from "../readline";
+import { idsMatchExactly, sortedValues } from "../progress-utils";
 import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
+import { writeJsonArtifact, type WriteJsonArtifactFn } from "../write-json-artifact";
 
 export interface CreatePrototypeOptions {
   provider: AgentProvider;
   iterations?: number;
   retryOnFail?: number;
   stopOnCritical?: boolean;
+  force?: boolean;
+}
+
+const DECLINE_DIRTY_TREE_ABORT_MESSAGE = "Aborted. Commit or discard your changes and re-run `bun nvst create prototype`.";
+const DIRTY_TREE_COMMIT_PROMPT = "Working tree has uncommitted changes. Stage and commit them now to proceed? [y/N]";
+
+interface CreatePrototypeDeps {
+  invokeAgentFn: (options: AgentInvokeOptions) => Promise<AgentResult>;
+  loadSkillFn: (projectRoot: string, skillName: string) => Promise<string>;
+  checkGhAvailableFn: (projectRoot: string) => Promise<boolean>;
+  createPullRequestFn: (
+    projectRoot: string,
+    title: string,
+    body: string,
+  ) => Promise<{ exitCode: number; stderr: string }>;
+  logFn: (message: string) => void;
+  warnFn: (message: string) => void;
+  promptDirtyTreeCommitFn: (question: string) => Promise<boolean>;
+  gitAddAndCommitFn: (projectRoot: string, commitMessage: string) => Promise<void>;
+  writeJsonArtifactFn: WriteJsonArtifactFn;
+}
+
+const defaultDeps: CreatePrototypeDeps = {
+  invokeAgentFn: invokeAgent,
+  loadSkillFn: loadSkill,
+  checkGhAvailableFn: async (projectRoot) => {
+    const proc = Bun.spawn(["gh", "--version"], {
+      cwd: projectRoot,
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return (await proc.exited) === 0;
+  },
+  createPullRequestFn: async (projectRoot, title, body) => {
+    const result = await dollar`gh pr create --title ${title} --body ${body}`
+      .cwd(projectRoot)
+      .nothrow()
+      .quiet();
+    return {
+      exitCode: result.exitCode,
+      stderr: result.stderr.toString().trim(),
+    };
+  },
+  logFn: console.log,
+  warnFn: console.warn,
+  promptDirtyTreeCommitFn: promptForDirtyTreeCommit,
+  gitAddAndCommitFn: runGitAddAndCommit,
+  writeJsonArtifactFn: writeJsonArtifact,
+};
+
+type ReadLineFn = () => Promise<string | null>;
+type WriteFn = (message: string) => void;
+type IsTTYFn = () => boolean;
+
+function defaultWrite(message: string): void {
+  process.stdout.write(`${message}\n`);
 }
 
-const ProgressEntrySchema = z.object({
-  use_case_id: z.string(),
-  status: z.enum(["pending", "failed", "completed"]),
-  attempt_count: z.number().int().nonnegative(),
-  last_agent_exit_code: z.number().int().nullable(),
-  quality_checks: z.array(
-    z.object({
-      command: z.string(),
-      exit_code: z.number().int(),
-    }),
-  ),
-  last_error_summary: z.string(),
-  updated_at: z.string(),
-});
-
-export const PrototypeProgressSchema = z.object({
-  entries: z.array(ProgressEntrySchema),
-});
-
-function sortedValues(values: string[]): string[] {
-  return [...values].sort((a, b) => a.localeCompare(b));
+function defaultIsTTY(): boolean {
+  return process.stdin.isTTY === true;
 }
 
-function idsMatchExactly(left: string[], right: string[]): boolean {
-  if (left.length !== right.length) {
+export async function promptForDirtyTreeCommit(
+  question: string,
+  readLineFn: ReadLineFn = defaultReadLine,
+  writeFn: WriteFn = defaultWrite,
+  isTTYFn: IsTTYFn = defaultIsTTY,
+): Promise<boolean> {
+  if (!isTTYFn()) {
     return false;
   }
 
-  for (let i = 0; i < left.length; i += 1) {
-    if (left[i] !== right[i]) {
-      return false;
-    }
+  writeFn(question);
+
+  let line: string | null;
+  try {
+    line = await readLineFn();
+  } catch {
+    line = null;
+  }
+
+  return line !== null && (line.trim() === "y" || line.trim() === "Y");
+}
+
+async function runGitAddAndCommit(projectRoot: string, commitMessage: string): Promise<void> {
+  const addResult = await dollar`git add -A`.cwd(projectRoot).nothrow().quiet();
+  if (addResult.exitCode !== 0) {
+    throw new Error(`Pre-prototype commit failed:\n${addResult.stderr.toString().trim()}`);
   }
 
-  return true;
+  const commitResult = await dollar`git commit -m ${commitMessage}`.cwd(projectRoot).nothrow().quiet();
+  if (commitResult.exitCode !== 0) {
+    throw new Error(`Pre-prototype commit failed:\n${commitResult.stderr.toString().trim()}`);
+  }
+}
+
+export async function runPrePrototypeCommit(
+  projectRoot: string,
+  iteration: string,
+  gitAddAndCommitFn: (projectRoot: string, commitMessage: string) => Promise<void> = runGitAddAndCommit,
+): Promise<void> {
+  const commitMessage = `chore: pre-prototype commit it_${iteration}`;
+  try {
+    await gitAddAndCommitFn(projectRoot, commitMessage);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    if (reason.startsWith("Pre-prototype commit failed:\n")) {
+      throw error;
+    }
+    throw new Error(`Pre-prototype commit failed:\n${reason}`);
+  }
 }
 
 function parseQualityChecks(projectContextContent: string): string[] {
@@ -103,9 +186,14 @@ function parseQualityChecks(projectContextContent: string): string[] {
     .filter((line) => line.length > 0);
 }
 
-export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<void> {
+export async function runCreatePrototype(
+  opts: CreatePrototypeOptions,
+  deps: Partial<CreatePrototypeDeps> = {},
+): Promise<void> {
+  const mergedDeps: CreatePrototypeDeps = { ...defaultDeps, ...deps };
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
+  const force = opts.force ?? false;
 
   if (opts.iterations !== undefined && (!Number.isInteger(opts.iterations) || opts.iterations < 1)) {
     throw new Error(
@@ -148,6 +236,8 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
     );
   }
 
+  let prePrototypeCommitDone = false;
+
   if (state.current_phase === "define") {
     if (
       state.phases.define.prd_generation.status === "completed" &&
@@ -160,39 +250,59 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
         );
       }
       if (workingTreeBeforeTransition.stdout.toString().trim().length > 0) {
-        throw new Error(
-          "Git working tree is dirty. Commit your changes or discard them before running `bun nvst create prototype` again.",
+        const shouldProceed = await mergedDeps.promptDirtyTreeCommitFn(
+          DIRTY_TREE_COMMIT_PROMPT,
         );
+        if (!shouldProceed) {
+          mergedDeps.logFn(DECLINE_DIRTY_TREE_ABORT_MESSAGE);
+          return;
+        }
+        await runPrePrototypeCommit(projectRoot, iteration, mergedDeps.gitAddAndCommitFn);
+        prePrototypeCommitDone = true;
       }
       state.current_phase = "prototype";
       await writeState(projectRoot, state);
     } else {
-      throw new Error(
+      await assertGuardrail(
+        state,
+        true,
         "Cannot create prototype: current_phase is define and prerequisites are not met. Complete define phase and run `bun nvst create project-context --agent <provider>` then `bun nvst approve project-context` first.",
+        { force },
       );
     }
   } else if (state.current_phase !== "prototype") {
-    throw new Error(
+    await assertGuardrail(
+      state,
+      true,
       "Cannot create prototype: current_phase must be define (with approved PRD) or prototype. Complete define phase and run `bun nvst create project-context --agent <provider>` then `bun nvst approve project-context` first.",
+      { force },
     );
   }
 
-  if (state.phases.prototype.project_context.status !== "created") {
-    throw new Error(
-      "Cannot create prototype: prototype.project_context.status must be created. Run `bun nvst create project-context --agent <provider>` and `bun nvst approve project-context` first.",
-    );
-  }
+  await assertGuardrail(
+    state,
+    state.phases.prototype.project_context.status !== "created",
+    "Cannot create prototype: prototype.project_context.status must be created. Run `bun nvst create project-context --agent <provider>` and `bun nvst approve project-context` first.",
+    { force },
+  );
 
-  const workingTreeAfterPhase = await dollar`git status --porcelain`.cwd(projectRoot).nothrow().quiet();
-  if (workingTreeAfterPhase.exitCode !== 0) {
-    throw new Error(
-      "Unable to verify git working tree status. Ensure this directory is a git repository and git is installed.",
-    );
-  }
-  if (workingTreeAfterPhase.stdout.toString().trim().length > 0) {
-    throw new Error(
-      "Git working tree is dirty. Commit your changes or discard them before running `bun nvst create prototype` again.",
-    );
+  if (!prePrototypeCommitDone) {
+    const workingTreeAfterPhase = await dollar`git status --porcelain`.cwd(projectRoot).nothrow().quiet();
+    if (workingTreeAfterPhase.exitCode !== 0) {
+      throw new Error(
+        "Unable to verify git working tree status. Ensure this directory is a git repository and git is installed.",
+      );
+    }
+    if (workingTreeAfterPhase.stdout.toString().trim().length > 0) {
+      const shouldProceed = await mergedDeps.promptDirtyTreeCommitFn(
+        DIRTY_TREE_COMMIT_PROMPT,
+      );
+      if (!shouldProceed) {
+        mergedDeps.logFn(DECLINE_DIRTY_TREE_ABORT_MESSAGE);
+        return;
+      }
+      await runPrePrototypeCommit(projectRoot, iteration, mergedDeps.gitAddAndCommitFn);
+    }
   }
 
   const branchName = `feature/it_${iteration}`;
@@ -220,7 +330,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
   const progressFileName = `it_${iteration}_progress.json`;
   const progressPath = join(projectRoot, FLOW_REL_DIR, progressFileName);
   const storyIds = sortedValues(prdValidation.data.userStories.map((story) => story.id));
-  let progressData: z.infer<typeof PrototypeProgressSchema>;
+  let progressData: PrototypeProgress;
 
   if (await exists(progressPath)) {
     let parsedProgress: unknown;
@@ -263,7 +373,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
       })),
     };
 
-    await writeFile(progressPath, `${JSON.stringify(progress, null, 2)}\n`, "utf8");
+    await mergedDeps.writeJsonArtifactFn(progressPath, PrototypeProgressSchema, progress);
     progressData = progress;
   }
 
@@ -273,7 +383,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
   });
 
   if (eligibleStories.length === 0) {
-    console.log("No pending or failed user stories to implement. Exiting without changes.");
+    mergedDeps.logFn("No pending or failed user stories to implement. Exiting without changes.");
     return;
   }
 
@@ -285,7 +395,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
 
   let skillTemplate: string;
   try {
-    skillTemplate = await loadSkill(projectRoot, "implement-user-story");
+    skillTemplate = await mergedDeps.loadSkillFn(projectRoot, "implement-user-story");
   } catch {
     throw new Error(
       "Required skill missing: expected .agents/skills/implement-user-story/SKILL.md.",
@@ -324,7 +434,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
         user_story: JSON.stringify(story, null, 2),
       });
 
-      const agentResult = await invokeAgent({
+      const agentResult = await mergedDeps.invokeAgentFn({
         provider: opts.provider,
         prompt,
         cwd: projectRoot,
@@ -358,7 +468,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
         entry.last_error_summary = "Agent or quality check failed";
       }
 
-      await writeFile(progressPath, `${JSON.stringify(progressData, null, 2)}\n`, "utf8");
+      await mergedDeps.writeJsonArtifactFn(progressPath, PrototypeProgressSchema, progressData);
 
       if (allPassed) {
         const commitMessage = `feat: implement ${story.id} - ${story.title}`;
@@ -371,9 +481,9 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
           entry.status = "failed";
           entry.last_error_summary = "Git commit failed";
           entry.updated_at = new Date().toISOString();
-          await writeFile(progressPath, `${JSON.stringify(progressData, null, 2)}\n`, "utf8");
+          await mergedDeps.writeJsonArtifactFn(progressPath, PrototypeProgressSchema, progressData);
 
-          console.log(
+          mergedDeps.logFn(
             `iteration=it_${iteration} story=${story.id} attempt=${entry.attempt_count} outcome=commit_failed`,
           );
 
@@ -381,7 +491,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
             haltedByCritical = true;
           }
         } else {
-          console.log(
+          mergedDeps.logFn(
             `iteration=it_${iteration} story=${story.id} attempt=${entry.attempt_count} outcome=passed`,
           );
         }
@@ -389,7 +499,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
         break;
       }
 
-      console.log(
+      mergedDeps.logFn(
         `iteration=it_${iteration} story=${story.id} attempt=${entry.attempt_count} outcome=failed`,
       );
 
@@ -413,13 +523,25 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
   await writeState(projectRoot, state);
 
   if (storiesAttempted === 0) {
-    console.log("No user stories attempted.");
+    mergedDeps.logFn("No user stories attempted.");
     return;
   }
 
   if (allCompleted) {
-    console.log("Prototype implementation completed for all user stories.");
+    const ghAvailable = await mergedDeps.checkGhAvailableFn(projectRoot);
+    if (!ghAvailable) {
+      mergedDeps.logFn("gh CLI not found — skipping PR creation");
+    } else {
+      const prTitle = `feat: prototype it_${iteration}`;
+      const prBody = `Prototype for iteration it_${iteration}`;
+      const prResult = await mergedDeps.createPullRequestFn(projectRoot, prTitle, prBody);
+      if (prResult.exitCode !== 0) {
+        const suffix = prResult.stderr.length > 0 ? `: ${prResult.stderr}` : "";
+        mergedDeps.warnFn(`gh pr create failed (non-fatal)${suffix}`);
+      }
+    }
+    mergedDeps.logFn("Prototype implementation completed for all user stories.");
   } else {
-    console.log("Prototype implementation paused with remaining pending or failed stories.");
+    mergedDeps.logFn("Prototype implementation paused with remaining pending or failed stories.");
   }
 }

package/src/commands/create-test-plan.ts

@@ -10,8 +10,9 @@ import {
   type AgentProvider,
   type AgentResult,
 } from "../agent";
+import { assertGuardrail } from "../guardrail";
 import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
-import { TestPlanSchema, type TestPlan } from "../../schemas/test-plan";
+import { TestPlanSchema, type TestPlan } from "../../scaffold/schemas/tmpl_test-plan";
 
 export interface CreateTestPlanOptions {
   provider: AgentProvider;
@@ -155,11 +156,12 @@ export async function runCreateTestPlan(
   const state = await readState(projectRoot);
   const mergedDeps: CreateTestPlanDeps = { ...defaultDeps, ...deps };
 
-  if (state.phases.prototype.project_context.status !== "created") {
-    throw new Error(
-      "Cannot create test plan: prototype.project_context.status must be created. Run `bun nvst approve project-context` first.",
-    );
-  }
+  await assertGuardrail(
+    state,
+    state.phases.prototype.project_context.status !== "created",
+    "Cannot create test plan: prototype.project_context.status must be created. Run `bun nvst approve project-context` first.",
+    { force: opts.force },
+  );
 
   const iteration = state.current_iteration;
   const fileName = `it_${iteration}_test-plan.md`;

package/src/commands/define-refactor-plan.test.ts

@@ -0,0 +1,208 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { AgentResult } from "../agent";
+import { readState, writeState } from "../state";
+import { runDefineRefactorPlan } from "./define-refactor-plan";
+
+async function createProjectRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "nvst-define-refactor-plan-"));
+}
+
+async function withCwd<T>(cwd: string, fn: () => Promise<T>): Promise<T> {
+  const previous = process.cwd();
+  process.chdir(cwd);
+  try {
+    return await fn();
+  } finally {
+    process.chdir(previous);
+  }
+}
+
+async function seedState(
+  projectRoot: string,
+  stateOverrides: {
+    currentPhase?: "define" | "prototype" | "refactor";
+    refactorPlanStatus?: "pending" | "pending_approval" | "approved";
+    prototypeApproved?: boolean;
+  } = {},
+): Promise<void> {
+  const currentPhase = stateOverrides.currentPhase ?? "refactor";
+  const refactorPlanStatus = stateOverrides.refactorPlanStatus ?? "pending";
+  const prototypeApproved = stateOverrides.prototypeApproved ?? true;
+
+  await mkdir(join(projectRoot, ".agents", "flow"), { recursive: true });
+
+  await writeState(projectRoot, {
+    current_iteration: "000013",
+    current_phase: currentPhase,
+    phases: {
+      define: {
+        requirement_definition: { status: "approved", file: "it_000013_product-requirement-document.md" },
+        prd_generation: { status: "completed", file: "it_000013_PRD.json" },
+      },
+      prototype: {
+        project_context: { status: "created", file: ".agents/PROJECT_CONTEXT.md" },
+        test_plan: { status: "created", file: "it_000013_test-plan.md" },
+        tp_generation: { status: "created", file: "it_000013_TEST-PLAN.json" },
+        prototype_build: { status: "created", file: "it_000013_progress.json" },
+        test_execution: { status: "completed", file: "it_000013_test-execution-report.json" },
+        prototype_approved: prototypeApproved,
+      },
+      refactor: {
+        evaluation_report: { status: "pending", file: null },
+        refactor_plan: { status: refactorPlanStatus, file: null },
+        refactor_execution: { status: "pending", file: null },
+        changelog: { status: "pending", file: null },
+      },
+    },
+    last_updated: "2026-02-26T00:00:00.000Z",
+    updated_by: "seed",
+    history: [],
+  });
+}
+
+const createdRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(createdRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("define refactor-plan command", () => {
+  test("registers define refactor-plan command in CLI dispatch", async () => {
+    const source = await readFile(join(process.cwd(), "src", "cli.ts"), "utf8");
+
+    expect(source).toContain('import { runDefineRefactorPlan } from "./commands/define-refactor-plan";');
+    expect(source).toContain('if (subcommand === "refactor-plan") {');
+    expect(source).toContain("await runDefineRefactorPlan({ provider, force });");
+  });
+
+  test("rejects when prototype_approved is false", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { prototypeApproved: false });
+
+    await withCwd(projectRoot, async () => {
+      await expect(runDefineRefactorPlan({ provider: "codex" })).rejects.toThrow(
+        "Cannot define refactor plan: phases.prototype.prototype_approved must be true",
+      );
+    });
+  });
+
+  test("allows bypassing prototype_approved guard with force", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { prototypeApproved: false });
+
+    await withCwd(projectRoot, async () => {
+      await runDefineRefactorPlan(
+        { provider: "codex", force: true },
+        {
+          loadSkillFn: async () => "Refactor planning instructions",
+          invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          nowFn: () => new Date("2026-02-26T10:00:00.000Z"),
+        },
+      );
+    });
+
+    const state = await readState(projectRoot);
+    expect(state.phases.refactor.evaluation_report.status).toBe("created");
+    expect(state.phases.refactor.refactor_plan.status).toBe("pending_approval");
+  });
+
+  test("rejects when current_phase is define", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { currentPhase: "define", prototypeApproved: true });
+
+    await withCwd(projectRoot, async () => {
+      await expect(runDefineRefactorPlan({ provider: "codex" })).rejects.toThrow(
+        "Cannot define refactor plan: current_phase must be 'prototype' or 'refactor'",
+      );
+    });
+  });
+
+  test("accepts when current_phase is prototype and prototype_approved is true, transitions to refactor", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { currentPhase: "prototype" });
+
+    await withCwd(projectRoot, async () => {
+      await runDefineRefactorPlan(
+        { provider: "codex" },
+        {
+          loadSkillFn: async () => "Refactor planning instructions",
+          invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          nowFn: () => new Date("2026-02-26T10:00:00.000Z"),
+        },
+      );
+    });
+
+    const state = await readState(projectRoot);
+    expect(state.current_phase).toBe("refactor");
+    expect(state.phases.refactor.evaluation_report.status).toBe("created");
+    expect(state.phases.refactor.refactor_plan.status).toBe("pending_approval");
+  });
+
+  test("rejects when refactor.refactor_plan.status is not pending", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { refactorPlanStatus: "approved" });
+
+    await withCwd(projectRoot, async () => {
+      await expect(runDefineRefactorPlan({ provider: "codex" })).rejects.toThrow(
+        "Cannot define refactor plan from status 'approved'. Expected pending.",
+      );
+    });
+  });
+
+  test("loads plan-refactor skill, invokes interactive agent, and persists pending_approval state", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot);
+
+    let loadedSkill = "";
+    let invocation: { interactive: boolean | undefined; prompt: string } | undefined;
+
+    await withCwd(projectRoot, async () => {
+      await runDefineRefactorPlan(
+        { provider: "codex" },
+        {
+          loadSkillFn: async (_root, skillName) => {
+            loadedSkill = skillName;
+            return "Refactor planning instructions from SKILL.md";
+          },
+          invokeAgentFn: async (options): Promise<AgentResult> => {
+            invocation = {
+              interactive: options.interactive,
+              prompt: options.prompt,
+            };
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+          nowFn: () => new Date("2026-02-26T10:00:00.000Z"),
+        },
+      );
+    });
+
+    expect(loadedSkill).toBe("plan-refactor");
+    if (invocation === undefined) {
+      throw new Error("Agent invocation was not captured");
+    }
+    expect(invocation.interactive).toBe(true);
+    expect(invocation.prompt).toContain("Refactor planning instructions from SKILL.md");
+    expect(invocation.prompt).toContain("### current_iteration");
+    expect(invocation.prompt).toContain("000013");
+
+    const state = await readState(projectRoot);
+    expect(state.phases.refactor.evaluation_report.status).toBe("created");
+    expect(state.phases.refactor.evaluation_report.file).toBe(
+      "it_000013_evaluation-report.md",
+    );
+    expect(state.phases.refactor.refactor_plan.status).toBe("pending_approval");
+    expect(state.phases.refactor.refactor_plan.file).toBe("it_000013_refactor-plan.md");
+    expect(state.last_updated).toBe("2026-02-26T10:00:00.000Z");
+    expect(state.updated_by).toBe("nvst:define-refactor-plan");
+  });
+});