mixdog 0.8.0 → 0.9.0

package/src/output-styles/default.md

@@ -1,38 +1,22 @@
 ---
 name: default
-description: Default concise engineering replies
+title: Summary
+description: Concise engineering summaries
 keep-coding-instructions: true
 ---
 
 # Output Style
 
-Default concise engineering replies. Technical substance stays; fluff dies.
-Uniformity beats local cleverness.
+Mixdog default — concise engineering summaries.
 
-- Answer first. No pleasantries, hedging, task restatement, or tool narration.
-- One answer only. Do not repeat the conclusion in a second paragraph or trailing
-  sentence.
-- Tool work: one short intent line, then batch silently. For long chains, one
-  checkpoint only: learned + next.
-- Default final: one sentence. If crowded, max 2 flat bullets. Code-change final:
-  max 3 flat bullets, but prefer one sentence with semicolons. Omit empty fields.
-- Hard cap user-visible replies at 2 short sentences unless the user asks for
-  detail. If a previous reply was too long, answer with one short sentence.
-- Keep the same shape for the same task type: explanation = one sentence;
-  implementation = changed + verified in one sentence; diagnosis = cause +
-  evidence + fix in one sentence.
-- No report headings/labels, nested bullets, tables, numbered lists, tool traces,
-  searched-path lists, agent/model/session metadata, timings, or token counts
-  unless user asks or it is decisive evidence.
-- Do not use label prefixes such as `Changed:`, `Verified:`, `변경:`, `검증:`,
-  `원인:`, or `결론:`. Use plain clauses instead.
-- Bridge/agent results: synthesize outcome; never forward full report.
-- Explore/retrieval results are evidence only; do not paste their bullets or file
-  lists into the answer unless the user explicitly asked for candidates/details.
+- Lead with the outcome plus a single decisive piece of evidence: a path,
+  command, error, or verification result. Drop everything non-essential.
+- Use labels such as `바뀐 점`, `확인한 것`, and `남은 리스크/다음 단계`
+  only in final reports; do not add titles/labels to interim progress text.
+- Collapse trivial tasks to a single short sentence.
+- Synthesize agent or retrieval results; never forward raw reports, long file
+  lists, tool traces, or session metadata.
+- Do not hide blockers, failed verification, or required follow-up; surface them
+  in one short clause rather than omitting them.
 - Keep paths, commands, symbols, API names, code, and exact errors verbatim.
-  Localize prose only.
-- Quote only the shortest decisive error. No raw logs or long file lists unless
-  asked.
-- Relax compression for security, destructive actions, ambiguity, or user
-  confusion.
 - Never name this style unless asked.

package/src/output-styles/extreme-simple.md

@@ -8,10 +8,13 @@ keep-coding-instructions: true
 
 # Output Style
 
-Extreme simple completion replies.
+Extreme — one ultra-short completion sentence. The most minimal of the styles.
 
-- Reply with one ultra-short completion sentence whenever possible.
-- Preferred completion pattern: `<target> 변경되었습니다. <verification> 통과 완료입니다.`
-- If verification was not run, use one short sentence that says the change is done and verification was not run.
-- Avoid headings, bullets, labels, explanations, tool traces, and metadata unless the user explicitly asks.
-- Preserve exact paths, commands, symbols, API names, code, and errors when they are the only decisive detail.
+- Reply with a single completion sentence whenever possible.
+- Preferred pattern: `<target> 변경되었습니다. <verification> 통과 완료입니다.`
+- If verification was not run, use one short sentence saying the change is done
+  and verification was not run.
+- No headings, bullets, labels, explanations, tool traces, or metadata unless
+  the user explicitly asks.
+- Preserve only the single decisive path, command, symbol, API name, code, or
+  error verbatim.

package/src/output-styles/simple.md

@@ -1,17 +1,30 @@
 ---
 name: simple
-title: Simple
-description: 1-2 concise sentences
+title: Practical Concise
+description: Outcome-first concise handoffs for coding work
+aliases: summary, concise, handoff
 keep-coding-instructions: true
 ---
 
 # Output Style
 
-Simple concise replies.
+Practical concise — outcome-first handoffs for coding work without report bloat.
 
-- Answer in 1-2 concise sentences by default.
-- Keep technical substance, paths, commands, symbols, API names, code, and exact errors verbatim.
-- Use bullets only when a sentence would become crowded.
-- Avoid headings, labels, nested bullets, tool traces, and metadata unless the user asks.
-- For code changes, say what changed and the decisive verification in one short sentence when possible.
-- If verification was not run, say so briefly.
+- Open with the outcome in one sentence: done, blocked, or awaiting a decision.
+- Add only high-signal evidence next: changed paths (use `file_path:line_number`
+  when it helps navigation), commands, lint/test results, or the exact error —
+  not step-by-step narration.
+- Keep controlled detail: usually 1–3 short bullets or 2–4 sentences total.
+  Expand only when the user asks, scope is ambiguous, or a blocker needs concrete
+  next steps.
+- On final handoffs, optional labels such as `바뀐 점`, `확인한 것`, and
+  `남은 리스크/다음 단계` fit Korean-facing profiles; use plain English labels
+  when the thread is English. Do not label interim progress.
+- Synthesize agent or retrieval results; never forward raw reports, long file
+  lists, tool traces, or session metadata.
+- Do not hide blockers, failed verification, or required follow-up; state them
+  in one short clause.
+- Keep paths, commands, symbols, API names, code, and exact errors verbatim.
+- Skip filler, acknowledgments, and repeated conclusions; if verification was
+  not run, say so once.
+- Never name this style unless asked.

package/src/repl.mjs

@@ -25,37 +25,42 @@ import { stdin, stdout } from 'node:process';
 import { basename } from 'node:path';
 
 import { bold, dim, cyan, green, red, yellow, colorEnabled } from './ui/ansi.mjs';
-import { renderMarkdown } from './ui/markdown.mjs';
-import { renderToolCard } from './ui/tool-card.mjs';
-import { createSessionStats, applyUsageDelta, renderStatusline } from './ui/statusline.mjs';
-import { createMixdogSessionRuntime } from './mixdog-session-runtime.mjs';
-import { installProcessSignalCleanup } from './runtime/shared/process-shutdown.mjs';
-
-/** Help text shared by `--help` and the `/help` slash command. */
-const HELP_LINES = [
-  'mixdog — standalone mixdog CLI/TUI coding agent.',
-  '',
-  'Usage:',
-  '  mixdog [--provider <name>] [--model <name>] [--readonly]',
-  '  mixdog --help',
-  '',
-  'Slash commands (inside the REPL):',
-  '  /help              show this help',
-  '  /clear             reset the conversation and clear the screen',
-  '  /compact           compact older conversation context',
-  '  /model <name>      switch model/preset for subsequent turns',
-  '  /OutputStyle [name] show or switch Lead output style',
-  '  /mode <name>       switch tool surface: full | readonly',
-  '  /exit              quit',
-  '',
-  'History: use ↑ / ↓ to recall previous inputs.',
-];
-
-/** Print the `--help` text. Routed here so app.mjs stays untouched. */
-export function printHelp(write = (s) => stdout.write(s)) {
-  write(HELP_LINES.join('\n') + '\n');
+import { printHelp } from './help.mjs';
+import { createSessionStats, applyUsageDelta } from './ui/session-stats.mjs';
+
+let runtimeModulePromise = null;
+let markdownModulePromise = null;
+let toolCardModulePromise = null;
+let statuslineModulePromise = null;
+let shutdownModulePromise = null;
+
+function loadRuntimeModule() {
+  runtimeModulePromise ??= import('./mixdog-session-runtime.mjs');
+  return runtimeModulePromise;
+}
+
+async function renderMarkdownLazy(text) {
+  const mod = await (markdownModulePromise ??= import('./ui/markdown.mjs'));
+  return mod.renderMarkdown(text);
+}
+
+async function renderToolCardLazy(call) {
+  const mod = await (toolCardModulePromise ??= import('./ui/tool-card.mjs'));
+  return mod.renderToolCard(call);
+}
+
+async function renderStatuslineLazy(opts) {
+  const mod = await (statuslineModulePromise ??= import('./ui/statusline.mjs'));
+  return mod.renderStatusline(opts);
 }
 
+async function loadShutdownModule() {
+  shutdownModulePromise ??= import('./runtime/shared/process-shutdown.mjs');
+  return shutdownModulePromise;
+}
+
+export { printHelp };
+
 export async function runRepl({ provider: providerName, model, toolMode = 'full' } = {}) {
   // `--help` short-circuits before any provider init so the smoke test (which
   // invokes `src/cli.mjs --help`) gets clean help output and a 0 exit. We read
@@ -65,19 +70,44 @@ export async function runRepl({ provider: providerName, model, toolMode = 'full'
     return 0;
   }
 
-  const runtime = await createMixdogSessionRuntime({ provider: providerName, model, toolMode });
   const stats = createSessionStats();
   const cwd = process.cwd();
   let rl = null;
+  let runtime = null;
+  let runtimePromise = null;
   let closed = false;
+
+  const ensureRuntime = async () => {
+    if (closed) throw new Error('runtime closed');
+    if (runtime) return runtime;
+    if (!runtimePromise) {
+      runtimePromise = (async () => {
+        const { createMixdogSessionRuntime } = await loadRuntimeModule();
+        const next = await createMixdogSessionRuntime({ provider: providerName, model, toolMode });
+        runtime = next;
+        return next;
+      })().finally(() => {
+        runtimePromise = null;
+      });
+    }
+    const next = await runtimePromise;
+    if (closed) {
+      try { await next.close('cli-exit'); } catch {}
+      if (runtime === next) runtime = null;
+      throw new Error('runtime closed');
+    }
+    return next;
+  };
+
   const closeRuntime = async (reason = 'cli-exit') => {
     if (closed) return;
     closed = true;
     try { rl?.close(); } catch {}
-    await runtime.close(reason);
+    const pendingRuntime = runtime || (runtimePromise ? await runtimePromise.catch(() => null) : null);
+    if (pendingRuntime) await pendingRuntime.close(reason);
   };
 
-  printBanner(runtime.provider, runtime.model, cwd, runtime.toolMode);
+  printBanner(providerName, model, cwd, toolMode);
 
   rl = createInterface({
     input: stdin,
@@ -86,6 +116,7 @@ export async function runRepl({ provider: providerName, model, toolMode = 'full'
     // historySize > 0 enables readline's built-in ↑/↓ recall of prior inputs.
     historySize: 200,
   });
+  const { installProcessSignalCleanup } = await loadShutdownModule();
   const signalCleanup = installProcessSignalCleanup({
     name: 'mixdog-repl',
     timeoutMs: 6500,
@@ -110,9 +141,13 @@ export async function runRepl({ provider: providerName, model, toolMode = 'full'
       if (line.startsWith('/')) {
         const handled = await handleSlash(line, {
           rl,
-          runtime,
+          ensureRuntime,
+          getRuntime: () => runtime,
           stats,
           cwd,
+          providerName,
+          model,
+          toolMode,
           closeRuntime,
         });
         if (handled === 'exit') {
@@ -128,11 +163,12 @@ export async function runRepl({ provider: providerName, model, toolMode = 'full'
       let streamedText = '';
       let printedAny = false;
       try {
+        const runtime = await ensureRuntime();
         const { result } = await runtime.ask(
           line,
           {
             onToolCall: async (_iter, calls) => {
-            for (const c of calls || []) stdout.write('\n' + renderToolCard(c) + '\n');
+              for (const c of calls || []) stdout.write('\n' + (await renderToolCardLazy(c)) + '\n');
           },
             onTextDelta: (chunk) => {
               printedAny = true;
@@ -152,10 +188,10 @@ export async function runRepl({ provider: providerName, model, toolMode = 'full'
         if (finalText) {
           if (printedAny && colorEnabled()) {
             eraseStreamedBlock(streamedText);
-            stdout.write(renderMarkdown(finalText) + '\n');
+            stdout.write(await renderMarkdownLazy(finalText) + '\n');
           } else if (!printedAny) {
             // Nothing streamed live (provider without onTextDelta) — render once.
-            stdout.write(renderMarkdown(finalText) + '\n');
+            stdout.write(await renderMarkdownLazy(finalText) + '\n');
           } else {
             // Non-TTY / NO_COLOR: leave the raw stream, just terminate the line.
             stdout.write('\n');
@@ -163,7 +199,7 @@ export async function runRepl({ provider: providerName, model, toolMode = 'full'
         }
 
         // Per-turn statusline footer.
-        stdout.write('\n' + (await renderStatusline({
+        stdout.write('\n' + (await renderStatuslineLazy({
           provider: runtime.provider,
           model: runtime.model,
           cwd,
@@ -195,7 +231,9 @@ function promptText() {
 
 function printBanner(providerName, model, cwd, toolMode) {
   const title = bold('mixdog');
-  const id = cyan(`${providerName}/${model}`);
+  const providerLabel = providerName || 'auto';
+  const modelLabel = model || 'default';
+  const id = cyan(`${providerLabel}/${modelLabel}`);
   stdout.write(`${title} ${dim('—')} ${id} ${dim('·')} ${dim(toolMode)} ${dim('·')} ${dim(basename(cwd))}\n`);
   stdout.write(dim('Type a message, or /help for commands. Ctrl+C to exit.') + '\n\n');
 }
@@ -236,63 +274,80 @@ async function handleSlash(line, ctx) {
       return;
 
     case 'clear':
-      await ctx.runtime.clear();
       {
+        const runtime = await ctx.ensureRuntime();
+        await runtime.clear();
         const fresh = createSessionStats();
         for (const k of Object.keys(fresh)) ctx.stats[k] = fresh[k];
+        // Clear screen + scrollback and home the cursor.
+        stdout.write(colorEnabled() ? '\x1b[2J\x1b[3J\x1b[H' : '\n');
+        stdout.write(dim('conversation reset.') + '\n');
+        stdout.write((await renderStatuslineLazy({
+          provider: runtime.provider,
+          model: runtime.model,
+          cwd: ctx.cwd,
+          stats: ctx.stats,
+          contextWindow: runtime.contextWindow,
+          rawContextWindow: runtime.rawContextWindow,
+        })) + '\n');
       }
-      // Clear screen + scrollback and home the cursor.
-      stdout.write(colorEnabled() ? '\x1b[2J\x1b[3J\x1b[H' : '\n');
-      stdout.write(dim('conversation reset.') + '\n');
-      stdout.write((await renderStatusline({
-        provider: ctx.runtime.provider,
-        model: ctx.runtime.model,
-        cwd: ctx.cwd,
-        stats: ctx.stats,
-        contextWindow: ctx.runtime.contextWindow,
-        rawContextWindow: ctx.runtime.rawContextWindow,
-      })) + '\n');
       return;
 
     case 'compact':
       {
-        const r = await ctx.runtime.compact();
+        const runtime = await ctx.ensureRuntime();
+        const r = await runtime.compact();
         if (!r) {
           stdout.write(yellow('compact failed') + '\n');
           return;
         }
+        if (r.error) {
+          stdout.write(red('compact failed') + '\n');
+          return;
+        }
         if (r.changed === false && r.reason) {
           stdout.write(yellow(r.reason) + '\n');
           return;
         }
+        if (r.changed === false) {
+          stdout.write(yellow('nothing to compact') + '\n');
+          return;
+        }
         stdout.write(green(`✓ compacted context: ${r.beforeMessages}→${r.afterMessages} messages, context ${r.beforeTokens}→${r.afterTokens}`) + '\n');
       }
       return;
 
     case 'model':
       if (!arg) {
-        stdout.write(yellow(`current model: ${ctx.runtime.provider}/${ctx.runtime.model}`) + '\n');
+        const runtime = ctx.getRuntime?.();
+        const provider = runtime?.provider || ctx.providerName || 'auto';
+        const currentModel = runtime?.model || ctx.model || 'default';
+        stdout.write(yellow(`current model: ${provider}/${currentModel}`) + '\n');
         stdout.write(dim('usage: /model <preset-or-model>') + '\n');
         return;
       }
-      await ctx.runtime.setRoute({ model: arg });
-      stdout.write(green(`✓ model → ${ctx.runtime.provider}/${ctx.runtime.model}`) + '\n');
+      {
+        const runtime = await ctx.ensureRuntime();
+        await runtime.setRoute({ model: arg });
+        stdout.write(green(`✓ model → ${runtime.provider}/${runtime.model}`) + '\n');
+      }
       return;
 
     case 'outputstyle':
     case 'output-style':
     case 'style':
       {
+        const runtime = await ctx.ensureRuntime();
         const lower = arg.toLowerCase();
         if (!arg || lower === 'status' || lower === 'current' || lower === 'show') {
-          const status = ctx.runtime.getOutputStyle?.() || ctx.runtime.listOutputStyles?.();
+          const status = runtime.getOutputStyle?.() || runtime.listOutputStyles?.();
           const label = status?.current?.label || status?.current?.id || status?.configured || 'Default';
           const available = (status?.styles || []).map((style) => style.label || style.id).join(', ');
           stdout.write(yellow(`current output style: ${label}`) + '\n');
           if (available) stdout.write(dim(`available: ${available}`) + '\n');
           return;
         }
-        const result = await ctx.runtime.setOutputStyle(arg);
+        const result = await runtime.setOutputStyle(arg);
         const label = result?.current?.label || result?.current?.id || arg;
         const suffix = result?.appliedToCurrentSession === false ? ' (use /clear to apply to this chat)' : '';
         stdout.write(green(`✓ output style → ${label}${suffix}`) + '\n');
@@ -301,12 +356,16 @@ async function handleSlash(line, ctx) {
 
     case 'mode':
       if (!arg) {
-        stdout.write(yellow(`current mode: ${ctx.runtime.toolMode}`) + '\n');
+        const runtime = ctx.getRuntime?.();
+        stdout.write(yellow(`current mode: ${runtime?.toolMode || ctx.toolMode}`) + '\n');
         stdout.write(dim('usage: /mode full|readonly') + '\n');
         return;
       }
-      await ctx.runtime.setToolMode(arg);
-      stdout.write(green(`✓ mode → ${ctx.runtime.toolMode}`) + '\n');
+      {
+        const runtime = await ctx.ensureRuntime();
+        await runtime.setToolMode(arg);
+        stdout.write(green(`✓ mode → ${runtime.toolMode}`) + '\n');
+      }
       return;
 
     case 'exit':

package/src/rules/agent/00-common.md

@@ -0,0 +1,15 @@
+# Agent Constraints
+
+- Use English for agent task communication.
+- Do not touch git/Ship. Even when the brief instructs `git add` / `commit` /
+  `push` / `stash`, refuse with `git operations deferred to Lead`.
+- NEVER PREAMBLE. Do not generate preamble tokens, including tool-call
+  preambles, status/progress narration, "I will..." setup text, or transition
+  text before tool calls.
+- If tools are needed, call them immediately. Emit text only for the final
+  handoff after tool work is done.
+- Final output style: follow the role's stricter output contract when one is
+  defined; otherwise write a compact English handoff for Lead: outcome, key
+  files, verification, and only material risks. Avoid report-style headings,
+  markdown tables unless explicitly requested, long narration, raw logs, and
+  unnecessary next-checks.

package/src/rules/{bridge → agent}/20-skip-protocol.md

@@ -1,6 +1,6 @@
 # Skip Protocol
 
-For inbound-event bridge reports (`webhook-handler`, `scheduler-task`):
+For inbound-event agent reports (`webhook-handler`, `scheduler-task`):
 if Lead has nothing actionable to relay
 (label-only, duplicate/dedup, no action needed, nothing to report),
 prefix the whole response with:
@@ -8,4 +8,3 @@ prefix the whole response with:
 ```
 [meta:silent]
 ```
-

package/src/rules/agent/30-explorer.md

@@ -0,0 +1,22 @@
+---
+permission: read
+toolSchemaProfile: read
+kind: retrieval
+---
+
+# Role: explorer
+
+Locator only. Find likely file/symbol/line anchors for the query; do not
+analyze, debug, decide, or recommend.
+
+Output only:
+- `path:line — symbol/name — short reason`
+- or `EXPLORATION_FAILED`
+
+No preambles, including tool-call preambles. No bullets, headings, summaries,
+code quotes, verdicts, or invented coordinates; output anchor lines only.
+Prompt queries need exact function/prompt anchors. Weak anchors: `?`.
+
+Work fast: maximize independent read-only fan-out in every lookup turn. Once
+credible anchors are found, you must stop; do not call another tool or
+broaden/verify.

package/src/rules/{bridge → agent}/40-cycle1-agent.md

@@ -1,3 +1,10 @@
+---
+permission: read
+toolSchemaProfile: none
+kind: maintenance
+maintKey: memory
+---
+
 # Role: cycle1-agent
 
 Turn numbered chat rows into memory chunks.

package/src/rules/{bridge → agent}/41-cycle2-agent.md

@@ -1,3 +1,10 @@
+---
+permission: read
+toolSchemaProfile: none
+kind: maintenance
+maintKey: memory
+---
+
 # Role: cycle2-agent
 
 Backend re-scorer for `is_root` long-term memory. Input has phase,

package/src/rules/{bridge → agent}/42-cycle3-agent.md

@@ -1,3 +1,10 @@
+---
+permission: read
+toolSchemaProfile: none
+kind: maintenance
+maintKey: memory
+---
+
 # Role: cycle3-agent
 
 Reviewer for user-curated CORE memory (`core_entries`). Input shows each entry

package/src/rules/lead/01-general.md

@@ -1,5 +1,9 @@
-# General
-
-- Destructive/hard-to-reverse actions require explicit confirmation.
-- Never push, build, or deploy without an explicit user request.
-  Implementation approval is not deploy approval.
+# General
+
+- Omit direct names, honorifics, headings, and labels in preambles.
+- Preambles are optional: use them only when they add user-visible value, keep
+  them to one short sentence, and skip routine lookup narration.
+- When you emit a preamble or other user-facing lead-in, it MUST be in the user's configured response language (see Profile Preferences).
+- Destructive/hard-to-reverse actions require explicit confirmation.
+- Never push, build, or deploy without an explicit user request.
+  Implementation approval is not deploy approval.

package/src/rules/lead/04-workflow.md

@@ -1,12 +1,51 @@
-# Workflow
-
-- Lead is the supervisor of agents, responsible for task delegation,
-  coordination, judgment, and final decisions.
-- Prefer dividing work into independent scopes and delegating them concurrently
-  for faster completion.
-- After spawning an async agent, treat that agent's scope as owned by the agent:
-  do not poll status/read, send check-ins, or otherwise interfere while it works.
-- If the next Lead step depends on that spawned agent's workspace result, pause
-  only that dependent path and wait for the completion notification.
-- While waiting, continue any Lead-side work that does not require the agent's
-  result.
+# Workflow
+
+Priority:
+- When an `# Active Workflow` block is present, it is the binding session
+  workflow and takes precedence over all other workflow guidance.
+
+Delegation:
+- Lead is the supervisor of agents, responsible for task delegation,
+  coordination, judgment, and final decisions.
+- As supervisor, prefer delegating implementation work to an agent; keep direct
+  work limited to coordination and User Workflow exceptions such as
+  one-or-two-step edits, pre-planning, config changes, and final git deployment.
+- Implementation edits to product/runtime/TUI code MUST be delegated to a
+  Worker/Heavy Worker, even when small. Lead may directly edit only rules, docs,
+  config, and final deployment/git steps, unless the user explicitly asks Lead
+  to patch directly.
+- Delegation split: different code paths / entry points / file groups are
+  separate scopes — implementation AND analysis, review, debugging split the
+  same way. With 2+ independent scopes, spawn each scoped agent in the
+  SAME turn, not one after another. Shared functions or cross-cutting concerns
+  do NOT justify collapsing them into one delegation: split per path, and Lead
+  verifies the cross-cutting parts (shared state, telemetry consistency, etc.)
+  directly. "One agent must see the whole context" is not a valid reason to
+  merge; the only legitimate single-scope case is a genuinely inseparable
+  dependency — and then state the reason.
+- Follow-up work on the same path or scope MUST reuse the existing agent (same
+  tag). Spawn a new agent only for a genuinely separate scope.
+- Pick the agent role defined in the User Workflow section that fits the task
+  (worker, heavy-worker, reviewer, debugger, …) when spawning.
+- Write agent-facing briefs and follow-up task messages in English.
+- Agent briefs must be bounded: state the goal/success criteria, known starting
+  files or anchors if available, allowed/forbidden changes, expected
+  deliverable, and verification boundary. For heavy-worker, include known first
+  components to inspect and the stopping condition; complex work must not
+  become open-ended.
+
+Agent lifecycle:
+- After spawning async agent(s), END THE TURN immediately. Do not poll
+  status/read, guess the outcome, or start dependent work — treat the result as
+  unknown until the completion notification resumes you. status/read are manual
+  recovery only, never progress checks.
+- Unless instructed otherwise, wait for the spawned agent(s); once their results
+  are collected, automatically continue with the next turn.
+
+Agent result handling:
+- Cross-check material agent responses before using them for decisions or
+  summarizing them to the user.
+- When an agent returns, always synthesize its result into a concise report for
+  the user (outcome + key changes/evidence). Never forward the raw agent output.
+- If anything here conflicts with the User Workflow section, this Workflow takes
+  precedence, except that the `# Active Workflow` block always wins.

package/src/rules/lead/lead-tool.md

@@ -0,0 +1,6 @@
+# Lead Tool Use
+
+- Lead owns repo-local shell work: git, build, test, run, and verification commands.
+- Use the current project/workspace selected by the session. Only change the work project when the user asks for a different project or a tool call explicitly needs another project root.
+- Use `shell` directly for approved git/build/test/run work; do not delegate those commands to agents.
+- Use `agent` for scoped implementation, research, review, and debugging, not for git commit/push/stash or Ship.

package/src/rules/shared/01-tool.md

@@ -1,3 +1,14 @@
 # Tool Use
 
-- When multiple tool calls are independent, run them in the same tool turn.
+- Run independent tool calls in the same turn. Start source lookup with one
+  compact combined batch, not serial probes.
+- Route by clue: `explore` broad unknowns, `code_graph` symbols/deps/callers,
+  `grep` exact text, `find` path/name clues, `glob` structure, `list` dirs,
+  `read` known file windows.
+- Use available `explore` for broad/uncertain repo anchors; narrow queries.
+- Use available `search` / `web_fetch` only for web/current external info;
+  available `recall` only for history.
+- Fan out read-only lookup calls. Batch known independent files with `read`.
+- If editing is available, put related multi-file edits in one `apply_patch`.
+  Do not run state-changing edits or shell alongside other tool calls.
+- Use available `shell` only for git/build/test/run/verification, not browsing.