@nathapp/nax 0.27.1 → 0.28.0

package/src/prompts/builder.ts

@@ -0,0 +1,178 @@
+/**
+ * PromptBuilder — unified entry point for composing agent prompts.
+ *
+ * Composes prompts from ordered sections:
+ *   (1) Constitution
+ *   (2) Role task body (user override OR default template)
+ *   (3) Story context          [non-overridable]
+ *   (4) Isolation rules        [non-overridable]
+ *   (5) Context markdown
+ *   (6) Conventions footer     [non-overridable, always last]
+ */
+
+import type { NaxConfig } from "../config/types";
+import type { UserStory } from "../prd";
+import type { PromptOptions, PromptRole } from "./types";
+
+const SECTION_SEP = "\n\n---\n\n";
+
+export class PromptBuilder {
+  private _role: PromptRole;
+  private _options: PromptOptions;
+  private _story: UserStory | undefined;
+  private _contextMd: string | undefined;
+  private _constitution: string | undefined;
+  private _overridePath: string | undefined;
+  private _workdir: string | undefined;
+  private _loaderConfig: NaxConfig | undefined;
+
+  private constructor(role: PromptRole, options: PromptOptions = {}) {
+    this._role = role;
+    this._options = options;
+  }
+
+  static for(role: PromptRole, options?: PromptOptions): PromptBuilder {
+    return new PromptBuilder(role, options ?? {});
+  }
+
+  story(story: UserStory): PromptBuilder {
+    this._story = story;
+    return this;
+  }
+
+  context(md: string | undefined): PromptBuilder {
+    if (md) this._contextMd = md;
+    return this;
+  }
+
+  constitution(c: string | undefined): PromptBuilder {
+    if (c) this._constitution = c;
+    return this;
+  }
+
+  override(path: string): PromptBuilder {
+    this._overridePath = path;
+    return this;
+  }
+
+  withLoader(workdir: string, config: NaxConfig): PromptBuilder {
+    this._workdir = workdir;
+    this._loaderConfig = config;
+    return this;
+  }
+
+  async build(): Promise<string> {
+    const sections: string[] = [];
+
+    // (1) Constitution
+    if (this._constitution) {
+      sections.push(`# CONSTITUTION (follow these rules strictly)\n\n${this._constitution}`);
+    }
+
+    // (2) Role task body — user override or default template
+    sections.push(await this._resolveRoleBody());
+
+    // (3) Story context — non-overridable
+    if (this._story) {
+      sections.push(buildStoryContext(this._story));
+    }
+
+    // (4) Isolation rules — non-overridable
+    sections.push(buildIsolationRules(this._role, this._options));
+
+    // (5) Context markdown
+    if (this._contextMd) {
+      sections.push(this._contextMd);
+    }
+
+    // (6) Conventions footer — non-overridable, always last
+    sections.push(CONVENTIONS_FOOTER);
+
+    return sections.join(SECTION_SEP);
+  }
+
+  private async _resolveRoleBody(): Promise<string> {
+    // withLoader takes priority over explicit override path
+    if (this._workdir && this._loaderConfig) {
+      const { loadOverride } = await import("./loader");
+      const content = await loadOverride(this._role, this._workdir, this._loaderConfig);
+      if (content !== null) {
+        return content;
+      }
+    }
+    if (this._overridePath) {
+      try {
+        const file = Bun.file(this._overridePath);
+        if (await file.exists()) {
+          return await file.text();
+        }
+      } catch {
+        // fall through to default template
+      }
+    }
+    return buildDefaultRoleBody(this._role, this._story?.title, this._options);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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/index.ts

@@ -0,0 +1,2 @@
+export { PromptBuilder } from "./builder";
+export type { PromptRole, PromptSection, PromptOptions } from "./types";

package/src/prompts/loader.ts

@@ -0,0 +1,43 @@
+/**
+ * Prompt Override Loader
+ *
+ * Resolves and reads user-supplied override files relative to workdir.
+ */
+
+import { join } from "node:path";
+import type { NaxConfig } from "../config/types";
+import type { PromptRole } from "./types";
+
+/**
+ * Load a user override for the given role from the path specified in config.
+ *
+ * @param role - The prompt role
+ * @param workdir - The project working directory
+ * @param config - The merged NaxConfig
+ * @returns The override file contents, or null if absent/missing
+ * @throws Error when file path is set but file is unreadable (e.g. permissions error)
+ */
+export async function loadOverride(role: PromptRole, workdir: string, config: NaxConfig): Promise<string | null> {
+  const overridePath = config.prompts?.overrides?.[role];
+
+  if (!overridePath) {
+    return null;
+  }
+
+  const absolutePath = join(workdir, overridePath);
+  const file = Bun.file(absolutePath);
+
+  if (!(await file.exists())) {
+    return null;
+  }
+
+  try {
+    return await file.text();
+  } catch (err) {
+    throw new Error(
+      `Cannot read prompt override for role "${role}" at "${absolutePath}": ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}

package/src/prompts/sections/conventions.ts

@@ -0,0 +1,15 @@
+/**
+ * Conventions Section
+ *
+ * Includes bun test scoping warning and commit message instructions (non-overridable).
+ */
+
+export function buildConventionsSection(): string {
+  return (
+    "# Conventions\n\n" +
+    "Follow existing code patterns and conventions. Write idiomatic, maintainable code.\n\n" +
+    "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.\n\n" +
+    "Commit your changes when done using conventional commit format (e.g. `feat:`, `fix:`, `test:`)."
+  );
+}

package/src/prompts/sections/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Prompt Sections
+ *
+ * Non-overridable section builders for the PromptBuilder.
+ */
+
+export { buildIsolationSection } from "./isolation";
+export { buildRoleTaskSection } from "./role-task";
+export { buildStorySection } from "./story";
+export { buildVerdictSection } from "./verdict";
+export { buildConventionsSection } from "./conventions";

package/src/prompts/sections/isolation.ts

@@ -0,0 +1,24 @@
+/**
+ * Isolation Rules Section
+ *
+ * Generates isolation rules based on mode:
+ * - strict: No access to src/ files
+ * - lite: May read src/ and create minimal stubs
+ */
+
+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.";
+
+export function buildIsolationSection(mode: "strict" | "lite"): string {
+  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}`;
+  }
+
+  // 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}`;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Role-Task Section
+ *
+ * Generates role definition for:
+ * - standard: Make failing tests pass (implementer role)
+ * - lite: Write tests first then implement (combined role)
+ */
+
+export function buildRoleTaskSection(variant: "standard" | "lite"): string {
+  if (variant === "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" +
+      "- Goal: all tests green"
+    );
+  }
+
+  // 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" +
+    "- Goal: all tests green, all criteria met"
+  );
+}

package/src/prompts/sections/story.ts

@@ -0,0 +1,13 @@
+/**
+ * Story Section
+ *
+ * Formats story title, description, and numbered acceptance criteria.
+ */
+
+import type { UserStory } from "../../prd/types";
+
+export function buildStorySection(story: UserStory): string {
+  const criteria = story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
+
+  return `# Story Context\n\n**Story:** ${story.title}\n\n**Description:**\n${story.description}\n\n**Acceptance Criteria:**\n${criteria}`;
+}

package/src/prompts/sections/verdict.ts

@@ -0,0 +1,70 @@
+/**
+ * Verdict Section
+ *
+ * Verifier verdict JSON schema instructions (non-overridable).
+ * Provides instructions for writing the .nax-verifier-verdict.json file.
+ */
+
+import type { UserStory } from "../../prd/types";
+
+export function buildVerdictSection(story: UserStory): string {
+  return `# Verdict Instructions
+
+## Write Verdict File
+
+After completing your verification, you **MUST** write a verdict file at the **project root**:
+
+**File:** \`.nax-verifier-verdict.json\`
+
+Set \`approved: true\` when ALL of these conditions are met:
+- All tests pass
+- Implementation is clean and follows conventions
+- All acceptance criteria met
+- Any test modifications by implementer are legitimate fixes
+
+Set \`approved: false\` when ANY of these conditions are true:
+- Tests are failing and you cannot fix them
+- The implementer loosened test assertions to mask bugs
+- Critical acceptance criteria are not met
+- Code quality is poor (security issues, severe bugs, etc.)
+
+**Full JSON schema example** (fill in all fields with real values):
+
+\`\`\`json
+{
+  "version": 1,
+  "approved": true,
+  "tests": {
+    "allPassing": true,
+    "passCount": 42,
+    "failCount": 0
+  },
+  "testModifications": {
+    "detected": false,
+    "files": [],
+    "legitimate": true,
+    "reasoning": "No test files were modified by the implementer"
+  },
+  "acceptanceCriteria": {
+    "allMet": true,
+    "criteria": [
+      { "criterion": "Example criterion", "met": true }
+    ]
+  },
+  "quality": {
+    "rating": "good",
+    "issues": []
+  },
+  "fixes": [],
+  "reasoning": "All tests pass, implementation is clean, all acceptance criteria are met."
+}
+\`\`\`
+
+**Field notes:**
+- \`quality.rating\` must be one of: \`"good"\`, \`"acceptable"\`, \`"poor"\`
+- \`testModifications.files\` — list any test files the implementer changed
+- \`fixes\` — list any fixes you applied yourself during this verification session
+- \`reasoning\` — brief summary of your overall assessment
+
+When done, commit any fixes with message: "fix: verify and adjust ${story.title}"`;
+}

package/src/prompts/templates/implementer.ts

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

package/src/prompts/templates/single-session.ts

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

package/src/prompts/templates/test-writer.ts

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

package/src/prompts/templates/verifier.ts

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

package/src/prompts/types.ts

@@ -0,0 +1,21 @@
+/**
+ * PromptBuilder Types
+ *
+ * Shared types for the unified prompt building system.
+ */
+
+/** Role determining which default template body to use */
+export type PromptRole = "test-writer" | "implementer" | "verifier" | "single-session";
+
+/** A single section of a composed prompt */
+export interface PromptSection {
+  /** Unique section identifier */
+  id: string;
+  /** Section content */
+  content: string;
+  /** Whether this section can be removed by user override */
+  overridable: boolean;
+}
+
+/** Options passed to PromptBuilder.for() */
+export type PromptOptions = Record<string, unknown>;

package/src/tdd/session-runner.ts

@@ -9,15 +9,9 @@ import type { ModelTier, NaxConfig } from "../config";
 import { resolveModel } from "../config";
 import { getLogger } from "../logger";
 import type { UserStory } from "../prd";
+import { PromptBuilder } from "../prompts";
 import { cleanupProcessTree } from "./cleanup";
 import { getChangedFiles, verifyImplementerIsolation, verifyTestWriterIsolation } from "./isolation";
-import {
-  buildImplementerLitePrompt,
-  buildImplementerPrompt,
-  buildTestWriterLitePrompt,
-  buildTestWriterPrompt,
-  buildVerifierPrompt,
-} from "./prompts";
 import type { IsolationCheck } from "./types";
 import type { TddSessionResult, TddSessionRole } from "./types";
 
@@ -95,15 +89,21 @@ export async function runTddSession(
   let prompt: string;
   switch (role) {
     case "test-writer":
-      prompt = lite ? buildTestWriterLitePrompt(story, contextMarkdown) : buildTestWriterPrompt(story, contextMarkdown);
+      prompt = await PromptBuilder.for("test-writer", { isolation: lite ? "lite" : "strict" })
+        .withLoader(workdir, config)
+        .story(story)
+        .context(contextMarkdown)
+        .build();
       break;
     case "implementer":
-      prompt = lite
-        ? buildImplementerLitePrompt(story, contextMarkdown)
-        : buildImplementerPrompt(story, contextMarkdown);
+      prompt = await PromptBuilder.for("implementer", { variant: lite ? "lite" : "standard" })
+        .withLoader(workdir, config)
+        .story(story)
+        .context(contextMarkdown)
+        .build();
       break;
     case "verifier":
-      prompt = buildVerifierPrompt(story);
+      prompt = await PromptBuilder.for("verifier").withLoader(workdir, config).story(story).build();
       break;
   }
 

package/test/integration/cli/cli-config-prompts-explain.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Integration tests for `nax config --explain` prompts section (PB-005)
+ *
+ * Verifies that the prompts.overrides config block is documented in the
+ * --explain output with example paths.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { configCommand } from "../../../src/cli/config";
+import { loadConfig } from "../../../src/config/loader";
+
+describe("config --explain: prompts section", () => {
+  let tempDir: string;
+  let originalCwd: string;
+  let consoleOutput: string[];
+  let originalConsoleLog: typeof console.log;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "nax-config-prompts-test-"));
+    originalCwd = process.cwd();
+
+    consoleOutput = [];
+    originalConsoleLog = console.log;
+    console.log = (...args: unknown[]) => {
+      consoleOutput.push(args.map((a) => String(a)).join(" "));
+    };
+  });
+
+  afterEach(() => {
+    console.log = originalConsoleLog;
+    process.chdir(originalCwd);
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("explain output includes a prompts section", async () => {
+    const config = await loadConfig(tempDir);
+    await configCommand(config, { explain: true });
+
+    const output = consoleOutput.join("\n");
+    expect(output).toContain("prompts");
+  });
+
+  test("explain output documents prompts.overrides", async () => {
+    const config = await loadConfig(tempDir);
+    await configCommand(config, { explain: true });
+
+    const output = consoleOutput.join("\n");
+    expect(output).toContain("prompts.overrides");
+  });
+
+  test("explain output includes example path .nax/prompts/test-writer.md", async () => {
+    const config = await loadConfig(tempDir);
+    await configCommand(config, { explain: true });
+
+    const output = consoleOutput.join("\n");
+    expect(output).toContain(".nax/prompts/test-writer.md");
+  });
+
+  test("explain output mentions override roles (test-writer, implementer, verifier)", async () => {
+    const config = await loadConfig(tempDir);
+    await configCommand(config, { explain: true });
+
+    const output = consoleOutput.join("\n");
+    // At least one of the roles should appear in the prompts documentation
+    const mentionsRole =
+      output.includes("test-writer") ||
+      output.includes("implementer") ||
+      output.includes("verifier");
+    expect(mentionsRole).toBe(true);
+  });
+});