docs: update README and AGENTS.md for new plugin structure

- Document the proper OpenCode plugin API structure
- Add Plugin API section explaining exports
- Update project structure to reflect new files
- Add plugin function and metadata module descriptions

Signed-off-by: leocavalcante <leo@cavalcante.dev>

Author: leocavalcante

AGENTS.md

@@ -4,11 +4,11 @@ This file provides instructions for AI coding agents working in this repository.
 
 ## Project Overview
 
-This is an **OpenCode plugin** that provides autonomous development agents. The plugin installs three agents that work together to create an infinite Plan-Build-Commit loop.
+This is an **OpenCode plugin** that provides autonomous development agents. The plugin follows the [OpenCode plugin API](https://opencode.ai/docs/plugins/) and installs three agents that work together to create an infinite Plan-Build-Commit loop.
 
 - **Type**: OpenCode Plugin
 - **Runtime**: Bun
-- **Language**: TypeScript (minimal)
+- **Language**: TypeScript
 
 ## Project Structure
 
@@ -19,19 +19,66 @@ opencode-plugin-opencoder/
 │   ├── opencoder-planner.md  # Planning subagent
 │   └── opencoder-builder.md  # Building subagent
 ├── src/
-│   └── index.ts              # Plugin entry point (exports metadata)
+│   ├── index.ts              # Main entry: exports plugin + re-exports metadata
+│   ├── plugin.ts             # Plugin function (OpenCode plugin API)
+│   ├── metadata.ts           # Metadata exports (name, version, agents)
+│   ├── paths.mjs             # Path utilities for install/uninstall scripts
+│   └── paths.d.mts           # Type declarations for paths.mjs
+├── tests/
+│   ├── index.test.ts         # Tests for main exports
+│   ├── plugin.test.ts        # Tests for plugin function
+│   ├── agents.test.ts        # Tests for agent files
+│   ├── install.test.ts       # Tests for install/uninstall scripts
+│   └── paths.test.ts         # Tests for path utilities
 ├── postinstall.mjs           # Copies agents to ~/.config/opencode/agents/
+├── preuninstall.mjs          # Removes agents on uninstall
 ├── package.json              # npm package configuration
 ├── biome.json                # Linter configuration
 └── tsconfig.json             # TypeScript configuration
 ```
 
+## Plugin Architecture
+
+The plugin follows the OpenCode plugin structure:
+
+### Main Exports (`src/index.ts`)
+
+```typescript
+// Plugin function (default + named export)
+export { OpenCoderPlugin } from "./plugin"
+export { OpenCoderPlugin as default } from "./plugin"
+
+// Metadata re-exports (backwards compatibility)
+export { name, version, description, agents } from "./metadata"
+```
+
+### Plugin Function (`src/plugin.ts`)
+
+```typescript
+import type { Plugin } from "@opencode-ai/plugin"
+
+export const OpenCoderPlugin: Plugin = async (ctx) => {
+  // Returns hooks object (minimal for now)
+  return {}
+}
+```
+
+### Metadata (`src/metadata.ts`)
+
+Contains package metadata exports for introspection and backwards compatibility.
+
 ## Commands
 
 ```bash
 # Install dependencies
 bun install
 
+# Run tests
+bun test
+
+# Run type checker
+bun run typecheck
+
 # Run linter
 bun run lint
 

README.md

@@ -4,7 +4,7 @@ OpenCode plugin providing autonomous development agents for continuous codebase
 
 ## Overview
 
-This plugin installs three agents that work together to create an infinite autonomous development loop:
+This plugin follows the [OpenCode plugin API](https://opencode.ai/docs/plugins/) and installs three agents that work together to create an infinite autonomous development loop:
 
 | Agent | Purpose |
 |-------|---------|
@@ -14,6 +14,17 @@ This plugin installs three agents that work together to create an infinite auton
 
 ## Installation
 
+Add the plugin to your `opencode.json` config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-plugin-opencoder"]
+}
+```
+
+Or install manually:
+
 ```bash
 bun add opencode-plugin-opencoder
 ```
@@ -115,6 +126,22 @@ Or copy the agents manually:
 cp node_modules/opencode-plugin-opencoder/agents/*.md ~/.config/opencode/agents/
 ```
 
+## Plugin API
+
+This plugin exports:
+
+```typescript
+// Main plugin function (OpenCode plugin API)
+import { OpenCoderPlugin } from "opencode-plugin-opencoder"
+// or
+import OpenCoderPlugin from "opencode-plugin-opencoder"
+
+// Metadata exports (for introspection)
+import { name, version, description, agents } from "opencode-plugin-opencoder"
+```
+
+The plugin currently provides a minimal hooks structure that can be extended in the future. Agent registration is handled via the postinstall script since the OpenCode plugin API does not yet support dynamic agent registration.
+
 ## Development
 
 ```bash