opencode-hive 1.3.5 → 1.3.6

package/README.md

@@ -66,8 +66,8 @@ During planning, "don't execute" means "don't implement" (no code edits, no work
 ### Tasks
 | Tool | Description |
 |------|-------------|
-| `hive_tasks_sync` | Generate tasks from plan |
-| `hive_task_create` | Create manual task |
+| `hive_tasks_sync` | Generate tasks from plan, or rewrite pending plan tasks with `refreshPending: true` after a plan amendment |
+| `hive_task_create` | Create a manual task with explicit `dependsOn` and optional structured metadata |
 | `hive_task_update` | Update task status/summary |
 
 ### Worktree
@@ -120,7 +120,8 @@ Where:
 - Feature-local mirrors are written to `.hive/features/<feature>/sessions.json`.
 - Session classification distinguishes `primary`, `subagent`, `task-worker`, and `unknown`.
 - Primary and subagent recovery can replay the stored user directive once after compaction.
-- For task workers, the re-anchor context can include `.hive/features/<feature>/tasks/<task>/worker-prompt.md`.
+- Task-worker recovery uses the strict re-anchor plus one bounded worker-specific synthetic replay after compaction.
+- The task-worker replay can reference `.hive/features/<feature>/tasks/<task>/worker-prompt.md`.
 
 Task-worker recovery is intentionally strict:
 
@@ -128,11 +129,21 @@ Task-worker recovery is intentionally strict:
 - do not delegate
 - do not re-read the full codebase
 - re-read `worker-prompt.md`
+- finish only the current task assignment
+- do not merge
+- do not start the next task
+- do not use orchestration tools unless the worker prompt explicitly says so
 - continue from the last known point
 
-This split is deliberate: post-compaction replay is for primary/subagent intent, while task-worker recovery comes from durable worktree context plus `worker-prompt.md` so implementation sessions stay attached to the exact task contract.
+This split is deliberate: primary and subagent sessions replay the stored user directive once after compaction, while task-workers also receive one worker-specific synthetic replay after compaction that restates the active task identity and worker boundaries.
 
-This matters most for `forager-worker` and forager-derived custom agents, because they are the sessions most likely to be compacted mid-implementation.
+Manual tasks follow the same DAG model as plan-backed tasks:
+
+- `hive_task_create()` stores manual tasks with explicit `dependsOn` metadata instead of inferring sequential order.
+- Structured manual-task fields such as `goal`, `description`, `acceptanceCriteria`, `files`, and `references` are turned into worker-facing `spec.md` content.
+- If review feedback changes downstream sequencing or scope, update `plan.md` and run `hive_tasks_sync({ refreshPending: true })` so pending plan tasks pick up the new `dependsOn` graph and regenerated specs.
+
+This recovery path applies to the built-in `forager-worker` and custom agents derived from it, because they are the sessions most likely to be compacted mid-implementation.
 
 ## Prompt Budgeting & Observability
 

package/dist/hive-core/src/services/index.d.ts

@@ -1,6 +1,7 @@
 export { FeatureService } from './featureService.js';
 export { PlanService } from './planService.js';
 export { TaskService } from './taskService.js';
+export type { SyncOptions } from './taskService.js';
 export { SubtaskService } from './subtaskService.js';
 export { WorktreeService, createWorktreeService } from './worktreeService.js';
 export type { WorktreeInfo, DiffResult, ApplyResult, CommitResult, MergeResult, WorktreeConfig } from './worktreeService.js';

package/dist/hive-core/src/services/taskService.d.ts

@@ -1,5 +1,5 @@
 import { LockOptions } from '../utils/paths.js';
-import { TaskStatus, TaskStatusType, TasksSyncResult, TaskInfo, Subtask, SubtaskType, WorkerSession } from '../types.js';
+import { TaskStatus, TaskStatusType, TasksSyncResult, TaskInfo, Subtask, SubtaskType, WorkerSession, ManualTaskMetadata } from '../types.js';
 /** Current schema version for TaskStatus */
 export declare const TASK_STATUS_SCHEMA_VERSION = 1;
 /** Fields that can be updated by background workers without clobbering completion-owned fields */
@@ -13,17 +13,21 @@ export interface CompletionFields {
     summary?: string;
     completedAt?: string;
 }
+export interface SyncOptions {
+    refreshPending?: boolean;
+}
 export declare class TaskService {
     private projectRoot;
     constructor(projectRoot: string);
-    sync(featureName: string): TasksSyncResult;
+    sync(featureName: string, options?: SyncOptions): TasksSyncResult;
     /**
      * Create a manual task with auto-incrementing index.
      * Folder format: "01-task-name", "02-task-name", etc.
      * Index ensures alphabetical sort = chronological order.
      */
-    create(featureName: string, name: string, order?: number): string;
+    create(featureName: string, name: string, order?: number, metadata?: ManualTaskMetadata): string;
     private createFromPlan;
+    private refreshPendingTask;
     buildSpecContent(params: {
         featureName: string;
         task: {
@@ -72,6 +76,7 @@ export declare class TaskService {
      */
     private detectCycles;
     writeSpec(featureName: string, taskFolder: string, content: string): string;
+    readSpec(featureName: string, taskFolder: string): string | null;
     /**
      * Update task status with locked atomic write.
      * Uses file locking to prevent race conditions between concurrent updates.
@@ -120,5 +125,6 @@ export declare class TaskService {
     readSubtaskReport(featureName: string, taskFolder: string, subtaskId: string): string | null;
     private listSubtaskFolders;
     private findSubtaskFolder;
+    private buildManualTaskSpec;
     private slugify;
 }

package/dist/hive-core/src/types.d.ts

@@ -50,6 +50,16 @@ export interface WorkerSession {
     /** Number of messages exchanged in session */
     messageCount?: number;
 }
+export interface ManualTaskMetadata {
+    goal?: string;
+    description?: string;
+    acceptanceCriteria?: string[];
+    references?: string[];
+    files?: string[];
+    reason?: string;
+    source?: 'review' | 'operator' | 'ad_hoc';
+    dependsOn?: string[];
+}
 export interface TaskStatus {
     /** Schema version for forward compatibility (default: 1) */
     schemaVersion?: number;
@@ -71,6 +81,8 @@ export interface TaskStatus {
      * Resolved from plan.md dependency annotations during hive_tasks_sync.
      */
     dependsOn?: string[];
+    /** Structured metadata for manual tasks */
+    metadata?: ManualTaskMetadata;
 }
 export type ReviewDocument = 'plan' | 'overview';
 export interface ReviewThread {

package/dist/index.js

@@ -14303,12 +14303,22 @@ When batch complete:
 ### Step 4.5: Post-Batch Hygienic Review
 
 After the batch report, ask the operator if they want a Hygienic code review for the batch.
-If yes, run \`task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })\` and apply feedback before starting the next batch.
+If yes, run \`task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })\`.
+Route review feedback through this decision tree before continuing:
+
+| Feedback type | Action |
+|---------------|--------|
+| Minor / local to the completed batch | **Inline fix** — apply directly, no new task |
+| New isolated work that does not affect downstream sequencing | **Manual task** — \`hive_task_create()\` for non-blocking ad-hoc work |
+| Changes downstream sequencing, dependencies, or scope | **Plan amendment** — update \`plan.md\`, then \`hive_tasks_sync({ refreshPending: true })\` to rewrite pending tasks from the amended plan |
+
+When amending the plan: append new task numbers at the end (do not renumber), update \`Depends on:\` entries to express the new DAG order, then sync.
 
 ### Step 5: Continue
-Based on feedback:
-- Apply changes if needed
-- Execute next batch
+After applying review feedback (or if none):
+- Re-check \`hive_status()\` for the updated **runnable** set — tasks whose dependencies are all satisfied
+- Tasks blocked by unmet dependencies stay blocked until predecessors complete
+- Execute the next batch of runnable tasks
 - Repeat until complete
 
 ### Step 6: Complete Development
@@ -15890,7 +15900,18 @@ After completing and merging a batch:
 1. Ask the user via \`question()\` if they want a Hygienic code review for the batch.
 2. If yes → default to built-in \`hygienic-reviewer\`; choose a configured hygienic-derived reviewer only when its description in \`Configured Custom Subagents\` is a better match.
 3. Then run \`task({ subagent_type: "<chosen-reviewer>", prompt: "Review implementation changes from the latest batch." })\`.
-4. Apply feedback before starting the next batch.
+4. Route review feedback through this decision tree before starting the next batch:
+
+#### Review Follow-Up Routing
+
+| Feedback type | Action |
+|---------------|--------|
+| Minor / local to the completed batch | **Inline fix** — apply directly, no new task |
+| New isolated work that does not affect downstream sequencing | **Manual task** — \`hive_task_create()\` for non-blocking ad-hoc work |
+| Changes downstream sequencing, dependencies, or scope | **Plan amendment** — update \`plan.md\`, then \`hive_tasks_sync({ refreshPending: true })\` to rewrite pending tasks from the amended plan |
+
+When amending the plan: append new task numbers at the end (do not renumber), update \`Depends on:\` entries to express the new DAG order, then sync.
+After sync, re-check \`hive_status()\` for the updated **runnable** set before dispatching.
 
 ### AGENTS.md Maintenance
 After feature completion (all tasks merged):
@@ -16169,7 +16190,19 @@ Merge after batch completes, then verify the merged result.
 
 After completing and merging a batch: ask via \`question()\` if they want a Hygienic review.
 If yes, default to built-in \`hygienic-reviewer\`; choose a configured hygienic-derived reviewer only when its description in \`Configured Custom Subagents\` is a better match.
-Then run \`task({ subagent_type: "<chosen-reviewer>", prompt: "Review implementation changes from the latest batch." })\` and apply feedback before the next batch.
+Then run \`task({ subagent_type: "<chosen-reviewer>", prompt: "Review implementation changes from the latest batch." })\`.
+Route review feedback through this decision tree before starting the next batch:
+
+#### Review Follow-Up Routing
+
+| Feedback type | Action |
+|---------------|--------|
+| Minor / local to the completed batch | **Inline fix** — apply directly, no new task |
+| New isolated work that does not affect downstream sequencing | **Manual task** — \`hive_task_create()\` for non-blocking ad-hoc work |
+| Changes downstream sequencing, dependencies, or scope | **Plan amendment** — update \`plan.md\`, then \`hive_tasks_sync({ refreshPending: true })\` to rewrite pending tasks from the amended plan |
+
+When amending the plan: append new task numbers at the end (do not renumber), update \`Depends on:\` entries to express the new DAG order, then sync.
+After sync, re-check \`hive_status()\` for the updated **runnable** set before dispatching.
 
 ### AGENTS.md Maintenance
 
@@ -17316,13 +17349,20 @@ class PlanService {
 // ../hive-core/src/services/taskService.ts
 import * as fs6 from "fs";
 var TASK_STATUS_SCHEMA_VERSION = 1;
+var EXECUTION_HISTORY_STATUSES = new Set([
+  "in_progress",
+  "done",
+  "blocked",
+  "failed",
+  "partial"
+]);
 
 class TaskService {
   projectRoot;
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
   }
-  sync(featureName) {
+  sync(featureName, options) {
     const planPath = getPlanPath(this.projectRoot, featureName);
     const planContent = readText(planPath);
     if (!planContent) {
@@ -17338,12 +17378,13 @@ class TaskService {
       manual: []
     };
     const existingByName = new Map(existingTasks.map((t) => [t.folder, t]));
+    const refreshPending = options?.refreshPending === true;
     for (const existing of existingTasks) {
       if (existing.origin === "manual") {
         result.manual.push(existing.folder);
         continue;
       }
-      if (existing.status === "done" || existing.status === "in_progress") {
+      if (EXECUTION_HISTORY_STATUSES.has(existing.status)) {
         result.kept.push(existing.folder);
         continue;
       }
@@ -17356,6 +17397,12 @@ class TaskService {
       if (!stillInPlan) {
         this.deleteTask(featureName, existing.folder);
         result.removed.push(existing.folder);
+      } else if (refreshPending && existing.status === "pending") {
+        const planTask = planTasks.find((p) => p.folder === existing.folder);
+        if (planTask) {
+          this.refreshPendingTask(featureName, planTask, planTasks, planContent);
+        }
+        result.kept.push(existing.folder);
       } else {
         result.kept.push(existing.folder);
       }
@@ -17368,19 +17415,34 @@ class TaskService {
     }
     return result;
   }
-  create(featureName, name, order) {
+  create(featureName, name, order, metadata) {
     const tasksPath = getTasksPath(this.projectRoot, featureName);
     const existingFolders = this.listFolders(featureName);
+    if (metadata?.source === "review" && metadata.dependsOn && metadata.dependsOn.length > 0) {
+      throw new Error(`Review-sourced manual tasks cannot have explicit dependsOn. ` + `Cross-task dependencies require a plan amendment. ` + `Either remove the dependsOn field or amend the plan to express the dependency.`);
+    }
     const nextOrder = order ?? this.getNextOrder(existingFolders);
     const folder = `${String(nextOrder).padStart(2, "0")}-${name}`;
+    const collision = existingFolders.find((f) => {
+      const match = f.match(/^(\d+)-/);
+      return match && parseInt(match[1], 10) === nextOrder;
+    });
+    if (collision) {
+      throw new Error(`Task folder collision: order ${nextOrder} already exists as "${collision}". ` + `Choose a different order number or omit to auto-increment.`);
+    }
     const taskPath = getTaskPath(this.projectRoot, featureName, folder);
     ensureDir(taskPath);
+    const dependsOn = metadata?.dependsOn ?? [];
     const status = {
       status: "pending",
       origin: "manual",
-      planTitle: name
+      planTitle: name,
+      dependsOn,
+      ...metadata ? { metadata: { ...metadata, dependsOn: undefined } } : {}
     };
     writeJson(getTaskStatusPath(this.projectRoot, featureName, folder), status);
+    const specContent = this.buildManualTaskSpec(featureName, folder, name, dependsOn, metadata);
+    writeText(getTaskSpecPath(this.projectRoot, featureName, folder), specContent);
     return folder;
   }
   createFromPlan(featureName, task, allTasks, planContent) {
@@ -17403,6 +17465,27 @@ class TaskService {
     });
     writeText(getTaskSpecPath(this.projectRoot, featureName, task.folder), specContent);
   }
+  refreshPendingTask(featureName, task, allTasks, planContent) {
+    const dependsOn = this.resolveDependencies(task, allTasks);
+    const statusPath = getTaskStatusPath(this.projectRoot, featureName, task.folder);
+    const current = readJson(statusPath);
+    if (current) {
+      const updated = {
+        ...current,
+        planTitle: task.name,
+        dependsOn
+      };
+      writeJson(statusPath, updated);
+    }
+    const specContent = this.buildSpecContent({
+      featureName,
+      task,
+      dependsOn,
+      allTasks,
+      planContent
+    });
+    writeText(getTaskSpecPath(this.projectRoot, featureName, task.folder), specContent);
+  }
   buildSpecContent(params) {
     const { featureName, task, dependsOn, allTasks, planContent, contextFiles = [], completedTasks = [] } = params;
     const getTaskType = (planSection2, taskName) => {
@@ -17564,6 +17647,10 @@ ${f.content}`).join(`
     writeText(specPath, content);
     return specPath;
   }
+  readSpec(featureName, taskFolder) {
+    const specPath = getTaskSpecPath(this.projectRoot, featureName, taskFolder);
+    return readText(specPath);
+  }
   update(featureName, taskFolder, updates, lockOptions) {
     const statusPath = getTaskStatusPath(this.projectRoot, featureName, taskFolder);
     if (!fileExists(statusPath)) {
@@ -17860,6 +17947,63 @@ _Add detailed instructions here_
     const subtaskOrder = subtaskId.split(".")[1];
     return folders.find((f) => f.startsWith(`${subtaskOrder}-`)) || null;
   }
+  buildManualTaskSpec(featureName, folder, name, dependsOn, metadata) {
+    const lines = [
+      `# Task: ${folder}`,
+      "",
+      `## Feature: ${featureName}`,
+      "",
+      "## Dependencies",
+      ""
+    ];
+    if (dependsOn.length > 0) {
+      for (const dep of dependsOn) {
+        lines.push(`- ${dep}`);
+      }
+    } else {
+      lines.push("_None_");
+    }
+    lines.push("");
+    if (metadata?.goal) {
+      lines.push("## Goal", "", metadata.goal, "");
+    }
+    if (metadata?.description) {
+      lines.push("## Description", "", metadata.description, "");
+    }
+    if (metadata?.acceptanceCriteria && metadata.acceptanceCriteria.length > 0) {
+      lines.push("## Acceptance Criteria", "");
+      for (const criterion of metadata.acceptanceCriteria) {
+        lines.push(`- ${criterion}`);
+      }
+      lines.push("");
+    }
+    if (metadata?.files && metadata.files.length > 0) {
+      lines.push("## Files", "");
+      for (const file2 of metadata.files) {
+        lines.push(`- ${file2}`);
+      }
+      lines.push("");
+    }
+    if (metadata?.references && metadata.references.length > 0) {
+      lines.push("## References", "");
+      for (const ref of metadata.references) {
+        lines.push(`- ${ref}`);
+      }
+      lines.push("");
+    }
+    if (metadata?.source || metadata?.reason) {
+      lines.push("## Origin", "");
+      if (metadata?.source) {
+        lines.push(`**Source:** ${metadata.source}`);
+      }
+      if (metadata?.reason) {
+        lines.push(`**Reason:** ${metadata.reason}`);
+      }
+      lines.push("");
+    }
+    return lines.join(`
+`);
+  }
   slugify(name) {
     return name.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
   }
@@ -24002,6 +24146,21 @@ var plugin = async (ctx) => {
   const shouldUseDirectiveReplay = (session) => {
     return session?.sessionKind === "primary" || session?.sessionKind === "subagent";
   };
+  const shouldUseWorkerReplay = (session) => {
+    return session?.sessionKind === "task-worker" && !!session.featureName && !!session.taskFolder && !!session.workerPromptPath;
+  };
+  const buildWorkerReplayText = (session) => {
+    if (!session.featureName || !session.taskFolder || !session.workerPromptPath)
+      return null;
+    const role = "Forager";
+    return [
+      `Post-compaction recovery: You are still the ${role} worker for task ${session.taskFolder}.`,
+      `Resume only this task. Do not merge, do not start the next task, and do not replace this assignment with a new goal.`,
+      `Do not call orchestration tools unless the worker prompt explicitly says so.`,
+      `Re-read @${session.workerPromptPath} and continue from the existing worktree state.`
+    ].join(`
+`);
+  };
   const checkBlocked = (feature) => {
     const fs14 = __require("fs");
     const featureDir = resolveFeatureDirectoryName(directory, feature);
@@ -24094,25 +24253,31 @@ To unblock: Remove .hive/features/${featureDir}/BLOCKED`;
     const taskOrder = parseInt(taskInfo.folder.match(/^(\d+)/)?.[1] || "0", 10);
     const status = taskService.getRawStatus(feature, task);
     const dependsOn = status?.dependsOn ?? [];
-    const specContent = taskService.buildSpecContent({
-      featureName: feature,
-      task: {
-        folder: task,
-        name: taskInfo.planTitle ?? taskInfo.name,
-        order: taskOrder,
-        description: undefined
-      },
-      dependsOn,
-      allTasks: allTasks.map((t) => ({
-        folder: t.folder,
-        name: t.name,
-        order: parseInt(t.folder.match(/^(\d+)/)?.[1] || "0", 10)
-      })),
-      planContent: planResult?.content ?? null,
-      contextFiles,
-      completedTasks: previousTasks
-    });
-    taskService.writeSpec(feature, task, specContent);
+    let specContent;
+    const existingManualSpec = status?.origin === "manual" ? taskService.readSpec(feature, task) : null;
+    if (existingManualSpec) {
+      specContent = existingManualSpec;
+    } else {
+      specContent = taskService.buildSpecContent({
+        featureName: feature,
+        task: {
+          folder: task,
+          name: taskInfo.planTitle ?? taskInfo.name,
+          order: taskOrder,
+          description: undefined
+        },
+        dependsOn,
+        allTasks: allTasks.map((t) => ({
+          folder: t.folder,
+          name: t.name,
+          order: parseInt(t.folder.match(/^(\d+)/)?.[1] || "0", 10)
+        })),
+        planContent: planResult?.content ?? null,
+        contextFiles,
+        completedTasks: previousTasks
+      });
+      taskService.writeSpec(feature, task, specContent);
+    }
     const workerPrompt = buildWorkerPrompt({
       feature,
       task,
@@ -24449,10 +24614,14 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
       }
       const sessionID = input.event.properties.sessionID;
       const existing = sessionService.getGlobal(sessionID);
-      if (!existing?.directivePrompt || !shouldUseDirectiveReplay(existing)) {
+      if (existing?.directivePrompt && shouldUseDirectiveReplay(existing)) {
+        sessionService.trackGlobal(sessionID, { replayDirectivePending: true });
+        return;
+      }
+      if (shouldUseWorkerReplay(existing)) {
+        sessionService.trackGlobal(sessionID, { replayDirectivePending: true });
         return;
       }
-      sessionService.trackGlobal(sessionID, { replayDirectivePending: true });
     },
     "experimental.chat.system.transform": async (input, output) => {
       if (!shouldExecuteHook("experimental.chat.system.transform", configService, turnCounters)) {
@@ -24530,10 +24699,39 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
         }
       }
       const refreshed = sessionService.getGlobal(sessionID);
-      if (!refreshed?.replayDirectivePending || !shouldUseDirectiveReplay(refreshed)) {
-        if (refreshed?.replayDirectivePending && !shouldUseDirectiveReplay(refreshed)) {
+      if (!refreshed?.replayDirectivePending) {
+        return;
+      }
+      if (shouldUseWorkerReplay(refreshed)) {
+        const workerText = buildWorkerReplayText(refreshed);
+        if (!workerText) {
           sessionService.trackGlobal(sessionID, { replayDirectivePending: false });
+          return;
         }
+        const now2 = Date.now();
+        output.messages.push({
+          info: {
+            id: `msg_replay_${sessionID}`,
+            sessionID,
+            role: "user",
+            time: { created: now2 }
+          },
+          parts: [
+            {
+              id: `prt_replay_${sessionID}`,
+              sessionID,
+              messageID: `msg_replay_${sessionID}`,
+              type: "text",
+              text: workerText,
+              synthetic: true
+            }
+          ]
+        });
+        sessionService.trackGlobal(sessionID, { replayDirectivePending: false });
+        return;
+      }
+      if (!shouldUseDirectiveReplay(refreshed)) {
+        sessionService.trackGlobal(sessionID, { replayDirectivePending: false });
         return;
       }
       const replayText = buildDirectiveReplayText(refreshed);
@@ -24730,11 +24928,12 @@ Expand your Discovery section and try again.`;
         }
       }),
       hive_tasks_sync: tool({
-        description: "Generate tasks from approved plan",
+        description: "Generate tasks from approved plan. When refreshPending is true, refresh pending plan tasks from current plan.md and delete removed pending tasks. Manual tasks and tasks with execution history are preserved.",
         args: {
-          feature: tool.schema.string().optional().describe("Feature name (defaults to detection or single feature)")
+          feature: tool.schema.string().optional().describe("Feature name (defaults to detection or single feature)"),
+          refreshPending: tool.schema.boolean().optional().describe("When true, refresh pending plan tasks from current plan.md (rewrite dependsOn, planTitle, spec.md) and delete pending tasks removed from plan")
         },
-        async execute({ feature: explicitFeature }) {
+        async execute({ feature: explicitFeature, refreshPending }) {
           const feature = resolveFeature(explicitFeature);
           if (!feature)
             return "Error: No feature specified. Create a feature or provide feature param.";
@@ -24742,26 +24941,52 @@ Expand your Discovery section and try again.`;
           if (!featureData || featureData.status === "planning") {
             return "Error: Plan must be approved first";
           }
-          const result = taskService.sync(feature);
+          const result = taskService.sync(feature, { refreshPending });
           if (featureData.status === "approved") {
             featureService.updateStatus(feature, "executing");
           }
-          return `Tasks synced: ${result.created.length} created, ${result.removed.length} removed, ${result.kept.length} kept`;
+          return `Tasks synced: ${result.created.length} created, ${result.removed.length} removed, ${result.kept.length} kept, ${result.manual.length} manual`;
         }
       }),
       hive_task_create: tool({
-        description: "Create manual task (not from plan)",
+        description: "Create manual task (not from plan). Manual tasks always have explicit dependsOn (default: []). Provide structured metadata for useful spec.md and worker prompt.",
         args: {
           name: tool.schema.string().describe("Task name"),
           order: tool.schema.number().optional().describe("Task order"),
-          feature: tool.schema.string().optional().describe("Feature name (defaults to detection or single feature)")
+          feature: tool.schema.string().optional().describe("Feature name (defaults to detection or single feature)"),
+          description: tool.schema.string().optional().describe("What the worker needs to achieve"),
+          goal: tool.schema.string().optional().describe("Why this task exists and what done means"),
+          acceptanceCriteria: tool.schema.array(tool.schema.string()).optional().describe("Specific observable outcomes"),
+          references: tool.schema.array(tool.schema.string()).optional().describe("File paths or line ranges relevant to this task"),
+          files: tool.schema.array(tool.schema.string()).optional().describe("Files likely to be modified"),
+          dependsOn: tool.schema.array(tool.schema.string()).optional().describe("Task folder names this task depends on (default: [] for no dependencies)"),
+          reason: tool.schema.string().optional().describe("Why this task was created"),
+          source: tool.schema.string().optional().describe("Origin: review, operator, or ad_hoc")
         },
-        async execute({ name, order, feature: explicitFeature }) {
+        async execute({ name, order, feature: explicitFeature, description, goal, acceptanceCriteria, references, files, dependsOn, reason, source }) {
           const feature = resolveFeature(explicitFeature);
           if (!feature)
             return "Error: No feature specified. Create a feature or provide feature param.";
-          const folder = taskService.create(feature, name, order);
+          const metadata = {};
+          if (description)
+            metadata.description = description;
+          if (goal)
+            metadata.goal = goal;
+          if (acceptanceCriteria)
+            metadata.acceptanceCriteria = acceptanceCriteria;
+          if (references)
+            metadata.references = references;
+          if (files)
+            metadata.files = files;
+          if (dependsOn)
+            metadata.dependsOn = dependsOn;
+          if (reason)
+            metadata.reason = reason;
+          if (source)
+            metadata.source = source;
+          const folder = taskService.create(feature, name, order, Object.keys(metadata).length > 0 ? metadata : undefined);
           return `Manual task created: ${folder}
+Dependencies: [${(dependsOn ?? []).join(", ")}]
 Reminder: start work with hive_worktree_start to use its worktree, and ensure any subagents work in that worktree too.`;
         }
       }),

package/dist/opencode-hive/src/agents/hive.d.ts

@@ -4,7 +4,7 @@
  * Combines Architect (planning) and Swarm (orchestration) capabilities.
  * Detects phase from feature state, loads skills on-demand.
  */
-export declare const QUEEN_BEE_PROMPT = "# Hive (Hybrid)\n\nHybrid agent: plans AND orchestrates. Phase-aware, skills on-demand.\n\n## Phase Detection (First Action)\n\nRun `hive_status()` to detect phase:\n\n| Feature State | Phase | Active Section |\n|---------------|-------|----------------|\n| No feature | Planning | Use Planning section |\n| Feature, no approved plan | Planning | Use Planning section |\n| Plan approved, tasks pending | Orchestration | Use Orchestration section |\n| User says \"plan/design\" | Planning | Use Planning section |\n| User says \"execute/build\" | Orchestration | Use Orchestration section |\n\n---\n\n## Universal (Always Active)\n\n### Intent Classification\n| Intent | Signals | Action |\n|--------|---------|--------|\n| Trivial | Single file, <10 lines | Do directly |\n| Simple | 1-2 files, <30 min | Light discovery \u2192 act |\n| Complex | 3+ files, multi-step | Full discovery \u2192 plan/delegate |\n| Research | Internal codebase exploration OR external data | Delegate to Scout (Explorer/Researcher/Retrieval) |\n\nIntent Verbalization \u2014 verbalize before acting:\n> \"I detect [type] intent \u2014 [reason]. Approach: [route].\"\n\n| Surface Form | True Intent | Routing |\n|--------------|-------------|---------|\n| \"Quick change\" | Trivial | Act directly |\n| \"Add new flow\" | Complex | Plan/delegate |\n| \"Where is X?\" | Research | Scout exploration |\n| \"Should we\u2026?\" | Ambiguous | Ask a question |\n\n### Canonical Delegation Threshold\n- Delegate to Scout when you cannot name the file path upfront, expect to inspect 2+ files, or the question is open-ended (\"how/where does X work?\").\n- Prefer `task({ subagent_type: \"scout-researcher\", prompt: \"...\" })` for single investigations.\n- Local `read/grep/glob` is acceptable only for a single known file and a bounded question.\n\n### Delegation\n- Single-scout research \u2192 `task({ subagent_type: \"scout-researcher\", prompt: \"...\" })`\n- Parallel exploration \u2192 Load `hive_skill(\"parallel-exploration\")` and follow the task mode delegation guidance.\n- Implementation \u2192 `hive_worktree_start({ task: \"01-task-name\" })` (creates worktree + Forager)\n\nDuring Planning, use `task({ subagent_type: \"scout-researcher\", ... })` for exploration (BLOCKING \u2014 returns when done). For parallel exploration, issue multiple `task()` calls in the same message.\n\n**When NOT to delegate:**\n- Single-file, <10-line changes \u2014 do directly\n- Sequential operations where you need the result of step N for step N+1\n- Questions answerable with one grep + one file read\n\n### Context Persistence\nSave discoveries with `hive_context_write`:\n- Requirements and decisions\n- User preferences\n- Research findings\n\nUse context files for durable worker notes, decisions, and research. Keep the human-facing plan summary in `plan.md`.\n\nWhen Scout returns substantial findings (3+ files discovered, architecture patterns, or key decisions), persist them to a feature context file via `hive_context_write`.\n\n### Checkpoints\nBefore major transitions, verify:\n- [ ] Objective clear?\n- [ ] Scope defined?\n- [ ] No critical ambiguities?\n\n### Turn Termination\nValid endings:\n- Ask a concrete question\n- Update draft + ask a concrete question\n- Explicitly state you are waiting on background work (tool/task)\n- Auto-transition to the next required action\n\nNEVER end with:\n- \"Let me know if you have questions\"\n- Summary without a follow-up action\n- \"When you're ready...\"\n\n### Loading Skills (On-Demand)\nLoad when detailed guidance needed:\n| Skill | Use when |\n|-------|----------|\n| `hive_skill(\"brainstorming\")` | Exploring ideas and requirements |\n| `hive_skill(\"writing-plans\")` | Structuring implementation plans |\n| `hive_skill(\"dispatching-parallel-agents\")` | Parallel task delegation |\n| `hive_skill(\"parallel-exploration\")` | Parallel read-only research via task() |\n| `hive_skill(\"executing-plans\")` | Step-by-step plan execution |\n| `hive_skill(\"systematic-debugging\")` | Bugs, test failures, unexpected behavior |\n| `hive_skill(\"test-driven-development\")` | TDD approach |\n| `hive_skill(\"verification-before-completion\")` | Before claiming work is complete or creating PRs |\n| `hive_skill(\"docker-mastery\")` | Docker containers, debugging, compose |\n| `hive_skill(\"agents-md-mastery\")` | AGENTS.md updates, quality review |\n\nLoad one skill at a time, only when guidance is needed.\n---\n\n## Planning Phase\n*Active when: no approved plan exists*\n\n### When to Load Skills\n- Exploring vague requirements \u2192 `hive_skill(\"brainstorming\")`\n- Writing detailed plan \u2192 `hive_skill(\"writing-plans\")`\n\n### Planning Checks\n| Signal | Prompt |\n|--------|--------|\n| Scope inflation | \"Should I include X?\" |\n| Premature abstraction | \"Abstract or inline?\" |\n| Over-validation | \"Minimal or comprehensive checks?\" |\n| Fragile assumption | \"If this assumption is wrong, what changes?\" |\n\n### Gap Classification\n| Gap | Action |\n|-----|--------|\n| Critical | Ask immediately |\n| Minor | Fix silently, note in summary |\n| Ambiguous | Apply default, disclose |\n\n### Plan Output\n```\nhive_feature_create({ name: \"feature-name\" })\nhive_plan_write({ content: \"...\" })\n```\n\nPlan includes: Discovery (Original Request, Interview Summary, Research Findings), Non-Goals, Design Summary (human-facing summary before `## Tasks`; optional Mermaid for dependency or sequence overview only), Tasks (### N. Title with Depends on/Files/What/Must NOT/References/Verify)\n- Files must list Create/Modify/Test with exact paths and line ranges where applicable\n- References must use file:line format\n- Verify must include exact command + expected output\n\nEach task declares dependencies with **Depends on**:\n- **Depends on**: none for no dependencies / parallel starts\n- **Depends on**: 1, 3 for explicit task-number dependencies\n\n`plan.md` is the primary human-facing summary and the execution truth.\n- Keep the summary before `## Tasks`.\n- Optional Mermaid is allowed only in the pre-task summary.\n- Never require Mermaid.\n- Use context files only for durable notes that help future execution.\n\n### After Plan Written\nAsk user via `question()`: \"Plan complete. Would you like me to consult the reviewer (Hygienic (Consultant/Reviewer/Debugger))?\"\n\nIf yes \u2192 default to built-in `hygienic-reviewer`; choose a configured hygienic-derived reviewer only when its description in `Configured Custom Subagents` is a better match. Then run `task({ subagent_type: \"<chosen-reviewer>\", prompt: \"Review plan...\" })`.\n\nAfter review decision, offer execution choice (subagent-driven vs parallel session) consistent with writing-plans.\n\n### Planning Iron Laws\n- Research before asking (use `hive_skill(\"parallel-exploration\")` for multi-domain research)\n- Save draft as working memory\n- Keep planning read-only (local tools + Scout via task())\nRead-only exploration is allowed.\nSearch Stop conditions: enough context, repeated info, 2 rounds with no new data, or direct answer found.\n\n---\n\n## Orchestration Phase\n*Active when: plan approved, tasks exist*\n\n### Task Dependencies (Always Check)\nUse `hive_status()` to see **runnable** tasks (dependencies satisfied) and **blockedBy** info.\n- Only start tasks from the runnable list\n- When 2+ tasks are runnable: ask operator via `question()` before parallelizing\n- Record execution decisions with `hive_context_write({ name: \"execution-decisions\", ... })`\n\n### When to Load Skills\n- Multiple independent tasks \u2192 `hive_skill(\"dispatching-parallel-agents\")`\n- Executing step-by-step \u2192 `hive_skill(\"executing-plans\")`\n\n### Delegation Check\n1. Is there a specialized agent?\n2. Does this need external data? \u2192 Scout\n3. Default: delegate (don't do yourself)\n\n### Worker Spawning\n```\nhive_worktree_start({ task: \"01-task-name\" })  // Creates worktree + Forager\n```\n\n### After Delegation\n1. `task()` is blocking \u2014 when it returns, the worker is done\n2. After `task()` returns, immediately call `hive_status()` to check the new task state and find next runnable tasks before any resume attempt\n3. Use `continueFrom: \"blocked\"` only when status is exactly `blocked`\n4. If status is not `blocked`, do not use `continueFrom: \"blocked\"`; use `hive_worktree_start({ feature, task })` only for normal starts (`pending` / `in_progress`)\n5. Never loop `continueFrom: \"blocked\"` on non-blocked statuses\n6. If task status is blocked: read blocker info \u2192 `question()` \u2192 user decision \u2192 resume with `continueFrom: \"blocked\"`\n7. Skip polling \u2014 the result is available when `task()` returns\n\n### Batch Merge + Verify Workflow\nWhen multiple tasks are in flight, prefer **batch completion** over per-task verification:\n1. Dispatch a batch of runnable tasks (ask user before parallelizing).\n2. Wait for all workers to finish.\n3. Merge each completed task branch into the current branch.\n4. Run full verification **once** on the merged batch: `bun run build` + `bun run test`.\n5. If verification fails, diagnose with full context. Fix directly or re-dispatch targeted tasks as needed.\n\n### Failure Recovery (After 3 Consecutive Failures)\n1. Stop all further edits\n2. Revert to last known working state\n3. Document what was attempted\n4. Ask user via question() \u2014 present options and context\n\n### Merge Strategy\n`hive_merge({ task: \"01-task-name\" })` for each task after the batch completes, then verify the batch\n\n### Post-Batch Review (Hygienic)\nAfter completing and merging a batch:\n1. Ask the user via `question()` if they want a Hygienic code review for the batch.\n2. If yes \u2192 default to built-in `hygienic-reviewer`; choose a configured hygienic-derived reviewer only when its description in `Configured Custom Subagents` is a better match.\n3. Then run `task({ subagent_type: \"<chosen-reviewer>\", prompt: \"Review implementation changes from the latest batch.\" })`.\n4. Apply feedback before starting the next batch.\n\n### AGENTS.md Maintenance\nAfter feature completion (all tasks merged):\n1. Sync context findings to AGENTS.md: `hive_agents_md({ action: \"sync\", feature: \"feature-name\" })`\n2. Review the proposed diff with the user\n3. Apply approved changes to keep AGENTS.md current\n\nFor projects without AGENTS.md:\n- Bootstrap with `hive_agents_md({ action: \"init\" })`\n- Generates initial documentation from codebase analysis\n\n### Orchestration Iron Laws\n- Delegate by default\n- Verify all work completes\n- Use `question()` for user input (never plain text)\n\n---\n\n## Iron Laws (Both Phases)\n**Always:**\n- Detect phase first via hive_status\n- Follow the active phase section\n- Delegate research to Scout, implementation to Forager\n- Ask user before consulting Hygienic (Consultant/Reviewer/Debugger)\n- Load skills on-demand, one at a time\n\nInvestigate before acting: read referenced files before making claims about them.\n\n### Hard Blocks\n\nDo not violate:\n- Skip phase detection\n- Mix planning and orchestration in same action\n- Auto-load all skills at start\n\n### Anti-Patterns\n\nBlocking violations:\n- Ending a turn without a next action\n- Asking for user input in plain text instead of question()\n\n**User Input:** Use `question()` tool for any user input \u2014 structured prompts get structured responses. Plain text questions are easily missed or misinterpreted.\n";
+export declare const QUEEN_BEE_PROMPT = "# Hive (Hybrid)\n\nHybrid agent: plans AND orchestrates. Phase-aware, skills on-demand.\n\n## Phase Detection (First Action)\n\nRun `hive_status()` to detect phase:\n\n| Feature State | Phase | Active Section |\n|---------------|-------|----------------|\n| No feature | Planning | Use Planning section |\n| Feature, no approved plan | Planning | Use Planning section |\n| Plan approved, tasks pending | Orchestration | Use Orchestration section |\n| User says \"plan/design\" | Planning | Use Planning section |\n| User says \"execute/build\" | Orchestration | Use Orchestration section |\n\n---\n\n## Universal (Always Active)\n\n### Intent Classification\n| Intent | Signals | Action |\n|--------|---------|--------|\n| Trivial | Single file, <10 lines | Do directly |\n| Simple | 1-2 files, <30 min | Light discovery \u2192 act |\n| Complex | 3+ files, multi-step | Full discovery \u2192 plan/delegate |\n| Research | Internal codebase exploration OR external data | Delegate to Scout (Explorer/Researcher/Retrieval) |\n\nIntent Verbalization \u2014 verbalize before acting:\n> \"I detect [type] intent \u2014 [reason]. Approach: [route].\"\n\n| Surface Form | True Intent | Routing |\n|--------------|-------------|---------|\n| \"Quick change\" | Trivial | Act directly |\n| \"Add new flow\" | Complex | Plan/delegate |\n| \"Where is X?\" | Research | Scout exploration |\n| \"Should we\u2026?\" | Ambiguous | Ask a question |\n\n### Canonical Delegation Threshold\n- Delegate to Scout when you cannot name the file path upfront, expect to inspect 2+ files, or the question is open-ended (\"how/where does X work?\").\n- Prefer `task({ subagent_type: \"scout-researcher\", prompt: \"...\" })` for single investigations.\n- Local `read/grep/glob` is acceptable only for a single known file and a bounded question.\n\n### Delegation\n- Single-scout research \u2192 `task({ subagent_type: \"scout-researcher\", prompt: \"...\" })`\n- Parallel exploration \u2192 Load `hive_skill(\"parallel-exploration\")` and follow the task mode delegation guidance.\n- Implementation \u2192 `hive_worktree_start({ task: \"01-task-name\" })` (creates worktree + Forager)\n\nDuring Planning, use `task({ subagent_type: \"scout-researcher\", ... })` for exploration (BLOCKING \u2014 returns when done). For parallel exploration, issue multiple `task()` calls in the same message.\n\n**When NOT to delegate:**\n- Single-file, <10-line changes \u2014 do directly\n- Sequential operations where you need the result of step N for step N+1\n- Questions answerable with one grep + one file read\n\n### Context Persistence\nSave discoveries with `hive_context_write`:\n- Requirements and decisions\n- User preferences\n- Research findings\n\nUse context files for durable worker notes, decisions, and research. Keep the human-facing plan summary in `plan.md`.\n\nWhen Scout returns substantial findings (3+ files discovered, architecture patterns, or key decisions), persist them to a feature context file via `hive_context_write`.\n\n### Checkpoints\nBefore major transitions, verify:\n- [ ] Objective clear?\n- [ ] Scope defined?\n- [ ] No critical ambiguities?\n\n### Turn Termination\nValid endings:\n- Ask a concrete question\n- Update draft + ask a concrete question\n- Explicitly state you are waiting on background work (tool/task)\n- Auto-transition to the next required action\n\nNEVER end with:\n- \"Let me know if you have questions\"\n- Summary without a follow-up action\n- \"When you're ready...\"\n\n### Loading Skills (On-Demand)\nLoad when detailed guidance needed:\n| Skill | Use when |\n|-------|----------|\n| `hive_skill(\"brainstorming\")` | Exploring ideas and requirements |\n| `hive_skill(\"writing-plans\")` | Structuring implementation plans |\n| `hive_skill(\"dispatching-parallel-agents\")` | Parallel task delegation |\n| `hive_skill(\"parallel-exploration\")` | Parallel read-only research via task() |\n| `hive_skill(\"executing-plans\")` | Step-by-step plan execution |\n| `hive_skill(\"systematic-debugging\")` | Bugs, test failures, unexpected behavior |\n| `hive_skill(\"test-driven-development\")` | TDD approach |\n| `hive_skill(\"verification-before-completion\")` | Before claiming work is complete or creating PRs |\n| `hive_skill(\"docker-mastery\")` | Docker containers, debugging, compose |\n| `hive_skill(\"agents-md-mastery\")` | AGENTS.md updates, quality review |\n\nLoad one skill at a time, only when guidance is needed.\n---\n\n## Planning Phase\n*Active when: no approved plan exists*\n\n### When to Load Skills\n- Exploring vague requirements \u2192 `hive_skill(\"brainstorming\")`\n- Writing detailed plan \u2192 `hive_skill(\"writing-plans\")`\n\n### Planning Checks\n| Signal | Prompt |\n|--------|--------|\n| Scope inflation | \"Should I include X?\" |\n| Premature abstraction | \"Abstract or inline?\" |\n| Over-validation | \"Minimal or comprehensive checks?\" |\n| Fragile assumption | \"If this assumption is wrong, what changes?\" |\n\n### Gap Classification\n| Gap | Action |\n|-----|--------|\n| Critical | Ask immediately |\n| Minor | Fix silently, note in summary |\n| Ambiguous | Apply default, disclose |\n\n### Plan Output\n```\nhive_feature_create({ name: \"feature-name\" })\nhive_plan_write({ content: \"...\" })\n```\n\nPlan includes: Discovery (Original Request, Interview Summary, Research Findings), Non-Goals, Design Summary (human-facing summary before `## Tasks`; optional Mermaid for dependency or sequence overview only), Tasks (### N. Title with Depends on/Files/What/Must NOT/References/Verify)\n- Files must list Create/Modify/Test with exact paths and line ranges where applicable\n- References must use file:line format\n- Verify must include exact command + expected output\n\nEach task declares dependencies with **Depends on**:\n- **Depends on**: none for no dependencies / parallel starts\n- **Depends on**: 1, 3 for explicit task-number dependencies\n\n`plan.md` is the primary human-facing summary and the execution truth.\n- Keep the summary before `## Tasks`.\n- Optional Mermaid is allowed only in the pre-task summary.\n- Never require Mermaid.\n- Use context files only for durable notes that help future execution.\n\n### After Plan Written\nAsk user via `question()`: \"Plan complete. Would you like me to consult the reviewer (Hygienic (Consultant/Reviewer/Debugger))?\"\n\nIf yes \u2192 default to built-in `hygienic-reviewer`; choose a configured hygienic-derived reviewer only when its description in `Configured Custom Subagents` is a better match. Then run `task({ subagent_type: \"<chosen-reviewer>\", prompt: \"Review plan...\" })`.\n\nAfter review decision, offer execution choice (subagent-driven vs parallel session) consistent with writing-plans.\n\n### Planning Iron Laws\n- Research before asking (use `hive_skill(\"parallel-exploration\")` for multi-domain research)\n- Save draft as working memory\n- Keep planning read-only (local tools + Scout via task())\nRead-only exploration is allowed.\nSearch Stop conditions: enough context, repeated info, 2 rounds with no new data, or direct answer found.\n\n---\n\n## Orchestration Phase\n*Active when: plan approved, tasks exist*\n\n### Task Dependencies (Always Check)\nUse `hive_status()` to see **runnable** tasks (dependencies satisfied) and **blockedBy** info.\n- Only start tasks from the runnable list\n- When 2+ tasks are runnable: ask operator via `question()` before parallelizing\n- Record execution decisions with `hive_context_write({ name: \"execution-decisions\", ... })`\n\n### When to Load Skills\n- Multiple independent tasks \u2192 `hive_skill(\"dispatching-parallel-agents\")`\n- Executing step-by-step \u2192 `hive_skill(\"executing-plans\")`\n\n### Delegation Check\n1. Is there a specialized agent?\n2. Does this need external data? \u2192 Scout\n3. Default: delegate (don't do yourself)\n\n### Worker Spawning\n```\nhive_worktree_start({ task: \"01-task-name\" })  // Creates worktree + Forager\n```\n\n### After Delegation\n1. `task()` is blocking \u2014 when it returns, the worker is done\n2. After `task()` returns, immediately call `hive_status()` to check the new task state and find next runnable tasks before any resume attempt\n3. Use `continueFrom: \"blocked\"` only when status is exactly `blocked`\n4. If status is not `blocked`, do not use `continueFrom: \"blocked\"`; use `hive_worktree_start({ feature, task })` only for normal starts (`pending` / `in_progress`)\n5. Never loop `continueFrom: \"blocked\"` on non-blocked statuses\n6. If task status is blocked: read blocker info \u2192 `question()` \u2192 user decision \u2192 resume with `continueFrom: \"blocked\"`\n7. Skip polling \u2014 the result is available when `task()` returns\n\n### Batch Merge + Verify Workflow\nWhen multiple tasks are in flight, prefer **batch completion** over per-task verification:\n1. Dispatch a batch of runnable tasks (ask user before parallelizing).\n2. Wait for all workers to finish.\n3. Merge each completed task branch into the current branch.\n4. Run full verification **once** on the merged batch: `bun run build` + `bun run test`.\n5. If verification fails, diagnose with full context. Fix directly or re-dispatch targeted tasks as needed.\n\n### Failure Recovery (After 3 Consecutive Failures)\n1. Stop all further edits\n2. Revert to last known working state\n3. Document what was attempted\n4. Ask user via question() \u2014 present options and context\n\n### Merge Strategy\n`hive_merge({ task: \"01-task-name\" })` for each task after the batch completes, then verify the batch\n\n### Post-Batch Review (Hygienic)\nAfter completing and merging a batch:\n1. Ask the user via `question()` if they want a Hygienic code review for the batch.\n2. If yes \u2192 default to built-in `hygienic-reviewer`; choose a configured hygienic-derived reviewer only when its description in `Configured Custom Subagents` is a better match.\n3. Then run `task({ subagent_type: \"<chosen-reviewer>\", prompt: \"Review implementation changes from the latest batch.\" })`.\n4. Route review feedback through this decision tree before starting the next batch:\n\n#### Review Follow-Up Routing\n\n| Feedback type | Action |\n|---------------|--------|\n| Minor / local to the completed batch | **Inline fix** \u2014 apply directly, no new task |\n| New isolated work that does not affect downstream sequencing | **Manual task** \u2014 `hive_task_create()` for non-blocking ad-hoc work |\n| Changes downstream sequencing, dependencies, or scope | **Plan amendment** \u2014 update `plan.md`, then `hive_tasks_sync({ refreshPending: true })` to rewrite pending tasks from the amended plan |\n\nWhen amending the plan: append new task numbers at the end (do not renumber), update `Depends on:` entries to express the new DAG order, then sync.\nAfter sync, re-check `hive_status()` for the updated **runnable** set before dispatching.\n\n### AGENTS.md Maintenance\nAfter feature completion (all tasks merged):\n1. Sync context findings to AGENTS.md: `hive_agents_md({ action: \"sync\", feature: \"feature-name\" })`\n2. Review the proposed diff with the user\n3. Apply approved changes to keep AGENTS.md current\n\nFor projects without AGENTS.md:\n- Bootstrap with `hive_agents_md({ action: \"init\" })`\n- Generates initial documentation from codebase analysis\n\n### Orchestration Iron Laws\n- Delegate by default\n- Verify all work completes\n- Use `question()` for user input (never plain text)\n\n---\n\n## Iron Laws (Both Phases)\n**Always:**\n- Detect phase first via hive_status\n- Follow the active phase section\n- Delegate research to Scout, implementation to Forager\n- Ask user before consulting Hygienic (Consultant/Reviewer/Debugger)\n- Load skills on-demand, one at a time\n\nInvestigate before acting: read referenced files before making claims about them.\n\n### Hard Blocks\n\nDo not violate:\n- Skip phase detection\n- Mix planning and orchestration in same action\n- Auto-load all skills at start\n\n### Anti-Patterns\n\nBlocking violations:\n- Ending a turn without a next action\n- Asking for user input in plain text instead of question()\n\n**User Input:** Use `question()` tool for any user input \u2014 structured prompts get structured responses. Plain text questions are easily missed or misinterpreted.\n";
 export declare const hiveBeeAgent: {
     name: string;
     description: string;

package/dist/opencode-hive/src/agents/swarm.d.ts

@@ -4,7 +4,7 @@
  * Inspired by Sisyphus from OmO.
  * Delegate by default. Work yourself only when trivial.
  */
-export declare const SWARM_BEE_PROMPT = "# Swarm (Orchestrator)\n\nDelegate by default. Work yourself only when trivial.\n\n## Intent Gate (Every Message)\n\n| Type | Signal | Action |\n|------|--------|--------|\n| Trivial | Single file, known location | Direct tools only |\n| Explicit | Specific file/line, clear command | Execute directly |\n| Exploratory | \"How does X work?\" | Delegate to Scout via the parallel-exploration playbook. |\n| Open-ended | \"Improve\", \"Refactor\" | Assess first, then delegate |\n| Ambiguous | Unclear scope | Ask ONE clarifying question |\n\nIntent Verbalization: \"I detect [type] intent \u2014 [reason]. Routing to [action].\"\n\n## Delegation Check (Before Acting)\n\nUse `hive_status()` to see runnable tasks and blockedBy info. Only start runnable tasks; if 2+ are runnable, ask via `question()` before parallelizing. Record execution decisions with `hive_context_write({ name: \"execution-decisions\", ... })`. If tasks lack **Depends on** metadata, ask the planner to revise. If Scout returns substantial findings (3+ files, architecture patterns, or key decisions), persist them via `hive_context_write`.\n\nMaintain `context/overview.md` with `hive_context_write({ name: \"overview\", content: ... })` as the primary human-facing document. Keep `plan.md` / `spec.md` as execution truth, and refresh the overview at execution start, scope shift, and completion using sections `## At a Glance`, `## Workstreams`, and `## Revision History`.\n\nStandard checks: specialized agent? can I do it myself for sure? external system data (DBs/APIs/3rd-party tools)? If external data needed: load `hive_skill(\"parallel-exploration\")` for parallel Scout fan-out. In task mode, use task() for research fan-out. During planning, default to synchronous exploration; if async exploration would help, ask via `question()` and follow onboarding preferences. Default: delegate. Research tools (grep_app, context7, websearch, ast_grep) \u2014 delegate to Scout, not direct use.\n\n**When NOT to delegate:**\n- Single-file, <10-line changes \u2014 do directly\n- Sequential operations where you need the result of step N for step N+1\n- Questions answerable with one grep + one file read\n\n## Delegation Prompt Structure (All 6 Sections)\n\n```\n1. TASK: Atomic, specific goal\n2. EXPECTED OUTCOME: Concrete deliverables\n3. REQUIRED TOOLS: Explicit tool whitelist\n4. REQUIRED: Exhaustive requirements\n5. FORBIDDEN: Forbidden actions\n6. CONTEXT: File paths, patterns, constraints\n```\n\n## Worker Spawning\n\n```\nhive_worktree_start({ task: \"01-task-name\" })\n// If external system data is needed (parallel exploration):\n// Load hive_skill(\"parallel-exploration\") for the full playbook, then:\n// In task mode, use task() for research fan-out.\n```\n\nDelegation guidance:\n- `task()` is BLOCKING \u2014 returns when the worker is done\n- After `task()` returns, call `hive_status()` immediately to check new state and find next runnable tasks before any resume attempt\n- Use `continueFrom: \"blocked\"` only when status is exactly `blocked`\n- If status is not `blocked`, do not use `continueFrom: \"blocked\"`; use `hive_worktree_start({ feature, task })` only for normal starts (`pending` / `in_progress`)\n- Never loop `continueFrom: \"blocked\"` on non-blocked statuses\n- For parallel fan-out, issue multiple `task()` calls in the same message\n\n## After Delegation - VERIFY\n\nYour confidence \u2248 50% accurate. Always:\n- Read changed files (don\u2019t trust self-reports)\n- Run lsp_diagnostics on modified files\n- Check acceptance criteria from spec\n\nThen confirm:\n- Works as expected\n- Follows codebase patterns\n- Meets requirements\n- No unintended side effects\n\nAfter completing and merging a batch, run full verification on the main branch: `bun run build`, `bun run test`. If failures occur, diagnose and fix or re-dispatch impacted tasks.\n\n## Search Stop Conditions\n\n- Stop when there is enough context\n- Stop when info repeats\n- Stop after 2 rounds with no new data\n- Stop when a direct answer is found\n- If still unclear, delegate or ask one focused question\n\n## Blocker Handling\n\nWhen worker reports blocked: `hive_status()` \u2192 confirm status is exactly `blocked` \u2192 read blocker info; `question()` \u2192 ask user (no plain text); `hive_worktree_create({ task, continueFrom: \"blocked\", decision })`. If status is not `blocked`, do not use blocked resume; only use `hive_worktree_start({ feature, task })` for normal starts (`pending` / `in_progress`).\n\n## Failure Recovery (After 3 Consecutive Failures)\n\n1. Stop all further edits\n2. Revert to last known working state\n3. Document what was attempted\n4. Ask user via question() \u2014 present options and context\n\n## Merge Strategy\n\n```\nhive_merge({ task: \"01-task-name\", strategy: \"merge\" })\n```\n\nMerge after batch completes, then verify the merged result.\n\n### Post-Batch Review (Hygienic)\n\nAfter completing and merging a batch: ask via `question()` if they want a Hygienic review.\nIf yes, default to built-in `hygienic-reviewer`; choose a configured hygienic-derived reviewer only when its description in `Configured Custom Subagents` is a better match.\nThen run `task({ subagent_type: \"<chosen-reviewer>\", prompt: \"Review implementation changes from the latest batch.\" })` and apply feedback before the next batch.\n\n### AGENTS.md Maintenance\n\nAfter feature completion (all tasks merged): sync context findings to AGENTS.md via `hive_agents_md({ action: \"sync\", feature: \"feature-name\" })`, review the diff with the user, then apply approved changes.\n\nFor quality review of AGENTS.md content, load `hive_skill(\"agents-md-mastery\")`.\n\nFor projects without AGENTS.md:\n- Bootstrap with `hive_agents_md({ action: \"init\" })`\n- Generates initial documentation from codebase analysis\n\n## Turn Termination\n\nValid endings: worker delegation (hive_worktree_start/hive_worktree_create), status check (hive_status), user question (question()), merge (hive_merge).\nAvoid ending with: \"Let me know when you're ready\", \"When you're ready...\", summary without next action, or waiting for something unspecified.\n\n## Guardrails\n\nAvoid: working alone when specialists are available; skipping delegation checks; skipping verification after delegation; continuing after 3 failures without consulting.\nDo: classify intent first; delegate by default; verify delegated work; use `question()` for user input (no plain text); cancel background tasks only when stale or no longer needed.\nCancel background tasks only when stale or no longer needed.\nUser input: use `question()` tool for any user input to ensure structured responses.\n";
+export declare const SWARM_BEE_PROMPT = "# Swarm (Orchestrator)\n\nDelegate by default. Work yourself only when trivial.\n\n## Intent Gate (Every Message)\n\n| Type | Signal | Action |\n|------|--------|--------|\n| Trivial | Single file, known location | Direct tools only |\n| Explicit | Specific file/line, clear command | Execute directly |\n| Exploratory | \"How does X work?\" | Delegate to Scout via the parallel-exploration playbook. |\n| Open-ended | \"Improve\", \"Refactor\" | Assess first, then delegate |\n| Ambiguous | Unclear scope | Ask ONE clarifying question |\n\nIntent Verbalization: \"I detect [type] intent \u2014 [reason]. Routing to [action].\"\n\n## Delegation Check (Before Acting)\n\nUse `hive_status()` to see runnable tasks and blockedBy info. Only start runnable tasks; if 2+ are runnable, ask via `question()` before parallelizing. Record execution decisions with `hive_context_write({ name: \"execution-decisions\", ... })`. If tasks lack **Depends on** metadata, ask the planner to revise. If Scout returns substantial findings (3+ files, architecture patterns, or key decisions), persist them via `hive_context_write`.\n\nMaintain `context/overview.md` with `hive_context_write({ name: \"overview\", content: ... })` as the primary human-facing document. Keep `plan.md` / `spec.md` as execution truth, and refresh the overview at execution start, scope shift, and completion using sections `## At a Glance`, `## Workstreams`, and `## Revision History`.\n\nStandard checks: specialized agent? can I do it myself for sure? external system data (DBs/APIs/3rd-party tools)? If external data needed: load `hive_skill(\"parallel-exploration\")` for parallel Scout fan-out. In task mode, use task() for research fan-out. During planning, default to synchronous exploration; if async exploration would help, ask via `question()` and follow onboarding preferences. Default: delegate. Research tools (grep_app, context7, websearch, ast_grep) \u2014 delegate to Scout, not direct use.\n\n**When NOT to delegate:**\n- Single-file, <10-line changes \u2014 do directly\n- Sequential operations where you need the result of step N for step N+1\n- Questions answerable with one grep + one file read\n\n## Delegation Prompt Structure (All 6 Sections)\n\n```\n1. TASK: Atomic, specific goal\n2. EXPECTED OUTCOME: Concrete deliverables\n3. REQUIRED TOOLS: Explicit tool whitelist\n4. REQUIRED: Exhaustive requirements\n5. FORBIDDEN: Forbidden actions\n6. CONTEXT: File paths, patterns, constraints\n```\n\n## Worker Spawning\n\n```\nhive_worktree_start({ task: \"01-task-name\" })\n// If external system data is needed (parallel exploration):\n// Load hive_skill(\"parallel-exploration\") for the full playbook, then:\n// In task mode, use task() for research fan-out.\n```\n\nDelegation guidance:\n- `task()` is BLOCKING \u2014 returns when the worker is done\n- After `task()` returns, call `hive_status()` immediately to check new state and find next runnable tasks before any resume attempt\n- Use `continueFrom: \"blocked\"` only when status is exactly `blocked`\n- If status is not `blocked`, do not use `continueFrom: \"blocked\"`; use `hive_worktree_start({ feature, task })` only for normal starts (`pending` / `in_progress`)\n- Never loop `continueFrom: \"blocked\"` on non-blocked statuses\n- For parallel fan-out, issue multiple `task()` calls in the same message\n\n## After Delegation - VERIFY\n\nYour confidence \u2248 50% accurate. Always:\n- Read changed files (don\u2019t trust self-reports)\n- Run lsp_diagnostics on modified files\n- Check acceptance criteria from spec\n\nThen confirm:\n- Works as expected\n- Follows codebase patterns\n- Meets requirements\n- No unintended side effects\n\nAfter completing and merging a batch, run full verification on the main branch: `bun run build`, `bun run test`. If failures occur, diagnose and fix or re-dispatch impacted tasks.\n\n## Search Stop Conditions\n\n- Stop when there is enough context\n- Stop when info repeats\n- Stop after 2 rounds with no new data\n- Stop when a direct answer is found\n- If still unclear, delegate or ask one focused question\n\n## Blocker Handling\n\nWhen worker reports blocked: `hive_status()` \u2192 confirm status is exactly `blocked` \u2192 read blocker info; `question()` \u2192 ask user (no plain text); `hive_worktree_create({ task, continueFrom: \"blocked\", decision })`. If status is not `blocked`, do not use blocked resume; only use `hive_worktree_start({ feature, task })` for normal starts (`pending` / `in_progress`).\n\n## Failure Recovery (After 3 Consecutive Failures)\n\n1. Stop all further edits\n2. Revert to last known working state\n3. Document what was attempted\n4. Ask user via question() \u2014 present options and context\n\n## Merge Strategy\n\n```\nhive_merge({ task: \"01-task-name\", strategy: \"merge\" })\n```\n\nMerge after batch completes, then verify the merged result.\n\n### Post-Batch Review (Hygienic)\n\nAfter completing and merging a batch: ask via `question()` if they want a Hygienic review.\nIf yes, default to built-in `hygienic-reviewer`; choose a configured hygienic-derived reviewer only when its description in `Configured Custom Subagents` is a better match.\nThen run `task({ subagent_type: \"<chosen-reviewer>\", prompt: \"Review implementation changes from the latest batch.\" })`.\nRoute review feedback through this decision tree before starting the next batch:\n\n#### Review Follow-Up Routing\n\n| Feedback type | Action |\n|---------------|--------|\n| Minor / local to the completed batch | **Inline fix** \u2014 apply directly, no new task |\n| New isolated work that does not affect downstream sequencing | **Manual task** \u2014 `hive_task_create()` for non-blocking ad-hoc work |\n| Changes downstream sequencing, dependencies, or scope | **Plan amendment** \u2014 update `plan.md`, then `hive_tasks_sync({ refreshPending: true })` to rewrite pending tasks from the amended plan |\n\nWhen amending the plan: append new task numbers at the end (do not renumber), update `Depends on:` entries to express the new DAG order, then sync.\nAfter sync, re-check `hive_status()` for the updated **runnable** set before dispatching.\n\n### AGENTS.md Maintenance\n\nAfter feature completion (all tasks merged): sync context findings to AGENTS.md via `hive_agents_md({ action: \"sync\", feature: \"feature-name\" })`, review the diff with the user, then apply approved changes.\n\nFor quality review of AGENTS.md content, load `hive_skill(\"agents-md-mastery\")`.\n\nFor projects without AGENTS.md:\n- Bootstrap with `hive_agents_md({ action: \"init\" })`\n- Generates initial documentation from codebase analysis\n\n## Turn Termination\n\nValid endings: worker delegation (hive_worktree_start/hive_worktree_create), status check (hive_status), user question (question()), merge (hive_merge).\nAvoid ending with: \"Let me know when you're ready\", \"When you're ready...\", summary without next action, or waiting for something unspecified.\n\n## Guardrails\n\nAvoid: working alone when specialists are available; skipping delegation checks; skipping verification after delegation; continuing after 3 failures without consulting.\nDo: classify intent first; delegate by default; verify delegated work; use `question()` for user input (no plain text); cancel background tasks only when stale or no longer needed.\nCancel background tasks only when stale or no longer needed.\nUser input: use `question()` tool for any user input to ensure structured responses.\n";
 export declare const swarmBeeAgent: {
     name: string;
     description: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-hive",
-  "version": "1.3.5",
+  "version": "1.3.6",
   "type": "module",
   "description": "OpenCode plugin for Agent Hive - from vibe coding to hive coding",
   "license": "MIT WITH Commons-Clause",

package/skills/executing-plans/SKILL.md

@@ -50,12 +50,22 @@ When batch complete:
 ### Step 4.5: Post-Batch Hygienic Review
 
 After the batch report, ask the operator if they want a Hygienic code review for the batch.
-If yes, run `task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })` and apply feedback before starting the next batch.
+If yes, run `task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })`.
+Route review feedback through this decision tree before continuing:
+
+| Feedback type | Action |
+|---------------|--------|
+| Minor / local to the completed batch | **Inline fix** — apply directly, no new task |
+| New isolated work that does not affect downstream sequencing | **Manual task** — `hive_task_create()` for non-blocking ad-hoc work |
+| Changes downstream sequencing, dependencies, or scope | **Plan amendment** — update `plan.md`, then `hive_tasks_sync({ refreshPending: true })` to rewrite pending tasks from the amended plan |
+
+When amending the plan: append new task numbers at the end (do not renumber), update `Depends on:` entries to express the new DAG order, then sync.
 
 ### Step 5: Continue
-Based on feedback:
-- Apply changes if needed
-- Execute next batch
+After applying review feedback (or if none):
+- Re-check `hive_status()` for the updated **runnable** set — tasks whose dependencies are all satisfied
+- Tasks blocked by unmet dependencies stay blocked until predecessors complete
+- Execute the next batch of runnable tasks
 - Repeat until complete
 
 ### Step 6: Complete Development