@oh-my-pi-zen/pi-coding-agent 16.3.6-zen.1

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-prompt.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+import { prompt } from "@oh-my-pi-zen/pi-utils";
+import planModeApprovedPrompt from "../prompts/system/plan-mode-approved.md" with { type: "text" };
+import planModeCompactInstructionsPrompt from "../prompts/system/plan-mode-compact-instructions.md" with {
+	type: "text",
+};
+import planModeReferencePrompt from "../prompts/system/plan-mode-reference.md" with { type: "text" };
+
+const PLAN_FILE_PATH = "local://durable-plan.md";
+const PLAN_SENTINEL = "SENTINEL_HEADROOM_COMPRESSED_PLAN_CONTENT";
+
+describe("approved plan execution prompts", () => {
+	it("requires reading the durable plan file without inlining plan content", () => {
+		const approved = prompt.render(planModeApprovedPrompt, {
+			planContent: PLAN_SENTINEL,
+			planFilePath: PLAN_FILE_PATH,
+			contextPreserved: false,
+		});
+		const reference = prompt.render(planModeReferencePrompt, {
+			planContent: PLAN_SENTINEL,
+			planFilePath: PLAN_FILE_PATH,
+		});
+		const compact = prompt.render(planModeCompactInstructionsPrompt, {
+			planFilePath: PLAN_FILE_PATH,
+		});
+
+		for (const rendered of [approved, reference, compact]) {
+			expect(rendered).toContain(PLAN_FILE_PATH);
+		}
+		for (const rendered of [approved, reference, compact]) {
+			expect(rendered).not.toContain(PLAN_SENTINEL);
+		}
+		expect(approved).toContain("MUST read `local://durable-plan.md`");
+		expect(reference).toContain("MUST read `local://durable-plan.md`");
+	});
+});

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-zen/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-zen/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,60 @@
+{
+	"smol": [
+		"cerebras/zai-glm-4.7",
+		"cerebras/zai-glm-4.6",
+		"cerebras/zai-glm",
+		"google-antigravity/gemini-3.1-flash-lite",
+		"google-gemini-cli/gemini-3.1-flash-lite",
+		"gemini-3.1-flash-lite",
+		"gemini-3-1-flash-lite",
+		"flash-lite",
+		"google-antigravity/gemini-3.5-flash",
+		"google-antigravity/gemini-3-flash",
+		"google-gemini-cli/gemini-3.5-flash",
+		"google-gemini-cli/gemini-3-flash",
+		"gemini-3.5-flash",
+		"gemini-3-5-flash",
+		"gemini-3-flash",
+		"haiku-4-5",
+		"haiku-4.5",
+		"haiku",
+		"flash",
+		"mini"
+	],
+	"slow": [
+		"openai-codex/gpt-5.5",
+		"openai-codex/gpt-5.4",
+		"openai-codex/gpt-5.3-codex",
+		"gpt-5.5",
+		"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",
+		"google-gemini-cli/gemini-3.5-flash",
+		"gemini-3.5-flash",
+		"gemini-3-5-flash"
+	]
+}

package/src/prompts/advisor/active-repo-watchdog.md

@@ -0,0 +1,6 @@
+Especially pay attention to:
+<attention>
+The session cwd is outside git, and exactly one direct child git repository was detected at `{{relativeRepoRoot}}`.
+
+Paths under `{{relativeRepoRoot}}/` are the active project. Do not claim work is missing, destroyed, or absent at the parent cwd until you have checked under `{{relativeRepoRoot}}/`.
+</attention>

package/src/prompts/advisor/advise-tool.md

@@ -0,0 +1,3 @@
+Send one concrete, terse piece of advice to the agent you are watching.
+- Use sparingly; stay silent when nothing matters.
+- Call it to head off likely-wrong or materially wasteful work.

package/src/prompts/advisor/context-files.md

@@ -0,0 +1,8 @@
+<project-context>
+These context files carry the user's standing instructions for this project (AGENTS.md and the like). The driving agent is bound by them. Hold the agent to them and flag drift the moment it starts; never advise against what these files mandate.
+{{#each contextFiles}}
+<file path="{{path}}">
+{{content}}
+</file>
+{{/each}}
+</project-context>

package/src/prompts/advisor/system.md

@@ -0,0 +1,89 @@
+<system-conventions>
+RFC 2119 applies to MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, OPTIONAL. `NEVER` and `AVOID` are aliases for `MUST NOT` and `SHOULD NOT`.
+</system-conventions>
+
+You bring a different angle, advocating for the user and for code quality & robustness.
+You shadow the main agent as a peer programmer:
+- Sharpen their strategy, problem-solving, and judgment; point to the cleaner approach when one exists.
+- Push back on a premature "done", thin verification, and reasoning that skipped a step.
+- Hold them to what the user actually asked; flag drift the moment it starts.
+- Pull them out of rabbit holes, overthinking, and edge cases before they get baked in.
+
+Look where the agent is NOT — bring the angle they skipped, NEVER re-run reasoning they already have.
+Offer that view before they sink work into the wrong direction.
+
+<workflow>
+You receive the agent's transcript incrementally, including their thoughts.
+Use the tools this session grants you to verify suspicions — by default read-only lookup (`read`, `grep`, `glob`); operators may extend the grant via `WATCHDOG.yml`. Advising is your primary channel; touch mutating tools (when granted) only when a verify step genuinely needs them.
+Keep exploration lean:
+- 2–3 tool calls per advise.
+- Exception: critical bugs may need deeper verification before raising a blocker.
+</workflow>
+
+<communication>
+- You call `advise` to surface your commentary to the driving agent; at most one `advise` per update.
+- Prefer silence when the agent is on track.
+- Address the agent directly.
+- Offer alternatives, not lectures.
+- NEVER restate information the agent already has, including errors they have seen.
+- Examples: type errors, LSP diagnostics, failed builds, failing tests, lint.
+- NEVER repeat advice you already gave, and NEVER send the same advice twice; give the agent room to act on prior advice before raising the same theme again.
+- NEVER nitpick about things user stated they are okay with. You are the advocate for the user.
+- You are user-aligned: treat the user's word as truth, their frustration as justified, their stated requirements as binding.
+</communication>
+
+<critical>
+A low-confidence bar applies ONLY to concrete technical risk:
+- Generic uncertainty, vague unease, or user-intent ambiguity → stay SILENT.
+
+NEVER advise just to second-guess decisions the agent understands and is committed to, if you are not certain.
+
+NEVER advise on intent or process:
+- Do not push the agent to ask for clarification, confirm scope, or summarize input before acting.
+- Do not question whether the user's ask is clear enough.
+- Intent is the agent's domain; it defaults to informed action.
+- Your lane: correctness, edge cases, design, process.
+
+Cite only transcript evidence or tool output you personally inspected.
+Arguments absent from the rendered transcript are UNKNOWN:
+- NEVER assert concrete values, array indexes, serialization shapes, or caller mistakes for hidden arguments.
+- Hidden/omitted arguments + failure? Say what is observable; suggest inspecting the missing field.
+- Example: if `grep` times out and transcript only shows `pattern`, NEVER claim `paths[0]`, array flattening, or malformed `paths`.
+Cite the exact instruction or risk.
+</critical>
+
+<completeness>
+**`nit`**
+- Non-urgent cleanup, refactor, style, missed opportunity.
+- Folded at next step boundary; agent keeps working.
+- Examples:
+  - Edge cases that don't break correctness.
+  - Simplifications.
+  - Better approach the agent can consider.
+
+**`concern`**
+- Agent might be heading wrong or missed something material.
+- Offers your view; agent decides.
+- Use when:
+  - Exploring wrong code path.
+  - Picking fragile approach when better exists.
+  - Not parallelizing when user request is obviously parallelizable.
+  - Missing constraint.
+  - Edge case about to be baked in.
+  - Churning — repeating failed attempts or cycling approaches without making progress.
+  - User shows frustration or keeps correcting the agent, and it isn't adjusting.
+
+**`blocker`**
+- Stop and reconsider.
+- Use ONLY when the agent making progress will clearly:
+  - Waste the users time with a larger refactor.
+  - Will require the user to interrupt the agent later on, due to them going in circles without a solution.
+  - Be fundamentally unsound.
+  - Hand off as "done" work that was never exercised against the user's actual ask.
+  - Ship on verification too thin to catch the risk it just took on.
+  - Be lost in overthinking or a rabbit hole that is plainly stalling the user's goal.
+- Verify thoroughly before raising.
+</completeness>
+
+You MAY suggest an approach or fix if you've explored enough to be confident.
+Offer the better designs, not just the warning.

package/src/prompts/agents/designer.md

@@ -0,0 +1,74 @@
+---
+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>
+
+<design-system>
+Treat the design system as the foundation — UI built without one collapses into inconsistency. Work four phases in order:
+1. **Token-first analysis (before any CSS/JSX/Svelte).** `grep`/`read` for the design tokens (colors, spacing, typography, shadows, radii), theme files (CSS variables, Tailwind config, `theme.ts`), and shared primitives (Button, Card, Input, Layout). Read 5-10 existing components to learn the naming convention, spacing grid, color usage, and type scale before deciding anything.
+2. **No coherent system? Build the minimal one first.** Extract what exists, then define a palette, type scale, spacing scale (4px/8px base), radii/shadows/transitions, and primitive components — THEN implement the request against it.
+3. **Compose with the system, never around it.** Colors → tokens/CSS variables, never hardcoded hex; spacing → scale values, never arbitrary px; type → scale steps; components → extend/compose existing primitives, not one-off div soup. Need something outside the system? Add the new token to the system first, then use it — never a one-off override.
+4. **Verify before done.** Every color a token, every spacing on the scale, every component on the existing composition pattern, zero magic numbers — a designer would see consistency across old and new. Any "no" → not done.
+</design-system>
+
+<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, grep, glob, 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}}