@jmylchreest/aide-plugin 0.0.24 → 0.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "description": "aide plugin for OpenCode — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",
@@ -14,6 +14,7 @@
     "src/core",
     "src/cli",
     "src/lib",
+    "skills",
     "bin",
     "README.md"
   ],

package/skills/build-fix/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: build-fix
+description: Fix build, lint, and type errors
+triggers:
+  - fix build
+  - fix the build
+  - build is broken
+  - lint errors
+  - type errors
+  - fix errors
+---
+
+# Build Fix Mode
+
+**Recommended model tier:** balanced (sonnet) - this skill performs straightforward operations
+
+Rapidly fix all build, type, and lint errors with minimal changes.
+
+## Prerequisites
+
+Before starting, ensure you have:
+- Access to the project root directory
+- Build tools installed (npm, tsc, etc.)
+
+## Workflow
+
+### Step 1: Capture All Errors
+
+Run all checks and capture output:
+
+```bash
+# Run in sequence, capture all output
+npm run build 2>&1 | head -100
+npm run lint 2>&1 | head -100
+npx tsc --noEmit 2>&1 | head -100
+```
+
+**If commands fail to run:**
+- Check package.json for available scripts
+- Try `npm install` if dependencies are missing
+- Use `npm ci` for clean install if lock file exists
+
+### Step 2: Categorize Errors by Priority
+
+Process errors in this order:
+
+1. **Type errors** (highest priority) - Fix TypeScript/type issues first
+2. **Build errors** - Compilation failures
+3. **Lint errors** - ESLint, Prettier, etc.
+4. **Warnings** - Address only if trivial
+
+Group similar errors:
+- Missing imports
+- Type mismatches
+- Unused variables
+- Formatting issues
+
+### Step 3: Search for Context
+
+Use MCP tools to find definitions and patterns:
+
+```
+# Find type definitions
+mcp__plugin_aide_aide__code_search query="InterfaceName" kind="interface"
+
+# Find function signatures
+mcp__plugin_aide_aide__code_search query="functionName" kind="function"
+
+# Get symbols in a file
+mcp__plugin_aide_aide__code_symbols file="path/to/file.ts"
+
+# Check project conventions
+mcp__plugin_aide_aide__decision_get topic="coding-style"
+```
+
+### Step 4: Apply Fixes Systematically
+
+Fix in batches by category:
+
+1. **All missing imports together** - Add import statements
+2. **All type annotations together** - Add/fix type declarations
+3. **All unused variables together** - Remove or prefix with `_`
+
+### Step 5: Verify After Each Batch
+
+```bash
+# Run full verification
+npm run build && npm run lint && npx tsc --noEmit
+```
+
+**Verification criteria:**
+- Exit code 0 for all commands
+- No error output
+- Warnings are acceptable if not introduced by changes
+
+### Step 6: Final Verification
+
+```bash
+# Run tests to ensure fixes didn't break functionality
+npm test
+```
+
+## Failure Handling
+
+| Failure | Action |
+|---------|--------|
+| `npm run build` fails to start | Run `npm install` first |
+| Circular dependency error | Check import structure, may need refactoring |
+| Type error in third-party lib | Check @types package version, update if needed |
+| Cannot resolve module | Check tsconfig.json paths, baseUrl settings |
+| ESLint config error | Check .eslintrc, ensure plugins installed |
+| Fix introduces new errors | Revert and try alternative approach |
+
+## Rules
+
+- **Minimal changes** - Fix only what's broken
+- **No refactoring** - Don't improve "while you're there"
+- **No new features** - Just fix errors
+- **Match style** - Follow existing patterns exactly
+- **One batch at a time** - Verify between batches
+
+## Common Fixes Reference
+
+| Error | Fix |
+|-------|-----|
+| Cannot find module | Add import statement |
+| Type 'X' not assignable | Add type annotation or use type assertion |
+| 'X' is declared but never used | Remove or prefix with `_` |
+| Missing return type | Add explicit return type |
+| Unexpected any | Add proper type annotation |
+| Property does not exist | Check interface, add property or fix typo |
+| Argument of type X not assignable | Check function signature, cast if needed |
+
+## MCP Tools
+
+- `mcp__plugin_aide_aide__code_search` - Find type definitions, function signatures
+- `mcp__plugin_aide_aide__code_symbols` - List all symbols in a file
+- `mcp__plugin_aide_aide__decision_get` - Check project coding decisions
+
+## Output Format
+
+Report all fixes made:
+
+```markdown
+## Build Fix Report
+
+### Errors Fixed
+
+- `src/foo.ts:10` - Added missing import for `Bar`
+- `src/foo.ts:25` - Fixed type: `string` -> `string | null`
+- `src/bar.ts:5` - Removed unused variable `temp`
+
+### Verification
+
+- Build: PASS
+- Lint: PASS
+- Types: PASS
+- Tests: PASS
+
+### Notes
+[Any observations or remaining warnings]
+```

package/skills/code-search/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: code-search
+description: Search code symbols, find function calls, and analyze codebase
+triggers:
+  - find function
+  - where is
+  - who calls
+  - find class
+  - find method
+  - search code
+  - code search
+  - find symbol
+  - call sites
+  - references to
+  - what calls
+  - show me the
+---
+
+# Code Search
+
+**Recommended model tier:** balanced (sonnet) - this skill performs straightforward operations
+
+Search for code symbols (functions, classes, methods, types) and find their call sites.
+
+## Available Tools
+
+### 1. Search Symbols (`mcp__plugin_aide_aide__code_search`)
+
+Find functions, classes, methods, interfaces, and types by name or signature.
+
+**Example usage:**
+```
+Search for: "getUserById"
+→ Uses code_search tool
+→ Returns: function signatures, file locations, line numbers
+```
+
+### 2. Find References (`mcp__plugin_aide_aide__code_references`)
+
+Find all places where a symbol is called/used.
+
+**Example usage:**
+```
+Who calls "getUserById"?
+→ Uses code_references tool
+→ Returns: all call sites with file:line and context
+```
+
+### 3. List File Symbols (`mcp__plugin_aide_aide__code_symbols`)
+
+List all symbols defined in a specific file.
+
+**Example usage:**
+```
+What functions are in src/auth.ts?
+→ Uses code_symbols tool
+→ Returns: all functions, classes, types in that file
+```
+
+### 4. Check Index Status (`mcp__plugin_aide_aide__code_stats`)
+
+Check if the codebase has been indexed.
+
+**Example usage:**
+```
+Is the code indexed?
+→ Uses code_stats tool
+→ Returns: file count, symbol count, reference count
+```
+
+## Workflow
+
+1. **First, check if codebase is indexed:**
+   - Use `code_stats` to verify indexing
+   - If not indexed, tell user to run: `aide code index`
+
+2. **Search for symbols:**
+   - Use `code_search` with the symbol name or pattern
+   - Filter by kind (function, method, class, interface, type)
+   - Filter by language (typescript, javascript, go, python)
+
+3. **Find call sites:**
+   - Use `code_references` to find where a symbol is used
+   - Shows all callers with context
+
+4. **Explore specific files:**
+   - Use `code_symbols` to list all definitions in a file
+
+## Example Session
+
+**User:** "Where is the authentication function?"
+
+**Assistant action:**
+1. Use `code_search` with query "auth" or "authenticate"
+2. Show matching functions with file locations
+
+**User:** "Who calls authenticateUser?"
+
+**Assistant action:**
+1. Use `code_references` with symbol "authenticateUser"
+2. Show all call sites grouped by file
+
+## Notes
+
+- Code must be indexed first: `aide code index`
+- Indexing is incremental - only changed files are re-parsed
+- Supports: TypeScript, JavaScript, Go, Python, Rust, and more
+- For file watching: `AIDE_CODE_WATCH=1 claude`

package/skills/debug/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: debug
+description: Systematic debugging workflow for tracking down bugs and issues
+triggers:
+  - "debug this"
+  - "debug mode"
+  - "fix this bug"
+  - "trace the bug"
+  - "find the bug"
+---
+
+# Debug Mode
+
+**Recommended model tier:** smart (opus) - this skill requires complex reasoning
+
+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.)
+
+## Workflow
+
+### Step 1: Reproduce the Issue
+
+**Goal:** Confirm the bug exists and understand its behavior.
+
+```bash
+# Run the failing code/test
+npm test -- --grep "failing test"
+# OR
+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
+
+### Step 2: Locate the Relevant Code
+
+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 symbols in suspect file
+mcp__plugin_aide_aide__code_symbols file="path/to/file.ts"
+
+# Search for error message text in code
+Grep for "error message text"
+```
+
+### Step 3: Trace the Execution Path
+
+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"`
+
+### 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 |
+
+### Step 5: Validate Hypotheses
+
+Test each hypothesis systematically:
+
+```bash
+# Add temporary logging
+console.log('DEBUG: variable =', JSON.stringify(variable));
+
+# Check with debugger
+node --inspect-brk script.js
+
+# Run specific test
+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)
+- Check async ordering
+
+### 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
+- Fix variable scope
+- Add missing initialization
+
+### Step 7: Verify the Fix
+
+```bash
+# Run the originally failing test/scenario
+npm test -- --grep "failing test"
+
+# Run related tests
+npm test -- --grep "related feature"
+
+# Run full test suite to check for regressions
+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 |
+
+## MCP Tools
+
+- `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_references` - Find all callers of a function
+- `mcp__plugin_aide_aide__memory_search` - Check for related past issues
+
+## Output Format
+
+```markdown
+## 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]
+```
+
+## Tips
+
+- Always get the full error message and stack trace first
+- Don't guess - trace the code path methodically
+- One fix at a time - don't bundle unrelated changes
+- Remove temporary logging before committing
+- Consider if the bug could occur elsewhere

package/skills/decide/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: decide
+description: Formal decision-making interview for architectural choices
+triggers:
+  - decide
+  - help me decide
+  - help me choose
+  - how should we
+  - what should we use
+  - which option
+  - trade-offs
+  - pros and cons
+allowed-tools: Bash(aide decision set *)
+---
+
+# Decision Mode
+
+**Recommended model tier:** smart (opus) - this skill requires complex reasoning
+
+Formal decision-making workflow for architectural and technical choices.
+
+## Purpose
+
+When facing a significant technical decision, this workflow guides you through structured analysis to make an informed choice that will be recorded and respected by all future sessions and agents.
+
+## Workflow
+
+### Phase 1: IDENTIFY
+
+Ask the user to clarify:
+- What decision needs to be made?
+- What is the context? (new system, migration, constraint?)
+- What are the requirements? (scale, team, timeline?)
+- Are there any hard constraints?
+
+**Example questions:**
+- "What technical decision do you need to make?"
+- "What problem are you trying to solve?"
+- "Are there any constraints I should know about?"
+
+### Phase 2: EXPLORE
+
+Research and propose options:
+- List 3-5 viable alternatives
+- Include the obvious choices AND less common ones
+- For each option, note what it's best suited for
+
+**Output format:**
+```markdown
+## Options
+
+1. **[Option A]** - Brief description
+   - Best for: [use case]
+
+2. **[Option B]** - Brief description
+   - Best for: [use case]
+
+3. **[Option C]** - Brief description
+   - Best for: [use case]
+```
+
+### Phase 3: ANALYZE
+
+For each option, evaluate:
+- **Pros**: What are the benefits?
+- **Cons**: What are the drawbacks?
+- **Fit**: How well does it match the requirements?
+
+**Output format:**
+```markdown
+## Analysis
+
+| Option | Pros | Cons | Fit |
+|--------|------|------|-----|
+| Option A | Fast, simple | Limited scale | Good for MVP |
+| Option B | Scalable | Complex setup | Good for growth |
+| Option C | Flexible | Learning curve | Good if team knows it |
+```
+
+Consider:
+- Complexity (implementation, maintenance)
+- Team familiarity
+- Scalability
+- Security implications
+- Cost (time, money, resources)
+- Reversibility (how hard to change later?)
+
+### Phase 4: RECOMMEND
+
+Provide a clear recommendation with rationale:
+
+```markdown
+## Recommendation
+
+I recommend **[Option]** because:
+1. [Primary reason tied to requirements]
+2. [Secondary benefit]
+3. [Risk mitigation]
+
+This choice [addresses constraint X] while [enabling future Y].
+```
+
+Ask for confirmation:
+- "Does this recommendation align with your goals?"
+- "Would you like to proceed with this decision?"
+- "Any concerns before we record this?"
+
+### Phase 5: CONFIRM
+
+Wait for explicit user approval before recording:
+- User says "yes", "go ahead", "let's do it" → proceed to record
+- User has concerns → address them, refine recommendation
+- User wants different option → adjust and confirm
+
+### Phase 6: RECORD
+
+Store the decision using the `aide decision set` CLI command via Bash:
+
+```bash
+aide decision set "<topic-slug>" "<decision summary>" --rationale="<why this was chosen>"
+```
+
+**Topic naming:**
+- Use kebab-case: `auth-strategy`, `database-choice`, `api-design`
+- Be specific: `user-auth-method` not just `auth`
+- Include scope if relevant: `payments-queue-strategy`
+
+**Verify** the decision was stored:
+```bash
+aide decision get "<topic-slug>"
+```
+
+## Example Session
+
+```
+User: help me decide how to handle background jobs
+
+Claude: [IDENTIFY]
+What kind of background jobs do you need to handle?
+- Scheduled tasks (cron-like)?
+- Async processing (triggered by events)?
+- Long-running workers?
+
+What's your current stack and scale expectations?
+
+User: Async processing for email sending and webhook deliveries.
+Stack is Node.js/TypeScript, expecting 10K jobs/day initially.
+
+Claude: [EXPLORE]
+## Options
+
+1. **BullMQ (Redis)** - Production-ready Node.js queue
+   - Best for: Node.js apps needing reliability + Redis features
+
+2. **AWS SQS + Lambda** - Serverless queue
+   - Best for: AWS-native apps, variable load
+
+3. **Database-backed queue** - Simple polling
+   - Best for: Low volume, no new infrastructure
+
+4. **RabbitMQ** - Enterprise message broker
+   - Best for: Complex routing, multi-language
+
+[ANALYZE]
+| Option | Pros | Cons | Fit |
+|--------|------|------|-----|
+| BullMQ | Native TS, retries, dashboard | Needs Redis | Excellent |
+| SQS+Lambda | Serverless, scales | Cold starts, AWS lock-in | Good |
+| DB queue | Simple, no new infra | Polling overhead, scale limits | MVP only |
+| RabbitMQ | Powerful routing | Overkill, operational burden | Over-engineered |
+
+[RECOMMEND]
+I recommend **BullMQ with Redis** because:
+1. Native TypeScript support matches your stack
+2. Built-in retries, delays, and rate limiting for email/webhooks
+3. Bull Board provides visibility without custom tooling
+4. 10K/day is well within comfortable range, scales to millions
+
+Redis adds infrastructure but enables other features (caching, sessions).
+
+Do you want to proceed with this decision?
+
+User: yes, let's go with BullMQ
+
+Claude: [RECORD]
+[Calls aide decision set via Bash]
+
+```bash
+aide decision set "background-jobs-queue" "Use BullMQ with Redis for background job processing (emails, webhooks)" --rationale="Native TypeScript support, built-in retries/delays/rate-limiting, Bull Board for visibility, 10K/day well within capacity. Rejected: SQS+Lambda (AWS lock-in, cold starts), DB queue (limited scale), RabbitMQ (over-engineered)"
+```
+
+Decision recorded. Future sessions will follow this architectural choice.
+```
+
+## Integration
+
+Decisions stored via `aide decision set` are:
+1. Persisted in the aide memory database
+2. Injected into future session contexts at startup
+3. Visible to swarm agents (they won't contradict decisions)
+4. Queryable via `aide decision get`, `aide decision list`, or the MCP tools `decision_get`/`decision_list`
+
+## When to Use This Skill
+
+**Good candidates for formal decisions:**
+- Authentication/authorization strategy
+- Database technology choice
+- API design patterns
+- State management approach
+- Testing strategy
+- Deployment architecture
+- Third-party service selection
+
+**NOT needed for:**
+- Minor implementation details
+- Obvious choices with no trade-offs
+- Temporary/experimental code
+- Personal preferences (use memories instead)
+
+## Changing Decisions
+
+Decisions can be superseded:
+1. Run `/aide:decide` again for the same topic
+2. New decision replaces old (history preserved)
+3. Use `mcp__plugin_aide_aide__decision_history` to see evolution