@astrofoundry/pi-astro 0.8.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @astrofoundry/pi-astro
 
-Personal customizations for the [pi coding agent](https://github.com/badlogic/pi-mono) — registers an `astro_agent` tool, a `grimoire` docs tool, a `claude-globals` rules-injection extension, 8 curated subagents, 3 skills, and an `astro` theme.
+Personal customizations for the [pi coding agent](https://github.com/badlogic/pi-mono) — registers an `astro_agent` tool, a `grimoire` docs tool, a `claude-globals` rules-injection extension, a `caveman` compressed-output toggle, 8 curated subagents, 4 skills, and an `astro` theme.
 
 ## Full setup
 
@@ -66,12 +66,13 @@ pi                # launch; confirm [Extensions] lists astro-agents, claude-glob
   - **macOS voice install (required once for the default):** open **System Settings → Accessibility → Spoken Content → System Voice → Manage Voices…**, expand **English**, check **Samantha (Enhanced)**, click **Done** to download (~500 MB – 1 GB). Verify with `say -v "Samantha (Enhanced)" hi`. If the voice is missing, `say` errors silently and you'll only hear the Glass sound.
 - `vscode-image` — only active inside VS Code's integrated terminal (`TERM_PROGRAM=vscode`). Switches pi-tui's image output to the **Kitty graphics protocol** so images returned by tools like `gemini_image` render as real pixels instead of the `[Image: …]` text fallback. **Requires enabling `Terminal › Integrated: Enable Images` in VS Code settings** (off by default); restart the integrated terminal after flipping it. Disable with `PI_VSCODE_IMAGE_OFF=1`. `/vscode-image` prints current status.
 - `claude-globals` — auto-injects `~/.claude/CLAUDE.md` into every pi session's system prompt
+- `caveman` — `/caveman [lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off|status]` toggles a persistent compressed-output mode. No argument toggles between off and the default level (`full`). Active level is shown as a footer badge and survives `/reload`. The skill body at `skills/caveman/SKILL.md` is also available as a one-shot via `/skill:caveman`.
 
 **Bundled subagents** (callable via `astro_agent`):
 - `code-reviewer`, `google-tech-lead`, `spec-writer`, `tester-api`, `tester-ui`, `ui-architect`, `ui-design-system`, `ui-frontend-developer`
 
 **Skills** (loadable via `/skill:<name>`):
-- `playwright-cli`, `postman-cli`, `raycast-script-creator`
+- `playwright-cli`, `postman-cli`, `raycast-script-creator`, `caveman`
 
 **Theme:**
 - `astro` — dark, gold accent, GitHub-dark-inspired

package/extensions/caveman/README.md

@@ -0,0 +1,80 @@
+# caveman
+
+Persistent compressed-output mode for the [pi coding agent](https://github.com/badlogic/pi-mono). Strips fillers, hedging, and connectives from assistant prose to cut output tokens by ~70-75% while preserving every technical fact. Code, error strings, command lines, paths, identifiers, and version numbers stay untouched.
+
+Ships as part of [`@astrofoundry/pi-astro`](../../README.md). No extra install.
+
+## Quick start
+
+In any pi session:
+
+```
+/caveman
+```
+
+Caveman is now on at level `full`. Type the same command again to switch it off. The active level is shown as a footer badge and survives `/reload`.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/caveman` | Toggle: off → `full`, on → off |
+| `/caveman lite` | Activate at level `lite` |
+| `/caveman full` | Activate at level `full` (default) |
+| `/caveman ultra` | Activate at level `ultra` |
+| `/caveman wenyan-lite` | Activate at level `wenyan-lite` |
+| `/caveman wenyan-full` | Activate at level `wenyan-full` |
+| `/caveman wenyan-ultra` | Activate at level `wenyan-ultra` |
+| `/caveman off` | Deactivate |
+| `/caveman status` | Print the current level |
+
+Argument autocomplete is wired — type `/caveman ` and tab-cycle the levels.
+
+You can also deactivate by saying "stop caveman" or "normal mode" in plain prose.
+
+## Levels
+
+Pick the trade-off between compression and readability:
+
+| Level | Behaviour | Example answer to "Why does this React component re-render?" |
+|---|---|---|
+| `lite` | Drop fillers and pleasantries only. Full sentences, articles kept. | "Your component re-renders because every render creates a new object reference for the prop. Wrap it in `useMemo`." |
+| `full` | Drop articles, fragments allowed. Default. | "New object ref each render. Inline obj prop = new ref = re-render. Wrap in `useMemo`." |
+| `ultra` | Aggressive abbreviation, arrows for causality. | "Inline obj prop → new ref → re-render. `useMemo`." |
+| `wenyan-lite` | Classical Chinese register, modern grammar. | "組件每次重繪皆生新對象參照。以 `useMemo` 包之。" |
+| `wenyan-full` | Full 文言文, classical particles. | "每繪生新參照，故重繪。以 `useMemo` 包之。" |
+| `wenyan-ultra` | Maximum classical compression. | "新參照→重繪。`useMemo` 包。" |
+
+## What stays normal
+
+Caveman never applies to:
+
+- **Source code, commit messages, PR descriptions, code review comments** — written in normal prose.
+- **Documentation files** (`.md`, `.mdx`, `.rst`) — caveman is for chat, not artifacts.
+- **Quoted log lines, stack traces, error messages** — reproduced exactly.
+
+Caveman also drops itself temporarily for safety:
+
+- Security warnings.
+- Confirmations for destructive or irreversible operations.
+- Multi-step procedures whose order matters.
+- When you ask a clarifying question or repeat yourself.
+
+The mode resumes immediately after the clarified step is complete.
+
+## One-shot vs persistent
+
+Two ways to use it:
+
+- **Persistent** — `/caveman` (or `/caveman <level>`). Stays on until you turn it off. Restored across `/reload` and session resume.
+- **One-shot** — `/skill:caveman`. Loads the skill content for a single response, then the next reply returns to normal. Useful when you want a single terse answer without committing to a mode.
+
+## State and persistence
+
+State lives in the pi session itself — no flag files in your home directory, no shell scripts, no symlink risk. Each session keeps its own toggle, so two pi sessions in different projects can run different modes.
+
+## Tips
+
+- If you find caveman too clipped while debugging tricky logic, switch to `lite` for the duration: `/caveman lite`.
+- Use `/caveman ultra` for short Q&A and debugging chains. Pair it with thinking levels and small models to keep latency low.
+- The wenyan levels are useful when you genuinely want the classical register — they are not a joke language and require both you and the model to be comfortable reading 文言文.

package/extensions/caveman/index.test.ts

@@ -0,0 +1,253 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type Handler = (event: unknown, ctx: unknown) => unknown | Promise<unknown>;
+
+interface CommandOptions {
+    description?: string;
+    handler: (args: string, ctx: unknown) => Promise<void> | void;
+    getArgumentCompletions?: (prefix: string) => unknown;
+}
+
+interface FakePi {
+    handlers: Record<string, Handler>;
+    commands: Map<string, CommandOptions>;
+    appendEntry: ReturnType<typeof vi.fn>;
+    on: (event: string, h: Handler) => void;
+    registerCommand: (name: string, opts: CommandOptions) => void;
+}
+
+function makePi(): FakePi {
+    const handlers: Record<string, Handler> = {};
+    const commands = new Map<string, CommandOptions>();
+    return {
+        handlers,
+        commands,
+        appendEntry: vi.fn(),
+        on(event, h) {
+            handlers[event] = h;
+        },
+        registerCommand(name, opts) {
+            commands.set(name, opts);
+        },
+    };
+}
+
+interface FakeCtx {
+    ui: {
+        notify: ReturnType<typeof vi.fn>;
+        setStatus: ReturnType<typeof vi.fn>;
+    };
+    sessionManager: { getEntries: () => unknown[] };
+}
+
+function makeCtx(entries: unknown[] = []): FakeCtx {
+    return {
+        ui: {
+            notify: vi.fn(),
+            setStatus: vi.fn(),
+        },
+        sessionManager: {
+            getEntries: () => entries,
+        },
+    };
+}
+
+describe("caveman extension", () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    async function load(): Promise<typeof import("./index.ts")> {
+        return await import("./index.ts");
+    }
+
+    async function install(): Promise<{ pi: FakePi; mod: Awaited<ReturnType<typeof load>> }> {
+        const mod = await load();
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        return { pi, mod };
+    }
+
+    it("registers /caveman command and the two lifecycle handlers", async () => {
+        const mod = await load();
+        const pi = makePi();
+        mod.default(pi as unknown as Parameters<typeof mod.default>[0]);
+        expect(pi.commands.has("caveman")).toBe(true);
+        expect(pi.handlers.session_start).toBeDefined();
+        expect(pi.handlers.before_agent_start).toBeDefined();
+    });
+
+    it("/caveman with no args toggles on to default level (full)", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("", ctx);
+        expect(pi.appendEntry).toHaveBeenCalledWith("caveman-mode", { level: "full" });
+        expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", expect.stringContaining("full"));
+        expect(ctx.ui.notify).toHaveBeenCalledWith("caveman: full", "info");
+    });
+
+    it("/caveman called twice with no args toggles back off", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("", ctx);
+        await pi.commands.get("caveman")!.handler("", ctx);
+        expect(pi.appendEntry).toHaveBeenLastCalledWith("caveman-mode", { level: null });
+        expect(ctx.ui.setStatus).toHaveBeenLastCalledWith("caveman", undefined);
+        expect(ctx.ui.notify).toHaveBeenLastCalledWith("caveman: off", "info");
+    });
+
+    it.each(["lite", "full", "ultra", "wenyan-lite", "wenyan-full", "wenyan-ultra"])(
+        "/caveman %s activates that level",
+        async (level) => {
+            const { pi } = await install();
+            const ctx = makeCtx();
+            await pi.commands.get("caveman")!.handler(level, ctx);
+            expect(pi.appendEntry).toHaveBeenCalledWith("caveman-mode", { level });
+            expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", `🪨 caveman:${level}`);
+            expect(ctx.ui.notify).toHaveBeenCalledWith(`caveman: ${level}`, "info");
+        },
+    );
+
+    it("/caveman off clears status and persists null level", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("ultra", ctx);
+        await pi.commands.get("caveman")!.handler("off", ctx);
+        expect(pi.appendEntry).toHaveBeenLastCalledWith("caveman-mode", { level: null });
+        expect(ctx.ui.setStatus).toHaveBeenLastCalledWith("caveman", undefined);
+        expect(ctx.ui.notify).toHaveBeenLastCalledWith("caveman: off", "info");
+    });
+
+    it("/caveman status reports current level without changing state", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("ultra", ctx);
+        const persistedBefore = pi.appendEntry.mock.calls.length;
+        await pi.commands.get("caveman")!.handler("status", ctx);
+        expect(pi.appendEntry.mock.calls.length).toBe(persistedBefore);
+        expect(ctx.ui.notify).toHaveBeenLastCalledWith("caveman: ultra", "info");
+    });
+
+    it("/caveman status reports off when inactive", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("status", ctx);
+        expect(pi.appendEntry).not.toHaveBeenCalled();
+        expect(ctx.ui.notify).toHaveBeenCalledWith("caveman: off", "info");
+    });
+
+    it("/caveman with an unknown argument warns and does not change state", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("nonsense", ctx);
+        expect(pi.appendEntry).not.toHaveBeenCalled();
+        expect(ctx.ui.setStatus).not.toHaveBeenCalled();
+        expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringMatching(/unknown level/), "warning");
+    });
+
+    it("argument autocomplete returns wenyan completions for 'wen'", async () => {
+        const { pi } = await install();
+        const completions = pi.commands.get("caveman")!.getArgumentCompletions!("wen");
+        expect(completions).toEqual(
+            expect.arrayContaining([
+                { value: "wenyan-lite", label: "wenyan-lite" },
+                { value: "wenyan-full", label: "wenyan-full" },
+                { value: "wenyan-ultra", label: "wenyan-ultra" },
+            ]),
+        );
+    });
+
+    it("argument autocomplete returns null when no candidate matches", async () => {
+        const { pi } = await install();
+        const completions = pi.commands.get("caveman")!.getArgumentCompletions!("zzz");
+        expect(completions).toBeNull();
+    });
+
+    it("argument autocomplete includes off and status", async () => {
+        const { pi } = await install();
+        const completions = pi.commands.get("caveman")!.getArgumentCompletions!("");
+        expect(completions).toEqual(
+            expect.arrayContaining([
+                { value: "off", label: "off" },
+                { value: "status", label: "status" },
+            ]),
+        );
+    });
+
+    it("session_start restores activeLevel from the latest custom entry", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx([
+            { type: "custom", customType: "caveman-mode", data: { level: "full" } },
+            { type: "custom", customType: "caveman-mode", data: { level: "ultra" } },
+        ]);
+        await pi.handlers.session_start({}, ctx);
+        expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", "🪨 caveman:ultra");
+        const result = (await pi.handlers.before_agent_start(
+            { systemPrompt: "ORIG" },
+            makeCtx(),
+        )) as { systemPrompt: string };
+        expect(result.systemPrompt).toContain("CAVEMAN MODE ACTIVE — level: ultra");
+    });
+
+    it("session_start clears status when the latest entry persisted off", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx([
+            { type: "custom", customType: "caveman-mode", data: { level: "full" } },
+            { type: "custom", customType: "caveman-mode", data: { level: null } },
+        ]);
+        await pi.handlers.session_start({}, ctx);
+        expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", undefined);
+    });
+
+    it("session_start ignores unrelated custom entries and corrupt level data", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx([
+            { type: "custom", customType: "other-extension", data: { level: "full" } },
+            { type: "custom", customType: "caveman-mode", data: { level: "not-a-real-level" } },
+        ]);
+        await pi.handlers.session_start({}, ctx);
+        expect(ctx.ui.setStatus).toHaveBeenCalledWith("caveman", undefined);
+    });
+
+    it("before_agent_start returns void when caveman is inactive", async () => {
+        const { pi } = await install();
+        const result = await pi.handlers.before_agent_start(
+            { systemPrompt: "ORIG" },
+            makeCtx(),
+        );
+        expect(result).toBeUndefined();
+    });
+
+    it("before_agent_start appends caveman ruleset filtered to the active level", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("ultra", ctx);
+        const result = (await pi.handlers.before_agent_start(
+            { systemPrompt: "ORIG" },
+            makeCtx(),
+        )) as { systemPrompt: string };
+        expect(result.systemPrompt.startsWith("ORIG\n\n")).toBe(true);
+        expect(result.systemPrompt).toContain("CAVEMAN MODE ACTIVE — level: ultra");
+        expect(result.systemPrompt).toContain("**ultra**");
+        expect(result.systemPrompt).not.toContain("**lite**");
+        expect(result.systemPrompt).not.toContain("**wenyan-lite**");
+        expect(result.systemPrompt).not.toContain("**wenyan-full**");
+    });
+
+    it("before_agent_start keeps only the active level's worked-example bullets", async () => {
+        const { pi } = await install();
+        const ctx = makeCtx();
+        await pi.commands.get("caveman")!.handler("lite", ctx);
+        const result = (await pi.handlers.before_agent_start(
+            { systemPrompt: "ORIG" },
+            makeCtx(),
+        )) as { systemPrompt: string };
+        expect(result.systemPrompt).toMatch(/^- lite:/m);
+        expect(result.systemPrompt).not.toMatch(/^- ultra:/m);
+        expect(result.systemPrompt).not.toMatch(/^- wenyan-full:/m);
+    });
+});

package/extensions/caveman/index.ts

@@ -0,0 +1,169 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const LEVELS = [
+    "lite",
+    "full",
+    "ultra",
+    "wenyan-lite",
+    "wenyan-full",
+    "wenyan-ultra",
+] as const;
+
+type Level = (typeof LEVELS)[number];
+
+const DEFAULT_LEVEL: Level = "full";
+const ENTRY_TYPE = "caveman-mode";
+const STATUS_KEY = "caveman";
+
+const extensionDir = path.dirname(fileURLToPath(import.meta.url));
+const skillPath = path.resolve(
+    extensionDir,
+    "..",
+    "..",
+    "skills",
+    "caveman",
+    "SKILL.md",
+);
+
+interface PersistedState {
+    level: Level | null;
+}
+
+function isLevel(value: unknown): value is Level {
+    return typeof value === "string" && (LEVELS as readonly string[]).includes(value);
+}
+
+function parseLevel(arg: string): Level | null {
+    return isLevel(arg) ? arg : null;
+}
+
+function readSkillBody(): string {
+    const raw = fs.readFileSync(skillPath, "utf8");
+    return raw.replace(/^---[\s\S]*?---\s*/, "");
+}
+
+function filterForLevel(body: string, level: Level): string {
+    return body
+        .split("\n")
+        .reduce<string[]>((acc, line) => {
+            const tableRow = line.match(/^\|\s*\*\*([^*|]+?)\*\*\s*\|/);
+            if (tableRow) {
+                if (tableRow[1] === level) acc.push(line);
+                return acc;
+            }
+            const exampleBullet = line.match(/^- (\S+?):\s/);
+            if (exampleBullet) {
+                if (exampleBullet[1] === level) acc.push(line);
+                return acc;
+            }
+            acc.push(line);
+            return acc;
+        }, [])
+        .join("\n");
+}
+
+function buildInjection(level: Level, body: string): string {
+    return `CAVEMAN MODE ACTIVE — level: ${level}\n\n${filterForLevel(body, level)}`;
+}
+
+function statusText(level: Level): string {
+    return `🪨 caveman:${level}`;
+}
+
+const HELP =
+    "Usage: /caveman [lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off|status]. " +
+    "No argument toggles between off and the default level (full).";
+
+export default function cavemanExtension(pi: ExtensionAPI): void {
+    let activeLevel: Level | null = null;
+    let cachedBody: string | null = null;
+
+    function loadBody(): string {
+        if (cachedBody === null) {
+            cachedBody = readSkillBody();
+        }
+        return cachedBody;
+    }
+
+    function persist(): void {
+        pi.appendEntry<PersistedState>(ENTRY_TYPE, { level: activeLevel });
+    }
+
+    pi.on("session_start", async (_event, ctx) => {
+        let restored: Level | null = null;
+        for (const entry of ctx.sessionManager.getEntries()) {
+            if (entry.type === "custom" && entry.customType === ENTRY_TYPE) {
+                const data = entry.data as PersistedState | undefined;
+                restored = data && isLevel(data.level) ? data.level : null;
+            }
+        }
+        activeLevel = restored;
+        ctx.ui.setStatus(STATUS_KEY, activeLevel ? statusText(activeLevel) : undefined);
+    });
+
+    pi.on("before_agent_start", async (event) => {
+        if (!activeLevel) return;
+        const body = loadBody();
+        return {
+            systemPrompt: `${event.systemPrompt}\n\n${buildInjection(activeLevel, body)}`,
+        };
+    });
+
+    pi.registerCommand("caveman", {
+        description: `Toggle compressed-output mode. ${HELP}`,
+        getArgumentCompletions: (prefix) => {
+            const items = [...LEVELS, "off", "status"];
+            const lower = prefix.toLowerCase();
+            const matches = items
+                .filter((value) => value.startsWith(lower))
+                .map((value) => ({ value, label: value }));
+            return matches.length > 0 ? matches : null;
+        },
+        handler: async (args, ctx) => {
+            const arg = args.trim().toLowerCase();
+
+            if (arg === "status") {
+                ctx.ui.notify(
+                    activeLevel ? `caveman: ${activeLevel}` : "caveman: off",
+                    "info",
+                );
+                return;
+            }
+
+            if (arg === "off") {
+                activeLevel = null;
+                persist();
+                ctx.ui.setStatus(STATUS_KEY, undefined);
+                ctx.ui.notify("caveman: off", "info");
+                return;
+            }
+
+            if (arg === "") {
+                activeLevel = activeLevel ? null : DEFAULT_LEVEL;
+            } else {
+                const level = parseLevel(arg);
+                if (!level) {
+                    ctx.ui.notify(
+                        `caveman: unknown level "${arg}". ${HELP}`,
+                        "warning",
+                    );
+                    return;
+                }
+                activeLevel = level;
+            }
+
+            persist();
+            ctx.ui.setStatus(
+                STATUS_KEY,
+                activeLevel ? statusText(activeLevel) : undefined,
+            );
+            ctx.ui.notify(
+                activeLevel ? `caveman: ${activeLevel}` : "caveman: off",
+                "info",
+            );
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/skills/caveman/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: caveman
+description: >
+  Persistent compressed-output mode. Strips fillers, hedging, and connectives
+  from assistant prose to cut output tokens by ~70-75% while preserving every
+  technical fact. Six intensity levels: lite, full (default), ultra, wenyan-lite,
+  wenyan-full, wenyan-ultra. Activate with /caveman or /skill:caveman; deactivate
+  with /caveman off, "stop caveman", or "normal mode".
+---
+
+# Caveman Mode
+
+Output compression via principled prose-stripping. Substance is preserved
+verbatim — only redundancy and social padding are removed. Code, error
+strings, command lines, paths, identifiers, and version numbers are reproduced
+unchanged.
+
+## Persistence
+
+While active, **every** assistant response uses caveman compression. Do not
+drift back to verbose prose mid-conversation, even after long context, after
+context compaction, or after style instructions injected by other extensions.
+Resume caveman immediately after any unavoidable break (security warning,
+destructive-action confirmation, multi-step procedure).
+
+The level set by `/caveman <level>` persists until changed or session end.
+Switch off only on explicit user request: "stop caveman", "normal mode", or
+`/caveman off`.
+
+## Compression rules
+
+Drop:
+
+- Articles when grammatically optional (a, an, the).
+- Filler adverbs and intensifiers (just, really, basically, actually, simply, very).
+- Pleasantries (sure, certainly, of course, happy to, let me, I'd be glad to).
+- Hedging phrases (it seems, perhaps, you might want to, I think).
+- Restating the question before answering it.
+
+Keep:
+
+- Every technical fact, parameter name, file path, command, and version number.
+- Code blocks verbatim. Error messages quoted exactly.
+- Cause-and-effect order — never reorder steps for terseness.
+- Punctuation needed for parsing (commas separating list items, periods between independent claims).
+
+Sentence pattern: `<subject> <action> <reason>. <next step>.`
+
+Anti-example: "Sure! I'd be happy to help you with that. The issue you're seeing is most likely caused by..."
+Example: "Bug in auth middleware. Token expiry uses `<` not `<=`. Fix:"
+
+## Intensity levels
+
+| Level | Behaviour |
+|---|---|
+| **lite** | Drop fillers and pleasantries only. Keep articles + full sentences. Professional but tight. |
+| **full** | Drop articles. Sentence fragments allowed. Short synonyms (fix not "implement a solution for"). Default. |
+| **ultra** | Abbreviate (DB, auth, cfg, req, res, fn, impl). Replace conjunctions with arrows for causality (X → Y). Single word when sufficient. |
+| **wenyan-lite** | Classical Chinese register, modern grammar. Drop fillers and hedging. |
+| **wenyan-full** | Full 文言文 — verb precedes object, omit subject when implied, classical particles (之 / 乃 / 為 / 其). 80–90% character reduction. |
+| **wenyan-ultra** | Maximum classical compression. One classical phrase per thought. |
+
+### Worked example — "Why does this React component re-render on every parent update?"
+
+- lite: "Your component re-renders because every render creates a new object reference for the prop. Wrap it in `useMemo`."
+- full: "New object ref each render. Inline obj prop = new ref = re-render. Wrap in `useMemo`."
+- ultra: "Inline obj prop → new ref → re-render. `useMemo`."
+- wenyan-lite: "組件每次重繪皆生新對象參照。以 `useMemo` 包之。"
+- wenyan-full: "每繪生新參照，故重繪。以 `useMemo` 包之。"
+- wenyan-ultra: "新參照→重繪。`useMemo` 包。"
+
+### Worked example — "Explain database connection pooling."
+
+- lite: "Connection pooling reuses already-open connections instead of opening a new one per request, avoiding handshake overhead."
+- full: "Pool reuse open connections. No new handshake per request."
+- ultra: "Pool = reuse conn. Skip handshake → fast under load."
+- wenyan-lite: "連接池重用已開連接，免逐請求重握之耗。"
+- wenyan-full: "池存連接而重用，無逐請求重握之耗。"
+- wenyan-ultra: "池連，免握。"
+
+## Auto-clarity (override caveman temporarily)
+
+Drop caveman compression when ambiguity would harm correctness:
+
+- Security warnings.
+- Confirmations for destructive or irreversible operations.
+- Multi-step procedures whose order matters and where fragments would invite misreading.
+- The user repeats a question or asks for clarification.
+
+Use full prose for the duration of the override. Resume caveman immediately
+after the clarified step is complete.
+
+Example — destructive operation:
+
+> **Warning:** the next command permanently deletes every row in `users` and
+> cannot be undone:
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Verify a current backup exists before running. Caveman resume.
+
+## Boundaries (caveman never applies)
+
+- Source code, commit messages, PR descriptions, code review comments — write in normal prose.
+- Documentation files (`.md`, `.mdx`, `.rst`) — caveman is for chat, not artifacts.
+- Quoted log lines, stack traces, error messages — reproduce exactly.
+
+## Deactivation
+
+- `/caveman off` — explicit slash command.
+- "stop caveman" / "normal mode" / "disable caveman" — natural-language requests.
+
+After deactivation, return to normal prose immediately on the next response.