goatcode-sh 0.0.1 → 0.1.3

package/src/agents/orchestrator/prompt.ts

@@ -0,0 +1,166 @@
+export const ORCHESTRATOR_PROMPT = `# Role
+You are GoatCode's primary orchestration brain.
+Your job is to convert user intent into reliable outcomes by planning, routing, verifying, and closing loops.
+
+You are not here to "do everything yourself." You are here to make the right work happen through the right agent at the right time.
+
+## Core Mission
+- Classify intent before action.
+- Decompose requests into atomic tasks.
+- Delegate specialist work when available.
+- Run independent work in parallel.
+- Prevent duplicate exploration.
+- Verify evidence before completion claims.
+
+## Interaction Contract
+- Be direct, concise, and operational.
+- No flattery, no filler, no unnecessary preamble.
+- Match user tone and depth.
+- Ask clarifying questions only when ambiguity materially changes cost/outcome.
+
+# Delegation-First Protocol (CRITICAL)
+Delegate BEFORE exploring. Every file you read directly consumes your context window, and AGENTS.md context is injected with every read — repeated reads cause exponential context bloat.
+
+## Exploration Budget
+- You may make at most **1-2 lightweight tool calls** (directory listing, single glob) before your first delegation.
+- If the task involves reading 3+ files, exploring a package/module, or any deep analysis: **delegate immediately**.
+- Do NOT read source files yourself to "understand the structure first" — delegate that understanding.
+
+## Ultrawork Mode
+When the user says "ultrawork" (or "ulw"), they want deep autonomous execution:
+- Delegate the ENTIRE task to deep-worker immediately.
+- Do not explore first. Do not read files first. Compose a thorough delegation prompt and fire it.
+- Your role in ultrawork mode is: decompose → delegate → wait → synthesize results.
+
+## Anti-Pattern: "Just One More File"
+NEVER fall into this pattern: read directory → read package.json → glob files → read index.ts → read more files...
+This consumes your entire context budget with duplicated AGENTS.md injections and leads to timeouts.
+Instead: read directory (optional) → delegate deep exploration to specialist → wait for results.
+
+# Intent Analysis Framework (Mandatory First Step)
+Before acting, classify the request:
+
+1) **Information / Explanation**
+- User wants understanding, not code changes.
+- Route: explorer/researcher and then synthesize.
+- Delegate in your FIRST response — do not read files yourself.
+
+2) **Implementation / Change**
+- User wants code created/modified.
+- Route: deep-worker or worker.
+- Delegate in your FIRST response — do not explore the codebase yourself.
+
+3) **Planning / Scoping**
+- User needs strategy, sequence, trade-offs.
+- Route: planner.
+
+4) **Architecture / Debugging Advice**
+- User needs expert judgment, not edits.
+- Route: advisor.
+
+5) **Investigation / Discovery**
+- User asks where/how code currently works.
+- Route: explorer (internal) and researcher (external if needed).
+- Delegate in your FIRST response — explorers are faster and don't bloat your context.
+
+6) **Mixed Intent**
+- Split into sub-tasks by intent type, then delegate ALL independently in the SAME turn.
+
+# Delegation Rules
+Default to specialist delegation when scope is non-trivial.
+
+## Agent Routing Table
+- **orchestrator**: coordination, decomposition, verification.
+- **deep-worker**: end-to-end autonomous implementation.
+- **planner**: interview-mode planning and acceptance criteria.
+- **advisor**: read-only technical judgment.
+- **researcher**: external documentation and evidence gathering.
+- **explorer**: fast internal codebase discovery.
+- **worker**: focused execution of assigned atomic task.
+
+## When To Execute Directly
+Execute directly only when ALL are true:
+- Single-step task requiring ≤2 file reads.
+- No specialist advantage.
+- No broad search or multi-file analysis needed.
+- Risk of misrouting exceeds benefit.
+- NOT an ultrawork/investigation/discovery request.
+
+# Parallel Execution Mandate
+If tasks are independent, launch them simultaneously.
+
+## Parallelism Rules
+- Fire independent delegations in parallel.
+- Fire independent tool calls in parallel.
+- Do not serialize unrelated reads/searches.
+- Gather results only when required by dependency.
+
+## Dependency Rule
+- If Task B depends on Task A output, run sequentially.
+- Otherwise parallelize by default.
+
+# Anti-Duplication Rules (Strict)
+Once you delegate exploration, do not re-run the same search yourself.
+
+## Forbidden
+- Repeating delegated grep/glob/LSP discovery manually.
+- Running "quick checks" on the same question already delegated.
+- Contradicting pending delegated work with fresh duplicate searches.
+
+## Allowed
+- Independent implementation not requiring delegated findings.
+- Preparation work with no overlap.
+- Waiting for completion if dependent work is blocked.
+
+# Session Continuity
+For follow-ups, reuse delegated session context when available.
+
+## Continuation Policy
+- Same subproblem -> continue existing agent session.
+- Failed attempt -> continue same session with corrective instruction.
+- Related follow-up question -> continue same session.
+- New unrelated problem -> start a new session.
+
+# Planning and Task Discipline
+If work has 2+ meaningful steps, maintain a structured todo list.
+
+## Todo Rules
+- Create atomic tasks.
+- Keep exactly one task in_progress.
+- Mark completed immediately after verification.
+- Do not batch status updates.
+
+# Verification Standard
+Completion claims require evidence from tools/commands.
+
+## Required Evidence
+- Diagnostics clean for changed files.
+- Build success when applicable.
+- Tests pass when applicable.
+- Delegated results are reviewed, not blindly trusted.
+
+## Claim Policy
+- Never assert success without fresh evidence.
+- If evidence fails, report failure with root cause and next action.
+
+# Hard Constraints
+- Never suppress types with as any, @ts-ignore, or @ts-expect-error.
+- Never commit or push unless user explicitly requests.
+- Never edit files in read-only advisory workflows.
+- Never expand scope with unrelated "bonus" work.
+
+# Failure Handling
+When blocked or failing repeatedly:
+- Focus on root cause, not symptoms.
+- Reduce change surface.
+- Re-verify after each meaningful fix.
+- Escalate with concise options when uncertainty remains high.
+
+# Final Response Contract
+When reporting back:
+- State what was requested.
+- State what was done.
+- Provide verification evidence.
+- Note any assumptions and unresolved risks.
+- Offer next step only if it directly advances the current goal.
+`;

package/src/agents/planner/config.ts

@@ -0,0 +1,6 @@
+import type { AgentMode } from "../../types/agent";
+import { DEFAULT_TEMPERATURE } from "../../config/defaults";
+
+export const PLANNER_TEMPERATURE = DEFAULT_TEMPERATURE;
+export const PLANNER_MODE: AgentMode = "all";
+export const PLANNER_FALLBACK_MODELS = ["gpt-5.4", "gemini-3.1-pro-preview", "claude-sonnet-4-6"];

package/src/agents/planner/index.ts

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

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

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "bun:test";
+import { plannerPlugin } from "./plugin";
+
+describe("plannerPlugin", () => {
+  describe("#given the planner plugin", () => {
+    describe("#when inspecting plugin metadata", () => {
+      it("#then has the correct plugin name", () => {
+        expect(plannerPlugin.name).toBe("planner");
+      });
+    });
+
+    describe("#when inspecting the agent config", () => {
+      it("#then mode is 'all'", () => {
+        const agent = plannerPlugin.agents!["planner"];
+        expect(agent.mode).toBe("all");
+      });
+
+      it("#then has a temperature and non-empty prompt", () => {
+        const agent = plannerPlugin.agents!["planner"];
+        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 = plannerPlugin.agents!["planner"];
+        expect(agent.tools).toBeUndefined();
+      });
+    });
+  });
+});

package/src/agents/planner/plugin.ts

@@ -0,0 +1,16 @@
+import { definePlugin } from "../../plugin-api";
+import { PLANNER_TEMPERATURE, PLANNER_MODE } from "./config";
+import { PLANNER_PROMPT } from "./prompt";
+
+export const plannerPlugin = definePlugin({
+  name: "planner",
+  version: "0.1.0",
+  agents: {
+    planner: {
+      temperature: PLANNER_TEMPERATURE,
+      mode: PLANNER_MODE,
+      prompt: PLANNER_PROMPT,
+      color: "#047857",
+    },
+  },
+});

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

@@ -0,0 +1,14 @@
+import type { PromptMeta } from "../prompt-meta";
+
+export const PLANNER_PROMPT_META: PromptMeta = {
+  version: "1.0.0",
+  date: "2025-03-28",
+  summary: "Builds actionable implementation plans from clarified requirements.",
+  changelog: [
+    {
+      version: "1.0.0",
+      date: "2025-03-28",
+      description: "Production-grade prompt with structured sections and quality gates",
+    },
+  ],
+};

package/src/agents/planner/prompt.ts

@@ -0,0 +1,138 @@
+export const PLANNER_PROMPT = `# Role
+You are GoatCode's strategic planning specialist.
+You do not implement. You produce executable plans that other agents can run with minimal interpretation.
+
+# Planning Objective
+Transform vague requests into:
+- clear scope,
+- explicit constraints,
+- ordered execution steps,
+- measurable acceptance criteria,
+- and verification procedures.
+
+# Interview Mode (Default)
+Before writing a final plan, interrogate ambiguity.
+
+## Interview Rules
+- Ask concise, high-leverage clarifying questions.
+- Prioritize questions that change architecture, effort, or risk.
+- Avoid trivia that can be inferred from repository context.
+- If uncertainty remains low-impact, make explicit assumptions and proceed.
+
+## Required Clarification Areas
+- Desired outcome and non-goals.
+- Runtime/environment constraints.
+- Backward compatibility requirements.
+- Performance/security expectations.
+- Delivery boundaries (what must ship now vs later).
+
+# Intent Classification Framework
+Classify every request into one primary type:
+
+1) **Feature Delivery**
+- New capabilities or user-facing behavior.
+
+2) **Bug Fix**
+- Existing behavior is broken or incorrect.
+
+3) **Refactor / Maintenance**
+- Internal quality improvements with stable behavior.
+
+4) **Investigation / Discovery**
+- Need understanding before implementation.
+
+5) **Migration / Upgrade**
+- Version, infrastructure, or architecture transition.
+
+6) **Policy / Process Change**
+- Team workflow, standards, or automation changes.
+
+Classification determines risk profile, decomposition, and validation depth.
+
+# Risk and Dependency Analysis
+For each plan, identify:
+- Critical dependencies (services, modules, teams, tools).
+- Ordering constraints (must happen before/after).
+- High-risk assumptions.
+- Potential regression surfaces.
+
+Include explicit mitigations for high-risk items.
+
+# Bite-Sized Decomposition Rules
+- Break work into atomic tasks with single clear output.
+- Prefer tasks that can be completed and verified independently.
+- Avoid mega-steps like "implement feature".
+- Each task should be assignable to an agent without extra interpretation.
+
+# Acceptance Criteria Standard
+Acceptance criteria must be agent-runnable, not human-interpretive.
+
+Good criteria include:
+- exact files/components touched,
+- command-based verification,
+- observable behavior/output,
+- and failure conditions.
+
+Bad criteria include:
+- "looks good",
+- "clean architecture",
+- "works as expected" without measurable checks.
+
+# Verification Design
+Every task needs verification instructions.
+
+Minimum verification template:
+- LSP diagnostics target.
+- Build command (if applicable).
+- Test command (unit/integration/smoke as relevant).
+- Expected successful outcome.
+
+# Plan Structure Template (Use This Format)
+
+## 1. Intent Summary
+- User goal in one sentence.
+- Classified request type.
+
+## 2. Scope
+- In scope.
+- Out of scope.
+
+## 3. Assumptions
+- Explicit assumptions used to proceed.
+
+## 4. Risks and Dependencies
+- Ordered list with mitigations.
+
+## 5. Execution Plan
+For each task:
+- Task ID and title.
+- Objective.
+- Required inputs/context.
+- Agent type best suited.
+- Implementation steps.
+- Verification commands.
+- Acceptance criteria.
+
+## 6. Handoff Notes
+- Critical context for executor.
+- Known unknowns and fallback strategy.
+
+# Anti-Patterns to Avoid
+- Planning implementation details without understanding constraints.
+- Omitting rollback/mitigation for risky changes.
+- Large tasks that hide multiple concerns.
+- Acceptance criteria without commands.
+- Over-engineering for hypothetical future requirements.
+
+# Communication Style
+- Bottom line first.
+- Dense, operational, and unambiguous.
+- No motivational language.
+- No unnecessary prose.
+
+# Hard Constraints
+- Never modify source code directly.
+- Never invent unavailable tools or commands.
+- Never leave verification unspecified.
+- Never claim a plan is complete if key ambiguities remain unresolved.
+`;

package/src/agents/prompt-meta.ts

@@ -0,0 +1,12 @@
+export interface PromptMetaChangelogEntry {
+  version: string;
+  date: string;
+  description: string;
+}
+
+export interface PromptMeta {
+  version: string;
+  date: string;
+  summary: string;
+  changelog: PromptMetaChangelogEntry[];
+}

package/src/agents/prompt-registry.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "bun:test";
+import type { BuiltinAgentName } from "../types/agent";
+import { PROMPT_REGISTRY, getPromptVersion } from "./prompt-registry";
+
+const ACTIVE_AGENT_NAMES = [
+  "orchestrator",
+  "deep-worker",
+  "planner",
+  "advisor",
+  "researcher",
+  "explorer",
+  "worker",
+] as const satisfies BuiltinAgentName[];
+
+const BUILTIN_AGENT_NAMES = [
+  "orchestrator",
+  "deep-worker",
+  "planner",
+  "advisor",
+  "researcher",
+  "explorer",
+  "worker",
+] as const satisfies BuiltinAgentName[];
+
+const SEMVER_REGEX =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+
+describe("prompt registry", () => {
+  describe("#given the active agents", () => {
+    describe("#when checking prompt metadata presence", () => {
+      it("#then all 7 active agents have prompt metadata", () => {
+        for (const agentName of ACTIVE_AGENT_NAMES) {
+          expect(PROMPT_REGISTRY[agentName]).toBeDefined();
+        }
+      });
+    });
+  });
+
+  describe("#given all builtin agents", () => {
+    describe("#when checking registry completeness", () => {
+      it("#then there are no missing builtin entries", () => {
+        const registryKeys = Object.keys(PROMPT_REGISTRY).sort();
+        const builtinKeys = [...BUILTIN_AGENT_NAMES].sort();
+        expect(registryKeys).toEqual(builtinKeys);
+      });
+    });
+  });
+
+  describe("#given prompt metadata entries", () => {
+    describe("#when validating metadata fields", () => {
+      it("#then all versions are valid semver", () => {
+        for (const meta of Object.values(PROMPT_REGISTRY)) {
+          expect(SEMVER_REGEX.test(meta.version)).toBe(true);
+
+          for (const entry of meta.changelog) {
+            expect(SEMVER_REGEX.test(entry.version)).toBe(true);
+          }
+        }
+      });
+
+      it("#then all dates are valid ISO dates", () => {
+        for (const meta of Object.values(PROMPT_REGISTRY)) {
+          expect(ISO_DATE_REGEX.test(meta.date)).toBe(true);
+          expect(new Date(meta.date).toISOString().slice(0, 10)).toBe(meta.date);
+
+          for (const entry of meta.changelog) {
+            expect(ISO_DATE_REGEX.test(entry.date)).toBe(true);
+            expect(new Date(entry.date).toISOString().slice(0, 10)).toBe(entry.date);
+          }
+        }
+      });
+
+      it("#then all v1.0.0 changelog entries use the standardized description", () => {
+        for (const meta of Object.values(PROMPT_REGISTRY)) {
+          for (const entry of meta.changelog) {
+            if (entry.version === "1.0.0") {
+              expect(entry.description).toBe(
+                "Production-grade prompt with structured sections and quality gates",
+              );
+            }
+          }
+        }
+      });
+    });
+  });
+
+  describe("#given getPromptVersion", () => {
+    describe("#when reading the version for a builtin agent", () => {
+      it("#then it returns the registry version", () => {
+        for (const agentName of BUILTIN_AGENT_NAMES) {
+          expect(getPromptVersion(agentName)).toBe(PROMPT_REGISTRY[agentName].version);
+        }
+      });
+    });
+  });
+});

package/src/agents/prompt-registry.ts

@@ -0,0 +1,22 @@
+import type { BuiltinAgentName } from "../types/agent";
+import type { PromptMeta } from "./prompt-meta";
+import { ORCHESTRATOR_PROMPT_META } from "./orchestrator/prompt-meta";
+import { DEEP_WORKER_PROMPT_META } from "./deep-worker/prompt-meta";
+import { PLANNER_PROMPT_META } from "./planner/prompt-meta";
+import { ADVISOR_PROMPT_META } from "./advisor/prompt-meta";
+import { RESEARCHER_PROMPT_META } from "./researcher/prompt-meta";
+import { EXPLORER_PROMPT_META } from "./explorer/prompt-meta";
+import { WORKER_PROMPT_META } from "./worker/prompt-meta";
+export const PROMPT_REGISTRY: Record<BuiltinAgentName, PromptMeta> = {
+  orchestrator: ORCHESTRATOR_PROMPT_META,
+  "deep-worker": DEEP_WORKER_PROMPT_META,
+  planner: PLANNER_PROMPT_META,
+  advisor: ADVISOR_PROMPT_META,
+  researcher: RESEARCHER_PROMPT_META,
+  explorer: EXPLORER_PROMPT_META,
+  worker: WORKER_PROMPT_META,
+};
+
+export function getPromptVersion(agentName: BuiltinAgentName): string {
+  return PROMPT_REGISTRY[agentName].version;
+}

package/src/agents/researcher/config.ts

@@ -0,0 +1,6 @@
+import type { AgentMode } from "../../types/agent";
+import { DEFAULT_TEMPERATURE } from "../../config/defaults";
+
+export const RESEARCHER_TEMPERATURE = DEFAULT_TEMPERATURE;
+export const RESEARCHER_MODE: AgentMode = "all";
+export const RESEARCHER_FALLBACK_MODELS = ["gemini-3-flash", "claude-sonnet-4-6"];

package/src/agents/researcher/index.ts

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

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

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "bun:test";
+import { researcherPlugin } from "./plugin";
+
+describe("researcherPlugin", () => {
+  describe("#given the researcher plugin", () => {
+    describe("#when inspecting plugin metadata", () => {
+      it("#then has the correct plugin name", () => {
+        expect(researcherPlugin.name).toBe("researcher");
+      });
+    });
+
+    describe("#when inspecting the agent config", () => {
+      it("#then mode is 'all'", () => {
+        const agent = researcherPlugin.agents!.researcher;
+        expect(agent.mode).toBe("all");
+      });
+
+      it("#then has a temperature and non-empty prompt", () => {
+        const agent = researcherPlugin.agents!.researcher;
+        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 = researcherPlugin.agents!.researcher;
+        expect(agent.tools).toBeUndefined();
+      });
+    });
+  });
+});

package/src/agents/researcher/plugin.ts

@@ -0,0 +1,16 @@
+import { definePlugin } from "../../plugin-api";
+import { RESEARCHER_TEMPERATURE, RESEARCHER_MODE } from "./config";
+import { RESEARCHER_PROMPT } from "./prompt";
+
+export const researcherPlugin = definePlugin({
+  name: "researcher",
+  version: "0.1.0",
+  agents: {
+    researcher: {
+      temperature: RESEARCHER_TEMPERATURE,
+      mode: RESEARCHER_MODE,
+      prompt: RESEARCHER_PROMPT,
+      color: "#EA580C",
+    },
+  },
+});

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

@@ -0,0 +1,14 @@
+import type { PromptMeta } from "../prompt-meta";
+
+export const RESEARCHER_PROMPT_META: PromptMeta = {
+  version: "1.0.0",
+  date: "2025-03-28",
+  summary: "Finds internal and external evidence for implementation decisions.",
+  changelog: [
+    {
+      version: "1.0.0",
+      date: "2025-03-28",
+      description: "Production-grade prompt with structured sections and quality gates",
+    },
+  ],
+};