opencode-swarm-plugin 0.15.0 → 0.16.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.16.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

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";