opencode-swarm-plugin 0.26.0 → 0.27.0

package/examples/skills/{beads-workflow → hive-workflow}/SKILL.md

@@ -1,29 +1,29 @@
 ---
-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.
+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:
-  - beads
+  - hive
   - issues
   - tracking
   - workflow
 tools:
-  - beads_create
-  - beads_query
-  - beads_update
-  - beads_close
-  - beads_create_epic
-  - beads_sync
+  - hive_create
+  - hive_query
+  - hive_update
+  - hive_close
+  - hive_create_epic
+  - hive_sync
 related_skills:
   - swarm-coordination
 ---
 
-# Beads Workflow Skill
+# Hive Workflow Skill
 
-Beads is a local-first issue tracking system designed for AI agents. This skill provides best practices for effective bead management.
+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/.
 
-## Bead Types
+## Cell Types
 
 | Type      | When to Use                             |
 | --------- | --------------------------------------- |
@@ -33,9 +33,9 @@ Beads is a local-first issue tracking system designed for AI agents. This skill
 | `chore`   | Maintenance, refactoring, dependencies  |
 | `epic`    | Large initiative with multiple subtasks |
 
-## Creating Effective Beads
+## Creating Effective Cells
 
-### Good Bead Titles
+### Good Cell Titles
 
 ```text
 - "Fix null pointer exception in UserService.getProfile()"
@@ -43,7 +43,7 @@ Beads is a local-first issue tracking system designed for AI agents. This skill
 - "Migrate auth tokens from localStorage to httpOnly cookies"
 ```
 
-### Bad Bead Titles
+### Bad Cell Titles
 
 ```text
 - "Fix bug" (too vague)
@@ -51,7 +51,7 @@ Beads is a local-first issue tracking system designed for AI agents. This skill
 - "stuff" (meaningless)
 ```
 
-### Bead Body Structure
+### Cell Body Structure
 
 ```markdown
 ## Problem
@@ -93,15 +93,15 @@ open → in_progress → closed
 ### Open → In Progress
 
 ```typescript
-beads_update(id: "abc123", state: "in_progress")
+hive_update(id: "hv-abc123", state: "in_progress")
 ```
 
-Use when you start working on a bead.
+Use when you start working on a cell.
 
 ### In Progress → Closed
 
 ```typescript
-beads_close(id: "abc123", resolution: "Fixed in commit abc1234")
+hive_close(id: "hv-abc123", resolution: "Fixed in commit abc1234")
 ```
 
 Use when work is complete.
@@ -109,29 +109,29 @@ Use when work is complete.
 ### In Progress → Blocked
 
 ```typescript
-beads_update(id: "abc123", state: "blocked", body: "Blocked by #xyz789")
+hive_update(id: "hv-abc123", state: "blocked", body: "Blocked by #hv-xyz789")
 ```
 
 Use when you can't proceed due to a dependency.
 
-## Querying Beads
+## Querying Cells
 
 ### Find Open Work
 
 ```typescript
-beads_query(state: "open", type: "bug")
+hive_query(state: "open", type: "bug")
 ```
 
 ### Search by Keywords
 
 ```typescript
-beads_query(search: "authentication")
+hive_query(search: "authentication")
 ```
 
 ### List Recent Activity
 
 ```typescript
-beads_query(limit: 10, sort: "updated")
+hive_query(limit: 10, sort: "updated")
 ```
 
 ## Epic Management
@@ -150,10 +150,10 @@ 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
+- [ ] #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
@@ -161,32 +161,32 @@ Modernize the authentication system
 1. Create the epic first:
 
 ```typescript
-beads_create(type: "epic", title: "User Auth Overhaul", body: "...")
+hive_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")
+hive_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
+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 beads** - Use `#bead-id` references
+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
 
-Beads sync with git:
+Cells sync with git:
 
 - Changes tracked locally
-- Use `beads_sync()` to commit and push to remote
+- Use `hive_sync()` to commit and push to remote
 
 ## Integration with Swarm
 
@@ -194,15 +194,15 @@ When working in a swarm:
 
 ```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
+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 beads as subtasks complete
+5. Close cells as subtasks complete
 6. Close epic when all subtasks done
-7. Sync with `beads_sync()` (MANDATORY at session end)
+7. Sync with `hive_sync()` (MANDATORY at session end)
 ```
 
-### Skill Recommendations for Common Bead Types
+### Skill Recommendations for Common Cell Types
 
 ```text
 - `type: "bug"` → Load `testing-patterns` for regression tests

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

@@ -36,7 +36,7 @@ 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
+- Thread-based coordination tied to cells
 
 ## When to Use Swarm Coordination
 

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

@@ -13,8 +13,8 @@ tools:
   - swarm_complete
   - swarm_status
   - swarm_progress
-  - beads_create_epic
-  - beads_query
+  - hive_create_epic
+  - hive_query
   - swarmmail_init
   - swarmmail_send
   - swarmmail_inbox
@@ -43,7 +43,7 @@ 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
+- Thread-based coordination tied to cells
 
 ## When to Swarm
 
@@ -262,7 +262,7 @@ I'd recommend (${recommendation.letter}) because ${recommendation.reason}. Which
 **Confirm Only (`--confirm-only`):**
 
 - Generate plan silently
-- Show final BeadTree
+- Show final CellTree
 - Get yes/no only
 
 **Rules for Socratic Mode:**
@@ -308,7 +308,7 @@ Synthesize findings into `shared_context` for workers.
 >
 > **NEVER do planning inline in the coordinator thread.** Decomposition work (file reading, CASS searching, reasoning about task breakdown) consumes massive amounts of context and will exhaust your token budget on long swarms.
 >
-> **ALWAYS delegate planning to a `swarm/planner` subagent** and receive only the structured BeadTree JSON result back.
+> **ALWAYS delegate planning to a `swarm/planner` subagent** and receive only the structured CellTree JSON result back.
 
 **❌ Anti-Pattern (Context-Heavy):**
 
@@ -324,7 +324,7 @@ const validation = await swarm_validate_decomposition({ ... });
 
 ```typescript
 // 1. Create planning bead with full context
-await beads_create({
+await hive_create({
   title: `Plan: ${taskTitle}`,
   type: "task",
   description: `Decompose into subtasks. Context: ${synthesizedContext}`,
@@ -335,7 +335,7 @@ const planningResult = await Task({
   subagent_type: "swarm/planner",
   description: `Decompose task: ${taskTitle}`,
   prompt: `
-You are a swarm planner. Generate a BeadTree for this task.
+You are a swarm planner. Generate a CellTree for this task.
 
 ## Task
 ${taskDescription}
@@ -346,11 +346,11 @@ ${synthesizedContext}
 ## Instructions
 1. Use swarm_plan_prompt(task="...", max_subtasks=5, query_cass=true)
 2. Reason about decomposition strategy
-3. Generate BeadTree JSON
+3. Generate CellTree JSON
 4. Validate with swarm_validate_decomposition
-5. Return ONLY the validated BeadTree JSON (no analysis, no file contents)
+5. Return ONLY the validated CellTree JSON (no analysis, no file contents)
 
-Output format: Valid BeadTree JSON only.
+Output format: Valid CellTree JSON only.
   `,
 });
 
@@ -358,7 +358,7 @@ Output format: Valid BeadTree JSON only.
 const beadTree = JSON.parse(planningResult);
 
 // 4. Create epic + subtasks atomically
-await beads_create_epic({
+await hive_create_epic({
   epic_title: beadTree.epic.title,
   epic_description: beadTree.epic.description,
   subtasks: beadTree.subtasks,
@@ -474,7 +474,7 @@ await swarm_complete({
   files_touched: [...],
 });
 await swarmmail_release(); // Release any remaining reservations
-await beads_sync();
+await hive_sync();
 ```
 
 ## Context Survival Patterns (CRITICAL)
@@ -793,7 +793,7 @@ skills_list();
 // 3. Decompose
 swarm_plan_prompt({ task });
 swarm_validate_decomposition();
-beads_create_epic();
+hive_create_epic();
 
 // 4. Reserve files
 swarmmail_reserve({ paths, reason, ttl_seconds });
@@ -809,7 +809,7 @@ swarmmail_read_message({ message_id });
 // 7. Complete
 swarm_complete();
 swarmmail_release();
-beads_sync();
+hive_sync();
 ```
 
 See `references/coordinator-patterns.md` for detailed patterns.

package/global-skills/swarm-coordination/references/coordinator-patterns.md

@@ -35,7 +35,7 @@ After knowledge gathering:
 1. Select strategy (auto or explicit)
 2. Generate decomposition with `swarm_plan_prompt` or `swarm_decompose`
 3. Validate with `swarm_validate_decomposition`
-4. Create beads with `beads_create_epic`
+4. Create cells with `hive_create_epic`
 
 ### 3. Worker Spawning
 
@@ -48,7 +48,7 @@ For each subtask:
 
 ### 4. Progress Monitoring
 
-- Check `beads_query(status="in_progress")` for active work
+- Check `hive_query(status="in_progress")` for active work
 - Check `swarmmail_inbox()` for worker messages
 - Intervene on blockers (see Intervention Patterns below)
 
@@ -97,7 +97,7 @@ For each subtask:
 - Scope changed fundamentally mid-swarm
 - Resource exhaustion (context, time, cost)
 
-On abort: Close all beads with reason, summarize partial progress.
+On abort: Close all cells with reason, summarize partial progress.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,7 @@
     "@opencode-ai/plugin": "^1.0.134",
     "gray-matter": "^4.0.3",
     "ioredis": "^5.4.1",
-    "swarm-mail": "0.2.0",
+    "swarm-mail": "0.3.0",
     "zod": "4.1.8"
   },
   "devDependencies": {

package/src/compaction-hook.ts

@@ -0,0 +1,161 @@
+/**
+ * Swarm-Aware Compaction Hook
+ *
+ * Provides context preservation during OpenCode session compaction.
+ * When context is compacted, this hook injects instructions for the summarizer
+ * to preserve swarm coordination state and enable seamless resumption.
+ *
+ * Hook signature (from @opencode-ai/plugin):
+ * ```typescript
+ * "experimental.session.compacting"?: (
+ *   input: { sessionID: string },
+ *   output: { context: string[] }
+ * ) => Promise<void>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { SWARM_COMPACTION_CONTEXT, createCompactionHook } from "opencode-swarm-plugin";
+ *
+ * const hooks: Hooks = {
+ *   "experimental.session.compacting": createCompactionHook(),
+ * };
+ * ```
+ */
+
+// ============================================================================
+// Compaction Context
+// ============================================================================
+
+/**
+ * Swarm-aware compaction context
+ *
+ * Injected during compaction to keep the swarm cooking. The coordinator should
+ * wake up from compaction and immediately resume orchestration - spawning agents,
+ * monitoring progress, unblocking work.
+ *
+ * This is NOT about preserving state for a human - it's about the swarm continuing
+ * autonomously after context compression.
+ */
+export const SWARM_COMPACTION_CONTEXT = `## 🐝 SWARM ACTIVE - Keep Cooking
+
+You are the **COORDINATOR** of an active swarm. Context was compacted but the swarm is still running.
+
+**YOUR JOB:** Keep orchestrating. Spawn agents. Monitor progress. Unblock work. Ship it.
+
+### Preserve in Summary
+
+Extract from session context:
+
+1. **Epic & Subtasks** - IDs, titles, status, file assignments
+2. **What's Running** - Which agents are active, what they're working on  
+3. **What's Blocked** - Blockers and what's needed to unblock
+4. **What's Done** - Completed work and any follow-ups needed
+5. **What's Next** - Pending subtasks ready to spawn
+
+### Summary Format
+
+\`\`\`
+## 🐝 Swarm State
+
+**Epic:** <bd-xxx> - <title>
+**Project:** <path>
+**Progress:** X/Y subtasks complete
+
+**Active:**
+- <bd-xxx>: <title> [in_progress] → <agent> working on <files>
+
+**Blocked:**
+- <bd-xxx>: <title> - BLOCKED: <reason>
+
+**Completed:**
+- <bd-xxx>: <title> ✓
+
+**Ready to Spawn:**
+- <bd-xxx>: <title> (files: <...>)
+\`\`\`
+
+### On Resume - IMMEDIATELY
+
+1. \`swarm_status(epic_id="<epic>", project_key="<path>")\` - Get current state
+2. \`swarmmail_inbox(limit=5)\` - Check for agent messages
+3. **Spawn ready subtasks** - Don't wait, fire them off
+4. **Unblock blocked work** - Resolve dependencies, reassign if needed
+5. **Collect completed work** - Close done subtasks, verify quality
+
+### Keep the Swarm Cooking
+
+- **Spawn aggressively** - If a subtask is ready and unblocked, spawn an agent
+- **Monitor actively** - Check status, read messages, respond to blockers
+- **Close the loop** - When all subtasks done, verify and close the epic
+- **Don't stop** - The swarm runs until the epic is closed
+
+**You are not waiting for instructions. You are the coordinator. Coordinate.**
+`;
+
+// ============================================================================
+// Hook Registration Helper
+// ============================================================================
+
+/**
+ * Check for swarm sign - evidence a swarm passed through
+ * 
+ * Like deer scat on a trail, we look for traces:
+ * - In-progress cells (active work)
+ * - Open cells with parent_id (subtasks of an epic)
+ * - Unclosed epics
+ * 
+ * Uses the adapter directly to query beads.
+ */
+import { getHiveAdapter, getHiveWorkingDirectory } from "./hive";
+
+async function hasSwarmSign(): Promise<boolean> {
+  try {
+    const projectKey = getHiveWorkingDirectory();
+    const adapter = await getHiveAdapter(projectKey);
+    const cells = await adapter.queryCells(projectKey, {});
+    
+    if (!Array.isArray(cells)) return false;
+
+    // Look for swarm sign:
+    // 1. Any in_progress cells
+    // 2. Any open cells with a parent (subtasks)
+    // 3. Any epics that aren't closed
+    return cells.some(
+      (c) =>
+        c.status === "in_progress" ||
+        (c.status === "open" && c.parent_id) ||
+        (c.type === "epic" && c.status !== "closed"),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create the compaction hook for use in plugin registration
+ *
+ * Only injects swarm context if there's an active swarm (in-progress beads).
+ * This keeps the coordinator cooking after compaction.
+ *
+ * @example
+ * ```typescript
+ * import { createCompactionHook } from "opencode-swarm-plugin";
+ *
+ * export const SwarmPlugin: Plugin = async () => ({
+ *   tool: { ... },
+ *   "experimental.session.compacting": createCompactionHook(),
+ * });
+ * ```
+ */
+export function createCompactionHook() {
+  return async (
+    _input: { sessionID: string },
+    output: { context: string[] },
+  ): Promise<void> => {
+    const hasSign = await hasSwarmSign();
+    if (hasSign) {
+      output.context.push(SWARM_COMPACTION_CONTEXT);
+    }
+  };
+}