@nathapp/nax 0.30.0 → 0.31.0

package/bin/nax.ts

@@ -54,6 +54,7 @@ import {
   planCommand,
   pluginsListCommand,
   promptsCommand,
+  promptsInitCommand,
   runsListCommand,
   runsShowCommand,
 } from "../src/cli";
@@ -849,8 +850,10 @@ program
 // ── prompts ──────────────────────────────────────────
 program
   .command("prompts")
-  .description("Assemble prompts for stories without executing agents")
-  .requiredOption("-f, --feature <name>", "Feature name")
+  .description("Assemble or initialize prompts")
+  .option("-f, --feature <name>", "Feature name (required unless using --init)")
+  .option("--init", "Initialize default prompt templates", false)
+  .option("--force", "Overwrite existing template files", false)
   .option("--story <id>", "Filter to a single story ID (e.g., US-003)")
   .option("--out <dir>", "Output directory for prompt files (default: stdout)")
   .option("-d, --dir <path>", "Project directory", process.cwd())
@@ -864,6 +867,26 @@ program
       process.exit(1);
     }
 
+    // Handle --init command
+    if (options.init) {
+      try {
+        await promptsInitCommand({
+          workdir,
+          force: options.force,
+        });
+      } catch (err) {
+        console.error(chalk.red(`Error: ${(err as Error).message}`));
+        process.exit(1);
+      }
+      return;
+    }
+
+    // Handle regular prompts command (requires --feature)
+    if (!options.feature) {
+      console.error(chalk.red("Error: --feature is required (unless using --init)"));
+      process.exit(1);
+    }
+
     // Load config
     const config = await loadConfig(workdir);
 

package/dist/nax.js

@@ -19505,7 +19505,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.30.0",
+    version: "0.31.0",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -19567,8 +19567,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("f7c3de1"))
-        return "f7c3de1";
+      if (/^[0-9a-f]{6,10}$/.test("6b2cc85"))
+        return "6b2cc85";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -19621,6 +19621,11 @@ async function loadPRD(path) {
     story.escalations = story.escalations ?? [];
     story.dependencies = story.dependencies ?? [];
     story.tags = story.tags ?? [];
+    const rawStatus = story.status;
+    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;
@@ -23980,7 +23985,7 @@ async function runTddSession(role, agent, story, config2, workdir, modelTier, be
       prompt = await PromptBuilder.for("implementer", { variant: lite ? "lite" : "standard" }).withLoader(workdir, config2).story(story).context(contextMarkdown).build();
       break;
     case "verifier":
-      prompt = await PromptBuilder.for("verifier").withLoader(workdir, config2).story(story).build();
+      prompt = await PromptBuilder.for("verifier").withLoader(workdir, config2).story(story).context(contextMarkdown).build();
       break;
   }
   const logger = getLogger();
@@ -26889,14 +26894,14 @@ async function checkPendingStories(prd) {
     message: passed ? `${pendingStories.length} pending stories found` : "no pending stories to execute"
   };
 }
-async function checkOptionalCommands(config2) {
+async function checkOptionalCommands(config2, workdir) {
   const missing = [];
-  if (!config2.execution.lintCommand) {
+  const hasLint = config2.quality?.commands?.lint || config2.execution?.lintCommand || await hasPackageScript(workdir, "lint");
+  const hasTypecheck = config2.quality?.commands?.typecheck || config2.execution?.typecheckCommand || await hasPackageScript(workdir, "typecheck");
+  if (!hasLint)
     missing.push("lint");
-  }
-  if (!config2.execution.typecheckCommand) {
+  if (!hasTypecheck)
     missing.push("typecheck");
-  }
   const passed = missing.length === 0;
   return {
     name: "optional-commands-configured",
@@ -26905,6 +26910,14 @@ async function checkOptionalCommands(config2) {
     message: passed ? "All optional commands configured" : `Optional commands not configured: ${missing.join(", ")}`
   };
 }
+async function hasPackageScript(workdir, name) {
+  try {
+    const pkg = await Bun.file(`${workdir}/package.json`).json();
+    return Boolean(pkg?.scripts?.[name]);
+  } catch {
+    return false;
+  }
+}
 async function checkGitignoreCoversNax(workdir) {
   const gitignorePath = `${workdir}/.gitignore`;
   const exists = existsSync23(gitignorePath);
@@ -27096,7 +27109,7 @@ async function runPrecheck(config2, prd, options) {
       () => checkClaudeMdExists(workdir),
       () => checkDiskSpace(),
       () => checkPendingStories(prd),
-      () => checkOptionalCommands(config2),
+      () => checkOptionalCommands(config2, workdir),
       () => checkGitignoreCoversNax(workdir),
       () => checkPromptOverrideFiles(config2, workdir)
     ];
@@ -62763,11 +62776,119 @@ function buildFrontmatter(story, ctx, role) {
 `)}
 `;
 }
+var TEMPLATE_ROLES = [
+  { file: "test-writer.md", role: "test-writer" },
+  { file: "implementer.md", role: "implementer", variant: "standard" },
+  { file: "verifier.md", role: "verifier" },
+  { file: "single-session.md", role: "single-session" }
+];
+var 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" } } }
+-->
+
+`;
+async function promptsInitCommand(options) {
+  const { workdir, force = false } = options;
+  const templatesDir = join18(workdir, "nax", "templates");
+  mkdirSync3(templatesDir, { recursive: true });
+  const existingFiles = TEMPLATE_ROLES.map((t) => t.file).filter((f) => existsSync15(join18(templatesDir, f)));
+  if (existingFiles.length > 0 && !force) {
+    console.warn(`[WARN] nax/templates/ already contains files: ${existingFiles.join(", ")}. No files overwritten.
+       Pass --force to overwrite existing templates.`);
+    return [];
+  }
+  const written = [];
+  for (const template of TEMPLATE_ROLES) {
+    const filePath = join18(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}/`, "")}`);
+  }
+  await autoWirePromptsConfig(workdir);
+  return written;
+}
+async function autoWirePromptsConfig(workdir) {
+  const configPath = join18(workdir, "nax.config.json");
+  if (!existsSync15(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(`
+No nax.config.json found. To activate overrides, create nax/config.json with:
+${exampleConfig}`);
+    return;
+  }
+  const configFile = Bun.file(configPath);
+  const configContent = await configFile.text();
+  const config2 = JSON.parse(configContent);
+  if (config2.prompts?.overrides && Object.keys(config2.prompts.overrides).length > 0) {
+    console.log(`[INFO] prompts.overrides already configured in nax.config.json. Skipping auto-wiring.
+` + "       To reset overrides, remove the prompts.overrides section and re-run this command.");
+    return;
+  }
+  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"
+  };
+  if (!config2.prompts) {
+    config2.prompts = {};
+  }
+  config2.prompts.overrides = overrides;
+  const updatedConfig = formatConfigJson(config2);
+  await Bun.write(configPath, updatedConfig);
+  console.log("[OK] Auto-wired prompts.overrides in nax.config.json");
+}
+function formatConfigJson(config2) {
+  const lines = ["{"];
+  const keys = Object.keys(config2);
+  for (let i = 0;i < keys.length; i++) {
+    const key = keys[i];
+    const value = config2[key];
+    const isLast = i === keys.length - 1;
+    if (key === "prompts" && typeof value === "object" && value !== null) {
+      const promptsObj = value;
+      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(`
+`);
+}
 async function handleThreeSessionTddPrompts(story, ctx, outputDir, logger) {
   const [testWriterPrompt, implementerPrompt, verifierPrompt] = await Promise.all([
     PromptBuilder.for("test-writer", { isolation: "strict" }).withLoader(ctx.workdir, ctx.config).story(story).context(ctx.contextMarkdown).build(),
     PromptBuilder.for("implementer", { variant: "standard" }).withLoader(ctx.workdir, ctx.config).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 = [
     { role: "test-writer", prompt: testWriterPrompt },
@@ -72689,7 +72810,7 @@ program2.command("accept").description("Override failed acceptance criteria").re
     process.exit(1);
   }
 });
-program2.command("prompts").description("Assemble prompts for stories without executing agents").requiredOption("-f, --feature <name>", "Feature name").option("--story <id>", "Filter to a single story ID (e.g., US-003)").option("--out <dir>", "Output directory for prompt files (default: stdout)").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (options) => {
+program2.command("prompts").description("Assemble or initialize prompts").option("-f, --feature <name>", "Feature name (required unless using --init)").option("--init", "Initialize default prompt templates", false).option("--force", "Overwrite existing template files", false).option("--story <id>", "Filter to a single story ID (e.g., US-003)").option("--out <dir>", "Output directory for prompt files (default: stdout)").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (options) => {
   let workdir;
   try {
     workdir = validateDirectory(options.dir);
@@ -72697,6 +72818,22 @@ program2.command("prompts").description("Assemble prompts for stories without ex
     console.error(source_default.red(`Invalid directory: ${err.message}`));
     process.exit(1);
   }
+  if (options.init) {
+    try {
+      await promptsInitCommand({
+        workdir,
+        force: options.force
+      });
+    } catch (err) {
+      console.error(source_default.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+    return;
+  }
+  if (!options.feature) {
+    console.error(source_default.red("Error: --feature is required (unless using --init)"));
+    process.exit(1);
+  }
   const config2 = await loadConfig(workdir);
   try {
     const processedStories = await promptsCommand({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

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/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/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;
   }