opencode-architect 0.2.3 → 0.3.0

package/README.md

@@ -19,8 +19,7 @@ Use this package any time you are doing OpenCode work: designing agents, buildin
 ## What you get 🧰
 
 - A suite of expert agents: architect, agent designer, command crafter, packager, publisher, MCP integrator, plugin engineer, skill creator, tool builder
-- `sync-docs` command + tool for fetching the latest OpenCode documentation
-- Automatic doc sync on startup with a toast error if the sync fails
+- Self-contained bundled references covering stable OpenCode fundamentals — no network sync at startup
 - Built-in alignment with OpenCode best practices for coding and prompt engineering
 
 ## Best time to use it ✅

package/agent-loader.ts

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { AgentConfig } from "@opencode-ai/sdk";
+
+export const AGENT_FILENAMES: readonly string[] = [
+  "opencode-agent-designer.md",
+  "opencode-architect.md",
+  "opencode-command-crafter.md",
+  "opencode-extension-auditor.md",
+  "opencode-packager.md",
+  "opencode-publisher.md",
+  "opencode-mcp-integrator.md",
+  "opencode-plugin-engineer.md",
+  "opencode-skill-creator.md",
+  "opencode-tool-builder.md",
+];
+
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+const RELATIVE_REFERENCE_REGEX = /`((?:\.{1,2})(?:[\\/][^`\\/]+)+)`/g;
+
+interface AgentFrontmatter {
+  description: string;
+  mode: "primary" | "subagent" | "all";
+  tools?: Record<string, boolean>;
+  permission?: {
+    edit?: "ask" | "allow" | "deny";
+    bash?: ("ask" | "allow" | "deny") | Record<string, "ask" | "allow" | "deny">;
+    webfetch?: "ask" | "allow" | "deny";
+    doom_loop?: "ask" | "allow" | "deny";
+    external_directory?: "ask" | "allow" | "deny";
+  };
+}
+
+export class AgentLoader {
+  private readonly agentsDir: string;
+
+  public constructor(agentsDir: string) {
+    this.agentsDir = agentsDir;
+  }
+
+  public async loadAgents(): Promise<Record<string, AgentConfig>> {
+    const agents: Record<string, AgentConfig> = {};
+
+    for (const filename of AGENT_FILENAMES) {
+      const agentPath = path.join(this.agentsDir, filename);
+      const agentContent = await readFile(agentPath, "utf-8");
+      const agentName = path.basename(filename, ".md");
+      agents[agentName] = await this.parseAgentMarkdown(agentPath, agentContent, agentName);
+    }
+
+    return agents;
+  }
+
+  private async parseAgentMarkdown(
+    agentPath: string,
+    content: string,
+    agentName: string,
+  ): Promise<AgentConfig> {
+    const match = content.match(FRONTMATTER_REGEX);
+
+    if (!match || match.length < 3) {
+      throw new Error(`Agent ${agentName} must have YAML frontmatter`);
+    }
+
+    const frontmatterYaml = match[1] as string;
+    const rawPrompt = match[2] as string;
+    const frontmatter = parseYaml(frontmatterYaml) as AgentFrontmatter;
+    const prompt = this.resolveReferencePaths(
+      rawPrompt.replace(/^\r?\n/, ""),
+      path.dirname(agentPath),
+    );
+
+    const config: AgentConfig = {
+      description: frontmatter.description,
+      mode: frontmatter.mode,
+      prompt,
+    };
+
+    if (frontmatter.tools) {
+      config.tools = frontmatter.tools;
+    }
+
+    if (frontmatter.permission) {
+      config.permission = frontmatter.permission;
+    }
+
+    return config;
+  }
+
+  private resolveReferencePaths(prompt: string, agentDir: string): string {
+    return prompt.replace(RELATIVE_REFERENCE_REGEX, (_token: string, relativePath: string) => {
+      const normalized = relativePath.replaceAll("\\", "/");
+      const absolute = path.resolve(agentDir, normalized).replaceAll("\\", "/");
+      return `\`${absolute}\``;
+    });
+  }
+}

package/assets/agents/opencode-agent-designer.md

@@ -51,12 +51,18 @@ Deliverables
 - Create or update the agent file.
 - If adding a new agent, add a short line to '.opencode/AGENTS.md' describing it.
 
-Docs usage
+References usage
 
-- Use '~/.cache/opencode/opencode-architect/docs/agents.md' for agent fields, modes, tools, and permissions.
-- Use '~/.cache/opencode/opencode-architect/docs/tools.md' for available tool IDs and behavior.
-- Use '~/.cache/opencode/opencode-architect/docs/config.md' for agent config precedence and defaults.
+Bundled reference files are addressed relative to this agent file's own directory:
+
+- Use '../references/agents.md' for agent fields, modes, tools, and permissions.
+- Use '../references/tools.md' for available tool IDs and behavior.
+- Use '../references/config.md' for agent config precedence and defaults.
+
+Live knowledge fallback
+
+For anything beyond the bundled references, query the deepwiki MCP tools (read_wiki_structure, read_wiki_contents, ask_question) against repo 'anomalyco/opencode' when available; otherwise run 'npx defuddle <url>' on the relevant opencode.ai/docs page if you have a way to execute commands. Degrade gracefully: when neither source is available, rely on the bundled references and your own knowledge — never block on live lookups.
 
 Required reading
 
-Before writing or editing any agent prompt, you MUST read '~/.cache/opencode/opencode-architect/docs/claude-4-best-practices.md' for prompt engineering techniques. Do not skip this step.
+Before writing or editing any agent prompt, you MUST read '../references/prompt-engineering.md' for prompt engineering techniques. Do not skip this step.

package/assets/agents/opencode-architect.md

@@ -16,12 +16,10 @@ If available, prefer Exa MCP over default websearch tools. If available, prefer
 
 You are the OpenCode meta orchestrator. Your only job is to analyze requests and delegate to the right specialist subagent. You never implement changes yourself.
 
-Before routing, you MUST read `..\references\opencode-architect-oneshots.md` in full.
+Before routing, you MUST read `../references/opencode-architect-oneshots.md` in full.
 Extract the relevant example for your task. If no direct match exists, use the most
 analogous example pattern. Include a citation of the example number in your delegation prompt.
 
-When starting check for docs availability. If '~/.cache/opencode/opencode-architect/docs' is missing or empty, run 'bun scripts/fetch-opencode-docs.ts'.
-
 ## Structural Templates
 
 When creating plugin packages intended for local sharing or npm distribution, ALWAYS use
@@ -246,17 +244,22 @@ After extraction workflow completes, always return to architect. Ask user if the
 - State the chosen agent(s) and call task tool.
 - Include rationale only when asked or when confidence is low.
 
-## Docs usage
+## References usage
+
+Bundled reference files are addressed relative to this agent file's own directory:
+
+- Use `../references/agents.md` to confirm agent fields and permissions.
+- Use `../references/tools.md` for built-in tools and the custom tool API.
+- Use `../references/plugins.md` for plugin hooks and events.
+- Use `../references/commands.md` for command frontmatter and templating.
+- Use `../references/skills.md` for skill frontmatter rules.
+- Use `../references/mcp-servers.md` for MCP configuration and scoping.
+- Use `../references/config.md` for config precedence and schema options.
+- Use `../references/prompt-engineering.md` for prompt engineering and skill-authoring techniques.
+
+## Live knowledge fallback
 
-- Use '~/.cache/opencode/opencode-architect/docs/agents.md' to confirm agent fields and permissions.
-- Use '~/.cache/opencode/opencode-architect/docs/tools.md' and '~/.cache/opencode/opencode-architect/docs/custom-tools.md' for tool references.
-- Use '~/.cache/opencode/opencode-architect/docs/plugins.md' for plugin hooks and events.
-- Use '~/.cache/opencode/opencode-architect/docs/commands.md' for command frontmatter and templating.
-- Use '~/.cache/opencode/opencode-architect/docs/skills.md' for skill frontmatter rules.
-- Use '~/.cache/opencode/opencode-architect/docs/mcp-servers.md' for MCP configuration and scoping.
-- Use '~/.cache/opencode/opencode-architect/docs/config.md' for config precedence and schema options.
-- Use '~/.cache/opencode/opencode-architect/docs/claude-4-best-practices.md' for prompt engineering techniques.
-- Use '~/.cache/opencode/opencode-architect/docs/claude-skill-best-practices.md' for skill authoring guidelines.
+For anything beyond the bundled references, query the deepwiki MCP tools (read_wiki_structure, read_wiki_contents, ask_question) against repo `anomalyco/opencode` when available. If deepwiki is unavailable, run `npx defuddle <url>` on the relevant opencode.ai/docs page to extract its content. Degrade gracefully: when neither source is available, rely on the bundled references and your own knowledge — never block on live lookups. When delegating, pass this fallback instruction to subagents.
 
 ## Required reading for subagents
 
@@ -266,7 +269,7 @@ When delegating tasks that involve writing prompts (agents, skills, commands), i
 
 - When answering questions or providing guidance, cite the source documentation.
 - Include file path and line numbers when referencing specific information.
-- Example: "According to '~/.cache/opencode/opencode-architect/docs/plugins.md' (lines 142-194), available hooks include..."
+- Example: "According to '../references/plugins.md' (Event hooks section), available hooks include..."
 
 ## Clarification Triggers
 

package/assets/agents/opencode-command-crafter.md

@@ -32,11 +32,16 @@ Deliverables
 - Create or update command files.
 - Keep prompts concise and task-focused.
 
-Docs usage
+References usage
 
-- Use '~/.cache/opencode/opencode-architect/docs/commands.md' for frontmatter and templating.
-- Use '~/.cache/opencode/opencode-architect/docs/tui.md' for built-in commands and UX constraints.
+Bundled reference files are addressed relative to this agent file's own directory:
+
+- Use '../references/commands.md' for frontmatter and templating.
+
+Live knowledge fallback
+
+For anything beyond the bundled references (e.g. built-in TUI commands and UX constraints), query the deepwiki MCP tools (read_wiki_structure, read_wiki_contents, ask_question) against repo 'anomalyco/opencode' when available; otherwise run 'npx defuddle <url>' on the relevant opencode.ai/docs page if you have a way to execute commands. Degrade gracefully: when neither source is available, rely on the bundled references and your own knowledge — never block on live lookups.
 
 Required reading
 
-Before writing or editing any command prompt template, you MUST read '~/.cache/opencode/opencode-architect/docs/claude-4-best-practices.md' for prompt engineering techniques. Do not skip this step.
+Before writing or editing any command prompt template, you MUST read '../references/prompt-engineering.md' for prompt engineering techniques. Do not skip this step.

package/assets/agents/opencode-mcp-integrator.md

@@ -32,7 +32,13 @@ Deliverables
 - Update 'opencode.json' safely.
 - Keep MCP configs minimal and explicit.
 
-Docs usage
+References usage
 
-- Use '~/.cache/opencode/opencode-architect/docs/mcp-servers.md' for server configuration and OAuth.
-- Use '~/.cache/opencode/opencode-architect/docs/config.md' for tool scoping and permission patterns.
+Bundled reference files are addressed relative to this agent file's own directory:
+
+- Use '../references/mcp-servers.md' for server configuration and OAuth.
+- Use '../references/config.md' for tool scoping and permission patterns.
+
+Live knowledge fallback
+
+For anything beyond the bundled references, query the deepwiki MCP tools (read_wiki_structure, read_wiki_contents, ask_question) against repo 'anomalyco/opencode' when available; otherwise run 'npx defuddle <url>' on the relevant opencode.ai/docs page if you have a way to execute commands. Degrade gracefully: when neither source is available, rely on the bundled references and your own knowledge — never block on live lookups.

package/assets/agents/opencode-plugin-engineer.md

@@ -42,8 +42,13 @@ Deliverables
 - Keep plugins small and focused.
 - Avoid writing logs with console if structured logging is available.
 
-Docs usage
+References usage
 
-- Use '~/.cache/opencode/opencode-architect/docs/plugins.md' for hooks, events, and plugin structure.
-- Use '~/.cache/opencode/opencode-architect/docs/sdk.md' for client logging and API interactions.
-- Use '~/.cache/opencode/opencode-architect/docs/tools.md' for built-in tool names used in hooks.
+Bundled reference files are addressed relative to this agent file's own directory:
+
+- Use '../references/plugins.md' for hooks, events, and plugin structure.
+- Use '../references/tools.md' for built-in tool names used in hooks.
+
+Live knowledge fallback
+
+For anything beyond the bundled references (e.g. SDK client logging and API interactions), query the deepwiki MCP tools (read_wiki_structure, read_wiki_contents, ask_question) against repo 'anomalyco/opencode' when available; otherwise run 'npx defuddle <url>' on the relevant opencode.ai/docs page if you have a way to execute commands. Degrade gracefully: when neither source is available, rely on the bundled references and your own knowledge — never block on live lookups.

package/assets/agents/opencode-publisher.md

@@ -82,10 +82,15 @@ Route from opencode-architect when user wants to:
 - "make distributable"
 - "publish package"
 
-## Docs usage
+## References usage
 
-- Use '~/.cache/opencode/opencode-architect/docs/plugins.md' for plugin structure
-- Use '~/.cache/opencode/opencode-architect/docs/sdk.md' for SDK features
+Bundled reference files are addressed relative to this agent file's own directory:
+
+- Use '../references/plugins.md' for plugin structure
+
+## Live knowledge fallback
+
+For anything beyond the bundled references (e.g. SDK features), query the deepwiki MCP tools (read_wiki_structure, read_wiki_contents, ask_question) against repo 'anomalyco/opencode' when available; otherwise run 'npx defuddle <url>' on the relevant opencode.ai/docs page. Degrade gracefully: when neither source is available, rely on the bundled references and your own knowledge — never block on live lookups.
 
 ## Code style rules
 

package/assets/agents/opencode-skill-creator.md

@@ -38,15 +38,18 @@ Deliverables
 - Create the skill folder and SKILL.md.
 - Keep the skill prompt concise and reusable.
 
-Docs usage
+References usage
 
-- Use '~/.cache/opencode/opencode-architect/docs/skills.md' for frontmatter fields and naming rules.
+Bundled reference files are addressed relative to this agent file's own directory:
 
-Required reading
+- Use '../references/skills.md' for frontmatter fields and naming rules.
+
+Live knowledge fallback
 
-Before writing or editing any skill prompt, you MUST read:
+For anything beyond the bundled references, query the deepwiki MCP tools (read_wiki_structure, read_wiki_contents, ask_question) against repo 'anomalyco/opencode' when available; otherwise run 'npx defuddle <url>' on the relevant opencode.ai/docs page if you have a way to execute commands. Degrade gracefully: when neither source is available, rely on the bundled references and your own knowledge — never block on live lookups.
+
+Required reading
 
-- '~/.cache/opencode/opencode-architect/docs/claude-skill-best-practices.md' for skill authoring guidelines and patterns.
-- '~/.cache/opencode/opencode-architect/docs/claude-4-best-practices.md' for general prompt engineering techniques.
+Before writing or editing any skill prompt, you MUST read '../references/prompt-engineering.md' for skill authoring guidelines and prompt engineering techniques.
 
 Do not skip this step.

package/assets/agents/opencode-tool-builder.md

@@ -31,7 +31,12 @@ Deliverables
 - Create or update tool files.
 - Keep tools narrowly scoped and documented.
 
-Docs usage
+References usage
 
-- Use '~/.cache/opencode/opencode-architect/docs/custom-tools.md' for tool structure and exports.
-- Use '~/.cache/opencode/opencode-architect/docs/tools.md' for built-in tool behavior and permissions.
+Bundled reference files are addressed relative to this agent file's own directory:
+
+- Use '../references/tools.md' for tool structure, exports, and built-in tool behavior and permissions.
+
+Live knowledge fallback
+
+For anything beyond the bundled references, query the deepwiki MCP tools (read_wiki_structure, read_wiki_contents, ask_question) against repo 'anomalyco/opencode' when available; otherwise run 'npx defuddle <url>' on the relevant opencode.ai/docs page if you have a way to execute commands. Degrade gracefully: when neither source is available, rely on the bundled references and your own knowledge — never block on live lookups.

package/assets/references/agents.md

@@ -0,0 +1,68 @@
+# OpenCode agents — fundamentals
+
+Agents are markdown-defined AI assistants. Locations (plural directory names):
+
+- Project: `.opencode/agents/`
+- Global: `~/.config/opencode/agents/`
+
+The filename becomes the agent name (`review.md` → `review` agent). The markdown body is the system prompt.
+
+## Types
+
+- `primary` — main assistant the user interacts with (Tab to cycle).
+- `subagent` — invoked by primary agents via the Task tool or by `@` mention.
+- `mode` defaults to `all` if unspecified; set it explicitly.
+
+## Frontmatter fields
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `description` | yes | What the agent does and when to use it. Drives subagent selection. |
+| `mode` | no | `primary`, `subagent`, or `all` (default `all`). |
+| `model` | no | `provider/model-id` (e.g. `anthropic/claude-sonnet-4-5`). Unset: primary uses the configured global model; subagents inherit the invoking agent's model. |
+| `temperature` | no | 0.0–1.0. Low (0.0–0.2) focused/deterministic; high (0.6+) creative. Model-specific defaults apply if unset. |
+| `steps` | no | Max agentic iterations before forced text-only summary. `maxSteps` is deprecated. |
+| `tools` | no | **Deprecated** boolean map (`write: false`, `bash: false`, `mymcp_*: false`). Prefer `permission`. |
+| `permission` | no | Allow/ask/deny control, per key or per glob pattern (see below). |
+| `hidden` | no | `true` hides a `subagent` from the `@` menu; still invokable via Task tool. |
+| `disable` | no | `true` disables the agent. |
+| `color` | no | Hex (e.g. `#ff6b6b`) or theme color (`primary`, `accent`, ...). |
+| `top_p` | no | Alternative randomness control, 0.0–1.0. |
+| other keys | no | Passed through to the provider as model options (e.g. `reasoningEffort`). |
+
+## Permissions
+
+Values: `"allow"`, `"ask"`, `"deny"`. Either shorthand or an object of glob/pattern → action.
+
+Keys: `read`, `edit`, `glob`, `grep`, `list`, `bash`, `task`, `webfetch`, `websearch`, `external_directory`, `todowrite`, `skill`, `lsp`, `question`, `doom_loop`.
+
+- `edit` gates all file modifications: `write`, `edit`, `apply_patch`.
+- `todowrite` gates `todowrite` and `todoread`.
+- Shorthand-only keys: `webfetch`, `websearch`, `external_directory`, `question`, `doom_loop`, `lsp` (also accepts patterns — check schema when in doubt).
+
+Bash command scoping (last matching rule wins; put `*` first, specific rules after):
+
+```yaml
+permission:
+  bash:
+    "*": ask
+    "git status *": allow
+    "git push": ask
+  webfetch: deny
+```
+
+Task (subagent) scoping with globs — denied subagents are removed from the Task tool description:
+
+```yaml
+permission:
+  task:
+    "*": deny
+    "orchestrator-*": allow
+    "code-reviewer": ask
+```
+
+Users can always invoke any subagent directly via `@` regardless of task permissions.
+
+## JSON alternative
+
+Agents can also be configured under the `agent` key in `opencode.json` with the same options plus `prompt` (inline string or `{file:./path}` relative to the config file). Markdown files are preferred for readability.

package/assets/references/commands.md

@@ -0,0 +1,49 @@
+# OpenCode commands — fundamentals
+
+Custom commands are prompt templates invoked as `/name` in the TUI, in addition to built-ins (`/init`, `/undo`, `/redo`, `/share`, `/help`).
+
+Locations:
+
+- Project: `.opencode/commands/`
+- Global: `~/.config/opencode/commands/`
+
+The filename becomes the command name (`test.md` → `/test`).
+
+## Markdown format
+
+The frontmatter defines properties; the body is the prompt template.
+
+```markdown
+---
+description: Run tests with coverage
+agent: build
+model: anthropic/claude-haiku-4-5
+---
+
+Run the full test suite with coverage report and show any failures.
+Focus on the failing tests and suggest fixes.
+```
+
+## Frontmatter keys
+
+| Key | Required | Notes |
+| --- | --- | --- |
+| `description` | no* | Shown in the TUI command list. |
+| `template` | no* | The prompt (JSON config only; in markdown the body is the template). |
+| `agent` | no | Which agent executes it. Defaults to the current agent. |
+| `model` | no | Overrides the default model. |
+| `subtask` | no | `true` forces a subagent invocation (keeps primary context clean), even for `primary`-mode agents. |
+
+*In JSON config (`command.<name>` in `opencode.json`), `template` is required and `description` identifies the command.
+
+## Template features
+
+- `$ARGUMENTS` — full argument string: `/component Button` → `Button`.
+- `$1`, `$2`, `$3` — positional args: `/create-file config.json src "content"` → `$1`=`config.json`, `$2`=`src`, `$3`=`content`.
+- `` !`command` `` — inject shell output into the prompt (runs in the project root), e.g. ``!`git log --oneline -10` ``.
+- `@path/to/file` — include file content in the prompt.
+
+## Notes
+
+- A custom command with the same name as a built-in overrides it.
+- Keep prompts concise and task-focused; the template is the whole instruction the model receives.

package/assets/references/config.md

@@ -0,0 +1,50 @@
+# OpenCode config — fundamentals
+
+OpenCode is configured with `opencode.json` (or `.jsonc`). Schema: `https://opencode.ai/config.json`. TUI settings live in a separate `tui.json` (`https://opencode.ai/tui.json`).
+
+## Locations and precedence
+
+Configs are **merged, not replaced**; later sources override earlier ones only for conflicting keys:
+
+1. Remote config (`.well-known/opencode`, organizational defaults)
+2. Global config (`~/.config/opencode/opencode.json`)
+3. Custom config (`OPENCODE_CONFIG` env var)
+4. Project config (`opencode.json` at project root, searched up to the git root)
+5. `.opencode/` directories (agents, commands, plugins, skills, tools)
+6. Inline config (`OPENCODE_CONFIG_CONTENT` env var)
+7. Managed files (`/etc/opencode/`, `%ProgramData%\opencode`, macOS app support) and macOS MDM preferences — highest, not user-overridable
+
+So: defaults/remote < global < project; managed settings override everything.
+
+## Key schema options
+
+| Key | Purpose |
+| --- | --- |
+| `model` | Default model, `provider/model-id`. |
+| `small_model` | Cheap model for lightweight tasks (titles, summaries). |
+| `provider` | Provider config; `options` supports `timeout`, `headerTimeout`, `chunkTimeout`. |
+| `enabled_providers` / `disabled_providers` | Provider allowlist/blocklist (`disabled_providers` wins). |
+| `agent` | Inline agent definitions; `default_agent` picks the default primary agent. |
+| `command` | Inline command definitions (`template`, `description`, `agent`, `model`). |
+| `mode` | Inline mode/agent-group definitions. |
+| `mcp` | MCP server config (see mcp-servers reference). |
+| `plugin` | npm plugin packages to load. |
+| `tools` | Global tool enable/disable map with globs (`"write": false`). |
+| `permission` | Global `allow`/`ask`/`deny` map (see agents reference for keys). |
+| `instructions` | Extra instruction files/globs (e.g. `["CONTRIBUTING.md", "docs/rules/*.md"]`). |
+| `lsp` | LSP servers (`true` for defaults, or object with per-server overrides). |
+| `formatter` | Formatters (`true` for defaults, or object; custom: `command`, `extensions`, `environment`). |
+| `keybinds` | TUI shortcuts (in `tui.json`; merged with defaults). |
+| `share` | `"manual"` (default) / `"auto"` / `"disabled"`. |
+| `autoupdate` | `true` / `false` / `"notify"`. |
+| `snapshot` | `false` disables undo snapshots. |
+| `compaction` | `{ auto, prune, reserved }` context compaction behavior. |
+| `watcher` | `{ ignore: [globs] }` file watcher exclusions. |
+| `server` | `port`, `hostname`, `mdns`, `cors` for `opencode serve`/`web`. |
+| `shell` | Shell for interactive terminal and tool calls (e.g. `pwsh`). |
+| `subagent_depth` | Subagent nesting depth (default 1; 0 disables subagents). |
+| `experimental` | Options under active development (e.g. `policies`). |
+
+## Directory conventions
+
+`.opencode/` and `~/.config/opencode/` use **plural** subdirectory names: `agents/`, `commands/`, `plugins/`, `skills/`, `tools/`, `themes/` (singular accepted for backwards compatibility). Configs are safe to check into git; `prompt` paths in agent config resolve relative to the config file.

package/assets/references/mcp-servers.md

@@ -0,0 +1,55 @@
+# OpenCode MCP servers — fundamentals
+
+MCP (Model Context Protocol) servers add external tools alongside built-ins. Configure them under the `mcp` key in `opencode.json` with a unique name per server.
+
+Caution: MCP tools add to context — enable only what you need.
+
+## Local servers
+
+```json
+{
+  "mcp": {
+    "my-local-mcp": {
+      "type": "local",
+      "command": ["npx", "-y", "my-mcp-command"],
+      "enabled": true,
+      "environment": { "MY_ENV_VAR": "value" }
+    }
+  }
+}
+```
+
+Options: `type` (required, `"local"`), `command` (required array), `cwd`, `environment`, `enabled`, `timeout` (ms to fetch tools, default 5000).
+
+## Remote servers
+
+```json
+{
+  "mcp": {
+    "my-remote-mcp": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp",
+      "enabled": true,
+      "headers": { "Authorization": "Bearer {env:MY_API_KEY}" }
+    }
+  }
+}
+```
+
+Options: `type` (required, `"remote"`), `url` (required), `headers`, `oauth`, `enabled`, `timeout`.
+
+## OAuth (remote)
+
+- Automatic: OpenCode detects the 401, runs the OAuth flow (dynamic client registration, RFC 7591), and stores tokens. No config needed for most servers.
+- Pre-registered credentials: `"oauth": { "clientId": "...", "clientSecret": "...", "scope": "tools:read" }` (use `{env:VAR}` for secrets).
+- `"oauth": false` disables auto-OAuth (e.g. API-key servers).
+- CLI: `opencode mcp auth <name>`, `opencode mcp list`, `opencode mcp logout <name>`, `opencode mcp debug <name>`.
+
+## Tool scoping
+
+MCP tools register as `<servername>_<toolname>`, so glob patterns control them like any tool:
+
+- Disable globally: `"tools": { "my-mcp*": false }` or via permission `"my-mcp_*": "ask"` (permission patterns match built-ins, custom tools, and MCP tools alike).
+- Enable per agent only: disable globally in `tools`, then set `"tools": { "my-mcp*": true }` inside the agent's config.
+- Glob syntax: `*` (any chars), `?` (one char); last matching permission rule wins.
+- Per-server enable/disable: `"enabled": false` on the server entry hides all its tools without deleting config.

package/assets/references/plugins.md

@@ -0,0 +1,76 @@
+# OpenCode plugins — fundamentals
+
+Plugins are JS/TS modules that hook into OpenCode events and customize behavior.
+
+Locations:
+
+- Project: `.opencode/plugins/`
+- Global: `~/.config/opencode/plugins/`
+
+Files in these directories load automatically at startup. npm packages can be loaded via the `plugin` array in `opencode.json`. Load order: global config → project config → global plugin dir → project plugin dir.
+
+## Plugin shape
+
+A plugin exports one or more async functions. Each receives a context and returns a hooks object:
+
+```ts
+import type { Plugin } from "@opencode-ai/plugin"
+
+export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
+  return {
+    // hook implementations
+  }
+}
+```
+
+Context: `project` (project info), `directory` (cwd), `worktree` (git worktree root), `client` (opencode SDK client), `$` (Bun shell API).
+
+## Config hooks
+
+Returning a `tool` object adds custom tools; a plugin tool that shares a built-in tool's name takes precedence:
+
+```ts
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+export const CustomToolsPlugin: Plugin = async (ctx) => {
+  return {
+    tool: {
+      mytool: tool({
+        description: "What the tool does",
+        args: { foo: tool.schema.string() },
+        async execute(args, context) {
+          const { directory, worktree } = context
+          return `Hello ${args.foo} from ${directory}`
+        },
+      }),
+    },
+  }
+}
+```
+
+## Event hooks
+
+Hooks are named event handlers: `"<event>": async (input, output) => { ... }`.
+
+Key events:
+
+- Commands: `command.executed`
+- Files: `file.edited`, `file.watcher.updated`
+- Messages: `message.updated`, `message.part.updated`, `message.part.removed`, `message.removed`
+- Permissions: `permission.asked`, `permission.replied`
+- Sessions: `session.created`, `session.idle`, `session.updated`, `session.error`, `session.compacted`, `session.deleted`, `session.diff`, `session.status`
+- Tools: `tool.execute.before`, `tool.execute.after`
+- Shell: `shell.env`
+- TUI: `tui.prompt.append`, `tui.command.execute`, `tui.toast.show`
+- Other: `installation.updated`, `lsp.client.diagnostics`, `lsp.updated`, `server.connected`, `todo.updated`
+
+A catch-all `event: async ({ event }) => {...}` hook receives every event (`event.type` switches on it).
+
+`tool.execute.before` can inspect/modify `output.args` or throw to block; `shell.env` mutates `output.env`.
+
+Compaction hook `experimental.session.compacting` can append via `output.context.push(...)` or fully replace the prompt via `output.prompt`.
+
+## Dependencies and logging
+
+- Local plugins can use npm packages: add a `package.json` to the config directory (`.opencode/package.json`); OpenCode runs `bun install` at startup.
+- Prefer structured logging via `client.app.log({ body: { service, level, message, extra } })` over `console.log`. Levels: `debug`, `info`, `warn`, `error`.

package/assets/references/prompt-engineering.md

@@ -0,0 +1,46 @@
+# Prompt engineering — distilled best practices
+
+Distilled from Anthropic's Claude prompting best practices and skill-authoring best practices. Apply to agent prompts, skill bodies, and command templates.
+
+## Core principles
+
+- **Be clear and direct.** State the desired output, format, and constraints explicitly. If you want above-and-beyond behavior, ask for it. The colleague test: could someone with minimal context follow your prompt?
+- **Explain why.** Give context/motivation for rules ("never use ellipses because a TTS engine reads this aloud"). The model generalizes from the explanation.
+- **Sequence matters.** Use numbered steps or bullets when order or completeness matters. Put critical instructions at the end of long prompts.
+- **Give a role.** A one-sentence persona in the system prompt focuses tone and behavior ("You are a code reviewer focused on security...").
+
+## Examples and structure
+
+- Few-shot examples (3–5) are the most reliable way to steer format, tone, and structure. Make them relevant, diverse, and wrapped in tags (`<example>` inside `<examples>`).
+- Use XML tags to separate instructions, context, documents, and inputs in complex prompts (`<instructions>`, `<context>`, `<documents>`). Consistent, descriptive tag names.
+- Long context: put longform data near the top and the query/instructions at the end; wrap each document in `<document>` tags with metadata; ask the model to quote relevant passages before answering.
+
+## Output control
+
+- Say what to do, not what not to do ("write flowing prose paragraphs" beats "don't use bullets").
+- Match your prompt's style to the desired output style (markdown-heavy prompts yield markdown-heavy answers).
+- Use structured outputs (JSON/XML schemas) when precise parsing is needed; request verbatim structure with an explicit template.
+
+## Tool use and agentic behavior
+
+- Models may suggest instead of act. Be explicit: "Change this function" vs "Can you suggest changes". Prompt blocks can set a default-to-action or do-not-act bias.
+- Independent tool calls can run in parallel; this is steerable ("make all independent calls in parallel" / "execute sequentially").
+- Prefer general guidance over aggressive over-prompting ("Use this tool when..." beats "CRITICAL: you MUST..."). Over-instruction causes overtriggering.
+- Self-check: "Before you finish, verify your answer against the criteria" catches errors; ask for it only when quality demands it.
+- Guard rails for agents: confirm before irreversible or shared-system actions; avoid over-engineering (only requested changes, no speculative abstractions); investigate files before answering (never speculate about unread code); write general solutions, don't hardcode to tests.
+- Subagents: use for parallelizable, context-isolated workstreams; work directly for simple sequential tasks.
+
+## Skill and instruction authoring
+
+- **Concise is key** — the context window is a public good. Only add context the model doesn't already have; make every paragraph justify its tokens.
+- **Set degrees of freedom** to match fragility: high freedom (heuristics) for flexible tasks; low freedom (exact scripts, "do not modify this command") for fragile operations.
+- **Descriptions drive selection**: third person, what it does + when to use it, with specific trigger terms. Avoid vague names (`helper`, `utils`) and vague descriptions.
+- **Progressive disclosure**: overview in the main file; details in separately linked files, one level deep (nested references cause partial reads). Table of contents for files over 100 lines.
+- **Workflows and feedback loops**: numbered steps with copy-paste checklists for complex tasks; validate → fix → repeat loops for quality-critical operations; create verifiable intermediate outputs before destructive or batch operations.
+- **Stability**: no time-sensitive information; consistent terminology (pick one term per concept); avoid Windows-style paths — always forward slashes.
+- **Provide a default, not a menu**: one recommended approach with an escape hatch for exceptions, not five equivalent options.
+
+## Iteration
+
+- Test with real tasks and observe how the instructions are actually navigated; iterate on observed failures, not assumptions.
+- Build evaluations before extensive documentation: identify gaps, write minimal instructions to close them, measure against baseline.

package/assets/references/skills.md

@@ -0,0 +1,57 @@
+# OpenCode skills — fundamentals
+
+Skills are reusable instruction packages discovered on-demand via the native `skill` tool. Agents see each skill's name and description in `<available_skills>` and load the full SKILL.md only when relevant.
+
+Locations (one folder per skill):
+
+- Project: `.opencode/skills/<name>/SKILL.md`
+- Global: `~/.config/opencode/skills/<name>/SKILL.md`
+- Compatible paths: `.claude/skills/<name>/SKILL.md`, `.agents/skills/<name>/SKILL.md` (project and home variants)
+
+## Frontmatter rules
+
+Only these fields are recognized; unknown fields are ignored:
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `name` | yes | 1–64 chars, lowercase alphanumeric with single hyphens (`^[a-z0-9]+(-[a-z0-9]+)*$`), no leading/trailing `-`, no `--`, must match the folder name. |
+| `description` | yes | 1–1024 chars. Third person; state what the skill does AND when to use it. This drives skill selection — be specific and include key trigger terms. |
+| `license` | no | e.g. `MIT`. |
+| `compatibility` | no | e.g. `opencode`. |
+| `metadata` | no | String-to-string map. |
+
+If a skill does not show up: verify `SKILL.md` capitalization, required frontmatter, unique names across locations, and that permissions don't `deny` it.
+
+## Progressive disclosure
+
+- Metadata (name + description) is pre-loaded at startup; the body is read on demand; bundled files are read only as needed — no context penalty until accessed.
+- Keep SKILL.md under ~500 lines; split deeper content into separate files.
+- Default assumption: the model is already smart — only add context it doesn't have.
+
+## Co-located references pattern
+
+Bundle detail files next to SKILL.md in the skill folder:
+
+```
+my-skill/
+├── SKILL.md          # overview + navigation (loaded when triggered)
+├── reference.md      # loaded as needed
+├── examples.md       # loaded as needed
+└── scripts/tool.py   # executed, not loaded
+```
+
+- Keep references **one level deep** from SKILL.md — nested references cause partial reads. Link each file directly from SKILL.md.
+- Add a table of contents at the top of reference files over 100 lines.
+- Make execution intent explicit: "Run `scripts/foo.py`" (execute) vs "See `scripts/foo.py`" (read as reference).
+
+## Base-directory convention
+
+Address co-located files **relative to the skill's own directory** (its base directory), always with **forward slashes** (`reference/guide.md`, not `reference\guide.md` or absolute paths). Forward-slash relative paths work on every platform.
+
+## Authoring quick rules
+
+- Set degrees of freedom to match fragility: exact scripts for critical/fragile operations, heuristics for flexible tasks.
+- Provide workflows as numbered steps with checklists; add feedback loops (validate → fix → repeat) for quality-critical tasks.
+- No time-sensitive information; use consistent terminology throughout; avoid offering many equivalent options — pick a default with an escape hatch.
+- Gerund names read well (`processing-pdfs`); avoid vague names (`helper`, `utils`).
+- Gate access with `permission.skill` glob patterns (`"internal-*": "deny"`); disable entirely with `tools: { skill: false }`.

package/assets/references/tools.md

@@ -0,0 +1,49 @@
+# OpenCode tools — fundamentals
+
+By default all tools are enabled and need no permission to run. Control them via the `permission` config (global or per agent).
+
+## Built-in tools
+
+| Tool | Purpose | Permission key |
+| --- | --- | --- |
+| `bash` | Execute shell commands | `bash` |
+| `read` | Read files (supports line ranges) | `read` |
+| `edit` | Exact string replacement in files | `edit` |
+| `write` | Create/overwrite files | `edit` |
+| `apply_patch` | Apply patch files | `edit` |
+| `grep` | Regex content search | `grep` |
+| `glob` | File pattern matching | `glob` |
+| `skill` | Load a SKILL.md | `skill` |
+| `todowrite` | Task lists (disabled for subagents by default) | `todowrite` |
+| `webfetch` | Fetch a URL | `webfetch` |
+| `websearch` | Web search (provider/env gated) | `websearch` |
+| `question` | Ask the user structured questions | `question` |
+| `lsp` | LSP intelligence (experimental) | `lsp` |
+
+`edit`, `write`, and `apply_patch` share the single `edit` permission. `grep`/`glob` use ripgrep and respect `.gitignore` (a `.ignore` file can re-include paths). Hooks must check `input.tool === "apply_patch"` and use `output.args.patchText` (paths embedded in marker lines).
+
+## Custom tools
+
+Defined in `.opencode/tools/` (project) or `~/.config/opencode/tools/` (global). The filename becomes the tool name (`database.ts` → `database` tool).
+
+```ts
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Query the project database",
+  args: {
+    query: tool.schema.string().describe("SQL query to execute"),
+  },
+  async execute(args, context) {
+    return `Executed: ${args.query}`
+  },
+})
+```
+
+Key API points:
+
+- `tool.schema` is Zod (`tool.schema.string()`, `.number()`, `.describe(...)`); or import `zod` directly and export a plain object.
+- `execute(args, context)` — context provides `agent`, `sessionID`, `messageID`, `directory` (session cwd), `worktree` (git worktree root). Use `context.worktree` for repo-root paths.
+- Multiple named exports in one file become separate tools named `<filename>_<exportname>` (`math_add`, `math_multiply`).
+- A custom tool with a built-in tool's name overrides it (prefer unique names; use permissions to just disable).
+- The definition is TS/JS, but `execute` can invoke scripts in any language (e.g. via `Bun.$`).

package/index.ts

@@ -1,120 +1,21 @@
-import type { Plugin, PluginInput } from "@opencode-ai/plugin";
-import { readFile } from "node:fs/promises";
+import type { Plugin } from "@opencode-ai/plugin";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import type { AgentConfig } from "@opencode-ai/sdk";
-import { command as syncDocsCommand } from "./commands/sync-docs";
-import { OpenCodeDocsFetcher } from "./scripts/fetch-opencode-docs";
-import { SilentLogger } from "./scripts/logger";
-import { createSyncDocsTool } from "./tools/sync-docs";
+import { AgentLoader } from "./agent-loader";
 
 const AGENTS_DIR = path.join(import.meta.dirname, "assets", "agents");
 
-const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
-
-interface AgentFrontmatter {
-  description: string;
-  mode: "primary" | "subagent" | "all";
-  tools?: Record<string, boolean>;
-  permission?: {
-    edit?: "ask" | "allow" | "deny";
-    bash?: ("ask" | "allow" | "deny") | Record<string, "ask" | "allow" | "deny">;
-    webfetch?: "ask" | "allow" | "deny";
-    doom_loop?: "ask" | "allow" | "deny";
-    external_directory?: "ask" | "allow" | "deny";
-  };
-}
-
-async function parseAgentMarkdown(content: string, agentName: string): Promise<AgentConfig> {
-  const match = content.match(FRONTMATTER_REGEX);
-
-  if (!match || match.length < 3) {
-    throw new Error(`Agent ${agentName} must have YAML frontmatter`);
-  }
-
-  const frontmatterYaml = match[1] as string;
-  const rawPrompt = match[2] as string;
-  const frontmatter = parseYaml(frontmatterYaml) as AgentFrontmatter;
-  const prompt = rawPrompt.replace(/^\r?\n/, "");
-
-  const config: AgentConfig = {
-    description: frontmatter.description,
-    mode: frontmatter.mode,
-    prompt,
-  };
-
-  if (frontmatter.tools) {
-    config.tools = frontmatter.tools;
-  }
-
-  if (frontmatter.permission) {
-    config.permission = frontmatter.permission;
-  }
-
-  return config;
-}
-
-const OpencodeArchitect: Plugin = async (input) => {
-  const syncDocsTool = createSyncDocsTool();
-
-  syncDocsOnStartup(input.client);
-
-  const agents = await loadAgents();
+const OpencodeArchitect: Plugin = async () => {
+  const agents = await new AgentLoader(AGENTS_DIR).loadAgents();
 
   return {
     config: async (config) => {
       config.agent = config.agent || {};
-      config.command = config.command || {};
 
       for (const [name, agentConfig] of Object.entries(agents)) {
         config.agent[name] = agentConfig;
       }
-
-      config.command["sync-docs"] = syncDocsCommand;
-    },
-    tool: {
-      "sync-docs": syncDocsTool,
     },
   };
 };
 
 export default OpencodeArchitect;
-
-async function loadAgents(): Promise<Record<string, AgentConfig>> {
-  const agentFiles = [
-    "opencode-agent-designer.md",
-    "opencode-architect.md",
-    "opencode-command-crafter.md",
-    "opencode-extension-auditor.md",
-    "opencode-packager.md",
-    "opencode-publisher.md",
-    "opencode-mcp-integrator.md",
-    "opencode-plugin-engineer.md",
-    "opencode-skill-creator.md",
-    "opencode-tool-builder.md",
-  ];
-
-  const agents: Record<string, AgentConfig> = {};
-
-  for (const filename of agentFiles) {
-    const agentPath = path.join(AGENTS_DIR, filename);
-    const agentContent = await readFile(agentPath, "utf-8");
-    const agentName = path.basename(filename, ".md");
-    agents[agentName] = await parseAgentMarkdown(agentContent, agentName);
-  }
-
-  return agents;
-}
-
-function syncDocsOnStartup(client: PluginInput["client"]): void {
-  const fetcher = new OpenCodeDocsFetcher(new SilentLogger());
-  fetcher.run().catch((error: unknown) => {
-    const message = error instanceof Error ? error.message : String(error);
-    client.tui.showToast({
-      body: {
-        message: `Failed to sync OpenCode docs: ${message}`,
-        variant: "error",
-      },
-    });
-  });
-}

package/package.json

@@ -1,39 +1,41 @@
 {
   "name": "opencode-architect",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "module": "index.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/diegohb/opencode-architect.git"
+    "url": "git+https://github.com/Expert-Vision-Software/opencode-architect.git"
   },
+  "homepage": "https://github.com/Expert-Vision-Software/opencode-architect#readme",
   "publisher": "Expert Vision Software",
   "author": "Expert Vision Support <support@expertvision.software>",
   "bugs": {
-    "url": "https://github.com/diegohb/opencode-architect/issues",
+    "url": "https://github.com/Expert-Vision-Software/opencode-architect/issues",
     "email": "support@expertvision.software"
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "test": "bun test",
     "release": "npm version patch && npm publish && git push --follow-tags"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "index.ts",
-    "tools",
-    "commands",
-    "scripts",
+    "agent-loader.ts",
     "assets"
   ],
   "dependencies": {
-    "yaml": "^2.7.1"
+    "yaml": "^2.7.1",
+    "@opencode-ai/plugin": "*"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "latest",
     "@opencode-ai/sdk": "latest",
-    "@types/bun": "latest"
-  },
-  "peerDependencies": {
-    "typescript": "^5"
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "typescript": "latest"
   }
 }

package/commands/sync-docs.ts

@@ -1,9 +0,0 @@
-import type { Config } from "@opencode-ai/sdk";
-
-export const command: NonNullable<Config["command"]>[string] = {
-  description: "Sync OpenCode docs into ~/.cache/opencode/opencode-architect/docs",
-  template:
-    "Use the sync-docs tool to fetch the latest OpenCode documentation into `~/.cache/opencode/opencode-architect/docs`.",
-};
-
-export default command;

package/scripts/fetch-opencode-docs.ts

@@ -1,193 +0,0 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-
-import type { Logger } from "./logger";
-import { ConsoleLogger } from "./logger";
-
-interface ExternalDoc {
-  url: string;
-  filename: string;
-}
-
-export class OpenCodeDocsFetcher {
-  private readonly sitemapUrl: string;
-  private readonly docsDir: string;
-  private readonly externalDocs: ExternalDoc[];
-  private readonly logger: Logger;
-
-  public constructor(logger: Logger | null = null) {
-    this.sitemapUrl = "https://opencode.ai/sitemap.xml";
-    this.docsDir = path.join(
-      os.homedir(),
-      ".cache",
-      "opencode",
-      "opencode-architect",
-      "docs",
-    );
-    this.logger = logger ?? new ConsoleLogger();
-    this.externalDocs = [
-      {
-        url: "https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md",
-        filename: "claude-skill-best-practices.md",
-      },
-      {
-        url: "https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices.md",
-        filename: "claude-4-best-practices.md",
-      },
-    ];
-  }
-
-  public async run(): Promise<void> {
-    try {
-      await this.ensureDocsDir();
-      const sitemap = await this.fetchText(this.sitemapUrl);
-      const docUrls = this.extractDocUrls(sitemap);
-      const markdownUrls = this.buildMarkdownUrls(docUrls);
-      await this.downloadDocs(markdownUrls);
-      await this.downloadExternalDocs();
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      this.logger.error(`Failed to fetch OpenCode docs: ${message}`);
-      process.exitCode = 1;
-    }
-  }
-
-  private async ensureDocsDir(): Promise<void> {
-    await mkdir(this.docsDir, { recursive: true });
-  }
-
-  private async fetchText(url: string): Promise<string> {
-    const response = await fetch(url, {
-      headers: {
-        "User-Agent": "opencode-docs-fetcher",
-      },
-    });
-    if (!response.ok) {
-      throw new Error(`Request failed (${response.status}) for ${url}`);
-    }
-    return await response.text();
-  }
-
-  private extractDocUrls(sitemap: string): string[] {
-    const urls: string[] = [];
-    const regex = /<loc>([^<]+)<\/loc>/g;
-    let match: RegExpExecArray | null = regex.exec(sitemap);
-    while (match) {
-      const url = match[1];
-      if (url !== undefined) {
-        try {
-          const parsed = new URL(url);
-          if (parsed.pathname.startsWith("/docs/")) {
-            urls.push(url);
-          }
-        } catch {
-          continue;
-        }
-      }
-      match = regex.exec(sitemap);
-    }
-    return Array.from(new Set(urls));
-  }
-
-  private buildMarkdownUrls(urls: string[]): string[] {
-    const markdownUrls: string[] = [];
-    for (const url of urls) {
-      const parsed = new URL(url);
-      if (!parsed.pathname.startsWith("/docs/")) {
-        continue;
-      }
-      const normalizedPath = this.normalizeDocPath(parsed.pathname);
-      if (normalizedPath === "/docs") {
-        continue;
-      }
-      const markdownUrl = `${parsed.origin}${normalizedPath}.md`;
-      markdownUrls.push(markdownUrl);
-    }
-    return Array.from(new Set(markdownUrls));
-  }
-
-  private normalizeDocPath(pathname: string): string {
-    if (pathname.endsWith("/")) {
-      return pathname.slice(0, -1);
-    }
-    return pathname;
-  }
-
-  private async downloadDocs(urls: string[]): Promise<void> {
-    let successCount = 0;
-    let failureCount = 0;
-    for (const url of urls) {
-      try {
-        const content = await this.fetchText(url);
-        const filename = this.buildFilename(url);
-        const filePath = path.join(this.docsDir, filename);
-        await writeFile(filePath, content);
-        successCount += 1;
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        this.logger.error(`Failed to fetch ${url}: ${message}`);
-        failureCount += 1;
-      }
-    }
-
-    this.logger.info(
-      `OpenCode docs fetch complete. Success: ${successCount}, Failed: ${failureCount}.`,
-    );
-  }
-
-  private async downloadExternalDocs(): Promise<void> {
-    let successCount = 0;
-    let failureCount = 0;
-    for (const doc of this.externalDocs) {
-      try {
-        const content = await this.fetchText(doc.url);
-        const filePath = path.join(this.docsDir, doc.filename);
-        await writeFile(filePath, content);
-        successCount += 1;
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        this.logger.error(`Failed to fetch ${doc.url}: ${message}`);
-        failureCount += 1;
-      }
-    }
-
-    this.logger.info(
-      `External docs fetch complete. Success: ${successCount}, Failed: ${failureCount}.`,
-    );
-  }
-
-  private buildFilename(url: string): string {
-    const parsed = new URL(url);
-    const pathname = parsed.pathname;
-    if (pathname === "/docs.md" || pathname === "/docs/.md") {
-      return "index.md";
-    }
-
-    let relative = pathname;
-    if (relative.startsWith("/docs/")) {
-      relative = relative.slice("/docs/".length);
-    } else if (relative.startsWith("/docs")) {
-      relative = relative.slice("/docs".length);
-    }
-
-    if (relative.startsWith("/")) {
-      relative = relative.slice(1);
-    }
-
-    if (relative.length === 0) {
-      return "index.md";
-    }
-
-    const normalized = relative.replace(/\//g, "-");
-    if (normalized.endsWith(".md")) {
-      return normalized;
-    }
-    return `${normalized}.md`;
-  }
-
-}
-
-if (import.meta.main) {
-  void new OpenCodeDocsFetcher().run();
-}

package/scripts/logger.ts

@@ -1,20 +0,0 @@
-export interface Logger {
-  info(message: string): void;
-  error(message: string): void;
-}
-
-export class ConsoleLogger implements Logger {
-  public info(message: string): void {
-    console.log(message);
-  }
-
-  public error(message: string): void {
-    console.error(message);
-  }
-}
-
-export class SilentLogger implements Logger {
-  public info(_message: string): void {}
-
-  public error(_message: string): void {}
-}

package/tools/sync-docs.ts

@@ -1,24 +0,0 @@
-import { tool } from "@opencode-ai/plugin";
-
-import { OpenCodeDocsFetcher } from "../scripts/fetch-opencode-docs";
-
-type ToolDefinition = ReturnType<typeof tool>;
-
-function createSyncDocsTool(): ToolDefinition {
-  return tool({
-    description: "Sync OpenCode documentation by fetching the latest docs from opencode.ai",
-    args: {},
-    async execute(_args, _context) {
-      try {
-        const fetcher = new OpenCodeDocsFetcher();
-        await fetcher.run();
-        return "Successfully synced OpenCode documentation.";
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return `Failed to sync docs: ${message}`;
-      }
-    },
-  });
-}
-
-export { createSyncDocsTool };