rafcode 2.5.1-0 → 3.0.0

package/src/core/runner-interface.ts

@@ -0,0 +1,14 @@
+import type { RunnerOptions, RunResult } from './runner-types.js';
+
+/**
+ * Provider-agnostic CLI runner interface.
+ * Both ClaudeRunner and CodexRunner implement this interface.
+ */
+export interface ICliRunner {
+  runInteractive(systemPrompt: string, userMessage: string, options?: RunnerOptions): Promise<number>;
+  runResume(options?: RunnerOptions): Promise<number>;
+  run(prompt: string, options?: RunnerOptions): Promise<RunResult>;
+  runVerbose(prompt: string, options?: RunnerOptions): Promise<RunResult>;
+  kill(): void;
+  isRunning(): boolean;
+}

package/src/core/runner-types.ts

@@ -0,0 +1,75 @@
+import type { UsageData, HarnessProvider } from '../types/config.js';
+
+/**
+ * Options for a single runner execution (run, runVerbose, runInteractive, etc.).
+ */
+export interface RunnerOptions {
+  /**
+   * Timeout in minutes for this single execution.
+   * Default: 60 minutes.
+   * Each call to run() or runVerbose() gets its own fresh timeout.
+   * Retries get a fresh timeout - elapsed time is NOT accumulated across attempts.
+   */
+  timeout?: number;
+  cwd?: string;
+  /**
+   * Skip permission prompts for file operations.
+   * Only used in interactive mode (runInteractive).
+   */
+  dangerouslySkipPermissions?: boolean;
+  /**
+   * Path to the outcome file. When provided, enables completion detection:
+   * - Monitors stdout for completion markers (<promise>COMPLETE/FAILED</promise>)
+   * - Polls the outcome file for completion markers
+   * When detected, starts a grace period before terminating the process,
+   * allowing time for git commit operations to complete.
+   */
+  outcomeFilePath?: string;
+  /**
+   * Commit verification context. When provided, the grace period will verify
+   * that the expected git commit has been made before terminating.
+   * Only applies when a COMPLETE marker is detected (not FAILED).
+   */
+  commitContext?: {
+    /** HEAD commit hash recorded before task execution began. */
+    preExecutionHead: string;
+    /** Expected commit message prefix (e.g., "RAF[005:01]"). */
+    expectedPrefix: string;
+    /** Path to the outcome file that should be committed. */
+    outcomeFilePath: string;
+  };
+  /**
+   * Dynamic verbose display callback. When provided, called for each stream event
+   * to determine whether to write display output to stdout. Overrides the static
+   * verbose parameter in _runStreamJson. Used by the runtime verbose toggle.
+   */
+  verboseCheck?: () => boolean;
+}
+
+/**
+ * Configuration for creating a runner instance.
+ */
+export interface RunnerConfig {
+  /**
+   * Model to use (e.g., opus, sonnet, haiku, gpt-5.4).
+   * Default: provider-specific default.
+   */
+  model?: string;
+  /**
+   * CLI provider to use.
+   * Default: 'claude'.
+   */
+  provider?: HarnessProvider;
+}
+
+/**
+ * Result of a non-interactive runner execution.
+ */
+export interface RunResult {
+  output: string;
+  exitCode: number;
+  timedOut: boolean;
+  contextOverflow: boolean;
+  /** Token usage data from the stream-json result event. */
+  usageData?: UsageData;
+}

package/src/core/shutdown-handler.ts

@@ -1,18 +1,25 @@
-import { ClaudeRunner } from './claude-runner.js';
+import type { ICliRunner } from './runner-interface.js';
 import { logger } from '../utils/logger.js';
 
 type CleanupCallback = () => void | Promise<void>;
 
 class ShutdownHandler {
-  private claudeRunner: ClaudeRunner | null = null;
+  private runner: ICliRunner | null = null;
   private cleanupCallbacks: CleanupCallback[] = [];
   private isShuttingDown = false;
 
   /**
-   * Register a Claude runner to be killed on shutdown.
+   * Register a CLI runner to be killed on shutdown.
    */
-  registerClaudeRunner(runner: ClaudeRunner): void {
-    this.claudeRunner = runner;
+  registerRunner(runner: ICliRunner): void {
+    this.runner = runner;
+  }
+
+  /**
+   * @deprecated Use registerRunner instead.
+   */
+  registerClaudeRunner(runner: ICliRunner): void {
+    this.registerRunner(runner);
   }
 
   /**
@@ -54,10 +61,10 @@ class ShutdownHandler {
     this.isShuttingDown = true;
     logger.info(`\nReceived ${signal}, shutting down gracefully...`);
 
-    // Kill Claude process if running
-    if (this.claudeRunner?.isRunning()) {
-      logger.debug('Killing Claude process...');
-      this.claudeRunner.kill();
+    // Kill runner process if running
+    if (this.runner?.isRunning()) {
+      logger.debug('Killing runner process...');
+      this.runner.kill();
     }
 
     // Run cleanup callbacks
@@ -85,7 +92,7 @@ class ShutdownHandler {
    * Clear registrations (useful for testing).
    */
   clear(): void {
-    this.claudeRunner = null;
+    this.runner = null;
     this.cleanupCallbacks = [];
   }
 }

package/src/core/state-derivation.ts

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { getPlansDir, getOutcomesDir, getInputPath, decodeBase26, TASK_ID_PATTERN } from '../utils/paths.js';
+import { getPlansDir, getOutcomesDir, getInputPath, TASK_ID_PATTERN } from '../utils/paths.js';
 import { parsePlanFrontmatter, type PlanFrontmatter } from '../utils/frontmatter.js';
 
 export type DerivedTaskStatus = 'pending' | 'completed' | 'failed' | 'blocked';
@@ -44,7 +44,7 @@ export interface DerivedStats {
 
 /**
  * Discover all projects in the RAF directory.
- * Projects are directories matching the pattern XXXXXX-project-name (6-char base26 prefix).
+ * Projects are directories matching the pattern N-project-name (numeric prefix).
  */
 export function discoverProjects(rafDir: string): DiscoveredProject[] {
   if (!fs.existsSync(rafDir)) {
@@ -56,16 +56,13 @@ export function discoverProjects(rafDir: string): DiscoveredProject[] {
 
   for (const entry of entries) {
     if (entry.isDirectory()) {
-      const match = entry.name.match(/^([a-z]{6})-(.+)$/i);
+      const match = entry.name.match(/^(\d+)-(.+)$/);
       if (match && match[1] && match[2]) {
-        const decoded = decodeBase26(match[1].toLowerCase());
-        if (decoded !== null) {
-          projects.push({
-            number: decoded,
-            name: match[2],
-            path: path.join(rafDir, entry.name),
-          });
-        }
+        projects.push({
+          number: parseInt(match[1], 10),
+          name: match[2],
+          path: path.join(rafDir, entry.name),
+        });
       }
     }
   }
@@ -89,7 +86,7 @@ export function parseDependencies(content: string): string[] {
     return [];
   }
 
-  // Parse comma-separated task IDs (2-char base36)
+  // Parse comma-separated numeric task IDs
   const taskIdRegex = new RegExp(`^${TASK_ID_PATTERN}$`);
   return dependenciesLine
     .split(',')
@@ -184,7 +181,7 @@ export function deriveProjectStatus(
 /**
  * Derive project state from the folder structure.
  * Scans plans/ for plan files and outcomes/ for outcome files.
- * Matches them by task ID (2-char base36 prefix for tasks) and determines status.
+ * Matches them by task ID (numeric prefix for tasks) and determines status.
  * Also parses dependencies and derives blocked status.
  */
 export function deriveProjectState(projectPath: string): DerivedProjectState {

package/src/core/worktree.ts

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { logger } from '../utils/logger.js';
-import { extractProjectNumber, extractProjectName, isBase26Prefix, decodeBase26 } from '../utils/paths.js';
+import { extractProjectNumber, extractProjectName, parseProjectPrefix } from '../utils/paths.js';
 
 export interface WorktreeCreateResult {
   success: boolean;
@@ -368,7 +368,7 @@ export interface WorktreeProjectResolution {
  * Resolve a project identifier against worktree folder names.
  * Uses the same matching strategy as `resolveProjectIdentifierWithDetails`:
  * 1. Full folder name match (exact, case-insensitive)
- * 2. Base26 prefix match (6-char ID)
+ * 2. Numeric prefix match (e.g., "3" matches "3-auth-system")
  * 3. Project name match (the portion after the prefix)
  *
  * @param repoBasename - The basename of the current git repo
@@ -394,20 +394,18 @@ export function resolveWorktreeProjectByIdentifier(
     }
   }
 
-  // 2. Base26 prefix match
-  if (isBase26Prefix(identifier)) {
-    const targetNumber = decodeBase26(identifier);
-    if (targetNumber !== null) {
-      for (const dir of wtProjectDirs) {
-        const prefix = extractProjectNumber(dir);
-        if (prefix) {
-          const dirNumber = decodeBase26(prefix);
-          if (dirNumber === targetNumber) {
-            return {
-              folder: dir,
-              worktreeRoot: computeWorktreePath(repoBasename, dir),
-            };
-          }
+  // 2. Numeric prefix match
+  const targetNumber = parseProjectPrefix(identifier);
+  if (targetNumber !== null) {
+    for (const dir of wtProjectDirs) {
+      const prefix = extractProjectNumber(dir);
+      if (prefix) {
+        const dirNumber = parseProjectPrefix(prefix);
+        if (dirNumber === targetNumber) {
+          return {
+            folder: dir,
+            worktreeRoot: computeWorktreePath(repoBasename, dir),
+          };
         }
       }
     }

package/src/index.ts

@@ -11,7 +11,7 @@ const program = new Command();
 
 program
   .name('raf')
-  .description('RAF - Automated Task Planning & Execution with Claude Code')
+  .description('RAF - Automated Task Planning & Execution')
   .version(getVersion());
 
 program.addCommand(createPlanCommand());

package/src/parsers/codex-stream-renderer.ts

@@ -0,0 +1,108 @@
+/**
+ * Renders JSONL events from Codex CLI into human-readable verbose output.
+ *
+ * Codex CLI (`codex exec --json`) emits one JSON object per line with event types:
+ * - AgentMessage: Text content from the agent
+ * - CommandExecution: Shell command execution (command + exit code)
+ * - FileChange: File modification (path + change kind)
+ * - McpToolCall: MCP tool invocation
+ * - TodoList: Task tracking (skipped)
+ */
+
+import type { RenderResult } from './stream-renderer.js';
+
+export interface CodexEvent {
+  type: string;
+  /** AgentMessage fields */
+  content?: string;
+  /** CommandExecution fields */
+  command?: string;
+  exit_code?: number;
+  /** FileChange fields */
+  file_path?: string;
+  change_kind?: string;
+  /** McpToolCall fields */
+  tool_name?: string;
+  server_name?: string;
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.substring(0, maxLen - 3) + '...';
+}
+
+/**
+ * Parse and render a single JSONL line from Codex CLI output.
+ * Returns the same RenderResult interface as Claude's stream renderer.
+ */
+export function renderCodexStreamEvent(line: string): RenderResult {
+  if (!line.trim()) {
+    return { display: '', textContent: '' };
+  }
+
+  let event: CodexEvent;
+  try {
+    event = JSON.parse(line) as CodexEvent;
+  } catch {
+    // Not valid JSON - pass through raw
+    return { display: line + '\n', textContent: line };
+  }
+
+  switch (event.type) {
+    case 'AgentMessage':
+      return renderAgentMessage(event);
+
+    case 'CommandExecution':
+      return renderCommandExecution(event);
+
+    case 'FileChange':
+      return renderFileChange(event);
+
+    case 'McpToolCall':
+      return renderMcpToolCall(event);
+
+    case 'TodoList':
+      // Skip todo list events - minimal noise
+      return { display: '', textContent: '' };
+
+    default:
+      // Skip unknown event types gracefully
+      return { display: '', textContent: '' };
+  }
+}
+
+function renderAgentMessage(event: CodexEvent): RenderResult {
+  const text = event.content ?? '';
+  return {
+    display: text ? text + '\n' : '',
+    textContent: text,
+  };
+}
+
+function renderCommandExecution(event: CodexEvent): RenderResult {
+  const cmd = event.command ?? '';
+  const exitCode = event.exit_code ?? 0;
+  const status = exitCode === 0 ? '✓' : `✗ exit ${exitCode}`;
+  return {
+    display: `  → Running: ${truncate(cmd, 120)} [${status}]\n`,
+    textContent: '',
+  };
+}
+
+function renderFileChange(event: CodexEvent): RenderResult {
+  const filePath = event.file_path ?? 'unknown';
+  const kind = event.change_kind ?? 'modified';
+  return {
+    display: `  → File ${kind}: ${filePath}\n`,
+    textContent: '',
+  };
+}
+
+function renderMcpToolCall(event: CodexEvent): RenderResult {
+  const tool = event.tool_name ?? 'unknown';
+  const server = event.server_name ? ` (${event.server_name})` : '';
+  return {
+    display: `  → MCP tool: ${tool}${server}\n`,
+    textContent: '',
+  };
+}

package/src/parsers/output-parser.ts

@@ -19,7 +19,7 @@ const CONTEXT_OVERFLOW_PATTERNS = [
 ];
 
 /**
- * Parse Claude's output to determine task result.
+ * Parse the LLM's output to determine task result.
  */
 export function parseOutput(output: string): ParsedOutput {
   const result: ParsedOutput = {
@@ -120,7 +120,7 @@ export function isRetryableFailure(parsed: ParsedOutput): boolean {
 }
 
 /**
- * Extract a summary from Claude's output for the outcome file.
+ * Extract a summary from the LLM's output for the outcome file.
  */
 export function extractSummary(output: string): string {
   // Remove ANSI codes

package/src/parsers/stream-renderer.ts

@@ -3,7 +3,7 @@
  *
  * Event types from `claude -p --output-format stream-json --verbose`:
  * - system (init): Session initialization info
- * - assistant: Claude's response with text or tool_use content blocks
+ * - assistant: LLM response with text or tool_use content blocks
  * - user: Tool results (tool_result content blocks)
  * - result: Final result with success/failure status and token usage
  */

package/src/prompts/amend.ts

@@ -17,7 +17,7 @@ export interface AmendPromptResult {
 /**
  * Generate a prompt for amending an existing project with new tasks.
  * - systemPrompt: Amendment mode conventions, existing tasks context (via --append-system-prompt)
- * - userMessage: Reference to input.md and new task description (via positional argument, triggers Claude to start)
+ * - userMessage: Reference to input.md and new task description (via positional argument, triggers the LLM to start)
  */
 export function getAmendPrompt(params: AmendPromptParams): AmendPromptResult {
   const {
@@ -153,7 +153,7 @@ effort: medium
 
 ## Dependencies
 [Optional section - omit if task has no dependencies]
-[Comma-separated list of task IDs this task depends on, e.g., "01, 02"]
+[Comma-separated list of task IDs this task depends on, e.g., "1, 2"]
 [If a dependency fails, this task will be automatically blocked]
 
 ## Requirements
@@ -180,7 +180,7 @@ effort: medium
 
 ### Frontmatter Requirements
 
-The \`effort\` field is REQUIRED in every plan file. It indicates task complexity and determines which Claude model will execute the task:
+The \`effort\` field is REQUIRED in every plan file. It indicates task complexity and determines which model will execute the task:
 - \`effort: low\` — Trivial/mechanical changes, simple one-file edits, config changes
 - \`effort: medium\` — Well-scoped feature work, bug fixes with clear plans, multi-file changes following existing patterns
 - \`effort: high\` — Architectural changes, complex logic, tasks requiring deep codebase understanding
@@ -201,8 +201,8 @@ This is rarely needed — prefer using the \`effort\` label so the user's config
 After creating all new plan files:
 1. Provide a summary of:
    - The new tasks you've created, including the effort level for each task. Example format:
-     - Task 02: add-caching (effort: medium)
-     - Task 03: update-docs (effort: low)
+     - Task 2: add-caching (effort: medium)
+     - Task 3: update-docs (effort: low)
    - How they relate to existing tasks
    - Total task count in the project
 2. Display this exit message to the user:
@@ -221,7 +221,7 @@ Planning complete! To exit this session and run your tasks:
 4. New tasks start from number ${encodeTaskId(nextTaskNumber)}
 5. Use descriptive, kebab-case names for plan files
 6. Each plan should be self-contained with all context needed
-7. Specify task dependencies using the ## Dependencies section with task IDs only (e.g., "01, 02")
+7. Specify task dependencies using the ## Dependencies section with task IDs only (e.g., "1, 2")
 8. Tasks without dependencies should omit the Dependencies section entirely
 9. Be specific - vague plans lead to poor execution
 10. ALWAYS include the \`effort\` frontmatter field in every plan file — assess each task's complexity

package/src/prompts/config-docs.md

@@ -22,9 +22,9 @@ The above only changes `models.plan` — all other model settings keep their def
 
 ## Config Reference
 
-### `models` — Claude Model Selection
+### `models` — Model Selection
 
-Controls which Claude model is used for each scenario. Values can be a short alias (`"sonnet"`, `"haiku"`, `"opus"`) or a full model ID.
+Controls which model is used for each scenario. Values can be a short alias (`"sonnet"`, `"haiku"`, `"opus"`) or a full model ID.
 
 **Model ID format**: Full model IDs follow the pattern `claude-{family}-{version}`, for example:
 - `"claude-opus-4-5-20251101"` — Opus 4.5 from November 2025
@@ -45,7 +45,7 @@ Controls which Claude model is used for each scenario. Values can be a short ali
 
 ### `effortMapping` — Task Effort to Model Mapping
 
-Maps task complexity labels (in plan frontmatter) to Claude models. When a plan file has `effort: medium`, RAF resolves the execution model using this mapping.
+Maps task complexity labels (in plan frontmatter) to models. When a plan file has `effort: medium`, RAF resolves the execution model using this mapping.
 
 | Key | Default | Description |
 |-----|---------|-------------|
@@ -84,7 +84,7 @@ Example:
 
 - **Type**: boolean
 - **Default**: `true`
-- **Description**: When `true`, Claude automatically commits changes after completing each task. When `false`, changes are left uncommitted.
+- **Description**: When `true`, RAF automatically commits changes after completing each task. When `false`, changes are left uncommitted.
 
 ### `worktree` — Default Worktree Mode
 
@@ -158,7 +158,7 @@ Example:
 The config is validated when loaded. Invalid configs cause an error with a descriptive message. The following rules are enforced:
 
 - **Unknown keys are rejected** at every nesting level. Typos like `"model"` instead of `"models"` will be caught.
-- **Model values** (`models.*`, `effortMapping.*`) must be a short alias (`"sonnet"`, `"haiku"`, `"opus"`) or a full model ID matching the pattern `claude-{family}-{version}` (e.g., `"claude-sonnet-4-5-20250929"`).
+- **Model values** (`models.*`, `effortMapping.*`) must be a short alias (`"sonnet"`, `"haiku"`, `"opus"`) or a full model ID (e.g., `"claude-sonnet-4-5-20250929"`, `"o3"`).
 - **`effortMapping` keys** must be `"low"`, `"medium"`, or `"high"`.
 - **`timeout`** must be a positive finite number.
 - **`maxRetries`** must be a non-negative integer.
@@ -277,9 +277,9 @@ To reset a single setting, remove its key from the config file. Any key not pres
 
 ---
 
-## For Claude — Config Editing Session Instructions
+## Config Editing Session Instructions
 
-This section contains instructions for Claude when operating as the interactive config editor during `raf config` sessions.
+This section contains instructions for the LLM when operating as the interactive config editor during `raf config` sessions.
 
 ### Your Role
 

package/src/prompts/execution.ts

@@ -85,8 +85,8 @@ ${previousOutcomes.map((o) => `### Task ${o.taskId}\n${o.content}`).join('\n\n')
 `;
   }
 
-  // Encode task number to 2-char base36
-  const paddedTaskNumber = taskNumber.toString(36).padStart(2, '0');
+  // Encode task number to plain numeric string
+  const paddedTaskNumber = taskNumber.toString();
 
   // Build example commit message from config template
   const commitTemplate = getCommitFormat('task');

package/src/prompts/planning.ts

@@ -12,7 +12,7 @@ export interface PlanningPromptResult {
 /**
  * Generate the planning prompt with system instructions and user message separated.
  * - systemPrompt: RAF planning conventions, file structure, interview process (via --append-system-prompt)
- * - userMessage: Reference to input.md file (via positional argument, triggers Claude to start)
+ * - userMessage: Reference to input.md file (via positional argument, triggers the LLM to start)
  */
 export function getPlanningPrompt(params: PlanningPromptParams): PlanningPromptResult {
   const { projectPath, worktreeMode } = params;
@@ -37,7 +37,7 @@ Project folder: ${projectPath}
 Based on the project description, identify distinct tasks. Each task should:
 - Be independently completable
 - Have a clear outcome
-- Take roughly 10-30 minutes of work for Claude
+- Take roughly 10-30 minutes of work
 
 **CRITICAL: Order tasks by logical execution order.** Lower-numbered tasks should be completed before higher-numbered ones. Consider:
 - Setup/foundation tasks come first (e.g., defining schemas, creating interfaces)
@@ -76,8 +76,8 @@ This file serves as documentation of design choices made during planning. Append
 ### Step 3: Create Plan Files
 
 After interviewing the user about all tasks, create plan files in the plans folder:
-- ${projectPath}/plans/01-task-name.md
-- ${projectPath}/plans/02-task-name.md
+- ${projectPath}/plans/1-task-name.md
+- ${projectPath}/plans/2-task-name.md
 - etc.
 
 Each plan file MUST have Obsidian-style frontmatter at the top, before the \`# Task:\` heading. The frontmatter uses standard YAML format with opening and closing \`---\` delimiters:
@@ -96,7 +96,7 @@ effort: medium
 
 ## Dependencies
 [Optional section - omit if task has no dependencies]
-[Comma-separated list of task IDs this task depends on, e.g., "01, 02"]
+[Comma-separated list of task IDs this task depends on, e.g., "1, 2"]
 [If a dependency fails, this task will be automatically blocked]
 
 ## Requirements
@@ -122,7 +122,7 @@ effort: medium
 
 ### Frontmatter Requirements
 
-The \`effort\` field is REQUIRED in every plan file. It indicates task complexity and determines which Claude model will execute the task:
+The \`effort\` field is REQUIRED in every plan file. It indicates task complexity and determines which model will execute the task:
 - \`effort: low\` — Trivial/mechanical changes, simple one-file edits, config changes
 - \`effort: medium\` — Well-scoped feature work, bug fixes with clear plans, multi-file changes following existing patterns
 - \`effort: high\` — Architectural changes, complex logic, tasks requiring deep codebase understanding
@@ -151,12 +151,12 @@ For each task, analyze which other tasks must complete successfully before it ca
 **Dependency format examples:**
 \`\`\`markdown
 ## Dependencies
-01
+1
 \`\`\`
 or for multiple dependencies:
 \`\`\`markdown
 ## Dependencies
-01, 02
+1, 2
 \`\`\`
 
 **Rules for dependencies:**
@@ -169,9 +169,9 @@ or for multiple dependencies:
 
 After creating all plan files:
 1. Provide a summary of the tasks you've created, including the effort level for each task. Example:
-   - Task 01: setup-database (effort: low)
-   - Task 02: implement-auth (effort: medium)
-   - Task 03: refactor-api (effort: high)
+   - Task 1: setup-database (effort: low)
+   - Task 2: implement-auth (effort: medium)
+   - Task 3: refactor-api (effort: high)
 2. Display this exit message to the user:
 
 \`\`\`
@@ -183,7 +183,7 @@ Planning complete! To exit this session and run your tasks:
 ## Important Rules
 
 1. ALWAYS interview the user before creating plans
-2. Create plans in numbered order (01, 02, 03, etc.) reflecting logical execution order
+2. Create plans in numbered order (1, 2, 3, etc.) reflecting logical execution order
 3. Use descriptive, kebab-case names for plan files
 4. Each plan should be self-contained with all context needed
 5. Infer dependencies automatically - analyze task relationships, don't ask the user about dependencies