opencode-swarm-plugin 0.30.0 → 0.30.2

package/dist/schemas/index.d.ts

@@ -26,6 +26,12 @@
  * - `AgentProgressSchema` - Individual agent status
  * - `SpawnedAgentSchema` - Spawned agent metadata
  *
+ * ## Worker Handoff Schemas (Swarm Contracts)
+ * - `WorkerHandoffSchema` - Complete structured handoff contract
+ * - `WorkerHandoffContractSchema` - Task contract (files, criteria)
+ * - `WorkerHandoffContextSchema` - Narrative context (epic summary, role)
+ * - `WorkerHandoffEscalationSchema` - Escalation protocols
+ *
  * @module schemas
  */
 export { CellStatusSchema, CellTypeSchema, CellDependencySchema, CellSchema, CellCreateArgsSchema, CellUpdateArgsSchema, CellCloseArgsSchema, CellQueryArgsSchema, SubtaskSpecSchema, CellTreeSchema, EpicCreateArgsSchema, EpicCreateResultSchema, type CellStatus, type CellType, type CellDependency, type Cell, type CellCreateArgs, type CellUpdateArgs, type CellCloseArgs, type CellQueryArgs, type SubtaskSpec, type CellTree, type EpicCreateArgs, type EpicCreateResult, } from "./cell";
@@ -34,6 +40,7 @@ export { CriterionEvaluationSchema, WeightedCriterionEvaluationSchema, Evaluatio
 export { EffortLevelSchema, DependencyTypeSchema, DecomposedSubtaskSchema, SubtaskDependencySchema, TaskDecompositionSchema, DecomposeArgsSchema, SpawnedAgentSchema, SwarmSpawnResultSchema, AgentProgressSchema, SwarmStatusSchema, type EffortLevel, type DependencyType, type DecomposedSubtask, type SubtaskDependency, type TaskDecomposition, type DecomposeArgs, type SpawnedAgent, type SwarmSpawnResult, type AgentProgress, type SwarmStatus, } from "./task";
 export { MandateContentTypeSchema, MandateStatusSchema, VoteTypeSchema, MandateEntrySchema, VoteSchema, MandateScoreSchema, CreateMandateArgsSchema, CastVoteArgsSchema, QueryMandatesArgsSchema, ScoreCalculationResultSchema, DEFAULT_MANDATE_DECAY_CONFIG, mandateSchemas, type MandateContentType, type MandateStatus, type VoteType, type MandateEntry, type Vote, type MandateScore, type MandateDecayConfig, type CreateMandateArgs, type CastVoteArgs, type QueryMandatesArgs, type ScoreCalculationResult, } from "./mandate";
 export { SwarmStrategySchema, SwarmDirectivesSchema, SwarmRecoverySchema, SwarmBeadContextSchema, CreateSwarmContextArgsSchema, UpdateSwarmContextArgsSchema, QuerySwarmContextsArgsSchema, type SwarmStrategy, type SwarmDirectives, type SwarmRecovery, type SwarmBeadContext, type CreateSwarmContextArgs, type UpdateSwarmContextArgs, type QuerySwarmContextsArgs, } from "./swarm-context";
+export { WorkerHandoffContractSchema, WorkerHandoffContextSchema, WorkerHandoffEscalationSchema, WorkerHandoffSchema, type WorkerHandoff, type WorkerHandoffContract, type WorkerHandoffContext, type WorkerHandoffEscalation, } from "./worker-handoff";
 export { BaseCellEventSchema, CellCreatedEventSchema, CellUpdatedEventSchema, CellStatusChangedEventSchema, CellClosedEventSchema, CellReopenedEventSchema, CellDeletedEventSchema, CellDependencyAddedEventSchema, CellDependencyRemovedEventSchema, CellLabelAddedEventSchema, CellLabelRemovedEventSchema, CellCommentAddedEventSchema, CellCommentUpdatedEventSchema, CellCommentDeletedEventSchema, CellEpicChildAddedEventSchema, CellEpicChildRemovedEventSchema, CellEpicClosureEligibleEventSchema, CellAssignedEventSchema, CellWorkStartedEventSchema, CellCompactedEventSchema, CellEventSchema, createCellEvent, isCellEventType, getCellIdFromEvent, isStateTransitionEvent, isEpicEvent, isAgentEvent, type CellEvent, type CellCreatedEvent, type CellUpdatedEvent, type CellStatusChangedEvent, type CellClosedEvent, type CellReopenedEvent, type CellDeletedEvent, type CellDependencyAddedEvent, type CellDependencyRemovedEvent, type CellLabelAddedEvent, type CellLabelRemovedEvent, type CellCommentAddedEvent, type CellCommentUpdatedEvent, type CellCommentDeletedEvent, type CellEpicChildAddedEvent, type CellEpicChildRemovedEvent, type CellEpicClosureEligibleEvent, type CellAssignedEvent, type CellWorkStartedEvent, type CellCompactedEvent, } from "./cell-events";
 export { BaseBeadEventSchema, BeadCreatedEventSchema, BeadUpdatedEventSchema, BeadStatusChangedEventSchema, BeadClosedEventSchema, BeadReopenedEventSchema, BeadDeletedEventSchema, BeadDependencyAddedEventSchema, BeadDependencyRemovedEventSchema, BeadLabelAddedEventSchema, BeadLabelRemovedEventSchema, BeadCommentAddedEventSchema, BeadCommentUpdatedEventSchema, BeadCommentDeletedEventSchema, BeadEpicChildAddedEventSchema, BeadEpicChildRemovedEventSchema, BeadEpicClosureEligibleEventSchema, BeadAssignedEventSchema, BeadWorkStartedEventSchema, BeadCompactedEventSchema, BeadEventSchema, createBeadEvent, isBeadEventType, getBeadIdFromEvent, type BeadEvent, type BeadCreatedEvent, type BeadUpdatedEvent, type BeadStatusChangedEvent, type BeadClosedEvent, type BeadReopenedEvent, type BeadDeletedEvent, type BeadDependencyAddedEvent, type BeadDependencyRemovedEvent, type BeadLabelAddedEvent, type BeadLabelRemovedEvent, type BeadCommentAddedEvent, type BeadCommentUpdatedEvent, type BeadCommentDeletedEvent, type BeadEpicChildAddedEvent, type BeadEpicChildRemovedEvent, type BeadEpicClosureEligibleEvent, type BeadAssignedEvent, type BeadWorkStartedEvent, type BeadCompactedEvent, } from "./cell-events";
 //# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"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"}

package/dist/schemas/worker-handoff.d.ts

@@ -0,0 +1,78 @@
+/**
+ * WorkerHandoff schemas - structured contracts replacing prose instructions
+ *
+ * Replaces the 400-line SUBTASK_PROMPT_V2 with machine-readable contracts.
+ * Workers receive typed handoffs with explicit files, criteria, and escalation paths.
+ */
+import { z } from "zod";
+/**
+ * Contract section - the binding agreement between coordinator and worker
+ *
+ * Defines:
+ * - What task to complete (task_id)
+ * - What files to modify (files_owned) vs read (files_readonly)
+ * - What's already done (dependencies_completed)
+ * - How to know you're done (success_criteria)
+ */
+export declare const WorkerHandoffContractSchema: z.ZodObject<{
+    task_id: z.ZodString;
+    files_owned: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    files_readonly: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    dependencies_completed: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    success_criteria: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type WorkerHandoffContract = z.infer<typeof WorkerHandoffContractSchema>;
+/**
+ * Context section - the narrative explaining the "why"
+ *
+ * Provides:
+ * - Big picture (epic_summary)
+ * - This worker's specific role
+ * - What's already been done
+ * - What comes after
+ */
+export declare const WorkerHandoffContextSchema: z.ZodObject<{
+    epic_summary: z.ZodString;
+    your_role: z.ZodString;
+    what_others_did: z.ZodString;
+    what_comes_next: z.ZodString;
+}, z.core.$strip>;
+export type WorkerHandoffContext = z.infer<typeof WorkerHandoffContextSchema>;
+/**
+ * Escalation section - what to do when things go wrong
+ *
+ * Defines:
+ * - How to report blockers
+ * - Protocol for scope changes
+ */
+export declare const WorkerHandoffEscalationSchema: z.ZodObject<{
+    blocked_contact: z.ZodString;
+    scope_change_protocol: z.ZodString;
+}, z.core.$strip>;
+export type WorkerHandoffEscalation = z.infer<typeof WorkerHandoffEscalationSchema>;
+/**
+ * Complete WorkerHandoff - combines all three sections
+ *
+ * This is the full structured contract that replaces prose instructions.
+ */
+export declare const WorkerHandoffSchema: z.ZodObject<{
+    contract: z.ZodObject<{
+        task_id: z.ZodString;
+        files_owned: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        files_readonly: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        dependencies_completed: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        success_criteria: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    context: z.ZodObject<{
+        epic_summary: z.ZodString;
+        your_role: z.ZodString;
+        what_others_did: z.ZodString;
+        what_comes_next: z.ZodString;
+    }, z.core.$strip>;
+    escalation: z.ZodObject<{
+        blocked_contact: z.ZodString;
+        scope_change_protocol: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type WorkerHandoff = z.infer<typeof WorkerHandoffSchema>;
+//# sourceMappingURL=worker-handoff.d.ts.map

package/dist/schemas/worker-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-handoff.d.ts","sourceRoot":"","sources":["../../src/schemas/worker-handoff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B;;;;;;iBAwCtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B;;;;;iBAwBrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B;;;iBAYxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/swarm-orchestrate.d.ts

@@ -19,6 +19,56 @@
  * - 3-strike detection for architectural problems
  */
 import { z } from "zod";
+import { type WorkerHandoff } from "./schemas/worker-handoff";
+/**
+ * Generate a WorkerHandoff object from subtask parameters
+ *
+ * Creates a machine-readable contract that replaces prose instructions in SUBTASK_PROMPT_V2.
+ * Workers receive typed handoffs with explicit files, criteria, and escalation paths.
+ *
+ * @param params - Subtask parameters
+ * @returns WorkerHandoff object validated against schema
+ */
+export declare function generateWorkerHandoff(params: {
+    task_id: string;
+    files_owned: string[];
+    files_readonly?: string[];
+    dependencies_completed?: string[];
+    success_criteria?: string[];
+    epic_summary: string;
+    your_role: string;
+    what_others_did?: string;
+    what_comes_next?: string;
+}): WorkerHandoff;
+/**
+ * Validate that files_touched is a subset of files_owned (supports globs)
+ *
+ * Checks contract compliance - workers should only modify files they own.
+ * Glob patterns in files_owned are matched against files_touched paths.
+ *
+ * @param files_touched - Actual files modified by the worker
+ * @param files_owned - Files the worker is allowed to modify (may include globs)
+ * @returns Validation result with violations list
+ *
+ * @example
+ * ```typescript
+ * // Exact match - passes
+ * validateContract(["src/a.ts"], ["src/a.ts", "src/b.ts"])
+ * // => { valid: true, violations: [] }
+ *
+ * // Glob match - passes
+ * validateContract(["src/auth/service.ts"], ["src/auth/**"])
+ * // => { valid: true, violations: [] }
+ *
+ * // Violation - fails
+ * validateContract(["src/other.ts"], ["src/auth/**"])
+ * // => { valid: false, violations: ["src/other.ts"] }
+ * ```
+ */
+export declare function validateContract(files_touched: string[], files_owned: string[]): {
+    valid: boolean;
+    violations: string[];
+};
 /**
  * Initialize swarm and check tool availability
  *

package/dist/swarm-orchestrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm-orchestrate.d.ts","sourceRoot":"","sources":["../src/swarm-orchestrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA8hBxB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;CA8JrB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;CAoFvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;CAkHzB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;CA6E1B,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqnBzB,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkJ/B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;CA6CjC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;CAmClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAmB9B,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;CAoJ9B,CAAC;AA4BH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqG3B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;CAsGxB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgMtB,CAAC;AAMH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAc5B,CAAC"}
+{"version":3,"file":"swarm-orchestrate.d.ts","sourceRoot":"","sources":["../src/swarm-orchestrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,0BAA0B,CAAC;AAmDlC;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,aAAa,CA4BhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EAAE,EACvB,WAAW,EAAE,MAAM,EAAE,GACpB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAqC1C;AA8hBD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;CA8JrB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;CAoFvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;CAkHzB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;CA6E1B,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8qBzB,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkJ/B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;CA6CjC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;CAmClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAmB9B,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;CAoJ9B,CAAC;AA4BH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqG3B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;CAsGxB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgMtB,CAAC;AAMH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAc5B,CAAC"}

package/dist/swarm-prompts.d.ts

@@ -37,7 +37,7 @@ export declare const SUBTASK_PROMPT = "You are a swarm agent working on a subtas
  *
  * Supports {error_context} placeholder for retry prompts.
  */
-export declare const SUBTASK_PROMPT_V2 = "You are a swarm agent working on: **{subtask_title}**\n\n## [IDENTITY]\nAgent: (assigned at spawn)\nCell: {bead_id}\nEpic: {epic_id}\n\n## [TASK]\n{subtask_description}\n\n## [FILES]\nReserved (exclusive):\n{file_list}\n\nOnly modify these files. Need others? Message the coordinator.\n\n## [CONTEXT]\n{shared_context}\n\n{compressed_context}\n\n{error_context}\n\n## [MANDATORY SURVIVAL CHECKLIST]\n\n**CRITICAL: Follow this checklist IN ORDER. Each step builds on the previous.**\n\n### Step 1: Initialize Coordination (REQUIRED - DO THIS FIRST)\n```\nswarmmail_init(project_path=\"{project_path}\", task_description=\"{bead_id}: {subtask_title}\")\n```\n\n**This registers you with the coordination system and enables:**\n- File reservation tracking\n- Inter-agent communication\n- Progress monitoring\n- Conflict detection\n\n**If you skip this step, your work will not be tracked and swarm_complete will fail.**\n\n### Step 2: Query Past Learnings (BEFORE starting work)\n```\nsemantic-memory_find(query=\"<keywords from your task>\", limit=5)\n```\n\n**Check if past agents solved similar problems.** Search for:\n- Error messages if debugging\n- Domain concepts (e.g., \"authentication\", \"caching\")\n- Technology stack (e.g., \"Next.js\", \"React\")\n- Patterns (e.g., \"event sourcing\", \"validation\")\n\n**Past learnings save time and prevent repeating mistakes.**\n\n### Step 3: Load Relevant Skills (if available)\n```\nskills_list()  # See what skills exist\nskills_use(name=\"<relevant-skill>\", context=\"<your task>\")  # Load skill\n```\n\n**Common skill triggers:**\n- Writing tests? \u2192 `skills_use(name=\"testing-patterns\")`\n- Breaking dependencies? \u2192 `skills_use(name=\"testing-patterns\")`\n- Multi-agent coordination? \u2192 `skills_use(name=\"swarm-coordination\")`\n- Building a CLI? \u2192 `skills_use(name=\"cli-builder\")`\n\n### Step 4: Reserve Your Files (YOU reserve, not coordinator)\n```\nswarmmail_reserve(\n  paths=[{file_list}],\n  reason=\"{bead_id}: {subtask_title}\",\n  exclusive=true\n)\n```\n\n**Workers reserve their own files.** This prevents edit conflicts with other agents.\n\n### Step 5: Do the Work\n- Read your assigned files\n- Implement changes\n- Verify (typecheck if applicable)\n\n### Step 6: Report Progress at Milestones\n```\nswarm_progress(\n  project_key=\"{project_path}\",\n  agent_name=\"<your-agent-name>\",\n  bead_id=\"{bead_id}\",\n  status=\"in_progress\",\n  progress_percent=25,  # or 50, 75\n  message=\"<what you just completed>\"\n)\n```\n\n**Report at 25%, 50%, 75% completion.** This:\n- Triggers auto-checkpoint (saves context)\n- Keeps coordinator informed\n- Prevents silent failures\n\n### Step 7: Manual Checkpoint BEFORE Risky Operations\n```\nswarm_checkpoint(\n  project_key=\"{project_path}\",\n  agent_name=\"<your-agent-name>\",\n  bead_id=\"{bead_id}\"\n)\n```\n\n**Call BEFORE:**\n- Large refactors\n- File deletions\n- Breaking API changes\n- Anything that might fail catastrophically\n\n**Checkpoints preserve context so you can recover if things go wrong.**\n\n### Step 8: Store Learnings (if you discovered something)\n```\nsemantic-memory_store(\n  information=\"<what you learned, WHY it matters, how to apply it>\",\n  metadata=\"<tags: domain, tech-stack, pattern-type>\"\n)\n```\n\n**Store:**\n- Tricky bugs you solved (root cause + solution)\n- Project-specific patterns or domain rules\n- Tool/library gotchas and workarounds\n- Failed approaches (anti-patterns to avoid)\n\n**Don't store generic knowledge.** Store the WHY, not just the WHAT.\n\n### Step 9: Complete (REQUIRED - releases reservations)\n```\nswarm_complete(\n  project_key=\"{project_path}\",\n  agent_name=\"<your-agent-name>\",\n  bead_id=\"{bead_id}\",\n  summary=\"<what you accomplished>\",\n  files_touched=[\"list\", \"of\", \"files\"]\n)\n```\n\n**This automatically:**\n- Runs UBS bug scan\n- Releases file reservations\n- Records learning signals\n- Notifies coordinator\n\n**DO NOT manually close the cell with hive_close.** Use swarm_complete.\n\n## [SWARM MAIL COMMUNICATION]\n\n### Check Inbox Regularly\n```\nswarmmail_inbox()  # Check for coordinator messages\nswarmmail_read_message(message_id=N)  # Read specific message\n```\n\n### When Blocked\n```\nswarmmail_send(\n  to=[\"coordinator\"],\n  subject=\"BLOCKED: {bead_id}\",\n  body=\"<blocker description, what you need>\",\n  importance=\"high\",\n  thread_id=\"{epic_id}\"\n)\nhive_update(id=\"{bead_id}\", status=\"blocked\")\n```\n\n### Report Issues to Other Agents\n```\nswarmmail_send(\n  to=[\"OtherAgent\", \"coordinator\"],\n  subject=\"Issue in {bead_id}\",\n  body=\"<describe problem, don't fix their code>\",\n  thread_id=\"{epic_id}\"\n)\n```\n\n### Manual Release (if needed)\n```\nswarmmail_release()  # Manually release reservations\n```\n\n**Note:** `swarm_complete` automatically releases reservations. Only use manual release if aborting work.\n\n## [OTHER TOOLS]\n### Hive - You Have Autonomy to File Issues\nYou can create new cells against this epic when you discover:\n- **Bugs**: Found a bug while working? File it.\n- **Tech debt**: Spotted something that needs cleanup? File it.\n- **Follow-up work**: Task needs more work than scoped? File a follow-up.\n- **Dependencies**: Need something from another agent? File and link it.\n\n```\nhive_create(\n  title=\"<descriptive title>\",\n  type=\"bug\",  # or \"task\", \"chore\"\n  priority=2,\n  parent_id=\"{epic_id}\",  # Links to this epic\n  description=\"Found while working on {bead_id}: <details>\"\n)\n```\n\n**Don't silently ignore issues.** File them so they get tracked and addressed.\n\nOther cell operations:\n- hive_update(id, status) - Mark blocked if stuck\n- hive_query(status=\"open\") - See what else needs work\n\n### Skills\n- skills_list() - Discover available skills\n- skills_use(name) - Activate skill for specialized guidance\n- skills_create(name) - Create new skill (if you found a reusable pattern)\n\n## [CRITICAL REQUIREMENTS]\n\n**NON-NEGOTIABLE:**\n1. Step 1 (swarmmail_init) MUST be first - do it before anything else\n2. Step 2 (semantic-memory_find) MUST happen before starting work\n3. Step 4 (swarmmail_reserve) - YOU reserve files, not coordinator\n4. Step 6 (swarm_progress) - Report at milestones, don't work silently\n5. Step 9 (swarm_complete) - Use this to close, NOT hive_close\n\n**If you skip these steps:**\n- Your work won't be tracked (swarm_complete will fail)\n- You'll waste time repeating solved problems (no semantic memory query)\n- Edit conflicts with other agents (no file reservation)\n- Lost work if you crash (no checkpoints)\n- Future agents repeat your mistakes (no learnings stored)\n\nBegin now.";
+export declare const SUBTASK_PROMPT_V2 = "You are a swarm agent working on: **{subtask_title}**\n\n## [IDENTITY]\nAgent: (assigned at spawn)\nCell: {bead_id}\nEpic: {epic_id}\n\n## [TASK]\n{subtask_description}\n\n## [FILES]\nReserved (exclusive):\n{file_list}\n\nOnly modify these files. Need others? Message the coordinator.\n\n## [CONTEXT]\n{shared_context}\n\n{compressed_context}\n\n{error_context}\n\n## [MANDATORY SURVIVAL CHECKLIST]\n\n**CRITICAL: Follow this checklist IN ORDER. Each step builds on the previous.**\n\n### Step 1: Initialize Coordination (REQUIRED - DO THIS FIRST)\n```\nswarmmail_init(project_path=\"{project_path}\", task_description=\"{bead_id}: {subtask_title}\")\n```\n\n**This registers you with the coordination system and enables:**\n- File reservation tracking\n- Inter-agent communication\n- Progress monitoring\n- Conflict detection\n\n**If you skip this step, your work will not be tracked and swarm_complete will fail.**\n\n### Step 2: Query Past Learnings (BEFORE starting work)\n```\nsemantic-memory_find(query=\"<keywords from your task>\", limit=5)\n```\n\n**Check if past agents solved similar problems.** Search for:\n- Error messages if debugging\n- Domain concepts (e.g., \"authentication\", \"caching\")\n- Technology stack (e.g., \"Next.js\", \"React\")\n- Patterns (e.g., \"event sourcing\", \"validation\")\n\n**Past learnings save time and prevent repeating mistakes.**\n\n### Step 3: Load Relevant Skills (if available)\n```\nskills_list()  # See what skills exist\nskills_use(name=\"<relevant-skill>\", context=\"<your task>\")  # Load skill\n```\n\n**Common skill triggers:**\n- Writing tests? \u2192 `skills_use(name=\"testing-patterns\")`\n- Breaking dependencies? \u2192 `skills_use(name=\"testing-patterns\")`\n- Multi-agent coordination? \u2192 `skills_use(name=\"swarm-coordination\")`\n- Building a CLI? \u2192 `skills_use(name=\"cli-builder\")`\n\n### Step 4: Reserve Your Files (YOU reserve, not coordinator)\n```\nswarmmail_reserve(\n  paths=[{file_list}],\n  reason=\"{bead_id}: {subtask_title}\",\n  exclusive=true\n)\n```\n\n**Workers reserve their own files.** This prevents edit conflicts with other agents.\n\n### Step 5: Do the Work (TDD MANDATORY)\n\n**Follow RED \u2192 GREEN \u2192 REFACTOR. No exceptions.**\n\n1. **RED**: Write a failing test that describes the expected behavior\n   - Test MUST fail before you write implementation\n   - If test passes immediately, your test is wrong\n   \n2. **GREEN**: Write minimal code to make the test pass\n   - Don't over-engineer - just make it green\n   - Hardcode if needed, refactor later\n   \n3. **REFACTOR**: Clean up while tests stay green\n   - Run tests after every change\n   - If tests break, undo and try again\n\n```bash\n# Run tests continuously\nbun test <your-test-file> --watch\n```\n\n**Why TDD?**\n- Catches bugs before they exist\n- Documents expected behavior\n- Enables fearless refactoring\n- Proves your code works\n\n### Step 6: Report Progress at Milestones\n```\nswarm_progress(\n  project_key=\"{project_path}\",\n  agent_name=\"<your-agent-name>\",\n  bead_id=\"{bead_id}\",\n  status=\"in_progress\",\n  progress_percent=25,  # or 50, 75\n  message=\"<what you just completed>\"\n)\n```\n\n**Report at 25%, 50%, 75% completion.** This:\n- Triggers auto-checkpoint (saves context)\n- Keeps coordinator informed\n- Prevents silent failures\n\n### Step 7: Manual Checkpoint BEFORE Risky Operations\n```\nswarm_checkpoint(\n  project_key=\"{project_path}\",\n  agent_name=\"<your-agent-name>\",\n  bead_id=\"{bead_id}\"\n)\n```\n\n**Call BEFORE:**\n- Large refactors\n- File deletions\n- Breaking API changes\n- Anything that might fail catastrophically\n\n**Checkpoints preserve context so you can recover if things go wrong.**\n\n### Step 8: Store Learnings (if you discovered something)\n```\nsemantic-memory_store(\n  information=\"<what you learned, WHY it matters, how to apply it>\",\n  metadata=\"<tags: domain, tech-stack, pattern-type>\"\n)\n```\n\n**Store:**\n- Tricky bugs you solved (root cause + solution)\n- Project-specific patterns or domain rules\n- Tool/library gotchas and workarounds\n- Failed approaches (anti-patterns to avoid)\n\n**Don't store generic knowledge.** Store the WHY, not just the WHAT.\n\n### Step 9: Complete (REQUIRED - releases reservations)\n```\nswarm_complete(\n  project_key=\"{project_path}\",\n  agent_name=\"<your-agent-name>\",\n  bead_id=\"{bead_id}\",\n  summary=\"<what you accomplished>\",\n  files_touched=[\"list\", \"of\", \"files\"]\n)\n```\n\n**This automatically:**\n- Runs UBS bug scan\n- Releases file reservations\n- Records learning signals\n- Notifies coordinator\n\n**DO NOT manually close the cell with hive_close.** Use swarm_complete.\n\n## [SWARM MAIL COMMUNICATION]\n\n### Check Inbox Regularly\n```\nswarmmail_inbox()  # Check for coordinator messages\nswarmmail_read_message(message_id=N)  # Read specific message\n```\n\n### When Blocked\n```\nswarmmail_send(\n  to=[\"coordinator\"],\n  subject=\"BLOCKED: {bead_id}\",\n  body=\"<blocker description, what you need>\",\n  importance=\"high\",\n  thread_id=\"{epic_id}\"\n)\nhive_update(id=\"{bead_id}\", status=\"blocked\")\n```\n\n### Report Issues to Other Agents\n```\nswarmmail_send(\n  to=[\"OtherAgent\", \"coordinator\"],\n  subject=\"Issue in {bead_id}\",\n  body=\"<describe problem, don't fix their code>\",\n  thread_id=\"{epic_id}\"\n)\n```\n\n### Manual Release (if needed)\n```\nswarmmail_release()  # Manually release reservations\n```\n\n**Note:** `swarm_complete` automatically releases reservations. Only use manual release if aborting work.\n\n## [OTHER TOOLS]\n### Hive - You Have Autonomy to File Issues\nYou can create new cells against this epic when you discover:\n- **Bugs**: Found a bug while working? File it.\n- **Tech debt**: Spotted something that needs cleanup? File it.\n- **Follow-up work**: Task needs more work than scoped? File a follow-up.\n- **Dependencies**: Need something from another agent? File and link it.\n\n```\nhive_create(\n  title=\"<descriptive title>\",\n  type=\"bug\",  # or \"task\", \"chore\"\n  priority=2,\n  parent_id=\"{epic_id}\",  # Links to this epic\n  description=\"Found while working on {bead_id}: <details>\"\n)\n```\n\n**Don't silently ignore issues.** File them so they get tracked and addressed.\n\nOther cell operations:\n- hive_update(id, status) - Mark blocked if stuck\n- hive_query(status=\"open\") - See what else needs work\n\n### Skills\n- skills_list() - Discover available skills\n- skills_use(name) - Activate skill for specialized guidance\n- skills_create(name) - Create new skill (if you found a reusable pattern)\n\n## [CRITICAL REQUIREMENTS]\n\n**NON-NEGOTIABLE:**\n1. Step 1 (swarmmail_init) MUST be first - do it before anything else\n2. Step 2 (semantic-memory_find) MUST happen before starting work\n3. Step 4 (swarmmail_reserve) - YOU reserve files, not coordinator\n4. Step 6 (swarm_progress) - Report at milestones, don't work silently\n5. Step 9 (swarm_complete) - Use this to close, NOT hive_close\n\n**If you skip these steps:**\n- Your work won't be tracked (swarm_complete will fail)\n- You'll waste time repeating solved problems (no semantic memory query)\n- Edit conflicts with other agents (no file reservation)\n- Lost work if you crash (no checkpoints)\n- Future agents repeat your mistakes (no learnings stored)\n\nBegin now.";
 /**
  * Prompt for self-evaluation before completing a subtask.
  *

package/dist/swarm-prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm-prompts.d.ts","sourceRoot":"","sources":["../src/swarm-prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,m6EAkET,CAAC;AAEzB;;GAEG;AACH,eAAO,MAAM,6BAA6B,gxDAyDlB,CAAC;AAEzB;;;;;GAKG;AACH,eAAO,MAAM,cAAc,mkFAgFK,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,qiNAwOnB,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,8jCAmCU,CAAC;AAMzC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH,GAAG,MAAM,CAuDT;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAUT;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,GAAG,MAAM,CAMT;AAMD;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;CAoC/B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0D9B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;CAoClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;CA0I5B,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKvB,CAAC"}
+{"version":3,"file":"swarm-prompts.d.ts","sourceRoot":"","sources":["../src/swarm-prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,m6EAkET,CAAC;AAEzB;;GAEG;AACH,eAAO,MAAM,6BAA6B,gxDAyDlB,CAAC;AAEzB;;;;;GAKG;AACH,eAAO,MAAM,cAAc,mkFAgFK,CAAC;AAEjC;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,ksOA8PnB,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,8jCAmCU,CAAC;AAMzC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH,GAAG,MAAM,CA2ET;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAUT;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,GAAG,MAAM,CAMT;AAMD;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;CAoC/B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0D9B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;CAoClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;CA0I5B,CAAC;AAEH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKvB,CAAC"}

package/dist/swarm-review.d.ts

@@ -167,6 +167,10 @@ export declare function getReviewStatus(taskId: string): TaskReviewStatus;
  * Clear review status (for testing or reset)
  */
 export declare function clearReviewStatus(taskId: string): void;
+/**
+ * Mark a task as reviewed but not approved (for testing)
+ */
+export declare function markReviewRejected(taskId: string): void;
 export declare const reviewTools: {
     swarm_review: {
         description: string;

package/dist/swarm-review.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm-review.d.ts","sourceRoot":"","sources":["../src/swarm-review.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,iBAAiB;;;;;iBAK5B,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,UAAU,GAAG,eAAe,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;iBAkB5B,CAAC;AAEJ;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1C,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;CACrC;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAsGzE;AAmED;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CA+GvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;CA6KhC,CAAC;AAMH;;GAEG;AACH,UAAU,gBAAgB;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAOD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAQhE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGtD;AAMD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGvB,CAAC"}
+{"version":3,"file":"swarm-review.d.ts","sourceRoot":"","sources":["../src/swarm-review.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,iBAAiB;;;;;iBAK5B,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,UAAU,GAAG,eAAe,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;iBAkB5B,CAAC;AAEJ;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1C,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;CACrC;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAsGzE;AAmED;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CA+GvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;CA6KhC,CAAC;AAMH;;GAEG;AACH,UAAU,gBAAgB;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAOD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGvD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAQhE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEvD;AAMD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGvB,CAAC"}

package/docs/planning/ADR-008-worker-handoff-protocol.md

@@ -0,0 +1,293 @@
+# ADR-008: Worker Handoff Protocol - Structured Contracts Over Prose
+
+## Status
+
+Proposed
+
+## Context
+
+The current `SUBTASK_PROMPT_V2` is a **280-line prose instruction manual** that gets injected into every swarm worker's context. This approach has fundamental problems:
+
+### Current Problems
+
+1. **Workers ignore prose** - Long text instructions get skimmed or missed entirely
+2. **No validation** - Can't programmatically verify workers followed protocol
+3. **Context bloat** - 280 lines * N workers burns tokens fast
+4. **Drift and violations** - Workers modify files outside their scope, no automatic detection
+5. **Manual error recovery** - Coordinator can't auto-detect contract violations
+
+**Concrete example of failure:**
+```
+Worker assigned: ["src/auth/service.ts"]
+Worker actually touched: ["src/auth/service.ts", "src/lib/jwt.ts", "src/types/user.ts"]
+                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                         Scope creep undetected until swarm_complete
+```
+
+Current `swarm_complete` validates `files_touched ⊆ files_owned`, but the **contract** was never machine-readable to begin with.
+
+### Research & Inspirations
+
+From "Patterns for Building AI Agents" and production event-driven systems:
+
+**mdflow adapter pattern:**
+- Convention-based behavior inference
+- Template variables define expectations
+- Minimal configuration, maximum clarity
+
+**Bellemare's event-driven orchestration:**
+- Explicit contracts between services
+- Commands vs Events distinction
+- Contract violations fail fast with clear errors
+
+**Key insight:** Agents need **two channels**:
+1. **Contract** (machine-readable, validated) - WHAT to do, WHERE to do it
+2. **Context** (human-readable, advisory) - WHY it matters, HOW it fits together
+
+## Decision
+
+Replace 280-line prose with **WorkerHandoff envelope** that separates contract from context.
+
+### WorkerHandoff Structure
+
+```typescript
+interface WorkerHandoff {
+  // Machine-readable - enforced by tools
+  contract: {
+    task_id: string;              // Cell ID for tracking
+    files_owned: string[];        // Exclusive write access (validated)
+    files_readonly: string[];     // Can read, MUST NOT modify (validated)
+    dependencies_completed: string[];  // Tasks that finished before this
+    success_criteria: string[];   // Exit conditions (checkable)
+  };
+  
+  // Human-readable - advisory context
+  context: {
+    epic_summary: string;         // Big picture goal
+    your_role: string;            // What this subtask accomplishes
+    what_others_did: string;      // Dependency outputs
+    what_comes_next: string;      // Downstream task expectations
+  };
+  
+  // Escalation paths - when things go wrong
+  escalation: {
+    blocked_contact: string;      // "coordinator" or agent name
+    scope_change_protocol: string; // "swarmmail_send + await approval"
+  };
+}
+```
+
+### Example Handoff
+
+```json
+{
+  "contract": {
+    "task_id": "bd-123.2",
+    "files_owned": ["src/auth/service.ts", "src/auth/service.test.ts"],
+    "files_readonly": ["src/types/user.ts", "src/lib/jwt.ts"],
+    "dependencies_completed": ["bd-123.1"],
+    "success_criteria": [
+      "AuthService.login() returns JWT token",
+      "Tests pass: bun test src/auth/service.test.ts",
+      "Type check passes: tsc --noEmit"
+    ]
+  },
+  "context": {
+    "epic_summary": "Add OAuth authentication to user service",
+    "your_role": "Implement AuthService with JWT token generation",
+    "what_others_did": "bd-123.1 created User schema with email/password fields",
+    "what_comes_next": "bd-123.3 will integrate this service into API routes"
+  },
+  "escalation": {
+    "blocked_contact": "coordinator",
+    "scope_change_protocol": "swarmmail_send(subject='Scope Change', ack_required=true)"
+  }
+}
+```
+
+### Validation in swarm_complete
+
+```typescript
+// swarm_complete now validates against contract
+function validateCompletion(handoff: WorkerHandoff, result: CompletionReport) {
+  const violations: string[] = [];
+  
+  // 1. File scope violations
+  const unauthorized = result.files_touched.filter(
+    f => !handoff.contract.files_owned.includes(f)
+  );
+  if (unauthorized.length > 0) {
+    violations.push(`Touched unauthorized files: ${unauthorized.join(", ")}`);
+  }
+  
+  // 2. Success criteria (checkable ones)
+  for (const criterion of handoff.contract.success_criteria) {
+    if (criterion.startsWith("Tests pass:")) {
+      // Run the test command, validate exit 0
+    }
+    if (criterion.startsWith("Type check passes:")) {
+      // Run tsc --noEmit, validate exit 0
+    }
+  }
+  
+  // 3. Learning signals from violations
+  if (violations.length > 0) {
+    recordLearningSignal({
+      task_id: handoff.contract.task_id,
+      violation_type: "scope_creep",
+      details: violations,
+      impact: "negative"  // Penalize decomposition strategy
+    });
+  }
+  
+  return { valid: violations.length === 0, violations };
+}
+```
+
+### Integration with Existing Tools
+
+**swarm_spawn_subtask generates handoffs:**
+
+```typescript
+export const swarm_spawn_subtask = tool(/* ... */)
+  .handler(async ({ input, context }) => {
+    const handoff: WorkerHandoff = {
+      contract: {
+        task_id: input.bead_id,
+        files_owned: input.files,
+        files_readonly: inferReadonlyFiles(input.files, epicContext),
+        dependencies_completed: input.dependencies_completed || [],
+        success_criteria: generateSuccessCriteria(input.subtask_description)
+      },
+      context: {
+        epic_summary: epicContext.summary,
+        your_role: input.subtask_title,
+        what_others_did: summarizeDependencies(input.dependencies_completed),
+        what_comes_next: summarizeDownstream(input.bead_id)
+      },
+      escalation: {
+        blocked_contact: "coordinator",
+        scope_change_protocol: "swarmmail_send(subject='Scope Change', ack_required=true)"
+      }
+    };
+    
+    return formatHandoff(handoff); // Compact JSON + minimal prose wrapper
+  });
+```
+
+**swarm_complete validates contract:**
+
+```typescript
+export const swarm_complete = tool(/* ... */)
+  .handler(async ({ input, context }) => {
+    const handoff = getStoredHandoff(input.bead_id);
+    const validation = validateCompletion(handoff, {
+      files_touched: input.files_touched,
+      summary: input.summary
+    });
+    
+    if (!validation.valid) {
+      throw new Error(
+        `Contract violations detected:\n${validation.violations.join("\n")}`
+      );
+    }
+    
+    // Proceed with UBS scan, reservation release, etc.
+  });
+```
+
+## Consequences
+
+### Positive
+
+- **Validation enforced** - Can't complete with contract violations
+- **Clear boundaries** - Workers know exactly what's in/out of scope
+- **Better learning** - Scope creep violations feed back into strategy selection
+- **Context efficiency** - Contract is ~30 lines JSON vs 280 lines prose
+- **Fail fast** - Violations detected immediately, not during merge
+- **Programmatic recovery** - Coordinator can auto-detect and reassign work
+
+### Negative
+
+- **Requires storage** - Handoffs must persist (already have event store)
+- **Success criteria limited** - Can't validate all criteria automatically
+- **Migration cost** - Existing `SUBTASK_PROMPT_V2` users need update
+- **More upfront work** - Coordinator must generate better contracts
+
+### Neutral
+
+- **Prose still exists** - `context` field provides human explanation, just smaller
+- **Not eliminating checklist** - 9-step survival checklist stays, but moves to tool enforcement
+
+## Implementation Notes
+
+### Phase 1: Storage & Schema
+
+1. Add `WorkerHandoff` schema to swarm-mail event types
+2. Store handoffs in event log when spawning subtasks
+3. Retrieve handoffs in `swarm_complete` for validation
+
+### Phase 2: Generation Logic
+
+1. Implement `inferReadonlyFiles()` - analyze imports/dependencies
+2. Implement `generateSuccessCriteria()` - parse task description for checkable conditions
+3. Implement `summarizeDependencies()` and `summarizeDownstream()` - build context from epic graph
+
+### Phase 3: Validation
+
+1. Add contract validation to `swarm_complete`
+2. Implement checkable criteria runners (test commands, type checks)
+3. Record learning signals for violations
+
+### Phase 4: Migration
+
+1. Update `formatSubtaskPromptV2` to generate handoff JSON
+2. Deprecate 280-line prose template
+3. Update tests for new handoff format
+
+### Phase 5: Enhanced Features (Future)
+
+1. **Readonly enforcement** - Detect modifications to `files_readonly` via git diff
+2. **Dependency validation** - Verify `dependencies_completed` actually ran first
+3. **Auto-generated success criteria** - Parse test files, infer criteria from code
+
+## Alternatives Considered
+
+### Keep Prose, Add Validation
+
+Keep `SUBTASK_PROMPT_V2` but add validation after-the-fact. **Rejected** because:
+- Still burns 280 lines of context per worker
+- Workers still ignore prose
+- Validation happens too late (after work done)
+
+### Minimal Contract Only
+
+Remove context entirely, pure machine contract. **Rejected** because:
+- Workers need WHY to make good judgment calls
+- Context helps with edge cases not in contract
+- Loss of human readability hurts debugging
+
+### Command Pattern (Bellemare Style)
+
+Full event-sourcing with Command objects. **Rejected** because:
+- Over-engineered for current needs
+- Already have event store for coordination
+- Contract + context is simpler and sufficient
+
+## References
+
+- **"Patterns for Building AI Agents"** - Subagent context sharing patterns
+- **mdflow** - Convention-based adapter design, template variable contracts
+- **Bellemare's "Building Event-Driven Microservices"** - Explicit contracts, fail-fast validation
+- **Current implementation:** `src/swarm-prompts.ts` (SUBTASK_PROMPT_V2, lines 253-530)
+- **Related:** ADR-007 (Structured Review), ADR-002 (Package Extraction)
+
+## Success Criteria
+
+- [ ] `WorkerHandoff` schema defined and validated with Zod
+- [ ] `swarm_spawn_subtask` generates handoffs instead of raw prose
+- [ ] `swarm_complete` validates contract before accepting completion
+- [ ] Scope violations trigger learning signals (negative feedback)
+- [ ] Workers receive handoff as JSON + compact context wrapper (<50 lines)
+- [ ] Test suite validates contract enforcement catches violations
+- [ ] Migration path documented for existing swarm users

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.30.0",
+  "version": "0.30.2",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,8 +32,10 @@
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "@opencode-ai/plugin": "^1.0.134",
+    "effect": "^3.19.12",
     "gray-matter": "^4.0.3",
     "ioredis": "^5.4.1",
+    "minimatch": "^10.1.1",
     "swarm-mail": "0.4.0",
     "zod": "4.1.8"
   },