opencode-swarm-plugin 0.44.2 → 0.45.0

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

@@ -0,0 +1,212 @@
+---
+name: hive-workflow
+description: Issue tracking and task management using the hive 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:
+  - hive
+  - issues
+  - tracking
+  - workflow
+tools:
+  - hive_create
+  - hive_query
+  - hive_update
+  - hive_close
+  - hive_create_epic
+  - hive_sync
+related_skills:
+  - swarm-coordination
+---
+
+# Hive Workflow Skill
+
+Hive is a local-first issue tracking system designed for AI agents. This skill provides best practices for effective cell management.
+
+**NOTE:** For swarm workflows, combine this skill with `swarm-coordination` from global-skills/.
+
+## Cell 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 Cells
+
+### Good Cell 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 Cell Titles
+
+```text
+- "Fix bug" (too vague)
+- "Make it better" (not actionable)
+- "stuff" (meaningless)
+```
+
+### Cell 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)
+```
+
+### State Transitions
+
+### Open → In Progress
+
+```typescript
+hive_update(id: "hv-abc123", state: "in_progress")
+```
+
+Use when you start working on a cell.
+
+### In Progress → Closed
+
+```typescript
+hive_close(id: "hv-abc123", resolution: "Fixed in commit abc1234")
+```
+
+Use when work is complete.
+
+### In Progress → Blocked
+
+```typescript
+hive_update(id: "hv-abc123", state: "blocked", body: "Blocked by #hv-xyz789")
+```
+
+Use when you can't proceed due to a dependency.
+
+## Querying Cells
+
+### Find Open Work
+
+```typescript
+hive_query(state: "open", type: "bug")
+```
+
+### Search by Keywords
+
+```typescript
+hive_query(search: "authentication")
+```
+
+### List Recent Activity
+
+```typescript
+hive_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
+
+- [ ] #hv-001: Implement OAuth2 provider
+- [ ] #hv-002: Add MFA support
+- [ ] #hv-003: Migrate session storage
+- [ ] #hv-004: Update login UI
+```
+
+### Creating an Epic with Subtasks
+
+1. Create the epic first:
+
+```typescript
+hive_create(type: "epic", title: "User Auth Overhaul", body: "...")
+```
+
+2. Create subtasks linked to the epic:
+
+```typescript
+hive_create(type: "task", title: "Implement OAuth2", parent: "epic-id")
+```
+
+## Best Practices
+
+```text
+1. **One cell per logical unit of work** - Don't combine unrelated fixes
+2. **Update state promptly** - Keep cells reflecting reality
+3. **Add context in body** - Future you will thank present you
+4. **Link related cells** - Use `#hv-id` references
+5. **Close with resolution** - Explain how it was resolved
+6. **Use labels** - `priority:high`, `area:frontend`, etc.
+```
+
+## Sync and Collaboration
+
+Cells sync with git:
+
+- Changes tracked locally
+- Use `hive_sync()` to commit and push to remote
+
+## Integration with Swarm
+
+When working in a swarm:
+
+```text
+1. Load `swarm-coordination` skill with `skills_use(name="swarm-coordination")`
+2. Create epic with `hive_create_epic()` (atomic operation)
+3. Coordinator assigns cells to worker agents
+4. Workers load relevant skills based on subtask type
+5. Close cells as subtasks complete
+6. Close epic when all subtasks done
+7. Sync with `hive_sync()` (MANDATORY at session end)
+```
+
+### Skill Recommendations for Common Cell 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/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,292 @@
+---
+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
+  - swarmmail_init
+  - swarmmail_send
+  - swarmmail_inbox
+  - swarmmail_read_message
+  - swarmmail_reserve
+  - swarmmail_release
+  - 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.
+
+## 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 cells
+
+## 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:
+
+```text
+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:
+
+```text
+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:
+
+```text
+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. **Initialize Swarm Mail first** - Use `swarmmail_init` before any work
+2. **Reserve files before editing** - Use `swarmmail_reserve` to claim files
+3. **Respect reservations** - Don't edit files reserved by other agents
+4. **Release when done** - Use `swarmmail_release` or let `swarm_complete` handle it
+5. **Coordinate on shared files** - If you must edit a reserved file, send a message to the owning agent
+
+```typescript
+// Initialize first
+await swarmmail_init({
+  project_path: "$PWD",
+  task_description: "Working on auth feature",
+});
+
+// Reserve files
+await swarmmail_reserve({
+  paths: ["src/auth/**"],
+  reason: "bd-123: Auth implementation",
+  ttl_seconds: 3600,
+});
+
+// Work...
+
+// Release when done
+await swarmmail_release();
+```
+
+## Communication Patterns
+
+### Broadcasting Updates
+
+```typescript
+swarmmail_send({
+  to: ["*"],
+  subject: "API Complete",
+  body: "Completed API endpoints, ready for frontend integration",
+  thread_id: epic_id,
+});
+```
+
+### Direct Coordination
+
+```typescript
+swarmmail_send({
+  to: ["frontend-agent"],
+  subject: "Auth API Spec",
+  body: "Auth API is at /api/auth/*, here's the spec...",
+  thread_id: epic_id,
+});
+```
+
+### Checking for Messages
+
+```typescript
+// Check inbox (max 5, no bodies for context safety)
+const inbox = await swarmmail_inbox();
+
+// Read specific message body
+const message = await swarmmail_read_message({ message_id: N });
+```
+
+### Reporting Blockers
+
+```typescript
+swarmmail_send({
+  to: ["coordinator"],
+  subject: "BLOCKED: Need DB schema",
+  body: "Can't proceed without users table",
+  thread_id: epic_id,
+  importance: "urgent",
+});
+```
+
+## Best Practices
+
+1. **Initialize Swarm Mail first** - Always call `swarmmail_init` before any work
+2. **Small, focused subtasks** - Each subtask should be completable in one agent session
+3. **Clear boundaries** - Define exactly what files/modules each subtask touches
+4. **Explicit handoffs** - When one task enables another, communicate clearly
+5. **Graceful failures** - If a subtask fails, don't block the whole swarm
+6. **Progress updates** - Use beads to track subtask status
+7. **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]
+  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]
+  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]
+  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. Initialize Swarm Mail with `swarmmail_init`
+2. Load `swarm-coordination` skill
+3. Analyze task type
+4. Load additional skills based on domain (testing, design, CLI)
+5. Include skill recommendations in `shared_context` for workers
+
+**For Workers:**
+
+1. Initialize Swarm Mail with `swarmmail_init`
+2. Read `shared_context` from coordinator
+3. Load recommended skills with `skills_use(name="skill-name")`
+4. Apply skill knowledge to subtask
+5. Report progress via `swarmmail_send`
+6. Complete with `swarm_complete`
+
+**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]
+```
+
+## 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               |