chore: install openagent opencode
Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
This commit is contained in:
156
.opencode/context/openagents-repo/guides/adding-agent-basics.md
Normal file
156
.opencode/context/openagents-repo/guides/adding-agent-basics.md
Normal file
@@ -0,0 +1,156 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Adding a New Agent (Basics)
|
||||
|
||||
**Prerequisites**: Load `core-concepts/agents.md` first
|
||||
**Purpose**: Create and register a new agent in 4 steps
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Adding a new agent involves:
|
||||
1. Creating the agent file
|
||||
2. Creating test structure
|
||||
3. Updating the registry
|
||||
4. Validating everything works
|
||||
|
||||
**Time**: ~15-20 minutes
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create Agent File
|
||||
|
||||
### Choose Category
|
||||
|
||||
```bash
|
||||
# Available categories:
|
||||
# - core/ (system agents)
|
||||
# - development/ (dev specialists)
|
||||
# - content/ (content creators)
|
||||
# - data/ (data analysts)
|
||||
# - product/ (product managers)
|
||||
# - learning/ (educators)
|
||||
```
|
||||
|
||||
### Create File with Frontmatter
|
||||
|
||||
```bash
|
||||
touch .opencode/agent/{category}/{agent-name}.md
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "Brief description of what this agent does"
|
||||
category: "{category}"
|
||||
type: "agent"
|
||||
tags: ["tag1", "tag2"]
|
||||
dependencies: []
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
**Purpose**: What this agent does
|
||||
|
||||
## Focus
|
||||
- Key responsibility 1
|
||||
- Key responsibility 2
|
||||
|
||||
## Workflow
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
|
||||
## Constraints
|
||||
- Constraint 1
|
||||
- Constraint 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create Test Structure
|
||||
|
||||
```bash
|
||||
# Create directories
|
||||
mkdir -p evals/agents/{category}/{agent-name}/{config,tests}
|
||||
|
||||
# Create config
|
||||
cat > evals/agents/{category}/{agent-name}/config/config.yaml << 'EOF'
|
||||
agent: {category}/{agent-name}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
timeout: 60000
|
||||
suites:
|
||||
- smoke
|
||||
EOF
|
||||
|
||||
# Create smoke test
|
||||
cat > evals/agents/{category}/{agent-name}/tests/smoke-test.yaml << 'EOF'
|
||||
name: Smoke Test
|
||||
description: Basic functionality check
|
||||
agent: {category}/{agent-name}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Hello, can you help me?"
|
||||
expectations:
|
||||
- type: no_violations
|
||||
EOF
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Update Registry
|
||||
|
||||
```bash
|
||||
# Dry run first
|
||||
./scripts/registry/auto-detect-components.sh --dry-run
|
||||
|
||||
# Add to registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# Verify
|
||||
cat registry.json | jq '.components.agents[] | select(.id == "{agent-name}")'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Validate
|
||||
|
||||
```bash
|
||||
# Validate registry
|
||||
./scripts/registry/validate-registry.sh
|
||||
|
||||
# Run smoke test
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent-name} --pattern="smoke-test.yaml"
|
||||
|
||||
# Test installation
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Agent file created with proper frontmatter
|
||||
- [ ] Test structure created (config + smoke test)
|
||||
- [ ] Registry updated via auto-detect
|
||||
- [ ] Registry validation passes
|
||||
- [ ] Smoke test passes
|
||||
- [ ] Agent appears in `./install.sh --list`
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **Add more tests** → `adding-agent-testing.md`
|
||||
- **Test thoroughly** → `testing-agent.md`
|
||||
- **Debug issues** → `debugging.md`
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `core-concepts/agents.md` - Agent concepts
|
||||
- `adding-agent-testing.md` - Additional test patterns
|
||||
- `testing-agent.md` - Testing guide
|
||||
- `creating-subagents.md` - Claude Code subagents (different system)
|
||||
145
.opencode/context/openagents-repo/guides/adding-agent-testing.md
Normal file
145
.opencode/context/openagents-repo/guides/adding-agent-testing.md
Normal file
@@ -0,0 +1,145 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Adding Agent Tests
|
||||
|
||||
**Prerequisites**: Load `adding-agent-basics.md` first
|
||||
**Purpose**: Additional test patterns for agents
|
||||
|
||||
---
|
||||
|
||||
## Additional Test Types
|
||||
|
||||
### Approval Gate Test
|
||||
|
||||
```yaml
|
||||
# evals/agents/{category}/{agent-name}/tests/approval-gate.yaml
|
||||
name: Approval Gate Test
|
||||
description: Verify agent requests approval before execution
|
||||
agent: {category}/{agent-name}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Create a new file called test.js"
|
||||
expectations:
|
||||
- type: specific_evaluator
|
||||
evaluator: approval_gate
|
||||
should_pass: true
|
||||
```
|
||||
|
||||
### Context Loading Test
|
||||
|
||||
```yaml
|
||||
# evals/agents/{category}/{agent-name}/tests/context-loading.yaml
|
||||
name: Context Loading Test
|
||||
description: Verify agent loads required context
|
||||
agent: {category}/{agent-name}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Write a new function"
|
||||
expectations:
|
||||
- type: context_loaded
|
||||
contexts: ["core/standards/code-quality.md"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Example: API Specialist
|
||||
|
||||
```bash
|
||||
# 1. Create agent file
|
||||
cat > .opencode/agent/subagents/development/api-specialist.md << 'EOF'
|
||||
---
|
||||
description: "Expert in REST and GraphQL API design"
|
||||
category: "development"
|
||||
type: "agent"
|
||||
tags: ["api", "rest", "graphql"]
|
||||
dependencies: ["subagent:tester"]
|
||||
---
|
||||
|
||||
# API Specialist
|
||||
|
||||
**Purpose**: Design and implement robust APIs
|
||||
|
||||
## Focus
|
||||
- REST API design
|
||||
- GraphQL schemas
|
||||
- API documentation
|
||||
- Authentication/authorization
|
||||
|
||||
## Workflow
|
||||
1. Analyze requirements
|
||||
2. Design API structure
|
||||
3. Implement endpoints
|
||||
4. Add tests
|
||||
5. Document API
|
||||
|
||||
## Constraints
|
||||
- Follow REST best practices
|
||||
- Use proper HTTP methods
|
||||
- Include error handling
|
||||
- Add comprehensive tests
|
||||
EOF
|
||||
|
||||
# 2. Create test structure
|
||||
mkdir -p evals/agents/development/api-specialist/{config,tests}
|
||||
|
||||
cat > evals/agents/development/api-specialist/config/config.yaml << 'EOF'
|
||||
agent: development/api-specialist
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
timeout: 60000
|
||||
suites:
|
||||
- smoke
|
||||
EOF
|
||||
|
||||
cat > evals/agents/development/api-specialist/tests/smoke-test.yaml << 'EOF'
|
||||
name: Smoke Test
|
||||
description: Basic functionality check
|
||||
agent: development/api-specialist
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Hello, can you help me design an API?"
|
||||
expectations:
|
||||
- type: no_violations
|
||||
EOF
|
||||
|
||||
# 3. Update registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# 4. Validate
|
||||
./scripts/registry/validate-registry.sh
|
||||
cd evals/framework && bun --bun run eval:sdk -- --agent=development/api-specialist --pattern="smoke-test.yaml"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Auto-detect doesn't find agent | Check frontmatter is valid YAML |
|
||||
| Registry validation fails | Verify file path is correct |
|
||||
| Test fails unexpectedly | Load `debugging.md` for troubleshooting |
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Subagent (Optional)
|
||||
|
||||
For Claude Code-only helpers, create a project subagent:
|
||||
|
||||
- **Path**: `.claude/agents/{subagent-name}.md`
|
||||
- **Required**: `name`, `description` frontmatter
|
||||
- **Optional**: `tools`, `disallowedTools`, `permissionMode`, `skills`, `hooks`
|
||||
- **Reload**: restart Claude Code or run `/agents`
|
||||
|
||||
See `creating-subagents.md` for Claude Code subagent details.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `adding-agent-basics.md` - Basic agent creation
|
||||
- `testing-agent.md` - Testing guide
|
||||
- `debugging.md` - Troubleshooting
|
||||
- `creating-subagents.md` - Claude Code subagents
|
||||
149
.opencode/context/openagents-repo/guides/adding-skill-basics.md
Normal file
149
.opencode/context/openagents-repo/guides/adding-skill-basics.md
Normal file
@@ -0,0 +1,149 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Adding an OpenCode Skill (Basics)
|
||||
|
||||
**Prerequisites**: Load `plugins/context/capabilities/events_skills.md` first
|
||||
**Purpose**: Create an OpenCode skill directory and SKILL.md file
|
||||
|
||||
**Note**: This is for **OpenCode skills** (internal system). For **Claude Code Skills**, see `creating-skills.md`.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Adding an OpenCode skill involves:
|
||||
1. Creating skill directory structure
|
||||
2. Creating SKILL.md file
|
||||
3. Creating router script (optional)
|
||||
4. Creating CLI implementation (optional)
|
||||
5. Registering in registry (optional)
|
||||
6. Testing
|
||||
|
||||
**Time**: ~10-15 minutes
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create Skill Directory
|
||||
|
||||
### Choose Skill Name
|
||||
|
||||
- **kebab-case**: `task-management`, `brand-guidelines`
|
||||
- **Descriptive**: Clear indication of what skill provides
|
||||
- **Short**: Max 3-4 words
|
||||
|
||||
### Create Structure
|
||||
|
||||
```bash
|
||||
mkdir -p .opencode/skills/{skill-name}/scripts
|
||||
```
|
||||
|
||||
**Standard structure**:
|
||||
```
|
||||
.opencode/skills/{skill-name}/
|
||||
├── SKILL.md # Required: Main skill documentation
|
||||
├── router.sh # Optional: CLI router script
|
||||
└── scripts/
|
||||
└── skill-cli.ts # Optional: CLI tool implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create SKILL.md
|
||||
|
||||
### Frontmatter
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: {skill-name}
|
||||
description: Brief description of what the skill provides
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
**Purpose**: What this skill helps users do
|
||||
|
||||
## What I do
|
||||
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
- Feature 3
|
||||
|
||||
## How to use me
|
||||
|
||||
### Basic Commands
|
||||
|
||||
```bash
|
||||
bunx --bun ts-node .opencode/skills/{skill-name}/scripts/skill-cli.ts command1
|
||||
```
|
||||
|
||||
### Command Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `command1` | What command1 does |
|
||||
| `command2` | What command2 does |
|
||||
```
|
||||
|
||||
### Claude Code Skills (Optional)
|
||||
|
||||
For Claude Code Skills (`.claude/skills/`), add extra frontmatter:
|
||||
- `allowed-tools` - Tool restrictions
|
||||
- `context` + `agent` - Run in forked subagent
|
||||
- `hooks` - Lifecycle events
|
||||
- `user-invocable` - Hide from slash menu
|
||||
|
||||
See `creating-skills.md` for Claude Code Skills details.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Create Router Script (Optional)
|
||||
|
||||
For CLI-based skills:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
if [ $# -eq 0 ]; then
|
||||
echo "Usage: bash router.sh <command> [options]"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
COMMAND="$1"
|
||||
shift
|
||||
|
||||
case "$COMMAND" in
|
||||
help|--help|-h)
|
||||
echo "{Skill Name} - Description"
|
||||
echo "Commands: command1, command2, help"
|
||||
;;
|
||||
command1|command2)
|
||||
bunx --bun ts-node "$SCRIPT_DIR/scripts/skill-cli.ts" "$COMMAND" "$@"
|
||||
;;
|
||||
*)
|
||||
echo "Unknown command: $COMMAND"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
```bash
|
||||
chmod +x .opencode/skills/{skill-name}/router.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **CLI Implementation** → `adding-skill-implementation.md`
|
||||
- **Complete Example** → `adding-skill-example.md`
|
||||
- **Claude Code Skills** → `creating-skills.md`
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `creating-skills.md` - Claude Code Skills (different system)
|
||||
- `adding-skill-implementation.md` - CLI and registry
|
||||
- `adding-skill-example.md` - Task-management example
|
||||
- `plugins/context/capabilities/events_skills.md` - Skills Plugin
|
||||
169
.opencode/context/openagents-repo/guides/adding-skill-example.md
Normal file
169
.opencode/context/openagents-repo/guides/adding-skill-example.md
Normal file
@@ -0,0 +1,169 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Example: Task-Management Skill
|
||||
|
||||
**Purpose**: Complete example of creating an OpenCode skill
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```bash
|
||||
mkdir -p .opencode/skills/task-management/scripts
|
||||
```
|
||||
|
||||
```
|
||||
.opencode/skills/task-management/
|
||||
├── SKILL.md
|
||||
├── router.sh
|
||||
└── scripts/
|
||||
└── task-cli.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: task-management
|
||||
description: Task management CLI for tracking feature subtasks
|
||||
---
|
||||
|
||||
# Task Management Skill
|
||||
|
||||
**Purpose**: Track and manage feature subtasks
|
||||
|
||||
## What I do
|
||||
|
||||
- Track task progress
|
||||
- Show next eligible tasks
|
||||
- Identify blocked tasks
|
||||
- Mark completion
|
||||
- Validate task integrity
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Show all task statuses
|
||||
bunx --bun ts-node .opencode/skills/task-management/scripts/task-cli.ts status
|
||||
|
||||
# Show next eligible tasks
|
||||
bunx --bun ts-node .opencode/skills/task-management/scripts/task-cli.ts next
|
||||
|
||||
# Mark complete
|
||||
bunx --bun ts-node .opencode/skills/task-management/scripts/task-cli.ts complete <feature> <seq> "summary"
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## router.sh
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
case "$1" in
|
||||
help|--help|-h)
|
||||
echo "Task Management Skill"
|
||||
echo "Usage: bash router.sh <command>"
|
||||
echo "Commands: status, next, blocked, complete, validate"
|
||||
;;
|
||||
status|next|blocked|validate)
|
||||
bunx --bun ts-node "$SCRIPT_DIR/scripts/task-cli.ts" "$@"
|
||||
;;
|
||||
complete)
|
||||
bunx --bun ts-node "$SCRIPT_DIR/scripts/task-cli.ts" "$@"
|
||||
;;
|
||||
*)
|
||||
echo "Unknown command: $1"
|
||||
bash "$0" help
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## task-cli.ts (Excerpt)
|
||||
|
||||
```typescript
|
||||
#!/usr/bin/env ts-node
|
||||
|
||||
interface Task {
|
||||
id: string
|
||||
status: 'pending' | 'in_progress' | 'completed'
|
||||
title: string
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const command = process.argv[2] || 'help'
|
||||
|
||||
switch (command) {
|
||||
case 'status':
|
||||
await showStatus()
|
||||
break
|
||||
case 'next':
|
||||
await showNext()
|
||||
break
|
||||
case 'complete':
|
||||
const [, , , feature, seq, summary] = process.argv
|
||||
await markComplete(feature, seq, summary)
|
||||
break
|
||||
default:
|
||||
showHelp()
|
||||
}
|
||||
}
|
||||
|
||||
async function showStatus() {
|
||||
// Implementation
|
||||
console.log('Task status...')
|
||||
}
|
||||
|
||||
async function showNext() {
|
||||
// Implementation
|
||||
console.log('Next tasks...')
|
||||
}
|
||||
|
||||
async function markComplete(feature: string, seq: string, summary: string) {
|
||||
// Implementation
|
||||
console.log(`Completing ${feature} ${seq}: ${summary}`)
|
||||
}
|
||||
|
||||
function showHelp() {
|
||||
console.log(`
|
||||
Task Management CLI
|
||||
|
||||
Commands:
|
||||
status Show all task statuses
|
||||
next Show next eligible tasks
|
||||
blocked Show blocked tasks
|
||||
complete <f> <s> Mark task complete
|
||||
validate Validate task integrity
|
||||
`)
|
||||
}
|
||||
|
||||
main().catch(console.error)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Agents
|
||||
|
||||
Skills integrate with agents via:
|
||||
- Event hooks (`tool.execute.before`, `tool.execute.after`)
|
||||
- Skill content injection into conversation
|
||||
- Output enhancement
|
||||
|
||||
Example agent prompt invoking skill:
|
||||
```
|
||||
Use the task-management skill to show current task status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `adding-skill-basics.md` - Directory and SKILL.md setup
|
||||
- `adding-skill-implementation.md` - CLI and registry
|
||||
- `plugins/context/capabilities/events_skills.md` - Skills Plugin
|
||||
@@ -0,0 +1,169 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: OpenCode Skill Implementation
|
||||
|
||||
**Prerequisites**: Load `adding-skill-basics.md` first
|
||||
**Purpose**: CLI implementation, registry, and testing for OpenCode skills
|
||||
|
||||
---
|
||||
|
||||
## CLI Implementation
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```typescript
|
||||
#!/usr/bin/env ts-node
|
||||
// CLI implementation for {skill-name} skill
|
||||
|
||||
interface Args {
|
||||
command: string
|
||||
[key: string]: any
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const args = parseArgs()
|
||||
|
||||
switch (args.command) {
|
||||
case 'command1':
|
||||
await handleCommand1(args)
|
||||
break
|
||||
case 'command2':
|
||||
await handleCommand2(args)
|
||||
break
|
||||
case 'help':
|
||||
default:
|
||||
showHelp()
|
||||
}
|
||||
}
|
||||
|
||||
function parseArgs(): Args {
|
||||
const args = process.argv.slice(2)
|
||||
return {
|
||||
command: args[0] || 'help',
|
||||
...parseOptions(args.slice(1))
|
||||
}
|
||||
}
|
||||
|
||||
async function handleCommand1(args: Args) {
|
||||
console.log('Running command1...')
|
||||
}
|
||||
|
||||
function showHelp() {
|
||||
console.log(`
|
||||
{Skill Name}
|
||||
|
||||
Usage: bunx --bun ts-node scripts/skill-cli.ts <command> [options]
|
||||
|
||||
Commands:
|
||||
command1 Description
|
||||
command2 Description
|
||||
help Show this help
|
||||
`)
|
||||
}
|
||||
|
||||
main().catch(console.error)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Register in Registry (Optional)
|
||||
|
||||
### Add to Components
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": [
|
||||
{
|
||||
"id": "{skill-name}",
|
||||
"name": "Skill Name",
|
||||
"type": "skill",
|
||||
"path": ".opencode/skills/{skill-name}/SKILL.md",
|
||||
"description": "Brief description",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"dependencies": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Add to Profiles
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": {
|
||||
"essential": {
|
||||
"components": [
|
||||
"skill:{skill-name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Test CLI Commands
|
||||
|
||||
```bash
|
||||
# Test help
|
||||
bash .opencode/skills/{skill-name}/router.sh help
|
||||
|
||||
# Test commands
|
||||
bash .opencode/skills/{skill-name}/router.sh command1 --option value
|
||||
|
||||
# Test with npx
|
||||
bunx --bun ts-node .opencode/skills/{skill-name}/scripts/skill-cli.ts help
|
||||
```
|
||||
|
||||
### Test OpenCode Integration
|
||||
|
||||
1. Call skill via OpenCode
|
||||
2. Verify event hooks fire correctly
|
||||
3. Check conversation history for skill content
|
||||
4. Verify output enhancement works
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Keep Skills Focused
|
||||
- ✅ Task management skill → Tracks tasks
|
||||
- ❌ Task management + code generation + testing → Too broad
|
||||
|
||||
### Clear Documentation
|
||||
- Provide usage examples
|
||||
- Document all commands
|
||||
- Include expected outputs
|
||||
|
||||
### Error Handling
|
||||
- Handle missing arguments gracefully
|
||||
- Provide helpful error messages
|
||||
- Validate inputs before processing
|
||||
|
||||
### Performance
|
||||
- Use efficient algorithms
|
||||
- Cache when appropriate
|
||||
- Avoid unnecessary file operations
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] `.opencode/skills/{skill-name}/SKILL.md` created
|
||||
- [ ] `.opencode/skills/{skill-name}/router.sh` created (if CLI-based)
|
||||
- [ ] Router script is executable (`chmod +x`)
|
||||
- [ ] Registry updated (if needed)
|
||||
- [ ] Profile updated (if needed)
|
||||
- [ ] All commands tested
|
||||
- [ ] Documentation complete
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `adding-skill-basics.md` - Directory and SKILL.md setup
|
||||
- `adding-skill-example.md` - Complete example
|
||||
- `creating-skills.md` - Claude Code Skills
|
||||
- `plugins/context/capabilities/events_skills.md` - Skills Plugin
|
||||
@@ -0,0 +1,99 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Building CLIs in OpenAgents Control: Compact Guide
|
||||
|
||||
**Category**: guide
|
||||
**Purpose**: Rapidly build, register, and deploy CLI tools for OpenAgents Control skills
|
||||
**Framework**: FAB (Features, Advantages, Benefits)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
**Don't start from scratch.** Use the standard pattern to build robust CLIs in minutes.
|
||||
|
||||
1. **Create**: `mkdir -p .opencode/skills/{name}/scripts`
|
||||
2. **Implement**: Create `skill-cli.ts` (TypeScript) and `router.sh` (Bash)
|
||||
3. **Register**: Add to `registry.json`
|
||||
4. **Run**: `bash .opencode/skills/{name}/router.sh help`
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Core Architecture
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| **Logic** | `scripts/skill-cli.ts` | Type-safe implementation using `ts-node`. Handles args, logic, and output. |
|
||||
| **Router** | `router.sh` | Universal entry point. Routes commands to the TS script. |
|
||||
| **Docs** | `SKILL.md` | User guide, examples, and integration details. |
|
||||
| **Config** | `registry.json` | Makes the skill discoverable and installable via `install.sh`. |
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Implementation Patterns
|
||||
|
||||
### 1. The Router (`router.sh`)
|
||||
**Why**: Provides a consistent, dependency-free entry point for all environments.
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
case "$1" in
|
||||
help|--help|-h)
|
||||
echo "Usage: bash router.sh <command>"
|
||||
;;
|
||||
*)
|
||||
# Route to TypeScript implementation
|
||||
bunx --bun ts-node "$SCRIPT_DIR/scripts/skill-cli.ts" "$@"
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
### 2. The CLI Logic (`skill-cli.ts`)
|
||||
**Why**: Type safety, async/await support, and rich ecosystem access.
|
||||
|
||||
```typescript
|
||||
#!/usr/bin/env ts-node
|
||||
|
||||
async function main() {
|
||||
const [command, ...args] = process.argv.slice(2);
|
||||
|
||||
switch (command) {
|
||||
case 'action':
|
||||
await handleAction(args);
|
||||
break;
|
||||
default:
|
||||
console.log("Unknown command");
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
main().catch(console.error);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Quality Checklist
|
||||
|
||||
Before shipping, verify your CLI delivers value:
|
||||
|
||||
- [ ] **Help Command**: Does `router.sh help` provide clear, actionable usage info?
|
||||
- [ ] **Error Handling**: Do invalid inputs return helpful error messages (not stack traces)?
|
||||
- [ ] **Performance**: Does it start in < 1s? (Avoid heavy imports at top level)
|
||||
- [ ] **Idempotency**: Can commands be run multiple times safely?
|
||||
- [ ] **Registry**: Is it added to `registry.json` with correct paths?
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Copywriting Principles for CLI Output
|
||||
|
||||
Apply `content-creation` principles to your CLI output:
|
||||
|
||||
1. **Clarity**: Use **Active Voice**. "Created file" (Good) vs "File has been created" (Bad).
|
||||
2. **Specificity**: "Processed 5 files" (Good) vs "Processing complete" (Bad).
|
||||
3. **Action**: Tell the user what to do next. "Run `bun --bun test` to verify."
|
||||
|
||||
---
|
||||
|
||||
**Reference**: See `.opencode/context/openagents-repo/guides/adding-skill-basics.md` for the full, detailed walkthrough.
|
||||
291
.opencode/context/openagents-repo/guides/creating-release.md
Normal file
291
.opencode/context/openagents-repo/guides/creating-release.md
Normal file
@@ -0,0 +1,291 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Creating a Release
|
||||
|
||||
**Purpose**: Step-by-step workflow for creating a new release
|
||||
|
||||
---
|
||||
|
||||
## Quick Steps
|
||||
|
||||
```bash
|
||||
# 1. Update version
|
||||
echo "0.X.Y" > VERSION
|
||||
jq '.version = "0.X.Y"' package.json > tmp && mv tmp package.json
|
||||
|
||||
# 2. Update CHANGELOG
|
||||
# (Edit CHANGELOG.md manually)
|
||||
|
||||
# 3. Commit and tag
|
||||
git add VERSION package.json CHANGELOG.md
|
||||
git commit -m "chore: bump version to 0.X.Y"
|
||||
git tag -a v0.X.Y -m "Release v0.X.Y"
|
||||
|
||||
# 4. Push
|
||||
git push origin main
|
||||
git push origin v0.X.Y
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Determine Version
|
||||
|
||||
### Semantic Versioning
|
||||
|
||||
```
|
||||
MAJOR.MINOR.PATCH
|
||||
|
||||
- MAJOR: Breaking changes
|
||||
- MINOR: New features (backward compatible)
|
||||
- PATCH: Bug fixes
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
- `0.5.0` → `0.5.1` (bug fix)
|
||||
- `0.5.0` → `0.6.0` (new feature)
|
||||
- `0.5.0` → `1.0.0` (breaking change)
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Update Version Files
|
||||
|
||||
### VERSION File
|
||||
|
||||
```bash
|
||||
echo "0.X.Y" > VERSION
|
||||
```
|
||||
|
||||
### package.json
|
||||
|
||||
```bash
|
||||
jq '.version = "0.X.Y"' package.json > tmp && mv tmp package.json
|
||||
```
|
||||
|
||||
### Verify Consistency
|
||||
|
||||
```bash
|
||||
cat VERSION
|
||||
cat package.json | jq '.version'
|
||||
# Both should show same version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Update CHANGELOG
|
||||
|
||||
### Format
|
||||
|
||||
```markdown
|
||||
# Changelog
|
||||
|
||||
## [0.X.Y] - 2025-12-10
|
||||
|
||||
### Added
|
||||
- New feature 1
|
||||
- New feature 2
|
||||
|
||||
### Changed
|
||||
- Updated feature 1
|
||||
- Improved feature 2
|
||||
|
||||
### Fixed
|
||||
- Bug fix 1
|
||||
- Bug fix 2
|
||||
|
||||
### Removed
|
||||
- Deprecated feature 1
|
||||
|
||||
## [Previous Version] - Date
|
||||
...
|
||||
```
|
||||
|
||||
### Tips
|
||||
|
||||
✅ **Group by type** - Added, Changed, Fixed, Removed
|
||||
✅ **User-focused** - Describe impact, not implementation
|
||||
✅ **Link PRs** - Reference PR numbers
|
||||
✅ **Breaking changes** - Clearly mark breaking changes
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Commit Changes
|
||||
|
||||
```bash
|
||||
# Stage files
|
||||
git add VERSION package.json CHANGELOG.md
|
||||
|
||||
# Commit
|
||||
git commit -m "chore: bump version to 0.X.Y"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Create Git Tag
|
||||
|
||||
```bash
|
||||
# Create annotated tag
|
||||
git tag -a v0.X.Y -m "Release v0.X.Y"
|
||||
|
||||
# Verify tag
|
||||
git tag -l "v0.X.Y"
|
||||
git show v0.X.Y
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Push to GitHub
|
||||
|
||||
```bash
|
||||
# Push commit
|
||||
git push origin main
|
||||
|
||||
# Push tag
|
||||
git push origin v0.X.Y
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Create GitHub Release
|
||||
|
||||
### Via GitHub UI
|
||||
|
||||
1. Go to repository on GitHub
|
||||
2. Click "Releases"
|
||||
3. Click "Create a new release"
|
||||
4. Select tag: `v0.X.Y`
|
||||
5. Title: `v0.X.Y`
|
||||
6. Description: Copy from CHANGELOG
|
||||
7. Click "Publish release"
|
||||
|
||||
### Via GitHub CLI
|
||||
|
||||
```bash
|
||||
gh release create v0.X.Y \
|
||||
--title "v0.X.Y" \
|
||||
--notes "$(cat CHANGELOG.md | sed -n '/## \[0.X.Y\]/,/## \[/p' | head -n -1)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Verify Release
|
||||
|
||||
### Check GitHub
|
||||
|
||||
- ✅ Release appears on GitHub
|
||||
- ✅ Tag is correct
|
||||
- ✅ CHANGELOG is included
|
||||
- ✅ Assets are attached (if any)
|
||||
|
||||
### Test Installation
|
||||
|
||||
```bash
|
||||
# Test install from GitHub
|
||||
./install.sh --list
|
||||
|
||||
# Verify version
|
||||
cat VERSION
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Example
|
||||
|
||||
```bash
|
||||
# Releasing v0.6.0
|
||||
|
||||
# 1. Update version
|
||||
echo "0.6.0" > VERSION
|
||||
jq '.version = "0.6.0"' package.json > tmp && mv tmp package.json
|
||||
|
||||
# 2. Update CHANGELOG
|
||||
cat >> CHANGELOG.md << 'EOF'
|
||||
## [0.6.0] - 2025-12-10
|
||||
|
||||
### Added
|
||||
- New API specialist agent
|
||||
- GraphQL support in backend specialist
|
||||
|
||||
### Changed
|
||||
- Improved eval framework performance
|
||||
- Updated registry schema to 2.0.0
|
||||
|
||||
### Fixed
|
||||
- Fixed path resolution for subagents
|
||||
- Fixed registry validation edge cases
|
||||
EOF
|
||||
|
||||
# 3. Commit
|
||||
git add VERSION package.json CHANGELOG.md
|
||||
git commit -m "chore: bump version to 0.6.0"
|
||||
|
||||
# 4. Tag
|
||||
git tag -a v0.6.0 -m "Release v0.6.0"
|
||||
|
||||
# 5. Push
|
||||
git push origin main
|
||||
git push origin v0.6.0
|
||||
|
||||
# 6. Create GitHub release
|
||||
gh release create v0.6.0 \
|
||||
--title "v0.6.0" \
|
||||
--notes "See CHANGELOG.md for details"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
Before releasing:
|
||||
|
||||
- [ ] All tests pass
|
||||
- [ ] Registry validates
|
||||
- [ ] VERSION updated
|
||||
- [ ] package.json updated
|
||||
- [ ] CHANGELOG updated
|
||||
- [ ] Changes committed
|
||||
- [ ] Tag created
|
||||
- [ ] Pushed to GitHub
|
||||
- [ ] GitHub release created
|
||||
- [ ] Installation tested
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Version Mismatch
|
||||
|
||||
**Problem**: VERSION and package.json don't match
|
||||
**Solution**: Update both to same version
|
||||
|
||||
### Tag Already Exists
|
||||
|
||||
**Problem**: Tag already exists
|
||||
**Solution**: Delete tag and recreate
|
||||
```bash
|
||||
git tag -d v0.X.Y
|
||||
git push origin :refs/tags/v0.X.Y
|
||||
```
|
||||
|
||||
### Push Rejected
|
||||
|
||||
**Problem**: Push rejected (not up to date)
|
||||
**Solution**: Pull latest changes first
|
||||
```bash
|
||||
git pull origin main
|
||||
git push origin main
|
||||
git push origin v0.X.Y
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Version management**: `scripts/versioning/bump-version.sh`
|
||||
- **CHANGELOG**: `CHANGELOG.md`
|
||||
- **VERSION**: `VERSION`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-10
|
||||
**Version**: 0.5.0
|
||||
401
.opencode/context/openagents-repo/guides/debugging.md
Normal file
401
.opencode/context/openagents-repo/guides/debugging.md
Normal file
@@ -0,0 +1,401 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Debugging Common Issues
|
||||
|
||||
**Purpose**: Troubleshooting guide for common problems
|
||||
|
||||
---
|
||||
|
||||
## Quick Diagnostics
|
||||
|
||||
```bash
|
||||
# Check system health
|
||||
./scripts/registry/validate-registry.sh
|
||||
./scripts/validation/validate-test-suites.sh
|
||||
|
||||
# Check version consistency
|
||||
cat VERSION && cat package.json | jq '.version'
|
||||
|
||||
# Test core agents
|
||||
cd evals/framework && bun --bun run eval:sdk -- --agent=core/openagent --pattern="smoke-test.yaml"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Registry Issues
|
||||
|
||||
### Registry Validation Fails
|
||||
|
||||
**Symptoms**:
|
||||
```
|
||||
ERROR: Path does not exist: (example: .opencode/agent/core/missing.md)
|
||||
```
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
./scripts/registry/validate-registry.sh -v
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
1. **Path doesn't exist**: Remove entry or create file
|
||||
2. **Duplicate ID**: Rename one component
|
||||
3. **Invalid category**: Use valid category
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Re-run auto-detect
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# Validate
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Component Not in Registry
|
||||
|
||||
**Symptoms**:
|
||||
- Component doesn't appear in `./install.sh --list`
|
||||
- Auto-detect doesn't find component
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
# Check frontmatter
|
||||
head -10 .opencode/agent/{category}/{agent}.md
|
||||
|
||||
# Dry run auto-detect
|
||||
./scripts/registry/auto-detect-components.sh --dry-run
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
1. **Missing frontmatter**: Add frontmatter
|
||||
2. **Invalid YAML**: Fix YAML syntax
|
||||
3. **Wrong location**: Move to correct directory
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Add frontmatter
|
||||
cat > .opencode/agent/{category}/{agent}.md << 'EOF'
|
||||
---
|
||||
description: "Brief description"
|
||||
category: "category"
|
||||
type: "agent"
|
||||
---
|
||||
|
||||
# Agent Content
|
||||
EOF
|
||||
|
||||
# Re-run auto-detect
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Failures
|
||||
|
||||
### Approval Gate Violation
|
||||
|
||||
**Symptoms**:
|
||||
```
|
||||
✗ Approval Gate: FAIL
|
||||
Violation: Agent executed write tool without requesting approval
|
||||
```
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
# Run with debug
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={agent} --pattern="{test}" --debug
|
||||
|
||||
# Check session
|
||||
ls -lt .tmp/sessions/ | head -5
|
||||
cat .tmp/sessions/{session-id}/session.json | jq
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
Add approval request in agent prompt:
|
||||
```markdown
|
||||
Before executing:
|
||||
1. Present plan to user
|
||||
2. Request approval
|
||||
3. Execute after approval
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Context Loading Violation
|
||||
|
||||
**Symptoms**:
|
||||
```
|
||||
✗ Context Loading: FAIL
|
||||
Violation: Agent executed write tool without loading required context
|
||||
```
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
# Check what context was loaded
|
||||
cat .tmp/sessions/{session-id}/events.json | jq '.[] | select(.type == "context_load")'
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
Add context loading in agent prompt:
|
||||
```markdown
|
||||
Before implementing:
|
||||
1. Load core/standards/code-quality.md
|
||||
2. Apply standards to implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Tool Usage Violation
|
||||
|
||||
**Symptoms**:
|
||||
```
|
||||
✗ Tool Usage: FAIL
|
||||
Violation: Agent used bash tool for reading file instead of read tool
|
||||
```
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
# Check tool usage
|
||||
cat .tmp/sessions/{session-id}/events.json | jq '.[] | select(.type == "tool_call")'
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
Update agent to use correct tools:
|
||||
- Use `read` instead of `bash cat`
|
||||
- Use `list` instead of `bash ls`
|
||||
- Use `grep` instead of `bash grep`
|
||||
|
||||
---
|
||||
|
||||
## Install Issues
|
||||
|
||||
### Install Script Fails
|
||||
|
||||
**Symptoms**:
|
||||
```
|
||||
ERROR: Failed to fetch registry
|
||||
ERROR: Component not found
|
||||
```
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
# Check dependencies
|
||||
which curl jq
|
||||
|
||||
# Test with local registry
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
1. **Missing dependencies**: Install curl and jq
|
||||
2. **Registry not found**: Check registry.json exists
|
||||
3. **Component not found**: Verify component in registry
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Install dependencies (macOS)
|
||||
brew install curl jq
|
||||
|
||||
# Install dependencies (Linux)
|
||||
sudo apt-get install curl jq
|
||||
|
||||
# Test locally
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Collision Handling
|
||||
|
||||
**Symptoms**:
|
||||
```
|
||||
File exists: .opencode/agent/core/openagent.md
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
1. **Skip**: Keep existing file
|
||||
2. **Overwrite**: Replace with new file
|
||||
3. **Backup**: Backup existing, install new
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Skip all collisions
|
||||
./install.sh developer --skip-existing
|
||||
|
||||
# Overwrite all collisions
|
||||
./install.sh developer --force
|
||||
|
||||
# Backup all collisions
|
||||
./install.sh developer --backup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Path Resolution Issues
|
||||
|
||||
### Agent Not Found
|
||||
|
||||
**Symptoms**:
|
||||
```
|
||||
ERROR: Agent not found: development/frontend-specialist
|
||||
```
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
# Check file exists
|
||||
ls -la .opencode/agent/subagents/development/frontend-specialist.md
|
||||
|
||||
# Check registry
|
||||
cat registry.json | jq '.components.agents[] | select(.id == "frontend-specialist")'
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
1. **File doesn't exist**: Create file
|
||||
2. **Wrong path**: Fix path in registry
|
||||
3. **Not in registry**: Run auto-detect
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Re-run auto-detect
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# Validate
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version Issues
|
||||
|
||||
### Version Mismatch
|
||||
|
||||
**Symptoms**:
|
||||
```
|
||||
VERSION: 0.5.0
|
||||
package.json: 0.4.0
|
||||
registry.json: 0.5.0
|
||||
```
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
cat VERSION
|
||||
cat package.json | jq '.version'
|
||||
cat registry.json | jq '.version'
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
Update all to same version:
|
||||
```bash
|
||||
echo "0.5.0" > VERSION
|
||||
jq '.version = "0.5.0"' package.json > tmp && mv tmp package.json
|
||||
jq '.version = "0.5.0"' registry.json > tmp && mv tmp registry.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Issues
|
||||
|
||||
### Workflow Fails
|
||||
|
||||
**Symptoms**:
|
||||
- Registry validation fails in CI
|
||||
- Tests fail in CI but pass locally
|
||||
|
||||
**Diagnosis**:
|
||||
```bash
|
||||
# Run same commands as CI
|
||||
./scripts/registry/validate-registry.sh
|
||||
./scripts/validation/validate-test-suites.sh
|
||||
cd evals/framework && bun --bun run eval:sdk
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
1. **Registry invalid**: Fix registry
|
||||
2. **Tests fail**: Fix tests
|
||||
3. **Dependencies missing**: Update CI config
|
||||
|
||||
---
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Tests Timeout
|
||||
|
||||
**Symptoms**:
|
||||
```
|
||||
ERROR: Test timeout after 60000ms
|
||||
```
|
||||
|
||||
**Solution**:
|
||||
Increase timeout in config.yaml:
|
||||
```yaml
|
||||
timeout: 120000 # 2 minutes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Slow Auto-Detect
|
||||
|
||||
**Symptoms**:
|
||||
Auto-detect takes too long
|
||||
|
||||
**Solution**:
|
||||
Limit scope:
|
||||
```bash
|
||||
# Only scan specific directory
|
||||
./scripts/registry/auto-detect-components.sh --path .opencode/agent/development/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Check Logs
|
||||
|
||||
```bash
|
||||
# Session logs
|
||||
ls -lt .tmp/sessions/ | head -5
|
||||
cat .tmp/sessions/{session-id}/session.json | jq
|
||||
|
||||
# Event timeline
|
||||
cat .tmp/sessions/{session-id}/events.json | jq
|
||||
```
|
||||
|
||||
### Run Diagnostics
|
||||
|
||||
```bash
|
||||
# Full system check
|
||||
./scripts/registry/validate-registry.sh -v
|
||||
./scripts/validation/validate-test-suites.sh
|
||||
cd evals/framework && bun --bun run eval:sdk -- --agent=core/openagent
|
||||
```
|
||||
|
||||
### Common Commands
|
||||
|
||||
```bash
|
||||
# Validate everything
|
||||
./scripts/registry/validate-registry.sh && \
|
||||
./scripts/validation/validate-test-suites.sh && \
|
||||
cd evals/framework && bun --bun run eval:sdk
|
||||
|
||||
# Reset and rebuild
|
||||
./scripts/registry/auto-detect-components.sh --auto-add --force
|
||||
./scripts/registry/validate-registry.sh
|
||||
|
||||
# Test installation
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Testing guide**: `guides/testing-agent.md`
|
||||
- **Registry guide**: `guides/updating-registry.md`
|
||||
- **Eval concepts**: `core-concepts/evals.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-10
|
||||
**Version**: 0.5.0
|
||||
@@ -0,0 +1,223 @@
|
||||
<!-- Context: openagents-repo/guides/external-libraries-workflow | Priority: high | Version: 1.0 | Updated: 2026-01-29 -->
|
||||
# Guide: External Libraries Workflow
|
||||
|
||||
**Purpose**: Fetch current documentation for external packages when adding agents or skills
|
||||
|
||||
**When to Use**: Any time you're working with external libraries (Drizzle, Better Auth, Next.js, etc.)
|
||||
|
||||
**Time to Read**: 5 minutes
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
**Golden Rule**: NEVER rely on training data for external libraries → ALWAYS fetch current docs
|
||||
|
||||
**Process**:
|
||||
1. Detect external package in your task
|
||||
2. Check for install scripts (if first-time setup)
|
||||
3. Use **ExternalScout** to fetch current documentation
|
||||
4. Implement with fresh, version-specific knowledge
|
||||
|
||||
---
|
||||
|
||||
## When to Use ExternalScout (MANDATORY)
|
||||
|
||||
✅ **Use ExternalScout when**:
|
||||
- Adding new agents that depend on external packages
|
||||
- Adding new skills that integrate with external libraries
|
||||
- First-time package setup in your implementation
|
||||
- Package/dependency errors occur
|
||||
- Version upgrades are needed
|
||||
- ANY external library work
|
||||
|
||||
❌ **Don't rely on**:
|
||||
- Training data (outdated, often wrong)
|
||||
- Old documentation (APIs change)
|
||||
- Assumptions about package behavior
|
||||
|
||||
---
|
||||
|
||||
## Why This Matters
|
||||
|
||||
**Example**: Next.js Evolution
|
||||
```
|
||||
Training data (2023): Next.js 13 uses pages/ directory
|
||||
Current (2025): Next.js 15 uses app/ directory (App Router)
|
||||
|
||||
Training data = broken code ❌
|
||||
ExternalScout = working code ✅
|
||||
```
|
||||
|
||||
**Real Impact**:
|
||||
- APIs change (new methods, deprecated features)
|
||||
- Configuration patterns evolve
|
||||
- Breaking changes happen frequently
|
||||
- Version-specific features differ
|
||||
|
||||
---
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
### Step 1: Detect External Package
|
||||
|
||||
**Triggers**:
|
||||
- User mentions a library name
|
||||
- You see imports in code
|
||||
- package.json has new dependencies
|
||||
- Build errors reference external packages
|
||||
|
||||
**Action**: Identify which external packages are involved
|
||||
|
||||
**Example**:
|
||||
```
|
||||
User: "Add authentication with Better Auth"
|
||||
→ External package detected: Better Auth
|
||||
→ Proceed to Step 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Check Install Scripts (First-Time Only)
|
||||
|
||||
**For first-time package setup**, check if there are install scripts:
|
||||
|
||||
```bash
|
||||
# Look for install scripts
|
||||
ls scripts/install/ scripts/setup/ bin/install* setup.sh install.sh
|
||||
|
||||
# Check package-specific requirements
|
||||
grep -r "postinstall\|preinstall" package.json
|
||||
```
|
||||
|
||||
**If scripts exist**:
|
||||
- Read them to understand setup order
|
||||
- Check for environment variables needed
|
||||
- Identify prerequisites (database, services)
|
||||
- Follow their guidance before implementing
|
||||
|
||||
**Why**: Scripts may set up databases, generate files, or configure services in a specific order
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Fetch Current Documentation (MANDATORY)
|
||||
|
||||
**Use ExternalScout** to get live, version-specific documentation:
|
||||
|
||||
```bash
|
||||
# Invoke ExternalScout via task tool
|
||||
task(
|
||||
subagent_type="ExternalScout",
|
||||
description="Fetch Drizzle ORM documentation",
|
||||
prompt="Fetch current documentation for Drizzle ORM focusing on:
|
||||
- Modular schema patterns
|
||||
- Next.js integration
|
||||
- Database setup
|
||||
- Migration strategies"
|
||||
)
|
||||
```
|
||||
|
||||
**What ExternalScout Returns**:
|
||||
- Live documentation from official sources
|
||||
- Version-specific features
|
||||
- Integration patterns
|
||||
- Setup requirements
|
||||
- Code examples
|
||||
|
||||
**Supported Libraries** (18+):
|
||||
- Drizzle ORM
|
||||
- Better Auth
|
||||
- Next.js
|
||||
- TanStack Query/Router/Start
|
||||
- Cloudflare Workers
|
||||
- AWS Lambda
|
||||
- Vercel
|
||||
- Shadcn/ui
|
||||
- Radix UI
|
||||
- Tailwind CSS
|
||||
- Zustand
|
||||
- Jotai
|
||||
- Zod
|
||||
- React Hook Form
|
||||
- Vitest
|
||||
- Playwright
|
||||
- And more...
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Implement with Fresh Knowledge
|
||||
|
||||
**Now implement** using the documentation from ExternalScout:
|
||||
- Follow current best practices
|
||||
- Use version-specific APIs
|
||||
- Apply recommended patterns
|
||||
- Reference the fetched docs in your code
|
||||
|
||||
---
|
||||
|
||||
## Integration with Agent/Skill Creation
|
||||
|
||||
### When Adding an Agent
|
||||
|
||||
1. Read: `guides/adding-agent.md`
|
||||
2. **If agent uses external packages**:
|
||||
- Use ExternalScout to fetch docs
|
||||
- Document dependencies in agent metadata
|
||||
- Add to registry with correct versions
|
||||
3. Test: `guides/testing-agent.md`
|
||||
|
||||
### When Adding a Skill
|
||||
|
||||
1. Read: `guides/adding-skill.md`
|
||||
2. **If skill uses external packages**:
|
||||
- Use ExternalScout to fetch docs
|
||||
- Document dependencies in skill metadata
|
||||
- Add to registry with correct versions
|
||||
3. Test: `guides/testing-subagents.md`
|
||||
|
||||
---
|
||||
|
||||
## Common Packages in OpenAgents
|
||||
|
||||
| Package | Use Case | Priority |
|
||||
|---------|----------|----------|
|
||||
| **Drizzle ORM** | Database schemas & queries | ⭐⭐⭐⭐⭐ |
|
||||
| **Better Auth** | Authentication & authorization | ⭐⭐⭐⭐⭐ |
|
||||
| **Next.js** | Full-stack web framework | ⭐⭐⭐⭐⭐ |
|
||||
| **TanStack Query** | Server state management | ⭐⭐⭐⭐ |
|
||||
| **Zod** | Schema validation | ⭐⭐⭐⭐ |
|
||||
| **Tailwind CSS** | Styling | ⭐⭐⭐⭐ |
|
||||
| **Shadcn/ui** | UI components | ⭐⭐⭐ |
|
||||
| **Vitest** | Testing framework | ⭐⭐⭐ |
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
Before implementing with external libraries:
|
||||
|
||||
- [ ] Identified all external packages involved
|
||||
- [ ] Checked for install scripts (if first-time)
|
||||
- [ ] Used ExternalScout to fetch current docs
|
||||
- [ ] Reviewed version-specific features
|
||||
- [ ] Documented dependencies in metadata
|
||||
- [ ] Added to registry with correct versions
|
||||
- [ ] Tested implementation thoroughly
|
||||
- [ ] Referenced ExternalScout docs in code comments
|
||||
|
||||
---
|
||||
|
||||
## Related Guides
|
||||
|
||||
- `guides/adding-agent.md` - Creating new agents
|
||||
- `guides/adding-skill.md` - Creating new skills
|
||||
- `guides/debugging.md` - Troubleshooting (includes dependency issues)
|
||||
- `guides/updating-registry.md` - Registry management
|
||||
|
||||
---
|
||||
|
||||
## Key Principle
|
||||
|
||||
> **External libraries change constantly. Your training data is outdated. Always fetch current documentation before implementing.**
|
||||
|
||||
This is not optional - it's the difference between working code and broken code.
|
||||
@@ -0,0 +1,473 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: GitHub Issues and Project Board Workflow
|
||||
|
||||
**Prerequisites**: Basic understanding of GitHub issues and projects
|
||||
**Purpose**: Step-by-step workflow for managing issues and project board
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers how to work with GitHub issues and the project board to track and process different requests, features, and improvements.
|
||||
|
||||
**Project Board**: https://github.com/users/darrenhinde/projects/2/views/2
|
||||
|
||||
**Time**: Varies by task
|
||||
|
||||
---
|
||||
|
||||
## Quick Commands Reference
|
||||
|
||||
```bash
|
||||
# List issues
|
||||
gh issue list --repo darrenhinde/OpenAgentsControl
|
||||
|
||||
# Create issue
|
||||
gh issue create --repo darrenhinde/OpenAgentsControl --title "Title" --body "Body" --label "label1,label2"
|
||||
|
||||
# Add issue to project
|
||||
gh project item-add 2 --owner darrenhinde --url https://github.com/darrenhinde/OpenAgentsControl/issues/NUMBER
|
||||
|
||||
# View issue
|
||||
gh issue view NUMBER --repo darrenhinde/OpenAgentsControl
|
||||
|
||||
# Update issue
|
||||
gh issue edit NUMBER --repo darrenhinde/OpenAgentsControl --add-label "new-label"
|
||||
|
||||
# Close issue
|
||||
gh issue close NUMBER --repo darrenhinde/OpenAgentsControl
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Creating Issues
|
||||
|
||||
### Issue Types
|
||||
|
||||
**Feature Request**
|
||||
- Labels: `feature`, `enhancement`
|
||||
- Include: Goals, key features, success criteria
|
||||
- Template: See "Feature Issue Template" below
|
||||
|
||||
**Bug Report**
|
||||
- Labels: `bug`
|
||||
- Include: Steps to reproduce, expected vs actual behavior
|
||||
- Template: See "Bug Issue Template" below
|
||||
|
||||
**Improvement**
|
||||
- Labels: `enhancement`, `framework`
|
||||
- Include: Current state, proposed improvement, impact
|
||||
|
||||
**Question**
|
||||
- Labels: `question`
|
||||
- Include: Context, specific question, use case
|
||||
|
||||
### Priority Labels
|
||||
|
||||
- `priority-high` - Critical, blocking work
|
||||
- `priority-medium` - Important, not blocking
|
||||
- `priority-low` - Nice to have
|
||||
|
||||
### Category Labels
|
||||
|
||||
- `agents` - Agent system related
|
||||
- `framework` - Core framework changes
|
||||
- `evals` - Evaluation framework
|
||||
- `idea` - High-level proposal
|
||||
|
||||
### Creating an Issue
|
||||
|
||||
```bash
|
||||
# Basic issue
|
||||
gh issue create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "Add new feature X" \
|
||||
--body "Description of feature" \
|
||||
--label "feature,priority-medium"
|
||||
|
||||
# Feature with detailed body
|
||||
gh issue create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "Build plugin system" \
|
||||
--label "feature,framework,priority-high" \
|
||||
--body "$(cat <<'EOF'
|
||||
## Overview
|
||||
Brief description
|
||||
|
||||
## Goals
|
||||
- Goal 1
|
||||
- Goal 2
|
||||
|
||||
## Key Features
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Adding Issues to Project Board
|
||||
|
||||
### Add Single Issue
|
||||
|
||||
```bash
|
||||
# Add issue to project
|
||||
gh project item-add 2 \
|
||||
--owner darrenhinde \
|
||||
--url https://github.com/darrenhinde/OpenAgentsControl/issues/NUMBER
|
||||
```
|
||||
|
||||
### Add Multiple Issues
|
||||
|
||||
```bash
|
||||
# Add issues 137-142 to project
|
||||
for i in {137..142}; do
|
||||
gh project item-add 2 \
|
||||
--owner darrenhinde \
|
||||
--url https://github.com/darrenhinde/OpenAgentsControl/issues/$i
|
||||
done
|
||||
```
|
||||
|
||||
### Verify Issues on Board
|
||||
|
||||
```bash
|
||||
# View project items
|
||||
gh project item-list 2 --owner darrenhinde --format json | jq '.items[] | {title, status}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Processing Issues
|
||||
|
||||
### Workflow States
|
||||
|
||||
1. **Backlog** - New issues, not yet prioritized
|
||||
2. **Todo** - Prioritized, ready to work on
|
||||
3. **In Progress** - Currently being worked on
|
||||
4. **In Review** - PR submitted, awaiting review
|
||||
5. **Done** - Completed and merged
|
||||
|
||||
### Moving Issues
|
||||
|
||||
```bash
|
||||
# Update issue status (via project board UI or gh CLI)
|
||||
# Note: Status updates are typically done via web UI
|
||||
```
|
||||
|
||||
### Assigning Issues
|
||||
|
||||
```bash
|
||||
# Assign to yourself
|
||||
gh issue edit NUMBER \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--add-assignee @me
|
||||
|
||||
# Assign to someone else
|
||||
gh issue edit NUMBER \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--add-assignee username
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Working on Issues
|
||||
|
||||
### Start Work
|
||||
|
||||
1. **Assign issue to yourself**
|
||||
```bash
|
||||
gh issue edit NUMBER --repo darrenhinde/OpenAgentsControl --add-assignee @me
|
||||
```
|
||||
|
||||
2. **Move to "In Progress"** (via web UI)
|
||||
|
||||
3. **Create branch** (optional)
|
||||
```bash
|
||||
git checkout -b feature/issue-NUMBER-description
|
||||
```
|
||||
|
||||
4. **Reference issue in commits**
|
||||
```bash
|
||||
git commit -m "feat: implement X (#NUMBER)"
|
||||
```
|
||||
|
||||
### Update Progress
|
||||
|
||||
```bash
|
||||
# Add comment to issue
|
||||
gh issue comment NUMBER \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--body "Progress update: Completed X, working on Y"
|
||||
```
|
||||
|
||||
### Complete Work
|
||||
|
||||
1. **Create PR**
|
||||
```bash
|
||||
gh pr create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "Fix #NUMBER: Description" \
|
||||
--body "Closes #NUMBER\n\nChanges:\n- Change 1\n- Change 2"
|
||||
```
|
||||
|
||||
2. **Move to "In Review"** (via web UI)
|
||||
|
||||
3. **After merge, issue auto-closes** (if PR uses "Closes #NUMBER")
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Using Issues for Request Processing
|
||||
|
||||
### Request Types
|
||||
|
||||
**User Feature Request**
|
||||
1. Create issue with `feature` label
|
||||
2. Add to project board
|
||||
3. Prioritize based on impact
|
||||
4. Break down into subtasks if needed
|
||||
5. Assign to appropriate person/team
|
||||
|
||||
**Bug Report**
|
||||
1. Create issue with `bug` label
|
||||
2. Add reproduction steps
|
||||
3. Prioritize based on severity
|
||||
4. Assign for investigation
|
||||
5. Link to related issues if applicable
|
||||
|
||||
**Improvement Suggestion**
|
||||
1. Create issue with `enhancement` label
|
||||
2. Discuss approach in comments
|
||||
3. Get consensus before implementation
|
||||
4. Create implementation plan
|
||||
5. Execute and track progress
|
||||
|
||||
### Breaking Down Large Issues
|
||||
|
||||
For complex features, create parent issue and subtasks:
|
||||
|
||||
```bash
|
||||
# Parent issue
|
||||
gh issue create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "[EPIC] Plugin System" \
|
||||
--label "feature,framework,priority-high" \
|
||||
--body "Parent issue for plugin system work"
|
||||
|
||||
# Subtask issues
|
||||
gh issue create \
|
||||
--repo darrenhinde/OpenAgentsControl \
|
||||
--title "Plugin manifest system" \
|
||||
--label "feature" \
|
||||
--body "Part of #PARENT_NUMBER\n\nImplement plugin.json manifest"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Issue Templates
|
||||
|
||||
### Feature Issue Template
|
||||
|
||||
```markdown
|
||||
## Overview
|
||||
Brief description of the feature
|
||||
|
||||
## Goals
|
||||
- Goal 1
|
||||
- Goal 2
|
||||
- Goal 3
|
||||
|
||||
## Key Features
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
- Feature 3
|
||||
|
||||
## Related Issues
|
||||
- #123 (related issue)
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
- [ ] Criterion 3
|
||||
```
|
||||
|
||||
### Bug Issue Template
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of the bug
|
||||
|
||||
## Steps to Reproduce
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
3. Step 3
|
||||
|
||||
## Expected Behavior
|
||||
What should happen
|
||||
|
||||
## Actual Behavior
|
||||
What actually happens
|
||||
|
||||
## Environment
|
||||
- OS: macOS/Linux/Windows
|
||||
- Version: 0.5.2
|
||||
- Node: v20.x
|
||||
|
||||
## Additional Context
|
||||
Any other relevant information
|
||||
```
|
||||
|
||||
### Improvement Issue Template
|
||||
|
||||
```markdown
|
||||
## Current State
|
||||
Description of current implementation
|
||||
|
||||
## Proposed Improvement
|
||||
What should be improved and why
|
||||
|
||||
## Impact
|
||||
- Performance improvement
|
||||
- Developer experience
|
||||
- User experience
|
||||
|
||||
## Implementation Approach
|
||||
High-level approach to implementation
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Automation and Integration
|
||||
|
||||
### Auto-Close Issues
|
||||
|
||||
Use keywords in PR descriptions:
|
||||
- `Closes #123`
|
||||
- `Fixes #123`
|
||||
- `Resolves #123`
|
||||
|
||||
### Link Issues to PRs
|
||||
|
||||
```bash
|
||||
# In PR description
|
||||
gh pr create \
|
||||
--title "Add feature X" \
|
||||
--body "Implements #123\n\nChanges:\n- Change 1"
|
||||
```
|
||||
|
||||
### Issue References in Commits
|
||||
|
||||
```bash
|
||||
# Reference issue in commit
|
||||
git commit -m "feat: add plugin system (#137)"
|
||||
|
||||
# Close issue in commit
|
||||
git commit -m "fix: resolve permission error (closes #140)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Issue Creation
|
||||
|
||||
✅ **Clear titles** - Descriptive and specific
|
||||
✅ **Detailed descriptions** - Include context and goals
|
||||
✅ **Proper labels** - Use consistent labeling
|
||||
✅ **Success criteria** - Define what "done" means
|
||||
✅ **Link related issues** - Show dependencies
|
||||
|
||||
### Issue Management
|
||||
|
||||
✅ **Regular triage** - Review and prioritize weekly
|
||||
✅ **Keep updated** - Add comments on progress
|
||||
✅ **Close stale issues** - Clean up old/irrelevant issues
|
||||
✅ **Use milestones** - Group related issues
|
||||
✅ **Assign owners** - Clear responsibility
|
||||
|
||||
### Project Board
|
||||
|
||||
✅ **Update status** - Keep board current
|
||||
✅ **Limit WIP** - Don't overload "In Progress"
|
||||
✅ **Review regularly** - Weekly board review
|
||||
✅ **Archive completed** - Keep board clean
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Processing User Request
|
||||
|
||||
1. **Receive request** (via issue, email, chat)
|
||||
2. **Create issue** with appropriate labels
|
||||
3. **Add to project board**
|
||||
4. **Triage and prioritize**
|
||||
5. **Assign to team member**
|
||||
6. **Track progress** via status updates
|
||||
7. **Review and merge** PR
|
||||
8. **Close issue** and notify requester
|
||||
|
||||
### Planning New Feature
|
||||
|
||||
1. **Create epic issue** for overall feature
|
||||
2. **Break down into subtasks**
|
||||
3. **Add all to project board**
|
||||
4. **Prioritize subtasks**
|
||||
5. **Assign to team members**
|
||||
6. **Track progress** across subtasks
|
||||
7. **Complete and close** when all subtasks done
|
||||
|
||||
### Bug Triage
|
||||
|
||||
1. **Create bug issue** with reproduction steps
|
||||
2. **Label with severity** (critical, high, medium, low)
|
||||
3. **Add to project board**
|
||||
4. **Assign for investigation**
|
||||
5. **Reproduce and diagnose**
|
||||
6. **Fix and test**
|
||||
7. **Create PR** with fix
|
||||
8. **Close issue** after merge
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
Before closing an issue:
|
||||
|
||||
- [ ] All success criteria met
|
||||
- [ ] Tests passing
|
||||
- [ ] Documentation updated
|
||||
- [ ] PR merged (if applicable)
|
||||
- [ ] Related issues updated
|
||||
- [ ] Stakeholders notified
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Registry guide**: `guides/updating-registry.md`
|
||||
- **Release guide**: `guides/creating-release.md`
|
||||
- **Testing guide**: `guides/testing-agent.md`
|
||||
- **Debugging**: `guides/debugging.md`
|
||||
|
||||
---
|
||||
|
||||
## External Resources
|
||||
|
||||
- [GitHub Issues Documentation](https://docs.github.com/en/issues)
|
||||
- [GitHub Projects Documentation](https://docs.github.com/en/issues/planning-and-tracking-with-projects)
|
||||
- [GitHub CLI Documentation](https://cli.github.com/manual/)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-30
|
||||
**Version**: 0.5.2
|
||||
44
.opencode/context/openagents-repo/guides/navigation.md
Normal file
44
.opencode/context/openagents-repo/guides/navigation.md
Normal file
@@ -0,0 +1,44 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Guides
|
||||
|
||||
**Purpose**: Step-by-step guides for working with OpenAgents Control
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/guides/
|
||||
├── navigation.md (this file)
|
||||
└── [guide files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **Adding agents (basics)** | `./adding-agent-basics.md` |
|
||||
| **Adding agents (tests)** | `./adding-agent-testing.md` |
|
||||
| **Adding OpenCode skills** | `./adding-skill-basics.md` |
|
||||
| **Creating Claude Code skills** | `./creating-skills.md` |
|
||||
| **Creating Claude Code subagents** | `./creating-subagents.md` |
|
||||
| **Testing subagents** | `./testing-subagents.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Implementation Guides** → How to implement features
|
||||
**Agent Guides** → How to work with agents
|
||||
**Testing Guides** → How to test implementations
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Examples** → `../examples/navigation.md`
|
||||
- **Core Concepts** → `../core-concepts/navigation.md`
|
||||
155
.opencode/context/openagents-repo/guides/npm-publishing.md
Normal file
155
.opencode/context/openagents-repo/guides/npm-publishing.md
Normal file
@@ -0,0 +1,155 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# NPM Publishing Guide
|
||||
|
||||
**Purpose**: Quick reference for publishing OpenAgents Control to npm
|
||||
|
||||
**Time to Read**: 3 minutes
|
||||
|
||||
---
|
||||
|
||||
## Core Concept
|
||||
|
||||
OpenAgents Control is published as `@nextsystems/oac` on npm. Users install globally and run `oac [profile]` to set up their projects.
|
||||
|
||||
**Key files**:
|
||||
- `package.json` - Package configuration
|
||||
- `bin/oac.js` - CLI entry point
|
||||
- `.npmignore` - Exclude dev files
|
||||
- `install.sh` - Main installer (runs when user executes `oac`)
|
||||
|
||||
---
|
||||
|
||||
## Publishing Workflow
|
||||
|
||||
### 1. Prepare Release
|
||||
|
||||
```bash
|
||||
# Update version
|
||||
bun --bun version patch # 0.7.0 -> 0.7.1
|
||||
bun --bun version minor # 0.7.0 -> 0.8.0
|
||||
|
||||
# Update VERSION file
|
||||
bun --bun -p "require('./package.json').version" > VERSION
|
||||
|
||||
# Update CHANGELOG.md with changes
|
||||
```
|
||||
|
||||
### 2. Test Locally
|
||||
|
||||
```bash
|
||||
# Create package
|
||||
bun --bun pack
|
||||
|
||||
# Install globally from tarball
|
||||
bun --bun install -g ./nextsystems-oac-0.7.1.tgz
|
||||
|
||||
# Test CLI
|
||||
oac --version
|
||||
oac --help
|
||||
|
||||
# Uninstall
|
||||
bun --bun uninstall -g @nextsystems/oac
|
||||
```
|
||||
|
||||
### 3. Publish
|
||||
|
||||
```bash
|
||||
# Login (one-time)
|
||||
bun --bun login
|
||||
|
||||
# Publish (scoped packages need --access public)
|
||||
bun --bun publish --access public
|
||||
```
|
||||
|
||||
### 4. Verify
|
||||
|
||||
```bash
|
||||
# Check it's live
|
||||
bun --bun view @nextsystems/oac
|
||||
|
||||
# Test installation
|
||||
bun --bun install -g @nextsystems/oac
|
||||
oac --version
|
||||
```
|
||||
|
||||
### 5. Create GitHub Release
|
||||
|
||||
```bash
|
||||
git tag v0.7.1
|
||||
git push --tags
|
||||
# Create release on GitHub with changelog
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## User Installation
|
||||
|
||||
Once published, users can:
|
||||
|
||||
```bash
|
||||
# Global install (recommended)
|
||||
bun --bun install -g @nextsystems/oac
|
||||
oac developer
|
||||
|
||||
# Or use bunx --bun (no install)
|
||||
bunx --bun @nextsystems/oac developer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
**"You do not have permission to publish"**
|
||||
```bash
|
||||
bun --bun whoami # Check you're logged in
|
||||
bun --bun publish --access public # Scoped packages need public access
|
||||
```
|
||||
|
||||
**"Version already exists"**
|
||||
```bash
|
||||
bun --bun version patch # Bump version first
|
||||
```
|
||||
|
||||
**"You must verify your email"**
|
||||
```bash
|
||||
bun --bun profile get # Check email verification status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Package Configuration
|
||||
|
||||
**What's included** (see `package.json` → `files`):
|
||||
- `.opencode/` - Agents, commands, context, profiles, skills, tools
|
||||
- `scripts/` - Installation scripts
|
||||
- `bin/` - CLI entry point
|
||||
- `registry.json` - Component registry
|
||||
- `install.sh` - Main installer
|
||||
- Docs (README, CHANGELOG, LICENSE)
|
||||
|
||||
**What's excluded** (see `.npmignore`):
|
||||
- `node_modules/`
|
||||
- `evals/`
|
||||
- `.tmp/`
|
||||
- Dev files
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
- ✅ Enable 2FA: `bun --bun profile enable-2fa auth-and-writes`
|
||||
- ✅ Use strong bun --bun password
|
||||
- ✅ `@nextsystems` scope is protected (only you can publish)
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Package**: https://www.npmjs.com/package/@nextsystems/oac
|
||||
- **Stats**: https://npm-stat.com/charts.html?package=@nextsystems/oac
|
||||
- **Codebase**: `package.json`, `bin/oac.js`, `.npmignore`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-30
|
||||
370
.opencode/context/openagents-repo/guides/profile-validation.md
Normal file
370
.opencode/context/openagents-repo/guides/profile-validation.md
Normal file
@@ -0,0 +1,370 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Profile Validation
|
||||
|
||||
**Purpose**: Ensure installation profiles include all appropriate components
|
||||
**Priority**: HIGH - Check this when adding new agents or updating registry
|
||||
|
||||
---
|
||||
|
||||
## What Are Profiles?
|
||||
|
||||
Profiles are pre-configured component bundles in `registry.json` that users install:
|
||||
- **essential** - Minimal setup (openagent + core subagents)
|
||||
- **developer** - Full dev environment (all dev agents + tools)
|
||||
- **business** - Content/product focus (content agents + tools)
|
||||
- **full** - Everything (all agents, subagents, tools)
|
||||
- **advanced** - Full + meta-level (system-builder, repo-manager)
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
**Issue**: New agents added to `components.agents[]` but NOT added to profiles
|
||||
|
||||
**Result**: Users install a profile but don't get the new agents
|
||||
|
||||
**Example** (v0.5.0 bug):
|
||||
```json
|
||||
// ✅ Agent exists in components
|
||||
{
|
||||
"id": "devops-specialist",
|
||||
"path": ".opencode/agent/subagents/development/devops-specialist.md"
|
||||
}
|
||||
|
||||
// ❌ But NOT in developer profile
|
||||
"developer": {
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:opencoder"
|
||||
// Missing: "agent:devops-specialist"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
When adding a new agent, **ALWAYS** check:
|
||||
|
||||
### 1. Agent Added to Components
|
||||
```bash
|
||||
# Check agent exists in registry
|
||||
cat registry.json | jq '.components.agents[] | select(.id == "your-agent")'
|
||||
```
|
||||
|
||||
### 2. Agent Added to Appropriate Profiles
|
||||
|
||||
**Development agents** → Add to:
|
||||
- ✅ `developer` profile
|
||||
- ✅ `full` profile
|
||||
- ✅ `advanced` profile
|
||||
|
||||
**Content agents** → Add to:
|
||||
- ✅ `business` profile
|
||||
- ✅ `full` profile
|
||||
- ✅ `advanced` profile
|
||||
|
||||
**Data agents** → Add to:
|
||||
- ✅ `business` profile (if business-focused)
|
||||
- ✅ `full` profile
|
||||
- ✅ `advanced` profile
|
||||
|
||||
**Meta agents** → Add to:
|
||||
- ✅ `advanced` profile only
|
||||
|
||||
**Core agents** → Add to:
|
||||
- ✅ `essential` profile
|
||||
- ✅ All other profiles
|
||||
|
||||
### 3. Verify Profile Includes Agent
|
||||
|
||||
```bash
|
||||
# Check if agent is in developer profile
|
||||
cat registry.json | jq '.profiles.developer.components[] | select(. == "agent:your-agent")'
|
||||
|
||||
# Check if agent is in business profile
|
||||
cat registry.json | jq '.profiles.business.components[] | select(. == "agent:your-agent")'
|
||||
|
||||
# Check if agent is in full profile
|
||||
cat registry.json | jq '.profiles.full.components[] | select(. == "agent:your-agent")'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Profile Assignment Rules
|
||||
|
||||
### Developer Profile
|
||||
**Include**:
|
||||
- Core agents (openagent, opencoder)
|
||||
- Development specialist subagents (frontend, devops)
|
||||
- All code subagents (tester, reviewer, coder-agent, build-agent)
|
||||
- Dev commands (commit, test, validate-repo, analyze-patterns)
|
||||
- Dev context (standards/code, standards/tests, workflows/*)
|
||||
- Utility subagents (image-specialist for website images)
|
||||
- Tools (env, gemini for image generation)
|
||||
|
||||
**Exclude**:
|
||||
- Content agents (copywriter, technical-writer)
|
||||
- Data agents (data-analyst)
|
||||
- Meta agents (system-builder, repo-manager)
|
||||
|
||||
### Business Profile
|
||||
**Include**:
|
||||
- Core agent (openagent)
|
||||
- Content specialists (copywriter, technical-writer)
|
||||
- Data specialists (data-analyst)
|
||||
- Image tools (gemini, image-specialist)
|
||||
- Notification tools (notify)
|
||||
|
||||
**Exclude**:
|
||||
- Development specialists
|
||||
- Code subagents
|
||||
- Meta agents
|
||||
|
||||
### Full Profile
|
||||
**Include**:
|
||||
- Everything from developer profile
|
||||
- Everything from business profile
|
||||
- All agents except meta agents
|
||||
|
||||
**Exclude**:
|
||||
- Meta agents (system-builder, repo-manager)
|
||||
|
||||
### Advanced Profile
|
||||
**Include**:
|
||||
- Everything from full profile
|
||||
- Meta agents (system-builder, repo-manager)
|
||||
- Meta subagents (domain-analyzer, agent-generator, etc.)
|
||||
- Meta commands (build-context-system)
|
||||
|
||||
---
|
||||
|
||||
## Automated Validation
|
||||
|
||||
### Script to Check Profile Coverage
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Check if all agents are in appropriate profiles
|
||||
|
||||
echo "Checking profile coverage..."
|
||||
|
||||
# Get all agent IDs
|
||||
agents=$(cat registry.json | jq -r '.components.agents[].id')
|
||||
|
||||
for agent in $agents; do
|
||||
# Get agent category
|
||||
category=$(cat registry.json | jq -r ".components.agents[] | select(.id == \"$agent\") | .category")
|
||||
|
||||
# Check which profiles include this agent
|
||||
in_developer=$(cat registry.json | jq ".profiles.developer.components[] | select(. == \"agent:$agent\")" 2>/dev/null)
|
||||
in_business=$(cat registry.json | jq ".profiles.business.components[] | select(. == \"agent:$agent\")" 2>/dev/null)
|
||||
in_full=$(cat registry.json | jq ".profiles.full.components[] | select(. == \"agent:$agent\")" 2>/dev/null)
|
||||
in_advanced=$(cat registry.json | jq ".profiles.advanced.components[] | select(. == \"agent:$agent\")" 2>/dev/null)
|
||||
|
||||
# Validate based on category
|
||||
case $category in
|
||||
"development")
|
||||
if [[ -z "$in_developer" ]]; then
|
||||
echo "❌ $agent (development) missing from developer profile"
|
||||
fi
|
||||
if [[ -z "$in_full" ]]; then
|
||||
echo "❌ $agent (development) missing from full profile"
|
||||
fi
|
||||
if [[ -z "$in_advanced" ]]; then
|
||||
echo "❌ $agent (development) missing from advanced profile"
|
||||
fi
|
||||
;;
|
||||
"content"|"data")
|
||||
if [[ -z "$in_business" ]]; then
|
||||
echo "❌ $agent ($category) missing from business profile"
|
||||
fi
|
||||
if [[ -z "$in_full" ]]; then
|
||||
echo "❌ $agent ($category) missing from full profile"
|
||||
fi
|
||||
if [[ -z "$in_advanced" ]]; then
|
||||
echo "❌ $agent ($category) missing from advanced profile"
|
||||
fi
|
||||
;;
|
||||
"meta")
|
||||
if [[ -z "$in_advanced" ]]; then
|
||||
echo "❌ $agent (meta) missing from advanced profile"
|
||||
fi
|
||||
;;
|
||||
"essential"|"standard")
|
||||
if [[ -z "$in_full" ]]; then
|
||||
echo "❌ $agent ($category) missing from full profile"
|
||||
fi
|
||||
if [[ -z "$in_advanced" ]]; then
|
||||
echo "❌ $agent ($category) missing from advanced profile"
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
echo "✅ Profile coverage check complete"
|
||||
```
|
||||
|
||||
Save this as: `scripts/registry/validate-profile-coverage.sh`
|
||||
|
||||
---
|
||||
|
||||
## Manual Validation Steps
|
||||
|
||||
### After Adding a New Agent
|
||||
|
||||
1. **Add agent to components**:
|
||||
```bash
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
2. **Manually add to profiles**:
|
||||
Edit `registry.json` and add `"agent:your-agent"` to appropriate profiles
|
||||
|
||||
3. **Validate registry**:
|
||||
```bash
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
4. **Test local install**:
|
||||
```bash
|
||||
# Test developer profile
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
|
||||
# Verify agent appears in profile
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list | grep "your-agent"
|
||||
```
|
||||
|
||||
5. **Test actual install**:
|
||||
```bash
|
||||
# Install to temp directory
|
||||
mkdir -p /tmp/test-install
|
||||
cd /tmp/test-install
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" bash <(curl -s https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/install.sh) developer
|
||||
|
||||
# Check if agent was installed
|
||||
ls .opencode/agent/category/your-agent.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ Mistake 1: Only Adding to Components
|
||||
```json
|
||||
// Added to components
|
||||
"components": {
|
||||
"agents": [
|
||||
{"id": "new-agent", ...}
|
||||
]
|
||||
}
|
||||
|
||||
// But forgot to add to profiles
|
||||
"profiles": {
|
||||
"developer": {
|
||||
"components": [
|
||||
// Missing: "agent:new-agent"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ❌ Mistake 2: Wrong Profile Assignment
|
||||
```json
|
||||
// Development agent added to business profile
|
||||
"business": {
|
||||
"components": [
|
||||
"agent:devops-specialist" // ❌ Should be in developer
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### ❌ Mistake 3: Inconsistent Profile Coverage
|
||||
```json
|
||||
// Added to full but not advanced
|
||||
"full": {
|
||||
"components": ["agent:new-agent"]
|
||||
},
|
||||
"advanced": {
|
||||
"components": [
|
||||
// ❌ Missing: "agent:new-agent"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
✅ **Use auto-detect** - Adds to components automatically
|
||||
✅ **Check all profiles** - Verify agent in correct profiles
|
||||
✅ **Test locally** - Install and verify before pushing
|
||||
✅ **Validate** - Run validation script after changes
|
||||
✅ **Document** - Update CHANGELOG with profile changes
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
Add profile validation to CI:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/validate-registry.yml
|
||||
- name: Validate Registry
|
||||
run: ./scripts/registry/validate-registry.sh
|
||||
|
||||
- name: Validate Profile Coverage
|
||||
run: ./scripts/registry/validate-profile-coverage.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Agent Category | Essential | Developer | Business | Full | Advanced |
|
||||
|---------------|-----------|-----------|----------|------|----------|
|
||||
| core | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| development* | ❌ | ✅ | ❌ | ✅ | ✅ |
|
||||
| content | ❌ | ❌ | ✅ | ✅ | ✅ |
|
||||
| data | ❌ | ❌ | ✅ | ✅ | ✅ |
|
||||
| meta | ❌ | ❌ | ❌ | ❌ | ✅ |
|
||||
|
||||
*Note: Development category includes agents (opencoder) and specialist subagents (frontend, devops)
|
||||
|
||||
---
|
||||
|
||||
## Development Profile Changes (v2.0.0)
|
||||
|
||||
**What Changed**:
|
||||
- frontend-specialist: Agent → Subagent (specialized executor)
|
||||
- devops-specialist: Agent → Subagent (specialized executor)
|
||||
- backend-specialist: Removed (functionality covered by opencoder)
|
||||
- codebase-pattern-analyst: Removed (replaced by analyze-patterns command)
|
||||
- analyze-patterns: New command for pattern analysis
|
||||
|
||||
**Why**:
|
||||
- Streamlined main agents to 2 (openagent, opencoder)
|
||||
- Specialist subagents provide focused expertise when needed
|
||||
- Reduced cognitive load for new users
|
||||
- Clearer separation between main agents and specialized tools
|
||||
|
||||
**Impact**:
|
||||
- Developer profile now has 2 main agents + 8 subagents
|
||||
- Smaller, more focused profile
|
||||
- Same capabilities, better organization
|
||||
- No breaking changes for existing workflows
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Registry concepts**: `core-concepts/registry.md`
|
||||
- **Updating registry**: `guides/updating-registry.md`
|
||||
- **Adding agents**: `guides/adding-agent.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-28
|
||||
**Version**: 0.5.2
|
||||
@@ -0,0 +1,59 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Resolving Installer Wildcard Failures
|
||||
|
||||
**Purpose**: Capture the root cause, fix, and lessons from wildcard context install failures.
|
||||
|
||||
**Last Updated**: 2026-01-12
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
- Installer changes scoped to `install.sh`
|
||||
- Registry entries validated (`./scripts/registry/validate-registry.sh`)
|
||||
|
||||
**Estimated time**: 10 min
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Identify the failure mode
|
||||
**Symptom**:
|
||||
```
|
||||
curl: (3) URL rejected: Malformed input to a URL function
|
||||
```
|
||||
**Cause**: Wildcard expansion returned context IDs that weren’t path-aligned (e.g., `standards-code` mapped to `.opencode/context/core/standards/code-quality.md`). Installer treated IDs as paths.
|
||||
|
||||
### 2. Expand wildcards to path-based IDs
|
||||
**Goal**: Make wildcard expansion output `core/...` IDs that map directly to a path.
|
||||
|
||||
**Update**:
|
||||
- Expand `context:core/*` to `core/standards/code-quality` style IDs
|
||||
|
||||
### 3. Resolve context paths deterministically
|
||||
**Goal**: Avoid ambiguous matches and ensure one registry entry is used.
|
||||
|
||||
**Update**:
|
||||
- Add `resolve_component_path` to map context IDs to the registry path
|
||||
- Use `first(...)` in jq queries for deterministic selection
|
||||
|
||||
### 4. Verify installation
|
||||
```bash
|
||||
bash scripts/tests/test-e2e-install.sh
|
||||
```
|
||||
**Expected**: All E2E tests pass on macOS and Ubuntu.
|
||||
|
||||
## Verification
|
||||
```bash
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| `Malformed input to a URL function` | Ensure wildcard expansion returns `core/...` IDs and uses `resolve_component_path` |
|
||||
| Multiple context entries for one path | Use `first(...)` in jq lookups |
|
||||
|
||||
## Related
|
||||
- guides/debugging.md
|
||||
- guides/updating-registry.md
|
||||
- core-concepts/registry.md
|
||||
373
.opencode/context/openagents-repo/guides/subagent-invocation.md
Normal file
373
.opencode/context/openagents-repo/guides/subagent-invocation.md
Normal file
@@ -0,0 +1,373 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Subagent Invocation
|
||||
|
||||
**Purpose**: How to correctly invoke subagents using the task tool
|
||||
**Priority**: HIGH - Critical for agent delegation
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
**Issue**: Agents trying to invoke subagents with incorrect `subagent_type` format
|
||||
|
||||
**Error**:
|
||||
```
|
||||
Unknown agent type: ContextScout is not a valid agent type
|
||||
```
|
||||
|
||||
**Root Cause**: The `subagent_type` parameter in the task tool must match the registered agent type in the OpenCode CLI, not the file path.
|
||||
|
||||
---
|
||||
|
||||
## Correct Subagent Invocation
|
||||
|
||||
### Available Subagent Types
|
||||
|
||||
Based on the OpenCode CLI registration, use these exact strings for `subagent_type`:
|
||||
|
||||
**Core Subagents**:
|
||||
- `"Task Manager"` - Task breakdown and planning
|
||||
- `"Documentation"` - Documentation generation
|
||||
- `"ContextScout"` - Context file discovery
|
||||
|
||||
**Code Subagents**:
|
||||
- `"Coder Agent"` - Code implementation
|
||||
- `"TestEngineer"` - Test authoring
|
||||
- `"Reviewer"` - Code review
|
||||
- `"Build Agent"` - Build validation
|
||||
|
||||
**System Builder Subagents**:
|
||||
- `"Domain Analyzer"` - Domain analysis
|
||||
- `"Agent Generator"` - Agent generation
|
||||
- `"Context Organizer"` - Context organization
|
||||
- `"Workflow Designer"` - Workflow design
|
||||
- `"Command Creator"` - Command creation
|
||||
|
||||
**Utility Subagents**:
|
||||
- `"Image Specialist"` - Image generation/editing
|
||||
|
||||
---
|
||||
|
||||
## Invocation Syntax
|
||||
|
||||
### ✅ Correct Format
|
||||
|
||||
```javascript
|
||||
task(
|
||||
subagent_type="Task Manager",
|
||||
description="Break down feature into subtasks",
|
||||
prompt="Detailed instructions..."
|
||||
)
|
||||
```
|
||||
|
||||
### ❌ Incorrect Formats
|
||||
|
||||
```javascript
|
||||
// ❌ Using file path
|
||||
task(
|
||||
subagent_type="TaskManager",
|
||||
...
|
||||
)
|
||||
|
||||
// ❌ Using kebab-case ID
|
||||
task(
|
||||
subagent_type="task-manager",
|
||||
...
|
||||
)
|
||||
|
||||
// ❌ Using registry path
|
||||
task(
|
||||
subagent_type=".opencode/agent/subagents/core/task-manager.md",
|
||||
...
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Find the Correct Type
|
||||
|
||||
### Method 1: Check Registry
|
||||
|
||||
```bash
|
||||
# List all subagent names
|
||||
cat registry.json | jq -r '.components.subagents[] | "\(.name)"'
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
Task Manager
|
||||
Image Specialist
|
||||
Reviewer
|
||||
TestEngineer
|
||||
Documentation Writer
|
||||
Coder Agent
|
||||
Build Agent
|
||||
Domain Analyzer
|
||||
Agent Generator
|
||||
Context Organizer
|
||||
Workflow Designer
|
||||
Command Creator
|
||||
ContextScout
|
||||
```
|
||||
|
||||
### Method 2: Check OpenCode CLI
|
||||
|
||||
```bash
|
||||
# List available agents (if CLI supports it)
|
||||
opencode list agents
|
||||
```
|
||||
|
||||
### Method 3: Check Agent Frontmatter
|
||||
|
||||
Look at the `name` field in the subagent's frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: task-manager
|
||||
name: Task Manager # ← Use this for subagent_type
|
||||
type: subagent
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Subagent Invocations
|
||||
|
||||
### Task Manager
|
||||
|
||||
```javascript
|
||||
task(
|
||||
subagent_type="Task Manager",
|
||||
description="Break down complex feature",
|
||||
prompt="Break down the following feature into atomic subtasks:
|
||||
|
||||
Feature: {feature description}
|
||||
|
||||
Requirements:
|
||||
- {requirement 1}
|
||||
- {requirement 2}
|
||||
|
||||
Create subtask files in tasks/subtasks/{feature}/"
|
||||
)
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
```javascript
|
||||
task(
|
||||
subagent_type="Documentation",
|
||||
description="Update documentation for feature",
|
||||
prompt="Update documentation for {feature}:
|
||||
|
||||
What changed:
|
||||
- {change 1}
|
||||
- {change 2}
|
||||
|
||||
Files to update:
|
||||
- {doc 1}
|
||||
- {doc 2}"
|
||||
)
|
||||
```
|
||||
|
||||
### TestEngineer
|
||||
|
||||
```javascript
|
||||
task(
|
||||
subagent_type="TestEngineer",
|
||||
description="Write tests for feature",
|
||||
prompt="Write comprehensive tests for {feature}:
|
||||
|
||||
Files to test:
|
||||
- {file 1}
|
||||
- {file 2}
|
||||
|
||||
Test coverage:
|
||||
- Positive cases
|
||||
- Negative cases
|
||||
- Edge cases"
|
||||
)
|
||||
```
|
||||
|
||||
### Reviewer
|
||||
|
||||
```javascript
|
||||
task(
|
||||
subagent_type="Reviewer",
|
||||
description="Review implementation",
|
||||
prompt="Review the following implementation:
|
||||
|
||||
Files:
|
||||
- {file 1}
|
||||
- {file 2}
|
||||
|
||||
Focus areas:
|
||||
- Security
|
||||
- Performance
|
||||
- Code quality"
|
||||
)
|
||||
```
|
||||
|
||||
### Coder Agent
|
||||
|
||||
```javascript
|
||||
task(
|
||||
subagent_type="Coder Agent",
|
||||
description="Implement subtask",
|
||||
prompt="Implement the following subtask:
|
||||
|
||||
Subtask: {subtask description}
|
||||
|
||||
Files to create/modify:
|
||||
- {file 1}
|
||||
|
||||
Requirements:
|
||||
- {requirement 1}
|
||||
- {requirement 2}"
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ContextScout Special Case
|
||||
|
||||
**Status**: ⚠️ May not be registered in OpenCode CLI yet
|
||||
|
||||
The `ContextScout` subagent exists in the repository but may not be registered in the OpenCode CLI's available agent types.
|
||||
|
||||
### Workaround
|
||||
|
||||
Until ContextScout is properly registered, use direct file operations instead:
|
||||
|
||||
```javascript
|
||||
// ❌ This may fail
|
||||
task(
|
||||
subagent_type="ContextScout",
|
||||
description="Find context files",
|
||||
prompt="Search for context related to {topic}"
|
||||
)
|
||||
|
||||
// ✅ Use direct operations instead
|
||||
// 1. Use glob to find context files
|
||||
glob(pattern="**/*.md", path=".opencode/context")
|
||||
|
||||
// 2. Use grep to search content
|
||||
grep(pattern="registry", path=".opencode/context")
|
||||
|
||||
// 3. Read relevant files directly
|
||||
read(filePath=".opencode/context/openagents-repo/core-concepts/registry.md")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fixing Existing Agents
|
||||
|
||||
### Agents That Need Fixing
|
||||
|
||||
1. **repo-manager.md** - Uses `ContextScout`
|
||||
2. **opencoder.md** - Check if uses incorrect format
|
||||
|
||||
### Fix Process
|
||||
|
||||
1. **Find incorrect invocations**:
|
||||
```bash
|
||||
grep -r 'subagent_type="subagents/' .opencode/agent --include="*.md"
|
||||
```
|
||||
|
||||
2. **Replace with correct format**:
|
||||
```bash
|
||||
# Example: Fix task-manager invocation
|
||||
# Old: subagent_type="TaskManager"
|
||||
# New: subagent_type="Task Manager"
|
||||
```
|
||||
|
||||
3. **Test the fix**:
|
||||
```bash
|
||||
# Run agent with test prompt
|
||||
# Verify subagent delegation works
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
### Check Subagent Type Before Using
|
||||
|
||||
```javascript
|
||||
// Pseudo-code for validation
|
||||
available_types = [
|
||||
"Task Manager",
|
||||
"Documentation",
|
||||
"TestEngineer",
|
||||
"Reviewer",
|
||||
"Coder Agent",
|
||||
"Build Agent",
|
||||
"Image Specialist",
|
||||
"Domain Analyzer",
|
||||
"Agent Generator",
|
||||
"Context Organizer",
|
||||
"Workflow Designer",
|
||||
"Command Creator"
|
||||
]
|
||||
|
||||
if subagent_type not in available_types:
|
||||
error("Invalid subagent type: {subagent_type}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
✅ **Use exact names** - Match registry `name` field exactly
|
||||
✅ **Check registry first** - Verify subagent exists before using
|
||||
✅ **Test invocations** - Test delegation before committing
|
||||
✅ **Document dependencies** - List required subagents in agent frontmatter
|
||||
|
||||
❌ **Don't use paths** - Never use file paths as subagent_type
|
||||
❌ **Don't use IDs** - Don't use kebab-case IDs
|
||||
❌ **Don't assume** - Always verify subagent is registered
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "Unknown agent type"
|
||||
|
||||
**Cause**: Subagent type not registered in CLI or incorrect format
|
||||
|
||||
**Solutions**:
|
||||
1. Check registry for correct name
|
||||
2. Verify subagent exists in `.opencode/agent/subagents/`
|
||||
3. Use exact name from registry `name` field
|
||||
4. If subagent not registered, use direct operations instead
|
||||
|
||||
### Error: "Subagent not found"
|
||||
|
||||
**Cause**: Subagent file doesn't exist
|
||||
|
||||
**Solutions**:
|
||||
1. Check file exists at expected path
|
||||
2. Verify registry entry is correct
|
||||
3. Run `./scripts/registry/validate-registry.sh`
|
||||
|
||||
### Delegation Fails Silently
|
||||
|
||||
**Cause**: Subagent invoked but doesn't execute
|
||||
|
||||
**Solutions**:
|
||||
1. Check subagent has required tools enabled
|
||||
2. Verify subagent permissions allow operation
|
||||
3. Check subagent prompt is clear and actionable
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Registry**: `registry.json` - Component catalog
|
||||
- **Subagents**: `.opencode/agent/subagents/` - Subagent definitions
|
||||
- **Validation**: `scripts/registry/validate-registry.sh`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-29
|
||||
**Version**: 0.5.1
|
||||
305
.opencode/context/openagents-repo/guides/testing-agent.md
Normal file
305
.opencode/context/openagents-repo/guides/testing-agent.md
Normal file
@@ -0,0 +1,305 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Testing an Agent
|
||||
|
||||
**Prerequisites**: Load `core-concepts/evals.md` first
|
||||
**Purpose**: Step-by-step workflow for testing agents
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Run smoke test
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --pattern="smoke-test.yaml"
|
||||
|
||||
# Run all tests for agent
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent}
|
||||
|
||||
# Run with debug
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --debug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Types
|
||||
|
||||
### 1. Smoke Test
|
||||
**Purpose**: Basic functionality check
|
||||
|
||||
```yaml
|
||||
name: Smoke Test
|
||||
description: Verify agent responds correctly
|
||||
agent: {category}/{agent}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Hello, can you help me?"
|
||||
expectations:
|
||||
- type: no_violations
|
||||
```
|
||||
|
||||
**Run**:
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --agent={agent} --pattern="smoke-test.yaml"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Approval Gate Test
|
||||
**Purpose**: Verify agent requests approval
|
||||
|
||||
```yaml
|
||||
name: Approval Gate Test
|
||||
description: Verify agent requests approval before execution
|
||||
agent: {category}/{agent}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Create a new file called test.js"
|
||||
expectations:
|
||||
- type: specific_evaluator
|
||||
evaluator: approval_gate
|
||||
should_pass: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Context Loading Test
|
||||
**Purpose**: Verify agent loads required context
|
||||
|
||||
```yaml
|
||||
name: Context Loading Test
|
||||
description: Verify agent loads required context
|
||||
agent: {category}/{agent}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Write a new function"
|
||||
expectations:
|
||||
- type: context_loaded
|
||||
contexts: ["core/standards/code-quality.md"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Tool Usage Test
|
||||
**Purpose**: Verify agent uses correct tools
|
||||
|
||||
```yaml
|
||||
name: Tool Usage Test
|
||||
description: Verify agent uses appropriate tools
|
||||
agent: {category}/{agent}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Read the package.json file"
|
||||
expectations:
|
||||
- type: tool_usage
|
||||
tools: ["read"]
|
||||
min_count: 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Single Test
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --pattern="{test-name}.yaml"
|
||||
```
|
||||
|
||||
### All Tests for Agent
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent}
|
||||
```
|
||||
|
||||
### All Tests (All Agents)
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk
|
||||
```
|
||||
|
||||
### With Debug Output
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={agent} --pattern="{test}" --debug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Interpreting Results
|
||||
|
||||
### Pass Example
|
||||
|
||||
```
|
||||
✓ Test: smoke-test.yaml
|
||||
Status: PASS
|
||||
Duration: 5.2s
|
||||
|
||||
Evaluators:
|
||||
✓ Approval Gate: PASS
|
||||
✓ Context Loading: PASS
|
||||
✓ Tool Usage: PASS
|
||||
✓ Stop on Failure: PASS
|
||||
✓ Execution Balance: PASS
|
||||
```
|
||||
|
||||
### Fail Example
|
||||
|
||||
```
|
||||
✗ Test: approval-gate.yaml
|
||||
Status: FAIL
|
||||
Duration: 4.8s
|
||||
|
||||
Evaluators:
|
||||
✗ Approval Gate: FAIL
|
||||
Violation: Agent executed write tool without requesting approval
|
||||
Location: Message #3, Tool call #1
|
||||
✓ Context Loading: PASS
|
||||
✓ Tool Usage: PASS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging Failures
|
||||
|
||||
### Step 1: Run with Debug
|
||||
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --agent={agent} --pattern="{test}" --debug
|
||||
```
|
||||
|
||||
### Step 2: Check Session
|
||||
|
||||
```bash
|
||||
# Find recent session
|
||||
ls -lt .tmp/sessions/ | head -5
|
||||
|
||||
# View session
|
||||
cat .tmp/sessions/{session-id}/session.json | jq
|
||||
```
|
||||
|
||||
### Step 3: Analyze Events
|
||||
|
||||
```bash
|
||||
# View event timeline
|
||||
cat .tmp/sessions/{session-id}/events.json | jq
|
||||
```
|
||||
|
||||
### Step 4: Identify Issue
|
||||
|
||||
Common issues:
|
||||
- **Approval Gate Violation**: Agent executed without approval
|
||||
- **Context Loading Violation**: Agent didn't load required context
|
||||
- **Tool Usage Violation**: Agent used wrong tool (bash instead of read)
|
||||
- **Stop on Failure Violation**: Agent auto-fixed instead of stopping
|
||||
|
||||
### Step 5: Fix Agent
|
||||
|
||||
Update agent prompt to address the issue, then re-test.
|
||||
|
||||
---
|
||||
|
||||
## Writing New Tests
|
||||
|
||||
### Test Template
|
||||
|
||||
```yaml
|
||||
name: Test Name
|
||||
description: What this test validates
|
||||
agent: {category}/{agent}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "User message"
|
||||
- role: assistant
|
||||
content: "Expected response (optional)"
|
||||
expectations:
|
||||
- type: no_violations
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
✅ **Clear name** - Descriptive test name
|
||||
✅ **Good description** - Explain what's being tested
|
||||
✅ **Realistic scenario** - Test real-world usage
|
||||
✅ **Specific expectations** - Clear pass/fail criteria
|
||||
✅ **Fast execution** - Keep under 10 seconds
|
||||
|
||||
---
|
||||
|
||||
## Common Test Patterns
|
||||
|
||||
### Test Approval Workflow
|
||||
|
||||
```yaml
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Create a new file"
|
||||
expectations:
|
||||
- type: specific_evaluator
|
||||
evaluator: approval_gate
|
||||
should_pass: true
|
||||
```
|
||||
|
||||
### Test Context Loading
|
||||
|
||||
```yaml
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Write new code"
|
||||
expectations:
|
||||
- type: context_loaded
|
||||
contexts: ["core/standards/code-quality.md"]
|
||||
```
|
||||
|
||||
### Test Tool Selection
|
||||
|
||||
```yaml
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Read the README file"
|
||||
expectations:
|
||||
- type: tool_usage
|
||||
tools: ["read"]
|
||||
min_count: 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Continuous Testing
|
||||
|
||||
### Pre-Commit Hook
|
||||
|
||||
```bash
|
||||
# Setup pre-commit hook
|
||||
./scripts/validation/setup-pre-commit-hook.sh
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
Tests run automatically on:
|
||||
- Pull requests
|
||||
- Merges to main
|
||||
- Release tags
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Eval concepts**: `core-concepts/evals.md`
|
||||
- **Debugging guide**: `guides/debugging.md`
|
||||
- **Adding agents**: `guides/adding-agent.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-10
|
||||
**Version**: 0.5.0
|
||||
@@ -0,0 +1,139 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
---
|
||||
description: "Guide for testing subagents and handling approval gates"
|
||||
type: "context"
|
||||
category: "openagents-repo"
|
||||
tags: [testing, subagents, approval-gates]
|
||||
---
|
||||
|
||||
# Testing Subagents: Approval Gates
|
||||
|
||||
**Context**: openagents-repo/guides | **Priority**: HIGH | **Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Critical Rule: Subagents Don't Need Approval Gates
|
||||
|
||||
**IMPORTANT**: When writing tests for subagents, DO NOT include `expectedViolations` for `approval-gate`.
|
||||
|
||||
### Why?
|
||||
|
||||
Subagents are **delegated to** by parent agents (OpenAgent, OpenCoder, etc.). The parent agent already requested and received approval before delegating. Therefore:
|
||||
|
||||
- ✅ Subagents can execute tools directly without asking for approval
|
||||
- ✅ Subagents inherit approval from their parent
|
||||
- ❌ Subagents should NOT be tested for approval gate violations
|
||||
|
||||
### Test Configuration for Subagents
|
||||
|
||||
**Correct** (no approval gate expectations):
|
||||
```yaml
|
||||
category: developer
|
||||
agent: ContextScout
|
||||
|
||||
approvalStrategy:
|
||||
type: auto-approve
|
||||
|
||||
behavior:
|
||||
mustUseTools:
|
||||
- read
|
||||
- glob
|
||||
forbiddenTools:
|
||||
- write
|
||||
- edit
|
||||
minToolCalls: 2
|
||||
maxToolCalls: 15
|
||||
|
||||
# NO expectedViolations for approval-gate!
|
||||
```
|
||||
|
||||
**Incorrect** (don't do this):
|
||||
```yaml
|
||||
expectedViolations:
|
||||
- rule: approval-gate # ❌ WRONG for subagents
|
||||
shouldViolate: false
|
||||
severity: error
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Test Approval Gates
|
||||
|
||||
**Test approval gates for**:
|
||||
- ✅ Primary agents (OpenAgent, OpenCoder, System Builder)
|
||||
- ✅ Category agents (frontend-specialist, data-analyst, etc.)
|
||||
|
||||
**Don't test approval gates for**:
|
||||
- ❌ Subagents (contextscout, tester, reviewer, coder-agent, etc.)
|
||||
- ❌ Any agent with `mode: subagent` in frontmatter
|
||||
|
||||
---
|
||||
|
||||
## Approval Strategy for Subagents
|
||||
|
||||
Always use `auto-approve` for subagent tests:
|
||||
|
||||
```yaml
|
||||
approvalStrategy:
|
||||
type: auto-approve
|
||||
```
|
||||
|
||||
This simulates the parent agent having already approved the delegation.
|
||||
|
||||
---
|
||||
|
||||
## Example: ContextScout Test
|
||||
|
||||
```yaml
|
||||
id: contextscout-code-standards
|
||||
name: "ContextScout: Code Standards Discovery"
|
||||
description: Tests that ContextScout discovers code-related context files
|
||||
|
||||
category: developer
|
||||
agent: ContextScout
|
||||
|
||||
prompts:
|
||||
- text: |
|
||||
Search for context files related to: coding standards
|
||||
|
||||
Task type: code
|
||||
|
||||
Return:
|
||||
- Exact file paths
|
||||
- Priority order
|
||||
- Key findings
|
||||
|
||||
approvalStrategy:
|
||||
type: auto-approve
|
||||
|
||||
behavior:
|
||||
mustUseTools:
|
||||
- read
|
||||
- glob
|
||||
forbiddenTools:
|
||||
- write
|
||||
- edit
|
||||
minToolCalls: 2
|
||||
maxToolCalls: 15
|
||||
|
||||
timeout: 60000
|
||||
|
||||
tags:
|
||||
- contextscout
|
||||
- discovery
|
||||
- subagent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Testing subagents**: `.opencode/context/openagents-repo/guides/testing-subagents.md`
|
||||
- **Subagent invocation**: `.opencode/context/openagents-repo/guides/subagent-invocation.md`
|
||||
- **Agent concepts**: `.opencode/context/openagents-repo/core-concepts/agents.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
**Version**: 1.0.0
|
||||
284
.opencode/context/openagents-repo/guides/testing-subagents.md
Normal file
284
.opencode/context/openagents-repo/guides/testing-subagents.md
Normal file
@@ -0,0 +1,284 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Testing Subagents - Step-by-Step Guide
|
||||
|
||||
**Purpose**: How to test subagents in standalone mode
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ CRITICAL: Adding New Subagent to Framework
|
||||
|
||||
**Before testing**, you MUST update THREE locations in framework code:
|
||||
|
||||
### 1. `evals/framework/src/sdk/run-sdk-tests.ts` (~line 336)
|
||||
Add to `subagentParentMap`:
|
||||
```typescript
|
||||
'contextscout': 'openagent', // Maps subagent → parent
|
||||
```
|
||||
|
||||
### 2. `evals/framework/src/sdk/run-sdk-tests.ts` (~line 414)
|
||||
Add to `subagentPathMap`:
|
||||
```typescript
|
||||
'contextscout': 'ContextScout', // Maps name → path
|
||||
```
|
||||
|
||||
### 3. `evals/framework/src/sdk/test-runner.ts` (~line 238)
|
||||
Add to `agentMap`:
|
||||
```typescript
|
||||
'contextscout': 'ContextScout.md', // Maps name → file
|
||||
```
|
||||
|
||||
**If missing from ANY map**: Tests will fail with "No test files found" or "Unknown subagent"
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Test subagent directly (standalone mode)
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --subagent=contextscout --pattern="01-test.yaml"
|
||||
|
||||
# Test via delegation (integration mode)
|
||||
bun --bun run eval:sdk -- --subagent=contextscout --delegate --pattern="01-test.yaml"
|
||||
|
||||
# Debug mode
|
||||
bun --bun run eval:sdk -- --subagent=contextscout --pattern="01-test.yaml" --debug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Verify Agent File
|
||||
|
||||
**Check agent exists and has correct structure**:
|
||||
|
||||
```bash
|
||||
# Check agent file
|
||||
cat .opencode/agent/subagents/core/contextscout.md | head -20
|
||||
|
||||
# Verify frontmatter
|
||||
grep -A 5 "^id:" .opencode/agent/subagents/core/contextscout.md
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
```yaml
|
||||
id: contextscout
|
||||
name: ContextScout
|
||||
category: subagents/core
|
||||
type: subagent
|
||||
mode: subagent # ← Will be forced to 'primary' in standalone tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Verify Test Configuration
|
||||
|
||||
**Check test config points to correct agent**:
|
||||
|
||||
```bash
|
||||
cat evals/agents/ContextScout/config/config.yaml
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
```yaml
|
||||
agent: ContextScout # ← Full path
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
timeout: 60000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Run Standalone Test
|
||||
|
||||
**Use `--subagent` flag** (not `--agent`):
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --subagent=ContextScout --pattern="standalone/01-simple-discovery.yaml"
|
||||
```
|
||||
|
||||
**What to Look For**:
|
||||
```
|
||||
⚡ Standalone Test Mode
|
||||
Subagent: contextscout
|
||||
Mode: Forced to 'primary' for direct testing
|
||||
|
||||
Testing agent: contextscout # ← Should show subagent name
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Verify Agent Loaded Correctly
|
||||
|
||||
**Check test results**:
|
||||
|
||||
```bash
|
||||
# View latest results
|
||||
cat evals/results/latest.json | jq '.meta'
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
```json
|
||||
{
|
||||
"agent": "ContextScout", // ← Correct agent
|
||||
"model": "opencode/grok-code-fast",
|
||||
"timestamp": "2026-01-07T..."
|
||||
}
|
||||
```
|
||||
|
||||
**Red Flags**:
|
||||
- `"agent": "core/openagent"` ← Wrong! OpenAgent is running instead
|
||||
- `"agent": "contextscout"` ← Missing category prefix
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Check Tool Usage
|
||||
|
||||
**Verify subagent used tools**:
|
||||
|
||||
```bash
|
||||
# Check tool calls in output
|
||||
cat evals/results/latest.json | jq '.tests[0]' | grep -A 5 "Tool Calls"
|
||||
```
|
||||
|
||||
**Expected** (for ContextScout):
|
||||
```
|
||||
Tool Calls: 1
|
||||
Tools Used: glob
|
||||
|
||||
Tool Call Details:
|
||||
1. glob: {"pattern":"*.md","path":".opencode/context/core"}
|
||||
```
|
||||
|
||||
**Red Flags**:
|
||||
- `Tool Calls: 0` ← Agent didn't use any tools
|
||||
- `Tools Used: task` ← Parent agent delegating (wrong mode)
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Analyze Failures
|
||||
|
||||
**If test fails, check violations**:
|
||||
|
||||
```bash
|
||||
cat evals/results/latest.json | jq '.tests[0].violations'
|
||||
```
|
||||
|
||||
**Common Issues**:
|
||||
|
||||
### Issue 1: No Tool Calls
|
||||
```json
|
||||
{
|
||||
"type": "missing-required-tool",
|
||||
"message": "Required tool 'glob' was not used"
|
||||
}
|
||||
```
|
||||
|
||||
**Cause**: Agent prompt doesn't emphasize tool usage
|
||||
**Fix**: Add critical rules section emphasizing tools (see `examples/subagent-prompt-structure.md`)
|
||||
|
||||
### Issue 2: Wrong Agent Running
|
||||
```
|
||||
Agent: OpenAgent
|
||||
```
|
||||
|
||||
**Cause**: Used `--agent` instead of `--subagent`
|
||||
**Fix**: Use `--subagent=ContextScout`
|
||||
|
||||
### Issue 3: Tool Permission Denied
|
||||
```json
|
||||
{
|
||||
"type": "missing-approval",
|
||||
"message": "Execution tool 'bash' called without requesting approval"
|
||||
}
|
||||
```
|
||||
|
||||
**Cause**: Agent tried to use restricted tool
|
||||
**Fix**: See `errors/tool-permission-errors.md`
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Validate Results
|
||||
|
||||
**Check test passed**:
|
||||
|
||||
```bash
|
||||
# View summary
|
||||
cat evals/results/latest.json | jq '.summary'
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
```json
|
||||
{
|
||||
"total": 1,
|
||||
"passed": 1, // ← Should be 1
|
||||
"failed": 0,
|
||||
"pass_rate": 1.0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test File Organization
|
||||
|
||||
**Best Practice**: Organize by mode
|
||||
|
||||
```
|
||||
evals/agents/ContextScout/tests/
|
||||
├── standalone/ # Unit tests (--subagent flag)
|
||||
│ ├── 01-simple-discovery.yaml
|
||||
│ ├── 02-search-test.yaml
|
||||
│ └── 03-extraction-test.yaml
|
||||
└── delegation/ # Integration tests (--agent flag)
|
||||
├── 01-openagent-delegates.yaml
|
||||
└── 02-context-loading.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing Good Test Prompts
|
||||
|
||||
**Be explicit about tool usage**:
|
||||
|
||||
❌ **Vague** (may not work):
|
||||
```yaml
|
||||
prompts:
|
||||
- text: |
|
||||
List all markdown files in .opencode/context/core/
|
||||
```
|
||||
|
||||
✅ **Explicit** (works):
|
||||
```yaml
|
||||
prompts:
|
||||
- text: |
|
||||
Use the glob tool to find all markdown files in .opencode/context/core/
|
||||
|
||||
You MUST use the glob tool like this:
|
||||
glob(pattern="*.md", path=".opencode/context/core")
|
||||
|
||||
Then list the files you found.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Troubleshooting
|
||||
|
||||
| Symptom | Cause | Fix |
|
||||
|---------|-------|-----|
|
||||
| OpenAgent runs instead | Used `--agent` flag | Use `--subagent` flag |
|
||||
| Tool calls: 0 | Prompt doesn't emphasize tools | Add critical rules section |
|
||||
| Permission denied | Tool restricted in frontmatter | Check `tools:` and `permissions:` |
|
||||
| Test timeout | Agent stuck/looping | Check prompt logic, add timeout |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `concepts/subagent-testing-modes.md` - Understand standalone vs delegation
|
||||
- `lookup/subagent-test-commands.md` - Quick command reference
|
||||
- `errors/tool-permission-errors.md` - Common permission issues
|
||||
- `examples/subagent-prompt-structure.md` - Optimized prompt structure
|
||||
|
||||
**Reference**: `evals/framework/src/sdk/run-sdk-tests.ts`
|
||||
483
.opencode/context/openagents-repo/guides/updating-registry.md
Normal file
483
.opencode/context/openagents-repo/guides/updating-registry.md
Normal file
@@ -0,0 +1,483 @@
|
||||
<!-- Context: openagents-repo/guides | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Updating Registry
|
||||
|
||||
**Prerequisites**: Load `core-concepts/registry.md` first
|
||||
**Purpose**: How to update the component registry
|
||||
|
||||
---
|
||||
|
||||
## Quick Commands
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Actually update registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
### Step 3: Validate
|
||||
|
||||
```bash
|
||||
# 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):
|
||||
```yaml
|
||||
---
|
||||
description: Your component description
|
||||
tags:
|
||||
- tag1
|
||||
- tag2
|
||||
- tag3
|
||||
dependencies:
|
||||
- subagent:coder-agent
|
||||
- context:core/standards/code
|
||||
- command:context
|
||||
---
|
||||
```
|
||||
|
||||
**Inline arrays** (compact format):
|
||||
```yaml
|
||||
---
|
||||
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`):
|
||||
```yaml
|
||||
---
|
||||
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`):
|
||||
```yaml
|
||||
---
|
||||
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`):
|
||||
```yaml
|
||||
---
|
||||
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**:
|
||||
```yaml
|
||||
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
|
||||
|
||||
1. **Create component** with frontmatter (tags + dependencies)
|
||||
2. **Run auto-detect**: `./scripts/registry/auto-detect-components.sh --dry-run`
|
||||
3. **Verify extraction**: Check that tags/dependencies appear in output
|
||||
4. **Apply changes**: `./scripts/registry/auto-detect-components.sh --auto-add`
|
||||
5. **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
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### Fixing Errors
|
||||
|
||||
1. **Path not found**: Fix path or remove entry
|
||||
2. **Duplicate ID**: Rename one component
|
||||
3. **Invalid category**: Use valid category
|
||||
4. **Missing dependency**: Add dependency or remove reference
|
||||
|
||||
---
|
||||
|
||||
## Testing Registry Changes
|
||||
|
||||
### Test Locally
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```yaml
|
||||
# .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
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **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**:
|
||||
1. **Check frontmatter format**:
|
||||
- Must be at top of file
|
||||
- Must start/end with `---`
|
||||
- Must use valid YAML syntax
|
||||
|
||||
2. **Verify array format**:
|
||||
```yaml
|
||||
# ✅ Valid formats
|
||||
tags: [tag1, tag2]
|
||||
tags:
|
||||
- tag1
|
||||
- tag2
|
||||
|
||||
# ❌ Invalid
|
||||
tags: tag1, tag2 # Missing brackets
|
||||
```
|
||||
|
||||
3. **Check dependency format**:
|
||||
```yaml
|
||||
# ✅ Valid
|
||||
dependencies: [subagent:coder-agent, context:core/standards/code]
|
||||
|
||||
# ❌ Invalid
|
||||
dependencies: [coder-agent] # Missing type prefix
|
||||
```
|
||||
|
||||
4. **Run dry-run to debug**:
|
||||
```bash
|
||||
./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:
|
||||
```bash
|
||||
# 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`.
|
||||
|
||||
1. Find the component in `registry.json`
|
||||
2. Add `"aliases": ["old-name", "alternative-name"]`
|
||||
3. 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).
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```bash
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-06
|
||||
**Version**: 2.0.0
|
||||
Reference in New Issue
Block a user