chore: install openagent opencode
Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
This commit is contained in:
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