@jmylchreest/aide-plugin 0.0.24 → 0.0.26

package/skills/implement/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: implement
+description: TDD implementation - make failing tests pass
+triggers:
+  - implement this
+  - implement the
+  - make tests pass
+  - dev stage
+  - development stage
+---
+
+# Implement Mode
+
+**Recommended model tier:** smart (opus) - this skill requires complex reasoning
+
+Focused TDD implementation: make failing tests pass with minimal code.
+
+## Purpose
+
+This is the DEV stage of the SDLC pipeline. Tests already exist from the TEST stage. Your job is to write the minimal implementation that makes them pass.
+
+## Prerequisites
+
+Before starting:
+- Tests exist and are failing (from TEST stage)
+- Design/spec is available (from DESIGN stage)
+- You know which files to create/modify
+
+## Workflow
+
+### Step 1: Verify Tests Exist and Fail
+
+```bash
+# Run the tests - they MUST fail initially
+npm test -- path/to/feature.test.ts
+# or
+go test ./pkg/feature/...
+```
+
+**If tests pass**: The work is already done. Mark complete and move on.
+
+**If tests don't exist**: This is wrong - go back to TEST stage.
+
+### Step 2: Read the Tests
+
+Understand what the tests expect:
+- What functions/methods need to exist?
+- What are the expected inputs and outputs?
+- What edge cases are covered?
+
+```bash
+# Read the test file
+Read path/to/feature.test.ts
+```
+
+### Step 3: Check Design Decisions
+
+Use `mcp__plugin_aide_aide__decision_get` with the feature topic to review decisions from DESIGN stage.
+Use `mcp__plugin_aide_aide__decision_list` to see all project decisions.
+
+### Step 4: Implement Incrementally
+
+Write code to make tests pass **one at a time**:
+
+1. Pick the simplest failing test
+2. Write minimal code to pass it
+3. Run tests
+4. If passing, move to next test
+5. If failing, fix before proceeding
+
+```bash
+# Run specific test
+npm test -- --grep "should create user"
+# or
+go test -run TestCreateUser ./pkg/...
+```
+
+### Step 5: Backpressure Checkpoint (REQUIRED)
+
+**You CANNOT proceed until ALL tests pass.**
+
+```bash
+# Full test run
+npm test -- path/to/feature.test.ts
+# or
+go test -v ./pkg/feature/...
+```
+
+**BLOCKING RULE**: If any test fails:
+1. Analyze the failure
+2. Fix the issue
+3. Re-run tests
+4. Repeat until ALL pass
+
+**DO NOT skip failing tests. DO NOT proceed with red tests.**
+
+### Step 6: Verify Build
+
+```bash
+# Ensure it compiles
+npm run build
+# or
+go build ./...
+```
+
+### Step 7: Commit
+
+```bash
+git add -A
+git commit -m "feat: implement <feature> - tests passing"
+```
+
+## Rules
+
+1. **Tests First**: Never write code without a failing test
+2. **Minimal Code**: Only write what's needed to pass tests
+3. **No Gold Plating**: Don't add features not covered by tests
+4. **Red → Green**: Tests must fail before they pass
+5. **Atomic Commits**: One logical change per commit
+6. **No Skipping**: Every test must pass
+
+## Common Patterns
+
+### TypeScript/JavaScript
+
+```typescript
+// Read test expectations
+describe('UserService', () => {
+  it('should create user with email and name', async () => {
+    const user = await service.createUser({ email: 'test@example.com', name: 'Test' });
+    expect(user.id).toBeDefined();
+    expect(user.email).toBe('test@example.com');
+  });
+});
+
+// Implement to match
+export class UserService {
+  async createUser(input: CreateUserInput): Promise<User> {
+    return {
+      id: crypto.randomUUID(),
+      email: input.email,
+      name: input.name,
+      createdAt: new Date(),
+    };
+  }
+}
+```
+
+### Go
+
+```go
+// Read test expectations
+func TestCreateUser(t *testing.T) {
+    svc := NewUserService()
+    user, err := svc.CreateUser(context.Background(), CreateUserInput{
+        Email: "test@example.com",
+        Name:  "Test",
+    })
+    require.NoError(t, err)
+    assert.NotEmpty(t, user.ID)
+    assert.Equal(t, "test@example.com", user.Email)
+}
+
+// Implement to match
+func (s *UserService) CreateUser(ctx context.Context, input CreateUserInput) (*User, error) {
+    return &User{
+        ID:        uuid.New().String(),
+        Email:     input.Email,
+        Name:      input.Name,
+        CreatedAt: time.Now(),
+    }, nil
+}
+```
+
+## Failure Handling
+
+### Test Won't Pass After Multiple Attempts
+
+1. Re-read the test - is the expectation correct?
+2. Check if test has a bug (it happens)
+3. Check design decisions - is implementation matching spec?
+4. Record blocker:
+   ```bash
+   aide memory add --category=blocker "Cannot pass test X: <reason>"
+   ```
+5. If stuck after 3 attempts, ask for help
+
+### Build Fails
+
+1. Read error message carefully
+2. Check for missing imports
+3. Check for type mismatches
+4. Fix and re-run build
+5. Then re-run tests
+
+### Test Passes But Implementation Feels Wrong
+
+1. If tests pass, the contract is met
+2. Don't refactor during implement stage
+3. Note concerns for future:
+   ```bash
+   aide memory add --category=issue "Implementation of X could be improved: <how>"
+   ```
+4. Proceed - refactoring is a separate concern
+
+## Verification Checklist
+
+Before completing:
+- [ ] All tests pass (not just some)
+- [ ] Build succeeds
+- [ ] Changes are committed
+- [ ] No debug code left (console.log, fmt.Println for debugging)
+
+## Completion
+
+When all tests pass:
+
+```bash
+# Final verification
+npm test -- path/to/feature.test.ts && npm run build
+
+# Or Go
+go test -v ./pkg/feature/... && go build ./...
+```
+
+Output: "Implementation complete. All tests passing. Ready for VERIFY stage."
+
+## Integration with SDLC Pipeline
+
+This skill is designed for the DEV stage:
+
+```
+[DESIGN] → [TEST] → [DEV/IMPLEMENT] → [VERIFY] → [DOCS]
+                         ↑
+                    YOU ARE HERE
+```
+
+- **Input**: Failing tests from TEST stage
+- **Output**: Passing tests, working implementation
+- **Next**: VERIFY stage runs full validation

package/skills/memorise/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: memorise
+description: Capture key learnings, patterns, gotchas, or context as persistent memories
+triggers:
+  - remember this
+  - remember that
+  - dont forget
+  - memorise
+  - note that
+  - note this
+  - save this
+  - store this
+  - for future
+  - keep in mind
+allowed-tools: Bash(aide memory add *)
+---
+
+# Memorise
+
+**Recommended model tier:** balanced (sonnet) - this skill performs straightforward operations
+
+Capture important information for future sessions by storing it in the aide memory database.
+
+## How to Store
+
+Use the `aide memory add` CLI command via Bash:
+
+```bash
+aide memory add --category=<category> --tags=<comma,separated,tags> "<content>"
+```
+
+## Categories
+
+- `learning` - Something discovered about the codebase or tools
+- `decision` - An architectural or design choice made
+- `session` - Summary of a work session
+- `pattern` - A reusable approach or pattern identified
+- `gotcha` - A pitfall or issue to avoid in future
+
+## When to Use
+
+- End of a significant task or session
+- After discovering something important about the codebase
+- When a decision is made that should persist
+- After solving a tricky problem (capture the solution)
+- When user shares a preference or important information
+
+## Examples
+
+### Simple preference (global - injected at session start)
+```bash
+aide memory add --category=learning --tags=preferences,colour,scope:global "User's favourite colour is blue"
+```
+
+### Technical learning (project-specific)
+```bash
+aide memory add --category=learning --tags=testing,vitest,project:myapp,session:abc12345 "Vitest requires .js extensions for ESM imports even for .ts files. Configure moduleResolution: NodeNext in tsconfig."
+```
+
+### Session summary
+```bash
+aide memory add --category=session --tags=auth,api,project:myapp,session:abc12345 "Implemented JWT auth with 15min access tokens, 7day refresh tokens in httpOnly cookies. Files: src/auth/jwt.ts, src/middleware/auth.ts, src/routes/auth.ts"
+```
+
+### Gotcha (global - applies everywhere)
+```bash
+aide memory add --category=gotcha --tags=hooks,claude-code,scope:global "Hooks must not write to stderr - Claude Code interprets any stderr as error. Debug logging must go to files only."
+```
+
+## Instructions
+
+When the user invokes `/aide:memorise <something>`:
+
+1. Parse what they want to remember
+2. Determine the scope:
+   - **User preference** (colour, style, etc.) → add `scope:global`
+   - **Project-specific learning** → add `project:<project-name>,session:${CLAUDE_SESSION_ID:0:8}`
+   - **Session summary** → add `project:<project-name>,session:${CLAUDE_SESSION_ID:0:8}`
+3. Choose appropriate category and descriptive tags
+4. Format the content concisely but completely
+5. Call `aide memory add` via Bash to store it
+6. **Verify success** - check exit code is 0 and output contains the memory ID
+7. Confirm what was stored
+
+Keep content concise - aim for 1-3 sentences unless it's a complex session summary.
+
+## Failure Handling
+
+If `aide memory add` fails:
+
+1. **Check error message** - common issues:
+   - Database not accessible: ensure aide MCP server is running
+   - Invalid category: use one of `learning`, `decision`, `session`, `pattern`, `gotcha`
+   - Empty content: content must be non-empty
+
+2. **Retry with fixes** if the issue is correctable
+
+3. **Report failure** if unable to store:
+   ```
+   Failed to store memory: <error details>
+   Please check aide MCP server status.
+   ```
+
+## Verification
+
+A successful memory add returns:
+```
+Added memory: <ULID>
+```
+
+You can verify by searching for the memory:
+```bash
+aide memory search "<key term from content>" --limit=1
+```
+
+## Scope Tags
+
+Use scope tags to control when memories are injected:
+
+| Tag | When to Use | Injection |
+|-----|-------------|-----------|
+| `scope:global` | User preferences, universal learnings | Every session |
+| `project:<name>` | Project-specific learnings | Sessions in that project |
+| `session:<id>` | Context for this work session | Recent session injection |
+
+### Tagging Rules
+
+- **User preferences** (favourite colour, coding style): Always add `scope:global`
+- **Project learnings** (API patterns, testing approach): Add `project:<name>,session:<id>`
+- **Session summaries**: Add `project:<name>,session:<id>` with `category=session`
+
+Get the project name from the git remote or directory name. Session ID is available as `$CLAUDE_SESSION_ID` (use first 8 chars).
+
+## For Swarm/Multi-Agent
+
+Add agent context to tags:
+```bash
+aide memory add --category=session --tags=swarm,agent:main "Overall task outcome..."
+```

package/skills/perf/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: perf
+description: Performance analysis and optimization workflow
+triggers:
+  - "optimize"
+  - "performance"
+  - "slow"
+  - "too slow"
+  - "speed up"
+  - "make faster"
+---
+
+# Performance Mode
+
+**Recommended model tier:** smart (opus) - this skill requires complex reasoning
+
+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
+
+## Workflow
+
+### Step 1: Establish Baseline Measurement
+
+**Never optimize without data.** Measure current performance:
+
+```bash
+# Node.js - simple timing
+time node script.js
+
+# Node.js - CPU profiling
+node --cpu-prof script.js
+# Creates CPU.*.cpuprofile - analyze in Chrome DevTools
+
+# Go - benchmarks
+go test -bench=. -benchmem ./...
+
+# API endpoint
+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
+- Number of I/O operations
+
+### Step 2: Identify Hotspots
+
+Find where time is being spent:
+
+```bash
+# Node.js profiling
+node --cpu-prof app.js
+# Then load .cpuprofile in Chrome DevTools > Performance
+
+# Go profiling
+go test -cpuprofile=cpu.prof -bench=.
+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"
+
+# Find database queries
+Grep for "SELECT", "find(", "query("
+
+# Find network calls
+Grep for "fetch", "axios", "http.Get"
+```
+
+### 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 |
+
+### Step 4: Apply Optimizations
+
+**Priority order (highest impact first):**
+
+1. **Algorithmic improvements** - O(n^2) -> O(n log n)
+2. **Reduce I/O** - Batch requests, add caching
+3. **Parallelize** - Concurrent operations
+4. **Reduce allocations** - Reuse objects, pre-allocate
+5. **Micro-optimizations** - Only as last resort
+
+**Make one optimization at a time and measure after each.**
+
+### Step 5: Measure After Each Change
+
+```bash
+# Same measurement as baseline
+time node script.js
+go test -bench=. -benchmem ./...
+```
+
+Compare:
+- Did the metric improve?
+- By how much (percentage)?
+- Any negative side effects?
+
+**If no improvement:** Revert and try different approach.
+
+### Step 6: Verify No Regressions
+
+```bash
+# Run all tests
+npm test
+go test ./...
+
+# Check for correctness
+# Ensure output is still correct after optimization
+```
+
+## 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 |
+
+## Common Optimizations
+
+### JavaScript/TypeScript
+
+```typescript
+// BAD: N+1 queries
+for (const user of users) {
+  const posts = await db.getPosts(user.id);
+}
+
+// GOOD: Batch query
+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);
+
+// GOOD: Single pass
+const grouped = { a: [], b: [] };
+for (const x of items) {
+  if (x.type in grouped) grouped[x.type].push(x.value);
+}
+
+// BAD: Serial async
+const result1 = await fetch(url1);
+const result2 = await fetch(url2);
+
+// GOOD: Parallel async
+const [result1, result2] = await Promise.all([
+  fetch(url1),
+  fetch(url2)
+]);
+```
+
+### Go
+
+```go
+// BAD: Allocation in loop
+var result []T
+for _, item := range items {
+    result = append(result, process(item))
+}
+
+// GOOD: Pre-allocate
+result := make([]T, 0, len(items))
+for _, item := range items {
+    result = append(result, process(item))
+}
+
+// BAD: String concatenation
+s := ""
+for _, item := range items {
+    s += item
+}
+
+// GOOD: Builder
+var b strings.Builder
+for _, item := range items {
+    b.WriteString(item)
+}
+```
+
+### SQL
+
+```sql
+-- BAD: Missing index on frequently queried column
+SELECT * FROM users WHERE email = 'x@y.com';
+
+-- GOOD: Add index
+CREATE INDEX idx_users_email ON users(email);
+
+-- BAD: SELECT *
+SELECT * FROM users;
+
+-- GOOD: Select only needed columns
+SELECT id, name, email FROM users;
+
+-- BAD: Query in loop
+-- for each user: SELECT * FROM posts WHERE user_id = ?
+
+-- GOOD: Single batch query
+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__memory_search` - Check past performance decisions
+
+## Profiling Commands Reference
+
+### Node.js
+```bash
+# CPU profiling
+node --cpu-prof app.js
+# Produces .cpuprofile file
+
+# Memory profiling
+node --heap-prof app.js
+# Produces .heapprofile file
+
+# Clinic.js for analysis
+npx clinic doctor -- node app.js
+npx clinic flame -- node app.js
+```
+
+### Go
+```bash
+# CPU profiling
+go test -cpuprofile=cpu.prof -bench=.
+go tool pprof -http=:8080 cpu.prof
+
+# Memory profiling
+go test -memprofile=mem.prof -bench=.
+go tool pprof -http=:8080 mem.prof
+
+# Execution trace
+go test -trace=trace.out -bench=.
+go tool trace trace.out
+```
+
+### Browser
+- DevTools -> Performance -> Record
+- DevTools -> Memory -> Heap snapshot
+- Lighthouse for overall page performance
+
+## Verification Criteria
+
+Before completing:
+- [ ] Baseline measurement recorded
+- [ ] Improvement quantified (percentage)
+- [ ] All tests still pass
+- [ ] No correctness regressions
+- [ ] Memory usage acceptable
+
+## Output Format
+
+```markdown
+## 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
+```