opencode-swarm-plugin 0.32.0 → 0.33.0

package/dist/swarm-prompts.d.ts

@@ -38,6 +38,15 @@ export declare const SUBTASK_PROMPT = "You are a swarm agent working on a subtas
  * Supports {error_context} placeholder for retry prompts.
  */
 export declare const SUBTASK_PROMPT_V2 = "You are a swarm agent working on: **{subtask_title}**\n\n## [IDENTITY]\nAgent: (assigned at spawn)\nCell: {bead_id}\nEpic: {epic_id}\n\n## [TASK]\n{subtask_description}\n\n## [FILES]\nReserved (exclusive):\n{file_list}\n\nOnly modify these files. Need others? Message the coordinator.\n\n## [CONTEXT]\n{shared_context}\n\n{compressed_context}\n\n{error_context}\n\n## [MANDATORY SURVIVAL CHECKLIST]\n\n**CRITICAL: Follow this checklist IN ORDER. Each step builds on the previous.**\n\n### Step 1: Initialize Coordination (REQUIRED - DO THIS FIRST)\n```\nswarmmail_init(project_path=\"{project_path}\", task_description=\"{bead_id}: {subtask_title}\")\n```\n\n**This registers you with the coordination system and enables:**\n- File reservation tracking\n- Inter-agent communication\n- Progress monitoring\n- Conflict detection\n\n**If you skip this step, your work will not be tracked and swarm_complete will fail.**\n\n### Step 2: \uD83E\uDDE0 Query Past Learnings (MANDATORY - BEFORE starting work)\n\n**\u26A0\uFE0F CRITICAL: ALWAYS query semantic memory BEFORE writing ANY code.**\n\n```\nsemantic-memory_find(query=\"<keywords from your task>\", limit=5, expand=true)\n```\n\n**Why this is MANDATORY:**\n- Past agents may have already solved your exact problem\n- Avoids repeating mistakes that wasted 30+ minutes before\n- Discovers project-specific patterns and gotchas\n- Finds known workarounds for tool/library quirks\n\n**Search Query Examples by Task Type:**\n\n- **Bug fix**: Use exact error message or \"<symptom> <component>\"\n- **New feature**: Search \"<domain concept> implementation pattern\"\n- **Refactor**: Query \"<pattern name> migration approach\"\n- **Integration**: Look for \"<library name> gotchas configuration\"\n- **Testing**: Find \"testing <component type> characterization tests\"\n- **Performance**: Search \"<technology> performance optimization\"\n\n**BEFORE you start coding:**\n1. Run semantic-memory_find with keywords from your task\n2. Read the results with expand=true for full content\n3. Check if any memory solves your problem or warns of pitfalls\n4. Adjust your approach based on past learnings\n\n**If you skip this step, you WILL waste time solving already-solved problems.**\n\n### Step 3: Load Relevant Skills (if available)\n```\nskills_list()  # See what skills exist\nskills_use(name=\"<relevant-skill>\", context=\"<your task>\")  # Load skill\n```\n\n**Common skill triggers:**\n- Writing tests? \u2192 `skills_use(name=\"testing-patterns\")`\n- Breaking dependencies? \u2192 `skills_use(name=\"testing-patterns\")`\n- Multi-agent coordination? \u2192 `skills_use(name=\"swarm-coordination\")`\n- Building a CLI? \u2192 `skills_use(name=\"cli-builder\")`\n\n### Step 4: Reserve Your Files (YOU reserve, not coordinator)\n```\nswarmmail_reserve(\n  paths=[{file_list}],\n  reason=\"{bead_id}: {subtask_title}\",\n  exclusive=true\n)\n```\n\n**Workers reserve their own files.** This prevents edit conflicts with other agents.\n\n### Step 5: Do the Work (TDD MANDATORY)\n\n**Follow RED \u2192 GREEN \u2192 REFACTOR. No exceptions.**\n\n1. **RED**: Write a failing test that describes the expected behavior\n   - Test MUST fail before you write implementation\n   - If test passes immediately, your test is wrong\n   \n2. **GREEN**: Write minimal code to make the test pass\n   - Don't over-engineer - just make it green\n   - Hardcode if needed, refactor later\n   \n3. **REFACTOR**: Clean up while tests stay green\n   - Run tests after every change\n   - If tests break, undo and try again\n\n```bash\n# Run tests continuously\nbun test <your-test-file> --watch\n```\n\n**Why TDD?**\n- Catches bugs before they exist\n- Documents expected behavior\n- Enables fearless refactoring\n- Proves your code works\n\n### Step 6: Report Progress at Milestones\n```\nswarm_progress(\n  project_key=\"{project_path}\",\n  agent_name=\"<your-agent-name>\",\n  bead_id=\"{bead_id}\",\n  status=\"in_progress\",\n  progress_percent=25,  # or 50, 75\n  message=\"<what you just completed>\"\n)\n```\n\n**Report at 25%, 50%, 75% completion.** This:\n- Triggers auto-checkpoint (saves context)\n- Keeps coordinator informed\n- Prevents silent failures\n\n### Step 7: Manual Checkpoint BEFORE Risky Operations\n```\nswarm_checkpoint(\n  project_key=\"{project_path}\",\n  agent_name=\"<your-agent-name>\",\n  bead_id=\"{bead_id}\"\n)\n```\n\n**Call BEFORE:**\n- Large refactors\n- File deletions\n- Breaking API changes\n- Anything that might fail catastrophically\n\n**Checkpoints preserve context so you can recover if things go wrong.**\n\n### Step 8: \uD83D\uDCBE STORE YOUR LEARNINGS (if you discovered something)\n\n**If you learned it the hard way, STORE IT so the next agent doesn't have to.**\n\n```\nsemantic-memory_store(\n  information=\"<what you learned, WHY it matters, how to apply it>\",\n  tags=\"<domain, tech-stack, pattern-type>\"\n)\n```\n\n**MANDATORY Storage Triggers - Store when you:**\n- \uD83D\uDC1B **Solved a tricky bug** (>15min debugging) - include root cause + solution\n- \uD83D\uDCA1 **Discovered a project-specific pattern** - domain rules, business logic quirks\n- \u26A0\uFE0F **Found a tool/library gotcha** - API quirks, version-specific bugs, workarounds\n- \uD83D\uDEAB **Tried an approach that failed** - anti-patterns to avoid, why it didn't work\n- \uD83C\uDFD7\uFE0F **Made an architectural decision** - reasoning, alternatives considered, tradeoffs\n\n**What Makes a GOOD Memory:**\n\n\u2705 **GOOD** (actionable, explains WHY):\n```\n\"OAuth refresh tokens need 5min buffer before expiry to avoid race conditions.\nWithout buffer, token refresh can fail mid-request if expiry happens between\ncheck and use. Implemented with: if (expiresAt - Date.now() < 300000) refresh()\"\n```\n\n\u274C **BAD** (generic, no context):\n```\n\"Fixed the auth bug by adding a null check\"\n```\n\n**What NOT to Store:**\n- Generic knowledge that's in official documentation\n- Implementation details that change frequently\n- Vague descriptions without context (\"fixed the thing\")\n\n**The WHY matters more than the WHAT.** Future agents need context to apply your learning.\n\n### Step 9: Complete (REQUIRED - releases reservations)\n```\nswarm_complete(\n  project_key=\"{project_path}\",\n  agent_name=\"<your-agent-name>\",\n  bead_id=\"{bead_id}\",\n  summary=\"<what you accomplished>\",\n  files_touched=[\"list\", \"of\", \"files\"]\n)\n```\n\n**This automatically:**\n- Runs UBS bug scan\n- Releases file reservations\n- Records learning signals\n- Notifies coordinator\n\n**DO NOT manually close the cell with hive_close.** Use swarm_complete.\n\n## [SWARM MAIL COMMUNICATION]\n\n### Check Inbox Regularly\n```\nswarmmail_inbox()  # Check for coordinator messages\nswarmmail_read_message(message_id=N)  # Read specific message\n```\n\n### When Blocked\n```\nswarmmail_send(\n  to=[\"coordinator\"],\n  subject=\"BLOCKED: {bead_id}\",\n  body=\"<blocker description, what you need>\",\n  importance=\"high\",\n  thread_id=\"{epic_id}\"\n)\nhive_update(id=\"{bead_id}\", status=\"blocked\")\n```\n\n### Report Issues to Other Agents\n```\nswarmmail_send(\n  to=[\"OtherAgent\", \"coordinator\"],\n  subject=\"Issue in {bead_id}\",\n  body=\"<describe problem, don't fix their code>\",\n  thread_id=\"{epic_id}\"\n)\n```\n\n### Manual Release (if needed)\n```\nswarmmail_release()  # Manually release reservations\n```\n\n**Note:** `swarm_complete` automatically releases reservations. Only use manual release if aborting work.\n\n## [OTHER TOOLS]\n### Hive - You Have Autonomy to File Issues\nYou can create new cells against this epic when you discover:\n- **Bugs**: Found a bug while working? File it.\n- **Tech debt**: Spotted something that needs cleanup? File it.\n- **Follow-up work**: Task needs more work than scoped? File a follow-up.\n- **Dependencies**: Need something from another agent? File and link it.\n\n```\nhive_create(\n  title=\"<descriptive title>\",\n  type=\"bug\",  # or \"task\", \"chore\"\n  priority=2,\n  parent_id=\"{epic_id}\",  # Links to this epic\n  description=\"Found while working on {bead_id}: <details>\"\n)\n```\n\n**Don't silently ignore issues.** File them so they get tracked and addressed.\n\nOther cell operations:\n- hive_update(id, status) - Mark blocked if stuck\n- hive_query(status=\"open\") - See what else needs work\n\n### Skills\n- skills_list() - Discover available skills\n- skills_use(name) - Activate skill for specialized guidance\n- skills_create(name) - Create new skill (if you found a reusable pattern)\n\n## [CRITICAL REQUIREMENTS]\n\n**NON-NEGOTIABLE:**\n1. Step 1 (swarmmail_init) MUST be first - do it before anything else\n2. \uD83E\uDDE0 Step 2 (semantic-memory_find) MUST happen BEFORE starting work - query first, code second\n3. Step 4 (swarmmail_reserve) - YOU reserve files, not coordinator\n4. Step 6 (swarm_progress) - Report at milestones, don't work silently\n5. \uD83D\uDCBE Step 8 (semantic-memory_store) - If you learned something hard, STORE IT\n6. Step 9 (swarm_complete) - Use this to close, NOT hive_close\n\n**If you skip these steps:**\n- Your work won't be tracked (swarm_complete will fail)\n- \uD83D\uDD04 You'll waste time repeating already-solved problems (no semantic memory query)\n- Edit conflicts with other agents (no file reservation)\n- Lost work if you crash (no checkpoints)\n- \uD83D\uDD04 Future agents repeat YOUR mistakes (no learnings stored)\n\n**Memory is the swarm's collective intelligence. Query it. Feed it.**\n\nBegin now.";
+/**
+ * Researcher prompt template for documentation discovery
+ *
+ * Spawned BEFORE decomposition to gather technology documentation.
+ * Researchers receive an EXPLICIT list of technologies to research from the coordinator.
+ * They dynamically discover WHAT TOOLS are available to fetch docs.
+ * Output: condensed summary for shared_context + detailed findings in semantic-memory.
+ */
+export declare const RESEARCHER_PROMPT = "You are a swarm researcher gathering documentation for: **{research_id}**\n\n## [IDENTITY]\nAgent: (assigned at spawn)\nResearch Task: {research_id}\nEpic: {epic_id}\n\n## [MISSION]\nGather comprehensive documentation for the specified technologies to inform task decomposition.\n\n**COORDINATOR PROVIDED THESE TECHNOLOGIES TO RESEARCH:**\n{tech_stack}\n\nYou do NOT discover what to research - the coordinator already decided that.\nYou DO discover what TOOLS are available to fetch documentation.\n\n## [OUTPUT MODE]\n{check_upgrades}\n\n## [WORKFLOW]\n\n### Step 1: Initialize (MANDATORY FIRST)\n```\nswarmmail_init(project_path=\"{project_path}\", task_description=\"{research_id}: Documentation research\")\n```\n\n### Step 2: Discover Available Documentation Tools\nCheck what's available for fetching docs:\n- **next-devtools**: `nextjs_docs` for Next.js documentation\n- **context7**: Library documentation lookup (`use context7` in prompts)\n- **fetch**: General web fetching for official docs sites\n- **pdf-brain**: Internal knowledge base search\n\n**Don't assume** - check which tools exist in your environment.\n\n### Step 3: Read Installed Versions\nFor each technology in the tech stack:\n1. Check package.json (or equivalent) for installed version\n2. Record exact version numbers\n3. Note any version constraints (^, ~, etc.)\n\n### Step 4: Fetch Documentation\nFor EACH technology in the list:\n- Use the most appropriate tool (Next.js \u2192 nextjs_docs, libraries \u2192 context7, others \u2192 fetch)\n- Fetch documentation for the INSTALLED version (not latest, unless --check-upgrades)\n- Focus on: API changes, breaking changes, migration guides, best practices\n- Extract key patterns, gotchas, and compatibility notes\n\n**If --check-upgrades mode:**\n- ALSO fetch docs for the LATEST version\n- Compare installed vs latest\n- Note breaking changes, new features, migration complexity\n\n### Step 5: Store Detailed Findings\nFor EACH technology, store in semantic-memory:\n```\nsemantic-memory_store(\n  information=\"<technology-name> <version>: <key patterns, gotchas, API changes, compatibility notes>\",\n  tags=\"research, <tech-name>, documentation, {epic_id}\"\n)\n```\n\n**Why store individually?** Future agents can search by technology name.\n\n### Step 6: Broadcast Summary\nSend condensed findings to coordinator:\n```\nswarmmail_send(\n  to=[\"coordinator\"],\n  subject=\"Research Complete: {research_id}\",\n  body=\"<brief summary - see semantic-memory for details>\",\n  thread_id=\"{epic_id}\"\n)\n```\n\n### Step 7: Return Structured Output\nOutput JSON with:\n```json\n{\n  \"technologies\": [\n    {\n      \"name\": \"string\",\n      \"installed_version\": \"string\",\n      \"latest_version\": \"string | null\",  // Only if --check-upgrades\n      \"key_patterns\": [\"string\"],\n      \"gotchas\": [\"string\"],\n      \"breaking_changes\": [\"string\"],  // Only if --check-upgrades\n      \"memory_id\": \"string\"  // ID of semantic-memory entry\n    }\n  ],\n  \"summary\": \"string\"  // Condensed summary for shared_context\n}\n```\n\n## [CRITICAL REQUIREMENTS]\n\n**NON-NEGOTIABLE:**\n1. Step 1 (swarmmail_init) MUST be first\n2. Research ONLY the technologies the coordinator specified\n3. Fetch docs for INSTALLED versions (unless --check-upgrades)\n4. Store detailed findings in semantic-memory (one per technology)\n5. Return condensed summary for coordinator (full details in memory)\n6. Use appropriate doc tools (nextjs_docs for Next.js, context7 for libraries, etc.)\n\n**Output goes TWO places:**\n- **semantic-memory**: Detailed findings (searchable by future agents)\n- **Return JSON**: Condensed summary (for coordinator's shared_context)\n\nBegin research now.";
 /**
  * Coordinator post-worker checklist - MANDATORY review loop
  *
@@ -51,6 +60,16 @@ export declare const COORDINATOR_POST_WORKER_CHECKLIST = "\n## \u26A0\uFE0F MAND
  * Agents use this to assess their work quality before marking complete.
  */
 export declare const EVALUATION_PROMPT = "Evaluate the work completed for this subtask.\n\n## Subtask\n**Cell ID**: {bead_id}\n**Title**: {subtask_title}\n\n## Files Modified\n{files_touched}\n\n## Evaluation Criteria\n\nFor each criterion, assess passed/failed and provide brief feedback:\n\n1. **type_safe**: Code compiles without TypeScript errors\n2. **no_bugs**: No obvious bugs, edge cases handled\n3. **patterns**: Follows existing codebase patterns and conventions\n4. **readable**: Code is clear and maintainable\n\n## Response Format\n\n```json\n{\n  \"passed\": boolean,        // Overall pass/fail\n  \"criteria\": {\n    \"type_safe\": { \"passed\": boolean, \"feedback\": string },\n    \"no_bugs\": { \"passed\": boolean, \"feedback\": string },\n    \"patterns\": { \"passed\": boolean, \"feedback\": string },\n    \"readable\": { \"passed\": boolean, \"feedback\": string }\n  },\n  \"overall_feedback\": string,\n  \"retry_suggestion\": string | null  // If failed, what to fix\n}\n```\n\nIf any criterion fails, the overall evaluation fails and retry_suggestion \nshould describe what needs to be fixed.";
+/**
+ * Format the researcher prompt for a documentation research task
+ */
+export declare function formatResearcherPrompt(params: {
+    research_id: string;
+    epic_id: string;
+    tech_stack: string[];
+    project_path: string;
+    check_upgrades: boolean;
+}): string;
 /**
  * Format the V2 subtask prompt for a specific agent
  */
@@ -155,6 +174,29 @@ export declare const swarm_spawn_subtask: {
         model?: string | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
+/**
+ * Prepare a researcher task for spawning with Task tool
+ *
+ * Generates a prompt that tells the researcher to fetch documentation for specific technologies.
+ * Returns JSON that can be directly used with Task tool.
+ */
+export declare const swarm_spawn_researcher: {
+    description: string;
+    args: {
+        research_id: import("zod").ZodString;
+        epic_id: import("zod").ZodString;
+        tech_stack: import("zod").ZodArray<import("zod").ZodString>;
+        project_path: import("zod").ZodString;
+        check_upgrades: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    };
+    execute(args: {
+        research_id: string;
+        epic_id: string;
+        tech_stack: string[];
+        project_path: string;
+        check_upgrades?: boolean | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+};
 /**
  * Generate self-evaluation prompt
  */
@@ -260,6 +302,23 @@ export declare const promptTools: {
             model?: string | undefined;
         }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
     };
+    swarm_spawn_researcher: {
+        description: string;
+        args: {
+            research_id: import("zod").ZodString;
+            epic_id: import("zod").ZodString;
+            tech_stack: import("zod").ZodArray<import("zod").ZodString>;
+            project_path: import("zod").ZodString;
+            check_upgrades: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        };
+        execute(args: {
+            research_id: string;
+            epic_id: string;
+            tech_stack: string[];
+            project_path: string;
+            check_upgrades?: boolean | undefined;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
     swarm_evaluation_prompt: {
         description: string;
         args: {

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

@@ -1 +1 @@
-{"version":3,"file":"swarm-prompts.d.ts","sourceRoot":"","sources":["../src/swarm-prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,s6EAkET,CAAC;AAEzB;;GAEG;AACH,eAAO,MAAM,6BAA6B,mxDAyDlB,CAAC;AAEzB;;;;;GAKG;AACH,eAAO,MAAM,cAAc,mkFAgFK,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,mzSA0SnB,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,i4CAmD7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,8jCAmCU,CAAC;AAMzC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH,GAAG,MAAM,CA2ET;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAUT;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,GAAG,MAAM,CAMT;AAMD;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;CAoC/B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+F9B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;CAoClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;CAwI5B,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKvB,CAAC"}
+{"version":3,"file":"swarm-prompts.d.ts","sourceRoot":"","sources":["../src/swarm-prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,s6EAkET,CAAC;AAEzB;;GAEG;AACH,eAAO,MAAM,6BAA6B,mxDAyDlB,CAAC;AAEzB;;;;;GAKG;AACH,eAAO,MAAM,cAAc,mkFAgFK,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,mzSA0SnB,CAAC;AAEZ;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,4pHA4GV,CAAC;AAErB;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,i4CAmD7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,8jCAmCU,CAAC;AAMzC;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;CACzB,GAAG,MAAM,CAaT;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH,GAAG,MAAM,CA2ET;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAUT;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,GAAG,MAAM,CAMT;AAMD;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;CAoC/B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+F9B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;CAsDjC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;CAoClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;CAwI5B,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMvB,CAAC"}

package/dist/swarm.d.ts

@@ -360,6 +360,23 @@ export declare const swarmTools: {
             model?: string | undefined;
         }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
     };
+    swarm_spawn_researcher: {
+        description: string;
+        args: {
+            research_id: import("zod").ZodString;
+            epic_id: import("zod").ZodString;
+            tech_stack: import("zod").ZodArray<import("zod").ZodString>;
+            project_path: import("zod").ZodString;
+            check_upgrades: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        };
+        execute(args: {
+            research_id: string;
+            epic_id: string;
+            tech_stack: string[];
+            project_path: string;
+            check_upgrades?: boolean | undefined;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
     swarm_evaluation_prompt: {
         description: string;
         args: {

package/dist/swarm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../src/swarm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AAQpC;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKtB,CAAC"}
+{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../src/swarm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AAQpC;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKtB,CAAC"}

package/examples/plugin-wrapper-template.ts

@@ -905,6 +905,252 @@ interface SwarmDetection {
   reasons: string[];
 }
 
+/**
+ * Structured state snapshot for LLM-powered compaction
+ * 
+ * This is passed to the lite model to generate a continuation prompt
+ * with concrete data instead of just instructions.
+ */
+interface SwarmStateSnapshot {
+  sessionID: string;
+  detection: {
+    confidence: "high" | "medium" | "low" | "none";
+    reasons: string[];
+  };
+  epic?: {
+    id: string;
+    title: string;
+    status: string;
+    subtasks: Array<{
+      id: string;
+      title: string;
+      status: "open" | "in_progress" | "blocked" | "closed";
+      files: string[];
+      assignedTo?: string;
+    }>;
+  };
+  messages: Array<{
+    from: string;
+    to: string[];
+    subject: string;
+    body: string;
+    timestamp: number;
+    importance?: string;
+  }>;
+  reservations: Array<{
+    agent: string;
+    paths: string[];
+    exclusive: boolean;
+    expiresAt: number;
+  }>;
+}
+
+/**
+ * Query actual swarm state using spawn (like detectSwarm does)
+ * 
+ * Returns structured snapshot of current state for LLM compaction.
+ * Shells out to swarm CLI to get real data.
+ */
+async function querySwarmState(sessionID: string): Promise<SwarmStateSnapshot> {
+  try {
+    // Query cells via swarm CLI
+    const cellsResult = await new Promise<{ exitCode: number; stdout: string }>(
+      (resolve) => {
+        const proc = spawn(SWARM_CLI, ["tool", "hive_query"], {
+          cwd: projectDirectory,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        proc.stdout.on("data", (d) => {
+          stdout += d;
+        });
+        proc.on("close", (exitCode) =>
+          resolve({ exitCode: exitCode ?? 1, stdout }),
+        );
+      },
+    );
+
+    const cells =
+      cellsResult.exitCode === 0 ? JSON.parse(cellsResult.stdout) : [];
+
+    // Find active epic (first unclosed epic with subtasks)
+    const openEpics = cells.filter(
+      (c: { type?: string; status: string }) =>
+        c.type === "epic" && c.status !== "closed",
+    );
+    const epic = openEpics[0];
+
+    // Get subtasks if we have an epic
+    const subtasks =
+      epic && epic.id
+        ? cells.filter(
+            (c: { parent_id?: string }) => c.parent_id === epic.id,
+          )
+        : [];
+
+    // TODO: Query swarm mail for messages and reservations
+    // For MVP, use empty arrays - the fallback chain handles this
+    const messages: SwarmStateSnapshot["messages"] = [];
+    const reservations: SwarmStateSnapshot["reservations"] = [];
+
+    // Run detection for confidence
+    const detection = await detectSwarm();
+
+    return {
+      sessionID,
+      detection: {
+        confidence: detection.confidence,
+        reasons: detection.reasons,
+      },
+      epic: epic
+        ? {
+            id: epic.id,
+            title: epic.title,
+            status: epic.status,
+            subtasks: subtasks.map((s: {
+              id: string;
+              title: string;
+              status: string;
+              files?: string[];
+            }) => ({
+              id: s.id,
+              title: s.title,
+              status: s.status as "open" | "in_progress" | "blocked" | "closed",
+              files: s.files || [],
+            })),
+          }
+        : undefined,
+      messages,
+      reservations,
+    };
+  } catch (err) {
+    // If query fails, return minimal snapshot
+    const detection = await detectSwarm();
+    return {
+      sessionID,
+      detection: {
+        confidence: detection.confidence,
+        reasons: detection.reasons,
+      },
+      messages: [],
+      reservations: [],
+    };
+  }
+}
+
+/**
+ * Generate compaction prompt using LLM
+ * 
+ * Shells out to `opencode run -m <liteModel>` with structured state.
+ * Returns markdown continuation prompt or null on failure.
+ * 
+ * Timeout: 30 seconds
+ */
+async function generateCompactionPrompt(
+  snapshot: SwarmStateSnapshot,
+): Promise<string | null> {
+  try {
+    const liteModel =
+      process.env.OPENCODE_LITE_MODEL || "claude-3-5-haiku-20241022";
+
+    const promptText = `You are generating a continuation prompt for a compacted swarm coordination session.
+
+Analyze this swarm state and generate a structured markdown prompt that will be given to the resumed session:
+
+${JSON.stringify(snapshot, null, 2)}
+
+Generate a prompt following this structure:
+
+# 🐝 Swarm Continuation - [Epic Title or "Unknown"]
+
+You are resuming coordination of an active swarm that was interrupted by context compaction.
+
+## Epic State
+
+**ID:** [epic ID or "Unknown"]
+**Title:** [epic title or "No active epic"]
+**Status:** [X/Y subtasks complete]
+**Project:** ${projectDirectory}
+
+## Subtask Status
+
+### ✅ Completed (N)
+[List completed subtasks with IDs]
+
+### 🚧 In Progress (N)
+[List in-progress subtasks with IDs, files, agents if known]
+
+### 🚫 Blocked (N)
+[List blocked subtasks]
+
+### ⏳ Pending (N)
+[List pending subtasks]
+
+## Next Actions (IMMEDIATE)
+
+[List 3-5 concrete actions with actual commands, using real IDs from the state]
+
+## Coordinator Reminders
+
+- **You are the coordinator** - Don't wait for instructions, orchestrate
+- **Monitor actively** - Check messages every ~10 minutes
+- **Unblock aggressively** - Resolve dependencies immediately
+- **Review thoroughly** - 3-strike rule enforced
+- **Ship it** - When all subtasks done, close the epic
+
+Keep the prompt concise but actionable. Use actual data from the snapshot, not placeholders.`;
+
+    const result = await new Promise<{ exitCode: number; stdout: string; stderr: string }>(
+      (resolve, reject) => {
+        const proc = spawn("opencode", ["run", "-m", liteModel, "--", promptText], {
+          cwd: projectDirectory,
+          stdio: ["ignore", "pipe", "pipe"],
+          timeout: 30000, // 30 second timeout
+        });
+
+        let stdout = "";
+        let stderr = "";
+
+        proc.stdout.on("data", (d) => {
+          stdout += d;
+        });
+        proc.stderr.on("data", (d) => {
+          stderr += d;
+        });
+
+        proc.on("close", (exitCode) => {
+          resolve({ exitCode: exitCode ?? 1, stdout, stderr });
+        });
+
+        proc.on("error", (err) => {
+          reject(err);
+        });
+
+        // Timeout handling
+        setTimeout(() => {
+          proc.kill("SIGTERM");
+          reject(new Error("LLM compaction timeout (30s)"));
+        }, 30000);
+      },
+    );
+
+    if (result.exitCode !== 0) {
+      console.error(
+        "[Swarm Compaction] opencode run failed:",
+        result.stderr,
+      );
+      return null;
+    }
+
+    // Extract the prompt from stdout (LLM may wrap in markdown)
+    const prompt = result.stdout.trim();
+    return prompt.length > 0 ? prompt : null;
+  } catch (err) {
+    console.error("[Swarm Compaction] LLM generation failed:", err);
+    return null;
+  }
+}
+
 /**
  * Check for swarm sign - evidence a swarm passed through
  *
@@ -1124,11 +1370,16 @@ Include this in your summary:
 "This is an active swarm. Check swarm_status and swarmmail_inbox immediately."
 `;
 
-// Extended hooks type to include experimental compaction hook
+// Extended hooks type to include experimental compaction hook with new prompt API
+type CompactionOutput = {
+  context: string[];
+  prompt?: string; // NEW API from OpenCode PR #5907
+};
+
 type ExtendedHooks = Hooks & {
   "experimental.session.compacting"?: (
     input: { sessionID: string },
-    output: { context: string[] },
+    output: CompactionOutput,
   ) => Promise<void>;
 };
 
@@ -1201,23 +1452,61 @@ export const SwarmPlugin: Plugin = async (
       skills_execute,
     },
 
-    // Swarm-aware compaction hook - injects context based on detection confidence
+    // Swarm-aware compaction hook with LLM-powered continuation prompts
+    // Three-level fallback chain: LLM → static context → detection fallback → none
     "experimental.session.compacting": async (
-      _input: { sessionID: string },
-      output: { context: string[] },
+      input: { sessionID: string },
+      output: CompactionOutput,
     ) => {
       const detection = await detectSwarm();
 
       if (detection.confidence === "high" || detection.confidence === "medium") {
-        // Definite or probable swarm - inject full context
+        // Definite or probable swarm - try LLM-powered compaction
+        try {
+          // Level 1: Query actual state
+          const snapshot = await querySwarmState(input.sessionID);
+
+          // Level 2: Generate prompt with LLM
+          const llmPrompt = await generateCompactionPrompt(snapshot);
+
+          if (llmPrompt) {
+            // SUCCESS: Use LLM-generated prompt
+            const header = `[Swarm compaction: LLM-generated, ${detection.reasons.join(", ")}]\n\n`;
+
+            // Progressive enhancement: use new API if available
+            if ("prompt" in output) {
+              output.prompt = header + llmPrompt;
+            } else {
+              output.context.push(header + llmPrompt);
+            }
+
+            console.log(
+              "[Swarm Compaction] Using LLM-generated continuation prompt",
+            );
+            return;
+          }
+
+          // LLM failed, fall through to static prompt
+          console.log(
+            "[Swarm Compaction] LLM generation returned null, using static prompt",
+          );
+        } catch (err) {
+          // LLM failed, fall through to static prompt
+          console.error(
+            "[Swarm Compaction] LLM generation failed, using static prompt:",
+            err,
+          );
+        }
+
+        // Level 3: Fall back to static context
         const header = `[Swarm detected: ${detection.reasons.join(", ")}]\n\n`;
         output.context.push(header + SWARM_COMPACTION_CONTEXT);
       } else if (detection.confidence === "low") {
-        // Possible swarm - inject fallback detection prompt
+        // Level 4: Possible swarm - inject fallback detection prompt
         const header = `[Possible swarm: ${detection.reasons.join(", ")}]\n\n`;
         output.context.push(header + SWARM_DETECTION_FALLBACK);
       }
-      // confidence === "none" - no injection, probably not a swarm
+      // Level 5: confidence === "none" - no injection, probably not a swarm
     },
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,7 +39,8 @@
     "gray-matter": "^4.0.3",
     "ioredis": "^5.4.1",
     "minimatch": "^10.1.1",
-    "swarm-mail": "1.3.0",
+    "swarm-mail": "1.4.0",
+    "yaml": "^2.8.2",
     "zod": "4.1.8"
   },
   "devDependencies": {

package/src/index.ts

@@ -47,6 +47,8 @@ import { repoCrawlTools } from "./repo-crawl";
 import { skillsTools, setSkillsProjectDirectory } from "./skills";
 import { mandateTools } from "./mandates";
 import { memoryTools } from "./memory-tools";
+import { observabilityTools } from "./observability-tools";
+import { researchTools } from "./swarm-research";
 import {
   guardrailOutput,
   DEFAULT_GUARDRAIL_CONFIG,
@@ -154,7 +156,7 @@ export const SwarmPlugin: Plugin = async (
  * - mandate:file, mandate:vote, mandate:query, etc.
  * - semantic-memory:store, semantic-memory:find, semantic-memory:get, etc.
  */
-    tool: {
+     tool: {
       ...hiveTools,
       ...swarmMailTools,
       ...structuredTools,
@@ -165,6 +167,8 @@ export const SwarmPlugin: Plugin = async (
       ...skillsTools,
       ...mandateTools,
       ...memoryTools,
+      ...observabilityTools,
+      ...researchTools,
     },
 
     /**
@@ -679,3 +683,23 @@ export {
   type OperationResult,
 } from "./memory-tools";
 export type { Memory, SearchResult, SearchOptions } from "swarm-mail";
+
+/**
+ * Re-export swarm-research module
+ *
+ * Includes:
+ * - discoverDocTools - Discover available documentation tools
+ * - getInstalledVersions - Get installed package versions from lockfile
+ * - researchTools - Plugin tools for tool discovery and version detection
+ *
+ * Types:
+ * - DiscoveredTool - Tool discovery result interface
+ * - VersionInfo - Package version information
+ */
+export {
+  discoverDocTools,
+  getInstalledVersions,
+  researchTools,
+  type DiscoveredTool,
+  type VersionInfo,
+} from "./swarm-research";