chore: install openagent opencode
Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
This commit is contained in:
@@ -0,0 +1,559 @@
|
||||
<!-- Context: openagents-repo/core-concepts/agent-metadata | Priority: critical | Version: 1.0 | Updated: 2026-01-31 -->
|
||||
# Core Concept: Agent Metadata System
|
||||
|
||||
**Purpose**: Understanding the centralized metadata system for OpenAgents Control
|
||||
**Priority**: CRITICAL - Load this before working with agent metadata
|
||||
|
||||
---
|
||||
|
||||
## What Is the Agent Metadata System?
|
||||
|
||||
The agent metadata system separates **OpenCode-compliant agent configuration** from **OpenAgents Control registry metadata**. This solves the problem of OpenCode validation errors when agents contain fields that aren't part of the OpenCode agent schema.
|
||||
|
||||
**Key Principle**: Agent frontmatter contains ONLY valid OpenCode fields. All other metadata lives in a centralized file.
|
||||
|
||||
---
|
||||
|
||||
## The Problem We Solved
|
||||
|
||||
### Before (Validation Errors)
|
||||
|
||||
Agent frontmatter contained fields that OpenCode doesn't recognize:
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: opencoder # ❌ Not valid OpenCode field
|
||||
name: OpenCoder # ❌ Not valid OpenCode field
|
||||
category: core # ❌ Not valid OpenCode field
|
||||
type: core # ❌ Not valid OpenCode field
|
||||
version: 1.0.0 # ❌ Not valid OpenCode field
|
||||
author: opencode # ❌ Not valid OpenCode field
|
||||
tags: [development, coding] # ❌ Not valid OpenCode field
|
||||
dependencies: [] # ❌ Not valid OpenCode field
|
||||
description: "..." # ✅ Valid OpenCode field
|
||||
mode: primary # ✅ Valid OpenCode field
|
||||
temperature: 0.1 # ✅ Valid OpenCode field
|
||||
tools: {...} # ✅ Valid OpenCode field
|
||||
permission: {...} # ✅ Valid OpenCode field
|
||||
---
|
||||
```
|
||||
|
||||
**Result**: OpenCode validation errors:
|
||||
```
|
||||
Extra inputs are not permitted, field: 'id', value: 'opencoder'
|
||||
Extra inputs are not permitted, field: 'category', value: 'core'
|
||||
Extra inputs are not permitted, field: 'type', value: 'core'
|
||||
... (9 validation errors)
|
||||
```
|
||||
|
||||
### After (Clean Separation)
|
||||
|
||||
**Agent frontmatter** (`.opencode/agent/core/opencoder.md`):
|
||||
```yaml
|
||||
---
|
||||
# Metadata stored in: .opencode/config/agent-metadata.json
|
||||
description: "Orchestration agent for complex coding, architecture, and multi-file refactoring"
|
||||
mode: primary
|
||||
temperature: 0.1
|
||||
tools: {...}
|
||||
permission: {...}
|
||||
---
|
||||
```
|
||||
|
||||
**Centralized metadata** (`.opencode/config/agent-metadata.json`):
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"opencoder": {
|
||||
"id": "opencoder",
|
||||
"name": "OpenCoder",
|
||||
"category": "core",
|
||||
"type": "agent",
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"tags": ["development", "coding", "implementation"],
|
||||
"dependencies": [
|
||||
"subagent:documentation",
|
||||
"subagent:coder-agent",
|
||||
"context:core/standards/code"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Result**: ✅ No validation errors, clean separation of concerns
|
||||
|
||||
---
|
||||
|
||||
## Valid OpenCode Agent Fields
|
||||
|
||||
Based on [OpenCode documentation](https://opencode.ai/docs/agents/), these are the ONLY valid frontmatter fields:
|
||||
|
||||
### Required Fields
|
||||
- `description` - When to use this agent (required)
|
||||
- `mode` - Agent type: `primary`, `subagent`, or `all` (defaults to `all`)
|
||||
|
||||
### Optional Fields
|
||||
- `model` - Model override (e.g., `anthropic/claude-sonnet-4-20250514`)
|
||||
- `temperature` - Response randomness (0.0-1.0)
|
||||
- `maxSteps` - Max agentic iterations
|
||||
- `disable` - Set to `true` to disable agent
|
||||
- `prompt` - Custom prompt file path (e.g., `{file:./prompts/build.txt}`)
|
||||
- `hidden` - Hide from @ autocomplete (subagents only)
|
||||
- `tools` - Tool access configuration
|
||||
- `permission` - Permission rules for tools (v1.1.1+, replaces deprecated `permissions`)
|
||||
|
||||
### Example Valid Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "Code review agent with security focus"
|
||||
mode: subagent
|
||||
model: anthropic/claude-sonnet-4-20250514
|
||||
temperature: 0.1
|
||||
tools:
|
||||
read: true
|
||||
grep: true
|
||||
glob: true
|
||||
write: false
|
||||
edit: false
|
||||
permission: # v1.1.1+ (singular, not plural)
|
||||
bash:
|
||||
"*": ask
|
||||
"git *": allow
|
||||
edit: deny
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Centralized Metadata File
|
||||
|
||||
**Location**: `.opencode/config/agent-metadata.json`
|
||||
|
||||
### Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/schemas/agent-metadata.json",
|
||||
"schema_version": "1.0.0",
|
||||
"description": "Centralized metadata for OpenAgents Control agents",
|
||||
"agents": {
|
||||
"agent-id": {
|
||||
"id": "agent-id",
|
||||
"name": "Agent Name",
|
||||
"category": "core|development|content|data|product|learning|meta",
|
||||
"type": "agent|subagent",
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"dependencies": [
|
||||
"subagent:subagent-id",
|
||||
"context:path/to/context"
|
||||
]
|
||||
}
|
||||
},
|
||||
"defaults": {
|
||||
"agent": {
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"type": "agent",
|
||||
"tags": []
|
||||
},
|
||||
"subagent": {
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"type": "subagent",
|
||||
"tags": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Metadata Fields
|
||||
|
||||
| Field | Required | Description | Example |
|
||||
|-------|----------|-------------|---------|
|
||||
| `id` | Yes | Unique identifier (kebab-case) | `"opencoder"` |
|
||||
| `name` | Yes | Display name | `"OpenCoder"` |
|
||||
| `category` | Yes | Agent category | `"core"` |
|
||||
| `type` | Yes | Component type | `"agent"` or `"subagent"` |
|
||||
| `version` | Yes | Version number | `"1.0.0"` |
|
||||
| `author` | Yes | Author identifier | `"opencode"` |
|
||||
| `tags` | No | Discovery tags | `["development", "coding"]` |
|
||||
| `dependencies` | No | Component dependencies | `["subagent:tester"]` |
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Agent Creation
|
||||
|
||||
When creating a new agent:
|
||||
|
||||
**Step 1**: Create agent file with ONLY valid OpenCode fields
|
||||
|
||||
```bash
|
||||
# Create agent file
|
||||
touch .opencode/agent/category/my-agent.md
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "My agent description"
|
||||
mode: subagent
|
||||
temperature: 0.2
|
||||
tools:
|
||||
read: true
|
||||
write: true
|
||||
---
|
||||
|
||||
# Agent prompt content here
|
||||
```
|
||||
|
||||
**Step 2**: Add metadata to `.opencode/config/agent-metadata.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"my-agent": {
|
||||
"id": "my-agent",
|
||||
"name": "My Agent",
|
||||
"category": "development",
|
||||
"type": "subagent",
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"tags": ["custom", "helper"],
|
||||
"dependencies": ["context:core/standards/code"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3**: Run auto-detect to update registry
|
||||
|
||||
```bash
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
The auto-detect script:
|
||||
1. Reads frontmatter from agent file (description, mode, etc.)
|
||||
2. Reads metadata from `agent-metadata.json` (id, name, tags, dependencies)
|
||||
3. Merges both into registry.json entry
|
||||
|
||||
### 2. Auto-Detect Integration
|
||||
|
||||
The auto-detect script (`scripts/registry/auto-detect-components.sh`) has been enhanced to:
|
||||
|
||||
1. **Extract frontmatter** - Read description from agent file
|
||||
2. **Lookup metadata** - Check `agent-metadata.json` for agent ID
|
||||
3. **Merge data** - Combine frontmatter + metadata
|
||||
4. **Update registry** - Write complete entry to registry.json
|
||||
|
||||
**Code snippet** (from auto-detect script):
|
||||
|
||||
```bash
|
||||
# Check if agent-metadata.json exists and merge metadata from it
|
||||
local metadata_file="$REPO_ROOT/.opencode/config/agent-metadata.json"
|
||||
if [ -f "$metadata_file" ] && command -v jq &> /dev/null; then
|
||||
# Try to find metadata for this agent ID
|
||||
local metadata_entry
|
||||
metadata_entry=$(jq -r ".agents[\"$id\"] // empty" "$metadata_file" 2>/dev/null)
|
||||
|
||||
if [ -n "$metadata_entry" ] && [ "$metadata_entry" != "null" ]; then
|
||||
# Merge name, tags, dependencies from metadata
|
||||
# ...
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
### 3. Registry Output
|
||||
|
||||
The registry.json entry contains merged data:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "opencoder",
|
||||
"name": "OpenCoder",
|
||||
"type": "agent",
|
||||
"path": ".opencode/agent/core/opencoder.md",
|
||||
"description": "Orchestration agent for complex coding...",
|
||||
"category": "core",
|
||||
"tags": ["development", "coding", "implementation"],
|
||||
"dependencies": [
|
||||
"subagent:documentation",
|
||||
"subagent:coder-agent",
|
||||
"context:core/standards/code"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Adding a New Agent
|
||||
|
||||
```bash
|
||||
# 1. Create agent file (OpenCode-compliant frontmatter only)
|
||||
vim .opencode/agent/category/my-agent.md
|
||||
|
||||
# 2. Add metadata entry
|
||||
vim .opencode/config/agent-metadata.json
|
||||
|
||||
# 3. Update registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# 4. Validate
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
### Updating Agent Metadata
|
||||
|
||||
**To update OpenCode configuration** (tools, permissions, temperature):
|
||||
```bash
|
||||
# Edit agent file frontmatter
|
||||
vim .opencode/agent/category/my-agent.md
|
||||
```
|
||||
|
||||
**To update registry metadata** (tags, dependencies, version):
|
||||
```bash
|
||||
# Edit metadata file
|
||||
vim .opencode/config/agent-metadata.json
|
||||
|
||||
# Re-run auto-detect
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
### Updating Dependencies
|
||||
|
||||
**Add a dependency**:
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"my-agent": {
|
||||
"dependencies": [
|
||||
"subagent:tester",
|
||||
"context:core/standards/code",
|
||||
"subagent:new-dependency" // ← Add here
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then run:
|
||||
```bash
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### ✅ OpenCode Compliance
|
||||
- Agent frontmatter contains ONLY valid OpenCode fields
|
||||
- No validation errors from OpenCode
|
||||
- Agents work correctly with OpenCode CLI
|
||||
|
||||
### ✅ Registry Compatibility
|
||||
- Registry still has all metadata (id, name, category, tags, dependencies)
|
||||
- Auto-detect script merges frontmatter + metadata
|
||||
- Backward compatible with existing tools
|
||||
|
||||
### ✅ Single Source of Truth
|
||||
- Metadata centralized in one file
|
||||
- Easy to update dependencies across multiple agents
|
||||
- Clear separation: OpenCode config vs. registry metadata
|
||||
|
||||
### ✅ Maintainability
|
||||
- Update dependencies in one place
|
||||
- Consistent metadata across all agents
|
||||
- Easy to add new metadata fields
|
||||
|
||||
### ✅ Validation
|
||||
- OpenCode validates frontmatter (no extra fields)
|
||||
- Registry validator checks dependencies exist
|
||||
- Clear error messages when metadata is missing
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Migrating from permissions (plural) to permission (singular)
|
||||
|
||||
**OpenCode v1.1.1+ Change**: The field name changed from `permissions:` (plural) to `permission:` (singular).
|
||||
|
||||
**Before** (deprecated):
|
||||
```yaml
|
||||
permissions:
|
||||
bash:
|
||||
"*": "deny"
|
||||
```
|
||||
|
||||
**After** (v1.1.1+):
|
||||
```yaml
|
||||
permission:
|
||||
bash:
|
||||
"*": "deny"
|
||||
```
|
||||
|
||||
**Migration Steps**:
|
||||
1. Find all agents using `permissions:` (plural)
|
||||
```bash
|
||||
grep -r "^permissions:" .opencode/agent/
|
||||
```
|
||||
|
||||
2. Replace with `permission:` (singular) in each file
|
||||
|
||||
3. Verify no validation errors:
|
||||
```bash
|
||||
opencode agent validate
|
||||
```
|
||||
|
||||
### Migrating Existing Agents
|
||||
|
||||
**Step 1**: Identify agents with extra fields
|
||||
|
||||
```bash
|
||||
# Find agents with invalid OpenCode fields
|
||||
grep -r "^id:\|^name:\|^category:\|^type:\|^version:\|^author:\|^tags:\|^dependencies:" .opencode/agent/
|
||||
```
|
||||
|
||||
**Step 2**: Extract metadata to `agent-metadata.json`
|
||||
|
||||
For each agent:
|
||||
1. Copy `id`, `name`, `category`, `type`, `version`, `author`, `tags`, `dependencies` to metadata file
|
||||
2. Remove these fields from agent frontmatter
|
||||
3. Keep ONLY valid OpenCode fields in frontmatter
|
||||
|
||||
**Step 3**: Update registry
|
||||
|
||||
```bash
|
||||
# Remove old entries
|
||||
jq 'del(.components.agents[] | select(.id == "agent-id"))' registry.json > tmp.json && mv tmp.json registry.json
|
||||
|
||||
# Re-add with new metadata
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
**Step 4**: Validate
|
||||
|
||||
```bash
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Agent Frontmatter
|
||||
|
||||
✅ **DO**:
|
||||
- Keep frontmatter minimal (only OpenCode fields)
|
||||
- Add comment pointing to metadata file
|
||||
- Use consistent formatting
|
||||
|
||||
❌ **DON'T**:
|
||||
- Add custom fields to frontmatter
|
||||
- Duplicate metadata in both places
|
||||
- Skip the metadata file
|
||||
|
||||
### Metadata File
|
||||
|
||||
✅ **DO**:
|
||||
- Keep metadata file in version control
|
||||
- Update metadata when adding/removing dependencies
|
||||
- Use consistent naming (kebab-case for IDs)
|
||||
- Document why dependencies exist
|
||||
|
||||
❌ **DON'T**:
|
||||
- Forget to update metadata when creating agents
|
||||
- Leave orphaned entries (agents that don't exist)
|
||||
- Skip validation after updates
|
||||
|
||||
### Dependencies
|
||||
|
||||
✅ **DO**:
|
||||
- Declare ALL dependencies (subagents, contexts)
|
||||
- Use correct format: `type:id`
|
||||
- Validate dependencies exist in registry
|
||||
|
||||
❌ **DON'T**:
|
||||
- Reference components without declaring dependency
|
||||
- Use invalid dependency formats
|
||||
- Forget to update when dependencies change
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### OpenCode Validation Errors
|
||||
|
||||
**Problem**: `Extra inputs are not permitted, field: 'id'`
|
||||
|
||||
**Solution**: Remove invalid fields from agent frontmatter, add to metadata file
|
||||
|
||||
```bash
|
||||
# 1. Edit agent file - remove id, name, category, type, version, author, tags, dependencies
|
||||
vim .opencode/agent/category/agent.md
|
||||
|
||||
# 2. Add to metadata file
|
||||
vim .opencode/config/agent-metadata.json
|
||||
|
||||
# 3. Update registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
### Missing Metadata
|
||||
|
||||
**Problem**: Auto-detect can't find metadata for agent
|
||||
|
||||
**Solution**: Add entry to `agent-metadata.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"agent-id": {
|
||||
"id": "agent-id",
|
||||
"name": "Agent Name",
|
||||
"category": "core",
|
||||
"type": "agent",
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"tags": [],
|
||||
"dependencies": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Registry Out of Sync
|
||||
|
||||
**Problem**: Registry has old metadata
|
||||
|
||||
**Solution**: Remove entry and re-run auto-detect
|
||||
|
||||
```bash
|
||||
# Remove old entry
|
||||
jq 'del(.components.agents[] | select(.id == "agent-id"))' registry.json > tmp.json && mv tmp.json registry.json
|
||||
|
||||
# Re-add with current metadata
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **OpenCode Agent Docs**: https://opencode.ai/docs/agents/
|
||||
- **Registry System**: `.opencode/context/openagents-repo/core-concepts/registry.md`
|
||||
- **Adding Agents**: `.opencode/context/openagents-repo/guides/adding-agent-basics.md`
|
||||
- **Dependencies**: `.opencode/context/openagents-repo/quality/registry-dependencies.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-31
|
||||
**Version**: 1.0.0
|
||||
364
.opencode/context/openagents-repo/core-concepts/agents.md
Normal file
364
.opencode/context/openagents-repo/core-concepts/agents.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# Core Concept: Agents
|
||||
|
||||
**Purpose**: Understanding how agents work in OpenAgents Control
|
||||
**Priority**: CRITICAL - Load this before working with agents
|
||||
|
||||
---
|
||||
|
||||
## What Are Agents?
|
||||
|
||||
Agents are AI prompt files that define specialized behaviors for different tasks. They are:
|
||||
- **Markdown files** with frontmatter metadata
|
||||
- **Category-organized** by domain (core, development, content, etc.)
|
||||
- **Context-aware** - load relevant context files
|
||||
- **Testable** - validated through eval framework
|
||||
|
||||
---
|
||||
|
||||
## Agent Structure
|
||||
|
||||
### File Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "Brief description of what this agent does"
|
||||
category: "category-name"
|
||||
type: "agent"
|
||||
tags: ["tag1", "tag2"]
|
||||
dependencies: ["subagent:tester"]
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
[Agent prompt content - instructions, workflows, constraints]
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **Frontmatter** (YAML metadata)
|
||||
- `description`: Brief description
|
||||
- `category`: Category name (core, development, content, etc.)
|
||||
- `type`: Always "agent"
|
||||
- `tags`: Optional tags for discovery
|
||||
- `dependencies`: Optional dependencies (e.g., subagents)
|
||||
|
||||
2. **Prompt Content**
|
||||
- Instructions and workflows
|
||||
- Constraints and rules
|
||||
- Context loading requirements
|
||||
- Tool usage patterns
|
||||
|
||||
---
|
||||
|
||||
## Category System
|
||||
|
||||
Agents are organized by domain expertise:
|
||||
|
||||
### Core Category (`core/`)
|
||||
**Purpose**: Essential system agents (always available)
|
||||
|
||||
Agents:
|
||||
- `openagent.md` - General-purpose orchestrator
|
||||
- `opencoder.md` - Development specialist
|
||||
- `system-builder.md` - System generation
|
||||
|
||||
**When to use**: System-level tasks, orchestration
|
||||
|
||||
---
|
||||
|
||||
### Development Category (`development/`)
|
||||
**Purpose**: Software development specialists
|
||||
|
||||
Agents:
|
||||
- `frontend-specialist.md` - React, Vue, modern CSS
|
||||
- `devops-specialist.md` - CI/CD, deployment, infrastructure
|
||||
|
||||
**When to use**: Building applications, dev tasks
|
||||
|
||||
---
|
||||
|
||||
### Content Category (`content/`)
|
||||
**Purpose**: Content creation specialists
|
||||
|
||||
Agents:
|
||||
- `copywriter.md` - Marketing copy, persuasive writing
|
||||
- `technical-writer.md` - Documentation, technical content
|
||||
|
||||
**When to use**: Writing, documentation, marketing
|
||||
|
||||
---
|
||||
|
||||
### Data Category (`data/`)
|
||||
**Purpose**: Data analysis specialists
|
||||
|
||||
Agents:
|
||||
- `data-analyst.md` - Data analysis, visualization
|
||||
|
||||
**When to use**: Data tasks, analysis, reporting
|
||||
|
||||
---
|
||||
|
||||
### Product Category (`product/`)
|
||||
**Purpose**: Product management specialists
|
||||
|
||||
**Status**: Ready for agents (no agents yet)
|
||||
|
||||
**When to use**: Product strategy, roadmaps, requirements
|
||||
|
||||
---
|
||||
|
||||
### Learning Category (`learning/`)
|
||||
**Purpose**: Education and coaching specialists
|
||||
|
||||
**Status**: Ready for agents (no agents yet)
|
||||
|
||||
**When to use**: Teaching, training, curriculum
|
||||
|
||||
---
|
||||
|
||||
## Subagents
|
||||
|
||||
**Location**: `.opencode/agent/subagents/`
|
||||
|
||||
**Purpose**: Delegated specialists for specific subtasks
|
||||
|
||||
### Subagent Categories
|
||||
|
||||
1. **code/** - Code-related specialists
|
||||
- `tester.md` - Test authoring and TDD
|
||||
- `reviewer.md` - Code review and security
|
||||
- `coder-agent.md` - Focused implementations
|
||||
- `build-agent.md` - Type checking and builds
|
||||
|
||||
2. **core/** - Core workflow specialists
|
||||
- `task-manager.md` - Task breakdown and management
|
||||
- `documentation.md` - Documentation generation
|
||||
|
||||
3. **system-builder/** - System generation specialists
|
||||
- `agent-generator.md` - Generate agent files
|
||||
- `command-creator.md` - Create slash commands
|
||||
- `domain-analyzer.md` - Analyze domains
|
||||
- `context-organizer.md` - Organize context
|
||||
- `workflow-designer.md` - Design workflows
|
||||
|
||||
4. **utils/** - Utility specialists
|
||||
- `image-specialist.md` - Image editing and analysis
|
||||
|
||||
### Subagents vs Category Agents
|
||||
|
||||
| Aspect | Category Agents | Subagents |
|
||||
|--------|----------------|-----------|
|
||||
| **Purpose** | User-facing specialists | Delegated subtasks |
|
||||
| **Invocation** | Direct by user | Via task tool |
|
||||
| **Scope** | Broad domain | Narrow focus |
|
||||
| **Example** | `frontend-specialist` | `tester` |
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Interop (Optional)
|
||||
|
||||
OpenAgents Control can pair with Claude Code for local workflows and distribution:
|
||||
|
||||
- **Subagents**: Project helpers in `.claude/agents/`
|
||||
- **Skills**: Auto-invoked guidance in `.claude/skills/`
|
||||
- **Hooks**: Shell commands on lifecycle events (use sparingly)
|
||||
- **Plugins**: Share agents/skills/hooks across projects
|
||||
|
||||
Use this when you want Claude Code to follow OpenAgents Control standards or to ship reusable helpers.
|
||||
|
||||
---
|
||||
|
||||
## Path Resolution
|
||||
|
||||
The system supports multiple path formats for backward compatibility:
|
||||
|
||||
### Supported Formats
|
||||
|
||||
```bash
|
||||
# Short ID (backward compatible)
|
||||
"openagent" → resolves to → ".opencode/agent/core/openagent.md"
|
||||
|
||||
# Category path
|
||||
"core/openagent" → resolves to → ".opencode/agent/core/openagent.md"
|
||||
|
||||
# Full category path
|
||||
"development/frontend-specialist" → resolves to → ".opencode/agent/subagents/development/frontend-specialist.md"
|
||||
|
||||
# Subagent path
|
||||
"TestEngineer" → resolves to → ".opencode/agent/subagents/code/test-engineer.md"
|
||||
```
|
||||
|
||||
### Resolution Rules
|
||||
|
||||
1. Check if path includes `/` → use as category path
|
||||
2. If no `/` → check core/ first (backward compat)
|
||||
3. If not in core/ → search all categories
|
||||
4. If not found → error
|
||||
|
||||
---
|
||||
|
||||
## Prompt Variants
|
||||
|
||||
**Location**: `.opencode/prompts/{category}/{agent}/`
|
||||
|
||||
**Purpose**: Model-specific prompt optimizations
|
||||
|
||||
### Supported Models
|
||||
|
||||
- `gemini.md` - Google Gemini optimizations
|
||||
- `grok.md` - xAI Grok optimizations
|
||||
- `llama.md` - Meta Llama optimizations
|
||||
- `openrouter.md` - OpenRouter optimizations
|
||||
|
||||
### When to Create Variants
|
||||
|
||||
- Model has specific formatting requirements
|
||||
- Model performs better with different structure
|
||||
- Model has unique capabilities to leverage
|
||||
|
||||
### Fallback Behavior
|
||||
|
||||
If no variant exists for a model, the base agent file is used.
|
||||
|
||||
---
|
||||
|
||||
## Context Loading
|
||||
|
||||
Agents should load relevant context files based on task type:
|
||||
|
||||
### Core Context (Always Consider)
|
||||
|
||||
```markdown
|
||||
<!-- Context: standards/code | Priority: critical -->
|
||||
```
|
||||
|
||||
Loads: `.opencode/context/core/standards/code-quality.md`
|
||||
|
||||
### Category Context
|
||||
|
||||
```markdown
|
||||
<!-- Context: development/react-patterns | Priority: high -->
|
||||
```
|
||||
|
||||
Loads: `.opencode/context/ui/web/react-patterns.md`
|
||||
|
||||
### Multiple Contexts
|
||||
|
||||
```markdown
|
||||
<!-- Context: standards/code, standards/tests | Priority: critical -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Lifecycle
|
||||
|
||||
### 1. Creation
|
||||
```bash
|
||||
# Create agent file
|
||||
touch .opencode/agent/{category}/{agent-name}.md
|
||||
|
||||
# Add frontmatter and content
|
||||
# (See guides/adding-agent.md for details)
|
||||
```
|
||||
|
||||
### 2. Testing
|
||||
```bash
|
||||
# Create test structure
|
||||
mkdir -p evals/agents/{category}/{agent-name}/{config,tests}
|
||||
|
||||
# Run tests
|
||||
cd evals/framework && bun --bun run eval:sdk -- --agent={category}/{agent-name}
|
||||
```
|
||||
|
||||
### 3. Registration
|
||||
```bash
|
||||
# Auto-detect and add to registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# Validate
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
### 4. Distribution
|
||||
```bash
|
||||
# Users install via install.sh
|
||||
./install.sh {profile}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Agent Design
|
||||
|
||||
✅ **Single responsibility** - One domain, one agent
|
||||
✅ **Clear instructions** - Explicit workflows and constraints
|
||||
✅ **Context-aware** - Load relevant context files
|
||||
✅ **Testable** - Include eval tests
|
||||
✅ **Well-documented** - Clear description and usage
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- **Category agents**: `{domain}-specialist.md` (e.g., `frontend-specialist.md`)
|
||||
- **Core agents**: `{name}.md` (e.g., `openagent.md`)
|
||||
- **Subagents**: `{purpose}.md` (e.g., `tester.md`)
|
||||
|
||||
### Frontmatter Requirements
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "Required - brief description"
|
||||
category: "Required - category name"
|
||||
type: "Required - always 'agent'"
|
||||
tags: ["Optional - for discovery"]
|
||||
dependencies: ["Optional - e.g., 'subagent:tester'"]
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Delegation to Subagents
|
||||
|
||||
```markdown
|
||||
When task requires testing:
|
||||
1. Implement feature
|
||||
2. Delegate to TestEngineer for test creation
|
||||
```
|
||||
|
||||
### Context Loading
|
||||
|
||||
```markdown
|
||||
Before implementing:
|
||||
1. Load core/standards/code-quality.md
|
||||
2. Load category-specific context if available
|
||||
3. Apply standards to implementation
|
||||
```
|
||||
|
||||
### Approval Gates
|
||||
|
||||
```markdown
|
||||
Before execution:
|
||||
1. Present plan to user
|
||||
2. Request approval
|
||||
3. Execute incrementally
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Adding agents**: `guides/adding-agent.md`
|
||||
- **Testing agents**: `guides/testing-agent.md`
|
||||
- **Category system**: `core-concepts/categories.md`
|
||||
- **File locations**: `lookup/file-locations.md`
|
||||
- **Claude Code subagents**: `../to-be-consumed/claude-code-docs/create-subagents.md`
|
||||
- **Claude Code skills**: `../to-be-consumed/claude-code-docs/agent-skills.md`
|
||||
- **Claude Code hooks**: `../to-be-consumed/claude-code-docs/hooks.md`
|
||||
- **Claude Code plugins**: `../to-be-consumed/claude-code-docs/plugins.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-13
|
||||
**Version**: 0.5.1
|
||||
428
.opencode/context/openagents-repo/core-concepts/categories.md
Normal file
428
.opencode/context/openagents-repo/core-concepts/categories.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# Core Concept: Category System
|
||||
|
||||
**Purpose**: Understanding how components are organized
|
||||
**Priority**: HIGH - Load this before adding categories or organizing components
|
||||
|
||||
---
|
||||
|
||||
## What Are Categories?
|
||||
|
||||
Categories are domain-based groupings that organize agents, context files, and tests by expertise area.
|
||||
|
||||
**Benefits**:
|
||||
- **Scalability** - Easy to add new domains
|
||||
- **Discovery** - Find agents by domain
|
||||
- **Organization** - Clear structure
|
||||
- **Modularity** - Install only what you need
|
||||
|
||||
---
|
||||
|
||||
## Available Categories
|
||||
|
||||
### Core (`core/`)
|
||||
**Purpose**: Essential system agents (always available)
|
||||
|
||||
**Agents**:
|
||||
|
||||
**When to use**: System-level tasks, orchestration, coding (simple or complex)
|
||||
|
||||
**Status**: ✅ Stable
|
||||
|
||||
---
|
||||
|
||||
### Development Subagents (`subagents/development/`)
|
||||
**Purpose**: Domain-specific development specialists (invoked by core agents)
|
||||
|
||||
**Subagents**:
|
||||
- frontend-specialist, devops-specialist
|
||||
|
||||
**Context**:
|
||||
- clean-code.md, react-patterns.md, api-design.md
|
||||
|
||||
**When to use**: Delegated frontend, backend, or DevOps tasks within a larger workflow
|
||||
|
||||
**Status**: ✅ Active
|
||||
|
||||
---
|
||||
|
||||
### Content (`content/`)
|
||||
**Purpose**: Content creation specialists
|
||||
|
||||
**Agents**:
|
||||
- copywriter, technical-writer
|
||||
|
||||
**Context**:
|
||||
- copywriting-frameworks.md
|
||||
- tone-voice.md
|
||||
- audience-targeting.md
|
||||
- hooks.md
|
||||
|
||||
**When to use**: Writing, documentation, marketing
|
||||
|
||||
**Status**: ✅ Active
|
||||
|
||||
---
|
||||
|
||||
### Data (`data/`)
|
||||
**Purpose**: Data analysis specialists
|
||||
|
||||
**Agents**:
|
||||
- data-analyst
|
||||
|
||||
**Context**:
|
||||
- (Ready for data-specific context)
|
||||
|
||||
**When to use**: Data tasks, analysis, reporting
|
||||
|
||||
**Status**: ✅ Active
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Category Structure
|
||||
|
||||
### Directory Layout
|
||||
|
||||
```
|
||||
.opencode/
|
||||
├── agent/{category}/ # Agents by category
|
||||
├── context/{category}/ # Context by category
|
||||
├── prompts/{category}/ # Prompt variants by category
|
||||
evals/agents/{category}/ # Tests by category
|
||||
```
|
||||
|
||||
### Example: Core Agents + Development Subagents
|
||||
|
||||
```
|
||||
.opencode/agent/core/
|
||||
├── 0-category.json # Category metadata
|
||||
├── openagent.md
|
||||
├── opencoder.md
|
||||
|
||||
.opencode/agent/subagents/development/
|
||||
├── 0-category.json # Subagent category metadata
|
||||
├── frontend-specialist.md
|
||||
└── devops-specialist.md
|
||||
|
||||
.opencode/context/development/
|
||||
├── navigation.md
|
||||
├── clean-code.md
|
||||
├── react-patterns.md
|
||||
└── api-design.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Category Metadata
|
||||
|
||||
### 0-category.json
|
||||
|
||||
Each category has a metadata file:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Development",
|
||||
"description": "Software development specialists",
|
||||
"icon": "💻",
|
||||
"order": 2,
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `name`: Display name
|
||||
- `description`: Brief description
|
||||
- `icon`: Emoji icon
|
||||
- `order`: Display order
|
||||
- `status`: active, ready, planned
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Category Names
|
||||
|
||||
✅ **Lowercase** - `development`, not `Development`
|
||||
✅ **Singular** - `content`, not `contents`
|
||||
✅ **Descriptive** - Clear domain name
|
||||
✅ **Consistent** - Follow existing patterns
|
||||
|
||||
### Agent Names
|
||||
|
||||
✅ **Kebab-case** - `frontend-specialist.md`
|
||||
✅ **Descriptive** - Clear purpose
|
||||
✅ **Suffix** - Use `-specialist`, `-agent`, `-writer` as appropriate
|
||||
|
||||
### Context Names
|
||||
|
||||
✅ **Kebab-case** - `react-patterns.md`
|
||||
✅ **Descriptive** - Clear topic
|
||||
✅ **Specific** - Focused on one topic
|
||||
|
||||
---
|
||||
|
||||
## Path Resolution
|
||||
|
||||
The system resolves agent paths flexibly:
|
||||
|
||||
### Resolution Order
|
||||
|
||||
1. **Check for `/`** - If present, treat as category path
|
||||
2. **Check core/** - For backward compatibility
|
||||
3. **Search categories** - Look in all categories
|
||||
4. **Error** - If not found
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Short ID (backward compatible)
|
||||
"openagent" → ".opencode/agent/core/openagent.md"
|
||||
|
||||
# Subagent path
|
||||
"subagents/development/frontend-specialist" → ".opencode/agent/subagents/development/frontend-specialist.md"
|
||||
|
||||
# Subagent path
|
||||
"TestEngineer" → ".opencode/agent/subagents/code/test-engineer.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding a New Category
|
||||
|
||||
### Step 1: Create Directory Structure
|
||||
|
||||
```bash
|
||||
# Create agent directory
|
||||
mkdir -p .opencode/agent/{category}
|
||||
|
||||
# Create context directory
|
||||
mkdir -p .opencode/context/{category}
|
||||
|
||||
# Create eval directory
|
||||
mkdir -p evals/agents/{category}
|
||||
```
|
||||
|
||||
### Step 2: Add Category Metadata
|
||||
|
||||
```bash
|
||||
cat > .opencode/agent/{category}/0-category.json << 'EOF'
|
||||
{
|
||||
"name": "Category Name",
|
||||
"description": "Brief description",
|
||||
"icon": "🎯",
|
||||
"order": 10,
|
||||
"status": "ready"
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 3: Add Context README
|
||||
|
||||
```bash
|
||||
cat > .opencode/context/{category}/navigation.md << 'EOF'
|
||||
# Category Name Context
|
||||
|
||||
Context files for {category} specialists.
|
||||
|
||||
## Available Context
|
||||
|
||||
- (List context files here)
|
||||
|
||||
## When to Use
|
||||
|
||||
- (Describe when to use this context)
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 4: Validate
|
||||
|
||||
```bash
|
||||
# Validate structure
|
||||
./scripts/registry/validate-component.sh
|
||||
|
||||
# Update registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Category Guidelines
|
||||
|
||||
### When to Create a New Category
|
||||
|
||||
✅ **Distinct domain** - Clear expertise area
|
||||
✅ **Multiple agents** - Plan for 2+ agents
|
||||
✅ **Shared context** - Common knowledge to share
|
||||
✅ **User demand** - Requested by users
|
||||
|
||||
### When NOT to Create a Category
|
||||
|
||||
❌ **Single agent** - Use existing category
|
||||
❌ **Overlapping** - Fits in existing category
|
||||
❌ **Too specific** - Too narrow focus
|
||||
❌ **Unclear domain** - Not well-defined
|
||||
|
||||
---
|
||||
|
||||
## Category vs Subagent
|
||||
|
||||
### Use Category Agent When:
|
||||
- User-facing specialist
|
||||
- Broad domain expertise
|
||||
- Direct invocation by user
|
||||
- Example: `frontend-specialist`
|
||||
|
||||
### Use Subagent When:
|
||||
- Delegated subtask
|
||||
- Narrow focus
|
||||
- Invoked by other agents
|
||||
- Example: `tester`
|
||||
|
||||
---
|
||||
|
||||
## Context Organization
|
||||
|
||||
### Category Context Structure
|
||||
|
||||
```
|
||||
.opencode/context/{category}/
|
||||
├── navigation.md # Overview
|
||||
├── {topic-1}.md # Specific topic
|
||||
├── {topic-2}.md # Specific topic
|
||||
└── {topic-3}.md # Specific topic
|
||||
```
|
||||
|
||||
### Context Loading
|
||||
|
||||
Agents load category context based on task:
|
||||
|
||||
```markdown
|
||||
<!-- Context: development/react-patterns | Priority: high -->
|
||||
```
|
||||
|
||||
Loads: `.opencode/context/ui/web/react-patterns.md`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Organization
|
||||
|
||||
✅ **Clear categories** - Well-defined domains
|
||||
✅ **Consistent naming** - Follow conventions
|
||||
✅ **Proper metadata** - Complete 0-category.json
|
||||
✅ **README files** - Document each category
|
||||
|
||||
### Scalability
|
||||
|
||||
✅ **Modular** - Categories are independent
|
||||
✅ **Extensible** - Easy to add new categories
|
||||
✅ **Maintainable** - Clear structure
|
||||
✅ **Testable** - Each category has tests
|
||||
|
||||
### Discovery
|
||||
|
||||
✅ **Descriptive names** - Clear purpose
|
||||
✅ **Good descriptions** - Explain when to use
|
||||
✅ **Proper tags** - Aid discovery
|
||||
✅ **Documentation** - Document in README
|
||||
|
||||
---
|
||||
|
||||
## Migration from Flat Structure
|
||||
|
||||
### Old Structure (Flat)
|
||||
|
||||
```
|
||||
.opencode/agent/
|
||||
├── openagent.md
|
||||
├── opencoder.md
|
||||
├── frontend-specialist.md
|
||||
└── copywriter.md
|
||||
```
|
||||
|
||||
### New Structure (Category-Based)
|
||||
|
||||
```
|
||||
.opencode/agent/
|
||||
├── core/
|
||||
│ ├── openagent.md
|
||||
│ ├── opencoder.md
|
||||
├── subagents/
|
||||
│ ├── development/
|
||||
│ │ ├── frontend-specialist.md
|
||||
│ │ └── devops-specialist.md
|
||||
│ └── code/
|
||||
│ ├── coder-agent.md
|
||||
│ └── tester.md
|
||||
└── content/
|
||||
└── copywriter.md
|
||||
```
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
Old paths still work:
|
||||
- `openagent` → resolves to `core/openagent`
|
||||
- `opencoder` → resolves to `core/opencoder`
|
||||
|
||||
New agents use category paths:
|
||||
- `subagents/development/frontend-specialist`
|
||||
- `content/copywriter`
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Core Category with Multiple Agents
|
||||
|
||||
```
|
||||
core/
|
||||
├── 0-category.json
|
||||
├── openagent.md
|
||||
├── opencoder.md
|
||||
```
|
||||
|
||||
### Development Subagents
|
||||
|
||||
```
|
||||
subagents/development/
|
||||
├── 0-category.json
|
||||
├── frontend-specialist.md
|
||||
└── devops-specialist.md
|
||||
```
|
||||
|
||||
### Category with Shared Context
|
||||
|
||||
```
|
||||
context/development/
|
||||
├── navigation.md
|
||||
├── clean-code.md
|
||||
├── react-patterns.md
|
||||
└── api-design.md
|
||||
```
|
||||
|
||||
### Category with Tests
|
||||
|
||||
```
|
||||
evals/agents/core/
|
||||
├── openagent/
|
||||
│ ├── config/config.yaml
|
||||
│ └── tests/smoke-test.yaml
|
||||
├── opencoder/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Adding agents**: `guides/adding-agent.md`
|
||||
- **Adding categories**: `guides/add-category.md`
|
||||
- **Agent concepts**: `core-concepts/agents.md`
|
||||
- **File locations**: `lookup/file-locations.md`
|
||||
- **Content creation principles**: `../content-creation/principles/navigation.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-13
|
||||
**Version**: 0.5.1
|
||||
496
.opencode/context/openagents-repo/core-concepts/evals.md
Normal file
496
.opencode/context/openagents-repo/core-concepts/evals.md
Normal file
@@ -0,0 +1,496 @@
|
||||
<!-- Context: openagents-repo/evals | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Core Concept: Eval Framework
|
||||
|
||||
**Purpose**: Understanding how agent testing works
|
||||
**Priority**: CRITICAL - Load this before testing agents
|
||||
|
||||
---
|
||||
|
||||
## What Is the Eval Framework?
|
||||
|
||||
The eval framework is a TypeScript-based testing system that validates agent behavior through:
|
||||
- **Test definitions** (YAML files)
|
||||
- **Session collection** (capturing agent interactions)
|
||||
- **Evaluators** (rules that validate behavior)
|
||||
- **Reports** (pass/fail with detailed violations)
|
||||
|
||||
**Location**: `evals/framework/`
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Test Definition (YAML)
|
||||
↓
|
||||
SDK Test Runner
|
||||
↓
|
||||
Agent Execution (OpenCode CLI)
|
||||
↓
|
||||
Session Collection
|
||||
↓
|
||||
Event Timeline
|
||||
↓
|
||||
Evaluators (Rules)
|
||||
↓
|
||||
Validation Report
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Structure
|
||||
|
||||
### Directory Layout
|
||||
|
||||
```
|
||||
evals/agents/{category}/{agent-name}/
|
||||
├── config/
|
||||
│ └── config.yaml # Agent test configuration
|
||||
└── tests/
|
||||
├── smoke-test.yaml # Basic functionality test
|
||||
├── approval-gate.yaml # Approval gate test
|
||||
├── context-loading.yaml # Context loading test
|
||||
└── ... # Additional tests
|
||||
```
|
||||
|
||||
### Config File (`config.yaml`)
|
||||
|
||||
```yaml
|
||||
agent: {category}/{agent-name}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
timeout: 60000
|
||||
suites:
|
||||
- smoke
|
||||
- approval
|
||||
- context
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `agent`: Agent path (category/name format)
|
||||
- `model`: Model to use for testing
|
||||
- `timeout`: Test timeout in milliseconds
|
||||
- `suites`: Test suites to run
|
||||
|
||||
---
|
||||
|
||||
### Test File Format
|
||||
|
||||
```yaml
|
||||
name: Smoke Test
|
||||
description: Basic functionality check
|
||||
agent: core/openagent
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Hello, can you help me?"
|
||||
- role: assistant
|
||||
content: "Yes, I can help you!"
|
||||
expectations:
|
||||
- type: no_violations
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `name`: Test name
|
||||
- `description`: What this test validates
|
||||
- `agent`: Agent to test
|
||||
- `model`: Model to use
|
||||
- `conversation`: User/assistant exchanges
|
||||
- `expectations`: What should happen
|
||||
|
||||
---
|
||||
|
||||
## Evaluators
|
||||
|
||||
Evaluators are rules that validate agent behavior. Each evaluator checks for specific patterns.
|
||||
|
||||
### Available Evaluators
|
||||
|
||||
#### 1. Approval Gate Evaluator
|
||||
**Purpose**: Ensures agent requests approval before execution
|
||||
|
||||
**Validates**:
|
||||
- Agent proposes plan before executing
|
||||
- User approves before write/edit/bash operations
|
||||
- No auto-execution without approval
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent executed write tool without requesting approval first
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 2. Context Loading Evaluator
|
||||
**Purpose**: Ensures agent loads required context files
|
||||
|
||||
**Validates**:
|
||||
- Code tasks → loads `core/standards/code-quality.md`
|
||||
- Doc tasks → loads `core/standards/documentation.md`
|
||||
- Test tasks → loads `core/standards/test-coverage.md`
|
||||
- Context loaded BEFORE implementation
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent executed write tool without loading required context: core/standards/code-quality.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 3. Tool Usage Evaluator
|
||||
**Purpose**: Ensures agent uses appropriate tools
|
||||
|
||||
**Validates**:
|
||||
- Uses `read` instead of `bash cat`
|
||||
- Uses `list` instead of `bash ls`
|
||||
- Uses `grep` instead of `bash grep`
|
||||
- Proper tool selection for tasks
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent used bash tool for reading file instead of read tool
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 4. Stop on Failure Evaluator
|
||||
**Purpose**: Ensures agent stops on errors instead of auto-fixing
|
||||
|
||||
**Validates**:
|
||||
- Agent reports errors to user
|
||||
- Agent proposes fix and requests approval
|
||||
- No auto-fixing without approval
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent auto-fixed error without reporting and requesting approval
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 5. Execution Balance Evaluator
|
||||
**Purpose**: Ensures agent doesn't over-execute
|
||||
|
||||
**Validates**:
|
||||
- Reasonable ratio of read vs execute operations
|
||||
- Not executing excessively
|
||||
- Balanced tool usage
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent execution ratio too high: 80% execute vs 20% read
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Basic Test Run
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent}
|
||||
```
|
||||
|
||||
### Run Specific Test
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --pattern="smoke-test.yaml"
|
||||
```
|
||||
|
||||
### Run with Debug
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --debug
|
||||
```
|
||||
|
||||
### Run All Tests
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Collection
|
||||
|
||||
### What Are Sessions?
|
||||
|
||||
Sessions are recordings of agent interactions stored in `.tmp/sessions/`.
|
||||
|
||||
### Session Structure
|
||||
|
||||
```
|
||||
.tmp/sessions/{session-id}/
|
||||
├── session.json # Complete session data
|
||||
├── events.json # Event timeline
|
||||
└── context.md # Session context (if any)
|
||||
```
|
||||
|
||||
### Session Data
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "session-id",
|
||||
"timestamp": "2025-12-10T17:00:00Z",
|
||||
"agent": "core/openagent",
|
||||
"model": "anthropic/claude-sonnet-4-5",
|
||||
"messages": [...],
|
||||
"toolCalls": [...],
|
||||
"events": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### Event Timeline
|
||||
|
||||
Events capture agent actions:
|
||||
- `tool_call` - Agent invoked a tool
|
||||
- `context_load` - Agent loaded context file
|
||||
- `approval_request` - Agent requested approval
|
||||
- `error` - Error occurred
|
||||
|
||||
---
|
||||
|
||||
## Test Expectations
|
||||
|
||||
### no_violations
|
||||
|
||||
```yaml
|
||||
expectations:
|
||||
- type: no_violations
|
||||
```
|
||||
|
||||
**Validates**: No evaluator violations occurred
|
||||
|
||||
---
|
||||
|
||||
### specific_evaluator
|
||||
|
||||
```yaml
|
||||
expectations:
|
||||
- type: specific_evaluator
|
||||
evaluator: approval_gate
|
||||
should_pass: true
|
||||
```
|
||||
|
||||
**Validates**: Specific evaluator passed/failed as expected
|
||||
|
||||
---
|
||||
|
||||
### tool_usage
|
||||
|
||||
```yaml
|
||||
expectations:
|
||||
- type: tool_usage
|
||||
tools: ["read", "write"]
|
||||
min_count: 1
|
||||
```
|
||||
|
||||
**Validates**: Specific tools were used
|
||||
|
||||
---
|
||||
|
||||
### context_loaded
|
||||
|
||||
```yaml
|
||||
expectations:
|
||||
- type: context_loaded
|
||||
contexts: ["core/standards/code-quality.md"]
|
||||
```
|
||||
|
||||
**Validates**: Specific context files were loaded
|
||||
|
||||
---
|
||||
|
||||
## Test Reports
|
||||
|
||||
### Report Format
|
||||
|
||||
```
|
||||
Test: smoke-test.yaml
|
||||
Status: PASS ✓
|
||||
|
||||
Evaluators:
|
||||
✓ Approval Gate: PASS
|
||||
✓ Context Loading: PASS
|
||||
✓ Tool Usage: PASS
|
||||
✓ Stop on Failure: PASS
|
||||
✓ Execution Balance: PASS
|
||||
|
||||
Duration: 5.2s
|
||||
```
|
||||
|
||||
### Failure Report
|
||||
|
||||
```
|
||||
Test: approval-gate.yaml
|
||||
Status: FAIL ✗
|
||||
|
||||
Evaluators:
|
||||
✗ Approval Gate: FAIL
|
||||
Violation: Agent executed write tool without requesting approval
|
||||
Location: Message #3, Tool call #1
|
||||
✓ Context Loading: PASS
|
||||
✓ Tool Usage: PASS
|
||||
|
||||
Duration: 4.8s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing Tests
|
||||
|
||||
### Smoke Test (Basic Functionality)
|
||||
|
||||
```yaml
|
||||
name: Smoke Test
|
||||
description: Verify agent responds correctly
|
||||
agent: core/openagent
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Hello, can you help me?"
|
||||
expectations:
|
||||
- type: no_violations
|
||||
```
|
||||
|
||||
### Approval Gate Test
|
||||
|
||||
```yaml
|
||||
name: Approval Gate Test
|
||||
description: Verify agent requests approval before execution
|
||||
agent: core/opencoder
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Create a new file called test.js with a hello world function"
|
||||
expectations:
|
||||
- type: specific_evaluator
|
||||
evaluator: approval_gate
|
||||
should_pass: true
|
||||
```
|
||||
|
||||
### Context Loading Test
|
||||
|
||||
```yaml
|
||||
name: Context Loading Test
|
||||
description: Verify agent loads required context
|
||||
agent: core/opencoder
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Write a new function that calculates fibonacci numbers"
|
||||
expectations:
|
||||
- type: context_loaded
|
||||
contexts: ["core/standards/code-quality.md"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging Test Failures
|
||||
|
||||
### Step 1: Run with Debug
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={agent} --pattern="{test}" --debug
|
||||
```
|
||||
|
||||
### Step 2: Check Session
|
||||
|
||||
```bash
|
||||
# Find session
|
||||
ls -lt .tmp/sessions/ | head -5
|
||||
|
||||
# View session
|
||||
cat .tmp/sessions/{session-id}/session.json | jq
|
||||
```
|
||||
|
||||
### Step 3: Analyze Events
|
||||
|
||||
```bash
|
||||
# View events
|
||||
cat .tmp/sessions/{session-id}/events.json | jq
|
||||
```
|
||||
|
||||
### Step 4: Identify Violation
|
||||
|
||||
Look for:
|
||||
- Missing approval requests
|
||||
- Missing context loads
|
||||
- Wrong tool usage
|
||||
- Auto-fixing behavior
|
||||
|
||||
### Step 5: Fix Agent
|
||||
|
||||
Update agent prompt to:
|
||||
- Add approval gate
|
||||
- Add context loading
|
||||
- Use correct tools
|
||||
- Stop on failure
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Test Coverage
|
||||
|
||||
✅ **Smoke test** - Basic functionality
|
||||
✅ **Approval gate test** - Verify approval workflow
|
||||
✅ **Context loading test** - Verify context usage
|
||||
✅ **Tool usage test** - Verify correct tools
|
||||
✅ **Error handling test** - Verify stop on failure
|
||||
|
||||
### Test Design
|
||||
|
||||
✅ **Clear expectations** - Explicit what should happen
|
||||
✅ **Realistic scenarios** - Test real-world usage
|
||||
✅ **Isolated tests** - One concern per test
|
||||
✅ **Fast execution** - Keep tests under 10 seconds
|
||||
|
||||
### Debugging
|
||||
|
||||
✅ **Use debug mode** - See detailed output
|
||||
✅ **Check sessions** - Analyze agent behavior
|
||||
✅ **Review events** - Understand timeline
|
||||
✅ **Iterate quickly** - Fix and re-test
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Test Timeout
|
||||
|
||||
**Problem**: Test exceeds timeout
|
||||
**Solution**: Increase timeout in config.yaml or optimize agent
|
||||
|
||||
### Approval Gate Violation
|
||||
|
||||
**Problem**: Agent executes without approval
|
||||
**Solution**: Add approval request in agent prompt
|
||||
|
||||
### Context Loading Violation
|
||||
|
||||
**Problem**: Agent doesn't load required context
|
||||
**Solution**: Add context loading logic in agent prompt
|
||||
|
||||
### Tool Usage Violation
|
||||
|
||||
**Problem**: Agent uses wrong tools
|
||||
**Solution**: Update agent to use correct tools (read, list, grep)
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Testing guide**: `guides/testing-agent.md`
|
||||
- **Debugging guide**: `guides/debugging.md`
|
||||
- **Agent concepts**: `core-concepts/agents.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-10
|
||||
**Version**: 0.5.0
|
||||
@@ -0,0 +1,39 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Core Concepts
|
||||
|
||||
**Purpose**: Deep-dive documentation on core OpenAgents Control concepts
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/core-concepts/
|
||||
├── navigation.md (this file)
|
||||
└── [core concept files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **View core concepts** | `./` |
|
||||
| **Concepts** | `../concepts/navigation.md` |
|
||||
| **Guides** | `../guides/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Core Concepts** → In-depth documentation on fundamental OpenAgents ideas
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Concepts** → `../concepts/navigation.md`
|
||||
- **Guides** → `../guides/navigation.md`
|
||||
491
.opencode/context/openagents-repo/core-concepts/registry.md
Normal file
491
.opencode/context/openagents-repo/core-concepts/registry.md
Normal file
@@ -0,0 +1,491 @@
|
||||
<!-- Context: openagents-repo/registry | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Core Concept: Registry System
|
||||
|
||||
**Purpose**: Understanding how component tracking and distribution works
|
||||
**Priority**: CRITICAL - Load this before working with registry
|
||||
|
||||
---
|
||||
|
||||
## What Is the Registry?
|
||||
|
||||
The registry is a centralized catalog (`registry.json`) that tracks all components in OpenAgents Control:
|
||||
- **Agents** - AI agent prompts
|
||||
- **Subagents** - Delegated specialists
|
||||
- **Commands** - Slash commands
|
||||
- **Tools** - Custom tools
|
||||
- **Contexts** - Context files
|
||||
|
||||
**Location**: `registry.json` (root directory)
|
||||
|
||||
---
|
||||
|
||||
## Registry Schema
|
||||
|
||||
### Top-Level Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.5.0",
|
||||
"schema_version": "2.0.0",
|
||||
"components": {
|
||||
"agents": [...],
|
||||
"subagents": [...],
|
||||
"commands": [...],
|
||||
"tools": [...],
|
||||
"contexts": [...]
|
||||
},
|
||||
"profiles": {
|
||||
"essential": {...},
|
||||
"developer": {...},
|
||||
"business": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Component Entry
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "frontend-specialist",
|
||||
"name": "Frontend Specialist",
|
||||
"type": "agent",
|
||||
"path": ".opencode/agent/subagents/development/frontend-specialist.md",
|
||||
"description": "Expert in React, Vue, and modern CSS",
|
||||
"category": "development",
|
||||
"tags": ["react", "vue", "css", "frontend"],
|
||||
"dependencies": ["subagent:tester"],
|
||||
"version": "0.5.0"
|
||||
}
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `id`: Unique identifier (kebab-case)
|
||||
- `name`: Display name
|
||||
- `type`: Component type (agent, subagent, command, tool, context)
|
||||
- `path`: File path relative to repo root
|
||||
- `description`: Brief description
|
||||
- `category`: Category name (for agents)
|
||||
- `tags`: Optional tags for discovery
|
||||
- `dependencies`: Optional dependencies
|
||||
- `version`: Version when added/updated
|
||||
|
||||
---
|
||||
|
||||
## Auto-Detect System
|
||||
|
||||
The auto-detect system scans `.opencode/` and automatically updates the registry.
|
||||
|
||||
### How It Works
|
||||
|
||||
```
|
||||
1. Scan .opencode/ directory
|
||||
2. Find all .md files with frontmatter
|
||||
3. Extract metadata (description, category, type, tags)
|
||||
4. Validate paths exist
|
||||
5. Generate component entries
|
||||
6. Update registry.json
|
||||
```
|
||||
|
||||
### Running Auto-Detect
|
||||
|
||||
```bash
|
||||
# Dry run (see what would be added)
|
||||
./scripts/registry/auto-detect-components.sh --dry-run
|
||||
|
||||
# Actually add components
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# Force update existing entries
|
||||
./scripts/registry/auto-detect-components.sh --auto-add --force
|
||||
```
|
||||
|
||||
### What Gets Detected
|
||||
|
||||
✅ **Agents** - `.opencode/agent/{category}/*.md`
|
||||
✅ **Subagents** - `.opencode/agent/subagents/**/*.md`
|
||||
✅ **Commands** - `.opencode/command/**/*.md`
|
||||
✅ **Tools** - `.opencode/tool/**/index.ts`
|
||||
✅ **Contexts** - `.opencode/context/**/*.md`
|
||||
|
||||
### Frontmatter Requirements
|
||||
|
||||
For auto-detect to work, files must have frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "Brief description"
|
||||
category: "category-name" # For agents
|
||||
type: "agent" # Or subagent, command, tool, context
|
||||
tags: ["tag1", "tag2"] # Optional
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
### Registry Validation
|
||||
|
||||
```bash
|
||||
# Validate registry
|
||||
./scripts/registry/validate-registry.sh
|
||||
|
||||
# Verbose output
|
||||
./scripts/registry/validate-registry.sh -v
|
||||
```
|
||||
|
||||
### What Gets Validated
|
||||
|
||||
✅ **Schema** - Correct JSON structure
|
||||
✅ **Paths** - All paths exist
|
||||
✅ **IDs** - Unique IDs
|
||||
✅ **Categories** - Valid categories
|
||||
✅ **Dependencies** - Dependencies exist
|
||||
✅ **Versions** - Version consistency
|
||||
|
||||
### Validation Errors
|
||||
|
||||
```bash
|
||||
# Example errors
|
||||
ERROR: Path does not exist: (example: .opencode/agent/core/missing.md)
|
||||
ERROR: Duplicate ID: frontend-specialist
|
||||
ERROR: Invalid category: invalid-category
|
||||
ERROR: Missing dependency: subagent:nonexistent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agents vs Subagents
|
||||
|
||||
**Main Agents** (2 in Developer profile):
|
||||
- openagent: Universal coordination agent
|
||||
- opencoder: Complex coding and architecture
|
||||
|
||||
**Specialist Subagents** (8 in Developer profile):
|
||||
- frontend-specialist: React, Vue, CSS architecture
|
||||
- devops-specialist: CI/CD, infrastructure, deployment
|
||||
|
||||
- task-manager: Feature breakdown and planning
|
||||
- documentation: Create and update docs
|
||||
- coder-agent: Execute coding subtasks
|
||||
- reviewer: Code review and security
|
||||
- tester: Write unit and integration tests
|
||||
- build-agent: Type checking and validation
|
||||
- image-specialist: Generate and edit images
|
||||
|
||||
**Commands** (7 in Developer profile):
|
||||
- analyze-patterns: Analyze codebase for patterns
|
||||
- commit, test, context, clean, optimize, validate-repo
|
||||
|
||||
---
|
||||
|
||||
## Component Profiles
|
||||
|
||||
Profiles are pre-configured component bundles for quick installation.
|
||||
|
||||
### Available Profiles
|
||||
|
||||
#### Essential Profile
|
||||
**Purpose**: Minimal setup for basic usage
|
||||
|
||||
**Includes**:
|
||||
- Core agents (openagent, opencoder)
|
||||
- Essential commands (commit, test)
|
||||
- Core context files
|
||||
|
||||
```json
|
||||
"essential": {
|
||||
"description": "Minimal setup for basic usage",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:opencoder",
|
||||
"command:commit",
|
||||
"command:test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Developer Profile
|
||||
**Purpose**: Full development setup
|
||||
|
||||
**Includes**:
|
||||
- All core agents
|
||||
- Development specialists
|
||||
- All subagents
|
||||
- Dev commands
|
||||
- Dev context files
|
||||
|
||||
```json
|
||||
"developer": {
|
||||
"description": "Full development setup",
|
||||
"components": [
|
||||
"agent:*",
|
||||
"subagent:*",
|
||||
"command:*",
|
||||
"context:core/*",
|
||||
"context:development/*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Business Profile
|
||||
**Purpose**: Content and product focus
|
||||
|
||||
**Includes**:
|
||||
- Core agents
|
||||
- Content specialists
|
||||
- Product specialists
|
||||
- Content context files
|
||||
|
||||
```json
|
||||
"business": {
|
||||
"description": "Content and product focus",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:copywriter",
|
||||
"agent:technical-writer",
|
||||
"context:core/*",
|
||||
"context:content/*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Install System
|
||||
|
||||
The install system uses the registry to distribute components.
|
||||
|
||||
### Installation Flow
|
||||
|
||||
```
|
||||
1. User runs install.sh
|
||||
2. Check for local registry.json (development mode)
|
||||
3. If not local, fetch from GitHub (production mode)
|
||||
4. Parse registry.json
|
||||
5. Show component selection UI
|
||||
6. Resolve dependencies
|
||||
7. Download components from GitHub
|
||||
8. Install to .opencode/
|
||||
9. Handle collisions (skip/overwrite/backup)
|
||||
```
|
||||
|
||||
### Local Registry (Development)
|
||||
|
||||
```bash
|
||||
# Test with local registry
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
|
||||
# Install with local registry
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh developer
|
||||
```
|
||||
|
||||
### Remote Registry (Production)
|
||||
|
||||
```bash
|
||||
# Install from GitHub
|
||||
./install.sh developer
|
||||
|
||||
# List available components
|
||||
./install.sh --list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependency Resolution
|
||||
|
||||
### Dependency Format
|
||||
|
||||
```json
|
||||
"dependencies": [
|
||||
"subagent:tester",
|
||||
"context:core/standards/code"
|
||||
]
|
||||
```
|
||||
|
||||
### Resolution Rules
|
||||
|
||||
1. Parse dependency string (`type:id`)
|
||||
2. Find component in registry
|
||||
3. Check if already installed
|
||||
4. Add to install queue
|
||||
5. Recursively resolve dependencies
|
||||
6. Install in dependency order
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
User installs: frontend-specialist
|
||||
↓
|
||||
Depends on: subagent:tester
|
||||
↓
|
||||
Depends on: context:core/standards/tests
|
||||
↓
|
||||
Install order:
|
||||
1. context:core/standards/tests
|
||||
2. subagent:tester
|
||||
3. frontend-specialist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Collision Handling
|
||||
|
||||
When installing components that already exist:
|
||||
|
||||
### Collision Strategies
|
||||
|
||||
1. **Skip** - Keep existing file
|
||||
2. **Overwrite** - Replace with new file
|
||||
3. **Backup** - Backup existing, install new
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
```bash
|
||||
File exists: .opencode/agent/core/openagent.md
|
||||
[S]kip, [O]verwrite, [B]ackup, [A]ll skip, [F]orce all?
|
||||
```
|
||||
|
||||
### Non-Interactive Mode
|
||||
|
||||
```bash
|
||||
# Skip all collisions
|
||||
./install.sh developer --skip-existing
|
||||
|
||||
# Overwrite all collisions
|
||||
./install.sh developer --force
|
||||
|
||||
# Backup all collisions
|
||||
./install.sh developer --backup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version Management
|
||||
|
||||
### Version Fields
|
||||
|
||||
- **Registry version**: Overall registry version (e.g., "0.5.0")
|
||||
- **Schema version**: Registry schema version (e.g., "2.0.0")
|
||||
- **Component version**: When component was added/updated
|
||||
|
||||
### Version Consistency
|
||||
|
||||
```bash
|
||||
# Check version consistency
|
||||
cat VERSION
|
||||
cat package.json | jq '.version'
|
||||
cat registry.json | jq '.version'
|
||||
|
||||
# All should match
|
||||
```
|
||||
|
||||
### Updating Versions
|
||||
|
||||
```bash
|
||||
# Bump version
|
||||
echo "0.X.Y" > VERSION
|
||||
jq '.version = "0.X.Y"' package.json > tmp && mv tmp package.json
|
||||
jq '.version = "0.X.Y"' registry.json > tmp && mv tmp registry.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Workflows
|
||||
|
||||
#### Validate Registry (PR Checks)
|
||||
|
||||
```yaml
|
||||
# .github/workflows/validate-registry.yml
|
||||
- name: Validate Registry
|
||||
run: ./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
#### Auto-Update Registry (Post-Merge)
|
||||
|
||||
```yaml
|
||||
# .github/workflows/update-registry.yml
|
||||
- name: Update Registry
|
||||
run: ./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
#### Version Bump (On Release)
|
||||
|
||||
```yaml
|
||||
# .github/workflows/version-bump.yml
|
||||
- name: Bump Version
|
||||
run: ./scripts/versioning/bump-version.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Adding Components
|
||||
|
||||
✅ **Add frontmatter** - Required for auto-detect
|
||||
✅ **Run auto-detect** - Don't manually edit registry
|
||||
✅ **Validate** - Always validate after changes
|
||||
✅ **Test locally** - Use local registry for testing
|
||||
|
||||
### Maintaining Registry
|
||||
|
||||
✅ **Auto-detect first** - Let scripts handle updates
|
||||
✅ **Validate often** - Catch issues early
|
||||
✅ **Version consistency** - Keep versions in sync
|
||||
✅ **CI validation** - Automate validation in CI
|
||||
|
||||
### Dependencies
|
||||
|
||||
✅ **Explicit dependencies** - List all dependencies
|
||||
✅ **Test resolution** - Verify dependencies resolve
|
||||
✅ **Avoid cycles** - No circular dependencies
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Path Not Found
|
||||
|
||||
**Problem**: Registry references non-existent path
|
||||
**Solution**: Run auto-detect or fix path manually
|
||||
|
||||
### Duplicate ID
|
||||
|
||||
**Problem**: Two components with same ID
|
||||
**Solution**: Rename one component
|
||||
|
||||
### Invalid Category
|
||||
|
||||
**Problem**: Agent has invalid category
|
||||
**Solution**: Use valid category (core, development, content, data, product, learning)
|
||||
|
||||
### Missing Dependency
|
||||
|
||||
**Problem**: Dependency doesn't exist in registry
|
||||
**Solution**: Add dependency or remove reference
|
||||
|
||||
### Version Mismatch
|
||||
|
||||
**Problem**: VERSION, package.json, registry.json don't match
|
||||
**Solution**: Update all version files to match
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Updating registry**: `guides/updating-registry.md`
|
||||
- **Adding agents**: `guides/adding-agent.md`
|
||||
- **Categories**: `core-concepts/categories.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-28
|
||||
**Version**: 0.5.2
|
||||
Reference in New Issue
Block a user