opencode-swarm-plugin 0.12.30 → 0.13.0

package/examples/commands/swarm.md

@@ -23,20 +23,61 @@ $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()
+```
+
+**Load coordinator skills based on task type:**
+
+```
+# For swarm coordination (ALWAYS load this)
+skills_use(name="swarm-coordination")
+
+# For architectural decisions
+skills_use(name="system-design")
+
+# If task involves testing
+skills_use(name="testing-patterns")
+
+# If building CLI tools
+skills_use(name="cli-builder")
+```
+
+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 each subtask** (critical for worker effectiveness)
+
+### 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 +86,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 +97,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 +107,71 @@ 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>"
+)
+```
+
+**Include skill recommendations in shared_context:**
+
+```markdown
+## Recommended Skills
+
+Load these skills before starting work:
+
+- skills_use(name="testing-patterns") - if adding tests or breaking dependencies
+- skills_use(name="swarm-coordination") - if coordinating with other agents
+- skills_use(name="system-design") - if making architectural decisions
+- skills_use(name="cli-builder") - if working on CLI components
+
+See full skill list with skills_list().
 ```
 
 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 +179,35 @@ 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                              | Recommended Skills                |
+| -------------- | ------------------------ | ------------------------------------- | --------------------------------- |
+| file-based     | Refactoring, migrations  | refactor, migrate, rename, update all | system-design, testing-patterns   |
+| feature-based  | New features             | add, implement, build, create, new    | system-design, swarm-coordination |
+| risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent  | testing-patterns                  |
+| research-based | Investigation, discovery | research, investigate, explore, learn | system-design                     |
+
+## Skill Triggers (Auto-load based on task type)
+
+**Task Analysis** → Recommend these skills in shared_context:
+
+| Task Pattern           | Skills to Load                                          |
+| ---------------------- | ------------------------------------------------------- |
+| Contains "test"        | `skills_use(name="testing-patterns")`                   |
+| Contains "refactor"    | `skills_use(name="testing-patterns")` + `system-design` |
+| Contains "CLI"         | `skills_use(name="cli-builder")`                        |
+| Multi-agent work       | `skills_use(name="swarm-coordination")`                 |
+| Architecture decisions | `skills_use(name="system-design")`                      |
+| Breaking dependencies  | `skills_use(name="testing-patterns")`                   |
+
+## 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/examples/skills/beads-workflow/SKILL.md

@@ -11,60 +11,78 @@ tools:
   - beads_query
   - beads_update
   - beads_close
+  - beads_create_epic
+  - beads_sync
+related_skills:
+  - swarm-coordination
 ---
 
 # Beads Workflow Skill
 
 Beads is a local-first issue tracking system designed for AI agents. This skill provides best practices for effective bead management.
 
+**NOTE:** For swarm workflows, combine this skill with `swarm-coordination` from global-skills/.
+
 ## Bead Types
 
-| Type | When to Use |
-|------|-------------|
-| `bug` | Something is broken and needs fixing |
-| `feature` | New functionality to add |
-| `task` | General work item |
-| `chore` | Maintenance, refactoring, dependencies |
-| `epic` | Large initiative with multiple subtasks |
+| Type      | When to Use                             |
+| --------- | --------------------------------------- |
+| `bug`     | Something is broken and needs fixing    |
+| `feature` | New functionality to add                |
+| `task`    | General work item                       |
+| `chore`   | Maintenance, refactoring, dependencies  |
+| `epic`    | Large initiative with multiple subtasks |
 
 ## Creating Effective Beads
 
 ### Good Bead Titles
+
+```text
 - "Fix null pointer exception in UserService.getProfile()"
 - "Add dark mode toggle to settings page"
 - "Migrate auth tokens from localStorage to httpOnly cookies"
+```
 
 ### Bad Bead Titles
+
+```text
 - "Fix bug" (too vague)
 - "Make it better" (not actionable)
 - "stuff" (meaningless)
+```
 
 ### Bead Body Structure
 
 ```markdown
 ## Problem
+
 [Clear description of the issue or need]
 
 ## Expected Behavior
+
 [What should happen]
 
 ## Current Behavior
+
 [What currently happens, for bugs]
 
 ## Proposed Solution
+
 [How to fix/implement, if known]
 
 ## Acceptance Criteria
+
 - [ ] Criterion 1
 - [ ] Criterion 2
 
 ## Notes
+
 [Any additional context, links, or constraints]
 ```
 
 ## Workflow States
 
-```
+```text
 open → in_progress → closed
          ↓
       blocked (optional)
@@ -72,38 +90,47 @@ open → in_progress → closed
 
 ### State Transitions
 
-**Open → In Progress**
-```
+### Open → In Progress
+
+```typescript
 beads_update(id: "abc123", state: "in_progress")
 ```
+
 Use when you start working on a bead.
 
-**In Progress → Closed**
-```
+### In Progress → Closed
+
+```typescript
 beads_close(id: "abc123", resolution: "Fixed in commit abc1234")
 ```
+
 Use when work is complete.
 
-**In Progress → Blocked**
-```
+### In Progress → Blocked
+
+```typescript
 beads_update(id: "abc123", state: "blocked", body: "Blocked by #xyz789")
 ```
+
 Use when you can't proceed due to a dependency.
 
 ## Querying Beads
 
 ### Find Open Work
-```
+
+```typescript
 beads_query(state: "open", type: "bug")
 ```
 
 ### Search by Keywords
-```
+
+```typescript
 beads_query(search: "authentication")
 ```
 
 ### List Recent Activity
-```
+
+```typescript
 beads_query(limit: 10, sort: "updated")
 ```
 
@@ -118,9 +145,11 @@ title: User Authentication Overhaul
 ---
 
 ## Objective
+
 Modernize the authentication system
 
 ## Subtasks
+
 - [ ] #bead-001: Implement OAuth2 provider
 - [ ] #bead-002: Add MFA support
 - [ ] #bead-003: Migrate session storage
@@ -130,36 +159,54 @@ Modernize the authentication system
 ### Creating an Epic with Subtasks
 
 1. Create the epic first:
-```
+
+```typescript
 beads_create(type: "epic", title: "User Auth Overhaul", body: "...")
 ```
 
 2. Create subtasks linked to the epic:
-```
+
+```typescript
 beads_create(type: "task", title: "Implement OAuth2", parent: "epic-id")
 ```
 
 ## Best Practices
 
+```text
 1. **One bead per logical unit of work** - Don't combine unrelated fixes
 2. **Update state promptly** - Keep beads reflecting reality
 3. **Add context in body** - Future you will thank present you
 4. **Link related beads** - Use `#bead-id` references
 5. **Close with resolution** - Explain how it was resolved
 6. **Use labels** - `priority:high`, `area:frontend`, etc.
+```
 
 ## Sync and Collaboration
 
-Beads sync automatically with the central server:
-- Changes push on close
-- Conflicts merge automatically
-- Use `bd sync` to force sync
+Beads sync with git:
+
+- Changes tracked locally
+- Use `beads_sync()` to commit and push to remote
 
 ## Integration with Swarm
 
 When working in a swarm:
-1. Create a parent bead for the overall task
-2. Decompose into child beads for subtasks
-3. Assign agents to specific beads
-4. Close beads as subtasks complete
-5. Close parent when all children done
+
+```text
+1. Load `swarm-coordination` skill with `skills_use(name="swarm-coordination")`
+2. Create epic with `beads_create_epic()` (atomic operation)
+3. Coordinator assigns beads to worker agents
+4. Workers load relevant skills based on subtask type
+5. Close beads as subtasks complete
+6. Close epic when all subtasks done
+7. Sync with `beads_sync()` (MANDATORY at session end)
+```
+
+### Skill Recommendations for Common Bead Types
+
+```text
+- `type: "bug"` → Load `testing-patterns` for regression tests
+- `type: "feature"` → Load `system-design` for architecture
+- `type: "chore"` → Load `testing-patterns` if refactoring
+- `type: "epic"` → Load `swarm-coordination` for decomposition
+```

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

@@ -10,21 +10,31 @@ tools:
   - swarm_complete
   - agentmail_init
   - agentmail_send
+  - skills_use
+  - skills_list
+related_skills:
+  - testing-patterns
+  - system-design
+  - cli-builder
 ---
 
 # Swarm Coordination Skill
 
 This skill provides guidance for effective multi-agent coordination in OpenCode swarm workflows.
 
+**IMPORTANT:** This skill references global skills in `global-skills/`. Workers should load domain-specific skills based on their subtask type.
+
 ## When to Use Swarm Coordination
 
 Use swarm coordination when:
+
 - A task has multiple independent subtasks that can run in parallel
 - The task requires different specializations (e.g., frontend + backend + tests)
 - Work can be divided by file/module boundaries
 - Time-to-completion matters and parallelization helps
 
 Do NOT use swarm coordination when:
+
 - The task is simple and can be done by one agent
 - Subtasks have heavy dependencies on each other
 - The overhead of coordination exceeds the benefit
@@ -34,6 +44,7 @@ Do NOT use swarm coordination when:
 ### 1. Analyze the Task
 
 Before decomposing, understand:
+
 - What are the distinct units of work?
 - Which parts can run in parallel vs sequentially?
 - What are the file/module boundaries?
@@ -42,6 +53,7 @@ Before decomposing, understand:
 ### 2. Choose a Decomposition Strategy
 
 **Parallel Strategy** - For independent subtasks:
+
 ```
 Parent Task: "Add user authentication"
 ├── Subtask 1: "Create auth API endpoints" (backend)
@@ -51,6 +63,7 @@ Parent Task: "Add user authentication"
 ```
 
 **Sequential Strategy** - When order matters:
+
 ```
 Parent Task: "Migrate database schema"
 ├── Step 1: "Create migration files"
@@ -60,6 +73,7 @@ Parent Task: "Migrate database schema"
 ```
 
 **Hybrid Strategy** - Mixed dependencies:
+
 ```
 Parent Task: "Add feature X"
 ├── Phase 1 (parallel):
@@ -84,16 +98,19 @@ When multiple agents work on the same codebase:
 ## Communication Patterns
 
 ### Broadcasting Updates
+
 ```
 agentmail_send(recipients: ["all"], message: "Completed API endpoints, ready for frontend integration")
 ```
 
 ### Direct Coordination
+
 ```
 agentmail_send(recipients: ["frontend-agent"], message: "Auth API is at /api/auth/*, here's the spec...")
 ```
 
 ### Blocking on Dependencies
+
 ```
 # Wait for a dependency before proceeding
 agentmail_receive(wait: true, filter: "api-complete")
@@ -104,28 +121,101 @@ agentmail_receive(wait: true, filter: "api-complete")
 1. **Small, focused subtasks** - Each subtask should be completable in one agent session
 2. **Clear boundaries** - Define exactly what files/modules each subtask touches
 3. **Explicit handoffs** - When one task enables another, communicate clearly
-4. **Graceful failures** - If a subtask fails, don't block the whole swarm
+4. **Graceful failures** - If a subtask fail, don't block the whole swarm
 5. **Progress updates** - Use beads to track subtask status
+6. **Load relevant skills** - Workers should call `skills_use()` based on their task type:
+   - Testing work → `skills_use(name="testing-patterns")`
+   - Architecture decisions → `skills_use(name="system-design")`
+   - CLI development → `skills_use(name="cli-builder")`
+   - Multi-agent coordination → `skills_use(name="swarm-coordination")`
 
 ## Common Patterns
 
 ### Feature Development
+
 ```yaml
 decomposition:
   strategy: hybrid
+  skills: [system-design, swarm-coordination] # Load before decomposing
   phases:
     - name: design
       parallel: true
       subtasks: [api-design, ui-design]
+      recommended_skills: [system-design]
     - name: implement
       parallel: true
       subtasks: [backend, frontend]
+      recommended_skills: [system-design]
     - name: validate
       parallel: true
       subtasks: [tests, docs, review]
+      recommended_skills: [testing-patterns]
+```
+
+### Bug Fix Swarm
+
+```yaml
+decomposition:
+  strategy: sequential
+  skills: [testing-patterns] # Load before decomposing
+  subtasks:
+    - reproduce-bug
+    - identify-root-cause
+    - implement-fix
+    - add-regression-test
+  recommended_skills: [testing-patterns]
+```
+
+### Refactoring
+
+```yaml
+decomposition:
+  strategy: parallel
+  skills: [testing-patterns, system-design] # Load before decomposing
+  subtasks:
+    - refactor-module-a
+    - refactor-module-b
+    - update-imports
+    - run-full-test-suite
+  recommended_skills: [testing-patterns, system-design]
+```
+
+## Skill Integration Workflow
+
+**For Coordinators:**
+
+1. Load `swarm-coordination` skill first
+2. Analyze task type
+3. Load additional skills based on domain (testing, design, CLI)
+4. Include skill recommendations in `shared_context` for workers
+
+**For Workers:**
+
+1. Read `shared_context` from coordinator
+2. Load recommended skills with `skills_use(name="skill-name")`
+3. Apply skill knowledge to subtask
+4. Report completion
+
+**Example shared_context:**
+
+```markdown
+## Context from Coordinator
+
+Past similar tasks: [CASS results]
+Project learnings: [semantic-memory results]
+
+## Recommended Skills
+
+- skills_use(name="testing-patterns") - for test creation
+- skills_use(name="system-design") - for module boundaries
+
+## Task-Specific Notes
+
+[Domain knowledge from coordinator]
 ```
 
 ### Bug Fix Swarm
+
 ```yaml
 decomposition:
   strategy: sequential
@@ -137,6 +227,7 @@ decomposition:
 ```
 
 ### Refactoring
+
 ```yaml
 decomposition:
   strategy: parallel