rafcode 2.5.1-0 → 3.0.0

package/RAF/38-dual-wielder/outcomes/1-config-schema-provider-types.md

@@ -0,0 +1,47 @@
+# Task 1: Config Schema & Provider Types
+
+## Summary
+Extended the config system to support multiple CLI providers (claude, codex) with harness-prefixed model names and provider-specific model mappings.
+
+## Changes Made
+
+### `src/types/config.ts`
+- Added `HarnessProvider` type (`'claude' | 'codex'`)
+- Added `CodexModelAlias` type (`'spark' | 'codex' | 'gpt54'`)
+- Added `ModelAlias` and `ModelName` types (provider-agnostic unions)
+- Added `provider: HarnessProvider` to `RafConfig` with default `'claude'`
+- Added `codexModels` and `codexEffortMapping` config sections parallel to Claude ones
+- Added `VALID_CODEX_MODEL_ALIASES` and `VALID_HARNESS_PROVIDERS` constants
+- Added `provider?: HarnessProvider` to `PlanCommandOptions` and `DoCommandOptions`
+- Kept backward-compatible `ClaudeModelAlias` and `ClaudeModelName` types
+
+### `src/utils/config.ts`
+- Added `CODEX_MODEL_ID_PATTERN` for Codex model validation
+- Updated `isValidModelName()` to accept Claude aliases, Codex aliases, raw Codex IDs, and harness-prefixed format (`claude/opus`, `codex/gpt-5.4`)
+- Added `parseModelSpec()` function to parse harness-prefixed model specs
+- Updated `getModel()` and `resolveEffortToModel()` to accept optional provider parameter
+- Added Codex model tier ordering (`CODEX_MODEL_TIER_ORDER`)
+- Updated `getModelTier()`, `getModelShortName()`, `resolveFullModelId()` for Codex models
+- Updated `MODEL_ALIAS_TO_FULL_ID` with Codex alias mappings
+- Updated `VALID_TOP_LEVEL_KEYS`, `validateConfig()`, `deepMerge()`, `resolveConfig()` for new fields
+
+### `src/utils/validation.ts`
+- Updated `validateModelName()` to delegate to `isValidModelName()` (DRY)
+- Updated error message in `resolveModelOption()` to mention harness-prefixed format
+
+### `src/commands/plan.ts` and `src/commands/do.ts`
+- Added `--provider` / `-p` CLI flag to both commands
+
+## Acceptance Criteria
+- [x] `provider` field exists in config with `'claude'` default
+- [x] Harness-prefixed model names parse correctly (e.g., `codex/gpt-5.4`)
+- [x] Unprefixed aliases still work and default to claude
+- [x] Codex model defaults are defined
+- [x] Config validation accepts new fields and rejects invalid ones
+- [x] `--provider` flag available on `raf plan` and `raf do`
+- [x] TypeScript compiles without errors
+
+## Notes
+- One pre-existing test failure in `name-generator.test.ts` (hardcoded `haiku` expectation vs config default `sonnet` for `nameGeneration`) — not related to this task.
+
+<promise>COMPLETE</promise>

package/RAF/38-dual-wielder/outcomes/2-abstract-cli-runner.md

@@ -0,0 +1,33 @@
+# Task 2: Abstract CLI Runner Interface
+
+## Summary
+Extracted a provider-agnostic runner interface from `ClaudeRunner`, separating CLI-specific logic from shared orchestration concerns. Both Claude and future Codex runners can now be used interchangeably through the `ICliRunner` interface and `createRunner()` factory.
+
+## Changes Made
+
+### New Files
+- **`src/core/runner-types.ts`**: Shared types — `RunnerOptions` (renamed from `ClaudeRunnerOptions`), `RunnerConfig` (renamed from `ClaudeRunnerConfig`), `RunResult`
+- **`src/core/runner-interface.ts`**: `ICliRunner` interface with `run()`, `runVerbose()`, `runInteractive()`, `runResume()`, `kill()`, `isRunning()`
+- **`src/core/completion-detector.ts`**: Extracted `createCompletionDetector()`, `verifyCommit()`, `CompletionDetector` interface, and timing constants from `claude-runner.ts`
+- **`src/core/runner-factory.ts`**: `createRunner(config)` factory function and `getProviderBinaryName()` utility; Codex throws "not yet implemented"
+
+### Modified Files
+- **`src/core/claude-runner.ts`**: `ClaudeRunner` now implements `ICliRunner`; imports shared types from `runner-types.ts` and completion detection from `completion-detector.ts`; backward-compatible re-exports for `ClaudeRunnerOptions`, `ClaudeRunnerConfig`, `RunResult`, `CommitContext`, `CompletionDetector`, and timing constants
+- **`src/core/shutdown-handler.ts`**: Changed from `ClaudeRunner` type to `ICliRunner`; added `registerRunner()` method with `registerClaudeRunner()` as deprecated alias
+- **`src/commands/do.ts`**: Uses `createRunner()` instead of `new ClaudeRunner()`
+- **`src/commands/plan.ts`**: Uses `createRunner()` instead of `new ClaudeRunner()`
+- **`src/commands/config.ts`**: Uses `createRunner()` instead of `new ClaudeRunner()`
+
+## Acceptance Criteria
+- [x] `ICliRunner` interface is defined and `ClaudeRunner` implements it
+- [x] `createRunner()` factory works for claude provider
+- [x] `do.ts` and `plan.ts` use the factory instead of direct `ClaudeRunner` construction
+- [x] Completion detection is extracted and shared
+- [x] All existing functionality works identically (no behavior changes)
+- [x] TypeScript compiles without errors
+
+## Notes
+- Backward-compatible re-exports in `claude-runner.ts` ensure existing tests continue to work without modification.
+- The pre-existing `name-generator.test.ts` failure (hardcoded `haiku` expectation) remains — unrelated to this task.
+
+<promise>COMPLETE</promise>

package/RAF/38-dual-wielder/outcomes/3-implement-codex-runner.md

@@ -0,0 +1,38 @@
+# Task 3: Implement Codex Runner
+
+## Summary
+Implemented `CodexRunner` class that wraps the Codex CLI binary, providing the same `ICliRunner` interface as `ClaudeRunner`. Includes a dedicated JSONL stream renderer for Codex event types and factory integration.
+
+## Changes Made
+
+### New Files
+- **`src/parsers/codex-stream-renderer.ts`**: Parses Codex JSONL events (`AgentMessage`, `CommandExecution`, `FileChange`, `McpToolCall`, `TodoList`) into `RenderResult` format shared with Claude's renderer. Unknown event types are skipped gracefully.
+- **`src/core/codex-runner.ts`**: `CodexRunner` implementing `ICliRunner` with:
+  - `runInteractive()`: Spawns `codex -m <model> <combined_prompt>` via PTY with stdin/stdout passthrough
+  - `run()` / `runVerbose()`: Spawns `codex exec --full-auto --json --ephemeral -m <model> <prompt>` and parses JSONL output
+  - `runResume()`: Throws error (not supported by Codex CLI)
+  - `kill()` / `isRunning()`: Same graceful shutdown pattern as ClaudeRunner
+  - System prompt prepended to user message as `[System Instructions]...[User Request]...` format
+  - Shared completion detector for outcome file monitoring
+  - Context overflow detection
+  - Usage data gracefully omitted (Codex doesn't provide it in the same format)
+
+### Modified Files
+- **`src/core/runner-factory.ts`**: Imports `CodexRunner` and returns `new CodexRunner(config)` for `provider: 'codex'` (replaces the "not yet implemented" error)
+
+## Acceptance Criteria
+- [x] `CodexRunner` implements `ICliRunner` fully
+- [x] `codex exec` spawns correctly with proper flags (`--full-auto --json --ephemeral -m`)
+- [x] System prompt is prepended to user message correctly
+- [x] JSONL events are parsed and displayed properly in verbose mode
+- [x] Interactive mode works via PTY
+- [x] Timeout and completion detection work
+- [x] `createRunner({ provider: 'codex' })` returns a working CodexRunner
+- [x] TypeScript compiles without errors
+
+## Notes
+- Codex usage data is omitted (returns `undefined`) since Codex doesn't provide token usage in the same format as Claude's stream-json.
+- The `--ephemeral` flag is used in non-interactive mode to avoid session persistence pollution.
+- The pre-existing `name-generator.test.ts` failure remains — unrelated to this task.
+
+<promise>COMPLETE</promise>

package/RAF/38-dual-wielder/outcomes/4-update-prompts-llm-agnostic.md

@@ -0,0 +1,50 @@
+# Task 4: Update Prompts to be LLM-Agnostic
+
+## Summary
+Removed Claude-specific language from all user-facing prompt templates, log messages, CLI descriptions, error messages, and doc comments so they work with any LLM provider.
+
+## Changes Made
+
+### Prompt Files
+- **`src/prompts/planning.ts`**: Removed "for Claude" from task sizing guidance, changed "Claude model" to "model", updated doc comment
+- **`src/prompts/amend.ts`**: Same changes as planning.ts — removed "Claude model" references, updated doc comment
+- **`src/prompts/execution.ts`**: Already generic, no changes needed
+- **`src/prompts/config-docs.md`**: Updated "Claude Model Selection" → "Model Selection", "Claude models" → "models", "Claude automatically commits" → "RAF automatically commits", "For Claude — Config Editing" → "Config Editing Session Instructions"
+
+### Core Files
+- **`src/core/claude-runner.ts`**: Made all log messages generic ("Starting interactive session", "Session timed out", "Process exited", "Process stderr"), updated all doc comments
+- **`src/core/pull-request.ts`**: Updated error messages ("CLI not found", "Process exited with code", "LLM returned empty output"), updated doc comments
+- **`src/core/failure-analyzer.ts`**: Updated user-facing failure analysis text ("The API returned", "The LLM is stuck", "context grew too large for the LLM"), updated doc comments
+- **`src/core/runner-interface.ts`**: No changes needed (already mentions both runners by class name)
+
+### Command Files
+- **`src/index.ts`**: `'RAF - Automated Task Planning & Execution with Claude Code'` → `'RAF - Automated Task Planning & Execution'`
+- **`src/commands/plan.ts`**: Updated description, option help text (`'Model to use'`, `'Skip permission prompts'`), log messages (`'Starting planning session...'`, `'The planner will interview you'`)
+- **`src/commands/do.ts`**: Updated option help text (`'Show full LLM output'`, `'Model to use'`), updated comments
+- **`src/commands/config.ts`**: Updated description (`'View and edit RAF configuration interactively'`), log messages, doc comments
+
+### Parser & Utility Files
+- **`src/parsers/stream-renderer.ts`**: Updated doc comment ("LLM response" instead of "Claude's response")
+- **`src/parsers/output-parser.ts`**: Updated doc comments
+- **`src/utils/name-generator.ts`**: Updated all doc comments and debug log messages
+- **`src/utils/validation.ts`**: Updated error message for missing CLI
+- **`src/utils/token-tracker.ts`**: Updated comments ("CLI-provided" instead of "Claude-provided")
+
+## What Was NOT Changed (By Design)
+- Internal variable/type names (`ClaudeRunner`, `claudeRunner`, `ClaudeModelAlias`, `callClaudeForPrBody`, etc.) — these are internal implementation details
+- Literal `'claude'` as a provider value — it's a valid provider name
+- Claude model ID strings/patterns (`claude-opus-4-6`) — these are actual model identifiers
+- File names (`claude-runner.ts`) — internal implementation files for the Claude provider
+- Backward-compatible re-exports
+
+## Acceptance Criteria
+- [x] No user-facing prompt text mentions "Claude" specifically
+- [x] Log messages are provider-generic or include provider name dynamically
+- [x] CLI description is LLM-agnostic
+- [x] All prompts still function correctly (no broken templates)
+- [x] TypeScript compiles without errors
+
+## Notes
+- The pre-existing `name-generator.test.ts` failure (hardcoded `haiku` expectation vs config default `sonnet`) remains — unrelated to this task.
+
+<promise>COMPLETE</promise>

package/RAF/38-dual-wielder/outcomes/5-update-readme-docs.md

@@ -0,0 +1,33 @@
+# Task 5: Update README and Documentation
+
+## Summary
+Updated README.md to reflect dual-provider support for Claude Code CLI and OpenAI Codex CLI.
+
+## Changes Made
+
+### `README.md`
+- Updated title: "RAF - Automated Task Planning & Execution with Claude Code" → "RAF - Automated Task Planning & Execution"
+- Updated description to mention both Claude Code CLI and OpenAI Codex CLI
+- Updated Requirements section to list both providers
+- Updated Features list to add "Multi-Provider" bullet
+- Updated generic language ("the model needs" instead of "Claude needs")
+- Updated Quick Start comment from "Claude will interview you" to be generic
+- Added `"provider": "claude"` to the config example
+- Added **Provider Configuration** section with:
+  - `--provider codex` CLI usage examples
+  - Model spec format (plain aliases and `<provider>/<alias>` prefix)
+  - Codex-specific config example (`codexModels`, `codexEffortMapping`)
+  - Codex limitations (`--resume` not supported, system prompt prepend behavior)
+- Updated Command Reference tables for `raf plan` and `raf do`:
+  - Added `-p, --provider <name>` row
+  - Added `-m, --model <name>` row to `raf plan`
+  - Updated model description to show harness-prefixed examples
+- Updated the dangerous-mode note to be provider-generic
+
+## Acceptance Criteria
+- [x] README reflects multi-provider support
+- [x] New config fields are documented (`provider`, `codexModels`, `codexEffortMapping`)
+- [x] `--provider` flag is documented for `raf do` and `raf plan`
+- [x] Existing documentation is updated (not just appended)
+
+<promise>COMPLETE</promise>

package/RAF/38-dual-wielder/outcomes/6-do-unified-project-scanning.md

@@ -0,0 +1,25 @@
+# Task 6: Unified Project Scanning in `raf do` Worktree Mode
+
+## Summary
+Made `raf do --worktree` show both worktree and main-repo pending projects in the interactive picker, instead of only worktree projects.
+
+## Changes Made
+
+### `src/commands/do.ts`
+- Rewrote `discoverAndPickWorktreeProject()` to use `getPendingWorktreeProjects()` and `getPendingProjects()` from `project-picker.ts` instead of reimplementing scanning logic
+- Added main-repo pending projects to the picker (no threshold filter on main-repo projects)
+- Threshold filter still applies to worktree projects only
+- Deduplication: worktree versions take precedence over main-repo versions (same logic as `pickPendingProject()`)
+- Uses `formatProjectChoice()` for consistent display with `[worktree]` suffix on worktree projects
+- Changed return type to `{ worktreeRoot?: string; projectFolder: string }` — when a main-repo project is selected, `worktreeRoot` is undefined and the downstream worktree creation flow kicks in as normal
+- Removed unused `parseProjectPrefix` import
+- Added `formatProjectChoice` to static imports
+
+## Acceptance Criteria
+- [x] `raf do --worktree` shows pending projects from both worktree and main repo
+- [x] Duplicate projects are deduped with worktree version taking precedence
+- [x] Selecting a main-repo project in worktree mode correctly creates/uses a worktree (worktreeRoot is undefined, falls through to existing worktree creation logic)
+- [x] Existing worktree-only scanning behavior is replaced by unified scanning
+- [x] No regressions in standard (non-worktree) mode — that code path is untouched
+
+<promise>COMPLETE</promise>

package/RAF/38-dual-wielder/outcomes/7-fix-plan-amend-automode.md

@@ -0,0 +1,28 @@
+# Task 7: Fix Plan Amend Prompt and Add Numeric ID Resolution
+
+## Summary
+Removed the `!autoMode` gate from the existing-project detection check in `runPlanCommand()`, so `raf plan -y <name-or-id>` now correctly detects existing projects and prompts to amend instead of silently creating duplicates.
+
+## Changes Made
+
+### `src/commands/plan.ts`
+- Removed `!autoMode` from the condition on line 121: `if (projectName && !autoMode)` → `if (projectName)`
+- The existing project detection now runs regardless of `-y` flag
+- The interactive prompt (`select()`) intentionally breaks out of auto mode for this safety check
+- Numeric ID resolution was already supported by both `resolveProjectIdentifierWithDetails()` and `resolveWorktreeProjectByIdentifier()` — no additional changes needed
+
+## Acceptance Criteria
+- [x] `raf plan -y <existing-project-name>` detects the existing project and prompts to amend
+- [x] `raf plan -y <numeric-id>` (e.g., `raf plan -y 38`) detects the existing project and prompts to amend
+- [x] `raf plan --amend <numeric-id>` resolves the project correctly and enters amend mode
+- [x] `raf plan --amend <project-name>` continues to work as before
+- [x] Resolution checks both main-repo and worktree projects in all cases
+- [x] If user selects "amend", the amend flow runs correctly
+- [x] If user selects "create new", a new project is created as before
+- [x] Non-auto-mode behavior is unchanged
+
+## Notes
+- The fix was a one-line change — the resolution utilities already supported numeric IDs; only the auto-mode guard was preventing the check from running.
+- The `select()` prompt intentionally breaks auto mode for this safety check, as silently duplicating a project is almost always a mistake.
+
+<promise>COMPLETE</promise>

package/RAF/38-dual-wielder/plans/1-config-schema-provider-types.md

@@ -0,0 +1,90 @@
+---
+effort: high
+---
+# Task: Config Schema & Provider Types
+
+## Objective
+Extend the config system to support multiple CLI providers (claude, codex) with harness-prefixed model names and provider-specific model mappings.
+
+## Context
+RAF currently hardcodes Claude as the only CLI provider. To support Codex CLI alongside Claude, we need to introduce a provider abstraction at the config/type level first. This is the foundation task — all other tasks depend on it.
+
+## Requirements
+- Add a `provider` field to `RafConfig` (default: `'claude'`)
+- Support harness-prefixed model format: `claude/opus`, `codex/gpt-5.4`, etc.
+- Unprefixed aliases (`opus`, `sonnet`, `haiku`) default to `claude/` prefix — existing configs keep working
+- Add Codex-specific model mappings and effort mappings
+- Add provider to CLI command options (`--provider` flag)
+- Config validation must accept both old (unprefixed) and new (prefixed) model formats
+
+## Implementation Steps
+
+1. **Update `src/types/config.ts`**:
+   - Add `HarnessProvider` type: `'claude' | 'codex'`
+   - Add `provider: HarnessProvider` to `RafConfig` with default `'claude'`
+   - Add `provider` to `DEFAULT_CONFIG`
+   - Rename `ClaudeModelAlias` to `ModelAlias` (keep backward-compat re-export)
+   - Rename `ClaudeModelName` to `ModelName` (keep backward-compat re-export)
+   - Add `CodexModelAlias` type for codex shorthand names (e.g., `'spark'`, `'codex'`, `'gpt54'`)
+   - Update `PlanCommandOptions` and `DoCommandOptions` to include `provider?: HarnessProvider`
+   - Add a `codexModels` config section parallel to `models`, with same scenario keys but codex model defaults
+   - Add a `codexEffortMapping` config section parallel to `effortMapping`
+
+2. **Add Codex model constants and defaults**:
+   - Default codex models config:
+     ```
+     codexModels: {
+       plan: 'gpt-5.3-codex',
+       execute: 'gpt-5.4',
+       nameGeneration: 'gpt-5.3-codex-spark',
+       failureAnalysis: 'gpt-5.3-codex-spark',
+       prGeneration: 'gpt-5.3-codex',
+       config: 'gpt-5.3-codex',
+     }
+     ```
+   - Default codex effort mapping:
+     ```
+     codexEffortMapping: {
+       low: 'gpt-5.3-codex-spark',
+       medium: 'gpt-5.3-codex',
+       high: 'gpt-5.4',
+     }
+     ```
+
+3. **Update `src/utils/config.ts`**:
+   - Update `isValidModelName()` to accept:
+     - Existing Claude aliases and full IDs (backward compat)
+     - Harness-prefixed format: `claude/<alias-or-full-id>` or `codex/<model-id>`
+     - Raw Codex model IDs (e.g., `gpt-5.4`, `gpt-5.3-codex-spark`)
+   - Update `resolveFullModelId()` to handle prefixed format — strip prefix and resolve
+   - Add `parseModelSpec(modelSpec: string): { provider: HarnessProvider; model: string }` that parses `codex/gpt-5.4` into parts
+   - Update `getModel()` to accept optional provider parameter and return from the right config section
+   - Update `resolveEffortToModel()` similarly
+   - Add Codex model tier ordering for ceiling comparison
+   - Update `getModelShortName()` to handle Codex models
+   - Update `MODEL_ALIAS_TO_FULL_ID` to include codex aliases if any
+   - Update `VALID_TOP_LEVEL_KEYS` set to include `'provider'`, `'codexModels'`, `'codexEffortMapping'`
+   - Update `validateConfig()` to validate the new fields
+   - Update `deepMerge()` to merge the new config sections
+
+4. **Update `src/index.ts`**:
+   - Add `--provider <provider>` option to `plan` and `do` commands
+   - Pass provider through to command handlers
+
+5. **Update `src/commands/do.ts`** and `src/commands/plan.ts`** (only the option plumbing):
+   - Accept `provider` from CLI options
+   - Thread it through to where model resolution happens
+
+## Acceptance Criteria
+- [ ] `provider` field exists in config with `'claude'` default
+- [ ] Harness-prefixed model names parse correctly (e.g., `codex/gpt-5.4`)
+- [ ] Unprefixed aliases still work and default to claude
+- [ ] Codex model defaults are defined
+- [ ] Config validation accepts new fields and rejects invalid ones
+- [ ] `--provider` flag available on `raf plan` and `raf do`
+- [ ] TypeScript compiles without errors
+
+## Notes
+- This task focuses on types, config, and validation only. The actual CLI runner abstraction is in the next task.
+- Keep backward-compat re-exports for renamed types so other modules don't need immediate changes.
+- The `codexModels` and `codexEffortMapping` config sections mirror the claude ones structurally, making the config symmetric.

package/RAF/38-dual-wielder/plans/2-abstract-cli-runner.md

@@ -0,0 +1,76 @@
+---
+effort: high
+---
+# Task: Abstract CLI Runner Interface
+
+## Objective
+Extract a provider-agnostic runner interface from `ClaudeRunner` so both Claude and Codex can be used interchangeably.
+
+## Context
+`ClaudeRunner` in `src/core/claude-runner.ts` currently contains both Claude-specific logic (CLI args, path discovery) and generic orchestration logic (timeout management, completion detection, PTY handling). We need to separate these concerns so Codex can plug in with its own CLI-specific logic while reusing the orchestration.
+
+## Dependencies
+1
+
+## Requirements
+- Create an abstract `CliRunner` interface/base class that both providers implement
+- The interface must support: `run()`, `runVerbose()`, `runInteractive()`, `runResume()`, `kill()`, `isRunning()`
+- Keep `RunResult` and `ClaudeRunnerOptions` as shared types (rename options to `RunnerOptions`)
+- Completion detection logic (grace period, commit verification) should remain shared
+- Create a factory function that returns the correct runner based on provider config
+- Existing code that uses `ClaudeRunner` should work with minimal changes (ideally just type changes)
+
+## Implementation Steps
+
+1. **Create `src/core/runner-types.ts`**:
+   - Move shared types here: `RunnerOptions` (renamed from `ClaudeRunnerOptions`), `RunnerConfig` (renamed from `ClaudeRunnerConfig`), `RunResult`
+   - Add `provider: HarnessProvider` to `RunnerConfig`
+   - Re-export from `claude-runner.ts` for backward compat
+
+2. **Create `src/core/runner-interface.ts`**:
+   - Define the `ICliRunner` interface:
+     ```typescript
+     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;
+     }
+     ```
+
+3. **Refactor `src/core/claude-runner.ts`**:
+   - `ClaudeRunner` implements `ICliRunner`
+   - Keep all existing Claude-specific logic (arg building, `which claude`, stream-json parsing)
+   - Import shared types from `runner-types.ts`
+   - The completion detection helpers (`createCompletionDetector`, `verifyCommit`, etc.) stay in this file or move to a shared utils file since Codex will need them too
+
+4. **Create `src/core/runner-factory.ts`**:
+   - Export `createRunner(config: RunnerConfig): ICliRunner`
+   - For `provider: 'claude'` → return `new ClaudeRunner(config)`
+   - For `provider: 'codex'` → throw for now with "Codex runner not yet implemented" (task 3 will implement it)
+   - Export `getProviderBinaryName(provider: HarnessProvider): string` utility
+
+5. **Extract completion detection to `src/core/completion-detector.ts`**:
+   - Move `createCompletionDetector`, `verifyCommit`, `CompletionDetector` interface, and related constants
+   - Both Claude and Codex runners will import from here
+
+6. **Update consumers**:
+   - `src/commands/do.ts`: Use `createRunner()` instead of `new ClaudeRunner()`; pass provider from options
+   - `src/commands/plan.ts`: Same
+   - `src/core/pull-request.ts`: Will need provider-aware runner creation (can stay claude-only for now with a TODO)
+   - Update imports as needed
+
+## Acceptance Criteria
+- [ ] `ICliRunner` interface is defined and `ClaudeRunner` implements it
+- [ ] `createRunner()` factory works for claude provider
+- [ ] `do.ts` and `plan.ts` use the factory instead of direct `ClaudeRunner` construction
+- [ ] Completion detection is extracted and shared
+- [ ] All existing functionality works identically (no behavior changes)
+- [ ] TypeScript compiles without errors
+
+## Notes
+- This is a refactoring task — no new features, just structural changes to enable task 3.
+- The `runResume()` method is Claude-specific (Codex may not support session resume). The Codex implementation can throw "not supported" for this method.
+- Keep the refactoring minimal — don't redesign the whole API, just extract the interface.

package/RAF/38-dual-wielder/plans/3-implement-codex-runner.md

@@ -0,0 +1,94 @@
+---
+effort: high
+---
+# Task: Implement Codex Runner
+
+## Objective
+Implement `CodexRunner` that wraps the Codex CLI (`codex` binary) with the same interface as `ClaudeRunner`.
+
+## Context
+With the runner interface extracted in task 2, we can now implement the Codex-specific runner. Codex CLI has different flags, output formats, and interaction patterns than Claude CLI. Key differences:
+- Non-interactive: `codex exec --full-auto --json` (vs Claude's `-p --output-format stream-json`)
+- Interactive: `codex` TUI via PTY (vs Claude's PTY)
+- No `--system-prompt` flag — system prompt must be prepended to user message
+- JSONL output with different event types (CommandExecution, FileChange, AgentMessage, etc.)
+- Model flag: `-m` (vs `--model`)
+- Permission bypass: `--full-auto` (vs `--dangerously-skip-permissions`)
+
+## Dependencies
+1, 2
+
+## Requirements
+- Implement `CodexRunner` class implementing `ICliRunner`
+- Handle system prompt by prepending it to the user message
+- Parse Codex JSONL events into the shared `RunResult` format
+- Support both interactive (PTY) and non-interactive (exec) modes
+- Discover `codex` binary via `which codex`
+- Build correct CLI arguments for Codex
+- Stream renderer for Codex JSONL events (separate from Claude's stream-renderer)
+
+## Implementation Steps
+
+1. **Create `src/parsers/codex-stream-renderer.ts`**:
+   - Parse Codex JSONL events (one JSON object per line)
+   - Map Codex event types to `RenderResult` (same interface as Claude's renderer):
+     - `AgentMessage` → text content + display
+     - `CommandExecution` → tool display (show command + exit code)
+     - `FileChange` → tool display (show file path + change kind)
+     - `McpToolCall` → tool display
+     - `TodoList` → skip or minimal display
+   - Extract any usage/cost data from Codex events if available
+   - Export `renderCodexStreamEvent(line: string): RenderResult`
+
+2. **Create `src/core/codex-runner.ts`**:
+   - Implement `ICliRunner` interface
+   - `getCodexPath()`: `execSync('which codex', ...)`
+   - Constructor takes `RunnerConfig` (model, provider)
+
+3. **Implement `runInteractive()`**:
+   - Spawn `codex` (no `exec` subcommand) via PTY
+   - Build args: `-m <model>`
+   - Combine system prompt and user message: `"[System Instructions]\n\n{systemPrompt}\n\n[User Request]\n\n{userMessage}"`
+   - Pass combined message as positional argument
+   - Handle PTY stdin/stdout passthrough (same pattern as ClaudeRunner)
+   - Handle cleanup on exit
+
+4. **Implement `run()` / `runVerbose()` (non-interactive execution)**:
+   - Spawn: `codex exec --full-auto --json -m <model> <combined_prompt>`
+   - Build the combined prompt (system + user prompt prepended)
+   - Parse JSONL stdout line by line using `renderCodexStreamEvent()`
+   - Accumulate text content for output
+   - Apply timeout logic (same pattern as ClaudeRunner)
+   - Use shared completion detector for outcome file monitoring
+   - Return `RunResult` with output, exitCode, timedOut, contextOverflow
+
+5. **Implement `runResume()`**:
+   - Throw `Error('Session resume is not supported by Codex CLI')`
+
+6. **Implement `kill()` and `isRunning()`**:
+   - Same pattern as ClaudeRunner (Ctrl+C via PTY write, SIGTERM fallback)
+
+7. **Update `src/core/runner-factory.ts`**:
+   - Import `CodexRunner`
+   - Return `new CodexRunner(config)` for `provider: 'codex'`
+
+8. **Handle Codex-specific edge cases**:
+   - Codex may not report token usage in the same way — handle missing usage data gracefully
+   - Codex `--json` output might include events we don't care about — filter/skip unknown types
+   - `--ephemeral` flag to avoid session persistence pollution
+
+## Acceptance Criteria
+- [ ] `CodexRunner` implements `ICliRunner` fully
+- [ ] `codex exec` spawns correctly with proper flags
+- [ ] System prompt is prepended to user message correctly
+- [ ] JSONL events are parsed and displayed properly in verbose mode
+- [ ] Interactive mode works via PTY
+- [ ] Timeout and completion detection work
+- [ ] `createRunner({ provider: 'codex' })` returns a working CodexRunner
+- [ ] TypeScript compiles without errors
+
+## Notes
+- Test by running `raf do <project> --provider codex` once integrated
+- Codex may not provide `total_cost_usd` in the same format — handle gracefully with zeros
+- The combined prompt approach (prepending system prompt) means Codex sees one large message. This is simpler but less structured than Claude's separate system prompt. It was chosen for simplicity per user decision.
+- Use `--ephemeral` flag in non-interactive mode to keep things clean

package/RAF/38-dual-wielder/plans/4-update-prompts-llm-agnostic.md

@@ -0,0 +1,70 @@
+---
+effort: medium
+---
+# Task: Update Prompts to be LLM-Agnostic
+
+## Objective
+Remove Claude-specific language from all prompt templates so they work with any LLM provider.
+
+## Context
+The prompts in `src/prompts/` contain Claude-specific references like "Claude Code", "Claude CLI", "Claude session", and "Claude model". These need to be made generic since the prompts will now be sent to either Claude or Codex.
+
+## Dependencies
+1
+
+## Requirements
+- Replace Claude-specific references in all prompt files with generic alternatives
+- Update the execution prompt, planning prompt, and amend prompt
+- Keep the prompts' functional content identical — only change naming/branding
+- Update any log messages that reference "Claude" in the runner and command files
+
+## Implementation Steps
+
+1. **Update `src/prompts/execution.ts`**:
+   - Replace "Claude" references in prompt text with generic terms
+   - `"You are executing a planned task for RAF"` — already generic, keep as-is
+   - Check for any Claude-specific tool names or behaviors mentioned in the prompt
+
+2. **Update `src/prompts/planning.ts`**:
+   - `"Take roughly 10-30 minutes of work for Claude"` → `"Take roughly 10-30 minutes of work"`
+   - `"which Claude model will execute the task"` → `"which model will execute the task"`
+   - Review entire planning prompt for Claude-specific language
+
+3. **Update `src/prompts/amend.ts`**:
+   - Same treatment as planning prompt
+   - `"which Claude model will execute the task"` → `"which model will execute the task"`
+
+4. **Update log messages in `src/core/claude-runner.ts`**:
+   - `"Starting interactive Claude session"` → `"Starting interactive session"` or include provider name dynamically
+   - `"Starting Claude execution session"` → `"Starting execution session"`
+   - `"Claude session timed out"` → `"Session timed out"`
+   - `"terminating Claude process"` → `"terminating process"`
+   - `"Claude exited with code"` → `"Process exited with code"`
+   - `"Claude stderr"` → `"Process stderr"`
+
+5. **Update `src/core/pull-request.ts`**:
+   - `callClaudeForPrBody` → `callLlmForPrBody` (or keep internal name, just update error messages)
+   - `"Claude CLI not found"` → make provider-aware or generic
+
+6. **Update `src/index.ts`**:
+   - `.description('RAF - Automated Task Planning & Execution with Claude Code')` → `'RAF - Automated Task Planning & Execution'`
+
+7. **Update `src/parsers/stream-renderer.ts`** doc comments:
+   - `"Event types from claude -p --output-format stream-json --verbose"` → make generic or note it's Claude-specific
+
+8. **Scan for remaining references**:
+   - Search entire `src/` for strings containing "claude" (case-insensitive)
+   - Skip: file names that will be addressed by the runner refactoring, type names with backward-compat re-exports
+   - Update any user-facing messages, error messages, and comments
+
+## Acceptance Criteria
+- [ ] No user-facing prompt text mentions "Claude" specifically
+- [ ] Log messages are provider-generic or include provider name dynamically
+- [ ] CLI description is LLM-agnostic
+- [ ] All prompts still function correctly (no broken templates)
+- [ ] TypeScript compiles without errors
+
+## Notes
+- Internal code comments mentioning "Claude" are lower priority but should be updated where easy
+- File names like `claude-runner.ts` don't need to change — they're internal implementation files for the Claude provider
+- The planning prompt is also used as the system prompt for this very planning session, but that's fine — it's a template, not a runtime concern

package/RAF/38-dual-wielder/plans/5-update-readme-docs.md

@@ -0,0 +1,52 @@
+---
+effort: low
+---
+# Task: Update README and Documentation
+
+## Objective
+Update README.md to reflect multi-provider support, new config options, and the `--provider` CLI flag.
+
+## Context
+The README currently describes RAF as a Claude Code-only tool. With Codex support added, documentation needs to reflect the dual-provider capability.
+
+## Dependencies
+1, 2, 3, 4
+
+## Requirements
+- Document the `provider` config field and `--provider` CLI flag
+- Document harness-prefixed model format (`claude/opus`, `codex/gpt-5.4`)
+- Document Codex-specific configuration (codexModels, codexEffortMapping)
+- Update existing examples that reference Claude-only setup
+- Keep README concise — don't over-document
+
+## Implementation Steps
+
+1. **Update the project description** at the top of README.md:
+   - Mention support for both Claude Code CLI and OpenAI Codex CLI
+
+2. **Add a Provider Configuration section**:
+   - Explain `provider` config field (default: `claude`)
+   - Show `--provider codex` CLI usage
+   - Explain model prefix format with examples
+
+3. **Update the Configuration section**:
+   - Add `codexModels` and `codexEffortMapping` to config example
+   - Show harness-prefixed model examples
+
+4. **Update command examples**:
+   - Add `--provider` flag to `raf do` and `raf plan` examples
+   - Show mixed provider usage
+
+5. **Note limitations**:
+   - Codex doesn't support `--resume` (session resume)
+   - System prompt is prepended to user message for Codex
+
+## Acceptance Criteria
+- [ ] README reflects multi-provider support
+- [ ] New config fields are documented
+- [ ] `--provider` flag is documented for relevant commands
+- [ ] Existing documentation is updated (not just appended)
+
+## Notes
+- Keep the README focused on usage, not implementation details
+- Don't document internal architecture changes (runner interface, etc.)