diff --git a/.opencode/agent/agent-builder.md b/.opencode/agent/agent-builder.md new file mode 100644 index 0000000..542993d --- /dev/null +++ b/.opencode/agent/agent-builder.md @@ -0,0 +1,391 @@ +--- +description: AI agent specialized in creating OpenCode agents with expert knowledge of agent configuration, modes, tools, and best practices +mode: subagent +model: anthropic/claude-sonnet-4-20250514 +tools: + read: true + write: true + edit: true + bash: true +--- + +# Agent Builder Agent + +You are an expert OpenCode agent developer. You help users create, configure, and optimize custom agents for OpenCode with deep knowledge of the agent architecture, configuration options, and best practices. + +## Core Knowledge + +### Agent Structure + +OpenCode agents are defined as Markdown files with YAML frontmatter: + +```markdown +--- +description: Brief description of what this agent does +mode: primary|subagent|all +model: provider/model-id +tools: + read: true + write: true + edit: true + bash: true +permission: + edit: allow + bash: ask +--- + +# Agent Name + +System prompt instructions go here... +``` + +### Agent Modes + +| Mode | Description | Use Case | +|------|-------------|----------| +| `primary` | Main assistant, user cycles via Tab | Build, Plan, Review agents | +| `subagent` | Invoked by @ mention or automatically | Specialized helpers | +| `all` | Available in both contexts | Versatile agents | + +### File Locations + +- **Global agents**: `~/.config/opencode/agent/` +- **Project agents**: `.opencode/agent/` + +### Configuration Options + +#### Required Fields + +| Field | Description | +|-------|-------------| +| `description` | Brief explanation (1-2 sentences) - used for agent selection | + +#### Optional Fields + +| Field | Description | Default | +|-------|-------------|---------| +| `mode` | `primary`, `subagent`, or `all` | `subagent` | +| `model` | Override model (e.g., `anthropic/claude-sonnet-4-20250514`) | Inherits | +| `temperature` | Response randomness (0.0-1.0) | Default | +| `maxSteps` | Max iterations before text-only | Default | +| `tools` | Enable/disable specific tools | All enabled | +| `permission` | Tool approval requirements | Inherits | +| `disable` | Set `true` to deactivate | `false` | + +### Tool Configuration + +```yaml +tools: + # Individual tools + read: true + write: true + edit: true + bash: true + glob: true + grep: true + webfetch: true + websearch: true + + # MCP tools with wildcards + mcp_filesystem_*: true + mcp_github_*: false +``` + +### Permission Levels + +```yaml +permission: + edit: allow # No approval needed + bash: ask # User must approve + webfetch: deny # Completely disabled + + # Bash with patterns + bash: + "npm *": allow + "git *": allow + "rm *": deny +``` + +## Instructions + +When helping users create agents: + +1. **Understand the purpose** - Ask what tasks the agent should handle +2. **Choose appropriate mode** - Primary for main workflows, subagent for specialized tasks +3. **Select minimal tools** - Only enable tools the agent actually needs +4. **Write clear prompts** - Be specific about capabilities and constraints +5. **Consider security** - Set appropriate permissions for sensitive operations +6. **Follow best practices**: + - Keep descriptions concise but descriptive + - Use appropriate temperature for the task + - Set reasonable maxSteps limits + - Document expected usage patterns + +## Common Agent Patterns + +### Primary Agent: Build (Development) + +```markdown +--- +description: Development agent with full tool access for building features +mode: primary +tools: + read: true + write: true + edit: true + bash: true + glob: true + grep: true +permission: + edit: allow + bash: ask +--- + +# Build Agent + +You are a software development assistant focused on building and implementing features. + +## Capabilities +- Read and analyze code +- Write new files and edit existing ones +- Run build commands and tests +- Search the codebase + +## Guidelines +- Understand requirements before implementing +- Follow existing code patterns +- Write tests for new functionality +- Run linters before committing +``` + +### Primary Agent: Plan (Analysis Only) + +```markdown +--- +description: Analysis-only agent for planning and investigation without modifications +mode: primary +tools: + read: true + glob: true + grep: true + write: false + edit: false + bash: false +permission: + edit: deny + bash: deny +--- + +# Plan Agent + +You are a planning and analysis assistant. You help users understand codebases and design solutions WITHOUT making changes. + +## Capabilities +- Read and analyze code +- Search for patterns +- Explain architecture +- Propose implementation plans + +## Constraints +- NEVER modify files +- NEVER run commands +- Only provide analysis and recommendations +``` + +### Subagent: Code Review + +```markdown +--- +description: Reviews code changes for quality, security, and best practices +mode: subagent +tools: + read: true + glob: true + grep: true + bash: true +permission: + bash: + "git diff*": allow + "git log*": allow + "git show*": allow +--- + +# Code Review Agent + +You are a code review specialist. Analyze code changes for: + +## Review Criteria +1. **Correctness** - Does the code work as intended? +2. **Security** - Any vulnerabilities or sensitive data exposure? +3. **Performance** - Inefficiencies or bottlenecks? +4. **Maintainability** - Is it readable and well-structured? +5. **Testing** - Adequate test coverage? + +## Output Format +Provide structured feedback: +- Summary (1-2 sentences) +- Issues (with severity: critical/major/minor) +- Suggestions for improvement +- Approval recommendation +``` + +### Subagent: Documentation + +```markdown +--- +description: Writes and updates technical documentation +mode: subagent +model: anthropic/claude-sonnet-4-20250514 +tools: + read: true + write: true + edit: true + glob: true + grep: true +--- + +# Documentation Agent + +You are a technical writing specialist. Create clear, accurate documentation. + +## Documentation Types +- README files +- API documentation +- Code comments +- Architecture docs +- User guides + +## Writing Guidelines +- Use clear, concise language +- Include code examples +- Structure with headers +- Add relevant links +- Keep audience in mind +``` + +### Subagent: Security Audit + +```markdown +--- +description: Analyzes code for security vulnerabilities and best practices +mode: subagent +tools: + read: true + glob: true + grep: true + bash: true +permission: + bash: + "npm audit*": allow + "grep *": allow +--- + +# Security Audit Agent + +You are a security specialist. Analyze code for vulnerabilities. + +## Check For +- SQL injection +- XSS vulnerabilities +- Command injection +- Sensitive data exposure +- Insecure dependencies +- Authentication issues +- Authorization flaws + +## Output Format +Provide security report: +- Severity (Critical/High/Medium/Low) +- Location (file:line) +- Description +- Remediation steps +``` + +### Subagent: Test Writer + +```markdown +--- +description: Generates comprehensive tests for code +mode: subagent +tools: + read: true + write: true + edit: true + glob: true + grep: true + bash: true +permission: + bash: + "npm test*": allow + "jest *": allow + "pytest *": allow +--- + +# Test Writer Agent + +You are a testing specialist. Write comprehensive tests. + +## Test Types +- Unit tests +- Integration tests +- E2E tests +- Edge cases + +## Guidelines +- Test happy path first +- Cover error cases +- Use descriptive test names +- Mock external dependencies +- Aim for high coverage +``` + +## Model Selection Guide + +| Model | Best For | +|-------|----------| +| `anthropic/claude-sonnet-4-20250514` | General development, balanced speed/quality | +| `anthropic/claude-opus-4-20250514` | Complex analysis, architecture decisions | +| `anthropic/claude-haiku-3-5-20241022` | Quick tasks, simple queries | + +## Creating Agents via CLI + +Users can also create agents interactively: + +```bash +opencode agent create +``` + +This guides through: +1. Agent name +2. Purpose/description +3. Mode selection +4. Tool preferences +5. Auto-generates system prompt + +## Validation Checklist + +Before finalizing an agent: + +- [ ] Description is clear and concise +- [ ] Mode matches intended usage +- [ ] Only necessary tools are enabled +- [ ] Permissions are appropriately restrictive +- [ ] System prompt is specific and focused +- [ ] Temperature is suitable for the task +- [ ] maxSteps prevents runaway iterations + +## File Naming + +- Use kebab-case: `code-review.md`, `test-writer.md` +- Match filename to agent purpose +- Place in correct directory based on scope + +## Testing Agents + +After creating an agent: + +1. Start OpenCode: `opencode` +2. For primary agents: Press Tab to cycle to new agent +3. For subagents: Use `@agent-name` to invoke +4. Test with representative tasks +5. Iterate on prompt based on behavior diff --git a/.opencode/command/create-agent.md b/.opencode/command/create-agent.md new file mode 100644 index 0000000..d5a7ce0 --- /dev/null +++ b/.opencode/command/create-agent.md @@ -0,0 +1,86 @@ +--- +template: | + Create a new OpenCode agent with the following specifications: + + Agent name: $1 + Template type: $2 + + Available templates: + - primary: Main development agent with full access + - plan: Analysis-only agent (no modifications) + - review: Code review focused agent + - docs: Documentation writing agent + - security: Security audit agent + - test: Test writing agent + - custom: Bare template for custom configuration + + If no template specified, use 'custom'. + + Generate the agent in .opencode/agent/$1.md with: + 1. Appropriate YAML frontmatter (description, mode, tools, permissions) + 2. Clear system prompt with capabilities and guidelines + 3. Best practices for the agent type + 4. Example usage patterns + + After creating, explain how to invoke and test the agent. +description: Scaffold a new OpenCode agent from templates +agent: agent-builder +--- + +# Create Agent Command + +Scaffolds a new OpenCode agent with best practices and proper structure. + +## Usage + +``` +/create-agent [template] +``` + +## Templates + +| Template | Mode | Description | Use Case | +|----------|------|-------------|----------| +| `primary` | primary | Full-access development agent | Main coding assistant | +| `plan` | primary | Analysis-only, no modifications | Planning and investigation | +| `review` | subagent | Code review specialist | PR and code review | +| `docs` | subagent | Documentation writer | README, API docs | +| `security` | subagent | Security auditor | Vulnerability scanning | +| `test` | subagent | Test generator | Writing test suites | +| `custom` | subagent | Minimal template | Custom agents | + +## Examples + +``` +/create-agent my-agent # Custom agent template +/create-agent build primary # Primary development agent +/create-agent analyzer plan # Analysis-only agent +/create-agent reviewer review # Code review agent +/create-agent doc-writer docs # Documentation agent +/create-agent sec-check security # Security audit agent +/create-agent tester test # Test writing agent +``` + +## Generated Structure + +Agents are created in `.opencode/agent/.md` with: + +1. **YAML Frontmatter** + - description + - mode (primary/subagent) + - model (optional override) + - tools configuration + - permission settings + +2. **System Prompt** + - Agent identity and purpose + - Capabilities section + - Guidelines and constraints + - Output format expectations + +## After Creation + +1. **For primary agents**: Press Tab in OpenCode to cycle between agents +2. **For subagents**: Use `@agent-name` to invoke in conversation +3. **Test with sample tasks** to verify behavior +4. **Iterate on prompt** based on performance diff --git a/.openskills/prpm-json-best-practices-skill/SKILL.md b/.opencode/skill/prpm-json/SKILL.md similarity index 77% rename from .openskills/prpm-json-best-practices-skill/SKILL.md rename to .opencode/skill/prpm-json/SKILL.md index e5634b8..599409d 100644 --- a/.openskills/prpm-json-best-practices-skill/SKILL.md +++ b/.opencode/skill/prpm-json/SKILL.md @@ -1,6 +1,7 @@ --- +name: prpm-json description: Best practices for structuring prpm.json package manifests with required fields, tags, organization, multi-package management, enhanced file format, eager/lazy activation, and conversion hints -mode: all +license: MIT --- ## When to Apply This Skill @@ -67,32 +68,34 @@ mode: all | `agents.md` | Agents.md format | | `generic` | Generic/universal format | | `mcp` | Model Context Protocol | +| `opencode` | OpenCode (agents, skills, plugins) | ### Subtype (Package Type) | Subtype | Description | Typical Formats | |---------|-------------|-----------------| -| `agent` | Autonomous agents | `claude`, `agents.md` | -| `skill` | Specialized capabilities | `claude` | +| `agent` | Autonomous agents | `claude`, `opencode`, `agents.md` | +| `skill` | Specialized capabilities | `claude`, `opencode` | | `rule` | IDE rules and guidelines | `cursor`, `windsurf` | -| `slash-command` | Slash commands | `cursor`, `continue` | +| `slash-command` | Slash commands | `cursor`, `continue`, `opencode` | | `prompt` | Prompt templates | `generic` | | `collection` | Package collections | Any | | `chatmode` | Chat modes | `kiro` | | `tool` | MCP tools | `mcp` | +| `plugin` | Plugin modules | `opencode` | ## Eager vs Lazy Activation ### Setting Eager in prpm.json -``` +```json { "name": "code-style-enforcer", "version": "1.0.0", - "format": "claude", + "format": "opencode", "subtype": "skill", "eager": true, - "files": [".claude/skills/code-style/SKILL.md"] + "files": [".opencode/skill/code-style/SKILL.md"] } ``` @@ -100,7 +103,7 @@ mode: all ### Tag Examples -``` +```json { "tags": [ "typescript", @@ -116,20 +119,20 @@ mode: all ### Multi-Package Organization -``` +```json { "packages": [ - // Private > Claude > Agents - { "name": "internal-agent", "private": true, "format": "claude", "subtype": "agent" }, + // Private > OpenCode > Agents + { "name": "internal-agent", "private": true, "format": "opencode", "subtype": "agent" }, - // Private > Claude > Skills - { "name": "internal-skill", "private": true, "format": "claude", "subtype": "skill" }, + // Private > OpenCode > Skills + { "name": "internal-skill", "private": true, "format": "opencode", "subtype": "skill" }, // Private > Cursor > Rules { "name": "internal-rule", "private": true, "format": "cursor", "subtype": "rule" }, - // Public > Claude > Skills - { "name": "public-skill", "format": "claude", "subtype": "skill" }, + // Public > OpenCode > Skills + { "name": "public-skill", "format": "opencode", "subtype": "skill" }, // Public > Cursor > Rules { "name": "public-rule", "format": "cursor", "subtype": "rule" } @@ -141,7 +144,7 @@ mode: all ### Keep Versions in Sync -``` +```json { "packages": [ { "name": "pkg-one", "version": "1.2.0" }, @@ -155,17 +158,17 @@ mode: all ### Files Array -``` +```json { - "format": "claude", + "format": "opencode", "subtype": "agent", - "files": [".claude/agents/my-agent.md"] + "files": [".opencode/agent/my-agent.md"] } ``` ### Enhanced File Format -``` +```json { "files": [ { @@ -190,7 +193,7 @@ mode: all ### File Verification -``` +```bash # Check all files in prpm.json exist for file in $(cat prpm.json | jq -r '.packages[].files[]'); do if [ ! -f "$file" ]; then @@ -203,18 +206,18 @@ done ### Check for Duplicate Names -``` +```bash # Check for duplicate package names cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ``` ### Resolving Duplicates -``` +```json { "packages": [ - { "name": "typescript-safety", "format": "claude" }, - { "name": "typescript-safety", "format": "cursor" } + { "name": "typescript-safety", "format": "opencode" }, + { "name": "typescript-safety-cursor", "format": "cursor" } ] } ``` @@ -223,11 +226,11 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### **Purpose:** Help improve quality when converting packages to other formats. The `conversion` field provides format-specific hints for cross-format transformations. -``` +```json { "name": "my-package", "version": "1.0.0", - "format": "claude", + "format": "opencode", "conversion": { "cursor": { "alwaysApply": false, @@ -259,27 +262,27 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### Cursor Hints -``` +```json { "conversion": { "cursor": { - "alwaysApply": boolean, // Whether rule should always apply - "priority": "high|medium|low", // Rule priority level - "globs": ["**/*.ts"] // File patterns to auto-attach + "alwaysApply": true, + "priority": "high", + "globs": ["**/*.ts"] } } } ``` -### Claude Hints +### OpenCode Hints -``` +```json { "conversion": { - "claude": { - "model": "sonnet|opus|haiku|inherit", // Preferred model - "tools": ["Read", "Write"], // Allowed tools - "subagentType": "format-conversion" // Subagent type if agent + "opencode": { + "model": "anthropic/claude-sonnet-4-20250514", + "tools": ["read", "write", "edit", "bash"], + "mode": "subagent" } } } @@ -287,15 +290,15 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### Kiro Hints -``` +```json { "conversion": { "kiro": { - "inclusion": "always|fileMatch|manual", // When to include - "fileMatchPattern": "**/*.ts", // Pattern for fileMatch mode - "domain": "typescript", // Domain category - "tools": ["fs_read", "fs_write"], // Available tools - "mcpServers": { // MCP server configs + "inclusion": "always", + "fileMatchPattern": "**/*.ts", + "domain": "typescript", + "tools": ["fs_read", "fs_write"], + "mcpServers": { "database": { "command": "mcp-server-postgres", "args": [], @@ -309,12 +312,12 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### Copilot Hints -``` +```json { "conversion": { "copilot": { - "applyTo": "src/**", // Path patterns - "excludeAgent": "code-review|coding-agent" // Agent to exclude + "applyTo": "src/**", + "excludeAgent": "code-review" } } } @@ -322,13 +325,13 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### Continue Hints -``` +```json { "conversion": { "continue": { - "alwaysApply": boolean, // Always apply rule - "globs": ["**/*.ts"], // File patterns - "regex": ["import.*from"] // Regex patterns + "alwaysApply": true, + "globs": ["**/*.ts"], + "regex": ["import.*from"] } } } @@ -336,11 +339,11 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### Windsurf Hints -``` +```json { "conversion": { "windsurf": { - "characterLimit": 12000 // Warn if exceeding limit + "characterLimit": 12000 } } } @@ -348,12 +351,12 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### Agents.md Hints -``` +```json { "conversion": { "agentsMd": { - "project": "my-project", // Project name - "scope": "backend" // Scope/domain + "project": "my-project", + "scope": "backend" } } } @@ -363,47 +366,47 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### Private Internal Packages -``` +```json { "name": "internal-tool", "version": "1.0.0", "description": "Internal development tool", "private": true, - "format": "claude", + "format": "opencode", "subtype": "skill", "tags": ["prpm-internal", "development"], - "files": [".claude/skills/internal-tool/SKILL.md"] + "files": [".opencode/skill/internal-tool/SKILL.md"] } ``` ### Meta Packages (Creating Other Packages) -``` +```json { "name": "creating-skills", "version": "1.0.0", - "description": "Guide for creating effective Claude Code skills", - "format": "claude", + "description": "Guide for creating effective OpenCode skills", + "format": "opencode", "subtype": "skill", - "tags": ["meta", "claude-code", "skills", "documentation", "best-practices"], - "files": [".claude/skills/creating-skills/SKILL.md"] + "tags": ["meta", "opencode", "skills", "documentation", "best-practices"], + "files": [".opencode/skill/creating-skills/SKILL.md"] } ``` ### Cross-Format Packages -``` +```json { "packages": [ { "name": "format-conversion-agent", - "format": "claude", + "format": "opencode", "subtype": "agent", "description": "Agent for converting between AI prompt formats", - "files": [".claude/agents/format-conversion.md"] + "files": [".opencode/agent/format-conversion.md"] }, { - "name": "format-conversion", + "name": "format-conversion-rule", "format": "cursor", "subtype": "rule", "description": "Rule for converting between AI prompt formats", @@ -415,7 +418,7 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### Collections in prpm.json -``` +```json { "name": "my-prompts-repo", "author": "Your Name", @@ -461,7 +464,7 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### When to Use Scripts -``` +```json { "name": "my-packages", "license": "MIT", @@ -472,12 +475,11 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d { "name": "my-hook", "version": "1.0.0", - "format": "claude", - "subtype": "hook", + "format": "opencode", + "subtype": "plugin", "files": [ - ".claude/hooks/my-hook/hook.ts", - ".claude/hooks/my-hook/hook.json", - ".claude/hooks/my-hook/dist/hook.js" + ".opencode/plugin/my-hook/index.ts", + ".opencode/plugin/my-hook/dist/index.js" ] } ] @@ -486,30 +488,30 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### prepublishOnly Examples -``` +```json { "scripts": { - "prepublishOnly": "cd .claude/hooks/my-hook && npm run build" + "prepublishOnly": "cd .opencode/plugin/my-plugin && npm run build" } } ``` ### Common Patterns -``` +```json { "scripts": { - "prepublishOnly": "cd packages/hooks && npm run build" + "prepublishOnly": "cd packages/plugins && npm run build" } } ``` ### Debugging Script Failures -``` +```bash # Test your prepublishOnly script manually cd /path/to/prpm.json/directory -cd packages/hooks && npm run build +cd packages/plugins && npm run build # If it works manually but fails in PRPM, check: # - Working directory assumptions @@ -544,13 +546,13 @@ cd packages/hooks && npm run build ### Common Mistake: Duplicating Dependencies -``` -// prpm.json +```json +// prpm.json - WRONG { "name": "my-project", "packages": [ { - "name": "typescript-safety", // ❌ This is an INSTALLED package + "name": "typescript-safety", // This is an INSTALLED package "version": "1.0.0", "format": "cursor", "subtype": "rule", @@ -562,7 +564,7 @@ cd packages/hooks && npm run build ### Workflow Example -``` +```bash # Install a package (updates prpm.lock automatically) prpm install @prpm/typescript-safety @@ -578,7 +580,7 @@ prpm install @prpm/typescript-safety ### 1. Validate Manifest -``` +```bash # Validate JSON syntax cat prpm.json | jq . > /dev/null @@ -591,14 +593,14 @@ cat prpm.json | jq -r '.packages[].name' | sort | uniq -d ### 3. Test Locally -``` +```bash # Test package installation prpm install . --dry-run ``` ### 4. Publish -``` +```bash # Publish all packages prpm publish @@ -610,16 +612,16 @@ prpm publish --package my-skill ### Missing Required Fields -``` +```json { - "name": "my-skill", + "name": "my-skill" // Missing: version, description, format, subtype, files } ``` ### Wrong Tag Format -``` +```json { "tags": ["TypeScript", "Code_Quality", "bestPractices"] // Should be: ["typescript", "code-quality", "best-practices"] @@ -628,10 +630,10 @@ prpm publish --package my-skill ### Duplicate Names -``` +```json { "packages": [ - { "name": "my-skill", "format": "claude" }, + { "name": "my-skill", "format": "opencode" }, { "name": "my-skill", "format": "cursor" } // Second should be: "my-skill-rule" or similar ] @@ -640,32 +642,32 @@ prpm publish --package my-skill ### Missing Files -``` +```json { - "files": [".claude/skills/my-skill/SKILL.md"] - // But .claude/skills/my-skill/SKILL.md doesn't exist in the repo + "files": [".opencode/skill/my-skill/SKILL.md"] + // But .opencode/skill/my-skill/SKILL.md doesn't exist in the repo } ``` ### Absolute Paths -``` +```json { - "files": ["/Users/me/project/.claude/skills/my-skill/SKILL.md"] - // Should be: ".claude/skills/my-skill/SKILL.md" (relative to project root) + "files": ["/Users/me/project/.opencode/skill/my-skill/SKILL.md"] + // Should be: ".opencode/skill/my-skill/SKILL.md" (relative to project root) } ``` ### Missing Directory Prefix -``` +```json { - "files": ["agents/my-agent.md"] - // Should be: ".claude/agents/my-agent.md" (include .claude/ prefix) + "files": ["skill/my-skill/SKILL.md"] + // Should be: ".opencode/skill/my-skill/SKILL.md" (include .opencode/ prefix) } ``` -You are a an expert at creating and maintaining `prpm. +You are an expert at creating and maintaining `prpm.json` manifests. ## Remember diff --git a/AGENTS.md b/AGENTS.md index a037dee..c27ad98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ How to use skills (loaded into main context): - Use the from the skill entry below - Invoke: Bash("cat ") - The skill content will load into your current context -- Example: Bash("cat .openskills/backend-architect/SKILL.md") +- Example: Bash("cat .opencode/skill/prpm-json/SKILL.md") Usage notes: - Skills share your context window @@ -18,9 +18,9 @@ Usage notes: -prpm-json-best-practices-skill -Best practices for structuring prpm.json package manifests with required fields, tags, organization, and multi-package management -.openskills/prpm-json-best-practices-skill/SKILL.md +prpm-json +Best practices for structuring prpm.json package manifests with required fields, tags, organization, multi-package management, and conversion hints +.opencode/skill/prpm-json/SKILL.md diff --git a/README.md b/README.md index 7241a13..9785ec9 100644 --- a/README.md +++ b/README.md @@ -1,128 +1,101 @@ -# PRPM OpenCode Plugin Helper +# PRPM OpenCode Meta-Plugin -A development tool for building OpenCode plugins. It helps you discover events, debug plugin behavior, and scaffold new plugins with working templates. +A comprehensive development toolkit for building OpenCode plugins, agents, and skills. This meta-plugin provides AI-powered assistance, templates, and best practices for extending OpenCode. ## What This Plugin Does -**This is a plugin for plugin developers.** It provides: +**This is a plugin for OpenCode developers.** It provides: -1. **Debug Mode** - Logs all OpenCode events and tool executions in real-time -2. **Event Discovery** - Lists all available events you can hook into -3. **Template Scaffolding** - Provides working starter code for common plugin patterns +1. **Plugin Builder Agent** - AI assistant for creating plugins with knowledge of all 32+ events +2. **Agent Builder Agent** - AI assistant for creating custom agents with configuration expertise +3. **Debug Mode** - Logs all OpenCode events and tool executions in real-time +4. **Template Scaffolding** - Working starter code for common patterns ## Installation -```bash -# Copy the .opencode folder to your project -cp -r .opencode /path/to/your/project/ -``` - -Or install via PRPM: ```bash prpm install @prpm/opencode ``` -## How to Build a Plugin +Or manually copy the `.opencode` folder to your project. -### Step 1: Enable Debug Mode +## Included Packages -Run OpenCode with debug mode to see all events firing: +| Package | Type | Description | +|---------|------|-------------| +| `plugin-helper` | Plugin | Debug utility with event logging and templates | +| `plugin-builder-agent` | Agent | AI assistant for creating plugins | +| `agent-builder-agent` | Agent | AI assistant for creating agents | +| `create-plugin-command` | Command | Scaffold plugins from templates | +| `create-agent-command` | Command | Scaffold agents from templates | -```bash -cd /path/to/your/project -PRPM_PLUGIN_DEBUG=true opencode -``` +## Quick Start + +### Creating a Plugin -You'll see output like: +Use the slash command: ``` -[PRPM Debug] session.created {"sessionID":"abc123"}... -[PRPM Debug] Tool Before: Read {"filePath":"/src/index.ts"} -[PRPM Debug] Tool After: Read - Read file -[PRPM Debug] message.updated {"messageID":"msg1"}... -[PRPM Debug] session.idle {}... +/create-plugin my-plugin security ``` -### Step 2: Identify Events You Need - -Use OpenCode normally while watching the logs. For example: -- Want to run code when AI finishes? Look for `session.idle` -- Want to intercept file reads? Look for `tool.execute.before` with tool `Read` -- Want to know when files change? Look for `file.edited` - -Or list all available events: +Or invoke the agent directly: ``` -prpm:events +@plugin-builder help me create a plugin that blocks .env file access ``` -### Step 3: Get a Template +### Creating an Agent -List available templates: +Use the slash command: ``` -prpm:templates +/create-agent my-agent review ``` -View a specific template: +Or invoke the agent directly: ``` -prpm:template:basic -prpm:template:security -prpm:template:notification -prpm:template:custom-tool -prpm:template:logging +@agent-builder create a code review agent that focuses on security ``` -### Step 4: Create Your Plugin - -Replace `.opencode/plugin/index.ts` with your own code based on the template: - -```typescript -import type { Plugin } from "@opencode-ai/plugin"; - -const MyPlugin: Plugin = async ({ $ }) => { - return { - event: async ({ event }) => { - if (event.type === 'session.idle') { - await $`osascript -e 'display notification "Done!" with title "OpenCode"'`; - } - }, - }; -}; +### Debug Mode -export default MyPlugin; +Run OpenCode with debug logging to see all events: +```bash +PRPM_PLUGIN_DEBUG=true opencode ``` -### Step 5: Test It +## Plugin Templates -```bash -opencode -``` +| Template | Description | +|----------|-------------| +| `basic` | Simple event handler starter | +| `security` | Block sensitive file access | +| `notification` | OS notifications on events | +| `custom-tool` | Register custom AI tools | +| `logging` | Full event/tool logging | + +## Agent Templates + +| Template | Mode | Description | +|----------|------|-------------| +| `primary` | primary | Full-access development agent | +| `plan` | primary | Analysis-only, no modifications | +| `review` | subagent | Code review specialist | +| `docs` | subagent | Documentation writer | +| `security` | subagent | Security auditor | +| `test` | subagent | Test generator | +| `custom` | subagent | Minimal template | ## Available Commands | Command | Description | |---------|-------------| +| `/create-plugin [template]` | Scaffold a new plugin | +| `/create-agent [template]` | Scaffold a new agent | | `prpm:events` | List all OpenCode events | -| `prpm:templates` | List available plugin templates | -| `prpm:template:` | View a specific template | -| `prpm:debug:on` | Enable debug logging at runtime | +| `prpm:templates` | List plugin templates | +| `prpm:template:` | View specific template | +| `prpm:debug:on` | Enable debug logging | | `prpm:debug:off` | Disable debug logging | -## Plugin Templates - -### basic -Simple event handler starter - good for learning the plugin structure. - -### security -Blocks access to sensitive files (.env, credentials.json, etc.) - useful for protecting secrets. - -### notification -Sends OS notifications when sessions complete - works on macOS and Linux. - -### custom-tool -Registers a custom tool the AI can use - extends OpenCode's capabilities. - -### logging -Full event and tool logging - useful for debugging complex workflows. - ## Event Reference | Category | Events | @@ -139,22 +112,95 @@ Full event and tool logging - useful for debugging complex workflows. | **tool** | `tool.execute.before`, `tool.execute.after` | | **tui** | `tui.prompt.append`, `tui.command.execute`, `tui.toast.show` | -## Important: Plugin Export Pattern +## File Locations + +### Plugins +- **Global**: `~/.config/opencode/plugin/` +- **Project**: `.opencode/plugin/` + +### Agents +- **Global**: `~/.config/opencode/agent/` +- **Project**: `.opencode/agent/` + +### Skills +- **Global**: `~/.opencode/skill/` +- **Project**: `.opencode/skill/` -OpenCode plugins **must use a default export only**. Named exports will cause errors. +## Plugin Structure + +```typescript +import type { Plugin } from "@opencode-ai/plugin"; + +const MyPlugin: Plugin = async ({ $, project, directory }) => { + return { + event: async ({ event }) => { }, + "tool.execute.before": async (input, output) => { }, + "tool.execute.after": async (input, output) => { }, + tool: { /* custom tools */ } + }; +}; + +export default MyPlugin; +``` + +## Agent Structure + +```markdown +--- +description: Brief description of the agent +mode: primary|subagent|all +model: anthropic/claude-sonnet-4-20250514 +tools: + read: true + write: true + edit: true + bash: true +permission: + edit: allow + bash: ask +--- + +# Agent Name + +System prompt instructions... +``` + +## Skill Structure + +```markdown +--- +name: skill-name +description: What the skill provides +license: MIT +--- + +## When to Apply This Skill + +- Use when: [conditions] +- Don't use for: [exclusions] + +## Knowledge Content + +[Detailed guidance and best practices] +``` + +## Important Notes + +### Plugin Export Pattern + +OpenCode plugins **must use a default export only**: ```typescript // CORRECT const MyPlugin: Plugin = async (context) => { ... }; export default MyPlugin; -// WRONG - will cause "fn3 is not a function" error +// WRONG - causes errors export const MyPlugin: Plugin = async (context) => { ... }; export default MyPlugin; -export { OTHER_STUFF }; ``` -## Hook Signatures +### Hook Signatures ```typescript // Event handler @@ -165,103 +211,25 @@ event: async ({ event }) => { // Before tool execution "tool.execute.before": async (input, output) => { - // input: { tool: string, sessionID: string, callID: string } - // output: { args: any } + // input: { tool, sessionID, callID } + // output: { args } } // After tool execution "tool.execute.after": async (input, output) => { - // input: { tool: string, sessionID: string, callID: string } - // output: { title: string, output: string, metadata: any } + // input: { tool, sessionID, callID } + // output: { title, output, metadata } } ``` ## Claude Code Migration -If you're porting hooks from Claude Code: - | Claude Code Hook | OpenCode Event | |------------------|----------------| | `PreToolUse` | `tool.execute.before` | | `PostToolUse` | `tool.execute.after` | | `SessionEnd` | `session.idle` | ---- - -
-For Agents - -## Agent Instructions - -You are helping a user build an OpenCode plugin. OpenCode is a CLI coding assistant similar to Claude Code. - -### Key Facts - -1. **Plugins live in `.opencode/plugin/index.ts`** -2. **Must use default export only** - named exports cause module loading errors -3. **Hook signatures matter** - `tool.execute.after` takes `(input, output)` not `(result)` - -### Correct Plugin Structure - -```typescript -import type { Plugin } from "@opencode-ai/plugin"; - -const MyPlugin: Plugin = async (context) => { - const { project, directory, $, client } = context; - - return { - // Event handler (optional) - event: async ({ event }) => { }, - - // Tool hooks (optional) - "tool.execute.before": async (input, output) => { }, - "tool.execute.after": async (input, output) => { }, - - // Custom tools (optional) - tool: { - myTool: tool({ ... }) - } - }; -}; - -export default MyPlugin; -``` - -### Common Mistakes to Avoid - -1. **Multiple exports** - Only use `export default`, no named exports -2. **Wrong hook signature** - `tool.execute.after` takes two params `(input, output)`, not one -3. **Using `result.duration` or `result.success`** - These don't exist in the API -4. **File not named `index.ts`** - OpenCode looks for `.opencode/plugin/index.ts` specifically - -### Available Context - -The plugin function receives: -- `project` - Project info (name, path, etc.) -- `directory` - Absolute path to project directory -- `$` - Bun shell for running commands -- `client` - OpenCode SDK client -- `worktree` - Git worktree path - -### Testing Plugins - -```bash -# With debug logging -PRPM_PLUGIN_DEBUG=true opencode - -# Normal mode -opencode -``` - -### When User Asks for Help - -1. First check if they have the correct export pattern -2. Verify hook signatures match the API -3. Suggest using debug mode to see what events fire -4. Provide complete, working code (not snippets) - -
- ## License MIT diff --git a/prpm.json b/prpm.json index 0ac7b14..1afa3dd 100644 --- a/prpm.json +++ b/prpm.json @@ -1,7 +1,7 @@ { "name": "opencode", "version": "1.0.0", - "description": "Meta-plugin for OpenCode that helps create, debug, and manage OpenCode plugins with AI assistance", + "description": "Meta-plugin for OpenCode that helps create, debug, and manage OpenCode plugins, agents, and skills with AI assistance", "author": "prpm", "organization": "prpm", "license": "MIT", @@ -9,6 +9,7 @@ "tags": [ "opencode", "plugin", + "agent", "meta", "developer-tools", "scaffolding", @@ -33,6 +34,15 @@ "files": [".opencode/agent/plugin-builder.md"], "tags": ["agent", "plugin-development", "ai", "code-generation"] }, + { + "name": "agent-builder-agent", + "version": "1.0.0", + "description": "AI agent specialized in creating OpenCode agents with expert knowledge of agent configuration, modes, tools, and best practices", + "format": "opencode", + "subtype": "agent", + "files": [".opencode/agent/agent-builder.md"], + "tags": ["agent", "agent-development", "ai", "meta", "scaffolding"] + }, { "name": "create-plugin-command", "version": "1.0.0", @@ -40,7 +50,16 @@ "format": "opencode", "subtype": "slash-command", "files": [".opencode/command/create-plugin.md"], - "tags": ["command", "scaffold", "template", "generator"] + "tags": ["command", "scaffold", "template", "generator", "plugin"] + }, + { + "name": "create-agent-command", + "version": "1.0.0", + "description": "Slash command to scaffold new OpenCode agents from templates (primary, plan, review, docs, security, test)", + "format": "opencode", + "subtype": "slash-command", + "files": [".opencode/command/create-agent.md"], + "tags": ["command", "scaffold", "template", "generator", "agent"] } ] }