opencode-architect 0.2.4 → 0.4.0

package/README.md

@@ -1,10 +1,18 @@
 # opencode-architect
 
-OpenCode, supercharged. ⚡
+[![npm version](https://img.shields.io/npm/v/opencode-architect)](https://www.npmjs.com/package/opencode-architect)
+[![License: MIT](https://img.shields.io/npm/l/opencode-architect)](./LICENSE.md)
+[![OpenCode plugin](https://img.shields.io/badge/opencode-plugin-blueviolet)](https://opencode.ai/docs/plugins)
 
-## To Install 🔌
+**Ten specialist agents that design, build, and package OpenCode extensions — agent skills, slash commands, custom tools, plugins, and MCP server integrations — right inside your AI coding assistant.**
 
-Add to "plugin" in `.opencode/opencode.json`:
+opencode-architect is an [OpenCode](https://opencode.ai) plugin and CLI that ships a suite of AI agent experts for OpenCode work: designing agents, creating skills and slash commands, building plugins and custom tools, integrating MCP servers, and packaging extensions for npm. Install it once and every specialist agent is available in your coding sessions.
+
+## Quick start: install the OpenCode plugin suite
+
+### Option 1 — Install as an OpenCode plugin
+
+Add the package to the `plugin` array in your OpenCode config — `.opencode/opencode.json` in your project, or `~/.config/opencode/opencode.json` for all projects:
 
 ```json
 {
@@ -12,27 +20,73 @@ Add to "plugin" in `.opencode/opencode.json`:
 }
 ```
 
-## Why this exists ✨
+The plugin registers the full agent suite at startup, with self-contained bundled references — no network sync.
+
+### Option 2 — Install with the CLI (bunx or npx)
+
+Copy the agents, references, and templates straight into your OpenCode directories, where you can read and modify every file:
+
+```bash
+# Project scope (default): copies into ./.opencode/
+bunx opencode-architect install
+
+# Global scope: copies into ~/.config/opencode/
+bunx opencode-architect install --scope global
+```
+
+`npx opencode-architect install` works the same way if you prefer npm's runner.
+
+Useful flags and commands:
+
+```bash
+bunx opencode-architect status                  # show install mode and version for a scope
+bunx opencode-architect uninstall               # remove exactly the files a copy install wrote
+bunx opencode-architect install --force         # overwrite locally modified files, switch a scope from plugin to copy install
+bunx opencode-architect --help                  # full usage
+```
+
+A copy install writes 10 agents into `agents/`, 9 reference docs into `opencode-architect/references/`, and 9 starter templates into `opencode-architect/templates/` of the scope base, plus an `opencode-architect.json` manifest that tracks versions and file hashes for safe upgrades. Relative reference paths inside agents are rewritten to absolute paths at install time.
+
+Plugin install and copy install are mutually exclusive per scope — the CLI refuses to copy over an existing plugin entry unless you pass `--force`.
+
+## What you get: ten specialist OpenCode agents
+
+Ten specialist agents, one router:
 
-Use this package any time you are doing OpenCode work: designing agents, building plugins, crafting commands, creating skills and tools, or integrating MCP servers.
+| Agent | What it does |
+| --- | --- |
+| `opencode-architect` | Routes OpenCode meta tasks to the right specialist — agents, skills, commands, tools, plugins, MCP setup, packaging, publishing |
+| `opencode-agent-designer` | Designs OpenCode agents and orchestrator subagents — roles, constraints, tools, permissions |
+| `opencode-skill-creator` | Creates OpenCode skills in `.opencode/skills` — SKILL.md, frontmatter, progressive disclosure |
+| `opencode-command-crafter` | Creates OpenCode slash commands in `.opencode/commands` — prompt templates, `$ARGUMENTS`, frontmatter |
+| `opencode-tool-builder` | Creates OpenCode custom tools in `.opencode/tools` — Zod schemas and execute logic |
+| `opencode-plugin-engineer` | Builds OpenCode plugins in `.opencode/plugins` — event hooks, custom tools, TypeScript |
+| `opencode-mcp-integrator` | Configures MCP servers and tool scoping in `opencode.json` — local/remote servers, permissions |
+| `opencode-packager` | Packages OpenCode extensions for local sharing across projects — `file:///` plugin packages |
+| `opencode-publisher` | Publishes OpenCode extensions to npm — transforms local packages into distributable ones |
+| `opencode-extension-auditor` | Analyzes `.opencode/` contents and reports packaging readiness — inventory, dependencies, complications |
 
-## What you get 🧰
+Also bundled and installed with the agents:
 
-- 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
-- Built-in alignment with OpenCode best practices for coding and prompt engineering
+- **References** — self-contained docs covering stable OpenCode fundamentals: agents, commands, config, MCP servers, plugins, prompt engineering, skills, tools, plus worked one-shot examples
+- **Templates** — starter files for new skills, plugins, package manifests, and TypeScript configs
 
-## Best time to use it ✅
+## When to use these OpenCode agents
 
-Use it whenever you want to:
+Reach for opencode-architect whenever you want to:
 
-- Spin up new OpenCode agents
-- Design or refine OpenCode plugins and commands
-- Create skills and tools with consistent prompt engineering
-- Integrate MCP servers with confidence
+- Spin up new OpenCode agents with consistent frontmatter and tool permissions
+- Create agent skills and slash commands with solid prompt engineering
+- Build OpenCode plugins and custom tools in TypeScript
+- Integrate MCP servers into your OpenCode setup with confidence
+- Package and publish your extensions so other developers can install them
 
-## Contributing 🤝
+## Requirements
+
+- [OpenCode](https://opencode.ai) — the AI coding assistant the plugin extends
+- [Bun](https://bun.sh) — runs the plugin and the CLI (`bunx`); if you use `npx`, Bun must still be on your `PATH` because the CLI ships as TypeScript
+
+## Development
 
 Install dependencies:
 
@@ -46,7 +100,13 @@ Type check:
 bun run check
 ```
 
-## Acknowledgements 🙏
+Run the test suite:
+
+```bash
+bun test
+```
+
+## Acknowledgements
 
 - [OpenCode](https://opencode.ai) - The AI coding assistant that makes this plugin possible
 - [Bun](https://bun.sh) - The fast all-in-one JavaScript runtime

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]*)$/;
+export 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

@@ -1,5 +1,5 @@
 ---
-description: Designs OpenCode agents and orchestrator subagents
+description: Designs OpenCode agents and orchestrator subagents - roles, constraints, tools, permissions
 mode: subagent
 tools:
   read: true
@@ -10,53 +10,19 @@ tools:
   bash: false
 ---
 
-If available, prefer Exa MCP over default websearch tools. If available, prefer grepai MCP over default codebase search tools.
+Prefer Exa MCP over default websearch tools and grepai MCP over default codebase search tools, when available.
 
-You create or refine OpenCode agents in '.opencode/agents/' as Markdown with YAML frontmatter. Focus on clear roles, crisp constraints, and correct tool permissions.
+You create or refine OpenCode agents in `.opencode/agents/` as Markdown with YAML frontmatter; the filename becomes the agent name.
 
-Agent essentials
+## Workflow
 
-- Frontmatter fields: description (required), mode (primary or subagent), model, temperature, maxSteps, tools, permission, hidden.
-- The filename becomes the agent name.
-- Default mode is all if not specified, but set it explicitly.
-- Subagents should be focused and scoped to one job.
-- Do not set a model by default unless explicitly requested.
+1. Read `../references/prompt-engineering.md` for prompt-engineering techniques before drafting anything.
+2. Consult `../references/agents.md` for agent fields, modes, tools, and permissions; `../references/tools.md` for tool IDs and behavior; `../references/config.md` for config precedence and defaults.
+3. Write the frontmatter: description (required), mode (primary or subagent - set it explicitly), model (only when the user names one), temperature, maxSteps, tools, permission, hidden, as needed.
+4. Write the prompt in this order: role and scope boundaries first, then expected inputs and output format, then direct, specific instructions.
+5. Reinforce the instructions where they fit: structure with headings and lists, critical instructions at the end, examples for ambiguous tasks and output formats, explicit constraints, structured outputs (JSON, XML) where precise parsing is needed, reasoning prompts for multi-step tasks, persistent context and persona for primary agents.
+6. Scope capability to the job: tools block enables or disables specific tools, permission gates edit, bash, or webfetch, permission.task limits which subagents run, and the prompt scans no wider than the job requires.
+7. For a new agent, add one line describing it to `.opencode/AGENTS.md`.
+8. Verify: fields valid per the references, role stated in one sentence, inputs and output format defined.
 
-Tools and permissions
-
-- tools block enables or disables specific tools.
-- permission can deny or ask for edit, bash, or webfetch.
-- task permissions can scope which subagents are allowed.
-
-Prompt design
-
-- Declare role and what the agent must not do.
-- Define inputs expected and output format.
-- Keep instructions concise and actionable.
-- Avoid repo-wide scans unless required.
-
-Prompting best practices
-
-- Put critical instructions at the end of the prompt for emphasis.
-- Use markdown structure (headings, lists) for complex prompts.
-- Be direct and specific rather than verbose; Claude 4 handles terse instructions well.
-- Provide examples for ambiguous tasks or desired output formats.
-- Use system prompts to establish persistent context and persona.
-- Set explicit constraints and boundaries to scope agent behavior.
-- Leverage structured outputs (JSON, XML) when precise parsing is needed.
-- Include thinking or reasoning prompts for multi-step tasks.
-
-Deliverables
-
-- Create or update the agent file.
-- If adding a new agent, add a short line to '.opencode/AGENTS.md' describing it.
-
-Docs 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.
-
-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.
+Done when the agent file loads with valid frontmatter and a prompt that names role, inputs, and output format.