|
|
@@ -1,2340 +0,0 @@
|
|
|
-<!-- 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
|
darrenhinde