@nathapp/nax 0.29.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
@@ -52,4 +52,4 @@
     "README.md",
     "CHANGELOG.md"
   ]
-}
+}

package/src/cli/analyze.ts

@@ -15,6 +15,7 @@ import { resolveModel } from "../config/schema";
 import { getLogger } from "../logger";
 import type { PRD, UserStory } from "../prd";
 import { routeTask } from "../routing";
+import { NAX_VERSION } from "../version";
 import {
   applyKeywordClassification,
   buildCodebaseContext,
@@ -63,13 +64,7 @@ export async function analyzeFeature(options: AnalyzeOptions): Promise<PRD> {
     );
   }
 
-  let naxVersion = "unknown";
-  try {
-    const pkgPath = new URL("../../package.json", import.meta.url);
-    naxVersion = (await Bun.file(pkgPath).json()).version;
-  } catch {
-    /* version is metadata only */
-  }
+  const naxVersion = NAX_VERSION;
 
   const now = new Date().toISOString();
   const prd: PRD = {

package/src/cli/index.ts

@@ -20,7 +20,9 @@ export {
 } from "./runs";
 export {
   promptsCommand,
+  promptsInitCommand,
   type PromptsCommandOptions,
+  type PromptsInitCommandOptions,
 } from "./prompts";
 export { initCommand, type InitOptions } from "./init";
 export { pluginsListCommand } from "./plugins";

package/src/cli/prompts.ts

@@ -18,6 +18,7 @@ import { constitutionStage, contextStage, promptStage, routingStage } from "../p
 import type { UserStory } from "../prd";
 import { loadPRD } from "../prd";
 import { PromptBuilder } from "../prompts";
+import { buildRoleTaskSection } from "../prompts/sections/role-task";
 
 export interface PromptsCommandOptions {
   /** Feature name */
@@ -240,6 +241,189 @@ function buildFrontmatter(story: UserStory, ctx: PipelineContext, role?: string)
   return `${lines.join("\n")}\n`;
 }
 
+export interface PromptsInitCommandOptions {
+  /** Working directory (project root) */
+  workdir: string;
+  /** Overwrite existing files if true */
+  force?: boolean;
+}
+
+const TEMPLATE_ROLES = [
+  { file: "test-writer.md", role: "test-writer" as const },
+  { file: "implementer.md", role: "implementer" as const, variant: "standard" as const },
+  { file: "verifier.md", role: "verifier" as const },
+  { file: "single-session.md", role: "single-session" as const },
+] as const;
+
+const TEMPLATE_HEADER = `<!--
+  This file controls the role-body section of the nax prompt for this role.
+  Edit the content below to customize the task instructions given to the agent.
+
+  NON-OVERRIDABLE SECTIONS (always injected by nax, cannot be changed here):
+    - Isolation rules (scope, file access boundaries)
+    - Story context (acceptance criteria, description, dependencies)
+    - Conventions (project coding standards)
+
+  To activate overrides, add to your nax/config.json:
+    { "prompts": { "overrides": { "<role>": "nax/templates/<role>.md" } } }
+-->
+
+`;
+
+/**
+ * Execute the `nax prompts --init` command.
+ *
+ * Creates nax/templates/ and writes 4 default role-body template files.
+ * Auto-wires prompts.overrides in nax.config.json if the file exists and overrides are not already set.
+ * Returns the list of file paths written. Returns empty array if files
+ * already exist and force is not set.
+ *
+ * @param options - Command options
+ * @returns Array of file paths written
+ */
+export async function promptsInitCommand(options: PromptsInitCommandOptions): Promise<string[]> {
+  const { workdir, force = false } = options;
+  const templatesDir = join(workdir, "nax", "templates");
+
+  mkdirSync(templatesDir, { recursive: true });
+
+  // Check for existing files
+  const existingFiles = TEMPLATE_ROLES.map((t) => t.file).filter((f) => existsSync(join(templatesDir, f)));
+
+  if (existingFiles.length > 0 && !force) {
+    console.warn(
+      `[WARN] nax/templates/ already contains files: ${existingFiles.join(", ")}. No files overwritten.\n       Pass --force to overwrite existing templates.`,
+    );
+    return [];
+  }
+
+  const written: string[] = [];
+
+  for (const template of TEMPLATE_ROLES) {
+    const filePath = join(templatesDir, template.file);
+    const roleBody =
+      template.role === "implementer"
+        ? buildRoleTaskSection(template.role, template.variant)
+        : buildRoleTaskSection(template.role);
+    const content = TEMPLATE_HEADER + roleBody;
+    await Bun.write(filePath, content);
+    written.push(filePath);
+  }
+
+  console.log(`[OK] Written ${written.length} template files to nax/templates/:`);
+  for (const filePath of written) {
+    console.log(`  - ${filePath.replace(`${workdir}/`, "")}`);
+  }
+
+  // Auto-wire prompts.overrides in nax.config.json
+  await autoWirePromptsConfig(workdir);
+
+  return written;
+}
+
+/**
+ * Auto-wire prompts.overrides in nax.config.json after template init.
+ *
+ * If nax.config.json exists and prompts.overrides is not already set,
+ * add the override paths. If overrides are already set, print a note.
+ * If nax.config.json doesn't exist, print manual instructions.
+ *
+ * @param workdir - Project working directory
+ */
+async function autoWirePromptsConfig(workdir: string): Promise<void> {
+  const configPath = join(workdir, "nax.config.json");
+
+  // If config file doesn't exist, print manual instructions
+  if (!existsSync(configPath)) {
+    const exampleConfig = JSON.stringify(
+      {
+        prompts: {
+          overrides: {
+            "test-writer": "nax/templates/test-writer.md",
+            implementer: "nax/templates/implementer.md",
+            verifier: "nax/templates/verifier.md",
+            "single-session": "nax/templates/single-session.md",
+          },
+        },
+      },
+      null,
+      2,
+    );
+    console.log(`\nNo nax.config.json found. To activate overrides, create nax/config.json with:\n${exampleConfig}`);
+    return;
+  }
+
+  // Read existing config
+  const configFile = Bun.file(configPath);
+  const configContent = await configFile.text();
+  const config = JSON.parse(configContent);
+
+  // Check if prompts.overrides is already set
+  if (config.prompts?.overrides && Object.keys(config.prompts.overrides).length > 0) {
+    console.log(
+      "[INFO] prompts.overrides already configured in nax.config.json. Skipping auto-wiring.\n" +
+        "       To reset overrides, remove the prompts.overrides section and re-run this command.",
+    );
+    return;
+  }
+
+  // Build the override paths
+  const overrides = {
+    "test-writer": "nax/templates/test-writer.md",
+    implementer: "nax/templates/implementer.md",
+    verifier: "nax/templates/verifier.md",
+    "single-session": "nax/templates/single-session.md",
+  };
+
+  // Add or update prompts section
+  if (!config.prompts) {
+    config.prompts = {};
+  }
+  config.prompts.overrides = overrides;
+
+  // Write config with custom formatting that avoids 4-space indentation
+  // by putting the overrides object on a single line
+  const updatedConfig = formatConfigJson(config);
+  await Bun.write(configPath, updatedConfig);
+
+  console.log("[OK] Auto-wired prompts.overrides in nax.config.json");
+}
+
+/**
+ * Format config JSON with 2-space indentation, keeping overrides object inline.
+ *
+ * This avoids 4-space indentation by putting the overrides object on the same line.
+ *
+ * @param config - Configuration object
+ * @returns Formatted JSON string
+ */
+function formatConfigJson(config: Record<string, unknown>): string {
+  const lines: string[] = ["{"];
+
+  const keys = Object.keys(config);
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const value = config[key];
+    const isLast = i === keys.length - 1;
+
+    if (key === "prompts" && typeof value === "object" && value !== null) {
+      // Special handling for prompts object - keep overrides inline
+      const promptsObj = value as Record<string, unknown>;
+      if (promptsObj.overrides) {
+        const overridesJson = JSON.stringify(promptsObj.overrides);
+        lines.push(`  "${key}": { "overrides": ${overridesJson} }${isLast ? "" : ","}`);
+      } else {
+        lines.push(`  "${key}": ${JSON.stringify(value)}${isLast ? "" : ","}`);
+      }
+    } else {
+      lines.push(`  "${key}": ${JSON.stringify(value)}${isLast ? "" : ","}`);
+    }
+  }
+
+  lines.push("}");
+  return lines.join("\n");
+}
+
 /**
  * Handle three-session TDD prompts by building separate prompts for each role.
  *
@@ -266,7 +450,7 @@ async function handleThreeSessionTddPrompts(
       .story(story)
       .context(ctx.contextMarkdown)
       .build(),
-    PromptBuilder.for("verifier").withLoader(ctx.workdir, ctx.config).story(story).build(),
+    PromptBuilder.for("verifier").withLoader(ctx.workdir, ctx.config).story(story).context(ctx.contextMarkdown).build(),
   ]);
 
   const sessions = [

package/src/execution/lifecycle/headless-formatter.ts

@@ -5,10 +5,10 @@
  * Extracts run header and footer formatting logic from runner.ts.
  */
 
-import path from "node:path";
 import chalk from "chalk";
 import type { RunSummary } from "../../logging";
 import { formatRunSummary } from "../../logging";
+import { NAX_VERSION } from "../../version";
 
 export interface RunHeaderOptions {
   feature: string;
@@ -42,11 +42,9 @@ export async function outputRunHeader(options: RunHeaderOptions): Promise<void>
     return;
   }
 
-  const pkg = await Bun.file(path.join(import.meta.dir, "..", "..", "..", "package.json")).json();
-
   console.log("");
   console.log(chalk.bold(chalk.blue("═".repeat(60))));
-  console.log(chalk.bold(chalk.blue(`  ▶ NAX v${pkg.version} — RUN STARTED`)));
+  console.log(chalk.bold(chalk.blue(`  ▶ NAX v${NAX_VERSION} — RUN STARTED`)));
   console.log(chalk.blue("═".repeat(60)));
   console.log(`  ${chalk.gray("Feature:")}  ${chalk.cyan(feature)}`);
   console.log(`  ${chalk.gray("Stories:")}  ${chalk.cyan(`${totalStories} total, ${pendingStories} pending`)}`);

package/src/prd/index.ts

@@ -49,6 +49,10 @@ export async function loadPRD(path: string): Promise<PRD> {
     story.escalations = story.escalations ?? [];
     story.dependencies = story.dependencies ?? [];
     story.tags = story.tags ?? [];
+    // Normalize aliases: "open" → "pending", "done" → "passed"
+    const rawStatus = story.status as string;
+    if (rawStatus === "open") story.status = "pending";
+    if (rawStatus === "done") story.status = "passed";
     story.status = story.status ?? "pending";
     story.acceptanceCriteria = story.acceptanceCriteria ?? [];
     story.storyPoints = story.storyPoints ?? 1;

package/src/precheck/checks-warnings.ts

@@ -90,15 +90,19 @@ export async function checkPendingStories(prd: PRD): Promise<Check> {
 /**
  * Check if optional commands are configured.
  */
-export async function checkOptionalCommands(config: NaxConfig): Promise<Check> {
+export async function checkOptionalCommands(config: NaxConfig, workdir: string): Promise<Check> {
   const missing: string[] = [];
 
-  if (!config.execution.lintCommand) {
-    missing.push("lint");
-  }
-  if (!config.execution.typecheckCommand) {
-    missing.push("typecheck");
-  }
+  // Check quality.commands first, then execution config, then package.json fallback
+  const hasLint =
+    config.quality?.commands?.lint || config.execution?.lintCommand || (await hasPackageScript(workdir, "lint"));
+  const hasTypecheck =
+    config.quality?.commands?.typecheck ||
+    config.execution?.typecheckCommand ||
+    (await hasPackageScript(workdir, "typecheck"));
+
+  if (!hasLint) missing.push("lint");
+  if (!hasTypecheck) missing.push("typecheck");
 
   const passed = missing.length === 0;
 
@@ -110,6 +114,16 @@ export async function checkOptionalCommands(config: NaxConfig): Promise<Check> {
   };
 }
 
+/** Check if package.json has a script by name */
+async function hasPackageScript(workdir: string, name: string): Promise<boolean> {
+  try {
+    const pkg = await Bun.file(`${workdir}/package.json`).json();
+    return Boolean(pkg?.scripts?.[name]);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Check if .gitignore covers nax runtime files.
  * Patterns: nax.lock, runs/, test/tmp/

package/src/precheck/index.ts

@@ -141,7 +141,7 @@ export async function runPrecheck(
       () => checkClaudeMdExists(workdir),
       () => checkDiskSpace(),
       () => checkPendingStories(prd),
-      () => checkOptionalCommands(config),
+      () => checkOptionalCommands(config, workdir),
       () => checkGitignoreCoversNax(workdir),
       () => checkPromptOverrideFiles(config, workdir),
     ];

package/src/prompts/builder.ts

@@ -12,6 +12,10 @@
 
 import type { NaxConfig } from "../config/types";
 import type { UserStory } from "../prd";
+import { buildConventionsSection } from "./sections/conventions";
+import { buildIsolationSection } from "./sections/isolation";
+import { buildRoleTaskSection } from "./sections/role-task";
+import { buildStorySection } from "./sections/story";
 import type { PromptOptions, PromptRole } from "./types";
 
 const SECTION_SEP = "\n\n---\n\n";
@@ -69,16 +73,17 @@ export class PromptBuilder {
       sections.push(`# CONSTITUTION (follow these rules strictly)\n\n${this._constitution}`);
     }
 
-    // (2) Role task body — user override or default template
+    // (2) Role task body — user override or default section
     sections.push(await this._resolveRoleBody());
 
     // (3) Story context — non-overridable
     if (this._story) {
-      sections.push(buildStoryContext(this._story));
+      sections.push(buildStorySection(this._story));
     }
 
     // (4) Isolation rules — non-overridable
-    sections.push(buildIsolationRules(this._role, this._options));
+    const isolation = this._options.isolation as string | undefined;
+    sections.push(buildIsolationSection(this._role, isolation as "strict" | "lite" | undefined));
 
     // (5) Context markdown
     if (this._contextMd) {
@@ -86,7 +91,7 @@ export class PromptBuilder {
     }
 
     // (6) Conventions footer — non-overridable, always last
-    sections.push(CONVENTIONS_FOOTER);
+    sections.push(buildConventionsSection());
 
     return sections.join(SECTION_SEP);
   }
@@ -107,72 +112,10 @@ export class PromptBuilder {
           return await file.text();
         }
       } catch {
-        // fall through to default template
+        // fall through to default section
       }
     }
-    return buildDefaultRoleBody(this._role, this._story?.title, this._options);
+    const variant = this._options.variant as "standard" | "lite" | undefined;
+    return buildRoleTaskSection(this._role, variant);
   }
 }
-
-// ---------------------------------------------------------------------------
-// Section builders (module-private)
-// ---------------------------------------------------------------------------
-
-function buildDefaultRoleBody(role: PromptRole, title = "", options: PromptOptions = {}): string {
-  const variant = options.variant as string | undefined;
-  switch (role) {
-    case "test-writer":
-      return `# Test Writer — "${title}"\n\nYour role: Write failing tests ONLY. Do NOT implement any source code.`;
-    case "implementer":
-      if (variant === "lite") {
-        return `# Implementer (Lite) — "${title}"\n\nYour role: Write tests AND implement the feature in a single session.`;
-      }
-      return `# Implementer — "${title}"\n\nYour role: Make all failing tests pass.`;
-    case "verifier":
-      return `# Verifier — "${title}"\n\nYour role: Verify the implementation and tests.`;
-    case "single-session":
-      return `# Task — "${title}"\n\nYour role: Write tests AND implement the feature in a single session.`;
-  }
-}
-
-function buildStoryContext(story: UserStory): string {
-  return `# Story Context
-
-**Story:** ${story.title}
-
-**Description:**
-${story.description}
-
-**Acceptance Criteria:**
-${story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n")}`;
-}
-
-const TEST_FILTER_RULE =
-  "When running tests, run ONLY test files related to your changes" +
-  " (e.g. `bun test ./test/specific.test.ts`). NEVER run `bun test` without a file filter" +
-  " — full suite output will flood your context window and cause failures.";
-
-function buildIsolationRules(role: PromptRole, options: PromptOptions = {}): string {
-  const header = "# Isolation Rules\n\n";
-  const footer = `\n\n${TEST_FILTER_RULE}`;
-  const isolation = options.isolation as string | undefined;
-
-  switch (role) {
-    case "test-writer":
-      if (isolation === "lite") {
-        return `${header}isolation scope: Primarily create test files in the test/ directory. You MAY read source files and MAY import from source files to ensure correct types/interfaces. Stub-only src/ files are allowed (empty exports, no logic). Tests must fail for the right reasons (feature not implemented).${footer}`;
-      }
-      return `${header}isolation scope: Only create or modify files in the test/ directory. Tests must fail because the feature is not yet implemented. Do NOT modify any source files in src/.${footer}`;
-    case "implementer":
-      return `${header}isolation scope: Implement source code in src/ to make the tests pass. Do NOT modify test files. Run tests frequently to track progress.${footer}`;
-    case "verifier":
-      return `${header}isolation scope: Verify and fix only — do not change behaviour unless it violates acceptance criteria. Ensure all tests pass and all criteria are met.${footer}`;
-    case "single-session":
-      return `${header}isolation scope: Write tests first (test/ directory), then implement (src/ directory). All tests must pass by the end.${footer}`;
-  }
-}
-
-const CONVENTIONS_FOOTER =
-  "# Conventions\n\n" +
-  "Follow existing code patterns and conventions. Write idiomatic, maintainable code." +
-  " Commit your changes when done.";

package/src/prompts/sections/isolation.ts

@@ -1,9 +1,15 @@
 /**
  * Isolation Rules Section
  *
- * Generates isolation rules based on mode:
- * - strict: No access to src/ files
- * - lite: May read src/ and create minimal stubs
+ * Generates isolation rules for all 4 roles:
+ * - test-writer: Strict/Lite modes for test-first TDD
+ * - implementer: Implement source while respecting test integrity
+ * - verifier: Read-only inspection
+ * - single-session: Both test/ and src/ modification allowed
+ *
+ * Backwards compatible: also accepts old API (mode only)
+ * - buildIsolationSection("strict") → test-writer, strict
+ * - buildIsolationSection("lite") → test-writer, lite
  */
 
 const TEST_FILTER_RULE =
@@ -11,14 +17,38 @@ const TEST_FILTER_RULE =
   "(e.g. `bun test ./test/specific.test.ts`). NEVER run `bun test` without a file filter " +
   "— full suite output will flood your context window and cause failures.";
 
-export function buildIsolationSection(mode: "strict" | "lite"): string {
+export function buildIsolationSection(
+  roleOrMode: "implementer" | "test-writer" | "verifier" | "single-session" | "strict" | "lite",
+  mode?: "strict" | "lite",
+): string {
+  // Old API support: buildIsolationSection("strict") or buildIsolationSection("lite")
+  if ((roleOrMode === "strict" || roleOrMode === "lite") && mode === undefined) {
+    return buildIsolationSection("test-writer", roleOrMode);
+  }
+
+  const role = roleOrMode as "implementer" | "test-writer" | "verifier" | "single-session";
+
   const header = "# Isolation Rules\n\n";
   const footer = `\n\n${TEST_FILTER_RULE}`;
 
-  if (mode === "strict") {
-    return `${header}isolation scope: Isolation scope: Only create or modify files in the test/ directory. Tests must fail because the feature is not yet implemented. Do NOT modify any source files in src/.${footer}`;
+  if (role === "test-writer") {
+    const m = mode ?? "strict";
+    if (m === "strict") {
+      return `${header}isolation scope: Only create or modify files in the test/ directory. Tests must fail because the feature is not yet implemented. Do NOT modify any source files in src/.${footer}`;
+    }
+
+    // lite mode for test-writer
+    return `${header}isolation scope: Create test files in test/. MAY read src/ files and MAY import from src/ to ensure correct types/interfaces. May create minimal stubs in src/ if needed to make imports work, but do NOT implement real logic.${footer}`;
+  }
+
+  if (role === "implementer") {
+    return `${header}isolation scope: Implement source code in src/ to make tests pass. Do not modify test files. Run tests frequently to track progress.${footer}`;
+  }
+
+  if (role === "verifier") {
+    return `${header}isolation scope: Read-only inspection. Review all test results, implementation code, and acceptance criteria compliance. You MAY write a verdict file (.nax-verifier-verdict.json) and apply legitimate fixes if needed.${footer}`;
   }
 
-  // lite mode
-  return `${header}isolation scope: Create test files in test/. MAY read src/ files and MAY import from src/ to ensure correct types/interfaces. May create minimal stubs in src/ if needed to make imports work, but do NOT implement real logic.${footer}`;
+  // single-session role
+  return `${header}isolation scope: Create test files in test/ directory, then implement source code in src/ to make tests pass. Both directories are in scope for this session.${footer}`;
 }

package/src/prompts/sections/role-task.ts

@@ -1,34 +1,94 @@
 /**
  * Role-Task Section
  *
- * Generates role definition for:
- * - standard: Make failing tests pass (implementer role)
- * - lite: Write tests first then implement (combined role)
+ * Generates role definition for all 4 roles in nax prompt orchestration:
+ * - implementer: Make failing tests pass (standard/lite variants)
+ * - test-writer: Write tests first (RED phase)
+ * - verifier: Review and verify implementation
+ * - single-session: Write tests AND implement in one session
+ *
+ * Backwards compatible: also accepts old API (variant only)
+ * - buildRoleTaskSection("standard") → implementer, standard
+ * - buildRoleTaskSection("lite") → implementer, lite
  */
 
-export function buildRoleTaskSection(variant: "standard" | "lite"): string {
-  if (variant === "standard") {
+export function buildRoleTaskSection(
+  roleOrVariant: "implementer" | "test-writer" | "verifier" | "single-session" | "standard" | "lite",
+  variant?: "standard" | "lite",
+): string {
+  // Old API support: buildRoleTaskSection("standard") or buildRoleTaskSection("lite")
+  if ((roleOrVariant === "standard" || roleOrVariant === "lite") && variant === undefined) {
+    return buildRoleTaskSection("implementer", roleOrVariant);
+  }
+
+  const role = roleOrVariant as "implementer" | "test-writer" | "verifier" | "single-session";
+
+  if (role === "implementer") {
+    const v = variant ?? "standard";
+    if (v === "standard") {
+      return (
+        "# Role: Implementer\n\n" +
+        "Your task: make failing tests pass.\n\n" +
+        "Instructions:\n" +
+        "- Implement source code in src/ to make tests pass\n" +
+        "- Do NOT modify test files\n" +
+        "- Run tests frequently to track progress\n" +
+        "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
+        "- Goal: all tests green, all changes committed"
+      );
+    }
+
+    // lite variant
+    return (
+      "# Role: Implementer (Lite)\n\n" +
+      "Your task: Write tests AND implement the feature in a single session.\n\n" +
+      "Instructions:\n" +
+      "- Write tests first (test/ directory), then implement (src/ directory)\n" +
+      "- All tests must pass by the end\n" +
+      "- Use Bun test (describe/test/expect)\n" +
+      "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
+      "- Goal: all tests green, all criteria met, all changes committed"
+    );
+  }
+
+  if (role === "test-writer") {
+    return (
+      "# Role: Test-Writer\n\n" +
+      "Your task: Write comprehensive failing tests for the feature.\n\n" +
+      "Instructions:\n" +
+      "- Create test files in test/ directory that cover acceptance criteria\n" +
+      "- Tests must fail initially (RED phase) — the feature is not yet implemented\n" +
+      "- Use Bun test (describe/test/expect)\n" +
+      "- Write clear test names that document expected behavior\n" +
+      "- Focus on behavior, not implementation details\n" +
+      "- Goal: comprehensive test suite ready for implementation"
+    );
+  }
+
+  if (role === "verifier") {
     return (
-      "# Role: Implementer\n\n" +
-      "Your task: make failing tests pass.\n\n" +
+      "# Role: Verifier\n\n" +
+      "Your task: Review and verify the implementation against acceptance criteria.\n\n" +
       "Instructions:\n" +
-      "- Implement source code in src/ to make tests pass\n" +
-      "- Do NOT modify test files\n" +
-      "- Run tests frequently to track progress\n" +
-      "- When all tests are green, stage and commit ALL changed files with git commit -m 'feat: <description>'\n" +
-      "- Goal: all tests green, all changes committed"
+      "- Review all test results — verify tests pass\n" +
+      "- Check that implementation meets all acceptance criteria\n" +
+      "- Inspect code quality, error handling, and edge cases\n" +
+      "- Verify test modifications (if any) are legitimate fixes\n" +
+      "- Write a detailed verdict with reasoning\n" +
+      "- Goal: provide comprehensive verification and quality assurance"
     );
   }
 
-  // lite variant
+  // single-session role
   return (
-    "# Role: Implementer (Lite)\n\n" +
-    "Your task: Write tests AND implement the feature in a single session.\n\n" +
+    "# Role: Single-Session\n\n" +
+    "Your task: Write tests AND implement the feature in a single focused session.\n\n" +
     "Instructions:\n" +
-    "- Write tests first (test/ directory), then implement (src/ directory)\n" +
-    "- All tests must pass by the end\n" +
+    "- Phase 1: Write comprehensive tests (test/ directory)\n" +
+    "- Phase 2: Implement to make all tests pass (src/ directory)\n" +
     "- Use Bun test (describe/test/expect)\n" +
-    "- When all tests are green, stage and commit ALL changed files with git commit -m 'feat: <description>'\n" +
-    "- Goal: all tests green, all criteria met, all changes committed"
+    "- Run tests frequently throughout implementation\n" +
+    "- When all tests are green, stage and commit ALL changed files with: git commit -m 'feat: <description>'\n" +
+    "- Goal: all tests passing, all changes committed, full story complete"
   );
 }

package/src/tdd/session-runner.ts

@@ -103,7 +103,11 @@ export async function runTddSession(
         .build();
       break;
     case "verifier":
-      prompt = await PromptBuilder.for("verifier").withLoader(workdir, config).story(story).build();
+      prompt = await PromptBuilder.for("verifier")
+        .withLoader(workdir, config)
+        .story(story)
+        .context(contextMarkdown)
+        .build();
       break;
   }
 

package/src/prompts/templates/implementer.ts

@@ -1,6 +0,0 @@
-/**
- * Default template body for the implementer role.
- * Stub — logic not yet implemented.
- */
-
-export const defaultTemplate = "";