opencode-swarm-plugin 0.16.0 → 0.17.1

package/dist/plugin.js

@@ -29829,7 +29829,7 @@ function parseBead(output) {
     const parsed = JSON.parse(output);
     const data = Array.isArray(parsed) ? parsed[0] : parsed;
     if (!data) {
-      throw new BeadError("No bead data in response", "parse");
+      throw new BeadError("No bead data in response. The bd CLI may not be installed or returned unexpected output. Try: Run 'bd --version' to verify installation, or check if .beads/ directory exists in project.", "parse");
     }
     return BeadSchema.parse(data);
   } catch (error45) {
@@ -29839,7 +29839,7 @@ function parseBead(output) {
     if (error45 instanceof BeadError) {
       throw error45;
     }
-    throw new BeadError(`Failed to parse bead JSON: ${output}`, "parse");
+    throw new BeadError(`Failed to parse bead JSON because output is malformed. Try: Check if bd CLI is up to date with 'bd --version' (need v1.0.0+), or inspect output: ${output.slice(0, 100)}`, "parse");
   }
 }
 function parseBeads(output) {
@@ -29850,7 +29850,7 @@ function parseBeads(output) {
     if (error45 instanceof exports_external.ZodError) {
       throw new BeadValidationError(`Invalid beads data: ${error45.message}`, error45);
     }
-    throw new BeadError(`Failed to parse beads JSON: ${output}`, "parse");
+    throw new BeadError(`Failed to parse beads JSON because output is malformed. Try: Check if bd CLI is up to date with 'bd --version' (need v1.0.0+), or inspect output: ${output.slice(0, 100)}`, "parse");
   }
 }
 var beads_create = tool({
@@ -29867,14 +29867,14 @@ var beads_create = tool({
     const cmdParts = buildCreateCommand(validated);
     const result = await runBdCommand(cmdParts.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to create bead: ${result.stderr}`, cmdParts.join(" "), result.exitCode, result.stderr);
+      throw new BeadError(`Failed to create bead because bd command exited with code ${result.exitCode}. Error: ${result.stderr}. Try: Check if beads initialized with 'bd init' in project root, or verify .beads/ directory exists.`, cmdParts.join(" "), result.exitCode, result.stderr);
     }
     const stdout = result.stdout.trim();
     if (!stdout) {
-      throw new BeadError("bd create returned empty output", cmdParts.join(" "), 0, "Empty stdout");
+      throw new BeadError("bd create returned empty output because command produced no response. Try: Check if bd is properly installed with 'bd --version', or run 'bd list' to test basic functionality.", cmdParts.join(" "), 0, "Empty stdout");
     }
     if (stdout.startsWith("error:") || stdout.startsWith("Error:")) {
-      throw new BeadError(`bd create failed: ${stdout}`, cmdParts.join(" "), 0, stdout);
+      throw new BeadError(`bd create failed because command returned error in stdout: ${stdout}. Try: Check error message above, verify beads initialized with 'bd init', or check .beads/issues.jsonl for corruption.`, cmdParts.join(" "), 0, stdout);
     }
     const bead = parseBead(stdout);
     return JSON.stringify(bead, null, 2);
@@ -29906,7 +29906,7 @@ var beads_create_epic = tool({
       });
       const epicResult = await runBdCommand(epicCmd.slice(1));
       if (epicResult.exitCode !== 0) {
-        throw new BeadError(`Failed to create epic: ${epicResult.stderr}`, epicCmd.join(" "), epicResult.exitCode);
+        throw new BeadError(`Failed to create epic because bd command failed: ${epicResult.stderr}. Try: Verify beads initialized with 'bd init', check if .beads/ directory is writable, or run 'bd list' to test basic functionality.`, epicCmd.join(" "), epicResult.exitCode);
       }
       const epic = parseBead(epicResult.stdout);
       created.push(epic);
@@ -29924,7 +29924,7 @@ var beads_create_epic = tool({
         });
         const subtaskResult = await runBdCommand(subtaskCmd.slice(1));
         if (subtaskResult.exitCode !== 0) {
-          throw new BeadError(`Failed to create subtask: ${subtaskResult.stderr}`, subtaskCmd.join(" "), subtaskResult.exitCode);
+          throw new BeadError(`Failed to create subtask because bd command failed: ${subtaskResult.stderr}. Try: Check if parent epic exists with 'bd show ${epic.id}', verify .beads/issues.jsonl is not corrupted, or check for invalid characters in title.`, subtaskCmd.join(" "), subtaskResult.exitCode);
         }
         const subtaskBead = parseBead(subtaskResult.stdout);
         created.push(subtaskBead);
@@ -29980,7 +29980,7 @@ ${rollbackErrors.join(`
 
 No beads to rollback.`;
       }
-      throw new BeadError(`Epic creation failed: ${errorMsg}${rollbackInfo}`, "beads_create_epic", 1);
+      throw new BeadError(`Epic creation failed: ${errorMsg}${rollbackInfo}. Try: If rollback failed, manually close beads with 'bd close <id> --reason "Rollback"', check .beads/issues.jsonl for partial state, or re-run beads_create_epic with corrected parameters.`, "beads_create_epic", 1);
     }
   }
 });
@@ -30008,7 +30008,7 @@ var beads_query = tool({
     }
     const result = await runBdCommand(cmd.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to query beads: ${result.stderr}`, cmd.join(" "), result.exitCode);
+      throw new BeadError(`Failed to query beads because bd command failed: ${result.stderr}. Try: Check if beads initialized with 'bd init', verify .beads/ directory exists, or run 'bd --version' to check CLI version.`, cmd.join(" "), result.exitCode);
     }
     const beads = parseBeads(result.stdout);
     const limited = beads.slice(0, validated.limit);
@@ -30038,7 +30038,7 @@ var beads_update = tool({
     cmd.push("--json");
     const result = await runBdCommand(cmd.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to update bead: ${result.stderr}`, cmd.join(" "), result.exitCode);
+      throw new BeadError(`Failed to update bead because bd command failed: ${result.stderr}. Try: Verify bead exists with 'bd show ${validated.id}', check for invalid status values, or inspect .beads/issues.jsonl for corruption.`, cmd.join(" "), result.exitCode);
     }
     const bead = parseBead(result.stdout);
     return JSON.stringify(bead, null, 2);
@@ -30062,7 +30062,7 @@ var beads_close = tool({
     ];
     const result = await runBdCommand(cmd.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to close bead: ${result.stderr}`, cmd.join(" "), result.exitCode);
+      throw new BeadError(`Failed to close bead because bd command failed: ${result.stderr}. Try: Verify bead exists and is not already closed with 'beads_query(status="closed")' or 'bd show ${validated.id}', check if bead ID is correct.`, cmd.join(" "), result.exitCode);
     }
     const bead = parseBead(result.stdout);
     return `Closed ${bead.id}: ${validated.reason}`;
@@ -30082,7 +30082,7 @@ var beads_start = tool({
       "--json"
     ]);
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to start bead: ${result.stderr}`, `bd update ${args.id} --status in_progress --json`, result.exitCode);
+      throw new BeadError(`Failed to start bead because bd update command failed: ${result.stderr}. Try: Verify bead exists with 'bd show ${args.id}', check if already in_progress with 'beads_query(status="in_progress")', or use beads_update directly.`, `bd update ${args.id} --status in_progress --json`, result.exitCode);
     }
     const bead = parseBead(result.stdout);
     return `Started: ${bead.id}`;
@@ -30094,7 +30094,7 @@ var beads_ready = tool({
   async execute(args, ctx) {
     const result = await runBdCommand(["ready", "--json"]);
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to get ready beads: ${result.stderr}`, "bd ready --json", result.exitCode);
+      throw new BeadError(`Failed to get ready beads because bd ready command failed: ${result.stderr}. Try: Check if beads initialized with 'bd init', verify .beads/ directory is readable, or run 'bd list --json' to test basic query.`, "bd ready --json", result.exitCode);
     }
     const beads = parseBeads(result.stdout);
     if (beads.length === 0) {
@@ -30127,7 +30127,7 @@ var beads_sync = tool({
     };
     const flushResult = await withTimeout(runBdCommand(["sync", "--flush-only"]), TIMEOUT_MS, "bd sync --flush-only");
     if (flushResult.exitCode !== 0) {
-      throw new BeadError(`Failed to flush beads: ${flushResult.stderr}`, "bd sync --flush-only", flushResult.exitCode);
+      throw new BeadError(`Failed to flush beads because bd sync failed: ${flushResult.stderr}. Try: Check if .beads/ directory is writable, verify no corrupted JSONL files, or run 'bd list' to test basic beads functionality.`, "bd sync --flush-only", flushResult.exitCode);
     }
     const beadsStatusResult = await runGitCommand([
       "status",
@@ -30138,11 +30138,11 @@ var beads_sync = tool({
     if (hasChanges) {
       const addResult = await runGitCommand(["add", ".beads/"]);
       if (addResult.exitCode !== 0) {
-        throw new BeadError(`Failed to stage beads: ${addResult.stderr}`, "git add .beads/", addResult.exitCode);
+        throw new BeadError(`Failed to stage beads because git add failed: ${addResult.stderr}. Try: Check if .beads/ directory exists, verify git is initialized with 'git status', or check for .gitignore patterns blocking .beads/.`, "git add .beads/", addResult.exitCode);
       }
       const commitResult = await withTimeout(runGitCommand(["commit", "-m", "chore: sync beads"]), TIMEOUT_MS, "git commit");
       if (commitResult.exitCode !== 0 && !commitResult.stdout.includes("nothing to commit")) {
-        throw new BeadError(`Failed to commit beads: ${commitResult.stderr}`, "git commit", commitResult.exitCode);
+        throw new BeadError(`Failed to commit beads because git commit failed: ${commitResult.stderr}. Try: Check git config (user.name, user.email) with 'git config --list', verify working tree is clean, or check for pre-commit hooks blocking commit.`, "git commit", commitResult.exitCode);
       }
     }
     if (autoPull) {
@@ -30181,7 +30181,7 @@ var beads_sync = tool({
         }
       }
       if (pullResult.exitCode !== 0) {
-        throw new BeadError(`Failed to pull: ${pullResult.stderr}`, "git pull --rebase", pullResult.exitCode);
+        throw new BeadError(`Failed to pull because git pull --rebase failed: ${pullResult.stderr}. Try: Resolve merge conflicts manually with 'git status', check if remote is accessible with 'git remote -v', or use skip_verification to bypass automatic pull.`, "git pull --rebase", pullResult.exitCode);
       }
       const importResult = await withTimeout(runBdCommand(["sync", "--import-only"]), TIMEOUT_MS, "bd sync --import-only");
       if (importResult.exitCode !== 0) {
@@ -30190,7 +30190,7 @@ var beads_sync = tool({
     }
     const pushResult = await withTimeout(runGitCommand(["push"]), TIMEOUT_MS, "git push");
     if (pushResult.exitCode !== 0) {
-      throw new BeadError(`Failed to push: ${pushResult.stderr}`, "git push", pushResult.exitCode);
+      throw new BeadError(`Failed to push because git push failed: ${pushResult.stderr}. Try: Check if remote branch is up to date with 'git pull --rebase', verify push permissions, check remote URL with 'git remote -v', or force push with 'git push --force-with-lease' if safe.`, "git push", pushResult.exitCode);
     }
     const statusResult = await runGitCommand(["status", "--porcelain"]);
     const status = statusResult.stdout.trim();
@@ -30210,7 +30210,7 @@ var beads_link_thread = tool({
   async execute(args, ctx) {
     const queryResult = await runBdCommand(["show", args.bead_id, "--json"]);
     if (queryResult.exitCode !== 0) {
-      throw new BeadError(`Failed to get bead: ${queryResult.stderr}`, `bd show ${args.bead_id} --json`, queryResult.exitCode);
+      throw new BeadError(`Failed to get bead because bd show command failed: ${queryResult.stderr}. Try: Verify bead ID is correct with 'beads_query()', check if bead exists with 'bd list --json', or check .beads/issues.jsonl for valid entries.`, `bd show ${args.bead_id} --json`, queryResult.exitCode);
     }
     const bead = parseBead(queryResult.stdout);
     const existingDesc = bead.description || "";
@@ -30229,7 +30229,7 @@ ${threadMarker}` : threadMarker;
       "--json"
     ]);
     if (updateResult.exitCode !== 0) {
-      throw new BeadError(`Failed to update bead: ${updateResult.stderr}`, `bd update ${args.bead_id} -d ...`, updateResult.exitCode);
+      throw new BeadError(`Failed to update bead because bd update command failed: ${updateResult.stderr}. Try: Verify bead exists with 'bd show ${args.bead_id}', check for invalid characters in description, or inspect .beads/issues.jsonl for corruption.`, `bd update ${args.bead_id} -d ...`, updateResult.exitCode);
     }
     return `Linked bead ${args.bead_id} to thread ${args.thread_id}`;
   }
@@ -33846,7 +33846,7 @@ async function runVerificationGate(filesTouched, skipUbs = false) {
       };
       if (!ubsStep.passed) {
         ubsStep.error = `Found ${ubsResult.summary.critical} critical bugs`;
-        blockers.push(`UBS: ${ubsResult.summary.critical} critical bugs found`);
+        blockers.push(`UBS found ${ubsResult.summary.critical} critical bug(s). Try: Run 'ubs scan ${filesTouched.join(" ")}' to see details, fix critical bugs in reported files, or use skip_ubs_scan=true to bypass (not recommended).`);
       }
       steps.push(ubsStep);
     } else {
@@ -33863,12 +33863,12 @@ async function runVerificationGate(filesTouched, skipUbs = false) {
   const typecheckStep = await runTypecheckVerification();
   steps.push(typecheckStep);
   if (!typecheckStep.passed && !typecheckStep.skipped) {
-    blockers.push(`Typecheck: ${typecheckStep.error?.slice(0, 100) || "failed"}`);
+    blockers.push(`Typecheck failed: ${typecheckStep.error?.slice(0, 100) || "type errors found"}. Try: Run 'tsc --noEmit' to see full errors, check tsconfig.json configuration, or fix reported type errors in modified files.`);
   }
   const testStep = await runTestVerification(filesTouched);
   steps.push(testStep);
   if (!testStep.passed && !testStep.skipped) {
-    blockers.push(`Tests: ${testStep.error?.slice(0, 100) || "failed"}`);
+    blockers.push(`Tests failed: ${testStep.error?.slice(0, 100) || "test failures"}. Try: Run 'bun test ${testStep.command.split(" ").slice(2).join(" ")}' to see full output, check test assertions, or fix failing tests in modified files.`);
   }
   const passedCount = steps.filter((s) => s.passed).length;
   const skippedCount = steps.filter((s) => s.skipped).length;
@@ -33923,8 +33923,8 @@ async function runUbsScan(files) {
         }
       };
     } catch (error45) {
-      console.error(`[swarm] CRITICAL: UBS scan failed to parse JSON output:`, error45);
-      console.error(`[swarm] Raw output:`, output);
+      console.error(`[swarm] CRITICAL: UBS scan failed to parse JSON output because output is malformed:`, error45);
+      console.error(`[swarm] Raw output: ${output}. Try: Run 'ubs doctor' to check installation, verify UBS version with 'ubs --version' (need v1.0.0+), or check if UBS supports --json flag.`);
       return {
         exitCode: result.exitCode,
         bugs: [],
@@ -34014,7 +34014,7 @@ var swarm_complete = tool({
               error: s.error?.slice(0, 200)
             }))
           },
-          hint: "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
+          hint: verificationResult.blockers.length > 0 ? `Fix these issues: ${verificationResult.blockers.map((b, i) => `${i + 1}. ${b}`).join(", ")}. Use skip_verification=true only as last resort.` : "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
           gate_function: "IDENTIFY → RUN → READ → VERIFY → CLAIM (you are at VERIFY, claim blocked)"
         }, null, 2);
       }
@@ -34025,12 +34025,12 @@ var swarm_complete = tool({
       if (ubsResult && ubsResult.summary.critical > 0) {
         return JSON.stringify({
           success: false,
-          error: "UBS found critical bugs - fix before completing",
+          error: `UBS found ${ubsResult.summary.critical} critical bug(s) that must be fixed before completing`,
           ubs_scan: {
             critical_count: ubsResult.summary.critical,
             bugs: ubsResult.bugs.filter((b) => b.severity === "critical")
           },
-          hint: "Fix the critical bugs and try again, or use skip_ubs_scan=true to bypass"
+          hint: `Fix these critical bugs: ${ubsResult.bugs.filter((b) => b.severity === "critical").map((b) => `${b.file}:${b.line} - ${b.message}`).slice(0, 3).join("; ")}. Try: Run 'ubs scan ${args.files_touched?.join(" ") || "."} --json' for full report, fix reported issues, or use skip_ubs_scan=true to bypass (not recommended).`
         }, null, 2);
       }
     }
@@ -34056,7 +34056,7 @@ var swarm_complete = tool({
     }
     const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.quiet().nothrow();
     if (closeResult.exitCode !== 0) {
-      throw new SwarmError(`Failed to close bead: ${closeResult.stderr.toString()}`, "complete");
+      throw new SwarmError(`Failed to close bead because bd close command failed: ${closeResult.stderr.toString()}. Try: Verify bead exists and is not already closed with 'bd show ${args.bead_id}', check if bead ID is correct with 'beads_query()', or use beads_close tool directly.`, "complete");
     }
     try {
       await releaseSwarmFiles({
@@ -35234,7 +35234,7 @@ class SemanticMemoryMandateStorage {
   async update(id, updates) {
     const existing = await this.get(id);
     if (!existing) {
-      throw new Error(`Mandate ${id} not found`);
+      throw new Error(`Mandate '${id}' not found. Use list() to see available mandates.`);
     }
     const updated = { ...existing, ...updates };
     await this.store(updated);
@@ -35242,7 +35242,7 @@ class SemanticMemoryMandateStorage {
   async vote(vote) {
     const existing = await this.hasVoted(vote.mandate_id, vote.agent_name);
     if (existing) {
-      throw new Error(`Agent ${vote.agent_name} has already voted on mandate ${vote.mandate_id}`);
+      throw new Error(`Agent '${vote.agent_name}' has already voted on mandate '${vote.mandate_id}'. Each agent can vote once per mandate to ensure fair consensus.`);
     }
     await this.storeInternal(this.config.collections.votes, vote, {
       id: vote.id,
@@ -35333,7 +35333,7 @@ class InMemoryMandateStorage {
   async update(id, updates) {
     const existing = await this.get(id);
     if (!existing) {
-      throw new Error(`Mandate ${id} not found`);
+      throw new Error(`Mandate '${id}' not found. Use list() to see available mandates.`);
     }
     const updated = { ...existing, ...updates };
     this.entries.set(id, updated);
@@ -35341,7 +35341,7 @@ class InMemoryMandateStorage {
   async vote(vote) {
     const existing = await this.hasVoted(vote.mandate_id, vote.agent_name);
     if (existing) {
-      throw new Error(`Agent ${vote.agent_name} has already voted on mandate ${vote.mandate_id}`);
+      throw new Error(`Agent '${vote.agent_name}' has already voted on mandate '${vote.mandate_id}'. Each agent can vote once per mandate to ensure fair consensus.`);
     }
     this.votes.set(vote.id, vote);
   }
@@ -35396,13 +35396,13 @@ function createMandateStorage(config2 = {}) {
     case "memory":
       return new InMemoryMandateStorage(fullConfig);
     default:
-      throw new Error(`Unknown storage backend: ${fullConfig.backend}`);
+      throw new Error(`Unknown storage backend: '${fullConfig.backend}'. Valid backends are 'semantic-memory' or 'memory'.`);
   }
 }
 async function updateMandateStatus(mandateId, storage) {
   const entry = await storage.get(mandateId);
   if (!entry) {
-    throw new Error(`Mandate ${mandateId} not found`);
+    throw new Error(`Mandate '${mandateId}' not found when calculating score. Use storage.list() to verify the mandate exists.`);
   }
   const score = await storage.calculateScore(mandateId);
   const previousStatus = entry.status;
@@ -35566,11 +35566,11 @@ var mandate_vote = tool({
     const storage = getMandateStorage();
     const mandate = await storage.get(validated.mandate_id);
     if (!mandate) {
-      throw new MandateError(`Mandate ${validated.mandate_id} not found`, "mandate_vote");
+      throw new MandateError(`Mandate '${validated.mandate_id}' not found. Use mandate_list() to see available mandates, or check the ID is correct.`, "mandate_vote");
     }
     const hasVoted = await storage.hasVoted(validated.mandate_id, args.agent_name);
     if (hasVoted) {
-      throw new MandateError(`Agent ${args.agent_name} has already voted on mandate ${validated.mandate_id}`, "mandate_vote");
+      throw new MandateError(`Agent '${args.agent_name}' has already voted on mandate '${validated.mandate_id}'. Each agent can vote once per mandate. This is expected behavior to prevent vote manipulation.`, "mandate_vote");
     }
     const vote = {
       id: generateVoteId(),
@@ -35713,7 +35713,7 @@ var mandate_stats = tool({
       if (args.mandate_id) {
         const mandate = await storage.get(args.mandate_id);
         if (!mandate) {
-          throw new MandateError(`Mandate ${args.mandate_id} not found`, "mandate_stats");
+          throw new MandateError(`Mandate '${args.mandate_id}' not found. Use mandate_list() to see available mandates, or check the ID is correct.`, "mandate_stats");
         }
         const score = await storage.calculateScore(args.mandate_id);
         const votes = await storage.getVotes(args.mandate_id);

package/examples/commands/swarm.md

@@ -342,5 +342,64 @@ Not: Do Everything Inline → Run Out of Context → Fail
 - [ ] Workers spawned in parallel
 - [ ] Progress monitored via **swarmmail_inbox** (limit=5, no bodies)
 - [ ] PR created (or pushed to main)
+- [ ] **ASCII art session summary** (MANDATORY - see below)
+
+## ASCII Art & Visual Flair (MANDATORY)
+
+**We fucking LOVE visual output.** Every swarm completion MUST include:
+
+### Required Elements
+
+1. **ASCII banner** - Big text for the epic title or "SWARM COMPLETE"
+2. **Architecture diagram** - Show what was built with box-drawing chars
+3. **Stats summary** - Files, subtasks, releases in a nice box
+4. **Ship-it flourish** - Cow, bee, or memorable closer
+
+### Box-Drawing Reference
+
+```
+─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼    (light)
+━ ┃ ┏ ┓ ┗ ┛ ┣ ┫ ┳ ┻ ╋    (heavy)
+═ ║ ╔ ╗ ╚ ╝ ╠ ╣ ╦ ╩ ╬    (double)
+```
+
+### Example Session Summary
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃                    🐝 SWARM COMPLETE 🐝                     ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+    EPIC: Add User Authentication
+    ══════════════════════════════
+
+    ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+    │   OAuth     │────▶│   Session   │────▶│  Protected  │
+    │   Provider  │     │   Manager   │     │   Routes    │
+    └─────────────┘     └─────────────┘     └─────────────┘
+
+    SUBTASKS
+    ────────
+    ├── auth-123.1 ✓ OAuth provider setup
+    ├── auth-123.2 ✓ Session management
+    ├── auth-123.3 ✓ Protected route middleware
+    └── auth-123.4 ✓ Integration tests
+
+    STATS
+    ─────
+    Files Modified:  12
+    Tests Added:     24
+    Time:            ~45 min
+
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+
+    moo. ship it.
+```
+
+**This is not optional.** Make it beautiful. Make it memorable. PRs get shared.
 
 Begin with swarmmail_init and knowledge gathering now.

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

@@ -443,3 +443,73 @@ beads_sync();
 ```
 
 See `references/coordinator-patterns.md` for detailed patterns.
+
+## ASCII Art, Whimsy & Diagrams (MANDATORY)
+
+**We fucking LOVE visual flair.** Every swarm session should include:
+
+### Session Summaries
+
+When completing a swarm, output a beautiful summary with:
+
+- ASCII art banner (figlet-style or custom)
+- Box-drawing characters for structure
+- Architecture diagrams showing what was built
+- Stats (files modified, subtasks completed, etc.)
+- A memorable quote or cow saying "ship it"
+
+### During Coordination
+
+- Use tables for status updates
+- Draw dependency trees with box characters
+- Show progress with visual indicators
+
+### Examples
+
+**Session Complete Banner:**
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃         🐝 SWARM COMPLETE 🐝                 ┃
+┃                                              ┃
+┃   Epic: Add Authentication                   ┃
+┃   Subtasks: 4/4 ✓                            ┃
+┃   Files: 12 modified                         ┃
+┃                                              ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+```
+
+**Architecture Diagram:**
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   INPUT     │────▶│  PROCESS    │────▶│   OUTPUT    │
+└─────────────┘     └─────────────┘     └─────────────┘
+```
+
+**Dependency Tree:**
+
+```
+epic-123
+├── epic-123.1 ✓ Auth service
+├── epic-123.2 ✓ Database schema
+├── epic-123.3 ◐ API routes (in progress)
+└── epic-123.4 ○ Tests (pending)
+```
+
+**Ship It:**
+
+```
+    \   ^__^
+     \  (oo)\_______
+        (__)\       )\/\
+            ||----w |
+            ||     ||
+
+    moo. ship it.
+```
+
+**This is not optional.** PRs get shared on Twitter. Session summaries get screenshot. Make them memorable. Make them beautiful. Make them fun.
+
+Box-drawing characters: `─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ ━ ┃ ┏ ┓ ┗ ┛`
+Progress indicators: `✓ ✗ ◐ ○ ● ▶ ▷ ★ ☆ 🐝`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

package/src/beads.ts

@@ -178,7 +178,10 @@ function parseBead(output: string): Bead {
     // CLI commands like `bd close`, `bd update` return arrays even for single items
     const data = Array.isArray(parsed) ? parsed[0] : parsed;
     if (!data) {
-      throw new BeadError("No bead data in response", "parse");
+      throw new BeadError(
+        "No bead data in response. The bd CLI may not be installed or returned unexpected output. Try: Run 'bd --version' to verify installation, or check if .beads/ directory exists in project.",
+        "parse",
+      );
     }
     return BeadSchema.parse(data);
   } catch (error) {
@@ -191,7 +194,10 @@ function parseBead(output: string): Bead {
     if (error instanceof BeadError) {
       throw error;
     }
-    throw new BeadError(`Failed to parse bead JSON: ${output}`, "parse");
+    throw new BeadError(
+      `Failed to parse bead JSON because output is malformed. Try: Check if bd CLI is up to date with 'bd --version' (need v1.0.0+), or inspect output: ${output.slice(0, 100)}`,
+      "parse",
+    );
   }
 }
 
@@ -209,7 +215,10 @@ function parseBeads(output: string): Bead[] {
         error,
       );
     }
-    throw new BeadError(`Failed to parse beads JSON: ${output}`, "parse");
+    throw new BeadError(
+      `Failed to parse beads JSON because output is malformed. Try: Check if bd CLI is up to date with 'bd --version' (need v1.0.0+), or inspect output: ${output.slice(0, 100)}`,
+      "parse",
+    );
   }
 }
 
@@ -249,7 +258,7 @@ export const beads_create = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to create bead: ${result.stderr}`,
+        `Failed to create bead because bd command exited with code ${result.exitCode}. Error: ${result.stderr}. Try: Check if beads initialized with 'bd init' in project root, or verify .beads/ directory exists.`,
         cmdParts.join(" "),
         result.exitCode,
         result.stderr,
@@ -260,7 +269,7 @@ export const beads_create = tool({
     const stdout = result.stdout.trim();
     if (!stdout) {
       throw new BeadError(
-        "bd create returned empty output",
+        "bd create returned empty output because command produced no response. Try: Check if bd is properly installed with 'bd --version', or run 'bd list' to test basic functionality.",
         cmdParts.join(" "),
         0,
         "Empty stdout",
@@ -270,7 +279,7 @@ export const beads_create = tool({
     // Check for error messages in stdout (bd sometimes outputs errors to stdout)
     if (stdout.startsWith("error:") || stdout.startsWith("Error:")) {
       throw new BeadError(
-        `bd create failed: ${stdout}`,
+        `bd create failed because command returned error in stdout: ${stdout}. Try: Check error message above, verify beads initialized with 'bd init', or check .beads/issues.jsonl for corruption.`,
         cmdParts.join(" "),
         0,
         stdout,
@@ -331,7 +340,7 @@ export const beads_create_epic = tool({
 
       if (epicResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to create epic: ${epicResult.stderr}`,
+          `Failed to create epic because bd command failed: ${epicResult.stderr}. Try: Verify beads initialized with 'bd init', check if .beads/ directory is writable, or run 'bd list' to test basic functionality.`,
           epicCmd.join(" "),
           epicResult.exitCode,
         );
@@ -361,7 +370,7 @@ export const beads_create_epic = tool({
 
         if (subtaskResult.exitCode !== 0) {
           throw new BeadError(
-            `Failed to create subtask: ${subtaskResult.stderr}`,
+            `Failed to create subtask because bd command failed: ${subtaskResult.stderr}. Try: Check if parent epic exists with 'bd show ${epic.id}', verify .beads/issues.jsonl is not corrupted, or check for invalid characters in title.`,
             subtaskCmd.join(" "),
             subtaskResult.exitCode,
           );
@@ -430,7 +439,7 @@ export const beads_create_epic = tool({
       }
 
       throw new BeadError(
-        `Epic creation failed: ${errorMsg}${rollbackInfo}`,
+        `Epic creation failed: ${errorMsg}${rollbackInfo}. Try: If rollback failed, manually close beads with 'bd close <id> --reason "Rollback"', check .beads/issues.jsonl for partial state, or re-run beads_create_epic with corrected parameters.`,
         "beads_create_epic",
         1,
       );
@@ -482,7 +491,7 @@ export const beads_query = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to query beads: ${result.stderr}`,
+        `Failed to query beads because bd command failed: ${result.stderr}. Try: Check if beads initialized with 'bd init', verify .beads/ directory exists, or run 'bd --version' to check CLI version.`,
         cmd.join(" "),
         result.exitCode,
       );
@@ -534,7 +543,7 @@ export const beads_update = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to update bead: ${result.stderr}`,
+        `Failed to update bead because bd command failed: ${result.stderr}. Try: Verify bead exists with 'bd show ${validated.id}', check for invalid status values, or inspect .beads/issues.jsonl for corruption.`,
         cmd.join(" "),
         result.exitCode,
       );
@@ -570,7 +579,7 @@ export const beads_close = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to close bead: ${result.stderr}`,
+        `Failed to close bead because bd command failed: ${result.stderr}. Try: Verify bead exists and is not already closed with 'beads_query(status="closed")' or 'bd show ${validated.id}', check if bead ID is correct.`,
         cmd.join(" "),
         result.exitCode,
       );
@@ -601,7 +610,7 @@ export const beads_start = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to start bead: ${result.stderr}`,
+        `Failed to start bead because bd update command failed: ${result.stderr}. Try: Verify bead exists with 'bd show ${args.id}', check if already in_progress with 'beads_query(status="in_progress")', or use beads_update directly.`,
         `bd update ${args.id} --status in_progress --json`,
         result.exitCode,
       );
@@ -623,7 +632,7 @@ export const beads_ready = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to get ready beads: ${result.stderr}`,
+        `Failed to get ready beads because bd ready command failed: ${result.stderr}. Try: Check if beads initialized with 'bd init', verify .beads/ directory is readable, or run 'bd list --json' to test basic query.`,
         "bd ready --json",
         result.exitCode,
       );
@@ -696,7 +705,7 @@ export const beads_sync = tool({
     );
     if (flushResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to flush beads: ${flushResult.stderr}`,
+        `Failed to flush beads because bd sync failed: ${flushResult.stderr}. Try: Check if .beads/ directory is writable, verify no corrupted JSONL files, or run 'bd list' to test basic beads functionality.`,
         "bd sync --flush-only",
         flushResult.exitCode,
       );
@@ -715,7 +724,7 @@ export const beads_sync = tool({
       const addResult = await runGitCommand(["add", ".beads/"]);
       if (addResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to stage beads: ${addResult.stderr}`,
+          `Failed to stage beads because git add failed: ${addResult.stderr}. Try: Check if .beads/ directory exists, verify git is initialized with 'git status', or check for .gitignore patterns blocking .beads/.`,
           "git add .beads/",
           addResult.exitCode,
         );
@@ -732,7 +741,7 @@ export const beads_sync = tool({
         !commitResult.stdout.includes("nothing to commit")
       ) {
         throw new BeadError(
-          `Failed to commit beads: ${commitResult.stderr}`,
+          `Failed to commit beads because git commit failed: ${commitResult.stderr}. Try: Check git config (user.name, user.email) with 'git config --list', verify working tree is clean, or check for pre-commit hooks blocking commit.`,
           "git commit",
           commitResult.exitCode,
         );
@@ -798,7 +807,7 @@ export const beads_sync = tool({
 
       if (pullResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to pull: ${pullResult.stderr}`,
+          `Failed to pull because git pull --rebase failed: ${pullResult.stderr}. Try: Resolve merge conflicts manually with 'git status', check if remote is accessible with 'git remote -v', or use skip_verification to bypass automatic pull.`,
           "git pull --rebase",
           pullResult.exitCode,
         );
@@ -824,7 +833,7 @@ export const beads_sync = tool({
     );
     if (pushResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to push: ${pushResult.stderr}`,
+        `Failed to push because git push failed: ${pushResult.stderr}. Try: Check if remote branch is up to date with 'git pull --rebase', verify push permissions, check remote URL with 'git remote -v', or force push with 'git push --force-with-lease' if safe.`,
         "git push",
         pushResult.exitCode,
       );
@@ -858,7 +867,7 @@ export const beads_link_thread = tool({
 
     if (queryResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to get bead: ${queryResult.stderr}`,
+        `Failed to get bead because bd show command failed: ${queryResult.stderr}. Try: Verify bead ID is correct with 'beads_query()', check if bead exists with 'bd list --json', or check .beads/issues.jsonl for valid entries.`,
         `bd show ${args.bead_id} --json`,
         queryResult.exitCode,
       );
@@ -887,7 +896,7 @@ export const beads_link_thread = tool({
 
     if (updateResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to update bead: ${updateResult.stderr}`,
+        `Failed to update bead because bd update command failed: ${updateResult.stderr}. Try: Verify bead exists with 'bd show ${args.bead_id}', check for invalid characters in description, or inspect .beads/issues.jsonl for corruption.`,
         `bd update ${args.bead_id} -d ...`,
         updateResult.exitCode,
       );