opencode-swarm-plugin 0.23.6 → 0.25.0

package/src/swarm-decompose.ts

@@ -905,8 +905,345 @@ export class DecompositionError extends SwarmError {
   }
 }
 
+/**
+ * Planning phase state machine for Socratic planning
+ */
+type PlanningPhase = "questioning" | "alternatives" | "recommendation" | "ready";
+
+/**
+ * Planning mode that determines interaction level
+ */
+type PlanningMode = "socratic" | "fast" | "auto" | "confirm-only";
+
+/**
+ * Socratic planning output structure
+ */
+interface SocraticPlanOutput {
+  mode: PlanningMode;
+  phase: PlanningPhase;
+  questions?: Array<{ question: string; options?: string[] }>;
+  alternatives?: Array<{
+    name: string;
+    description: string;
+    tradeoffs: string;
+  }>;
+  recommendation?: { approach: string; reasoning: string };
+  memory_context?: string;
+  codebase_context?: {
+    git_status?: string;
+    relevant_files?: string[];
+  };
+  ready_to_decompose: boolean;
+  next_action?: string;
+}
+
+/**
+ * Interactive planning tool with Socratic questioning
+ *
+ * Implements a planning phase BEFORE decomposition that:
+ * 1. Gathers context (git, files, semantic memory)
+ * 2. Asks clarifying questions (socratic mode)
+ * 3. Explores alternatives with tradeoffs
+ * 4. Recommends an approach with reasoning
+ * 5. Confirms before proceeding to decomposition
+ *
+ * Modes:
+ * - socratic: Full interactive planning with questions, alternatives, recommendations
+ * - fast: Skip brainstorming, go straight to decomposition with memory context
+ * - auto: Auto-select best approach based on task keywords, minimal interaction
+ * - confirm-only: Show decomposition, wait for yes/no confirmation
+ *
+ * Based on the Socratic Planner Pattern from obra/superpowers.
+ *
+ * @see docs/analysis-socratic-planner-pattern.md
+ */
+export const swarm_plan_interactive = tool({
+  description:
+    "Interactive planning phase with Socratic questioning before decomposition. Supports multiple modes from full interactive to auto-proceed.",
+  args: {
+    task: tool.schema.string().min(1).describe("The task to plan"),
+    mode: tool.schema
+      .enum(["socratic", "fast", "auto", "confirm-only"])
+      .default("socratic")
+      .describe("Planning mode: socratic (full), fast (skip questions), auto (minimal), confirm-only (single yes/no)"),
+    context: tool.schema
+      .string()
+      .optional()
+      .describe("Optional additional context about the task"),
+    user_response: tool.schema
+      .string()
+      .optional()
+      .describe("User's response to a previous question (for multi-turn socratic mode)"),
+    phase: tool.schema
+      .enum(["questioning", "alternatives", "recommendation", "ready"])
+      .optional()
+      .describe("Current planning phase (for resuming multi-turn interaction)"),
+  },
+  async execute(args): Promise<string> {
+    // Import needed modules
+    const { selectStrategy, formatStrategyGuidelines, STRATEGIES } =
+      await import("./swarm-strategies");
+    const { formatMemoryQueryForDecomposition } = await import("./learning");
+
+    // Determine current phase
+    const currentPhase: PlanningPhase = args.phase || "questioning";
+    const mode: PlanningMode = args.mode || "socratic";
+
+    // Gather context - always do this regardless of mode
+    let memoryContext = "";
+    let codebaseContext: { git_status?: string; relevant_files?: string[] } = {};
+
+    // Generate semantic memory query instruction
+    // Note: Semantic memory is accessed via OpenCode's global tools, not as a direct import
+    // The coordinator should call semantic-memory_find before calling this tool
+    // and pass results in the context parameter
+    try {
+      const memoryQuery = formatMemoryQueryForDecomposition(args.task, 3);
+      memoryContext = `[Memory Query Instruction]\n${memoryQuery.instruction}\nQuery: "${memoryQuery.query}"\nLimit: ${memoryQuery.limit}`;
+    } catch (error) {
+      console.warn("[swarm_plan_interactive] Memory query formatting failed:", error);
+    }
+
+    // Get git context for codebase awareness
+    try {
+      const gitResult = await Bun.$`git status --short`.quiet().nothrow();
+      if (gitResult.exitCode === 0) {
+        codebaseContext.git_status = gitResult.stdout.toString().trim();
+      }
+    } catch (error) {
+      // Git not available or not in a git repo - continue without it
+    }
+
+    // Fast mode: Skip to recommendation
+    if (mode === "fast") {
+      const strategyResult = selectStrategy(args.task);
+      const guidelines = formatStrategyGuidelines(strategyResult.strategy);
+
+      const output: SocraticPlanOutput = {
+        mode: "fast",
+        phase: "ready",
+        recommendation: {
+          approach: strategyResult.strategy,
+          reasoning: `${strategyResult.reasoning}\n\n${guidelines}`,
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: true,
+        next_action: "Proceed to swarm_decompose or swarm_delegate_planning",
+      };
+
+      return JSON.stringify(output, null, 2);
+    }
+
+    // Auto mode: Auto-select and proceed
+    if (mode === "auto") {
+      const strategyResult = selectStrategy(args.task);
+
+      const output: SocraticPlanOutput = {
+        mode: "auto",
+        phase: "ready",
+        recommendation: {
+          approach: strategyResult.strategy,
+          reasoning: `Auto-selected based on task keywords: ${strategyResult.reasoning}`,
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: true,
+        next_action: "Auto-proceeding to decomposition",
+      };
+
+      return JSON.stringify(output, null, 2);
+    }
+
+    // Confirm-only mode: Generate decomposition, show it, wait for yes/no
+    if (mode === "confirm-only") {
+      // This mode will be handled by calling swarm_delegate_planning
+      // and then asking for confirmation on the result
+      const output: SocraticPlanOutput = {
+        mode: "confirm-only",
+        phase: "ready",
+        recommendation: {
+          approach: "Will generate decomposition for your review",
+          reasoning: "Use swarm_delegate_planning to generate the plan, then present it for yes/no confirmation",
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: false,
+        next_action: "Call swarm_delegate_planning, then show result and ask for confirmation",
+      };
+
+      return JSON.stringify(output, null, 2);
+    }
+
+    // Socratic mode: Full interactive planning
+    // Phase 1: Questioning
+    if (currentPhase === "questioning") {
+      // Analyze task to identify what needs clarification
+      const taskLower = args.task.toLowerCase();
+      const questions: Array<{ question: string; options?: string[] }> = [];
+
+      // Check for vague task signals from skill
+      const isVague = {
+        noFiles: !taskLower.includes("src/") && !taskLower.includes("file"),
+        vagueVerb:
+          taskLower.includes("improve") ||
+          taskLower.includes("fix") ||
+          taskLower.includes("update") ||
+          taskLower.includes("make better"),
+        noSuccessCriteria: !taskLower.includes("test") && !taskLower.includes("verify"),
+      };
+
+      // Generate clarifying questions (one at a time)
+      if (isVague.noFiles) {
+        questions.push({
+          question: "Which part of the codebase should this change affect?",
+          options: [
+            "Core functionality (src/)",
+            "UI components (components/)",
+            "API routes (app/api/)",
+            "Configuration and tooling",
+            "Tests",
+          ],
+        });
+      } else if (isVague.vagueVerb) {
+        questions.push({
+          question: "What specific change are you looking for?",
+          options: [
+            "Add new functionality",
+            "Modify existing behavior",
+            "Remove/deprecate something",
+            "Refactor without behavior change",
+            "Fix a bug",
+          ],
+        });
+      } else if (isVague.noSuccessCriteria) {
+        questions.push({
+          question: "How will we know this task is complete?",
+          options: [
+            "All tests pass",
+            "Feature works as demonstrated",
+            "Code review approved",
+            "Documentation updated",
+            "Performance target met",
+          ],
+        });
+      }
+
+      // If task seems clear, move to alternatives phase
+      if (questions.length === 0) {
+        const output: SocraticPlanOutput = {
+          mode: "socratic",
+          phase: "alternatives",
+          memory_context: memoryContext || undefined,
+          codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+          ready_to_decompose: false,
+          next_action: "Task is clear. Call again with phase=alternatives to explore approaches",
+        };
+        return JSON.stringify(output, null, 2);
+      }
+
+      // Return first question only (Socratic principle: one at a time)
+      const output: SocraticPlanOutput = {
+        mode: "socratic",
+        phase: "questioning",
+        questions: [questions[0]],
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: false,
+        next_action: "User should answer this question, then call again with user_response",
+      };
+
+      return JSON.stringify(output, null, 2);
+    }
+
+    // Phase 2: Alternatives
+    if (currentPhase === "alternatives") {
+      const strategyResult = selectStrategy(args.task);
+
+      // Build 2-3 alternative approaches
+      const alternatives: Array<{
+        name: string;
+        description: string;
+        tradeoffs: string;
+      }> = [];
+
+      // Primary recommendation
+      alternatives.push({
+        name: strategyResult.strategy,
+        description: strategyResult.reasoning,
+        tradeoffs: `Confidence: ${(strategyResult.confidence * 100).toFixed(0)}%. ${STRATEGIES[strategyResult.strategy].description}`,
+      });
+
+      // Add top 2 alternatives
+      for (let i = 0; i < Math.min(2, strategyResult.alternatives.length); i++) {
+        const alt = strategyResult.alternatives[i];
+        alternatives.push({
+          name: alt.strategy,
+          description: STRATEGIES[alt.strategy].description,
+          tradeoffs: `Match score: ${alt.score}. ${STRATEGIES[alt.strategy].antiPatterns[0] || "Consider trade-offs carefully"}`,
+        });
+      }
+
+      const output: SocraticPlanOutput = {
+        mode: "socratic",
+        phase: "alternatives",
+        alternatives,
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: false,
+        next_action: "User should choose an approach, then call again with phase=recommendation",
+      };
+
+      return JSON.stringify(output, null, 2);
+    }
+
+    // Phase 3: Recommendation
+    if (currentPhase === "recommendation") {
+      const strategyResult = selectStrategy(args.task);
+      const guidelines = formatStrategyGuidelines(strategyResult.strategy);
+
+      const output: SocraticPlanOutput = {
+        mode: "socratic",
+        phase: "recommendation",
+        recommendation: {
+          approach: strategyResult.strategy,
+          reasoning: `Based on your input and task analysis:\n\n${strategyResult.reasoning}\n\n${guidelines}`,
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: false,
+        next_action: "User should confirm to proceed. Then call again with phase=ready",
+      };
+
+      return JSON.stringify(output, null, 2);
+    }
+
+    // Phase 4: Ready
+    if (currentPhase === "ready") {
+      const output: SocraticPlanOutput = {
+        mode: "socratic",
+        phase: "ready",
+        recommendation: {
+          approach: "Confirmed by user",
+          reasoning: "Ready to proceed with decomposition",
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: true,
+        next_action: "Proceed to swarm_decompose or swarm_delegate_planning",
+      };
+
+      return JSON.stringify(output, null, 2);
+    }
+
+    // Should never reach here
+    throw new Error(`Invalid planning phase: ${currentPhase}`);
+  },
+});
+
 export const decomposeTools = {
   swarm_decompose,
   swarm_validate_decomposition,
   swarm_delegate_planning,
+  swarm_plan_interactive,
 };

package/src/swarm-orchestrate.ts

@@ -871,30 +871,8 @@ export const swarm_progress = tool({
           });
           await appendEvent(event, args.project_key);
 
-          // Update swarm_contexts table
-          const { getDatabase } = await import("swarm-mail");
-          const db = await getDatabase(args.project_key);
-          const now = Date.now();
-          await db.query(
-            `INSERT INTO swarm_contexts (id, epic_id, bead_id, strategy, files, dependencies, directives, recovery, created_at, updated_at)
-             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
-             ON CONFLICT (id) DO UPDATE SET
-               files = EXCLUDED.files,
-               recovery = EXCLUDED.recovery,
-               updated_at = EXCLUDED.updated_at`,
-            [
-              args.bead_id,
-              epicId,
-              args.bead_id,
-              checkpoint.strategy,
-              JSON.stringify(checkpoint.files),
-              JSON.stringify(checkpoint.dependencies),
-              JSON.stringify(checkpoint.directives),
-              JSON.stringify(checkpoint.recovery),
-              now,
-              now,
-            ],
-          );
+          // NOTE: The event handler (handleSwarmCheckpointed in store.ts) updates
+          // the swarm_contexts table. We follow event sourcing pattern here.
           checkpointCreated = true;
         } catch (error) {
           // Non-fatal - log and continue
@@ -2114,31 +2092,11 @@ export const swarm_checkpoint = tool({
 
       await appendEvent(event, args.project_key);
 
-      // Update swarm_contexts table for fast recovery
-      const { getDatabase } = await import("swarm-mail");
-      const db = await getDatabase(args.project_key);
+      // NOTE: The event handler (handleSwarmCheckpointed in store.ts) updates
+      // the swarm_contexts table. We don't write directly here to follow
+      // event sourcing pattern - single source of truth is the event log.
 
       const now = Date.now();
-      await db.query(
-        `INSERT INTO swarm_contexts (id, epic_id, bead_id, strategy, files, dependencies, directives, recovery, created_at, updated_at)
-         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
-         ON CONFLICT (id) DO UPDATE SET
-           files = EXCLUDED.files,
-           recovery = EXCLUDED.recovery,
-           updated_at = EXCLUDED.updated_at`,
-        [
-          args.bead_id, // Use bead_id as unique ID
-          args.epic_id,
-          args.bead_id,
-          checkpoint.strategy,
-          JSON.stringify(checkpoint.files),
-          JSON.stringify(checkpoint.dependencies),
-          JSON.stringify(checkpoint.directives),
-          JSON.stringify(checkpoint.recovery),
-          now,
-          now,
-        ],
-      );
 
       return JSON.stringify(
         {
@@ -2227,15 +2185,21 @@ export const swarm_recover = tool({
       }
 
       const row = result.rows[0];
+      // PGLite auto-parses JSON columns, so we need to handle both cases
+      const parseIfString = <T>(val: unknown): T =>
+        typeof val === "string" ? JSON.parse(val) : (val as T);
+
       const context: SwarmBeadContext = {
         id: row.id,
         epic_id: row.epic_id,
         bead_id: row.bead_id,
         strategy: row.strategy as SwarmBeadContext["strategy"],
-        files: JSON.parse(row.files),
-        dependencies: JSON.parse(row.dependencies),
-        directives: JSON.parse(row.directives),
-        recovery: JSON.parse(row.recovery),
+        files: parseIfString<string[]>(row.files),
+        dependencies: parseIfString<string[]>(row.dependencies),
+        directives: parseIfString<SwarmBeadContext["directives"]>(
+          row.directives,
+        ),
+        recovery: parseIfString<SwarmBeadContext["recovery"]>(row.recovery),
         created_at: row.created_at,
         updated_at: row.updated_at,
       };

package/src/swarm-prompts.ts

@@ -273,13 +273,11 @@ Only modify these files. Need others? Message the coordinator.
 
 {error_context}
 
-## [MANDATORY: SWARM MAIL INITIALIZATION]
+## [MANDATORY SURVIVAL CHECKLIST]
 
-**CRITICAL: YOU MUST INITIALIZE SWARM MAIL BEFORE DOING ANY WORK.**
+**CRITICAL: Follow this checklist IN ORDER. Each step builds on the previous.**
 
-This is your FIRST step - before reading files, before planning, before ANY other action.
-
-### Step 1: Initialize (REQUIRED - DO THIS FIRST)
+### Step 1: Initialize Coordination (REQUIRED - DO THIS FIRST)
 \`\`\`
 swarmmail_init(project_path="{project_path}", task_description="{bead_id}: {subtask_title}")
 \`\`\`
@@ -292,26 +290,124 @@ swarmmail_init(project_path="{project_path}", task_description="{bead_id}: {subt
 
 **If you skip this step, your work will not be tracked and swarm_complete will fail.**
 
-## [SWARM MAIL USAGE]
+### Step 2: Query Past Learnings (BEFORE starting work)
+\`\`\`
+semantic-memory_find(query="<keywords from your task>", limit=5)
+\`\`\`
 
-After initialization, use Swarm Mail for coordination:
+**Check if past agents solved similar problems.** Search for:
+- Error messages if debugging
+- Domain concepts (e.g., "authentication", "caching")
+- Technology stack (e.g., "Next.js", "React")
+- Patterns (e.g., "event sourcing", "validation")
 
-### Check Inbox Regularly
+**Past learnings save time and prevent repeating mistakes.**
+
+### Step 3: Load Relevant Skills (if available)
 \`\`\`
-swarmmail_inbox()  # Check for coordinator messages
-swarmmail_read_message(message_id=N)  # Read specific message
+skills_list()  # See what skills exist
+skills_use(name="<relevant-skill>", context="<your task>")  # Load skill
 \`\`\`
 
-### Report Progress (REQUIRED - don't work silently)
+**Common skill triggers:**
+- Writing tests? → \`skills_use(name="testing-patterns")\`
+- Breaking dependencies? → \`skills_use(name="testing-patterns")\`
+- Multi-agent coordination? → \`skills_use(name="swarm-coordination")\`
+- Building a CLI? → \`skills_use(name="cli-builder")\`
+
+### Step 4: Reserve Your Files (YOU reserve, not coordinator)
 \`\`\`
-swarmmail_send(
-  to=["coordinator"],
-  subject="Progress: {bead_id}",
-  body="<what you did, blockers, questions>",
-  thread_id="{epic_id}"
+swarmmail_reserve(
+  paths=[{file_list}],
+  reason="{bead_id}: {subtask_title}",
+  exclusive=true
+)
+\`\`\`
+
+**Workers reserve their own files.** This prevents edit conflicts with other agents.
+
+### Step 5: Do the Work
+- Read your assigned files
+- Implement changes
+- Verify (typecheck if applicable)
+
+### Step 6: Report Progress at Milestones
+\`\`\`
+swarm_progress(
+  project_key="{project_path}",
+  agent_name="<your-agent-name>",
+  bead_id="{bead_id}",
+  status="in_progress",
+  progress_percent=25,  # or 50, 75
+  message="<what you just completed>"
 )
 \`\`\`
 
+**Report at 25%, 50%, 75% completion.** This:
+- Triggers auto-checkpoint (saves context)
+- Keeps coordinator informed
+- Prevents silent failures
+
+### Step 7: Manual Checkpoint BEFORE Risky Operations
+\`\`\`
+swarm_checkpoint(
+  project_key="{project_path}",
+  agent_name="<your-agent-name>",
+  bead_id="{bead_id}"
+)
+\`\`\`
+
+**Call BEFORE:**
+- Large refactors
+- File deletions
+- Breaking API changes
+- Anything that might fail catastrophically
+
+**Checkpoints preserve context so you can recover if things go wrong.**
+
+### Step 8: Store Learnings (if you discovered something)
+\`\`\`
+semantic-memory_store(
+  information="<what you learned, WHY it matters, how to apply it>",
+  metadata="<tags: domain, tech-stack, pattern-type>"
+)
+\`\`\`
+
+**Store:**
+- Tricky bugs you solved (root cause + solution)
+- Project-specific patterns or domain rules
+- Tool/library gotchas and workarounds
+- Failed approaches (anti-patterns to avoid)
+
+**Don't store generic knowledge.** Store the WHY, not just the WHAT.
+
+### Step 9: Complete (REQUIRED - releases reservations)
+\`\`\`
+swarm_complete(
+  project_key="{project_path}",
+  agent_name="<your-agent-name>",
+  bead_id="{bead_id}",
+  summary="<what you accomplished>",
+  files_touched=["list", "of", "files"]
+)
+\`\`\`
+
+**This automatically:**
+- Runs UBS bug scan
+- Releases file reservations
+- Records learning signals
+- Notifies coordinator
+
+**DO NOT manually close the bead with beads_close.** Use swarm_complete.
+
+## [SWARM MAIL COMMUNICATION]
+
+### Check Inbox Regularly
+\`\`\`
+swarmmail_inbox()  # Check for coordinator messages
+swarmmail_read_message(message_id=N)  # Read specific message
+\`\`\`
+
 ### When Blocked
 \`\`\`
 swarmmail_send(
@@ -324,42 +420,48 @@ swarmmail_send(
 beads_update(id="{bead_id}", status="blocked")
 \`\`\`
 
-### Release Files When Done
+### Report Issues to Other Agents
+\`\`\`
+swarmmail_send(
+  to=["OtherAgent", "coordinator"],
+  subject="Issue in {bead_id}",
+  body="<describe problem, don't fix their code>",
+  thread_id="{epic_id}"
+)
+\`\`\`
+
+### Manual Release (if needed)
 \`\`\`
-swarmmail_release()  # Or let swarm_complete handle it
+swarmmail_release()  # Manually release reservations
 \`\`\`
 
+**Note:** \`swarm_complete\` automatically releases reservations. Only use manual release if aborting work.
+
 ## [OTHER TOOLS]
 ### Beads
 - beads_update(id, status) - Mark blocked if stuck
 - beads_create(title, type) - Log new bugs found
 
-### Skills (if available)
+### Skills
 - skills_list() - Discover available skills
 - skills_use(name) - Activate skill for specialized guidance
-
-### Completion (REQUIRED)
-- swarm_complete(project_key, agent_name, bead_id, summary, files_touched)
-
-## [LEARNING]
-As you work, note reusable patterns, best practices, or domain insights:
-- If you discover something that would help future agents, consider creating a skill
-- Use skills_create to codify patterns for the project
-- Good skills have clear "when to use" descriptions with actionable instructions
-- Skills make swarms smarter over time
-
-## [WORKFLOW]
-1. **swarmmail_init** - Initialize session (MANDATORY FIRST STEP)
-2. Read assigned files
-3. Implement changes
-4. **swarmmail_send** - Report progress to coordinator
-5. Verify (typecheck)
-6. **swarm_complete** - Mark done, release reservations
-
-**CRITICAL REQUIREMENTS:**
-- Step 1 (swarmmail_init) is NON-NEGOTIABLE - do it before anything else
-- Never work silently - send progress updates via swarmmail_send every significant milestone
-- If you complete without initializing, swarm_complete will detect this and warn/fail
+- skills_create(name) - Create new skill (if you found a reusable pattern)
+
+## [CRITICAL REQUIREMENTS]
+
+**NON-NEGOTIABLE:**
+1. Step 1 (swarmmail_init) MUST be first - do it before anything else
+2. Step 2 (semantic-memory_find) MUST happen before starting work
+3. Step 4 (swarmmail_reserve) - YOU reserve files, not coordinator
+4. Step 6 (swarm_progress) - Report at milestones, don't work silently
+5. Step 9 (swarm_complete) - Use this to close, NOT beads_close
+
+**If you skip these steps:**
+- Your work won't be tracked (swarm_complete will fail)
+- You'll waste time repeating solved problems (no semantic memory query)
+- Edit conflicts with other agents (no file reservation)
+- Lost work if you crash (no checkpoints)
+- Future agents repeat your mistakes (no learnings stored)
 
 Begin now.`;