10 KiB

Raw Blame History

Guide: Updating Registry

Prerequisites: Load core-concepts/registry.md first
Purpose: How to update the component registry

Quick Commands

# Auto-detect and add new components
./scripts/registry/auto-detect-components.sh --auto-add

# Validate registry
./scripts/registry/validate-registry.sh

# Dry run (see what would change)
./scripts/registry/auto-detect-components.sh --dry-run

When to Update Registry

Update the registry when you:

✅ Add a new agent
✅ Add a new command
✅ Add a new tool
✅ Add a new context file
✅ Change component metadata
✅ Move or rename components

Auto-Detect (Recommended)

Step 1: Dry Run

# See what would be added/updated
./scripts/registry/auto-detect-components.sh --dry-run

Output:

Scanning .opencode/ for components...

Would add:
  - agent: development/api-specialist
  - context: development/api-patterns.md

Would update:
  - agent: core/openagent (description changed)

Step 2: Apply Changes

# Actually update registry
./scripts/registry/auto-detect-components.sh --auto-add

Step 3: Validate

# Validate registry
./scripts/registry/validate-registry.sh

Frontmatter Metadata (Auto-Extracted)

The auto-detect script automatically extracts tags and dependencies from component frontmatter. This is the recommended way to add metadata.

Supported Formats

Multi-line arrays (recommended for readability):

---
description: Your component description
tags:
  - tag1
  - tag2
  - tag3
dependencies:
  - subagent:coder-agent
  - context:core/standards/code
  - command:context
---

Inline arrays (compact format):

---
description: Your component description
tags: [tag1, tag2, tag3]
dependencies: [subagent:coder-agent, context:core/standards/code]
---

Component-Specific Examples

Command (.opencode/command/your-command.md):

---
description: Brief description of what this command does
tags:
  - category
  - feature
  - use-case
dependencies:
  - subagent:context-organizer
  - subagent:contextscout
---

Subagent (.opencode/agent/subagents/category/your-agent.md):

---
id: your-agent
name: Your Agent Name
description: What this agent does
category: specialist
type: specialist
tags:
  - domain
  - capability
dependencies:
  - subagent:coder-agent
  - context:core/standards/code
---

Context (.opencode/context/category/your-context.md):

---
description: What knowledge this context provides
tags:
  - domain
  - topic
dependencies:
  - context:core/standards/code
---

Dependency Format

Dependencies use the format: type:id

Valid types:

subagent: - References a subagent (e.g., subagent:coder-agent)
command: - References a command (e.g., command:context)
context: - References a context file (e.g., context:core/standards/code)
agent: - References a main agent (e.g., agent:openagent)

Examples:

dependencies:
  - subagent:coder-agent          # Depends on coder-agent subagent
  - context:core/standards/code   # Requires code standards context
  - command:context               # Uses context command

How It Works

Create component with frontmatter (tags + dependencies)
Run auto-detect: ./scripts/registry/auto-detect-components.sh --dry-run
Verify extraction: Check that tags/dependencies appear in output
Apply changes: ./scripts/registry/auto-detect-components.sh --auto-add
Validate: ./scripts/registry/validate-registry.sh

The script automatically:

✅ Extracts description, tags, dependencies from frontmatter
✅ Handles both inline and multi-line array formats
✅ Converts to proper JSON arrays in registry
✅ Validates dependency references exist

Manual Updates (Not Recommended)

Only edit registry.json manually if auto-detect doesn't work.

Prefer frontmatter: Add tags/dependencies to component frontmatter instead of editing registry directly.

Adding Component Manually

{
  "id": "agent-name",
  "name": "Agent Name",
  "type": "agent",
  "path": ".opencode/agent/category/agent-name.md",
  "description": "Brief description",
  "category": "category",
  "tags": ["tag1", "tag2"],
  "dependencies": [],
  "version": "0.5.0"
}

Validate After Manual Edit

./scripts/registry/validate-registry.sh

Validation

What Gets Validated

✅ Schema - Correct JSON structure
✅ Paths - All paths exist
✅ IDs - Unique IDs
✅ Categories - Valid categories
✅ Dependencies - Dependencies exist

Validation Errors

# Example errors
ERROR: Path does not exist: .opencode/agent/core/missing.md
ERROR: Duplicate ID: frontend-specialist
ERROR: Invalid category: invalid-category
ERROR: Missing dependency: subagent:nonexistent

Fixing Errors

Path not found: Fix path or remove entry
Duplicate ID: Rename one component
Invalid category: Use valid category
Missing dependency: Add dependency or remove reference

Testing Registry Changes

Test Locally

# Test with local registry
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list

# Try installing a component
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --component agent:your-agent

Verify Component Appears

# List all agents
cat registry.json | jq '.components.agents[].id'

# Check specific component
cat registry.json | jq '.components.agents[] | select(.id == "your-agent")'

Common Tasks

Add New Component to Registry

# 1. Create component file with frontmatter (including tags/dependencies)
# 2. Run auto-detect
./scripts/registry/auto-detect-components.sh --auto-add

# 3. Validate
./scripts/registry/validate-registry.sh

Example: Adding a new command with tags/dependencies:

# 1. Create .opencode/command/my-command.md with frontmatter:
cat > .opencode/command/my-command.md << 'EOF'
---
description: My custom command description
tags: [automation, workflow]
dependencies: [subagent:coder-agent]
---

# My Command
...
EOF

# 2. Auto-detect extracts metadata
./scripts/registry/auto-detect-components.sh --dry-run

# 3. Apply changes
./scripts/registry/auto-detect-components.sh --auto-add

# 4. Validate
./scripts/registry/validate-registry.sh

Update Component Metadata

# 1. Update frontmatter in component file (tags, dependencies, description)
# 2. Run auto-detect
./scripts/registry/auto-detect-components.sh --auto-add

# 3. Validate
./scripts/registry/validate-registry.sh

Example: Adding tags to existing component:

# 1. Edit .opencode/command/existing-command.md frontmatter:
# Add or update:
#   tags: [new-tag, another-tag]
#   dependencies: [subagent:new-dependency]

# 2. Auto-detect picks up changes
./scripts/registry/auto-detect-components.sh --dry-run

# 3. Apply
./scripts/registry/auto-detect-components.sh --auto-add

Remove Component

# 1. Delete component file
# 2. Run auto-detect (will remove from registry)
./scripts/registry/auto-detect-components.sh --auto-add

# 3. Validate
./scripts/registry/validate-registry.sh

CI/CD Integration

Automatic Validation

Registry is validated on:

Pull requests (.github/workflows/validate-registry.yml)
Merges to main
Release tags

Auto-Update on Merge

Registry can be auto-updated after merge:

# .github/workflows/update-registry.yml
- name: Update Registry
  run: ./scripts/registry/auto-detect-components.sh --auto-add

Best Practices

✅ Use frontmatter - Add tags/dependencies to component files, not registry
✅ Use auto-detect - Don't manually edit registry
✅ Validate often - Catch issues early
✅ Test locally - Use local registry for testing
✅ Dry run first - See changes before applying
✅ Version consistency - Keep versions in sync
✅ Multi-line arrays - More readable than inline format
✅ Meaningful tags - Use descriptive, searchable tags
✅ Declare dependencies - Helps with component discovery and validation

Registry concepts: core-concepts/registry.md
Adding agents: guides/adding-agent.md
Debugging: guides/debugging.md

Troubleshooting

Tags/Dependencies Not Extracted

Problem: Auto-detect doesn't extract tags or dependencies from frontmatter.

Solutions:

Check frontmatter format:
- Must be at top of file
- Must start/end with ---
- Must use valid YAML syntax

Verify array format:

# ✅ Valid formats
tags: [tag1, tag2]
tags:
  - tag1
  - tag2

# ❌ Invalid
tags: tag1, tag2  # Missing brackets

Check dependency format:

# ✅ Valid
dependencies: [subagent:coder-agent, context:core/standards/code]

# ❌ Invalid
dependencies: [coder-agent]  # Missing type prefix

Run dry-run to debug:

./scripts/registry/auto-detect-components.sh --dry-run
# Check output shows extracted tags/dependencies

Dependency Validation Errors

Problem: Validation fails with "Missing dependency" error.

Solution: Ensure referenced component exists in registry:

# Check if dependency exists
jq '.components.subagents[] | select(.id == "coder-agent")' registry.json

# If missing, add the dependency component first

Context Not Found (Aliases)

Problem: Error Could not find path for context:old-name even though file exists.

Cause: The context file might have been renamed or the ID in registry doesn't match the requested name.

Solution: Add an alias to the component in registry.json.

Find the component in registry.json
Add "aliases": ["old-name", "alternative-name"]
Validate registry

Managing Aliases

Aliases allow components to be referenced by multiple names. This is useful for:

Backward compatibility (renamed files)
Shorthand references
Alternative naming conventions

Adding Aliases

Currently, aliases must be added manually to registry.json (auto-detect does not yet support them).

{
  "id": "session-management",
  "name": "Session Management",
  "type": "context",
  "path": ".opencode/context/core/workflows/session-management.md",
  "aliases": [
    "workflows-sessions",
    "sessions"
  ],
  ...
}

Note: Always validate the registry after manual edits:

./scripts/registry/validate-registry.sh

Last Updated: 2025-01-06
Version: 2.0.0

10 KiB Raw Blame History