@quinteroac/agents-coding-toolkit 0.1.0-preview

package/src/commands/init.ts

@@ -0,0 +1,85 @@
+import { access, mkdir, readdir } from "node:fs/promises";
+import { basename, dirname, join, relative } from "node:path";
+
+const TEMPLATE_PREFIX = "tmpl_";
+const SCAFFOLD_ROOT = join(import.meta.dir, "..", "..", "scaffold");
+
+export interface ScaffoldEntry {
+  sourcePath: string;
+  destinationPath: string;
+  relativeDestinationPath: string;
+}
+
+function stripTemplatePrefix(fileName: string): string {
+  return fileName.startsWith(TEMPLATE_PREFIX) ? fileName.slice(TEMPLATE_PREFIX.length) : fileName;
+}
+
+async function walkFiles(directoryPath: string): Promise<string[]> {
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  const filePaths: string[] = [];
+
+  for (const entry of entries) {
+    const entryPath = join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      filePaths.push(...(await walkFiles(entryPath)));
+      continue;
+    }
+    if (entry.isFile()) {
+      filePaths.push(entryPath);
+    }
+  }
+
+  return filePaths;
+}
+
+export async function getScaffoldEntries(projectRoot: string): Promise<ScaffoldEntry[]> {
+  const sourceFiles = await walkFiles(SCAFFOLD_ROOT);
+
+  return sourceFiles.map((sourcePath) => {
+    const relativeFromScaffold = relative(SCAFFOLD_ROOT, sourcePath);
+    const sourceDir = dirname(relativeFromScaffold);
+    const targetFileName = stripTemplatePrefix(basename(relativeFromScaffold));
+    const relativeDestinationPath =
+      sourceDir === "." ? targetFileName : join(sourceDir, targetFileName);
+
+    return {
+      sourcePath,
+      destinationPath: join(projectRoot, relativeDestinationPath),
+      relativeDestinationPath,
+    };
+  });
+}
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runInit(): Promise<void> {
+  const projectRoot = process.cwd();
+  const entries = await getScaffoldEntries(projectRoot);
+
+  const created: string[] = [];
+  const skipped: string[] = [];
+
+  for (const entry of entries) {
+    if (await exists(entry.destinationPath)) {
+      console.warn(`Skipping existing file: ${entry.relativeDestinationPath}`);
+      skipped.push(entry.relativeDestinationPath);
+      continue;
+    }
+
+    await mkdir(dirname(entry.destinationPath), { recursive: true });
+    await Bun.write(entry.destinationPath, Bun.file(entry.sourcePath));
+    created.push(entry.relativeDestinationPath);
+    console.log(`Created: ${entry.relativeDestinationPath}`);
+  }
+
+  console.log(
+    `\nInit complete. Created ${created.length} file(s), skipped ${skipped.length} existing file(s).`,
+  );
+}

package/src/commands/refine-project-context.ts

@@ -0,0 +1,74 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { buildPrompt, invokeAgent, loadSkill, type AgentProvider } from "../agent";
+import { exists, readState, writeState } from "../state";
+
+export interface RefineProjectContextOptions {
+    provider: AgentProvider;
+    challenge: boolean;
+}
+
+export async function runRefineProjectContext(opts: RefineProjectContextOptions): Promise<void> {
+    const { provider, challenge } = opts;
+    const projectRoot = process.cwd();
+    const state = await readState(projectRoot);
+
+    // US-003-AC01: Validate status is pending_approval or created
+    const projectContext = state.phases.prototype.project_context;
+    if (projectContext.status !== "pending_approval" && projectContext.status !== "created") {
+        throw new Error(
+            `Cannot refine project context from status '${projectContext.status}'. ` +
+            "Expected pending_approval or created.",
+        );
+    }
+
+    // Validate file reference exists in state
+    const contextFile = projectContext.file;
+    if (!contextFile) {
+        throw new Error("Cannot refine project context: project_context.file is missing.");
+    }
+
+    const contextPath = join(projectRoot, contextFile);
+    if (!(await exists(contextPath))) {
+        throw new Error(`Cannot refine project context: file not found at ${contextPath}`);
+    }
+
+    // US-003-AC03: Challenge mode uses a dedicated skill section
+    const skillName = challenge ? "refine-project-context" : "refine-project-context";
+    const skillBody = await loadSkill(projectRoot, skillName);
+    const contextContent = await readFile(contextPath, "utf8");
+
+    const context: Record<string, string> = {
+        current_iteration: state.current_iteration,
+        project_context_file: contextFile,
+        project_context_content: contextContent,
+    };
+
+    if (challenge) {
+        context.mode = "challenger";
+    }
+
+    const prompt = buildPrompt(skillBody, context);
+    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}.`);
+    }
+
+    // US-003-AC04: After refinement, set status back to pending_approval
+    projectContext.status = "pending_approval";
+    state.last_updated = new Date().toISOString();
+    state.updated_by = challenge
+        ? "nvst:refine-project-context:challenge"
+        : "nvst:refine-project-context";
+
+    await writeState(projectRoot, state);
+
+    console.log("Project context refined and marked as pending approval.");
+}

package/src/commands/refine-requirement.ts

@@ -0,0 +1,60 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { buildPrompt, invokeAgent, loadSkill, type AgentProvider } from "../agent";
+import { exists, readState, FLOW_REL_DIR } from "../state";
+
+export interface RefineRequirementOptions {
+  provider: AgentProvider;
+  challenge: boolean;
+}
+
+export async function runRefineRequirement(opts: RefineRequirementOptions): Promise<void> {
+  const { provider, challenge } = opts;
+  const projectRoot = process.cwd();
+  const state = await readState(projectRoot);
+
+  const requirementDefinition = state.phases.define.requirement_definition;
+  if (requirementDefinition.status !== "in_progress") {
+    throw new Error(
+      `Cannot refine requirement from status '${requirementDefinition.status}'. Expected in_progress.`,
+    );
+  }
+
+  const requirementFile = requirementDefinition.file;
+  if (!requirementFile) {
+    throw new Error("Cannot refine requirement: define.requirement_definition.file is missing.");
+  }
+
+  const requirementPath = join(projectRoot, FLOW_REL_DIR, requirementFile);
+  if (!(await exists(requirementPath))) {
+    throw new Error(`Cannot refine requirement: file not found at ${requirementPath}`);
+  }
+
+  const skillBody = await loadSkill(projectRoot, "refine-pr-document");
+  const requirementContent = await readFile(requirementPath, "utf8");
+
+  const context: Record<string, string> = {
+    current_iteration: state.current_iteration,
+    requirement_file: requirementFile,
+    requirement_content: requirementContent,
+  };
+
+  if (challenge) {
+    context.mode = "challenger";
+  }
+
+  const prompt = buildPrompt(skillBody, context);
+  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}.`);
+  }
+
+  console.log("Requirement refined.");
+}

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

@@ -0,0 +1,200 @@
+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 { runRefineTestPlan } from "./refine-test-plan";
+
+async function createProjectRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "nvst-refine-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,
+  status: "pending" | "pending_approval" | "created",
+  file: string | null,
+) {
+  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: "created", file: ".agents/PROJECT_CONTEXT.md" },
+        test_plan: { status, file },
+        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-21T00: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("refine test-plan command", () => {
+  test("registers refine test-plan command in CLI dispatch", async () => {
+    const source = await readFile(join(process.cwd(), "src", "cli.ts"), "utf8");
+
+    expect(source).toContain('import { runRefineTestPlan } from "./commands/refine-test-plan";');
+    expect(source).toContain('if (subcommand === "test-plan") {');
+    expect(source).toContain('const challenge = postAgentArgs.includes("--challenge");');
+    expect(source).toContain("await runRefineTestPlan({ provider, challenge });");
+  });
+
+  test("loads refine-test-plan skill, reads test plan file context, invokes agent interactively, and does not update state", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending_approval", "it_000003_test-plan.md");
+
+    const testPlanPath = join(projectRoot, ".agents", "flow", "it_000003_test-plan.md");
+    await writeFile(testPlanPath, "# Existing Test Plan\n- Case A\n", "utf8");
+
+    let loadedSkill = "";
+    let invocation: { interactive: boolean | undefined; prompt: string } | undefined;
+    const stateBefore = JSON.stringify(await readState(projectRoot));
+
+    await withCwd(projectRoot, async () => {
+      await runRefineTestPlan(
+        { provider: "codex", challenge: false },
+        {
+          loadSkillFn: async (_root, skillName) => {
+            loadedSkill = skillName;
+            return "Refine test plan skill";
+          },
+          invokeAgentFn: async (options): Promise<AgentResult> => {
+            invocation = {
+              interactive: options.interactive,
+              prompt: options.prompt,
+            };
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+        },
+      );
+    });
+
+    expect(loadedSkill).toBe("refine-test-plan");
+    if (invocation === undefined) {
+      throw new Error("Agent invocation was not captured");
+    }
+
+    expect(invocation.interactive).toBe(true);
+    expect(invocation.prompt).toContain("### current_iteration");
+    expect(invocation.prompt).toContain("000003");
+    expect(invocation.prompt).toContain("### test_plan_file");
+    expect(invocation.prompt).toContain("it_000003_test-plan.md");
+    expect(invocation.prompt).toContain("### test_plan_content");
+    expect(invocation.prompt).toContain("# Existing Test Plan");
+
+    const stateAfter = JSON.stringify(await readState(projectRoot));
+    expect(stateAfter).toBe(stateBefore);
+  });
+
+  test("passes mode=challenger in prompt context when challenge mode is enabled without updating state", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending_approval", "it_000003_test-plan.md");
+
+    const testPlanPath = join(projectRoot, ".agents", "flow", "it_000003_test-plan.md");
+    await writeFile(testPlanPath, "# Existing Test Plan\n- Case B\n", "utf8");
+
+    let invocationPrompt = "";
+    const stateBefore = JSON.stringify(await readState(projectRoot));
+
+    await withCwd(projectRoot, async () => {
+      await runRefineTestPlan(
+        { provider: "codex", challenge: true },
+        {
+          loadSkillFn: async () => "Refine test plan skill",
+          invokeAgentFn: async (options): Promise<AgentResult> => {
+            invocationPrompt = options.prompt;
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+        },
+      );
+    });
+
+    expect(invocationPrompt).toContain("### mode");
+    expect(invocationPrompt).toContain("challenger");
+
+    const stateAfter = JSON.stringify(await readState(projectRoot));
+    expect(stateAfter).toBe(stateBefore);
+  });
+
+  test("requires test_plan.status to be pending_approval", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending", "it_000003_test-plan.md");
+
+    await withCwd(projectRoot, async () => {
+      await expect(
+        runRefineTestPlan(
+          { provider: "codex", challenge: false },
+          {
+            loadSkillFn: async () => "unused",
+            invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          },
+        ),
+      ).rejects.toThrow("Cannot refine test plan from status 'pending'. Expected pending_approval.");
+    });
+  });
+});
+
+describe("refine-test-plan skill definition", () => {
+  test("has YAML frontmatter and required editor/challenger guidance", async () => {
+    const skillPath = join(
+      process.cwd(),
+      ".agents",
+      "skills",
+      "refine-test-plan",
+      "SKILL.md",
+    );
+    const source = await readFile(skillPath, "utf8");
+
+    expect(source.startsWith("---\n")).toBe(true);
+    expect(source).toContain("name: refine-test-plan");
+    expect(source).toContain("description:");
+    expect(source).toContain("user-invocable: true");
+    expect(source).toContain("Editor mode");
+    expect(source).toContain("default");
+    expect(source).toContain("Preserve the existing section structure");
+    expect(source).toContain("Challenger mode");
+    expect(source).toContain("`mode = \"challenger\"`");
+    expect(source).toContain("Coverage gaps");
+    expect(source).toContain("Weak or non-verifiable assertions");
+    expect(source).toContain("Over-reliance on manual testing");
+    expect(source).toContain("Update `it_{current_iteration}_test-plan.md` in place.");
+    expect(source).toContain("Same output file path is preserved");
+  });
+});

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

@@ -0,0 +1,93 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  buildPrompt,
+  invokeAgent,
+  loadSkill,
+  type AgentInvokeOptions,
+  type AgentProvider,
+  type AgentResult,
+} from "../agent";
+import { exists, FLOW_REL_DIR, readState } from "../state";
+
+export interface RefineTestPlanOptions {
+  provider: AgentProvider;
+  challenge: boolean;
+}
+
+interface RefineTestPlanDeps {
+  existsFn: (path: string) => Promise<boolean>;
+  invokeAgentFn: (options: AgentInvokeOptions) => Promise<AgentResult>;
+  loadSkillFn: (projectRoot: string, skillName: string) => Promise<string>;
+  readFileFn: typeof readFile;
+}
+
+const defaultDeps: RefineTestPlanDeps = {
+  existsFn: exists,
+  invokeAgentFn: invokeAgent,
+  loadSkillFn: loadSkill,
+  readFileFn: readFile,
+};
+
+export async function runRefineTestPlan(
+  opts: RefineTestPlanOptions,
+  deps: Partial<RefineTestPlanDeps> = {},
+): Promise<void> {
+  const { provider, challenge } = opts;
+  const projectRoot = process.cwd();
+  const state = await readState(projectRoot);
+  const mergedDeps: RefineTestPlanDeps = { ...defaultDeps, ...deps };
+
+  const testPlan = state.phases.prototype.test_plan;
+  if (testPlan.status !== "pending_approval") {
+    throw new Error(
+      `Cannot refine test plan from status '${testPlan.status}'. Expected pending_approval.`,
+    );
+  }
+
+  const testPlanFile = testPlan.file;
+  if (!testPlanFile) {
+    throw new Error("Cannot refine test plan: prototype.test_plan.file is missing.");
+  }
+
+  const testPlanPath = join(projectRoot, FLOW_REL_DIR, testPlanFile);
+  if (!(await mergedDeps.existsFn(testPlanPath))) {
+    throw new Error(`Cannot refine test plan: file not found at ${testPlanPath}`);
+  }
+
+  let skillBody: string;
+  try {
+    skillBody = await mergedDeps.loadSkillFn(projectRoot, "refine-test-plan");
+  } catch {
+    throw new Error(
+      "Required skill missing: expected .agents/skills/refine-test-plan/SKILL.md.",
+    );
+  }
+
+  const testPlanContent = await mergedDeps.readFileFn(testPlanPath, "utf8");
+  const context: Record<string, string> = {
+    current_iteration: state.current_iteration,
+    test_plan_file: testPlanFile,
+    test_plan_content: testPlanContent,
+  };
+
+  if (challenge) {
+    context.mode = "challenger";
+  }
+
+  const prompt = buildPrompt(skillBody, context);
+
+  const result = await mergedDeps.invokeAgentFn({
+    provider,
+    prompt,
+    cwd: projectRoot,
+    interactive: true,
+  });
+
+  if (result.exitCode !== 0) {
+    throw new Error(`Agent invocation failed with exit code ${result.exitCode}.`);
+  }
+
+  console.log("Test plan refined.");
+}

package/src/commands/start-iteration.test.ts

@@ -0,0 +1,144 @@
+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 { readState } from "../state";
+import { runStartIteration } from "./start-iteration";
+
+async function createProjectRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "nvst-start-iteration-"));
+}
+
+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);
+  }
+}
+
+const createdRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(createdRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("start-iteration command", () => {
+  test("registers start iteration in CLI dispatch", async () => {
+    const source = await readFile(join(process.cwd(), "src", "cli.ts"), "utf8");
+    expect(source).toContain('import { runStartIteration } from "./commands/start-iteration";');
+    expect(source).toContain("await runStartIteration();");
+  });
+
+  test("preserves project_context when already created (immutable across iterations)", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    const flowDir = join(projectRoot, ".agents", "flow");
+    await mkdir(flowDir, { recursive: true });
+
+    // Seed state with project_context already created
+    await writeFile(
+      join(projectRoot, ".agents", "state.json"),
+      JSON.stringify(
+        {
+          current_iteration: "000008",
+          current_phase: "refactor",
+          phases: {
+            define: {
+              requirement_definition: { status: "approved", file: "it_000008_product-requirement-document.md" },
+              prd_generation: { status: "completed", file: "it_000008_PRD.json" },
+            },
+            prototype: {
+              project_context: { status: "created", file: ".agents/PROJECT_CONTEXT.md" },
+              test_plan: { status: "created", file: "it_000008_TP.json" },
+              tp_generation: { status: "created", file: "it_000008_TP.json" },
+              prototype_build: { status: "created", file: null },
+              test_execution: { status: "completed", file: null },
+              prototype_approved: true,
+            },
+            refactor: {
+              evaluation_report: { status: "created", file: null },
+              refactor_plan: { status: "approved", file: null },
+              refactor_execution: { status: "completed", file: null },
+              changelog: { status: "created", file: null },
+            },
+          },
+          last_updated: "2026-02-22T20:00:00.000Z",
+          history: [{ iteration: "000007", archived_at: "2026-02-22T19:00:00.000Z", archived_path: ".agents/flow/archived/000007" }],
+        },
+        null,
+        2,
+      ),
+    );
+
+    // Create an iteration file to archive
+    await writeFile(join(flowDir, "it_000008_ISSUES.json"), "[]");
+
+    await withCwd(projectRoot, async () => {
+      await runStartIteration();
+    });
+
+    const state = await readState(projectRoot);
+    expect(state.current_iteration).toBe("000009");
+    expect(state.phases.prototype.project_context).toEqual({
+      status: "created",
+      file: ".agents/PROJECT_CONTEXT.md",
+    });
+  });
+
+  test("does not preserve project_context when it was pending", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    const flowDir = join(projectRoot, ".agents", "flow");
+    await mkdir(flowDir, { recursive: true });
+
+    await writeFile(
+      join(projectRoot, ".agents", "state.json"),
+      JSON.stringify(
+        {
+          current_iteration: "000002",
+          current_phase: "define",
+          phases: {
+            define: {
+              requirement_definition: { status: "pending", file: null },
+              prd_generation: { status: "pending", file: null },
+            },
+            prototype: {
+              project_context: { status: "pending", file: null },
+              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-22T20:00:00.000Z",
+          history: [],
+        },
+        null,
+        2,
+      ),
+    );
+
+    await writeFile(join(flowDir, "it_000002_PRD.json"), "{}");
+
+    await withCwd(projectRoot, async () => {
+      await runStartIteration();
+    });
+
+    const state = await readState(projectRoot);
+    expect(state.phases.prototype.project_context).toEqual({
+      status: "pending",
+      file: null,
+    });
+  });
+});