rafcode 3.0.0 → 3.8.0

package/src/prompts/planning.ts

@@ -15,16 +15,8 @@ export interface PlanningPromptResult {
  * - userMessage: Reference to input.md file (via positional argument, triggers the LLM to start)
  */
 export function getPlanningPrompt(params: PlanningPromptParams): PlanningPromptResult {
-  const { projectPath, worktreeMode } = params;
-  const worktreeFlag = worktreeMode ? ' --worktree' : '';
-
-  const systemPrompt = `You are a project planning assistant for RAF (Ralph's Automation Framework). Your task is to analyze the user's project description and create detailed task plans.
-
-## Your Goals
-
-1. **Analyze the input** and identify distinct, actionable tasks
-2. **Interview the user** about EACH task to gather specific requirements
-3. **Create plan files** for each task with clear instructions
+  const { projectPath } = params;
+  const systemPrompt = `You are a project planning assistant for RAF (Ralph's Automation Framework). Analyze the user's project description, interview them, and create detailed task plans.
 
 ## Project Location
 
@@ -34,53 +26,25 @@ Project folder: ${projectPath}
 
 ### Step 1: Identify and Order Tasks
 
-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
+Identify distinct tasks from the project description. Each task should be independently completable, have a clear outcome, and take roughly 10-30 minutes.
 
-**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)
-- Core implementation tasks come next
-- Integration and extension tasks come later
-- Testing and validation tasks typically come last
+**Order tasks by logical execution order:** setup/foundation → core implementation → integration/extension → testing/validation.
 
 ### Step 2: Interview the User
 
-For EACH task you identify, you MUST use the AskUserQuestion tool to gather:
-- Specific requirements and constraints
-- Technology preferences
-- Any existing code or patterns to follow
-- Edge cases to handle
-
-DO NOT skip the interview step. The quality of your plans depends on understanding the user's exact needs.
+For EACH task, use the AskUserQuestion tool to gather specific requirements, technology preferences, existing patterns to follow, and edge cases. Do not skip this step.
 
-### Step 2.5: Record Decisions
-
-After EACH interview question is answered, record the Q&A pair in the decisions file:
-- ${projectPath}/decisions.md
-
-Use this format:
+After EACH answer, append the Q&A pair to \`${projectPath}/decisions.md\`:
 \`\`\`markdown
-# Project Decisions
-
-## [Question asked]
-[User's answer]
-
 ## [Question asked]
 [User's answer]
 \`\`\`
 
-This file serves as documentation of design choices made during planning. Append each new Q&A pair as you conduct the interview.
-
 ### Step 3: Create Plan Files
 
-After interviewing the user about all tasks, create plan files in the plans folder:
-- ${projectPath}/plans/1-task-name.md
-- ${projectPath}/plans/2-task-name.md
-- etc.
+Create plan files in \`${projectPath}/plans/\` numbered in execution order (e.g., \`1-task-name.md\`, \`2-task-name.md\`). Use kebab-case names.
 
-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:
+Each plan file MUST have this structure:
 
 \`\`\`markdown
 ---
@@ -89,116 +53,51 @@ effort: medium
 # Task: [Task Name]
 
 ## Objective
-[Clear, one-sentence description of what this task accomplishes]
+[Clear, one-sentence description]
 
 ## Context
 [Why this task is needed, how it fits into the larger project]
 
 ## Dependencies
-[Optional section - omit if task has no dependencies]
-[Comma-separated list of task IDs this task depends on, e.g., "1, 2"]
-[If a dependency fails, this task will be automatically blocked]
+[Optional — omit if none. Comma-separated task IDs, e.g., "1, 2"]
 
 ## Requirements
-[Specific requirements gathered from the user interview]
 - Requirement 1
 - Requirement 2
-- ...
 
 ## Implementation Steps
 1. [Step 1]
 2. [Step 2]
-3. [Step 3]
-...
 
 ## Acceptance Criteria
 - [ ] Criterion 1
 - [ ] Criterion 2
-- [ ] All tests pass
 
 ## Notes
-[Any additional context, warnings, or considerations]
-\`\`\`
-
-### Frontmatter Requirements
-
-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
-
-Optionally, you can add an explicit \`model\` field to override the effort-based model selection:
-\`\`\`markdown
----
-effort: medium
-model: opus
----
-# Task: ...
+[Additional context, warnings, or considerations]
 \`\`\`
 
-This is rarely needed — prefer using the \`effort\` label so the user's config controls the actual model used.
+**Frontmatter fields:**
+- \`effort\` (REQUIRED): \`low\` (trivial/mechanical), \`medium\` (well-scoped feature work), \`high\` (architectural/complex)
+- \`model\` (optional): Override effort-based model selection. Rarely needed — prefer \`effort\` so the user's config controls the model.
 
-### Step 4: Infer Task Dependencies
+**Dependencies:** Infer automatically from task relationships (don't ask the user). Only reference lower-numbered tasks. Only direct dependencies, not transitive ones. Omit section if no prerequisites.
 
-For each task, analyze which other tasks must complete successfully before it can begin. Add a \`## Dependencies\` section to plan files that have prerequisites.
+### Step 4: Confirm Completion
 
-**How to identify dependencies:**
-- If task B uses output/artifacts from task A → B depends on A
-- If task B modifies code created by task A → B depends on A
-- If task B tests functionality from task A → B depends on A
-- If task B extends or builds upon task A → B depends on A
-
-**Dependency format examples:**
-\`\`\`markdown
-## Dependencies
-1
-\`\`\`
-or for multiple dependencies:
-\`\`\`markdown
-## Dependencies
-1, 2
-\`\`\`
-
-**Rules for dependencies:**
-- Only reference lower-numbered tasks (tasks are ordered by execution order)
-- Omit the Dependencies section entirely if a task has no prerequisites
-- Keep dependency lists minimal - only direct dependencies, not transitive ones
-- Never create circular dependencies (impossible if you only reference lower-numbered tasks)
-
-### Step 5: Confirm Completion
-
-After creating all plan files:
-1. Provide a summary of the tasks you've created, including the effort level for each task. Example:
-   - 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:
+Provide a summary with effort levels (e.g., "Task 1: setup-database (effort: low)"), then display:
 
 \`\`\`
 Planning complete! To exit this session and run your tasks:
   1. Press Ctrl-C twice to exit
-  2. Then run: raf do <project>${worktreeFlag}
+  2. Then run: raf do <project>
 \`\`\`
 
-## Important Rules
-
-1. ALWAYS interview the user before creating plans
-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
-6. Only add Dependencies section when a task genuinely requires another to complete first
-7. Dependencies must only reference lower-numbered tasks to prevent circular dependencies
-8. Be specific - vague plans lead to poor execution
-9. ALWAYS include the \`effort\` frontmatter field in every plan file — assess each task's complexity
-
-## Plan Output Style
-
-Plans can include whatever level of detail you deem helpful for the executing agent. Use your judgment:
-- Include implementation details when they clarify the approach
-- Code snippets are acceptable when they help illustrate a specific pattern
-- File paths are helpful when referencing existing project files, patterns, or directories
-- Focus on clarity — the goal is for the executing agent to understand what needs to be done`;
+## Rules
+
+- Each plan must be self-contained with all context needed for execution
+- Be specific — vague plans lead to poor execution
+- Include implementation details, code snippets, and file paths when they clarify the approach`;
 
   const userMessage = `Here is my project description:
 

package/src/types/config.ts

@@ -1,13 +1,13 @@
-/** CLI harness provider */
-export type HarnessProvider = 'claude' | 'codex';
+/** CLI harness name */
+export type HarnessName = 'claude' | 'codex';
 
 /** Short alias for a Claude model family */
 export type ClaudeModelAlias = 'sonnet' | 'haiku' | 'opus';
 
 /** Short alias for a Codex model family */
-export type CodexModelAlias = 'spark' | 'codex' | 'gpt54';
+export type CodexModelAlias = 'codex' | 'gpt54';
 
-/** Provider-agnostic model alias (union of all provider aliases) */
+/** Harness-agnostic model alias (union of all harness aliases) */
 export type ModelAlias = ClaudeModelAlias | CodexModelAlias;
 
 /**
@@ -17,7 +17,7 @@ export type ModelAlias = ClaudeModelAlias | CodexModelAlias;
  */
 export type ClaudeModelName = ClaudeModelAlias | (string & { __brand?: 'FullModelId' });
 
-/** Provider-agnostic model name — accepts any alias, full ID, or harness-prefixed format */
+/** Harness-agnostic model name — accepts any alias, full ID, or harness-prefixed format */
 export type ModelName = string & { __brand?: 'ModelName' };
 
 /** Task complexity label for per-task effort frontmatter. Maps to models via effortMapping. */
@@ -26,23 +26,38 @@ export type TaskEffortLevel = 'low' | 'medium' | 'high';
 export type ModelScenario = 'plan' | 'execute' | 'nameGeneration' | 'failureAnalysis' | 'prGeneration' | 'config';
 export type CommitFormatType = 'task' | 'plan' | 'amend';
 
+/**
+ * A harness-aware model configuration entry.
+ * Stores model, harness, and optional reasoning effort together.
+ */
+export interface ModelEntry {
+  /** Model name: short alias (opus, sonnet, gpt-5.4) or full ID */
+  model: string;
+  /** Which CLI harness to use for this entry */
+  harness: HarnessName;
+  /** Optional reasoning effort hint. Codex accepts: "none", "minimal", "low", "medium", "high", "xhigh" */
+  reasoningEffort?: string;
+  /** Enable fast mode for faster output (Claude only). Default: false/omitted. */
+  fast?: boolean;
+}
+
 export interface ModelsConfig {
-  plan: ClaudeModelName;
-  execute: ClaudeModelName;
-  nameGeneration: ClaudeModelName;
-  failureAnalysis: ClaudeModelName;
-  prGeneration: ClaudeModelName;
-  config: ClaudeModelName;
+  plan: ModelEntry;
+  execute: ModelEntry;
+  nameGeneration: ModelEntry;
+  failureAnalysis: ModelEntry;
+  prGeneration: ModelEntry;
+  config: ModelEntry;
 }
 
 /**
- * Maps task complexity labels to model names.
+ * Maps task complexity labels to harness-aware model entries.
  * Used to resolve per-task effort frontmatter to a model.
  */
 export interface EffortMappingConfig {
-  low: ClaudeModelName;
-  medium: ClaudeModelName;
-  high: ClaudeModelName;
+  low: ModelEntry;
+  medium: ModelEntry;
+  high: ModelEntry;
 }
 
 export interface CommitFormatConfig {
@@ -59,15 +74,9 @@ export interface DisplayConfig {
 }
 
 export interface RafConfig {
-  /** CLI harness provider. Default: 'claude' */
-  provider: HarnessProvider;
   models: ModelsConfig;
-  /** Maps task complexity labels (low/medium/high) to models. Used for per-task effort frontmatter. */
+  /** Maps task complexity labels (low/medium/high) to model entries. Used for per-task effort frontmatter. */
   effortMapping: EffortMappingConfig;
-  /** Codex model assignments per scenario */
-  codexModels: ModelsConfig;
-  /** Maps task complexity labels to Codex models */
-  codexEffortMapping: EffortMappingConfig;
   timeout: number;
   maxRetries: number;
   autoCommit: boolean;
@@ -79,32 +88,18 @@ export interface RafConfig {
 }
 
 export const DEFAULT_CONFIG: RafConfig = {
-  provider: 'claude',
   models: {
-    plan: 'opus',
-    execute: 'opus',
-    nameGeneration: 'sonnet',
-    failureAnalysis: 'haiku',
-    prGeneration: 'sonnet',
-    config: 'sonnet',
+    plan: { model: 'opus', harness: 'claude' },
+    execute: { model: 'opus', harness: 'claude' },
+    nameGeneration: { model: 'sonnet', harness: 'claude' },
+    failureAnalysis: { model: 'haiku', harness: 'claude' },
+    prGeneration: { model: 'sonnet', harness: 'claude' },
+    config: { model: 'sonnet', harness: 'claude' },
   },
   effortMapping: {
-    low: 'sonnet',
-    medium: 'opus',
-    high: 'opus',
-  },
-  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',
-  },
-  codexEffortMapping: {
-    low: 'gpt-5.3-codex-spark',
-    medium: 'gpt-5.3-codex',
-    high: 'gpt-5.4',
+    low: { model: 'sonnet', harness: 'claude' },
+    medium: { model: 'opus', harness: 'claude' },
+    high: { model: 'opus', harness: 'claude' },
   },
   timeout: 60,
   maxRetries: 3,
@@ -112,9 +107,9 @@ export const DEFAULT_CONFIG: RafConfig = {
   worktree: false,
   syncMainBranch: true,
   commitFormat: {
-    task: '{prefix}[{projectId}:{taskId}] {description}',
-    plan: '{prefix}[{projectId}] Plan: {projectName}',
-    amend: '{prefix}[{projectId}] Amend: {projectName}',
+    task: '{prefix}[{projectName}:{taskId}] {description}',
+    plan: '{prefix}[{projectName}] Plan: {description}',
+    amend: '{prefix}[{projectName}] Amend: {description}',
     prefix: 'RAF',
   },
   display: {
@@ -131,9 +126,9 @@ export type UserConfig = DeepPartial<RafConfig>;
 
 export const VALID_MODEL_ALIASES: readonly ClaudeModelAlias[] = ['sonnet', 'haiku', 'opus'];
 
-export const VALID_CODEX_MODEL_ALIASES: readonly CodexModelAlias[] = ['spark', 'codex', 'gpt54'];
+export const VALID_CODEX_MODEL_ALIASES: readonly CodexModelAlias[] = ['codex', 'gpt54'];
 
-export const VALID_HARNESS_PROVIDERS: readonly HarnessProvider[] = ['claude', 'codex'];
+export const VALID_HARNESSES: readonly HarnessName[] = ['claude', 'codex'];
 
 /**
  * Regex for full Claude model IDs (e.g., `claude-sonnet-4-5-20250929`, `claude-opus-4-5-20251101`).
@@ -157,9 +152,6 @@ export const DEFAULT_RAF_CONFIG = {
 
 export interface PlanCommandOptions {
   projectName?: string;
-  model?: ClaudeModelName;
-  sonnet?: boolean;
-  provider?: HarnessProvider;
 }
 
 export interface DoCommandOptions {
@@ -167,10 +159,6 @@ export interface DoCommandOptions {
   verbose?: boolean;
   debug?: boolean;
   force?: boolean;
-  model?: ClaudeModelName;
-  sonnet?: boolean;
-  worktree?: boolean;
-  provider?: HarnessProvider;
 }
 
 export interface StatusCommandOptions {
@@ -184,7 +172,7 @@ export interface ModelTokenUsage {
   cacheReadInputTokens: number;
   cacheCreationInputTokens: number;
   /** Cost in USD for this model's usage (provided by Claude CLI). */
-  costUsd: number;
+  costUsd?: number | null;
 }
 
 /** Token usage data extracted from Claude CLI stream-json result event. */
@@ -197,5 +185,5 @@ export interface UsageData {
   /** Per-model breakdown (e.g., { "claude-opus-4-6": { ... } }). */
   modelUsage: Record<string, ModelTokenUsage>;
   /** Total cost in USD for this usage (provided by Claude CLI). */
-  totalCostUsd: number;
+  totalCostUsd: number | null;
 }