opencode-swarm-plugin 0.42.6 → 0.42.8

package/.changeset/swarm-insights-data-layer.md

@@ -0,0 +1,63 @@
+---
+"opencode-swarm-plugin": minor
+---
+
+## 🧠 Swarm Insights: Data-Driven Decomposition
+
+> "It should allow the learner both to reflect on the quality of found solutions so that more effective cognitive schemata can be induced (including discriminations and generalizations) or further elaborated."
+> 
+> — *Training Complex Cognitive Skills: A Four-Component Instructional Design Model for Technical Training*
+
+**What changed:**
+
+New data layer (`swarm-insights.ts`) aggregates learnings from swarm coordination events to inform future decompositions. Coordinators and workers now get concise, context-efficient summaries injected into their prompts.
+
+**Key exports:**
+
+- `getStrategyInsights(swarmMail, task)` - Strategy success rates and recommendations
+  - Queries `subtask_outcome` events, calculates win/loss ratios
+  - Returns: `{ strategy, successRate, totalAttempts, recommendation }`
+  - Powers coordinator strategy selection with empirical data
+
+- `getFileInsights(swarmMail, files)` - File-specific gotchas from past failures
+  - Identifies files with high failure rates
+  - Returns: `{ file, failureCount, lastFailure, gotchas[] }`
+  - Workers see warnings about tricky files before touching them
+
+- `getPatternInsights(swarmMail)` - Common failure patterns and anti-patterns
+  - Detects recurring error types (type_error, timeout, conflict, test_failure)
+  - Returns: `{ pattern, frequency, recommendation }`
+  - Surfaces systemic issues for proactive prevention
+
+- `formatInsightsForPrompt(bundle, options)` - Context-aware formatting
+  - Token budget enforcement (default 500 tokens, ~2000 chars)
+  - Prioritizes top 3 strategies, 5 files, 3 patterns
+  - Clean markdown output for prompt injection
+
+- `getCachedInsights(swarmMail, cacheKey, computeFn)` - 5-minute TTL caching
+  - Prevents redundant queries during active swarms
+  - Transparent cache miss fallback
+
+**Why it matters:**
+
+Before this, coordinators decomposed tasks blind to past failures. "Split by file type" might have failed 8 times, but the coordinator would try it again. Workers would touch `auth/tokens.ts` without knowing it caused 3 prior failures.
+
+Now:
+- **Better decomposition**: Coordinator prompts show strategy success rates (e.g., "file-based: 85% success, feature-based: 40% - avoid")
+- **Fewer repeated mistakes**: Workers see file-specific warnings before editing
+- **Compounding learning**: Each swarm completion feeds the insights engine, improving future decompositions
+- **Context-efficient**: Hard token caps prevent insights from dominating prompt budgets
+
+The swarm now learns from its mistakes, not just records them.
+
+**Data sources:**
+- Event store: `subtask_outcome`, `eval_finalized` events
+- Semantic memory: File-specific learnings (TODO: full integration)
+- Anti-pattern registry: Detection and inversion rules
+
+**Integration points:**
+- Coordinator prompts: Inject strategy insights during decomposition
+- Worker prompts: Inject file insights when subtasks are spawned
+- Learning layer: Confidence decay, pattern maturity, implicit feedback scoring
+
+This is the foundation for adaptive swarm intelligence - decomposition that gets smarter with every task completed.

package/.hive/issues.jsonl

@@ -111,3 +111,14 @@
 {"id":"opencode-swarm-plugin--ys7z8-mjm7elm2poh","title":"Create swarm-insights data layer","description":"Create a data layer that aggregates insights for prompt injection.\n\nFile: src/swarm-insights.ts (NEW)\n\nImplementation:\n1. getStrategyInsights(task) - success rates by strategy for similar tasks\n2. getFileInsights(files) - past issues, gotchas for specific files\n3. getPatternInsights() - common failure patterns, anti-patterns\n4. Cache results to avoid repeated queries\n5. Add tests in swarm-insights.test.ts","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-26T01:39:28.874Z","updated_at":"2025-12-26T01:57:17.504Z","closed_at":"2025-12-26T01:57:17.504Z","dependencies":[],"labels":[],"comments":[]}
 {"id":"opencode-swarm-plugin--ys7z8-mjm7eo34l57","title":"Inject insights into coordinator prompts","description":"Inject aggregated insights into coordinator prompts before decomposition.\n\nFile: src/swarm-prompts.ts\n\nImplementation:\n1. Call getStrategyInsights() in swarm_plan_prompt\n2. Add \"## Historical Insights\" section to prompt\n3. Include: strategy success rates, common pitfalls, recommendations\n4. Keep injection concise (<500 tokens)\n5. Add tests verifying injection","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-26T01:39:32.080Z","updated_at":"2025-12-26T02:03:27.468Z","closed_at":"2025-12-26T02:03:27.468Z","dependencies":[],"labels":[],"comments":[]}
 {"id":"opencode-swarm-plugin--ys7z8-mjm7eq8o1oq","title":"Inject insights into worker prompts","description":"Inject file-specific insights into worker prompts.\n\nFile: src/swarm-prompts.ts\n\nImplementation:\n1. Call getFileInsights(files) in swarm_spawn_subtask\n2. Add \"## File-Specific Gotchas\" section to worker prompt\n3. Include: past bugs in these files, known issues, patterns\n4. Query semantic-memory for relevant learnings\n5. Keep injection concise (<300 tokens per file)\n6. Add tests verifying injection","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-26T01:39:34.872Z","updated_at":"2025-12-26T02:08:10.131Z","closed_at":"2025-12-26T02:08:10.131Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmadcpu98d","title":"Document swarm-insights layer + CLI help + plugin template","description":"Full documentation for the new swarm-insights data layer:\n- README.md: Add swarm-insights architecture section\n- CLI help: Update swarm stats/history descriptions\n- Plugin template: Add swarm-insights tool descriptions\n- AGENTS.md: Document insights tools for agents\n- JSDoc: Ensure swarm-insights.ts has complete docs\n- Changeset: Document the new feature for release","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-26T03:02:29.538Z","updated_at":"2025-12-26T03:02:29.538Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmadcq6aib","title":"Update CLI help text for stats/history commands","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-26T03:02:29.550Z","updated_at":"2025-12-26T03:02:29.550Z","parent_id":"opencode-swarm-plugin--ys7z8-mjmadcpu98d","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmadcq85et","title":"Add swarm-insights tools to plugin-wrapper-template.ts","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-26T03:02:29.552Z","updated_at":"2025-12-26T03:02:29.552Z","parent_id":"opencode-swarm-plugin--ys7z8-mjmadcpu98d","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmadcqag0y","title":"Ensure swarm-insights.ts has complete JSDoc","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-26T03:02:29.554Z","updated_at":"2025-12-26T03:02:29.554Z","parent_id":"opencode-swarm-plugin--ys7z8-mjmadcpu98d","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmadcqcklk","title":"Create changeset for swarm-insights feature","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-26T03:02:29.556Z","updated_at":"2025-12-26T03:02:29.556Z","parent_id":"opencode-swarm-plugin--ys7z8-mjmadcpu98d","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmadcq2s4l","title":"Update README.md with swarm-insights architecture","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-26T03:02:29.546Z","updated_at":"2025-12-26T03:12:28.691Z","closed_at":"2025-12-26T03:12:28.691Z","parent_id":"opencode-swarm-plugin--ys7z8-mjmadcpu98d","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmavq7f31x","title":"ADR-010: CASS Inhousing Feasibility Study","description":"Deep dive into CASS (coding_agent_session_search) to determine if we should bring cross-agent session search in-house, eliminating the Python dependency.\n\n**Deliverables:**\n1. Full architecture analysis of CASS\n2. Gap analysis vs our semantic-memory\n3. Agent session format survey\n4. ADR-010 with TDD implementation plan, docs, and observability\n\n**Success Criteria:**\n- Clear recommendation: inhouse vs keep vs hybrid\n- If inhouse: schema design, TDD test plan, effort estimate\n- Observability hooks designed (aligns with ADR-005)\n- Migration path documented","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-26T03:16:46.827Z","updated_at":"2025-12-26T03:29:01.651Z","closed_at":"2025-12-26T03:29:01.651Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmavq7m7od","title":"T1: CASS Architecture Deep Dive","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-26T03:16:46.834Z","updated_at":"2025-12-26T03:22:05.154Z","closed_at":"2025-12-26T03:22:05.154Z","parent_id":"opencode-swarm-plugin--ys7z8-mjmavq7f31x","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmavq7pz17","title":"T2: Semantic Memory Gap Analysis","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-26T03:16:46.837Z","updated_at":"2025-12-26T03:22:06.745Z","closed_at":"2025-12-26T03:22:06.745Z","parent_id":"opencode-swarm-plugin--ys7z8-mjmavq7f31x","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmavq7rt9z","title":"T3: Agent Session Format Survey","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-26T03:16:46.839Z","updated_at":"2025-12-26T03:22:08.486Z","closed_at":"2025-12-26T03:22:08.486Z","parent_id":"opencode-swarm-plugin--ys7z8-mjmavq7f31x","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-swarm-plugin--ys7z8-mjmavq7va7b","title":"T4: Write ADR-010 with TDD Plan","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-26T03:16:46.843Z","updated_at":"2025-12-26T03:28:59.753Z","closed_at":"2025-12-26T03:28:59.753Z","parent_id":"opencode-swarm-plugin--ys7z8-mjmavq7f31x","dependencies":[],"labels":[],"comments":[]}

package/.turbo/turbo-build.log

@@ -1,9 +1,9 @@
 $ bun build ./src/index.ts --outdir ./dist --target node --external @electric-sql/pglite --external swarm-mail --external vitest --external @vitest/ui --external lightningcss && bun build ./src/plugin.ts --outfile ./dist/plugin.js --target node --external @electric-sql/pglite --external swarm-mail --external vitest --external @vitest/ui --external lightningcss && tsc
-Bundled 1349 modules in 198ms
+Bundled 1349 modules in 204ms
 
   index.js  4.34 MB  (entry point)
 
-Bundled 1350 modules in 193ms
+Bundled 1350 modules in 235ms
 
   plugin.js  4.31 MB  (entry point)
 

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # opencode-swarm-plugin
 
+## 0.42.8
+
+### Patch Changes
+
+- [`a797bea`](https://github.com/joelhooks/swarm-tools/commit/a797bea871e5d698ebb38b41f47ff07faa7c108b) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🔗 Tweets Now Link to the Right PR
+
+  Release tweets were linking to the wrong PR. The old logic grabbed "most recent merged PR that isn't a version bump" - but with the new `release:` prefix on version PRs, it was picking up stale PRs.
+
+  **Fixed:** Now uses `github.sha` to find the exact PR that triggered the workflow. No more guessing.
+
+  ```
+  BEFORE: gh pr list --limit 5 --jq 'filter...'  → wrong PR
+  AFTER:  gh pr list --search "${{ github.sha }}" → triggering PR
+  ```
+
+## 0.42.7
+
+### Patch Changes
+
+- [`7a6a4a3`](https://github.com/joelhooks/swarm-tools/commit/7a6a4a37c4ea753de359dac5062d11186ee98ccd) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 📐 Swarm Insights Gets Its Blueprint
+
+  > _"The major documentation tool for information architecture... diagrams."_
+  > — Jesse James Garrett, The Elements of User Experience
+
+  The README now shows you how the swarm learns, not just that it does.
+
+  **Added:**
+
+  - ASCII diagram of the swarm learning loop (task → decompose → execute → complete → insights → repeat)
+  - Data flow architecture showing Event Store → Insights Aggregation → Agents
+  - Full API reference with TypeScript examples for coordinators and workers
+  - Token budget table (500 for coordinators, 300 for workers)
+  - Recommendation threshold table (≥80% = good, <40% = AVOID)
+  - Data sources table (Event Store, Semantic Memory, Anti-Pattern Registry)
+
+  **Why it matters:**
+  Diagrams > prose for architecture. Now you can see the feedback loop at a glance instead of reading paragraphs. The API examples are copy-pasteable.
+
+  ```
+  ┌──────────┐    ┌──────────┐    ┌──────────┐
+  │  TASK    │───▶│ INSIGHTS │───▶│  BETTER  │
+  │          │    │  LAYER   │    │  SWARMS  │
+  └──────────┘    └──────────┘    └──────────┘
+  ```
+
+- [`0ad79d5`](https://github.com/joelhooks/swarm-tools/commit/0ad79d57cd119517a8e04d0e74b4909f20a7f0be) Thanks [@joelhooks](https://github.com/joelhooks)! - ## Release Tweets Link to Source, PR Titles Get Smart
+
+  - Tweets now include link to the feature PR (or commit if pushed direct to main)
+  - Version bump PRs get AI-generated titles from changeset content via Opus
+  - No more "chore: update versions" - titles describe what actually shipped
+
 ## 0.42.6
 
 ### Patch Changes

package/README.md

@@ -49,6 +49,152 @@ Done. You're swarming.
 
 ---
 
+## How Swarms Get Smarter Over Time
+
+Swarms learn from outcomes. Every completed subtask records what worked and what failed - then injects that wisdom into future prompts.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        SWARM LEARNING LOOP                              │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐         │
+│   │  TASK    │───▶│ DECOMPOSE│───▶│  EXECUTE │───▶│ COMPLETE │         │
+│   └──────────┘    └──────────┘    └──────────┘    └──────────┘         │
+│        ▲               │               │               │                │
+│        │               ▼               ▼               ▼                │
+│        │         ┌─────────────────────────────────────────┐            │
+│        │         │           EVENT STORE                   │            │
+│        │         │  subtask_outcome, eval_finalized, ...   │            │
+│        │         └─────────────────────────────────────────┘            │
+│        │                           │                                    │
+│        │                           ▼                                    │
+│        │         ┌─────────────────────────────────────────┐            │
+│        │         │         INSIGHTS LAYER                  │            │
+│        │         │  Strategy | File | Pattern insights     │            │
+│        │         └─────────────────────────────────────────┘            │
+│        │                           │                                    │
+│        └───────────────────────────┘                                    │
+│                  (injected into next decomposition)                     │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### The Insights Layer
+
+**swarm-insights** (`src/swarm-insights.ts`) is the data aggregation layer that queries historical outcomes and semantic memory to provide context-efficient summaries for coordinator and worker agents.
+
+**Three insight types:**
+
+| Type | What It Tracks | Used By |
+|------|----------------|---------|
+| **StrategyInsight** | Success rates by decomposition strategy (file-based, feature-based, risk-based) | Coordinators |
+| **FileInsight** | File-specific failure patterns and gotchas from past subtasks | Workers |
+| **PatternInsight** | Common failure patterns across all subtasks (type errors, timeouts, conflicts) | Coordinators |
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         DATA FLOW                                       │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐   │
+│  │   Event Store   │     │ Semantic Memory │     │  Anti-Patterns  │   │
+│  │  (libSQL)       │     │  (Ollama/FTS)   │     │  (Registry)     │   │
+│  └────────┬────────┘     └────────┬────────┘     └────────┬────────┘   │
+│           │                       │                       │            │
+│           ▼                       ▼                       ▼            │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                    INSIGHTS AGGREGATION                         │   │
+│  │                                                                 │   │
+│  │  getStrategyInsights()  getFileInsights()  getPatternInsights() │   │
+│  │         │                      │                    │           │   │
+│  │         └──────────────────────┼────────────────────┘           │   │
+│  │                                ▼                                │   │
+│  │                    formatInsightsForPrompt()                    │   │
+│  │                    (token-budgeted output)                      │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                   │                                    │
+│           ┌───────────────────────┼───────────────────────┐            │
+│           ▼                       ▼                       ▼            │
+│  ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐   │
+│  │   Coordinator   │     │     Worker      │     │     Worker      │   │
+│  │   (strategy +   │     │  (file-specific │     │  (file-specific │   │
+│  │    patterns)    │     │    gotchas)     │     │    gotchas)     │   │
+│  └─────────────────┘     └─────────────────┘     └─────────────────┘   │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### API Reference
+
+**For coordinators** (strategy selection):
+```typescript
+import { getStrategyInsights, getPatternInsights, formatInsightsForPrompt } from "opencode-swarm-plugin";
+
+const strategies = await getStrategyInsights(swarmMail, task);
+// Returns: [{ strategy: "file-based", successRate: 85.5, totalAttempts: 12, recommendation: "..." }]
+
+const patterns = await getPatternInsights(swarmMail);
+// Returns: [{ pattern: "type_error", frequency: 5, recommendation: "Add type annotations" }]
+
+const summary = formatInsightsForPrompt({ strategies, patterns }, { maxTokens: 500 });
+// Injected into decomposition prompt
+```
+
+**For workers** (file-specific context):
+```typescript
+import { getFileInsights, formatInsightsForPrompt } from "opencode-swarm-plugin";
+
+const fileInsights = await getFileInsights(swarmMail, ["src/auth.ts", "src/db.ts"]);
+// Returns: [{ file: "src/auth.ts", failureCount: 3, lastFailure: "2025-12-20T...", gotchas: [...] }]
+
+const summary = formatInsightsForPrompt({ files: fileInsights }, { maxTokens: 300 });
+// Injected into worker prompt
+```
+
+**Caching** (5-minute TTL):
+```typescript
+import { getCachedInsights, clearInsightsCache } from "opencode-swarm-plugin";
+
+const insights = await getCachedInsights(swarmMail, "strategies:auth-task", async () => ({
+  strategies: await getStrategyInsights(swarmMail, "add auth"),
+}));
+
+clearInsightsCache(); // Force fresh computation
+```
+
+### Token Budgets
+
+| Agent Type | Max Tokens | What's Included |
+|------------|------------|-----------------|
+| Coordinator | 500 | Top 3 strategies + top 3 patterns |
+| Worker | 300 | Top 5 files with gotchas |
+
+### Recommendation Thresholds
+
+Strategy success rates map to recommendations:
+
+| Success Rate | Recommendation |
+|--------------|----------------|
+| ≥80% | "performing well" |
+| 60-79% | "moderate - monitor for issues" |
+| 40-59% | "low success - consider alternatives" |
+| <40% | "AVOID - high failure rate" |
+
+### Data Sources
+
+| Source | What It Provides | Query Pattern |
+|--------|------------------|---------------|
+| Event Store | `subtask_outcome` events with strategy, success, files_touched, error_type | SQL aggregation |
+| Semantic Memory | File-specific learnings from past debugging | Semantic search (TODO) |
+| Anti-Pattern Registry | Patterns with >60% failure rate | Direct lookup |
+
+**See [swarmtools.ai/docs/insights](https://swarmtools.ai/docs) for full details.**
+
+---
+
 ## Optional But Recommended
 
 ### Semantic Memory (for pattern learning)
@@ -209,6 +355,7 @@ src/
 ├── swarm-mail.ts          # Agent coordination tools
 ├── swarm-orchestrate.ts   # Coordinator logic (spawns workers)
 ├── swarm-decompose.ts     # Task decomposition strategies
+├── swarm-insights.ts      # Historical insights aggregation (strategy/file/pattern)
 ├── swarm-review.ts        # Review gate for completed work
 ├── skills.ts              # Knowledge injection system
 ├── learning.ts            # Pattern maturity, outcomes

package/bin/swarm.ts

@@ -2522,8 +2522,8 @@ ${cyan("Commands:")}
     --port <n>          Port to listen on (default: 3001)
   swarm cells     List or get cells from database (replaces 'swarm tool hive_query')
   swarm log       View swarm logs with filtering
-  swarm stats     Show swarm health metrics and success rates
-  swarm history   Show recent swarm activity timeline
+  swarm stats     Show swarm health metrics powered by swarm-insights (strategy success rates, patterns)
+  swarm history   Show recent swarm activity timeline with insights data
   swarm eval      Eval-driven development commands
   swarm update    Update to latest version
   swarm version   Show version and banner
@@ -2559,10 +2559,10 @@ ${cyan("Log Viewing:")}
   swarm log sessions --json            Raw JSON output for jq
 
 ${cyan("Stats & History:")}
-  swarm stats                          Show swarm health metrics (last 7 days)
+  swarm stats                          Show swarm health metrics powered by swarm-insights (last 7 days)
   swarm stats --since 24h              Show stats for custom time period
   swarm stats --json                   Output as JSON for scripting
-  swarm history                        Show recent swarms (last 10)
+  swarm history                        Show recent swarm activity timeline with insights data (last 10)
   swarm history --limit 20             Show more swarms
   swarm history --status success       Filter by success/failed/in_progress
   swarm history --strategy file-based  Filter by decomposition strategy

package/dist/swarm-insights.d.ts

@@ -40,6 +40,19 @@ export interface FormatOptions {
  *
  * Queries the event store for subtask_outcome events and calculates
  * success rates by strategy. Returns recommendations based on historical data.
+ *
+ * @param swarmMail - SwarmMail adapter for database access
+ * @param _task - Task description (currently unused, reserved for future filtering)
+ * @returns Promise resolving to array of strategy insights with success rates and recommendations
+ *
+ * @example
+ * ```typescript
+ * const insights = await getStrategyInsights(swarmMail, "Add authentication");
+ * // Returns: [
+ * //   { strategy: "file-based", successRate: 85.5, totalAttempts: 12, recommendation: "..." },
+ * //   { strategy: "feature-based", successRate: 65.0, totalAttempts: 8, recommendation: "..." }
+ * // ]
+ * ```
  */
 export declare function getStrategyInsights(swarmMail: SwarmMailAdapter, _task: string): Promise<StrategyInsight[]>;
 /**
@@ -47,6 +60,18 @@ export declare function getStrategyInsights(swarmMail: SwarmMailAdapter, _task:
  *
  * Queries the event store for failures involving these files and
  * semantic memory for file-specific gotchas.
+ *
+ * @param swarmMail - SwarmMail adapter for database access
+ * @param files - Array of file paths to analyze
+ * @returns Promise resolving to array of file-specific insights including failure counts and gotchas
+ *
+ * @example
+ * ```typescript
+ * const insights = await getFileInsights(swarmMail, ["src/auth.ts", "src/db.ts"]);
+ * // Returns: [
+ * //   { file: "src/auth.ts", failureCount: 3, lastFailure: "2025-12-20T10:30:00Z", gotchas: [...] }
+ * // ]
+ * ```
  */
 export declare function getFileInsights(swarmMail: SwarmMailAdapter, files: string[]): Promise<FileInsight[]>;
 /**
@@ -54,6 +79,18 @@ export declare function getFileInsights(swarmMail: SwarmMailAdapter, files: stri
  *
  * Analyzes event store for recurring failure patterns and
  * queries the anti-pattern registry.
+ *
+ * @param swarmMail - SwarmMail adapter for database access
+ * @returns Promise resolving to array of pattern insights with frequency and recommendations
+ *
+ * @example
+ * ```typescript
+ * const patterns = await getPatternInsights(swarmMail);
+ * // Returns: [
+ * //   { pattern: "type_error", frequency: 5, recommendation: "Add explicit type annotations and null checks" },
+ * //   { pattern: "timeout", frequency: 3, recommendation: "Consider breaking into smaller tasks" }
+ * // ]
+ * ```
  */
 export declare function getPatternInsights(swarmMail: SwarmMailAdapter): Promise<PatternInsight[]>;
 /**
@@ -62,17 +99,57 @@ export declare function getPatternInsights(swarmMail: SwarmMailAdapter): Promise
  * Produces a concise, context-efficient summary suitable for
  * inclusion in coordinator or worker prompts.
  *
- * @param bundle - Insights to format
- * @param options - Formatting options (maxTokens)
- * @returns Formatted string for prompt injection
+ * @param bundle - Insights bundle containing strategies, files, and patterns
+ * @param options - Formatting options (maxTokens defaults to 500)
+ * @returns Formatted markdown string for prompt injection, or empty string if no insights
+ *
+ * @example
+ * ```typescript
+ * const bundle = {
+ *   strategies: [{ strategy: "file-based", successRate: 85.5, totalAttempts: 12, recommendation: "..." }],
+ *   files: [{ file: "src/auth.ts", failureCount: 2, lastFailure: null, gotchas: [] }],
+ *   patterns: [{ pattern: "type_error", frequency: 3, recommendation: "Add type checks" }]
+ * };
+ * const formatted = formatInsightsForPrompt(bundle, { maxTokens: 300 });
+ * // Returns formatted markdown with top 3 strategies, top 5 files, top 3 patterns
+ * ```
  */
 export declare function formatInsightsForPrompt(bundle: InsightsBundle, options?: FormatOptions): string;
 /**
  * Get cached insights or compute fresh ones.
+ *
+ * Simple in-memory cache with 5-minute TTL to avoid redundant database queries.
+ *
+ * @param _swarmMail - SwarmMail adapter (currently unused, reserved for future cache invalidation)
+ * @param cacheKey - Unique key for caching (e.g., "strategies:task-name" or "files:src/auth.ts")
+ * @param computeFn - Function to compute fresh insights if cache miss
+ * @returns Promise resolving to cached or freshly computed insights bundle
+ *
+ * @example
+ * ```typescript
+ * const insights = await getCachedInsights(
+ *   swarmMail,
+ *   "strategies:add-auth",
+ *   async () => ({
+ *     strategies: await getStrategyInsights(swarmMail, "add auth"),
+ *   })
+ * );
+ * // First call: computes and caches. Subsequent calls within 5min: returns cached.
+ * ```
  */
 export declare function getCachedInsights(_swarmMail: SwarmMailAdapter, cacheKey: string, computeFn: () => Promise<InsightsBundle>): Promise<InsightsBundle>;
 /**
  * Clear the insights cache.
+ *
+ * Useful for testing or forcing fresh insights computation.
+ *
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * clearInsightsCache();
+ * // All cached insights invalidated, next getCachedInsights() will recompute
+ * ```
  */
 export declare function clearInsightsCache(): void;
 //# sourceMappingURL=swarm-insights.d.ts.map

package/dist/swarm-insights.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm-insights.d.ts","sourceRoot":"","sources":["../src/swarm-insights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMnD,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,EAAE,CAAC,CA+B5B;AAsBD;;;;;GAKG;AACH,wBAAsB,eAAe,CACpC,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,WAAW,EAAE,CAAC,CAsCxB;AAsBD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACvC,SAAS,EAAE,gBAAgB,GACzB,OAAO,CAAC,cAAc,EAAE,CAAC,CAkC3B;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,aAAkB,GACzB,MAAM,CA8CR;AAaD;;GAEG;AACH,wBAAsB,iBAAiB,CACtC,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,GACtC,OAAO,CAAC,cAAc,CAAC,CAazB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"swarm-insights.d.ts","sourceRoot":"","sources":["../src/swarm-insights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMnD,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,EAAE,CAAC,CA+B5B;AAmCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,eAAe,CACpC,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,WAAW,EAAE,CAAC,CAsCxB;AAiCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CACvC,SAAS,EAAE,gBAAgB,GACzB,OAAO,CAAC,cAAc,EAAE,CAAC,CAkC3B;AAiCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,aAAkB,GACzB,MAAM,CA8CR;AAaD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,iBAAiB,CACtC,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,GACtC,OAAO,CAAC,cAAc,CAAC,CAazB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/examples/plugin-wrapper-template.ts

@@ -1002,6 +1002,32 @@ const skills_execute = tool({
   execute: (args, ctx) => execTool("skills_execute", args, ctx),
 });
 
+// =============================================================================
+// Swarm Insights Tools
+// =============================================================================
+
+const swarm_get_strategy_insights = tool({
+  description: "Get strategy success rates for decomposition planning. Use this when planning task decomposition to see which strategies (file-based, feature-based, risk-based) have historically succeeded or failed. Returns success rates and recommendations based on past swarm outcomes.",
+  args: {
+    task: tool.schema.string().describe("Task description to analyze for strategy recommendation"),
+  },
+  execute: (args, ctx) => execTool("swarm_get_strategy_insights", args, ctx),
+});
+
+const swarm_get_file_insights = tool({
+  description: "Get file-specific gotchas for worker context. Use this when assigning files to workers to warn them about historical failure patterns. Queries past outcomes and semantic memory for file-specific learnings (edge cases, common bugs, performance traps).",
+  args: {
+    files: tool.schema.array(tool.schema.string()).describe("File paths to get insights for"),
+  },
+  execute: (args, ctx) => execTool("swarm_get_file_insights", args, ctx),
+});
+
+const swarm_get_pattern_insights = tool({
+  description: "Get common failure patterns across swarms. Use this during planning or when debugging stuck swarms to see recurring anti-patterns (type errors, timeouts, conflicts, test failures). Returns top 5 most frequent failure patterns with recommendations.",
+  args: {},
+  execute: (args, ctx) => execTool("swarm_get_pattern_insights", args, ctx),
+});
+
 // =============================================================================
 // Plugin Export
 // =============================================================================
@@ -2034,6 +2060,10 @@ const SwarmPlugin: Plugin = async (
       skills_init,
       skills_add_script,
       skills_execute,
+      // Swarm Insights
+      swarm_get_strategy_insights,
+      swarm_get_file_insights,
+      swarm_get_pattern_insights,
     },
 
     // Swarm-aware compaction hook with LLM-powered continuation prompts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.42.6",
+  "version": "0.42.8",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",

package/src/swarm-insights.ts

@@ -55,6 +55,19 @@ export interface FormatOptions {
  *
  * Queries the event store for subtask_outcome events and calculates
  * success rates by strategy. Returns recommendations based on historical data.
+ *
+ * @param swarmMail - SwarmMail adapter for database access
+ * @param _task - Task description (currently unused, reserved for future filtering)
+ * @returns Promise resolving to array of strategy insights with success rates and recommendations
+ *
+ * @example
+ * ```typescript
+ * const insights = await getStrategyInsights(swarmMail, "Add authentication");
+ * // Returns: [
+ * //   { strategy: "file-based", successRate: 85.5, totalAttempts: 12, recommendation: "..." },
+ * //   { strategy: "feature-based", successRate: 65.0, totalAttempts: 8, recommendation: "..." }
+ * // ]
+ * ```
  */
 export async function getStrategyInsights(
 	swarmMail: SwarmMailAdapter,
@@ -94,6 +107,19 @@ export async function getStrategyInsights(
 
 /**
  * Generate recommendation based on strategy and success rate.
+ *
+ * @param strategy - Strategy name (e.g., "file-based", "feature-based")
+ * @param successRate - Success rate percentage (0-100)
+ * @returns Recommendation string based on performance thresholds
+ *
+ * @example
+ * ```typescript
+ * getStrategyRecommendation("file-based", 85);
+ * // Returns: "file-based is performing well (85% success)"
+ *
+ * getStrategyRecommendation("feature-based", 35);
+ * // Returns: "AVOID feature-based - high failure rate (35%)"
+ * ```
  */
 function getStrategyRecommendation(strategy: string, successRate: number): string {
 	if (successRate >= 80) {
@@ -117,6 +143,18 @@ function getStrategyRecommendation(strategy: string, successRate: number): strin
  *
  * Queries the event store for failures involving these files and
  * semantic memory for file-specific gotchas.
+ *
+ * @param swarmMail - SwarmMail adapter for database access
+ * @param files - Array of file paths to analyze
+ * @returns Promise resolving to array of file-specific insights including failure counts and gotchas
+ *
+ * @example
+ * ```typescript
+ * const insights = await getFileInsights(swarmMail, ["src/auth.ts", "src/db.ts"]);
+ * // Returns: [
+ * //   { file: "src/auth.ts", failureCount: 3, lastFailure: "2025-12-20T10:30:00Z", gotchas: [...] }
+ * // ]
+ * ```
  */
 export async function getFileInsights(
 	swarmMail: SwarmMailAdapter,
@@ -166,6 +204,17 @@ export async function getFileInsights(
  *
  * In a full implementation, this would query the semantic memory
  * for file-specific learnings. For now, returns empty array.
+ *
+ * @param _swarmMail - SwarmMail adapter (currently unused)
+ * @param _file - File path to query learnings for
+ * @returns Promise resolving to array of gotcha strings (currently empty, TODO)
+ *
+ * @example
+ * ```typescript
+ * const gotchas = await getFileGotchas(swarmMail, "src/auth.ts");
+ * // TODO: Will return semantic memory learnings like:
+ * // ["OAuth tokens need 5min buffer", "Always validate refresh token expiry"]
+ * ```
  */
 async function getFileGotchas(
 	_swarmMail: SwarmMailAdapter,
@@ -186,6 +235,18 @@ async function getFileGotchas(
  *
  * Analyzes event store for recurring failure patterns and
  * queries the anti-pattern registry.
+ *
+ * @param swarmMail - SwarmMail adapter for database access
+ * @returns Promise resolving to array of pattern insights with frequency and recommendations
+ *
+ * @example
+ * ```typescript
+ * const patterns = await getPatternInsights(swarmMail);
+ * // Returns: [
+ * //   { pattern: "type_error", frequency: 5, recommendation: "Add explicit type annotations and null checks" },
+ * //   { pattern: "timeout", frequency: 3, recommendation: "Consider breaking into smaller tasks" }
+ * // ]
+ * ```
  */
 export async function getPatternInsights(
 	swarmMail: SwarmMailAdapter,
@@ -227,6 +288,18 @@ export async function getPatternInsights(
 
 /**
  * Generate recommendation for a failure pattern.
+ *
+ * @param errorType - Type of error pattern (e.g., "type_error", "timeout", "conflict")
+ * @returns Recommendation string for addressing the pattern
+ *
+ * @example
+ * ```typescript
+ * getPatternRecommendation("type_error");
+ * // Returns: "Add explicit type annotations and null checks"
+ *
+ * getPatternRecommendation("unknown_error");
+ * // Returns: "Address unknown_error issues"
+ * ```
  */
 function getPatternRecommendation(errorType: string): string {
 	// Common patterns and their recommendations
@@ -250,9 +323,20 @@ function getPatternRecommendation(errorType: string): string {
  * Produces a concise, context-efficient summary suitable for
  * inclusion in coordinator or worker prompts.
  *
- * @param bundle - Insights to format
- * @param options - Formatting options (maxTokens)
- * @returns Formatted string for prompt injection
+ * @param bundle - Insights bundle containing strategies, files, and patterns
+ * @param options - Formatting options (maxTokens defaults to 500)
+ * @returns Formatted markdown string for prompt injection, or empty string if no insights
+ *
+ * @example
+ * ```typescript
+ * const bundle = {
+ *   strategies: [{ strategy: "file-based", successRate: 85.5, totalAttempts: 12, recommendation: "..." }],
+ *   files: [{ file: "src/auth.ts", failureCount: 2, lastFailure: null, gotchas: [] }],
+ *   patterns: [{ pattern: "type_error", frequency: 3, recommendation: "Add type checks" }]
+ * };
+ * const formatted = formatInsightsForPrompt(bundle, { maxTokens: 300 });
+ * // Returns formatted markdown with top 3 strategies, top 5 files, top 3 patterns
+ * ```
  */
 export function formatInsightsForPrompt(
 	bundle: InsightsBundle,
@@ -318,6 +402,25 @@ const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 
 /**
  * Get cached insights or compute fresh ones.
+ *
+ * Simple in-memory cache with 5-minute TTL to avoid redundant database queries.
+ *
+ * @param _swarmMail - SwarmMail adapter (currently unused, reserved for future cache invalidation)
+ * @param cacheKey - Unique key for caching (e.g., "strategies:task-name" or "files:src/auth.ts")
+ * @param computeFn - Function to compute fresh insights if cache miss
+ * @returns Promise resolving to cached or freshly computed insights bundle
+ *
+ * @example
+ * ```typescript
+ * const insights = await getCachedInsights(
+ *   swarmMail,
+ *   "strategies:add-auth",
+ *   async () => ({
+ *     strategies: await getStrategyInsights(swarmMail, "add auth"),
+ *   })
+ * );
+ * // First call: computes and caches. Subsequent calls within 5min: returns cached.
+ * ```
  */
 export async function getCachedInsights(
 	_swarmMail: SwarmMailAdapter,
@@ -340,6 +443,16 @@ export async function getCachedInsights(
 
 /**
  * Clear the insights cache.
+ *
+ * Useful for testing or forcing fresh insights computation.
+ *
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * clearInsightsCache();
+ * // All cached insights invalidated, next getCachedInsights() will recompute
+ * ```
  */
 export function clearInsightsCache(): void {
 	insightsCache.clear();