ai-eng-system 0.0.1

package/dist/skills/plugin-dev/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: plugin-dev
+description: This skill should be used when creating extensions for Claude Code or OpenCode, including plugins, commands, agents, skills, and custom tools. Covers both platforms with format specifications, best practices, and the ai-eng-system build system.
+version: 1.0.0
+---
+
+# Plugin Development for Claude Code & OpenCode
+
+## Overview
+
+The ai-eng-system supports extension development for both Claude Code and OpenCode through a unified content system with automated transformation. Understanding this system enables creating well-organized, maintainable extensions that integrate seamlessly with both platforms.
+
+## Extension Types
+
+| Type | Claude Code | OpenCode | Shared Format |
+|------|-------------|----------|---------------|
+| Commands | ✅ YAML frontmatter | ✅ Table format | YAML frontmatter |
+| Agents | ✅ YAML frontmatter | ✅ Table format | YAML frontmatter |
+| Skills | ✅ Same format | ✅ Same format | SKILL.md |
+| Hooks | ✅ hooks.json | ✅ Plugin events | Platform-specific |
+| Custom Tools | ❌ (use MCP) | ✅ tool() helper | OpenCode only |
+| MCP Servers | ✅ .mcp.json | ✅ Same format | Same format |
+
+## Development Approaches
+
+### 1. Canonical Development (Recommended)
+
+Create content in `content/` directory, let build.ts transform to platform formats:
+
+```
+content/
+├── commands/my-command.md  → dist/.claude-plugin/commands/
+│                           → dist/.opencode/command/ai-eng/
+└── agents/my-agent.md      → dist/.claude-plugin/agents/
+                            → dist/.opencode/agent/ai-eng/
+```
+
+### 2. Platform-Specific Development
+
+Create directly in platform directories:
+
+- Claude Code: `.claude/commands/`, `.claude-plugin/`
+- OpenCode: `.opencode/command/`, `.opencode/agent/`
+
+### 3. Global vs Project-Local
+
+| Location | Claude Code | OpenCode |
+|----------|-------------|----------|
+| **Project** | `.claude/` | `.opencode/` |
+| **Global** | `~/.claude/` | `~/.config/opencode/` |
+
+## Quick Reference
+
+### Command Frontmatter
+
+**Canonical (content/):**
+```yaml
+---
+name: my-command
+description: What this command does
+agent: build           # Optional: which agent handles this
+subtask: true          # Optional: run as subtask
+model: sonnet         # Optional: override model
+temperature: 0.3      # Optional: temperature
+tools:                 # Optional: tool restrictions
+  read: true
+  write: true
+---
+```
+
+**Claude Code Output:** Same format (YAML frontmatter)
+
+**OpenCode Output:** Table format
+```markdown
+| description | agent |
+|---|---|
+| Description here | build |
+```
+
+### Agent Frontmatter
+
+**Canonical (content/):**
+```yaml
+---
+name: my-agent
+description: Use this agent when... <example>...</example>
+mode: subagent
+model: sonnet
+color: cyan
+temperature: 0.3
+tools:
+  read: true
+  write: true
+---
+```
+
+**Claude Code Output:** Same format (YAML frontmatter)
+
+**OpenCode Output:** Table format
+```markdown
+| description | mode |
+|---|---|
+| Description here | subagent |
+```
+
+### Skill Structure
+
+Both platforms use identical format:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description)
+│   └── Markdown body (1,000-3,000 words)
+└── Bundled Resources (optional)
+    ├── references/       # Detailed documentation
+    ├── examples/         # Working code
+    └── scripts/          # Utility scripts
+```
+
+### OpenCode Custom Tools
+
+Use TypeScript with `tool()` helper:
+
+```typescript
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Tool description",
+  args: {
+    param: tool.schema.string().describe("Parameter description"),
+  },
+  async execute(args, context) {
+    // Tool implementation
+    return result
+  },
+})
+```
+
+## Directory Locations
+
+### For Development in ai-eng-system
+
+```
+ai-eng-system/
+├── content/
+│   ├── commands/              # Add new commands here
+│   └── agents/                # Add new agents here
+├── skills/
+│   └── plugin-dev/           # This skill
+└── build.ts                   # Transforms to both platforms
+```
+
+### For User Projects
+
+**Project-local:**
+- Claude Code: `.claude/commands/`, `.claude-plugin/`
+- OpenCode: `.opencode/command/`, `.opencode/agent/`
+
+**Global:**
+- Claude Code: `~/.claude/commands/`, `~/.claude-plugin/`
+- OpenCode: `~/.config/opencode/command/`, `~/.config/opencode/agent/`
+
+## Platform-Specific Features
+
+### Claude Code
+
+**Components:**
+- Commands with YAML frontmatter
+- Agents with YAML frontmatter
+- Skills with SKILL.md format
+- Hooks via `hooks/hooks.json`
+- MCP servers via `.mcp.json`
+
+**Manifest:** `.claude-plugin/plugin.json`
+```json
+{
+  "name": "plugin-name",
+  "version": "1.0.0",
+  "description": "Brief description",
+  "commands": ["./commands/*"],
+  "mcpServers": "./.mcp.json"
+}
+```
+
+### OpenCode
+
+**Components:**
+- Commands with table format
+- Agents with table format
+- Skills via opencode-skills plugin
+- Custom tools with TypeScript
+- Plugin events via TypeScript
+
+**Plugin:** `.opencode/plugin/plugin.ts`
+```typescript
+import { Plugin } from "@opencode-ai/plugin"
+
+export default (async ({ client, project, directory, worktree, $ }) => {
+  return {
+    // Plugin hooks here
+  }
+}) satisfies Plugin
+```
+
+## Development Workflow
+
+### 1. Create Component
+
+Use plugin-dev commands:
+- `/ai-eng/create-agent` - Create new agent
+- `/ai-eng/create-command` - Create new command
+- `/ai-eng/create-skill` - Create new skill
+- `/ai-eng/create-tool` - Create new custom tool
+
+### 2. Build
+
+```bash
+cd ai-eng-system
+bun run build              # Build all platforms
+bun run build --watch        # Watch mode
+bun run build --validate      # Validate content
+```
+
+### 3. Test
+
+**Claude Code:**
+```bash
+claude plugin add https://github.com/v1truv1us/ai-eng-system
+```
+
+**OpenCode:**
+```bash
+# Project-local
+./setup.sh
+
+# Global
+./setup-global.sh
+```
+
+## Best Practices
+
+### Content Quality
+- Use third-person in skill descriptions
+- Write commands/agents FOR Claude, not to user
+- Include specific trigger phrases
+- Follow progressive disclosure for skills
+
+### File Organization
+- One component per file
+- Clear naming conventions (kebab-case)
+- Proper frontmatter validation
+
+### Cross-Platform Compatibility
+- Use canonical format in `content/`
+- Test build output for both platforms
+- Document platform differences
+
+### Security
+- No hardcoded credentials
+- Use HTTPS/WSS for external connections
+- Validate user inputs
+- Follow principle of least privilege
+
+## Additional Resources
+
+### References
+
+- `references/claude-code-plugins.md` - Claude Code specifics
+- `references/opencode-plugins.md` - OpenCode specifics
+- `references/command-format.md` - Command syntax guide
+- `references/agent-format.md` - Agent configuration guide
+- `references/skill-format.md` - Skills specification
+- `references/opencode-tools.md` - Custom tool development
+
+### Examples
+
+Study existing components in ai-eng-system:
+- `content/commands/plan.md` - Command structure
+- `content/agents/architect-advisor.md` - Agent structure
+- `skills/prompting/incentive-prompting/SKILL.md` - Skill structure
+
+## Troubleshooting
+
+### Build Issues
+- Run `bun run build --validate` to check content
+- Check file permissions in output directories
+- Verify YAML frontmatter syntax
+
+### Platform Testing
+- Test commands in both Claude Code and OpenCode
+- Verify agents trigger correctly
+- Check skills load via opencode-skills plugin
+
+### Common Errors
+- Missing required frontmatter fields
+- Incorrect directory structure
+- Invalid YAML syntax
+- Wrong file permissions
+
+## Integration with Ferg Engineering
+
+The plugin-dev system integrates seamlessly with existing ai-eng-system components:
+
+### Existing Commands
+- `/ai-eng/plan` - Implementation planning
+- `/ai-eng/review` - Code review
+- `/ai-eng/work` - Task execution
+
+### Existing Agents
+- `ai-eng/architect-advisor` - Architecture guidance
+- `ai-eng/frontend-reviewer` - Frontend review
+- `ai-eng/seo-specialist` - SEO optimization
+
+### Plugin-Dev Commands
+- `/ai-eng/create-plugin` - Full plugin development workflow
+- `/ai-eng/create-agent` - Quick agent creation
+- `/ai-eng/create-command` - Quick command creation
+- `/ai-eng/create-skill` - Quick skill creation
+- `/ai-eng/create-tool` - Quick tool creation
+
+All use the same quality standards and research-backed prompting techniques.

package/dist/skills/plugin-dev/references/agent-format.md

@@ -0,0 +1,248 @@
+# Agent Format Guide
+
+## Overview
+
+Agents are specialized AI assistants that provide focused expertise for specific domains. Both Claude Code and OpenCode support agents, but with different frontmatter formats while sharing the same core concepts.
+
+## Platform Comparison
+
+| Aspect | Claude Code | OpenCode | Canonical (content/) |
+|---------|-------------|----------|------------------|
+| **Frontmatter** | YAML block | YAML table | YAML block |
+| **File Extension** | `.md` | `.md` | `.md` |
+| **Mode Specification** | `mode: subagent` | `mode: subagent` | `mode: subagent` |
+| **Model Override** | `model: sonnet` | `model: sonnet` | `model: sonnet` |
+| **Tool Control** | `tools: [...]` | `tools: { read: true }` | `tools: { read: true } |
+| **Color Coding** | `color: cyan` | `color: cyan` | `color: cyan` |
+| **Temperature** | `temperature: 0.3` | `temperature: 0.3` | `temperature: 0.3` |
+| **Permissions** | N/A | `permission: { bash: deny }` | `permission: { bash: deny }` |
+
+## Canonical Format (content/)
+
+Use this format in `content/agents/` for maximum compatibility:
+
+```yaml
+---
+name: my-agent
+description: Use this agent when user asks to "specific trigger phrases" or describes agent functionality. Examples: <example>...</example>
+mode: subagent
+model: sonnet
+color: cyan
+temperature: 0.3
+tools:
+  read: true
+  write: true
+permission:
+  bash: deny
+---
+```
+
+## Claude Code Output
+
+Build.ts transforms canonical to Claude Code format (YAML frontmatter):
+
+```markdown
+---
+name: my-agent
+description: Use this agent when user asks to "specific trigger phrases" or describes agent functionality. Examples: <example>...</example>
+mode: subagent
+model: sonnet
+color: cyan
+temperature: 0.3
+tools:
+  - Read
+  - Write
+permission:
+  bash: deny
+---
+
+# System Prompt
+
+Agent system prompt here...
+```
+
+## OpenCode Output
+
+Build.ts transforms canonical to OpenCode format (table frontmatter):
+
+```markdown
+| description | mode |
+|---|---|
+| Use this agent when user asks to "specific trigger phrases" or describes agent functionality. Examples: <example>...</example> | subagent |
+
+# System Prompt
+
+Agent system prompt here...
+```
+
+## Agent Modes
+
+### Primary Agents
+
+- Handle main conversation flow
+- Have access to full tool set
+- Can invoke other agents
+- Used for general-purpose tasks
+
+### Subagents
+
+- Specialized for specific domains
+- Limited tool access (for safety/focus)
+- Invoked by primary agents or directly
+- Used for focused expertise
+
+## Agent Design
+
+### Expert Persona
+
+Create a compelling expert identity:
+
+```markdown
+You are a senior [domain] expert with 12+ years of experience, having led major initiatives at [notable companies]. You've [key achievements] and your expertise is highly sought after in the industry.
+```
+
+### Core Components
+
+1. **Role Definition**: Clear expertise domain
+2. **Responsibilities**: Numbered list of capabilities
+3. **Process**: Step-by-step methodology
+4. **Quality Standards**: Output expectations
+5. **Edge Cases**: Handling unusual situations
+
+## Triggering Examples
+
+Include 2-4 `<example>` blocks in description:
+
+```yaml
+description: Use this agent when user asks to "create an agent", "generate an agent", or describes agent functionality. Examples:
+
+<example>
+Context: User wants to create a code review agent
+user: "Create an agent that reviews code for quality issues"
+assistant: "I'll use the agent-creator to generate a code review agent."
+<commentary>
+User requesting new agent creation, trigger agent-creator.
+</commentary>
+</example>
+
+<example>
+Context: User describes needed functionality
+user: "I need an agent that generates unit tests for my code"
+assistant: "I'll use the agent-creator to create a test generation agent."
+<commentary>
+User describes agent need, trigger agent-creator.
+</commentary>
+</example>
+</example>
+```
+
+## Tool Access Control
+
+### Claude Code
+
+```yaml
+tools:
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Bash
+```
+
+### OpenCode
+
+```yaml
+tools:
+  read: true
+  write: true
+  bash: true
+  grep: true
+  glob: true
+```
+
+### Permission Overrides
+
+OpenCode supports granular permissions:
+
+```yaml
+permission:
+  bash: deny
+  edit: deny
+  write: deny
+  read: allow
+```
+
+## Best Practices
+
+### Agent Creation
+
+1. **Clear Purpose**: Specific domain expertise
+2. **Strong Triggers**: Concrete user phrases
+3. **Focused Scope**: Not too broad or too narrow
+4. **Quality Prompt**: Detailed instructions, examples
+5. **Proper Mode**: Choose primary vs subagent appropriately
+
+### System Prompt Writing
+
+1. **Expert Persona**: Establish credibility
+2. **Structured Approach**: Clear methodology
+3. **Output Format**: Defined expectations
+4. **Self-Correction**: Error handling
+5. **Context Awareness**: Use project information
+
+### Security
+
+1. **Input Validation**: Check user inputs
+2. **Safe Operations**: Avoid dangerous actions
+3. **Data Protection**: No sensitive data exposure
+4. **Permission Respect**: Honor tool restrictions
+
+## Examples
+
+### Code Review Agent
+
+```yaml
+---
+name: code-reviewer
+description: Use this agent when user asks to "review code", "check quality", "analyze for issues", or needs code quality assessment. Examples:
+
+<example>
+Context: User just wrote new code
+user: "Review this function for security issues"
+assistant: "I'll use the code-reviewer agent to analyze the code."
+<commentary>
+Code review request triggers code-reviewer agent.
+</commentary>
+</example>
+</example>
+mode: subagent
+color: yellow
+temperature: 0.1
+tools:
+  read: true
+  grep: true
+  glob: true
+permission:
+  bash: deny
+  edit: deny
+  write: deny
+---
+
+You are a senior code reviewer with 10+ years of experience...
+
+## Integration with Ferg System
+
+### Existing Agents
+
+- `ai-eng/architect-advisor` - System architecture guidance
+- `ai-eng/frontend-reviewer` - Frontend code review
+- `ai-eng/seo-specialist` - SEO optimization
+- `ai-eng/prompt-optimizer` - Prompt enhancement
+
+### Plugin-Dev Agents
+
+- `ai-eng/agent-creator` - AI-assisted agent generation
+- `ai-eng/skill-creator` - Skill development guidance
+- `ai-eng/plugin-validator` - Plugin structure validation
+
+All agents follow the same quality standards and use the build.ts transformation system.