opencode-froggy 0.7.2 → 0.9.0

package/README.md

@@ -7,7 +7,7 @@
   <a href="https://www.npmjs.com/package/opencode-froggy"><img src="https://badge.fury.io/js/opencode-froggy.svg" alt="npm version"></a>
 </p>
 
-OpenCode plugin providing hooks, specialized agents (architect, doc-writer, rubber-duck, partner, code-reviewer, code-simplifier), skills (code-release), and tools (gitingest, blockchain queries, agent-promote).
+OpenCode plugin providing hooks, specialized agents (architect, doc-writer, rubber-duck, partner, code-reviewer, code-simplifier), skills (code-release), and tools (gitingest, pdf-to-markdown, blockchain queries, agent-promote).
 
 ---
 
@@ -22,6 +22,7 @@ OpenCode plugin providing hooks, specialized agents (architect, doc-writer, rubb
   - [gitingest](#gitingest)
   - [prompt-session](#prompt-session)
   - [list-child-sessions](#list-child-sessions)
+  - [pdf-to-markdown](#pdf-to-markdown)
   - [agent-promote](#agent-promote)
   - [Blockchain](#blockchain)
     - [Configuration](#configuration)
@@ -245,6 +246,37 @@ Child sessions (2):
 
 ---
 
+### pdf-to-markdown
+
+Convert a text-based PDF into enriched Markdown (headings, paragraphs, lists). Returns Markdown as plain text.
+
+#### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `filePath` | `string` | Yes | - | Absolute path to the PDF file to convert |
+| `maxPages` | `number` | No | All pages | Maximum number of pages to convert (positive integer) |
+
+#### Usage Examples
+
+```typescript
+// Convert an entire PDF
+pdfToMarkdown({ filePath: "/path/to/file.pdf" })
+
+// Convert the first 3 pages
+pdfToMarkdown({
+  filePath: "/path/to/file.pdf",
+  maxPages: 3
+})
+```
+
+#### Notes
+
+- The conversion extracts text content; image-only PDFs may return empty output.
+- `maxPages` is capped at the document's total page count.
+
+---
+
 ### agent-promote
 
 Promote an agent to primary (default) or specify a grade.

package/command/doc-changes.md

@@ -26,7 +26,6 @@ Automatically detect documentation files in the project:
 - Look for `README.md` at project root
 - Look for `docs/` or `documentation/` directories
 - Look for other `.md` files that describe usage, API, or features
-- Check if `CHANGELOG.md` exists (do NOT create it if missing)
 
 ## Update Phase
 

package/{skill/code-release/SKILL.md → command/release.md}

@@ -1,13 +1,12 @@
 ---
-name: code-release
-description: >
-  Prepare and execute a release with version bumping, changelog updates, and tags.
-use_when: >
-  REQUIRED: When the user asks to prepare or perform a release,
-  call skill({ name: "code-release" }) before changing any release artifacts.
+description: Prepare and execute a release with version bumping, changelog updates, and tags
 ---
 
-# Code Release Skill
+## Context
+
+- Current version: !`node -p "require('./package.json').version"`
+- Latest tag: !`git describe --tags --abbrev=0 2>/dev/null || echo "none"`
+- Commits since last tag: !`git log $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~10")..HEAD --oneline 2>/dev/null || git log --oneline -10`
 
 ## CRITICAL CONSTRAINT
 
@@ -17,13 +16,15 @@ Any destructive or remote action requires confirmation, including:
 - `git tag`
 - `git push`
 
-## Step 1: Determine last released version
+## Your task
+
+### Step 1: Determine last released version
 
 1. Prefer the latest Git tag that matches `v<semver>`.
 2. If no matching tag exists, use the version in `package.json`.
 3. Collect commits since the last version (tag to `HEAD`).
 
-## Step 2: Propose version bump
+### Step 2: Propose version bump
 
 Analyze commits since the last version and recommend a semver bump:
 - **major**: breaking changes or incompatible behavior changes.
@@ -32,14 +33,14 @@ Analyze commits since the last version and recommend a semver bump:
 
 Present the recommendation and ask the user to confirm before changing any files.
 
-## Step 3: Update release artifacts (after confirmation)
+### Step 3: Update release artifacts (after confirmation)
 
 - Update the version in `package.json`.
 - Update `CHANGELOG` with a new section for the version.
 - Summarize changes based on the commit range.
 - Preserve the existing changelog format.
 
-## Step 4: Tag and publish (after confirmation)
+### Step 4: Tag and publish (after confirmation)
 
 - Commit release changes with a clear release message.
 - Create an annotated tag (for example, `vX.Y.Z`).

package/dist/index.js

@@ -5,7 +5,7 @@ import { getGlobalHookDir, getProjectHookDir } from "./config-paths";
 import { hasCodeExtension } from "./code-files";
 import { log } from "./logger";
 import { executeBashAction, DEFAULT_BASH_TIMEOUT, } from "./bash-executor";
-import { gitingestTool, createPromptSessionTool, createListChildSessionsTool, createAgentPromoteTool, createSkillTool, getPromotedAgents, ethTransactionTool, ethAddressTxsTool, ethAddressBalanceTool, ethTokenTransfersTool, } from "./tools";
+import { gitingestTool, pdfToMarkdownTool, createPromptSessionTool, createListChildSessionsTool, createAgentPromoteTool, createSkillTool, getPromotedAgents, ethTransactionTool, ethAddressTxsTool, ethAddressBalanceTool, ethTokenTransfersTool, } from "./tools";
 export { parseFrontmatter, loadAgents, loadCommands } from "./loaders";
 export { buildSkillActivationBlock } from "./skill-activation";
 import { buildSkillActivationBlock } from "./skill-activation";
@@ -37,6 +37,7 @@ const SmartfrogPlugin = async (ctx) => {
     const skillTool = createSkillTool({
         pluginSkills: skills,
         pluginDir: PLUGIN_ROOT,
+        client: ctx.client,
     });
     log("[init] Plugin loaded", {
         agents: Object.keys(agents),
@@ -46,6 +47,7 @@ const SmartfrogPlugin = async (ctx) => {
         hooks: Array.from(hooks.keys()),
         tools: [
             "gitingest",
+            "pdf-to-markdown",
             "skill",
             "agent-promote",
             "eth-transaction",
@@ -204,6 +206,7 @@ const SmartfrogPlugin = async (ctx) => {
         },
         tool: {
             gitingest: gitingestTool,
+            "pdf-to-markdown": pdfToMarkdownTool,
             skill: skillTool,
             "prompt-session": createPromptSessionTool(ctx.client),
             "list-child-sessions": createListChildSessionsTool(ctx.client),

package/dist/tools/index.d.ts

@@ -1,4 +1,6 @@
 export { gitingestTool, fetchGitingest, type GitingestArgs } from "./gitingest";
+export { convertPdfToMarkdown, type PdfToMarkdownArgs } from "./pdf-to-markdown-core";
+export { pdfToMarkdownTool } from "./pdf-to-markdown";
 export { createPromptSessionTool, type PromptSessionArgs } from "./prompt-session";
 export { createListChildSessionsTool } from "./list-child-sessions";
 export { createAgentPromoteTool, getPromotedAgents, type AgentPromoteArgs } from "./agent-promote";

package/dist/tools/index.js

@@ -1,4 +1,6 @@
 export { gitingestTool, fetchGitingest } from "./gitingest";
+export { convertPdfToMarkdown } from "./pdf-to-markdown-core";
+export { pdfToMarkdownTool } from "./pdf-to-markdown";
 export { createPromptSessionTool } from "./prompt-session";
 export { createListChildSessionsTool } from "./list-child-sessions";
 export { createAgentPromoteTool, getPromotedAgents } from "./agent-promote";

package/dist/tools/pdf-to-markdown-core.d.ts

@@ -0,0 +1,9 @@
+export interface PdfToMarkdownArgs {
+    filePath: string;
+    maxPages?: number;
+}
+interface MarkdownOptions {
+    maxPages?: number;
+}
+export declare function convertPdfToMarkdown(filePath: string, options?: MarkdownOptions): Promise<string>;
+export {};

package/dist/tools/pdf-to-markdown-core.js

@@ -0,0 +1,179 @@
+import { readFile } from "node:fs/promises";
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+function isTextItem(item) {
+    return "str" in item;
+}
+function getFontSize(item) {
+    if (typeof item.height === "number" && item.height > 0) {
+        return item.height;
+    }
+    const [a, b] = item.transform;
+    const size = Math.hypot(a, b);
+    return size > 0 ? size : 0;
+}
+function mergeLineText(previous, next) {
+    if (previous.endsWith("-") && !previous.endsWith(" -")) {
+        return `${previous.slice(0, -1)}${next}`;
+    }
+    if (/[\s-]$/.test(previous) || /^[,.;:!?)]/.test(next)) {
+        return `${previous}${next}`;
+    }
+    return `${previous} ${next}`;
+}
+function groupTextLines(items) {
+    const sorted = [...items].sort((a, b) => {
+        const yDiff = b.transform[5] - a.transform[5];
+        if (Math.abs(yDiff) > 0.1)
+            return yDiff;
+        return a.transform[4] - b.transform[4];
+    });
+    const lines = [];
+    for (const item of sorted) {
+        const text = item.str.trim();
+        if (!text)
+            continue;
+        const y = item.transform[5];
+        const x = item.transform[4];
+        const fontSize = getFontSize(item);
+        const lastLine = lines[lines.length - 1];
+        if (lastLine) {
+            const tolerance = Math.max(2, Math.min(lastLine.fontSize, fontSize) * 0.5);
+            if (Math.abs(lastLine.y - y) <= tolerance) {
+                lastLine.text = mergeLineText(lastLine.text, text);
+                lastLine.fontSize = Math.max(lastLine.fontSize, fontSize);
+                continue;
+            }
+        }
+        lines.push({ text, y, x, fontSize });
+    }
+    return lines;
+}
+function getHeadingLevel(fontSize, maxFontSize, bodyFontSize) {
+    if (maxFontSize === 0)
+        return null;
+    if (fontSize < bodyFontSize * 1.2)
+        return null;
+    const ratio = fontSize / maxFontSize;
+    if (ratio >= 0.85)
+        return 1;
+    if (ratio >= 0.7)
+        return 2;
+    if (ratio >= 0.6)
+        return 3;
+    return null;
+}
+function getBodyFontSize(lines) {
+    const counts = new Map();
+    for (const line of lines) {
+        const rounded = Math.round(line.fontSize * 10) / 10;
+        counts.set(rounded, (counts.get(rounded) ?? 0) + 1);
+    }
+    let bestSize = 0;
+    let bestCount = 0;
+    for (const [size, count] of counts) {
+        if (count > bestCount || (count === bestCount && size < bestSize)) {
+            bestSize = size;
+            bestCount = count;
+        }
+    }
+    return bestSize || Math.max(...lines.map(line => line.fontSize));
+}
+function formatListItem(text) {
+    const trimmed = text.trim();
+    const match = /^([*\-]|\u2022|\d+\.)\s+(.*)$/.exec(trimmed);
+    if (!match)
+        return null;
+    return `- ${match[2].trim()}`;
+}
+function shouldMergeLines(previous, next) {
+    if (next.y > previous.y)
+        return false;
+    const gap = previous.y - next.y;
+    const fontSize = previous.fontSize || next.fontSize;
+    const gapThreshold = Math.max(4, fontSize * 1.6);
+    const fontDelta = Math.abs(previous.fontSize - next.fontSize);
+    if (fontDelta > fontSize * 0.4)
+        return false;
+    return gap <= gapThreshold;
+}
+function linesToMarkdown(lines) {
+    if (lines.length === 0)
+        return [];
+    const maxFontSize = Math.max(...lines.map(line => line.fontSize));
+    const bodyFontSize = getBodyFontSize(lines);
+    const output = [];
+    let currentParagraph = null;
+    let lastLine = null;
+    const flushParagraph = () => {
+        if (currentParagraph) {
+            output.push(currentParagraph, "");
+            currentParagraph = null;
+        }
+    };
+    for (const line of lines) {
+        const text = line.text.replace(/\s+/g, " ").trim();
+        if (!text)
+            continue;
+        const headingLevel = getHeadingLevel(line.fontSize, maxFontSize, bodyFontSize);
+        const listItem = formatListItem(text);
+        if (headingLevel) {
+            flushParagraph();
+            output.push(`${"#".repeat(headingLevel)} ${text}`, "");
+            lastLine = line;
+            continue;
+        }
+        if (listItem) {
+            flushParagraph();
+            output.push(listItem, "");
+            lastLine = line;
+            continue;
+        }
+        if (currentParagraph && lastLine && shouldMergeLines(lastLine, line)) {
+            currentParagraph = `${currentParagraph} ${text}`;
+        }
+        else {
+            flushParagraph();
+            currentParagraph = text;
+        }
+        lastLine = line;
+    }
+    flushParagraph();
+    while (output.length > 0 && output[output.length - 1].trim() === "") {
+        output.pop();
+    }
+    return output;
+}
+export async function convertPdfToMarkdown(filePath, options = {}) {
+    let data;
+    try {
+        const buffer = await readFile(filePath);
+        data = new Uint8Array(buffer);
+    }
+    catch (error) {
+        throw new Error(`Failed to read PDF at ${filePath}: ${String(error)}`);
+    }
+    const loadingTask = getDocument({ data });
+    const pdf = await loadingTask.promise;
+    const totalPages = pdf.numPages;
+    const maxPages = options.maxPages && options.maxPages > 0
+        ? Math.min(options.maxPages, totalPages)
+        : totalPages;
+    const markdownLines = [];
+    for (let pageNumber = 1; pageNumber <= maxPages; pageNumber += 1) {
+        const page = await pdf.getPage(pageNumber);
+        const textContent = await page.getTextContent({ normalizeWhitespace: true });
+        const items = textContent.items.filter(isTextItem);
+        const lines = groupTextLines(items);
+        const pageMarkdown = linesToMarkdown(lines);
+        if (pageMarkdown.length > 0) {
+            if (markdownLines.length > 0) {
+                markdownLines.push("");
+            }
+            markdownLines.push(...pageMarkdown);
+        }
+    }
+    while (markdownLines.length > 0 && markdownLines[markdownLines.length - 1].trim() === "") {
+        markdownLines.pop();
+    }
+    return markdownLines.join("\n");
+}

package/dist/tools/pdf-to-markdown.d.ts

@@ -0,0 +1,12 @@
+import { type ToolContext } from "@opencode-ai/plugin";
+export declare const pdfToMarkdownTool: {
+    description: string;
+    args: {
+        filePath: import("zod").ZodString;
+        maxPages: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        filePath: string;
+        maxPages?: number | undefined;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/tools/pdf-to-markdown.js

@@ -0,0 +1,17 @@
+import { tool } from "@opencode-ai/plugin";
+import { convertPdfToMarkdown } from "./pdf-to-markdown-core";
+export const pdfToMarkdownTool = tool({
+    description: "Convert a text-based PDF into enriched Markdown (headings, paragraphs, lists). Returns Markdown as plain text.",
+    args: {
+        filePath: tool.schema.string().describe("Absolute path to the PDF file to convert"),
+        maxPages: tool.schema
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Limit the number of pages to convert"),
+    },
+    async execute(args, _context) {
+        return convertPdfToMarkdown(args.filePath, { maxPages: args.maxPages });
+    },
+});

package/dist/tools/pdf-to-markdown.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/pdf-to-markdown.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { convertPdfToMarkdown } from "./pdf-to-markdown-core";
+function escapePdfText(text) {
+    return text.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+}
+function buildPdf(lines) {
+    const header = "%PDF-1.4\n%\xFF\xFF\xFF\xFF\n";
+    const objects = [];
+    objects.push("1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
+    objects.push("2 0 obj\n<< /Type /Pages /Kids [3 0 R] /Count 1 >>\nendobj\n");
+    objects.push("3 0 obj\n" +
+        "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] " +
+        "/Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>\n" +
+        "endobj\n");
+    objects.push("4 0 obj\n<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>\nendobj\n");
+    const textCommands = lines
+        .map(line => {
+        const escaped = escapePdfText(line.text);
+        return `/F1 ${line.fontSize} Tf 1 0 0 1 ${line.x} ${line.y} Tm (${escaped}) Tj`;
+    })
+        .join("\n");
+    const stream = `BT\n${textCommands}\nET`;
+    const streamLength = Buffer.byteLength(stream, "utf-8");
+    objects.push(`5 0 obj\n<< /Length ${streamLength} >>\nstream\n${stream}\nendstream\nendobj\n`);
+    const offsets = [0];
+    let currentOffset = Buffer.byteLength(header, "utf-8");
+    for (const obj of objects) {
+        offsets.push(currentOffset);
+        currentOffset += Buffer.byteLength(obj, "utf-8");
+    }
+    const xrefOffset = currentOffset;
+    const xrefLines = ["xref", `0 ${objects.length + 1}`, "0000000000 65535 f "];
+    for (let i = 1; i < offsets.length; i += 1) {
+        xrefLines.push(`${String(offsets[i]).padStart(10, "0")} 00000 n `);
+    }
+    const xref = `${xrefLines.join("\n")}\n`;
+    const trailer = "trailer\n" +
+        `<< /Size ${objects.length + 1} /Root 1 0 R >>\n` +
+        "startxref\n" +
+        `${xrefOffset}\n` +
+        "%%EOF\n";
+    const pdfContent = [header, ...objects, xref, trailer].join("");
+    return Buffer.from(pdfContent, "binary");
+}
+async function withTempPdf(lines, run) {
+    const dir = await mkdtemp(join(tmpdir(), "pdf-md-"));
+    const filePath = join(dir, "sample.pdf");
+    try {
+        await writeFile(filePath, buildPdf(lines));
+        await run(filePath);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+describe("pdf-to-markdown", () => {
+    it("renders headings based on font size", async () => {
+        await withTempPdf([
+            { text: "Title", fontSize: 24, x: 100, y: 700 },
+            { text: "Body text", fontSize: 12, x: 100, y: 660 },
+        ], async (filePath) => {
+            const markdown = await convertPdfToMarkdown(filePath);
+            expect(markdown).toContain("# Title");
+        });
+    });
+    it("merges nearby lines into a paragraph", async () => {
+        await withTempPdf([
+            { text: "First line", fontSize: 12, x: 100, y: 700 },
+            { text: "Second line", fontSize: 12, x: 100, y: 684 },
+        ], async (filePath) => {
+            const markdown = await convertPdfToMarkdown(filePath);
+            expect(markdown).toContain("First line Second line");
+        });
+    });
+    it("formats bullet markers as list items", async () => {
+        await withTempPdf([{ text: "- Bullet item", fontSize: 12, x: 100, y: 700 }], async (filePath) => {
+            const markdown = await convertPdfToMarkdown(filePath);
+            expect(markdown).toContain("- Bullet item");
+        });
+    });
+});

package/dist/tools/skill.d.ts

@@ -1,5 +1,7 @@
 import { type ToolContext } from "@opencode-ai/plugin";
+import type { createOpencodeClient } from "@opencode-ai/sdk";
 import { type LoadedSkill } from "../loaders";
+type Client = ReturnType<typeof createOpencodeClient>;
 export interface SkillInfo {
     name: string;
     description: string;
@@ -9,6 +11,7 @@ export interface SkillInfo {
 export interface CreateSkillToolOptions {
     pluginSkills: LoadedSkill[];
     pluginDir: string;
+    client: Client;
 }
 export declare function createSkillTool(options: CreateSkillToolOptions): {
     description: string;
@@ -19,3 +22,4 @@ export declare function createSkillTool(options: CreateSkillToolOptions): {
         name: string;
     }, context: ToolContext): Promise<string>;
 };
+export {};

package/dist/tools/skill.js

@@ -3,6 +3,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { parseFrontmatter } from "../loaders";
+import { log } from "../logger";
 const TOOL_DESCRIPTION_PREFIX = `Load a skill to get detailed instructions for a specific task.`;
 const TOOL_DESCRIPTION_NO_SKILLS = `${TOOL_DESCRIPTION_PREFIX} No skills are currently available.`;
 function discoverSkillsFromDir(skillsDir, scope) {
@@ -89,12 +90,13 @@ function loadSkillContent(location) {
 export function createSkillTool(options) {
     let cachedSkills = null;
     let cachedDescription = null;
+    const { client, pluginDir, pluginSkills } = options;
     const getSkills = (cwd) => {
         if (cachedSkills)
             return cachedSkills;
         // Merge order: plugin defaults < global < project (later entries override earlier on name collision)
         const allSkills = [
-            ...pluginSkillsToInfo(options.pluginSkills, options.pluginDir),
+            ...pluginSkillsToInfo(pluginSkills, pluginDir),
             ...discoverClaudeGlobalSkills(),
             ...discoverOpencodeGlobalSkills(),
             ...discoverClaudeProjectSkills(cwd),
@@ -139,6 +141,18 @@ export function createSkillTool(options) {
             }
             const body = loadSkillContent(skill.location);
             const dir = dirname(skill.location);
+            try {
+                await client.tui.showToast({
+                    body: {
+                        message: `Skill "${skill.name}" loaded`,
+                        variant: "info",
+                        duration: 3000,
+                    },
+                });
+            }
+            catch (error) {
+                log("[skill] Failed to show toast", { error: String(error) });
+            }
             return [
                 `## Skill: ${skill.name}`,
                 "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-froggy",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "OpenCode plugin with a hook layer (tool.before.*, session.idle...), agents (code-reviewer, doc-writer), and commands (/review-pr, /commit)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -39,12 +39,14 @@
   },
   "dependencies": {
     "js-yaml": "^4.1.0",
+    "pdfjs-dist": "^4.8.69",
     "viem": "^2.44.1"
   },
   "devDependencies": {
     "@opencode-ai/plugin": "latest",
     "@types/bun": "latest",
     "@types/js-yaml": "^4.0.9",
+    "@vitest/coverage-v8": "^4.0.17",
     "typescript": "^5.7.0",
     "vitest": "^4.0.16"
   },

package/skill/ask-questions-if-underspecified/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: ask-questions-if-underspecified
+description: Clarify requirements before implementing. Use when serious doubts arise.
+use_when: >
+  When a request has multiple plausible interpretations or key details
+  (objective, scope, constraints, environment, or safety) are unclear,
+  load this skill before starting implementation.
+  Do NOT use when the request is already clear or when a quick, low-risk
+  discovery read can answer the missing details.
+---
+
+# Ask Questions If Underspecified
+
+## Goal
+
+Ask the minimum set of clarifying questions needed to avoid wrong work; do not start implementing until the must-have questions are answered (or the user explicitly approves proceeding with stated assumptions).
+
+## Workflow
+
+### 1) Decide whether the request is underspecified
+
+Treat a request as underspecified if after exploring how to perform the work, some or all of the following are not clear:
+- Define the objective (what should change vs stay the same)
+- Define "done" (acceptance criteria, examples, edge cases)
+- Define scope (which files/components/users are in/out)
+- Define constraints (compatibility, performance, style, deps, time)
+- Identify environment (language/runtime versions, OS, build/test runner)
+- Clarify safety/reversibility (data migration, rollout/rollback, risk)
+
+If multiple plausible interpretations exist, assume it is underspecified.
+
+### 2) Ask must-have questions first (keep it small)
+
+Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.
+
+Use the `question` tool to present structured choices:
+- Offer multiple-choice options with clear labels
+- Mark recommended defaults with "(Recommended)" in the label
+- Use `multiple: true` when the user can select several options
+- The user can always select "Other" for custom input
+
+### 3) Pause before acting
+
+Until must-have answers arrive:
+- Do not run commands, edit files, or produce a detailed plan that depends on unknowns
+- Do perform a clearly labeled, low-risk discovery step only if it does not commit you to a direction (e.g., inspect repo structure, read relevant config files)
+
+If the user explicitly asks you to proceed without answers:
+- State your assumptions as a short numbered list
+- Ask for confirmation; proceed only after they confirm or correct them
+
+### 4) Confirm interpretation, then proceed
+
+Once you have answers, restate the requirements in 1-3 sentences (including key constraints and what success looks like), then start work.
+
+## Anti-patterns
+
+- Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
+- Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.