<critical_rules priority="highest"> ALWAYS request approval before ANY execution NEVER auto-fix issues without explicit user approval STOP immediately on test failure Confirm before cleaning up files </critical_rules>
<external_file_loading policy="lazy"> When encountering file references (e.g., @references/workflow.md), use Read tool on demand. Loaded content overrides defaults. Follow references recursively when needed. </external_file_loading>
<context_hierarchy> <system_context>OpenCode plugin bundling specialized agents and utilities</system_context> <domain_context>Architecture, agent design, command crafting, MCP integration, plugin engineering, skill creation, tool building</domain_context> <task_context>Meta-project producing instructions consumed by OTHER agents in end-users' projects</task_context> <execution_context>TypeScript with Bun native TS support, ESM output</execution_context> </context_hierarchy>
opencode-architect plugin Agent orchestration, plugin registration, command/tool exposure Creating and distributing OpenCode extensions (skills, commands, agents, plugins, tools) Copy transparency for skills/commands/agents; TypeScript plugins and plugin-registered tools in package<product_overview> <entry_point>index.ts</entry_point> <auto_init>agent, skill, and command registration from bundled assets on startup</auto_init> <build_output>ESM + type declarations</build_output> </product_overview>
<happy_path>
- User creates extensions via delegation to specialist agents
- skill-creator, command-crafter, agent-designer, plugin-engineer, tool-builder, mcp-integrator
- Default outputs: .opencode/skills/<name>/SKILL.md, .opencode/commands/<name>.md, .opencode/agents/<name>.md; custom tools and plugins are Effect-first plugin code in .opencode/plugin/<name>.ts (or plugins/) — v2 has no file-based tool definition
- User refines extensions based on usage feedback
- Project-local extensions stop here: no packaging required
- Delegate to opencode-packager
- Extracts .opencode/ content to package-root skills//commands//agents/ (no assets/ wrapper), placed in this workspace (default) or a sibling ../opencode-<name>/ directory; creates a default-only index.ts, the Effect-first plugin definition in src/plugin.ts, package.json (declaring exports["./server"]), tsconfig.json
- Delegate to opencode-publisher, fed by the packager's output
- Transforms to npm-ready structure, adds CLI entry point, extracts installer module
- Delegate from architect to the bundled opencode-v2-upgrade skill
- Inventories extensions, ports v1 plugin code and v1 tool files, rewrites configs to v2-native keys, and reports v2 recommendations; no-ops on already-v2 projects, skips consumer-modified files, and never touches the OpenCode app installation
</happy_path>
<agent_categories> skill-creator, command-crafter, agent-designer .opencode/ plugin-engineer, tool-builder, mcp-integrator .opencode/ packager, publisher New package directory architect Delegates to others </agent_categories>
<design_principles>
- Skills, commands, agents COPIED to consumer's .opencode/ (not via config.skills.paths)
- End-users can see, read, modify extension content locally
- Plugins and plugin-registered tools remain as TypeScript in package
- Custom plugin code in .opencode/plugin/ or .opencode/plugins/ requires merge decisions during packaging
- Packager delegates to opencode-plugin-engineer for guidance
</design_principles>
<file_structure_conventions>
- Keep agents, tools, commands focused and cohesive
- Wire new agents/commands through plugin entry for runtime availability </file_structure_conventions>
GitHub Issues at Expert-Vision-Software/opencode-architect, accessed via the gh CLI. See docs/agents/issue-tracker.md.
Default vocabulary — the five canonical role names used as-is. See docs/agents/triage-labels.md.
Single-context: root CONTEXT.md + docs/adr/. See docs/agents/domain.md.
Ship via tag push only — GitHub Actions publishes to npm. Never run npm publish locally. See docs/agents/release.md.