opencode-swarm-plugin 0.12.30 → 0.12.31

package/bin/swarm.ts

@@ -497,23 +497,65 @@ $ARGUMENTS
 
 ## Workflow
 
-1. **Initialize**: \`agentmail_init\` with project_path and task_description
-2. **Decompose**: Use \`swarm_select_strategy\` then \`swarm_plan_prompt\` to break down the task
-3. **Create beads**: \`beads_create_epic\` with subtasks and file assignments
-4. **Reserve files**: \`agentmail_reserve\` for each subtask's files
-5. **Spawn agents**: Use Task tool with \`swarm_spawn_subtask\` prompts
-6. **Monitor**: Check \`agentmail_inbox\` for progress, use \`agentmail_summarize_thread\` for overview
-7. **Complete**: \`swarm_complete\` when done, then \`beads_sync\` to push
-
-## Strategy Selection
-
-| 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   |
-
-Begin decomposition now.
+### 1. Initialize
+\`agentmail_init(project_path="$PWD", task_description="Swarm: <task>")\`
+
+### 2. Knowledge Gathering (MANDATORY)
+
+**Before decomposing, query ALL knowledge sources:**
+
+\`\`\`
+semantic-memory_find(query="<task keywords>", limit=5)   # Past learnings
+cass_search(query="<task description>", limit=5)         # Similar past tasks  
+pdf-brain_search(query="<domain concepts>", limit=5)     # Design patterns
+skills_list()                                            # Available skills
+\`\`\`
+
+Synthesize findings into shared_context for workers.
+
+### 3. Decompose
+\`\`\`
+swarm_select_strategy(task="<task>")
+swarm_plan_prompt(task="<task>", context="<synthesized knowledge>")
+swarm_validate_decomposition(response="<BeadTree JSON>")
+\`\`\`
+
+### 4. Create Beads
+\`beads_create_epic(epic_title="<task>", subtasks=[...])\`
+
+### 5. Reserve Files
+\`agentmail_reserve(paths=[...], reason="<bead-id>: <desc>")\`
+
+### 6. Spawn Agents (ALL in single message)
+\`\`\`
+swarm_spawn_subtask(bead_id, epic_id, subtask_title, files, shared_context)
+Task(subagent_type="swarm/worker", prompt="<from above>")
+\`\`\`
+
+### 7. Monitor
+\`\`\`
+swarm_status(epic_id, project_key)
+agentmail_inbox()
+\`\`\`
+
+Intervene if: blocked >5min, file conflicts, scope creep.
+
+### 8. Complete
+\`\`\`
+swarm_complete(...)
+beads_sync()
+\`\`\`
+
+## Strategy Reference
+
+| Strategy       | Best For                 | Keywords                               |
+| -------------- | ------------------------ | -------------------------------------- |
+| file-based     | Refactoring, migrations  | refactor, migrate, rename, update all  |
+| feature-based  | New features             | add, implement, build, create, feature |
+| risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent   |
+| research-based | Investigation, discovery | research, investigate, explore, learn  |
+
+Begin with knowledge gathering now.
 `;
 
 const getPlannerAgent = (model: string) => `---
@@ -526,12 +568,30 @@ You are a swarm planner. Decompose tasks into optimal parallel subtasks.
 
 ## Workflow
 
-1. Call \`swarm_select_strategy\` to analyze the task
-2. Call \`swarm_plan_prompt\` to get strategy-specific guidance
-3. Create a BeadTree following the guidelines
-4. Return ONLY valid JSON - no markdown, no explanation
+### 1. Knowledge Gathering (MANDATORY)
 
-## Output Format
+**Before decomposing, query ALL knowledge sources:**
+
+\`\`\`
+semantic-memory_find(query="<task keywords>", limit=5)   # Past learnings
+cass_search(query="<task description>", limit=5)         # Similar past tasks  
+pdf-brain_search(query="<domain concepts>", limit=5)     # Design patterns
+skills_list()                                            # Available skills
+\`\`\`
+
+Synthesize findings - note relevant patterns, past approaches, and skills to recommend.
+
+### 2. Strategy Selection
+
+\`swarm_select_strategy(task="<task>")\`
+
+### 3. Generate Plan
+
+\`swarm_plan_prompt(task="<task>", context="<synthesized knowledge>")\`
+
+### 4. Output BeadTree
+
+Return ONLY valid JSON - no markdown, no explanation:
 
 \`\`\`json
 {
@@ -539,7 +599,7 @@ You are a swarm planner. Decompose tasks into optimal parallel subtasks.
   "subtasks": [
     {
       "title": "...",
-      "description": "...",
+      "description": "Include relevant context from knowledge gathering",
       "files": ["src/..."],
       "dependencies": [],
       "estimated_complexity": 2
@@ -554,6 +614,7 @@ You are a swarm planner. Decompose tasks into optimal parallel subtasks.
 - No file overlap between subtasks
 - Include tests with the code they test
 - Order by dependency (if B needs A, A comes first)
+- Pass synthesized knowledge to workers via subtask descriptions
 `;
 
 const getWorkerAgent = (model: string) => `---
@@ -564,17 +625,45 @@ model: ${model}
 
 You are a swarm worker agent. Execute your assigned subtask efficiently.
 
+## Context
+
+Your prompt includes shared_context from the coordinator's knowledge gathering:
+- Relevant patterns from pdf-brain
+- Similar past approaches from CASS
+- Project-specific learnings from semantic-memory
+
+**Use this context** - it contains patterns and prior art relevant to your task.
+
+## Workflow
+
+1. **Read** assigned files to understand current state
+2. **Check skills** if you need domain guidance: \`skills_use(name="<relevant-skill>")\`
+3. **Implement** changes following patterns from shared_context
+4. **Verify** (typecheck, lint if applicable)
+5. **Complete** with \`swarm_complete\`
+
 ## Rules
+
 - Focus ONLY on your assigned files
-- Report progress via Agent Mail
-- Use beads_update to track status
-- Call swarm_complete when done
+- Report blockers immediately via Agent Mail (don't spin)
+- Use beads_update if blocked
+- Call swarm_complete when done - it handles bead closure and file release
 
-## Workflow
-1. Read assigned files
-2. Implement changes
-3. Verify (typecheck if applicable)
-4. Report completion
+## Communication
+
+\`\`\`
+agentmail_send(
+  to=["coordinator"],
+  subject="Progress/Blocker",
+  body="...",
+  thread_id="<epic_id>"
+)
+\`\`\`
+
+## Learning
+
+If you discover a reusable pattern worth preserving:
+\`semantic-memory_store(information="<pattern + why it matters>")\`
 `;
 
 // ============================================================================

package/examples/commands/swarm.md

@@ -23,20 +23,45 @@ $ARGUMENTS
 agentmail_init(project_path="$PWD", task_description="Swarm: <task summary>")
 ```
 
-### 2. Create Feature Branch (unless --to-main)
+### 2. Knowledge Gathering (MANDATORY)
+
+**Before decomposing, query ALL knowledge sources:**
+
+```
+# Past learnings from this project
+semantic-memory_find(query="<task keywords>", limit=5)
+
+# How similar tasks were solved before
+cass_search(query="<task description>", limit=5)
+
+# Design patterns and prior art
+pdf-brain_search(query="<domain concepts>", limit=5)
+
+# Available skills to inject into workers
+skills_list()
+```
+
+Synthesize findings into shared context for workers. Note:
+
+- Relevant patterns from pdf-brain
+- Similar past approaches from CASS
+- Project-specific learnings from semantic-memory
+- Skills to recommend for subtasks
+
+### 3. Create Feature Branch (unless --to-main)
 
 ```bash
 git checkout -b swarm/<short-task-name>
 git push -u origin HEAD
 ```
 
-### 3. Decompose Task
+### 4. Decompose Task
 
 Use strategy selection and planning:
 
 ```
 swarm_select_strategy(task="<the task>")
-swarm_plan_prompt(task="<the task>", strategy="<auto or selected>")
+swarm_plan_prompt(task="<the task>", strategy="<auto or selected>", context="<synthesized knowledge>")
 ```
 
 Follow the prompt to create a BeadTree, then validate:
@@ -45,7 +70,7 @@ Follow the prompt to create a BeadTree, then validate:
 swarm_validate_decomposition(response="<your BeadTree JSON>")
 ```
 
-### 4. Create Beads
+### 5. Create Beads
 
 ```
 beads_create_epic(epic_title="<task>", subtasks=[{title, files, priority}...])
@@ -56,8 +81,9 @@ Rules:
 - Each bead completable by one agent
 - Independent where possible (parallelizable)
 - 3-7 beads per swarm
+- No file overlap between subtasks
 
-### 5. Reserve Files
+### 6. Reserve Files
 
 ```
 agentmail_reserve(paths=[<files>], reason="<bead-id>: <description>")
@@ -65,43 +91,56 @@ agentmail_reserve(paths=[<files>], reason="<bead-id>: <description>")
 
 No two agents should edit the same file.
 
-### 6. Spawn Agents
+### 7. Spawn Agents
 
 **CRITICAL: Spawn ALL in a SINGLE message with multiple Task calls.**
 
 For each subtask:
 
 ```
-swarm_spawn_subtask(bead_id="<id>", epic_id="<epic>", subtask_title="<title>", files=[...])
+swarm_spawn_subtask(
+  bead_id="<id>",
+  epic_id="<epic>",
+  subtask_title="<title>",
+  files=[...],
+  shared_context="<synthesized knowledge from step 2>"
+)
 ```
 
 Then spawn:
 
 ```
-Task(subagent_type="swarm-worker", description="<bead-title>", prompt="<from swarm_spawn_subtask>")
+Task(subagent_type="swarm/worker", description="<bead-title>", prompt="<from swarm_spawn_subtask>")
 ```
 
-### 7. Monitor (unless --no-sync)
+### 8. Monitor (unless --no-sync)
 
 ```
-swarm_status(epic_id="<epic-id>")
+swarm_status(epic_id="<epic-id>", project_key="$PWD")
 agentmail_inbox()
 ```
 
+**Intervention triggers:**
+
+- Worker blocked >5 min → Check inbox, offer guidance
+- File conflict → Mediate, reassign files
+- Worker asking questions → Answer directly
+- Scope creep → Redirect, create new bead for extras
+
 If incompatibilities spotted, broadcast:
 
 ```
 agentmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", importance="high")
 ```
 
-### 8. Complete
+### 9. Complete
 
 ```
 swarm_complete(project_key="$PWD", agent_name="<your-name>", bead_id="<epic-id>", summary="<done>", files_touched=[...])
 beads_sync()
 ```
 
-### 9. Create PR (unless --to-main)
+### 10. Create PR (unless --to-main)
 
 ```bash
 gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Beads\n<list>"
@@ -109,10 +148,22 @@ gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Be
 
 ## Strategy Reference
 
-| Strategy      | Best For                | Keywords                              |
-| ------------- | ----------------------- | ------------------------------------- |
-| file-based    | Refactoring, migrations | refactor, migrate, rename, update all |
-| feature-based | New features            | add, implement, build, create, new    |
-| risk-based    | Bug fixes, security     | fix, bug, security, critical, urgent  |
-
-Begin decomposition now.
+| Strategy       | Best For                 | Keywords                              |
+| -------------- | ------------------------ | ------------------------------------- |
+| file-based     | Refactoring, migrations  | refactor, migrate, rename, update all |
+| feature-based  | New features             | add, implement, build, create, new    |
+| risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent  |
+| research-based | Investigation, discovery | research, investigate, explore, learn |
+
+## Quick Checklist
+
+- [ ] Knowledge gathered (semantic-memory, CASS, pdf-brain, skills)
+- [ ] Strategy selected
+- [ ] BeadTree validated (no file conflicts)
+- [ ] Epic + subtasks created
+- [ ] Files reserved
+- [ ] Workers spawned in parallel
+- [ ] Progress monitored
+- [ ] PR created (or pushed to main)
+
+Begin with knowledge gathering now.

package/package.json

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