@jmylchreest/aide-plugin 0.0.37 → 0.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "description": "aide plugin for OpenCode — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",

package/skills/code-search/SKILL.md

@@ -60,7 +60,21 @@ What functions are in src/auth.ts?
 → Returns: all functions, classes, types in that file
 ```
 
-### 4. Check Index Status (`mcp__plugin_aide_aide__code_stats`)
+### 4. File Outline (`mcp__plugin_aide_aide__code_outline`)
+
+Get a collapsed structural outline of a file — signatures preserved, bodies replaced with `{ ... }`.
+Uses ~5-15% of the tokens of the full file. **Use this before reading a file** to understand its
+structure, then use `Read` with offset/limit for specific sections.
+
+**Example usage:**
+
+```
+Outline src/auth.ts
+→ Uses code_outline tool
+→ Returns: collapsed view with signatures, line ranges, bodies collapsed
+```
+
+### 5. Check Index Status (`mcp__plugin_aide_aide__code_stats`)
 
 Check if the codebase has been indexed.
 
@@ -108,6 +122,20 @@ Is the code indexed?
 1. Use `code_references` with symbol "authenticateUser"
 2. Show all call sites grouped by file
 
+## What These Tools Cover
+
+`code_search` and `code_references` work from the tree-sitter symbol index. They find:
+
+- Function, method, class, interface, type definitions by name
+- Symbol signatures (parameter types, return types)
+- Doc comments attached to definitions
+- Call sites for a specific symbol name (via `code_references`)
+
+For anything else — patterns inside function bodies, method call chains, string literals,
+SQL queries, imports, variable declarations — use **Grep**, which searches code content directly.
+
+In short: `code_search` finds _where things are defined_; Grep finds _patterns in code content_.
+
 ## Notes
 
 - Code must be indexed first: `./.aide/bin/aide code index`

package/skills/debug/SKILL.md

@@ -18,6 +18,7 @@ Systematic approach to identifying and fixing bugs.
 ## Prerequisites
 
 Before starting:
+
 - Get the exact error message or unexpected behavior description
 - Identify the entry point or trigger for the bug
 - Note any relevant environment details (Node version, OS, etc.)
@@ -36,12 +37,14 @@ node path/to/script.js
 ```
 
 Document:
+
 - Exact error message
 - Steps to trigger
 - Expected vs actual behavior
 - Is it consistent or intermittent?
 
 **If cannot reproduce:**
+
 - Check environment differences
 - Look for race conditions
 - Check for cached state
@@ -54,6 +57,9 @@ Use tools to find code related to the error:
 # Search for function mentioned in stack trace
 mcp__plugin_aide_aide__code_search query="functionName" kind="function"
 
+# Get a structural overview of the suspect file (signatures + line ranges)
+mcp__plugin_aide_aide__code_outline file="path/to/file.ts"
+
 # Get symbols in suspect file
 mcp__plugin_aide_aide__code_symbols file="path/to/file.ts"
 
@@ -65,23 +71,26 @@ Grep for "error message text"
 
 Follow the code flow from entry to error:
 
-1. Start at the entry point (route handler, event listener, etc.)
-2. Trace through each function call
-3. Use `mcp__plugin_aide_aide__code_references` to find callers
-4. Check type definitions with `mcp__plugin_aide_aide__code_search kind="interface"`
+1. Use `code_outline` on each file in the call chain to understand its structure
+2. Use `code_references` to find callers of the failing function
+3. Use `Read` with offset/limit to read specific functions in the execution path
+   (use line numbers from the outline)
+4. Check type definitions with `code_search kind="interface"`
+
+Outlines help you identify which functions matter, so you can read just those sections.
 
 ### Step 4: Form Hypotheses
 
 Based on the error type, consider these causes:
 
-| Symptom | Likely Causes |
-|---------|---------------|
-| "undefined is not a function" | Variable is null/undefined, wrong import |
-| "Cannot read property of undefined" | Missing null check, async timing issue |
-| "Type error" | Type mismatch, wrong function signature |
-| "Maximum call stack" | Infinite recursion, circular reference |
-| "Network error" | Bad URL, CORS, timeout, server down |
-| "State not updating" | Mutation instead of new object, missing dependency |
+| Symptom                             | Likely Causes                                      |
+| ----------------------------------- | -------------------------------------------------- |
+| "undefined is not a function"       | Variable is null/undefined, wrong import           |
+| "Cannot read property of undefined" | Missing null check, async timing issue             |
+| "Type error"                        | Type mismatch, wrong function signature            |
+| "Maximum call stack"                | Infinite recursion, circular reference             |
+| "Network error"                     | Bad URL, CORS, timeout, server down                |
+| "State not updating"                | Mutation instead of new object, missing dependency |
 
 ### Step 5: Validate Hypotheses
 
@@ -99,6 +108,7 @@ npm test -- --grep "test name"
 ```
 
 **Validation checklist:**
+
 - Check variable values at key points
 - Verify assumptions about input data
 - Test edge cases (null, empty, boundary values)
@@ -107,11 +117,13 @@ npm test -- --grep "test name"
 ### Step 6: Apply the Fix
 
 **Rules:**
+
 - Change only what's necessary to fix the bug
 - Don't refactor unrelated code
 - Match existing code patterns
 
 **Common fixes:**
+
 - Add null/undefined check
 - Fix type annotation
 - Correct async/await usage
@@ -132,24 +144,26 @@ npm test
 ```
 
 **Verification criteria:**
+
 - Original issue no longer occurs
 - Related tests still pass
 - No new errors introduced
 
 ## Failure Handling
 
-| Situation | Action |
-|-----------|--------|
-| Cannot reproduce | Check environment, add logging to narrow down |
-| Multiple bugs intertwined | Fix one at a time, verify after each |
-| Fix causes new failures | Revert, analyze dependencies, try different approach |
-| Root cause is in dependency | Check for updates, file issue, implement workaround |
-| Bug is in async code | Add proper await, check Promise chains |
+| Situation                   | Action                                               |
+| --------------------------- | ---------------------------------------------------- |
+| Cannot reproduce            | Check environment, add logging to narrow down        |
+| Multiple bugs intertwined   | Fix one at a time, verify after each                 |
+| Fix causes new failures     | Revert, analyze dependencies, try different approach |
+| Root cause is in dependency | Check for updates, file issue, implement workaround  |
+| Bug is in async code        | Add proper await, check Promise chains               |
 
 ## MCP Tools
 
+- `mcp__plugin_aide_aide__code_outline` - **Start here.** Get collapsed file skeleton to understand structure before reading
 - `mcp__plugin_aide_aide__code_search` - Find functions, classes, types involved in the bug
-- `mcp__plugin_aide_aide__code_symbols` - Understand file structure
+- `mcp__plugin_aide_aide__code_symbols` - List all symbols in a file
 - `mcp__plugin_aide_aide__code_references` - Find all callers of a function
 - `mcp__plugin_aide_aide__memory_search` - Check for related past issues
 
@@ -159,24 +173,30 @@ npm test
 ## Debug Report: [Issue Title]
 
 ### Problem
+
 [What was happening vs what should happen]
 
 ### Reproduction
+
 [Steps to reproduce the issue]
 
 ### Root Cause
+
 [Identified cause with file:line reference]
 [Why the bug occurred]
 
 ### Fix Applied
+
 [What was changed and why]
 
 ### Verification
+
 - Original issue: FIXED
 - Related tests: PASS
 - Full suite: PASS
 
 ### Prevention
+
 [Optional: How to prevent similar bugs]
 ```
 

package/skills/forget/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: forget
+description: Soft-delete memories by adding/removing the forget tag, or hard-delete outdated memories
+triggers:
+  - forget this
+  - forget that
+  - forget memory
+  - remove memory
+  - delete memory
+  - outdated memory
+  - wrong memory
+  - incorrect memory
+  - supersede memory
+  - obsolete
+  - no longer true
+  - no longer relevant
+  - not true anymore
+  - that was wrong
+  - disregard
+allowed-tools: Bash(./.aide/bin/aide memory *)
+---
+
+# Forget
+
+**Recommended model tier:** balanced (sonnet) - this skill performs straightforward operations
+
+Manage outdated, incorrect, or obsolete memories by soft-deleting (tagging with `forget`) or hard-deleting them.
+
+## Key Concepts
+
+### Soft Delete (Preferred)
+
+Memories tagged with `forget` are **excluded by default** from search, list, and context injection. They remain in the database and can be recovered.
+
+```bash
+./.aide/bin/aide memory tag <MEMORY_ID> --add=forget
+```
+
+### Hard Delete (Permanent)
+
+Permanently removes a memory from the database. Use when the memory is clearly wrong or contains sensitive data.
+
+```bash
+./.aide/bin/aide memory delete <MEMORY_ID>
+```
+
+### Unforget (Recover)
+
+Remove the `forget` tag to restore a soft-deleted memory.
+
+```bash
+./.aide/bin/aide memory tag <MEMORY_ID> --remove=forget
+```
+
+## Workflow
+
+When the user wants to forget, correct, or supersede a memory:
+
+### Step 1: Find the Memory
+
+Search for the memory to identify its ID:
+
+```bash
+# Search by content keywords
+./.aide/bin/aide memory search "<keywords>" --full --limit=10
+
+# If the memory might already be forgotten, include all
+./.aide/bin/aide memory list --all
+```
+
+### Step 2: Confirm with User
+
+Before deleting or forgetting, show the user what was found and confirm which memories to act on. Display the memory ID, content, and tags.
+
+### Step 3: Apply the Appropriate Action
+
+Choose based on the situation:
+
+| Situation                            | Action                                  | Command                                |
+| ------------------------------------ | --------------------------------------- | -------------------------------------- |
+| Memory is outdated but was once true | Soft delete (forget)                    | `aide memory tag <ID> --add=forget`    |
+| Memory is factually wrong            | Hard delete                             | `aide memory delete <ID>`              |
+| Memory is resolved (issue fixed)     | Soft delete + optionally add resolution | See "Superseding" below                |
+| Memory contains sensitive data       | Hard delete                             | `aide memory delete <ID>`              |
+| Memory was accidentally forgotten    | Unforget                                | `aide memory tag <ID> --remove=forget` |
+
+### Step 4: Optionally Add a Replacement
+
+If the memory is being superseded (not just deleted), add a new corrected memory **without** the `forget` tag:
+
+```bash
+# 1. Forget the old memory
+./.aide/bin/aide memory tag <OLD_ID> --add=forget
+
+# 2. Add the corrected memory (NO forget tag)
+./.aide/bin/aide memory add --category=<category> --tags=<relevant,tags> "<corrected content>"
+```
+
+### Step 5: Verify
+
+Confirm the memory is no longer visible in normal searches:
+
+```bash
+# Should NOT appear in normal search
+./.aide/bin/aide memory search "<keywords>"
+
+# Should appear with --all flag
+./.aide/bin/aide memory list --all
+```
+
+## Anti-Patterns (AVOID)
+
+### DO NOT add a new memory with the forget tag to "supersede" an old one
+
+This is the most common mistake. Adding a new memory tagged `forget` does nothing useful:
+
+- The new "superseding" memory is immediately hidden (because it has the `forget` tag)
+- The original incorrect memory remains visible and active
+
+**Wrong:**
+
+```bash
+# BAD - creates a hidden memory, leaves the original untouched
+aide memory add --tags="forget,some-topic" "RESOLVED: the old issue is fixed"
+```
+
+**Correct:**
+
+```bash
+# GOOD - forget the original, add a visible replacement
+aide memory tag <ORIGINAL_ID> --add=forget
+aide memory add --tags="some-topic" "RESOLVED: the old issue is fixed"
+```
+
+### DO NOT guess memory IDs
+
+Always search first to find the exact memory ID. Memory IDs are ULIDs (e.g., `01KJ3X7GMQET613WMPT7JT8GYD`).
+
+### DO NOT forget memories without user confirmation
+
+Always show the user what will be affected and get confirmation before acting, especially for hard deletes.
+
+## Batch Operations
+
+To forget multiple related memories:
+
+```bash
+# Search for all related memories
+./.aide/bin/aide memory search "<topic>" --full --limit=50
+
+# Forget each one (after user confirmation)
+./.aide/bin/aide memory tag <ID1> --add=forget
+./.aide/bin/aide memory tag <ID2> --add=forget
+```
+
+To clear ALL memories (destructive, requires explicit user request):
+
+```bash
+./.aide/bin/aide memory clear
+```
+
+## Examples
+
+### User says "that thing about ESM imports is wrong"
+
+```bash
+# 1. Find the memory
+./.aide/bin/aide memory search "ESM imports" --full
+
+# 2. Show user and confirm
+# "Found memory 01KJ... about ESM imports requiring .js extensions. Delete this?"
+
+# 3. Soft delete
+./.aide/bin/aide memory tag 01KJ3XVFXBFTKKH1M500N6R5 --add=forget
+```
+
+### User says "we changed from JWT to sessions, update the memory"
+
+```bash
+# 1. Find the old memory
+./.aide/bin/aide memory search "JWT auth" --full
+
+# 2. Forget the old one
+./.aide/bin/aide memory tag <OLD_ID> --add=forget
+
+# 3. Add the corrected one
+./.aide/bin/aide memory add --category=decision --tags=auth,sessions,project:myapp "Auth strategy changed from JWT to server-side sessions with Redis store"
+```
+
+### User says "recover that forgotten memory about testing"
+
+```bash
+# 1. Find forgotten memories
+./.aide/bin/aide memory list --all
+
+# 2. Unforget it
+./.aide/bin/aide memory tag <ID> --remove=forget
+```
+
+## Failure Handling
+
+If `aide memory tag` fails:
+
+1. **"memory not found"** - The ID may be wrong. Re-search with `--all` flag to include forgotten memories.
+2. **Panic/crash** - If the tag command panics, fall back to delete + re-add:
+   ```bash
+   # Workaround: get memory content, delete, re-add with forget tag
+   ./.aide/bin/aide memory list --all  # Find the memory content
+   ./.aide/bin/aide memory delete <ID>
+   ./.aide/bin/aide memory add --category=<cat> --tags=<existing-tags>,forget "<content>"
+   ```
+3. **Database locked** - Another process may hold the lock. Wait and retry, or ensure the aide daemon is running (CLI routes through gRPC when daemon is active).
+
+## Verification
+
+After forgetting a memory, verify:
+
+```bash
+# Memory should NOT appear here
+./.aide/bin/aide memory search "<term>"
+
+# Memory SHOULD appear here (with forget tag)
+./.aide/bin/aide memory list --all
+```

package/skills/implement/SKILL.md

@@ -51,10 +51,19 @@ Understand what the tests expect:
 - What edge cases are covered?
 
 ```bash
-# Read the test file
+# For large test files, get the structure first
+mcp__plugin_aide_aide__code_outline file="path/to/feature.test.ts"
+
+# Then read specific test sections with offset/limit
+Read path/to/feature.test.ts offset=<start> limit=<count>
+
+# For small test files (<100 lines), reading the full file is fine
 Read path/to/feature.test.ts
 ```
 
+When implementing, use `code_outline` on adjacent/related source files to understand
+their structure before reading them fully. This preserves context for the implementation work.
+
 ### Step 3: Check Design Decisions
 
 Use `mcp__plugin_aide_aide__decision_get` with the feature topic to review decisions from DESIGN stage.

package/skills/perf/SKILL.md

@@ -19,6 +19,7 @@ Systematic approach to identifying and fixing performance issues.
 ## Prerequisites
 
 Before starting:
+
 - Identify the specific operation or endpoint that is slow
 - Understand what "fast enough" means (target latency, throughput)
 - Ensure you can measure performance reproducibly
@@ -45,6 +46,7 @@ curl -w "@curl-format.txt" -o /dev/null -s "http://localhost:3000/api/endpoint"
 ```
 
 **Record baseline metrics:**
+
 - Execution time (p50, p95, p99 if available)
 - Memory usage
 - Number of operations per second
@@ -65,30 +67,42 @@ go tool pprof -http=:8080 cpu.prof
 ```
 
 ```
-# Search for common expensive patterns
-mcp__plugin_aide_aide__code_search query="forEach" kind="function"
-mcp__plugin_aide_aide__code_search query="map" kind="function"
+# Get structural overview of suspect files (signatures + line ranges, not full content)
+mcp__plugin_aide_aide__code_outline file="path/to/hotspot.ts"
 
-# Find database queries
-Grep for "SELECT", "find(", "query("
+# Find functions/classes in suspect area by name
+mcp__plugin_aide_aide__code_search query="processData" kind="function"
 
-# Find network calls
-Grep for "fetch", "axios", "http.Get"
+# Find all callers of a hot function
+mcp__plugin_aide_aide__code_references symbol="processData"
+
+# Search for expensive patterns in code bodies (Grep is better here)
+Grep for ".forEach(", ".map(", ".filter("    # Loop/iteration patterns
+Grep for "SELECT", "find(", "query("         # Database queries
+Grep for "fetch(", "axios", "http.Get"       # Network calls
+Grep for "setTimeout", "setInterval"         # Timers
+Grep for "JSON.parse", "JSON.stringify"      # Serialization
 ```
 
+Note: `code_search` finds function/class/type _definitions_ by name.
+For patterns inside function bodies (loops, queries, call chains), use Grep.
+
+After identifying hotspot functions via profiling and search, use `Read` with offset/limit to read
+specific functions (use line numbers from `code_outline`).
+
 ### Step 3: Analyze Performance Patterns
 
 Look for these common issues:
 
-| Issue | Pattern | Solution |
-|-------|---------|----------|
-| N+1 queries | Loop containing DB call | Batch/eager load |
-| Repeated computation | Same calculation in loop | Memoize/cache |
-| Large allocations | Creating objects in loop | Reuse/pool objects |
-| Blocking I/O | Sync file/network ops | Make async/concurrent |
-| Missing indexes | Slow DB queries | Add database indexes |
-| Unnecessary work | Processing unused data | Filter/skip early |
-| Serial execution | Sequential independent ops | Parallelize |
+| Issue                | Pattern                    | Solution              |
+| -------------------- | -------------------------- | --------------------- |
+| N+1 queries          | Loop containing DB call    | Batch/eager load      |
+| Repeated computation | Same calculation in loop   | Memoize/cache         |
+| Large allocations    | Creating objects in loop   | Reuse/pool objects    |
+| Blocking I/O         | Sync file/network ops      | Make async/concurrent |
+| Missing indexes      | Slow DB queries            | Add database indexes  |
+| Unnecessary work     | Processing unused data     | Filter/skip early     |
+| Serial execution     | Sequential independent ops | Parallelize           |
 
 ### Step 4: Apply Optimizations
 
@@ -111,6 +125,7 @@ go test -bench=. -benchmem ./...
 ```
 
 Compare:
+
 - Did the metric improve?
 - By how much (percentage)?
 - Any negative side effects?
@@ -130,13 +145,13 @@ go test ./...
 
 ## Failure Handling
 
-| Situation | Action |
-|-----------|--------|
-| Cannot measure reliably | Increase sample size, reduce variance sources |
-| Optimization made it slower | Revert, analyze why, profile more carefully |
-| Optimization broke tests | Fix tests or revert if behavior changed |
-| Bottleneck is external | Document, consider caching, async processing |
-| Memory improved but CPU worse | Evaluate trade-off for use case |
+| Situation                     | Action                                        |
+| ----------------------------- | --------------------------------------------- |
+| Cannot measure reliably       | Increase sample size, reduce variance sources |
+| Optimization made it slower   | Revert, analyze why, profile more carefully   |
+| Optimization broke tests      | Fix tests or revert if behavior changed       |
+| Bottleneck is external        | Document, consider caching, async processing  |
+| Memory improved but CPU worse | Evaluate trade-off for use case               |
 
 ## Common Optimizations
 
@@ -149,12 +164,12 @@ for (const user of users) {
 }
 
 // GOOD: Batch query
-const userIds = users.map(u => u.id);
+const userIds = users.map((u) => u.id);
 const posts = await db.getPostsForUsers(userIds);
 
 // BAD: Repeated work
-const typeA = items.filter(x => x.type === 'a').map(x => x.value);
-const typeB = items.filter(x => x.type === 'b').map(x => x.value);
+const typeA = items.filter((x) => x.type === "a").map((x) => x.value);
+const typeB = items.filter((x) => x.type === "b").map((x) => x.value);
 
 // GOOD: Single pass
 const grouped = { a: [], b: [] };
@@ -167,10 +182,7 @@ const result1 = await fetch(url1);
 const result2 = await fetch(url2);
 
 // GOOD: Parallel async
-const [result1, result2] = await Promise.all([
-  fetch(url1),
-  fetch(url2)
-]);
+const [result1, result2] = await Promise.all([fetch(url1), fetch(url2)]);
 ```
 
 ### Go
@@ -225,13 +237,17 @@ SELECT * FROM posts WHERE user_id IN (?, ?, ?);
 
 ## MCP Tools
 
-- `mcp__plugin_aide_aide__code_search` - Find loops, queries, expensive operations
-- `mcp__plugin_aide_aide__code_symbols` - Understand function structure
+- `mcp__plugin_aide_aide__code_outline` - **Start here.** Get collapsed file skeleton to identify functions before reading
+- `mcp__plugin_aide_aide__code_search` - Find function/class/type definitions by name
+- `mcp__plugin_aide_aide__code_symbols` - List all symbol definitions in a file
+- `mcp__plugin_aide_aide__code_references` - Find all callers of a hot function (exact name match)
 - `mcp__plugin_aide_aide__memory_search` - Check past performance decisions
+- **Grep** - Find code patterns in bodies: loops, queries, call chains, string literals
 
 ## Profiling Commands Reference
 
 ### Node.js
+
 ```bash
 # CPU profiling
 node --cpu-prof app.js
@@ -247,6 +263,7 @@ npx clinic flame -- node app.js
 ```
 
 ### Go
+
 ```bash
 # CPU profiling
 go test -cpuprofile=cpu.prof -bench=.
@@ -262,6 +279,7 @@ go tool trace trace.out
 ```
 
 ### Browser
+
 - DevTools -> Performance -> Record
 - DevTools -> Memory -> Heap snapshot
 - Lighthouse for overall page performance
@@ -269,6 +287,7 @@ go tool trace trace.out
 ## Verification Criteria
 
 Before completing:
+
 - [ ] Baseline measurement recorded
 - [ ] Improvement quantified (percentage)
 - [ ] All tests still pass
@@ -281,25 +300,30 @@ Before completing:
 ## Performance Analysis: [Operation/Endpoint Name]
 
 ### Baseline
+
 - Execution time: 450ms (p50), 680ms (p95)
 - Memory: 125MB peak
 - Database queries: 150
 
 ### Hotspots Identified
+
 1. `db.getUsers()` - 300ms (67% of total)
 2. `processData()` - 100ms (22% of total)
 3. `formatOutput()` - 50ms (11% of total)
 
 ### Optimizations Applied
+
 1. Batched user queries - 300ms -> 50ms
 2. Memoized processData for repeated calls - 100ms -> 5ms
 
 ### Results
+
 - Execution time: 450ms -> 105ms (77% faster)
 - Memory: 125MB -> 80MB (36% reduction)
 - Database queries: 150 -> 3 (98% reduction)
 
 ### Verification
+
 - All tests: PASS
 - Output correctness: VERIFIED
 ```

package/skills/review/SKILL.md

@@ -18,6 +18,7 @@ Comprehensive code review covering quality, security, and maintainability.
 ## Review Checklist
 
 ### Code Quality
+
 - [ ] Clear naming (variables, functions, classes)
 - [ ] Single responsibility (functions do one thing)
 - [ ] DRY (no unnecessary duplication)
@@ -26,6 +27,7 @@ Comprehensive code review covering quality, security, and maintainability.
 - [ ] Edge cases considered
 
 ### Security (OWASP Top 10)
+
 - [ ] Input validation (no injection vulnerabilities)
 - [ ] Authentication checks (routes protected)
 - [ ] Authorization (proper access control)
@@ -36,6 +38,7 @@ Comprehensive code review covering quality, security, and maintainability.
 - [ ] Secure dependencies (no known vulnerabilities)
 
 ### Maintainability
+
 - [ ] Code is readable without comments
 - [ ] Comments explain "why" not "what"
 - [ ] Consistent with codebase patterns
@@ -43,28 +46,47 @@ Comprehensive code review covering quality, security, and maintainability.
 - [ ] No dead code
 
 ### Performance
+
 - [ ] No N+1 queries
 - [ ] Appropriate caching
 - [ ] No memory leaks
 - [ ] Efficient algorithms
 
+## Context-Efficient Reading
+
+Prefer lightweight tools first, then read in detail where needed:
+
+- **`code_outline`** -- Collapsed skeleton with signatures and line ranges. Great first step for unfamiliar files.
+- **`code_symbols`** -- Quick symbol list when you only need names and kinds.
+- **`code_search`** / **`code_references`** -- Find symbol definitions or callers across the codebase.
+- **`Read` with offset/limit** -- Read specific functions using line numbers from the outline.
+- **Grep** -- Find patterns in code content (loops, queries, string literals) that the index doesn't cover.
+
+For reviews spanning many files, consider using **Task sub-agents** (`explore` type) which run in their
+own context and return summaries.
+
 ## Review Process
 
-1. **Read the diff/files** - Understand what changed
-2. **Search for context** - Use `code_search` MCP tool to find:
-   - Related symbols that might be affected
-   - Other usages of modified functions/classes
-   - Similar patterns in the codebase
-3. **Check integration** - How does it fit the larger system?
-4. **Run static analysis** - Use lsp_diagnostics, ast_grep if available
-5. **Document findings** - Use severity levels
+1. **Outline changed files** - Use `code_outline` on each changed file to understand structure.
+   Identify areas of concern from signatures and line ranges.
+2. **Read targeted sections** - Use `Read` with `offset`/`limit` to read only the specific
+   functions/sections that need detailed review (use line numbers from the outline).
+3. **Search for context** - Use `code_search`, `code_references`, and **Grep**:
+   - `code_search` — Find related function/class/type _definitions_ by name
+   - `code_references` — Find all callers/usages of a modified symbol (exact name match)
+   - **Grep** — Find code _patterns_ in bodies (error handling, SQL queries, security-sensitive calls)
+4. **Check integration** - How does it fit the larger system?
+5. **Run static analysis** - Use lsp_diagnostics, ast_grep if available
+6. **Document findings** - Use severity levels
 
 ## MCP Tools
 
 Use these tools during review:
 
+- `mcp__plugin_aide_aide__code_outline` - **Start here.** Get collapsed file skeleton with signatures and line ranges
 - `mcp__plugin_aide_aide__code_search` - Find symbols related to changes (e.g., `code_search query="getUserById"`)
 - `mcp__plugin_aide_aide__code_symbols` - List all symbols in a file being reviewed
+- `mcp__plugin_aide_aide__code_references` - Find all callers/usages of a modified symbol
 - `mcp__plugin_aide_aide__memory_search` - Check for related past decisions or issues
 
 ## Output Format
@@ -73,28 +95,34 @@ Use these tools during review:
 ## Code Review: [Feature/PR Name]
 
 ### Summary
+
 [1-2 sentence overview]
 
 ### Findings
 
 #### 🔴 Critical (must fix)
+
 - **[Issue]** `file:line`
   - Problem: [description]
   - Fix: [recommendation]
 
 #### 🟡 Warning (should fix)
+
 - **[Issue]** `file:line`
   - Problem: [description]
   - Fix: [recommendation]
 
 #### 🔵 Suggestion (consider)
+
 - **[Issue]** `file:line`
   - Suggestion: [recommendation]
 
 ### Security Notes
+
 - [Any security-specific observations]
 
 ### Verdict
+
 [ ] ✅ Approve
 [ ] ⚠️ Approve with comments
 [ ] ❌ Request changes
@@ -102,11 +130,11 @@ Use these tools during review:
 
 ## Severity Guide
 
-| Level | Criteria |
-|-------|----------|
-| Critical | Security vulnerability, data loss risk, crash |
-| Warning | Bug potential, maintainability issue, performance |
-| Suggestion | Style, minor improvement, optional |
+| Level      | Criteria                                          |
+| ---------- | ------------------------------------------------- |
+| Critical   | Security vulnerability, data loss risk, crash     |
+| Warning    | Bug potential, maintainability issue, performance |
+| Suggestion | Style, minor improvement, optional                |
 
 ## Failure Handling
 
@@ -122,10 +150,12 @@ Use these tools during review:
 ## Review Status: Incomplete
 
 ### Blockers
+
 - Could not access: `path/to/file.ts` (permission denied)
 - Missing context: Need to understand `AuthService` implementation
 
 ### Partial Findings
+
 [Include any findings from files that were reviewed]
 ```
 
@@ -133,14 +163,16 @@ Use these tools during review:
 
 A complete code review must:
 
-1. **Read all changed files** - Verify each file was actually read
-2. **Check for related code** - Use code search to find callers/callees
-3. **Verify test coverage** - Check if tests exist for critical paths
-4. **Document all findings** - Even if no issues found, state that explicitly
+1. **Outline all changed files** - Use `code_outline` on every file in scope
+2. **Read critical sections** - Use targeted `Read` with offset/limit on flagged areas
+3. **Check for related code** - Use `code_search` and `code_references` to find callers/callees
+4. **Verify test coverage** - Check if tests exist for critical paths
+5. **Document all findings** - Even if no issues found, state that explicitly
 
 ### Checklist before submitting review:
 
-- [ ] All files in diff/scope have been read
+- [ ] All files in diff/scope have been outlined
+- [ ] Critical functions/sections read in detail (with offset/limit)
 - [ ] Related symbols searched (callers, implementations)
 - [ ] Security checklist evaluated
 - [ ] Findings documented with file:line references

package/skills/test/SKILL.md

@@ -17,6 +17,7 @@ Write comprehensive tests and run test suites.
 ## Prerequisites
 
 Before starting:
+
 - Identify the code to be tested (function, module, feature)
 - Understand the testing framework used in the project
 
@@ -27,6 +28,7 @@ Before starting:
 Use the `mcp__plugin_aide_aide__decision_get` tool with topic `testing` to check for testing framework decisions.
 
 Common frameworks by language:
+
 - **TypeScript/JavaScript:** Vitest, Jest, Mocha
 - **Go:** built-in `go test`
 - **Python:** pytest, unittest
@@ -34,13 +36,18 @@ Common frameworks by language:
 ### Step 2: Discover Existing Test Patterns
 
 Use `Glob` to find test files:
+
 - Pattern: `**/*.test.ts`, `**/*.spec.ts` (TypeScript)
 - Pattern: `**/*_test.go` (Go)
 - Pattern: `**/test_*.py`, `**/*_test.py` (Python)
 
-Use `mcp__plugin_aide_aide__code_search` with query `describe` and `it` to find test patterns.
+Use **Grep** to find test patterns in existing test files:
+
+- `Grep pattern="describe\(" include="*.test.*"` — find test suites
+- `Grep pattern="it\(|test\(" include="*.test.*"` — find test cases
 
 Read an existing test file to understand:
+
 - Import patterns
 - Setup/teardown patterns
 - Mocking approach
@@ -52,6 +59,7 @@ Use `mcp__plugin_aide_aide__code_symbols` with the target file path to get funct
 Use `mcp__plugin_aide_aide__code_search` to find related types.
 
 Identify:
+
 - Input parameters and types
 - Return type
 - Side effects
@@ -63,12 +71,14 @@ Identify:
 Follow the project's testing conventions. Cover these scenarios:
 
 **Test Categories:**
+
 1. **Happy path** - Normal, expected inputs
 2. **Edge cases** - Empty, null, boundary values
 3. **Error cases** - Invalid inputs, expected failures
 4. **Async behavior** - If applicable
 
 **Naming convention:**
+
 - Descriptive names that explain what is being tested
 - Format: "should [expected behavior] when [condition]"
 
@@ -103,51 +113,52 @@ go tool cover -html=coverage.out
 ```
 
 **Coverage targets:**
+
 - New code: aim for >80%
 - Critical paths: aim for >90%
 - Focus on meaningful tests, not just coverage numbers
 
 ## Failure Handling
 
-| Failure | Action |
-|---------|--------|
-| Test imports fail | Check path aliases, ensure test config matches main |
-| Mock not working | Verify mock setup, check dependency injection |
-| Async test timeout | Add proper await, increase timeout if needed |
-| Flaky test | Check for shared state, timing issues, or external deps |
-| Coverage too low | Add edge case tests, error path tests |
+| Failure            | Action                                                  |
+| ------------------ | ------------------------------------------------------- |
+| Test imports fail  | Check path aliases, ensure test config matches main     |
+| Mock not working   | Verify mock setup, check dependency injection           |
+| Async test timeout | Add proper await, increase timeout if needed            |
+| Flaky test         | Check for shared state, timing issues, or external deps |
+| Coverage too low   | Add edge case tests, error path tests                   |
 
 ## Test Structure Templates
 
 ### TypeScript/JavaScript (Vitest/Jest)
 
 ```typescript
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { functionToTest } from './module';
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { functionToTest } from "./module";
 
-describe('functionToTest', () => {
+describe("functionToTest", () => {
   beforeEach(() => {
     // Reset state before each test
     vi.clearAllMocks();
   });
 
-  it('should return expected result for valid input', () => {
-    const result = functionToTest('valid input');
-    expect(result).toBe('expected output');
+  it("should return expected result for valid input", () => {
+    const result = functionToTest("valid input");
+    expect(result).toBe("expected output");
   });
 
-  it('should handle empty input', () => {
-    const result = functionToTest('');
-    expect(result).toBe('');
+  it("should handle empty input", () => {
+    const result = functionToTest("");
+    expect(result).toBe("");
   });
 
-  it('should throw error for null input', () => {
-    expect(() => functionToTest(null)).toThrow('Input required');
+  it("should throw error for null input", () => {
+    expect(() => functionToTest(null)).toThrow("Input required");
   });
 
-  it('should handle async operation', async () => {
-    const result = await functionToTest('async input');
-    expect(result).resolves.toBe('async output');
+  it("should handle async operation", async () => {
+    const result = await functionToTest("async input");
+    expect(result).resolves.toBe("async output");
   });
 });
 ```
@@ -213,6 +224,7 @@ class TestFunctionToTest:
 ## Verification Criteria
 
 Before completing:
+
 - [ ] All new tests pass
 - [ ] Existing tests still pass
 - [ ] Coverage meets project standards
@@ -225,9 +237,11 @@ Before completing:
 ## Tests Added
 
 ### Files
+
 - `path/to/file.test.ts` - 5 tests for UserService
 
 ### Test Cases
+
 1. should create user with valid data
 2. should reject duplicate email
 3. should hash password before saving
@@ -235,10 +249,12 @@ Before completing:
 5. should validate email format
 
 ### Coverage
+
 - New code: 92%
 - Total project: 84%
 
 ### Verification
+
 - All tests: PASS
 - No flaky tests observed
 ```

package/src/core/context-guard.ts

@@ -0,0 +1,214 @@
+/**
+ * Context Guard — platform-agnostic core logic.
+ *
+ * Monitors Read tool calls and advises agents to use code_outline
+ * before reading large files. This preserves context window for
+ * the actual task by avoiding dumping entire files into conversation.
+ *
+ * Behaviour:
+ *   - Triggers on Read tool calls for files > 5KB (~150 lines)
+ *   - Tracks which files have been outlined (code_outline/code_symbols)
+ *   - Returns an advisory message (never blocks)
+ *   - Also tracks code_outline/code_symbols calls to mark files as "known"
+ *
+ * Used by both Claude Code hooks (PreToolUse) and OpenCode plugin.
+ */
+
+import { statSync, readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve, isAbsolute, normalize } from "path";
+import { tmpdir } from "os";
+import { join } from "path";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "context-guard";
+
+/** Default size threshold in bytes (~150 lines) */
+const DEFAULT_SIZE_THRESHOLD = 5120;
+
+/** File extensions that are typically not source code (skip advisory) */
+const SKIP_EXTENSIONS = new Set([
+  ".json",
+  ".lock",
+  ".sum",
+  ".mod",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".env",
+  ".md",
+  ".txt",
+  ".csv",
+  ".svg",
+  ".png",
+  ".jpg",
+  ".gif",
+  ".ico",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+]);
+
+export interface ContextGuardResult {
+  /** Whether to inject an advisory message */
+  shouldAdvise: boolean;
+  /** Advisory message to inject */
+  advisory?: string;
+  /** Whether this call should be tracked (code_outline/code_symbols) */
+  tracked?: boolean;
+}
+
+/**
+ * Get the path to the tracking file for this session.
+ */
+function getTrackingPath(sessionId: string): string {
+  return join(tmpdir(), `aide-context-guard-${sessionId}.json`);
+}
+
+/**
+ * Load the set of files that have been outlined in this session.
+ */
+function loadOutlinedFiles(sessionId: string): Set<string> {
+  const trackingPath = getTrackingPath(sessionId);
+  try {
+    if (existsSync(trackingPath)) {
+      const data = JSON.parse(readFileSync(trackingPath, "utf-8"));
+      return new Set(data.files || []);
+    }
+  } catch {
+    // Corrupted file, start fresh
+  }
+  return new Set();
+}
+
+/**
+ * Save a file as "outlined" in the tracking file.
+ */
+function trackOutlinedFile(sessionId: string, filePath: string): void {
+  const files = loadOutlinedFiles(sessionId);
+  files.add(filePath);
+  const trackingPath = getTrackingPath(sessionId);
+  try {
+    writeFileSync(
+      trackingPath,
+      JSON.stringify({ files: Array.from(files) }),
+      "utf-8",
+    );
+  } catch (err) {
+    debug(SOURCE, `Failed to write tracking file: ${err}`);
+  }
+}
+
+/**
+ * Estimate line count from file size (rough: ~35 bytes per line average).
+ */
+function estimateLines(sizeBytes: number): number {
+  return Math.round(sizeBytes / 35);
+}
+
+/**
+ * Check whether a Read call should receive a context-efficiency advisory.
+ *
+ * Also handles tracking code_outline/code_symbols calls.
+ */
+export function checkContextGuard(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  cwd: string,
+  sessionId: string,
+): ContextGuardResult {
+  const normalizedTool = toolName.toLowerCase();
+
+  // Track code_outline and code_symbols calls
+  if (
+    normalizedTool.includes("code_outline") ||
+    normalizedTool.includes("code_symbols")
+  ) {
+    const filePath =
+      (toolInput.file as string) ||
+      (toolInput.filePath as string) ||
+      (toolInput.file_path as string);
+    if (filePath && sessionId) {
+      const resolved = normalize(
+        isAbsolute(filePath) ? filePath : resolve(cwd, filePath),
+      );
+      trackOutlinedFile(sessionId, resolved);
+      debug(SOURCE, `Tracked outline for: ${filePath}`);
+    }
+    return { shouldAdvise: false, tracked: true };
+  }
+
+  // Only advise on Read tool calls
+  if (normalizedTool !== "read") {
+    return { shouldAdvise: false };
+  }
+
+  // Extract file path from tool input
+  const filePath =
+    (toolInput.filePath as string) ||
+    (toolInput.file_path as string) ||
+    (toolInput.path as string);
+
+  if (!filePath) {
+    return { shouldAdvise: false };
+  }
+
+  // Resolve to absolute path
+  const resolvedPath = normalize(
+    isAbsolute(filePath) ? filePath : resolve(cwd, filePath),
+  );
+
+  // Skip non-source-code files
+  const ext = filePath.substring(filePath.lastIndexOf(".")).toLowerCase();
+  if (SKIP_EXTENSIONS.has(ext)) {
+    return { shouldAdvise: false };
+  }
+
+  // Check if the agent is already using offset/limit (targeted read)
+  const offset = toolInput.offset as number | undefined;
+  const limit = toolInput.limit as number | undefined;
+  if (offset !== undefined && offset > 1) {
+    // Agent is doing a targeted read — no advisory needed
+    return { shouldAdvise: false };
+  }
+  if (limit !== undefined && limit < 100) {
+    // Agent is limiting the read — no advisory needed
+    return { shouldAdvise: false };
+  }
+
+  // Check file size
+  let fileSize: number;
+  try {
+    const stat = statSync(resolvedPath);
+    fileSize = stat.size;
+  } catch {
+    // Can't stat file — don't advise (file might not exist yet)
+    return { shouldAdvise: false };
+  }
+
+  // Skip small files
+  if (fileSize < DEFAULT_SIZE_THRESHOLD) {
+    return { shouldAdvise: false };
+  }
+
+  // Check if this file has already been outlined in this session
+  if (sessionId) {
+    const outlinedFiles = loadOutlinedFiles(sessionId);
+    if (outlinedFiles.has(resolvedPath)) {
+      debug(SOURCE, `File already outlined, skipping advisory: ${filePath}`);
+      return { shouldAdvise: false };
+    }
+  }
+
+  // Generate advisory
+  const estLines = estimateLines(fileSize);
+  const sizeKB = (fileSize / 1024).toFixed(1);
+
+  const advisory =
+    `[aide:context] This file is ~${estLines} lines (${sizeKB}KB). Consider using \`code_outline\` ` +
+    `first to see its structure, then \`Read\` with offset/limit for specific sections. ` +
+    `This preserves your context window for the full task.`;
+
+  debug(SOURCE, `Advisory for ${filePath}: ${estLines} lines, ${sizeKB}KB`);
+  return { shouldAdvise: true, advisory };
+}

package/src/opencode/index.ts

@@ -156,8 +156,8 @@ export const AidePlugin: Plugin = async (ctx: PluginInput): Promise<Hooks> => {
     // Plugin may be called before the client is fully ready
   }
 
-  // Also log to stderr for direct observability
-  console.error(rawLog);
+  // Also log to stderr when debugging
+  if (process.env.AIDE_DEBUG === "1") console.error(rawLog);
 
   const resolved = resolveProjectRoot(ctx);
 
@@ -170,7 +170,7 @@ export const AidePlugin: Plugin = async (ctx: PluginInput): Promise<Hooks> => {
   } catch {
     // non-fatal
   }
-  console.error(resolvedLog);
+  if (process.env.AIDE_DEBUG === "1") console.error(resolvedLog);
 
   return createHooks(resolved.root, ctx.worktree, ctx.client, pluginRoot, {
     skipInit: !resolved.hasProjectRoot,