opencode-swarm-plugin 0.61.0 → 0.62.0

package/dist/swarm-prompts.js

@@ -17256,6 +17256,7 @@ __export(exports_skills, {
   validateCSOCompliance: () => validateCSOCompliance,
   skills_use: () => skills_use,
   skills_update: () => skills_update,
+  skills_reload: () => skills_reload,
   skills_read: () => skills_read,
   skills_list: () => skills_list,
   skills_init: () => skills_init,
@@ -17740,7 +17741,7 @@ var import_gray_matter, ALWAYS_ON_GUIDANCE_HEADER = "## Always-On Guidance Skill
 - Read before Edit; no speculative changes or output`, OPUS_4_5_GUIDANCE = `#### Opus 4.5 (Concise)
 - Be concise and deliberate while obeying mandates
 - Follow tool priorities without shortcuts
-- Prefer direct answers over speculation`, skillsProjectDirectory, skillsCache = null, PROJECT_SKILL_DIRECTORIES, skills_list, skills_use, skills_execute, skills_read, DEFAULT_SKILLS_DIR = ".opencode/skill", skills_create, skills_update, skills_delete, skills_add_script, skills_init, skillsTools;
+- Prefer direct answers over speculation`, skillsProjectDirectory, skillsCache = null, PROJECT_SKILL_DIRECTORIES, skills_list, skills_use, skills_execute, skills_read, DEFAULT_SKILLS_DIR = ".opencode/skill", skills_create, skills_update, skills_delete, skills_add_script, skills_reload, skills_init, skillsTools;
 var init_skills = __esm(() => {
   init_dist();
   import_gray_matter = __toESM(require_gray_matter(), 1);
@@ -18170,6 +18171,38 @@ executed with skills_execute. Use for:
       }
     }
   });
+  skills_reload = tool({
+    description: `Hot-reload skills by clearing cache and re-scanning skill directories.
+
+Use this to:
+- Test a newly created skill immediately without restarting
+- Verify skill modifications took effect
+- Refresh skills after external changes
+
+The tool clears the cached skills, re-scans all skill directories,
+and returns a list of loaded skills.`,
+    args: {},
+    async execute() {
+      invalidateSkillsCache();
+      const skills = await discoverSkills();
+      const refs = Array.from(skills.values()).map((skill) => ({
+        name: skill.metadata.name,
+        description: skill.metadata.description,
+        path: skill.path,
+        hasScripts: skill.hasScripts
+      }));
+      return JSON.stringify({
+        success: true,
+        reloaded: refs.length,
+        skills: refs.map((r) => ({
+          name: r.name,
+          description: r.description,
+          hasScripts: r.hasScripts
+        })),
+        message: `Reloaded ${refs.length} skill(s). All skills are now up-to-date.`
+      }, null, 2);
+    }
+  });
   skills_init = tool({
     description: `Initialize a new skill with full directory structure and templates.
 
@@ -18282,6 +18315,7 @@ echo "Project directory: $1"
     skills_update,
     skills_delete,
     skills_add_script,
+    skills_reload,
     skills_init
   };
 });
@@ -39524,6 +39558,7 @@ var EpicCreateArgsSchema = exports_external.object({
   epic_id: exports_external.string().optional(),
   subtasks: exports_external.array(exports_external.object({
     title: exports_external.string().min(1),
+    description: exports_external.string().optional(),
     priority: exports_external.number().int().min(0).max(3).default(2),
     files: exports_external.array(exports_external.string()).optional().default([]),
     id_suffix: exports_external.string().optional()
@@ -40553,7 +40588,8 @@ var hive_create_epic = tool({
           title: subtask.title,
           type: "task",
           priority: subtask.priority ?? 2,
-          parent_id: epic.id
+          parent_id: epic.id,
+          description: subtask.description
         });
         await adapter.markDirty(projectKey, subtaskCell.id);
         created.push(subtaskCell);
@@ -43806,6 +43842,152 @@ var swarm_recover = tool({
     }
   }
 });
+var swarm_branch = tool({
+  description: "Create a session branch for exploration. Saves current context with a label for later return.",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Current subtask bead ID"),
+    epic_id: tool.schema.string().describe("Epic bead ID"),
+    branch_label: tool.schema.string().describe("Label for this branch (e.g., 'debug-cache-issue')"),
+    branch_purpose: tool.schema.string().describe("Why branching? (e.g., 'investigate API timeout')"),
+    files_modified: tool.schema.array(tool.schema.string()).describe("Files modified before branching"),
+    progress_percent: tool.schema.number().min(0).max(100).optional().describe("Current progress percentage")
+  },
+  async execute(args) {
+    try {
+      const branchId = `branch-${Date.now()}-${args.branch_label.replace(/[^a-z0-9-]/gi, "-")}`;
+      const checkpoint = {
+        epic_id: args.epic_id,
+        bead_id: args.bead_id,
+        strategy: "file-based",
+        files: args.files_modified,
+        dependencies: [],
+        directives: {
+          branch_label: args.branch_label,
+          branch_purpose: args.branch_purpose,
+          branch_id: branchId
+        },
+        recovery: {
+          last_checkpoint: Date.now(),
+          files_modified: args.files_modified,
+          progress_percent: args.progress_percent || 0,
+          last_message: `Branched for: ${args.branch_purpose}`
+        }
+      };
+      const { createEvent: createEvent5, appendEvent: appendEvent4 } = await import("swarm-mail");
+      const checkpointData = JSON.stringify(checkpoint);
+      const event = createEvent5("swarm_checkpointed", {
+        project_key: args.project_key,
+        epic_id: args.epic_id,
+        bead_id: args.bead_id,
+        strategy: checkpoint.strategy,
+        files: checkpoint.files,
+        dependencies: checkpoint.dependencies,
+        directives: checkpoint.directives,
+        recovery: checkpoint.recovery,
+        checkpoint_size_bytes: Buffer.byteLength(checkpointData, "utf8"),
+        trigger: "manual"
+      });
+      await appendEvent4(event, args.project_key);
+      return JSON.stringify({
+        success: true,
+        branch_id: branchId,
+        branch_label: args.branch_label,
+        branch_purpose: args.branch_purpose,
+        checkpoint_timestamp: Date.now(),
+        message: `Session branched: ${args.branch_label}. Use swarm_return to restore main context.`,
+        files_snapshot: args.files_modified
+      }, null, 2);
+    } catch (error45) {
+      console.warn(`[swarm_branch] Failed to create branch ${args.branch_label}:`, error45);
+      return JSON.stringify({
+        success: false,
+        error: error45 instanceof Error ? error45.message : String(error45),
+        message: `Failed to branch session: ${args.branch_label}`
+      }, null, 2);
+    }
+  }
+});
+var swarm_return = tool({
+  description: "Return from session branch. Restores main context, optionally carrying back learnings.",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    epic_id: tool.schema.string().describe("Epic bead ID"),
+    branch_label: tool.schema.string().optional().describe("Label of branch to return from (defaults to latest)"),
+    carry_back_learnings: tool.schema.string().optional().describe("Learnings or insights to carry back to main context"),
+    carry_back_files: tool.schema.array(tool.schema.string()).optional().describe("Files to preserve from branch (others discarded)")
+  },
+  async execute(args) {
+    try {
+      const { getSwarmMailLibSQL: getSwarmMailLibSQL5 } = await import("swarm-mail");
+      const swarmMail = await getSwarmMailLibSQL5(args.project_key);
+      const db = await swarmMail.getDatabase();
+      const result = await db.query(args.branch_label ? `SELECT * FROM swarm_contexts
+             WHERE epic_id = $1 AND json_extract(directives, '$.branch_label') = $2
+             ORDER BY updated_at DESC
+             LIMIT 1` : `SELECT * FROM swarm_contexts
+             WHERE epic_id = $1 AND json_extract(directives, '$.branch_id') IS NOT NULL
+             ORDER BY updated_at DESC
+             LIMIT 1`, args.branch_label ? [args.epic_id, args.branch_label] : [args.epic_id]);
+      if (!result.rows || result.rows.length === 0) {
+        return JSON.stringify({
+          success: false,
+          found: false,
+          message: args.branch_label ? `No branch found with label: ${args.branch_label}` : "No branch checkpoints found for this epic",
+          epic_id: args.epic_id
+        }, null, 2);
+      }
+      const row = result.rows[0];
+      const parseIfString = (val) => typeof val === "string" ? JSON.parse(val) : val;
+      const context = {
+        id: row.id,
+        epic_id: row.epic_id,
+        bead_id: row.bead_id,
+        strategy: row.strategy,
+        files: parseIfString(row.files),
+        dependencies: parseIfString(row.dependencies),
+        directives: parseIfString(row.directives),
+        recovery: parseIfString(row.recovery),
+        created_at: row.created_at,
+        updated_at: row.updated_at
+      };
+      const { createEvent: createEvent5, appendEvent: appendEvent4 } = await import("swarm-mail");
+      const event = createEvent5("swarm_recovered", {
+        project_key: args.project_key,
+        epic_id: args.epic_id,
+        bead_id: context.bead_id,
+        recovered_from_checkpoint: context.recovery.last_checkpoint
+      });
+      await appendEvent4(event, args.project_key);
+      const branchLabel = context.directives.branch_label || "unnamed-branch";
+      return JSON.stringify({
+        success: true,
+        found: true,
+        branch_label: branchLabel,
+        branch_purpose: context.directives.branch_purpose,
+        context_restored: {
+          bead_id: context.bead_id,
+          files: context.files,
+          progress_percent: context.recovery.progress_percent
+        },
+        learnings_carried_back: args.carry_back_learnings || null,
+        files_carried_back: args.carry_back_files || [],
+        message: `Returned from branch: ${branchLabel}`,
+        age_seconds: Math.round((Date.now() - context.updated_at) / 1000)
+      }, null, 2);
+    } catch (error45) {
+      console.warn(`[swarm_return] Failed to return from branch:`, error45);
+      return JSON.stringify({
+        success: false,
+        found: false,
+        error: error45 instanceof Error ? error45.message : String(error45),
+        message: "Failed to return from branch",
+        epic_id: args.epic_id
+      }, null, 2);
+    }
+  }
+});
 var swarm_learn = tool({
   description: `Analyze completed work and optionally create a skill from learned patterns.
 

package/dist/swarm.d.ts

@@ -340,6 +340,46 @@ export declare const swarmTools: {
             epic_id: string;
         }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
     };
+    swarm_branch: {
+        description: string;
+        args: {
+            project_key: import("zod").ZodString;
+            agent_name: import("zod").ZodString;
+            bead_id: import("zod").ZodString;
+            epic_id: import("zod").ZodString;
+            branch_label: import("zod").ZodString;
+            branch_purpose: import("zod").ZodString;
+            files_modified: import("zod").ZodArray<import("zod").ZodString>;
+            progress_percent: import("zod").ZodOptional<import("zod").ZodNumber>;
+        };
+        execute(args: {
+            project_key: string;
+            agent_name: string;
+            bead_id: string;
+            epic_id: string;
+            branch_label: string;
+            branch_purpose: string;
+            files_modified: string[];
+            progress_percent?: number | undefined;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
+    swarm_return: {
+        description: string;
+        args: {
+            project_key: import("zod").ZodString;
+            epic_id: import("zod").ZodString;
+            branch_label: import("zod").ZodOptional<import("zod").ZodString>;
+            carry_back_learnings: import("zod").ZodOptional<import("zod").ZodString>;
+            carry_back_files: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        };
+        execute(args: {
+            project_key: string;
+            epic_id: string;
+            branch_label?: string | undefined;
+            carry_back_learnings?: string | undefined;
+            carry_back_files?: string[] | undefined;
+        }, context: import("@opencode-ai/plugin").ToolContext): Promise<string>;
+    };
     swarm_learn: {
         description: string;
         args: {

package/dist/swarm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../src/swarm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAW/B;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQtB,CAAC"}
+{"version":3,"file":"swarm.d.ts","sourceRoot":"","sources":["../src/swarm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAW/B;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQtB,CAAC"}

package/examples/plugin-wrapper-template.ts

@@ -40,7 +40,10 @@ import { tool } from "@opencode-ai/plugin";
 import { spawn } from "child_process";
 import { appendFileSync, mkdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
+import { homedir, platform } from "node:os";
+
+// Platform detection for Windows compatibility
+const isWindows = platform() === "win32";
 
 // =============================================================================
 // Swarm Signature Detection (INLINED - do not import from opencode-swarm-plugin)
@@ -304,7 +307,9 @@ function getSwarmSummary(projection: SwarmProjection): string {
 // Constants
 // =============================================================================
 
-const SWARM_CLI = "swarm";
+// On Windows, use .cmd extension to avoid shell escaping issues with JSON args
+const SWARM_CLI = isWindows ? "swarm.cmd" : "swarm";
+const OPENCODE_CLI = isWindows ? "opencode.cmd" : "opencode";
 
 // =============================================================================
 // File-based Logging (writes to ~/.config/swarm-tools/logs/)
@@ -2058,7 +2063,7 @@ Keep the prompt concise but actionable. Use actual data from the snapshot, not p
     const llmStart = Date.now();
     const result = await new Promise<{ exitCode: number; stdout: string; stderr: string }>(
       (resolve, reject) => {
-        const proc = spawn("opencode", ["run", "-m", liteModel, "--", promptText], {
+        const proc = spawn(OPENCODE_CLI, ["run", "-m", liteModel, "--", promptText], {
           cwd: projectDirectory,
           stdio: ["ignore", "pipe", "pipe"],
           timeout: 30000, // 30 second timeout

package/global-skills/skill-generator/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: skill-generator
+description: Meta-skill for generating new skills with proper format and structure. Use when creating new skills for the swarm system or when agents need to generate skill scaffolds. Ensures skills follow conventions (frontmatter format, directory structure, bundled resources).
+---
+
+# Skill Generator
+
+Generate new skills with proper format, structure, and conventions. This meta-skill helps agents create skills without hallucinating the format.
+
+## Quick Start
+
+To generate a new skill:
+
+```bash
+bash scripts/generate-skill.sh <skill-name> [target-directory]
+```
+
+This creates a complete skill scaffold with:
+- SKILL.md with proper frontmatter
+- scripts/ directory for executable helpers
+- references/ directory for documentation
+- Placeholder content following conventions
+
+## Skill Format Conventions
+
+Every skill MUST include:
+
+1. **SKILL.md** (required) - Main skill file with:
+   - YAML frontmatter (name, description)
+   - Markdown body with instructions
+
+2. **Bundled Resources** (optional):
+   - `scripts/` - Executable code (bash/python/etc)
+   - `references/` - Documentation loaded on-demand
+   - `assets/` - Files used in output (templates, etc)
+
+### Frontmatter Requirements
+
+```yaml
+---
+name: skill-name
+description: What the skill does AND when to use it. Include triggering scenarios.
+---
+```
+
+The description field is critical for skill discovery and triggering. Include:
+- What the skill does
+- When to use it (specific triggers)
+- What contexts activate it
+
+### Directory Structure
+
+```
+skill-name/
+├── SKILL.md (required)
+├── scripts/ (optional)
+│   └── example-script.sh
+├── references/ (optional)
+│   └── conventions.md
+└── assets/ (optional)
+    └── template-file
+```
+
+## Writing Effective Skills
+
+### Keep SKILL.md Lean
+
+Target <500 lines in SKILL.md. Move detailed content to references/:
+
+- Core workflow → SKILL.md
+- Detailed examples → references/
+- API docs → references/
+- Long explanations → references/
+
+### Use Imperative Form
+
+Write instructions as commands:
+- "Read the file first" ✓
+- "You should read the file" ✗
+- "Check for patterns" ✓
+- "Consider checking patterns" ✗
+
+### Progressive Disclosure
+
+Skills use three-level loading:
+
+1. **Metadata** (~100 words) - Always in context
+2. **SKILL.md body** (<5k words) - When skill triggers
+3. **Bundled resources** (unlimited) - Loaded as needed
+
+## Bundled Resources
+
+### scripts/
+
+Executable code for deterministic tasks:
+- When the same code is rewritten repeatedly
+- When reliability is critical
+- Run via bash/python without loading to context
+
+Make scripts executable:
+```bash
+chmod +x scripts/my-script.sh
+```
+
+### references/
+
+Documentation loaded on-demand:
+- Database schemas
+- API documentation
+- Detailed workflow guides
+- Domain knowledge
+
+Keep reference files focused. For files >100 lines, include a table of contents.
+
+Reference from SKILL.md with clear guidance on when to read:
+```markdown
+See references/api-docs.md for complete API reference.
+```
+
+### assets/
+
+Files used in output (not loaded to context):
+- Templates
+- Images/icons
+- Boilerplate code
+- Fonts/typography
+
+## What NOT to Include
+
+Do NOT create these files:
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+
+Skills should contain only what an AI agent needs to execute the task. No auxiliary documentation.
+
+## Validation
+
+Before finalizing, validate the skill:
+
+```bash
+bun scripts/validate-skill.ts path/to/skill
+```
+
+Checks:
+- YAML frontmatter format
+- Required fields present
+- No TODO placeholders
+- No extraneous files
+- Naming conventions
+
+## Reference
+
+See references/conventions.md for complete skill format specification.