opencode-swarm-plugin 0.31.7 → 0.33.0

package/src/swarm-prompts.ts

@@ -464,6 +464,29 @@ swarm_complete(
 
 **DO NOT manually close the cell with hive_close.** Use swarm_complete.
 
+## [ON-DEMAND RESEARCH]
+
+If you encounter unknown API behavior or version-specific issues:
+
+1. **Check semantic-memory first:**
+   \`semantic-memory_find(query="<library> <version> <topic>", limit=3, expand=true)\`
+
+2. **If not found, spawn researcher:**
+   \`swarm_spawn_researcher(research_id="{bead_id}-research", epic_id="{epic_id}", tech_stack=["<library>"], project_path="{project_path}")\`
+   Then spawn with Task tool: \`Task(subagent_type="swarm/researcher", prompt="<from above>")\`
+
+3. **Wait for research, then continue**
+
+**Research triggers:**
+- "I'm not sure how this API works in version X"
+- "This might have breaking changes"
+- "The docs I remember might be outdated"
+
+**Don't research:**
+- Standard patterns you're confident about
+- Well-documented, stable APIs
+- Obvious implementations
+
 ## [SWARM MAIL COMMUNICATION]
 
 ### Check Inbox Regularly
@@ -551,6 +574,183 @@ Other cell operations:
 
 Begin 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 const RESEARCHER_PROMPT = `You are a swarm researcher gathering documentation for: **{research_id}**
+
+## [IDENTITY]
+Agent: (assigned at spawn)
+Research Task: {research_id}
+Epic: {epic_id}
+
+## [MISSION]
+Gather comprehensive documentation for the specified technologies to inform task decomposition.
+
+**COORDINATOR PROVIDED THESE TECHNOLOGIES TO RESEARCH:**
+{tech_stack}
+
+You do NOT discover what to research - the coordinator already decided that.
+You DO discover what TOOLS are available to fetch documentation.
+
+## [OUTPUT MODE]
+{check_upgrades}
+
+## [WORKFLOW]
+
+### Step 1: Initialize (MANDATORY FIRST)
+\`\`\`
+swarmmail_init(project_path="{project_path}", task_description="{research_id}: Documentation research")
+\`\`\`
+
+### Step 2: Discover Available Documentation Tools
+Check what's available for fetching docs:
+- **next-devtools**: \`nextjs_docs\` for Next.js documentation
+- **context7**: Library documentation lookup (\`use context7\` in prompts)
+- **fetch**: General web fetching for official docs sites
+- **pdf-brain**: Internal knowledge base search
+
+**Don't assume** - check which tools exist in your environment.
+
+### Step 3: Read Installed Versions
+For each technology in the tech stack:
+1. Check package.json (or equivalent) for installed version
+2. Record exact version numbers
+3. Note any version constraints (^, ~, etc.)
+
+### Step 4: Fetch Documentation
+For EACH technology in the list:
+- Use the most appropriate tool (Next.js → nextjs_docs, libraries → context7, others → fetch)
+- Fetch documentation for the INSTALLED version (not latest, unless --check-upgrades)
+- Focus on: API changes, breaking changes, migration guides, best practices
+- Extract key patterns, gotchas, and compatibility notes
+
+**If --check-upgrades mode:**
+- ALSO fetch docs for the LATEST version
+- Compare installed vs latest
+- Note breaking changes, new features, migration complexity
+
+### Step 5: Store Detailed Findings
+For EACH technology, store in semantic-memory:
+\`\`\`
+semantic-memory_store(
+  information="<technology-name> <version>: <key patterns, gotchas, API changes, compatibility notes>",
+  tags="research, <tech-name>, documentation, {epic_id}"
+)
+\`\`\`
+
+**Why store individually?** Future agents can search by technology name.
+
+### Step 6: Broadcast Summary
+Send condensed findings to coordinator:
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="Research Complete: {research_id}",
+  body="<brief summary - see semantic-memory for details>",
+  thread_id="{epic_id}"
+)
+\`\`\`
+
+### Step 7: Return Structured Output
+Output JSON with:
+\`\`\`json
+{
+  "technologies": [
+    {
+      "name": "string",
+      "installed_version": "string",
+      "latest_version": "string | null",  // Only if --check-upgrades
+      "key_patterns": ["string"],
+      "gotchas": ["string"],
+      "breaking_changes": ["string"],  // Only if --check-upgrades
+      "memory_id": "string"  // ID of semantic-memory entry
+    }
+  ],
+  "summary": "string"  // Condensed summary for shared_context
+}
+\`\`\`
+
+## [CRITICAL REQUIREMENTS]
+
+**NON-NEGOTIABLE:**
+1. Step 1 (swarmmail_init) MUST be first
+2. Research ONLY the technologies the coordinator specified
+3. Fetch docs for INSTALLED versions (unless --check-upgrades)
+4. Store detailed findings in semantic-memory (one per technology)
+5. Return condensed summary for coordinator (full details in memory)
+6. Use appropriate doc tools (nextjs_docs for Next.js, context7 for libraries, etc.)
+
+**Output goes TWO places:**
+- **semantic-memory**: Detailed findings (searchable by future agents)
+- **Return JSON**: Condensed summary (for coordinator's shared_context)
+
+Begin research now.`;
+
+/**
+ * Coordinator post-worker checklist - MANDATORY review loop
+ *
+ * This checklist is returned to coordinators after spawning a worker.
+ * It ensures coordinators REVIEW worker output before spawning the next worker.
+ */
+export const COORDINATOR_POST_WORKER_CHECKLIST = `
+## ⚠️ MANDATORY: Post-Worker Review (DO THIS IMMEDIATELY)
+
+**A worker just returned. Before doing ANYTHING else, complete this checklist:**
+
+### Step 1: Check Swarm Mail
+\`\`\`
+swarmmail_inbox()
+swarmmail_read_message(message_id=N)  // Read any messages from the worker
+\`\`\`
+
+### Step 2: Review the Work
+\`\`\`
+swarm_review(
+  project_key="{project_key}",
+  epic_id="{epic_id}",
+  task_id="{task_id}",
+  files_touched=[{files_touched}]
+)
+\`\`\`
+
+This generates a review prompt with:
+- Epic context (what we're trying to achieve)
+- Subtask requirements
+- Git diff of changes
+- Dependency status
+
+### Step 3: Evaluate Against Criteria
+- Does the work fulfill the subtask requirements?
+- Does it serve the overall epic goal?
+- Does it enable downstream tasks?
+- Type safety, no obvious bugs?
+
+### Step 4: Send Feedback
+\`\`\`
+swarm_review_feedback(
+  project_key="{project_key}",
+  task_id="{task_id}",
+  worker_id="{worker_id}",
+  status="approved",  // or "needs_changes"
+  summary="<brief summary>",
+  issues="[]"  // or "[{file, line, issue, suggestion}]"
+)
+\`\`\`
+
+### Step 5: ONLY THEN Continue
+- If approved: Close the cell, spawn next worker
+- If needs_changes: Worker gets feedback, retries (max 3 attempts)
+- If 3 failures: Mark blocked, escalate to human
+
+**⚠️ DO NOT spawn the next worker until review is complete.**
+`;
+
 /**
  * Prompt for self-evaluation before completing a subtask.
  *
@@ -597,6 +797,30 @@ should describe what needs to be fixed.`;
 // Helper Functions
 // ============================================================================
 
+/**
+ * Format the researcher prompt for a documentation research task
+ */
+export function formatResearcherPrompt(params: {
+  research_id: string;
+  epic_id: string;
+  tech_stack: string[];
+  project_path: string;
+  check_upgrades: boolean;
+}): string {
+  const techList = params.tech_stack.map((t) => `- ${t}`).join("\n");
+  
+  const upgradesMode = params.check_upgrades
+    ? "**UPGRADE COMPARISON MODE**: Fetch docs for BOTH installed AND latest versions. Compare and note breaking changes."
+    : "**DEFAULT MODE**: Fetch docs for INSTALLED versions only (from lockfiles).";
+
+  return RESEARCHER_PROMPT
+    .replace(/{research_id}/g, params.research_id)
+    .replace(/{epic_id}/g, params.epic_id)
+    .replace("{tech_stack}", techList)
+    .replace("{project_path}", params.project_path)
+    .replace("{check_upgrades}", upgradesMode);
+}
+
 /**
  * Format the V2 subtask prompt for a specific agent
  */
@@ -852,6 +1076,15 @@ export const swarm_spawn_subtask = tool({
     
     const selectedModel = selectWorkerModel(subtask, config);
 
+    // Generate post-completion instructions for coordinator
+    const filesJoined = args.files.map(f => `"${f}"`).join(", ");
+    const postCompletionInstructions = COORDINATOR_POST_WORKER_CHECKLIST
+      .replace(/{project_key}/g, args.project_path || "$PWD")
+      .replace(/{epic_id}/g, args.epic_id)
+      .replace(/{task_id}/g, args.bead_id)
+      .replace(/{files_touched}/g, filesJoined)
+      .replace(/{worker_id}/g, "worker");  // Will be filled by actual worker name
+
     return JSON.stringify(
       {
         prompt,
@@ -861,6 +1094,69 @@ export const swarm_spawn_subtask = tool({
         project_path: args.project_path,
         recovery_context: args.recovery_context,
         recommended_model: selectedModel,
+        post_completion_instructions: postCompletionInstructions,
+      },
+      null,
+      2,
+    );
+  },
+});
+
+/**
+ * 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 const swarm_spawn_researcher = tool({
+  description:
+    "Prepare a research task for spawning. Returns prompt for gathering technology documentation. Researcher fetches docs and stores findings in semantic-memory.",
+  args: {
+    research_id: tool.schema.string().describe("Unique ID for this research task"),
+    epic_id: tool.schema.string().describe("Parent epic ID"),
+    tech_stack: tool.schema
+      .array(tool.schema.string())
+      .describe("Explicit list of technologies to research (from coordinator)"),
+    project_path: tool.schema
+      .string()
+      .describe("Absolute project path for swarmmail_init"),
+    check_upgrades: tool.schema
+      .boolean()
+      .optional()
+      .describe("If true, compare installed vs latest versions (default: false)"),
+  },
+  async execute(args) {
+    const prompt = formatResearcherPrompt({
+      research_id: args.research_id,
+      epic_id: args.epic_id,
+      tech_stack: args.tech_stack,
+      project_path: args.project_path,
+      check_upgrades: args.check_upgrades ?? false,
+    });
+
+    return JSON.stringify(
+      {
+        prompt,
+        research_id: args.research_id,
+        epic_id: args.epic_id,
+        tech_stack: args.tech_stack,
+        project_path: args.project_path,
+        check_upgrades: args.check_upgrades ?? false,
+        subagent_type: "swarm/researcher",
+        expected_output: {
+          technologies: [
+            {
+              name: "string",
+              installed_version: "string",
+              latest_version: "string | null",
+              key_patterns: ["string"],
+              gotchas: ["string"],
+              breaking_changes: ["string"],
+              memory_id: "string",
+            },
+          ],
+          summary: "string",
+        },
       },
       null,
       2,
@@ -1056,6 +1352,7 @@ export const swarm_plan_prompt = tool({
 export const promptTools = {
   swarm_subtask_prompt,
   swarm_spawn_subtask,
+  swarm_spawn_researcher,
   swarm_evaluation_prompt,
   swarm_plan_prompt,
 };