memory-journal-mcp 7.7.0 → 8.0.0

package/skills/adversarial-performance/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: adversarial-performance
+description: |
+  Multi-pass adversarial performance audit for entire repositories. Combines
+  structured profiling (Agent A) with adversarial stress-testing critique
+  (Agent B) through iterative passes. Optimize repo/backend performance, hot-paths, build size, and server throughput. Do NOT use for frontend page load metrics 
+  or Lighthouse audits (use web-perf). NOT for frontend Core Web Vitals (use web-perf).
+---
+
+# Adversarial Performance
+
+A multi-pass performance auditing system that produces high-confidence
+optimization assessments by introducing structured adversarial critique
+stages. Audits pass through an iterative pipeline of profiling,
+stress-testing critique, optimization planning, and optional external
+validation — producing output optimized for measurable impact, effort
+efficiency, and regression safety.
+
+## When to Load
+
+Load this skill when any of these apply:
+
+- Running a performance audit against an entire repository
+- Profiling build times, runtime hot paths, or bundle size
+- The user asks for an adversarial performance review or stress-test analysis
+- The user says "perf audit", "performance review", "find bottlenecks",
+  "adversarial performance", "optimize this repo", "make this faster",
+  "why is this slow", or "speed up my code"
+- Preparing a performance baseline report before a major release
+- You want to reduce blind spots in your own performance assessment
+
+## Auto-Detection
+
+Before starting, auto-detect the project profile by scanning the repository:
+
+| Signal                                          | Project Profile | Extra Categories                                           |
+| ----------------------------------------------- | --------------- | ---------------------------------------------------------- |
+| MCP SDK imports, tool handlers, `tools/list`    | `mcp-server`    | Token & Context Efficiency (Category 7) — full depth       |
+| Express/Hono/Fastify, HTTP handlers, `listen()` | `web-app`       | Runtime Performance (Category 4) — extra API latency focus |
+| `bin` field, CLI arg parsing                    | `cli-tool`      | Startup Cost analysis in Category 4                        |
+| Vitest/Jest/Playwright config                   | `tested`        | Test Suite Performance (Category 5) — full depth           |
+| Dockerfile present                              | `containerized` | Build Performance (Category 1) — Docker layer analysis     |
+| Database imports (better-sqlite3, pg, mysql2)   | `data-layer`    | Database & I/O (Category 6) — full depth                   |
+
+Profiles stack. A typical MCP server might be `mcp-server + cli-tool +
+tested + containerized + data-layer`.
+
+## Adversarial Protocol
+
+This skill follows the standard dual-agent adversarial pattern (Agent A: The Profiler, Agent B: The Stress Tester).
+For the core pipeline rules, phase definitions, and agent switching protocols, read:
+**[../adversarial-security/references/adversarial-base-protocol.md](../adversarial-security/references/adversarial-base-protocol.md)**
+
+For the performance-specific protocol with review dimensions, scoring weights, and output templates, read:
+**[references/multi-pass-performance-protocol.md](references/multi-pass-performance-protocol.md)**
+
+## Audit Categories
+
+The 7 performance categories audited during Phase 1 (Profiling) and
+challenged during Phase 2 (Stress Test) are:
+
+1. Build Performance
+2. Bundle & Output Analysis
+3. Dependency Weight
+4. Runtime Performance
+5. Test Suite Performance
+6. Database & I/O Performance
+7. Token & Context Efficiency (MCP servers — graceful degradation)
+
+For the full checklist with measurement methods, anti-patterns, and
+optimization patterns, read
+[references/audit-categories.md](references/audit-categories.md).
+
+## External Validation (Phase 4)
+
+Phase 4 triggers an independent validation pass using the GitHub CLI (`gh copilot`).
+This provides a fundamentally different model's perspective on the audit,
+catching performance patterns that internal review normalizes.
+
+For Copilot-specific prompt templates, read
+[references/copilot-performance-prompts.md](references/copilot-performance-prompts.md).
+
+**Prerequisites:** `gh` CLI v2.x+ with `gh auth status` passing. If `gh copilot`
+is not available, skip Phase 4 gracefully and note the skip in the journal entry.
+
+Read [references/copilot-usage.md](references/copilot-usage.md) for critical non-interactive execution requirements.
+
+## Feedback Loop & Documentation
+
+Every phase creates a journal entry with structured tags and entry types.
+This builds a searchable audit trail that tracks performance evolution
+across releases.
+
+For journal templates, tag conventions, and retrospective templates, read
+[references/feedback-loop.md](references/feedback-loop.md).
+
+### Journal Opt-Out
+
+See [references/journal-opt-out.md](references/journal-opt-out.md) for instructions on how to handle explicit opt-outs from journaling.
+
+### Consolidated Report
+
+The final deliverable is a **single consolidated artifact** merging all four
+phases into one document. Do NOT produce separate artifacts per phase — the user should receive one
+comprehensive document with all findings, optimizations, and external
+validation results. Before sharing output outside the audit context, redact or generalize sensitive query patterns, specific API payloads, and avoid including live credentials or internal hostnames.
+
+## Configuration
+
+| Variable             | Default    | Description                                                                                                     |
+| -------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- |
+| `MAX_AUDIT_PASSES`   | `2`        | Maximum stress-test cycles (phases 2–3 repeat)                                                                  |
+| `AUDIT_DEPTH`        | `standard` | Depth: `scan`, `standard`, or `intensive`                                                                       |
+| `COPILOT_VALIDATION` | `true`     | Enable/disable the Copilot extension validation phase                                                           |
+| `PROJECT_PROFILE`    | `auto`     | Auto-detect or explicit profile list                                                                            |
+| `RUN_COMMANDS`       | `false`    | Whether to execute measurement commands (`tsc --diagnostics`, `npm test`, etc.) or perform static analysis only |
+
+### Audit Depth Profiles
+
+- **Scan**: Quick triage — Categories 1, 3, 4 only. Focus on the most
+  impactful bottlenecks. Best for small repos or time-constrained reviews.
+- **Standard**: Full 7-category audit with all review dimensions. Default
+  for most repositories.
+- **Intensive**: Extended audit with additional focus on:
+  - Algorithmic complexity analysis (Big-O) on hot paths
+  - Memory allocation profiling patterns
+  - Cold start vs. warm path divergence
+  - Concurrency bottleneck analysis (event loop blocking, worker saturation)
+  - Historical regression tracking (compare against prior audit baselines)
+
+## Synergies
+
+| Skill/Workflow         | Relationship                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| `adversarial-security` | Sibling skill — applies adversarial pattern to security; this applies it to performance     |
+| `adversarial-planner`  | Parent pattern — plan-level adversarial review; this and security extend it to audits       |
+| `autonomous-dev`       | Generator/Evaluator pipeline at code level; use after this skill to implement optimizations |
+| `/perf-audit` workflow | Provides the category checklist; this skill adds adversarial methodology on top             |
+| `web-perf`             | Web-specific performance skill; use alongside for frontend-heavy projects                   |

package/skills/adversarial-performance/references/audit-categories.md

@@ -0,0 +1,462 @@
+# Audit Categories
+
+Detailed reference for the 7 performance audit categories. Each category
+includes what to measure, anti-patterns, optimization patterns, and
+depth-specific considerations.
+
+Agent A (Profiler) uses this as a measurement checklist during Phase 1.
+Agent B (Stress Tester) uses it to construct worst-case scenarios in Phase 2.
+
+---
+
+## Category 1 — Build Performance
+
+### What to Measure
+
+- Total TypeScript compilation time (`tsc --noEmit --diagnostics`)
+- Bundler build time (`npm run build`)
+- Files compiled and lines of code
+- Memory usage during compilation
+- Incremental vs. clean build times
+- Docker image build time (if containerized)
+
+### Anti-Patterns
+
+```typescript
+// Deep generic nesting — exponential type resolution
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K]
+} // Deeply nested usage causes slow compilation
+
+// Circular type references
+type A = { b: B }
+type B = { a: A } // Compiler struggles with these
+
+// Barrel re-exports pulling in entire dependency graph
+export * from './module-a'
+export * from './module-b'
+// Forces tsc to resolve everything even if only one export is used
+```
+
+### Optimization Patterns
+
+```typescript
+// Explicit exports instead of barrel wildcards
+export { SpecificType } from "./module-a";
+export { SpecificFunction } from "./module-b";
+
+// Project references for monorepo build parallelism
+// tsconfig.json
+{ "references": [{ "path": "./packages/core" }] }
+
+// Incremental compilation
+// tsconfig.json
+{ "compilerOptions": { "incremental": true, "tsBuildInfoFile": ".tsbuildinfo" } }
+```
+
+### Depth: Intensive
+
+- Profile individual file compilation times to find the slowest files
+- Analyze type complexity (deeply nested generics, conditional types)
+- Measure Docker layer cache hit rates
+- Compare clean vs. incremental build to validate caching effectiveness
+
+---
+
+## Category 2 — Bundle & Output Analysis
+
+### What to Measure
+
+- Total output size (`dist/` or `build/`)
+- Top 5 largest output files by size
+- Source map presence and size in production
+- Number of output chunks (for code-split builds)
+- Tree-shaking effectiveness (are unused exports eliminated?)
+
+### Anti-Patterns
+
+```typescript
+// Importing entire library when only one function is needed
+import _ from 'lodash' // Pulls in ~600KB
+_.get(obj, 'path')
+
+// Dev dependency accidentally in production bundle
+import { faker } from '@faker-js/faker' // 3MB+ test utility
+
+// Source maps shipped to production
+// tsup.config.ts
+{
+  sourcemap: true
+} // Fine for dev, costly for production
+```
+
+### Optimization Patterns
+
+```typescript
+// Targeted imports
+import get from 'lodash/get' // ~1KB vs 600KB
+
+// External dependencies (not bundled)
+// tsup.config.ts
+{
+  external: ['better-sqlite3', 'sql.js']
+}
+
+// Source maps only in dev
+{
+  sourcemap: process.env.NODE_ENV !== 'production'
+}
+```
+
+### Depth: Intensive
+
+- Trace each large output file to its source to find bundling waste
+- Analyze tree-shaking failures (what's included but never called?)
+- Measure gzip/brotli compressed sizes for realistic transfer cost
+
+---
+
+## Category 3 — Dependency Weight
+
+### What to Measure
+
+- Total production dependency count (direct + transitive)
+- Top 5 heaviest dependencies by install size
+- Duplicate packages (different versions of the same dep)
+- Dependency tree depth (deep trees increase install time and risk)
+- `devDependencies` accidentally in `dependencies`
+
+### Anti-Patterns
+
+```json
+// Heavy utility library for one function
+"dependencies": { "moment": "^2.30.0" }  // 300KB+ for date formatting
+
+// Duplicate versions in tree
+"better-sqlite3": "11.0.0"  // direct
+"some-plugin > better-sqlite3": "10.0.0"  // transitive duplicate
+
+// Dev dependency in prod
+"dependencies": { "@types/node": "^22.0.0" }  // Should be devDependencies
+```
+
+### Optimization Patterns
+
+```json
+// Lighter alternatives
+"dependencies": { "dayjs": "^1.11.0" }  // 2KB vs 300KB
+
+// Deduplication
+// npm dedupe
+
+// Correct dependency placement
+"devDependencies": { "@types/node": "^22.0.0" }
+```
+
+### Depth: Intensive
+
+- Calculate total `node_modules` size for production install
+- Compare each heavy dependency against lighter alternatives
+- Check for phantom dependencies (used but not declared — rely on hoisting)
+
+---
+
+## Category 4 — Runtime Performance
+
+### What to Look For
+
+This is a **static analysis** category. Scan source code for patterns that
+cause runtime performance issues without running a profiler.
+
+- **Hot-path allocations** — object/array creation inside tight loops,
+  repeated `JSON.parse`/`JSON.stringify`, unnecessary spread operators in
+  iteration
+- **Missing early returns** — functions doing expensive work before checking
+  guard conditions
+- **Redundant computation** — values computed multiple times when they could
+  be cached or hoisted
+- **Blocking operations** — synchronous file I/O (`fs.readFileSync` in
+  request handlers), CPU-intensive loops without yielding, serial `await`
+  where parallel is safe
+- **Memory leaks** — event listeners not cleaned up, growing Maps/Sets
+  without eviction, closures capturing large scopes, timers without
+  `clearInterval`
+- **Startup cost** — heavy top-level initialization, eager loading of
+  rarely-used modules
+
+### Anti-Patterns
+
+```typescript
+// Object allocation in hot loop
+for (const row of rows) {
+  const result = { ...defaults, ...row } // New object every iteration
+  results.push(result)
+}
+
+// Serial await where parallel is safe
+const a = await fetchA()
+const b = await fetchB() // b doesn't depend on a — should be parallel
+
+// Sync file I/O in request handler
+app.get('/config', (req, res) => {
+  const config = fs.readFileSync('config.json') // Blocks event loop
+  res.json(JSON.parse(config))
+})
+
+// Missing early return
+function processItem(item) {
+  const expensive = computeExpensiveThing(item) // Done before validation
+  if (!item.isValid) return null // Wasted computation
+  return expensive
+}
+
+// Memory leak — growing Map without eviction
+const cache = new Map()
+function getUser(id) {
+  if (!cache.has(id)) cache.set(id, fetchUser(id)) // Never evicts
+  return cache.get(id)
+}
+```
+
+### Optimization Patterns
+
+```typescript
+// Reuse object shape
+const result = Object.create(null)
+for (const row of rows) {
+  Object.assign(result, defaults, row)
+  results.push({ ...result })
+}
+
+// Parallel await
+const [a, b] = await Promise.all([fetchA(), fetchB()])
+
+// Async file I/O with caching
+let configCache
+app.get('/config', async (req, res) => {
+  configCache ??= await fs.readFile('config.json', 'utf8')
+  res.json(JSON.parse(configCache))
+})
+
+// Early return before expensive work
+function processItem(item) {
+  if (!item.isValid) return null
+  return computeExpensiveThing(item)
+}
+
+// LRU cache with eviction
+import { LRUCache } from 'lru-cache'
+const cache = new LRUCache({ max: 1000, ttl: 60_000 })
+```
+
+### Depth: Intensive
+
+- Trace hot paths end-to-end (request → handler → query → response)
+- Analyze Big-O complexity of key algorithms
+- Check for event loop blocking using heuristic detection (sync I/O,
+  heavy computation, long-running regex)
+- Estimate cold start time (first request after process start)
+
+---
+
+## Category 5 — Test Suite Performance
+
+### What to Measure
+
+- Total suite duration
+- Top 5 slowest test files (with durations)
+- Top 5 slowest individual tests (with durations)
+- Parallelization configuration (Vitest `pool`, `poolOptions`)
+- Test isolation overhead (setup/teardown time)
+
+### Anti-Patterns
+
+```typescript
+// Real I/O in unit tests
+test("fetches data", async () => {
+  const data = await fetch("https://api.example.com/data"); // Network I/O
+});
+
+// Heavy setup for simple assertions
+beforeEach(async () => {
+  await seedEntireDatabase(); // 500ms setup for a 10ms assertion
+});
+
+// Sequential tests that could parallelize
+// vitest.config.ts
+{ test: { pool: "forks", poolOptions: { forks: { singleFork: true } } } }
+```
+
+### Optimization Patterns
+
+```typescript
+// Mock external I/O
+vi.mock('node:fetch', () => ({ default: vi.fn() }))
+
+// Minimal setup — seed only what the test needs
+beforeEach(async () => {
+  await seedSingleTable('users', [testUser])
+})
+
+// Parallel execution
+// vitest.config.ts
+{
+  test: {
+    pool: 'threads'
+  }
+}
+```
+
+### Applicability
+
+If the project has no test suite, report this category as N/A.
+
+---
+
+## Category 6 — Database & I/O Performance
+
+### What to Look For
+
+- **N+1 queries** — database queries executed inside loops instead of
+  batching
+- **Unbounded queries** — `SELECT *` without `LIMIT`, missing pagination
+- **Missing indexes** — filtered/joined columns without indexes
+- **Connection management** — pool sizing, connection leak risks, missing
+  timeouts
+- **Caching** — repeated identical queries without caching, stale TTLs
+- **Serialization overhead** — excessive object transformation between
+  layers, unnecessary deep cloning
+
+### Anti-Patterns
+
+```typescript
+// N+1 query
+const users = await db.query('SELECT * FROM users')
+for (const user of users) {
+  const orders = await db.query(`SELECT * FROM orders WHERE user_id = ?`, [user.id])
+  // Each iteration is a new query
+}
+
+// Unbounded query
+const allRows = await db.query('SELECT * FROM large_table') // No LIMIT
+
+// Unnecessary deep clone
+const copy = JSON.parse(JSON.stringify(largeObject)) // Expensive!
+```
+
+### Optimization Patterns
+
+```typescript
+// Batch query
+const users = await db.query('SELECT * FROM users')
+const userIds = users.map((u) => u.id)
+const orders = await db.query(
+  `SELECT * FROM orders WHERE user_id IN (${userIds.map(() => '?').join(',')})`,
+  userIds
+)
+
+// Bounded query with pagination
+const rows = await db.query('SELECT * FROM large_table LIMIT ? OFFSET ?', [100, offset])
+
+// Structured clone (faster than JSON roundtrip)
+const copy = structuredClone(largeObject)
+```
+
+### Applicability
+
+If the project doesn't interact with databases or perform significant I/O,
+report this category as N/A. Still check for file system operations and
+network calls.
+
+---
+
+## Category 7 — Token & Context Efficiency
+
+### Applicability
+
+This category applies to **all project types** with graceful degradation:
+
+| Project Profile | Depth         | Rationale                              |
+| --------------- | ------------- | -------------------------------------- |
+| `mcp-server`    | Full          | Primary target — all checks apply      |
+| `web-app`       | Informational | Check API response verbosity           |
+| `cli-tool`      | Informational | Check output verbosity, help text size |
+| `library`       | Informational | Check type export complexity           |
+
+### What to Look For
+
+- **Verbose tool output** — tools returning full objects when summaries
+  suffice. Do `outputSchema` definitions constrain response size?
+- **Missing Code Mode** — servers with 15+ tools should offer sandboxed JS
+  execution for token-efficient multi-step operations (70–90% savings)
+- **Instruction bloat** — `instructions` field sending full documentation
+  instead of slim pointers to pull-based help resources
+- **Tool count** — 50+ tool servers without `--tool-filter` waste context
+  on unused tool definitions
+- **Redundant tools** — tools with significantly overlapping functionality
+- **Response padding** — success responses including unnecessary metadata,
+  empty arrays, or default values that could be omitted
+
+### Anti-Patterns
+
+```typescript
+// Tool returning everything — wastes tokens
+return {
+  success: true,
+  data: entireTable, // Could be thousands of rows
+  metadata: fullSchemaInfo, // Not requested
+  stats: computedStats, // Not requested
+}
+
+// Huge instructions field — pushed on every connection
+const INSTRUCTIONS = `Full 10-page documentation here...` // 5KB+
+
+// 170 tools, no filtering
+server.registerAllTools() // Client receives all 170 tool schemas
+```
+
+### Optimization Patterns
+
+```typescript
+// Constrained output — only what was asked for
+return {
+  success: true,
+  rows: data.slice(0, limit),
+  totalCount: data.length,
+  truncated: data.length > limit,
+}
+
+// Slim instructions + pull-based help resources
+const INSTRUCTIONS = 'Use sqlite://help for documentation.' // ~50 chars
+
+// Tool filtering
+// --tool-filter "core,json,codemode"  → 47 tools instead of 170
+```
+
+### MCP Server Checklist
+
+When the target is an MCP server, specifically verify:
+
+- [ ] `instructions` field is < 1KB (slim pointer, not full docs)
+- [ ] Help resources exist for pull-based documentation
+- [ ] `--tool-filter` is implemented for large tool counts
+- [ ] Code Mode (sandboxed JS) is available for multi-step operations
+- [ ] `outputSchema` constrains response shapes (no unbounded arrays)
+- [ ] Tools don't return redundant metadata by default
+- [ ] Progress notifications are used for long-running operations
+- [ ] Resources are used for large static data (schemas, configs)
+
+---
+
+## Category Cross-Reference
+
+Quick lookup for which categories matter most by project profile:
+
+| Project Profile | Primary Categories | Secondary |
+| --------------- | ------------------ | --------- |
+| MCP Server      | 4, 6, 7            | 1, 3      |
+| Web App         | 1, 2, 4            | 3, 5      |
+| CLI Tool        | 1, 3, 4            | 5         |
+| Library         | 1, 2, 3            | 4         |
+| Data-heavy      | 4, 6               | 1, 3, 5   |
+| Test-heavy      | 5, 4               | 1         |

package/skills/adversarial-performance/references/copilot-performance-prompts.md

@@ -0,0 +1,44 @@
+# Copilot Performance Prompts
+
+Reference for Phase 4 of the adversarial performance protocol — the
+independent external validation pass using the GitHub Copilot CLI.
+
+## Prerequisites
+
+1. **GitHub CLI installed**: `gh --version` (v2.x+)
+2. **Authenticated**: `gh auth status` passing
+3. **Copilot available**: `gh copilot --version` — the `copilot` subcommand is built into modern `gh` CLI (no separate extension needed)
+
+If Copilot CLI is not available, skip Phase 4 gracefully.
+
+## Prompt Templates
+
+> **⚠️ CRITICAL — Non-Interactive Mode**: The `gh copilot` CLI must be run in
+> non-interactive mode using the `-p` (or `--prompt`) flag. Interactive mode
+> will hang indefinitely in an automated agent context. Use:
+>
+> ```
+> gh copilot -p "<prompt>" --allow-tool "shell(find,cat,head,grep)"
+> ```
+>
+> The `--allow-tool` flag grants Copilot read access to the repository files.
+
+- Expect 60–120 seconds per prompt. In environments with hard synchronous timeouts (like Antigravity's 10s `WaitMsBeforeAsync` limit), allow the command to naturally fall into the background. Use the `schedule` tool or wait for the system notification to retrieve the results. Do not skip execution due to timeout constraints.
+
+## Parsing Copilot Output
+
+1. **Extract findings** — parse tables or numbered lists
+2. **Map to categories** — classify against the 7 audit categories
+3. **Quantify impact** — if Copilot didn't estimate improvement, add
+   your own estimates based on the code context
+4. **Deduplicate** — compare against Phase 2 findings
+5. **Disposition** — apply Accept/Reject/Modify/Defer from Phase 3
+
+## Prompt Selection Guide
+
+| Audit Depth | Project Profile | Prompts to Use                             |
+| ----------- | --------------- | ------------------------------------------ |
+| Scan        | Any             | Full Repository only                       |
+| Standard    | Non-MCP         | Full Repository + Dependencies             |
+| Standard    | MCP Server      | Full Repository + Dependencies + MCP Token |
+| Intensive   | Any             | All 3 prompts                              |

package/skills/adversarial-performance/references/copilot-usage.md

@@ -0,0 +1,16 @@
+# GitHub Copilot External Validation
+
+> **⚠️ CRITICAL — Non-Interactive Mode**: The `gh copilot` CLI must be run in
+> non-interactive mode using the `-p` (or `--prompt`) flag. Interactive mode
+> will hang indefinitely in an automated agent context. Use:
+>
+> ```
+> gh copilot -p "Considering these standards from Phase 0 research: [insert findings]. <prompt>" --allow-tool "shell(find,cat,head,grep)"
+> ```
+>
+> The `--allow-tool` flag grants Copilot read access to the repository files.
+> Always `Set-Location` (or `cd`) to the target repository before invoking.
+>
+> **⚠️ TIMEOUT GUIDANCE**: Expect 60–120 seconds per prompt. In environments with hard synchronous timeouts, use the `-s` flag or allow the command to naturally fall into the background.
+
+> **⚠️ CRITICAL — No Fabrication**: You MUST actually execute `gh copilot` commands. Do NOT fabricate or predict what Copilot would say.