opencode-swarm-plugin 0.32.0 → 0.34.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,124 @@ 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
  *
@@ -602,10 +743,32 @@ swarm_review_feedback(
 )
 \`\`\`
 
-### 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
+### Step 5: Take Action Based on Review
+
+**If APPROVED:**
+- Close the cell with hive_close
+- Spawn next worker (if any) using swarm_spawn_subtask
+
+**If NEEDS_CHANGES:**
+- Generate retry prompt:
+  \`\`\`
+  swarm_spawn_retry(
+    bead_id="{task_id}",
+    epic_id="{epic_id}",
+    original_prompt="<original prompt>",
+    attempt=<current_attempt>,
+    issues="<JSON from swarm_review_feedback>",
+    diff="<git diff of previous changes>",
+    files=[{files_touched}],
+    project_path="{project_key}"
+  )
+  \`\`\`
+- Spawn new worker with Task() using the retry prompt
+- Increment attempt counter (max 3 attempts)
+
+**If 3 FAILURES:**
+- Mark task as blocked: \`hive_update(id="{task_id}", status="blocked")\`
+- Escalate to human - likely an architectural problem, not execution issue
 
 **⚠️ DO NOT spawn the next worker until review is complete.**
 `;
@@ -656,6 +819,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
  */
@@ -937,6 +1124,219 @@ export const swarm_spawn_subtask = tool({
   },
 });
 
+/**
+ * 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,
+    );
+  },
+});
+
+/**
+ * Generate retry prompt for a worker that needs to fix issues from review feedback
+ * 
+ * Coordinators use this when swarm_review_feedback returns "needs_changes".
+ * Creates a new worker spawn with context about what went wrong and what to fix.
+ */
+export const swarm_spawn_retry = tool({
+  description:
+    "Generate retry prompt for a worker that failed review. Includes issues from previous attempt, diff if provided, and standard worker contract.",
+  args: {
+    bead_id: tool.schema.string().describe("Original subtask bead ID"),
+    epic_id: tool.schema.string().describe("Parent epic bead ID"),
+    original_prompt: tool.schema.string().describe("The prompt given to failed worker"),
+    attempt: tool.schema.number().int().min(1).max(3).describe("Current attempt number (1, 2, or 3)"),
+    issues: tool.schema.string().describe("JSON array of ReviewIssue objects from swarm_review_feedback"),
+    diff: tool.schema
+      .string()
+      .optional()
+      .describe("Git diff of previous changes"),
+    files: tool.schema
+      .array(tool.schema.string())
+      .describe("Files to modify (from original subtask)"),
+    project_path: tool.schema
+      .string()
+      .optional()
+      .describe("Absolute project path for swarmmail_init"),
+  },
+  async execute(args) {
+    // Validate attempt number
+    if (args.attempt > 3) {
+      throw new Error(
+        `Retry attempt ${args.attempt} exceeds maximum of 3. After 3 failures, task should be marked blocked.`,
+      );
+    }
+
+    // Parse issues
+    let issuesArray: Array<{
+      file: string;
+      line: number;
+      issue: string;
+      suggestion: string;
+    }> = [];
+    try {
+      issuesArray = JSON.parse(args.issues);
+    } catch (e) {
+      // If issues is not valid JSON, treat as empty array
+      issuesArray = [];
+    }
+
+    // Format issues section
+    const issuesSection = issuesArray.length > 0
+      ? `## ISSUES FROM PREVIOUS ATTEMPT
+
+The previous attempt had the following issues that need to be fixed:
+
+${issuesArray
+  .map(
+    (issue, idx) =>
+      `**${idx + 1}. ${issue.file}:${issue.line}**
+   - **Issue**: ${issue.issue}
+   - **Suggestion**: ${issue.suggestion}`,
+  )
+  .join("\n\n")}
+
+**Critical**: Fix these issues while preserving any working changes from the previous attempt.`
+      : "";
+
+    // Format diff section
+    const diffSection = args.diff
+      ? `## PREVIOUS ATTEMPT
+
+Here's what was tried in the previous attempt:
+
+\`\`\`diff
+${args.diff}
+\`\`\`
+
+Review this carefully - some changes may be correct and should be preserved.`
+      : "";
+
+    // Build the retry prompt
+    const retryPrompt = `⚠️ **RETRY ATTEMPT ${args.attempt}/3**
+
+This is a retry of a previously attempted subtask. The coordinator reviewed the previous attempt and found issues that need to be fixed.
+
+${issuesSection}
+
+${diffSection}
+
+## ORIGINAL TASK
+
+${args.original_prompt}
+
+## YOUR MISSION
+
+1. **Understand what went wrong** - Read the issues carefully
+2. **Fix the specific problems** - Address each issue listed above
+3. **Preserve working code** - Don't throw away correct changes from previous attempt
+4. **Follow the standard worker contract** - See below
+
+## MANDATORY WORKER CONTRACT
+
+### Step 1: Initialize (REQUIRED FIRST)
+\`\`\`
+swarmmail_init(project_path="${args.project_path || "$PWD"}", task_description="${args.bead_id}: Retry ${args.attempt}/3")
+\`\`\`
+
+### Step 2: Reserve Files
+\`\`\`
+swarmmail_reserve(
+  paths=${JSON.stringify(args.files)},
+  reason="${args.bead_id}: Retry attempt ${args.attempt}",
+  exclusive=true
+)
+\`\`\`
+
+### Step 3: Fix the Issues
+- Address each issue listed above
+- Run tests to verify fixes
+- Don't introduce new bugs
+
+### Step 4: Complete
+\`\`\`
+swarm_complete(
+  project_key="${args.project_path || "$PWD"}",
+  agent_name="<your-agent-name>",
+  bead_id="${args.bead_id}",
+  summary="Fixed issues from review: <brief summary>",
+  files_touched=[<files you modified>]
+)
+\`\`\`
+
+**Remember**: This is attempt ${args.attempt} of 3. If this fails review again, there may be an architectural problem that needs human intervention.
+
+Begin work now.`;
+
+    return JSON.stringify(
+      {
+        prompt: retryPrompt,
+        bead_id: args.bead_id,
+        attempt: args.attempt,
+        max_attempts: 3,
+        files: args.files,
+        issues_count: issuesArray.length,
+      },
+      null,
+      2,
+    );
+  },
+});
+
 /**
  * Generate self-evaluation prompt
  */
@@ -1125,6 +1525,8 @@ export const swarm_plan_prompt = tool({
 export const promptTools = {
   swarm_subtask_prompt,
   swarm_spawn_subtask,
+  swarm_spawn_researcher,
+  swarm_spawn_retry,
   swarm_evaluation_prompt,
   swarm_plan_prompt,
 };