opencode-swarm-plugin 0.12.31 → 0.13.1

package/examples/commands/swarm.md

@@ -15,19 +15,31 @@ $ARGUMENTS
 
 **Default: Feature branch + PR with context sync.**
 
+## MANDATORY: Swarm Mail
+
+**ALL coordination MUST use `swarmmail_*` tools.** This is non-negotiable.
+
+Swarm Mail is embedded (no external server needed) and provides:
+
+- File reservations to prevent conflicts
+- Message passing between agents
+- Thread-based coordination tied to beads
+
 ## Workflow
 
-### 1. Initialize
+### 1. Initialize Swarm Mail (FIRST)
 
-```
-agentmail_init(project_path="$PWD", task_description="Swarm: <task summary>")
+```bash
+swarmmail_init(project_path="$PWD", task_description="Swarm: <task summary>")
 ```
 
+This registers you as the coordinator agent.
+
 ### 2. Knowledge Gathering (MANDATORY)
 
 **Before decomposing, query ALL knowledge sources:**
 
-```
+```bash
 # Past learnings from this project
 semantic-memory_find(query="<task keywords>", limit=5)
 
@@ -41,12 +53,28 @@ pdf-brain_search(query="<domain concepts>", limit=5)
 skills_list()
 ```
 
+**Load coordinator skills based on task type:**
+
+```bash
+# 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 subtasks
+- **Skills to recommend for each subtask** (critical for worker effectiveness)
 
 ### 3. Create Feature Branch (unless --to-main)
 
@@ -59,20 +87,20 @@ git push -u origin HEAD
 
 Use strategy selection and planning:
 
-```
+```bash
 swarm_select_strategy(task="<the task>")
 swarm_plan_prompt(task="<the task>", strategy="<auto or selected>", context="<synthesized knowledge>")
 ```
 
 Follow the prompt to create a BeadTree, then validate:
 
-```
+```bash
 swarm_validate_decomposition(response="<your BeadTree JSON>")
 ```
 
 ### 5. Create Beads
 
-```
+```bash
 beads_create_epic(epic_title="<task>", subtasks=[{title, files, priority}...])
 ```
 
@@ -83,13 +111,13 @@ Rules:
 - 3-7 beads per swarm
 - No file overlap between subtasks
 
-### 6. Reserve Files
+### 6. Reserve Files (via Swarm Mail)
 
-```
-agentmail_reserve(paths=[<files>], reason="<bead-id>: <description>")
+```bash
+swarmmail_reserve(paths=[<files>], reason="<bead-id>: <description>", ttl_seconds=3600)
 ```
 
-No two agents should edit the same file.
+No two agents should edit the same file. Reservations prevent conflicts.
 
 ### 7. Spawn Agents
 
@@ -97,7 +125,7 @@ No two agents should edit the same file.
 
 For each subtask:
 
-```
+```bash
 swarm_spawn_subtask(
   bead_id="<id>",
   epic_id="<epic>",
@@ -107,17 +135,33 @@ swarm_spawn_subtask(
 )
 ```
 
-Then spawn:
+**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:
+
+```bash
 Task(subagent_type="swarm/worker", description="<bead-title>", prompt="<from swarm_spawn_subtask>")
 ```
 
 ### 8. Monitor (unless --no-sync)
 
-```
+```bash
 swarm_status(epic_id="<epic-id>", project_key="$PWD")
-agentmail_inbox()
+swarmmail_inbox()  # Check for worker messages
+swarmmail_read_message(message_id=N)  # Read specific message
 ```
 
 **Intervention triggers:**
@@ -129,14 +173,15 @@ agentmail_inbox()
 
 If incompatibilities spotted, broadcast:
 
-```
-agentmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", importance="high")
+```bash
+swarmmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", importance="high", thread_id="<epic-id>")
 ```
 
 ### 9. Complete
 
-```
+```bash
 swarm_complete(project_key="$PWD", agent_name="<your-name>", bead_id="<epic-id>", summary="<done>", files_touched=[...])
+swarmmail_release()  # Release any remaining reservations
 beads_sync()
 ```
 
@@ -146,24 +191,51 @@ beads_sync()
 gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Beads\n<list>"
 ```
 
+## Swarm Mail Quick Reference
+
+| Tool                     | Purpose                             |
+| ------------------------ | ----------------------------------- |
+| `swarmmail_init`         | Initialize session (REQUIRED FIRST) |
+| `swarmmail_send`         | Send message to agents              |
+| `swarmmail_inbox`        | Check inbox (max 5, no bodies)      |
+| `swarmmail_read_message` | Read specific message body          |
+| `swarmmail_reserve`      | Reserve files for exclusive editing |
+| `swarmmail_release`      | Release file reservations           |
+| `swarmmail_ack`          | Acknowledge message                 |
+| `swarmmail_health`       | Check database health               |
+
 ## 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  |
-| research-based | Investigation, discovery | research, investigate, explore, learn |
+| 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
 
+- [ ] **swarmmail_init** called FIRST
 - [ ] Knowledge gathered (semantic-memory, CASS, pdf-brain, skills)
 - [ ] Strategy selected
 - [ ] BeadTree validated (no file conflicts)
 - [ ] Epic + subtasks created
-- [ ] Files reserved
+- [ ] Files reserved via **swarmmail_reserve**
 - [ ] Workers spawned in parallel
-- [ ] Progress monitored
+- [ ] Progress monitored via **swarmmail_inbox**
 - [ ] PR created (or pushed to main)
 
-Begin with knowledge gathering now.
+Begin with swarmmail_init and 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
+```