opencode-herdr-orchestration 0.1.5 → 0.2.0

package/hooks/pre-push

@@ -4,11 +4,11 @@ set -eu
 
 mode=${SHEPHERD_MODE:-none}
 case "$mode" in
-  sheep-build|sheep-plan|review)
-    echo "opencode-herdr-orchestration: $mode may not push; remote Git belongs to shepherd-build." >&2
+  shepherd|sheepdog|grazer|sheep|shearer)
+    echo "opencode-herdr-orchestration: $mode may not push; final delivery belongs to the shepherd-governor." >&2
     exit 1
     ;;
-  plan)
+  governor)
     ;;
   *)
     exit 0
@@ -17,7 +17,7 @@ esac
 
 current_branch=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
 if [ -z "$current_branch" ]; then
-  echo "opencode-herdr-orchestration: shepherd-plan may not push from detached HEAD." >&2
+  echo "opencode-herdr-orchestration: shepherd-governor may not push from detached HEAD." >&2
   exit 1
 fi
 
@@ -32,7 +32,7 @@ is_protected() {
 }
 
 if is_protected "$current_branch"; then
-  echo "opencode-herdr-orchestration: shepherd-plan may not push protected branch $current_branch." >&2
+  echo "opencode-herdr-orchestration: shepherd-governor may not push protected branch $current_branch." >&2
   exit 1
 fi
 
@@ -41,20 +41,20 @@ while read -r local_ref local_sha remote_ref remote_sha; do
   [ -n "${local_ref:-}" ] || continue
 
   if [ "$local_sha" = "$zero" ]; then
-    echo "opencode-herdr-orchestration: shepherd-plan may not delete remote refs." >&2
+    echo "opencode-herdr-orchestration: shepherd-governor may not delete remote refs." >&2
     exit 1
   fi
 
   expected_local="refs/heads/$current_branch"
   expected_remote="refs/heads/$current_branch"
   if [ "$local_ref" != "$expected_local" ] || [ "$remote_ref" != "$expected_remote" ]; then
-    echo "opencode-herdr-orchestration: shepherd-plan may push only $expected_local to the same remote branch." >&2
+    echo "opencode-herdr-orchestration: shepherd-governor may push only $expected_local to the same remote branch." >&2
     exit 1
   fi
 
   remote_branch=${remote_ref#refs/heads/}
   if is_protected "$remote_branch"; then
-    echo "opencode-herdr-orchestration: shepherd-plan may not update protected branch $remote_branch." >&2
+    echo "opencode-herdr-orchestration: shepherd-governor may not update protected branch $remote_branch." >&2
     exit 1
   fi
 done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-herdr-orchestration",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Capability-separated Herdr orchestration agents for OpenCode",
   "author": "CodingJinxx",
   "repository": {
@@ -28,7 +28,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "check": "node --check src/plugin.js && node --check src/index.js && node --check src/agents.js && node --check src/prompts.js && node --check src/response.js && node --check bin/orchestration.js"
+    "check": "node --check src/plugin.js && node --check src/index.js && node --check src/agents.js && node --check src/prompts.js && node --check src/response.js && node --check src/state.js && node --check bin/orchestration.js"
   },
   "engines": {
     "node": ">=20"

package/src/agents.js

@@ -1,8 +1,9 @@
 import {
-  SHEEP_BUILD_PROMPT,
-  SHEEP_PLAN_PROMPT,
-  SHEPHERD_BUILD_PROMPT,
-  SHEPHERD_PLAN_PROMPT,
+  GRAZER_PROMPT,
+  SHEEPDOG_PROMPT,
+  SHEEP_PROMPT,
+  SHEPHERD_GOVERNOR_PROMPT,
+  SHEPHERD_PROMPT,
   SHEARER_REVIEW_PROMPT,
 } from "./prompts.js";
 
@@ -66,6 +67,112 @@ const markdownOnly = {
   "**/*.md": "allow",
 };
 
+// Constrained orchestration state tools. The planning shepherd authors plan
+// artifacts; shepherd-governor and sheepdog read the authoritative plan, and
+// sheepdog records and reads execution artifacts. This matrix is the single
+// source of truth for both the plugin-level tool enforcement (src/index.js)
+// and the per-agent permission entries below.
+export const STATE_TOOLS = Object.freeze({
+  planWrite: "herdr_plan_write",
+  planRead: "herdr_plan_read",
+  executionWrite: "herdr_execution_write",
+  executionRead: "herdr_execution_read",
+});
+
+export const STATE_TOOL_ACCESS = Object.freeze(
+  new Map([
+    [STATE_TOOLS.planWrite, new Set(["shepherd"])],
+    [STATE_TOOLS.planRead, new Set(["shepherd", "shepherd-governor", "sheepdog"])],
+    [STATE_TOOLS.executionWrite, new Set(["sheepdog"])],
+    [STATE_TOOLS.executionRead, new Set(["sheepdog"])],
+  ]),
+);
+
+const ALL_STATE_TOOLS = Object.freeze(Object.values(STATE_TOOLS));
+
+function stateToolPermissions(allowedTools) {
+  return Object.fromEntries(
+    ALL_STATE_TOOLS.map((name) => [name, allowedTools.includes(name) ? "allow" : "deny"]),
+  );
+}
+
+const SHEPHERD_STATE_TOOLS = [STATE_TOOLS.planWrite, STATE_TOOLS.planRead];
+const GOVERNOR_STATE_TOOLS = [STATE_TOOLS.planRead];
+const SHEEPDOG_STATE_TOOLS = [
+  STATE_TOOLS.planRead,
+  STATE_TOOLS.executionWrite,
+  STATE_TOOLS.executionRead,
+];
+
+const SHEPHERD_SPAWNABLE_AGENTS = ["grazer"];
+const GOVERNOR_SPAWNABLE_AGENTS = ["grazer", "sheepdog"];
+const SHEEPDOG_SPAWNABLE_AGENTS = ["grazer", "sheep", "shearer-low", "shearer-medium"];
+
+const SHEEPDOG_LIFECYCLE_ALLOWS = {
+  "git merge --ff-only*": "allow",
+  "git merge --no-ff --no-edit*": "allow",
+  "git merge --continue": "allow",
+  "git merge --abort": "allow",
+  "git merge --quit": "allow",
+  "git cherry-pick*": "allow",
+  "git cherry-pick --continue": "allow",
+  "git cherry-pick --skip": "allow",
+  "git cherry-pick --abort": "allow",
+  "git cherry-pick --quit": "allow",
+  "git commit*": "allow",
+};
+
+const SHEEPDOG_DENIALS = {
+  "git push*": "deny",
+  "git pull*": "deny",
+  "git fetch*": "deny",
+  "git remote*": "deny",
+  "git rebase*": "deny",
+  "git reset*": "deny",
+  "git revert*": "deny",
+  "git checkout*": "deny",
+  "git switch*": "deny",
+  "git stash*": "deny",
+  "git clean*": "deny",
+  "git worktree*": "deny",
+  "git branch -D*": "deny",
+  "git branch -d*": "deny",
+  "git commit --no-verify*": "deny",
+  "git commit * --no-verify*": "deny",
+  "git commit --amend*": "deny",
+  "git commit * --amend*": "deny",
+  "git merge *--no-verify*": "deny",
+};
+
+const SHEEP_DENIALS = {
+  "herdr*": "deny",
+  "gh*": "deny",
+  "npm publish*": "deny",
+  "git push*": "deny",
+  "git pull*": "deny",
+  "git fetch*": "deny",
+  "git remote*": "deny",
+  "git merge*": "deny",
+  "git cherry-pick*": "deny",
+  "git rebase*": "deny",
+  "git reset*": "deny",
+  "git revert*": "deny",
+  "git checkout*": "deny",
+  "git switch*": "deny",
+  "git stash*": "deny",
+  "git clean*": "deny",
+  "git worktree*": "deny",
+  "git tag*": "deny",
+  "git apply*": "deny",
+  "git am*": "deny",
+  "git branch -D*": "deny",
+  "git branch -d*": "deny",
+  "git commit --no-verify*": "deny",
+  "git commit *--no-verify*": "deny",
+  "git commit --amend*": "deny",
+  "git commit *--amend*": "deny",
+};
+
 function mergeRecord(base, override) {
   if (!base || typeof base !== "object" || Array.isArray(base)) return override ?? base;
   if (!override || typeof override !== "object" || Array.isArray(override)) return override ?? base;
@@ -80,29 +187,40 @@ export function mergeAgent(defaults, override) {
   return mergeRecord(defaults, override);
 }
 
+function spawnMatrix(agents) {
+  return Object.fromEntries(
+    agents.map((agent) => [`herdr agent start * --kind opencode --pane * -- --agent ${agent}`, "allow"]),
+  );
+}
+
 export function createAgents(options = {}) {
   const shepherdModel = options.shepherdModel;
   const workerModel = options.workerModel ?? "litellm/glm-5.3-flash";
+  const workerVariant = options.workerVariant;
+  const sheepdogModel = options.sheepdogModel ?? "litellm/glm-5.3-flash";
+  const sheepdogVariant = options.sheepdogVariant;
   const reviewerModel = options.reviewerModel ?? "litellm-responses/gpt-5.6-terra";
-  const shepherdBuildPermissions = options.shepherdBuildPermissions ?? {};
-  const shepherdBuildPrompt = appendPrompt(SHEPHERD_BUILD_PROMPT, options.shepherdBuildPromptAppend);
+  const shepherdPermissions = options.shepherdPermissions ?? {};
+  const shepherdPrompt = appendPrompt(SHEPHERD_PROMPT, options.shepherdPromptAppend);
 
   return {
-    "shepherd-plan": {
+    shepherd: {
       mode: "primary",
       ...(shepherdModel ? { model: shepherdModel } : {}),
-      description: "Researches and presents implementation-ready plans through sheep-plan workers without implementing them.",
-      prompt: SHEPHERD_PLAN_PROMPT,
+      description:
+        "Plans through grazer research and presents implementation-ready plans; never implements, integrates, or delivers.",
+      prompt: shepherdPrompt,
       permission: {
         grep: "allow",
         todowrite: "allow",
         edit: markdownOnly,
         apply_patch: markdownOnly,
         herdr_agent_response: "allow",
+        ...stateToolPermissions(SHEPHERD_STATE_TOOLS),
         bash: {
           "*": "deny",
           ...herdrInspection,
-          "herdr agent start * --kind opencode --pane * -- --agent sheep-plan": "allow",
+          ...spawnMatrix(SHEPHERD_SPAWNABLE_AGENTS),
           "git status*": "allow",
           "git diff*": "allow",
           "git log*": "allow",
@@ -114,44 +232,38 @@ export function createAgents(options = {}) {
           "git add *.md": "allow",
           "git add **/*.md": "allow",
           "git commit*": "allow",
-          "git push origin HEAD": "allow",
-          "git push -u origin HEAD": "allow",
-          "git push --set-upstream origin HEAD": "allow",
+          "git push*": "deny",
           "git commit --no-verify*": "deny",
           "git commit * --no-verify*": "deny",
-          "git push *main*": "deny",
-          "git push *master*": "deny",
-          "git push *:*": "deny",
-          "git push *--no-verify*": "deny",
-          "git push *--force*": "deny",
-          "git push *-f*": "deny",
-          "git push *--delete*": "deny",
+          "git commit --amend*": "deny",
+          "git commit * --amend*": "deny",
           "git branch -D*": "deny",
           "git branch -d*": "deny",
           "git worktree remove * --force*": "deny",
           ...separatorDenials,
         },
         task: "deny",
+        ...shepherdPermissions,
       },
     },
 
-    "shepherd-build": {
+    "shepherd-governor": {
       mode: "primary",
       ...(shepherdModel ? { model: shepherdModel } : {}),
-      description: "Executes approved plans through planning, implementation, and independent review workers.",
-      prompt: shepherdBuildPrompt,
+      description:
+        "Executes approved plans through sheepdog squads, verifies results, and owns final delivery: pushes, merges, PRs.",
+      prompt: SHEPHERD_GOVERNOR_PROMPT,
       permission: {
         grep: "allow",
+        todowrite: "allow",
         edit: markdownOnly,
         apply_patch: markdownOnly,
         herdr_agent_response: "allow",
+        ...stateToolPermissions(GOVERNOR_STATE_TOOLS),
         bash: {
           "*": "deny",
           ...herdrInspection,
-          "herdr agent start * --kind opencode --pane * -- --agent sheep-plan": "allow",
-          "herdr agent start * --kind opencode --pane * -- --agent sheep-build": "allow",
-          "herdr agent start * --kind opencode --pane * -- --agent shearer-review-low": "allow",
-          "herdr agent start * --kind opencode --pane * -- --agent shearer-review-medium": "allow",
+          ...spawnMatrix(GOVERNOR_SPAWNABLE_AGENTS),
           "git status*": "allow",
           "git diff*": "allow",
           "git log*": "allow",
@@ -159,7 +271,7 @@ export function createAgents(options = {}) {
           "git branch*": "allow",
           "git rev-parse*": "allow",
           "git merge-base*": "allow",
-          "git worktree*": "allow",
+          "git worktree list*": "allow",
           "git add *.md": "allow",
           "git add **/*.md": "allow",
           "git commit*": "allow",
@@ -174,25 +286,64 @@ export function createAgents(options = {}) {
           "git push *--delete*": "deny",
           "git push *--no-verify*": "deny",
           "git commit *--no-verify*": "deny",
+          "git commit --amend*": "deny",
+          "git commit *--amend*": "deny",
           "git merge *--no-verify*": "deny",
           "git branch -D*": "deny",
           "git branch -d*": "deny",
+          "git worktree add*": "deny",
+          "git worktree remove*": "deny",
+          "git worktree move*": "deny",
+          "git worktree prune*": "deny",
           "git worktree remove * --force*": "deny",
+          "herdr worktree create*": "deny",
+          "herdr worktree open*": "deny",
+          "herdr worktree remove*": "deny",
           "gh pr create*": "allow",
           "gh pr view*": "allow",
           "gh pr checks*": "allow",
           ...separatorDenials,
         },
         task: "deny",
-        ...shepherdBuildPermissions,
       },
     },
 
-    "sheep-plan": {
+    sheepdog: {
+      mode: "primary",
+      model: sheepdogModel,
+      ...(sheepdogVariant ? { variant: sheepdogVariant } : {}),
+      description:
+        "Leads execution squads of grazer, sheep, and shearers, prepares worker branches and worktrees, owns validation, review tiers, retries, and conflict recovery, and performs clean local integration with merge and cherry-pick lifecycle commands only.",
+      prompt: SHEEPDOG_PROMPT,
+      permission: {
+        read: "allow",
+        glob: "allow",
+        grep: "allow",
+        list: "allow",
+        todowrite: "allow",
+        edit: "deny",
+        apply_patch: "deny",
+        herdr_agent_response: "allow",
+        ...stateToolPermissions(SHEEPDOG_STATE_TOOLS),
+        bash: {
+          "*": "deny",
+          ...safeGitInspection,
+          ...herdrInspection,
+          ...spawnMatrix(SHEEPDOG_SPAWNABLE_AGENTS),
+          ...SHEEPDOG_LIFECYCLE_ALLOWS,
+          ...SHEEPDOG_DENIALS,
+          ...separatorDenials,
+        },
+        task: "deny",
+      },
+    },
+
+    grazer: {
       mode: "primary",
       model: workerModel,
-      description: "Performs read-only repository research for a shepherd.",
-      prompt: SHEEP_PLAN_PROMPT,
+      ...(workerVariant ? { variant: workerVariant } : {}),
+      description: "Performs read-only repository research for the shepherd, shepherd-governor, or sheepdog.",
+      prompt: GRAZER_PROMPT,
       permission: {
         read: "allow",
         glob: "allow",
@@ -202,50 +353,41 @@ export function createAgents(options = {}) {
         edit: "deny",
         apply_patch: "deny",
         herdr_agent_response: "deny",
+        ...stateToolPermissions([]),
         bash: { "*": "deny", ...safeGitInspection, ...separatorDenials },
         task: "deny",
       },
     },
 
-    "sheep-build": {
+    sheep: {
       mode: "primary",
       model: workerModel,
-      description: "Implements a bounded task, verifies it, and hands a local commit to shepherd-build.",
-      prompt: SHEEP_BUILD_PROMPT,
+      ...(workerVariant ? { variant: workerVariant } : {}),
+      description:
+        "Implements a bounded task, verifies it, and hands a local commit to sheepdog.",
+      prompt: SHEEP_PROMPT,
       permission: {
         grep: "allow",
         herdr_agent_response: "deny",
+        ...stateToolPermissions([]),
         bash: {
           "*": "allow",
-          "git push*": "deny",
-          "git merge*": "deny",
-          "git pull*": "deny",
-          "git branch -D*": "deny",
-          "git branch -d*": "deny",
-          "git rebase*": "deny",
-          "git reset*": "deny",
-          "git commit *--no-verify*": "deny",
-          "git commit --no-verify*": "deny",
-          "git *;*": "deny",
-          "git *&&*": "deny",
-          "git *||*": "deny",
-          "git *|*": "deny",
-          "git *>*": "deny",
-          "git *<*": "deny",
+          ...SHEEP_DENIALS,
+          ...separatorDenials,
         },
         task: "deny",
       },
     },
 
-    "shearer-review-low": reviewerAgent(reviewerModel, "low"),
-    "shearer-review-medium": reviewerAgent(reviewerModel, "medium"),
+    "shearer-low": reviewerAgent(reviewerModel, "low"),
+    "shearer-medium": reviewerAgent(reviewerModel, "medium"),
   };
 }
 
 function appendPrompt(prompt, addition) {
   if (addition === undefined || addition === "") return prompt;
   if (typeof addition !== "string") {
-    throw new TypeError("shepherdBuildPromptAppend must be a string.");
+    throw new TypeError("shepherdPromptAppend must be a string.");
   }
   return `${prompt.trimEnd()}\n\n${addition.trim()}`;
 }
@@ -266,6 +408,7 @@ function reviewerAgent(model, variant) {
       apply_patch: "deny",
       todowrite: "deny",
       herdr_agent_response: "deny",
+      ...stateToolPermissions([]),
       bash: { "*": "deny", ...safeGitInspection, ...separatorDenials },
       task: "deny",
     },

package/src/index.js

@@ -1,20 +1,112 @@
-import { createAgents, mergeAgent } from "./agents.js";
+import { tool } from "@opencode-ai/plugin";
+
+import { createAgents, mergeAgent, STATE_TOOL_ACCESS, STATE_TOOLS } from "./agents.js";
 import { createResponseTool } from "./response.js";
+import { createStateService } from "./state.js";
 
 const SESSION_MODES = new Map();
 
 function modeForAgent(agent) {
-  if (agent === "shepherd-plan") return "plan";
-  if (agent === "shepherd-build") return "build";
-  if (agent === "shearer-review-low" || agent === "shearer-review-medium") return "review";
-  if (agent === "sheep-plan") return "sheep-plan";
-  if (agent === "sheep-build") return "sheep-build";
+  if (agent === "shepherd") return "shepherd";
+  if (agent === "shepherd-governor") return "governor";
+  if (agent === "sheepdog") return "sheepdog";
+  if (agent === "grazer") return "grazer";
+  if (agent === "sheep") return "sheep";
+  if (agent === "shearer-low" || agent === "shearer-medium") return "shearer";
   return "none";
 }
 
+function stateError(code, message, retryable = false) {
+  return { ok: false, error: { code, message, retryable } };
+}
+
+// Exposes the constrained orchestration state API (src/state.js) as plugin
+// tools. Enforcement mirrors STATE_TOOL_ACCESS in src/agents.js: the planning
+// shepherd writes and reads plan artifacts; shepherd-governor and sheepdog
+// read the authoritative plan; sheepdog writes and reads execution artifacts.
+// Artifacts are durable Markdown files under the repository's shared Git
+// common directory, so linked worktrees share state while separate clones
+// never do. The state service invokes only read-only `git rev-parse`; it
+// never writes arbitrary Git metadata.
+export function createStateTools(stateOptions = {}) {
+  const state = createStateService(stateOptions);
+
+  const definitions = [
+    {
+      name: STATE_TOOLS.planWrite,
+      description:
+        "Durably store a plan Markdown artifact under the repository's shared Git common directory, keyed by plan ID. Planning shepherd only.",
+      write: true,
+      run: (args) => state.writePlan(args),
+    },
+    {
+      name: STATE_TOOLS.planRead,
+      description:
+        "Read a stored plan Markdown artifact by plan ID. Shepherd, shepherd-governor, and sheepdog only.",
+      write: false,
+      run: (args) => state.readPlan(args.planId),
+    },
+    {
+      name: STATE_TOOLS.executionWrite,
+      description:
+        "Durably store an execution Markdown artifact for a plan under the repository's shared Git common directory, keyed by plan ID. Sheepdog only.",
+      write: true,
+      run: (args) => state.writeExecution(args),
+    },
+    {
+      name: STATE_TOOLS.executionRead,
+      description:
+        "Read a stored execution Markdown artifact by plan ID. Sheepdog only.",
+      write: false,
+      run: (args) => state.readExecution(args.planId),
+    },
+  ];
+
+  const tools = {};
+  for (const definition of definitions) {
+    tools[definition.name] = tool({
+      description: definition.description,
+      args: {
+        planId: tool.schema
+          .string()
+          .describe("Plan ID keying the artifact; 1-64 characters of letters, digits, dot, underscore, or hyphen."),
+        ...(definition.write
+          ? {
+              markdown: tool.schema
+                .string()
+                .min(1)
+                .describe("Complete Markdown body to store as the artifact content."),
+            }
+          : {}),
+      },
+      async execute(args, context) {
+        const allowed = STATE_TOOL_ACCESS.get(definition.name);
+        if (!allowed?.has(context?.agent)) {
+          return JSON.stringify(
+            stateError(
+              "UNAUTHORIZED_AGENT",
+              `Agent ${context?.agent ?? "unknown"} may not use ${definition.name}.`,
+            ),
+          );
+        }
+        const result = await definition.run(args);
+        context.metadata({
+          title: result.ok ? `${definition.name}: ${args.planId}` : `${definition.name}: ${result.error.code}`,
+          metadata: result.ok
+            ? { planId: args.planId, path: result.artifact.path }
+            : { error: result.error.code },
+        });
+        return JSON.stringify(result);
+      },
+    });
+  }
+  return tools;
+}
+
 export const HerdrOrchestrationPlugin = async (_input, options = {}) => ({
   tool: {
     herdr_agent_response: createResponseTool(options.response),
+    ...createStateTools(options.state),
   },
   config(config) {
     config.agent ??= {};
@@ -43,4 +135,4 @@ export const HerdrOrchestrationPlugin = async (_input, options = {}) => ({
 });
 
 export default HerdrOrchestrationPlugin;
-export { createAgents, modeForAgent };
+export { createAgents, mergeAgent, modeForAgent, STATE_TOOL_ACCESS, STATE_TOOLS };