opencode-swarm-plugin 0.37.0 → 0.38.0

package/src/swarm-prompts.ts

@@ -576,8 +576,289 @@ Other cell operations:
 Begin now.`;
 
 /**
- * Researcher prompt template for documentation discovery
- *
+ * Coordinator Agent Prompt Template
+ * 
+ * Used by the /swarm command to instruct coordinators on their role.
+ * Coordinators NEVER execute work directly - they clarify, decompose, spawn workers, and review.
+ * 
+ * Key sections:
+ * - Role boundaries (what coordinators NEVER do)
+ * - Phase 1.5: Research Phase (spawn researchers, DON'T fetch docs directly)
+ * - Forbidden tools (repo-crawl, webfetch, context7, pdf-brain_search)
+ * - MANDATORY review loop after each worker completes
+ * 
+ * Placeholders:
+ * - {task} - The task description from user
+ * - {project_path} - Absolute path to project root
+ */
+export const COORDINATOR_PROMPT = `You are a swarm coordinator. Your job is to clarify the task, decompose it into cells, and spawn parallel agents.
+
+## Task
+
+{task}
+
+## CRITICAL: Coordinator Role Boundaries
+
+**⚠️ COORDINATORS NEVER EXECUTE WORK DIRECTLY**
+
+Your role is **ONLY** to:
+1. **Clarify** - Ask questions to understand scope
+2. **Decompose** - Break into subtasks with clear boundaries  
+3. **Spawn** - Create worker agents for ALL subtasks
+4. **Monitor** - Check progress, unblock, mediate conflicts
+5. **Verify** - Confirm completion, run final checks
+
+**YOU DO NOT:**
+- Read implementation files (only metadata/structure for planning)
+- Edit code directly
+- Run tests yourself (workers run tests)
+- Implement features
+- Fix bugs inline
+- Make "quick fixes" yourself
+
+**ALWAYS spawn workers, even for sequential tasks.** Sequential just means spawn them in order and wait for each to complete before spawning the next.
+
+### Why This Matters
+
+| Coordinator Work | Worker Work | Consequence of Mixing |
+|-----------------|-------------|----------------------|
+| Sonnet context ($$$) | Disposable context | Expensive context waste |
+| Long-lived state | Task-scoped state | Context exhaustion |
+| Orchestration concerns | Implementation concerns | Mixed concerns |
+| No checkpoints | Checkpoints enabled | No recovery |
+| No learning signals | Outcomes tracked | No improvement |
+
+## CRITICAL: NEVER Fetch Documentation Directly
+
+**⚠️ COORDINATORS DO NOT CALL RESEARCH TOOLS DIRECTLY**
+
+The following tools are **FORBIDDEN** for coordinators to call:
+
+- \`repo-crawl_file\`, \`repo-crawl_readme\`, \`repo-crawl_search\`, \`repo-crawl_structure\`, \`repo-crawl_tree\`
+- \`repo-autopsy_*\` (all variants)
+- \`webfetch\`, \`fetch_fetch\`
+- \`context7_resolve-library-id\`, \`context7_get-library-docs\`
+- \`pdf-brain_search\`, \`pdf-brain_read\`
+
+**WHY?** These tools dump massive context that exhausts your expensive Sonnet context. Your job is orchestration, not research.
+
+**INSTEAD:** Use \`swarm_spawn_researcher\` (see Phase 1.5 below) to spawn a researcher worker who:
+- Fetches documentation in disposable context
+- Stores full details in semantic-memory
+- Returns a condensed summary for shared_context
+
+## Workflow
+
+### Phase 0: Socratic Planning (INTERACTIVE - unless --fast)
+
+**Before decomposing, clarify the task with the user.**
+
+Check for flags in the task:
+- \`--fast\` → Skip questions, use reasonable defaults
+- \`--auto\` → Zero interaction, heuristic decisions
+- \`--confirm-only\` → Show plan, get yes/no only
+
+**Default (no flags): Full Socratic Mode**
+
+1. **Analyze task for ambiguity:**
+   - Scope unclear? (what's included/excluded)
+   - Strategy unclear? (file-based vs feature-based)
+   - Dependencies unclear? (what needs to exist first)
+   - Success criteria unclear? (how do we know it's done)
+
+2. **If clarification needed, ask ONE question at a time:**
+   \`\`\`
+   The task "<task>" needs clarification before I can decompose it.
+
+   **Question:** <specific question>
+
+   Options:
+   a) <option 1> - <tradeoff>
+   b) <option 2> - <tradeoff>
+   c) <option 3> - <tradeoff>
+
+   I'd recommend (b) because <reason>. Which approach?
+   \`\`\`
+
+3. **Wait for user response before proceeding**
+
+4. **Iterate if needed** (max 2-3 questions)
+
+**Rules:**
+- ONE question at a time - don't overwhelm
+- Offer concrete options - not open-ended
+- Lead with recommendation - save cognitive load
+- Wait for answer - don't assume
+
+### Phase 1: Initialize
+\`swarmmail_init(project_path="{project_path}", task_description="Swarm: {task}")\`
+
+### Phase 1.5: Research Phase (FOR COMPLEX TASKS)
+
+**⚠️ If the task requires understanding unfamiliar technologies, APIs, or libraries, spawn a researcher FIRST.**
+
+**DO NOT call documentation tools directly.** Instead:
+
+\`\`\`
+// 1. Spawn researcher with explicit tech stack
+swarm_spawn_researcher(
+  research_id="research-nextjs-cache-components",
+  epic_id="<epic-id>",
+  tech_stack=["Next.js 16 Cache Components", "React Server Components"],
+  project_path="{project_path}"
+)
+
+// 2. Spawn researcher as Task subagent
+const researchFindings = await Task(subagent_type="swarm/researcher", prompt="<from above>")
+
+// 3. Researcher returns condensed summary
+// Use this summary in shared_context for workers
+\`\`\`
+
+**When to spawn a researcher:**
+- Task involves unfamiliar framework versions (e.g., Next.js 16 vs 14)
+- Need to compare installed vs latest library APIs
+- Working with experimental/preview features
+- Need architectural guidance from documentation
+
+**When NOT to spawn a researcher:**
+- Using well-known stable APIs (React hooks, Express middleware)
+- Task is purely refactoring existing code
+- You already have relevant findings from semantic-memory or CASS
+
+**Researcher output:**
+- Full findings stored in semantic-memory (searchable by future agents)
+- Condensed 3-5 bullet summary returned for shared_context
+
+### Phase 2: Knowledge Gathering (MANDATORY)
+
+**Before decomposing, query ALL knowledge sources:**
+
+\`\`\`
+semantic-memory_find(query="<task keywords>", limit=5)   # Past learnings
+cass_search(query="<task description>", limit=5)         # Similar past tasks  
+skills_list()                                            # Available skills
+\`\`\`
+
+Synthesize findings into shared_context for workers.
+
+### Phase 3: Decompose
+\`\`\`
+swarm_select_strategy(task="<task>")
+swarm_plan_prompt(task="<task>", context="<synthesized knowledge>")
+swarm_validate_decomposition(response="<CellTree JSON>")
+\`\`\`
+
+### Phase 4: Create Cells
+\`hive_create_epic(epic_title="<task>", subtasks=[...])\`
+
+### Phase 5: DO NOT Reserve Files
+
+> **⚠️ Coordinator NEVER reserves files.** Workers reserve their own files.
+> If coordinator reserves, workers get blocked and swarm stalls.
+
+### Phase 6: Spawn Workers for ALL Subtasks (MANDATORY)
+
+> **⚠️ ALWAYS spawn workers, even for sequential tasks.**
+> - Parallel tasks: Spawn ALL in a single message
+> - Sequential tasks: Spawn one, wait for completion, spawn next
+
+**For parallel work:**
+\`\`\`
+// Single message with multiple Task calls
+swarm_spawn_subtask(bead_id_1, epic_id, title_1, files_1, shared_context, project_path="{project_path}")
+Task(subagent_type="swarm/worker", prompt="<from above>")
+swarm_spawn_subtask(bead_id_2, epic_id, title_2, files_2, shared_context, project_path="{project_path}")
+Task(subagent_type="swarm/worker", prompt="<from above>")
+\`\`\`
+
+**For sequential work:**
+\`\`\`
+// Spawn worker 1, wait for completion
+swarm_spawn_subtask(bead_id_1, ...)
+const result1 = await Task(subagent_type="swarm/worker", prompt="<from above>")
+
+// THEN spawn worker 2 with context from worker 1
+swarm_spawn_subtask(bead_id_2, ..., shared_context="Worker 1 completed: " + result1)
+const result2 = await Task(subagent_type="swarm/worker", prompt="<from above>")
+\`\`\`
+
+**NEVER do the work yourself.** Even if it seems faster, spawn a worker.
+
+**IMPORTANT:** Pass \`project_path\` to \`swarm_spawn_subtask\` so workers can call \`swarmmail_init\`.
+
+### Phase 7: MANDATORY Review Loop (NON-NEGOTIABLE)
+
+**⚠️ AFTER EVERY Task() RETURNS, YOU MUST:**
+
+1. **CHECK INBOX** - Worker may have sent messages
+   \`swarmmail_inbox()\`
+   \`swarmmail_read_message(message_id=N)\`
+
+2. **REVIEW WORK** - Generate review with diff
+   \`swarm_review(project_key, epic_id, task_id, files_touched)\`
+
+3. **EVALUATE** - Does it meet epic goals?
+   - Fulfills subtask requirements?
+   - Serves overall epic goal?
+   - Enables downstream tasks?
+   - Type safety, no obvious bugs?
+
+4. **SEND FEEDBACK** - Approve or request changes
+   \`swarm_review_feedback(project_key, task_id, worker_id, status, issues)\`
+   
+   **If approved:**
+   - Close cell, spawn next worker
+   
+   **If needs_changes:**
+   - \`swarm_review_feedback\` returns \`retry_context\` (NOT sends message - worker is dead)
+   - Generate retry prompt: \`swarm_spawn_retry(retry_context)\`
+   - Spawn NEW worker with Task() using retry prompt
+   - Max 3 attempts before marking task blocked
+   
+   **If 3 failures:**
+   - Mark task blocked, escalate to human
+
+5. **ONLY THEN** - Spawn next worker or complete
+
+**DO NOT skip this. DO NOT batch reviews. Review EACH worker IMMEDIATELY after return.**
+
+**Intervene if:**
+- Worker blocked >5min → unblock or reassign
+- File conflicts → mediate between workers
+- Scope creep → approve or reject expansion
+- Review fails 3x → mark task blocked, escalate to human
+
+### Phase 8: Complete
+\`\`\`
+# After all workers complete and reviews pass:
+hive_sync()                                    # Sync all cells to git
+# Coordinator does NOT call swarm_complete - workers do that
+\`\`\`
+
+## Strategy Reference
+
+| Strategy       | Best For                 | Keywords                               |
+| -------------- | ------------------------ | -------------------------------------- |
+| file-based     | Refactoring, migrations  | refactor, migrate, rename, update all  |
+| feature-based  | New features             | add, implement, build, create, feature |
+| risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent   |
+| research-based | Investigation, discovery | research, investigate, explore, learn  |
+
+## Flag Reference
+
+| Flag | Effect |
+|------|--------|
+| \`--fast\` | Skip Socratic questions, use defaults |
+| \`--auto\` | Zero interaction, heuristic decisions |
+| \`--confirm-only\` | Show plan, get yes/no only |
+
+Begin with Phase 0 (Socratic Planning) unless \`--fast\` or \`--auto\` flag is present.
+`;
+
+/**
+ * Researcher Agent Prompt Template
+ * 
  * 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.
@@ -844,6 +1125,18 @@ export function formatResearcherPrompt(params: {
     .replace("{check_upgrades}", upgradesMode);
 }
 
+/**
+ * Format the coordinator prompt with task and project path substitution
+ */
+export function formatCoordinatorPrompt(params: {
+  task: string;
+  projectPath: string;
+}): string {
+  return COORDINATOR_PROMPT
+    .replace(/{task}/g, params.task)
+    .replace(/{project_path}/g, params.projectPath);
+}
+
 /**
  * Format the V2 subtask prompt for a specific agent
  */

package/src/swarm-research.integration.test.ts

@@ -495,6 +495,158 @@ describe("End-to-end research workflow", () => {
 	});
 });
 
+describe("Research spawn instructions (NEW)", () => {
+	let testProjectPath: string;
+
+	beforeEach(() => {
+		testProjectPath = join(tmpdir(), `spawn-test-${Date.now()}`);
+		mkdirSync(testProjectPath, { recursive: true });
+	});
+
+	afterEach(() => {
+		rmSync(testProjectPath, { recursive: true, force: true });
+	});
+
+	test("runResearchPhase generates spawn instructions for each technology", async () => {
+		// Create package.json with dependencies
+		const packageJson = {
+			dependencies: {
+				zod: "^3.22.4",
+				typescript: "^5.3.3",
+			},
+		};
+
+		writeFileSync(
+			join(testProjectPath, "package.json"),
+			JSON.stringify(packageJson, null, 2),
+		);
+
+		// Run research phase
+		const result = await runResearchPhase(
+			"Add Zod validation to TypeScript API",
+			testProjectPath,
+		);
+
+		// Should have spawn_instructions array
+		expect(result.spawn_instructions).toBeDefined();
+		expect(Array.isArray(result.spawn_instructions)).toBe(true);
+
+		// Should have one instruction per technology
+		expect(result.spawn_instructions.length).toBe(result.tech_stack.length);
+
+		// Each instruction should have required fields
+		for (const instruction of result.spawn_instructions) {
+			expect(instruction.research_id).toBeDefined();
+			expect(instruction.research_id).toMatch(/^research-/); // Should start with "research-"
+			expect(instruction.tech).toBeDefined();
+			expect(result.tech_stack).toContain(instruction.tech); // Tech should be from tech_stack
+			expect(instruction.prompt).toBeDefined();
+			expect(typeof instruction.prompt).toBe("string");
+			expect(instruction.prompt.length).toBeGreaterThan(0);
+			expect(instruction.subagent_type).toBe("swarm/researcher");
+		}
+	});
+
+	test("runResearchPhase prompts contain correct technology", async () => {
+		const packageJson = {
+			dependencies: {
+				zod: "^3.22.4",
+			},
+		};
+
+		writeFileSync(
+			join(testProjectPath, "package.json"),
+			JSON.stringify(packageJson, null, 2),
+		);
+
+		const result = await runResearchPhase("Use Zod", testProjectPath);
+
+		// Should have exactly one spawn instruction (one tech)
+		expect(result.spawn_instructions.length).toBe(1);
+
+		const instruction = result.spawn_instructions[0];
+		expect(instruction.tech).toBe("zod");
+		expect(instruction.prompt).toContain("zod");
+		expect(instruction.prompt).toContain(testProjectPath);
+	});
+
+	test("runResearchPhase with multiple technologies generates multiple instructions", async () => {
+		const packageJson = {
+			dependencies: {
+				zod: "^3.22.4",
+				typescript: "^5.3.3",
+				react: "^18.2.0",
+			},
+		};
+
+		writeFileSync(
+			join(testProjectPath, "package.json"),
+			JSON.stringify(packageJson, null, 2),
+		);
+
+		const result = await runResearchPhase(
+			"Build React app with Zod and TypeScript",
+			testProjectPath,
+		);
+
+		// Should extract 3 technologies
+		expect(result.tech_stack.length).toBe(3);
+
+		// Should have 3 spawn instructions
+		expect(result.spawn_instructions.length).toBe(3);
+
+		// Each tech should have one instruction
+		const techs = result.spawn_instructions.map((i) => i.tech);
+		expect(techs).toContain("zod");
+		expect(techs).toContain("typescript");
+		expect(techs).toContain("react");
+
+		// Research IDs should be unique
+		const researchIds = result.spawn_instructions.map((i) => i.research_id);
+		const uniqueIds = new Set(researchIds);
+		expect(uniqueIds.size).toBe(researchIds.length);
+	});
+
+	test("runResearchPhase with empty tech_stack returns empty spawn_instructions", async () => {
+		// Don't create package.json - no dependencies
+
+		const result = await runResearchPhase(
+			"Implement something with FooBarBaz",
+			testProjectPath,
+		);
+
+		// Should have empty tech_stack (no known technologies)
+		expect(result.tech_stack).toEqual([]);
+
+		// Should have empty spawn_instructions
+		expect(result.spawn_instructions).toEqual([]);
+
+		// Other fields should be empty
+		expect(result.summaries).toEqual({});
+		expect(result.memory_ids).toEqual([]);
+	});
+
+	test("spawn instruction prompts include swarmmail_init", async () => {
+		const packageJson = {
+			dependencies: {
+				zod: "^3.22.4",
+			},
+		};
+
+		writeFileSync(
+			join(testProjectPath, "package.json"),
+			JSON.stringify(packageJson, null, 2),
+		);
+
+		const result = await runResearchPhase("Use Zod", testProjectPath);
+
+		// Prompt should include swarmmail_init (researcher workers need this)
+		const instruction = result.spawn_instructions[0];
+		expect(instruction.prompt).toContain("swarmmail_init");
+		expect(instruction.prompt).toContain("semantic-memory_store");
+	});
+});
+
 describe("Real-world fixture: this repo", () => {
 	test("discovers tools and versions from actual repo", async () => {
 		// Use the plugin package directory, not monorepo root
@@ -540,5 +692,10 @@ describe("Real-world fixture: this repo", () => {
 		expect(result.summaries).toBeDefined();
 		expect(result.memory_ids).toBeDefined();
 		expect(Array.isArray(result.memory_ids)).toBe(true);
+
+		// NEW: Should have spawn_instructions
+		expect(result.spawn_instructions).toBeDefined();
+		expect(Array.isArray(result.spawn_instructions)).toBe(true);
+		expect(result.spawn_instructions.length).toBeGreaterThan(0);
 	});
 });