rafcode 2.1.1 → 2.3.0

package/.claude/settings.local.json

@@ -28,7 +28,10 @@
       "Bash(git stash:*)",
       "Bash(git checkout:*)",
       "WebFetch(domain:docs.anthropic.com)",
-      "WebFetch(domain:news.ycombinator.com)"
+      "WebFetch(domain:news.ycombinator.com)",
+      "Bash(chmod:*)",
+      "Bash(bash:*)",
+      "Bash(git add:*)"
     ]
   }
 }

package/CLAUDE.md

@@ -17,9 +17,10 @@ RAF (Ralph's Automation Framework) is a Node.js CLI tool that orchestrates task
 ```
 src/
 ├── index.ts                 # CLI entry point
-├── commands/                # CLI commands (plan, do, status)
+├── commands/                # CLI commands (plan, do, status, config)
 ├── core/                    # Core business logic
 ├── prompts/                 # System prompts for Claude
+│   └── config-docs.md       # Full config reference (used by raf config)
 ├── parsers/                 # Output parsing utilities
 ├── utils/                   # Utility functions
 └── types/                   # TypeScript type definitions
@@ -133,6 +134,38 @@ npm run lint       # Type check without emit
 - Failure reports include: Failure Reason, Analysis, Suggested Fix, Relevant Output
 - All failure outcomes end with `<promise>FAILED</promise>` marker
 
+### Configurable by Default
+- If a feature or setting can be configurable, it should be configurable through the config system
+- Built-in defaults in `DEFAULT_CONFIG` (`src/types/config.ts`) provide sensible out-of-the-box behavior
+- Global config at `~/.raf/raf.config.json` overrides defaults
+- CLI flags override config values
+- Three-tier precedence: **CLI flag > global config > built-in defaults**
+- When adding new features, add corresponding config keys to the schema
+
+### Configuration System
+- **Config file**: `~/.raf/raf.config.json` (optional — missing file uses all defaults)
+- **Schema** (defined in `src/types/config.ts`):
+  - `models.*` — Claude model per scenario (`execute`, `plan`, `nameGeneration`, `failureAnalysis`, `prGeneration`, `config`)
+  - `effort.*` — effort level per scenario (same scenarios as models)
+  - `timeout` — task timeout in seconds
+  - `maxRetries` — max retry attempts per task
+  - `autoCommit` — whether Claude auto-commits on task completion
+  - `worktree` — default worktree mode for plan/do commands
+  - `commitFormat.*` — commit message templates (`task`, `plan`, `amend`, `prefix`)
+  - `claudeCommand` — path/name of the Claude CLI binary
+- **Validation**: strict — unknown keys rejected at every nesting level (`src/utils/config.ts`)
+- **Deep-merge**: partial overrides merge with defaults (only specify keys you want to change)
+- **Helper accessors**: `getModel()`, `getEffort()`, `getCommitFormat()`, `getCommitPrefix()`, `getTimeout()`, `getMaxRetries()`, `getAutoCommit()`, `getWorktreeDefault()`, `getClaudeCommand()` (all in `src/utils/config.ts`)
+- **Full reference**: `src/prompts/config-docs.md` (also serves as system prompt for `raf config`)
+
+### `raf config` Command
+- `raf config` — launches interactive Claude session for viewing/editing config
+- `raf config "use haiku for name generation"` — session with initial prompt
+- `raf config --reset` — deletes config file after confirmation prompt
+- Session uses config documentation as system prompt and shows current config state
+- Post-session validation checks the config file for errors and warns on issues
+- Implementation: `src/commands/config.ts`
+
 ### Project Naming Convention
 - Format: `XXXXXX-project-name` where `XXXXXX` is a 6-character base26 ID (a-z only)
 - ID is generated from `(current_unix_seconds - RAF_EPOCH)` encoded as base26, left-padded with 'a' to 6 characters
@@ -159,26 +192,36 @@ Support multiple identifier formats in commands:
 
 Use `resolveProjectIdentifierWithDetails()` from `src/utils/paths.ts`
 
+### Token Usage Tracking
+- After each task, RAF displays a per-task token summary (input/output tokens, cache tokens, estimated cost)
+- After all tasks complete, RAF displays a grand total summary block
+- Token data comes from Claude's `--output-format stream-json --verbose` result events
+- Cost calculation uses configurable per-model pricing (`pricing.*` config keys)
+- `TokenTracker` class (`src/utils/token-tracker.ts`) accumulates usage across tasks
+- Formatting utilities in `src/utils/terminal-symbols.ts`: `formatTaskTokenSummary()`, `formatTokenTotalSummary()`, `formatNumber()`, `formatCost()`
+- Failed tasks with partial usage data are still tracked in totals
+- Tasks with no usage data (timeout, crash) are silently skipped
+
 ### Git Commit Schema
 
 All git commits are made by Claude during task execution. RAF does not create any automated commits.
 
-**Commit format** (Claude-generated during task execution):
-```
-RAF[<project-number>:<task>] <description>
-```
-Claude writes a concise description of what was accomplished, focusing on the actual change rather than the task name.
+**Commit format** is configurable via `commitFormat.*` config keys. The default templates use `{placeholder}` syntax:
+- `commitFormat.task`: `"{prefix}[{projectId}:{taskId}] {description}"` — task completion commits
+- `commitFormat.plan`: `"{prefix}[{projectId}] Plan: {projectName}"` — plan commits
+- `commitFormat.amend`: `"{prefix}[{projectId}] Amend: {projectName}"` — amendment commits
+- `commitFormat.prefix`: `"RAF"` — prefix token used in all templates
 
-Examples:
+Default output example:
 ```
 RAF[abcdef:01] Add validation for user input fields
 RAF[abcdef:02] Fix null pointer in auth handler
-RAF[abaaba:03] Refactor database connection pooling
 ```
 
 - Claude commits code changes and outcome file together in one commit per task
 - No commits on failure (changes are stashed instead)
 - Handle "not in git repo" gracefully (warning, no crash)
+- Template rendering: `renderCommitMessage()` in `src/utils/config.ts`
 
 ### Amendment Mode
 - `raf plan --amend <identifier>` adds tasks to existing projects
@@ -279,6 +322,11 @@ When working in a worktree, use absolute paths to the worktree directory for all
 
 ## Important Reminders
 
-1. After task completion update README.md (user facing) and CLAUDE.md (internal)
-2. Cover changes with tests - use TDD approach
-3. Use Clean Architecture principles (SOLID)
+1. **Keep README.md updated** — Update the user-facing README when:
+   - A new CLI command is added (add usage section + Command Reference entry)
+   - Existing command flags or behavior change
+   - Important features are added (e.g., worktrees, config, token tracking)
+   - The Features list needs a new bullet point
+2. **Keep CLAUDE.md updated** — Update internal docs when architectural decisions, config keys, or conventions change
+3. Cover changes with tests - use TDD approach
+4. Use Clean Architecture principles (SOLID)

package/RAF/ahslfe-config-wizard/decisions.md

@@ -0,0 +1,34 @@
+# Project Decisions
+
+## Config scope: should ALL hardcoded values become configurable, or only user-facing settings?
+User-facing only. Only settings users care about: models, effort, timeouts, retries, worktree, commit format. Internal poll intervals, grace periods, and char limits stay hardcoded.
+
+## Model configuration: per-scenario or simpler approach?
+Per-scenario models. Each scenario gets its own model key, e.g. models.plan: 'opus', models.execute: 'opus', models.nameGeneration: 'sonnet', etc.
+
+## Commit format: how configurable?
+Template string. A template like `{prefix}[{projectId}:{taskId}] {description}` where users can change the prefix ('RAF') and structure.
+
+## `raf config` with no arguments: Claude session or editor?
+Claude session. Always start an interactive Claude Sonnet session. User describes what they want in natural language, Claude edits config.
+
+## Reasoning effort: per-scenario or single global?
+Per-scenario effort. Each scenario gets its own effort level, e.g. effort.plan: 'high', effort.execute: 'medium', effort.nameGeneration: 'low'.
+
+## Worktree default behavior?
+Default off (current). Worktree is opt-in via --worktree flag. Config can flip this to make it default-on.
+
+## Config validation after changes?
+Strict validation. Validate schema, reject unknown keys and invalid values. Show errors and don't save bad config.
+
+## Config file name?
+raf.config.json — keep current name. Path: ~/.raf/raf.config.json
+
+## `raf config` Claude session mode?
+Interactive TTY. Spawn an interactive Claude Sonnet session (like planning mode). User can have a conversation, ask questions, make multiple changes.
+
+## Config documentation location?
+Bundled in package. Ship as part of the npm package (e.g., src/prompts/config-docs.md). Versioned with the code, injected at runtime.
+
+## Should there be a `raf config --reset`?
+Yes, with confirmation prompt before deleting the config file (falling back to defaults).

package/RAF/ahslfe-config-wizard/input.md

@@ -0,0 +1 @@
+- [ ] introduce config. go through the codebase and come up with config structure, ask me if something needs to be configured or not. also introduce "raf config [prompt]" that will take prompt and uses sonnet to make changes in raf config. make it json. store config in ~/.raf. create a .md doc with documentation and use it in instructions for "raf config [prompt or no prompt]" to start interactive session with claude (sonnet) to update config (claude will have appended system prompt with all the knowledge about config and how and where to change it). put in config stuff like reasoning, model choice per scenario (plan, do, project name generation etc.), worktree or not worktree by default, put there max setting you find in the repo (like commit format)

package/RAF/ahslfe-config-wizard/outcomes/01-define-config-schema.md

@@ -0,0 +1,38 @@
+# Outcome: Define Config Schema & Defaults
+
+## Summary
+
+Defined the comprehensive JSON config schema with all user-facing configurable values, validation, deep-merge, and typed helper accessors.
+
+## Key Changes
+
+### `src/types/config.ts`
+- Replaced the old flat `RafConfig` interface with a comprehensive nested schema: `models`, `effort`, `commitFormat` sub-objects plus scalar fields (`timeout`, `maxRetries`, `autoCommit`, `worktree`, `claudeCommand`)
+- Added `DEFAULT_CONFIG` constant with all defaults per the plan
+- Added utility types: `ClaudeModelName`, `EffortLevel`, `ModelScenario`, `EffortScenario`, `CommitFormatType`, `DeepPartial<T>`, `UserConfig`
+- Exported `VALID_MODELS` and `VALID_EFFORTS` arrays for validation
+- Kept backward-compat `DEFAULT_RAF_CONFIG` export (deprecated) so existing consumers don't break
+
+### `src/utils/config.ts`
+- Added `validateConfig()` — strict validation that rejects unknown keys at every nesting level, validates model names, effort levels, number ranges, and types
+- Added `ConfigValidationError` class for typed error handling
+- Added `resolveConfig(configPath?)` — loads from `~/.raf/raf.config.json`, validates, and deep-merges with defaults
+- Added `saveConfig(configPath, userConfig)` — writes partial user config with directory creation
+- Added helper accessors: `getModel()`, `getEffort()`, `getCommitFormat()`, `getCommitPrefix()`, `getTimeout()`, `getMaxRetries()`, `getAutoCommit()`, `getWorktreeDefault()`, `getClaudeCommand()`
+- Added `getResolvedConfig()` with caching and `resetConfigCache()` for tests
+- Kept backward-compat `loadConfig()`, `getConfig()`, `getEditor()`, `getClaudeModel()` functions
+
+### `tests/unit/config.test.ts`
+- 50 tests covering: validation (unknown keys, invalid values, edge cases), deep-merge (partial nested overrides), resolveConfig (file loading, defaults, immutability), saveConfig, helper accessors, DEFAULT_CONFIG completeness
+
+## Acceptance Criteria
+
+- [x] Comprehensive TypeScript types defined for the full config schema
+- [x] DEFAULT_CONFIG constant covers all settings with sensible defaults
+- [x] Validation rejects unknown keys, invalid model names, invalid effort levels, wrong types
+- [x] Deep-merge works correctly (partial overrides, nested objects)
+- [x] Config loads from `~/.raf/raf.config.json`
+- [x] Helper functions provide typed access to config values
+- [x] All tests pass (50/50; 1 pre-existing failure in unrelated test)
+
+<promise>COMPLETE</promise>

package/RAF/ahslfe-config-wizard/outcomes/02-refactor-codebase-to-use-config.md

@@ -0,0 +1,67 @@
+# Outcome: Refactor Codebase to Use Config
+
+## Summary
+
+Replaced all hardcoded settings throughout the codebase with config lookups using the schema from task 01. Every model name, effort level, commit format, and worktree default now reads from the centralized config system. CLI flags still take precedence over config values.
+
+## Key Changes
+
+### `src/utils/config.ts`
+- Added `renderCommitMessage(template, variables)` utility that replaces `{placeholder}` tokens in commit format templates
+
+### `src/utils/name-generator.ts`
+- Replaced hardcoded `SONNET_MODEL` constant with `getModel('nameGeneration')` from config
+- Replaced hardcoded `'claude'` command with `getClaudeCommand()` from config
+- Updated JSDoc comments to be model-agnostic
+
+### `src/core/failure-analyzer.ts`
+- Replaced hardcoded `'haiku'` model with `getModel('failureAnalysis')` from config
+- Uses `getClaudeCommand()` for CLI path resolution
+
+### `src/core/pull-request.ts`
+- Replaced hardcoded `'sonnet'` model with `getModel('prGeneration')` from config
+- Uses `getClaudeCommand()` for CLI path resolution
+
+### `src/core/claude-runner.ts`
+- Replaced hardcoded `'opus'` default with `getModel('execute')` from config
+- Uses `getClaudeCommand()` for CLI path resolution
+
+### `src/utils/validation.ts`
+- `resolveModelOption()` now accepts a `scenario` parameter (defaults to `'execute'`)
+- Default model comes from `getModel(scenario)` instead of hardcoded `'opus'`
+
+### `src/commands/plan.ts`
+- Passes `'plan'` scenario to `resolveModelOption()` for correct model default
+- Worktree mode default reads from `getWorktreeDefault()` config
+
+### `src/commands/do.ts`
+- Passes `'execute'` scenario to `resolveModelOption()` for correct model default
+- Replaced hardcoded `'medium'` effort with `getEffort('execute')` from config
+- Worktree mode default reads from `getWorktreeDefault()` config
+
+### `src/prompts/execution.ts`
+- Commit format in execution prompt dynamically generated from `getCommitFormat('task')` + `getCommitPrefix()` + `renderCommitMessage()`
+
+### `src/core/git.ts`
+- Plan/amend commit messages use `getCommitFormat('plan')`/`getCommitFormat('amend')` + `getCommitPrefix()` + `renderCommitMessage()`
+
+### `tests/unit/pull-request.test.ts`
+- Added `homedir` to the `node:os` mock (needed because `config.ts` is now imported transitively)
+
+### `tests/unit/config.test.ts`
+- Added 20 new tests:
+  - 7 tests for `renderCommitMessage()` (basic replacement, unknown placeholders, all format types, custom prefix)
+  - 10 tests verifying defaults match previous hardcoded values (models, effort, timeout, maxRetries, autoCommit, worktree, claudeCommand, commit formats)
+  - 3 tests verifying config overrides work (custom models, effort, commit format)
+
+## Acceptance Criteria
+
+- [x] No hardcoded model names remain in execution paths (only in DEFAULT_CONFIG)
+- [x] No hardcoded effort levels remain in execution paths
+- [x] Commit format uses templates from config
+- [x] CLI flags override config values (resolveModelOption passes CLI value first, falls back to config)
+- [x] Behavior is identical to before when no config file exists (defaults match current hardcoded values)
+- [x] All existing tests still pass (1040/1041; 1 pre-existing failure in unrelated test)
+- [x] New tests verify config integration (20 new tests)
+
+<promise>COMPLETE</promise>

package/RAF/ahslfe-config-wizard/outcomes/03-create-config-documentation.md

@@ -0,0 +1,37 @@
+# Outcome: Create Config Documentation
+
+## Summary
+
+Created comprehensive config documentation at `src/prompts/config-docs.md` that serves as both user-facing reference and system prompt for the `raf config` Claude session.
+
+## Key Changes
+
+### `src/prompts/config-docs.md` (new file)
+- **Overview** section explaining config location (`~/.raf/raf.config.json`), caching, and optional-key semantics
+- **File format** section explaining JSON format and deep-merge behavior with examples
+- **Config reference** documenting every key:
+  - `models.*` (6 scenarios) — type, valid values (`sonnet`/`haiku`/`opus`), defaults, descriptions
+  - `effort.*` (6 scenarios) — type, valid values (`low`/`medium`/`high`), defaults, descriptions
+  - `timeout` — positive number, default 60
+  - `maxRetries` — non-negative integer, default 3
+  - `autoCommit` — boolean, default true
+  - `worktree` — boolean, default false
+  - `commitFormat.*` (4 keys) — template strings with `{placeholder}` syntax
+  - `claudeCommand` — non-empty string, default "claude"
+- **Commit format template variables** documented per template type (task, plan, amend) with all available placeholders
+- **Validation rules** section listing all rejection conditions (unknown keys, invalid values, type checks)
+- **CLI precedence** section explaining flag > config > default order
+- **4 example configs**: minimal (single override), common (cost-conscious), full (all defaults explicit), team branding (custom prefix)
+- **Reset instructions** for full reset (delete file) and single-key reset (remove key)
+- **Claude session instructions** covering: reading config, making changes (partial writes, validation, preserving keys), explaining changes, showing current config, common user requests
+
+## Acceptance Criteria
+
+- [x] Every config key from the schema is documented with type, default, valid values, and description
+- [x] Commit format template variables are fully documented
+- [x] At least 3 example configs included (minimal, common, full, + team branding)
+- [x] Claude session instructions are clear and complete
+- [x] File is readable standalone as user documentation
+- [x] File is at `src/prompts/config-docs.md`
+
+<promise>COMPLETE</promise>

package/RAF/ahslfe-config-wizard/outcomes/04-implement-raf-config-command.md

@@ -0,0 +1,47 @@
+# Outcome: Implement `raf config` Command
+
+## Summary
+
+Implemented the `raf config` CLI command that launches an interactive Claude Sonnet TTY session for viewing and editing RAF configuration, with `--reset` support and post-session validation.
+
+## Key Changes
+
+### `src/commands/config.ts` (new file)
+- `createConfigCommand()` — Commander.js command definition with variadic `[prompt...]` argument and `--reset` flag
+- `runConfigSession(initialPrompt?)` — Spawns interactive Claude TTY session with:
+  - Config documentation from `src/prompts/config-docs.md` as system prompt
+  - Current config file contents (or "no config file" message)
+  - Model from `config.models.config` (default: sonnet)
+  - Effort level from `config.effort.config` (default: medium) via `CLAUDE_CODE_EFFORT_LEVEL` env var
+  - `--dangerously-skip-permissions` so Claude can write to `~/.raf/raf.config.json`
+- `handleReset()` — Prompts for confirmation via readline, deletes config file on confirm
+- `postSessionValidation()` — After Claude session ends, reads and validates config file, reports success/warnings
+- `loadConfigDocs()` — Reads the .md file at runtime using `import.meta.url` path resolution
+- `getCurrentConfigState()` — Returns config file contents or "no config file" message
+- `buildConfigSystemPrompt()` — Combines config docs and current state into system prompt
+
+### `src/index.ts`
+- Registered `createConfigCommand()` so `raf config` appears in CLI help
+
+### `tests/unit/config-command.test.ts` (new file)
+- 20 tests covering:
+  - Command setup (5): name, description, variadic argument, --reset option, parent registration
+  - Post-session validation (7): valid configs, unknown keys, invalid models/efforts, non-object, empty config
+  - Reset flow (2): file deletion, non-existent file handling
+  - Config file round-trip (3): write/read valid, invalid JSON detection, validation error detection
+  - System prompt construction (2): no-file state, existing config state
+
+## Acceptance Criteria
+
+- [x] `raf config` starts an interactive Claude Sonnet session with config knowledge
+- [x] `raf config "use haiku for name generation"` starts session with that prompt
+- [x] `raf config --reset` prompts for confirmation and deletes config file
+- [x] Claude session has full config documentation as system prompt
+- [x] Claude session shows current config state
+- [x] Post-session validation checks the config file
+- [x] `~/.raf/` directory is created if it doesn't exist (Claude instructed to create it)
+- [x] Command is registered and appears in `raf --help`
+- [x] Tests cover command setup and reset flow (20 tests)
+- [x] All tests pass (1060/1061; 1 pre-existing failure in unrelated test)
+
+<promise>COMPLETE</promise>

package/RAF/ahslfe-config-wizard/outcomes/05-update-claude-md.md

@@ -0,0 +1,26 @@
+# Outcome: Update CLAUDE.md with Config Architecture
+
+## Summary
+
+Updated CLAUDE.md to document the new config system, the "configurable by default" principle, and the `raf config` command.
+
+## Key Changes
+
+### `CLAUDE.md`
+- **Directory structure**: Updated commands comment to include `config`, added `config-docs.md` under `prompts/`
+- **Configurable by Default** (new architectural decision): Documents the principle that all settings should be configurable, with three-tier precedence (CLI flag > global config > built-in defaults)
+- **Configuration System** (new section): Documents config file location, schema overview, validation, deep-merge, helper accessors, and pointer to full reference
+- **`raf config` Command** (new section): Documents all three usage modes (`raf config`, `raf config <prompt>`, `raf config --reset`)
+- **Git Commit Schema**: Updated to reference configurable `commitFormat.*` templates with `{placeholder}` syntax instead of hardcoded format, added `renderCommitMessage()` reference
+
+## Acceptance Criteria
+
+- [x] "Configurable by Default" principle documented as architectural decision
+- [x] Config system fully documented (location, schema overview, precedence, validation)
+- [x] `raf config` command documented
+- [x] Directory structure updated
+- [x] Old config references updated (commit format now references templates)
+- [x] Commit format section references templates
+- [x] CLAUDE.md remains well-organized and concise
+
+<promise>COMPLETE</promise>

package/RAF/ahslfe-config-wizard/plans/01-define-config-schema.md

@@ -0,0 +1,73 @@
+# Task: Define Config Schema & Defaults
+
+## Objective
+Define the comprehensive JSON config schema with all user-facing configurable values and their defaults.
+
+## Context
+RAF currently has a minimal config in `src/types/config.ts` with only `defaultTimeout`, `defaultMaxRetries`, `autoCommit`, and `claudeCommand`. Many values are hardcoded across the codebase. This task creates the complete schema that all subsequent tasks will use.
+
+## Requirements
+- Config file: `~/.raf/raf.config.json`
+- Built-in defaults embedded in code, global config in `~/.raf/` overrides them
+- Strict validation: reject unknown keys and invalid values
+- All values are optional in the file (defaults used for anything not specified)
+
+### Config structure (user-facing settings only):
+
+**Models** (per-scenario):
+- `models.plan` — model for planning sessions (default: `'opus'`)
+- `models.execute` — model for task execution (default: `'opus'`)
+- `models.nameGeneration` — model for project name generation (default: `'sonnet'`)
+- `models.failureAnalysis` — model for analyzing failures (default: `'haiku'`)
+- `models.prGeneration` — model for PR body generation (default: `'sonnet'`)
+- `models.config` — model for config editing sessions (default: `'sonnet'`)
+- Valid values: `'sonnet'`, `'haiku'`, `'opus'`
+
+**Reasoning effort** (per-scenario):
+- `effort.plan` — effort for planning (default: `'high'`)
+- `effort.execute` — effort for task execution (default: `'medium'`)
+- `effort.nameGeneration` — effort for name gen (default: `'low'`)
+- `effort.failureAnalysis` — effort for failure analysis (default: `'low'`)
+- `effort.prGeneration` — effort for PR gen (default: `'medium'`)
+- `effort.config` — effort for config sessions (default: `'medium'`)
+- Valid values: `'low'`, `'medium'`, `'high'`
+
+**Execution**:
+- `timeout` — default task timeout in minutes (default: `60`)
+- `maxRetries` — max retry attempts per task (default: `3`)
+- `autoCommit` — auto-commit on task success (default: `true`)
+
+**Worktree**:
+- `worktree` — use worktree by default for plan/do (default: `false`)
+
+**Commit format**:
+- `commitFormat.task` — template for task commits (default: `'{prefix}[{projectId}:{taskId}] {description}'`)
+- `commitFormat.plan` — template for plan commits (default: `'{prefix}[{projectId}] Plan: {projectName}'`)
+- `commitFormat.amend` — template for amend commits (default: `'{prefix}[{projectId}] Amend: {projectName}'`)
+- `commitFormat.prefix` — the prefix used in templates (default: `'RAF'`)
+
+**CLI**:
+- `claudeCommand` — path/name of claude CLI binary (default: `'claude'`)
+
+## Implementation Steps
+1. Replace the existing `RafConfig` type in `src/types/config.ts` with the new comprehensive schema (nested objects for `models`, `effort`, `commitFormat`)
+2. Define a `DEFAULT_CONFIG` constant with all default values
+3. Create a validation function that checks every key against the schema: valid model names, valid effort levels, number ranges, string formats, no unknown keys
+4. Create a `resolveConfig()` function that deep-merges the default config with the user's partial config from `~/.raf/raf.config.json` — user values override defaults at the leaf level
+5. Update `src/utils/config.ts` to use the new schema — `loadConfig()` should read from `~/.raf/raf.config.json` (not project-local), validate, and merge with defaults
+6. Export helpers: `getModel(scenario)`, `getEffort(scenario)`, `getCommitFormat(type)`, `getTimeout()`, etc. for easy consumption
+7. Write tests for validation (unknown keys rejected, invalid values rejected, partial configs merged correctly, defaults returned when no config file exists)
+
+## Acceptance Criteria
+- [ ] Comprehensive TypeScript types defined for the full config schema
+- [ ] DEFAULT_CONFIG constant covers all settings with sensible defaults
+- [ ] Validation rejects unknown keys, invalid model names, invalid effort levels, wrong types
+- [ ] Deep-merge works correctly (partial overrides, nested objects)
+- [ ] Config loads from `~/.raf/raf.config.json`
+- [ ] Helper functions provide typed access to config values
+- [ ] All tests pass
+
+## Notes
+- The existing `RafConfig` type and `loadConfig`/`saveConfig` in `src/utils/config.ts` need to be replaced, not extended — they currently load from project-local dirs
+- The commit format template uses `{placeholder}` syntax — the rendering will happen in task 02 when code is refactored
+- Keep `src/types/config.ts` as the single source of truth for config types

package/RAF/ahslfe-config-wizard/plans/02-refactor-codebase-to-use-config.md

@@ -0,0 +1,74 @@
+# Task: Refactor Codebase to Use Config
+
+## Objective
+Replace all hardcoded settings throughout the codebase with config lookups using the schema from task 01.
+
+## Context
+The codebase has hardcoded model names, effort levels, timeouts, commit formats, and other settings scattered across many files. This task wires everything up to use the centralized config system.
+
+## Dependencies
+01
+
+## Requirements
+- Every previously hardcoded user-facing setting must read from config
+- CLI flags (--model, --timeout, etc.) still override config values
+- Precedence: CLI flag > `~/.raf/raf.config.json` > built-in defaults
+- No behavioral changes — existing defaults preserved, just sourced from config now
+
+### Files and values to refactor:
+
+**Model references:**
+- `src/utils/name-generator.ts` — hardcoded `'sonnet'` → `config.models.nameGeneration`
+- `src/core/failure-analyzer.ts` — hardcoded `'haiku'` → `config.models.failureAnalysis`
+- `src/core/pull-request.ts` — hardcoded `'sonnet'` → `config.models.prGeneration`
+- `src/core/claude-runner.ts` — default `'opus'` → `config.models.execute`
+- `src/utils/validation.ts` — default model `'opus'` → `config.models.plan` or `config.models.execute` depending on context
+- `src/commands/plan.ts` — model resolution → config.models.plan as default
+- `src/commands/do.ts` — model resolution → config.models.execute as default
+
+**Effort levels:**
+- `src/commands/do.ts` — hardcoded `'medium'` → `config.effort.execute`
+- Pass effort to name-generator, failure-analyzer, PR-generator from config
+
+**Timeouts:**
+- `src/commands/do.ts` — default `'60'` → `config.timeout`
+- `src/utils/name-generator.ts` — `30000` timeout
+- `src/core/failure-analyzer.ts` — `60000` timeout
+- `src/core/pull-request.ts` — `120000` timeout
+
+**Commit formats:**
+- `src/prompts/execution.ts` — task commit format → `config.commitFormat.task` template
+- `src/core/git.ts` — plan/amend commit formats → `config.commitFormat.plan` / `config.commitFormat.amend` templates
+- Implement a `renderCommitMessage(template, vars)` utility that replaces `{placeholder}` tokens
+
+**Worktree default:**
+- `src/commands/plan.ts` — default worktree flag → `config.worktree`
+- `src/commands/do.ts` — default worktree flag → `config.worktree`
+
+**Other:**
+- `src/commands/do.ts` — maxRetries, autoCommit → config values
+- `src/utils/config.ts` — `claudeCommand` → config value
+
+## Implementation Steps
+1. Identify all call sites that need config access — use the file/line references above
+2. Create a `renderCommitMessage(template, variables)` utility for commit format templates
+3. Update each file to import and use config helpers instead of hardcoded values
+4. Ensure CLI flags take precedence: where a CLI flag is provided, use it; otherwise fall back to config
+5. Update the planning system prompt to include the configured commit format (so Claude knows what format to use)
+6. Update the execution system prompt similarly
+7. Write tests verifying that config values are respected and CLI flags override them
+8. Test that default behavior is unchanged when no config file exists
+
+## Acceptance Criteria
+- [ ] No hardcoded model names remain in execution paths (only in DEFAULT_CONFIG)
+- [ ] No hardcoded effort levels remain in execution paths
+- [ ] Commit format uses templates from config
+- [ ] CLI flags override config values
+- [ ] Behavior is identical to before when no config file exists (defaults match current hardcoded values)
+- [ ] All existing tests still pass
+- [ ] New tests verify config integration
+
+## Notes
+- Be careful with the precedence chain — some values go through multiple layers (CLI → command → runner)
+- The commit format in system prompts needs to be dynamically generated, not static strings
+- Don't change internal constants (poll intervals, grace periods, char limits) — those stay hardcoded per the decisions

package/RAF/ahslfe-config-wizard/plans/03-create-config-documentation.md

@@ -0,0 +1,57 @@
+# Task: Create Config Documentation
+
+## Objective
+Create a comprehensive config documentation file bundled in the package that serves as both user-facing docs and the system prompt for the `raf config` Claude session.
+
+## Context
+The `raf config` command will spawn an interactive Claude session that needs full knowledge of the config schema, valid values, defaults, and how to edit the file. This documentation serves double duty: it's readable by users and injected as a system prompt for Claude during config sessions.
+
+## Dependencies
+01
+
+## Requirements
+- File location: `src/prompts/config-docs.md` (bundled in package, versioned with code)
+- Must be comprehensive enough for Claude to edit config without any other context
+- Must be readable by humans as standalone documentation
+- Must cover every config key, its type, valid values, default, and what it controls
+
+### Content structure:
+1. **Overview** — what the config is, where it lives (`~/.raf/raf.config.json`), how it works
+2. **File format** — JSON, all keys optional, deep-merge with defaults
+3. **Config reference** — every key documented:
+   - Key path (e.g., `models.plan`)
+   - Type and valid values
+   - Default value
+   - What it controls and when it's used
+   - Example
+4. **Commit format templates** — explain the `{placeholder}` syntax, available variables per template type
+5. **Validation rules** — what gets rejected (unknown keys, invalid values)
+6. **Examples** — complete example configs for common scenarios (minimal, full, team-specific)
+7. **CLI precedence** — explain that CLI flags override config values
+8. **Reset instructions** — how to reset to defaults
+
+### Claude-specific instructions (for when used as system prompt):
+- How to read the current config file
+- How to validate changes before saving
+- How to explain changes to the user
+- Never remove keys the user didn't ask to change
+
+## Implementation Steps
+1. Write the documentation file at `src/prompts/config-docs.md` covering all sections above
+2. Reference the actual config schema types from task 01 to ensure completeness — every key in the schema must be documented
+3. Include practical examples showing partial configs (users only set what they want to change)
+4. Add a "For Claude" section at the end with instructions for the config editing session (read file, validate, explain, write)
+5. Ensure the file can be imported/read at runtime by the config command (task 04 will handle the actual import)
+
+## Acceptance Criteria
+- [ ] Every config key from the schema is documented with type, default, valid values, and description
+- [ ] Commit format template variables are fully documented
+- [ ] At least 3 example configs included (minimal, common, full)
+- [ ] Claude session instructions are clear and complete
+- [ ] File is readable standalone as user documentation
+- [ ] File is at `src/prompts/config-docs.md`
+
+## Notes
+- This file will be read by Claude at runtime during `raf config` sessions — keep it clear and unambiguous
+- The documentation must stay in sync with the schema — if schema changes, docs must update too
+- Keep the tone practical and direct — this is a reference document, not a tutorial