ashlr-plugin 1.36.4

package/servers/websearch-server-handlers.ts

@@ -0,0 +1,215 @@
+/**
+ * websearch-server-handlers — side-effect module.
+ *
+ * Importing this file registers the ashlr__websearch tool into the shared
+ * registry (_tool-base.ts). Used by both the standalone entry point
+ * (websearch-server.ts) and the router (_router.ts via _router-handlers.ts).
+ */
+
+import { registerTool, type ToolCallContext, type ToolResult } from "./_tool-base";
+import { summarizeIfLarge } from "./_summarize";
+import { recordSavingAccurate } from "./_accounting";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface WebSearchArgs {
+  query: string;
+  maxResults?: number;
+  summarize?: boolean;
+}
+
+interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+  score?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Core logic (exported for tests)
+// ---------------------------------------------------------------------------
+
+/** Truncate a snippet to ~maxChars without cutting mid-word. */
+function snipSnippet(s: string, maxChars: number): string {
+  if (s.length <= maxChars) return s;
+  const cut = s.lastIndexOf(" ", maxChars);
+  const end = cut > maxChars * 0.7 ? cut : maxChars;
+  return s.slice(0, end) + "…";
+}
+
+/** Extract domain from a URL string. Returns the full URL on parse failure. */
+function domainOf(url: string): string {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Deduplicate results by domain — keep the highest-scored (or first) result
+ * per domain.
+ */
+function dedupeByDomain(results: SearchResult[]): SearchResult[] {
+  const seen = new Map<string, SearchResult>();
+  for (const r of results) {
+    const domain = domainOf(r.url);
+    const existing = seen.get(domain);
+    if (!existing) {
+      seen.set(domain, r);
+    } else {
+      // Prefer higher score; if scores are equal/absent, keep first.
+      const existingScore = existing.score ?? 0;
+      const newScore = r.score ?? 0;
+      if (newScore > existingScore) seen.set(domain, r);
+    }
+  }
+  return Array.from(seen.values());
+}
+
+export async function ashlrWebsearch(args: WebSearchArgs): Promise<string> {
+  const { query, maxResults = 5, summarize: doSummarize = true } = args;
+
+  // -------------------------------------------------------------------------
+  // Native WebSearch invocation.
+  //
+  // Claude Code's WebSearch tool is not callable as a subprocess — it lives
+  // inside the harness process. We expose it as a passthrough stub here and
+  // accept that the real compression value lies in post-processing the results
+  // that the hook redirects through us. When this function is called directly
+  // (e.g. from tests or in contexts where results are provided) it handles
+  // the deduplication + truncation + summarization pipeline.
+  //
+  // In the hook redirect flow: the PreToolUse hook blocks the native WebSearch
+  // and asks the agent to call ashlr__websearch instead. The agent re-issues
+  // the search query. Since we cannot invoke WebSearch directly from an MCP
+  // tool, we return a structured stub that the agent can act on.
+  // -------------------------------------------------------------------------
+
+  // Build a lightweight structured response.
+  // In production this is where results from the native search would arrive.
+  // We emit a clear contract so the agent knows what happened.
+  const rawPayload = JSON.stringify({ query, note: "websearch-redirect-stub" });
+  const rawBytes = rawPayload.length;
+
+  const output = {
+    query,
+    results: [] as Array<{ title: string; url: string; snippet: string; score?: number }>,
+    summary: undefined as string | undefined,
+    droppedCount: 0,
+    note: "[ashlr__websearch] WebSearch results are not directly accessible from an MCP tool subprocess. " +
+      "This tool compresses WebSearch output when invoked via the hook redirect path. " +
+      "If you need web search results, ensure the PreToolUse hook is active and call WebSearch — " +
+      "it will be redirected through ashlr__websearch automatically. " +
+      `Query: ${query}`,
+  };
+
+  const compactJson = JSON.stringify(output);
+  const compactBytes = compactJson.length;
+
+  await recordSavingAccurate({
+    rawBytes,
+    compactBytes,
+    toolName: "ashlr__websearch",
+    cacheHit: false,
+  });
+
+  return compactJson;
+}
+
+/**
+ * Process raw WebSearch results (as a parsed array) through the dedup +
+ * truncation + summarize pipeline. Exported for tests.
+ */
+export async function processWebSearchResults(
+  query: string,
+  rawResults: SearchResult[],
+  opts: { maxResults?: number; summarize?: boolean } = {},
+): Promise<{
+  query: string;
+  results: SearchResult[];
+  summary?: string;
+  droppedCount: number;
+  rawBytes: number;
+  compactBytes: number;
+}> {
+  const { maxResults = 5, summarize: doSummarize = true } = opts;
+
+  const rawBytes = JSON.stringify(rawResults).length;
+
+  // Step 1: Deduplicate by domain.
+  const deduped = dedupeByDomain(rawResults);
+  const droppedByDedupe = rawResults.length - deduped.length;
+
+  // Step 2: Sort by score descending, take top maxResults.
+  const sorted = deduped.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+  const kept = sorted.slice(0, maxResults);
+  const droppedCount = droppedByDedupe + Math.max(0, deduped.length - maxResults);
+
+  // Step 3: Snip each snippet to ~500 chars.
+  const compactResults: SearchResult[] = kept.map((r) => ({
+    title: r.title,
+    url: r.url,
+    snippet: snipSnippet(r.snippet ?? "", 500),
+    score: r.score,
+  }));
+
+  // Step 4: Optionally summarize.
+  let summary: string | undefined;
+  if (doSummarize && compactResults.length > 3) {
+    const joined = compactResults
+      .map((r, i) => `[${i + 1}] ${r.title}\n${r.url}\n${r.snippet}`)
+      .join("\n\n");
+    const summResult = await summarizeIfLarge(joined, {
+      toolName: "ashlr__websearch",
+      systemPrompt:
+        "You are summarizing web search results for an AI coding agent. Output ≤300 chars as one paragraph. " +
+        "Preserve: the most relevant finding with its source URL, key facts or code snippets mentioned. " +
+        "Omit ads, marketing copy, and irrelevant results. Output as plain text.",
+      thresholdBytes: 1, // Always summarize when called.
+    });
+    if (summResult.summarized || summResult.wasCached) {
+      summary = summResult.text;
+    }
+  }
+
+  const output = { query, results: compactResults, summary, droppedCount };
+  const compactBytes = JSON.stringify(output).length;
+
+  await recordSavingAccurate({
+    rawBytes,
+    compactBytes,
+    toolName: "ashlr__websearch",
+    cacheHit: false,
+  });
+
+  return { ...output, rawBytes, compactBytes };
+}
+
+// ---------------------------------------------------------------------------
+// Registration (side-effect on import)
+// ---------------------------------------------------------------------------
+
+registerTool({
+  name: "ashlr__websearch",
+  description:
+    "Token-efficient web search wrapper. Deduplicates results by domain, truncates snippets to ~500 chars, " +
+    "and synthesizes a 1-paragraph summary when more than 3 results are returned. " +
+    "Use instead of WebSearch to save 40-80% tokens on search result payloads. " +
+    "Args: query (required), maxResults (default 5), summarize (default true).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query:      { type: "string",  description: "Search query" },
+      maxResults: { type: "number",  description: "Max results to return (default 5)" },
+      summarize:  { type: "boolean", description: "Whether to synthesize a summary paragraph (default true)" },
+    },
+    required: ["query"],
+  },
+  handler: async (args: Record<string, unknown>, _ctx: ToolCallContext): Promise<ToolResult> => {
+    const text = await ashlrWebsearch(args as unknown as WebSearchArgs);
+    return { content: [{ type: "text", text }] };
+  },
+});

package/servers/websearch-server.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+/**
+ * ashlr-websearch MCP server — standalone entry point.
+ *
+ * Imports websearch-server-handlers (registers ashlr__websearch into the
+ * shared registry) then runs as a standalone stdio MCP server.
+ *
+ * For in-process router use, import websearch-server-handlers directly.
+ */
+
+import "./websearch-server-handlers";
+import { runStandalone } from "./_tool-base";
+
+// Re-export core logic so tests that import from this module keep working.
+export { ashlrWebsearch, processWebSearchResults } from "./websearch-server-handlers";
+
+if (import.meta.main) {
+  await runStandalone("ashlr-websearch", "0.1.0");
+}

package/servers/write-server-handlers.ts

@@ -0,0 +1,27 @@
+/**
+ * write-server-handlers — registers ashlr__write into the shared tool registry.
+ */
+
+import { registerTool, type ToolCallContext, type ToolResult } from "./_tool-base";
+import { ashlrWrite, formatWriteResult, type WriteArgs } from "./write-server";
+
+registerTool({
+  name: "ashlr__write",
+  description:
+    "Write content to a file without echoing the full content back. " +
+    "If the file already exists, delegates to ashlr__edit (full-file replace, compact diff response). " +
+    "If the file is new, creates it and returns a compact acknowledgment (path, bytes, sha8). " +
+    "Either way, the full file content is never returned — ~80% token savings vs native Write.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      filePath: { type: "string", description: "Absolute or cwd-relative path to write" },
+      content: { type: "string", description: "File content to write" },
+    },
+    required: ["filePath", "content"],
+  },
+  handler: async (args: Record<string, unknown>, _ctx: ToolCallContext): Promise<ToolResult> => {
+    const result = await ashlrWrite(args as unknown as WriteArgs);
+    return { content: [{ type: "text", text: formatWriteResult(result) }] };
+  },
+});

package/servers/write-server.ts

@@ -0,0 +1,97 @@
+/**
+ * write-server — ashlr__write tool implementation.
+ *
+ * Handles two cases:
+ *   1. File exists: delegates to ashlrEdit (full-file replace). The compact
+ *      diff summary from ashlrEdit is returned unchanged — same format,
+ *      ~80% token savings vs echoing the full new file.
+ *   2. File is new: writes it directly and returns a compact ack (path,
+ *      byte count, first-8-chars of sha256). Never echoes the content.
+ *
+ * Savings baseline:
+ *   - existing file: raw = content.length (Claude Code would echo it back);
+ *      compact = ashlrEdit's compact diff. recordSaving is already called
+ *      by ashlrEdit internally; no double-record here.
+ *   - new file: raw = content.length; compact = ack JSON bytes.
+ */
+
+import { readFile, writeFile } from "fs/promises";
+import { createHash } from "crypto";
+import { existsSync } from "fs";
+import { recordSaving } from "./_stats";
+import { clampToCwd } from "./_cwd-clamp";
+import { ashlrEdit, type EditResult } from "./edit-server";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface WriteArgs {
+  filePath: string;
+  content: string;
+}
+
+export interface WriteNewResult {
+  created: string;
+  bytes: number;
+  sha8: string;
+}
+
+export type WriteResult =
+  | { kind: "new"; ack: WriteNewResult }
+  | { kind: "existing"; editResult: EditResult };
+
+// ---------------------------------------------------------------------------
+// Core implementation
+// ---------------------------------------------------------------------------
+
+export async function ashlrWrite(input: WriteArgs): Promise<WriteResult> {
+  const { filePath, content } = input;
+
+  const clamp = clampToCwd(filePath, "ashlr__write");
+  if (!clamp.ok) throw new Error(clamp.message);
+  const abs = clamp.abs;
+
+  // Case 1: file exists — delegate to ashlrEdit (full-file replace).
+  // ashlrEdit internally calls recordSaving, so we don't double-record.
+  if (existsSync(abs)) {
+    const existingContent = await readFile(abs, "utf-8");
+    // Full-file replace: search = entire existing content, replace = new content.
+    const editResult = await ashlrEdit({
+      path: filePath,
+      search: existingContent,
+      replace: content,
+      strict: true,
+    });
+    return { kind: "existing", editResult };
+  }
+
+  // Case 2: new file — write it and return compact ack.
+  await writeFile(abs, content, "utf-8");
+
+  const sha8 = createHash("sha256").update(content).digest("hex").slice(0, 8);
+  const ack: WriteNewResult = {
+    created: abs,
+    bytes: content.length,
+    sha8,
+  };
+
+  // Record savings: raw = content bytes (what Claude Code would echo back);
+  // compact = ack JSON bytes.
+  const compactBytes = JSON.stringify(ack).length;
+  await recordSaving(content.length, compactBytes, "ashlr__write");
+
+  return { kind: "new", ack };
+}
+
+/**
+ * Format the WriteResult as a human-readable text response for the MCP tool.
+ */
+export function formatWriteResult(result: WriteResult): string {
+  if (result.kind === "new") {
+    const { created, bytes, sha8 } = result.ack;
+    return `[ashlr__write] created ${created}  ·  ${bytes} bytes  ·  sha8=${sha8}`;
+  }
+  // Delegate to the edit result text directly — same compact diff format.
+  return result.editResult.text;
+}

package/skills/ashlr-brief/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: ashlr-brief
+description: Tunable response-shortening skill for Claude Code. Trims filler from prose to reduce output tokens 30–55% while preserving grammar and code fidelity. Three intensity levels (lite / standard / concise). Auto-clarity exceptions for security, destructive actions, errors, and code blocks.
+---
+
+# Ashlr Brief
+
+Reduce token spend by trimming Claude's *output*, not just tool I/O. Inspired by [Julius Brussee's caveman](https://github.com/JuliusBrussee/caveman), but designed to remain readable in PRs, code reviews, and explanations — full grammar at the default level, no telegraphic "caveman voice" unless explicitly opted into.
+
+## Activation
+
+Three ways to activate:
+
+1. **Slash command** — `/ashlr-brief on standard`
+2. **Natural language** — "be brief", "tldr", "less tokens", "stop being brief"
+3. **Eco mode** — `/ashlr-eco-mode on` auto-activates `standard` if no level is already chosen
+
+Persistence: the active level is written to `~/.ashlr/brief.json` and re-injected on every SessionStart, so behavior stays stable across sessions until explicitly changed.
+
+## Intensity levels
+
+### `lite` — professional terseness
+- **Drop:** filler ("just", "really", "basically", "actually", "simply", "essentially", "in order to"), hedging ("might possibly", "I think it could"), self-narration ("Let me look at...", "I'll now...")
+- **Keep:** articles, complete sentences, paragraph breaks, full grammar, all explanations the user asked for
+- **Tone:** professional, direct, like a senior engineer in a code review
+- Expected output reduction: ~25–35%
+
+### `standard` — default — drop padding, keep grammar
+- All of `lite`, plus:
+- Drop transition padding ("Now that we have X, let's move on to Y", "As you can see")
+- Replace verbose constructions with short ones ("in order to" → "to", "due to the fact that" → "because")
+- Cut restating-the-question preambles
+- One-sentence summaries instead of "Here's what I did:" lists when the diff already shows it
+- **Keep:** complete sentences, articles, code blocks untouched
+- Expected output reduction: ~35–45%
+
+### `concise` — fragments + arrows allowed
+- All of `standard`, plus:
+- Sentence fragments OK when meaning is clear
+- Arrow notation for causality (`X → Y` instead of "X causes Y")
+- Common abbreviations OK (`db`, `auth`, `cfg`, `req`, `res`, `fn`, `ctx`)
+- Bullets over prose for lists of 3+
+- **Keep:** Code blocks, error messages, file paths, identifiers — never abbreviated
+- Expected output reduction: ~50–60%
+
+## Auto-clarity exceptions
+
+The brief level is **automatically suspended** for these contexts (full grammar restored just for that response):
+
+1. **Destructive actions** — `rm -rf`, `git reset --hard`, `git push --force`, `DROP TABLE`, dropping migrations, deleting branches, killing processes
+2. **Security findings** — credentials, secrets, vulnerabilities, RLS holes, XSS/SQLi/SSRF
+3. **Multi-step migrations** — DB schema changes, breaking-API rollouts, anything where ambiguity costs hours
+4. **Error messages and stack traces** — render verbatim, no compression
+5. **Code blocks, diffs, file:line citations** — pass through untouched at all levels
+6. **First response of a session** — full grammar so the user sees what they're working with before brevity engages
+
+## Anti-patterns (do NOT do)
+
+- Do **not** drop articles at `lite` or `standard` — caveman-voice is opt-in via `concise` only
+- Do **not** abbreviate identifiers, file paths, or function names
+- Do **not** compress error messages, command output, or stack traces
+- Do **not** silently apply brief to a response that's already in an auto-clarity exception
+- Do **not** activate without a visible status-line indicator — the user must always be able to see the active level
+
+## Example transforms
+
+**Before (verbose):**
+> I'll now look at the file you mentioned. Let me read it first to understand the structure. Looking at this, I can see that the function `handleAuth` is essentially doing token validation. I think we should probably refactor it in order to make it more testable.
+
+**After (`standard`):**
+> The `handleAuth` function does token validation. Refactor for testability: extract the validation step into a pure helper.
+
+**After (`concise`):**
+> `handleAuth` → token validation. Refactor: extract validation → pure helper. More testable.
+
+## Implementation note
+
+This skill is loaded via `hooks/sessionstart-brief.ts` which reads `~/.ashlr/brief.json`, then injects the corresponding section above into the session's `additionalContext`. The natural-language toggles are handled by `hooks/userpromptsubmit-brief-trigger.ts`. The status-line cell `[brief: <level>]` is rendered by `scripts/savings-status-line.ts`.
+
+Pro/Team tier: project-level enforcement via `.ashlr/brief.json` (in the repo root) is honored only when committed by a Pro/Team user; free users can still set their own user-level preference at `~/.ashlr/brief.json`.

package/skills/ashlr-codex-doctor/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: ashlr-codex-doctor
+description: Check Ashlr's Codex plugin packaging, MCP manifest, hooks, skills, and workspace allow-list. Use when Codex setup, plugin loading, or MCP registration looks wrong.
+---
+
+# Ashlr Codex Doctor
+
+Run:
+
+```sh
+ashlr-plugin codex-doctor --json
+```
+
+Read the JSON before changing files. Focus on:
+
+- `pluginManifest.present`, `hasSkills`, `hasMcpServers`, and `hasHooks`
+- `mcp.server` and `mcp.bin`
+- `hooks.defaultMode`, which should normally be `nudge`
+- `workspaceAccess.allowProjectPaths` when tools refuse paths outside cwd
+
+If workspace access is the issue, set `ASHLR_ALLOW_PROJECT_PATHS` to the absolute project root before launching Codex or pass explicit `cwd` arguments to Ashlr MCP tools.

package/skills/ashlr-codex-efficient-tools/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: ashlr-codex-efficient-tools
+description: Codex-native efficient tool workflow. Prefer Ashlr MCP read, grep, tree, bash, savings, and genome tools before native scans when they reduce context.
+---
+
+# Ashlr Codex Efficient Tools
+
+Use Ashlr MCP tools for high-volume context work:
+
+- Use `ashlr__orient` once before broad exploration when a genome exists.
+- Use `ashlr__grep` for search instead of repeated native scans.
+- Use `ashlr__tree` for compact directory maps.
+- Use `ashlr__read` for large files or files where only head/tail plus structure is needed.
+- Use `ashlr__bash` for verbose commands such as tests, typechecks, `git log`, and package installs.
+- Use `ashlr__savings` or `ashlr-plugin stats --json` to inspect token/cost savings.
+
+Keep native tools for tiny files, exact patch application, or commands where raw output is short and important.

package/skills/ashlr-codex-genome-refresh/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: ashlr-codex-genome-refresh
+description: Refresh or maintain Ashlr project genome state from Codex. Use after architectural changes, schema/routing changes, or substantial refactors.
+---
+
+# Ashlr Codex Genome Refresh
+
+After meaningful architecture changes, refresh project memory:
+
+```sh
+ashlr-plugin genome-refresh --json
+```
+
+When an MCP genome tool is available, prefer the direct tool:
+
+- `ashlr__genome_status` to inspect current genome state
+- `ashlr__genome_propose` for a concise update proposal
+- `ashlr__genome_consolidate` after reviewing pending proposals
+
+Do not propose routine typo fixes or test-only changes. One proposal per logical architectural change is enough.

package/skills/ashlr-codex-parallel-explore/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: ashlr-codex-parallel-explore
+description: Efficient parallel exploration habits for Codex. Use when a task needs several independent codebase questions answered before implementation.
+---
+
+# Ashlr Codex Parallel Explore
+
+For multi-file work, split exploration into independent questions:
+
+- One explorer maps ownership, entrypoints, and existing patterns.
+- Another explorer audits risks, tests, and edge cases.
+- Keep implementation local unless a worker can own a disjoint file set.
+
+Use Ashlr tools in each exploration:
+
+```sh
+ashlr-plugin codex-start --json
+```
+
+Then prefer `ashlr__orient`, `ashlr__grep`, `ashlr__tree`, and `ashlr__read` before opening raw files.

package/skills/ashlr-codex-savings/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: ashlr-codex-savings
+description: Inspect Ashlr token savings from Codex using host-neutral CLI and MCP surfaces.
+---
+
+# Ashlr Codex Savings
+
+Use either surface:
+
+```sh
+ashlr-plugin stats --json
+ashlr-plugin tools --json
+```
+
+When the MCP server is available, call `ashlr__savings` for an in-session summary.
+
+Stats are written after tool calls, not during MCP registration. If there are no stats yet, run one Ashlr MCP tool first.

package/skills/ashlr-cost-refactor/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ashlr-cost-refactor
+description: Token-efficient refactoring discipline for Claude Code. Diff-first before editing, structural edits for renames, find-all-refs then one multi_edit per file, no re-reads between edits, one genome proposal at the end. Reduces refactor session cost 40–65%.
+---
+
+# Ashlr Cost Refactor
+
+A structured discipline for refactoring tasks that minimizes token spend without sacrificing correctness.
+
+## Rules (active when this skill is enabled)
+
+### 1. Diff first
+Before editing anything, run `ashlr__diff` or `ashlr__diff_semantic` to understand what already changed (staged/unstaged). This prevents redundant edits to files that are already in the state you want.
+
+### 2. Structural edits for renames
+When renaming a symbol, type, or file — use `ashlr__edit_structural` instead of search/replace. Structural edit finds all references in one pass and renames them correctly, including imports and re-exports.
+
+### 3. Find all refs, then one `ashlr__multi_edit` per file
+Before editing a file, run `ashlr__grep` to find all references. Then apply all changes to that file in a single `ashlr__multi_edit` call. Do not make sequential single edits to the same file — each one burns a full round-trip.
+
+### 4. No re-reads between edits in a sequence
+Once you've read a file and know its structure, proceed through your edit sequence without re-reading. `ashlr__edit` and `ashlr__multi_edit` return diffs that confirm each change — that's sufficient to continue.
+
+### 5. One `ashlr__genome_propose` at the end
+After the refactor is complete and stable, write one genome proposal summarizing the entire change: what was renamed/moved, why, and the affected file paths. Do not propose mid-refactor.
+
+### 6. Verify with `ashlr__bash` not `Read`
+After a refactor, confirm with `bun run typecheck` or `bun test` via `ashlr__bash`. Do not re-read edited files to verify — the typecheck output is authoritative and far cheaper.
+
+## Sequence template
+
+```
+1. ashlr__diff_semantic()             — see what's already changed
+2. ashlr__grep("OldName|oldFn")       — find all refs
+3. ashlr__edit_structural(...)        — rename symbols
+   OR ashlr__multi_edit([...])        — batch all edits per file
+4. ashlr__bash("bun run typecheck")   — verify, not Read
+5. ashlr__genome_propose(summary)     — one proposal at the end
+```
+
+## Anti-patterns
+
+- Running `Read` before each edit in a multi-file refactor
+- Making 3 sequential `ashlr__edit` calls on the same file
+- Re-reading a file after editing it to confirm the change
+- Calling `ashlr__genome_propose` after each individual edit
+
+## Activation
+
+Enable via `/ashlr-cost-refactor on` or by writing `{"enabled":true}` to `~/.ashlr/cost-refactor.json`. Toggle off with `/ashlr-cost-refactor off`.

package/skills/ashlr-efficient/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: ashlr-efficient
+description: Output structure reshaper for Claude Code. Complements ashlr-brief's prose trimming by enforcing inverted-pyramid order, inline code for identifiers, tables for multi-item comparisons, and no transitional filler. Works standalone or alongside ashlr-brief.
+---
+
+# Ashlr Efficient
+
+Reshapes the **structure** of responses — not just their wordiness. Works independently of `ashlr-brief` (which trims prose volume). When both are active, both rulesets apply simultaneously.
+
+## Rules (active when this skill is enabled)
+
+### 1. Inverted pyramid — answer first
+Lead with the answer or conclusion. Context and explanation follow. Never open with background before the answer.
+
+**Before:** "In order to understand why this matters, we need to look at how auth works in this codebase. The token is validated in middleware..."
+**After:** "The `verifyToken` middleware at `src/auth.ts:42` is the validation point. It checks..."
+
+### 2. Inline code for all identifiers and paths
+Any function name, variable, type, file path, CLI command, or config key appears in backtick inline code — never in plain prose.
+
+**Before:** "The handleAuth function in the auth file calls verifyToken."
+**After:** "`handleAuth` in `src/auth.ts` calls `verifyToken`."
+
+### 3. Tables for 3+ item comparisons
+When comparing 3 or more options, tools, config values, or behaviors — use a markdown table, not a bulleted prose list.
+
+**Before:**
+- `ashlr__edit` is for single edits
+- `ashlr__multi_edit` is for multiple edits to one file
+- `ashlr__edit_structural` is for renames
+
+**After:**
+| Tool | Use case |
+|---|---|
+| `ashlr__edit` | Single search/replace |
+| `ashlr__multi_edit` | Multiple edits, one file |
+| `ashlr__edit_structural` | Symbol/file renames |
+
+### 4. No transitional filler
+Drop: "Now that we've seen X, let's look at Y", "As mentioned above", "Moving on to", "Let's now", "With that in mind", "That said". Just move to the next point.
+
+### 5. `file:line` citations instead of quoted blocks
+When pointing to code, use `path/to/file.ts:42` format. Only quote the exact lines when they are load-bearing to the explanation (e.g., a bug pattern, a function signature the user asked for).
+
+## Auto-clarity exceptions (full structure restored)
+
+These contexts always get full explanatory structure regardless of the efficient level:
+- Destructive actions (`rm -rf`, `git reset --hard`, force-push, `DROP TABLE`)
+- Security findings (credentials, secrets, vulnerabilities)
+- Error messages and stack traces (rendered verbatim)
+- Multi-step migrations where sequence matters
+- Code blocks and diffs (pass through untouched)
+
+## When both `ashlr-brief` and `ashlr-efficient` are active
+
+Both rulesets apply simultaneously:
+- `ashlr-brief` reduces prose volume (drops filler words, padding)
+- `ashlr-efficient` reshapes structure (answer-first, tables, inline code, no filler transitions)
+
+The combined effect is maximum output efficiency without sacrificing correctness or readability.
+
+## Activation
+
+Enable via `/ashlr-efficient on` or by writing `{"enabled":true}` to `~/.ashlr/efficient.json`. Toggle off with `/ashlr-efficient off`.