|
|
@@ -0,0 +1,2340 @@
|
|
|
+<!-- Context: openagents-repo/oac-package-refactor | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
|
|
|
+
|
|
|
+# Feature: OAC Package Refactor
|
|
|
+
|
|
|
+**Purpose**: Transform OpenAgents Control into a flexible npm package with CLI tooling for multi-IDE support and community contributions
|
|
|
+
|
|
|
+**Status**: In Development
|
|
|
+**Branch**: `feature/oac-package-refactor`
|
|
|
+**Priority**: CRITICAL
|
|
|
+**Version Target**: 1.0.0
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Vision
|
|
|
+
|
|
|
+Transform `@nextsystems/oac` from a simple installer into a comprehensive CLI package manager that:
|
|
|
+- ✅ Manages agents, skills, and contexts across multiple IDEs (OpenCode, Cursor, Claude Code, Windsurf)
|
|
|
+- ✅ Provides flexible configuration for agent behavior and permissions
|
|
|
+- ✅ Supports community contributions via shadcn-like component registry
|
|
|
+- ✅ Handles context files from multiple locations
|
|
|
+- ✅ Enables version management and updates
|
|
|
+- ✅ Maintains backward compatibility with existing workflows
|
|
|
+- ✅ **CRITICAL**: User runs in project root, chooses local or global install, always confirms overwrites (unless YOLO mode)
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Core Features
|
|
|
+
|
|
|
+### 1. Multi-IDE Support
|
|
|
+
|
|
|
+**Goal**: One configuration, multiple IDEs
|
|
|
+
|
|
|
+```bash
|
|
|
+# Configure once
|
|
|
+oac configure
|
|
|
+
|
|
|
+# Install for any IDE
|
|
|
+oac install opencode
|
|
|
+oac install cursor
|
|
|
+oac install claude
|
|
|
+
|
|
|
+# Apply updates to all
|
|
|
+oac update --all
|
|
|
+```
|
|
|
+
|
|
|
+**Implementation**:
|
|
|
+- Use compatibility layer adapters for IDE-specific translation
|
|
|
+- Maintain single source of truth in OAC format
|
|
|
+- Auto-detect IDE configurations
|
|
|
+- Handle IDE-specific limitations gracefully
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 2. Flexible Configuration System
|
|
|
+
|
|
|
+**Goal**: User-controlled agent behavior and permissions
|
|
|
+
|
|
|
+**Configuration File**: `~/.config/oac/config.json` (global) or `.oac/config.json` (local/project)
|
|
|
+
|
|
|
+**CRITICAL BEHAVIOR**:
|
|
|
+- User runs `oac` commands in their project root directory
|
|
|
+- Always asks: "Install locally (this project) or globally?"
|
|
|
+- Always confirms before overwriting files (unless `--yolo` flag)
|
|
|
+- YOLO mode (`--yolo`): Auto-confirms all, reports changes at end
|
|
|
+- Default mode: Interactive approval for every file conflict
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "version": "1.0.0",
|
|
|
+ "preferences": {
|
|
|
+ "defaultIDE": "opencode",
|
|
|
+ "installLocation": "local",
|
|
|
+ "autoUpdate": false,
|
|
|
+ "updateChannel": "stable",
|
|
|
+ "confirmOverwrites": true,
|
|
|
+ "yoloMode": false
|
|
|
+ },
|
|
|
+ "ides": {
|
|
|
+ "opencode": {
|
|
|
+ "enabled": true,
|
|
|
+ "path": ".opencode",
|
|
|
+ "profile": "developer"
|
|
|
+ },
|
|
|
+ "cursor": {
|
|
|
+ "enabled": false,
|
|
|
+ "path": ".cursor",
|
|
|
+ "profile": "developer"
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "agents": {
|
|
|
+ "behavior": {
|
|
|
+ "approvalGates": true,
|
|
|
+ "contextLoading": "lazy",
|
|
|
+ "delegationThreshold": 4
|
|
|
+ },
|
|
|
+ "permissions": {
|
|
|
+ "bash": "approve",
|
|
|
+ "write": "approve",
|
|
|
+ "edit": "approve",
|
|
|
+ "task": "approve"
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "context": {
|
|
|
+ "locations": [
|
|
|
+ ".opencode/context",
|
|
|
+ ".claude/context",
|
|
|
+ "docs/context"
|
|
|
+ ],
|
|
|
+ "autoDiscover": true,
|
|
|
+ "cacheEnabled": true
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Commands**:
|
|
|
+```bash
|
|
|
+oac configure # Interactive wizard
|
|
|
+oac configure set agents.permissions.bash auto
|
|
|
+oac configure get ides.opencode.enabled
|
|
|
+oac configure show
|
|
|
+oac configure reset
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 3. User Approval & YOLO Mode (CRITICAL)
|
|
|
+
|
|
|
+**Goal**: User maintains full control over their project, with optional fast mode
|
|
|
+
|
|
|
+**Default Behavior: Interactive Approval**
|
|
|
+
|
|
|
+Every operation that modifies files asks for confirmation:
|
|
|
+
|
|
|
+```bash
|
|
|
+# User runs in project root
|
|
|
+cd ~/my-project
|
|
|
+oac install opencode
|
|
|
+
|
|
|
+# OAC asks:
|
|
|
+? Install location:
|
|
|
+ > Local (this project: ~/my-project/.opencode)
|
|
|
+ Global (~/.config/oac)
|
|
|
+
|
|
|
+# User selects "Local"
|
|
|
+
|
|
|
+# OAC shows what will be installed:
|
|
|
+📦 Installing OpenCode Developer Profile
|
|
|
+
|
|
|
+ Will create/modify:
|
|
|
+ ✓ .opencode/agent/core/openagent.md
|
|
|
+ ✓ .opencode/agent/core/opencoder.md
|
|
|
+ ⚠ .opencode/agent/subagents/code/test-engineer.md (exists - will overwrite)
|
|
|
+ ✓ .opencode/context/core/standards/code-quality.md
|
|
|
+ ✓ .opencode/config.json
|
|
|
+
|
|
|
+ Total: 15 files (2 new, 12 updated, 1 conflict)
|
|
|
+
|
|
|
+? Proceed with installation? (Y/n)
|
|
|
+
|
|
|
+# If conflicts exist:
|
|
|
+⚠ File exists: .opencode/agent/subagents/code/test-engineer.md
|
|
|
+
|
|
|
+ Current: 245 lines, modified 2 days ago
|
|
|
+ New: 312 lines, version 0.8.0
|
|
|
+
|
|
|
+? What would you like to do?
|
|
|
+ > Skip (keep existing)
|
|
|
+ Overwrite (replace with new)
|
|
|
+ Backup (save as .bak, install new)
|
|
|
+ Diff (show changes)
|
|
|
+ Skip all conflicts
|
|
|
+ Overwrite all conflicts
|
|
|
+```
|
|
|
+
|
|
|
+**YOLO Mode: Fast & Furious**
|
|
|
+
|
|
|
+Skip all confirmations, auto-resolve conflicts, report at end:
|
|
|
+
|
|
|
+```bash
|
|
|
+# Enable YOLO mode
|
|
|
+oac install opencode --yolo
|
|
|
+
|
|
|
+# Or set in config
|
|
|
+oac configure set preferences.yoloMode true
|
|
|
+
|
|
|
+# YOLO mode behavior:
|
|
|
+📦 Installing OpenCode Developer Profile (YOLO MODE)
|
|
|
+
|
|
|
+ ⚡ Auto-confirming all operations...
|
|
|
+ ✓ Created .opencode/agent/core/openagent.md
|
|
|
+ ✓ Created .opencode/agent/core/opencoder.md
|
|
|
+ ⚠ Overwrote .opencode/agent/subagents/code/test-engineer.md (backed up to .bak)
|
|
|
+ ✓ Created .opencode/context/core/standards/code-quality.md
|
|
|
+ ✓ Created .opencode/config.json
|
|
|
+
|
|
|
+ ✅ Installation complete!
|
|
|
+
|
|
|
+ 📊 Summary:
|
|
|
+ - 13 files created
|
|
|
+ - 2 files overwritten (backups in .opencode/.backups/)
|
|
|
+ - 0 files skipped
|
|
|
+ - Total time: 1.2s
|
|
|
+
|
|
|
+ ⚠ Review changes: git diff
|
|
|
+```
|
|
|
+
|
|
|
+**Conflict Resolution Strategies**
|
|
|
+
|
|
|
+```typescript
|
|
|
+enum ConflictStrategy {
|
|
|
+ ASK = 'ask', // Ask user for each conflict (default)
|
|
|
+ SKIP = 'skip', // Skip all conflicts, keep existing
|
|
|
+ OVERWRITE = 'overwrite', // Overwrite all conflicts
|
|
|
+ BACKUP = 'backup', // Backup existing, install new
|
|
|
+ YOLO = 'yolo' // Auto-resolve (backup + overwrite)
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Configuration**
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "preferences": {
|
|
|
+ "confirmOverwrites": true,
|
|
|
+ "yoloMode": false,
|
|
|
+ "conflictStrategy": "ask",
|
|
|
+ "autoBackup": true,
|
|
|
+ "backupLocation": ".opencode/.backups"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Commands with Approval Control**
|
|
|
+
|
|
|
+```bash
|
|
|
+# Interactive (default)
|
|
|
+oac install opencode
|
|
|
+oac update
|
|
|
+oac add agent:rust-specialist
|
|
|
+
|
|
|
+# YOLO mode (skip confirmations)
|
|
|
+oac install opencode --yolo
|
|
|
+oac update --yolo
|
|
|
+oac add agent:rust-specialist --yolo
|
|
|
+
|
|
|
+# Force overwrite (no backups)
|
|
|
+oac install opencode --force
|
|
|
+
|
|
|
+# Skip conflicts (keep existing)
|
|
|
+oac install opencode --skip-existing
|
|
|
+
|
|
|
+# Dry run (show what would happen)
|
|
|
+oac install opencode --dry-run
|
|
|
+```
|
|
|
+
|
|
|
+**Safety Features**
|
|
|
+
|
|
|
+- ✅ Always create backups before overwriting (unless `--force`)
|
|
|
+- ✅ Show diff before overwriting
|
|
|
+- ✅ Maintain backup history in `.opencode/.backups/`
|
|
|
+- ✅ Git integration: detect uncommitted changes, warn user
|
|
|
+- ✅ Rollback support: `oac rollback` to undo last operation
|
|
|
+- ✅ Audit log: `.oac/audit.log` tracks all operations
|
|
|
+
|
|
|
+**Example: Full Interactive Flow**
|
|
|
+
|
|
|
+```bash
|
|
|
+cd ~/my-awesome-project
|
|
|
+oac install opencode
|
|
|
+
|
|
|
+# Step 1: Location
|
|
|
+? Install location:
|
|
|
+ > Local (this project: ~/my-awesome-project/.opencode)
|
|
|
+ Global (~/.config/oac)
|
|
|
+
|
|
|
+# Step 2: Profile
|
|
|
+? Select profile:
|
|
|
+ > developer (Full development setup)
|
|
|
+ essential (Minimal setup)
|
|
|
+ business (Content and product focus)
|
|
|
+ custom (Choose components)
|
|
|
+
|
|
|
+# Step 3: Review
|
|
|
+📦 Installing OpenCode Developer Profile
|
|
|
+
|
|
|
+ Will install to: ~/my-awesome-project/.opencode
|
|
|
+
|
|
|
+ Components:
|
|
|
+ - 2 core agents (openagent, opencoder)
|
|
|
+ - 8 subagents (tester, reviewer, coder-agent, ...)
|
|
|
+ - 7 commands (commit, test, context, ...)
|
|
|
+ - 15 context files
|
|
|
+
|
|
|
+ Total size: ~2.5 MB
|
|
|
+
|
|
|
+? Proceed? (Y/n) y
|
|
|
+
|
|
|
+# Step 4: Conflict Resolution (if any)
|
|
|
+⚠ 3 files already exist:
|
|
|
+
|
|
|
+ 1. .opencode/agent/subagents/code/test-engineer.md
|
|
|
+ Current: 245 lines, modified 2 days ago
|
|
|
+ New: 312 lines, version 0.8.0
|
|
|
+
|
|
|
+? Action:
|
|
|
+ > Backup and overwrite
|
|
|
+ Skip (keep existing)
|
|
|
+ Show diff
|
|
|
+
|
|
|
+# Step 5: Installation
|
|
|
+⚡ Installing...
|
|
|
+ ✓ Created .opencode/agent/core/openagent.md
|
|
|
+ ✓ Created .opencode/agent/core/opencoder.md
|
|
|
+ ⚠ Backed up .opencode/agent/subagents/code/test-engineer.md → .backups/TestEngineer.md.2026-02-14
|
|
|
+ ✓ Overwrote .opencode/agent/subagents/code/test-engineer.md
|
|
|
+ ...
|
|
|
+
|
|
|
+# Step 6: Summary
|
|
|
+✅ Installation complete!
|
|
|
+
|
|
|
+📊 Summary:
|
|
|
+- 13 files created
|
|
|
+- 2 files updated
|
|
|
+- 3 files backed up
|
|
|
+- 0 files skipped
|
|
|
+
|
|
|
+📁 Installed to: ~/my-awesome-project/.opencode
|
|
|
+
|
|
|
+🔍 Next steps:
|
|
|
+ 1. Review changes: git diff
|
|
|
+ 2. Test setup: oac doctor
|
|
|
+ 3. Configure: oac configure
|
|
|
+
|
|
|
+💡 Tip: Use 'oac --yolo' to skip confirmations next time
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 4. Community Component Registry (shadcn-like)
|
|
|
+
|
|
|
+**Goal**: Enable users to create and share custom agents, skills, and contexts
|
|
|
+
|
|
|
+**Registry Structure**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "version": "1.0.0",
|
|
|
+ "official": {
|
|
|
+ "agents": [...],
|
|
|
+ "skills": [...],
|
|
|
+ "contexts": [...]
|
|
|
+ },
|
|
|
+ "community": {
|
|
|
+ "agents": [
|
|
|
+ {
|
|
|
+ "id": "rust-specialist",
|
|
|
+ "name": "Rust Specialist",
|
|
|
+ "author": "community-user",
|
|
|
+ "source": "https://github.com/user/oac-rust-specialist",
|
|
|
+ "version": "1.0.0",
|
|
|
+ "downloads": 1234,
|
|
|
+ "verified": false
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Commands**:
|
|
|
+```bash
|
|
|
+# Add component from registry
|
|
|
+oac add agent:rust-specialist
|
|
|
+
|
|
|
+# Add from GitHub URL
|
|
|
+oac add https://github.com/user/oac-rust-specialist
|
|
|
+
|
|
|
+# Add from local path
|
|
|
+oac add ./my-custom-agent
|
|
|
+
|
|
|
+# List available community components
|
|
|
+oac browse agents
|
|
|
+oac browse skills
|
|
|
+
|
|
|
+# Publish your component
|
|
|
+oac publish ./my-agent --type agent
|
|
|
+
|
|
|
+# Search registry
|
|
|
+oac search "rust"
|
|
|
+```
|
|
|
+
|
|
|
+**Component Package Format**:
|
|
|
+```
|
|
|
+my-custom-agent/
|
|
|
+├── oac.json # Component metadata
|
|
|
+├── agent.md # Agent prompt
|
|
|
+├── tests/ # Optional tests
|
|
|
+│ └── smoke-test.yaml
|
|
|
+├── context/ # Optional context files
|
|
|
+│ └── rust-patterns.md
|
|
|
+└── README.md # Documentation
|
|
|
+```
|
|
|
+
|
|
|
+**oac.json Schema**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "name": "rust-specialist",
|
|
|
+ "version": "1.0.0",
|
|
|
+ "type": "agent",
|
|
|
+ "description": "Expert in Rust programming",
|
|
|
+ "author": "username",
|
|
|
+ "license": "MIT",
|
|
|
+ "repository": "https://github.com/user/oac-rust-specialist",
|
|
|
+ "keywords": ["rust", "systems", "programming"],
|
|
|
+ "dependencies": {
|
|
|
+ "agents": [],
|
|
|
+ "skills": [],
|
|
|
+ "contexts": ["core/standards/code-quality"]
|
|
|
+ },
|
|
|
+ "files": {
|
|
|
+ "agent": "agent.md",
|
|
|
+ "tests": "tests/",
|
|
|
+ "context": "context/"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 4. Context Resolution System (CRITICAL)
|
|
|
+
|
|
|
+**Goal**: Intelligent context resolution for agents running locally or globally
|
|
|
+
|
|
|
+**The Problem**:
|
|
|
+- Agents can run from **global install** (`~/.config/oac/`) or **local install** (`./opencode/`)
|
|
|
+- Context files exist in **project-specific** locations AND **global** locations
|
|
|
+- Need to resolve: "Which context file should the agent use?"
|
|
|
+- User preferences (global) vs project requirements (local)
|
|
|
+
|
|
|
+**The Solution: Layered Context Resolution**
|
|
|
+
|
|
|
+#### Context Layers (Priority Order)
|
|
|
+
|
|
|
+```
|
|
|
+1. PROJECT OVERRIDE (./.oac/context/) [Highest Priority]
|
|
|
+ ↓ User's project-specific overrides
|
|
|
+
|
|
|
+2. PROJECT CONTEXT (./.opencode/context/)
|
|
|
+ ↓ Project-specific context files
|
|
|
+
|
|
|
+3. IDE CONTEXT (./.cursor/context/, ./.claude/context/)
|
|
|
+ ↓ IDE-specific context (if different IDE)
|
|
|
+
|
|
|
+4. PROJECT DOCS (./docs/, ./docs/context/)
|
|
|
+ ↓ Project documentation
|
|
|
+
|
|
|
+5. USER GLOBAL (~/.config/oac/context/)
|
|
|
+ ↓ User's personal preferences/standards
|
|
|
+
|
|
|
+6. OAC GLOBAL (~/.config/oac/official/) [Lowest Priority]
|
|
|
+ ↓ Official OAC context files
|
|
|
+```
|
|
|
+
|
|
|
+#### Resolution Algorithm
|
|
|
+
|
|
|
+```typescript
|
|
|
+class ContextResolver {
|
|
|
+ async resolve(ref: string, options: ResolveOptions): Promise<string | null> {
|
|
|
+ const {
|
|
|
+ agentLocation, // 'global' | 'local'
|
|
|
+ projectRoot, // Current working directory
|
|
|
+ preferLocal // User preference
|
|
|
+ } = options;
|
|
|
+
|
|
|
+ // Build search paths based on agent location and preferences
|
|
|
+ const searchPaths = this.buildSearchPaths(agentLocation, projectRoot, preferLocal);
|
|
|
+
|
|
|
+ // Search in priority order
|
|
|
+ for (const basePath of searchPaths) {
|
|
|
+ const fullPath = path.join(basePath, ref);
|
|
|
+ if (await fs.pathExists(fullPath)) {
|
|
|
+ return fullPath;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ return null; // Not found
|
|
|
+ }
|
|
|
+
|
|
|
+ private buildSearchPaths(
|
|
|
+ agentLocation: 'global' | 'local',
|
|
|
+ projectRoot: string,
|
|
|
+ preferLocal: boolean
|
|
|
+ ): string[] {
|
|
|
+ const paths: string[] = [];
|
|
|
+
|
|
|
+ // If agent is running locally OR user prefers local context
|
|
|
+ if (agentLocation === 'local' || preferLocal) {
|
|
|
+ // Prioritize project context
|
|
|
+ paths.push(
|
|
|
+ path.join(projectRoot, '.oac/context'), // Project override
|
|
|
+ path.join(projectRoot, '.opencode/context'), // Project context
|
|
|
+ path.join(projectRoot, '.cursor/context'), // IDE context
|
|
|
+ path.join(projectRoot, '.claude/context'),
|
|
|
+ path.join(projectRoot, 'docs/context'), // Project docs
|
|
|
+ path.join(projectRoot, 'docs')
|
|
|
+ );
|
|
|
+ }
|
|
|
+
|
|
|
+ // Always include global context (fallback)
|
|
|
+ paths.push(
|
|
|
+ path.join(os.homedir(), '.config/oac/context'), // User global
|
|
|
+ path.join(os.homedir(), '.config/oac/official') // OAC official
|
|
|
+ );
|
|
|
+
|
|
|
+ // If agent is running globally AND user prefers global
|
|
|
+ if (agentLocation === 'global' && !preferLocal) {
|
|
|
+ // Reverse priority: global first, then project
|
|
|
+ return [
|
|
|
+ path.join(os.homedir(), '.config/oac/context'),
|
|
|
+ path.join(os.homedir(), '.config/oac/official'),
|
|
|
+ ...paths.slice(0, -2) // Add project paths after global
|
|
|
+ ];
|
|
|
+ }
|
|
|
+
|
|
|
+ return paths;
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### Configuration
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "context": {
|
|
|
+ "resolution": {
|
|
|
+ "preferLocal": true, // Prefer project context over global
|
|
|
+ "allowOverrides": true, // Allow .oac/context/ overrides
|
|
|
+ "fallbackToGlobal": true, // Fall back to global if not found locally
|
|
|
+ "cacheResolution": true // Cache resolved paths
|
|
|
+ },
|
|
|
+ "locations": {
|
|
|
+ "project": [
|
|
|
+ ".oac/context", // Project overrides (highest priority)
|
|
|
+ ".opencode/context", // Project context
|
|
|
+ ".cursor/context", // IDE-specific
|
|
|
+ ".claude/context",
|
|
|
+ "docs/context", // Project docs
|
|
|
+ "docs"
|
|
|
+ ],
|
|
|
+ "global": [
|
|
|
+ "~/.config/oac/context", // User global context
|
|
|
+ "~/.config/oac/official" // OAC official context
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ "autoDiscover": true,
|
|
|
+ "validation": {
|
|
|
+ "warnOnMissing": true,
|
|
|
+ "errorOnMissing": false,
|
|
|
+ "suggestAlternatives": true
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### Example Scenarios
|
|
|
+
|
|
|
+**Scenario 1: Agent runs locally, context exists in project**
|
|
|
+
|
|
|
+```bash
|
|
|
+# User is in project directory
|
|
|
+cd ~/my-project
|
|
|
+
|
|
|
+# Agent runs locally
|
|
|
+oac install opencode --local
|
|
|
+
|
|
|
+# Agent needs: 'core/standards/code-quality.md'
|
|
|
+# Resolution:
|
|
|
+# 1. Check: ~/my-project/.oac/context/core/standards/code-quality.md ❌
|
|
|
+# 2. Check: ~/my-project/.opencode/context/core/standards/code-quality.md ✅
|
|
|
+# → Uses project-specific context
|
|
|
+```
|
|
|
+
|
|
|
+**Scenario 2: Agent runs globally, no project context**
|
|
|
+
|
|
|
+```bash
|
|
|
+# User is in project directory
|
|
|
+cd ~/my-project
|
|
|
+
|
|
|
+# Agent runs from global install
|
|
|
+oac install opencode --global
|
|
|
+
|
|
|
+# Agent needs: 'core/standards/code-quality.md'
|
|
|
+# Resolution:
|
|
|
+# 1. Check: ~/.config/oac/context/core/standards/code-quality.md ✅
|
|
|
+# → Uses global context
|
|
|
+```
|
|
|
+
|
|
|
+**Scenario 3: Project override**
|
|
|
+
|
|
|
+```bash
|
|
|
+# User wants custom code quality standards for this project
|
|
|
+mkdir -p ~/my-project/.oac/context/core/standards
|
|
|
+cp ~/.config/oac/official/core/standards/code-quality.md \
|
|
|
+ ~/my-project/.oac/context/core/standards/code-quality.md
|
|
|
+
|
|
|
+# Edit project-specific version
|
|
|
+vim ~/my-project/.oac/context/core/standards/code-quality.md
|
|
|
+
|
|
|
+# Agent needs: 'core/standards/code-quality.md'
|
|
|
+# Resolution:
|
|
|
+# 1. Check: ~/my-project/.oac/context/core/standards/code-quality.md ✅
|
|
|
+# → Uses project override (highest priority)
|
|
|
+```
|
|
|
+
|
|
|
+**Scenario 4: Mixed context (project + global)**
|
|
|
+
|
|
|
+```bash
|
|
|
+# Project has some context
|
|
|
+~/my-project/.opencode/context/
|
|
|
+ └── project/
|
|
|
+ └── architecture.md
|
|
|
+
|
|
|
+# Global has standard context
|
|
|
+~/.config/oac/official/
|
|
|
+ └── core/
|
|
|
+ └── standards/
|
|
|
+ └── code-quality.md
|
|
|
+
|
|
|
+# Agent needs both:
|
|
|
+# - 'project/architecture.md' → Found in project ✅
|
|
|
+# - 'core/standards/code-quality.md' → Falls back to global ✅
|
|
|
+```
|
|
|
+
|
|
|
+#### Context Merging (Advanced)
|
|
|
+
|
|
|
+For certain context types, we can **merge** instead of override:
|
|
|
+
|
|
|
+```typescript
|
|
|
+interface ContextMergeStrategy {
|
|
|
+ type: 'override' | 'merge' | 'append';
|
|
|
+ mergeKey?: string; // For merge strategy
|
|
|
+}
|
|
|
+
|
|
|
+// Example: Merge project and global standards
|
|
|
+const merged = await contextResolver.resolveWithMerge(
|
|
|
+ 'core/standards/code-quality.md',
|
|
|
+ {
|
|
|
+ strategy: 'merge',
|
|
|
+ mergeKey: 'standards', // Merge 'standards' sections
|
|
|
+ preferLocal: true // Local takes precedence on conflicts
|
|
|
+ }
|
|
|
+);
|
|
|
+
|
|
|
+// Result:
|
|
|
+// - Global standards: base rules
|
|
|
+// - Project standards: additional/override rules
|
|
|
+// - Final: combined ruleset
|
|
|
+```
|
|
|
+
|
|
|
+#### CLI Commands for Context Management
|
|
|
+
|
|
|
+```bash
|
|
|
+# Show context resolution for a reference
|
|
|
+oac context resolve 'core/standards/code-quality.md'
|
|
|
+ → Resolved to: ~/my-project/.opencode/context/core/standards/code-quality.md
|
|
|
+ → Source: project
|
|
|
+ → Fallbacks checked: 2
|
|
|
+
|
|
|
+# List all available context files
|
|
|
+oac context list
|
|
|
+ --local # Project context only
|
|
|
+ --global # Global context only
|
|
|
+ --all # All (default)
|
|
|
+ --tree # Show as tree
|
|
|
+
|
|
|
+# Validate context references
|
|
|
+oac context validate
|
|
|
+ → Checking 45 context references...
|
|
|
+ ✓ 42 resolved
|
|
|
+ ⚠ 3 missing (using fallbacks)
|
|
|
+
|
|
|
+# Create project override
|
|
|
+oac context override 'core/standards/code-quality.md'
|
|
|
+ → Copied from: ~/.config/oac/official/core/standards/code-quality.md
|
|
|
+ → To: ~/my-project/.oac/context/core/standards/code-quality.md
|
|
|
+ → Edit this file to customize for your project
|
|
|
+
|
|
|
+# Show context sources
|
|
|
+oac context sources
|
|
|
+ Project Context:
|
|
|
+ .oac/context/ (2 files)
|
|
|
+ .opencode/context/ (15 files)
|
|
|
+ docs/ (8 files)
|
|
|
+
|
|
|
+ Global Context:
|
|
|
+ ~/.config/oac/context/ (5 files)
|
|
|
+ ~/.config/oac/official/ (42 files)
|
|
|
+
|
|
|
+ Total: 72 context files
|
|
|
+
|
|
|
+# Sync global context to project
|
|
|
+oac context sync --to-project
|
|
|
+ → Copying global context to project...
|
|
|
+ ✓ Copied 42 files to .opencode/context/
|
|
|
+
|
|
|
+# Sync project context to global
|
|
|
+oac context sync --to-global
|
|
|
+ → Copying project context to global...
|
|
|
+ ⚠ This will affect all projects using global context
|
|
|
+ ? Proceed? (y/N)
|
|
|
+```
|
|
|
+
|
|
|
+#### Agent Context Loading
|
|
|
+
|
|
|
+Agents need to know where they're running from:
|
|
|
+
|
|
|
+```typescript
|
|
|
+// In agent prompt or configuration
|
|
|
+class AgentContext {
|
|
|
+ location: 'global' | 'local';
|
|
|
+ projectRoot: string | null;
|
|
|
+ contextResolver: ContextResolver;
|
|
|
+
|
|
|
+ async loadContext(ref: string): Promise<string> {
|
|
|
+ const resolved = await this.contextResolver.resolve(ref, {
|
|
|
+ agentLocation: this.location,
|
|
|
+ projectRoot: this.projectRoot || process.cwd(),
|
|
|
+ preferLocal: true
|
|
|
+ });
|
|
|
+
|
|
|
+ if (!resolved) {
|
|
|
+ throw new Error(`Context not found: ${ref}`);
|
|
|
+ }
|
|
|
+
|
|
|
+ return fs.readFile(resolved, 'utf-8');
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### Environment Variables
|
|
|
+
|
|
|
+```bash
|
|
|
+# Override context resolution behavior
|
|
|
+OAC_CONTEXT_PREFER_LOCAL=true # Prefer project context
|
|
|
+OAC_CONTEXT_PREFER_GLOBAL=true # Prefer global context
|
|
|
+OAC_CONTEXT_PROJECT_ROOT=/path/to/project
|
|
|
+OAC_CONTEXT_GLOBAL_ROOT=~/.config/oac
|
|
|
+OAC_CONTEXT_CACHE_ENABLED=true
|
|
|
+OAC_CONTEXT_VALIDATION=strict # strict | warn | off
|
|
|
+```
|
|
|
+
|
|
|
+#### Visual Representation
|
|
|
+
|
|
|
+```
|
|
|
+Agent Running Locally (in ~/my-project):
|
|
|
+┌─────────────────────────────────────────┐
|
|
|
+│ Agent: openagent (local) │
|
|
|
+│ Working Dir: ~/my-project │
|
|
|
+└─────────────────────────────────────────┘
|
|
|
+ ↓
|
|
|
+ Needs: 'core/standards/code-quality.md'
|
|
|
+ ↓
|
|
|
+┌─────────────────────────────────────────┐
|
|
|
+│ Context Resolver │
|
|
|
+│ Mode: preferLocal = true │
|
|
|
+└─────────────────────────────────────────┘
|
|
|
+ ↓
|
|
|
+ Search Priority:
|
|
|
+ 1. ~/my-project/.oac/context/... ❌
|
|
|
+ 2. ~/my-project/.opencode/context/... ✅ FOUND
|
|
|
+ 3. (skip remaining)
|
|
|
+ ↓
|
|
|
+ Returns: ~/my-project/.opencode/context/core/standards/code-quality.md
|
|
|
+
|
|
|
+
|
|
|
+Agent Running Globally:
|
|
|
+┌─────────────────────────────────────────┐
|
|
|
+│ Agent: openagent (global) │
|
|
|
+│ Working Dir: ~/my-project │
|
|
|
+└─────────────────────────────────────────┘
|
|
|
+ ↓
|
|
|
+ Needs: 'core/standards/code-quality.md'
|
|
|
+ ↓
|
|
|
+┌─────────────────────────────────────────┐
|
|
|
+│ Context Resolver │
|
|
|
+│ Mode: preferLocal = true (default) │
|
|
|
+└─────────────────────────────────────────┘
|
|
|
+ ↓
|
|
|
+ Search Priority:
|
|
|
+ 1. ~/my-project/.oac/context/... ❌
|
|
|
+ 2. ~/my-project/.opencode/context/... ❌
|
|
|
+ 3. ~/.config/oac/context/... ❌
|
|
|
+ 4. ~/.config/oac/official/... ✅ FOUND
|
|
|
+ ↓
|
|
|
+ Returns: ~/.config/oac/official/core/standards/code-quality.md
|
|
|
+```
|
|
|
+
|
|
|
+#### Best Practices
|
|
|
+
|
|
|
+**For Users**:
|
|
|
+- ✅ Use global context for personal coding standards
|
|
|
+- ✅ Use project context for project-specific requirements
|
|
|
+- ✅ Use `.oac/context/` for temporary overrides
|
|
|
+- ✅ Keep project context in version control
|
|
|
+- ✅ Keep global context private (personal preferences)
|
|
|
+
|
|
|
+**For Projects**:
|
|
|
+- ✅ Include essential context in `.opencode/context/`
|
|
|
+- ✅ Document required context files in README
|
|
|
+- ✅ Use `oac context validate` in CI/CD
|
|
|
+- ✅ Provide `.oac/context/` examples for common overrides
|
|
|
+
|
|
|
+**For OAC**:
|
|
|
+- ✅ Ship official context in `~/.config/oac/official/`
|
|
|
+- ✅ Never modify user's global context without permission
|
|
|
+- ✅ Warn when context is missing
|
|
|
+- ✅ Suggest alternatives when context not found
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 5. Version Management & Updates
|
|
|
+
|
|
|
+**Goal**: Keep agents and components up-to-date across all IDEs
|
|
|
+
|
|
|
+```bash
|
|
|
+# Check for updates
|
|
|
+oac update --check
|
|
|
+
|
|
|
+# Update all components
|
|
|
+oac update
|
|
|
+
|
|
|
+# Update and apply to specific IDE
|
|
|
+oac update --claude --global
|
|
|
+oac update --opencode --local
|
|
|
+
|
|
|
+# Update specific component
|
|
|
+oac update agent:openagent
|
|
|
+
|
|
|
+# Update from specific version
|
|
|
+oac update --version 0.8.0
|
|
|
+
|
|
|
+# Rollback to previous version
|
|
|
+oac rollback agent:openagent
|
|
|
+```
|
|
|
+
|
|
|
+**Update Flow**:
|
|
|
+1. Fetch latest registry from GitHub
|
|
|
+2. Compare with local cache
|
|
|
+3. Show available updates
|
|
|
+4. Download updated components
|
|
|
+5. Apply to configured IDEs
|
|
|
+6. Validate installation
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 5. Agent Customization & Personal Presets (CRITICAL)
|
|
|
+
|
|
|
+**Goal**: Allow users to view, customize, and save personal agent configurations
|
|
|
+
|
|
|
+**The Problem**:
|
|
|
+- Users want to customize agent prompts for their workflow
|
|
|
+- Users want to save personal presets
|
|
|
+- Updates shouldn't overwrite customizations
|
|
|
+- Need easy way to view and edit agent configs
|
|
|
+
|
|
|
+**The Solution: Multi-Layer Customization System**
|
|
|
+
|
|
|
+#### Layer 1: View Agent Configuration
|
|
|
+
|
|
|
+```bash
|
|
|
+# View agent prompt and config
|
|
|
+oac show agent:openagent
|
|
|
+ → Opens agent file in pager (less/bat)
|
|
|
+ → Shows: prompt, config, metadata
|
|
|
+
|
|
|
+# View in editor
|
|
|
+oac edit agent:openagent
|
|
|
+ → Opens in $EDITOR (vim/vscode/etc.)
|
|
|
+ → Read-only by default (shows warning)
|
|
|
+
|
|
|
+# View config only
|
|
|
+oac config show agent:openagent
|
|
|
+ → Shows just the configuration (YAML frontmatter)
|
|
|
+
|
|
|
+# Export agent
|
|
|
+oac export agent:openagent --output ./my-openagent.md
|
|
|
+ → Exports to file for inspection
|
|
|
+```
|
|
|
+
|
|
|
+#### Layer 2: Create Personal Preset
|
|
|
+
|
|
|
+```bash
|
|
|
+# Create personal preset (copy to user space)
|
|
|
+oac customize agent:openagent
|
|
|
+
|
|
|
+? What would you like to customize?
|
|
|
+ > Create personal preset (recommended)
|
|
|
+ Edit in place (advanced)
|
|
|
+ Fork to new agent
|
|
|
+
|
|
|
+? Preset name: my-openagent
|
|
|
+? Description: My customized OpenAgent with stricter approval gates
|
|
|
+
|
|
|
+✓ Created preset: ~/.config/oac/presets/agents/my-openagent.md
|
|
|
+✓ Linked to: agent:openagent (base)
|
|
|
+
|
|
|
+📝 Edit your preset:
|
|
|
+ oac edit preset:my-openagent
|
|
|
+
|
|
|
+💡 Use your preset:
|
|
|
+ oac use preset:my-openagent
|
|
|
+```
|
|
|
+
|
|
|
+**Preset Structure**:
|
|
|
+```
|
|
|
+~/.config/oac/
|
|
|
+├── presets/
|
|
|
+│ ├── agents/
|
|
|
+│ │ ├── my-openagent.md # User's custom version
|
|
|
+│ │ ├── my-opencoder.md
|
|
|
+│ │ └── strict-reviewer.md
|
|
|
+│ ├── skills/
|
|
|
+│ │ └── my-git-workflow.md
|
|
|
+│ └── .presets.json # Preset metadata
|
|
|
+```
|
|
|
+
|
|
|
+**Preset Metadata** (`.presets.json`):
|
|
|
+```json
|
|
|
+{
|
|
|
+ "presets": {
|
|
|
+ "my-openagent": {
|
|
|
+ "type": "agent",
|
|
|
+ "base": "agent:openagent",
|
|
|
+ "baseVersion": "0.7.1",
|
|
|
+ "created": "2026-02-14T10:30:00Z",
|
|
|
+ "modified": "2026-02-14T15:45:00Z",
|
|
|
+ "customizations": [
|
|
|
+ "Modified approval gates",
|
|
|
+ "Added custom context paths",
|
|
|
+ "Changed delegation threshold"
|
|
|
+ ],
|
|
|
+ "autoUpdate": false,
|
|
|
+ "updateStrategy": "manual"
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### Layer 3: Edit Personal Preset
|
|
|
+
|
|
|
+```bash
|
|
|
+# Edit preset in default editor
|
|
|
+oac edit preset:my-openagent
|
|
|
+ → Opens ~/.config/oac/presets/agents/my-openagent.md in $EDITOR
|
|
|
+
|
|
|
+# Edit with specific editor
|
|
|
+oac edit preset:my-openagent --editor code
|
|
|
+ → Opens in VS Code
|
|
|
+
|
|
|
+# Interactive customization wizard
|
|
|
+oac customize preset:my-openagent --interactive
|
|
|
+
|
|
|
+? What would you like to customize?
|
|
|
+ ✓ Approval gates behavior
|
|
|
+ ✓ Context loading strategy
|
|
|
+ ☐ Delegation threshold
|
|
|
+ ☐ Tool permissions
|
|
|
+
|
|
|
+? Approval gates:
|
|
|
+ > Always ask (current)
|
|
|
+ Auto-approve reads
|
|
|
+ YOLO mode by default
|
|
|
+
|
|
|
+? Context loading:
|
|
|
+ > Lazy (current)
|
|
|
+ Eager (load all upfront)
|
|
|
+ Manual (user specifies)
|
|
|
+
|
|
|
+✓ Updated preset: my-openagent
|
|
|
+✓ Changes saved to ~/.config/oac/presets/agents/my-openagent.md
|
|
|
+```
|
|
|
+
|
|
|
+#### Layer 4: Use Personal Preset
|
|
|
+
|
|
|
+```bash
|
|
|
+# Use preset instead of base agent
|
|
|
+oac use preset:my-openagent
|
|
|
+ → Activates preset in current project
|
|
|
+
|
|
|
+# Use preset globally
|
|
|
+oac use preset:my-openagent --global
|
|
|
+ → Sets as default for all projects
|
|
|
+
|
|
|
+# Use preset for specific IDE
|
|
|
+oac use preset:my-openagent --ide opencode
|
|
|
+ → Applies to OpenCode only
|
|
|
+
|
|
|
+# List active presets
|
|
|
+oac presets list --active
|
|
|
+ opencode: preset:my-openagent
|
|
|
+ cursor: agent:openagent (base)
|
|
|
+ claude: preset:strict-reviewer
|
|
|
+
|
|
|
+# Switch back to base
|
|
|
+oac use agent:openagent
|
|
|
+ → Deactivates preset, uses base agent
|
|
|
+```
|
|
|
+
|
|
|
+#### Layer 5: Update Management (CRITICAL)
|
|
|
+
|
|
|
+**Problem**: Updates shouldn't overwrite user customizations
|
|
|
+
|
|
|
+**Solution**: Smart update strategy with user control
|
|
|
+
|
|
|
+```bash
|
|
|
+# Check for updates to base agent
|
|
|
+oac update --check
|
|
|
+
|
|
|
+📦 Updates Available:
|
|
|
+
|
|
|
+agent:openagent (base for preset:my-openagent)
|
|
|
+ Current: 0.7.1
|
|
|
+ Latest: 0.8.0
|
|
|
+
|
|
|
+ Changes:
|
|
|
+ - Added new context loading patterns
|
|
|
+ - Improved delegation logic
|
|
|
+ - Fixed approval gate bug
|
|
|
+
|
|
|
+ ⚠️ You have a personal preset based on this agent
|
|
|
+
|
|
|
+? How would you like to update?
|
|
|
+ > Review changes first (recommended)
|
|
|
+ Update base, keep my customizations
|
|
|
+ Update base, merge my customizations
|
|
|
+ Skip this update
|
|
|
+ Auto-update base (don't ask again)
|
|
|
+
|
|
|
+# Review changes before updating
|
|
|
+oac diff agent:openagent 0.7.1 0.8.0
|
|
|
+ → Shows diff between versions
|
|
|
+
|
|
|
+# Update with merge strategy
|
|
|
+oac update agent:openagent --merge-preset my-openagent
|
|
|
+
|
|
|
+⚡ Updating agent:openagent (0.7.1 → 0.8.0)
|
|
|
+
|
|
|
+📝 Merging with preset:my-openagent...
|
|
|
+
|
|
|
+✓ Base agent updated
|
|
|
+⚠️ Conflicts detected in preset:
|
|
|
+
|
|
|
+ Section: Approval Gates
|
|
|
+ Base (new): "Always ask before execution"
|
|
|
+ Your preset: "Auto-approve read operations"
|
|
|
+
|
|
|
+? Keep your customization? (Y/n) y
|
|
|
+
|
|
|
+✓ Preset updated with merge
|
|
|
+✓ Backup saved: ~/.config/oac/presets/.backups/my-openagent.2026-02-14.md
|
|
|
+
|
|
|
+📊 Summary:
|
|
|
+ - Base agent: Updated to 0.8.0
|
|
|
+ - Your preset: Merged (3 conflicts resolved)
|
|
|
+ - Customizations: Preserved
|
|
|
+```
|
|
|
+
|
|
|
+**Update Strategies**:
|
|
|
+```typescript
|
|
|
+enum PresetUpdateStrategy {
|
|
|
+ MANUAL = 'manual', // User reviews every update
|
|
|
+ AUTO_BASE = 'auto-base', // Auto-update base, keep preset unchanged
|
|
|
+ AUTO_MERGE = 'auto-merge', // Auto-merge, prompt on conflicts
|
|
|
+ LOCKED = 'locked' // Never update base
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Configuration**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "presets": {
|
|
|
+ "my-openagent": {
|
|
|
+ "updateStrategy": "manual",
|
|
|
+ "autoUpdate": false,
|
|
|
+ "mergeStrategy": {
|
|
|
+ "onConflict": "ask", // ask | keep-mine | keep-theirs
|
|
|
+ "backupOnMerge": true,
|
|
|
+ "maxBackups": 10
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### Layer 6: Preset Sharing
|
|
|
+
|
|
|
+```bash
|
|
|
+# Export preset for sharing
|
|
|
+oac export preset:my-openagent --output ./my-openagent-preset.md
|
|
|
+ → Exports with metadata
|
|
|
+
|
|
|
+# Share preset with team
|
|
|
+oac share preset:my-openagent
|
|
|
+ → Generates shareable link or file
|
|
|
+
|
|
|
+# Import preset from teammate
|
|
|
+oac import preset ./teammate-preset.md
|
|
|
+ → Imports as new preset
|
|
|
+
|
|
|
+# Publish preset to community
|
|
|
+oac publish preset:my-openagent --public
|
|
|
+ → Publishes to community registry (optional)
|
|
|
+```
|
|
|
+
|
|
|
+#### Layer 7: In-Place Editing (Advanced)
|
|
|
+
|
|
|
+**Warning**: Editing installed agents directly is risky
|
|
|
+
|
|
|
+```bash
|
|
|
+# Edit installed agent (not recommended)
|
|
|
+oac edit agent:openagent --in-place
|
|
|
+
|
|
|
+⚠️ WARNING: Editing installed agent directly
|
|
|
+
|
|
|
+ This will modify the installed agent file.
|
|
|
+ Updates will overwrite your changes.
|
|
|
+
|
|
|
+ Recommended: Create a preset instead
|
|
|
+ oac customize agent:openagent
|
|
|
+
|
|
|
+? Are you sure you want to edit in-place? (y/N) n
|
|
|
+
|
|
|
+# Force in-place edit (advanced users)
|
|
|
+oac edit agent:openagent --in-place --force
|
|
|
+
|
|
|
+⚠️ Editing: .opencode/agent/core/openagent.md
|
|
|
+⚠️ Changes will be overwritten on update
|
|
|
+⚠️ Creating backup: (example: .opencode/.backups/openagent.md.2026-02-14)
|
|
|
+
|
|
|
+[Opens in editor]
|
|
|
+
|
|
|
+✓ Saved changes
|
|
|
+⚠️ Remember: Updates will overwrite this file
|
|
|
+💡 Tip: Create a preset to preserve customizations
|
|
|
+```
|
|
|
+
|
|
|
+#### CLI Commands Summary
|
|
|
+
|
|
|
+```bash
|
|
|
+# View
|
|
|
+oac show agent:openagent # View agent
|
|
|
+oac config show agent:openagent # View config only
|
|
|
+oac export agent:openagent # Export to file
|
|
|
+
|
|
|
+# Customize
|
|
|
+oac customize agent:openagent # Create preset (wizard)
|
|
|
+oac edit preset:my-openagent # Edit preset
|
|
|
+oac customize preset:my-openagent --interactive # Interactive wizard
|
|
|
+
|
|
|
+# Use
|
|
|
+oac use preset:my-openagent # Activate preset
|
|
|
+oac use preset:my-openagent --global # Set as default
|
|
|
+oac presets list # List presets
|
|
|
+oac presets list --active # Show active presets
|
|
|
+
|
|
|
+# Update
|
|
|
+oac update --check # Check for updates
|
|
|
+oac diff agent:openagent 0.7.1 0.8.0 # Show changes
|
|
|
+oac update agent:openagent --merge-preset my-openagent
|
|
|
+
|
|
|
+# Share
|
|
|
+oac export preset:my-openagent # Export preset
|
|
|
+oac import preset ./preset.md # Import preset
|
|
|
+oac share preset:my-openagent # Share with team
|
|
|
+oac publish preset:my-openagent # Publish to community
|
|
|
+
|
|
|
+# Advanced
|
|
|
+oac edit agent:openagent --in-place # Edit installed agent (risky)
|
|
|
+oac fork agent:openagent my-agent # Fork to new agent
|
|
|
+```
|
|
|
+
|
|
|
+#### Configuration Schema
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "presets": {
|
|
|
+ "enabled": true,
|
|
|
+ "location": "~/.config/oac/presets",
|
|
|
+ "defaultUpdateStrategy": "manual",
|
|
|
+ "backupOnEdit": true,
|
|
|
+ "maxBackups": 10,
|
|
|
+ "warnOnInPlaceEdit": true
|
|
|
+ },
|
|
|
+ "customization": {
|
|
|
+ "allowInPlaceEdit": true,
|
|
|
+ "requireConfirmation": true,
|
|
|
+ "autoBackup": true,
|
|
|
+ "showDiffOnUpdate": true
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### Preset File Format
|
|
|
+
|
|
|
+```markdown
|
|
|
+---
|
|
|
+# Preset Metadata
|
|
|
+preset:
|
|
|
+ name: my-openagent
|
|
|
+ base: agent:openagent
|
|
|
+ baseVersion: 0.7.1
|
|
|
+ type: agent
|
|
|
+ created: 2026-02-14T10:30:00Z
|
|
|
+ modified: 2026-02-14T15:45:00Z
|
|
|
+
|
|
|
+# Customizations
|
|
|
+customizations:
|
|
|
+ - section: "Approval Gates"
|
|
|
+ description: "Auto-approve read operations"
|
|
|
+ - section: "Context Loading"
|
|
|
+ description: "Changed to eager loading"
|
|
|
+
|
|
|
+# Update Strategy
|
|
|
+update:
|
|
|
+ strategy: manual
|
|
|
+ autoUpdate: false
|
|
|
+ mergeStrategy: ask
|
|
|
+---
|
|
|
+
|
|
|
+# My Custom OpenAgent
|
|
|
+
|
|
|
+[Your customized agent prompt here]
|
|
|
+
|
|
|
+<!-- CUSTOMIZATION: Approval Gates -->
|
|
|
+**Modified Behavior**: Auto-approve read operations (glob, read, grep)
|
|
|
+<!-- END CUSTOMIZATION -->
|
|
|
+
|
|
|
+[Rest of agent prompt...]
|
|
|
+```
|
|
|
+
|
|
|
+#### Visual Workflow
|
|
|
+
|
|
|
+```
|
|
|
+User wants to customize agent:openagent
|
|
|
+ ↓
|
|
|
+ oac customize agent:openagent
|
|
|
+ ↓
|
|
|
+ ┌─────────────────────────────┐
|
|
|
+ │ Create Personal Preset │
|
|
|
+ │ │
|
|
|
+ │ Name: my-openagent │
|
|
|
+ │ Base: agent:openagent │
|
|
|
+ │ Location: ~/.config/oac/ │
|
|
|
+ └─────────────────────────────┘
|
|
|
+ ↓
|
|
|
+ Copy base agent to preset location
|
|
|
+ ↓
|
|
|
+ ┌─────────────────────────────┐
|
|
|
+ │ Edit Preset │
|
|
|
+ │ │
|
|
|
+ │ oac edit preset:my-openagent│
|
|
|
+ │ [Opens in $EDITOR] │
|
|
|
+ └─────────────────────────────┘
|
|
|
+ ↓
|
|
|
+ User makes changes, saves
|
|
|
+ ↓
|
|
|
+ ┌─────────────────────────────┐
|
|
|
+ │ Activate Preset │
|
|
|
+ │ │
|
|
|
+ │ oac use preset:my-openagent │
|
|
|
+ └─────────────────────────────┘
|
|
|
+ ↓
|
|
|
+ Preset is now active
|
|
|
+ ↓
|
|
|
+ Base agent updates (0.7.1 → 0.8.0)
|
|
|
+ ↓
|
|
|
+ ┌─────────────────────────────┐
|
|
|
+ │ Update Check │
|
|
|
+ │ │
|
|
|
+ │ ⚠️ Preset based on updated │
|
|
|
+ │ agent │
|
|
|
+ │ │
|
|
|
+ │ ? How to update? │
|
|
|
+ │ > Review changes │
|
|
|
+ │ Merge │
|
|
|
+ │ Skip │
|
|
|
+ └─────────────────────────────┘
|
|
|
+ ↓
|
|
|
+ User reviews diff
|
|
|
+ ↓
|
|
|
+ ┌─────────────────────────────┐
|
|
|
+ │ Merge Strategy │
|
|
|
+ │ │
|
|
|
+ │ Conflicts: │
|
|
|
+ │ - Approval gates (yours) │
|
|
|
+ │ - Context loading (theirs) │
|
|
|
+ │ │
|
|
|
+ │ ? Keep your changes? Y/n │
|
|
|
+ └─────────────────────────────┘
|
|
|
+ ↓
|
|
|
+ Preset updated with merge
|
|
|
+ Backup created
|
|
|
+ Customizations preserved
|
|
|
+```
|
|
|
+
|
|
|
+#### Best Practices
|
|
|
+
|
|
|
+**For Users**:
|
|
|
+- ✅ Always create presets instead of editing in-place
|
|
|
+- ✅ Use descriptive preset names
|
|
|
+- ✅ Document your customizations in preset metadata
|
|
|
+- ✅ Review updates before merging
|
|
|
+- ✅ Keep backups of important presets
|
|
|
+
|
|
|
+**For OAC**:
|
|
|
+- ✅ Default to preset creation (safest)
|
|
|
+- ✅ Warn loudly on in-place edits
|
|
|
+- ✅ Always create backups before updates
|
|
|
+- ✅ Show clear diffs before merging
|
|
|
+- ✅ Preserve user customizations by default
|
|
|
+- ✅ Make it easy to revert to base agent
|
|
|
+
|
|
|
+#### Edge Cases Handled
|
|
|
+
|
|
|
+1. **User edits in-place, then update arrives**
|
|
|
+ - Detect local modifications
|
|
|
+ - Warn user
|
|
|
+ - Offer to create preset from modifications
|
|
|
+ - Backup before overwriting
|
|
|
+
|
|
|
+2. **Preset based on old version, multiple updates behind**
|
|
|
+ - Show all changes since preset creation
|
|
|
+ - Offer step-by-step merge or bulk merge
|
|
|
+ - Highlight breaking changes
|
|
|
+
|
|
|
+3. **User has multiple presets for same base agent**
|
|
|
+ - Allow multiple presets
|
|
|
+ - Each preset tracks its own base version
|
|
|
+ - Update each independently
|
|
|
+
|
|
|
+4. **Preset conflicts with IDE limitations**
|
|
|
+ - Warn if preset won't work with IDE
|
|
|
+ - Suggest compatible alternatives
|
|
|
+ - Auto-adapt if possible
|
|
|
+
|
|
|
+5. **User deletes base agent but has preset**
|
|
|
+ - Preset becomes standalone
|
|
|
+ - Warn that updates won't work
|
|
|
+ - Offer to reinstall base
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 6. IDE Feature Parity & Capacity Management (CRITICAL)
|
|
|
+
|
|
|
+**Goal**: Support different feature sets per IDE based on their capabilities
|
|
|
+
|
|
|
+**The Problem**:
|
|
|
+- Different IDEs support different features
|
|
|
+- OpenCode and Claude Code: Full feature support (agents, skills, context, plugins, tools)
|
|
|
+- Cursor: Limited (single .cursorrules file, no skills/plugins)
|
|
|
+- Windsurf: Partial support
|
|
|
+- Need to gracefully handle unsupported features
|
|
|
+
|
|
|
+**Feature Support Matrix**:
|
|
|
+
|
|
|
+```typescript
|
|
|
+interface IDECapabilities {
|
|
|
+ id: string;
|
|
|
+ name: string;
|
|
|
+ features: {
|
|
|
+ multipleAgents: boolean;
|
|
|
+ skills: boolean;
|
|
|
+ plugins: boolean;
|
|
|
+ tools: boolean;
|
|
|
+ contexts: boolean;
|
|
|
+ commands: boolean;
|
|
|
+ granularPermissions: boolean;
|
|
|
+ hooks: boolean;
|
|
|
+ };
|
|
|
+ limits?: {
|
|
|
+ maxAgents?: number;
|
|
|
+ maxFileSize?: number;
|
|
|
+ maxContextFiles?: number;
|
|
|
+ };
|
|
|
+}
|
|
|
+
|
|
|
+const IDE_CAPABILITIES: Record<string, IDECapabilities> = {
|
|
|
+ opencode: {
|
|
|
+ id: 'opencode',
|
|
|
+ name: 'OpenCode',
|
|
|
+ features: {
|
|
|
+ multipleAgents: true,
|
|
|
+ skills: true,
|
|
|
+ plugins: true,
|
|
|
+ tools: true,
|
|
|
+ contexts: true,
|
|
|
+ commands: true,
|
|
|
+ granularPermissions: true,
|
|
|
+ hooks: true
|
|
|
+ }
|
|
|
+ // No limits - full support
|
|
|
+ },
|
|
|
+
|
|
|
+ claude: {
|
|
|
+ id: 'claude',
|
|
|
+ name: 'Claude Code',
|
|
|
+ features: {
|
|
|
+ multipleAgents: true,
|
|
|
+ skills: true,
|
|
|
+ plugins: true,
|
|
|
+ tools: true,
|
|
|
+ contexts: true,
|
|
|
+ commands: false,
|
|
|
+ granularPermissions: false,
|
|
|
+ hooks: true
|
|
|
+ }
|
|
|
+ // Full support except commands and granular permissions
|
|
|
+ },
|
|
|
+
|
|
|
+ cursor: {
|
|
|
+ id: 'cursor',
|
|
|
+ name: 'Cursor IDE',
|
|
|
+ features: {
|
|
|
+ multipleAgents: false, // Single .cursorrules file
|
|
|
+ skills: false,
|
|
|
+ plugins: false,
|
|
|
+ tools: false,
|
|
|
+ contexts: true, // Embedded in .cursorrules
|
|
|
+ commands: false,
|
|
|
+ granularPermissions: false,
|
|
|
+ hooks: false
|
|
|
+ },
|
|
|
+ limits: {
|
|
|
+ maxAgents: 1, // Merge all agents into one
|
|
|
+ maxFileSize: 100000 // ~100KB limit for .cursorrules
|
|
|
+ }
|
|
|
+ },
|
|
|
+
|
|
|
+ windsurf: {
|
|
|
+ id: 'windsurf',
|
|
|
+ name: 'Windsurf',
|
|
|
+ features: {
|
|
|
+ multipleAgents: true,
|
|
|
+ skills: false,
|
|
|
+ plugins: false,
|
|
|
+ tools: false,
|
|
|
+ contexts: true,
|
|
|
+ commands: false,
|
|
|
+ granularPermissions: false,
|
|
|
+ hooks: false
|
|
|
+ },
|
|
|
+ limits: {
|
|
|
+ maxAgents: 10
|
|
|
+ }
|
|
|
+ }
|
|
|
+};
|
|
|
+```
|
|
|
+
|
|
|
+**Feature Detection & Warnings**:
|
|
|
+
|
|
|
+```bash
|
|
|
+# User tries to install skill for Cursor
|
|
|
+oac install cursor --profile developer
|
|
|
+
|
|
|
+⚠ Feature Compatibility Warning:
|
|
|
+
|
|
|
+ IDE: Cursor
|
|
|
+ Profile: developer
|
|
|
+
|
|
|
+ Unsupported features in this profile:
|
|
|
+ ❌ Skills (8 skills will be skipped)
|
|
|
+ ❌ Plugins (2 plugins will be skipped)
|
|
|
+ ❌ Commands (7 commands will be skipped)
|
|
|
+ ⚠ Multiple agents (2 agents will be merged into .cursorrules)
|
|
|
+
|
|
|
+ Supported features:
|
|
|
+ ✓ Agents (will merge into single .cursorrules)
|
|
|
+ ✓ Contexts (will embed in .cursorrules)
|
|
|
+
|
|
|
+? How would you like to proceed?
|
|
|
+ > Continue with supported features only
|
|
|
+ Cancel installation
|
|
|
+ Show detailed compatibility report
|
|
|
+ Create custom profile for Cursor
|
|
|
+
|
|
|
+# Detailed compatibility report
|
|
|
+oac compatibility cursor --profile developer
|
|
|
+
|
|
|
+IDE Compatibility Report: Cursor
|
|
|
+Profile: developer
|
|
|
+
|
|
|
+┌─────────────────────┬──────────┬────────────────────────┐
|
|
|
+│ Feature │ Status │ Action │
|
|
|
+├─────────────────────┼──────────┼────────────────────────┤
|
|
|
+│ Agents (2) │ ⚠ Merge │ Combine into .cursorrules │
|
|
|
+│ Subagents (8) │ ⚠ Merge │ Combine into .cursorrules │
|
|
|
+│ Skills (8) │ ❌ Skip │ Not supported │
|
|
|
+│ Plugins (2) │ ❌ Skip │ Not supported │
|
|
|
+│ Commands (7) │ ❌ Skip │ Not supported │
|
|
|
+│ Contexts (15) │ ✓ Embed │ Embed in .cursorrules │
|
|
|
+│ Tools (3) │ ❌ Skip │ Not supported │
|
|
|
+└─────────────────────┴──────────┴────────────────────────┘
|
|
|
+
|
|
|
+Estimated .cursorrules size: 45KB (within 100KB limit)
|
|
|
+
|
|
|
+Recommendations:
|
|
|
+• Use OpenCode or Claude Code for full feature support
|
|
|
+• Create Cursor-specific profile with essential agents only
|
|
|
+• Consider using oac create profile --for cursor
|
|
|
+```
|
|
|
+
|
|
|
+**Adaptive Installation**:
|
|
|
+
|
|
|
+```typescript
|
|
|
+class AdaptiveInstaller {
|
|
|
+ async install(ide: string, profile: string, options: InstallOptions) {
|
|
|
+ const capabilities = IDE_CAPABILITIES[ide];
|
|
|
+ const components = await this.loadProfile(profile);
|
|
|
+
|
|
|
+ // Filter components based on IDE capabilities
|
|
|
+ const supported = this.filterByCapabilities(components, capabilities);
|
|
|
+ const unsupported = components.filter(c => !supported.includes(c));
|
|
|
+
|
|
|
+ // Warn user about unsupported features
|
|
|
+ if (unsupported.length > 0 && !options.yolo) {
|
|
|
+ const proceed = await this.warnUnsupportedFeatures(
|
|
|
+ ide,
|
|
|
+ supported,
|
|
|
+ unsupported,
|
|
|
+ capabilities
|
|
|
+ );
|
|
|
+
|
|
|
+ if (!proceed) {
|
|
|
+ return { cancelled: true };
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ // Apply transformations for IDE-specific limitations
|
|
|
+ const transformed = await this.transformForIDE(supported, capabilities);
|
|
|
+
|
|
|
+ // Install
|
|
|
+ return this.installComponents(transformed, ide, options);
|
|
|
+ }
|
|
|
+
|
|
|
+ private filterByCapabilities(
|
|
|
+ components: Component[],
|
|
|
+ capabilities: IDECapabilities
|
|
|
+ ): Component[] {
|
|
|
+ return components.filter(component => {
|
|
|
+ switch (component.type) {
|
|
|
+ case 'agent':
|
|
|
+ case 'subagent':
|
|
|
+ return capabilities.features.multipleAgents ||
|
|
|
+ components.filter(c => c.type === 'agent').length === 1;
|
|
|
+ case 'skill':
|
|
|
+ return capabilities.features.skills;
|
|
|
+ case 'plugin':
|
|
|
+ return capabilities.features.plugins;
|
|
|
+ case 'tool':
|
|
|
+ return capabilities.features.tools;
|
|
|
+ case 'context':
|
|
|
+ return capabilities.features.contexts;
|
|
|
+ case 'command':
|
|
|
+ return capabilities.features.commands;
|
|
|
+ default:
|
|
|
+ return false;
|
|
|
+ }
|
|
|
+ });
|
|
|
+ }
|
|
|
+
|
|
|
+ private async transformForIDE(
|
|
|
+ components: Component[],
|
|
|
+ capabilities: IDECapabilities
|
|
|
+ ): Promise<Component[]> {
|
|
|
+ // Special handling for Cursor: merge all agents
|
|
|
+ if (capabilities.id === 'cursor') {
|
|
|
+ const agents = components.filter(c => c.type === 'agent' || c.type === 'subagent');
|
|
|
+ const contexts = components.filter(c => c.type === 'context');
|
|
|
+
|
|
|
+ // Merge agents into single .cursorrules
|
|
|
+ const merged = await this.mergeAgentsForCursor(agents, contexts);
|
|
|
+
|
|
|
+ return [merged];
|
|
|
+ }
|
|
|
+
|
|
|
+ return components;
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**IDE-Specific Profiles**:
|
|
|
+
|
|
|
+```bash
|
|
|
+# Create profile optimized for specific IDE
|
|
|
+oac create profile --for cursor --name cursor-essentials
|
|
|
+
|
|
|
+? Select components for Cursor profile:
|
|
|
+ Agents (select up to 3 - will be merged):
|
|
|
+ ✓ openagent
|
|
|
+ ✓ opencoder
|
|
|
+ ✓ frontend-specialist
|
|
|
+
|
|
|
+ Contexts (will be embedded):
|
|
|
+ ✓ core/standards/code-quality
|
|
|
+ ✓ development/react-patterns
|
|
|
+
|
|
|
+ ⚠ Skills, plugins, and commands are not supported by Cursor
|
|
|
+
|
|
|
+✓ Created profile: cursor-essentials
|
|
|
+✓ Estimated .cursorrules size: 32KB
|
|
|
+✓ Compatible with Cursor IDE
|
|
|
+
|
|
|
+# List IDE-specific profiles
|
|
|
+oac profiles --for cursor
|
|
|
+ cursor-essentials
|
|
|
+ cursor-minimal
|
|
|
+ cursor-frontend
|
|
|
+
|
|
|
+# Install IDE-specific profile
|
|
|
+oac install cursor --profile cursor-essentials
|
|
|
+```
|
|
|
+
|
|
|
+**Component Creation with IDE Support**:
|
|
|
+
|
|
|
+```bash
|
|
|
+# Create component with IDE compatibility info
|
|
|
+oac create agent rust-specialist
|
|
|
+
|
|
|
+? Which IDEs should support this agent?
|
|
|
+ ✓ OpenCode (full support)
|
|
|
+ ✓ Claude Code (full support)
|
|
|
+ ✓ Cursor (will be merged with other agents)
|
|
|
+ ✓ Windsurf (full support)
|
|
|
+
|
|
|
+? Agent size optimization:
|
|
|
+ > Standard (no optimization)
|
|
|
+ Compact (optimize for Cursor's file size limit)
|
|
|
+ Minimal (essential instructions only)
|
|
|
+
|
|
|
+✓ Created agent with multi-IDE support
|
|
|
+✓ Estimated sizes:
|
|
|
+ - OpenCode: 15KB (standalone)
|
|
|
+ - Claude Code: 15KB (standalone)
|
|
|
+ - Cursor: +15KB (merged into .cursorrules)
|
|
|
+ - Windsurf: 15KB (standalone)
|
|
|
+```
|
|
|
+
|
|
|
+**Capacity Warnings**:
|
|
|
+
|
|
|
+```bash
|
|
|
+# Installing too many components for Cursor
|
|
|
+oac install cursor --profile developer
|
|
|
+
|
|
|
+⚠ Capacity Warning:
|
|
|
+
|
|
|
+ IDE: Cursor
|
|
|
+ Limit: 100KB for .cursorrules
|
|
|
+
|
|
|
+ Current profile size: 125KB
|
|
|
+ ❌ Exceeds limit by 25KB
|
|
|
+
|
|
|
+? How would you like to proceed:
|
|
|
+ > Remove optional components (interactive)
|
|
|
+ Use compact mode (reduce file sizes)
|
|
|
+ Create custom profile
|
|
|
+ Cancel installation
|
|
|
+
|
|
|
+# Interactive component selection
|
|
|
+? Select components to include (max 100KB):
|
|
|
+
|
|
|
+ Core (required):
|
|
|
+ ✓ openagent (12KB)
|
|
|
+ ✓ opencoder (15KB)
|
|
|
+
|
|
|
+ Specialists (optional):
|
|
|
+ ✓ frontend-specialist (18KB)
|
|
|
+ ✓ devops-specialist (16KB)
|
|
|
+ ☐ data-analyst (14KB)
|
|
|
+ ☐ copywriter (12KB)
|
|
|
+
|
|
|
+ Contexts:
|
|
|
+ ✓ core/standards (8KB)
|
|
|
+ ✓ development/patterns (12KB)
|
|
|
+
|
|
|
+ Current: 81KB / 100KB
|
|
|
+ Remaining: 19KB
|
|
|
+```
|
|
|
+
|
|
|
+**CLI Commands for IDE Management**:
|
|
|
+
|
|
|
+```bash
|
|
|
+# Check IDE compatibility
|
|
|
+oac compatibility <ide>
|
|
|
+ --profile <profile> # Check profile compatibility
|
|
|
+ --component <component> # Check component compatibility
|
|
|
+
|
|
|
+# List supported IDEs
|
|
|
+oac ides
|
|
|
+ --features # Show feature matrix
|
|
|
+ --limits # Show capacity limits
|
|
|
+
|
|
|
+# Show IDE capabilities
|
|
|
+oac ide info <ide>
|
|
|
+ → Shows full feature support matrix
|
|
|
+
|
|
|
+# Optimize for IDE
|
|
|
+oac optimize --for <ide>
|
|
|
+ → Optimizes current installation for IDE
|
|
|
+ → Removes unsupported features
|
|
|
+ → Compacts files if needed
|
|
|
+
|
|
|
+# Validate IDE installation
|
|
|
+oac validate --ide <ide>
|
|
|
+ → Checks if installation is valid for IDE
|
|
|
+ → Warns about unsupported features
|
|
|
+ → Checks capacity limits
|
|
|
+```
|
|
|
+
|
|
|
+**Configuration**:
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "ides": {
|
|
|
+ "opencode": {
|
|
|
+ "enabled": true,
|
|
|
+ "path": ".opencode",
|
|
|
+ "profile": "developer",
|
|
|
+ "features": "all"
|
|
|
+ },
|
|
|
+ "cursor": {
|
|
|
+ "enabled": true,
|
|
|
+ "path": ".cursor",
|
|
|
+ "profile": "cursor-essentials",
|
|
|
+ "features": "auto-detect",
|
|
|
+ "optimization": {
|
|
|
+ "mergeAgents": true,
|
|
|
+ "embedContexts": true,
|
|
|
+ "compactMode": true,
|
|
|
+ "maxFileSize": 100000
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "claude": {
|
|
|
+ "enabled": true,
|
|
|
+ "path": ".claude",
|
|
|
+ "profile": "developer",
|
|
|
+ "features": "all"
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "compatibility": {
|
|
|
+ "warnUnsupported": true,
|
|
|
+ "autoOptimize": false,
|
|
|
+ "strictMode": false
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**Best Practices**:
|
|
|
+
|
|
|
+**For Full Features** (OpenCode, Claude Code):
|
|
|
+- ✅ Use standard profiles (developer, business, etc.)
|
|
|
+- ✅ Install all component types
|
|
|
+- ✅ No optimization needed
|
|
|
+
|
|
|
+**For Limited IDEs** (Cursor):
|
|
|
+- ✅ Create IDE-specific profiles
|
|
|
+- ✅ Keep agent count low (1-3 agents)
|
|
|
+- ✅ Use compact mode
|
|
|
+- ✅ Embed contexts instead of separate files
|
|
|
+- ✅ Monitor file size limits
|
|
|
+
|
|
|
+**For All IDEs**:
|
|
|
+- ✅ Check compatibility before installing: `oac compatibility <ide>`
|
|
|
+- ✅ Use `--dry-run` to preview changes
|
|
|
+- ✅ Create custom profiles for specific needs
|
|
|
+- ✅ Validate after installation: `oac validate --ide <ide>`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## CLI Commands Reference
|
|
|
+
|
|
|
+**CRITICAL**: All commands run in project root directory. User chooses local (project) or global install.
|
|
|
+
|
|
|
+### Installation & Setup
|
|
|
+
|
|
|
+```bash
|
|
|
+# Initialize OAC in current directory (interactive)
|
|
|
+oac init [profile]
|
|
|
+ --local # Force local install (./opencode)
|
|
|
+ --global # Force global install (~/.config/oac)
|
|
|
+ --yolo # Skip all confirmations
|
|
|
+ --dry-run # Show what would happen
|
|
|
+
|
|
|
+# Install for specific IDE (asks local/global)
|
|
|
+oac install [ide]
|
|
|
+ --local # Install to current directory
|
|
|
+ --global # Install to global config
|
|
|
+ --profile <name> # Use specific profile
|
|
|
+ --yolo # Auto-confirm all
|
|
|
+ --skip-existing # Skip conflicts, keep existing
|
|
|
+ --force # Overwrite all, no backups
|
|
|
+ --dry-run # Preview changes
|
|
|
+
|
|
|
+# Configure OAC settings
|
|
|
+oac configure
|
|
|
+ set <key> <value> # Set config value
|
|
|
+ get <key> # Get config value
|
|
|
+ show # Show all config
|
|
|
+ reset # Reset to defaults
|
|
|
+```
|
|
|
+
|
|
|
+### Component Management
|
|
|
+
|
|
|
+```bash
|
|
|
+# Add component from registry (asks local/global)
|
|
|
+oac add <component>
|
|
|
+ --local # Add to current project
|
|
|
+ --global # Add to global config
|
|
|
+ --yolo # Auto-confirm
|
|
|
+ --dry-run # Preview
|
|
|
+
|
|
|
+# Remove component
|
|
|
+oac remove <component>
|
|
|
+ --local # Remove from current project
|
|
|
+ --global # Remove from global
|
|
|
+ --yolo # Auto-confirm
|
|
|
+
|
|
|
+# List installed components
|
|
|
+oac list [--type]
|
|
|
+ --local # List local components
|
|
|
+ --global # List global components
|
|
|
+ --agents # List agents only
|
|
|
+ --skills # List skills only
|
|
|
+ --contexts # List contexts only
|
|
|
+
|
|
|
+# Search registry
|
|
|
+oac search <query>
|
|
|
+ --type <type> # Filter by type
|
|
|
+ --verified # Verified only
|
|
|
+
|
|
|
+# Browse available components
|
|
|
+oac browse [type]
|
|
|
+ --verified # Verified only
|
|
|
+ --community # Community only
|
|
|
+```
|
|
|
+
|
|
|
+### Updates & Sync
|
|
|
+
|
|
|
+```bash
|
|
|
+# Update components (asks which to update)
|
|
|
+oac update [options]
|
|
|
+ --check # Check for updates only
|
|
|
+ --all # Update all components
|
|
|
+ --local # Update local install
|
|
|
+ --global # Update global install
|
|
|
+ --claude # Apply to Claude Code
|
|
|
+ --opencode # Apply to OpenCode
|
|
|
+ --yolo # Auto-confirm all
|
|
|
+ --dry-run # Preview updates
|
|
|
+
|
|
|
+# Apply config to IDE (asks for confirmation)
|
|
|
+oac apply [ide]
|
|
|
+ --all # Apply to all configured IDEs
|
|
|
+ --yolo # Auto-confirm
|
|
|
+ --force # Overwrite all
|
|
|
+ --dry-run # Preview
|
|
|
+
|
|
|
+# Sync across all IDEs
|
|
|
+oac sync
|
|
|
+ --yolo # Auto-confirm
|
|
|
+ --dry-run # Preview
|
|
|
+```
|
|
|
+
|
|
|
+### Creation & Scaffolding (Interactive)
|
|
|
+
|
|
|
+```bash
|
|
|
+# Interactive component creation wizard
|
|
|
+oac create
|
|
|
+ ? What would you like to create?
|
|
|
+ > Agent
|
|
|
+ Skill
|
|
|
+ Context
|
|
|
+ Plugin
|
|
|
+ Command
|
|
|
+ Tool
|
|
|
+
|
|
|
+ ? Component type:
|
|
|
+ > agent
|
|
|
+ subagent
|
|
|
+
|
|
|
+ ? Name: rust-specialist
|
|
|
+ ? Description: Expert in Rust programming
|
|
|
+ ? Category: development
|
|
|
+
|
|
|
+ ✓ Created .opencode/agent/subagents/development/rust-specialist.md
|
|
|
+ ✓ Created tests/smoke-test.yaml
|
|
|
+ ✓ Added to registry
|
|
|
+
|
|
|
+ Next steps:
|
|
|
+ 1. Edit agent prompt
|
|
|
+ 2. Add tests
|
|
|
+ 3. Test: oac test agent:rust-specialist
|
|
|
+
|
|
|
+# Create specific component types
|
|
|
+oac create agent [name]
|
|
|
+ --category <category> # Agent category
|
|
|
+ --template <template> # Use template
|
|
|
+ --with-tests # Include test scaffold
|
|
|
+ --interactive # Interactive wizard (default)
|
|
|
+
|
|
|
+oac create skill [name]
|
|
|
+ --trigger <pattern> # Skill trigger pattern
|
|
|
+ --template <template>
|
|
|
+
|
|
|
+oac create context [name]
|
|
|
+ --category <category>
|
|
|
+ --template <template>
|
|
|
+
|
|
|
+oac create plugin [name]
|
|
|
+ --type <type> # Plugin type
|
|
|
+
|
|
|
+# List available templates
|
|
|
+oac templates
|
|
|
+ --type <type> # Filter by type
|
|
|
+
|
|
|
+# Use template
|
|
|
+oac create agent --template specialist
|
|
|
+ → Uses specialist agent template
|
|
|
+```
|
|
|
+
|
|
|
+### Publishing (Community)
|
|
|
+
|
|
|
+```bash
|
|
|
+# Publish component to registry
|
|
|
+oac publish <path>
|
|
|
+ --type <type> # Component type
|
|
|
+ --dry-run # Validate only
|
|
|
+
|
|
|
+# Remove from registry
|
|
|
+oac unpublish <component>
|
|
|
+
|
|
|
+# Validate component package
|
|
|
+oac validate <path>
|
|
|
+```
|
|
|
+
|
|
|
+### Utilities
|
|
|
+
|
|
|
+```bash
|
|
|
+# Check installation health
|
|
|
+oac doctor
|
|
|
+ --local # Check local install
|
|
|
+ --global # Check global install
|
|
|
+ --fix # Auto-fix issues (asks confirmation)
|
|
|
+
|
|
|
+# Clean cache and temp files
|
|
|
+oac clean
|
|
|
+ --cache # Clean cache only
|
|
|
+ --backups # Clean backups only
|
|
|
+ --all # Clean everything
|
|
|
+ --yolo # Auto-confirm
|
|
|
+
|
|
|
+# Rollback last operation
|
|
|
+oac rollback
|
|
|
+ --steps <n> # Rollback n operations
|
|
|
+ --to <timestamp> # Rollback to timestamp
|
|
|
+
|
|
|
+# Show version info
|
|
|
+oac version
|
|
|
+ --check # Check for updates
|
|
|
+
|
|
|
+# Show help
|
|
|
+oac help [command]
|
|
|
+```
|
|
|
+
|
|
|
+### Global Flags (All Commands)
|
|
|
+
|
|
|
+```bash
|
|
|
+--yolo # Skip all confirmations, auto-resolve conflicts
|
|
|
+--dry-run # Show what would happen, don't execute
|
|
|
+--verbose # Show detailed output
|
|
|
+--quiet # Minimal output
|
|
|
+--no-color # Disable colors
|
|
|
+--json # Output as JSON
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Architecture
|
|
|
+
|
|
|
+### Directory Structure
|
|
|
+
|
|
|
+```
|
|
|
+@nextsystems/oac/
|
|
|
+├── bin/
|
|
|
+│ └── oac.js # CLI entry point
|
|
|
+├── src/
|
|
|
+│ ├── cli/
|
|
|
+│ │ ├── commands/ # CLI command implementations
|
|
|
+│ │ │ ├── init.ts
|
|
|
+│ │ │ ├── install.ts
|
|
|
+│ │ │ ├── configure.ts
|
|
|
+│ │ │ ├── add.ts
|
|
|
+│ │ │ ├── update.ts
|
|
|
+│ │ │ ├── apply.ts
|
|
|
+│ │ │ ├── publish.ts
|
|
|
+│ │ │ └── ...
|
|
|
+│ │ ├── config/
|
|
|
+│ │ │ ├── manager.ts # Configuration management
|
|
|
+│ │ │ ├── schema.ts # Zod schemas
|
|
|
+│ │ │ └── defaults.ts # Default configs
|
|
|
+│ │ └── index.ts # CLI orchestrator
|
|
|
+│ ├── core/
|
|
|
+│ │ ├── registry/
|
|
|
+│ │ │ ├── loader.ts # Load registry
|
|
|
+│ │ │ ├── resolver.ts # Resolve dependencies
|
|
|
+│ │ │ ├── validator.ts # Validate registry
|
|
|
+│ │ │ └── publisher.ts # Publish components
|
|
|
+│ │ ├── installer/
|
|
|
+│ │ │ ├── component.ts # Install components
|
|
|
+│ │ │ ├── profile.ts # Install profiles
|
|
|
+│ │ │ └── ide.ts # IDE-specific setup
|
|
|
+│ │ ├── updater/
|
|
|
+│ │ │ ├── version.ts # Version checking
|
|
|
+│ │ │ ├── fetcher.ts # Fetch updates
|
|
|
+│ │ │ └── applier.ts # Apply updates
|
|
|
+│ │ └── context/
|
|
|
+│ │ ├── locator.ts # Find context files
|
|
|
+│ │ ├── resolver.ts # Resolve paths
|
|
|
+│ │ └── validator.ts # Validate refs
|
|
|
+│ ├── adapters/
|
|
|
+│ │ ├── base.ts # Base adapter
|
|
|
+│ │ ├── opencode.ts # OpenCode adapter
|
|
|
+│ │ ├── cursor.ts # Cursor adapter
|
|
|
+│ │ ├── claude.ts # Claude Code adapter
|
|
|
+│ │ └── windsurf.ts # Windsurf adapter
|
|
|
+│ ├── types/
|
|
|
+│ │ ├── registry.ts # Registry types
|
|
|
+│ │ ├── config.ts # Config types
|
|
|
+│ │ └── component.ts # Component types
|
|
|
+│ └── utils/
|
|
|
+│ ├── logger.ts # Logging
|
|
|
+│ ├── spinner.ts # Progress indicators
|
|
|
+│ └── prompts.ts # Interactive prompts
|
|
|
+├── config/
|
|
|
+│ ├── oac.config.json # Default config
|
|
|
+│ └── ide-mappings.json # IDE mappings
|
|
|
+├── .opencode/ # Existing structure
|
|
|
+├── registry.json # Official registry
|
|
|
+├── community-registry.json # Community registry
|
|
|
+└── package.json
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Technical Stack
|
|
|
+
|
|
|
+### Dependencies
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "dependencies": {
|
|
|
+ "commander": "^12.0.0", // CLI framework
|
|
|
+ "inquirer": "^9.2.0", // Interactive prompts
|
|
|
+ "zod": "^3.22.0", // Schema validation
|
|
|
+ "chalk": "^5.3.0", // Terminal colors
|
|
|
+ "ora": "^8.0.0", // Spinners
|
|
|
+ "boxen": "^7.1.0", // Boxes
|
|
|
+ "table": "^6.8.0", // Tables
|
|
|
+ "fs-extra": "^11.2.0", // File system
|
|
|
+ "glob": "^10.3.0", // Pattern matching
|
|
|
+ "semver": "^7.6.0", // Version comparison
|
|
|
+ "node-fetch": "^3.3.0", // HTTP requests
|
|
|
+ "yaml": "^2.3.0", // YAML parsing
|
|
|
+ "tar": "^6.2.0", // Package extraction
|
|
|
+ "simple-git": "^3.22.0" // Git operations
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Implementation Phases
|
|
|
+
|
|
|
+### Phase 1: Core CLI Infrastructure (Week 1)
|
|
|
+**Goal**: Set up CLI framework and configuration system
|
|
|
+
|
|
|
+**Tasks**:
|
|
|
+- Set up TypeScript project in `src/`
|
|
|
+- Install dependencies (Commander, Zod, inquirer)
|
|
|
+- Create configuration schema and manager
|
|
|
+- Implement basic commands (init, configure, list)
|
|
|
+- Write tests
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- `src/cli/index.ts`
|
|
|
+- `src/cli/config/manager.ts`
|
|
|
+- `src/cli/config/schema.ts`
|
|
|
+- `oac configure` works
|
|
|
+- `oac list` works
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 2: Registry & Component Management (Week 2)
|
|
|
+**Goal**: Component installation and management
|
|
|
+
|
|
|
+**Tasks**:
|
|
|
+- Port registry validation to TypeScript
|
|
|
+- Implement registry loader and resolver
|
|
|
+- Create component installer
|
|
|
+- Implement profile installer
|
|
|
+- Add dependency resolution
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- `src/core/registry/loader.ts`
|
|
|
+- `src/core/installer/component.ts`
|
|
|
+- `oac install opencode --profile developer` works
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 3: IDE Adapters Integration (Week 3)
|
|
|
+**Goal**: Multi-IDE support
|
|
|
+
|
|
|
+**Tasks**:
|
|
|
+- Move compatibility layer to `src/adapters/`
|
|
|
+- Implement IDE-specific installers
|
|
|
+- Create adapter registry
|
|
|
+- Implement `oac apply` command
|
|
|
+- Add IDE detection
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- `src/adapters/opencode.ts`
|
|
|
+- `src/adapters/cursor.ts`
|
|
|
+- `oac apply cursor` works
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 4: Update System (Week 4)
|
|
|
+**Goal**: Version management
|
|
|
+
|
|
|
+**Tasks**:
|
|
|
+- Create version checker
|
|
|
+- Implement update fetcher
|
|
|
+- Create update applier
|
|
|
+- Implement `oac update` command
|
|
|
+- Add update notifications
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- `src/core/updater/version.ts`
|
|
|
+- `oac update --check` works
|
|
|
+- `oac update --claude --global` works
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 5: Context System (Week 5)
|
|
|
+**Goal**: Flexible context locations
|
|
|
+
|
|
|
+**Tasks**:
|
|
|
+- Create context locator service
|
|
|
+- Implement context resolver
|
|
|
+- Add context validator
|
|
|
+- Update agents to use locator
|
|
|
+- Add context discovery
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- `src/core/context/locator.ts`
|
|
|
+- Context files resolve from multiple locations
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 6: Community Registry (Week 6)
|
|
|
+**Goal**: shadcn-like component sharing
|
|
|
+
|
|
|
+**Tasks**:
|
|
|
+- Design component package format
|
|
|
+- Implement `oac add` command
|
|
|
+- Implement `oac publish` command
|
|
|
+- Create community registry
|
|
|
+- Add component validation
|
|
|
+- Implement search and browse
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- `src/cli/commands/add.ts`
|
|
|
+- `src/cli/commands/publish.ts`
|
|
|
+- `src/core/registry/publisher.ts`
|
|
|
+- `oac add agent:rust-specialist` works
|
|
|
+- `oac publish ./my-agent` works
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Phase 7: Polish & Documentation (Week 7)
|
|
|
+**Goal**: Production-ready package
|
|
|
+
|
|
|
+**Tasks**:
|
|
|
+- Add comprehensive error handling
|
|
|
+- Improve CLI UX
|
|
|
+- Write user documentation
|
|
|
+- Create migration guide
|
|
|
+- Update README
|
|
|
+- Publish to npm
|
|
|
+
|
|
|
+**Deliverables**:
|
|
|
+- `docs/cli-reference.md`
|
|
|
+- `docs/configuration.md`
|
|
|
+- `docs/community-components.md`
|
|
|
+- `docs/migration-guide.md`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Community Component Guidelines
|
|
|
+
|
|
|
+### Component Types
|
|
|
+
|
|
|
+**Agents**: AI agent prompts for specific domains
|
|
|
+- Example: `rust-specialist`, `python-expert`, `devops-guru`
|
|
|
+
|
|
|
+**Skills**: Auto-invoked guidance for specific tasks
|
|
|
+- Example: `git-workflow`, `testing-patterns`, `security-checks`
|
|
|
+
|
|
|
+**Contexts**: Shared knowledge files
|
|
|
+- Example: `rust-patterns`, `react-best-practices`, `api-design`
|
|
|
+
|
|
|
+**Tools**: Custom MCP tools
|
|
|
+- Example: `database-inspector`, `api-tester`, `log-analyzer`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Publishing Requirements
|
|
|
+
|
|
|
+**Must have**:
|
|
|
+- ✅ Valid `oac.json` metadata
|
|
|
+- ✅ Component file (agent.md, skill.md, etc.)
|
|
|
+- ✅ README.md with usage instructions
|
|
|
+- ✅ LICENSE file (MIT, Apache 2.0, etc.)
|
|
|
+- ✅ Passes validation (`oac validate`)
|
|
|
+
|
|
|
+**Should have**:
|
|
|
+- ✅ Tests (smoke-test.yaml minimum)
|
|
|
+- ✅ Examples in README
|
|
|
+- ✅ Version history in CHANGELOG.md
|
|
|
+- ✅ GitHub repository
|
|
|
+
|
|
|
+**Nice to have**:
|
|
|
+- ✅ Context files
|
|
|
+- ✅ Multiple test cases
|
|
|
+- ✅ Screenshots/demos
|
|
|
+- ✅ Video tutorial
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### Verification System
|
|
|
+
|
|
|
+**Verified Components**: Official or community-approved
|
|
|
+- ✅ Reviewed by maintainers
|
|
|
+- ✅ Follows best practices
|
|
|
+- ✅ Has comprehensive tests
|
|
|
+- ✅ Well-documented
|
|
|
+- ✅ Actively maintained
|
|
|
+
|
|
|
+**Unverified Components**: Community contributions
|
|
|
+- ⚠️ Use at your own risk
|
|
|
+- ⚠️ May not follow best practices
|
|
|
+- ⚠️ May have limited testing
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Backward Compatibility
|
|
|
+
|
|
|
+**Preserve existing workflows**:
|
|
|
+- ✅ Keep `install.sh` for direct usage
|
|
|
+- ✅ Keep `bin/oac.js` as entry point
|
|
|
+- ✅ Keep registry.json format
|
|
|
+- ✅ Keep `.opencode/` structure
|
|
|
+- ✅ Support legacy `oac [profile]` syntax
|
|
|
+
|
|
|
+**Migration path**:
|
|
|
+```bash
|
|
|
+# Old way (still works)
|
|
|
+npm install -g @nextsystems/oac
|
|
|
+oac developer
|
|
|
+
|
|
|
+# New way (enhanced)
|
|
|
+npm install -g @nextsystems/oac
|
|
|
+oac configure
|
|
|
+oac install opencode
|
|
|
+oac add agent:rust-specialist
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Success Metrics
|
|
|
+
|
|
|
+**Must have**:
|
|
|
+- ✅ Multi-IDE installation works
|
|
|
+- ✅ Configuration persists
|
|
|
+- ✅ Updates work across IDEs
|
|
|
+- ✅ Community components can be added
|
|
|
+- ✅ Context resolution works
|
|
|
+- ✅ Backward compatible
|
|
|
+
|
|
|
+**Nice to have**:
|
|
|
+- ✅ 100+ community components
|
|
|
+- ✅ Auto-update notifications
|
|
|
+- ✅ IDE auto-detection
|
|
|
+- ✅ Plugin system
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Related Files
|
|
|
+
|
|
|
+**Core Concepts**:
|
|
|
+- `core-concepts/agents.md` - Agent system
|
|
|
+- `core-concepts/registry.md` - Registry system
|
|
|
+- `concepts/compatibility-layer.md` - Multi-IDE support
|
|
|
+
|
|
|
+**Guides**:
|
|
|
+- `guides/npm-publishing.md` - Publishing workflow
|
|
|
+- `guides/adding-agent.md` - Creating agents
|
|
|
+
|
|
|
+**Lookup**:
|
|
|
+- `lookup/file-locations.md` - File structure
|
|
|
+- `lookup/compatibility-layer-structure.md` - Adapter structure
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## Next Steps
|
|
|
+
|
|
|
+**Immediate**:
|
|
|
+1. ✅ Create feature branch
|
|
|
+2. ✅ Create context file (this file)
|
|
|
+3. Create GitHub issue for tracking
|
|
|
+4. Set up project board
|
|
|
+
|
|
|
+**Phase 1 Start**:
|
|
|
+1. Set up TypeScript project structure
|
|
|
+2. Install dependencies
|
|
|
+3. Create configuration schema
|
|
|
+4. Implement `oac configure` command
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+**Last Updated**: 2026-02-14
|
|
|
+**Version**: 1.0.0-alpha
|
|
|
+**Status**: Planning → Implementation
|
Darren Hinde