|
|
@@ -0,0 +1,1166 @@
|
|
|
+# JSON-Based Agent Configuration System
|
|
|
+
|
|
|
+**Date**: 2026-02-15
|
|
|
+**Status**: Architecture Design
|
|
|
+**Branch**: `feature/oac-package-refactor`
|
|
|
+**Priority**: CRITICAL - Foundation for v2.0
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🎯 Vision
|
|
|
+
|
|
|
+Transform agent management from markdown-based to **JSON-configured, type-safe, multi-IDE compatible** system with single source of truth.
|
|
|
+
|
|
|
+### Current Problems
|
|
|
+
|
|
|
+❌ **Markdown agents are hard to parse and validate**
|
|
|
+❌ **No type safety or schema validation**
|
|
|
+❌ **Difficult to extract metadata programmatically**
|
|
|
+❌ **Can't easily query agent properties**
|
|
|
+❌ **Version management is manual**
|
|
|
+❌ **Hard to convert between IDE formats**
|
|
|
+❌ **Duplication across IDEs (OpenCode, Claude, Cursor)**
|
|
|
+
|
|
|
+### New Approach
|
|
|
+
|
|
|
+✅ **Single source of truth** - `.opencode/` contains universal format
|
|
|
+✅ **JSON config + Markdown prompts** - Separation of concerns
|
|
|
+✅ **Type-safe** - Full TypeScript interfaces
|
|
|
+✅ **Queryable** - Easy filtering and searching
|
|
|
+✅ **Validatable** - JSON Schema validation
|
|
|
+✅ **Versionable** - Semantic versioning built-in
|
|
|
+✅ **Convertible** - Transform to any IDE format
|
|
|
+✅ **Multi-IDE** - Apply to OpenCode, Claude, Cursor, Windsurf
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🏗️ Architecture
|
|
|
+
|
|
|
+### Single Source of Truth
|
|
|
+
|
|
|
+```
|
|
|
+.opencode/ ← UNIVERSAL FORMAT (source of truth)
|
|
|
+├── agents/
|
|
|
+│ ├── core/
|
|
|
+│ │ ├── openagent/
|
|
|
+│ │ │ ├── agent.json ← Configuration (metadata, permissions, tools)
|
|
|
+│ │ │ ├── prompt.md ← Prompt content (human-readable)
|
|
|
+│ │ │ ├── system.md ← System instructions (optional)
|
|
|
+│ │ │ └── examples.md ← Examples (optional)
|
|
|
+│ │ └── opencoder/
|
|
|
+│ │ ├── agent.json
|
|
|
+│ │ └── prompt.md
|
|
|
+│ │
|
|
|
+│ ├── subagents/
|
|
|
+│ │ ├── code-reviewer/
|
|
|
+│ │ │ ├── agent.json
|
|
|
+│ │ │ └── prompt.md
|
|
|
+│ │ └── test-engineer/
|
|
|
+│ │ ├── agent.json
|
|
|
+│ │ └── prompt.md
|
|
|
+│ │
|
|
|
+│ └── manifest.json ← Registry of all agents
|
|
|
+│
|
|
|
+├── context/ ← Context files (unchanged)
|
|
|
+├── skills/ ← Skills (unchanged)
|
|
|
+├── tools/ ← MCP tools (unchanged)
|
|
|
+└── config.json ← Main OAC config
|
|
|
+
|
|
|
+ ↓ OAC CLI converts/applies ↓
|
|
|
+
|
|
|
+┌────────────┬─────────────┬──────────┬───────────┐
|
|
|
+│ OpenCode │ Claude Code │ Cursor │ Windsurf │
|
|
|
+│ (native) │ (convert) │ (flatten)│ (flatten) │
|
|
|
+└────────────┴─────────────┴──────────┴───────────┘
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 📄 Agent Configuration Schema
|
|
|
+
|
|
|
+### TypeScript Interface
|
|
|
+
|
|
|
+```typescript
|
|
|
+// packages/core/src/types/agent.ts
|
|
|
+
|
|
|
+export interface AgentConfig {
|
|
|
+ // Metadata
|
|
|
+ $schema: string;
|
|
|
+ version: string;
|
|
|
+ id: string;
|
|
|
+ name: string;
|
|
|
+ description: string;
|
|
|
+ category: 'core' | 'subagent' | 'specialist' | 'meta';
|
|
|
+
|
|
|
+ // Agent behavior
|
|
|
+ mode: 'primary' | 'subagent' | 'tool';
|
|
|
+ model?: string;
|
|
|
+
|
|
|
+ // Prompt configuration
|
|
|
+ prompt: {
|
|
|
+ file?: string; // Path to prompt file (e.g., "./prompt.md")
|
|
|
+ inline?: string; // Inline prompt (for simple agents)
|
|
|
+ system?: string; // System instructions file
|
|
|
+ examples?: string; // Examples file
|
|
|
+ temperature?: number;
|
|
|
+ maxTokens?: number;
|
|
|
+ };
|
|
|
+
|
|
|
+ // Permissions (approval gates)
|
|
|
+ permissions: {
|
|
|
+ bash?: PermissionLevel;
|
|
|
+ write?: PermissionLevel;
|
|
|
+ edit?: PermissionLevel;
|
|
|
+ read?: PermissionLevel;
|
|
|
+ task?: PermissionLevel;
|
|
|
+ [key: string]: PermissionLevel | undefined;
|
|
|
+ };
|
|
|
+
|
|
|
+ // Tools (MCP)
|
|
|
+ tools: {
|
|
|
+ [toolName: string]: boolean | ToolConfig;
|
|
|
+ };
|
|
|
+
|
|
|
+ // Skills
|
|
|
+ skills?: string[];
|
|
|
+
|
|
|
+ // Plugins
|
|
|
+ plugins?: string[];
|
|
|
+
|
|
|
+ // Context files (@ notation)
|
|
|
+ context?: string[];
|
|
|
+
|
|
|
+ // Dependencies
|
|
|
+ dependencies?: {
|
|
|
+ agents?: string[];
|
|
|
+ subagents?: string[];
|
|
|
+ skills?: string[];
|
|
|
+ tools?: string[];
|
|
|
+ };
|
|
|
+
|
|
|
+ // IDE Compatibility
|
|
|
+ compatibility: {
|
|
|
+ opencode: CompatibilityLevel;
|
|
|
+ claude: CompatibilityLevel;
|
|
|
+ cursor: CompatibilityLevel;
|
|
|
+ windsurf: CompatibilityLevel;
|
|
|
+ [ide: string]: CompatibilityLevel;
|
|
|
+ };
|
|
|
+
|
|
|
+ // Metadata
|
|
|
+ author?: string;
|
|
|
+ license?: string;
|
|
|
+ repository?: string;
|
|
|
+ tags?: string[];
|
|
|
+}
|
|
|
+
|
|
|
+export type PermissionLevel = 'allow' | 'approve' | 'deny';
|
|
|
+export type CompatibilityLevel = 'full' | 'partial' | 'none';
|
|
|
+
|
|
|
+export interface ToolConfig {
|
|
|
+ enabled: boolean;
|
|
|
+ config?: Record<string, any>;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### JSON Schema
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "$schema": "http://json-schema.org/draft-07/schema#",
|
|
|
+ "type": "object",
|
|
|
+ "required": ["$schema", "version", "id", "name", "mode", "prompt", "permissions", "tools", "compatibility"],
|
|
|
+ "properties": {
|
|
|
+ "$schema": {
|
|
|
+ "type": "string",
|
|
|
+ "const": "https://openagents.dev/schemas/agent-v2.json"
|
|
|
+ },
|
|
|
+ "version": {
|
|
|
+ "type": "string",
|
|
|
+ "pattern": "^\\d+\\.\\d+\\.\\d+$"
|
|
|
+ },
|
|
|
+ "id": {
|
|
|
+ "type": "string",
|
|
|
+ "pattern": "^[a-z0-9-]+$"
|
|
|
+ },
|
|
|
+ "name": {
|
|
|
+ "type": "string"
|
|
|
+ },
|
|
|
+ "description": {
|
|
|
+ "type": "string"
|
|
|
+ },
|
|
|
+ "category": {
|
|
|
+ "type": "string",
|
|
|
+ "enum": ["core", "subagent", "specialist", "meta"]
|
|
|
+ },
|
|
|
+ "mode": {
|
|
|
+ "type": "string",
|
|
|
+ "enum": ["primary", "subagent", "tool"]
|
|
|
+ },
|
|
|
+ "model": {
|
|
|
+ "type": "string"
|
|
|
+ },
|
|
|
+ "prompt": {
|
|
|
+ "type": "object",
|
|
|
+ "properties": {
|
|
|
+ "file": { "type": "string" },
|
|
|
+ "inline": { "type": "string" },
|
|
|
+ "system": { "type": "string" },
|
|
|
+ "examples": { "type": "string" },
|
|
|
+ "temperature": { "type": "number", "minimum": 0, "maximum": 2 },
|
|
|
+ "maxTokens": { "type": "number", "minimum": 1 }
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "permissions": {
|
|
|
+ "type": "object",
|
|
|
+ "additionalProperties": {
|
|
|
+ "type": "string",
|
|
|
+ "enum": ["allow", "approve", "deny"]
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "tools": {
|
|
|
+ "type": "object",
|
|
|
+ "additionalProperties": {
|
|
|
+ "oneOf": [
|
|
|
+ { "type": "boolean" },
|
|
|
+ {
|
|
|
+ "type": "object",
|
|
|
+ "properties": {
|
|
|
+ "enabled": { "type": "boolean" },
|
|
|
+ "config": { "type": "object" }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "compatibility": {
|
|
|
+ "type": "object",
|
|
|
+ "required": ["opencode", "claude", "cursor", "windsurf"],
|
|
|
+ "properties": {
|
|
|
+ "opencode": { "type": "string", "enum": ["full", "partial", "none"] },
|
|
|
+ "claude": { "type": "string", "enum": ["full", "partial", "none"] },
|
|
|
+ "cursor": { "type": "string", "enum": ["full", "partial", "none"] },
|
|
|
+ "windsurf": { "type": "string", "enum": ["full", "partial", "none"] }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 📋 Example Configurations
|
|
|
+
|
|
|
+### Example 1: OpenAgent (Primary Agent)
|
|
|
+
|
|
|
+**`.opencode/agents/core/openagent/agent.json`**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "$schema": "https://openagents.dev/schemas/agent-v2.json",
|
|
|
+ "version": "2.0.0",
|
|
|
+ "id": "openagent",
|
|
|
+ "name": "OpenAgent",
|
|
|
+ "description": "Meta orchestration agent for complex workflows",
|
|
|
+ "category": "core",
|
|
|
+
|
|
|
+ "mode": "primary",
|
|
|
+ "model": "anthropic/claude-sonnet-4-20250514",
|
|
|
+
|
|
|
+ "prompt": {
|
|
|
+ "file": "./prompt.md",
|
|
|
+ "system": "./system.md",
|
|
|
+ "examples": "./examples.md",
|
|
|
+ "temperature": 0.7,
|
|
|
+ "maxTokens": 8000
|
|
|
+ },
|
|
|
+
|
|
|
+ "permissions": {
|
|
|
+ "bash": "approve",
|
|
|
+ "write": "approve",
|
|
|
+ "edit": "approve",
|
|
|
+ "read": "allow",
|
|
|
+ "task": "approve",
|
|
|
+ "glob": "allow",
|
|
|
+ "grep": "allow"
|
|
|
+ },
|
|
|
+
|
|
|
+ "tools": {
|
|
|
+ "bash": true,
|
|
|
+ "read": true,
|
|
|
+ "write": true,
|
|
|
+ "edit": true,
|
|
|
+ "task": true,
|
|
|
+ "glob": true,
|
|
|
+ "grep": true,
|
|
|
+ "todowrite": true,
|
|
|
+ "todoread": true
|
|
|
+ },
|
|
|
+
|
|
|
+ "skills": [
|
|
|
+ "task-management",
|
|
|
+ "context-discovery"
|
|
|
+ ],
|
|
|
+
|
|
|
+ "plugins": [],
|
|
|
+
|
|
|
+ "context": [
|
|
|
+ "@core/standards/code-quality",
|
|
|
+ "@core/workflows/task-delegation",
|
|
|
+ "@core/workflows/code-review"
|
|
|
+ ],
|
|
|
+
|
|
|
+ "dependencies": {
|
|
|
+ "subagents": [
|
|
|
+ "task-manager",
|
|
|
+ "context-scout",
|
|
|
+ "coder-agent",
|
|
|
+ "code-reviewer",
|
|
|
+ "test-engineer",
|
|
|
+ "doc-writer"
|
|
|
+ ],
|
|
|
+ "skills": [
|
|
|
+ "task-management"
|
|
|
+ ],
|
|
|
+ "tools": [
|
|
|
+ "bash",
|
|
|
+ "read",
|
|
|
+ "write",
|
|
|
+ "edit",
|
|
|
+ "task"
|
|
|
+ ]
|
|
|
+ },
|
|
|
+
|
|
|
+ "compatibility": {
|
|
|
+ "opencode": "full",
|
|
|
+ "claude": "full",
|
|
|
+ "cursor": "partial",
|
|
|
+ "windsurf": "partial"
|
|
|
+ },
|
|
|
+
|
|
|
+ "author": "NextSystems",
|
|
|
+ "license": "MIT",
|
|
|
+ "repository": "https://github.com/nextsystems/openagents-control",
|
|
|
+ "tags": [
|
|
|
+ "orchestration",
|
|
|
+ "meta",
|
|
|
+ "planning",
|
|
|
+ "delegation"
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**`.opencode/agents/core/openagent/prompt.md`**:
|
|
|
+
|
|
|
+```markdown
|
|
|
+You are OpenAgent, a meta orchestration agent for complex workflows.
|
|
|
+
|
|
|
+## Your Role
|
|
|
+
|
|
|
+You coordinate complex tasks by:
|
|
|
+1. Analyzing user requests
|
|
|
+2. Breaking down into subtasks
|
|
|
+3. Delegating to specialist agents
|
|
|
+4. Validating results
|
|
|
+5. Completing the workflow
|
|
|
+
|
|
|
+## Key Principles
|
|
|
+
|
|
|
+- Always use ContextScout before execution
|
|
|
+- Request approval before bash/write/edit/task
|
|
|
+- Stop on test failures
|
|
|
+- Maintain clear communication
|
|
|
+
|
|
|
+## Workflow
|
|
|
+
|
|
|
+[Stage 1: Analyze]
|
|
|
+- Classify task type and complexity
|
|
|
+- Use ContextScout for discovery
|
|
|
+
|
|
|
+[Stage 2: Plan]
|
|
|
+- Present plan and get approval
|
|
|
+- Identify context needed
|
|
|
+
|
|
|
+[Stage 3: Execute]
|
|
|
+- Load context
|
|
|
+- Execute or delegate
|
|
|
+- Track progress
|
|
|
+
|
|
|
+[Stage 4: Validate]
|
|
|
+- Run tests
|
|
|
+- Stop on failure
|
|
|
+- Report results
|
|
|
+
|
|
|
+[Stage 5: Complete]
|
|
|
+- Update docs
|
|
|
+- Summarize changes
|
|
|
+- Confirm satisfaction
|
|
|
+```
|
|
|
+
|
|
|
+### Example 2: CodeReviewer (Subagent)
|
|
|
+
|
|
|
+**`.opencode/agents/subagents/code-reviewer/agent.json`**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "$schema": "https://openagents.dev/schemas/agent-v2.json",
|
|
|
+ "version": "1.0.0",
|
|
|
+ "id": "code-reviewer",
|
|
|
+ "name": "CodeReviewer",
|
|
|
+ "description": "Reviews code for best practices and potential issues",
|
|
|
+ "category": "subagent",
|
|
|
+
|
|
|
+ "mode": "subagent",
|
|
|
+ "model": "anthropic/claude-sonnet-4-20250514",
|
|
|
+
|
|
|
+ "prompt": {
|
|
|
+ "file": "./prompt.md",
|
|
|
+ "temperature": 0.3,
|
|
|
+ "maxTokens": 4000
|
|
|
+ },
|
|
|
+
|
|
|
+ "permissions": {
|
|
|
+ "bash": "deny",
|
|
|
+ "write": "deny",
|
|
|
+ "edit": "deny",
|
|
|
+ "read": "allow",
|
|
|
+ "glob": "allow",
|
|
|
+ "grep": "allow"
|
|
|
+ },
|
|
|
+
|
|
|
+ "tools": {
|
|
|
+ "read": true,
|
|
|
+ "glob": true,
|
|
|
+ "grep": true
|
|
|
+ },
|
|
|
+
|
|
|
+ "skills": [],
|
|
|
+ "plugins": [],
|
|
|
+
|
|
|
+ "context": [
|
|
|
+ "@core/standards/code-quality",
|
|
|
+ "@core/standards/security-patterns",
|
|
|
+ "@core/workflows/code-review"
|
|
|
+ ],
|
|
|
+
|
|
|
+ "dependencies": {
|
|
|
+ "tools": ["read", "glob", "grep"]
|
|
|
+ },
|
|
|
+
|
|
|
+ "compatibility": {
|
|
|
+ "opencode": "full",
|
|
|
+ "claude": "full",
|
|
|
+ "cursor": "partial",
|
|
|
+ "windsurf": "partial"
|
|
|
+ },
|
|
|
+
|
|
|
+ "author": "NextSystems",
|
|
|
+ "license": "MIT",
|
|
|
+ "tags": [
|
|
|
+ "code-review",
|
|
|
+ "quality",
|
|
|
+ "security"
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**`.opencode/agents/subagents/code-reviewer/prompt.md`**:
|
|
|
+
|
|
|
+```markdown
|
|
|
+You are CodeReviewer, a specialist in code quality and security.
|
|
|
+
|
|
|
+## Your Role
|
|
|
+
|
|
|
+Review code for:
|
|
|
+- Security vulnerabilities
|
|
|
+- Performance issues
|
|
|
+- Best practices violations
|
|
|
+- Maintainability concerns
|
|
|
+- Code smells
|
|
|
+
|
|
|
+## Review Process
|
|
|
+
|
|
|
+1. Read the code files
|
|
|
+2. Analyze against standards
|
|
|
+3. Identify issues by severity
|
|
|
+4. Provide actionable recommendations
|
|
|
+5. Suggest improvements
|
|
|
+
|
|
|
+## Output Format
|
|
|
+
|
|
|
+**Critical Issues**: Security vulnerabilities, data loss risks
|
|
|
+**High Priority**: Performance problems, major code smells
|
|
|
+**Medium Priority**: Best practice violations
|
|
|
+**Low Priority**: Style improvements, minor optimizations
|
|
|
+
|
|
|
+Always provide specific line numbers and code examples.
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🔧 Format Converters
|
|
|
+
|
|
|
+### OpenCode Converter
|
|
|
+
|
|
|
+```typescript
|
|
|
+// packages/core/src/agent/converters/opencode.ts
|
|
|
+
|
|
|
+export class OpenCodeConverter {
|
|
|
+ convert(config: AgentConfig): string {
|
|
|
+ const openCodeConfig = {
|
|
|
+ $schema: "https://opencode.ai/config.json",
|
|
|
+ agent: {
|
|
|
+ [config.id]: {
|
|
|
+ mode: config.mode,
|
|
|
+ model: config.model,
|
|
|
+ prompt: config.prompt.file
|
|
|
+ ? `{file:${config.prompt.file}}`
|
|
|
+ : config.prompt.inline,
|
|
|
+ tools: this.convertTools(config.tools),
|
|
|
+ permissions: config.permissions
|
|
|
+ }
|
|
|
+ }
|
|
|
+ };
|
|
|
+
|
|
|
+ return JSON.stringify(openCodeConfig, null, 2);
|
|
|
+ }
|
|
|
+
|
|
|
+ private convertTools(tools: Record<string, boolean | any>): Record<string, boolean> {
|
|
|
+ const result: Record<string, boolean> = {};
|
|
|
+
|
|
|
+ for (const [name, value] of Object.entries(tools)) {
|
|
|
+ result[name] = typeof value === 'boolean' ? value : value.enabled;
|
|
|
+ }
|
|
|
+
|
|
|
+ return result;
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### Claude Converter
|
|
|
+
|
|
|
+```typescript
|
|
|
+// packages/core/src/agent/converters/claude.ts
|
|
|
+
|
|
|
+export class ClaudeConverter {
|
|
|
+ convert(config: AgentConfig): string {
|
|
|
+ // Claude uses similar format but doesn't support skills/plugins
|
|
|
+
|
|
|
+ const claudeConfig = {
|
|
|
+ agent: {
|
|
|
+ [config.id]: {
|
|
|
+ mode: config.mode,
|
|
|
+ model: config.model,
|
|
|
+ prompt: config.prompt.content || config.prompt.inline,
|
|
|
+ tools: this.filterSupportedTools(config.tools),
|
|
|
+ permissions: config.permissions
|
|
|
+ }
|
|
|
+ }
|
|
|
+ };
|
|
|
+
|
|
|
+ return JSON.stringify(claudeConfig, null, 2);
|
|
|
+ }
|
|
|
+
|
|
|
+ private filterSupportedTools(tools: Record<string, boolean | any>): Record<string, boolean> {
|
|
|
+ // Claude only supports: bash, read, write, edit, glob, grep
|
|
|
+ const supported = ['bash', 'read', 'write', 'edit', 'glob', 'grep'];
|
|
|
+ const result: Record<string, boolean> = {};
|
|
|
+
|
|
|
+ for (const [name, value] of Object.entries(tools)) {
|
|
|
+ if (supported.includes(name)) {
|
|
|
+ result[name] = typeof value === 'boolean' ? value : value.enabled;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ return result;
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### Cursor Converter
|
|
|
+
|
|
|
+```typescript
|
|
|
+// packages/core/src/agent/converters/cursor.ts
|
|
|
+
|
|
|
+export class CursorConverter {
|
|
|
+ convert(config: AgentConfig): string {
|
|
|
+ // Cursor uses plain text .cursorrules
|
|
|
+ let rules = `# ${config.name}\n\n`;
|
|
|
+ rules += `${config.description}\n\n`;
|
|
|
+
|
|
|
+ // Add prompt content (flattened)
|
|
|
+ if (config.prompt.content) {
|
|
|
+ rules += this.flattenPrompt(config.prompt.content);
|
|
|
+ }
|
|
|
+
|
|
|
+ // Add permissions as rules
|
|
|
+ rules += '\n\n## Permissions\n\n';
|
|
|
+ for (const [tool, level] of Object.entries(config.permissions)) {
|
|
|
+ rules += `- ${tool}: ${level}\n`;
|
|
|
+ }
|
|
|
+
|
|
|
+ return rules;
|
|
|
+ }
|
|
|
+
|
|
|
+ private flattenPrompt(content: string): string {
|
|
|
+ // Remove complex sections, keep simple instructions
|
|
|
+ let result = content;
|
|
|
+
|
|
|
+ // Remove frontmatter
|
|
|
+ result = result.replace(/^---[\s\S]*?---\n/m, '');
|
|
|
+
|
|
|
+ // Remove complex sections
|
|
|
+ const sectionsToRemove = ['Workflow', 'Examples', 'Advanced'];
|
|
|
+ for (const section of sectionsToRemove) {
|
|
|
+ const regex = new RegExp(`## ${section}[\\s\\S]*?(?=##|$)`, 'gi');
|
|
|
+ result = result.replace(regex, '');
|
|
|
+ }
|
|
|
+
|
|
|
+ return result.trim();
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🚀 OAC CLI Commands
|
|
|
+
|
|
|
+### Convert Command
|
|
|
+
|
|
|
+```bash
|
|
|
+# Convert agent to specific IDE format
|
|
|
+oac convert openagent --to=opencode
|
|
|
+oac convert openagent --to=claude
|
|
|
+oac convert openagent --to=cursor
|
|
|
+
|
|
|
+# Convert all agents
|
|
|
+oac convert --all --to=opencode
|
|
|
+
|
|
|
+# Output to file
|
|
|
+oac convert openagent --to=opencode --output=.opencode/config.json
|
|
|
+
|
|
|
+# Dry run (show output without writing)
|
|
|
+oac convert openagent --to=cursor --dry-run
|
|
|
+```
|
|
|
+
|
|
|
+### Validate Command
|
|
|
+
|
|
|
+```bash
|
|
|
+# Validate agent config against schema
|
|
|
+oac validate openagent
|
|
|
+
|
|
|
+# Validate all agents
|
|
|
+oac validate --all
|
|
|
+
|
|
|
+# Check IDE compatibility
|
|
|
+oac validate openagent --ide=cursor
|
|
|
+
|
|
|
+# Verbose output
|
|
|
+oac validate openagent --verbose
|
|
|
+```
|
|
|
+
|
|
|
+### Apply Command
|
|
|
+
|
|
|
+```bash
|
|
|
+# Apply agent to IDE (auto-convert)
|
|
|
+oac apply openagent --ide=opencode
|
|
|
+oac apply openagent --ide=claude
|
|
|
+oac apply openagent --ide=cursor
|
|
|
+
|
|
|
+# Apply all agents
|
|
|
+oac apply --all --ide=opencode
|
|
|
+
|
|
|
+# Apply with profile
|
|
|
+oac apply --profile=developer --ide=opencode
|
|
|
+
|
|
|
+# Dry run
|
|
|
+oac apply openagent --ide=cursor --dry-run
|
|
|
+
|
|
|
+# Force overwrite
|
|
|
+oac apply openagent --ide=opencode --force
|
|
|
+```
|
|
|
+
|
|
|
+### Create Command
|
|
|
+
|
|
|
+```bash
|
|
|
+# Create new agent interactively
|
|
|
+oac create agent
|
|
|
+
|
|
|
+# Create from template
|
|
|
+oac create agent --template=subagent --name=my-reviewer
|
|
|
+
|
|
|
+# Create with wizard
|
|
|
+oac create agent --wizard
|
|
|
+```
|
|
|
+
|
|
|
+### Info Command
|
|
|
+
|
|
|
+```bash
|
|
|
+# Show agent info
|
|
|
+oac info openagent
|
|
|
+
|
|
|
+# Show compatibility matrix
|
|
|
+oac info openagent --compatibility
|
|
|
+
|
|
|
+# Show dependencies
|
|
|
+oac info openagent --dependencies
|
|
|
+
|
|
|
+# Show all metadata
|
|
|
+oac info openagent --full
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 📊 Benefits
|
|
|
+
|
|
|
+### 1. Type Safety
|
|
|
+
|
|
|
+```typescript
|
|
|
+// Full TypeScript support
|
|
|
+import { AgentConfig } from '@oac/types';
|
|
|
+
|
|
|
+const config: AgentConfig = {
|
|
|
+ // IDE autocomplete works!
|
|
|
+ id: 'my-agent',
|
|
|
+ name: 'MyAgent',
|
|
|
+ mode: 'subagent',
|
|
|
+ // TypeScript validates everything
|
|
|
+ permissions: {
|
|
|
+ bash: 'approve', // ✅ Valid
|
|
|
+ write: 'invalid' // ❌ Type error!
|
|
|
+ }
|
|
|
+};
|
|
|
+```
|
|
|
+
|
|
|
+### 2. Easy Querying
|
|
|
+
|
|
|
+```typescript
|
|
|
+// Find all agents that use bash
|
|
|
+const bashAgents = agents.filter(a => a.tools.bash === true);
|
|
|
+
|
|
|
+// Find agents compatible with Cursor
|
|
|
+const cursorAgents = agents.filter(a => a.compatibility.cursor !== 'none');
|
|
|
+
|
|
|
+// Find all subagents
|
|
|
+const subagents = agents.filter(a => a.mode === 'subagent');
|
|
|
+
|
|
|
+// Find agents by category
|
|
|
+const coreAgents = agents.filter(a => a.category === 'core');
|
|
|
+```
|
|
|
+
|
|
|
+### 3. Schema Validation
|
|
|
+
|
|
|
+```bash
|
|
|
+# Validate against JSON schema
|
|
|
+oac validate openagent
|
|
|
+
|
|
|
+# Output:
|
|
|
+# ✅ Valid agent config
|
|
|
+# ✅ All required fields present
|
|
|
+# ✅ Permissions valid (allow/approve/deny)
|
|
|
+# ✅ Tools valid
|
|
|
+# ✅ Compatibility matrix complete
|
|
|
+# ✅ Version format valid (2.0.0)
|
|
|
+```
|
|
|
+
|
|
|
+### 4. Version Management
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "version": "2.0.0",
|
|
|
+ "compatibility": {
|
|
|
+ "oac": ">=0.8.0",
|
|
|
+ "opencode": ">=1.0.0"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 5. Easy Conversion
|
|
|
+
|
|
|
+```typescript
|
|
|
+// Convert to any format
|
|
|
+const openCodeConfig = converterRegistry.convert(agentConfig, 'opencode');
|
|
|
+const claudeConfig = converterRegistry.convert(agentConfig, 'claude');
|
|
|
+const cursorRules = converterRegistry.convert(agentConfig, 'cursor');
|
|
|
+
|
|
|
+// All from single source!
|
|
|
+```
|
|
|
+
|
|
|
+### 6. Separation of Concerns
|
|
|
+
|
|
|
+```
|
|
|
+agent.json → Configuration (machine-readable, type-safe)
|
|
|
+prompt.md → Content (human-readable, editable)
|
|
|
+system.md → System instructions (optional)
|
|
|
+examples.md → Examples (optional)
|
|
|
+```
|
|
|
+
|
|
|
+### 7. IDE Support
|
|
|
+
|
|
|
+```typescript
|
|
|
+// VS Code autocomplete
|
|
|
+{
|
|
|
+ "id": "my-agent",
|
|
|
+ "mode": "sub" // ← Autocomplete suggests: "subagent"
|
|
|
+ "permissions": {
|
|
|
+ "bash": "app" // ← Autocomplete suggests: "approve"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🗺️ Migration Path
|
|
|
+
|
|
|
+### Phase 1: Infrastructure (Week 1)
|
|
|
+
|
|
|
+**Goal**: Build JSON config system and converters
|
|
|
+
|
|
|
+- [ ] Define TypeScript interfaces (`packages/core/src/types/agent.ts`)
|
|
|
+- [ ] Create JSON schema (`packages/core/src/schemas/agent-v2.json`)
|
|
|
+- [ ] Build config loader (`packages/core/src/agent/loader.ts`)
|
|
|
+- [ ] Build converters:
|
|
|
+ - [ ] OpenCode converter
|
|
|
+ - [ ] Claude converter
|
|
|
+ - [ ] Cursor converter
|
|
|
+ - [ ] Windsurf converter
|
|
|
+- [ ] Build converter registry
|
|
|
+- [ ] Add unit tests
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- ✅ TypeScript types
|
|
|
+- ✅ JSON schema
|
|
|
+- ✅ Config loader with validation
|
|
|
+- ✅ All converters implemented
|
|
|
+- ✅ Test coverage >80%
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 2: CLI Commands (Week 2)
|
|
|
+
|
|
|
+**Goal**: Implement CLI for convert/validate/apply
|
|
|
+
|
|
|
+- [ ] Implement `oac convert` command
|
|
|
+ - [ ] Support `--to` flag (opencode, claude, cursor)
|
|
|
+ - [ ] Support `--output` flag
|
|
|
+ - [ ] Support `--dry-run` flag
|
|
|
+ - [ ] Support `--all` flag
|
|
|
+- [ ] Implement `oac validate` command
|
|
|
+ - [ ] Schema validation
|
|
|
+ - [ ] Compatibility checking
|
|
|
+ - [ ] Dependency validation
|
|
|
+- [ ] Implement `oac apply` command
|
|
|
+ - [ ] Auto-detect IDE
|
|
|
+ - [ ] Convert and apply
|
|
|
+ - [ ] Support `--force` flag
|
|
|
+ - [ ] Support `--dry-run` flag
|
|
|
+- [ ] Implement `oac info` command
|
|
|
+ - [ ] Show agent metadata
|
|
|
+ - [ ] Show compatibility matrix
|
|
|
+ - [ ] Show dependencies
|
|
|
+- [ ] Add help text and examples
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- ✅ All CLI commands working
|
|
|
+- ✅ Help documentation
|
|
|
+- ✅ Error handling
|
|
|
+- ✅ User-friendly output
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 3: Migration Script (Week 3)
|
|
|
+
|
|
|
+**Goal**: Migrate existing markdown agents to JSON config
|
|
|
+
|
|
|
+- [ ] Write migration script (`scripts/migrate-agents.ts`)
|
|
|
+ - [ ] Parse markdown frontmatter
|
|
|
+ - [ ] Extract metadata
|
|
|
+ - [ ] Generate agent.json
|
|
|
+ - [ ] Split prompt into prompt.md
|
|
|
+ - [ ] Preserve all information
|
|
|
+- [ ] Migrate core agents:
|
|
|
+ - [ ] OpenAgent
|
|
|
+ - [ ] OpenCoder
|
|
|
+- [ ] Migrate all subagents:
|
|
|
+ - [ ] TaskManager
|
|
|
+ - [ ] ContextScout
|
|
|
+ - [ ] CoderAgent
|
|
|
+ - [ ] CodeReviewer
|
|
|
+ - [ ] TestEngineer
|
|
|
+ - [ ] DocWriter
|
|
|
+ - [ ] BuildAgent
|
|
|
+ - [ ] (all others)
|
|
|
+- [ ] Generate manifest.json
|
|
|
+- [ ] Validate all migrated configs
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- ✅ Migration script
|
|
|
+- ✅ All agents migrated
|
|
|
+- ✅ Validation passing
|
|
|
+- ✅ No data loss
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 4: Testing & Validation (Week 4)
|
|
|
+
|
|
|
+**Goal**: Comprehensive testing of new system
|
|
|
+
|
|
|
+- [ ] Unit tests:
|
|
|
+ - [ ] Config loader
|
|
|
+ - [ ] Each converter
|
|
|
+ - [ ] Validation logic
|
|
|
+- [ ] Integration tests:
|
|
|
+ - [ ] Convert → Apply workflow
|
|
|
+ - [ ] Multi-IDE apply
|
|
|
+ - [ ] Profile-based apply
|
|
|
+- [ ] End-to-end tests:
|
|
|
+ - [ ] Create agent → Validate → Apply → Test
|
|
|
+- [ ] Compatibility tests:
|
|
|
+ - [ ] OpenCode native format
|
|
|
+ - [ ] Claude conversion
|
|
|
+ - [ ] Cursor flattening
|
|
|
+- [ ] Performance tests:
|
|
|
+ - [ ] Load 100+ agents
|
|
|
+ - [ ] Convert all agents
|
|
|
+ - [ ] Apply to multiple IDEs
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- ✅ Test coverage >90%
|
|
|
+- ✅ All tests passing
|
|
|
+- ✅ Performance benchmarks
|
|
|
+- ✅ Compatibility verified
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 5: Documentation (Week 5)
|
|
|
+
|
|
|
+**Goal**: Complete documentation for new system
|
|
|
+
|
|
|
+- [ ] User documentation:
|
|
|
+ - [ ] JSON config format guide
|
|
|
+ - [ ] Migration guide (markdown → JSON)
|
|
|
+ - [ ] CLI command reference
|
|
|
+ - [ ] IDE compatibility matrix
|
|
|
+ - [ ] Best practices
|
|
|
+- [ ] Developer documentation:
|
|
|
+ - [ ] TypeScript interfaces
|
|
|
+ - [ ] Converter API
|
|
|
+ - [ ] Adding new IDE support
|
|
|
+ - [ ] Schema extension guide
|
|
|
+- [ ] Examples:
|
|
|
+ - [ ] Simple agent
|
|
|
+ - [ ] Complex agent with all features
|
|
|
+ - [ ] Subagent
|
|
|
+ - [ ] Multi-IDE setup
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- ✅ Complete user docs
|
|
|
+- ✅ Complete dev docs
|
|
|
+- ✅ Example agents
|
|
|
+- ✅ Migration guide
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 6: Deprecation (Week 6)
|
|
|
+
|
|
|
+**Goal**: Deprecate old markdown format
|
|
|
+
|
|
|
+- [ ] Add deprecation warnings:
|
|
|
+ - [ ] Warn when loading markdown agents
|
|
|
+ - [ ] Suggest migration command
|
|
|
+ - [ ] Show migration guide link
|
|
|
+- [ ] Update registry.json:
|
|
|
+ - [ ] Point to new JSON configs
|
|
|
+ - [ ] Mark markdown agents as deprecated
|
|
|
+- [ ] Update install.sh:
|
|
|
+ - [ ] Use new JSON format
|
|
|
+ - [ ] Auto-migrate on install
|
|
|
+- [ ] Update CI/CD:
|
|
|
+ - [ ] Validate JSON configs
|
|
|
+ - [ ] Fail on markdown agents (optional)
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- ✅ Deprecation warnings
|
|
|
+- ✅ Updated registry
|
|
|
+- ✅ Updated installer
|
|
|
+- ✅ CI/CD validation
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 📋 Implementation Checklist
|
|
|
+
|
|
|
+### Week 1: Infrastructure
|
|
|
+- [ ] Create `packages/core/src/types/agent.ts`
|
|
|
+- [ ] Create `packages/core/src/schemas/agent-v2.json`
|
|
|
+- [ ] Create `packages/core/src/agent/loader.ts`
|
|
|
+- [ ] Create `packages/core/src/agent/converters/opencode.ts`
|
|
|
+- [ ] Create `packages/core/src/agent/converters/claude.ts`
|
|
|
+- [ ] Create `packages/core/src/agent/converters/cursor.ts`
|
|
|
+- [ ] Create `packages/core/src/agent/converters/windsurf.ts`
|
|
|
+- [ ] Create `packages/core/src/agent/converters/registry.ts`
|
|
|
+- [ ] Write unit tests
|
|
|
+- [ ] Validate with sample configs
|
|
|
+
|
|
|
+### Week 2: CLI Commands
|
|
|
+- [ ] Create `packages/core/src/cli/convert.ts`
|
|
|
+- [ ] Create `packages/core/src/cli/validate.ts`
|
|
|
+- [ ] Create `packages/core/src/cli/apply.ts`
|
|
|
+- [ ] Create `packages/core/src/cli/info.ts`
|
|
|
+- [ ] Add to main CLI entry point
|
|
|
+- [ ] Write help text
|
|
|
+- [ ] Add examples
|
|
|
+- [ ] Test all commands
|
|
|
+
|
|
|
+### Week 3: Migration
|
|
|
+- [ ] Create `scripts/migrate-agents.ts`
|
|
|
+- [ ] Migrate OpenAgent
|
|
|
+- [ ] Migrate OpenCoder
|
|
|
+- [ ] Migrate all subagents
|
|
|
+- [ ] Generate manifest.json
|
|
|
+- [ ] Validate all configs
|
|
|
+- [ ] Test conversions
|
|
|
+
|
|
|
+### Week 4: Testing
|
|
|
+- [ ] Write unit tests
|
|
|
+- [ ] Write integration tests
|
|
|
+- [ ] Write e2e tests
|
|
|
+- [ ] Performance testing
|
|
|
+- [ ] Compatibility testing
|
|
|
+- [ ] Fix any issues
|
|
|
+
|
|
|
+### Week 5: Documentation
|
|
|
+- [ ] Write user guide
|
|
|
+- [ ] Write dev guide
|
|
|
+- [ ] Write migration guide
|
|
|
+- [ ] Create examples
|
|
|
+- [ ] Update README
|
|
|
+- [ ] Update CHANGELOG
|
|
|
+
|
|
|
+### Week 6: Deprecation
|
|
|
+- [ ] Add warnings
|
|
|
+- [ ] Update registry
|
|
|
+- [ ] Update installer
|
|
|
+- [ ] Update CI/CD
|
|
|
+- [ ] Final testing
|
|
|
+- [ ] Release v2.0.0
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🎯 Success Criteria
|
|
|
+
|
|
|
+### Must Have
|
|
|
+- ✅ All agents converted to JSON config
|
|
|
+- ✅ All CLI commands working
|
|
|
+- ✅ OpenCode, Claude, Cursor converters working
|
|
|
+- ✅ Schema validation working
|
|
|
+- ✅ Migration script working
|
|
|
+- ✅ Documentation complete
|
|
|
+- ✅ Tests passing (>90% coverage)
|
|
|
+
|
|
|
+### Nice to Have
|
|
|
+- ✅ Windsurf converter
|
|
|
+- ✅ Auto-migration on install
|
|
|
+- ✅ IDE detection
|
|
|
+- ✅ Interactive agent creation wizard
|
|
|
+- ✅ Web-based config editor
|
|
|
+
|
|
|
+### Future Enhancements
|
|
|
+- 🔮 Remote agent registry
|
|
|
+- 🔮 Agent marketplace
|
|
|
+- 🔮 Visual agent builder
|
|
|
+- 🔮 Agent versioning system
|
|
|
+- 🔮 Agent templates library
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 📊 Comparison: Before vs After
|
|
|
+
|
|
|
+### Before (Markdown)
|
|
|
+
|
|
|
+```markdown
|
|
|
+---
|
|
|
+id: openagent
|
|
|
+name: OpenAgent
|
|
|
+type: orchestrator
|
|
|
+---
|
|
|
+
|
|
|
+# OpenAgent
|
|
|
+
|
|
|
+You are OpenAgent...
|
|
|
+
|
|
|
+## Tools
|
|
|
+- bash (approve)
|
|
|
+- write (approve)
|
|
|
+- edit (approve)
|
|
|
+
|
|
|
+## Skills
|
|
|
+- task-management
|
|
|
+
|
|
|
+## Context
|
|
|
+- .opencode/context/core/standards/code-quality.md
|
|
|
+```
|
|
|
+
|
|
|
+**Problems**:
|
|
|
+- ❌ Hard to parse
|
|
|
+- ❌ No validation
|
|
|
+- ❌ No type safety
|
|
|
+- ❌ Hard to query
|
|
|
+- ❌ Manual conversion
|
|
|
+
|
|
|
+### After (JSON + Markdown)
|
|
|
+
|
|
|
+**agent.json**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "id": "openagent",
|
|
|
+ "name": "OpenAgent",
|
|
|
+ "mode": "primary",
|
|
|
+ "prompt": { "file": "./prompt.md" },
|
|
|
+ "permissions": {
|
|
|
+ "bash": "approve",
|
|
|
+ "write": "approve",
|
|
|
+ "edit": "approve"
|
|
|
+ },
|
|
|
+ "tools": {
|
|
|
+ "bash": true,
|
|
|
+ "write": true,
|
|
|
+ "edit": true
|
|
|
+ },
|
|
|
+ "skills": ["task-management"],
|
|
|
+ "context": ["@core/standards/code-quality"]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**prompt.md**:
|
|
|
+```markdown
|
|
|
+You are OpenAgent...
|
|
|
+```
|
|
|
+
|
|
|
+**Benefits**:
|
|
|
+- ✅ Easy to parse
|
|
|
+- ✅ Schema validated
|
|
|
+- ✅ Type safe
|
|
|
+- ✅ Easy to query
|
|
|
+- ✅ Auto-convert to any IDE
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 🚀 Next Steps
|
|
|
+
|
|
|
+1. **Review this plan** - Get team approval
|
|
|
+2. **Set up branch** - `feature/json-config-system`
|
|
|
+3. **Start Phase 1** - Build infrastructure
|
|
|
+4. **Weekly reviews** - Track progress
|
|
|
+5. **Launch v2.0.0** - After 6 weeks
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+**Status**: Ready for implementation
|
|
|
+**Estimated Timeline**: 6 weeks
|
|
|
+**Risk Level**: Low (backward compatible during migration)
|
|
|
+**Impact**: High (foundation for all future features)
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+**Last Updated**: 2026-02-15
|
|
|
+**Next Review**: After Phase 1 completion
|
darrenhinde