434 lines
12 KiB
Markdown
434 lines
12 KiB
Markdown
---
|
|
description: Validate context file dependencies across agents and registry
|
|
tags:
|
|
- registry
|
|
- validation
|
|
- context
|
|
- dependencies
|
|
- openagents
|
|
dependencies:
|
|
- command:analyze-patterns
|
|
---
|
|
|
|
# Check Context Dependencies
|
|
|
|
**Purpose**: Ensure agents properly declare their context file dependencies in frontmatter and registry.
|
|
|
|
**Arguments**: `$ARGUMENTS`
|
|
|
|
---
|
|
|
|
## What It Does
|
|
|
|
Validates consistency between:
|
|
1. **Actual usage** - Context files referenced in agent prompts
|
|
2. **Declared dependencies** - Dependencies in agent frontmatter
|
|
3. **Registry entries** - Dependencies in registry.json
|
|
|
|
**Identifies**:
|
|
- ✅ Missing dependency declarations (agents use context but don't declare it)
|
|
- ✅ Unused context files (exist but no agent references them)
|
|
- ✅ Broken references (referenced but don't exist)
|
|
- ✅ Format inconsistencies (wrong dependency format)
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Analyze all agents
|
|
/check-context-deps
|
|
|
|
# Analyze specific agent
|
|
/check-context-deps contextscout
|
|
|
|
# Auto-fix missing dependencies
|
|
/check-context-deps --fix
|
|
|
|
# Verbose output (show all reference locations)
|
|
/check-context-deps --verbose
|
|
|
|
# Combine flags
|
|
/check-context-deps contextscout --verbose
|
|
```
|
|
|
|
---
|
|
|
|
## Workflow
|
|
|
|
<workflow id="analyze_context_dependencies">
|
|
<stage id="1" name="ScanAgents" required="true">
|
|
Scan agent files for context references:
|
|
|
|
**Search patterns**:
|
|
- `.opencode/context/` (direct path references)
|
|
- `@.opencode/context/` (@ symbol references)
|
|
- `context:` (dependency declarations in frontmatter)
|
|
|
|
**Locations**:
|
|
- `.opencode/agent/**/*.md` (all agents and subagents)
|
|
- `.opencode/command/**/*.md` (commands that use context)
|
|
|
|
**Extract**:
|
|
- Agent/command ID
|
|
- Context file path
|
|
- Line number
|
|
- Reference type (path, @-reference, dependency)
|
|
</stage>
|
|
|
|
<stage id="2" name="CheckRegistry" required="true">
|
|
For each agent found, check registry.json:
|
|
|
|
```bash
|
|
jq '.components.agents[] | select(.id == "AGENT_ID") | .dependencies' registry.json
|
|
jq '.components.subagents[] | select(.id == "AGENT_ID") | .dependencies' registry.json
|
|
```
|
|
|
|
**Verify**:
|
|
- Does the agent have a dependencies array?
|
|
- Are context file references declared as `context:core/standards/code`?
|
|
- Are the dependency formats correct (`context:path/to/file`)?
|
|
</stage>
|
|
|
|
<stage id="3" name="ValidateContextFiles" required="true">
|
|
For each context file referenced:
|
|
|
|
**Check existence**:
|
|
```bash
|
|
test -f .opencode/context/core/standards/code-quality.md
|
|
```
|
|
|
|
**Check registry**:
|
|
```bash
|
|
jq '.components.contexts[] | select(.id == "core/standards/code")' registry.json
|
|
```
|
|
|
|
**Identify issues**:
|
|
- Context file referenced but doesn't exist
|
|
- Context file exists but not in registry
|
|
- Context file in registry but never used
|
|
</stage>
|
|
|
|
<stage id="4" name="Report" required="true">
|
|
Generate comprehensive report:
|
|
|
|
```markdown
|
|
# Context Dependency Analysis Report
|
|
|
|
## Summary
|
|
- Agents scanned: 25
|
|
- Context files referenced: 12
|
|
- Missing dependencies: 8
|
|
- Unused context files: 2
|
|
- Missing context files: 0
|
|
|
|
## Missing Dependencies (agents using context but not declaring)
|
|
|
|
### opencoder
|
|
**Uses but not declared**:
|
|
- context:core/standards/code (referenced 3 times)
|
|
- Line 64: "Code tasks → .opencode/context/core/standards/code-quality.md (MANDATORY)"
|
|
- Line 170: "Read .opencode/context/core/standards/code-quality.md NOW"
|
|
- Line 229: "NEVER execute write/edit without loading required context first"
|
|
|
|
**Current dependencies**: subagent:task-manager, subagent:coder-agent
|
|
**Recommended fix**: Add to frontmatter:
|
|
```yaml
|
|
dependencies:
|
|
- subagent:task-manager
|
|
- subagent:coder-agent
|
|
- context:core/standards/code # ADD THIS
|
|
```
|
|
|
|
### openagent
|
|
**Uses but not declared**:
|
|
- context:core/standards/code (referenced 5 times)
|
|
- context:core/standards/docs (referenced 3 times)
|
|
- context:core/standards/tests (referenced 3 times)
|
|
- context:core/workflows/review (referenced 2 times)
|
|
- context:core/workflows/delegation (referenced 4 times)
|
|
|
|
**Recommended fix**: Add to frontmatter:
|
|
```yaml
|
|
dependencies:
|
|
- subagent:task-manager
|
|
- subagent:documentation
|
|
- context:core/standards/code
|
|
- context:core/standards/docs
|
|
- context:core/standards/tests
|
|
- context:core/workflows/review
|
|
- context:core/workflows/delegation
|
|
```
|
|
|
|
## Unused Context Files (exist but no agent references them)
|
|
|
|
- context:core/standards/analysis (0 references)
|
|
- context:core/workflows/sessions (0 references)
|
|
|
|
**Recommendation**: Consider removing or documenting intended use
|
|
|
|
## Missing Context Files (referenced but don't exist)
|
|
|
|
None found ✅
|
|
|
|
## Context File Usage Map
|
|
|
|
| Context File | Used By | Reference Count |
|
|
|--------------|---------|-----------------|
|
|
| core/standards/code | opencoder, openagent, frontend-specialist, reviewer | 15 |
|
|
| core/standards/docs | openagent, documentation, technical-writer | 8 |
|
|
| core/standards/tests | openagent, tester | 6 |
|
|
| core/workflows/delegation | openagent, task-manager | 5 |
|
|
| core/workflows/review | openagent, reviewer | 4 |
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. Review missing dependencies above
|
|
2. Run `/check-context-deps --fix` to auto-update frontmatter
|
|
3. Run `./scripts/registry/auto-detect-components.sh` to update registry
|
|
4. Verify with `./scripts/registry/validate-registry.sh`
|
|
```
|
|
</stage>
|
|
|
|
<stage id="5" name="Fix" when="--fix flag provided">
|
|
For each agent with missing context dependencies:
|
|
|
|
1. Read the agent file
|
|
2. Parse frontmatter YAML
|
|
3. Add missing context dependencies to dependencies array
|
|
4. Preserve existing dependencies
|
|
5. Write updated file
|
|
6. Report what was changed
|
|
|
|
**Example**:
|
|
```diff
|
|
---
|
|
id: opencoder
|
|
dependencies:
|
|
- subagent:task-manager
|
|
- subagent:coder-agent
|
|
+ - context:core/standards/code
|
|
---
|
|
```
|
|
|
|
**Safety**:
|
|
- Only add dependencies that are actually referenced in the file
|
|
- Don't remove existing dependencies
|
|
- Preserve frontmatter formatting
|
|
- Show diff before applying (if interactive)
|
|
</stage>
|
|
</workflow>
|
|
|
|
---
|
|
|
|
## Implementation Details
|
|
|
|
### Search Patterns
|
|
|
|
**Find direct path references**:
|
|
```bash
|
|
grep -rn "\.opencode/context/" .opencode/agent/ .opencode/command/
|
|
```
|
|
|
|
**Find @ references**:
|
|
```bash
|
|
grep -rn "@\.opencode/context/" .opencode/agent/ .opencode/command/
|
|
```
|
|
|
|
**Find dependency declarations**:
|
|
```bash
|
|
grep -rn "^\s*-\s*context:" .opencode/agent/ .opencode/command/
|
|
```
|
|
|
|
### Path Normalization
|
|
|
|
**Convert to dependency format**:
|
|
- `.opencode/context/core/standards/code-quality.md` → `context:core/standards/code`
|
|
- `@.opencode/context/openagents-repo/quick-start.md` → `context:openagents-repo/quick-start`
|
|
- `context/core/standards/code` → `context:core/standards/code`
|
|
|
|
**Rules**:
|
|
1. Strip `.opencode/` prefix
|
|
2. Strip `.md` extension
|
|
3. Add `context:` prefix for dependencies
|
|
|
|
### Registry Lookup
|
|
|
|
**Check if context file is in registry**:
|
|
```bash
|
|
jq '.components.contexts[] | select(.id == "core/standards/code")' registry.json
|
|
```
|
|
|
|
**Get agent dependencies**:
|
|
```bash
|
|
jq '.components.agents[] | select(.id == "opencoder") | .dependencies[]?' registry.json
|
|
```
|
|
|
|
---
|
|
|
|
## Delegation
|
|
|
|
This command delegates to an analysis agent to perform the work:
|
|
|
|
```javascript
|
|
task(
|
|
subagent_type="PatternAnalyst",
|
|
description="Analyze context dependencies",
|
|
prompt=`
|
|
Analyze context file usage across all agents in this repository.
|
|
|
|
TASK:
|
|
1. Use grep to find all references to context files in:
|
|
- .opencode/agent/**/*.md
|
|
- .opencode/command/**/*.md
|
|
|
|
2. Search for these patterns:
|
|
- ".opencode/context/core/" (direct paths)
|
|
- "@.opencode/context/" (@ references)
|
|
- "context:" in frontmatter (dependency declarations)
|
|
|
|
3. For each agent file found:
|
|
- Extract agent ID from frontmatter
|
|
- List all context files it references
|
|
- Check registry.json for declared dependencies
|
|
- Identify missing dependency declarations
|
|
|
|
4. For each context file in .opencode/context/core/:
|
|
- Count how many agents reference it
|
|
- Check if it exists in registry.json
|
|
- Identify unused context files
|
|
|
|
5. Generate a comprehensive report showing:
|
|
- Agents with missing context dependencies
|
|
- Unused context files
|
|
- Missing context files (referenced but don't exist)
|
|
- Context file usage map (which agents use which files)
|
|
|
|
${ARGUMENTS.includes('--fix') ? `
|
|
6. AUTO-FIX MODE:
|
|
- Update agent frontmatter to add missing context dependencies
|
|
- Use format: context:core/standards/code
|
|
- Preserve existing dependencies
|
|
- Show what was changed
|
|
` : ''}
|
|
|
|
${ARGUMENTS.includes('--verbose') ? `
|
|
VERBOSE MODE: Include all reference locations (file:line) in report
|
|
` : ''}
|
|
|
|
${ARGUMENTS.length > 0 && !ARGUMENTS.includes('--') ? `
|
|
FILTER: Only analyze agent: ${ARGUMENTS[0]}
|
|
` : ''}
|
|
|
|
REPORT FORMAT:
|
|
- Summary statistics
|
|
- Missing dependencies by agent (with recommended fixes)
|
|
- Unused context files
|
|
- Context file usage map
|
|
- Next steps
|
|
|
|
DO NOT make changes without --fix flag.
|
|
ALWAYS show what would be changed before applying fixes.
|
|
`
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
### Example 1: Basic Analysis
|
|
|
|
```bash
|
|
/check-context-deps
|
|
```
|
|
|
|
**Output**:
|
|
```
|
|
Analyzing context file usage across 25 agents...
|
|
|
|
Found 8 agents with missing context dependencies:
|
|
- opencoder: missing context:core/standards/code
|
|
- openagent: missing 5 context dependencies
|
|
- frontend-specialist: missing context:core/standards/code
|
|
...
|
|
|
|
Run /check-context-deps --fix to auto-update frontmatter
|
|
```
|
|
|
|
### Example 2: Analyze Specific Agent
|
|
|
|
```bash
|
|
/check-context-deps contextscout
|
|
```
|
|
|
|
**Output**:
|
|
```
|
|
Analyzing agent: contextscout
|
|
|
|
Context files referenced:
|
|
✓ .opencode/context/core/context-system.md (1 reference)
|
|
- Line 15: "Load: context:core/context-system"
|
|
✓ .opencode/context/core/context-system/standards/mvi.md (2 references)
|
|
- Line 16: "Load: context:core/context-system/standards/mvi"
|
|
- Line 89: "MVI-aware prioritization"
|
|
|
|
Registry dependencies:
|
|
✓ context:core/context-system DECLARED
|
|
✓ context:core/context-system/standards/mvi DECLARED
|
|
|
|
All dependencies properly declared ✅
|
|
```
|
|
|
|
### Example 3: Auto-Fix
|
|
|
|
```bash
|
|
/check-context-deps --fix
|
|
```
|
|
|
|
**Output**:
|
|
```
|
|
Analyzing and fixing context dependencies...
|
|
|
|
Updated opencoder:
|
|
+ Added: context:core/standards/code
|
|
|
|
Updated openagent:
|
|
+ Added: context:core/standards/code
|
|
+ Added: context:core/standards/docs
|
|
+ Added: context:core/standards/tests
|
|
+ Added: context:core/workflows/review
|
|
+ Added: context:core/workflows/delegation
|
|
|
|
Total: 2 agents updated, 6 dependencies added
|
|
|
|
Next: Run ./scripts/registry/auto-detect-components.sh to update registry
|
|
```
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
✅ All agents that reference context files have them declared in dependencies
|
|
✅ All context files in registry are actually used by at least one agent
|
|
✅ No broken references (context files referenced but don't exist)
|
|
✅ Dependency format is consistent (`context:path/to/file`)
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- **Read-only by default** - Only reports findings, doesn't modify files
|
|
- **Use `--fix` to update** - Auto-adds missing dependencies to frontmatter
|
|
- **After fixing** - Run `./scripts/registry/auto-detect-components.sh --auto-add` to sync registry
|
|
- **Dependency format** - `context:path/to/file` (no `.opencode/` prefix, no `.md` extension)
|
|
- **Scans both** - Direct path references and @ references
|
|
|
|
## Related
|
|
|
|
- **Registry validation**: `./scripts/registry/validate-registry.sh`
|
|
- **Auto-detect components**: `./scripts/registry/auto-detect-components.sh`
|
|
- **Context guide**: `.opencode/context/openagents-repo/quality/registry-dependencies.md`
|