PR #332: prompts rewrite, build prompt gen, tool schemas, compress default permission

Author: spoons-and-mirrors

.gitignore

@@ -29,7 +29,7 @@ Thumbs.db
 .opencode/
 
 # Generated prompt files (from scripts/generate-prompts.ts)
-lib/prompts/*.generated.ts
+lib/prompts/**/*.generated.ts
 
 # Tests
 tests/results/

index.ts

@@ -112,6 +112,17 @@ const plugin: Plugin = (async (ctx) => {
                 logger.info(
                     `Added ${toolsToAdd.map((t) => `'${t}'`).join(" and ")} to experimental.primary_tools via config mutation`,
                 )
+
+                // Set compress permission to ask (only if not already configured)
+                if (config.tools.compress.enabled) {
+                    const permission = opencodeConfig.permission ?? {}
+                    if (!("compress" in permission)) {
+                        opencodeConfig.permission = {
+                            ...permission,
+                            compress: "ask",
+                        } as typeof permission
+                    }
+                }
             }
         },
     }

lib/prompts/compress-tool-spec.ts

@@ -0,0 +1,35 @@
+Use this tool to collapse a contiguous range of conversation into a preserved summary.
+
+THE PHILOSOPHY OF COMPRESS
+`compress` transforms verbose conversation sequences into dense, high-fidelity summaries. This is not cleanup - it is crystallization. Your summary becomes the authoritative record of what transpired.
+
+Think of compression as phase transitions: raw exploration becomes refined understanding. The original context served its purpose; your summary now carries that understanding forward.
+
+THE SUMMARY
+Your summary must be EXHAUSTIVE. Capture file paths, function signatures, decisions made, constraints discovered, key findings... EVERYTHING that maintains context integrity. This is not a brief note - it is an authoritative record so faithful that the original conversation adds no value.
+
+Yet be LEAN. Strip away the noise: failed attempts that led nowhere, verbose tool outputs, back-and-forth exploration. What remains should be pure signal - golden nuggets of detail that preserve full understanding with zero ambiguity.
+
+THE WAYS OF COMPRESS
+`compress` when a chapter closes - when a phase of work is truly complete and the raw conversation has served its purpose:
+
+Research concluded and findings are clear
+Implementation finished and verified
+Exploration exhausted and patterns understood
+
+Do NOT compress when:
+You may need exact code, error messages, or file contents from the range
+Work in that area is still active or may resume
+You're mid-sprint on related functionality
+
+Before compressing, ask: _"Is this chapter closed?"_ Compression is irreversible. The summary replaces everything in the range.
+
+BOUNDARY MATCHING
+You specify boundaries by matching unique text strings in the conversation. CRITICAL: In code-centric conversations, strings repeat often. Provide sufficiently unique text to match exactly once. If a match fails (not found or found multiple times), the tool will error - extend your boundary string with more surrounding context in order to make SURE the tool does NOT error.
+
+THE FORMAT OF COMPRESS
+`topic`: Short label (3-5 words) for display - e.g., "Auth System Exploration"
+`content`: Object containing:
+`startString`: Unique text string marking the beginning of the range
+`endString`: Unique text string marking the end of the range
+`summary`: Complete technical summary replacing all content in the range

lib/prompts/compress.md

@@ -0,0 +1,28 @@
+Use this tool to distill relevant findings from a selection of raw tool outputs into preserved knowledge, in order to denoise key bits and parts of context.
+
+THE PRUNABLE TOOLS LIST
+A <prunable-tools> will show in context when outputs are available for distillation (you don't need to look for it). Each entry follows the format `ID: tool, parameter (~token usage)` (e.g., `20: read, /path/to/file.ts (~1500 tokens)`). You MUST select outputs by their numeric ID. THESE ARE YOUR ONLY VALID TARGETS.
+
+THE PHILOSOPHY OF DISTILLATION
+`distill` is your favored instrument for transforming raw tool outputs into preserved knowledge. This is not mere summarization; it is high-fidelity extraction that makes the original output obsolete.
+
+Your distillation must be COMPLETE. Capture function signatures, type definitions, business logic, constraints, configuration values... EVERYTHING essential. Think of it as creating a high signal technical substitute so faithful that re-fetching the original would yield no additional value. Be thorough; be comprehensive; leave no ambiguity, ensure that your distillation stands alone, and is designed for easy retrieval and comprehension.
+
+AIM FOR IMPACT. Distillation is most powerful when applied to outputs that contain signal buried in noise. A single line requires no distillation; a hundred lines of API documentation do. Make sure the distillation is meaningful.
+
+THE WAYS OF DISTILL
+`distill` when you have extracted the essence from tool outputs and the raw form has served its purpose.
+Here are some examples:
+EXPLORATION: You've read extensively and grasp the architecture. The original file contents are no longer needed; your understanding, synthesized, is sufficient.
+PRESERVATION: Valuable technical details (signatures, logic, constraints) coexist with noise. Preserve the former; discard the latter.
+
+Not everything should be distilled. Prefer keeping raw outputs when:
+PRECISION MATTERS: You will edit the file, grep for exact strings, or need line-accurate references. Distillation sacrifices precision for essence.
+UNCERTAINTY REMAINS: If you might need to re-examine the original, defer. Distillation is irreversible; be certain before you commit.
+
+Before distilling, ask yourself: _"Will I need the raw output for upcoming work?"_ If you plan to edit a file you just read, keep it intact. Distillation is for completed exploration, not active work.
+
+THE FORMAT OF DISTILL
+`targets`: Array of objects, each containing:
+`id`: Numeric ID (as string) from the `<prunable-tools>` list
+`distillation`: Complete technical substitute for that tool output

lib/prompts/distill-tool-spec.ts

@@ -1,11 +1,9 @@
-// Tool specs
-import { PRUNE_TOOL_SPEC } from "./prune-tool-spec"
-import { DISTILL_TOOL_SPEC } from "./distill-tool-spec"
-import { COMPRESS_TOOL_SPEC } from "./compress-tool-spec"
-
 // Generated prompts (from .md files via scripts/generate-prompts.ts)
-import { SYSTEM as SYSTEM_PROMPT } from "./system.generated"
-import { NUDGE } from "./nudge.generated"
+import { SYSTEM as SYSTEM_PROMPT } from "./_codegen/system.generated"
+import { NUDGE } from "./_codegen/nudge.generated"
+import { PRUNE as PRUNE_TOOL_SPEC } from "./_codegen/prune.generated"
+import { DISTILL as DISTILL_TOOL_SPEC } from "./_codegen/distill.generated"
+import { COMPRESS as COMPRESS_TOOL_SPEC } from "./_codegen/compress.generated"
 
 export interface ToolFlags {
     distill: boolean

lib/prompts/distill.md

@@ -7,6 +7,6 @@ You should prioritize context management, but do not interrupt a critical atomic
 
 IMMEDIATE ACTION REQUIRED
 <distill>KNOWLEDGE PRESERVATION: If holding valuable raw data you POTENTIALLY will need in your task, use the `distill` tool. Produce a high-fidelity distillation to preserve insights - be thorough</distill>
-<prune>NOISE REMOVAL: If you read files or ran commands that yielded no value, use the `prune` tool to remove them. If newer tools supersedes older ones, prune the old</prune>
 <compress>PHASE COMPLETION: If a phase is complete, use the `compress` tool to condense the entire sequence into a detailed summary</compress>
+<prune>NOISE REMOVAL: If you read files or ran commands that yielded no value, use the `prune` tool to remove them. If newer tools supersedes older ones, prune the old</prune>
 </instruction>

lib/prompts/index.ts

@@ -0,0 +1,18 @@
+Use this tool to remove tool outputs from context entirely. No preservation - pure deletion.
+
+THE PRUNABLE TOOLS LIST
+A `<prunable-tools>` section surfaces in context showing outputs eligible for removal. Each line reads `ID: tool, parameter (~token usage)` (e.g., `20: read, /path/to/file.ts (~1500 tokens)`). Reference outputs by their numeric ID - these are your ONLY valid targets for pruning.
+
+THE WAYS OF PRUNE
+`prune` is surgical excision - eliminating noise (irrelevant or unhelpful outputs), superseded information (older outputs replaced by newer data), or wrong targets (you accessed something that turned out to be irrelevant). Use it to keep your context lean and focused.
+
+BATCH WISELY! Pruning is most effective when consolidated. Don't prune a single tiny output - accumulate several candidates before acting.
+
+Do NOT prune when:
+NEEDED LATER: You plan to edit the file or reference this context for implementation.
+UNCERTAINTY: If you might need to re-examine the original, keep it.
+
+Before pruning, ask: _"Is this noise, or will it serve me?"_ If the latter, keep it. Pruning that forces re-fetching is a net loss.
+
+THE FORMAT OF PRUNE
+`ids`: Array of numeric IDs (as strings) from the `<prunable-tools>` list