micro-models-agent 0.20.0 → 0.20.1

package/dist/main.js

@@ -2548,14 +2548,19 @@ Available commands:`,
 
 Use this knowledge to answer the user's question.`,
     "exec.stuck": "Stuck on step {stepId}. Current: {description}. No progress for {iterations} iterations.",
-    "exec.stuck_recovery": "[Stuck detected: {iterations} iterations without progress. Stop repeating the same approach. Try a fundamentally different strategy: use a different tool (e.g., 'browser' tool for JavaScript-heavy websites instead of 'web_browse'), break the task into smaller parts, or explain to the user what went wrong and ask for guidance.]",
+    "exec.stuck_recovery": '[STUCK: {iterations} iterations on step {stepId} — "{description}". You MUST change approach NOW. Concrete actions: (1) Check what this step needs — are dependencies installed? (2) Use plan show to see the plan. (3) If commands fail — create files directly via write_file. (4) After completing the step, call plan update step={stepId} status=done. Do NOT work on other steps until this one is finished.]',
     "exec.tool_errors": "Tool {tool} failed {count} times. Suggest alternative approach.",
-    "exec.tool_errors_recovery": "[Tool {tool} failed {count} times. Stop using this tool and try a different approach or explain the issue to the user.]",
-    "exec.repetitive_tool": "[You called {tool} {count} times in a row with the same arguments and result. Stop repeating — try a different approach: create files, change arguments, or explain the problem to the user.]",
-    "exec.consecutive_failures_recovery": "[{count} consecutive tool calls failed. You are going in circles — stop trying commands that keep failing. Explain the problem to the user, or try a completely different approach: write files directly, use a different tool, or break the task into smaller parts.]",
-    "exec.task_reminder": "[Remember the original task: {task}. Do not switch to unrelated tasks. If you cannot complete the original task, explain why to the user and ask for guidance.]",
-    "exec.plan_warning": '[⚠ Warning: you are working on step {step} - "{description}". Your {tool} call touches files not mentioned in the current step. Focus on the current step or update the plan via plan update.]',
-    "exec.off_track": `[⚠ Outside plan: step {stepId} is "{description}", but you're using {tool} on a different path. Explain or return.]`,
+    "exec.tool_errors_recovery": "[Tool {tool} failed {count} consecutive times. DO NOT use it again. Try a different approach: (1) create files directly via write_file, (2) use a different tool for the same task, (3) if nothing works — explain the problem and skip this step via plan update step=N status=skipped with a note why.]",
+    "exec.repetitive_tool": "[REPETITION: you called {tool} {count} times with identical arguments and result. This is pointless. IMMEDIATELY change approach: create files directly, change arguments, or if it's a process — check its status via process_log.]",
+    "exec.consecutive_failures_recovery": "[{count} CONSECUTIVE TOOLS FAILED. Stop running commands. Here is what to do: (1) Create files directly via write_file instead of terminal commands. (2) Check if dependencies are installed (npm install). (3) Use list_dir to see what's in the project. (4) Do not attempt build/tests until all files are created.]",
+    "exec.task_reminder": "[ORIGINAL TASK: {task}. You MUST work on this task only. Do not create files for other tasks. If you cannot complete it — explain why and request help.]",
+    "exec.plan_warning": '[⚠ PLAN: you are on step {step} — "{description}", but calling {tool} with files outside this step. This is FORBIDDEN — work STRICTLY on the current step. First complete it and call plan update step={step} status=done, only then move to the next.]',
+    "exec.plan_blocked": "[⛔ BLOCKED: {max} consecutive calls outside the current step. You are violating the plan. Return to step {step} and complete it. Other steps are blocked until this one is done.]",
+    "exec.off_track": `[⚠ OFF PLAN: step {stepId} is "{description}", but you're using {tool} on a different path. Return to the current step immediately.]`,
+    "exec.step_gate_deps": '[⚠ Step {step} "{description}": dependencies are not installed. First run the install command (npm install, pip install, etc.). Verify the lock file or dependency directory exists.]',
+    "exec.step_gate_empty": "[⚠ Step {step}: files exist but appear empty: {files}. Add real code to these files before advancing to the next step.]",
+    "exec.step_gate_ok": '[✓] Step {step} completed and verified. MOVING to step {nextStep}: "{nextDesc}". Work ONLY on this step.',
+    "exec.step_gate_last": "[✓] Step {step} completed — that was the final step. Verify everything together and provide the final answer.]",
     "exec.audit_pass": "[✓] Task complete: {done}/{total} steps done, {files} files verified",
     "exec.audit_fail": "[✗] Task incomplete: {done}/{total} steps done, {files} files missing",
     "exec.audit_fail_typecheck": "[✗] Task incomplete: {done}/{total} steps done, {missing} files missing, typecheck error: {typeError}",
@@ -3040,14 +3045,19 @@ var init_ru = __esm(() => {
 
 Используйте эти знания для ответа на вопрос пользователя.`,
     "exec.stuck": "Застряли на шаге {stepId}. Текущий: {description}. Нет прогресса {iterations} итераций.",
-    "exec.stuck_recovery": "[Обнаружено застревание: {iterations} итераций без прогресса. Прекратите повторять тот же подход. Попробуйте принципиально другую стратегию: используйте другой инструмент (например, 'browser' для сайтов с JavaScript вместо 'web_browse'), разбейте задачу на подзадачи или объясните пользователю что пошло не так и спросите совета.]",
+    "exec.stuck_recovery": '[ЗАСТРЕВАНИЕ: {iterations} итераций на шаге {stepId} — "{description}". ВЫ ДОЛЖНЫ сменить подход прямо сейчас. Конкретные действия: (1) Проверьте что нужно для этого шага — установлены ли зависимости? (2) Используйте plan show чтобы увидеть план. (3) Если команды не работают — создайте файлы напрямую через write_file. (4) После завершения шага вызовите plan update step={stepId} status=done. НЕ переходите к другим шагам пока этот не завершён.]',
     "exec.tool_errors": "Инструмент {tool} сбоил {count} раз. Предложите другой подход.",
-    "exec.tool_errors_recovery": "[Инструмент {tool} сбоил {count} раз. Прекратите использовать этот инструмент и попробуйте другой подход или объясните проблему пользователю.]",
-    "exec.repetitive_tool": "[Вы вызвали {tool} {count} раз подряд с одинаковыми аргументами и результатом. Прекратите повторять — попробуйте другой подход: создайте файлы, измените аргументы или объясните пользователю проблему.]",
-    "exec.consecutive_failures_recovery": "[{count} последовательных вызовов тулов завершились ошибкой. Вы ходите по кругу — прекратите пытаться выполнить команды, которые постоянно падают. Объясните проблему пользователю или попробуйте совершенно другой подход: напишите файлы напрямую, используйте другой инструмент или разбейте задачу на части.]",
-    "exec.task_reminder": "[Напоминание о задаче: {task}. Не переключайтесь на посторонние задачи. Если не можете выполнить задачу — объясните почему и спросите совета.]",
-    "exec.plan_warning": '[⚠ Внимание: вы работаете над шагом {step} — "{description}". Ваш вызов {tool} касается файлов, не упомянутых в текущем шаге. Сосредоточьтесь на текущем шаге или обновите план через plan update.]',
-    "exec.off_track": '[⚠ Вне плана: шаг {stepId} — "{description}", но вы используете {tool} для другого пути. Объясните или вернитесь.]',
+    "exec.tool_errors_recovery": "[Инструмент {tool} сбоил {count} раз подряд. НЕ ИСПОЛЬЗУЙТЕ его снова. Используйте другой подход: (1) создайте нужные файлы напрямую через write_file, (2) используйте другой инструмент для той же задачи, (3) если ничего не работает — объясните проблему и переходите к следующему шагу плана через plan update step=N status=skipped с пометкой почему.]",
+    "exec.repetitive_tool": "[ПОВТОРЕНИЕ: вы вызвали {tool} {count} раз с одинаковыми аргументами и результатом. Это бессмысленно. НЕМЕДЛЕННО смените подход: создайте файлы напрямую, измените аргументы или, если это процесс — проверьте его статус через process_log.]",
+    "exec.consecutive_failures_recovery": "[{count} ИНСТРУМЕНТОВ ПОДРЯД УПАЛИ. Хватит пытаться запускать команды. Вот что делать: (1) Создавайте файлы напрямую через write_file вместо команд терминала. (2) Проверьте, установлены ли зависимости (npm install). (3) Используйте list_dir чтобы увидеть что есть в проекте. (4) Не пытайтесь запустить сборку/тесты пока не созданы все файлы.]",
+    "exec.task_reminder": "[ИСХОДНАЯ ЗАДАЧА: {task}. ВЫ ДОЛЖНЫ работать только над этой задачей. Не создавайте файлы для других задач. Если не можете выполнить — объясните почему и запросите помощь.]",
+    "exec.plan_warning": '[⚠ ПЛАН: вы на шаге {step} — "{description}", но вызываете {tool} для файлов вне этого шага. Это ЗАПРЕЩЕНО — работайте СТРОГО над текущим шагом. Сначала завершите его и вызовите plan update step={step} status=done, только потом переходите к следующему.]',
+    "exec.plan_blocked": "[⛔ ЗАБЛОКИРОВАНО: {max} вызова подряд вне текущего шага. Вы нарушаете план. Вернитесь к шагу {step} и завершите его. Другие шаги будут заблокированы пока текущий не выполнен.]",
+    "exec.off_track": '[⚠ ВНЕ ПЛАНА: шаг {stepId} — "{description}", но вы используете {tool} для другого пути. Вернитесь к текущему шагу немедленно.]',
+    "exec.step_gate_deps": '[⚠ Шаг {step} "{description}": зависимости не установлены. Сначала выполните команду установки (npm install, pip install и т.д.). Проверьте что lock-файл или директория зависимостей существует.]',
+    "exec.step_gate_empty": "[⚠ Шаг {step}: файлы существуют, но выглядят пустыми: {files}. Добавьте реальный код в эти файлы перед тем как переходить к следующему шагу.]",
+    "exec.step_gate_ok": '[✓] Шаг {step} завершён и проверен. ПЕРЕХОДИМ к шагу {nextStep}: "{nextDesc}". Работайте ТОЛЬКО над этим шагом.',
+    "exec.step_gate_last": "[✓] Шаг {step} завершён — это был последний шаг. Проверьте всё вместе и предоставьте финальный ответ.]",
     "exec.audit_pass": "[✓] Задача выполнена: {done}/{total} шагов, {files} файлов проверено",
     "exec.audit_fail": "[✗] Задача не выполнена: {done}/{total} шагов, {files} файлов отсутствует",
     "exec.audit_fail_typecheck": "[✗] Задача не выполнена: {done}/{total} шагов, {missing} файлов отсутствует, ошибка typecheck: {typeError}",
@@ -12823,11 +12833,18 @@ class StuckDetector {
     if (!this.hasRepetitiveToolCalls())
       return "";
     const last = this.recentToolCalls[this.recentToolCalls.length - 1];
-    return t("exec.repetitive_tool", { tool: last.name, count: this.repetitionThreshold });
+    return t("exec.repetitive_tool", {
+      tool: last.name,
+      count: this.repetitionThreshold
+    });
   }
   getStuckReason() {
     if (this.isStuck()) {
-      return t("exec.stuck", { stepId: String(this.currentStepId), description: this.currentStepDescription, iterations: this.iterationsOnCurrentStep });
+      return t("exec.stuck", {
+        stepId: String(this.currentStepId ?? "?"),
+        description: this.currentStepDescription,
+        iterations: this.iterationsOnCurrentStep
+      });
     }
     const errorTool = Array.from(this.toolErrors.entries()).find(([_, c]) => c >= this.errorThreshold);
     if (errorTool) {
@@ -12837,14 +12854,23 @@ class StuckDetector {
   }
   getRecoveryMessage() {
     if (this.isStuck()) {
-      return t("exec.stuck_recovery", { iterations: this.iterationsOnCurrentStep });
+      return t("exec.stuck_recovery", {
+        iterations: this.iterationsOnCurrentStep,
+        stepId: String(this.currentStepId ?? "?"),
+        description: this.currentStepDescription
+      });
     }
     const errorTool = Array.from(this.toolErrors.entries()).find(([_, c]) => c >= this.errorThreshold);
     if (errorTool) {
-      return t("exec.tool_errors_recovery", { tool: errorTool[0], count: errorTool[1] });
+      return t("exec.tool_errors_recovery", {
+        tool: errorTool[0],
+        count: errorTool[1]
+      });
     }
     if (this.hasConsecutiveFailures()) {
-      return t("exec.consecutive_failures_recovery", { count: this.consecutiveFailures });
+      return t("exec.consecutive_failures_recovery", {
+        count: this.consecutiveFailures
+      });
     }
     if (this.hasRepetitiveToolCalls()) {
       return this.getRepetitiveToolMessage();
@@ -12859,7 +12885,11 @@ class StuckDetector {
     const pathInCall = (toolArgStr.match(/\b[\w./-]+\.[a-z]+/gi) || []).map((p) => p.toLowerCase());
     const overlaps = pathInCall.some((p) => pathInStep.some((s) => p.includes(s) || s.includes(p)));
     if (!overlaps && pathInStep.length > 0 && pathInCall.length > 0) {
-      return t("exec.off_track", { stepId: String(this.currentStepId), description: this.currentStepDescription, tool: toolName });
+      return t("exec.off_track", {
+        stepId: String(this.currentStepId),
+        description: this.currentStepDescription,
+        tool: toolName
+      });
     }
     return null;
   }
@@ -12994,7 +13024,7 @@ class PlanPersister {
 var init_plan_persister = () => {};
 
 // src/modules/execution/module.ts
-import { existsSync as existsSync26 } from "fs";
+import { existsSync as existsSync26, readFileSync as readFileSync15 } from "fs";
 import { resolve as resolve14 } from "path";
 
 class ExecutionModule {
@@ -13006,6 +13036,8 @@ class ExecutionModule {
   persister;
   baseDir;
   lastRecoveryIteration = -STUCK_RECOVERY_COOLDOWN;
+  consecutivePlanWarnings = 0;
+  lastStepId = -1;
   constructor(baseDir, stuckThreshold = 8) {
     this.baseDir = baseDir;
     this.verifier = new StepVerifier(baseDir);
@@ -13221,10 +13253,16 @@ Sub-tasks: ${note}`
       onBeforeThink: (ctx) => {
         const step = this.tracker?.getCurrentStep();
         if (this.tracker && step) {
+          if (step.id !== this.lastStepId) {
+            this.consecutivePlanWarnings = 0;
+            this.lastStepId = step.id;
+          }
           this.stuckDetector.setCurrentStep(step.id, step.description);
           this.stuckDetector.recordIteration(step.id);
         } else {
           this.stuckDetector.reset();
+          this.consecutivePlanWarnings = 0;
+          this.lastStepId = -1;
         }
         const stuckReason = this.stuckDetector.getStuckReason();
         if (stuckReason) {
@@ -13251,6 +13289,16 @@ Sub-tasks: ${note}`
             role: "user",
             content: `<system-summary>${warning}</system-summary>`
           });
+          this.consecutivePlanWarnings++;
+          if (this.consecutivePlanWarnings >= MAX_PLAN_WARNINGS_BEFORE_BLOCK) {
+            ctx.contextManager.addMessage({
+              role: "user",
+              content: `<system-summary>${t("exec.plan_blocked", { step: String(this.tracker?.getCurrentStep()?.id ?? "?"), max: MAX_PLAN_WARNINGS_BEFORE_BLOCK })}</system-summary>`
+            });
+            return false;
+          }
+        } else {
+          this.consecutivePlanWarnings = 0;
         }
         return true;
       },
@@ -13268,7 +13316,7 @@ Sub-tasks: ${note}`
           this.stuckDetector.recordToolSuccess();
         }
         if (this.tracker && result.success && (call.name === "write_file" || call.name === "edit_file")) {
-          this.advancePlanIfStepComplete();
+          this.advancePlanIfStepComplete(ctx.contextManager);
         }
       }
     };
@@ -13310,24 +13358,78 @@ Sub-tasks: ${note}`
       tool: call.name
     });
   }
-  advancePlanIfStepComplete() {
+  advancePlanIfStepComplete(contextManager) {
     const step = this.tracker?.getCurrentStep();
     if (!step)
       return;
+    const stepText = step.description.toLowerCase();
     const stepPaths = step.description.match(/\b[\w./\\-]+\.[a-z]+/gi) || [];
+    const isDepsStep = stepText.includes("install") || stepText.includes("зависим") || stepText.includes("init") || stepText.includes("инициализац");
+    if (isDepsStep) {
+      const lockFiles = [
+        "package-lock.json",
+        "bun.lockb",
+        "yarn.lock",
+        "pnpm-lock.yaml",
+        "node_modules",
+        "go.sum",
+        "Cargo.lock",
+        "Pipfile.lock",
+        "poetry.lock",
+        "requirements.txt"
+      ];
+      const hasLockFile = lockFiles.some((f) => existsSync26(resolve14(this.baseDir, f)));
+      if (!hasLockFile) {
+        if (contextManager) {
+          contextManager.addMessage({
+            role: "user",
+            content: `<system-summary>${t("exec.step_gate_deps", { step: String(step.id), description: step.description })}</system-summary>`
+          });
+        }
+        return;
+      }
+    }
     if (stepPaths.length === 0)
       return;
     const allExist = stepPaths.every((p) => existsSync26(resolve14(this.baseDir, p)));
-    if (allExist) {
-      this.tracker?.updateStepStatus(step.id, "done");
-      this.tracker?.advance();
-      if (this.tracker) {
-        this.persister.save(this.tracker.getPlan());
-      }
+    if (!allExist)
+      return;
+    const emptyFiles = [];
+    for (const p of stepPaths) {
+      try {
+        const content = readFileSync15(resolve14(this.baseDir, p), "utf-8");
+        if (content.trim().length < 10) {
+          emptyFiles.push(p);
+        }
+      } catch {}
+    }
+    if (emptyFiles.length > 0 && contextManager) {
+      contextManager.addMessage({
+        role: "user",
+        content: `<system-summary>${t("exec.step_gate_empty", { step: String(step.id), files: emptyFiles.join(", ") })}</system-summary>`
+      });
+      return;
+    }
+    this.tracker?.updateStepStatus(step.id, "done");
+    const hadNext = this.tracker?.advance() ?? false;
+    if (this.tracker) {
+      this.persister.save(this.tracker.getPlan());
+    }
+    if (contextManager) {
+      const nextStep = hadNext ? this.tracker?.getCurrentStep() : null;
+      const nextMsg = nextStep ? t("exec.step_gate_ok", {
+        step: String(step.id),
+        nextStep: String(nextStep.id),
+        nextDesc: nextStep.description
+      }) : t("exec.step_gate_last", { step: String(step.id) });
+      contextManager.addMessage({
+        role: "user",
+        content: `<system-summary>${nextMsg}</system-summary>`
+      });
     }
   }
 }
-var STUCK_RECOVERY_COOLDOWN = 5;
+var STUCK_RECOVERY_COOLDOWN = 5, MAX_PLAN_WARNINGS_BEFORE_BLOCK = 3;
 var init_module = __esm(() => {
   init_i18n();
   init_tracker();
@@ -13338,7 +13440,7 @@ var init_module = __esm(() => {
 });
 
 // src/modules/security/session-encryption.ts
-import { readFileSync as readFileSync15, writeFileSync as writeFileSync10, existsSync as existsSync27, readdirSync as readdirSync6, unlinkSync as unlinkSync3 } from "fs";
+import { readFileSync as readFileSync16, writeFileSync as writeFileSync10, existsSync as existsSync27, readdirSync as readdirSync6, unlinkSync as unlinkSync3 } from "fs";
 import { join as join19 } from "path";
 import { homedir as homedir8 } from "os";
 
@@ -13388,7 +13490,7 @@ class SessionFileEncryptor {
     return lines.map((line) => this.decryptFileContent(line));
   }
   readSessionFile(filePath) {
-    const content = readFileSync15(filePath, "utf8");
+    const content = readFileSync16(filePath, "utf8");
     return this.decryptFileContent(content);
   }
   writeSessionFile(filePath, content) {
@@ -13396,7 +13498,7 @@ class SessionFileEncryptor {
     writeFileSync10(filePath, encrypted, "utf8");
   }
   readSessionJSON(filePath) {
-    const content = readFileSync15(filePath, "utf8");
+    const content = readFileSync16(filePath, "utf8");
     return this.decryptJSON(content);
   }
   writeSessionJSON(filePath, obj) {
@@ -13404,7 +13506,7 @@ class SessionFileEncryptor {
     writeFileSync10(filePath, content, "utf8");
   }
   readSessionJSONL(filePath) {
-    const content = readFileSync15(filePath, "utf8");
+    const content = readFileSync16(filePath, "utf8");
     const lines = content.split(`
 `).filter((line) => line.trim());
     const decryptedLines = this.decryptJSONL(lines);
@@ -13423,7 +13525,7 @@ class SessionFileEncryptor {
       const filePath = join19(sessionDir, file);
       if (existsSync27(filePath) && !file.endsWith(".enc")) {
         try {
-          const content = readFileSync15(filePath, "utf8");
+          const content = readFileSync16(filePath, "utf8");
           const encrypted = this.encryptFileContent(content);
           writeFileSync10(filePath + ".enc", encrypted, "utf8");
           unlinkSync3(filePath);
@@ -13440,7 +13542,7 @@ class SessionFileEncryptor {
         const encFilePath = join19(sessionDir, file);
         const decFilePath = encFilePath.slice(0, -4);
         try {
-          const content = readFileSync15(encFilePath, "utf8");
+          const content = readFileSync16(encFilePath, "utf8");
           const decrypted = this.decryptFileContent(content);
           writeFileSync10(decFilePath, decrypted, "utf8");
           unlinkSync3(encFilePath);
@@ -13465,7 +13567,7 @@ import {
   existsSync as existsSync28,
   mkdirSync as mkdirSync12,
   readdirSync as readdirSync7,
-  readFileSync as readFileSync16,
+  readFileSync as readFileSync17,
   rmSync,
   writeFileSync as writeFileSync11,
   appendFileSync as appendFileSync5
@@ -13525,7 +13627,7 @@ class SessionStore {
     if (!existsSync28(path))
       return null;
     try {
-      const raw = readFileSync16(path, "utf-8");
+      const raw = readFileSync17(path, "utf-8");
       const content = this.encryptor ? this.encryptor.decryptFileContent(raw) : raw;
       return JSON.parse(content);
     } catch {
@@ -13555,7 +13657,7 @@ class SessionStore {
     if (!existsSync28(path))
       return [];
     try {
-      const raw = readFileSync16(path, "utf-8");
+      const raw = readFileSync17(path, "utf-8");
       const lines = raw.split(`
 `).filter(Boolean);
       if (this.encryptor?.isEnabled()) {
@@ -13584,7 +13686,7 @@ class SessionStore {
     if (!existsSync28(path))
       return [];
     try {
-      const raw = readFileSync16(path, "utf-8");
+      const raw = readFileSync17(path, "utf-8");
       const lines = raw.split(`
 `).filter(Boolean);
       if (this.encryptor?.isEnabled()) {
@@ -13626,7 +13728,7 @@ class SessionStore {
       if (updatedAt < thirtyDaysAgo) {
         const historyPath = this.historyPath(session2.id);
         if (existsSync28(historyPath)) {
-          const content = readFileSync16(historyPath, "utf-8");
+          const content = readFileSync17(historyPath, "utf-8");
           const compressed = gzipSync(content);
           const gzPath = join20(this.baseDir, `${session2.id}.jsonl.gz`);
           writeFileSync11(gzPath, compressed);
@@ -13835,7 +13937,7 @@ class ProfileCompressor {
 }
 
 // src/modules/user-profile/profile.ts
-import { readFileSync as readFileSync17, writeFileSync as writeFileSync12, existsSync as existsSync29, mkdirSync as mkdirSync13 } from "fs";
+import { readFileSync as readFileSync18, writeFileSync as writeFileSync12, existsSync as existsSync29, mkdirSync as mkdirSync13 } from "fs";
 import { join as join21 } from "path";
 import { homedir as homedir9, hostname, platform as platform4, type } from "os";
 import { env } from "process";
@@ -13870,7 +13972,7 @@ class UserProfile {
     if (!existsSync29(path))
       return null;
     try {
-      const data = JSON.parse(readFileSync17(path, "utf-8"));
+      const data = JSON.parse(readFileSync18(path, "utf-8"));
       this.info = {
         platform: data.platform,
         os: data.os,
@@ -13905,7 +14007,7 @@ class UserProfile {
 var init_profile = () => {};
 
 // src/modules/skills/loader.ts
-import { readdirSync as readdirSync8, readFileSync as readFileSync18, existsSync as existsSync30, statSync as statSync5 } from "fs";
+import { readdirSync as readdirSync8, readFileSync as readFileSync19, existsSync as existsSync30, statSync as statSync5 } from "fs";
 import { join as join22 } from "path";
 
 class SkillsLoader {
@@ -13927,7 +14029,7 @@ class SkillsLoader {
       }
       if (!entry.endsWith(".md") && !entry.endsWith(".skill.md"))
         continue;
-      const content = readFileSync18(fullPath, "utf-8");
+      const content = readFileSync19(fullPath, "utf-8");
       const parsed = this.parseSkillFile(content, fullPath);
       if (parsed)
         skills.push(parsed);
@@ -14199,7 +14301,7 @@ var init_browser2 = __esm(() => {
 });
 
 // src/modules/indexer/walker.ts
-import { readdirSync as readdirSync9, readFileSync as readFileSync19, statSync as statSync6, existsSync as existsSync31, watch } from "fs";
+import { readdirSync as readdirSync9, readFileSync as readFileSync20, statSync as statSync6, existsSync as existsSync31, watch } from "fs";
 import { join as join23, relative, extname as extname5 } from "path";
 
 class Indexer {
@@ -14249,7 +14351,7 @@ class Indexer {
           const ext = extname5(entry).toLowerCase();
           const language = LANGUAGES[ext];
           if (language) {
-            const content = readFileSync19(fullPath, "utf-8");
+            const content = readFileSync20(fullPath, "utf-8");
             const exports = this.extractExports(content, language);
             files.push({ path: relPath, language, exports, size: stat.size });
             totalSize += stat.size;
@@ -14301,7 +14403,7 @@ var init_walker = __esm(() => {
 });
 
 // src/modules/indexer/cache.ts
-import { readFileSync as readFileSync20, writeFileSync as writeFileSync13, existsSync as existsSync32, mkdirSync as mkdirSync14, rmSync as rmSync2 } from "fs";
+import { readFileSync as readFileSync21, writeFileSync as writeFileSync13, existsSync as existsSync32, mkdirSync as mkdirSync14, rmSync as rmSync2 } from "fs";
 import { join as join24 } from "path";
 
 class IndexCache {
@@ -14316,7 +14418,7 @@ class IndexCache {
     if (!existsSync32(this.cachePath))
       return null;
     try {
-      this.cache = JSON.parse(readFileSync20(this.cachePath, "utf-8"));
+      this.cache = JSON.parse(readFileSync21(this.cachePath, "utf-8"));
       return this.cache;
     } catch {
       return null;
@@ -14743,7 +14845,7 @@ __export(exports_bootstrap, {
 });
 import { homedir as homedir11 } from "os";
 import { join as join26, resolve as resolve15 } from "path";
-import { existsSync as existsSync33, readFileSync as readFileSync21, writeFileSync as writeFileSync14 } from "fs";
+import { existsSync as existsSync33, readFileSync as readFileSync22, writeFileSync as writeFileSync14 } from "fs";
 function buildSystemInfo(config, baseDir, profileCompressed) {
   const now = new Date().toISOString().replace("T", " ").slice(0, 19);
   const isWin = profileCompressed.toLowerCase().includes("win32");
@@ -14765,9 +14867,10 @@ function buildSystemInfo(config, baseDir, profileCompressed) {
   if (isWin) {
     lines.push(``, `Windows environment — use Windows-compatible commands:`, `- Use "dir" instead of "ls". Use "dir /b" for bare listing.`, `- Use "type" or "Get-Content" instead of "cat".`, `- Use "cd" instead of "pwd". Use "echo %cd%" to print working directory.`, `- Use "copy" instead of "cp", "move" instead of "mv", "del" instead of "rm".`, `- Do not use "mkdir -p" — Windows mkdir creates intermediate dirs by default. Use the create_dir tool instead.`, `- Use forward slashes (/) or escaped backslashes (\\\\) in file paths.`, `- Your working directory is: ${baseDir}`);
   }
-  lines.push(``, `Bash tool rules:`, `- Use the "workdir" parameter to run commands in a specific directory. Do NOT chain "cd dir && cmd" — the security module blocks the "&&" operator.`, `- Run one command per tool call. Split multi-step shell operations into separate bash calls.`);
+  lines.push(``, `Bash tool rules:`, `- Use the "workdir" parameter to run commands in a specific directory. Do NOT chain "cd dir && cmd" — the security module blocks the "&&" operator.`, `- Run one command per tool call. Split multi-step shell operations into separate bash calls.`, `- Background processes (dev servers, watchers, long-running npm install): use the "background: true" parameter or the tool will auto-detect and background them. Check output with process_log.`);
+  lines.push(``, `=== DEVELOPMENT RULES — follow these strictly ===`, ``, `1. DEPENDENCIES FIRST: Before writing any source code, ALWAYS install project dependencies (e.g., "npm install", "pip install -r requirements.txt", "cargo build", "go mod tidy"). Verify the package manager's lock file or dependency directory exists. Never write code that imports/uses packages that aren't installed yet.`, `2. TOOLKIT/FWK FIRST: If the task specifies a framework or UI library, initialize and configure it BEFORE writing application code. Run its project init command first, then add components/modules. Never write your own version of what the framework already provides.`, `3. ONE STEP AT A TIME: Follow the plan sequentially. Complete step N before starting step N+1. When a step is done: verify the deliverables exist and have real content (not empty), then call "plan update step=N status=done". Do not redo completed work.`, `4. VERIFY YOUR WORK: After creating/modifying files, verify they exist on disk. After installing dependencies, verify the package manager completed successfully. After any command, check its output for errors. Don't assume operations succeeded.`, `5. NO PREMATURE WORK: Do not create files for future steps. Do not add imports/references to packages or modules that haven't been installed yet. Do not reference files or components that don't exist yet. Build incrementally — one layer at a time.`, `6. WHEN STUCK: If a command fails 2+ times, STOP and try a different approach. Write files directly instead of using commands. Ask the user for help. Never repeat the same failing command more than twice.`);
   if (config.autoPlan) {
-    lines.push(``, `Plan rule: For complex tasks with 3+ steps, you may create a plan using the "plan" tool. For simple questions, just answer directly.`);
+    lines.push(``, `Plan rule (MANDATORY): For ANY task that requires creating files, installing packages, or multiple actions — you MUST create a plan using the "plan" tool BEFORE starting work. Each step must describe a concrete deliverable (specific files to create, packages to install, commands to run). Do not combine unrelated work into one step.`);
   }
   const hasMCP = config.mcpServers && Object.values(config.mcpServers).some((s) => s.enabled !== false);
   if (hasMCP) {
@@ -14975,7 +15078,7 @@ async function bootstrap(configDir, projectDir, noAgentsMd, exitOnComplete) {
     ];
     for (const p of agentsMdCandidates) {
       if (existsSync33(p)) {
-        const content = readFileSync21(p, "utf-8").trim();
+        const content = readFileSync22(p, "utf-8").trim();
         if (content) {
           agentsMdBlocks.push({
             content,
@@ -15810,7 +15913,7 @@ async function runSetup() {
 init_i18n();
 import { join as join28, dirname as dirname9 } from "path";
 import { homedir as homedir13 } from "os";
-import { existsSync as existsSync34, readFileSync as readFileSync22 } from "fs";
+import { existsSync as existsSync34, readFileSync as readFileSync23 } from "fs";
 
 // src/cli/security-commands.ts
 init_bootstrap();
@@ -16411,7 +16514,7 @@ function readVersion() {
   ];
   for (const p of candidates) {
     if (existsSync34(p)) {
-      const raw = JSON.parse(readFileSync22(p, "utf8"));
+      const raw = JSON.parse(readFileSync23(p, "utf8"));
       if (raw.version)
         return raw.version;
     }
@@ -16574,7 +16677,7 @@ init_bootstrap();
 // src/cli/repl.ts
 init_colors();
 import * as readline3 from "readline";
-import { existsSync as existsSync35, readFileSync as readFileSync23, writeFileSync as writeFileSync15 } from "fs";
+import { existsSync as existsSync35, readFileSync as readFileSync24, writeFileSync as writeFileSync15 } from "fs";
 import { join as join29, dirname as dirname10 } from "path";
 import { homedir as homedir14 } from "os";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -17030,7 +17133,7 @@ function readVersion2() {
   ];
   for (const p of candidates) {
     if (existsSync35(p)) {
-      const raw = JSON.parse(readFileSync23(p, "utf8"));
+      const raw = JSON.parse(readFileSync24(p, "utf8"));
       if (raw.version)
         return raw.version;
     }
@@ -17123,7 +17226,7 @@ class Repl {
   loadHistory() {
     if (existsSync35(this.historyPath)) {
       try {
-        const raw = readFileSync23(this.historyPath, "utf-8");
+        const raw = readFileSync24(this.historyPath, "utf-8");
         this.history = raw.split(`
 `).filter(Boolean).slice(-this.maxHistory);
       } catch {

package/dist/skills/builtin/builtin/git.md

@@ -0,0 +1,36 @@
+---
+name: git-expert
+description: Git branching, merge conflicts, rebasing, workflow strategies
+keywords: [git, branch, merge, rebase, commit, conflict, workflow]
+mma_version: 2
+---
+
+# Git Expert
+
+## Branching Strategies
+
+- **Feature branches**: `feature/xxx` from `main`, merge via PR
+- **Hotfix**: `hotfix/xxx` from `main`, merge to both `main` and `develop`
+- **Release**: `release/xxx` from `develop`, merge to `main` + `develop`
+
+## Conflict Resolution
+
+1. `git fetch origin` — get latest
+2. `git checkout your-branch`
+3. `git rebase origin/main` — apply your commits on top
+4. Resolve conflicts file by file
+5. `git add <files>` then `git rebase --continue`
+
+## Useful Commands
+
+- `git log --oneline --graph --all` — visualize history
+- `git diff --stat` — summary of changes
+- `git stash pop` — restore stashed changes
+- `git cherry-pick <commit>` — apply specific commit
+
+## Best Practices
+
+- Commit often with clear messages
+- Keep commits atomic (one logical change)
+- Never force push to shared branches
+- Use `git rebase -i` to clean up before PR

package/dist/skills/builtin/builtin/typescript.md

@@ -0,0 +1,35 @@
+---
+name: typescript-expert
+description: TypeScript type system, generics, advanced patterns, compiler API
+keywords: [typescript, types, generics, tsconfig, compiler, interface, type]
+mma_version: 2
+---
+
+# TypeScript Expert
+
+## Key Patterns
+
+- Use `readonly` for immutable properties
+- Prefer `interface` over `type` for object shapes
+- Use `as const` for literal types
+- Prefer `unknown` over `any` for type safety
+
+## Common Pitfalls
+
+- Avoid `any` — use `unknown` + type guards
+- Don't use `enum` — use `const` objects or union types
+- Avoid `namespace` — use ES modules
+
+## Type Guards
+
+```ts
+function isString(val: unknown): val is string {
+  return typeof val === 'string'
+}
+```
+
+## Generics
+
+- Use `extends` for constraints
+- Use `infer` for conditional type extraction
+- Prefer explicit over implicit for complex cases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micro-models-agent",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "Micro Models Agent (MMA) — LLM agent harness for small models (Qwen3.5-9B, 32K-64K context)",
   "type": "module",
   "bin": {