opencode-swarm-plugin 0.12.20 → 0.12.22

package/examples/skills/beads-workflow/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: beads-workflow
+description: Issue tracking and task management using the beads system. Use when creating, updating, or managing work items. Use when you need to track bugs, features, tasks, or epics. Do NOT use for simple one-off questions or explorations.
+tags:
+  - beads
+  - issues
+  - tracking
+  - workflow
+tools:
+  - beads_create
+  - beads_query
+  - beads_update
+  - beads_close
+---
+
+# Beads Workflow Skill
+
+Beads is a local-first issue tracking system designed for AI agents. This skill provides best practices for effective bead management.
+
+## 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 |
+
+## Creating Effective Beads
+
+### Good Bead Titles
+- "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
+- "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
+
+```
+open → in_progress → closed
+         ↓
+      blocked (optional)
+```
+
+### State Transitions
+
+**Open → In Progress**
+```
+beads_update(id: "abc123", state: "in_progress")
+```
+Use when you start working on a bead.
+
+**In Progress → Closed**
+```
+beads_close(id: "abc123", resolution: "Fixed in commit abc1234")
+```
+Use when work is complete.
+
+**In Progress → Blocked**
+```
+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
+```
+beads_query(state: "open", type: "bug")
+```
+
+### Search by Keywords
+```
+beads_query(search: "authentication")
+```
+
+### List Recent Activity
+```
+beads_query(limit: 10, sort: "updated")
+```
+
+## Epic Management
+
+Epics are containers for related work:
+
+```markdown
+---
+type: epic
+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
+- [ ] #bead-004: Update login UI
+```
+
+### Creating an Epic with Subtasks
+
+1. Create the epic first:
+```
+beads_create(type: "epic", title: "User Auth Overhaul", body: "...")
+```
+
+2. Create subtasks linked to the epic:
+```
+beads_create(type: "task", title: "Implement OAuth2", parent: "epic-id")
+```
+
+## Best Practices
+
+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
+
+## 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

package/examples/skills/skill-creator/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: skill-creator
+description: Guide for creating effective agent skills. Use when you want to create a new skill, improve an existing skill, or learn best practices for skill development. Helps codify learned patterns into reusable, discoverable skills.
+tags:
+  - meta
+  - skills
+  - learning
+  - documentation
+tools:
+  - skills_init
+  - skills_create
+  - skills_update
+  - skills_read
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+## What Are Skills?
+
+Skills are modular, self-contained packages that extend agent capabilities by providing:
+
+1. **Specialized workflows** - Multi-step procedures for specific domains
+2. **Tool integrations** - Instructions for working with specific file formats or APIs
+3. **Domain expertise** - Project-specific knowledge, schemas, business logic
+4. **Bundled resources** - Scripts, references, and assets for complex tasks
+
+Think of skills as "onboarding guides" that transform a general-purpose agent into a specialized one equipped with procedural knowledge.
+
+## Skill Anatomy
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description, tags, tools)
+│   └── Markdown instructions
+└── Bundled Resources (optional)
+    ├── scripts/      - Executable code (run with skills_execute)
+    └── references/   - Documentation (load with skills_read)
+```
+
+### Progressive Disclosure
+
+Skills use a three-level loading system:
+
+1. **Metadata** (name + description) - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - On-demand as needed
+
+Keep SKILL.md lean. Move detailed content to references/.
+
+## Creating a Skill
+
+### Step 1: Understand the Use Cases
+
+Before creating, understand concrete examples:
+- What triggers should activate this skill?
+- What user requests would benefit from it?
+- What workflows does it enable?
+
+**Ask clarifying questions** if scope is unclear.
+
+### Step 2: Initialize the Skill
+
+Use `skills_init` to create the full template structure:
+
+```
+skills_init(
+  name: "my-skill",
+  description: "Initial description",
+  directory: ".opencode/skills"
+)
+```
+
+This creates:
+- SKILL.md with TODO placeholders
+- scripts/ with example script
+- references/ with example doc
+
+### Step 3: Complete the SKILL.md
+
+Fill in the TODO placeholders. Key sections:
+
+**Frontmatter** - Critical for discoverability:
+```yaml
+---
+name: my-skill
+description: What it does and WHEN to use it. Be specific about triggering scenarios.
+tags:
+  - category
+  - domain
+tools:
+  - tool_names_used
+---
+```
+
+**When to Use** - Specific triggering scenarios:
+```markdown
+## When to Use This Skill
+
+- When working on X type of task
+- When files matching Y pattern are involved
+- When the user asks about Z topic
+```
+
+**Instructions** - Actionable, imperative form:
+```markdown
+## Instructions
+
+1. Read the configuration file first
+2. Check for existing patterns before creating
+3. Always validate output before completing
+```
+
+**Examples** - Realistic user requests:
+```markdown
+## Examples
+
+### Example: Realistic Scenario
+
+**User**: "Help me do X"
+
+**Process**:
+1. First step
+2. Second step
+3. Final step
+```
+
+### Step 4: Add Bundled Resources (Optional)
+
+**scripts/** - Executable helpers:
+- Use for repeated automation
+- Token-efficient (run without reading)
+- Run via `skills_execute`
+
+**references/** - On-demand documentation:
+- Detailed guides too long for SKILL.md
+- API documentation
+- Complex workflows
+- Load via `skills_read`
+
+### Step 5: Test and Iterate
+
+1. Use `skills_use` to load the skill
+2. Try it on real tasks
+3. Notice struggles or inefficiencies
+4. Update SKILL.md based on experience
+5. Test again
+
+## Best Practices
+
+### Metadata Quality
+
+The `name` and `description` determine when the skill triggers:
+
+**Good descriptions**:
+- "Guide for creating MCP servers. Use when building tools that connect LLMs to external APIs."
+- "File organization helper. Use when Downloads folder is messy or files need restructuring."
+
+**Bad descriptions**:
+- "A useful skill" (too vague)
+- "Does stuff with files" (not actionable)
+
+### Writing Style
+
+Use **imperative/infinitive form** throughout:
+- "Read the file first" (not "You should read the file")
+- "Check for patterns" (not "Consider checking patterns")
+
+### Keep SKILL.md Lean
+
+- Core instructions only (<5k words)
+- Move details to references/
+- Use examples sparingly
+- Delete placeholder sections
+
+### Design for Discoverability
+
+- Tags help agents find skills by category
+- "When to Use" sections enable proper triggering
+- Tools list shows what capabilities the skill uses
+
+## Quick Reference
+
+### Creating Skills
+
+| Tool | Use When |
+|------|----------|
+| `skills_init` | Want full template structure with TODOs |
+| `skills_create` | Have complete content ready to write |
+| `swarm_learn` | Converting learned patterns to skills |
+
+### Managing Skills
+
+| Tool | Use For |
+|------|---------|
+| `skills_list` | Discover available skills |
+| `skills_use` | Activate a skill by loading its content |
+| `skills_read` | Load a reference file from a skill |
+| `skills_update` | Modify an existing skill |
+| `skills_delete` | Remove an obsolete skill |
+
+### Execution
+
+| Tool | Use For |
+|------|---------|
+| `skills_execute` | Run a script from a skill |
+| `skills_add_script` | Add a new script to a skill |
+
+## From Learned Patterns to Skills
+
+When you discover something reusable during work:
+
+1. **Identify the pattern** - What worked well?
+2. **Consider scope** - Is it project-specific or universal?
+3. **Use `swarm_learn`** - Document the learning
+4. **Create the skill** - Use `create_skill=true` or `skills_init`
+5. **Test and refine** - Iterate based on usage
+
+Skills make swarms smarter over time by preserving learned knowledge for future agents.

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

@@ -0,0 +1,148 @@
+---
+name: swarm-coordination
+description: Multi-agent coordination patterns for OpenCode swarm workflows. Use when working on complex tasks that benefit from parallelization, when coordinating multiple agents, or when managing task decomposition. Do NOT use for simple single-agent tasks.
+tags:
+  - swarm
+  - multi-agent
+  - coordination
+tools:
+  - swarm_decompose
+  - swarm_complete
+  - agentmail_init
+  - agentmail_send
+---
+
+# Swarm Coordination Skill
+
+This skill provides guidance for effective multi-agent coordination in OpenCode swarm workflows.
+
+## 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
+
+## Task Decomposition Strategy
+
+### 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?
+- Are there shared resources that need coordination?
+
+### 2. Choose a Decomposition Strategy
+
+**Parallel Strategy** - For independent subtasks:
+```
+Parent Task: "Add user authentication"
+├── Subtask 1: "Create auth API endpoints" (backend)
+├── Subtask 2: "Build login/signup forms" (frontend)
+├── Subtask 3: "Write auth integration tests" (testing)
+└── Subtask 4: "Add auth documentation" (docs)
+```
+
+**Sequential Strategy** - When order matters:
+```
+Parent Task: "Migrate database schema"
+├── Step 1: "Create migration files"
+├── Step 2: "Update model definitions"
+├── Step 3: "Run migrations"
+└── Step 4: "Verify data integrity"
+```
+
+**Hybrid Strategy** - Mixed dependencies:
+```
+Parent Task: "Add feature X"
+├── Phase 1 (parallel):
+│   ├── Subtask A: "Design API"
+│   └── Subtask B: "Design UI mockups"
+├── Phase 2 (sequential, after Phase 1):
+│   └── Subtask C: "Implement based on designs"
+└── Phase 3 (parallel):
+    ├── Subtask D: "Write tests"
+    └── Subtask E: "Update docs"
+```
+
+## File Reservation Protocol
+
+When multiple agents work on the same codebase:
+
+1. **Reserve files before editing** - Use `agentmail_reserve` to claim files
+2. **Respect reservations** - Don't edit files reserved by other agents
+3. **Release when done** - Files auto-release on task completion
+4. **Coordinate on shared files** - If you must edit a reserved file, send a message to the owning agent
+
+## 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")
+```
+
+## Best Practices
+
+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
+5. **Progress updates** - Use beads to track subtask status
+
+## Common Patterns
+
+### Feature Development
+```yaml
+decomposition:
+  strategy: hybrid
+  phases:
+    - name: design
+      parallel: true
+      subtasks: [api-design, ui-design]
+    - name: implement
+      parallel: true
+      subtasks: [backend, frontend]
+    - name: validate
+      parallel: true
+      subtasks: [tests, docs, review]
+```
+
+### Bug Fix Swarm
+```yaml
+decomposition:
+  strategy: sequential
+  subtasks:
+    - reproduce-bug
+    - identify-root-cause
+    - implement-fix
+    - add-regression-test
+```
+
+### Refactoring
+```yaml
+decomposition:
+  strategy: parallel
+  subtasks:
+    - refactor-module-a
+    - refactor-module-b
+    - update-imports
+    - run-full-test-suite
+```