codemini-cli 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemini-cli",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Coding CLI optimized for small-model workflows and Windows PowerShell",
   "keywords": [
     "cli",

package/skills/superpowers-lite/SKILL.md

@@ -18,24 +18,35 @@ Routing:
 - execute directly
 - do not force brainstorming
 
-2. If the goal is clear but there are multiple reasonable implementation paths:
+2. If the task is a non-trivial implementation that likely needs codebase exploration, touches multiple areas, changes shared behavior, or needs explicit review/testing before coding:
+- prefer `auto plan`
+- inspect first, then present a short implementation plan for approval
+- do not jump straight into coding
+- do not use `brainstorm` as a substitute for implementation planning
+
+3. If the goal is clear but there are multiple reasonable implementation paths and the missing piece is mainly user preference, tradeoff choice, or one key constraint:
 - use `brainstorm`
 - ask exactly one clarifying question first
 - do not give options, recommendations, or a tentative solution in the same response
 - stop after the question and wait for the user's answer before continuing
 
-3. If the request is still missing a key constraint or success condition:
+4. If the request is still missing a key constraint or success condition:
 - ask exactly one clarifying question
 - do not give options yet
 - do not write code yet
 - stop after the question and wait for the user's answer
 
-4. If the request is greenfield and underspecified, such as "build a page", "make a site", "generate an app", or similar:
+5. If the request is greenfield and underspecified, such as "build a page", "make a site", "generate an app", or similar:
 - treat it as missing key constraints by default
 - ask one high-value question before coding
 - do not assume features, storage model, or scope unless the user already gave them
 - stop after the question and wait for the user's answer
 
+Decision boundary:
+- Use `brainstorm` when one focused user answer will determine the direction.
+- Use `auto plan` when the task is already implementation-shaped but the work is large enough that you should explore first and get sign-off on the plan.
+- If both could apply, prefer `brainstorm` first when the core uncertainty is user intent; prefer `auto plan` first when the core uncertainty is codebase impact and execution shape.
+
 Tool order:
 - prefer `grep` first for content search and candidate discovery
 - use `read` to inspect the smallest useful code block
@@ -74,7 +85,7 @@ Run the relevant test, check, or command before saying work is fixed or complete
 Default workflow:
 - Search with `grep`
 - Inspect local context with `read`
-- If the request is unclear, first decide: ask one question, brainstorm, or proceed
+- If the request is unclear, first decide: ask one question, brainstorm, auto plan, or proceed
 - Plan the next smallest step
 - Delegate if the work is independent
 - Edit with `edit`

package/src/cli.js

@@ -4,7 +4,7 @@ import { handleConfig } from './commands/config.js';
 import { handleDoctor } from './commands/doctor.js';
 import { handleSkill } from './commands/skill.js';
 
-const VERSION = '0.2.3';
+const VERSION = '0.2.4';
 
 function printHelp() {
   console.log(`codemini ${VERSION}

package/src/core/agent-loop.js

@@ -450,7 +450,16 @@ export async function runAgentLoop({
     }
 
     if (executionMode === 'plan') {
-      finalText = `${assistantText || ''}\n\n[plan mode] ${toolCalls.length} tool call(s) were planned but not executed.`;
+      const plannedLines = callsToPlanSummary(toolCalls);
+      finalText = [
+        assistantText || '',
+        '',
+        `[plan mode] ${toolCalls.length} tool call(s) were planned but not executed.`,
+        plannedLines.length > 0 ? 'Planned exploration:' : '',
+        ...plannedLines
+      ]
+        .filter(Boolean)
+        .join('\n');
       return { text: finalText.trim(), messages, steps: step + 1 };
     }
 
@@ -598,3 +607,12 @@ export async function runAgentLoop({
     steps: maxSteps
   };
 }
+
+function callsToPlanSummary(toolCalls = []) {
+  return toolCalls
+    .slice(0, 8)
+    .map((call) => {
+      const args = safeJsonParse(call?.arguments);
+      return `- ${formatToolDisplayName(normalizeToolCallName(call?.name), args)}`;
+    });
+}

package/src/core/chat-runtime.js

@@ -434,11 +434,15 @@ function buildGoalRequirementPacket(goal, role) {
 
 function buildAutoPlanPlannerGuidance() {
   return [
+    'Design a short implementation plan for a small model.',
     'Auto-plan planning rules:',
+    '- Start with a discovery or clarification step when the current implementation is not yet verified.',
     '- If the goal still leaves room for multiple approaches, choose one practical direction before planning execution.',
     '- Prefer the smallest local approach that satisfies the goal.',
     '- Do not output multiple alternative branches in the final plan.',
-    '- Turn the chosen direction into concrete execution steps for coder, reviewer, and tester.',
+    '- Do not assume implementation should begin before the plan is coherent.',
+    '- Turn the chosen direction into concrete execution steps for planner, coder, reviewer, and tester.',
+    '- Prefer 3-5 steps total unless the task is clearly larger.',
     '- Keep the plan ordered, implementation-oriented, and easy for small sub-agents to follow.'
   ].join('\n');
 }
@@ -594,8 +598,79 @@ function selectAutoSkillNames(text = '') {
   return selected;
 }
 
+function shouldAutoPlan(text = '') {
+  const input = String(text || '').trim();
+  if (!input) return false;
+
+  const lower = input.toLowerCase();
+  const explicitPlanning =
+    /(\/plan\b|plan first|make a plan|implementation plan|先做计划|先出方案|先规划|先计划)/i.test(lower);
+  if (explicitPlanning) return false;
+
+  const simpleSkip =
+    /(typo|readme|console\.log|log this|rename\s+\w+|one line|small tweak|tiny fix|格式化|拼写|注释|文案|小改|微调)/i.test(
+      lower
+    );
+  if (simpleSkip) return false;
+
+  const discussionFirst =
+    /(brainstorm|头脑风暴|方案|思路|怎么做|如何做|which (?:approach|option|way)|best way|trade-?off|not sure|unsure|unclear|whether it should|要不要|不确定|先别写|先不要写|先讨论|先想一下)/i.test(
+      lower
+    );
+  if (discussionFirst) return false;
+
+  const implementationRequest =
+    /\b(add|build|create|implement|support|introduce|design|refactor|rework|migrate|change|update|rewrite|restructure)\b/i.test(
+      lower
+    ) ||
+    /(新增|增加|实现|支持|设计|重构|改造|迁移|调整|重写|重做)/i.test(lower);
+  if (!implementationRequest) return false;
+
+  const nonTrivialSignals =
+    /\b(auth|authentication|workflow|flow|system|architecture|api|endpoint|state management|cache|caching|database|migration|service|shared helper|helper module|refactor|multi[- ]file|across files|with tests?|and tests?|with validation|error handling)\b/i.test(
+      lower
+    ) ||
+    /(架构|流程|系统|接口|缓存|数据库|迁移|服务|共享|模块|跨文件|测试|校验|错误处理)/i.test(lower);
+
+  const multipleActions = /\b(and|plus|also|while|along with)\b/i.test(lower) || /[，、；;].+/.test(input);
+  const singleFileScoped =
+    /\b(?:in|inside|within|only in)\s+[-_/.\w]+\.(?:[cm]?[jt]sx?|py|go|rb|java|rs|php|md)\b/i.test(lower) ||
+    /\b(?:src|app|lib|tests?)\/[-_/.\w]+\.(?:[cm]?[jt]sx?|py|go|rb|java|rs|php|md)\b/i.test(lower);
+
+  if (singleFileScoped && !multipleActions) return false;
+  if (singleFileScoped && !nonTrivialSignals) return false;
+
+  return nonTrivialSignals || (multipleActions && !singleFileScoped);
+}
+
+function classifyAutoRoute(text = '') {
+  const selectedSkills = selectAutoSkillNames(text);
+  const hasBrainstorm = selectedSkills.includes('brainstorm');
+  if (hasBrainstorm) {
+    return {
+      mode: 'brainstorm',
+      autoPlan: false,
+      selectedSkills
+    };
+  }
+
+  if (shouldAutoPlan(text)) {
+    return {
+      mode: 'auto_plan',
+      autoPlan: true,
+      selectedSkills: ['superpowers-lite']
+    };
+  }
+
+  return {
+    mode: 'direct',
+    autoPlan: false,
+    selectedSkills
+  };
+}
+
 function buildAutoSkillSystemPrompt(baseSystemPrompt, commands, config, text) {
-  const selected = selectAutoSkillNames(text).filter((name) => isSkillEnabled(config, name));
+  const selected = classifyAutoRoute(text).selectedSkills.filter((name) => isSkillEnabled(config, name));
   if (selected.length === 0) return baseSystemPrompt;
 
   const blocks = [];
@@ -662,6 +737,74 @@ function normalizeAutoPlan(parsed, goal) {
   return enforceAutoPlanGuardrailSteps(basePlan, goal);
 }
 
+function summarizeGoalForStepTitle(goal, fallback = 'requested change') {
+  const text = String(goal || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!text) return fallback;
+  const compact = text.length > 72 ? `${text.slice(0, 69).trimEnd()}...` : text;
+  return compact;
+}
+
+function buildFallbackAutoPlan(goal) {
+  const requirements = deriveGoalRequirements(goal);
+  const lightweightGoal = isLightweightAutoPlanGoal(goal, requirements);
+  const focus = summarizeGoalForStepTitle(goal);
+  const summary =
+    requirements.length > 0
+      ? `Auto fallback plan for: ${requirements.join('; ')}`
+      : `Auto fallback plan for: ${goal}`;
+
+  if (lightweightGoal) {
+    return {
+      summary,
+      steps: [
+        {
+          title: `Implement ${focus}`,
+          role: 'coder',
+          task: `Implement the requested change for: ${goal}. Follow the acceptance checklist and keep the change narrowly scoped.`
+        },
+        {
+          title: 'Verify the change',
+          role: 'tester',
+          task: `Verify the completed change for: ${goal}. Run the most relevant focused checks available and report concrete evidence plus anything still unverified.`
+        }
+      ]
+    };
+  }
+
+  return {
+    summary,
+    steps: [
+      {
+        title: 'Inspect the target area',
+        role: 'planner',
+        task: `Inspect the existing code paths, affected files, and current behavior for: ${goal}. Identify constraints, dependencies, and any compatibility risks before implementation.`
+      },
+      {
+        title: `Implement ${focus}`,
+        role: 'coder',
+        task: `Implement the requested changes for: ${goal}. Keep the behavior aligned with the acceptance checklist and preserve existing external behavior unless the goal explicitly changes it.`
+      },
+      {
+        title: 'Update or add focused verification',
+        role: 'coder',
+        task: `Add or update the most relevant tests and focused verification coverage for: ${goal}. Prefer narrow checks tied to the changed files and flows.`
+      },
+      {
+        title: 'Review for regressions and gaps',
+        role: 'reviewer',
+        task: `Review the completed work for: ${goal}. Start with the changed files, then check regressions, risky assumptions, backward compatibility, and missing edge cases.`
+      },
+      {
+        title: 'Verify the changed flows',
+        role: 'tester',
+        task: `Verify the completed work for: ${goal}. Run the most relevant checks available, report concrete evidence, and call out anything still not verified.`
+      }
+    ]
+  };
+}
+
 function enforceAutoPlanGuardrailSteps(plan, goal) {
   const source = Array.isArray(plan?.steps) ? plan.steps : [];
   const requirements = deriveGoalRequirements(goal);
@@ -770,6 +913,7 @@ function buildAutoPlanSystemSummary(auto) {
     `File: ${auto.filePath}`,
     `Plan Summary: ${auto.summary || '-'}`,
     `Final Summary: ${auto.finalSummary || auto.summary || '-'}`,
+    `Approval: ${auto.approvalStatus || 'not_required'}`,
     `Steps: ${auto.steps.length} total`,
     `Completed: ${auto.completedCount}`,
     `Warnings: ${auto.warningCount}`,
@@ -781,6 +925,9 @@ function buildAutoPlanSystemSummary(auto) {
   if (auto.failedTitles?.length) {
     lines.push(`Failed steps: ${auto.failedTitles.slice(0, 5).join(', ')}`);
   }
+  if (auto.approvalStatus === 'pending') {
+    lines.push('Next: review the plan summary, then use /plan approve to start implementation or /plan stay to keep planning.');
+  }
   return lines.join('\n');
 }
 
@@ -1142,6 +1289,11 @@ function buildRuntimeStateSnapshot({ currentSession, config, model, executionMod
       value: contextUsagePct,
       enumerable: false,
       writable: false
+    },
+    pendingPlanApproval: {
+      value: currentSession?.planState?.status === 'pending_approval',
+      enumerable: false,
+      writable: false
     }
   });
   return snapshot;
@@ -1164,6 +1316,61 @@ function stampedMessage(role, content, extra = {}) {
   };
 }
 
+function hasPendingPlanApproval(session) {
+  return session?.planState?.status === 'pending_approval';
+}
+
+function isApprovalText(text = '') {
+  const value = String(text || '').trim().toLowerCase();
+  if (!value) return false;
+  return /^(yes|y|ok|okay|approve|approved|continue|proceed|go ahead|start|开始|继续|可以|同意|批准|通过|按这个做)$/.test(value);
+}
+
+function isStayInPlanText(text = '') {
+  const value = String(text || '').trim().toLowerCase();
+  if (!value) return false;
+  return /^(stay|keep planning|keep in plan mode|not yet|wait|先别|先等等|继续计划|继续讨论|继续规划|暂不批准)$/.test(value);
+}
+
+function buildPendingPlanApprovalMessage(planState) {
+  const lines = [
+    'Plan approval is still pending.',
+    `Goal: ${planState?.goal || '-'}`,
+    `Plan file: ${planState?.filePath || '-'}`,
+    `Summary: ${planState?.finalSummary || planState?.summary || '-'}`,
+    'Use /plan approve to start implementation, or /plan stay to keep refining the plan first.'
+  ];
+  return lines.join('\n');
+}
+
+function buildApprovedPlanExecutionPrompt(planState, approvalText = '') {
+  const lines = [
+    'Approved implementation plan:',
+    `Original goal: ${planState?.goal || '-'}`,
+    `Plan file: ${planState?.filePath || '-'}`,
+    `Plan summary: ${planState?.summary || '-'}`,
+    `Final planning summary: ${planState?.finalSummary || planState?.summary || '-'}`,
+    `User approval: ${String(approvalText || '').trim() || 'approved'}`,
+    Array.isArray(planState?.steps) && planState.steps.length > 0 ? 'Planned steps:' : '',
+    ...(Array.isArray(planState?.steps)
+      ? planState.steps.slice(0, 8).map((step, index) => `${index + 1}. [${step.role}] ${step.title} :: ${step.task}`)
+      : []),
+    'Proceed with implementation now.',
+    'Follow the approved direction unless a blocking contradiction appears.',
+    'Output rules for this implementation phase:',
+    '- Be concise and practical.',
+    '- Do not celebrate, praise, or use emojis.',
+    '- Do not restate the full plan back to the user.',
+    '- If the work is already done, say so briefly and cite the verification evidence.',
+    '- After implementation or verification, prefer a short result summary in 3-6 lines.',
+    '- If the work is complete, use this exact structure:',
+    'Status: <done|partial|blocked>',
+    'Verified: <tests, checks, or evidence>',
+    'Next: <none or the single next action>'
+  ];
+  return lines.join('\n');
+}
+
 async function resolveSpecPath(rawArg = '', sessionId = '') {
   const input = String(rawArg || '').trim();
   const roots = [
@@ -1493,7 +1700,6 @@ async function runSubAgentTask({
 
 async function buildAutoPlanAndRun({
   goal,
-  session,
   config,
   model,
   systemPrompt,
@@ -1527,8 +1733,12 @@ async function buildAutoPlanAndRun({
           role: 'user',
           content: [
             'Create an execution plan and assign best sub-agent role for each step.',
+            'Return strict JSON only with shape {"summary":"...","steps":[{"title":"...","role":"planner|coder|reviewer|tester","task":"..."}]}. No markdown.',
+            'Always include final reviewer and tester steps unless the task is explicitly tiny.',
             requirementPacket,
-            'The final steps must include review and testing/verification unless the goal is a tiny single-change task, in which case you may keep only one implementation step plus one testing/verification step.'
+            'The first step should usually inspect or clarify the target area before implementation.',
+            'The final steps must include review and testing/verification unless the goal is a tiny single-change task, in which case you may keep only one implementation step plus one testing/verification step.',
+            'Prefer 3-5 steps total.'
           ]
             .filter(Boolean)
             .join('\n')
@@ -1541,89 +1751,22 @@ async function buildAutoPlanAndRun({
     autoPlan = normalizeAutoPlan(parsed, goal);
   } catch (err) {
     planningError = String(err?.message || err || 'planning failed');
+    autoPlan = buildFallbackAutoPlan(goal);
   }
 
-  const runItems = [];
-  const totalPlanSteps = autoPlan.steps.length + 1;
   for (let i = 0; i < autoPlan.steps.length; i += 1) {
     const step = autoPlan.steps[i];
     if (onAgentEvent) {
       onAgentEvent({
         type: 'assistant:delta',
-        text: `\n[plan] Step ${i + 1}/${totalPlanSteps} -> ${step.role}: ${step.title}\n`
-      });
-    }
-    try {
-      const stepResult = await runSubAgentTask({
-        role: step.role,
-        task: step.task,
-        goal,
-        priorSteps: runItems,
-        parentSession: session,
-        config,
-        model,
-        systemPrompt,
-        onAgentEvent,
-        extraRolePrompt: buildAutoPlanExecutionGuidance(step.role)
-      });
-      const outputLooksSuccessful = looksLikeSuccessfulStepOutput(stepResult.text);
-      const outputHasFailureSignals = stepOutputHasFailureSignals(step.role, stepResult.text);
-      const warningParts = [];
-      if (stepResult.blockedCount > 0) warningParts.push(`${stepResult.blockedCount} blocked tool call(s)`);
-      if (stepResult.toolErrorCount > 0) warningParts.push(`${stepResult.toolErrorCount} tool error(s)`);
-      const warning = warningParts.length > 0 ? `sub-agent recovered after ${warningParts.join(', ')}` : '';
-      const failed =
-        stepResult.hasErrorLine ||
-        outputHasFailureSignals ||
-        (!outputLooksSuccessful && (stepResult.blockedCount > 0 || stepResult.toolErrorCount > 0));
-      let error = '';
-      if (stepResult.hasErrorLine) {
-        error = 'sub-agent output contains error line(s)';
-      } else if (outputHasFailureSignals) {
-        error = 'sub-agent output reports unmet requirements or failed verification';
-      } else if (failed && stepResult.blockedCount > 0) {
-        error = `sub-agent ended with ${stepResult.blockedCount} blocked tool call(s)`;
-      } else if (failed && stepResult.toolErrorCount > 0) {
-        error = `sub-agent ended with ${stepResult.toolErrorCount} tool error(s)`;
-      }
-      runItems.push({
-        ...step,
-        output: stepResult.text,
-        error,
-        warning,
-        failed,
-        artifactPaths: stepResult.artifactPaths || []
-      });
-    } catch (err) {
-      runItems.push({
-        ...step,
-        output: '',
-        error: String(err?.message || err || 'sub-agent step failed'),
-        warning: '',
-        failed: true
+        text: `\n[plan] Step ${i + 1}/${autoPlan.steps.length} -> ${step.role}: ${step.title}\n`
       });
     }
   }
 
-  const failedItems = runItems.filter((s) => s.failed || s.error);
-  const warningItems = runItems.filter((s) => !s.failed && s.warning);
-  const completedItems = runItems.filter((s) => !s.failed);
-
-  if (onAgentEvent) {
-    onAgentEvent({
-      type: 'assistant:delta',
-      text: `\n[plan] Step ${totalPlanSteps}/${totalPlanSteps} -> summarizer: Final summary\n`
-    });
-  }
-  const finalSummary = await buildAutoPlanFinalSummary({
-    goal,
-    autoPlan,
-    runItems,
-    planningError,
-    config,
-    model,
-    systemPrompt
-  });
+  const finalSummary = planningError
+    ? `Plan created with fallback guidance because planning hit an error: ${planningError}`
+    : 'Plan created and waiting for approval before implementation.';
 
   const lines = [];
   lines.push(`# Auto Plan: ${goal}`);
@@ -1644,25 +1787,8 @@ async function buildAutoPlanAndRun({
     lines.push(`   - task: ${s.task}`);
   });
   lines.push('');
-  lines.push('## Sub-Agent Outputs');
-  runItems.forEach((s, idx) => {
-    lines.push(`### ${idx + 1}. [${s.role}] ${s.title}`);
-    if (s.error) {
-      lines.push(`Error: ${s.error}`);
-      if (s.output) {
-        lines.push('');
-        lines.push(s.output);
-      }
-      lines.push('');
-      return;
-    }
-    if (s.warning) {
-      lines.push(`Note: ${s.warning}`);
-      lines.push('');
-    }
-    lines.push(s.output || '(empty)');
-    lines.push('');
-  });
+  lines.push('## Approval');
+  lines.push('Pending user approval before implementation.');
 
   const filePath = await writeMarkdownInProjectDir(
     'plans',
@@ -1675,12 +1801,13 @@ async function buildAutoPlanAndRun({
     filePath,
     summary: autoPlan.summary,
     finalSummary,
+    approvalStatus: 'pending',
     steps: autoPlan.steps,
-    completedCount: completedItems.length,
-    warningCount: warningItems.length,
-    failedCount: failedItems.length,
-    warningTitles: warningItems.map((s) => `${s.role}:${s.title}`),
-    failedTitles: failedItems.map((s) => `${s.role}:${s.title}`)
+    completedCount: 0,
+    warningCount: planningError ? 1 : 0,
+    failedCount: 0,
+    warningTitles: planningError ? ['planner:fallback-plan'] : [],
+    failedTitles: []
   };
 }
 
@@ -1728,6 +1855,9 @@ export async function createChatRuntime({
   let config = initialConfig;
   const baseSystemPrompt = systemPrompt;
   let executionMode = config.execution?.mode || 'auto';
+  if (hasPendingPlanApproval(currentSession)) {
+    executionMode = 'plan';
+  }
   const commands = await loadCommandsAndSkills();
 
   // Set up tool result store under session directory
@@ -2372,6 +2502,16 @@ export async function createChatRuntime({
             onAgentEvent,
             sessionId: currentSession.id
           });
+          currentSession.planState = {
+            status: 'pending_approval',
+            source: 'auto',
+            goal,
+            filePath: auto.filePath,
+            summary: auto.summary || '',
+            finalSummary: auto.finalSummary || auto.summary || '',
+            steps: Array.isArray(auto.steps) ? auto.steps : []
+          };
+          executionMode = 'plan';
           const text = buildAutoPlanSystemSummary(auto);
           await persistLocalExchange(line, text);
           return {
@@ -2379,6 +2519,33 @@ export async function createChatRuntime({
             text
           };
         }
+        if (sub === 'approve') {
+          if (!hasPendingPlanApproval(currentSession)) {
+            return { type: 'system', text: 'No pending plan approval. Use /plan auto <goal> or /plan <goal> first.' };
+          }
+          const planState = { ...currentSession.planState };
+          const result = await askModel({
+            text: buildApprovedPlanExecutionPrompt(planState, '/plan approve'),
+            session: currentSession,
+            config,
+            model,
+            systemPrompt: activeReplySystemPrompt,
+            onAgentEvent,
+            executionMode: 'auto'
+          });
+          currentSession.planState = null;
+          executionMode = 'auto';
+          await saveSession(currentSession);
+          return { type: 'assistant', text: result.text };
+        }
+        if (sub === 'stay') {
+          if (!hasPendingPlanApproval(currentSession)) {
+            return { type: 'system', text: 'No pending plan approval.' };
+          }
+          const text = buildPendingPlanApprovalMessage(currentSession.planState);
+          await persistLocalExchange(line, text);
+          return { type: 'system', text };
+        }
         if (sub === 'from-spec') {
           const specArg = parsedInput.args.slice(1).join(' ').trim();
           const specPath = await resolveSpecPath(specArg, currentSession.id);
@@ -2499,6 +2666,9 @@ export async function createChatRuntime({
           const loaded = await loadSession(targetId);
           currentSession = loaded;
           setResultDir(path.join(getSessionsDir(), String(targetId)));
+          if (hasPendingPlanApproval(currentSession)) {
+            executionMode = 'plan';
+          }
           if (!historyIdCache.includes(targetId)) historyIdCache.unshift(targetId);
           historySessionCache = [
             { id: targetId, messageCount: Array.isArray(loaded.messages) ? loaded.messages.length : 0 },
@@ -2638,6 +2808,7 @@ export async function createChatRuntime({
               renderCommandPrompt(custom, []),
               'Explicit brainstorm mode:',
               '- Ask exactly one clarifying question first if any important uncertainty remains.',
+              '- Stop after the question and wait for the user\'s answer before continuing.',
               '- Do not inspect the repo or generate code unless the user explicitly asks for that.',
               '- If you recommend an option, present it as a suggested decision rather than a final choice for the user.',
               parsedInput.args.length > 0 ? `Current question:\n${parsedInput.args.join(' ')}` : ''
@@ -2676,6 +2847,34 @@ export async function createChatRuntime({
       return { type: 'assistant', text: result.text };
     }
 
+    if (hasPendingPlanApproval(currentSession)) {
+      if (isApprovalText(parsedInput.text)) {
+        const planState = { ...currentSession.planState };
+        const result = await askModel({
+          text: buildApprovedPlanExecutionPrompt(planState, parsedInput.text),
+          session: currentSession,
+          config,
+          model,
+          systemPrompt: activeReplySystemPrompt,
+          onAgentEvent,
+          executionMode: 'auto'
+        });
+        currentSession.planState = null;
+        executionMode = 'auto';
+        await saveSession(currentSession);
+        return { type: 'assistant', text: result.text };
+      }
+      if (isStayInPlanText(parsedInput.text)) {
+        const text = buildPendingPlanApprovalMessage(currentSession.planState);
+        await persistLocalExchange(line, text);
+        return { type: 'system', text };
+      }
+      return {
+        type: 'system',
+        text: buildPendingPlanApprovalMessage(currentSession.planState)
+      };
+    }
+
     if (compactState.autoEnabled) {
       const currentTokens = estimateMessagesTokens(currentSession.messages);
       const maxTokens = effectiveMaxContextTokens(config);
@@ -2703,7 +2902,33 @@ export async function createChatRuntime({
     }
 
     const expandedText = await expandFileMentions(parsedInput.text, process.cwd());
-    const selectedAutoSkills = selectAutoSkillNames(expandedText).filter((name) => isSkillEnabled(config, name));
+    const autoRoute = classifyAutoRoute(expandedText);
+    if (autoRoute.autoPlan) {
+      const auto = await buildAutoPlanAndRun({
+        goal: expandedText,
+        session: currentSession,
+        config,
+        model,
+        systemPrompt: activeBaseSystemPrompt,
+        onAgentEvent,
+        sessionId: currentSession.id
+      });
+      currentSession.planState = {
+        status: 'pending_approval',
+        source: 'auto',
+        goal: expandedText,
+        filePath: auto.filePath,
+        summary: auto.summary || '',
+        finalSummary: auto.finalSummary || auto.summary || '',
+        steps: Array.isArray(auto.steps) ? auto.steps : []
+      };
+      executionMode = 'plan';
+      const text = buildAutoPlanSystemSummary(auto);
+      await persistLocalExchange(line, text);
+      return { type: 'system', text };
+    }
+
+    const selectedAutoSkills = autoRoute.selectedSkills.filter((name) => isSkillEnabled(config, name));
     if (selectedAutoSkills.length > 0 && onAgentEvent) {
       onAgentEvent({
         type: 'skill:auto',

package/src/core/session-store.js

@@ -66,6 +66,25 @@ function sanitizeSession(session, fallbackId = '') {
 
   if (session?.model) out.model = String(session.model);
   if (session?.mode) out.mode = String(session.mode);
+  if (session?.planState && typeof session.planState === 'object') {
+    out.planState = {
+      status: String(session.planState.status || '').trim(),
+      source: String(session.planState.source || '').trim(),
+      goal: String(session.planState.goal || '').trim(),
+      filePath: String(session.planState.filePath || '').trim(),
+      summary: String(session.planState.summary || '').trim(),
+      finalSummary: String(session.planState.finalSummary || '').trim()
+    };
+    if (Array.isArray(session.planState.steps)) {
+      out.planState.steps = session.planState.steps
+        .map((step) => ({
+          title: String(step?.title || '').trim(),
+          role: String(step?.role || '').trim(),
+          task: String(step?.task || '').trim()
+        }))
+        .filter((step) => step.title || step.role || step.task);
+    }
+  }
 
   return out;
 }

package/src/core/shell-profile.js

@@ -142,12 +142,22 @@ Some tools are loaded on demand. If a needed tool is not listed, call tool_searc
 
 # Doing tasks
 
+- Search or read before editing unless the exact target is already known
 - If a command or tool is blocked or fails, inspect the error and retry with allowed commands or tools
 - For AST-scoped edits, if edit rejects due to missing or stale ast_target, fix arguments and retry
 - Do not claim filesystem access is impossible unless search/read tools also fail
 - Prefer editing existing files over creating new ones
 - Do not add comments, docstrings, or type annotations to code you did not change
 - Do not add features or refactor code beyond what was asked
+- When a tool result is large, keep only the useful summary in your reply and read the saved output only if it is needed
+- Keep tool results compact in context: prefer short conclusions over re-pasting raw output
+
+# Plan mode
+
+- In plan mode, explore and propose the next steps first
+- In plan mode, do not start implementation until the user asks you to continue
+- If requirements are still unclear, ask one focused question and stop
+- If there are multiple reasonable approaches, give short options and a suggested direction, then stop for user confirmation
 
 # Tone and style
 

package/src/core/tools.js

@@ -1738,7 +1738,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'read',
         description:
-          'Read a file. Call once for metadata and a read_token, then again with include_content=true and the same token to get content. Use this before editing.',
+          'Inspect a file. Call once for metadata and a read_token, then again with include_content=true and the same token to get content. Use this before editing. Do not use run with cat, head, or tail for file reads.',
         parameters: {
           type: 'object',
           properties: {
@@ -1758,7 +1758,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'grep',
         description:
-          'Search file contents. Use this for code search instead of grep or rg in run.',
+          'Search file contents. Use this for code search before read or edit. Do not use run with grep or rg for normal code search.',
         parameters: {
           type: 'object',
           properties: {
@@ -1780,7 +1780,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'glob',
         description:
-          'Find files by glob pattern. Use this for file discovery instead of find in run.',
+          'Find files by glob pattern. Use this for file discovery before read. Do not use run with find for normal file lookup.',
         parameters: {
           type: 'object',
           properties: {
@@ -1797,7 +1797,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'list',
-        description: 'List files and directories in a workspace path.',
+        description: 'List files and directories in a workspace path. Use this for quick directory discovery before deeper reads.',
         parameters: {
           type: 'object',
           properties: {
@@ -1812,7 +1812,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'edit',
         description:
-          'Edit existing files. Use block edits, exact replacements, or anchored inserts. When ast_target is provided, keep the edit constrained to that node. Prefer this over write for code changes.',
+          'Edit existing files. Use block edits, exact replacements, or anchored inserts. When ast_target is provided, keep the edit constrained to that node. Read first unless the exact target is already known. Prefer this over write for code changes.',
         parameters: {
           type: 'object',
           properties: {
@@ -1840,7 +1840,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'write',
         description:
-          'Create a new file or overwrite a file. Use this for new files or full rewrites. Prefer edit for existing code.',
+          'Create a new file or overwrite a file. Use this for new files or explicit full rewrites. Prefer edit for existing code changes.',
         parameters: {
           type: 'object',
           properties: {
@@ -1892,7 +1892,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'ast_query',
         description:
-          'Run a Tree-sitter query on a code file and return ast_target objects for node-scoped reads or edits.',
+          'Run a Tree-sitter query on a code file and return ast_target objects. Use this when you need node-scoped reads or edits for functions, classes, or methods.',
         parameters: {
           type: 'object',
           properties: {
@@ -1911,7 +1911,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'read_ast_node',
         description:
-          'Read a previously selected AST node with compact structural context.',
+          'Read a previously selected AST node with compact structural context. Use this after ast_query before a scoped structural edit.',
         parameters: {
           type: 'object',
           properties: {
@@ -1927,7 +1927,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'generate_diff',
-        description: 'Generate a unified diff for proposed content',
+        description: 'Generate a unified diff for proposed content. Use this when you want to preview or prepare a patch before applying it.',
         parameters: {
           type: 'object',
           properties: {
@@ -1942,7 +1942,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'patch',
-        description: 'Apply one or more unified diff hunks to workspace files',
+        description: 'Apply one or more unified diff hunks to workspace files. Use this for prepared unified diffs instead of ad-hoc shell patching.',
         parameters: {
           type: 'object',
           properties: {
@@ -1958,7 +1958,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'start_service',
         description:
-          'Start a long-running local service and return a compact handle.',
+          'Start a long-running local service and return a compact handle. Do not use run for watchers, dev servers, or other persistent processes.',
         parameters: {
           type: 'object',
           properties: {
@@ -1985,7 +1985,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'list_services',
-        description: 'List tracked local services and their current status.',
+        description: 'List tracked local services and their current status. Use this to find existing service handles before starting another one.',
         parameters: {
           type: 'object',
           properties: {}
@@ -1996,7 +1996,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'get_service_status',
-        description: 'Get the status of a started service.',
+        description: 'Get the status of a started service. Use this to confirm startup or diagnose a stalled service.',
         parameters: {
           type: 'object',
           properties: {
@@ -2010,7 +2010,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'get_service_logs',
-        description: 'Read recent logs from a started service.',
+        description: 'Read recent logs from a started service. Use this for targeted diagnosis instead of restarting blindly.',
         parameters: {
           type: 'object',
           properties: {
@@ -2026,7 +2026,7 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'stop_service',
-        description: 'Stop a started service.',
+        description: 'Stop a started service when it is no longer needed or when you need a clean restart.',
         parameters: {
           type: 'object',
           properties: {