Validate Repository

Comprehensive validation command that checks the entire OpenAgents Control repository for consistency between CLI, documentation, registry, and components.

Usage

/validate-repo

What It Checks

This command performs a comprehensive validation of:

Registry Integrity
- JSON syntax validation
- Component definitions completeness
- File path references
- Dependency declarations
Component Existence
- All agents exist at specified paths
- All subagents exist at specified paths
- All commands exist at specified paths
- All tools exist at specified paths
- All plugins exist at specified paths
- All context files exist at specified paths
- All config files exist at specified paths
Profile Consistency
- Component counts match documentation
- Profile descriptions are accurate
- Dependencies are satisfied
- No duplicate components
Documentation Accuracy
- README component counts match registry
- OpenAgent documentation references are valid
- Context file references are correct
- Installation guide is up to date
Context File Structure
- All referenced context files exist
- Context file organization is correct
- No orphaned context files
Cross-References
- Agent dependencies exist
- Subagent references are valid
- Command references are valid
- Tool dependencies are satisfied

Output

The command generates a detailed report showing:

✅ What's correct and validated
⚠️ Warnings for potential issues
❌ Errors that need fixing
📊 Summary statistics

Instructions

You are a validation specialist. Your task is to comprehensively validate the OpenAgents Control repository for consistency and correctness.

Step 1: Validate Registry JSON

Read and parse registry.json
Validate JSON syntax
Check schema structure:
- version field exists
- repository field exists
- categories object exists
- components object exists with all types
- profiles object exists
- metadata object exists

Step 2: Validate Component Definitions

For each component type (agents, subagents, commands, tools, plugins, contexts, config):

Check required fields:
- id (unique)
- name
- type
- path
- description
- tags (array)
- dependencies (array)
- category
Verify file exists at path
Check for duplicate IDs
Validate category is in defined categories

Step 3: Validate Profiles

For each profile (essential, developer, business, full, advanced):

Count components in profile
Verify all component references exist in components section
Check dependencies are satisfied
Validate no duplicate components

Step 4: Cross-Reference with Documentation

navigation.md:
- Extract component counts from profile descriptions
- Compare with actual registry counts
- Check profile descriptions match registry descriptions
docs/agents/openagent.md:
- Verify delegation criteria mentioned
- Check context file references
- Validate workflow descriptions
docs/getting-started/installation.md:
- Check profile descriptions
- Verify installation commands

Step 5: Validate Context File Structure

List all files in .opencode/context/
Check against registry context entries
Identify orphaned files (exist but not in registry)
Identify missing files (in registry but don't exist)
Validate structure:
- core/standards/ files
- core/workflows/ files
- core/system/ files
- project/ files

Step 6: Validate Dependencies

For each component with dependencies:

Parse dependency string (format: type:id)
Verify referenced component exists
Check for circular dependencies
Validate dependency chain completeness

Step 7: Generate Report

Create a comprehensive report with sections:

✅ Validated Successfully

Registry JSON syntax
Component file existence
Profile integrity
Documentation accuracy
Context file structure
Dependency chains

⚠️ Warnings

Orphaned files (exist but not referenced)
Unused components (defined but not in any profile)
Missing descriptions or tags
Outdated metadata dates

❌ Errors

Missing files
Broken dependencies
Invalid JSON
Component count mismatches
Broken documentation references
Duplicate component IDs

📊 Statistics

Total components: X
Total profiles: X
Total context files: X
Components per profile breakdown
File coverage percentage

Step 8: Provide Recommendations

Based on findings, suggest:

Files to create
Registry entries to add/remove
Documentation to update
Dependencies to fix

Example Report Format

# OpenAgents Control Repository Validation Report

Generated: 2025-11-19 14:30:00

## Summary

✅ 95% validation passed
⚠️ 3 warnings found
❌ 2 errors found

---

## ✅ Validated Successfully

### Registry Integrity
✅ JSON syntax valid
✅ All required fields present
✅ Schema structure correct

### Component Existence (45/47 files found)
✅ Agents: 3/3 files exist
✅ Subagents: 15/15 files exist
✅ Commands: 8/8 files exist
✅ Tools: 2/2 files exist
✅ Plugins: 2/2 files exist
✅ Contexts: 13/15 files exist
✅ Config: 2/2 files exist

### Profile Consistency
✅ Essential: 9 components (matches README)
✅ Developer: 29 components (matches README)
✅ Business: 15 components (matches README)
✅ Full: 35 components (matches README)
✅ Advanced: 42 components (matches README)

### Documentation Accuracy
✅ README component counts match registry
✅ OpenAgent documentation up to date
✅ Installation guide accurate

---

## ⚠️ Warnings (3)

1. **Orphaned Context File**
   - File: `.opencode/context/legacy/old-patterns.md`
   - Issue: Exists but not referenced in registry
   - Recommendation: Add to registry or remove file

2. **Unused Component**
   - Component: `workflow-orchestrator` (agent)
   - Issue: Defined in registry but not in any profile
   - Recommendation: Add to a profile or mark as deprecated

3. **Outdated Metadata**
   - Field: `metadata.lastUpdated`
   - Current: 2025-11-15
   - Recommendation: Update to current date

---

## ❌ Errors (2)

1. **Missing Context File**
   - Component: `context:advanced-patterns`
   - Expected path: `.opencode/context/core/advanced-patterns.md`
   - Referenced in: developer, full, advanced profiles
   - Action: Create file or remove from registry

2. **Broken Dependency**
   - Component: `agent:opencoder`
   - Dependency: `subagent:pattern-matcher`
   - Issue: Dependency not found in registry
   - Action: Add missing subagent or fix dependency reference

---

## 📊 Statistics

### Component Distribution
- Agents: 3
- Subagents: 15
- Commands: 8
- Tools: 2
- Plugins: 2
- Contexts: 15
- Config: 2
- **Total: 47 components**

### Profile Breakdown
- Essential: 9 components (19%)
- Developer: 29 components (62%)
- Business: 15 components (32%)
- Full: 35 components (74%)
- Advanced: 42 components (89%)

### File Coverage
- Total files defined: 47
- Files found: 45 (96%)
- Files missing: 2 (4%)
- Orphaned files: 1

### Dependency Health
- Total dependencies: 23
- Valid dependencies: 22 (96%)
- Broken dependencies: 1 (4%)
- Circular dependencies: 0

---

## 🔧 Recommended Actions

### High Priority (Errors)
1. Create missing file: `.opencode/context/core/advanced-patterns.md`
2. Fix broken dependency in `opencoder`

### Medium Priority (Warnings)
1. Remove orphaned file or add to registry
2. Add `workflow-orchestrator` to a profile or deprecate
3. Update metadata.lastUpdated to 2025-11-19

### Low Priority (Improvements)
1. Add more tags to components for better searchability
2. Consider adding descriptions to all context files
3. Document component categories in README

---

## Next Steps

1. Review and fix all ❌ errors
2. Address ⚠️ warnings as needed
3. Re-run validation to confirm fixes
4. Update documentation if needed

---

**Validation Complete** ✓

Implementation Notes

The command should:

Use bash/python for file system operations
Parse JSON with proper error handling
Generate markdown report
Be non-destructive (read-only validation)
Provide actionable recommendations
Support verbose mode for detailed output

Error Handling

Gracefully handle missing files
Continue validation even if errors found
Collect all issues before reporting
Provide clear error messages with context

Performance

Should complete in < 30 seconds
Cache file reads where possible
Parallel validation where safe
Progress indicators for long operations

validate-repo.md 8.5 KB History Raw