codemini-cli 0.1.14 → 0.1.15

package/OPERATIONS.md

@@ -110,6 +110,7 @@ Use this when you want to separate:
 ```text
 /help
 /commands
+/brainstorm <question>
 /config list
 /config get <key>
 /history list
@@ -144,6 +145,14 @@ Continue into the relevant files and explain how skill loading works.
 Find where shell.default is used and summarize the config path.
 ```
 
+### Brainstorm before coding
+
+```text
+/brainstorm Should login retry stay local or become a shared helper?
+```
+
+Use this when the implementation path is still fuzzy and you want the CLI to compare a few approaches before any code change.
+
 ### Spec and plan flow
 
 ```text
@@ -170,12 +179,18 @@ Execute this plan step by step.
 ```powershell
 codemini skill list
 codemini skill inspect superpowers-lite
-codemini skill enable brainstorming-lite
-codemini skill disable brainstorming-lite
+codemini skill enable brainstorm
+codemini skill disable brainstorm
 codemini skill reindex
 ```
 
 ## Better Prompt Patterns
+## Release Management
+
+### Release Checklist
+
+For information on how to perform a release, please see the [Release Checklist](RELEASE_CHECKLIST.md) document.
+
 
 These usually work better:
 

package/README.md

@@ -63,6 +63,7 @@ codemini skill list|install|enable|disable|inspect|reindex
 
 - `ui.reply_language` controls the assistant reply language at the prompt layer and also nudges generated docs and code comments to match
 - Slash completion now prioritizes important commands and config keys, shows short descriptions, and supports `←/→` page switching
+- Ambiguous feature requests can pause for lightweight brainstorming first, and `/brainstorm <question>` gives an explicit way to compare options before coding
 - `plan auto` now turns the original goal into an acceptance checklist, uses a lighter chain only for truly tiny tasks, and treats unmet checklist items as failure signals
 - Structured code tools reduce shell-noise for small models by preferring `locate -> open_target -> edit_target`
 
@@ -83,7 +84,19 @@ The base config directory is resolved in this order:
 - Linux/XDG: `$XDG_CONFIG_HOME/codemini-cli`
 - Fallback in restricted environments: `.codemini-cli/`
 
+### Brainstorming
+
+Use `/brainstorm <question>` when you want the assistant to stop before coding, compare 2-3 approaches, and choose one direction first.
+
+```text
+/brainstorm Should login retry stay local or become a shared helper?
+```
+
 ### Documentation
+### Release Checklist
+
+For information on how to perform a release, please see the [Release Checklist](RELEASE_CHECKLIST.md) document.
+
 
 - Operator guide and common command patterns: [OPERATIONS.md](/mnt/e/Git%20Projects/qurio-coder/OPERATIONS.md)
 - Packaging and deployment guide: [deployment.md](/mnt/e/Git%20Projects/qurio-coder/deployment.md)
@@ -164,6 +177,7 @@ codemini skill list|install|enable|disable|inspect|reindex
 
 - `ui.reply_language` 通过 prompt 层控制模型回复语言，也会尽量让生成文档和代码注释跟随该语言
 - slash 补全会优先展示更重要的命令和配置项，显示简短说明，并支持 `←/→` 翻页
+- 对于需求仍不明确的功能请求，CLI 会先偏向轻量 brainstorm；也可以显式使用 `/brainstorm <问题>` 先比较方案再决定是否编码
 - `plan auto` 会先把原始目标展开成验收清单；只有真正很小的任务才会走轻量链路；如果 reviewer 或 tester 标记了未满足或未验证的验收项，就不会按成功处理
 - 为了减少小模型被 shell 原始输出干扰，新增了 `locate -> open_target -> edit_target` 这套结构化代码工具流
 
@@ -184,6 +198,14 @@ CodeMini CLI 会从这些位置读取 skill：
 - Linux / XDG：`$XDG_CONFIG_HOME/codemini-cli`
 - 受限环境回退：`.codemini-cli/`
 
+### Brainstorm 用法
+
+当你希望助手先收敛方向、不要立即写代码时，可以使用：
+
+```text
+/brainstorm Should login retry stay local or become a shared helper?
+```
+
 ### 文档入口
 
 - 操作手册与常见命令组合：[OPERATIONS.md](/mnt/e/Git%20Projects/qurio-coder/OPERATIONS.md)

package/package.json

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

package/skills/{brainstorming-lite → brainstorm}/SKILL.md

@@ -1,11 +1,16 @@
 ---
-name: brainstorming-lite
-description: Lightweight brainstorming skill for 30B-class models. Clarify scope, ask one question at a time, compare a few options, and converge before implementation.
+name: brainstorm
+description: Lightweight brainstorming skill for 30B-class models. Use when a feature or behavior request is still unclear and the agent should compare a few approaches before coding.
 version: 0.1.0
 ---
 
 Use this skill before adding new behavior, new features, or meaningful workflow changes.
 
+Primary purpose:
+- stop premature coding when the request is still fuzzy
+- narrow the decision to a small number of approaches
+- leave with one chosen direction
+
 Rules:
 
 1. Ask one question at a time.
@@ -23,12 +28,39 @@ Write only enough design for the current scope. Do not inflate a simple task int
 5. Confirm before implementation.
 Summarize the chosen direction in a few bullets or a short paragraph, then move to execution only after alignment.
 
+6. No code before convergence.
+Do not write implementation code, pseudo-code, or file edits while the direction is still being chosen.
+
+Output format:
+
+Option 1:
+- idea:
+- pros:
+- cons:
+
+Option 2:
+- idea:
+- pros:
+- cons:
+
+Option 3 (optional):
+- idea:
+- pros:
+- cons:
+
+Decision:
+- chosen:
+- reason:
+
+After decision:
+- stop after the chosen direction unless the user clearly asks to continue into implementation
+
 Suggested flow:
 - Restate the task briefly
-- Ask the next best question
+- Ask the next best question when a key uncertainty blocks implementation
 - Propose options with tradeoffs
 - Confirm the chosen approach
-- Hand off to plan execution
+- Stop at a clear decision point
 
 Avoid:
 - large ceremonies

package/skills/superpowers-lite/SKILL.md

@@ -6,6 +6,12 @@ version: 0.1.0
 
 Use this skill as the default lightweight operating style for coding work.
 
+Primary behavior:
+- keep momentum on clear tasks
+- slow down before coding when the request is ambiguous
+- keep edits local
+- verify before claiming success
+
 Core rules:
 
 1. Search first.
@@ -21,15 +27,19 @@ When a task can be split cleanly, use sub-agents for bounded subtasks so the mai
 - a tiny file evidence packet
 - a concrete expected output
 
-4. Read and write with intent.
+4. Do not code against unclear requirements.
+If the requested behavior, scope, or acceptance is unclear, do not jump into implementation. Ask the next best question or use `brainstorm` to compare a few small options and converge first.
+
+5. Read and write with intent.
 Use `read_file` only when shell output is not enough. Use `write_file` for edits. Avoid unnecessary tool calls and avoid rereading the same file without a reason.
 
-5. Verify before claiming success.
+6. Verify before claiming success.
 Run the relevant test, check, or command before saying work is fixed or complete.
 
 Default workflow:
 - Search with `rg`
 - Inspect local context
+- If the request is unclear, pause for clarification or brainstorm
 - Plan the next smallest step
 - Delegate if the work is independent
 - 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.1.0';
+const VERSION = '0.1.15';
 
 function printHelp() {
   console.log(`codemini ${VERSION}

package/src/core/chat-runtime.js

@@ -106,8 +106,6 @@ const SUB_AGENT_CONTEXT_MAX_MESSAGES = 4;
 const SUB_AGENT_CONTEXT_MAX_CHARS = 1200;
 const SUB_AGENT_EVIDENCE_MAX_ITEMS = 3;
 const SUB_AGENT_HANDOFF_MAX_ITEMS = 6;
-const AUTO_SKILL_NAMES = ['superpowers-lite', 'brainstorming-lite', 'executing-plan-lite'];
-
 function getSubAgentRolePrompt(role) {
   if (role === 'planner') {
     return 'You are a planning sub-agent. Produce a concrete implementation plan with risks and verification.';
@@ -430,6 +428,40 @@ function buildGoalRequirementPacket(goal, role) {
   return lines.join('\n');
 }
 
+function buildAutoPlanPlannerGuidance() {
+  return [
+    'Auto-plan planning rules:',
+    '- 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.',
+    '- Keep the plan ordered, implementation-oriented, and easy for small sub-agents to follow.'
+  ].join('\n');
+}
+
+function buildAutoPlanExecutionGuidance(role) {
+  const common = [
+    'Auto-plan execution rules:',
+    '- Work in the smallest useful step.',
+    '- Read the target code before editing.',
+    '- Prefer local changes over broad refactors.',
+    '- Prefer narrow verification with concrete evidence before claiming success.'
+  ];
+
+  if (role === 'coder') {
+    common.push('- Keep edits tightly scoped to the chosen plan direction.');
+    common.push('- Avoid speculative cleanup or unrelated improvements.');
+  } else if (role === 'reviewer') {
+    common.push('- Review against the chosen plan direction and the acceptance checklist.');
+    common.push('- Call out missing requested behavior, regression risk, and unverified claims.');
+  } else if (role === 'tester') {
+    common.push('- Prefer running the narrowest real verification command that matches the changed area.');
+    common.push('- Distinguish clearly between verified behavior and assumptions.');
+  }
+
+  return common.join('\n');
+}
+
 async function pathExists(targetPath) {
   try {
     await fs.access(targetPath);
@@ -536,15 +568,19 @@ function isSkillEnabled(config, name) {
 function selectAutoSkillNames(text = '') {
   const input = String(text || '').toLowerCase();
   const selected = ['superpowers-lite'];
-  if (
-    /(brainstorm|头脑风暴|方案|思路|设计一下|设计方案|怎么做|如何做|approach|options?)/i.test(input)
-  ) {
-    selected.push('brainstorming-lite');
-  }
-  if (
-    /(按计划|执行计划|继续执行|下一步|implement|execute|carry out|完成验证|verify|plan)/i.test(input)
-  ) {
-    selected.push('executing-plan-lite');
+
+  const explicitBrainstorm =
+    /(brainstorm|头脑风暴|方案|思路|设计一下|设计方案|怎么做|如何做|approach|options?)/i.test(input);
+  const ambiguitySignals =
+    /(not sure|unsure|unclear|help me think|let'?s think|should we|which (?:approach|option|way)|best way|trade-?off|vs\b|versus|or should|要不要|不确定|不明确|先别写|先不要写|先讨论|先想一下|哪个方案|怎么设计|如何设计|取舍|还是)/i.test(
+      input
+    );
+  const featureRequest =
+    /\b(add|build|create|implement|support|introduce|design|refactor|change|update)\b/i.test(input) ||
+    /(新增|增加|实现|支持|设计|重构|改造|调整)/i.test(input);
+
+  if (explicitBrainstorm || (ambiguitySignals && featureRequest)) {
+    selected.push('brainstorm');
   }
   return selected;
 }
@@ -953,6 +989,7 @@ async function buildPlanFromSpecWithModel({
   model,
   systemPrompt
 }) {
+  const projectConstraints = await inferProjectImplementationConstraints(process.cwd());
   const prompt = [
     'Convert the provided engineering spec into an implementation plan in markdown.',
     'Use this structure exactly:',
@@ -972,7 +1009,7 @@ async function buildPlanFromSpecWithModel({
       { role: 'system', content: `${systemPrompt}\n${prompt}` },
       {
         role: 'user',
-        content: `Spec path: ${specPath || '(inline)'}\n\n${specText}`
+        content: `Spec path: ${specPath || '(inline)'}\n\nProject implementation constraints:\n${projectConstraints}\n\n${specText}`
       }
     ],
     timeoutMs: config.gateway.timeout_ms || 90000,
@@ -981,6 +1018,84 @@ async function buildPlanFromSpecWithModel({
   return String(result.text || '').trim();
 }
 
+async function collectLikelyImplementationFiles(cwd) {
+  const candidates = [];
+  const roots = ['src', 'app', 'lib'];
+  const preferredExts = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+
+  async function visit(dir) {
+    let entries = [];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.coder') continue;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(abs);
+        continue;
+      }
+      if (!preferredExts.has(path.extname(entry.name).toLowerCase())) continue;
+      candidates.push(path.relative(cwd, abs).replace(/\\/g, '/'));
+      if (candidates.length >= 8) return;
+    }
+  }
+
+  for (const root of roots) {
+    const absRoot = path.join(cwd, root);
+    if (!(await pathExists(absRoot))) continue;
+    await visit(absRoot);
+    if (candidates.length >= 8) break;
+  }
+  return candidates.slice(0, 8);
+}
+
+async function inferProjectImplementationConstraints(cwd) {
+  const hints = [];
+  const packageJsonPath = path.join(cwd, 'package.json');
+  const pyprojectPath = path.join(cwd, 'pyproject.toml');
+  const cargoPath = path.join(cwd, 'Cargo.toml');
+  const goModPath = path.join(cwd, 'go.mod');
+
+  if (await pathExists(packageJsonPath)) {
+    hints.push('- Detected package.json in the workspace.');
+    hints.push('- Prefer JavaScript/TypeScript style paths and file names that fit the existing repo.');
+    hints.push('- Reuse existing src/*.js, src/*.ts, or neighboring modules before inventing new utility modules.');
+  }
+  if (await pathExists(pyprojectPath)) {
+    hints.push('- Detected pyproject.toml in the workspace.');
+    hints.push('- Prefer Python modules and package layout that already exist in this repo.');
+  }
+  if (await pathExists(cargoPath)) {
+    hints.push('- Detected Cargo.toml in the workspace.');
+    hints.push('- Prefer Rust crate/module layout that matches the current workspace.');
+  }
+  if (await pathExists(goModPath)) {
+    hints.push('- Detected go.mod in the workspace.');
+    hints.push('- Prefer Go package paths and file names already present in the repo.');
+  }
+
+  if (hints.length === 0) {
+    hints.push('- No strong language marker was detected automatically.');
+    hints.push('- Infer the implementation language from the referenced files in the spec and preserve that language family.');
+  }
+
+  const likelyFiles = await collectLikelyImplementationFiles(cwd);
+  if (likelyFiles.length > 0) {
+    hints.push('- Likely existing implementation files to reuse first:');
+    for (const file of likelyFiles) {
+      hints.push(`  - ${file}`);
+    }
+    hints.push('- Prefer updating one of the listed files when the feature naturally fits there before inventing new modules.');
+  }
+
+  hints.push('- Do not invent files in another language family unless the spec explicitly requires it.');
+  hints.push('- If the spec references existing files, keep the plan anchored to those exact files or their immediate neighbors.');
+  return hints.join('\n');
+}
+
 function clampRange(start, end, max) {
   const s = Math.max(1, Math.min(start, max));
   const e = Math.max(s, Math.min(end, max));
@@ -1268,7 +1383,8 @@ async function runSubAgentTask({
   config,
   model,
   systemPrompt,
-  onAgentEvent
+  onAgentEvent,
+  extraRolePrompt = ''
 }) {
   const subSession = { id: `sub-${Date.now()}`, messages: [] };
   const rolePrompt = getSubAgentRolePrompt(role);
@@ -1320,7 +1436,7 @@ async function runSubAgentTask({
     session: subSession,
     config,
     model,
-    systemPrompt: `${systemPrompt}\n${rolePrompt}`,
+    systemPrompt: `${systemPrompt}\n${rolePrompt}${extraRolePrompt ? `\n${extraRolePrompt}` : ''}`,
     onAgentEvent: wrappedOnAgentEvent,
     persistSession: false,
     executionMode: 'auto'
@@ -1346,8 +1462,10 @@ async function buildAutoPlanAndRun({
   sessionId
 }) {
   const requirementPacket = buildGoalRequirementPacket(goal, 'planner');
-  const plannerPrompt =
-    'Return strict JSON only with shape {"summary":"...","steps":[{"title":"...","role":"planner|coder|reviewer|tester","task":"..."}]}. No markdown. Always include final reviewer and tester steps.';
+  const plannerPrompt = [
+    buildAutoPlanPlannerGuidance(),
+    'Return strict JSON only with shape {"summary":"...","steps":[{"title":"...","role":"planner|coder|reviewer|tester","task":"..."}]}. No markdown. Always include final reviewer and tester steps.'
+  ].join('\n');
   let autoPlan = {
     summary: `Auto plan for: ${goal}`,
     steps: [
@@ -1406,7 +1524,8 @@ async function buildAutoPlanAndRun({
         config,
         model,
         systemPrompt,
-        onAgentEvent
+        onAgentEvent,
+        extraRolePrompt: buildAutoPlanExecutionGuidance(step.role)
       });
       const outputLooksSuccessful = looksLikeSuccessfulStepOutput(stepResult.text);
       const outputHasFailureSignals = stepOutputHasFailureSignals(step.role, stepResult.text);
@@ -2414,10 +2533,16 @@ export async function createChatRuntime({
         return { type: 'system', text: `Skill is disabled: ${custom.name}` };
       }
 
-      const rendered = await expandFileMentions(
-        renderCommandPrompt(custom, parsedInput.args),
-        process.cwd()
-      );
+      const customPrompt =
+        custom.name === 'brainstorm'
+          ? [
+              renderCommandPrompt(custom, []),
+              parsedInput.args.length > 0 ? `Current question:\n${parsedInput.args.join(' ')}` : ''
+            ]
+              .filter(Boolean)
+              .join('\n\n')
+          : renderCommandPrompt(custom, parsedInput.args);
+      const rendered = await expandFileMentions(customPrompt, process.cwd());
       if (custom.metadata.type === 'skill' && onAgentEvent) {
         onAgentEvent({ type: 'skill:start', name: custom.name });
       }

package/src/core/tools.js

@@ -1105,17 +1105,55 @@ async function openTarget(root, args) {
   };
 }
 
-async function editTarget(root, args) {
+function normalizeEditTargetArgs(args = {}) {
   const file = String(args?.file || args?.path || '').trim();
-  const edit = args?.edit || {};
+  const nestedEdit = args?.edit && typeof args.edit === 'object' ? args.edit : null;
+  if (nestedEdit) {
+    return {
+      file,
+      edit: nestedEdit
+    };
+  }
+  return {
+    file,
+    edit: {
+      kind: args?.kind,
+      target: args?.target,
+      new_content: args?.new_content ?? args?.content,
+      old_text: args?.old_text,
+      new_text: args?.new_text,
+      anchor_text: args?.anchor_text,
+      content: args?.content
+    }
+  };
+}
+
+async function editTarget(root, args) {
+  const normalized = normalizeEditTargetArgs(args);
+  const file = normalized.file;
+  const edit = normalized.edit || {};
   const kind = String(edit.kind || '').trim();
   if (!file || !kind) throw new Error('edit_target requires file and edit.kind');
   if (kind === 'replace_block') {
-    return replaceBlock(root, {
-      path: file,
-      target: edit.target,
-      new_content: edit.new_content
-    });
+    try {
+      return await replaceBlock(root, {
+        path: file,
+        target: edit.target,
+        new_content: edit.new_content
+      });
+    } catch (error) {
+      if (!/old_hash mismatch/i.test(String(error?.message || ''))) throw error;
+      const validation = await validateEdit(root, {
+        path: file,
+        kind: 'replace_block',
+        target: edit.target
+      });
+      return replaceBlock(root, {
+        path: file,
+        target: validation.target,
+        new_content: edit.new_content
+      });
+    }
   }
   if (kind === 'replace_text') {
     return replaceText(root, {

package/skills/executing-plan-lite/SKILL.md

@@ -1,41 +0,0 @@
----
-name: executing-plan-lite
-description: Lightweight plan execution skill for 30B-class models. Execute the plan in small verified steps with narrow context and frequent checks.
-version: 0.1.0
----
-
-Use this skill when a direction is chosen and the next job is to carry out implementation reliably.
-
-Rules:
-
-1. Execute the plan in small verified steps.
-Take one bounded step at a time. Avoid mixing planning, implementation, and verification into one big jump.
-
-2. Keep the active context narrow.
-Work from the smallest relevant file set and recent evidence. If needed, use sub-agents for independent subtasks.
-
-3. Search before editing.
-Use `rg` to locate code, inspect the smallest useful context, then edit.
-
-4. Verify after each meaningful change.
-Run the most relevant test or command before claiming success.
-
-5. Report progress briefly.
-Summarize what changed, what was verified, and what remains.
-
-Suggested flow:
-- identify the next step
-- search and inspect
-- edit
-- verify
-- either continue or stop at a clear checkpoint
-
-Use sub-agents when:
-- the task can be split cleanly
-- the write scope is disjoint
-- the result can be reviewed independently
-
-Avoid:
-- broad refactors without a reason
-- carrying full history into each step
-- declaring completion without verification