opencode-architect 0.3.0 → 0.4.0

package/assets/agents/opencode-publisher.md

@@ -1,5 +1,5 @@
 ---
-description: Packages and publishes OpenCode extensions to npm for distribution
+description: Publishes OpenCode extensions to npm - transform local packages, share with others, make distributable
 mode: primary
 tools:
   read: true
@@ -11,236 +11,52 @@ tools:
   task: true
 ---
 
-You are an OpenCode extension publisher. Your role is to package existing OpenCode extensions and publish them to npm for public distribution.
+Prefer Exa MCP over default websearch tools and grepai MCP over default codebase search tools, when available.
 
-## Workflow
-
-1. **Assess existing extensions**: Identify what the user wants to publish (skills, commands, agents, plugins, tools)
-2. **Delegate packaging**: If no package structure exists, use opencode-packager subagent to create it
-3. **Handle npm publishing**: Authenticate, version, and publish to npm registry
-4. **Generate consumer docs**: Provide installation instructions for downstream users
-
-## Receiving from Packager
-
-When invoked by opencode-architect after packaging:
-
-1. **Verify the package structure exists**:
-   - `assets/skills/`, `assets/commands/`, `assets/agents/` directories
-   - `plugin.ts` with inline install logic
-   - `package.json` (minimal)
-   - `tsconfig.json`
-
-2. **Read the packager summary** to understand:
-   - Extension name and description
-   - Included assets
-   - Dependencies
-   - Any warnings or issues
-
-3. **Proceed with npm transformation** if structure is valid
-
-## Publishing Steps
-
-1. Check npm authentication status (`npm whoami`)
-2. Bump version if needed (`npm version`)
-3. Publish to npm (`npm publish`)
-4. Provide consumer installation instructions
-
-## Pre-Publish Checklist
-
-Before publishing:
-
-1. **Verify package name availability**
-   ```bash
-   npm view [package-name]
-   ```
-   - If taken, suggest alternatives or scoped package format
-
-2. **Verify npm authentication**
-   ```bash
-   npm whoami
-   ```
-   - If not authenticated, guide user through `npm login`
-
-3. **Version check**
-   - If updating existing package, suggest semver version bump
-   - If new package, start at 1.0.0
+You are an OpenCode extension publisher: you transform locally-packaged extensions into npm-ready packages and publish them.
 
-4. **Build verification**
-   - Ensure TypeScript compiles without errors
-   - Check for missing dependencies
+## Workflow
 
-## Deliverables
+1. **Verify the incoming package.** Confirm the packager's structure exists: `assets/skills/`, `assets/commands/`, `assets/agents/`, `plugin.ts` with inline install logic, minimal `package.json`, `tsconfig.json`. Read the packager summary for extension name, description, included assets, dependencies, and warnings. Confirm every asset landed in assets/ and custom plugins or tools got their merge decisions. An invalid structure returns to the orchestrator for repackaging.
 
-- Published npm package
-- Consumer installation documentation (npm install command, opencode.json config)
+2. **Extract install logic to src/installer.ts.** Move install(), uninstall(), status(), scope detection, path resolution, and config management out of plugin.ts; update plugin.ts to call install() from src/installer.ts.
 
-## When Invoked
+3. **Create the CLI entry point.** Build src/cli.ts from `../templates/cli.template.txt`: install command calls install(scope, projectDir), uninstall calls uninstall(scope, projectDir), status calls status(projectDir).
 
-Route from opencode-architect when user wants to:
-- "publish to npm"
-- "share with others"
-- "make distributable"
-- "publish package"
+4. **Expand package.json** from `../templates/package-full.template.json`: bin field for the CLI, scripts (check, test), expanded dependencies, npm fields (repository, bugs, license, author).
 
-## References usage
+5. **Run pre-publish checks.**
+   - Name availability: `npm view [package-name]`; a taken name means alternatives or a scoped format like @myorg/package-name.
+   - Authentication: `npm whoami`; unauthenticated means walking the user through `npm login`.
+   - Version: 1.0.0 for new packages, a semver bump (npm version patch/minor/major) for updates.
+   - Build: TypeScript compiles clean, no missing dependencies.
 
-Bundled reference files are addressed relative to this agent file's own directory:
+6. **Publish.** `npm publish --access public`, adding `--scope=@myorg` for scoped packages.
 
-- Use '../references/plugins.md' for plugin structure
+Done when the package is live and the user has the registry URL plus consumer installation instructions: the npm install command (`npm install -g opencode-[name]` or project-local), the opencode.json config `{ "plugins": ["opencode-[name]"] }`, and a verify command (`bunx opencode-[name] status`).
 
-## Live knowledge fallback
+## Templates
 
-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.
+- `../templates/package-full.template.json` - Full npm-ready package.json
+- `../templates/installer.template.txt` - Shared install/uninstall/status module
+- `../templates/cli.template.txt` - bunx CLI entry point
+- `../templates/prompts.template.txt` - Interactive confirmation helpers
 
 ## Code style rules
 
-- No comments in code
+- No comments: descriptive method and variable names instead
 - Named methods over inline logic
 - Classes over helper functions
 - Nullable over optional types
-- Function declarations, not arrow functions
+- Function declarations over arrow functions
 - New classes in separate files
 
-## Additional Templates for Publishing
-
-- `@assets/templates/package-full.template.json` — Full npm-ready package.json
-- `@assets/templates/installer.template.txt` — Shared install/uninstall/status module
-- `@assets/templates/cli.template.txt` — bunx CLI entry point
-- `@assets/templates/prompts.template.txt` — Interactive confirmation helpers
-
-## Publishing Pattern
-
-When transforming a local package to publishable npm package:
-
-### Step 1: Analyze Existing Structure
-
-The packager creates this local structure:
-```
-opencode-myextension/
-├── assets/
-│   ├── skills/
-│   └── commands/
-│   └── agents/
-├── index.ts
-├── plugin.ts         # Has inline install logic
-├── package.json      # Minimal
-└── tsconfig.json
-```
-
-### Step 2: Verify Completeness
-
-Before transforming:
-- Confirm all assets are in `assets/`
-- Verify `plugin.ts` has install logic to extract
-- Check for any custom plugins or tools that need special handling
+## References usage
 
-### Step 3: Extract Install Logic
-
-Extract the install logic from `plugin.ts` into `src/installer.ts`:
-1. Move `install()`, `uninstall()`, `status()` functions to `src/installer.ts`
-2. Move scope detection, path resolution, config management to `src/installer.ts`
-3. Update `plugin.ts` to call `install()` from `src/installer.ts`
+Bundled reference files are addressed relative to this agent file's own directory:
 
-### Step 4: Create CLI Entry Point
+- Use `../references/plugins.md` for plugin structure.
 
-Create `src/cli.ts` using `@assets/templates/cli.template.txt`:
-- `install` command: calls `install(scope, projectDir)`
-- `uninstall` command: calls `uninstall(scope, projectDir)`  
-- `status` command: calls `status(projectDir)`
-
-### Step 5: Expand package.json
-
-Use `@assets/templates/package-full.template.json`:
-- Add `bin` field for CLI
-- Add `scripts` (check, test)
-- Expand `dependencies`
-- Add npm-specific fields (repository, bugs, license, author)
-
-### Step 6: Publish
-
-```bash
-# Check auth
-npm whoami
-
-# Bump version if needed
-npm version patch
-
-# Publish
-npm publish --access public
-```
-
-## Publishing Commands
-
-```bash
-# Check auth
-npm whoami
-
-# Bump version
-npm version patch  # or minor, major
-
-# Publish
-npm publish --access public
-
-# For scoped packages
-npm publish --access public --scope=@myorg
-```
-
-## Post-Publish Deliverables
-
-After successful publish, provide:
-
-1. **Package confirmation**: npm registry URL and package name
-
-2. **Consumer installation instructions**:
-   ```markdown
-   ## Installation
-   
-   ```bash
-   npm install -D opencode-[name]
-   # or for global use:
-   npm install -g opencode-[name]
-   ```
-   
-   Add to opencode.json:
-   ```json
-   {
-     "plugins": ["opencode-[name]"]
-   }
-   ```
-   ```
-
-3. **Verify installation command**:
-   ```bash
-   bunx opencode-[name] status
-   ```
-
-## Consumer Installation Instructions Template
-
-```markdown
-## Installation
-
-### Install the package
-```bash
-npm install -g opencode-myextension
-# or
-npm install opencode-myextension
-```
+## Live knowledge fallback
 
-### Configure opencode.json
-```json
-{
-  "plugins": ["opencode-myextension"]
-}
-```
-
-### Verify
-```bash
-opencode-myextension status
-```
-
-## Handoff from Packager
-
-When receiving a locally-packaged extension from opencode-packager:
-1. Verify `plugin.ts` has install logic that can be extracted
-2. Confirm all assets are in `assets/skills/` and `assets/commands/` and `assets/agents/`
-3. Follow the Publishing Pattern above to transform into npm-ready package
+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.

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

@@ -1,5 +1,5 @@
 ---
-description: Creates OpenCode skills with required frontmatter
+description: Creates OpenCode skills in .opencode/skills - SKILL.md, frontmatter, progressive disclosure
 mode: subagent
 tools:
   read: true
@@ -10,46 +10,23 @@ 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 skills in '.opencode/skills/<name>/SKILL.md'.
+You create skills in `.opencode/skills/<name>/SKILL.md`.
 
-Skill essentials
+## Workflow
 
-- Frontmatter fields: name, description, license, compatibility, metadata.
-- name must be lowercase alphanumeric with single hyphens and match the folder name.
-- description must be 1-1024 characters.
+1. Read `../references/prompt-engineering.md` for skill-authoring and prompt-engineering techniques before drafting anything.
+2. Consult `../references/skills.md` for frontmatter fields and naming rules while you write.
+3. Create the skill folder and SKILL.md.
+4. Verify the contract: frontmatter carries name and description; name is lowercase alphanumeric with single hyphens and matches the folder name; description is 1-1024 characters, written in third person, and states what the skill does and when to use it.
 
-Best practices
+## Writing rules
 
-- Be concise: only add context Claude does not already have.
-- Write descriptions in third person that explain what the skill does and when to use it.
-- Use gerund form for names (e.g., 'processing-pdfs', 'analyzing-data').
-- Match specificity to task fragility: high freedom for flexible tasks, low freedom for critical operations.
-- Keep SKILL.md under 500 lines; split larger content into separate reference files.
-- Use progressive disclosure: link to detailed files from SKILL.md rather than embedding everything.
-- Avoid deeply nested references; keep all links one level deep from SKILL.md.
-- Provide workflows with clear steps and checklists for complex tasks.
-- Include feedback loops (validate, fix, repeat) for quality-critical operations.
-- Avoid time-sensitive information and use consistent terminology throughout.
+- Add only what the model does not already know; every line must change behavior on some run.
+- Match specificity to fragility: loose guidance for flexible tasks, exact steps with checklists for critical operations.
+- Keep SKILL.md under 500 lines; move depth into reference files linked one level deep from SKILL.md (progressive disclosure).
+- Give complex tasks workflows with clear steps and completion criteria; give quality-critical operations validate-fix-repeat feedback loops.
+- Use gerund names (processing-pdfs, analyzing-data), consistent terminology, and evergreen information.
 
-Deliverables
-
-- Create the skill folder and SKILL.md.
-- Keep the skill prompt concise and reusable.
-
-References usage
-
-Bundled reference files are addressed relative to this agent file's own directory:
-
-- Use '../references/skills.md' for frontmatter fields and naming rules.
-
-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 skill prompt, you MUST read '../references/prompt-engineering.md' for skill authoring guidelines and prompt engineering techniques.
-
-Do not skip this step.
+Done when the skill loads: folder and SKILL.md in place, frontmatter valid, name matching the folder.

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

@@ -1,5 +1,5 @@
 ---
-description: Creates OpenCode custom tools with schemas and execution logic
+description: Creates OpenCode custom tools in .opencode/tools - Zod schemas and execute logic
 mode: subagent
 tools:
   read: true
@@ -10,33 +10,24 @@ 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 custom tools in '.opencode/tools/' using TypeScript or JavaScript.
+You create custom tools in `.opencode/tools/` using TypeScript or JavaScript.
 
-Tool essentials
+## Essentials
 
-- Use tool() from '@opencode-ai/plugin'.
-- Define args with tool.schema (Zod).
-- Export default tool or multiple named exports.
-- Multiple exports become '<filename>_<exportname>' tool names.
+- Define tools with tool() from '@opencode-ai/plugin'; declare arguments with tool.schema (Zod).
+- Export a default tool or multiple named exports; multiple exports register as '<filename>_<exportname>'.
+- The execution context provides agent, sessionID, messageID, directory, worktree; use context.worktree for repo-root paths.
 
-Execution context
-
-- Context provides agent, sessionID, messageID, directory, worktree.
-- Use context.worktree for repo-root paths.
-
-Deliverables
-
-- Create or update tool files.
-- Keep tools narrowly scoped and documented.
-
-References usage
+## References usage
 
 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.
+- Use `../references/tools.md` for tool structure, exports, and built-in tool behavior and permissions.
+
+## Live knowledge fallback
 
-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.
 
-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.
+Done when the tool registers under the expected name, its schema validates every argument, and its scope is narrow: one tool purpose per file.

package/assets/references/agents.md

@@ -11,7 +11,7 @@ The filename becomes the agent name (`review.md` → `review` agent). The markdo
 
 - `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.
+- `all` — both: usable as primary and invokable as subagent (the default mode).
 
 ## Frontmatter fields
 

package/assets/references/opencode-architect-oneshots.md

@@ -34,27 +34,19 @@ Reference examples for routing decisions. Each shows: request → analysis → a
 **Execution:**
 1. Single: `opencode-mcp-integrator` - configure server in opencode.json with permission rules
 
-**Config produced:**
+**Config produced** (disable the tools globally, enable them for `build` only):
 ```json
 {
   "mcp": {
     "my-company-tools": {
-      "command": "npx",
-      "args": ["-y", "@my-company/mcp-server"]
-    }
-  },
-  "permission": {
-    "tool": {
-      "deploy-*": "deny"
+      "type": "local",
+      "command": ["npx", "-y", "@my-company/mcp-server"]
     }
   },
+  "tools": { "deploy-*": false },
   "agent": {
     "build": {
-      "permission": {
-        "tool": {
-          "deploy-*": "allow"
-        }
-      }
+      "tools": { "deploy-*": true }
     }
   }
 }
@@ -116,23 +108,18 @@ export const CommitValidatorPlugin = async (ctx) => {
 **Execution:**
 1. Single: `opencode-agent-designer` - create agent frontmatter
 
-**Agent structure:**
+**Agent structure** (`.opencode/agents/pr-reviewer.md`; the filename becomes the agent name):
 ```markdown
 ---
-name: pr-reviewer
 description: Review pull requests with security and quality focus
-tools:
-  bash: false
-  write: false
-  edit: false
-  github: true
-  read: true
-  grep: true
-  glob: true
+mode: subagent
+model: anthropic/claude-sonnet-4-5
 permission:
+  bash: deny
+  edit: deny
+  "github_*": allow
   skill:
-    "git-release": "allow"
-model: anthropic/claude-3.5-sonnet
+    "git-release": allow
 ---
 
 ## Role
@@ -144,6 +131,8 @@ Review PRs for code quality, security vulnerabilities, and test coverage.
 3. Provide structured feedback
 ```
 
+`read`/`grep`/`glob` need no entry (tools are enabled by default); `edit` denies `write` and `apply_patch` too.
+
 ---
 
 ## Example 5: Multi-Component Plugin Package
@@ -175,18 +164,14 @@ opencode-devtools/
 
 ---
 
-## Example 6: Local-Only Session Notification Plugin (plugin-engineer, NOT packager)
+## Example 6: Local-Only Session Notification Plugin (plugin-engineer)
 
 **User Request:**
 > Create a plugin that sends a desktop notification when a session completes or errors. This is for my local machine only, not for publishing.
 
 **Analysis:**
 - Plugin with event hooks → `opencode-plugin-engineer`
-- **NOT** packager because:
-  - No npm distribution needed
-  - No skills or commands to bundle
-  - Single local plugin file, not a package
-  - User explicitly said "local machine only"
+- Local machine only, single plugin file → `opencode-plugin-engineer` (distribution intent is the packager test; see the table below)
 
 **Execution:**
 1. Single: `opencode-plugin-engineer` - create local plugin with event hooks
@@ -214,23 +199,17 @@ export const SessionNotifyPlugin: Plugin = async ({ $ }) => {
 | Local-only plugin                    | Local package for sharing          |
 | Event hooks / behavior modification  | Bundling skills + commands as assets|
 | Single `.ts`/`.js` file              | Full package structure with package.json |
-| No distribution intent              | Intended for local file:// sharing |
-| Injecting env vars, notifications    | Combining multiple opencode artifacts |
+| Single-machine use                   | Local file:// sharing across projects |
 
 ---
 
-## Example 7: Plugin with Embedded Static Instructions (plugin-engineer, NOT packager)
+## Example 7: Plugin with Embedded Static Instructions (plugin-engineer)
 
 **User Request:**
 > Create a customer support plugin that injects a "support-agent" prompt into sessions. The prompt should be embedded in the plugin file itself, not as separate files.
 
 **Analysis:**
-- Plugin that injects static content → `opencode-plugin-engineer`
-- **NOT** packager because:
-  - Instructions are embedded as string literals in code
-  - No separate `.md` files to bundle
-  - Content is generated/managed programmatically within the plugin
-  - Not a distributable asset package
+- Prompt embedded as a string literal in the plugin file, managed programmatically at runtime → `opencode-plugin-engineer`
 
 **Execution:**
 1. Single: `opencode-plugin-engineer` - create plugin with embedded prompt string
@@ -270,24 +249,6 @@ export const SupportAgentPlugin: Plugin = async ({ client }) => {
 | Instructions embedded as string in code          | Separate `.md` files as assets     |
 | Content generated programmatically               | Static markdown files to distribute|
 | Single file contains logic + content             | Package structure with multiple files |
-| Runtime-generated prompts                        | Pre-authored skill/command files  |
-| Agent definitions with inline prompts            | Skill SKILL.md + command .md bundles |
-
-**Real-world pattern (reference):**
-```typescript
-// Agent with embedded prompt - NO separate .md files
-export const agent: AgentConfig = {
-  name: "data-analyzer",
-  prompt: `
-    Analyze data files and produce reports.
-    
-    ## Steps
-    1. Read input files
-    2. Parse and validate
-    3. Generate summary statistics
-  `
-}
-```
 
 ---
 

package/assets/references/skills.md

@@ -50,8 +50,6 @@ Address co-located files **relative to the skill's own directory** (its base dir
 
 ## 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`).
+- General authoring rules (degrees of freedom, workflows, defaults, terminology): see `prompt-engineering.md`.
+- Gerund names read well (`processing-pdfs`); vague names (`helper`, `utils`) hide the skill from selection.
 - Gate access with `permission.skill` glob patterns (`"internal-*": "deny"`); disable entirely with `tools: { skill: false }`.

package/assets/templates/skill-structure.template.md

@@ -24,7 +24,7 @@ compatibility: opencode
 metadata:
   version: 1.0.0
   audience: agents
-  topic: [topic1, topic2]
+  topic: "topic1, topic2"
 ---
 
 ## Activation Triggers
@@ -32,9 +32,9 @@ metadata:
 **USE this skill when user asks about:**
 - Category: "Example query"
 
-**DO NOT USE for:**
-- Non-technical topics
-- Known specific repos
+**Route elsewhere when:**
+- The topic is non-technical
+- The repo is well-known and already documented
 
 ## Workflow Summary