opencode-multiagent 0.2.0

package/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: dispatching-parallel-agents
+description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+---
+
+# Dispatching Parallel Agents
+
+## Overview
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes

package/skills/dispatching-parallel-agents/manifest.json

@@ -0,0 +1,18 @@
+{
+  "name": "dispatching-parallel-agents",
+  "version": "1.0.0",
+  "description": "Guidance for splitting independent work across multiple agents in parallel",
+  "triggers": [
+    "parallel agents",
+    "parallel dispatch",
+    "concurrent tasks",
+    "independent subtasks",
+    "parallelize"
+  ],
+  "applicable_agents": [
+    "critic",
+    "strategist"
+  ],
+  "max_context_tokens": 1800,
+  "entry_file": "SKILL.md"
+}

package/skills/drift-analysis/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: drift-analysis
+description: Use when the user asks about plan drift, reality check, comparing docs to code, project state analysis, roadmap alignment, implementation gaps, or needs guidance on identifying discrepancies between documented plans and actual implementation state.
+version: 5.1.0
+---
+
+# Drift Analysis
+
+Knowledge and patterns for analyzing project state, detecting plan drift, and creating prioritized reconstruction plans.
+
+## Architecture Overview
+
+```
+/drift-detect
+        │
+        ├─→ collectors.js (pure JavaScript)
+        │   ├─ scanGitHubState()
+        │   ├─ analyzeDocumentation()
+        │   └─ scanCodebase()
+        │
+        └─→ plan-synthesizer (Opus)
+            └─ Deep semantic analysis with full context
+```
+
+**Data collection**: Pure JavaScript (no LLM overhead)
+**Semantic analysis**: Single Opus call with complete context
+
+## Drift Detection Patterns
+
+### Types of Drift
+
+**Plan Drift**: When documented plans diverge from actual implementation
+- PLAN.md items remain unchecked for extended periods
+- Roadmap milestones slip without updates
+- Sprint/phase goals not reflected in code changes
+
+**Documentation Drift**: When documentation falls behind implementation
+- New features exist without corresponding docs
+- README describes features that don't exist
+- API docs don't match actual endpoints
+
+**Issue Drift**: When issue tracking diverges from reality
+- Stale issues that no longer apply
+- Completed work without closed issues
+- High-priority items neglected
+
+**Scope Drift**: When project scope expands beyond original plans
+- More features documented than can be delivered
+- Continuous addition without completion
+- Ever-growing backlog with no pruning
+
+### Detection Signals
+
+```
+HIGH-CONFIDENCE DRIFT INDICATORS:
+- Milestone 30+ days overdue with open issues
+- PLAN.md < 30% completion after 90 days
+- 5+ high-priority issues stale > 60 days
+- README features not found in codebase
+
+MEDIUM-CONFIDENCE INDICATORS:
+- Documentation files unchanged for 180+ days
+- Draft PRs open > 30 days
+- Issue themes don't match code activity
+- Large gap between documented and implemented features
+
+LOW-CONFIDENCE INDICATORS:
+- Many TODOs in codebase
+- Stale dependencies
+- Old git branches not merged
+```
+
+## Prioritization Framework
+
+### Priority Calculation
+
+```javascript
+function calculatePriority(item, weights) {
+  let score = 0;
+
+  // Severity base score
+  const severityScores = {
+    critical: 15,
+    high: 10,
+    medium: 5,
+    low: 2
+  };
+  score += severityScores[item.severity] || 5;
+
+  // Category multiplier
+  const categoryWeights = {
+    security: 2.0,    // Security issues get 2x
+    bugs: 1.5,        // Bugs get 1.5x
+    infrastructure: 1.3,
+    features: 1.0,
+    documentation: 0.8
+  };
+  score *= categoryWeights[item.category] || 1.0;
+
+  // Recency boost
+  if (item.createdRecently) score *= 1.2;
+
+  // Stale penalty (old items slightly deprioritized)
+  if (item.daysStale > 180) score *= 0.9;
+
+  return Math.round(score);
+}
+```
+
+### Time Bucket Thresholds
+
+| Bucket | Criteria | Max Items |
+|--------|----------|-----------|
+| Immediate | severity=critical OR priority >= 15 | 5 |
+| Short-term | severity=high OR priority >= 10 | 10 |
+| Medium-term | priority >= 5 | 15 |
+| Backlog | everything else | 20 |
+
+### Priority Weights (Default)
+
+```yaml
+security: 10     # Security issues always top priority
+bugs: 8          # Bugs affect users directly
+features: 5      # New functionality
+documentation: 3 # Important but not urgent
+tech-debt: 4     # Keeps codebase healthy
+```
+
+## Cross-Reference Patterns
+
+### Document-to-Code Matching
+
+```javascript
+// Fuzzy matching for feature names
+function featureMatch(docFeature, codeFeature) {
+  const normalize = s => s
+    .toLowerCase()
+    .replace(/[-_\s]+/g, '')
+    .replace(/s$/, ''); // Remove trailing 's'
+
+  const docNorm = normalize(docFeature);
+  const codeNorm = normalize(codeFeature);
+
+  return docNorm.includes(codeNorm) ||
+         codeNorm.includes(docNorm) ||
+         levenshteinDistance(docNorm, codeNorm) < 3;
+}
+```
+
+### Common Mismatches
+
+| Documented As | Implemented As |
+|---------------|----------------|
+| "user authentication" | auth/, login/, session/ |
+| "API endpoints" | routes/, api/, handlers/ |
+| "database models" | models/, entities/, schemas/ |
+| "caching layer" | cache/, redis/, memcache/ |
+| "logging system" | logger/, logs/, telemetry/ |
+
+## Output Templates
+
+### Drift Report Section
+
+```markdown
+## Drift Analysis
+
+### {drift_type}
+**Severity**: {severity}
+**Detected In**: {source}
+
+{description}
+
+**Evidence**:
+{evidence_items}
+
+**Recommendation**: {recommendation}
+```
+
+### Gap Report Section
+
+```markdown
+## Gap: {gap_title}
+
+**Category**: {category}
+**Severity**: {severity}
+
+{description}
+
+**Impact**: {impact_description}
+
+**To Address**:
+1. {action_item_1}
+2. {action_item_2}
+```
+
+### Reconstruction Plan Section
+
+```markdown
+## Reconstruction Plan
+
+### Immediate Actions (This Week)
+{immediate_items_numbered}
+
+### Short-Term (This Month)
+{short_term_items_numbered}
+
+### Medium-Term (This Quarter)
+{medium_term_items_numbered}
+
+### Backlog
+{backlog_items_numbered}
+```
+
+## Best Practices
+
+### When Analyzing Drift
+
+1. **Compare timestamps, not just content**
+   - When was the doc last updated vs. last code change?
+   - Are milestones dated realistically?
+
+2. **Look for patterns, not individual items**
+   - One stale issue isn't drift; 10 stale issues is a pattern
+   - One undocumented feature isn't drift; 5 undocumented features is
+
+3. **Consider context**
+   - Active development naturally has some drift
+   - Mature projects should have minimal drift
+   - Post-launch projects often have documentation lag
+
+4. **Weight by impact**
+   - User-facing drift matters more than internal
+   - Public API drift matters more than implementation details
+
+### When Creating Plans
+
+1. **Be actionable, not exhaustive**
+   - Top 5 immediate items, not top 50
+   - Each item should be completable in reasonable time
+
+2. **Group related items**
+   - "Update authentication docs" not "Update login page docs" + "Update signup docs"
+
+3. **Include success criteria**
+   - How do we know this drift item is resolved?
+
+4. **Balance categories**
+   - All security first, but don't ignore everything else
+   - Mix quick wins with important work
+
+## Data Collection (JavaScript)
+
+The collectors.js module extracts data without LLM overhead:
+
+### GitHub Data
+- Open issues categorized by labels
+- Open PRs with draft status
+- Milestones with due dates
+- Stale items (> 90 days inactive)
+- Theme analysis from titles
+
+### Documentation Data
+- Parsed README, PLAN.md, CLAUDE.md, CHANGELOG.md
+- Checkbox completion counts
+- Section analysis
+- Feature lists
+
+### Code Data
+- Directory structure
+- Framework detection
+- Test framework presence
+- Health indicators (CI, linting, tests)
+
+## Semantic Analysis (Opus)
+
+The plan-synthesizer receives all collected data and performs:
+
+1. **Cross-referencing**: Match documented features to implementation
+2. **Drift identification**: Find divergence patterns
+3. **Gap analysis**: Identify what's missing
+4. **Prioritization**: Context-aware ranking
+5. **Report generation**: Actionable recommendations
+
+## Example Input/Output
+
+### Collected Data (from collectors.js)
+
+```json
+{
+  "github": {
+    "issues": [...],
+    "categorized": { "bugs": [...], "features": [...] },
+    "stale": [...]
+  },
+  "docs": {
+    "files": { "README.md": {...}, "PLAN.md": {...} },
+    "checkboxes": { "total": 15, "checked": 3 }
+  },
+  "code": {
+    "frameworks": ["Express"],
+    "health": { "hasTests": true, "hasCi": true }
+  }
+}
+```
+
+### Analysis Output (from plan-synthesizer)
+
+```markdown
+# Reality Check Report
+
+## Executive Summary
+Project has moderate drift: 8 stale priority issues and 20% plan completion.
+Strong code health (tests + CI) but documentation lags implementation.
+
+## Drift Analysis
+### Priority Neglect
+**Severity**: high
+8 high-priority issues inactive for 60+ days...
+
+## Prioritized Plan
+### Immediate
+1. Close #45 (already implemented)
+2. Update README API section...
+```

package/skills/drift-analysis/manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "drift-analysis",
+  "version": "1.0.0",
+  "description": "Analyze plan drift between documented intent and repository reality",
+  "triggers": [
+    "drift",
+    "reality check",
+    "plan drift",
+    "implementation gap",
+    "roadmap alignment"
+  ],
+  "applicable_agents": [
+    "planner",
+    "auditor",
+    "strategist"
+  ],
+  "max_context_tokens": 2000,
+  "entry_file": "SKILL.md"
+}

package/skills/evaluation/SKILL.md

@@ -0,0 +1,5 @@
+# Evaluation
+
+- Define the comparison criteria before scoring options.
+- Separate facts, assumptions, and preferences.
+- Explain the final judgment with concrete trade-offs.

package/skills/evaluation/manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "evaluation",
+  "version": "1.0.0",
+  "description": "Lightweight evaluation framework for judgments and comparisons",
+  "triggers": [
+    "evaluate",
+    "assess",
+    "judge",
+    "compare",
+    "rate"
+  ],
+  "applicable_agents": [
+    "reviewer",
+    "critic",
+    "advisor"
+  ],
+  "max_context_tokens": 1500,
+  "entry_file": "SKILL.md"
+}

package/skills/executing-plans/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute all tasks, report when complete.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Tasks
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Stop when blocked, don't guess
+- Never start implementation on main/master branch without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+- **superpowers:writing-plans** - Creates the plan this skill executes
+- **superpowers:finishing-a-development-branch** - Complete development after all tasks

package/skills/executing-plans/manifest.json

@@ -0,0 +1,17 @@
+{
+  "name": "executing-plans",
+  "version": "1.0.0",
+  "description": "Execution guidance for following an existing implementation plan with checkpoints",
+  "triggers": [
+    "execute plan",
+    "follow plan",
+    "implementation plan",
+    "carry out plan",
+    "execution checkpoints"
+  ],
+  "applicable_agents": [
+    "executor"
+  ],
+  "max_context_tokens": 2000,
+  "entry_file": "SKILL.md"
+}

package/skills/handoff-protocols/SKILL.md

@@ -0,0 +1,5 @@
+# Handoff Protocols
+
+- State the current objective, status, and remaining risks.
+- Name the exact files, commands, and evidence the next owner needs.
+- End with explicit next actions and verification expectations.

package/skills/handoff-protocols/manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "handoff-protocols",
+  "version": "1.0.0",
+  "description": "Guidance for safe multi-agent or multi-step handoffs",
+  "triggers": [
+    "handoff",
+    "transfer",
+    "transition",
+    "pass to",
+    "onboard"
+  ],
+  "applicable_agents": [
+    "executor",
+    "planner",
+    "worker"
+  ],
+  "max_context_tokens": 1500,
+  "entry_file": "SKILL.md"
+}