rafcode 2.3.0 → 2.4.0

package/src/core/failure-analyzer.ts

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { execSync } from 'node:child_process';
-import { getModel, getClaudeCommand } from '../utils/config.js';
+import { getModel } from '../utils/config.js';
 
 /**
  * Failure types that can be detected programmatically without using the API.
@@ -213,9 +213,8 @@ function extractRelevantOutput(output: string, maxLines: number): string {
  * Get the path to Claude CLI.
  */
 function getClaudePath(): string {
-  const cmd = getClaudeCommand();
   try {
-    return execSync(`which ${cmd}`, { encoding: 'utf-8' }).trim();
+    return execSync('which claude', { encoding: 'utf-8' }).trim();
   } catch {
     throw new Error('Claude CLI not found. Please ensure it is installed and in your PATH.');
   }
@@ -312,6 +311,7 @@ Respond with ONLY a markdown report in this exact format:
     const failureModel = getModel('failureAnalysis');
     const proc = spawn(claudePath, [
       '--model', failureModel,
+      '--no-session-persistence',
       '--dangerously-skip-permissions',
       '-p',
       prompt,

package/src/core/pull-request.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 { getModel, getClaudeCommand, getModelShortName } from '../utils/config.js';
+import { getModel, getModelShortName } from '../utils/config.js';
 import { extractProjectName, getInputPath, getDecisionsPath, getOutcomesDir, TASK_ID_PATTERN } from '../utils/paths.js';
 
 export interface PrCreateResult {
@@ -354,10 +354,9 @@ export function filterClaudeOutput(output: string): string {
  * Call Claude to generate a PR body.
  */
 async function callClaudeForPrBody(prompt: string, timeoutMs: number): Promise<string> {
-  const cmd = getClaudeCommand();
   let claudePath: string;
   try {
-    claudePath = execSync(`which ${cmd}`, { encoding: 'utf-8', stdio: 'pipe' }).trim();
+    claudePath = execSync('which claude', { encoding: 'utf-8', stdio: 'pipe' }).trim();
   } catch {
     throw new Error('Claude CLI not found');
   }
@@ -369,6 +368,7 @@ async function callClaudeForPrBody(prompt: string, timeoutMs: number): Promise<s
     const prModel = getModel('prGeneration');
     const proc = spawn(claudePath, [
       '--model', prModel,
+      '--no-session-persistence',
       '--dangerously-skip-permissions',
       '-p',
       prompt,

package/src/core/state-derivation.ts

@@ -1,6 +1,7 @@
 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 { parsePlanFrontmatter, type PlanFrontmatter } from '../utils/frontmatter.js';
 
 export type DerivedTaskStatus = 'pending' | 'completed' | 'failed' | 'blocked';
 
@@ -16,6 +17,10 @@ export interface DerivedTask {
   planFile: string;
   status: DerivedTaskStatus;
   dependencies: string[];
+  /** Frontmatter metadata parsed from the plan file. */
+  frontmatter?: PlanFrontmatter;
+  /** Warnings from frontmatter parsing. */
+  frontmatterWarnings?: string[];
 }
 
 export interface DerivedProjectState {
@@ -218,23 +223,34 @@ export function deriveProjectState(projectPath: string): DerivedProjectState {
     }
   }
 
-  // First pass: Match plan files to outcomes and parse dependencies
+  // First pass: Match plan files to outcomes and parse dependencies + frontmatter
   for (const planFile of planFiles) {
     const match = planFile.match(new RegExp(`^(${TASK_ID_PATTERN})-(.+)\\.md$`));
     if (match && match[1]) {
       const taskId = match[1];
       const status = outcomeStatuses.get(taskId) ?? 'pending';
 
-      // Read plan file to extract dependencies
+      // Read plan file to extract dependencies and frontmatter
       const planContent = fs.readFileSync(path.join(plansDir, planFile), 'utf-8');
       const dependencies = parseDependencies(planContent);
+      const frontmatterResult = parsePlanFrontmatter(planContent);
 
-      tasks.push({
+      const task: DerivedTask = {
         id: taskId,
         planFile: path.join('plans', planFile),
         status,
         dependencies,
-      });
+      };
+
+      // Only add frontmatter if valid metadata was found
+      if (frontmatterResult.hasFrontmatter) {
+        task.frontmatter = frontmatterResult.frontmatter;
+      }
+      if (frontmatterResult.warnings.length > 0) {
+        task.frontmatterWarnings = frontmatterResult.warnings;
+      }
+
+      tasks.push(task);
     }
   }
 

package/src/core/worktree.ts

@@ -432,3 +432,233 @@ export function resolveWorktreeProjectByIdentifier(
   // Ambiguous or no match
   return null;
 }
+
+export interface SyncMainBranchResult {
+  success: boolean;
+  /** The detected main branch name (e.g., 'main' or 'master') */
+  mainBranch: string | null;
+  /** Whether any changes were pulled */
+  hadChanges: boolean;
+  error?: string;
+}
+
+/**
+ * Detect the main branch name from the remote.
+ * Uses refs/remotes/origin/HEAD, falling back to main/master.
+ * Reuses the same logic as detectBaseBranch from pull-request.ts.
+ */
+export function detectMainBranch(cwd?: string): string | null {
+  // Try to find the default branch from the remote
+  try {
+    const output = execSync('git symbolic-ref refs/remotes/origin/HEAD', {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+      ...(cwd ? { cwd } : {}),
+    }).trim();
+    // Output is like "refs/remotes/origin/main"
+    const parts = output.split('/');
+    return parts[parts.length - 1] ?? null;
+  } catch {
+    // Fallback: check for common branch names
+  }
+
+  // Try common default branches
+  for (const branch of ['main', 'master']) {
+    try {
+      execSync(`git rev-parse --verify "refs/heads/${branch}"`, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        ...(cwd ? { cwd } : {}),
+      });
+      return branch;
+    } catch {
+      // Try next
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Pull the main branch from remote before worktree creation.
+ * Uses fetch + merge --ff-only to safely update the main branch.
+ * This ensures the worktree is created from the latest remote state.
+ *
+ * Only pulls if currently on the main branch or if the main branch exists.
+ * Fails gracefully if there are conflicts or the branch has diverged.
+ *
+ * @param cwd - The directory to run git commands in (defaults to current directory)
+ */
+export function pullMainBranch(cwd?: string): SyncMainBranchResult {
+  const mainBranch = detectMainBranch(cwd);
+
+  if (!mainBranch) {
+    return {
+      success: false,
+      mainBranch: null,
+      hadChanges: false,
+      error: 'Could not detect main branch (no origin/HEAD or main/master found)',
+    };
+  }
+
+  // Get current branch to check if we need to switch
+  const currentBranch = getCurrentBranch();
+
+  // If not on main, we need to fetch and update the main branch ref
+  // without checking it out (to avoid disrupting the user's work)
+  if (currentBranch !== mainBranch) {
+    // Fetch the main branch from origin
+    try {
+      execSync(`git fetch origin ${mainBranch}:${mainBranch}`, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        ...(cwd ? { cwd } : {}),
+      });
+      logger.debug(`Fetched ${mainBranch} from origin`);
+      return {
+        success: true,
+        mainBranch,
+        hadChanges: true, // We fetched updates (may or may not have actual changes)
+      };
+    } catch (error) {
+      // This can fail if the local main has diverged from remote
+      // Try a simple fetch without updating the local ref
+      try {
+        execSync(`git fetch origin ${mainBranch}`, {
+          encoding: 'utf-8',
+          stdio: 'pipe',
+          ...(cwd ? { cwd } : {}),
+        });
+        logger.debug(`Fetched origin/${mainBranch} (local ${mainBranch} diverged, not updated)`);
+        return {
+          success: true,
+          mainBranch,
+          hadChanges: false,
+          error: `Local ${mainBranch} has diverged from origin, not updated`,
+        };
+      } catch (fetchError) {
+        const msg = fetchError instanceof Error ? fetchError.message : String(fetchError);
+        return {
+          success: false,
+          mainBranch,
+          hadChanges: false,
+          error: `Failed to fetch ${mainBranch}: ${msg}`,
+        };
+      }
+    }
+  }
+
+  // Currently on main branch - can do a regular pull with ff-only
+  // First, check for uncommitted changes that would block the pull
+  try {
+    const status = execSync('git status --porcelain', {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+      ...(cwd ? { cwd } : {}),
+    }).trim();
+
+    if (status) {
+      return {
+        success: false,
+        mainBranch,
+        hadChanges: false,
+        error: `Cannot pull ${mainBranch}: uncommitted changes in working directory`,
+      };
+    }
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      mainBranch,
+      hadChanges: false,
+      error: `Failed to check git status: ${msg}`,
+    };
+  }
+
+  // Fetch and merge with ff-only
+  try {
+    execSync(`git fetch origin ${mainBranch}`, {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+      ...(cwd ? { cwd } : {}),
+    });
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      mainBranch,
+      hadChanges: false,
+      error: `Failed to fetch from origin: ${msg}`,
+    };
+  }
+
+  try {
+    const output = execSync(`git merge --ff-only origin/${mainBranch}`, {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+      ...(cwd ? { cwd } : {}),
+    });
+    const hadChanges = !output.includes('Already up to date');
+    return {
+      success: true,
+      mainBranch,
+      hadChanges,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      mainBranch,
+      hadChanges: false,
+      error: `Cannot fast-forward ${mainBranch}: ${msg.includes('Not possible to fast-forward') ? 'branch has diverged from origin' : msg}`,
+    };
+  }
+}
+
+/**
+ * Push the main branch to remote before PR creation.
+ * Ensures the PR base is up to date.
+ *
+ * @param cwd - The directory to run git commands in (defaults to current directory)
+ */
+export function pushMainBranch(cwd?: string): SyncMainBranchResult {
+  const mainBranch = detectMainBranch(cwd);
+
+  if (!mainBranch) {
+    return {
+      success: false,
+      mainBranch: null,
+      hadChanges: false,
+      error: 'Could not detect main branch (no origin/HEAD or main/master found)',
+    };
+  }
+
+  try {
+    execSync(`git push origin ${mainBranch}`, {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+      ...(cwd ? { cwd } : {}),
+    });
+    return {
+      success: true,
+      mainBranch,
+      hadChanges: true,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    // Check if it's just "already up to date"
+    if (msg.includes('Everything up-to-date')) {
+      return {
+        success: true,
+        mainBranch,
+        hadChanges: false,
+      };
+    }
+    return {
+      success: false,
+      mainBranch,
+      hadChanges: false,
+      error: `Failed to push ${mainBranch}: ${msg}`,
+    };
+  }
+}

package/src/prompts/amend.ts

@@ -135,9 +135,11 @@ After interviewing the user about all NEW tasks, create plan files starting from
 - ${projectPath}/plans/${encodeTaskId(nextTaskNumber + 1)}-task-name.md
 - etc.
 
-Each plan file should follow this structure:
+Each plan file MUST have Obsidian-style frontmatter at the top, before the \`# Task:\` heading. The frontmatter format uses only a closing \`---\` delimiter (no opening delimiter):
 
 \`\`\`markdown
+effort: medium
+---
 # Task: [Task Name]
 
 ## Objective
@@ -175,6 +177,23 @@ Each plan file should follow this structure:
 [Reference to existing task outcomes if relevant]
 \`\`\`
 
+### Frontmatter Requirements
+
+The \`effort\` field is REQUIRED in every plan file. It indicates task complexity and determines which Claude 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: ...
+\`\`\`
+
+This is rarely needed — prefer using the \`effort\` label so the user's config controls the actual model used.
+
 ### Step 5: Confirm Completion
 
 After creating all new plan files:
@@ -201,19 +220,15 @@ Planning complete! To exit this session and run your tasks:
 7. Specify task dependencies using the ## Dependencies section with task IDs only (e.g., "01, 02")
 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
 
 ## Plan Output Style
 
-**CRITICAL**: Plans should be HIGH-LEVEL and CONCEPTUAL:
-- Describe WHAT needs to be done, not HOW to code it
-- Focus on architecture, data flow, and component interactions
-- NO code snippets or implementation details in plans
-- File paths ARE acceptable when referencing:
-  - Existing project files to modify
-  - Previous plan/outcome files for context
-  - Project structure and directories
-- Let the executing agent decide implementation specifics
-- Plans guide the work; they don't prescribe exact code`;
+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`;
 
   const userMessage = `I want to add the following new tasks to this project:
 

package/src/prompts/config-docs.md

@@ -37,24 +37,36 @@ Controls which Claude model is used for each scenario. Values can be a short ali
 | Key | Default | Description |
 |-----|---------|-------------|
 | `models.plan` | `"opus"` | Model used for planning sessions (`raf plan`) |
-| `models.execute` | `"opus"` | Model used for task execution (`raf do`) |
+| `models.execute` | `"opus"` | Ceiling model for task execution (`raf do`). Per-task models from effort frontmatter are capped to this tier. Also used as the fallback when a plan has no effort frontmatter. |
 | `models.nameGeneration` | `"sonnet"` | Model used for generating project names |
 | `models.failureAnalysis` | `"haiku"` | Model used for analyzing task failures |
 | `models.prGeneration` | `"sonnet"` | Model used for generating PR titles and descriptions |
 | `models.config` | `"sonnet"` | Model used for the interactive config editor (`raf config`) |
 
-### `effort` — Claude Effort Level
+### `effortMapping` — Task Effort to Model Mapping
 
-Controls the effort level passed to Claude for each scenario. All values must be one of: `"low"`, `"medium"`, `"high"`.
+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.
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `effort.plan` | `"high"` | Effort level for planning sessions |
-| `effort.execute` | `"medium"` | Effort level for task execution |
-| `effort.nameGeneration` | `"low"` | Effort level for project name generation |
-| `effort.failureAnalysis` | `"low"` | Effort level for failure analysis |
-| `effort.prGeneration` | `"medium"` | Effort level for PR generation |
-| `effort.config` | `"medium"` | Effort level for config editing sessions |
+| `effortMapping.low` | `"haiku"` | Model for low-complexity tasks |
+| `effortMapping.medium` | `"sonnet"` | Model for medium-complexity tasks |
+| `effortMapping.high` | `"opus"` | Model for high-complexity tasks |
+
+Values must be a short alias (`"sonnet"`, `"haiku"`, `"opus"`) or a full model ID.
+
+**Interaction with `models.execute`**: The `models.execute` value acts as a ceiling. If a task's effort maps to a more expensive model than the ceiling, the ceiling model is used instead. This gives users budget control while allowing tasks to use cheaper models when appropriate.
+
+Example:
+```json
+{
+  "models": { "execute": "sonnet" },
+  "effortMapping": { "low": "haiku", "medium": "sonnet", "high": "opus" }
+}
+```
+- Task with `effort: low` → haiku (under ceiling)
+- Task with `effort: medium` → sonnet (at ceiling)
+- Task with `effort: high` → sonnet (capped to ceiling, not opus)
 
 ### `timeout` — Task Timeout
 
@@ -80,6 +92,18 @@ Controls the effort level passed to Claude for each scenario. All values must be
 - **Default**: `false`
 - **Description**: When `true`, `raf plan` and `raf do` default to worktree mode (isolated git worktree). Can be overridden per-command with `--worktree` flag.
 
+### `syncMainBranch` — Sync Main Branch with Remote
+
+- **Type**: boolean
+- **Default**: `true`
+- **Description**: When `true`, RAF automatically syncs the main branch with the remote before worktree operations:
+  - **Before worktree creation** (`raf plan --worktree`): Pulls the main branch from remote to ensure the worktree starts from the latest code
+  - **Before PR creation** (post-execution "Create PR" action): Pushes the main branch to remote so the PR base is up to date
+
+The main branch is auto-detected from `refs/remotes/origin/HEAD`, falling back to `main` or `master` if not set.
+
+Failures in sync operations produce warnings but don't block the workflow. For example, if the local main branch has diverged from remote, the sync will warn and continue.
+
 ### `commitFormat` — Commit Message Templates
 
 Controls the format of git commit messages. Templates use `{placeholder}` syntax for variable substitution.
@@ -147,25 +171,62 @@ Example override:
 
 Only specify the fields you want to change — unset fields keep their defaults.
 
-### `claudeCommand` — Claude CLI Path
+### `display` — Token Summary Display Options
+
+Controls what information is shown in token usage summaries after tasks and in the grand total.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `display.showRateLimitEstimate` | `true` | Show estimated 5h rate limit window percentage (e.g., `~42% of 5h window`) |
+| `display.showCacheTokens` | `true` | Show cache read/create token counts in summaries |
+
+Example:
+
+```json
+{
+  "display": {
+    "showRateLimitEstimate": false,
+    "showCacheTokens": true
+  }
+}
+```
+
+### `rateLimitWindow` — Rate Limit Configuration
+
+Controls the rate limit estimation calculation.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `rateLimitWindow.sonnetTokenCap` | `88000` | The Sonnet-equivalent token cap for the 5-hour window. All token usage is normalized to Sonnet-equivalent tokens using pricing ratios. |
+
+The 5h window percentage is calculated as: `(estimatedCost / sonnetCostPerToken) / sonnetTokenCap * 100`
 
-- **Type**: string (non-empty)
-- **Default**: `"claude"`
-- **Description**: The command or path used to invoke the Claude CLI. Change this if `claude` is not on your PATH or you want to use a wrapper script.
+Where `sonnetCostPerToken` is derived from the configured Sonnet pricing. Heavier models (Opus) consume the window faster than lighter ones (Haiku) in proportion to their API pricing ratios.
+
+Example:
+
+```json
+{
+  "rateLimitWindow": {
+    "sonnetTokenCap": 100000
+  }
+}
+```
 
 ## Validation Rules
 
 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** 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"`).
-- **Effort values** must be exactly `"low"`, `"medium"`, or `"high"` (case-sensitive).
+- **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"`).
+- **`effortMapping` keys** must be `"low"`, `"medium"`, or `"high"`.
 - **`timeout`** must be a positive finite number.
 - **`maxRetries`** must be a non-negative integer.
-- **`autoCommit`** and **`worktree`** must be booleans.
+- **`autoCommit`**, **`worktree`**, and **`syncMainBranch`** must be booleans.
 - **`commitFormat` values** must be strings.
-- **`claudeCommand`** must be a non-empty string.
 - **`pricing`** categories must be `"opus"`, `"sonnet"`, or `"haiku"`. Each field must be a non-negative number.
+- **`display` values** (`showRateLimitEstimate`, `showCacheTokens`) must be booleans.
+- **`rateLimitWindow.sonnetTokenCap`** must be a positive number.
 - The config file must be valid JSON containing an object (not an array or primitive).
 
 ## CLI Precedence
@@ -199,14 +260,11 @@ Uses Sonnet instead of Opus for task execution. Everything else stays at default
     "plan": "sonnet",
     "execute": "sonnet"
   },
-  "effort": {
-    "plan": "medium"
-  },
   "worktree": true
 }
 ```
 
-Uses Sonnet for both planning and execution, reduces planning effort, and defaults to worktree mode.
+Uses Sonnet for planning and caps task execution at Sonnet (tasks with `effort: high` will use Sonnet instead of Opus). Defaults to worktree mode.
 
 ### Full — All Settings Explicit
 
@@ -220,29 +278,33 @@ Uses Sonnet for both planning and execution, reduces planning effort, and defaul
     "prGeneration": "sonnet",
     "config": "sonnet"
   },
-  "effort": {
-    "plan": "high",
-    "execute": "medium",
-    "nameGeneration": "low",
-    "failureAnalysis": "low",
-    "prGeneration": "medium",
-    "config": "medium"
+  "effortMapping": {
+    "low": "haiku",
+    "medium": "sonnet",
+    "high": "opus"
   },
   "timeout": 60,
   "maxRetries": 3,
   "autoCommit": true,
   "worktree": false,
+  "syncMainBranch": true,
   "commitFormat": {
     "task": "{prefix}[{projectId}:{taskId}] {description}",
     "plan": "{prefix}[{projectId}] Plan: {projectName}",
     "amend": "{prefix}[{projectId}] Amend: {projectName}",
     "prefix": "RAF"
   },
-  "claudeCommand": "claude",
   "pricing": {
     "opus": { "inputPerMTok": 15, "outputPerMTok": 75, "cacheReadPerMTok": 1.5, "cacheCreatePerMTok": 18.75 },
     "sonnet": { "inputPerMTok": 3, "outputPerMTok": 15, "cacheReadPerMTok": 0.3, "cacheCreatePerMTok": 3.75 },
     "haiku": { "inputPerMTok": 1, "outputPerMTok": 5, "cacheReadPerMTok": 0.1, "cacheCreatePerMTok": 1.25 }
+  },
+  "display": {
+    "showRateLimitEstimate": true,
+    "showCacheTokens": true
+  },
+  "rateLimitWindow": {
+    "sonnetTokenCap": 88000
   }
 }
 ```

package/src/prompts/planning.ts

@@ -80,9 +80,11 @@ After interviewing the user about all tasks, create plan files in the plans fold
 - ${projectPath}/plans/02-task-name.md
 - etc.
 
-Each plan file should follow this structure:
+Each plan file MUST have Obsidian-style frontmatter at the top, before the \`# Task:\` heading. The frontmatter format uses only a closing \`---\` delimiter (no opening delimiter):
 
 \`\`\`markdown
+effort: medium
+---
 # Task: [Task Name]
 
 ## Objective
@@ -117,6 +119,23 @@ Each plan file should follow this structure:
 [Any additional context, warnings, or considerations]
 \`\`\`
 
+### Frontmatter Requirements
+
+The \`effort\` field is REQUIRED in every plan file. It indicates task complexity and determines which Claude 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: ...
+\`\`\`
+
+This is rarely needed — prefer using the \`effort\` label so the user's config controls the actual model used.
+
 ### Step 4: Infer Task Dependencies
 
 For each task, analyze which other tasks must complete successfully before it can begin. Add a \`## Dependencies\` section to plan files that have prerequisites.
@@ -166,19 +185,15 @@ Planning complete! To exit this session and run your tasks:
 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
 
-**CRITICAL**: Plans should be HIGH-LEVEL and CONCEPTUAL:
-- Describe WHAT needs to be done, not HOW to code it
-- Focus on architecture, data flow, and component interactions
-- NO code snippets or implementation details in plans
-- File paths ARE acceptable when referencing:
-  - Existing project files to modify
-  - Previous plan/outcome files for context
-  - Project structure and directories
-- Let the executing agent decide implementation specifics
-- Plans guide the work; they don't prescribe exact code`;
+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`;
 
   const userMessage = `Here is my project description: