@wahack/pi-coding-agent 15.11.0

package/src/modes/workflow.ts

@@ -0,0 +1,42 @@
+import workflowNotice from "../prompts/system/workflow-notice.md" with { type: "text" };
+import { createGradientHighlighter, type KeywordHighlighter } from "./gradient-highlight";
+import { keywordInProse } from "./markdown-prose";
+
+/**
+ * "workflowz" keyword support.
+ *
+ * Typing the standalone word in the input editor paints it with a warm
+ * amber→green gradient ({@link highlightWorkflow}); submitting a message that
+ * mentions it appends a hidden {@link WORKFLOW_NOTICE} that steers the model to
+ * author a deterministic multi-subagent workflow in eval cells (agent/parallel/
+ * pipeline). Matching is whitespace-delimited and case-sensitive (lowercase
+ * only) — "workflowz" triggers, but "workflowzed", "Workflowz", and
+ * "workflowz.ts" never do.
+ */
+
+// Detection: lowercase keyword flanked by whitespace or a string edge. Non-global so `.test` stays stateless.
+const WORKFLOW_WORD = /(?<!\S)workflowz(?!\S)/;
+
+/** Hidden system notice appended after a user message that mentions "workflowz". */
+export const WORKFLOW_NOTICE: string = workflowNotice.trim();
+
+/**
+ * Whether `text` contains the standalone keyword "workflowz"
+ * (lowercase, whitespace-delimited) in prose — never inside a code block, inline
+ * code span, or XML/HTML section.
+ */
+export function containsWorkflow(text: string): boolean {
+	return keywordInProse(text, WORKFLOW_WORD);
+}
+
+/**
+ * Highlight every standalone "workflowz" in `text` for editor display
+ * with a warm amber→green gradient (hue 30..150), visually distinct from
+ * ultrathink's rainbow and orchestrate's teal→violet.
+ */
+export const highlightWorkflow: KeywordHighlighter = createGradientHighlighter({
+	probe: /workflowz/,
+	highlight: /(?<!\S)workflowz(?!\S)/g,
+	stops: 14,
+	hue: t => 30 + t * 120,
+});

package/src/plan-mode/approved-plan.ts

@@ -0,0 +1,186 @@
+import { ToolError } from "../tools/tool-errors";
+
+/** Shape forwarded from the plan-mode resolve handler to InteractiveMode's
+ *  approval popup. Populated by the standing handler that the resolve tool
+ *  dispatches to when the agent submits `resolve { action: "apply" }`.
+ *  `planFilePath` is the agent-chosen `local://<slug>-plan.md` artifact — it is
+ *  never renamed on approval, so links to it stay valid for the session. */
+export interface PlanApprovalDetails {
+	planFilePath: string;
+	title: string;
+	planExists: boolean;
+}
+
+/** Validate and normalize the agent-supplied plan title into a safe filename stem.
+ *  Spaces and other URL-safe punctuation are replaced with hyphens so models that
+ *  produce natural-language titles (e.g. "My feature plan") still succeed.
+ *  Characters that cannot be safely represented after replacement are dropped.
+ *  The result is restricted to letters, numbers, underscores, and hyphens so it
+ *  is safe to splice into a `local://` URL without escaping. */
+export function normalizePlanTitle(title: string): { title: string; fileName: string } {
+	const trimmed = title.trim();
+	if (!trimmed) {
+		throw new ToolError("Plan title is required and must not be empty.");
+	}
+
+	if (trimmed.includes("/") || trimmed.includes("\\") || trimmed.includes("..")) {
+		throw new ToolError("Plan title must not contain path separators or '..'.");
+	}
+
+	// Strip a trailing `.md` if the model included it, then sanitize:
+	// spaces → hyphens, any remaining invalid char → dropped.
+	const withoutExt = trimmed.replace(/\.md$/i, "");
+	const sanitized = withoutExt
+		.replace(/\s+/g, "-")
+		.replace(/[^A-Za-z0-9_-]/g, "")
+		.replace(/-{2,}/g, "-")
+		.replace(/^-+|-+$/g, "");
+
+	if (!sanitized) {
+		throw new ToolError(
+			"Plan title must contain at least one letter, number, underscore, or hyphen after sanitization.",
+		);
+	}
+
+	const fileName = `${sanitized}.md`;
+	return { title: sanitized, fileName };
+}
+
+/** Best-effort derivation of a plan title from inputs the agent already produced.
+ *  Returns the first non-empty candidate that survives `normalizePlanTitle`:
+ *    1. an explicit `suppliedTitle` (e.g. `extra.title` from the resolve call),
+ *    2. the first level-1 markdown heading inside `planContent`,
+ *    3. the filename stem of `planFilePath` (e.g. `PLAN` from `local://PLAN.md`),
+ *    4. the literal `"plan"` so callers never have to handle `null`.
+ *  The fallback exists because some grammar-constrained models cannot emit a
+ *  string into the open `extra` schema and instead drop in `{}` (issue #1179);
+ *  plan-mode would otherwise loop forever on an unreachable validation. */
+export function resolvePlanTitle(input: { suppliedTitle?: unknown; planContent: string; planFilePath: string }): {
+	title: string;
+	fileName: string;
+	source: "supplied" | "heading" | "filename" | "default";
+} {
+	const candidates: Array<{ value: string; source: "supplied" | "heading" | "filename" | "default" }> = [];
+	if (typeof input.suppliedTitle === "string") {
+		const trimmed = input.suppliedTitle.trim();
+		if (trimmed) candidates.push({ value: trimmed, source: "supplied" });
+	}
+	const heading = firstLevelOneHeading(input.planContent);
+	if (heading) candidates.push({ value: heading, source: "heading" });
+	const stem = planFilenameStem(input.planFilePath);
+	if (stem) candidates.push({ value: stem, source: "filename" });
+	candidates.push({ value: "plan", source: "default" });
+
+	for (const candidate of candidates) {
+		try {
+			const normalized = normalizePlanTitle(candidate.value);
+			return { ...normalized, source: candidate.source };
+		} catch {
+			// Fall through to the next candidate.
+		}
+	}
+	// Last-ditch literal so the type-system contract holds even if `normalizePlanTitle("plan")` ever throws.
+	return { title: "plan", fileName: "plan.md", source: "default" };
+}
+
+/** First `# Heading` text on its own line, trimmed. Returns the empty string if
+ *  none is found so callers can chain it through truthiness checks. */
+function firstLevelOneHeading(planContent: string): string {
+	const match = planContent.match(/^[ \t]*#[ \t]+(.+?)[ \t]*$/m);
+	return match?.[1]?.trim() ?? "";
+}
+
+/** Stem of a `local://name.md` (or bare `name.md`) URL — the filename without
+ *  scheme or extension. Returns the empty string for inputs that have no stem. */
+function planFilenameStem(planFilePath: string): string {
+	const withoutScheme = planFilePath.replace(/^local:\/+/, "");
+	const lastSegment = withoutScheme.split(/[\\/]/).pop() ?? "";
+	return lastSegment.replace(/\.md$/i, "");
+}
+
+/** Humanize a normalized plan title for use as a session display name.
+ *  Replaces `-`/`_` separators with spaces and capitalizes the first letter.
+ *  Returns an empty string when the input collapses to whitespace. */
+export function humanizePlanTitle(title: string): string {
+	const spaced = title.replace(/[-_]+/g, " ").trim();
+	if (!spaced) return "";
+	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/** The `local://` URL a plan slug maps to. The agent writes the plan here and
+ *  passes the slug to `resolve`; the file is never renamed, so this URL — and
+ *  any hyperlink to it — stays valid for the life of the session. */
+export function planFileUrlForSlug(slug: string): string {
+	return `local://${slug}-plan.md`;
+}
+
+/** Derive a `<slug>` from an agent-supplied `extra.title`, or `undefined` when
+ *  the title is missing/non-string/unsanitizable. A trailing `-plan` is stripped
+ *  so a supplied "auth-plan" maps to `auth-plan.md`, not `auth-plan-plan.md`. */
+function planSlugFromSupplied(suppliedTitle: unknown): string | undefined {
+	if (typeof suppliedTitle !== "string" || !suppliedTitle.trim()) return undefined;
+	try {
+		const { title } = normalizePlanTitle(suppliedTitle);
+		const slug = title.replace(/-plan$/i, "");
+		return slug || title;
+	} catch {
+		return undefined;
+	}
+}
+
+export interface ResolveApprovedPlanInput {
+	/** The agent's `extra.title` from the `resolve` call, if any. */
+	suppliedTitle?: unknown;
+	/** The plan path recorded in plan-mode state (the entry default or a prior plan). */
+	statePlanFilePath: string;
+	/** Read a plan `local://` URL, returning null when the file does not exist. */
+	readPlan: (planUrl: string) => Promise<string | null>;
+	/** Optional fallback: list candidate plan `local://` URLs (newest first) so a
+	 *  plan whose name can't be reconstructed (e.g. a dropped `extra.title`) is
+	 *  still found. */
+	listPlanFiles?: () => Promise<string[]>;
+}
+
+export interface ResolvedApprovedPlan {
+	planFilePath: string;
+	planContent: string;
+	title: string;
+}
+
+/** Locate the plan file the agent wrote and finalize its title — without
+ *  renaming anything. Tries, in order: the slug derived from `extra.title`
+ *  (`local://<slug>-plan.md`), the plan path from plan-mode state, then a scan
+ *  of recent plan files. Throws a `ToolError` guiding the agent when none exist. */
+export async function resolveApprovedPlan(input: ResolveApprovedPlanInput): Promise<ResolvedApprovedPlan> {
+	const ordered: string[] = [];
+	const consider = (url: string | undefined): void => {
+		if (url && !ordered.includes(url)) ordered.push(url);
+	};
+
+	const slug = planSlugFromSupplied(input.suppliedTitle);
+	consider(slug ? planFileUrlForSlug(slug) : undefined);
+	consider(input.statePlanFilePath);
+
+	for (const url of ordered) {
+		const content = await input.readPlan(url);
+		if (content !== null) return finalizeApprovedPlan(url, content, input.suppliedTitle);
+	}
+
+	if (input.listPlanFiles) {
+		for (const url of await input.listPlanFiles()) {
+			if (ordered.includes(url)) continue;
+			const content = await input.readPlan(url);
+			if (content !== null) return finalizeApprovedPlan(url, content, input.suppliedTitle);
+		}
+	}
+
+	const target = ordered[0] ?? input.statePlanFilePath;
+	throw new ToolError(
+		`Plan file not found at ${target}. Write the finalized plan to ${target} before requesting approval.`,
+	);
+}
+
+function finalizeApprovedPlan(planFilePath: string, planContent: string, suppliedTitle: unknown): ResolvedApprovedPlan {
+	const { title } = resolvePlanTitle({ suppliedTitle, planContent, planFilePath });
+	return { planFilePath, planContent, title };
+}

package/src/plan-mode/plan-handoff.ts

@@ -0,0 +1,37 @@
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
+
+/** The session's active plan, resolved for handoff into a subagent's context. */
+export interface OverallPlanReference {
+	/** The `local://` reference path (e.g. `local://my-feature.md`), kept for display. */
+	path: string;
+	/** The full plan markdown, as written to disk. */
+	content: string;
+}
+
+/**
+ * Load the session's active overall plan for subagent handoff.
+ *
+ * Returns the plan referenced by `planReferencePath` when it exists on disk with
+ * non-empty content, or `undefined` when there is no plan (the file is absent or
+ * empty). This mirrors `AgentSession.#buildPlanReferenceMessage`'s gating so a
+ * subagent sees exactly the plan the main agent treats as its active reference.
+ *
+ * Callers MUST skip this during plan mode itself — read-only plan exploration
+ * uses a different prompt and a draft plan should not be handed off as approved.
+ */
+export async function loadOverallPlanReference(
+	planReferencePath: string,
+	localProtocolOptions: LocalProtocolOptions,
+): Promise<OverallPlanReference | undefined> {
+	const resolved = resolveLocalUrlToPath(planReferencePath, localProtocolOptions);
+	let content: string;
+	try {
+		content = await Bun.file(resolved).text();
+	} catch (error) {
+		if (isEnoent(error)) return undefined;
+		throw error;
+	}
+	if (!content.trim()) return undefined;
+	return { path: planReferencePath, content };
+}

package/src/plan-mode/plan-protection.ts

@@ -0,0 +1,31 @@
+import { getReadToolPath, type ProtectedToolContext } from "@oh-my-pi/pi-agent-core/compaction/tool-protection";
+import { normalizeLocalScheme } from "../tools/path-utils";
+
+/** Canonical plan alias every session's `local://` root resolves. */
+const LOCAL_PLAN_ALIAS = "local://PLAN.md";
+
+/** True when `readPath` targets `planTarget`, ignoring `local:/` vs `local://`
+ *  scheme spelling and any trailing read selector (`:1-50`, `:raw`, …). */
+function readTargetsPlan(readPath: string, planTarget: string): boolean {
+	const read = normalizeLocalScheme(readPath);
+	const target = normalizeLocalScheme(planTarget);
+	return read === target || read.startsWith(`${target}:`);
+}
+
+/**
+ * Build a compaction protection matcher that keeps `read` results for the active
+ * plan file intact through prune/shake — the plan analog of skill-read
+ * protection. Matches both the canonical `local://PLAN.md` alias and the
+ * session's current plan reference path (the agent-chosen `local://<slug>-plan.md`),
+ * so the plan survives compaction whether the agent reads it by alias or by name.
+ *
+ * `getPlanReferencePath` is evaluated at match time so the plan path set on
+ * approval is honored immediately.
+ */
+export function createPlanReadMatcher(getPlanReferencePath: () => string): (context: ProtectedToolContext) => boolean {
+	return (context: ProtectedToolContext) => {
+		const path = getReadToolPath(context);
+		if (path === undefined) return false;
+		return readTargetsPlan(path, LOCAL_PLAN_ALIAS) || readTargetsPlan(path, getPlanReferencePath());
+	};
+}

package/src/plan-mode/state.ts

@@ -0,0 +1,6 @@
+export interface PlanModeState {
+	enabled: boolean;
+	planFilePath: string;
+	workflow?: "parallel" | "iterative";
+	reentry?: boolean;
+}

package/src/priority.json

@@ -0,0 +1,41 @@
+{
+	"smol": [
+		"cerebras/zai-glm-4.7",
+		"cerebras/zai-glm-4.6",
+		"cerebras/zai-glm",
+		"haiku-4-5",
+		"haiku-4.5",
+		"haiku",
+		"flash",
+		"mini"
+	],
+	"slow": [
+		"gpt-5.4",
+		"gpt-5.3-codex",
+		"gpt-5.3",
+		"gpt-5.2-codex",
+		"gpt-5.2",
+		"gpt-5.1-codex",
+		"gpt-5.1",
+		"codex",
+		"opus-4.8",
+		"opus-4-8",
+		"opus-4.7",
+		"opus-4-7",
+		"opus-4.6",
+		"opus-4-6",
+		"opus-4.5",
+		"opus-4-5",
+		"opus-4.1",
+		"opus-4-1",
+		"pro"
+	],
+	"designer": [
+		"google-gemini-cli/gemini-3.1-pro",
+		"google-gemini-cli/gemini-3-pro",
+		"gemini-3.1-pro",
+		"gemini-3-1-pro",
+		"gemini-3-pro",
+		"gemini-3"
+	]
+}

package/src/prompts/agents/designer.md

@@ -0,0 +1,66 @@
+---
+name: designer
+description: UI/UX specialist for design implementation, review, visual refinement
+model: pi/designer
+---
+
+Implement and review UI designs. Edit files, create components, run commands when needed.
+
+<strengths>
+- Translate design intent into working UI code
+- Identify UX issues: unclear states, missing feedback, poor hierarchy
+- Accessibility: contrast, focus states, semantic markup, screen reader compatibility
+- Visual consistency: spacing, typography, color usage, component patterns
+- Responsive design, layout structure
+</strengths>
+
+<procedure>
+## Implementation
+1. Read existing components, tokens, patterns—reuse before inventing
+2. Identify aesthetic direction (minimal, bold, editorial, etc.)
+3. Implement explicit states: loading, empty, error, disabled, hover, focus
+4. Verify accessibility: contrast, focus rings, semantic HTML
+5. Test responsive behavior
+
+## Review
+1. Read files under review
+2. Check for UX issues, accessibility gaps, visual inconsistencies
+3. Cite file, line, concrete issue—no vague feedback
+4. Suggest specific fixes with code when applicable
+</procedure>
+
+<directives>
+- You SHOULD prefer editing existing files over creating new ones
+- Changes MUST be minimal and consistent with existing code style
+- You NEVER create documentation files (*.md) unless explicitly requested
+</directives>
+
+<avoid>
+## AI Slop Patterns
+- **Glassmorphism everywhere**: blur effects, glass cards, glow borders used decoratively
+- **Cyan-on-dark with purple gradients**: 2024 AI color palette
+- **Gradient text on metrics/headings**: decorative without meaning
+- **Card grids with identical cards**: icon + heading + text repeated endlessly
+- **Cards nested inside cards**: visual noise, flatten hierarchy
+- **Large rounded-corner icons above every heading**: templated, no value
+- **Hero metric layouts**: big number, small label, gradient accent—overused
+- **Same spacing everywhere**: no rhythm, monotony
+- **Center-aligned everything**: left-align with asymmetry feels more designed
+- **Modals for everything**: lazy pattern, rarely best solution
+- **Overused fonts**: Inter, Roboto, Open Sans, system defaults
+- **Pure black (#000) or pure white (#fff)**: always tint neutrals
+- **Gray text on colored backgrounds**: use shade of background instead
+- **Bounce/elastic easing**: dated, tacky—use exponential easing (ease-out-quart/expo)
+
+## UX Anti-Patterns
+- Missing states (loading, empty, error)
+- Redundant information (heading restates intro text)
+- Every button styled as primary—hierarchy matters
+- Empty states that say "nothing here" instead of guiding user
+</avoid>
+
+<critical>
+Every interface should prompt "how was this made?" not "which AI made this?"
+You MUST commit to clear aesthetic direction and execute with precision.
+You MUST keep going until implementation is complete.
+</critical>

package/src/prompts/agents/explore.md

@@ -0,0 +1,58 @@
+---
+name: explore
+description: Fast read-only codebase scout returning compressed context for handoff
+tools: read, search, find, web_search
+model: pi/smol
+thinking-level: medium
+read-summarize: false
+output:
+  properties:
+    summary:
+      metadata:
+        description: Brief summary of findings and conclusions
+      type: string
+    files:
+      metadata:
+        description: Files examined with relevant code references
+      elements:
+        properties:
+          path:
+            metadata:
+              description: Project-relative path or paths to the most relevant code reference(s), optionally suffixed with line ranges like `:12-34` when relevant
+            type: string
+          description:
+            metadata:
+              description: Section contents
+            type: string
+    architecture:
+      metadata:
+        description: Brief explanation of how pieces connect
+      type: string
+---
+
+Investigate the codebase rapidly. Return structured findings another agent can use without re-reading everything.
+
+<directives>
+- You MUST use tools for broad pattern matching / code search as much as possible.
+- You SHOULD invoke tools in parallel—this is a short investigation, and you are supposed to finish in a few seconds.
+- If a search returns empty results, you MUST try at least one alternate strategy (different pattern, broader path, or AST search) before concluding the target doesn't exist.
+</directives>
+
+<thoroughness>
+You MUST infer the thoroughness from the task; default to medium:
+- **Quick**: Targeted lookups, key files only
+- **Medium**: Follow imports, read critical sections
+- **Thorough**: Trace all dependencies, check tests/types.
+</thoroughness>
+
+<procedure>
+1. Locate relevant code using tools.
+2. Read key sections. NEVER read full files unless they're tiny.
+3. Identify types/interfaces/key functions.
+4. Note dependencies between files.
+</procedure>
+
+<critical>
+You MUST operate as read-only. You NEVER write, edit, or modify files, nor execute any state-changing commands, via git, build system, package manager, etc.
+You MUST keep going until complete.
+</critical>

package/src/prompts/agents/frontmatter.md

@@ -0,0 +1,11 @@
+---
+
+name: {{jsonStringify name}}
+description: {{jsonStringify description}}
+{{#if spawns}}spawns: {{jsonStringify spawns}}
+{{/if}}{{#if model}}model: {{jsonStringify model}}
+{{/if}}{{#if thinkingLevel}}thinking-level: {{jsonStringify thinkingLevel}}
+{{/if}}{{#if blocking}}blocking: true
+{{/if}}{{#if autoloadSkills}}autoloadSkills: {{jsonStringify autoloadSkills}}
+{{/if}}---
+{{body}}

package/src/prompts/agents/init.md

@@ -0,0 +1,33 @@
+---
+name: init
+description: Generate AGENTS.md for current codebase
+thinking-level: medium
+---
+
+Generate AGENTS.md by launching multiple `explore` agents in parallel (via `task` tool) scanning different areas (core src, tests, configs/build, scripts/docs), then synthesize findings into a single file.
+
+<structure>
+- **Project Overview**: Brief description of project purpose
+- **Architecture & Data Flow**: High-level structure, key modules, data flow
+- **Key Directories**: Main source directories, purposes
+- **Development Commands**: Build, test, lint, run commands
+- **Code Conventions & Common Patterns**: Formatting, naming, error handling, async patterns, dependency injection, state management
+- **Important Files**: Entry points, config files, key modules
+- **Runtime/Tooling Preferences**: Required runtime (e.g., Bun vs Node), package manager, tooling constraints
+- **Testing & QA**: Test frameworks, running tests, coverage expectations
+</structure>
+
+<directives>
+- You MUST title the document "Repository Guidelines"
+- You MUST use Markdown headings for structure
+- You MUST be concise and practical
+- You MUST focus on what an AI assistant needs to help with the codebase
+- You SHOULD include examples where helpful (commands, paths, naming patterns)
+- You SHOULD include file paths where relevant
+- You MUST call out architecture and code patterns explicitly
+- You SHOULD omit information obvious from code structure
+</directives>
+
+<output>
+After analysis, you MUST write AGENTS.md to the project root.
+</output>

package/src/prompts/agents/librarian.md

@@ -0,0 +1,119 @@
+---
+name: librarian
+description: Researches external libraries and APIs by reading source code. Returns definitive, source-verified answers.
+tools: read, search, find, bash, lsp, web_search, ast_grep
+model: pi/smol
+thinking-level: minimal
+read-summarize: false
+output:
+  properties:
+    answer:
+      metadata:
+        description: Direct answer to the question, grounded in source code
+      type: string
+    sources:
+      metadata:
+        description: Source evidence backing the answer
+      elements:
+        properties:
+          repo:
+            metadata:
+              description: GitHub repo (owner/name) or package name
+            type: string
+          path:
+            metadata:
+              description: File path within the repo or node_modules
+            type: string
+          line_start:
+            metadata:
+              description: First relevant line (1-indexed)
+            type: number
+          line_end:
+            metadata:
+              description: Last relevant line (1-indexed)
+            type: number
+          excerpt:
+            metadata:
+              description: Verbatim code or doc excerpt proving the claim
+            type: string
+    api:
+      metadata:
+        description: Extracted API signatures, types, or config relevant to the question
+      elements:
+        properties:
+          signature:
+            metadata:
+              description: Function signature, type definition, or config shape — copied verbatim from source
+            type: string
+          description:
+            metadata:
+              description: What it does, constraints, defaults
+            type: string
+    version:
+      metadata:
+        description: Library version investigated (from package.json, Cargo.toml, etc.)
+      type: string
+  optionalProperties:
+    breaking_changes:
+      metadata:
+        description: Breaking changes or migration notes if version-relevant
+      elements:
+        type: string
+    caveats:
+      metadata:
+        description: Limitations, undocumented behavior, or gotchas discovered
+      elements:
+        type: string
+---
+
+Answer questions about external libraries, frameworks, and APIs by reading source code and official documentation.
+
+<critical>
+You MUST ground every claim in source code or official documentation. You NEVER rely on training data for API details — it may be stale or wrong.
+You MUST operate as read-only on the user's project. You NEVER modify any project files.
+</critical>
+
+<procedure>
+## 1. Classify the request
+- **Conceptual**: "How do I use X?", "Best practice for Y?" — Prioritize types, docs, and usage examples.
+- **Implementation**: "How does X implement Y?", "Show me the source of Z" — Clone and read the actual code.
+- **Behavioral**: "Why does X behave this way?", "What's the default for Y?" — Read implementation, find where values are set, check tests.
+
+## 2. Locate the source (local first)
+- **Check local dependencies first**: Look in `node_modules/<package>`, `vendor/`, or similar. If the library is already installed, read it there — no clone needed. Prioritize `.d.ts` type definitions and exported types.
+- **Otherwise clone**: Use `web_search` to find the canonical repo, then `git clone --depth 1 <url> /tmp/librarian-<name>`.
+- **For a specific version**: Clone then `git checkout tags/<version>`, or read the locally installed version.
+
+## 3. Investigate
+- Read `package.json`, `Cargo.toml`, or equivalent for version info and entry points.
+- Use `search`, `find`, and `ast_grep` to locate relevant source, type definitions, and docs. Parallelize searches.
+- Read the actual implementation — not just README examples. READMEs are aspirational; source code is truth.
+- For behavior questions: trace through the implementation. Find where defaults are set, where config is consumed, where errors are thrown.
+- Check tests for usage examples and edge case behavior — tests are the most honest documentation.
+
+## 4. Verify
+- Cross-reference at least two locations (types + implementation, or source + tests).
+- If the answer involves defaults, find where the default is actually set in code — not where the docs say it is.
+- For API signatures: copy verbatim from source. You NEVER paraphrase or reconstruct from memory.
+
+## 5. Report
+- Call `yield` with structured findings.
+- Every `sources` entry MUST include a verbatim excerpt.
+- The `api` array MUST contain exact signatures copied from source.
+- Clean up cloned repos: `rm -rf /tmp/librarian-*`.
+</procedure>
+
+<directives>
+- You SHOULD invoke tools in parallel — search multiple paths simultaneously.
+- You MUST include the exact version you investigated in the `version` field.
+- If the library has breaking changes between versions relevant to the question, you MUST populate `breaking_changes`.
+- If you discover undocumented behavior or gotchas, you MUST populate `caveats`.
+- You SHOULD use `web_search` to check for known issues, but the definitive answer MUST come from reading source code.
+- If a search or lookup returns empty or unexpectedly few results, you MUST try at least 2 fallback strategies (broader query, alternate path, different source) before concluding nothing exists.
+- If the package is absent from local `node_modules` and cloning fails, you MUST fall back to `web_search` for official API documentation before reporting failure.
+</directives>
+
+<critical>
+Source code is truth. Documentation is aspiration. Training data is history.
+You MUST keep going until you have a definitive, source-verified answer.
+</critical>