opencode-swarm-plugin 0.38.0 → 0.39.1

package/dist/plugin.js

@@ -22198,6 +22198,7 @@ __export(exports_eval_capture, {
   captureHumanFeedback: () => captureHumanFeedback,
   captureDecomposition: () => captureDecomposition,
   captureCoordinatorEvent: () => captureCoordinatorEvent,
+  captureCompactionEvent: () => captureCompactionEvent,
   appendEvalRecord: () => appendEvalRecord,
   SubtaskOutcomeSchema: () => SubtaskOutcomeSchema,
   EvalRecordSchema: () => EvalRecordSchema,
@@ -22406,6 +22407,17 @@ function captureCoordinatorEvent(event) {
 `;
   fs.appendFileSync(sessionPath, line, "utf-8");
 }
+function captureCompactionEvent(params) {
+  const event = {
+    session_id: params.session_id,
+    epic_id: params.epic_id,
+    timestamp: new Date().toISOString(),
+    event_type: "COMPACTION",
+    compaction_type: params.compaction_type,
+    payload: params.payload
+  };
+  captureCoordinatorEvent(event);
+}
 function readSessionEvents(sessionId) {
   const sessionPath = getSessionPath(sessionId);
   if (!fs.existsSync(sessionPath)) {
@@ -22517,6 +22529,20 @@ var init_eval_capture = __esm(() => {
         "epic_complete"
       ]),
       payload: exports_external.any()
+    }),
+    exports_external.object({
+      session_id: exports_external.string(),
+      epic_id: exports_external.string(),
+      timestamp: exports_external.string(),
+      event_type: exports_external.literal("COMPACTION"),
+      compaction_type: exports_external.enum([
+        "detection_complete",
+        "prompt_generated",
+        "context_injected",
+        "resumption_started",
+        "tool_call_tracked"
+      ]),
+      payload: exports_external.any()
     })
   ]);
   CoordinatorSessionSchema = exports_external.object({
@@ -42303,7 +42329,7 @@ var swarm_delegate_planning = tool({
     strategy: tool.schema.enum(["auto", "file-based", "feature-based", "risk-based"]).optional().default("auto").describe("Decomposition strategy (default: auto-detect)"),
     query_cass: tool.schema.boolean().optional().default(true).describe("Query CASS for similar past tasks (default: true)")
   },
-  async execute(args) {
+  async execute(args, _ctx) {
     const { selectStrategy: selectStrategy2, formatStrategyGuidelines: formatStrategyGuidelines2 } = await Promise.resolve().then(() => (init_swarm_strategies(), exports_swarm_strategies));
     const { formatMemoryQueryForDecomposition: formatMemoryQueryForDecomposition2 } = await Promise.resolve().then(() => (init_learning(), exports_learning));
     const { listSkills: listSkills2, getSkillsContextForSwarm: getSkillsContextForSwarm2, findRelevantSkills: findRelevantSkills2 } = await Promise.resolve().then(() => (init_skills(), exports_skills));
@@ -42319,7 +42345,7 @@ var swarm_delegate_planning = tool({
     }
     try {
       captureCoordinatorEvent({
-        session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+        session_id: _ctx.sessionID || "unknown",
         epic_id: "planning",
         timestamp: new Date().toISOString(),
         event_type: "DECISION",
@@ -44635,7 +44661,7 @@ var swarm_review_feedback = tool({
     summary: exports_external.string().optional().describe("Review summary"),
     issues: exports_external.string().optional().describe("JSON array of ReviewIssue objects (for needs_changes)")
   },
-  async execute(args) {
+  async execute(args, _ctx) {
     let parsedIssues = [];
     if (args.issues) {
       try {
@@ -44658,7 +44684,7 @@ var swarm_review_feedback = tool({
       markReviewApproved(args.task_id);
       try {
         captureCoordinatorEvent({
-          session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+          session_id: _ctx.sessionID || "unknown",
           epic_id: epicId,
           timestamp: new Date().toISOString(),
           event_type: "DECISION",
@@ -44696,7 +44722,7 @@ You may now complete the task with \`swarm_complete\`.`,
     const remaining = MAX_REVIEW_ATTEMPTS - attemptNumber;
     try {
       captureCoordinatorEvent({
-        session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+        session_id: _ctx.sessionID || "unknown",
         epic_id: epicId,
         timestamp: new Date().toISOString(),
         event_type: "DECISION",
@@ -45668,10 +45694,29 @@ Files touched: ${args.files_touched?.join(", ") || "none recorded"}`,
           reason: "No files_owned contract found (non-epic subtask or decomposition event missing)"
         }
       };
+      try {
+        const { captureSubtaskOutcome: captureSubtaskOutcome2 } = await Promise.resolve().then(() => (init_eval_capture(), exports_eval_capture));
+        const durationMs2 = args.start_time ? Date.now() - args.start_time : 0;
+        const evalEpicId = cell.parent_id || epicId2;
+        captureSubtaskOutcome2({
+          epicId: evalEpicId,
+          projectPath: args.project_key,
+          beadId: args.bead_id,
+          title: cell.title,
+          plannedFiles: args.planned_files || [],
+          actualFiles: args.files_touched || [],
+          durationMs: durationMs2,
+          errorCount: args.error_count || 0,
+          retryCount: args.retry_count || 0,
+          success: true
+        });
+      } catch (error45) {
+        console.warn("[swarm_complete] Failed to capture subtask outcome:", error45);
+      }
       try {
         const durationMs2 = args.start_time ? Date.now() - args.start_time : 0;
         captureCoordinatorEvent({
-          session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+          session_id: _ctx.sessionID || "unknown",
           epic_id: epicId2,
           timestamp: new Date().toISOString(),
           event_type: "OUTCOME",
@@ -45753,7 +45798,7 @@ ${errorStack.slice(0, 1000)}
       try {
         const durationMs = args.start_time ? Date.now() - args.start_time : 0;
         captureCoordinatorEvent({
-          session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+          session_id: _ctx.sessionID || "unknown",
           epic_id: epicId,
           timestamp: new Date().toISOString(),
           event_type: "OUTCOME",
@@ -45820,7 +45865,9 @@ var swarm_record_outcome = tool({
       "user_cancelled",
       "unknown"
     ]).optional().describe("Failure classification (only when success=false). Auto-classified if not provided."),
-    failure_details: tool.schema.string().optional().describe("Detailed failure context (error message, stack trace, etc.)")
+    failure_details: tool.schema.string().optional().describe("Detailed failure context (error message, stack trace, etc.)"),
+    project_path: tool.schema.string().optional().describe("Project path (for finalizing eval records when all subtasks complete)"),
+    epic_id: tool.schema.string().optional().describe("Epic ID (for finalizing eval records when all subtasks complete)")
   },
   async execute(args) {
     const signals = {
@@ -45842,6 +45889,18 @@ var swarm_record_outcome = tool({
     const validated = OutcomeSignalsSchema.parse(signals);
     const scored = scoreImplicitFeedback(validated, DEFAULT_LEARNING_CONFIG);
     const errorStats = await globalErrorAccumulator.getErrorStats(args.bead_id);
+    let finalizedRecord = null;
+    if (args.project_path && args.epic_id) {
+      try {
+        const { finalizeEvalRecord: finalizeEvalRecord2 } = await Promise.resolve().then(() => (init_eval_capture(), exports_eval_capture));
+        finalizedRecord = finalizeEvalRecord2({
+          epicId: args.epic_id,
+          projectPath: args.project_path
+        });
+      } catch (error45) {
+        console.warn("[swarm_record_outcome] Failed to finalize eval record:", error45);
+      }
+    }
     const criteriaToScore = args.criteria ?? [
       "type_safe",
       "no_bugs",
@@ -45883,6 +45942,7 @@ var swarm_record_outcome = tool({
         accumulated_errors: errorStats.total,
         unresolved_errors: errorStats.unresolved
       },
+      finalized_eval_record: finalizedRecord || undefined,
       note: "Feedback events should be stored for criterion weight calculation. Use learning.ts functions to apply weights."
     }, null, 2);
   }
@@ -45914,12 +45974,31 @@ async function runResearchPhase(task, projectPath, options2) {
   if (techStack.length === 0) {
     return {
       tech_stack: [],
+      spawn_instructions: [],
       summaries: {},
       memory_ids: []
     };
   }
+  const spawnInstructions = [];
+  for (const tech of techStack) {
+    const researchId = `research-${tech}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    const prompt = formatResearcherPrompt({
+      research_id: researchId,
+      epic_id: "standalone-research",
+      tech_stack: [tech],
+      project_path: projectPath,
+      check_upgrades: options2?.checkUpgrades ?? false
+    });
+    spawnInstructions.push({
+      research_id: researchId,
+      tech,
+      prompt,
+      subagent_type: "swarm/researcher"
+    });
+  }
   return {
     tech_stack: techStack,
+    spawn_instructions: spawnInstructions,
     summaries: {},
     memory_ids: []
   };
@@ -47153,7 +47232,7 @@ var swarm_spawn_subtask = tool({
     }).optional().describe("Recovery context from checkpoint compaction"),
     model: tool.schema.string().optional().describe("Optional explicit model override (auto-selected if not provided)")
   },
-  async execute(args) {
+  async execute(args, _ctx) {
     const prompt = formatSubtaskPromptV2({
       bead_id: args.bead_id,
       epic_id: args.epic_id,
@@ -47182,7 +47261,7 @@ var swarm_spawn_subtask = tool({
     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");
     try {
       captureCoordinatorEvent({
-        session_id: process.env.OPENCODE_SESSION_ID || "unknown",
+        session_id: _ctx.sessionID || "unknown",
         epic_id: args.epic_id,
         timestamp: new Date().toISOString(),
         event_type: "DECISION",
@@ -63331,9 +63410,21 @@ function getLog() {
   }
   return _logger;
 }
-var SWARM_COMPACTION_CONTEXT = `## \uD83D\uDC1D SWARM ACTIVE - You Are The COORDINATOR
+var SWARM_COMPACTION_CONTEXT = `
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│             \uD83D\uDC1D  YOU ARE THE COORDINATOR  \uD83D\uDC1D                 │
+│                                                             │
+│             NOT A WORKER. NOT AN IMPLEMENTER.               │
+│                  YOU ORCHESTRATE.                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+
+## \uD83C\uDFAF NON-NEGOTIABLE: YOU ARE THE COORDINATOR
 
-Context was compacted but the swarm is still running. You are the **COORDINATOR**.
+Context was compacted but the swarm is still running. **YOU ARE THE COORDINATOR.**
+
+Your role is ORCHESTRATION, not implementation. When you catch yourself about to do work directly, STOP.
 
 ### ⛔ NEVER DO THESE (Coordinator Anti-Patterns)
 
@@ -63344,9 +63435,27 @@ Context was compacted but the swarm is still running. You are the **COORDINATOR*
 - ❌ **NEVER** implement features yourself - SPAWN A WORKER
 - ❌ **NEVER** "just do it myself to save time" - NO. SPAWN A WORKER.
 - ❌ **NEVER** reserve files with \`swarmmail_reserve\` - Workers reserve files
+- ❌ **NEVER** fetch files/docs directly - SPAWN A RESEARCHER
 
 **If you catch yourself about to edit a file, STOP. Use \`swarm_spawn_subtask\` instead.**
 
+### \uD83D\uDEAB FORBIDDEN TOOLS (Coordinators MUST delegate these)
+
+**NEVER use these tools directly. ALWAYS spawn a researcher worker via \`swarm_spawn_researcher\`:**
+
+**Repository fetching:**
+- \`repo-crawl_file\`, \`repo-crawl_readme\`, \`repo-crawl_search\`, \`repo-crawl_structure\`, \`repo-crawl_tree\`
+- \`repo-autopsy_*\` (all repo-autopsy tools)
+
+**Web/documentation fetching:**
+- \`webfetch\`, \`fetch_fetch\`
+- \`context7_resolve-library-id\`, \`context7_get-library-docs\`
+
+**Knowledge base:**
+- \`pdf-brain_search\`, \`pdf-brain_read\`
+
+**If you need external data:** Use \`swarm_spawn_researcher\` with a clear research task. The researcher will fetch, summarize, and return findings.
+
 ### ✅ ALWAYS DO THESE (Coordinator Checklist)
 
 On resume, execute this checklist IN ORDER:
@@ -63396,6 +63505,87 @@ Extract from session context:
 - **Review work** - Use \`swarm_review\` and \`swarm_review_feedback\` for completed work
 - **Close the loop** - When all subtasks done, verify and close the epic
 
+**You are the COORDINATOR. You orchestrate. You do NOT implement. Spawn workers.**
+
+---
+
+## \uD83D\uDCCB FULL COORDINATOR WORKFLOW (Reference)
+
+You are ALWAYS swarming. Here is the complete workflow for any new work:
+
+### Phase 1.5: Research Phase (FOR COMPLEX TASKS)
+
+**If the task requires understanding unfamiliar technologies, spawn a researcher FIRST:**
+
+\`\`\`
+swarm_spawn_researcher(
+  research_id="research-<topic>",
+  epic_id="<epic-id>",
+  tech_stack=["<technology>"],
+  project_path="<path>"
+)
+// Then spawn with Task(subagent_type="swarm/researcher", prompt="<from above>")
+\`\`\`
+
+### Phase 2: Knowledge Gathering
+
+\`\`\`
+semantic-memory_find(query="<task keywords>", limit=5)   # Past learnings
+cass_search(query="<task description>", limit=5)         # Similar past tasks  
+skills_list()                                            # Available skills
+\`\`\`
+
+### 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.
+
+### Phase 6: Spawn Workers
+
+\`\`\`
+swarm_spawn_subtask(bead_id, epic_id, title, files, shared_context, project_path)
+Task(subagent_type="swarm/worker", prompt="<from above>")
+\`\`\`
+
+### Phase 7: MANDATORY Review Loop
+
+**AFTER EVERY Task() RETURNS:**
+
+1. \`swarmmail_inbox()\` - Check for messages
+2. \`swarm_review(project_key, epic_id, task_id, files_touched)\` - Generate review
+3. Evaluate against epic goals
+4. \`swarm_review_feedback(project_key, task_id, worker_id, status, issues)\`
+
+**If needs_changes:**
+\`\`\`
+swarm_spawn_retry(bead_id, epic_id, original_prompt, attempt, issues, diff, files, project_path)
+// Spawn NEW worker with Task() using retry prompt
+// Max 3 attempts before marking task blocked
+\`\`\`
+
+### Phase 8: Complete
+
+\`hive_sync()\` - Sync all cells to git
+
+## 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   |
+
 **You are the COORDINATOR. You orchestrate. You do NOT implement. Spawn workers.**
 `;
 var SWARM_DETECTION_FALLBACK = `## \uD83D\uDC1D Swarm Detection - Check Your Context
@@ -64070,7 +64260,7 @@ var SwarmPlugin = async (input) => {
       if (isInCoordinatorContext()) {
         const ctx = getCoordinatorContext();
         const violation = detectCoordinatorViolation({
-          sessionId: ctx.sessionId || "unknown",
+          sessionId: input2.sessionID || "unknown",
           epicId: ctx.epicId || "unknown",
           toolName,
           toolArgs: output.args,

package/dist/post-compaction-tracker.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Post-Compaction Tool Call Tracker
+ *
+ * Tracks tool calls after compaction resumption to detect coordinator violations
+ * and provide learning signals for eval-driven development.
+ *
+ * ## Purpose
+ *
+ * When context is compacted, the continuation agent needs observation to learn
+ * if it's following coordinator discipline. This tracker:
+ *
+ * 1. Emits resumption_started on first tool call (marks compaction exit)
+ * 2. Tracks up to N tool calls (default 20) with violation detection
+ * 3. Stops tracking after limit to avoid noise in long sessions
+ *
+ * ## Coordinator Violations Detected
+ *
+ * - **Edit/Write**: Coordinators NEVER edit files - spawn worker instead
+ * - **swarmmail_reserve/agentmail_reserve**: Workers reserve, not coordinators
+ *
+ * ## Integration
+ *
+ * Used by compaction hook to wire tool.call events → eval capture.
+ *
+ * @example
+ * ```typescript
+ * const tracker = createPostCompactionTracker({
+ *   sessionId: "session-123",
+ *   epicId: "bd-epic-456",
+ *   onEvent: captureCompactionEvent,
+ * });
+ *
+ * // Wire to OpenCode hook
+ * hooks["tool.call"] = (input) => {
+ *   tracker.trackToolCall({
+ *     tool: input.tool,
+ *     args: input.args,
+ *     timestamp: Date.now(),
+ *   });
+ * };
+ * ```
+ */
+/**
+ * Tool call event structure
+ */
+export interface ToolCallEvent {
+    tool: string;
+    args: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Compaction event payload (matches eval-capture.ts structure)
+ */
+export interface CompactionEvent {
+    session_id: string;
+    epic_id: string;
+    compaction_type: "detection_complete" | "prompt_generated" | "context_injected" | "resumption_started" | "tool_call_tracked";
+    payload: {
+        session_id?: string;
+        epic_id?: string;
+        tool?: string;
+        args?: Record<string, unknown>;
+        call_number?: number;
+        is_coordinator_violation?: boolean;
+        violation_reason?: string;
+        timestamp?: number;
+    };
+}
+/**
+ * Tracker configuration
+ */
+export interface PostCompactionTrackerConfig {
+    sessionId: string;
+    epicId: string;
+    onEvent: (event: CompactionEvent) => void;
+    maxCalls?: number;
+}
+/**
+ * Post-compaction tracker instance
+ */
+export interface PostCompactionTracker {
+    trackToolCall(event: ToolCallEvent): void;
+    isTracking(): boolean;
+}
+/**
+ * Default maximum number of tool calls to track
+ *
+ * Chosen to balance:
+ * - Enough data for pattern detection (20 calls is ~2-3 minutes of coordinator work)
+ * - Avoiding noise pollution in long sessions
+ */
+export declare const DEFAULT_MAX_TRACKED_CALLS = 20;
+/**
+ * Check if tool call is a coordinator violation
+ *
+ * @param tool - Tool name from OpenCode tool.call hook
+ * @returns Violation status with reason if forbidden
+ *
+ * @example
+ * ```typescript
+ * const result = isCoordinatorViolation("edit");
+ * // { isViolation: true, reason: "Coordinators NEVER edit..." }
+ *
+ * const result = isCoordinatorViolation("read");
+ * // { isViolation: false }
+ * ```
+ */
+export declare function isCoordinatorViolation(tool: string): {
+    isViolation: boolean;
+    reason?: string;
+};
+/**
+ * Create a post-compaction tool call tracker
+ *
+ * @example
+ * ```typescript
+ * const tracker = createPostCompactionTracker({
+ *   sessionId: "session-123",
+ *   epicId: "bd-epic-456",
+ *   onEvent: (event) => captureCompactionEvent(event),
+ *   maxCalls: 20
+ * });
+ *
+ * // Track tool calls
+ * tracker.trackToolCall({
+ *   tool: "read",
+ *   args: { filePath: "/test.ts" },
+ *   timestamp: Date.now()
+ * });
+ * ```
+ */
+export declare function createPostCompactionTracker(config: PostCompactionTrackerConfig): PostCompactionTracker;
+//# sourceMappingURL=post-compaction-tracker.d.ts.map

package/dist/post-compaction-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-compaction-tracker.d.ts","sourceRoot":"","sources":["../src/post-compaction-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EACX,oBAAoB,GACpB,kBAAkB,GAClB,kBAAkB,GAClB,oBAAoB,GACpB,mBAAmB,CAAC;IACxB,OAAO,EAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,wBAAwB,CAAC,EAAE,OAAO,CAAC;QACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC1C,UAAU,IAAI,OAAO,CAAC;CACvB;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAoB5C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG;IACpD,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAMA;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,2BAA2B,GAClC,qBAAqB,CA2DvB"}

package/dist/swarm-orchestrate.d.ts

@@ -283,6 +283,8 @@ export declare const swarm_record_outcome: {
             user_cancelled: "user_cancelled";
         }>>;
         failure_details: z.ZodOptional<z.ZodString>;
+        project_path: z.ZodOptional<z.ZodString>;
+        epic_id: z.ZodOptional<z.ZodString>;
     };
     execute(args: {
         bead_id: string;
@@ -295,6 +297,8 @@ export declare const swarm_record_outcome: {
         strategy?: "file-based" | "feature-based" | "risk-based" | "research-based" | undefined;
         failure_mode?: "timeout" | "unknown" | "conflict" | "validation" | "tool_failure" | "context_overflow" | "dependency_blocked" | "user_cancelled" | undefined;
         failure_details?: string | undefined;
+        project_path?: string | undefined;
+        epic_id?: string | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
 };
 /**
@@ -313,12 +317,27 @@ export declare const swarm_record_outcome: {
  * ```
  */
 export declare function extractTechStack(task: string): string[];
+/**
+ * Spawn instruction for a researcher worker
+ */
+export interface ResearchSpawnInstruction {
+    /** Unique ID for this research task */
+    research_id: string;
+    /** Technology being researched */
+    tech: string;
+    /** Full prompt for the researcher agent */
+    prompt: string;
+    /** Agent type for the Task tool */
+    subagent_type: "swarm/researcher";
+}
 /**
  * Research result from documentation discovery phase
  */
 export interface ResearchResult {
     /** Technologies identified and researched */
     tech_stack: string[];
+    /** Spawn instructions for researcher workers */
+    spawn_instructions: ResearchSpawnInstruction[];
     /** Summaries keyed by technology name */
     summaries: Record<string, string>;
     /** Semantic-memory IDs where research is stored */
@@ -731,6 +750,8 @@ export declare const orchestrateTools: {
                 user_cancelled: "user_cancelled";
             }>>;
             failure_details: z.ZodOptional<z.ZodString>;
+            project_path: z.ZodOptional<z.ZodString>;
+            epic_id: z.ZodOptional<z.ZodString>;
         };
         execute(args: {
             bead_id: string;
@@ -743,6 +764,8 @@ export declare const orchestrateTools: {
             strategy?: "file-based" | "feature-based" | "risk-based" | "research-based" | undefined;
             failure_mode?: "timeout" | "unknown" | "conflict" | "validation" | "tool_failure" | "context_overflow" | "dependency_blocked" | "user_cancelled" | undefined;
             failure_details?: string | undefined;
+            project_path?: string | undefined;
+            epic_id?: string | undefined;
         }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
     };
     swarm_research_phase: {

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

@@ -1 +1 @@
-{"version":3,"file":"swarm-orchestrate.d.ts","sourceRoot":"","sources":["../src/swarm-orchestrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,0BAA0B,CAAC;AAqDlC;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,aAAa,CA4BhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EAAE,EACvB,WAAW,EAAE,MAAM,EAAE,GACpB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAqC1C;AAkaD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;CA8JrB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;CAoFvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;CAkHzB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;CA6E1B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwuBzB,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkJ/B,CAAC;AAwBH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAUvD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,mDAAmD;IACnD,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACpC,OAAO,CAAC,cAAc,CAAC,CA2BzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;CAqC/B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;CA6CjC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;CAmClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAmB9B,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;CAoJ9B,CAAC;AA4BH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqG3B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;CAuGxB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgMtB,CAAC;AAMH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAe5B,CAAC"}
+{"version":3,"file":"swarm-orchestrate.d.ts","sourceRoot":"","sources":["../src/swarm-orchestrate.ts"],"names":[],"mappings":"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"}

package/dist/swarm-prompts.d.ts

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