@quinteroac/agents-coding-toolkit 0.1.0-preview

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

@@ -0,0 +1,381 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm, writeFile } 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 { parseTestPlanForValidation, runCreateTestPlan } from "./create-test-plan";
+
+async function createProjectRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "nvst-create-test-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, projectContextStatus: "pending" | "pending_approval" | "created") {
+  await mkdir(join(projectRoot, ".agents", "flow"), { recursive: true });
+
+  await writeState(projectRoot, {
+    current_iteration: "000003",
+    current_phase: "prototype",
+    phases: {
+      define: {
+        requirement_definition: { status: "approved", file: "it_000003_product-requirement-document.md" },
+        prd_generation: { status: "completed", file: "it_000003_PRD.json" },
+      },
+      prototype: {
+        project_context: { status: projectContextStatus, file: ".agents/PROJECT_CONTEXT.md" },
+        test_plan: { status: "pending", file: null },
+        tp_generation: { status: "pending", file: null },
+        prototype_build: { status: "pending", file: null },
+        test_execution: { status: "pending", file: null },
+        prototype_approved: false,
+      },
+      refactor: {
+        evaluation_report: { status: "pending", file: null },
+        refactor_plan: { status: "pending", file: null },
+        refactor_execution: { status: "pending", file: null },
+        changelog: { status: "pending", file: null },
+      },
+    },
+    last_updated: "2026-02-20T00:00:00.000Z",
+    updated_by: "seed",
+    history: [],
+  });
+
+  await writeFile(join(projectRoot, ".agents", "PROJECT_CONTEXT.md"), "# Context\n", "utf8");
+}
+
+const createdRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(createdRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("create test-plan command", () => {
+  test("registers create test-plan command in CLI dispatch", async () => {
+    const source = await readFile(join(process.cwd(), "src", "cli.ts"), "utf8");
+
+    expect(source).toContain('import { runCreateTestPlan } from "./commands/create-test-plan";');
+    expect(source).toContain('if (subcommand === "test-plan") {');
+    expect(source).toContain("await runCreateTestPlan({ provider, force });");
+  });
+
+  test("loads create-test-plan skill, invokes agent interactively with iteration context, writes state", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "created");
+
+    let loadedSkill = "";
+    let invocation: { interactive: boolean | undefined; prompt: string } | undefined;
+    const outputPath = join(projectRoot, ".agents", "flow", "it_000003_test-plan.md");
+
+    await withCwd(projectRoot, async () => {
+      await runCreateTestPlan(
+        { provider: "codex" },
+        {
+          loadSkillFn: async (_root, skillName) => {
+            loadedSkill = skillName;
+            return [
+              "# Create Test Plan",
+              "Every functional requirement (`FR-N`) must appear in at least one test case `Correlated Requirements` field.",
+              "Use this table column exactly: Correlated Requirements (US-XXX, FR-X).",
+            ].join("\n");
+          },
+          invokeAgentFn: async (options): Promise<AgentResult> => {
+            invocation = {
+              interactive: options.interactive,
+              prompt: options.prompt,
+            };
+            await writeFile(
+              outputPath,
+              [
+                "# Test Plan - Iteration 000003",
+                "## User Story: US-001 - Example Story",
+                "| Test Case ID | Description | Type (unit/integration/e2e) | Mode (automated/manual) | Correlated Requirements (US-XXX, FR-X) | Expected Result |",
+                "|---|---|---|---|---|---|",
+                "| TC-US001-01 | Validate login success | integration | automated | US-001, FR-1 | Login succeeds with valid credentials |",
+                "## Scope",
+                "- Validate login and session behavior",
+                "## Environment and data",
+                "- Node 22 with seeded test user",
+              ].join("\n"),
+              "utf8",
+            );
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+          nowFn: () => new Date("2026-02-21T03:00:00.000Z"),
+        },
+      );
+    });
+
+    expect(loadedSkill).toBe("create-test-plan");
+    if (invocation === undefined) {
+      throw new Error("Agent invocation was not captured");
+    }
+    expect(invocation.interactive).toBe(true);
+    expect(invocation.prompt).toContain("### iteration");
+    expect(invocation.prompt).toContain("000003");
+    expect(invocation.prompt).toContain("Correlated Requirements (US-XXX, FR-X)");
+    expect(invocation.prompt).toContain(
+      "Every functional requirement (`FR-N`) must appear in at least one test case `Correlated Requirements` field.",
+    );
+
+    const content = await readFile(outputPath, "utf8");
+    expect(content).toContain("# Test Plan");
+
+    const state = await readState(projectRoot);
+    expect(state.phases.prototype.test_plan.status).toBe("pending_approval");
+    expect(state.phases.prototype.test_plan.file).toBe("it_000003_test-plan.md");
+    expect(state.last_updated).toBe("2026-02-21T03:00:00.000Z");
+    expect(state.updated_by).toBe("nvst:create-test-plan");
+  });
+
+  test("supports --agent cursor and writes stdout output to the test-plan file", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "created");
+
+    const outputPath = join(projectRoot, ".agents", "flow", "it_000003_test-plan.md");
+    let capturedPrompt = "";
+    let capturedProvider = "";
+
+    await withCwd(projectRoot, async () => {
+      await runCreateTestPlan(
+        { provider: "cursor" },
+        {
+          loadSkillFn: async () => "Create a test plan using iteration and project context.",
+          invokeAgentFn: async (options): Promise<AgentResult> => {
+            capturedPrompt = options.prompt;
+            capturedProvider = options.provider;
+            return {
+              exitCode: 0,
+              stdout: [
+                "# Test Plan - Iteration 000003",
+                "## User Story: US-001 - Cursor flow",
+                "| Test Case ID | Description | Type (unit/integration/e2e) | Mode (automated/manual) | Correlated Requirements (US-XXX, FR-X) | Expected Result |",
+                "|---|---|---|---|---|---|",
+                "| TC-US001-01 | Validate cursor provider flow | integration | automated | US-001, FR-1 | Cursor provider generates plan output |",
+                "## Scope",
+                "- Cursor provider compatibility",
+                "## Environment and data",
+                "- Local dev shell",
+              ].join("\n"),
+              stderr: "",
+            };
+          },
+          nowFn: () => new Date("2026-02-21T03:30:00.000Z"),
+        },
+      );
+    });
+
+    expect(capturedProvider).toBe("cursor");
+    expect(capturedPrompt).toContain("### iteration");
+    expect(capturedPrompt).toContain("000003");
+    expect(capturedPrompt).toContain("### project_context");
+    expect(capturedPrompt).toContain("# Context");
+
+    const content = await readFile(outputPath, "utf8");
+    expect(content).toContain("TC-US001-01");
+    expect(content).toContain("Cursor provider compatibility");
+
+    const state = await readState(projectRoot);
+    expect(state.phases.prototype.test_plan.status).toBe("pending_approval");
+    expect(state.phases.prototype.test_plan.file).toBe("it_000003_test-plan.md");
+    expect(state.last_updated).toBe("2026-02-21T03:30:00.000Z");
+    expect(state.updated_by).toBe("nvst:create-test-plan");
+  });
+
+  test("requires project_context.status to be created", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending");
+
+    await withCwd(projectRoot, async () => {
+      await expect(
+        runCreateTestPlan(
+          { provider: "codex" },
+          {
+            loadSkillFn: async () => "unused",
+            invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          },
+        ),
+      ).rejects.toThrow("Cannot create test plan: prototype.project_context.status must be created");
+    });
+  });
+
+  test("asks for confirmation before overwrite and cancels when denied", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "created");
+
+    const outputPath = join(projectRoot, ".agents", "flow", "it_000003_test-plan.md");
+    await writeFile(outputPath, "old", "utf8");
+
+    let confirmCalls = 0;
+    let invokeCalls = 0;
+
+    await withCwd(projectRoot, async () => {
+      await runCreateTestPlan(
+        { provider: "codex" },
+        {
+          confirmOverwriteFn: async () => {
+            confirmCalls += 1;
+            return false;
+          },
+          loadSkillFn: async () => "unused",
+          invokeAgentFn: async () => {
+            invokeCalls += 1;
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+        },
+      );
+    });
+
+    expect(confirmCalls).toBe(1);
+    expect(invokeCalls).toBe(0);
+
+    const state = await readState(projectRoot);
+    expect(state.phases.prototype.test_plan.status).toBe("pending");
+    expect(state.phases.prototype.test_plan.file).toBeNull();
+  });
+
+  test("force overwrite bypasses confirmation", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "created");
+
+    const outputPath = join(projectRoot, ".agents", "flow", "it_000003_test-plan.md");
+    await writeFile(outputPath, "old", "utf8");
+
+    let confirmCalled = false;
+    let invokeCalls = 0;
+
+    await withCwd(projectRoot, async () => {
+      await runCreateTestPlan(
+        { provider: "codex", force: true },
+        {
+          confirmOverwriteFn: async () => {
+            confirmCalled = true;
+            return true;
+          },
+          loadSkillFn: async () => "skill",
+          invokeAgentFn: async () => {
+            invokeCalls += 1;
+            await writeFile(
+              outputPath,
+              [
+                "# Test Plan - Iteration 000003",
+                "## User Story: US-001 - Example Story",
+                "| Test Case ID | Description | Type (unit/integration/e2e) | Mode (automated/manual) | Correlated Requirements (US-XXX, FR-X) | Expected Result |",
+                "|---|---|---|---|---|---|",
+                "| TC-US001-01 | Validate login success | integration | automated | US-001, FR-1 | Login succeeds with valid credentials |",
+              ].join("\n"),
+              "utf8",
+            );
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+        },
+      );
+    });
+
+    expect(confirmCalled).toBe(false);
+    expect(invokeCalls).toBe(1);
+    expect(await readFile(outputPath, "utf8")).toContain("Correlated Requirements");
+  });
+
+  test("fails when generated markdown table omits correlated requirement IDs", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "created");
+
+    const outputPath = join(projectRoot, ".agents", "flow", "it_000003_test-plan.md");
+
+    await withCwd(projectRoot, async () => {
+      await expect(
+        runCreateTestPlan(
+          { provider: "codex" },
+          {
+            loadSkillFn: async () => "skill",
+            invokeAgentFn: async () => {
+              await writeFile(
+                outputPath,
+                [
+                  "# Test Plan - Iteration 000003",
+                  "## User Story: US-001 - Example Story",
+                  "| Test Case ID | Description | Type (unit/integration/e2e) | Mode (automated/manual) | Expected Result |",
+                  "|---|---|---|---|---|",
+                  "| TC-US001-01 | Validate login success | integration | automated | Login succeeds with valid credentials |",
+                ].join("\n"),
+                "utf8",
+              );
+              return { exitCode: 0, stdout: "", stderr: "" };
+            },
+          },
+        ),
+      ).rejects.toThrow(
+        "Generated test plan does not satisfy traceability requirements for the test-plan schema.",
+      );
+    });
+
+    const state = await readState(projectRoot);
+    expect(state.phases.prototype.test_plan.status).toBe("pending");
+    expect(state.phases.prototype.test_plan.file).toBeNull();
+  });
+});
+
+describe("create-test-plan skill definition", () => {
+  test("has YAML frontmatter and required automation-first instructions", async () => {
+    const skillPath = join(
+      process.cwd(),
+      ".agents",
+      "skills",
+      "create-test-plan",
+      "SKILL.md",
+    );
+    const source = await readFile(skillPath, "utf8");
+
+    expect(source.startsWith("---\n")).toBe(true);
+    expect(source).toContain("name: create-test-plan");
+    expect(source).toContain("description:");
+    expect(source).toContain("user-invocable: true");
+    expect(source).toContain("Read these first to understand what must be tested:");
+    expect(source).toContain("`it_{iteration}_PRD.json`");
+    expect(source).toContain("`.agents/PROJECT_CONTEXT.md`");
+    expect(source).toContain("structured by user story");
+    expect(source).toContain("| Test Case ID | Description | Type (unit/integration/e2e) | Mode (automated/manual) | Correlated Requirements (US-XXX, FR-X) | Expected Result |");
+    expect(source).toContain("Every functional requirement (`FR-N`) must have automated coverage.");
+    expect(source).toContain("Every functional requirement (`FR-N`) must appear in at least one test case `Correlated Requirements` field.");
+    expect(source).toContain("`Correlated Requirements` with at least one requirement ID (`US-XXX`, `FR-X`)");
+    expect(source).toContain(
+      "Manual tests are allowed only for UI/UX nuances that cannot be reliably validated through DOM/state assertions",
+    );
+    expect(source).toContain("`.agents/flow/it_{iteration}_test-plan.md`");
+  });
+});
+
+describe("parseTestPlanForValidation", () => {
+  test("maps requirement traceability into schema-compatible test items", () => {
+    const parsed = parseTestPlanForValidation(
+      [
+        "# Test Plan - Iteration 000003",
+        "| Test Case ID | Description | Type (unit/integration/e2e) | Mode (automated/manual) | Correlated Requirements (US-XXX, FR-X) | Expected Result |",
+        "|---|---|---|---|---|---|",
+        "| TC-US001-01 | Validate login success | integration | automated | US-001, FR-1 | Login succeeds with valid credentials |",
+      ].join("\n"),
+    );
+
+    expect(parsed.overallStatus).toBe("pending");
+    expect(parsed.automatedTests).toHaveLength(1);
+    expect(parsed.automatedTests[0]?.correlatedRequirements).toEqual(["US-001", "FR-1"]);
+  });
+});

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

@@ -0,0 +1,248 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import {
+  buildPrompt,
+  invokeAgent,
+  loadSkill,
+  type AgentInvokeOptions,
+  type AgentProvider,
+  type AgentResult,
+} from "../agent";
+import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
+import { TestPlanSchema, type TestPlan } from "../../schemas/test-plan";
+
+export interface CreateTestPlanOptions {
+  provider: AgentProvider;
+  force?: boolean;
+}
+
+interface CreateTestPlanDeps {
+  confirmOverwriteFn: (question: string) => Promise<boolean>;
+  existsFn: (path: string) => Promise<boolean>;
+  invokeAgentFn: (options: AgentInvokeOptions) => Promise<AgentResult>;
+  loadSkillFn: (projectRoot: string, skillName: string) => Promise<string>;
+  mkdirFn: typeof mkdir;
+  nowFn: () => Date;
+  readFileFn: typeof readFile;
+}
+
+const defaultDeps: CreateTestPlanDeps = {
+  confirmOverwriteFn: promptForConfirmation,
+  existsFn: exists,
+  invokeAgentFn: invokeAgent,
+  loadSkillFn: loadSkill,
+  mkdirFn: mkdir,
+  nowFn: () => new Date(),
+  readFileFn: readFile,
+};
+
+function parseRequirements(cell: string): string[] {
+  return cell
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => /^(US-\d{3}|FR-\d+)$/i.test(entry))
+    .map((entry) => entry.toUpperCase());
+}
+
+export function parseTestPlanForValidation(markdown: string): TestPlan {
+  const scope: string[] = [];
+  const environmentData: string[] = [];
+  const automatedTests: TestPlan["automatedTests"] = [];
+  const exploratoryManualTests: TestPlan["exploratoryManualTests"] = [];
+
+  type Section = "scope" | "environmentData" | null;
+  let currentSection: Section = null;
+  let inTable = false;
+
+  for (const line of markdown.split("\n")) {
+    const trimmed = line.trim();
+
+    if (/^##\s+Scope$/i.test(trimmed)) {
+      currentSection = "scope";
+      inTable = false;
+      continue;
+    }
+    if (/^##\s+Environment\s*(?:and|&)\s*data$/i.test(trimmed)) {
+      currentSection = "environmentData";
+      inTable = false;
+      continue;
+    }
+
+    if (
+      trimmed.startsWith("|")
+      && trimmed.includes("Test Case ID")
+      && trimmed.includes("Correlated Requirements")
+    ) {
+      inTable = true;
+      currentSection = null;
+      continue;
+    }
+
+    if (inTable && trimmed.startsWith("|")) {
+      if (trimmed.includes("---|")) continue;
+
+      const cells = trimmed
+        .split("|")
+        .map((cell) => cell.trim())
+        .filter((cell, index, all) => index > 0 && index < all.length - 1);
+
+      if (cells.length >= 6) {
+        const [id, description, , mode, correlatedRequirementsCell] = cells;
+        if (id === "Test Case ID") continue;
+
+        const item = {
+          id,
+          description,
+          status: "pending" as const,
+          correlatedRequirements: parseRequirements(correlatedRequirementsCell),
+        };
+        if (mode.toLowerCase().includes("automated")) {
+          automatedTests.push(item);
+        } else {
+          exploratoryManualTests.push(item);
+        }
+      }
+      continue;
+    }
+
+    if (inTable && trimmed.length === 0) {
+      inTable = false;
+      continue;
+    }
+
+    if (!currentSection || trimmed.length === 0 || /^<!--/.test(trimmed)) {
+      continue;
+    }
+
+    const bulletMatch = trimmed.match(/^[-*]\s+(.+)$/);
+    const value = bulletMatch ? bulletMatch[1].trim() : trimmed;
+    if (!value) continue;
+
+    if (currentSection === "scope") scope.push(value);
+    if (currentSection === "environmentData") environmentData.push(value);
+  }
+
+  return {
+    overallStatus: "pending",
+    scope,
+    environmentData,
+    automatedTests,
+    exploratoryManualTests,
+  };
+}
+
+export async function promptForConfirmation(question: string): Promise<boolean> {
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const answer = (await readline.question(question)).trim();
+    return /^y(?:es)?$/i.test(answer);
+  } finally {
+    readline.close();
+  }
+}
+
+export async function runCreateTestPlan(
+  opts: CreateTestPlanOptions,
+  deps: Partial<CreateTestPlanDeps> = {},
+): Promise<void> {
+  const projectRoot = process.cwd();
+  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.",
+    );
+  }
+
+  const iteration = state.current_iteration;
+  const fileName = `it_${iteration}_test-plan.md`;
+  const flowDir = join(projectRoot, FLOW_REL_DIR);
+  const outputPath = join(flowDir, fileName);
+
+  await mergedDeps.mkdirFn(flowDir, { recursive: true });
+
+  if ((await mergedDeps.existsFn(outputPath)) && !opts.force) {
+    const shouldOverwrite = await mergedDeps.confirmOverwriteFn(
+      `Test plan file already exists at ${join(FLOW_REL_DIR, fileName)}. Overwrite? [y/N] `,
+    );
+
+    if (!shouldOverwrite) {
+      console.log("Test plan creation cancelled.");
+      return;
+    }
+  }
+
+  let skillBody: string;
+  try {
+    skillBody = await mergedDeps.loadSkillFn(projectRoot, "create-test-plan");
+  } catch {
+    throw new Error(
+      "Required skill missing: expected .agents/skills/create-test-plan/SKILL.md.",
+    );
+  }
+
+  const projectContextPath = join(projectRoot, ".agents", "PROJECT_CONTEXT.md");
+  if (!(await mergedDeps.existsFn(projectContextPath))) {
+    throw new Error("Project context missing: expected .agents/PROJECT_CONTEXT.md.");
+  }
+
+  const projectContextContent = await mergedDeps.readFileFn(projectContextPath, "utf8");
+  const prompt = buildPrompt(skillBody, {
+    iteration,
+    project_context: projectContextContent,
+  });
+
+  const result = await mergedDeps.invokeAgentFn({
+    provider: opts.provider,
+    prompt,
+    cwd: projectRoot,
+    interactive: true,
+  });
+
+  if (result.exitCode !== 0) {
+    throw new Error(`Agent invocation failed with exit code ${result.exitCode}.`);
+  }
+
+  if (!(await mergedDeps.existsFn(outputPath)) && result.stdout.trim().length > 0) {
+    const content = result.stdout.endsWith("\n") ? result.stdout : `${result.stdout}\n`;
+    await Bun.write(outputPath, content);
+  }
+
+  if (!(await mergedDeps.existsFn(outputPath))) {
+    throw new Error(
+      `Test plan generation did not produce ${join(FLOW_REL_DIR, fileName)}.`,
+    );
+  }
+
+  const generatedMarkdown = await mergedDeps.readFileFn(outputPath, "utf8");
+  const parsed = parseTestPlanForValidation(generatedMarkdown);
+  const totalTestCases = parsed.automatedTests.length + parsed.exploratoryManualTests.length;
+  if (totalTestCases === 0) {
+    throw new Error(
+      "Generated test plan does not satisfy traceability requirements for the test-plan schema.",
+    );
+  }
+  const validation = TestPlanSchema.safeParse(parsed);
+  if (!validation.success) {
+    throw new Error(
+      "Generated test plan does not satisfy traceability requirements for the test-plan schema.",
+      { cause: validation.error },
+    );
+  }
+
+  state.phases.prototype.test_plan.status = "pending_approval";
+  state.phases.prototype.test_plan.file = fileName;
+  state.last_updated = mergedDeps.nowFn().toISOString();
+  state.updated_by = "nvst:create-test-plan";
+
+  await writeState(projectRoot, state);
+
+  console.log("Test plan generated and marked as pending approval.");
+}

package/src/commands/define-requirement.ts

@@ -0,0 +1,47 @@
+import { buildPrompt, invokeAgent, loadSkill, type AgentProvider } from "../agent";
+import { readState, writeState } from "../state";
+
+export interface DefineRequirementOptions {
+  provider: AgentProvider;
+}
+
+export async function runDefineRequirement(opts: DefineRequirementOptions): Promise<void> {
+  const { provider } = opts;
+  const projectRoot = process.cwd();
+  const state = await readState(projectRoot);
+
+  if (state.current_phase !== "define") {
+    throw new Error("Cannot define requirement: current_phase must be 'define'.");
+  }
+
+  const requirementDefinition = state.phases.define.requirement_definition;
+  if (requirementDefinition.status !== "pending") {
+    throw new Error(
+      `Cannot define requirement from status '${requirementDefinition.status}'. Expected pending.`,
+    );
+  }
+
+  const skillBody = await loadSkill(projectRoot, "create-pr-document");
+  const prompt = buildPrompt(skillBody, {
+    current_iteration: state.current_iteration,
+  });
+  const result = await invokeAgent({
+    provider,
+    prompt,
+    cwd: projectRoot,
+    interactive: true,
+  });
+
+  if (result.exitCode !== 0) {
+    throw new Error(`Agent invocation failed with exit code ${result.exitCode}.`);
+  }
+
+  requirementDefinition.status = "in_progress";
+  requirementDefinition.file = `it_${state.current_iteration}_product-requirement-document.md`;
+  state.last_updated = new Date().toISOString();
+  state.updated_by = "nvst:define-requirement";
+
+  await writeState(projectRoot, state);
+
+  console.log("Requirement definition started and marked as in progress.");
+}