@jmylchreest/aide-plugin 0.0.38 → 0.0.40

package/skills/patterns/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: patterns
+description: Analyze codebase patterns, detect anti-patterns, and surface static analysis findings
+triggers:
+  - find patterns
+  - anti-patterns
+  - code smells
+  - complexity
+  - duplicated code
+  - clones
+  - secrets
+  - coupling
+  - findings
+  - static analysis
+  - code health
+---
+
+# Pattern Analysis
+
+**Recommended model tier:** balanced (sonnet) - this skill combines search with structured analysis
+
+Analyze codebase patterns using static analysis findings. Surface complexity hotspots, code
+duplication, coupling issues, and potential secrets. Use this skill to understand code health
+and identify areas that need attention.
+
+## Prerequisites
+
+Findings must be generated first by running analyzers via the CLI:
+
+```bash
+# Run all analyzers
+./.aide/bin/aide findings run --path .
+
+# Run specific analyzers
+./.aide/bin/aide findings run --path . --analyzer complexity
+./.aide/bin/aide findings run --path . --analyzer coupling
+./.aide/bin/aide findings run --path . --analyzer secrets
+./.aide/bin/aide findings run --path . --analyzer clones
+```
+
+**Binary location:** The aide binary is at `.aide/bin/aide`. If it's on your `$PATH`, you can use `aide` directly.
+
+## Available Tools
+
+### 1. Search Findings (`mcp__plugin_aide_aide__findings_search`)
+
+Full-text search across all findings. Supports Bleve query syntax for advanced searches.
+
+**Parameters:**
+- `query` (required) — Search term or Bleve query
+- `analyzer` (optional) — Filter to one analyzer: `complexity`, `coupling`, `secrets`, `clones`
+- `severity` (optional) — Filter by severity: `info`, `warning`, `critical`
+- `file` (optional) — Filter by file path substring
+- `limit` (optional) — Max results (default 20)
+
+**Example usage:**
+
+```
+Search for: "high complexity"
+-> findings_search query="complexity" severity="warning"
+-> Returns: functions with high cyclomatic complexity, with file:line
+```
+
+### 2. List Findings (`mcp__plugin_aide_aide__findings_list`)
+
+List findings with filters. Use when you want to browse rather than search.
+
+**Parameters:**
+- `analyzer` (optional) — Filter to one analyzer
+- `severity` (optional) — Filter by severity
+- `file` (optional) — Filter by file path substring
+- `limit` (optional) — Max results (default 20)
+- `offset` (optional) — Pagination offset
+
+**Example usage:**
+
+```
+List all critical findings
+-> findings_list severity="critical"
+-> Returns: all critical-severity findings across all analyzers
+```
+
+### 3. Findings Statistics (`mcp__plugin_aide_aide__findings_stats`)
+
+Get aggregate counts by analyzer and severity. Use as a starting point to understand overall
+code health before drilling into specifics.
+
+**Example usage:**
+
+```
+How healthy is the codebase?
+-> findings_stats
+-> Returns: counts per analyzer, counts per severity, total findings
+```
+
+## Workflow
+
+### Quick Health Check
+
+1. **Get overview** — Use `findings_stats` to see counts by analyzer and severity
+2. **Triage critical** — Use `findings_list severity="critical"` to review highest-priority items
+3. **Drill into areas** — Use `findings_search` with file or query filters for specific concerns
+
+### Complexity Analysis
+
+1. Run `findings_search analyzer="complexity" severity="critical"` to find the most complex functions
+2. Use `code_outline` on flagged files to understand structure
+3. Use `Read` with offset/limit to examine the specific functions
+4. Recommend decomposition strategies
+
+### Duplication Analysis
+
+1. Run `findings_list analyzer="clones"` to see detected code clones
+2. Each finding includes the clone pair — both file locations and line ranges
+3. Use `Read` to compare the duplicated sections
+4. Recommend extraction into shared functions or modules
+
+### Coupling Analysis
+
+1. Run `findings_search analyzer="coupling"` to see import fan-out/fan-in issues
+2. High fan-out means a file imports too many things (potential god module)
+3. High fan-in means many files depend on one (fragile dependency)
+4. Cycle findings indicate circular dependency chains
+
+### Secret Detection
+
+1. Run `findings_list analyzer="secrets" severity="critical"` for confirmed secrets
+2. Run `findings_list analyzer="secrets"` for all potential secrets (including unverified)
+3. Each finding includes the secret category (e.g., AWS, GitHub, generic API key)
+4. Snippets are redacted for safety — use `Read` to examine context around the finding
+
+## Anti-Pattern Identification
+
+Beyond the automated analyzers, look for these patterns using findings as starting points:
+
+| Finding | Likely Anti-Pattern | Action |
+|---------|-------------------|--------|
+| Complexity > 20 | God function | Decompose into smaller functions |
+| Fan-out > 15 | Kitchen sink module | Split responsibilities |
+| Fan-in > 20 | Fragile dependency | Consider interface/abstraction |
+| Multiple clones | Copy-paste programming | Extract shared utility |
+| Import cycle | Circular dependency | Restructure module boundaries |
+
+## Output Format
+
+```markdown
+## Code Health Report
+
+### Overview
+- Total findings: X (Y critical, Z warnings)
+- Top concern: [area/file with most issues]
+
+### Hotspots
+1. **`file:line`** - [description] (severity)
+   - Impact: [why this matters]
+   - Recommendation: [what to do]
+
+### Patterns Detected
+- [List of anti-patterns found with evidence]
+
+### Recommendations
+1. [Prioritized action items]
+```
+
+## Failure Handling
+
+1. **No findings data** — Tell user to run analyzers first: `./.aide/bin/aide findings run --path .`
+2. **Stale findings** — Findings reflect the state at last analyzer run; recommend re-running if code changed significantly
+3. **False positives** — Secret detection may flag test fixtures or example configs; note when findings appear to be in test/example code
+
+## Verification Criteria
+
+- [ ] Checked `findings_stats` for overall picture
+- [ ] Reviewed critical findings
+- [ ] Cross-referenced findings with actual code (used `Read` or `code_outline`)
+- [ ] Provided actionable recommendations with file:line references
+- [ ] Noted any false positives or findings that need manual verification

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/plan-swarm/SKILL.md

@@ -113,6 +113,11 @@ Output a structured story list. Each story must be:
 
 4. **Instruct the user**: Run `/aide:swarm` to execute the plan
 
+**Note on task materialization:** The plan is stored as a decision, not as tasks. The `/aide:swarm` skill reads the plan and materializes tasks at execution time:
+
+- **Claude Code**: Each story agent creates native tasks (`TaskCreate`) with `blockedBy` dependency chaining for SDLC stages.
+- **OpenCode**: The orchestrator creates aide tasks (`task_create` MCP tool) for all SDLC stages upfront, and story agents claim them.
+
 ## Output Format
 
 The stored `swarm-plan` decision should be a JSON object:

package/skills/ralph/SKILL.md

@@ -34,6 +34,15 @@ You are now in **Ralph Wiggum mode** - an iterative development methodology that
 
 All state is managed through aide. Use MCP tools for reads, CLI for writes:
 
+### Task System Roles
+
+| System                      | Role                                                    | How                                                                   |
+| --------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------- |
+| **aide tasks** (MCP or CLI) | Durable task backlog, claiming, persistence enforcement | `task_create`/`task_claim`/`task_complete` (MCP) or `aide task` (CLI) |
+| **Native todowrite**        | Personal progress tracking within current iteration     | `todowrite` tool — tracks sub-steps of current task                   |
+
+aide tasks are the source of truth for ralph — they survive session restarts and are checked by persistence hooks to block premature stopping. Use native `todowrite` for your own step-by-step checklist within each task iteration.
+
 ### Reads (MCP Tools)
 
 | Tool                                   | Purpose              |
@@ -43,14 +52,18 @@ All state is managed through aide. Use MCP tools for reads, CLI for writes:
 | `mcp__plugin_aide_aide__decision_get`  | Get decisions        |
 | `mcp__plugin_aide_aide__decision_list` | List all decisions   |
 | `mcp__plugin_aide_aide__memory_search` | Search discoveries   |
+| `task_list`                            | List aide tasks      |
+| `task_get`                             | Get task by ID       |
 
-### Writes (CLI via Bash)
+### Writes (CLI via Bash or MCP)
 
 ```bash
 # Phase tracking
 ./.aide/bin/aide state set ralph:phase planning   # or "building"
 
-# Task management (use Claude's native TaskCreate/TaskUpdate/TaskList)
+# Task management — use aide tasks (persistent, claimable)
+# Via MCP: task_create, task_claim, task_complete
+# Via CLI: ./.aide/bin/aide task create/claim/complete
 
 # Decisions
 ./.aide/bin/aide decision set <topic> "<decision>" --rationale="<why>"
@@ -168,12 +181,6 @@ Claim it:
 ./.aide/bin/aide task claim <task-id> --agent=ralph
 ```
 
-Claim it:
-
-```bash
-./.aide/bin/aide task claim <task-id> --agent=ralph
-```
-
 #### 3. Verify Gap Still Exists (Don't Assume!)
 
 Before implementing, RE-VERIFY:

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,29 +46,51 @@ 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
+- `mcp__plugin_aide_aide__findings_search` - Search static analysis findings (complexity, secrets, clones) related to changed code
+- `mcp__plugin_aide_aide__findings_list` - List findings filtered by file, severity, or analyzer
+- `mcp__plugin_aide_aide__findings_stats` - Overview of finding counts by analyzer and severity
 
 ## Output Format
 
@@ -73,28 +98,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 +133,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 +153,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 +166,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