opencode-swarm-plugin 0.15.0 → 0.17.0

package/examples/commands/swarm.md

@@ -27,6 +27,49 @@ Swarm Mail is embedded (no external server needed) and provides:
 
 ## Workflow
 
+### 0. Task Clarity Check (BEFORE ANYTHING ELSE)
+
+**Before decomposing, ask yourself: Is this task clear enough to parallelize?**
+
+**Vague Task Signals:**
+
+- No specific files or components mentioned
+- Vague verbs: "improve", "fix", "update", "make better"
+- Large scope without constraints: "refactor the codebase"
+- Missing success criteria: "add auth" (what kind? OAuth? JWT? Session?)
+- Ambiguous boundaries: "handle errors" (which errors? where?)
+
+**If task is vague, ASK QUESTIONS FIRST:**
+
+```
+The task "<task>" needs clarification before I can decompose it effectively.
+
+1. [Specific question about scope/files/approach]
+
+Options:
+a) [Option A with trade-off]
+b) [Option B with trade-off]
+c) [Option C with trade-off]
+
+Which approach, or should I explore something else?
+```
+
+**Rules for clarifying questions:**
+
+- ONE question at a time (don't overwhelm)
+- Offer 2-3 concrete options when possible
+- Lead with your recommendation and why
+- Wait for answer before next question
+
+**Clear Task Signals (proceed to decompose):**
+
+- Specific files or directories mentioned
+- Concrete action verbs: "add X to Y", "migrate A to B", "extract C from D"
+- Defined scope: "the auth module", "API routes in /api/v2"
+- Measurable outcome: "tests pass", "type errors fixed", "endpoint returns X"
+
+**When in doubt, ask.** A 30-second clarification beats a 30-minute wrong decomposition.
+
 ### 1. Initialize Swarm Mail (FIRST)
 
 ```bash

package/global-skills/swarm-coordination/SKILL.md

@@ -63,6 +63,53 @@ Swarm Mail is embedded (no external server needed) and provides:
 
 **Heuristic:** If you can describe the task in one sentence without "and", don't swarm.
 
+## Task Clarity Check (BEFORE Decomposing)
+
+**Before decomposing, ask: Is this task clear enough to parallelize?**
+
+### Vague Task Signals (ASK QUESTIONS FIRST)
+
+| Signal                   | Example                        | Problem                          |
+| ------------------------ | ------------------------------ | -------------------------------- |
+| No files mentioned       | "improve performance"          | Where? Which files?              |
+| Vague verbs              | "fix", "update", "make better" | What specifically?               |
+| Large undefined scope    | "refactor the codebase"        | Which parts? What pattern?       |
+| Missing success criteria | "add auth"                     | OAuth? JWT? Session? What flows? |
+| Ambiguous boundaries     | "handle errors"                | Which errors? Where? How?        |
+
+### How to Clarify
+
+```markdown
+The task "<task>" needs clarification before I can decompose it.
+
+**Question:** [Specific question about scope/files/approach]
+
+Options:
+a) [Option A] - [trade-off]
+b) [Option B] - [trade-off]
+c) [Option C] - [trade-off]
+
+I'd recommend (a) because [reason]. Which approach?
+```
+
+**Rules:**
+
+- ONE question at a time (don't overwhelm)
+- Offer 2-3 concrete options when possible
+- Lead with your recommendation and why
+- Wait for answer before asking next question
+
+### Clear Task Signals (PROCEED to decompose)
+
+| Signal             | Example                        | Why it's clear   |
+| ------------------ | ------------------------------ | ---------------- |
+| Specific files     | "update src/auth/\*.ts"        | Scope defined    |
+| Concrete verbs     | "migrate from X to Y"          | Action defined   |
+| Defined scope      | "the payment module"           | Boundaries clear |
+| Measurable outcome | "tests pass", "no type errors" | Success criteria |
+
+**When in doubt, ask.** A 30-second clarification beats a 30-minute wrong decomposition.
+
 ## Coordinator Workflow
 
 ### Phase 1: Initialize Swarm Mail (FIRST)
@@ -309,16 +356,17 @@ One blocker affects multiple subtasks.
 
 ## Anti-Patterns
 
-| Anti-Pattern             | Symptom                                    | Fix                                  |
-| ------------------------ | ------------------------------------------ | ------------------------------------ |
-| **Mega-Coordinator**     | Coordinator editing files                  | Coordinator only orchestrates        |
-| **Silent Swarm**         | No communication, late conflicts           | Require updates, check inbox         |
-| **Over-Decomposed**      | 10 subtasks for 20 lines                   | 2-5 subtasks max                     |
-| **Under-Specified**      | "Implement backend"                        | Clear goal, files, criteria          |
-| **Inline Planning** ⚠️   | Context pollution, exhaustion on long runs | Delegate planning to subagent        |
-| **Heavy File Reading**   | Coordinator reading 10+ files              | Subagent reads, returns summary only |
-| **Deep CASS Drilling**   | Multiple cass_search calls inline          | Subagent searches, summarizes        |
-| **Manual Decomposition** | Hand-crafting subtasks without validation  | Use swarm_plan_prompt + validation   |
+| Anti-Pattern                | Symptom                                    | Fix                                  |
+| --------------------------- | ------------------------------------------ | ------------------------------------ |
+| **Decomposing Vague Tasks** | Wrong subtasks, wasted agent cycles        | Ask clarifying questions FIRST       |
+| **Mega-Coordinator**        | Coordinator editing files                  | Coordinator only orchestrates        |
+| **Silent Swarm**            | No communication, late conflicts           | Require updates, check inbox         |
+| **Over-Decomposed**         | 10 subtasks for 20 lines                   | 2-5 subtasks max                     |
+| **Under-Specified**         | "Implement backend"                        | Clear goal, files, criteria          |
+| **Inline Planning** ⚠️      | Context pollution, exhaustion on long runs | Delegate planning to subagent        |
+| **Heavy File Reading**      | Coordinator reading 10+ files              | Subagent reads, returns summary only |
+| **Deep CASS Drilling**      | Multiple cass_search calls inline          | Subagent searches, summarizes        |
+| **Manual Decomposition**    | Hand-crafting subtasks without validation  | Use swarm_plan_prompt + validation   |
 
 ## Shared Context Template
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

package/src/beads.ts

@@ -178,7 +178,10 @@ function parseBead(output: string): Bead {
     // CLI commands like `bd close`, `bd update` return arrays even for single items
     const data = Array.isArray(parsed) ? parsed[0] : parsed;
     if (!data) {
-      throw new BeadError("No bead data in response", "parse");
+      throw new BeadError(
+        "No bead data in response. The bd CLI may not be installed or returned unexpected output. Try: Run 'bd --version' to verify installation, or check if .beads/ directory exists in project.",
+        "parse",
+      );
     }
     return BeadSchema.parse(data);
   } catch (error) {
@@ -191,7 +194,10 @@ function parseBead(output: string): Bead {
     if (error instanceof BeadError) {
       throw error;
     }
-    throw new BeadError(`Failed to parse bead JSON: ${output}`, "parse");
+    throw new BeadError(
+      `Failed to parse bead JSON because output is malformed. Try: Check if bd CLI is up to date with 'bd --version' (need v1.0.0+), or inspect output: ${output.slice(0, 100)}`,
+      "parse",
+    );
   }
 }
 
@@ -209,7 +215,10 @@ function parseBeads(output: string): Bead[] {
         error,
       );
     }
-    throw new BeadError(`Failed to parse beads JSON: ${output}`, "parse");
+    throw new BeadError(
+      `Failed to parse beads JSON because output is malformed. Try: Check if bd CLI is up to date with 'bd --version' (need v1.0.0+), or inspect output: ${output.slice(0, 100)}`,
+      "parse",
+    );
   }
 }
 
@@ -249,7 +258,7 @@ export const beads_create = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to create bead: ${result.stderr}`,
+        `Failed to create bead because bd command exited with code ${result.exitCode}. Error: ${result.stderr}. Try: Check if beads initialized with 'bd init' in project root, or verify .beads/ directory exists.`,
         cmdParts.join(" "),
         result.exitCode,
         result.stderr,
@@ -260,7 +269,7 @@ export const beads_create = tool({
     const stdout = result.stdout.trim();
     if (!stdout) {
       throw new BeadError(
-        "bd create returned empty output",
+        "bd create returned empty output because command produced no response. Try: Check if bd is properly installed with 'bd --version', or run 'bd list' to test basic functionality.",
         cmdParts.join(" "),
         0,
         "Empty stdout",
@@ -270,7 +279,7 @@ export const beads_create = tool({
     // Check for error messages in stdout (bd sometimes outputs errors to stdout)
     if (stdout.startsWith("error:") || stdout.startsWith("Error:")) {
       throw new BeadError(
-        `bd create failed: ${stdout}`,
+        `bd create failed because command returned error in stdout: ${stdout}. Try: Check error message above, verify beads initialized with 'bd init', or check .beads/issues.jsonl for corruption.`,
         cmdParts.join(" "),
         0,
         stdout,
@@ -331,7 +340,7 @@ export const beads_create_epic = tool({
 
       if (epicResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to create epic: ${epicResult.stderr}`,
+          `Failed to create epic because bd command failed: ${epicResult.stderr}. Try: Verify beads initialized with 'bd init', check if .beads/ directory is writable, or run 'bd list' to test basic functionality.`,
           epicCmd.join(" "),
           epicResult.exitCode,
         );
@@ -361,7 +370,7 @@ export const beads_create_epic = tool({
 
         if (subtaskResult.exitCode !== 0) {
           throw new BeadError(
-            `Failed to create subtask: ${subtaskResult.stderr}`,
+            `Failed to create subtask because bd command failed: ${subtaskResult.stderr}. Try: Check if parent epic exists with 'bd show ${epic.id}', verify .beads/issues.jsonl is not corrupted, or check for invalid characters in title.`,
             subtaskCmd.join(" "),
             subtaskResult.exitCode,
           );
@@ -430,7 +439,7 @@ export const beads_create_epic = tool({
       }
 
       throw new BeadError(
-        `Epic creation failed: ${errorMsg}${rollbackInfo}`,
+        `Epic creation failed: ${errorMsg}${rollbackInfo}. Try: If rollback failed, manually close beads with 'bd close <id> --reason "Rollback"', check .beads/issues.jsonl for partial state, or re-run beads_create_epic with corrected parameters.`,
         "beads_create_epic",
         1,
       );
@@ -482,7 +491,7 @@ export const beads_query = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to query beads: ${result.stderr}`,
+        `Failed to query beads because bd command failed: ${result.stderr}. Try: Check if beads initialized with 'bd init', verify .beads/ directory exists, or run 'bd --version' to check CLI version.`,
         cmd.join(" "),
         result.exitCode,
       );
@@ -534,7 +543,7 @@ export const beads_update = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to update bead: ${result.stderr}`,
+        `Failed to update bead because bd command failed: ${result.stderr}. Try: Verify bead exists with 'bd show ${validated.id}', check for invalid status values, or inspect .beads/issues.jsonl for corruption.`,
         cmd.join(" "),
         result.exitCode,
       );
@@ -570,7 +579,7 @@ export const beads_close = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to close bead: ${result.stderr}`,
+        `Failed to close bead because bd command failed: ${result.stderr}. Try: Verify bead exists and is not already closed with 'beads_query(status="closed")' or 'bd show ${validated.id}', check if bead ID is correct.`,
         cmd.join(" "),
         result.exitCode,
       );
@@ -601,7 +610,7 @@ export const beads_start = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to start bead: ${result.stderr}`,
+        `Failed to start bead because bd update command failed: ${result.stderr}. Try: Verify bead exists with 'bd show ${args.id}', check if already in_progress with 'beads_query(status="in_progress")', or use beads_update directly.`,
         `bd update ${args.id} --status in_progress --json`,
         result.exitCode,
       );
@@ -623,7 +632,7 @@ export const beads_ready = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to get ready beads: ${result.stderr}`,
+        `Failed to get ready beads because bd ready command failed: ${result.stderr}. Try: Check if beads initialized with 'bd init', verify .beads/ directory is readable, or run 'bd list --json' to test basic query.`,
         "bd ready --json",
         result.exitCode,
       );
@@ -696,7 +705,7 @@ export const beads_sync = tool({
     );
     if (flushResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to flush beads: ${flushResult.stderr}`,
+        `Failed to flush beads because bd sync failed: ${flushResult.stderr}. Try: Check if .beads/ directory is writable, verify no corrupted JSONL files, or run 'bd list' to test basic beads functionality.`,
         "bd sync --flush-only",
         flushResult.exitCode,
       );
@@ -715,7 +724,7 @@ export const beads_sync = tool({
       const addResult = await runGitCommand(["add", ".beads/"]);
       if (addResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to stage beads: ${addResult.stderr}`,
+          `Failed to stage beads because git add failed: ${addResult.stderr}. Try: Check if .beads/ directory exists, verify git is initialized with 'git status', or check for .gitignore patterns blocking .beads/.`,
           "git add .beads/",
           addResult.exitCode,
         );
@@ -732,7 +741,7 @@ export const beads_sync = tool({
         !commitResult.stdout.includes("nothing to commit")
       ) {
         throw new BeadError(
-          `Failed to commit beads: ${commitResult.stderr}`,
+          `Failed to commit beads because git commit failed: ${commitResult.stderr}. Try: Check git config (user.name, user.email) with 'git config --list', verify working tree is clean, or check for pre-commit hooks blocking commit.`,
           "git commit",
           commitResult.exitCode,
         );
@@ -798,7 +807,7 @@ export const beads_sync = tool({
 
       if (pullResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to pull: ${pullResult.stderr}`,
+          `Failed to pull because git pull --rebase failed: ${pullResult.stderr}. Try: Resolve merge conflicts manually with 'git status', check if remote is accessible with 'git remote -v', or use skip_verification to bypass automatic pull.`,
           "git pull --rebase",
           pullResult.exitCode,
         );
@@ -824,7 +833,7 @@ export const beads_sync = tool({
     );
     if (pushResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to push: ${pushResult.stderr}`,
+        `Failed to push because git push failed: ${pushResult.stderr}. Try: Check if remote branch is up to date with 'git pull --rebase', verify push permissions, check remote URL with 'git remote -v', or force push with 'git push --force-with-lease' if safe.`,
         "git push",
         pushResult.exitCode,
       );
@@ -858,7 +867,7 @@ export const beads_link_thread = tool({
 
     if (queryResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to get bead: ${queryResult.stderr}`,
+        `Failed to get bead because bd show command failed: ${queryResult.stderr}. Try: Verify bead ID is correct with 'beads_query()', check if bead exists with 'bd list --json', or check .beads/issues.jsonl for valid entries.`,
         `bd show ${args.bead_id} --json`,
         queryResult.exitCode,
       );
@@ -887,7 +896,7 @@ export const beads_link_thread = tool({
 
     if (updateResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to update bead: ${updateResult.stderr}`,
+        `Failed to update bead because bd update command failed: ${updateResult.stderr}. Try: Verify bead exists with 'bd show ${args.bead_id}', check for invalid characters in description, or inspect .beads/issues.jsonl for corruption.`,
         `bd update ${args.bead_id} -d ...`,
         updateResult.exitCode,
       );

package/src/index.ts

@@ -38,6 +38,7 @@ import { structuredTools } from "./structured";
 import { swarmTools } from "./swarm";
 import { repoCrawlTools } from "./repo-crawl";
 import { skillsTools, setSkillsProjectDirectory } from "./skills";
+import { mandateTools } from "./mandates";
 
 /**
  * OpenCode Swarm Plugin
@@ -50,6 +51,7 @@ import { skillsTools, setSkillsProjectDirectory } from "./skills";
  * - swarm:* - Swarm orchestration and task decomposition
  * - repo-crawl:* - GitHub API tools for repository research
  * - skills:* - Agent skills discovery, activation, and execution
+ * - mandate:* - Agent voting system for collaborative knowledge curation
  *
  * @param input - Plugin context from OpenCode
  * @returns Plugin hooks including tools, events, and tool execution hooks
@@ -132,6 +134,7 @@ export const SwarmPlugin: Plugin = async (
      * - agent-mail:init, agent-mail:send, agent-mail:reserve, etc. (legacy MCP)
      * - swarm-mail:init, swarm-mail:send, swarm-mail:reserve, etc. (embedded)
      * - repo-crawl:readme, repo-crawl:structure, etc.
+     * - mandate:file, mandate:vote, mandate:query, etc.
      */
     tool: {
       ...beadsTools,
@@ -140,6 +143,7 @@ export const SwarmPlugin: Plugin = async (
       ...swarmTools,
       ...repoCrawlTools,
       ...skillsTools,
+      ...mandateTools,
     },
 
     /**
@@ -361,6 +365,7 @@ export const allTools = {
   ...swarmTools,
   ...repoCrawlTools,
   ...skillsTools,
+  ...mandateTools,
 } as const;
 
 /**
@@ -473,3 +478,76 @@ export {
   type SkillMetadata,
   type SkillRef,
 } from "./skills";
+
+/**
+ * Re-export mandates module
+ *
+ * Agent voting system for collaborative knowledge curation.
+ *
+ * Includes:
+ * - mandateTools - All mandate tools (file, vote, query, list, stats)
+ * - MandateError - Error class
+ *
+ * Features:
+ * - Submit ideas, tips, lore, snippets, and feature requests
+ * - Vote on entries (upvote/downvote) with 90-day decay
+ * - Semantic search for relevant mandates
+ * - Status transitions based on consensus (candidate → established → mandate)
+ * - Persistent storage with semantic-memory
+ *
+ * Types:
+ * - MandateEntry, Vote, MandateScore - Core data types
+ * - MandateStatus, MandateContentType - Enum types
+ */
+export { mandateTools, MandateError } from "./mandates";
+
+/**
+ * Re-export mandate-storage module
+ *
+ * Includes:
+ * - createMandateStorage - Factory function
+ * - getMandateStorage, setMandateStorage, resetMandateStorage - Global instance management
+ * - updateMandateStatus, updateAllMandateStatuses - Status update helpers
+ * - InMemoryMandateStorage, SemanticMemoryMandateStorage - Storage implementations
+ *
+ * Types:
+ * - MandateStorage - Unified storage interface
+ * - MandateStorageConfig, MandateStorageBackend, MandateStorageCollections - Configuration types
+ */
+export {
+  createMandateStorage,
+  getMandateStorage,
+  setMandateStorage,
+  resetMandateStorage,
+  updateMandateStatus,
+  updateAllMandateStatuses,
+  InMemoryMandateStorage,
+  SemanticMemoryMandateStorage,
+  DEFAULT_MANDATE_STORAGE_CONFIG,
+  type MandateStorage,
+  type MandateStorageConfig,
+  type MandateStorageBackend,
+  type MandateStorageCollections,
+} from "./mandate-storage";
+
+/**
+ * Re-export mandate-promotion module
+ *
+ * Includes:
+ * - evaluatePromotion - Evaluate status transitions
+ * - shouldPromote - Determine new status based on score
+ * - formatPromotionResult - Format promotion result for display
+ * - evaluateBatchPromotions, getStatusChanges, groupByTransition - Batch helpers
+ *
+ * Types:
+ * - PromotionResult - Promotion evaluation result
+ */
+export {
+  evaluatePromotion,
+  shouldPromote,
+  formatPromotionResult,
+  evaluateBatchPromotions,
+  getStatusChanges,
+  groupByTransition,
+  type PromotionResult,
+} from "./mandate-promotion";