@arvorco/relentless 0.3.1 → 0.4.2

package/src/init/scaffolder.ts

@@ -20,11 +20,242 @@
  * - Does not modify project root files (CLAUDE.md, AGENTS.md, etc.)
  */
 
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import chalk from "chalk";
 import { checkAgentHealth } from "../agents/registry";
-import { DEFAULT_CONFIG } from "../config/schema";
+import { DEFAULT_CONFIG, type Mode } from "../config/schema";
+
+/**
+ * Explanation of Auto Mode shown to users during init
+ */
+export const AUTO_MODE_EXPLANATION = `
+Smart Auto Mode automatically routes tasks to the most cost-effective model
+based on complexity. Simple tasks use free/cheap models, complex tasks use
+premium models. This typically saves 50-75% on API costs.
+`;
+
+/**
+ * Descriptions for each cost mode
+ */
+export const MODE_DESCRIPTIONS: Record<Mode, string> = {
+  free: "Free tier models only (OpenCode) - Maximum savings",
+  cheap: "Budget models (Haiku, Gemini Flash, GPT-5.2 low effort) - High savings, good quality",
+  good: "Balanced models (Sonnet, GPT-5.2 medium effort) - Good savings, high quality (Recommended)",
+  genius: "Premium models (Opus, GPT-5.2 high effort) - No savings, maximum quality",
+};
+
+/**
+ * Estimated savings percentages for each mode
+ */
+const MODE_SAVINGS: Record<Mode, string> = {
+  free: "~95%",
+  cheap: "~75%",
+  good: "~50%",
+  genius: "~0%",
+};
+
+/**
+ * Interface for Auto Mode configuration options
+ */
+export interface InitAutoModeOptions {
+  /** Skip the interactive prompt and use provided values */
+  skipPrompt?: boolean;
+  /** Whether Auto Mode should be enabled */
+  enabled?: boolean;
+  /** Default mode to use */
+  defaultMode?: Mode;
+  /** Generate YAML config instead of JSON */
+  generateYaml?: boolean;
+}
+
+/**
+ * Interface for readline mock (for testing)
+ */
+interface ReadlineInterface {
+  question: (prompt: string, callback: (answer: string) => void) => void;
+  close: () => void;
+}
+
+/**
+ * Options for promptAutoModeConfig
+ */
+export interface PromptAutoModeOptions {
+  /** Readline interface (can be mocked for testing) */
+  readline: ReadlineInterface;
+  /** Default mode if user presses Enter */
+  defaultMode: Mode;
+}
+
+/**
+ * Result from promptAutoModeConfig
+ */
+export interface AutoModeConfigResult {
+  enabled: boolean;
+  defaultMode?: Mode;
+}
+
+/**
+ * Get estimated savings percentage for a mode
+ */
+export function getEstimatedSavings(mode: Mode): string {
+  return MODE_SAVINGS[mode];
+}
+
+/**
+ * Parse Auto Mode related CLI flags
+ */
+export function parseAutoModeFlags(options: {
+  yes?: boolean;
+  noAutoMode?: boolean;
+}): InitAutoModeOptions {
+  // --no-auto-mode takes priority over --yes
+  if (options.noAutoMode) {
+    return {
+      skipPrompt: true,
+      enabled: false,
+    };
+  }
+
+  if (options.yes) {
+    return {
+      skipPrompt: true,
+      enabled: true,
+      defaultMode: "good",
+    };
+  }
+
+  return {
+    skipPrompt: false,
+  };
+}
+
+/**
+ * Check if project already has Auto Mode config
+ */
+export async function hasExistingAutoModeConfig(projectDir: string): Promise<boolean> {
+  const relentlessDir = join(projectDir, "relentless");
+
+  // Check config.json
+  const configJsonPath = join(relentlessDir, "config.json");
+  if (existsSync(configJsonPath)) {
+    try {
+      const content = await Bun.file(configJsonPath).text();
+      const config = JSON.parse(content);
+      if (config.autoMode !== undefined) {
+        return true;
+      }
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  // Check relentless.config.yaml
+  const yamlPath = join(relentlessDir, "relentless.config.yaml");
+  if (existsSync(yamlPath)) {
+    try {
+      const content = await Bun.file(yamlPath).text();
+      if (content.includes("autoMode:")) {
+        return true;
+      }
+    } catch {
+      // Ignore read errors
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Prompt user for Auto Mode configuration
+ */
+export async function promptAutoModeConfig(
+  options: PromptAutoModeOptions
+): Promise<AutoModeConfigResult> {
+  const { readline, defaultMode } = options;
+
+  return new Promise((resolve) => {
+    // First question: Enable Auto Mode?
+    readline.question(
+      chalk.yellow("Enable Smart Auto Mode? (Saves 50-75% on costs) [Y/n]: "),
+      (enableAnswer) => {
+        const normalizedAnswer = enableAnswer.trim().toLowerCase();
+
+        // Empty or affirmative answers enable Auto Mode
+        if (
+          normalizedAnswer === "" ||
+          normalizedAnswer === "y" ||
+          normalizedAnswer === "yes"
+        ) {
+          // Second question: Select mode
+          readline.question(
+            chalk.yellow(`Default mode? [free/cheap/good/genius] (${defaultMode}): `),
+            (modeAnswer) => {
+              const trimmedMode = modeAnswer.trim().toLowerCase();
+              let selectedMode: Mode = defaultMode;
+
+              if (trimmedMode === "") {
+                selectedMode = defaultMode;
+              } else if (["free", "cheap", "good", "genius"].includes(trimmedMode)) {
+                selectedMode = trimmedMode as Mode;
+              } else {
+                // Invalid mode - use default
+                selectedMode = defaultMode;
+              }
+
+              resolve({
+                enabled: true,
+                defaultMode: selectedMode,
+              });
+            }
+          );
+        } else {
+          // User declined
+          resolve({
+            enabled: false,
+          });
+        }
+      }
+    );
+  });
+}
+
+/**
+ * Generate YAML config content for Auto Mode
+ */
+export function generateAutoModeYamlConfig(config: AutoModeConfigResult): string {
+  const lines: string[] = [];
+
+  lines.push("# Relentless Auto Mode Configuration");
+  lines.push("# Generated by relentless init");
+  lines.push("");
+  lines.push("autoMode:");
+  lines.push(`  enabled: ${config.enabled}`);
+
+  if (config.enabled && config.defaultMode) {
+    lines.push(`  defaultMode: ${config.defaultMode}`);
+    lines.push("");
+    lines.push("  # Harness fallback order (uncomment to customize)");
+    lines.push("  # fallbackOrder:");
+    lines.push("  #   - claude");
+    lines.push("  #   - amp");
+    lines.push("  #   - opencode");
+    lines.push("  #   - codex");
+    lines.push("  #   - gemini");
+    lines.push("  #   - droid");
+    lines.push("");
+    lines.push("  # Custom model mappings by complexity (uncomment to customize)");
+    lines.push("  # modeModels:");
+    lines.push("  #   simple: haiku-4.5");
+    lines.push("  #   medium: sonnet-4.5");
+    lines.push("  #   complex: opus-4.5");
+    lines.push("  #   expert: opus-4.5");
+  }
+
+  lines.push("");
+
+  return lines.join("\n");
+}
 
 /**
  * Get the relentless root directory
@@ -47,14 +278,6 @@ function getRelentlessRoot(): string {
 
 const relentlessRoot = getRelentlessRoot();
 
-/**
- * Files to create in the relentless/ directory
- * These can be force-updated with -f flag
- */
-const RELENTLESS_FILES: Record<string, () => string> = {
-  "config.json": () => JSON.stringify(DEFAULT_CONFIG, null, 2),
-};
-
 /**
  * Default progress.txt content for a new feature with YAML frontmatter
  */
@@ -81,7 +304,11 @@ patterns: []
 /**
  * Initialize Relentless in a project
  */
-export async function initProject(projectDir: string = process.cwd(), force: boolean = false): Promise<void> {
+export async function initProject(
+  projectDir: string = process.cwd(),
+  force: boolean = false,
+  autoModeOptions: InitAutoModeOptions = {}
+): Promise<void> {
   console.log(chalk.bold.blue(`\n🚀 ${force ? "Reinstalling" : "Initializing"} Relentless\n`));
 
   // Check installed agents
@@ -112,17 +339,50 @@ export async function initProject(projectDir: string = process.cwd(), force: boo
   // Create relentless files (can be force-updated)
   console.log(chalk.dim("\nCreating relentless files..."));
 
-  for (const [filename, contentFn] of Object.entries(RELENTLESS_FILES)) {
-    const path = join(relentlessDir, filename);
-
-    if (existsSync(path) && !force) {
-      console.log(`  ${chalk.yellow("⚠")} relentless/${filename} already exists, skipping`);
-      continue;
+  // Generate config with Auto Mode settings if provided
+  const configPath = join(relentlessDir, "config.json");
+  const existingAutoMode = await hasExistingAutoModeConfig(projectDir);
+
+  if (existsSync(configPath) && !force) {
+    console.log(`  ${chalk.yellow("⚠")} relentless/config.json already exists, skipping`);
+  } else {
+    // Build config with Auto Mode settings
+    const config = { ...DEFAULT_CONFIG };
+
+    // Apply Auto Mode options if provided
+    if (autoModeOptions.skipPrompt) {
+      config.autoMode = {
+        ...config.autoMode,
+        enabled: autoModeOptions.enabled ?? false,
+      };
+      if (autoModeOptions.enabled && autoModeOptions.defaultMode) {
+        config.autoMode.defaultMode = autoModeOptions.defaultMode;
+      }
+    } else if (!existingAutoMode) {
+      // Set default autoMode if no existing config
+      config.autoMode = {
+        ...config.autoMode,
+        enabled: autoModeOptions.enabled ?? false,
+      };
+      if (autoModeOptions.enabled && autoModeOptions.defaultMode) {
+        config.autoMode.defaultMode = autoModeOptions.defaultMode;
+      }
     }
 
-    await Bun.write(path, contentFn());
-    const action = existsSync(path) && force ? "updated" : "created";
-    console.log(`  ${chalk.green("✓")} relentless/${filename} ${force ? `(${action})` : ""}`);
+    await Bun.write(configPath, JSON.stringify(config, null, 2));
+    const action = force ? "updated" : "created";
+    console.log(`  ${chalk.green("✓")} relentless/config.json (${action})`);
+  }
+
+  // Generate YAML config if requested
+  if (autoModeOptions.generateYaml && autoModeOptions.enabled !== undefined) {
+    const yamlPath = join(relentlessDir, "relentless.config.yaml");
+    const yamlContent = generateAutoModeYamlConfig({
+      enabled: autoModeOptions.enabled,
+      defaultMode: autoModeOptions.defaultMode,
+    });
+    await Bun.write(yamlPath, yamlContent);
+    console.log(`  ${chalk.green("✓")} relentless/relentless.config.yaml (created)`);
   }
 
   // Note: constitution.md and prompt.md are NOT created here
@@ -171,6 +431,7 @@ export async function initProject(projectDir: string = process.cwd(), force: boo
     "specify",
     "plan",
     "tasks",
+    "convert",
     "checklist",
     "clarify",
     "analyze",
@@ -382,6 +643,7 @@ export async function initProject(projectDir: string = process.cwd(), force: boo
     "relentless.checklist.md",
     "relentless.clarify.md",
     "relentless.constitution.md",
+    "relentless.convert.md",
     "relentless.implement.md",
     "relentless.plan.md",
     "relentless.specify.md",
@@ -573,6 +835,8 @@ For full documentation, see: https://github.com/ArvorCo/Relentless
   console.log(chalk.dim("\n4. Convert to JSON and run:"));
   console.log(`   ${chalk.cyan("relentless convert relentless/features/NNN-feature/tasks.md --feature NNN-feature")}`);
   console.log(`   ${chalk.cyan("relentless run --feature NNN-feature --tui")}`);
+  console.log(chalk.dim("\nUpgrade note:"));
+  console.log(chalk.dim("If you are upgrading Relentless, re-run /relentless.constitution to refresh prompt.md with the latest instructions."));
   console.log("");
 }
 
@@ -662,11 +926,7 @@ export function listFeatures(projectDir: string): string[] {
     return [];
   }
 
-  const entries = Bun.spawnSync(["ls", "-1", featuresDir]);
-  const output = new TextDecoder().decode(entries.stdout);
-
-  return output
-    .split("\n")
+  return readdirSync(featuresDir)
     .map((s) => s.trim())
     .filter((s) => s && s !== ".gitkeep");
 }

package/src/prd/parser.ts

@@ -4,7 +4,8 @@
  * Parses PRD markdown files and converts them to prd.json format
  */
 
-import { PRDSchema, type PRD, type UserStory } from "./types";
+import { PRDSchema, type PRD, type UserStory, type ExecutionHistory, type EscalationAttempt } from "./types";
+import type { Mode, HarnessName } from "../config/schema";
 
 /**
  * Check if a criterion line is valid (not a file path, divider, etc.)
@@ -59,6 +60,26 @@ export function parsePRDMarkdown(content: string): Partial<PRD> {
       continue;
     }
 
+    // Parse routing preference line
+    if (trimmed.match(/^(\*\*Routing Preference\*\*|Routing Preference):/i)) {
+      const raw = trimmed.replace(/^(\*\*Routing Preference\*\*|Routing Preference):/i, "").trim();
+      const lower = raw.toLowerCase();
+      const modeMatch = lower.match(/\b(free|cheap|good|genius)\b/);
+      const allowFreeMatch = lower.match(/allow\s+free:\s*(yes|no)/);
+      const harnessMatch = lower.match(/\b(claude|amp|opencode|codex|droid|gemini)\b/);
+      const modelMatch = raw.match(/\/([^\s]+)/);
+
+      prd.routingPreference = {
+        raw,
+        type: lower.includes("auto") ? "auto" : harnessMatch ? "harness" : undefined,
+        mode: modeMatch ? (modeMatch[1] as Mode) : undefined,
+        allowFree: allowFreeMatch ? allowFreeMatch[1] === "yes" : undefined,
+        harness: harnessMatch ? (harnessMatch[1] as HarnessName) : undefined,
+        model: modelMatch ? modelMatch[1].replace(/[,)]$/, "") : undefined,
+      };
+      continue;
+    }
+
     // Parse section headers (## Section)
     if (trimmed.startsWith("## ")) {
       currentSection = trimmed.replace("## ", "").toLowerCase();
@@ -258,6 +279,10 @@ export function createPRD(parsed: Partial<PRD>, featureName?: string): PRD {
     })),
   };
 
+  if (parsed.routingPreference) {
+    prd.routingPreference = parsed.routingPreference;
+  }
+
   // Validate
   return PRDSchema.parse(prd);
 }
@@ -419,3 +444,69 @@ export async function prioritizeStory(
     previousPriority,
   };
 }
+
+/**
+ * Result of updating story execution history
+ */
+export interface UpdateExecutionResult {
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Update a story's execution history after it completes
+ *
+ * @param prdPath - Path to the prd.json file
+ * @param storyId - The ID of the completed story
+ * @param executionData - Execution data to save
+ * @returns Result indicating success or failure
+ */
+export async function updateStoryExecution(
+  prdPath: string,
+  storyId: string,
+  executionData: {
+    attempts: number;
+    escalations: EscalationAttempt[];
+    actualCost: number;
+    actualHarness: HarnessName;
+    actualModel: string;
+    inputTokens?: number;
+    outputTokens?: number;
+  }
+): Promise<UpdateExecutionResult> {
+  // Load current PRD
+  const prd = await loadPRD(prdPath);
+
+  // Find the story
+  const storyIndex = prd.userStories.findIndex((s) => s.id === storyId);
+  if (storyIndex === -1) {
+    return {
+      success: false,
+      error: `Story ${storyId} not found in PRD`,
+    };
+  }
+
+  // Build execution history
+  const executionHistory: ExecutionHistory = {
+    attempts: executionData.attempts,
+    escalations: executionData.escalations,
+    actualCost: executionData.actualCost,
+    actualHarness: executionData.actualHarness,
+    actualModel: executionData.actualModel,
+    inputTokens: executionData.inputTokens,
+    outputTokens: executionData.outputTokens,
+  };
+
+  // Update the story with execution history
+  prd.userStories[storyIndex] = {
+    ...prd.userStories[storyIndex],
+    execution: executionHistory,
+  };
+
+  // Save the updated PRD
+  await savePRD(prd, prdPath);
+
+  return {
+    success: true,
+  };
+}

package/src/prd/types.ts

@@ -5,6 +5,128 @@
  */
 
 import { z } from "zod";
+import { ModeSchema, ComplexitySchema, HarnessNameSchema } from "../config/schema";
+
+// ============================================================================
+// Routing Metadata Schemas (US-026)
+// ============================================================================
+
+/**
+ * Routing metadata schema for user stories.
+ *
+ * Contains classification and routing decisions made during the
+ * `/relentless.tasks` phase after complexity classification.
+ *
+ * @example
+ * {
+ *   complexity: "medium",
+ *   harness: "claude",
+ *   model: "sonnet-4.5",
+ *   mode: "good",
+ *   estimatedCost: 0.15,
+ *   classificationReasoning: "Keywords suggest medium complexity"
+ * }
+ */
+export const RoutingMetadataSchema = z.object({
+  /** Task complexity level determined by the classifier */
+  complexity: ComplexitySchema,
+  /** Selected harness for executing this story */
+  harness: HarnessNameSchema,
+  /** Selected model within the harness */
+  model: z.string(),
+  /** Mode used for routing decision (free, cheap, good, genius) */
+  mode: ModeSchema,
+  /** Estimated cost in USD based on token estimation */
+  estimatedCost: z.number().nonnegative(),
+  /** Human-readable explanation of classification reasoning (optional) */
+  classificationReasoning: z.string().optional(),
+});
+
+export type RoutingMetadata = z.infer<typeof RoutingMetadataSchema>;
+
+/**
+ * Escalation attempt result type.
+ *
+ * Tracks the result of each execution attempt.
+ */
+export const EscalationResultSchema = z.enum(["success", "failure", "rate_limited"]);
+
+export type EscalationResult = z.infer<typeof EscalationResultSchema>;
+
+/**
+ * Escalation attempt schema.
+ *
+ * Records a single execution attempt with its outcome.
+ *
+ * @example
+ * {
+ *   attempt: 1,
+ *   harness: "claude",
+ *   model: "haiku-4.5",
+ *   result: "failure",
+ *   error: "Task too complex",
+ *   cost: 0.02,
+ *   duration: 45000
+ * }
+ */
+export const EscalationAttemptSchema = z.object({
+  /** Attempt number (1-indexed) */
+  attempt: z.number().int().min(1),
+  /** Harness used for this attempt */
+  harness: HarnessNameSchema,
+  /** Model used for this attempt */
+  model: z.string(),
+  /** Result of the attempt */
+  result: EscalationResultSchema,
+  /** Error message if the attempt failed (optional) */
+  error: z.string().optional(),
+  /** Actual cost for this attempt in USD */
+  cost: z.number().nonnegative(),
+  /** Duration of the attempt in milliseconds */
+  duration: z.number().nonnegative(),
+});
+
+export type EscalationAttempt = z.infer<typeof EscalationAttemptSchema>;
+
+/**
+ * Execution history schema for user stories.
+ *
+ * Contains execution details after the story has been executed,
+ * including escalation attempts and actual costs.
+ *
+ * @example
+ * {
+ *   attempts: 2,
+ *   escalations: [...],
+ *   actualCost: 0.17,
+ *   actualHarness: "claude",
+ *   actualModel: "sonnet-4.5",
+ *   inputTokens: 5000,
+ *   outputTokens: 3000
+ * }
+ */
+export const ExecutionHistorySchema = z.object({
+  /** Total number of attempts made */
+  attempts: z.number().int().min(1),
+  /** Array of escalation attempts with details */
+  escalations: z.array(EscalationAttemptSchema),
+  /** Total actual cost across all attempts in USD */
+  actualCost: z.number().nonnegative(),
+  /** Final harness that successfully completed the story */
+  actualHarness: HarnessNameSchema,
+  /** Final model that successfully completed the story */
+  actualModel: z.string(),
+  /** Total input tokens used across all attempts (optional) */
+  inputTokens: z.number().nonnegative().optional(),
+  /** Total output tokens used across all attempts (optional) */
+  outputTokens: z.number().nonnegative().optional(),
+});
+
+export type ExecutionHistory = z.infer<typeof ExecutionHistorySchema>;
+
+// ============================================================================
+// User Story Schema
+// ============================================================================
 
 /**
  * User story schema
@@ -22,6 +144,10 @@ export const UserStorySchema = z.object({
   phase: z.string().optional(), // Phase marker (e.g., "Setup", "Foundation", "Stories", "Polish")
   research: z.boolean().optional(), // Requires research phase before implementation
   skipped: z.boolean().optional(), // Whether the story was skipped by user command
+  // Routing metadata - populated during task planning phase (US-026)
+  routing: RoutingMetadataSchema.optional(),
+  // Execution history - populated after story execution (US-026)
+  execution: ExecutionHistorySchema.optional(),
 });
 
 export type UserStory = z.infer<typeof UserStorySchema>;
@@ -33,6 +159,16 @@ export const PRDSchema = z.object({
   project: z.string(),
   branchName: z.string(),
   description: z.string(),
+  routingPreference: z
+    .object({
+      type: z.enum(["auto", "harness"]).optional(),
+      mode: ModeSchema.optional(),
+      allowFree: z.boolean().optional(),
+      harness: HarnessNameSchema.optional(),
+      model: z.string().optional(),
+      raw: z.string().optional(),
+    })
+    .optional(),
   userStories: z.array(UserStorySchema),
 });