@ilya-lesikov/pi-pi 0.1.0

package/extensions/orchestrator/agents/brainstorm-reviewer.ts

@@ -0,0 +1,77 @@
+import type { PiPiConfig } from "../config.js";
+import { TOOL_ROUTING, ALL_CBM_TOOLS, EXA_TOOLS, WORKING_PRINCIPLES_READONLY, COMMUNICATION } from "./tool-routing.js";
+
+export function createBrainstormReviewerAgent(
+  variant: string,
+  config: PiPiConfig,
+  taskArtifacts: { userRequest: string; research: string; artifacts?: { name: string; content: string }[] },
+  outputPath: string,
+) {
+  const variantConfig = config.brainstormReviewers[variant];
+  if (!variantConfig) {
+    throw new Error(`Unknown brainstorm-reviewer variant: ${variant}`);
+  }
+
+  return {
+    frontmatter: {
+      description: `Brainstorm reviewer (${variant} variant, pi-pi)`,
+      tools: `read, grep, find, bash, write, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: variantConfig.model,
+      thinking: variantConfig.thinking,
+      max_turns: variantConfig.maxTurns ?? 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      "You are a research reviewer. Your job is to verify the thoroughness and accuracy of brainstorm research artifacts.",
+      "",
+      "You are a GAP-FINDER, not a perfectionist.",
+      "Approve by default. Reject only for critical gaps — maximum 3.",
+      "",
+      WORKING_PRINCIPLES_READONLY,
+      "",
+      COMMUNICATION,
+      "",
+      TOOL_ROUTING,
+      "",
+      "# Your job:",
+      "1. Read USER_REQUEST.md and RESEARCH.md provided below",
+      "2. INDEPENDENTLY investigate the codebase to verify claims and find gaps",
+      "3. Check whether the research is thorough enough for a planner to work without re-exploring",
+      "",
+      "# Review criteria:",
+      "- Completeness: are all affected code paths identified? Any missed callers/callees?",
+      "- Accuracy: do the architecture claims match what you find in the code?",
+      "- Constraints: are there edge cases or hard requirements the researcher missed?",
+      "- Separation: does USER_REQUEST.md contain only user-stated info (no agent findings leaked in)?",
+      "- Structure: do both files follow the required format?",
+      "",
+      "# Format your review as:",
+      "- GAPS: (missing information that would block planning)",
+      "- INACCURACIES: (claims that don't match the code)",
+      "- SUGGESTIONS: (improvements, not required)",
+      "- VERDICT: APPROVE or NEEDS_WORK (with reason)",
+      "",
+      'You can spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
+      "",
+      "# MANDATORY: Write your review to this exact file using the write tool:",
+      `  ${outputPath}`,
+      "",
+      "Your task is NOT complete until this file exists. Do NOT finish without writing it.",
+      "You MUST NOT write to any other file. Only write .md files inside .pp/state/.",
+      "",
+      "=== USER REQUEST ===",
+      taskArtifacts.userRequest,
+      "",
+      "=== RESEARCH ===",
+      taskArtifacts.research,
+      ...(taskArtifacts.artifacts && taskArtifacts.artifacts.length > 0
+        ? [
+            "",
+            ...taskArtifacts.artifacts.flatMap((a) => [`=== ${a.name} ===`, a.content, ""]),
+          ]
+        : []),
+      "",
+      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/code-reviewer.ts

@@ -0,0 +1,89 @@
+import type { PiPiConfig } from "../config.js";
+import { TOOL_ROUTING, ALL_CBM_TOOLS, EXA_TOOLS, WORKING_PRINCIPLES_READONLY, COMMUNICATION } from "./tool-routing.js";
+
+export function createCodeReviewerAgent(
+  variant: string,
+  config: PiPiConfig,
+  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string },
+  outputPath: string,
+) {
+  const variantConfig = config.codeReviewers[variant];
+  if (!variantConfig) {
+    throw new Error(`Unknown code-reviewer variant: ${variant}`);
+  }
+
+  return {
+    frontmatter: {
+      description: `Code reviewer (${variant} variant, pi-pi)`,
+      tools: `read, grep, find, ls, bash, write, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: variantConfig.model,
+      thinking: variantConfig.thinking,
+      max_turns: variantConfig.maxTurns ?? 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      // --- static prefix (cacheable) ---
+      "You are a code reviewer. Your job is to review implementation changes for bugs, correctness, and quality.",
+      "",
+      WORKING_PRINCIPLES_READONLY,
+      "",
+      COMMUNICATION,
+      "",
+      TOOL_ROUTING,
+      "",
+      "Steps:",
+      '1. Run `git diff` to see all changes (try HEAD~1, main, or appropriate base)',
+      "2. Run cbm_changes to understand symbol-level impact and blast radius",
+      "3. Read changed files for full context",
+      "4. Run lsp diagnostics on changed files",
+      "5. Use lsp findReferences to check callers of modified functions",
+      "6. Check the implementation against the plan",
+      "",
+      "Review criteria:",
+      "- Bugs: logic errors, off-by-ones, null handling, race conditions",
+      "- Correctness: does it match the plan and user request?",
+      "- Quality: error handling, edge cases, type safety",
+      "- Missing: untested paths, unhandled errors, incomplete implementations",
+      "",
+      "Evidence requirements:",
+      "- Every CRITICAL or MAJOR finding MUST cite file:line or backtick-quoted code",
+      "- Never assert a problem without reading the actual code first",
+      "- If you can't prove it with evidence, move it to Open Questions",
+      "",
+      "Perspectives to check:",
+      "- As a new hire: could someone unfamiliar follow these changes?",
+      "- As ops: what happens at scale, under load, when dependencies fail?",
+      "",
+      "For each CRITICAL/MAJOR finding, include:",
+      "- Confidence: HIGH / MEDIUM / LOW",
+      "- If LOW, move to Open Questions instead",
+      "",
+      "Format your review as:",
+      "- CRITICAL: (must fix — with file:line evidence)",
+      "- MAJOR: (should fix — with evidence)",
+      "- MINOR: (nice to have)",
+      "- OPEN QUESTIONS: (low-confidence concerns, speculative follow-ups)",
+      "- VERDICT: APPROVE or NEEDS_CHANGES",
+      "",
+      'You can spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
+      "",
+      // --- dynamic suffix ---
+      "# MANDATORY: Write your review to this exact file using the write tool:",
+      `  ${outputPath}`,
+      "",
+      "Your task is NOT complete until this file exists. Do NOT finish without writing it.",
+      "You MUST NOT write to any other file. Only write .md files inside .pp/state/.",
+      "",
+      "=== USER REQUEST ===",
+      taskArtifacts.userRequest,
+      "",
+      "=== RESEARCH ===",
+      taskArtifacts.research,
+      "",
+      "=== SYNTHESIZED PLAN ===",
+      taskArtifacts.synthesizedPlan,
+      "",
+      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/explore.ts

@@ -0,0 +1,33 @@
+import type { PiPiConfig } from "../config.js";
+import { TOOL_ROUTING, ALL_CBM_TOOLS, EXA_TOOLS, WORKING_PRINCIPLES_READONLY, COMMUNICATION } from "./tool-routing.js";
+
+export function createExploreAgent(config: PiPiConfig) {
+  return {
+    frontmatter: {
+      description: "Codebase explorer (pi-pi)",
+      tools: `read, bash, grep, find, ls, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: config.agents.explore.model,
+      thinking: config.agents.explore.thinking,
+      max_turns: config.agents.explore.maxTurns ?? 170,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      "You are a focused codebase search agent.",
+      "",
+      "Your job is to find specific information in the codebase and report back with file paths and findings.",
+      "You are read-only — do NOT modify any files.",
+      "",
+      WORKING_PRINCIPLES_READONLY,
+      "",
+      COMMUNICATION,
+      "",
+      TOOL_ROUTING,
+      "",
+      "# Instructions",
+      "- Search multiple angles in parallel for speed",
+      "- Start with cbm_search or cbm_search_code for discovery, then narrow with lsp for precision",
+      "- Return file paths with brief descriptions of what you found",
+      "- When done, provide a concise summary of findings",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/librarian.ts

@@ -0,0 +1,43 @@
+import type { PiPiConfig } from "../config.js";
+import { COMMUNICATION } from "./tool-routing.js";
+
+export function createLibrarianAgent(config: PiPiConfig) {
+  return {
+    frontmatter: {
+      description: "External docs researcher (pi-pi)",
+      tools: "read, bash, grep, find, exa_search, exa_fetch",
+      model: config.agents.librarian.model,
+      thinking: config.agents.librarian.thinking,
+      max_turns: config.agents.librarian.maxTurns ?? 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      "You are a research agent specializing in external documentation and libraries.",
+      "",
+      "Your job is to find documentation, best practices, and usage patterns for external libraries and APIs.",
+      "You are read-only — do NOT modify any project files.",
+      "",
+      COMMUNICATION,
+      "",
+      "# How to research",
+      "",
+      "Never guess at APIs — always look them up. Training data may be outdated or wrong.",
+      "",
+      "Web search and docs:",
+      "- exa_search: search the web for docs, guides, examples. Describe the ideal page, not keywords.",
+      "- exa_fetch: read a URL's full content as clean markdown. Use after exa_search for details.",
+      "",
+      "Local sources:",
+      "- Read installed package docs (node_modules/, vendor/, go module cache)",
+      "- grep: search installed dependencies for usage patterns",
+      "",
+      "Priority: exa_search → exa_fetch (for full page) → installed source → grep as fallback",
+      "",
+      "# Output",
+      "- Organize findings by topic",
+      "- Include exact URLs or file paths for every claim",
+      "- Quote relevant code snippets from docs",
+      "- Flag any version-specific caveats",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/plan-reviewer.ts

@@ -0,0 +1,75 @@
+import type { PiPiConfig } from "../config.js";
+import { TOOL_ROUTING, ALL_CBM_TOOLS, EXA_TOOLS, WORKING_PRINCIPLES_READONLY, COMMUNICATION } from "./tool-routing.js";
+
+export function createPlanReviewerAgent(
+  variant: string,
+  config: PiPiConfig,
+  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string },
+  outputPath: string,
+) {
+  const variantConfig = config.planReviewers[variant];
+  if (!variantConfig) {
+    throw new Error(`Unknown plan-reviewer variant: ${variant}`);
+  }
+
+  return {
+    frontmatter: {
+      description: `Plan reviewer (${variant} variant, pi-pi)`,
+      tools: `read, grep, find, bash, write, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: variantConfig.model,
+      thinking: variantConfig.thinking,
+      max_turns: variantConfig.maxTurns ?? 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      // --- static prefix (cacheable) ---
+      "You are a plan reviewer. Your job is to validate the implementation plan for executability and completeness.",
+      "",
+      "You are a BLOCKER-FINDER, not a perfectionist.",
+      "Approve by default. Reject only for critical blockers — maximum 3.",
+      "",
+      WORKING_PRINCIPLES_READONLY,
+      "",
+      COMMUNICATION,
+      "",
+      TOOL_ROUTING,
+      "",
+      "Review criteria:",
+      "- Are all plan items actionable and verifiable?",
+      "- Are there missing steps that would block implementation?",
+      "- Are there contradictions or ambiguities?",
+      "- Does the plan account for edge cases mentioned in the research?",
+      "",
+      "Perspectives to consider:",
+      "- As the executor: can each step be completed with only what's written? Where would I get stuck?",
+      "- As the skeptic: what is the strongest argument this approach will fail?",
+      "- Feasibility: does the executor have everything needed (context, dependencies, access) without asking questions?",
+      "- Ambiguity: could two developers interpret any step differently? If yes, flag it.",
+      "",
+      "Format your review as:",
+      "- BLOCKERS: (critical issues that must be fixed)",
+      "- SUGGESTIONS: (improvements, not required)",
+      "- VERDICT: APPROVE or REJECT (with reason)",
+      "",
+      'You can spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
+      "",
+      // --- dynamic suffix ---
+      "# MANDATORY: Write your review to this exact file using the write tool:",
+      `  ${outputPath}`,
+      "",
+      "Your task is NOT complete until this file exists. Do NOT finish without writing it.",
+      "You MUST NOT write to any other file. Only write .md files inside .pp/state/.",
+      "",
+      "=== USER REQUEST ===",
+      taskArtifacts.userRequest,
+      "",
+      "=== RESEARCH ===",
+      taskArtifacts.research,
+      "",
+      "=== SYNTHESIZED PLAN ===",
+      taskArtifacts.synthesizedPlan,
+      "",
+      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/planner.ts

@@ -0,0 +1,61 @@
+import type { PiPiConfig } from "../config.js";
+import { TOOL_ROUTING, ALL_CBM_TOOLS, EXA_TOOLS, WORKING_PRINCIPLES_READONLY, COMMUNICATION } from "./tool-routing.js";
+
+export function createPlannerAgent(
+  variant: string,
+  config: PiPiConfig,
+  taskArtifacts: { userRequest: string; research: string },
+  outputPath: string,
+) {
+  const variantConfig = config.planners[variant];
+  if (!variantConfig) {
+    throw new Error(`Unknown planner variant: ${variant}`);
+  }
+
+  return {
+    frontmatter: {
+      description: `Planner (${variant} variant, pi-pi)`,
+      tools: `read, grep, find, bash, write, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: variantConfig.model,
+      thinking: variantConfig.thinking,
+      max_turns: variantConfig.maxTurns ?? 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      // --- static prefix (cacheable) ---
+      "You are a planning agent. Your job is to create a detailed implementation plan.",
+      "",
+      WORKING_PRINCIPLES_READONLY,
+      "",
+      COMMUNICATION,
+      "",
+      TOOL_ROUTING,
+      "",
+      "Plan format rules:",
+      "- Start with # Plan",
+      "- ## Scope: 2-4 lines — what changes, what doesn't, critical constraints",
+      "- ## Checklist: each item is - [ ] <outcome> — Done when: <observable condition>",
+      "  Each item = one independently verifiable outcome. No code snippets or file-by-file instructions.",
+      "- ## Blockers: unresolved issues blocking implementation (omit if none)",
+      "- No other top-level sections allowed",
+      "- Describe outcomes, not code-level mechanics",
+      "",
+      'You can spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs.',
+      "",
+      // --- dynamic suffix ---
+      "# MANDATORY: Write your plan to this exact file using the write tool:",
+      `  ${outputPath}`,
+      "",
+      "Your task is NOT complete until this file exists. Do NOT finish without writing it.",
+      "You MUST NOT write to any other file. Only write .md files inside .pp/state/.",
+      "",
+      "=== USER REQUEST ===",
+      taskArtifacts.userRequest,
+      "",
+      "=== RESEARCH ===",
+      taskArtifacts.research,
+      "",
+      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/registry.ts

@@ -0,0 +1,156 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+interface AgentFrontmatter {
+  description: string;
+  tools: string;
+  model: string;
+  thinking: string;
+  max_turns?: number;
+  prompt_mode?: string;
+}
+
+export function registerAgentDefinitions(
+  pi: ExtensionAPI,
+  agents: Array<{ type: string; variant: string | null; frontmatter: AgentFrontmatter; prompt: string }>,
+): void {
+  const agentMap = new Map<string, any>();
+
+  for (const agent of agents) {
+    const suffix = agent.variant ? `_${agent.variant}` : "";
+    const name = `${agent.type}${suffix}`;
+    const toolNames = agent.frontmatter.tools === "none" ? [] : agent.frontmatter.tools.split(",").map((t: string) => t.trim()).filter(Boolean);
+
+    agentMap.set(name, {
+      name,
+      description: agent.frontmatter.description,
+      builtinToolNames: toolNames,
+      extensions: true,
+      skills: false,
+      model: agent.frontmatter.model,
+      thinking: agent.frontmatter.thinking,
+      maxTurns: agent.frontmatter.max_turns,
+      systemPrompt: agent.prompt,
+      promptMode: agent.frontmatter.prompt_mode ?? "replace",
+      inheritContext: false,
+      runInBackground: true,
+      isolated: false,
+      enabled: true,
+      source: "project",
+    });
+  }
+
+  pi.events.emit("subagents:register-agents", { agents: agentMap });
+}
+
+export function unregisterAgentDefinitions(pi: ExtensionAPI): void {
+  pi.events.emit("subagents:unregister-agents", { all: true });
+}
+
+export function setExtensionOnlyMode(pi: ExtensionAPI): void {
+  pi.events.emit("subagents:set-extension-only", { enabled: true });
+}
+
+export function spawnViaRpc(
+  pi: ExtensionAPI,
+  agentType: string,
+  prompt: string,
+  options: {
+    description: string;
+    maxTurns?: number;
+    spawnTimeout?: number;
+    validateCompletion?: () => string | undefined;
+    maxValidationRetries?: number;
+  },
+): Promise<{ id: string }> {
+  const timeout = options.spawnTimeout ?? 30000;
+  return new Promise((resolve, reject) => {
+    const requestId = crypto.randomUUID();
+    const replyEvent = `subagents:rpc:spawn:reply:${requestId}`;
+
+    const unsub = pi.events.on(replyEvent, (reply: any) => {
+      unsub();
+      if (reply.success) {
+        const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
+        mgr?.refreshWidget?.();
+        resolve({ id: reply.data?.id ?? requestId });
+      } else {
+        reject(new Error(reply.error || "spawn failed"));
+      }
+    });
+
+    pi.events.emit("subagents:rpc:spawn", {
+      requestId,
+      type: agentType,
+      prompt,
+      options: {
+        description: options.description,
+        run_in_background: true,
+        maxTurns: options.maxTurns,
+        validateCompletion: options.validateCompletion,
+        maxValidationRetries: options.maxValidationRetries,
+      },
+    });
+
+    setTimeout(() => {
+      unsub();
+      reject(new Error(`spawn timeout for ${agentType}`));
+    }, timeout);
+  });
+}
+
+export function waitForCompletion(
+  pi: ExtensionAPI,
+  agentId: string,
+): Promise<{ result: string; status: string }> {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      clearInterval(checkTimer);
+      unsubCompleted();
+      unsubFailed();
+    };
+
+    const unsubCompleted = pi.events.on("subagents:completed", (data: any) => {
+      if (data.id === agentId) {
+        cleanup();
+        resolve({ result: data.result ?? "", status: data.status ?? "completed" });
+      }
+    });
+
+    const unsubFailed = pi.events.on("subagents:failed", (data: any) => {
+      if (data.id === agentId) {
+        cleanup();
+        reject(new Error(data.error || `agent ${agentId} failed`));
+      }
+    });
+
+    const checkTimer = setInterval(() => {
+      const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
+      const record = mgr?.getRecord?.(agentId);
+      if (!record) {
+        cleanup();
+        reject(new Error(`agent ${agentId} not found in manager`));
+      }
+    }, 30000);
+  });
+}
+
+export function isSubagentsReady(pi: ExtensionAPI, pingTimeout?: number): Promise<boolean> {
+  const timeout = pingTimeout ?? 5000;
+  return new Promise((resolve) => {
+    const requestId = crypto.randomUUID();
+    const replyEvent = `subagents:rpc:ping:reply:${requestId}`;
+
+    const timer = setTimeout(() => {
+      unsub();
+      resolve(false);
+    }, timeout);
+
+    const unsub = pi.events.on(replyEvent, (reply: any) => {
+      clearTimeout(timer);
+      unsub();
+      resolve(reply.success === true);
+    });
+
+    pi.events.emit("subagents:rpc:ping", { requestId });
+  });
+}

package/extensions/orchestrator/agents/task.ts

@@ -0,0 +1,50 @@
+import type { PiPiConfig } from "../config.js";
+import { TOOL_ROUTING, ALL_CBM_TOOLS, EXA_TOOLS, WORKING_PRINCIPLES, FAILURE_RECOVERY, COMMUNICATION } from "./tool-routing.js";
+
+export function createTaskAgent(
+  config: PiPiConfig,
+  subtaskDescription: string,
+  taskArtifacts: { userRequest: string; synthesizedPlan: string },
+) {
+  return {
+    frontmatter: {
+      description: "Implementation subtask (pi-pi)",
+      tools: `read, write, edit, bash, grep, find, ls, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: config.agents.task.model,
+      thinking: config.agents.task.thinking,
+      max_turns: config.agents.task.maxTurns ?? 170,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      // --- static prefix (cacheable) ---
+      "You are a focused implementation agent working on a specific subtask.",
+      "",
+      WORKING_PRINCIPLES,
+      "",
+      COMMUNICATION,
+      "",
+      TOOL_ROUTING,
+      "",
+      FAILURE_RECOVERY,
+      "",
+      "# Constraints",
+      "- Do NOT spawn task subagents (no recursion)",
+      '- You CAN spawn subagents: Agent(subagent_type="Explore", ...) for codebase, Agent(subagent_type="Librarian", ...) for external docs',
+      "- Focus only on your subtask — do not modify unrelated code",
+      "- Before modifying a function, use lsp findReferences to understand all callers",
+      "- After editing files, run lsp diagnostics and fix errors before moving on",
+      "",
+      // --- dynamic suffix ---
+      "=== YOUR SUBTASK ===",
+      subtaskDescription,
+      "",
+      "=== USER REQUEST (for context) ===",
+      taskArtifacts.userRequest,
+      "",
+      "=== SYNTHESIZED PLAN (for broader context) ===",
+      taskArtifacts.synthesizedPlan,
+      "",
+      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/tool-routing.ts

@@ -0,0 +1,84 @@
+export const ALL_CBM_TOOLS = "cbm_search, cbm_search_code, cbm_trace, cbm_changes, cbm_query, cbm_architecture";
+export const EXA_TOOLS = "exa_search, exa_fetch";
+
+export const WORKING_PRINCIPLES = [
+  "# Working principles",
+  "",
+  "- Verify, don't assume. Check actual state with tools before making changes. Never guess paths, types, or APIs.",
+  "- Understand before modifying. Read the code, trace callers, check types BEFORE editing. Compiling ≠ correct.",
+  "- Smallest viable change. Do what was asked, nothing more. Don't broaden scope, don't refactor adjacent code.",
+  "- No temporary artifacts. No console.log, TODO, HACK, debugger, or commented-out code left behind.",
+  "- Evidence over claims. 'It should work' is not proof. Show fresh tool output (lsp diagnostics, test results, build output).",
+  "- Match existing patterns. Mirror the codebase's naming, error handling, imports, and structure exactly.",
+].join("\n");
+
+export const WORKING_PRINCIPLES_READONLY = [
+  "# Working principles",
+  "",
+  "- Verify, don't assume. Check actual state with tools. Never guess paths, types, or APIs.",
+  "- Evidence over claims. Show what you found with file paths and tool output, not guesses.",
+].join("\n");
+
+export const FAILURE_RECOVERY = [
+  "# Failure recovery",
+  "",
+  "If a fix attempt fails, analyze root cause before retrying — don't repeat the same approach.",
+  "After 3 failed attempts at the same issue:",
+  "1. STOP editing immediately",
+  "2. Revert to last working state if possible",
+  "3. Document what you tried and why it failed",
+  "4. Report the blocker — do not keep pushing",
+].join("\n");
+
+export const COMMUNICATION = [
+  "# Communication",
+  "",
+  "- CONCISE. Use minimum words needed. No preamble, no filler, no restatement.",
+  "- Never explain what you're about to do — just do it.",
+  "- Never summarize what you just did — the user can see the results.",
+  "- Think critically. Don't just agree — push back when something seems wrong.",
+  "- State concerns before implementing. If you see a better approach, say so.",
+  "- Dense over polished. One precise sentence beats three vague ones.",
+].join("\n");
+
+export const TOOL_ROUTING = [
+  "# Tool routing — what do you want to do?",
+  "",
+  "Find code by concept or behavior:",
+  "- cbm_search: natural-language search (query='deploy release chart')",
+  "- cbm_search with semantic_query: vector similarity (['deploy','install','upgrade'])",
+  "- cbm_search_code: graph-augmented grep — deduplicates into containing functions",
+  "Priority: cbm_search → lsp workspaceSymbol → grep",
+  "",
+  "Navigate to a definition, type, or interface:",
+  "- NEVER grep for definitions. ALWAYS use lsp goToDefinition.",
+  "- lsp hover: get type info and documentation",
+  "- lsp goToImplementation: find all types implementing an interface",
+  "- lsp documentSymbol: list all symbols in a file",
+  "",
+  "Find all usages of a symbol:",
+  "- NEVER grep for symbol names. ALWAYS use lsp findReferences.",
+  "",
+  "Trace call chains:",
+  "- lsp incomingCalls/outgoingCalls: accurate, needs file+line position",
+  "- cbm_trace: by function name, works across the whole graph",
+  "- cbm_query: Cypher queries for complex multi-hop patterns",
+  "",
+  "Find structural patterns:",
+  "- ast_search: AST-aware matching (e.g. 'if err != nil { $$$ }', 'go $FUNC($$$)')",
+  "",
+  "Search for literal text:",
+  "- grep: ONLY for literal strings, config keys, error messages. Not for definitions or references.",
+  "",
+  "Check for errors:",
+  "- lsp diagnostics: type errors and lint issues on a file",
+  "- lsp codeActions: auto-fix suggestions",
+  "",
+  "Assess impact of changes:",
+  "- cbm_changes: git diff → affected symbols + blast radius",
+  "- cbm_architecture: high-level codebase structure overview",
+  "",
+  "Web search:",
+  "- exa_search: search the web for docs, guides, examples. Describe the ideal page, not keywords.",
+  "- exa_fetch: read a URL's full content as clean markdown.",
+].join("\n");