goatcode-sh 0.0.1 → 0.1.2

package/package.json

@@ -1,9 +1,38 @@
 {
   "name": "goatcode-sh",
-  "version": "0.0.1",
-  "description": "Enterprise-grade OpenCode plugin with micro-plugin architecture and multi-agent orchestration",
-  "main": "index.js",
+  "version": "0.1.2",
+  "description": "Enterprise-grade OpenCode plugin with micro-plugin architecture, multi-agent orchestration, and professional naming",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "goatcode": "./src/cli/index.ts"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target bun --format esm --external zod --external @opencode-ai/plugin && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "find src -name '*.test.ts' -print0 | xargs -0 bun test",
+    "test:integration": "find src -name '*.integration.test.ts' -print0 | xargs -0 bun test",
+    "test:coverage": "bun test --coverage src",
+    "lint": "oxlint src --deny-warnings",
+    "fmt": "oxfmt --write 'src/**/*.ts'",
+    "fmt:check": "oxfmt --check 'src/**/*.ts'",
+    "test:eval": "cd eval && npx promptfoo eval -c promptfooconfig.yaml",
+    "test:ablation": "cd eval && npx promptfoo eval -c ablation-config.yaml",
+    "clean": "rm -rf dist",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:major": "npm version major && git push --follow-tags"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
   "keywords": [
     "opencode",
     "plugin",
@@ -11,14 +40,24 @@
     "orchestration",
     "ai"
   ],
-  "author": "ryanskidmore",
+  "author": "",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ryanskidmore/goatcode.git"
+    "url": "https://github.com/ryanskidmore/goatcode"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.2.24",
+    "@opencode-ai/sdk": "^1.2.24",
+    "zod": "^4.1.8",
+    "commander": "^14.0.2",
+    "picocolors": "^1.1.1"
   },
-  "homepage": "https://github.com/ryanskidmore/goatcode#readme",
-  "bugs": {
-    "url": "https://github.com/ryanskidmore/goatcode/issues"
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
+    "promptfoo": "^0.121.3",
+    "typescript": "^5.7.3"
   }
 }

package/src/agents/advisor/config.ts

@@ -0,0 +1,6 @@
+import type { AgentMode } from "../../types/agent";
+import { DEFAULT_TEMPERATURE } from "../../config/defaults";
+
+export const ADVISOR_TEMPERATURE = DEFAULT_TEMPERATURE;
+export const ADVISOR_MODE: AgentMode = "subagent";
+export const ADVISOR_FALLBACK_MODELS = ["gpt-5.4", "claude-opus-4-6"];

package/src/agents/advisor/index.ts

@@ -0,0 +1,2 @@
+export { advisorPlugin } from "./plugin";
+export * from "./config";

package/src/agents/advisor/plugin.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "bun:test";
+import { advisorPlugin } from "./plugin";
+import { buildToolsMap } from "../tool-restrictions";
+
+describe("advisorPlugin", () => {
+  describe("#given the advisor plugin", () => {
+    describe("#when inspecting plugin metadata", () => {
+      it("#then has the correct plugin name", () => {
+        expect(advisorPlugin.name).toBe("advisor");
+      });
+    });
+
+    describe("#when inspecting the agent config", () => {
+      it("#then mode is 'subagent'", () => {
+        const agent = advisorPlugin.agents!.advisor;
+        expect(agent.mode).toBe("subagent");
+      });
+
+      it("#then has a temperature and non-empty prompt", () => {
+        const agent = advisorPlugin.agents!.advisor;
+        expect(typeof agent.temperature).toBe("number");
+        expect(typeof agent.prompt).toBe("string");
+        expect(agent.prompt!.length).toBeGreaterThan(0);
+      });
+    });
+
+    describe("#when inspecting tool restrictions", () => {
+      it("#then buildToolsMap('advisor') denies write, edit, bash, and task tools", () => {
+        const tools = buildToolsMap("advisor");
+        expect(tools).toBeDefined();
+        expect(tools!["write"]).toBe(false);
+        expect(tools!["edit"]).toBe(false);
+        expect(tools!["bash"]).toBe(false);
+        expect(tools!["interactive_bash"]).toBe(false);
+        expect(tools!["delegate_task"]).toBe(false);
+        expect(tools!["task_create"]).toBe(false);
+        expect(tools!["task_update"]).toBe(false);
+      });
+
+      it("#then the agent config includes the tools map", () => {
+        const agent = advisorPlugin.agents!.advisor;
+        expect(agent.tools).toBeDefined();
+        expect(agent.tools!["write"]).toBe(false);
+        expect(agent.tools!["edit"]).toBe(false);
+      });
+    });
+  });
+});

package/src/agents/advisor/plugin.ts

@@ -0,0 +1,17 @@
+import { definePlugin } from "../../plugin-api";
+import { ADVISOR_TEMPERATURE, ADVISOR_MODE } from "./config";
+import { ADVISOR_PROMPT } from "./prompt";
+import { buildToolsMap } from "../tool-restrictions";
+
+export const advisorPlugin = definePlugin({
+  name: "advisor",
+  version: "0.1.0",
+  agents: {
+    advisor: {
+      temperature: ADVISOR_TEMPERATURE,
+      mode: ADVISOR_MODE,
+      prompt: ADVISOR_PROMPT,
+      tools: buildToolsMap("advisor"),
+    },
+  },
+});

package/src/agents/advisor/prompt-meta.ts

@@ -0,0 +1,14 @@
+import type { PromptMeta } from "../prompt-meta";
+
+export const ADVISOR_PROMPT_META: PromptMeta = {
+  version: "1.0.0",
+  date: "2025-03-28",
+  summary: "Provides architecture and debugging guidance in read-only mode.",
+  changelog: [
+    {
+      version: "1.0.0",
+      date: "2025-03-28",
+      description: "Production-grade prompt with structured sections and quality gates",
+    },
+  ],
+};

package/src/agents/advisor/prompt.ts

@@ -0,0 +1,93 @@
+export const ADVISOR_PROMPT = `# Role
+You are GoatCode's read-only senior technical advisor.
+You provide high-signal recommendations on architecture, debugging, trade-offs, and implementation direction.
+
+You never modify files.
+
+# Decision Philosophy: Pragmatic Minimalism
+Default to the simplest solution that satisfies the real requirement.
+
+## Principles
+- Favor proven local patterns over novel architecture.
+- Prefer reducing complexity over adding machinery.
+- Recommend one primary path; mention alternatives only when trade-offs are material.
+- Optimize for maintainability and operability, not theoretical elegance.
+
+# Read-First Requirement
+Do not conclude before understanding relevant code.
+
+## Evidence Rules
+- Anchor claims to concrete code observations.
+- If uncertain, state uncertainty explicitly.
+- Never fabricate file paths, APIs, or behavior.
+- Distinguish facts from hypotheses.
+
+# Debugging Guidance Model
+When diagnosing problems:
+- Trace from symptom to origin.
+- Identify root cause before proposing fixes.
+- Provide defense-in-depth recommendations when bug class is safety-critical.
+- Avoid shotgun advice lists with no prioritization.
+
+# Scope Discipline
+- Answer what was asked.
+- Do not expand scope with unrelated improvements.
+- Optional future ideas are allowed only as a short clearly-labeled section.
+
+# Effort Estimation (Mandatory)
+Label each primary recommendation:
+- **Quick**: < 1 hour
+- **Short**: 1-4 hours
+- **Medium**: 1-2 days
+- **Large**: 3+ days
+
+Include effort estimate with assumptions.
+
+# Response Structure (Strict)
+
+## 1. Bottom Line
+2-3 sentences, direct recommendation.
+
+## 2. Why
+Key evidence and trade-off rationale.
+
+## 3. Action Plan
+Numbered implementation steps, concrete and executable.
+
+## 4. Effort
+Quick/Short/Medium/Large with short justification.
+
+## 5. Risks / Watch-outs
+Only material risks and mitigations.
+
+## 6. Optional Future Considerations (Optional)
+At most 2 bullets, only if clearly useful.
+
+# Response Quality Bar
+- Concise and actionable.
+- No generic textbook explanations unless requested.
+- No redundant restatement of user input.
+- No performative certainty.
+
+# Anti-Patterns to Avoid
+- Recommending broad rewrites for local problems.
+- Suggesting new dependencies without necessity.
+- Mixing multiple conflicting strategies.
+- Advice that cannot be executed from current context.
+- Premature optimization not tied to requirements.
+
+# Tool Usage Guidance
+- Read/search tools are allowed for evidence gathering.
+- Use parallel reads when independent.
+- Prefer repository evidence over external speculation.
+
+# Hard Constraints
+- Read-only: NEVER write, edit, or apply patches.
+- Never claim "fixed"; you advise, executors implement.
+- Never recommend unsafe shortcuts like type suppression as solution.
+- Never commit/push or imply version-control operations.
+
+# Final Contract
+Deliver a recommendation the caller can execute immediately.
+If ambiguity blocks a safe recommendation, ask the smallest set of clarifying questions needed.
+`;

package/src/agents/agent-builder.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "bun:test";
+import { buildAgent } from "./agent-builder";
+import type { AgentFactory } from "../types/agent";
+
+describe("buildAgent", () => {
+  describe("#given a factory config with category defaults and user overrides", () => {
+    describe("#when buildAgent is called", () => {
+      it("#then user overrides win over base and category values", () => {
+        const source = Object.assign(
+          (model: string) => ({
+            model,
+            temperature: 0.1,
+            top_p: 0.2,
+            prompt: "base prompt",
+            tools: { read: true, write: true },
+          }),
+          { mode: "all" as const },
+        ) satisfies AgentFactory;
+
+        const result = buildAgent(
+          source,
+          "openai/gpt-5.3-codex",
+          {
+            model: "anthropic/claude-sonnet-4-6",
+            prompt_append: "category append",
+          },
+          {
+            model: "openai/gpt-5.4",
+            temperature: 0.7,
+            top_p: 0.9,
+            prompt_append: "override append",
+            denied_tools: ["write", "edit"],
+          },
+        );
+
+        expect(result.model).toBe("openai/gpt-5.4");
+        expect(result.temperature).toBe(0.7);
+        expect(result.top_p).toBe(0.9);
+        expect(result.prompt).toBe("base prompt\n\ncategory append\n\noverride append");
+        expect(result.tools).toEqual({
+          read: true,
+          write: false,
+          edit: false,
+        });
+      });
+    });
+  });
+
+  describe("#given a base config without model and no overrides", () => {
+    describe("#when buildAgent is called with category model", () => {
+      it("#then category model fills the missing base model", () => {
+        const result = buildAgent(
+          {
+            prompt: "base",
+          },
+          "openai/gpt-5.3-codex",
+          {
+            model: "anthropic/claude-sonnet-4-6",
+          },
+        );
+
+        expect(result.model).toBe("anthropic/claude-sonnet-4-6");
+      });
+    });
+  });
+});

package/src/agents/agent-builder.ts

@@ -0,0 +1,97 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { AgentFactory, AgentOverrideConfig } from "../types/agent";
+import type { CategoryConfig } from "../types/category";
+import { qualifyModel } from "../shared/provider-registry";
+
+export type AgentSource = AgentFactory | AgentConfig;
+
+export interface BuildAgentOptions {
+  defaultTemperature?: number;
+  preferredProvider?: string;
+}
+
+export function isAgentFactory(source: AgentSource): source is AgentFactory {
+  return typeof source === "function";
+}
+
+function appendPrompt(basePrompt: string | undefined, appendText: string): string {
+  if (!basePrompt) return appendText;
+  return `${basePrompt}\n\n${appendText}`;
+}
+
+export function buildAgent(
+  source: AgentSource,
+  model: string,
+  categoryConfig?: CategoryConfig,
+  overrides?: AgentOverrideConfig,
+  options?: BuildAgentOptions,
+): AgentConfig {
+  const base: AgentConfig = isAgentFactory(source)
+    ? source(model)
+    : {
+        ...source,
+        tools: source.tools ? { ...source.tools } : undefined,
+      };
+
+  if (categoryConfig) {
+    if (!base.model && categoryConfig.model) {
+      base.model = categoryConfig.model;
+    }
+
+    if (categoryConfig.prompt_append) {
+      base.prompt = appendPrompt(base.prompt, categoryConfig.prompt_append);
+    }
+
+    if (base["variant"] === undefined && categoryConfig.variant !== undefined) {
+      base["variant"] = categoryConfig.variant;
+    }
+  }
+
+  if (!base.model) {
+    base.model = model;
+  }
+
+  if (overrides) {
+    if (overrides.model) {
+      base.model = overrides.model;
+    }
+
+    if (overrides.temperature !== undefined) {
+      base.temperature = overrides.temperature;
+    }
+
+    if (overrides.top_p !== undefined) {
+      base.top_p = overrides.top_p;
+    }
+
+    if (overrides.prompt_append) {
+      base.prompt = appendPrompt(base.prompt, overrides.prompt_append);
+    }
+
+    if (overrides.variant !== undefined) {
+      base["variant"] = overrides.variant;
+    }
+
+    if (overrides.disable !== undefined) {
+      base.disable = overrides.disable;
+    }
+
+    if (overrides.denied_tools?.length) {
+      const tools: Record<string, boolean> = { ...base.tools };
+      for (const deniedTool of overrides.denied_tools) {
+        tools[deniedTool] = false;
+      }
+      base.tools = tools;
+    }
+  }
+
+  if (base.temperature === undefined && options?.defaultTemperature !== undefined) {
+    base.temperature = options.defaultTemperature;
+  }
+
+  if (base.model) {
+    base.model = qualifyModel(base.model, options?.preferredProvider);
+  }
+
+  return base;
+}

package/src/agents/agent-plugins.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "bun:test";
+import { orchestratorPlugin } from "./orchestrator/plugin";
+import { deepWorkerPlugin } from "./deep-worker/plugin";
+import { plannerPlugin } from "./planner/plugin";
+import { advisorPlugin } from "./advisor/plugin";
+import { researcherPlugin } from "./researcher/plugin";
+import { explorerPlugin } from "./explorer/plugin";
+import { workerPlugin } from "./worker/plugin";
+import { BUILTIN_AGENT_PLUGINS } from "./builtin-agents";
+
+const ALL_PLUGINS = [
+  orchestratorPlugin,
+  deepWorkerPlugin,
+  plannerPlugin,
+  advisorPlugin,
+  researcherPlugin,
+  explorerPlugin,
+  workerPlugin,
+];
+
+describe("agent plugins", () => {
+  describe("#given all builtin agent plugins", () => {
+    describe("#when inspecting each plugin", () => {
+      it("#then each has a unique name", () => {
+        const names = ALL_PLUGINS.map((p) => p.name);
+        expect(new Set(names).size).toBe(ALL_PLUGINS.length);
+      });
+
+      it("#then each contributes exactly one agent", () => {
+        for (const plugin of ALL_PLUGINS) {
+          expect(plugin.agents).toBeDefined();
+          expect(Object.keys(plugin.agents!).length).toBe(1);
+        }
+      });
+
+      it("#then each agent has a non-empty prompt", () => {
+        for (const plugin of ALL_PLUGINS) {
+          const agent = Object.values(plugin.agents!)[0];
+          expect(typeof agent.prompt).toBe("string");
+          expect(agent.prompt!.length).toBeGreaterThan(50);
+        }
+      });
+
+      it("#then each agent inherits model from user config (no hardcoded model)", () => {
+        for (const plugin of ALL_PLUGINS) {
+          const agent = Object.values(plugin.agents!)[0];
+          expect(agent.model).toBeUndefined();
+        }
+      });
+
+      it("#then each agent has a temperature number", () => {
+        for (const plugin of ALL_PLUGINS) {
+          const agent = Object.values(plugin.agents!)[0];
+          expect(typeof agent.temperature).toBe("number");
+        }
+      });
+
+      it("#then each plugin has version 0.1.0", () => {
+        for (const plugin of ALL_PLUGINS) {
+          expect(plugin.version).toBe("0.1.0");
+        }
+      });
+
+      it("#then the agent key matches the plugin name", () => {
+        for (const plugin of ALL_PLUGINS) {
+          const agentKeys = Object.keys(plugin.agents!);
+          expect(agentKeys[0]).toBe(plugin.name);
+        }
+      });
+    });
+
+    describe("#when checking tool-restricted agents", () => {
+      it("#then advisor has write, edit, bash, and task tools denied", () => {
+        const agent = advisorPlugin.agents!["advisor"];
+        expect(agent.tools).toBeDefined();
+        expect(agent.tools!["write"]).toBe(false);
+        expect(agent.tools!["edit"]).toBe(false);
+        expect(agent.tools!["bash"]).toBe(false);
+        expect(agent.tools!["interactive_bash"]).toBe(false);
+        expect(agent.tools!["delegate_task"]).toBe(false);
+        expect(agent.tools!["task_create"]).toBe(false);
+        expect(agent.tools!["task_update"]).toBe(false);
+      });
+    });
+
+    describe("#when checking BUILTIN_AGENT_PLUGINS barrel", () => {
+      it("#then it contains exactly 7 plugins", () => {
+        expect(BUILTIN_AGENT_PLUGINS).toHaveLength(7);
+      });
+
+      it("#then it matches the individual plugin imports", () => {
+        for (const plugin of ALL_PLUGINS) {
+          expect(BUILTIN_AGENT_PLUGINS).toContain(plugin);
+        }
+      });
+    });
+  });
+});

package/src/agents/agent-registry.ts

@@ -0,0 +1,25 @@
+import type { PluginAgentContribution } from "../types/agent";
+import { log } from "../shared/logger";
+
+export class AgentRegistry {
+  private readonly agents = new Map<string, PluginAgentContribution>();
+
+  register(name: string, agent: PluginAgentContribution): void {
+    if (this.agents.has(name)) {
+      log(`[AgentRegistry] Agent "${name}" already registered, overwriting`);
+    }
+    this.agents.set(name, agent);
+  }
+
+  get(name: string): PluginAgentContribution | undefined {
+    return this.agents.get(name);
+  }
+
+  getAll(): Map<string, PluginAgentContribution> {
+    return new Map(this.agents);
+  }
+
+  get size(): number {
+    return this.agents.size;
+  }
+}

package/src/agents/builtin-agents.ts

@@ -0,0 +1,18 @@
+import { orchestratorPlugin } from "./orchestrator";
+import { deepWorkerPlugin } from "./deep-worker";
+import { plannerPlugin } from "./planner";
+import { advisorPlugin } from "./advisor";
+import { researcherPlugin } from "./researcher";
+import { explorerPlugin } from "./explorer";
+import { workerPlugin } from "./worker";
+import type { PluginDefinition } from "../types/plugin";
+
+export const BUILTIN_AGENT_PLUGINS: PluginDefinition[] = [
+  orchestratorPlugin,
+  deepWorkerPlugin,
+  plannerPlugin,
+  advisorPlugin,
+  researcherPlugin,
+  explorerPlugin,
+  workerPlugin,
+];

package/src/agents/deep-worker/config.ts

@@ -0,0 +1,6 @@
+import type { AgentMode } from "../../types/agent";
+import { DEFAULT_TEMPERATURE } from "../../config/defaults";
+
+export const DEEP_WORKER_TEMPERATURE = DEFAULT_TEMPERATURE;
+export const DEEP_WORKER_MODE: AgentMode = "all";
+export const DEEP_WORKER_FALLBACK_MODELS = ["claude-opus-4-6"];

package/src/agents/deep-worker/index.ts

@@ -0,0 +1,2 @@
+export { deepWorkerPlugin } from "./plugin";
+export * from "./config";

package/src/agents/deep-worker/plugin.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "bun:test";
+import { deepWorkerPlugin } from "./plugin";
+
+describe("deepWorkerPlugin", () => {
+  describe("#given the deep-worker plugin", () => {
+    describe("#when inspecting plugin metadata", () => {
+      it("#then has the correct plugin name", () => {
+        expect(deepWorkerPlugin.name).toBe("deep-worker");
+      });
+    });
+
+    describe("#when inspecting the agent config", () => {
+      it("#then mode is 'all'", () => {
+        const agent = deepWorkerPlugin.agents!["deep-worker"];
+        expect(agent.mode).toBe("all");
+      });
+
+      it("#then has a temperature and non-empty prompt", () => {
+        const agent = deepWorkerPlugin.agents!["deep-worker"];
+        expect(typeof agent.temperature).toBe("number");
+        expect(typeof agent.prompt).toBe("string");
+        expect(agent.prompt!.length).toBeGreaterThan(0);
+      });
+
+      it("#then does not define tool restrictions", () => {
+        const agent = deepWorkerPlugin.agents!["deep-worker"];
+        expect(agent.tools).toBeUndefined();
+      });
+    });
+  });
+});

package/src/agents/deep-worker/plugin.ts

@@ -0,0 +1,16 @@
+import { definePlugin } from "../../plugin-api";
+import { DEEP_WORKER_TEMPERATURE, DEEP_WORKER_MODE } from "./config";
+import { DEEP_WORKER_PROMPT } from "./prompt";
+
+export const deepWorkerPlugin = definePlugin({
+  name: "deep-worker",
+  version: "0.1.0",
+  agents: {
+    "deep-worker": {
+      temperature: DEEP_WORKER_TEMPERATURE,
+      mode: DEEP_WORKER_MODE,
+      prompt: DEEP_WORKER_PROMPT,
+      color: "#7C3AED",
+    },
+  },
+});

package/src/agents/deep-worker/prompt-meta.ts

@@ -0,0 +1,14 @@
+import type { PromptMeta } from "../prompt-meta";
+
+export const DEEP_WORKER_PROMPT_META: PromptMeta = {
+  version: "1.0.0",
+  date: "2025-03-28",
+  summary: "Executes complex goals autonomously with end-to-end verification.",
+  changelog: [
+    {
+      version: "1.0.0",
+      date: "2025-03-28",
+      description: "Production-grade prompt with structured sections and quality gates",
+    },
+  ],
+};