opencode-herdr-orchestration 0.1.0 → 0.1.1

package/README.md

@@ -6,6 +6,43 @@ This package registers the agents, provides complete structured worker-response
 
 Requires Node.js 22.22.2 or newer when running the package CLI or tests.
 
+## Installation
+
+Add the published package to the global OpenCode configuration at `~/.config/opencode/opencode.json` or `~/.config/opencode/opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-herdr-orchestration"]
+}
+```
+
+If `plugin` already contains entries, append `"opencode-herdr-orchestration"` instead of replacing them. OpenCode installs npm plugins automatically when it starts.
+
+Optionally install the shared Git push policy for all current and future repositories:
+
+```bash
+npx opencode-herdr-orchestration install-hooks
+```
+
+Then quit and restart OpenCode intentionally. Agent and plugin configuration is loaded only at process startup; installing the package does not restart or modify running OpenCode sessions.
+
+Confirm the installed agents:
+
+```bash
+opencode agent list
+```
+
+The expected package agents are `shepherd-plan`, `shepherd-build`, `sheep-plan`, `sheep-build`, `shearer-review-low`, and `shearer-review-medium`.
+
+### Migrating from standalone agent files
+
+Agent definitions are merged by agent name. A local file with the same name as a package agent overrides the corresponding package fields, including its prompt and permissions.
+
+Before switching completely, archive or remove standalone files named `sheep-plan.md`, `sheep-build.md`, `shepherd-plan.md`, or `shepherd-build.md` after any existing OpenCode processes that depend on them have ended. Older misspelled files such as `sheperd-plan.md` and `sheperd-build.md` do not override the correctly named package agents; they load as additional legacy agents until removed.
+
+Do not remove agent files merely to affect an already-running process. Complete or stop that process first, update the files, then start a new OpenCode process and verify the effective agent list.
+
 ## Architecture
 
 ```text
@@ -30,7 +67,7 @@ shepherd-build
 
 The build shepherd chooses low review for localized mechanical changes with strong deterministic coverage. It chooses medium review for security, architecture, migrations, public APIs, deployment, concurrency, cross-component work, weak coverage, or material uncertainty.
 
-## Install the plugin
+## Plugin configuration
 
 During local development, reference the source directly in the global OpenCode configuration:
 
@@ -43,7 +80,7 @@ During local development, reference the source directly in the global OpenCode c
 }
 ```
 
-After publishing, use the package name instead:
+For the published package, use:
 
 ```jsonc
 {
@@ -67,9 +104,29 @@ Plugin tuple options can override model defaults:
 }
 ```
 
+Machine-specific `shepherd-build` permissions and instructions can also be added declaratively without a local JavaScript wrapper:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-herdr-orchestration",
+      {
+        "shepherdBuildPermissions": {
+          "private_deployment_status": "allow"
+        },
+        "shepherdBuildPromptAppend": "Use private deployment tools according to local policy."
+      }
+    ]
+  ]
+}
+```
+
+`shepherdBuildPermissions` is merged over the package's `shepherd-build` permissions. `shepherdBuildPromptAppend` is appended as a separate final paragraph. Keep secrets out of plugin options because configuration may be displayed by diagnostics.
+
 Local agent definitions with the same names are merged over plugin defaults. This permits deliberate user customization without losing unspecified plugin permissions or prompts.
 
-During migration, existing files such as `~/.config/opencode/agents/shepherd-build.md` continue to override the plugin prompt. Keep them while existing sessions depend on them. After those sessions end and the plugin has been validated, archive or remove the duplicate standalone definitions so the package becomes the single source of truth. Do not remove files merely to activate the plugin in already-running OpenCode processes; configuration is loaded at process startup.
+Machine- or organization-specific MCP tools, deployment rules, and private service instructions should stay in a local `shepherd-build` override rather than this public package. Add only the private permissions and prompt additions required by your environment; unspecified package defaults remain intact through deep merging.
 
 OpenCode loads plugins and agent definitions at startup. Restart OpenCode when intentionally enabling or updating the plugin. The installer never stops or restarts an OpenCode process.
 

package/package.json

@@ -1,46 +1,49 @@
-{
-  "name": "opencode-herdr-orchestration",
-  "version": "0.1.0",
-  "description": "Capability-separated Herdr orchestration agents for OpenCode",
-  "author": "CodingJinxx",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/CodingJinxx/opencode-herdr-orchestration.git"
-  },
-  "homepage": "https://github.com/CodingJinxx/opencode-herdr-orchestration#readme",
-  "bugs": {
-    "url": "https://github.com/CodingJinxx/opencode-herdr-orchestration/issues"
-  },
-  "type": "module",
-  "exports": "./src/index.js",
-  "bin": {
-    "opencode-herdr-orchestration": "bin/orchestration.js"
-  },
-  "files": [
-    "bin",
-    "hooks",
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --test",
-    "check": "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"
-  },
-  "engines": {
-    "node": ">=22.22.2"
-  },
-  "peerDependencies": {
-    "@opencode-ai/plugin": ">=1.3.0 <2"
-  },
-  "devDependencies": {
-    "@opencode-ai/plugin": "1.3.14"
-  },
-  "keywords": [
-    "opencode",
-    "herdr",
-    "orchestration",
-    "agents"
-  ],
-  "license": "MIT"
-}
+{
+  "name": "opencode-herdr-orchestration",
+  "version": "0.1.1",
+  "description": "Capability-separated Herdr orchestration agents for OpenCode",
+  "author": "CodingJinxx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CodingJinxx/opencode-herdr-orchestration.git"
+  },
+  "homepage": "https://github.com/CodingJinxx/opencode-herdr-orchestration#readme",
+  "bugs": {
+    "url": "https://github.com/CodingJinxx/opencode-herdr-orchestration/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/plugin.js",
+    "./core": "./src/index.js"
+  },
+  "bin": {
+    "opencode-herdr-orchestration": "bin/orchestration.js"
+  },
+  "files": [
+    "bin",
+    "hooks",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "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"
+  },
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.3.0 <2"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.3.14"
+  },
+  "keywords": [
+    "opencode",
+    "herdr",
+    "orchestration",
+    "agents"
+  ],
+  "license": "MIT"
+}

package/src/agents.js

@@ -77,6 +77,8 @@ export function mergeAgent(defaults, override) {
 export function createAgents(options = {}) {
   const workerModel = options.workerModel ?? "litellm/glm-5.3-flash";
   const reviewerModel = options.reviewerModel ?? "litellm-responses/gpt-5.6-terra";
+  const shepherdBuildPermissions = options.shepherdBuildPermissions ?? {};
+  const shepherdBuildPrompt = appendPrompt(SHEPHERD_BUILD_PROMPT, options.shepherdBuildPromptAppend);
 
   return {
     "shepherd-plan": {
@@ -128,17 +130,12 @@ export function createAgents(options = {}) {
     "shepherd-build": {
       mode: "primary",
       description: "Executes approved plans through planning, implementation, and independent review workers.",
-      prompt: SHEPHERD_BUILD_PROMPT,
+      prompt: shepherdBuildPrompt,
       permission: {
         grep: "allow",
         edit: markdownOnly,
         apply_patch: markdownOnly,
         herdr_agent_response: "allow",
-        "ia-forge_deployment_status": "allow",
-        "ia-forge_file_logs": "allow",
-        "ia-forge_run_preset": "allow",
-        "ia-forge_service_control": "allow",
-        "ia-forge_service_logs": "allow",
         bash: {
           "*": "deny",
           ...herdrInspection,
@@ -178,6 +175,7 @@ export function createAgents(options = {}) {
           ...separatorDenials,
         },
         task: "deny",
+        ...shepherdBuildPermissions,
       },
     },
 
@@ -235,6 +233,14 @@ export function createAgents(options = {}) {
   };
 }
 
+function appendPrompt(prompt, addition) {
+  if (addition === undefined || addition === "") return prompt;
+  if (typeof addition !== "string") {
+    throw new TypeError("shepherdBuildPromptAppend must be a string.");
+  }
+  return `${prompt.trimEnd()}\n\n${addition.trim()}`;
+}
+
 function reviewerAgent(model, variant) {
   return {
     mode: "primary",

package/src/plugin.js

@@ -0,0 +1 @@
+export { HerdrOrchestrationPlugin as server } from "./index.js";

package/src/prompts.js

@@ -1,7 +1,7 @@
 export const SHEPHERD_PLAN_PROMPT = String.raw`
 You are shepherd-plan, a planning orchestrator. Research the user's goal through repository evidence and sheep-plan workers, then present an implementation-ready plan. Planning may mutate planning infrastructure and Markdown planning artifacts, but never product implementation.
 
-Before using Herdr, verify HERDR_ENV=1. If absent, explain that orchestration requires a Herdr-managed pane and stop. Inspect repository instructions, status, branches, worktrees, HEAD, and relevant history. Preserve unrelated changes. Use todos for substantial planning.
+Before using Herdr, verify HERDR_ENV=1. If absent, explain that orchestration requires a Herdr-managed pane and stop. Learn the installed command syntax with herdr --help and herdr agent; the installed CLI is authoritative. Inspect repository instructions, status, branches, worktrees, HEAD, and relevant history. Preserve unrelated changes. Use todos for substantial planning.
 
 You may write only Markdown plans, research notes, task briefs, and handoffs. You may commit intended Markdown artifacts and push only the current attached non-protected branch using an approved HEAD push command. Immediately before pushing, inspect the current branch and stop on main, master, detached HEAD, or any repository-defined protected branch. Never merge, deploy, implement, or spawn an implementation-capable agent.
 
@@ -11,9 +11,13 @@ herdr agent start <name> --kind opencode --pane <pane-id> -- --agent sheep-plan
 
 Never pass another agent, model, --auto, or extra OpenCode argument. Use send-keys only to interrupt a genuinely stuck worker with Ctrl+C after inspection. Never type commands, answer arbitrary prompts, or use a worker terminal as a capability bypass.
 
+Worker names must be unique and satisfy Herdr's naming rules. Assign bounded work with herdr agent prompt <name> "..." --wait --timeout <milliseconds>. If additional research is needed, prompt the same worker again or create another non-overlapping sheep-plan assignment.
+
 After a worker settles, use herdr_agent_response as the authoritative result channel. Call it first with the worker name, then call it with each returned cursor until complete is true. Do not summarize, decide, or act on the worker result until every page has been read in order. Use herdr agent read only for live status, blocked dialogs, and stuck-worker diagnosis; terminal snapshots are never the completed worker response. If retrieval says the worker is not settled, wait and retry. If an interrupted worker has no completed response, inspect its actual partial state and redesign the task.
 
-Assume workers may fail on very large one-shot writes. Identify large-file work and plan generators or coherent bounded stages with valid checkpoints. If a worker later fails on a large write, the shepherd owns recovery: inspect partial state, preserve valid work, and redesign the task rather than repeating the same oversized prompt.
+If a worker is blocked, inspect it with herdr agent get and herdr agent read; do not answer approvals or questions without applying the user's safety constraints. Treat unknown as inconclusive, not complete. Synthesize worker findings instead of forwarding raw reports. Resolve contradictions when repository evidence permits and surface unresolved product choices to the user.
+
+Assume workers may fail on very large one-shot writes. Identify large-file work and plan generators or coherent bounded stages with valid checkpoints. If a worker later fails on a large write, the shepherd owns recovery: inspect partial state, preserve valid work, and redesign the task rather than repeating the same oversized prompt. Before committing a plan, inspect the staged diff and confirm it contains only intended Markdown planning artifacts.
 
 Every final plan must begin with:
 
@@ -27,7 +31,7 @@ Include scope, ordered tasks, likely files and symbols, dependencies, delegation
 export const SHEPHERD_BUILD_PROMPT = String.raw`
 You are shepherd-build, a delivery orchestrator. Selecting this agent after shepherd-plan approves the latest presented plan. You coordinate; every non-Markdown implementation change must come from a sheep-build commit. You may directly write only Markdown task briefs, handoffs, and review notes.
 
-Before using Herdr, verify HERDR_ENV=1. Inspect repository instructions, status, branches, worktrees, current HEAD, and history. Preserve unrelated changes and never force-push, bypass hooks, or rewrite history.
+Before using Herdr, verify HERDR_ENV=1. If absent, explain that orchestration requires a Herdr-managed pane and stop. Learn the installed command syntax with herdr --help and herdr agent; the installed CLI is authoritative. Inspect repository instructions, status, branches, worktrees, current HEAD, and history. Preserve unrelated changes and never force-push, bypass hooks, or rewrite history.
 
 At startup identify and report:
 
@@ -39,6 +43,8 @@ Inspect divergence from the approved base. Continue through mechanical drift, re
 
 Delegate using structured contracts containing, where relevant: task_id, plan_id, base_commit, objective, owned_paths, forbidden_paths, dependencies, acceptance_criteria, verification, escalate_if, and deliver. Resolve global ambiguity before delegating. Workers must escalate rather than guess when evidence contradicts the task, scope expands, public APIs or migrations change unexpectedly, a product or architecture decision is required, permissions block work, or repeated attempts fail.
 
+Parallelize only tasks that will not conflict. When implementation tasks can run concurrently, give each sheep-build a dedicated branch and worktree with non-overlapping ownership and explicit integration order.
+
 Spawn only these configured workers with no extra OpenCode arguments:
 
 herdr agent start <name> --kind opencode --pane <pane-id> -- --agent sheep-plan
@@ -48,19 +54,22 @@ herdr agent start <name> --kind opencode --pane <pane-id> -- --agent shearer-rev
 
 Use sheep-plan for research and sheep-build for implementation. Choose Terra low review for localized, mechanical changes with strong deterministic coverage. Choose Terra medium for security, architecture, migrations, public APIs, deployment, concurrency, cross-component work, weak coverage, or material uncertainty.
 
+Worker names must be unique and satisfy Herdr's naming rules. Assign work with herdr agent prompt <name> "..." --wait --timeout <milliseconds>.
+
 Use send-keys only to interrupt a genuinely stuck worker with Ctrl+C after inspection. Never type implementation commands, answer arbitrary prompts, or use a worker terminal as a capability bypass. After interruption, inspect any completed response and actual diff, preserve valid partial work, and issue a bounded recovery task.
 
 After any worker or shearer settles, use herdr_agent_response as the authoritative result channel. Call it first with the agent name, then call it with each returned cursor until complete is true. Do not summarize, review, integrate, or act on the result until every page has been read in order. Use herdr agent read only for live status, blocked dialogs, and stuck-worker diagnosis; terminal snapshots are never a completed response. If retrieval says the agent is not settled, wait and retry. If an interrupted worker has no completed response, inspect its actual partial state and redesign the task.
 
+If an agent is blocked, inspect it with herdr agent get and herdr agent read; do not answer approvals or questions without applying the user's safety constraints. Treat unknown as inconclusive, not complete.
+
 Assume workers may fail on very large one-shot writes. Prefer repository-native generators or coherent bounded stages with valid checkpoints. If a write fails, inspect partial state and redesign the prompt; never discard correct work, reduce required functionality, or repeat the same oversized prompt blindly.
 
 Require sheep-build to return a local commit, files changed, checks and results, assumptions, risks, and blockers. Sheep never pushes, merges, opens PRs, or delivers. Run or delegate deterministic repository-native checks before semantic review. Give the shearer fresh bounded context: user goal, approved plan, task contract, base and implementation commits, diff, and verification results, not the worker conversation.
 
 Review verdicts are PASS, REWORK, or ESCALATE. PASS permits integration after your own checks. REWORK returns concrete findings to the responsible sheep-build and requires review of the correction. ESCALATE returns to you for research, re-planning, or user judgment. After two failed semantic review cycles for the same task, escalate rather than loop indefinitely.
 
-Integrate only reviewed committed work. Perform repository-level verification after integration. Own push, PR, merge, and deployment according to repository instructions and user scope. Use gh only for GitHub repositories and only when PR delivery is requested. Finish with plan ID, assignments, commits, checks, review verdicts, integration and delivery result, deviations, and unresolved risks.
+Integrate only reviewed committed work. Inspect every worker commit for scope and unintended changes before integration, and return defects to the responsible sheep-build rather than editing implementation yourself. Prefer fast-forward or ordinary non-interactive merges. Delegate non-Markdown conflict resolution to sheep-build. Perform repository-level verification after integration. Do not merge or push while tests fail, unintended changes remain, or a deployment gate is failing. Before pushing, confirm the current branch and remote target. Merge into a protected branch only when requested or authorized by the user's end-to-end delivery scope and all acceptance criteria and repository gates pass. Own push, PR, merge, and deployment according to repository instructions and user scope. Use gh only for GitHub repositories and only when PR delivery is requested. Finish with plan ID, assignments, commits, checks, review verdicts, integration and delivery result, deviations, and unresolved risks.
 
-When ia-forge tools are available, use them as the source of truth for managed deployments and services. After pushing an infrastructure change, poll deployment status until the attempt finishes; success requires a successful attempt at the pushed commit. On failure inspect deployment service logs, delegate the correction to sheep-build, and repeat verification and review before another delivery attempt.
 `.trim();
 
 export const SHEEP_PLAN_PROMPT = String.raw`