utun2/.opencode/context/openagents-repo/quality/registry-dependencies.md

description	tags	dependencies
Maintain registry quality through dependency validation and consistency checks	[registry quality validation dependencies]	[]

Registry Dependency Validation

Purpose: Maintain registry quality through dependency validation and consistency checks
Audience: Contributors, maintainers, CI/CD processes

---

Quick Reference

Golden Rule: All component dependencies must be declared in frontmatter and validated before commits.

Critical Commands:

# Check context file dependencies
/check-context-deps

# Auto-fix missing dependencies
/check-context-deps --fix

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

# Update registry after changes
./scripts/registry/auto-detect-components.sh --auto-add

---

Dependency System

Dependency Types

Components can depend on other components using the type:id format:

Type	Format	Example	Description
agent	agent:id	agent:opencoder	Core agent profile
subagent	subagent:id	subagent:coder-agent	Delegatable subagent
command	command:id	command:context	Slash command
tool	tool:id	tool:gemini	External tool integration
plugin	plugin:id	plugin:context	Plugin component
context	context:path	context:core/standards/code	Context file
config	config:id	config:defaults	Configuration file

Declaring Dependencies

In component frontmatter (example):

id: opencoder
name: OpenCoder
description: Multi-language implementation agent
dependencies:
  - subagent:task-manager      # Can delegate to task-manager
  - subagent:coder-agent        # Can delegate to coder-agent
  - subagent:tester             # Can delegate to tester
  - context:core/standards/code # Requires code standards context

Why declare dependencies?

• ✅ Validation: Catch missing components before runtime
• ✅ Documentation: Clear visibility of what each component needs
• ✅ Installation: Installers can fetch all required dependencies
• ✅ Dependency graphs: Visualize component relationships
• ✅ Breaking change detection: Know what's affected by changes

---

Context File Dependencies

The Problem

Agents reference context files in their prompts but often don't declare them as dependencies:

<!-- In agent prompt -->
BEFORE any code implementation, ALWAYS load:
- Code tasks → .opencode/context/core/standards/code-quality.md (MANDATORY)

Without dependency declaration:

• ❌ No validation that context file exists
• ❌ Can't track which agents use which context files
• ❌ Breaking changes when context files are moved/deleted
• ❌ Installers don't know to fetch context files

The Solution

Declare context dependencies in frontmatter (example):

id: opencoder
dependencies:
  - context:core/standards/code  # ← ADD THIS

Use /check-context-deps to find missing declarations:

# Analyze all agents
/check-context-deps

# Auto-fix missing context dependencies
/check-context-deps --fix

Context Dependency Format

Path normalization:

File path:     .opencode/context/core/standards/code-quality.md
Dependency:    context:core/standards/code
               ^^^^^^^ ^^^^^^^^^^^^^^^^^^^
               type    path (no .opencode/, no .md)

Examples:

dependencies:
  - context:core/standards/code           # .opencode/context/core/standards/code-quality.md
  - context:core/standards/docs           # .opencode/context/core/standards/documentation.md
  - context:core/workflows/delegation     # .opencode/context/core/workflows/task-delegation-basics.md
  - context:openagents-repo/guides/adding-agent  # Project-specific context

---

Validation Workflow

Pre-Commit Checklist

Before committing changes to agents, commands, or context files:

1. Check context dependencies:

   /check-context-deps
   

   • Identifies agents using context files without declaring them
   • Reports unused context files
   • Validates context file paths

2. Fix missing dependencies (if needed):

   /check-context-deps --fix
   

   • Automatically adds missing context: dependencies to frontmatter
   • Preserves existing dependencies

3. Update registry:

   ./scripts/registry/auto-detect-components.sh --auto-add
   

   • Extracts dependencies from frontmatter
   • Updates registry.json

4. Validate registry:

   ./scripts/registry/validate-registry.sh
   

   • Checks all dependencies exist
   • Validates component paths
   • Reports missing dependencies

Validation Tools

1. /check-context-deps Command

Purpose: Analyze context file usage and validate dependencies

What it checks:

• ✅ Agents referencing context files in prompts
• ✅ Context dependencies declared in frontmatter
• ✅ Context files exist on disk
• ✅ Context files in registry
• ✅ Unused context files

Usage:

# Full analysis
/check-context-deps

# Specific agent
/check-context-deps opencoder

# Auto-fix
/check-context-deps --fix

# Verbose (show line numbers)
/check-context-deps --verbose

Example output:

# Context Dependency Analysis Report

## Summary
- Agents scanned: 25
- Context files referenced: 12
- Missing dependencies: 8
- Unused context files: 2

## Missing Dependencies

### opencoder
Uses but not declared:
- context:core/standards/code (referenced 3 times)
  - Line 64: "Code tasks → .opencode/context/core/standards/code-quality.md"
  
Recommended fix:
dependencies:
  - context:core/standards/code

2. auto-detect-components.sh Script

Purpose: Scan for new components and update registry

Dependency validation:

• Checks dependencies during component scanning
• Logs warnings for missing dependencies
• Non-blocking (warnings only)

Usage:

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

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

Example warning:

⚠ New command: Demo (demo)
  Dependencies: subagent:coder-agent,subagent:missing-agent
    ⚠ Dependency not found in registry: subagent:missing-agent

3. validate-registry.sh Script

Purpose: Comprehensive registry validation

Checks:

• ✅ All component paths exist
• ✅ All dependencies exist in registry
• ✅ No duplicate IDs
• ✅ Valid JSON structure
• ✅ Required fields present

Usage:

./scripts/registry/validate-registry.sh

Example output:

Validating registry.json...

✗ Dependency not found: opencoder → context:core/standards/code

Missing dependencies: 1
  - opencoder (agent) → context:core/standards/code

Fix: Add missing component to registry or remove from dependencies

---

Quality Standards

Well-Maintained Registry

A high-quality registry has:

✅ Complete dependencies: All component dependencies declared ✅ Validated dependencies: All dependencies exist in registry ✅ No orphans: All context files used by at least one component ✅ Consistent format: Dependencies use type:id format ✅ Up-to-date: Registry reflects current component state ✅ No broken paths: All component paths valid

Dependency Declaration Standards

DO:

• ✅ Declare all subagents you delegate to
• ✅ Declare all context files you reference
• ✅ Declare all commands you invoke
• ✅ Use correct format: type:id
• ✅ Keep dependencies in frontmatter (not hardcoded in prompts)

DON'T:

• ❌ Reference context files without declaring dependency
• ❌ Use invalid dependency formats
• ❌ Declare dependencies you don't actually use
• ❌ Forget to update registry after adding dependencies

---

Commit Guidelines

When Adding/Modifying Components

1. Add component with proper frontmatter (example):

id: my-agent
name: My Agent
description: Does something useful
tags:
  - development
  - coding
dependencies:
  - subagent:coder-agent
  - context:core/standards/code

2. Validate dependencies:

/check-context-deps my-agent

3. Update registry:

./scripts/registry/auto-detect-components.sh --auto-add

4. Validate registry:

./scripts/registry/validate-registry.sh

5. Commit with descriptive message:

git add .opencode/agent/my-agent.md registry.json
git commit -m "Add my-agent with coder-agent and code standards dependencies"

When Modifying Context Files

1. Check which agents depend on it:

jq '.components[] | .[] | select(.dependencies[]? | contains("context:core/standards/code")) | {id, name}' registry.json

2. Update context file:

# Make your changes
vim .opencode/context/core/standards/code-quality.md

3. Validate no broken references:

/check-context-deps --verbose

4. Update registry if needed:

./scripts/registry/auto-detect-components.sh --auto-add

5. Commit with impact note:

git commit -m "Update code standards - affects opencoder, openagent, reviewer"

When Deleting Components

1. Check dependencies first:

# Find what depends on this component
jq '.components[] | .[] | select(.dependencies[]? == "subagent:old-agent") | {id, name}' registry.json

2. Remove from dependents:

# Update agents that depend on it
# Remove the dependency from their frontmatter

3. Delete component:

rm .opencode/agent/subagents/old-agent.md

4. Update registry:

./scripts/registry/auto-detect-components.sh --auto-add

5. Validate:

./scripts/registry/validate-registry.sh

---

Troubleshooting

Missing Context Dependencies

Symptom:

/check-context-deps reports:
  opencoder: missing context:core/standards/code

Fix:

# Option 1: Auto-fix
/check-context-deps --fix

# Option 2: Manual fix
# Edit .opencode/agent/core/opencoder.md
# Add to frontmatter:
dependencies:
  - context:core/standards/code

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

Dependency Not Found in Registry

Symptom:

⚠ Dependency not found in registry: context:core/standards/code

Causes:

1. Context file doesn't exist
2. Context file exists but not in registry
3. Wrong dependency format

Fix:

# Check if file exists
ls -la .opencode/context/core/standards/code-quality.md

# If exists, add to registry
./scripts/registry/auto-detect-components.sh --auto-add

# If doesn't exist, remove dependency or create file

Unused Context Files

Symptom:

/check-context-deps reports:
  Unused: context:core/standards/analysis (0 references)

Fix:

# Option 1: Add to an agent that should use it
# Edit agent frontmatter to add dependency

# Option 2: Remove if truly unused
rm .opencode/context/core/standards/code-analysis.md
./scripts/registry/auto-detect-components.sh --auto-add

Circular Dependencies

Symptom:

Agent A depends on Agent B
Agent B depends on Agent A

Fix:

• Refactor to remove circular dependency
• Extract shared logic to a third component
• Use dependency injection instead

---

CI/CD Integration

Pre-Commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Validating registry dependencies..."

# Check context dependencies
/check-context-deps || {
  echo "❌ Context dependency validation failed"
  echo "Run: /check-context-deps --fix"
  exit 1
}

# Validate registry
./scripts/registry/validate-registry.sh || {
  echo "❌ Registry validation failed"
  exit 1
}

echo "✅ Registry validation passed"

GitHub Actions

name: Validate Registry

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Validate registry
        run: ./scripts/registry/validate-registry.sh
      
      - name: Check context dependencies
        run: /check-context-deps

---

Best Practices

For Component Authors

1. Always declare dependencies in frontmatter
2. Use /check-context-deps before committing
3. Update registry after adding components
4. Validate before pushing
5. Document why dependencies are needed

For Maintainers

1. Review dependencies in PRs
2. Run validation in CI/CD
3. Keep context files organized and documented
4. Monitor unused context files
5. Refactor when dependency graphs get complex

For CI/CD

1. Fail builds on validation errors
2. Report missing dependencies
3. Track dependency changes over time
4. Alert on circular dependencies
5. Enforce dependency declaration standards

---

Related Documentation

• Registry Guide: .opencode/context/openagents-repo/guides/updating-registry.md
• Registry Concepts: .opencode/context/openagents-repo/core-concepts/registry.md
• Adding Agents: .opencode/context/openagents-repo/guides/adding-agent.md
• Command Reference: /check-context-deps command

---

Summary

Key Takeaways:

1. Declare all dependencies in frontmatter (subagents, context files, etc.)
2. Use /check-context-deps to find missing context dependencies
3. Validate registry before commits
4. Keep registry in sync with component changes
5. Follow dependency format: type:id

Quality Checklist:

• All context files referenced have dependencies declared
• All dependencies exist in registry
• No unused context files (or documented why)
• Registry validates without errors
• Dependency format is consistent

Remember: Dependencies are documentation. They help users understand what components need and help the system validate integrity.