goatcode-sh 0.0.1 → 0.1.3

package/.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint, Format & Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.0"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Format check
+        run: bun run fmt:check
+
+      - name: Type check
+        run: bun run typecheck
+
+  tests:
+    name: Test, Integration & Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.0"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run tests
+        run: bun run test
+
+      - name: Run integration tests
+        run: bun run test:integration
+
+      - name: Run coverage (non-blocking)
+        run: bun run test:coverage
+        continue-on-error: true
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [quality, tests]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.0"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Verify build output
+        run: |
+          test -f dist/index.js || (echo "ERROR: dist/index.js not found" && exit 1)
+          test -f dist/index.d.ts || (echo "ERROR: dist/index.d.ts not found" && exit 1)
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7

package/.github/workflows/release.yml

@@ -0,0 +1,107 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  quality:
+    name: Lint, Format & Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.0"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Format check
+        run: bun run fmt:check
+
+      - name: Type check
+        run: bun run typecheck
+
+  tests:
+    name: Test & Integration
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.0"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run tests
+        run: bun run test
+
+      - name: Run integration tests
+        run: bun run test:integration
+
+  publish:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: [quality, tests]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.0"
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Verify build output
+        run: |
+          test -f dist/index.js || (echo "ERROR: dist/index.js not found" && exit 1)
+          test -f dist/index.d.ts || (echo "ERROR: dist/index.d.ts not found" && exit 1)
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          PKG_VERSION="$(jq -r '.version' package.json)"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "ERROR: Tag version ($TAG_VERSION) does not match package.json version ($PKG_VERSION)"
+            exit 1
+          fi
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [publish]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Create release
+        run: gh release create "$GITHUB_REF_NAME" --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.opencode/plugins/goatcode.js

@@ -0,0 +1 @@
+export { default as GoatCode } from "../../dist/index.js";

package/AGENTS.md

@@ -0,0 +1,59 @@
+# Agent Reference
+
+GoatCode includes 7 specialized agents. Each agent is tuned for specific tasks and has unique capabilities and tool restrictions.
+
+## Orchestrator
+
+The main coordinator for all tasks. It analyzes user intent, builds a plan, and delegates work to specialists.
+
+- **When to use**: For any new task or complex multi-step project.
+- **Key Capabilities**: Intent analysis, task delegation, parallel execution management, and final verification.
+- **Example Prompt**: "Analyze the user's request and break it down into atomic tasks for specialist agents."
+
+## DeepWorker
+
+An autonomous worker designed for end-to-end execution of complex technical goals.
+
+- **When to use**: When you have a clear goal but the implementation steps are unknown or complex.
+- **Key Capabilities**: Codebase exploration, research, and implementation without constant supervision.
+- **Example Prompt**: "Implement the new authentication flow including database migrations and API endpoints."
+
+## PlanBuilder
+
+A strategic planner that uses an interview mode to define project scope and requirements.
+
+- **When to use**: Before starting a large feature or refactor to ensure all requirements are clear.
+- **Key Capabilities**: Requirement gathering, ambiguity identification, and detailed plan generation.
+- **Example Prompt**: "Interview the user to understand the requirements for the new plugin system."
+
+## Advisor
+
+A read-only consultant for architecture, code review, and debugging advice.
+
+- **When to use**: When you need a second opinion on a design or help debugging a complex issue.
+- **Key Capabilities**: Architecture analysis, code review, and debugging strategy.
+- **Example Prompt**: "Review this architectural proposal for potential security vulnerabilities."
+
+## Researcher
+
+Specializes in searching external documentation and internal codebases.
+
+- **When to use**: When you need to find how to use a specific library or find existing patterns in the code.
+- **Key Capabilities**: Documentation search, code pattern identification, and classification.
+- **Example Prompt**: "Find the best practices for implementing JWT authentication in a Bun environment."
+
+## Explorer
+
+A fast agent for codebase search and pattern matching using grep and glob tools.
+
+- **When to use**: For quick searches across the entire project.
+- **Key Capabilities**: Fast pattern matching, file discovery, and parallel tool execution.
+- **Example Prompt**: "Find all occurrences of the 'PluginRegistry' class and its usages."
+
+## Worker
+
+A general purpose executor for standard tasks and category-based delegation.
+
+- **When to use**: For standard tasks that don't require a specific specialist.
+- **Key Capabilities**: General code editing, file management, and tool usage.
+- **Example Prompt**: "Update the version number in package.json and run the build script."

package/CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to GoatCode
+
+We appreciate your interest in contributing to GoatCode. This guide covers the development setup, architecture, and contribution process.
+
+## Development Setup
+
+GoatCode is built with Bun. Ensure you have Bun installed before starting.
+
+1. Clone the repository.
+2. Install dependencies:
+   ```bash
+   bun install
+   ```
+3. Run tests to verify your setup:
+   ```bash
+   bun test
+   ```
+4. Run type checking:
+   ```bash
+   bun run typecheck
+   ```
+
+## Architecture Overview
+
+GoatCode follows a micro-plugin architecture. The project was built in waves:
+
+1. **Foundation**: Project scaffolding, core types, and the plugin registry.
+2. **Core Systems**: Agent, tool, and hook systems, background manager, and session state.
+3. **Agents**: Implementation of the 11 specialized agents.
+4. **Tools**: Implementation of the 26 built-in tools.
+5. **Hooks**: Implementation of the 30 lifecycle hooks.
+6. **Features**: Category system, skill system, and slash commands.
+7. **CLI & Integration**: CLI framework and final plugin integration.
+8. **Documentation**: Comprehensive guides and API references.
+
+## Adding a New Plugin
+
+Every feature in GoatCode is a plugin. Use the `definePlugin` helper to create new contributions.
+
+### Adding a Tool Plugin
+
+1. Create a new directory in `src/tools/`.
+2. Define your tool using `definePlugin`:
+   ```typescript
+   import { definePlugin } from "../../plugin-api"
+
+   export const myToolPlugin = definePlugin({
+     name: "my-tool",
+     tools: {
+       my_tool: {
+         description: "Does something useful",
+         parameters: {
+           type: "object",
+           properties: {
+             input: { type: "string" }
+           }
+         },
+         execute: async ({ input }) => {
+           return `Processed: ${input}`
+         }
+       }
+     }
+   })
+   ```
+3. Register the plugin in the appropriate registry or configuration.
+
+### Adding a Hook Plugin
+
+1. Create a new directory in `src/hooks/`.
+2. Define your hook using `definePlugin`:
+   ```typescript
+   import { definePlugin } from "../../plugin-api"
+
+   export const myHookPlugin = definePlugin({
+     name: "my-hook",
+     hooks: {
+       "tool.execute.before": async (params) => {
+         console.log("Executing tool:", params.tool)
+       }
+     }
+   })
+   ```
+
+## Testing Conventions
+
+We use `bun:test` for all tests. Follow the given/when/then style with nested describe blocks.
+
+```typescript
+import { describe, it, expect } from "bun:test"
+
+describe("MyComponent", () => {
+  describe("#myMethod", () => {
+    describe("given valid input", () => {
+      it("should return the expected result", () => {
+        // test logic
+      })
+    })
+  })
+})
+```
+
+Tests should be co-located with the source files they test (e.g., `my-file.test.ts` next to `my-file.ts`).
+
+## PR Process
+
+1. Create a new branch for your changes.
+2. Ensure all tests pass and type checking succeeds.
+3. Write clear commit messages that explain the "why" behind the changes.
+4. Submit a pull request with a detailed description of your changes.
+5. All PRs require a review before merging.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Skidmore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,19 +1,113 @@
-# goatcode
+# GoatCode
 
-Enterprise-grade OpenCode plugin with micro-plugin architecture and multi-agent orchestration.
+GoatCode is a professional agent harness for OpenCode. It provides a modular plugin architecture where every agent, tool, and hook is an independent plugin. This system allows for deep customization and reliable multi-agent orchestration.
 
-> **This package is under active development.** This is a name reservation. Full implementation coming soon.
+## Overview
 
-## What is goatcode?
+GoatCode reimplements core agent capabilities with a focus on engineering quality and modularity. It uses a TypeScript-native configuration system and a micro-plugin registry to compose features.
 
-goatcode is a professionally-engineered OpenCode plugin that provides:
+Key features:
+- 7 specialized agents for different task categories.
+- 26 built-in tools including LSP integration and hash-anchored editing.
+- 27 lifecycle hooks for context injection, error recovery, and quality control.
+- Background agent parallelism for non-blocking work.
+- TypeScript-native configuration with full type safety.
 
-- Multi-agent orchestration with 11 specialized agents
-- Micro-plugin architecture where every feature is independently composable
-- TypeScript-native configuration (`goatcode.config.ts`)
-- Zero built-in external service connections (enterprise-secure by default)
-- Background agent parallelism with concurrency management
+## Installation
 
-## Links
+Install GoatCode via npm:
 
-- [GitHub](https://github.com/ryanskidmore/goatcode)
+```bash
+npm install goatcode-sh
+```
+
+GoatCode requires Bun to run.
+
+## Quick Start
+
+Initialize GoatCode in your project:
+
+```bash
+goatcode install
+```
+
+This command sets up the initial configuration and verifies your environment.
+
+## Configuration
+
+GoatCode uses a `goatcode.config.ts` file in your project root. Use the `defineConfig` helper for full type support.
+
+```typescript
+import { defineConfig } from "goatcode-sh"
+
+export default defineConfig({
+  agents: {
+    orchestrator: {
+      model: "anthropic/claude-3-5-sonnet",
+      temperature: 0
+    }
+  },
+  plugins: [
+    // Add external plugins here
+  ]
+})
+```
+
+You can also configure GoatCode at the user level by creating `~/.config/goatcode/config.ts`. User-level configuration is merged with project-level configuration, allowing for persistent preferences across projects.
+
+## Agents
+
+GoatCode includes 7 specialized agents.
+
+| Agent | Description |
+|-------|-------------|
+| Orchestrator | Main coordinator that plans and delegates tasks. |
+| DeepWorker | Autonomous worker for end-to-end execution. |
+| PlanBuilder | Strategic planner that interviews the user to define scope. |
+| Advisor | Read-only consultant for architecture and code review. |
+| Researcher | Specialist for documentation and code search. |
+| Explorer | Fast codebase search and pattern matching. |
+| Worker | General purpose executor for standard tasks. |
+
+## Tools
+
+GoatCode provides 26 tools for agents to interact with your codebase.
+
+| Category | Tools |
+|----------|-------|
+| LSP | goto_definition, find_references, symbols, diagnostics, prepare_rename, rename |
+| Search | ast_grep_search, ast_grep_replace, grep, glob |
+| Editing | hashline_edit |
+| Delegation | task_delegate |
+| Background | background_output, background_cancel |
+| Session | session_list, session_read, session_search, session_info |
+| Skills | skill_load, skill_mcp_invoke |
+| System | interactive_bash, look_at |
+| Tasks | task_create, task_list, task_get, task_update |
+
+## Hooks
+
+GoatCode uses 27 hooks to manage the agent lifecycle and improve output quality.
+
+| Category | Hooks |
+|----------|-------|
+| Context | context-injector, compaction-context, phase-reminder |
+| Recovery | edit-error, json-error, session-recovery, context-window-limit |
+| Models | model-fallback, runtime-fallback, preemptive-compaction |
+| Quality | comment-checker, write-file-guard, thinking-block-validator |
+| Productivity | keyword-detector, think-mode, anthropic-effort |
+| Output | tool-output-truncator, hashline-read-enhancer, hashline-diff-enhancer |
+| Continuation | todo-enforcer, compaction-todo-preserver, stop-guard, foreground-fallback |
+| Tasks | delegate-retry, empty-response-detector, task-resume-info, todowrite-disabler |
+| Nudges | post-read-nudge |
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `goatcode install` | Install and configure GoatCode in the current directory. |
+| `goatcode update` | Check for and install updates. |
+
+## Contributing
+
+We welcome contributions. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and architectural overview.