chore: install openagent opencode
Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
This commit is contained in:
@@ -0,0 +1,257 @@
|
||||
<!-- Context: openagents-repo/context-bundle-template | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
---
|
||||
description: "Template for creating context bundles when delegating tasks to subagents"
|
||||
type: "context"
|
||||
category: "openagents-repo"
|
||||
tags: [template, delegation, context]
|
||||
---
|
||||
|
||||
# Context Bundle Template
|
||||
|
||||
**Purpose**: Template for creating context bundles when delegating tasks to subagents
|
||||
|
||||
**Location**: `.tmp/context/{session-id}/bundle.md`
|
||||
|
||||
**Used by**: repo-manager agent when delegating to subagents
|
||||
|
||||
---
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Context Bundle: {Task Name}
|
||||
|
||||
Session: {session-id}
|
||||
Created: {ISO timestamp}
|
||||
For: {subagent-name}
|
||||
Status: in_progress
|
||||
|
||||
## Task Overview
|
||||
|
||||
{Brief description of what we're building/doing}
|
||||
|
||||
## User Request
|
||||
|
||||
{Original user request - what they asked for}
|
||||
|
||||
## Relevant Standards (Load These Before Starting)
|
||||
|
||||
**Core Standards**:
|
||||
- `.opencode/context/core/standards/code-quality.md` → Modular, functional code patterns
|
||||
- `.opencode/context/core/standards/test-coverage.md` → Testing requirements and TDD
|
||||
- `.opencode/context/core/standards/documentation.md` → Documentation standards
|
||||
- `.opencode/context/core/standards/security-patterns.md` → Error handling, security patterns
|
||||
|
||||
**Core Workflows**:
|
||||
- `.opencode/context/core/workflows/task-delegation-basics.md` → Delegation process
|
||||
- `.opencode/context/core/workflows/feature-breakdown.md` → Task breakdown methodology
|
||||
- `.opencode/context/core/workflows/code-review.md` → Code review guidelines
|
||||
|
||||
## Repository-Specific Context (Load These Before Starting)
|
||||
|
||||
**Quick Start** (ALWAYS load first):
|
||||
- `.opencode/context/openagents-repo/quick-start.md` → Repo orientation and common commands
|
||||
|
||||
**Core Concepts** (Load based on task type):
|
||||
- `.opencode/context/openagents-repo/core-concepts/agents.md` → How agents work
|
||||
- `.opencode/context/openagents-repo/core-concepts/evals.md` → How testing works
|
||||
- `.opencode/context/openagents-repo/core-concepts/registry.md` → How registry works
|
||||
- `.opencode/context/openagents-repo/core-concepts/categories.md` → How organization works
|
||||
|
||||
**Guides** (Load for specific workflows):
|
||||
- `.opencode/context/openagents-repo/guides/adding-agent-basics.md` → Step-by-step agent creation
|
||||
- `.opencode/context/openagents-repo/guides/testing-agent.md` → Testing workflow
|
||||
- `.opencode/context/openagents-repo/guides/updating-registry.md` → Registry workflow
|
||||
- `.opencode/context/openagents-repo/guides/debugging.md` → Troubleshooting
|
||||
|
||||
**Lookup** (Quick reference):
|
||||
- `.opencode/context/openagents-repo/lookup/file-locations.md` → Where everything is
|
||||
- `.opencode/context/openagents-repo/lookup/commands.md` → Command reference
|
||||
|
||||
## Key Requirements
|
||||
|
||||
{Extract key requirements from loaded context}
|
||||
|
||||
**From Standards**:
|
||||
- {requirement 1 from standards/code-quality.md}
|
||||
- {requirement 2 from standards/test-coverage.md}
|
||||
- {requirement 3 from standards/documentation.md}
|
||||
|
||||
**From Repository Context**:
|
||||
- {requirement 1 from repo context}
|
||||
- {requirement 2 from repo context}
|
||||
- {requirement 3 from repo context}
|
||||
|
||||
**Naming Conventions**:
|
||||
- {convention 1}
|
||||
- {convention 2}
|
||||
|
||||
**File Structure**:
|
||||
- {structure requirement 1}
|
||||
- {structure requirement 2}
|
||||
|
||||
## Technical Constraints
|
||||
|
||||
{List technical constraints and limitations}
|
||||
|
||||
- {constraint 1 - e.g., "Must use TypeScript"}
|
||||
- {constraint 2 - e.g., "Must follow category-based organization"}
|
||||
- {constraint 3 - e.g., "Must include proper frontmatter metadata"}
|
||||
|
||||
## Files to Create/Modify
|
||||
|
||||
{List all files that need to be created or modified}
|
||||
|
||||
**Create**:
|
||||
- `{file-path-1}` - {purpose and what it should contain}
|
||||
- `{file-path-2}` - {purpose and what it should contain}
|
||||
|
||||
**Modify**:
|
||||
- `{file-path-3}` - {what needs to be changed}
|
||||
- `{file-path-4}` - {what needs to be changed}
|
||||
|
||||
## Success Criteria
|
||||
|
||||
{Define what "done" looks like - binary pass/fail conditions}
|
||||
|
||||
- [ ] {criteria 1 - e.g., "Agent file created with proper frontmatter"}
|
||||
- [ ] {criteria 2 - e.g., "Eval tests pass"}
|
||||
- [ ] {criteria 3 - e.g., "Registry validation passes"}
|
||||
- [ ] {criteria 4 - e.g., "Documentation updated"}
|
||||
|
||||
## Validation Requirements
|
||||
|
||||
{How to validate the work}
|
||||
|
||||
**Scripts to Run**:
|
||||
- `{validation-script-1}` - {what it validates}
|
||||
- `{validation-script-2}` - {what it validates}
|
||||
|
||||
**Tests to Run**:
|
||||
- `{test-command-1}` - {what it tests}
|
||||
- `{test-command-2}` - {what it tests}
|
||||
|
||||
**Manual Checks**:
|
||||
- {check 1}
|
||||
- {check 2}
|
||||
|
||||
## Expected Output
|
||||
|
||||
{What the subagent should produce}
|
||||
|
||||
**Deliverables**:
|
||||
- {deliverable 1}
|
||||
- {deliverable 2}
|
||||
|
||||
**Format**:
|
||||
- {format requirement 1}
|
||||
- {format requirement 2}
|
||||
|
||||
## Progress Tracking
|
||||
|
||||
{Track progress through the task}
|
||||
|
||||
- [ ] Context loaded and understood
|
||||
- [ ] {step 1}
|
||||
- [ ] {step 2}
|
||||
- [ ] {step 3}
|
||||
- [ ] Validation passed
|
||||
- [ ] Documentation updated
|
||||
|
||||
---
|
||||
|
||||
## Instructions for Subagent
|
||||
|
||||
{Specific, detailed instructions for the subagent}
|
||||
|
||||
**IMPORTANT**:
|
||||
1. Load ALL context files listed in "Relevant Standards" and "Repository-Specific Context" sections BEFORE starting work
|
||||
2. Follow ALL requirements from the loaded context
|
||||
3. Apply naming conventions and file structure requirements
|
||||
4. Validate your work using the validation requirements
|
||||
5. Update progress tracking as you complete steps
|
||||
|
||||
**Your Task**:
|
||||
{Detailed description of what the subagent needs to do}
|
||||
|
||||
**Approach**:
|
||||
{Suggested approach or methodology}
|
||||
|
||||
**Constraints**:
|
||||
{Any additional constraints or notes}
|
||||
|
||||
**Questions/Clarifications**:
|
||||
{Any questions the subagent should consider or clarifications needed}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Instructions
|
||||
|
||||
### When to Create a Context Bundle
|
||||
|
||||
Create a context bundle when:
|
||||
- Delegating to any subagent
|
||||
- Task requires coordination across multiple components
|
||||
- Subagent needs project-specific context
|
||||
- Task has complex requirements or constraints
|
||||
|
||||
### How to Create a Context Bundle
|
||||
|
||||
1. **Create session directory**:
|
||||
```bash
|
||||
mkdir -p .tmp/context/{session-id}
|
||||
```
|
||||
|
||||
2. **Copy template**:
|
||||
```bash
|
||||
cp .opencode/context/openagents-repo/templates/context-bundle-template.md \
|
||||
.tmp/context/{session-id}/bundle.md
|
||||
```
|
||||
|
||||
3. **Fill in all sections**:
|
||||
- Replace all `{placeholders}` with actual values
|
||||
- List specific context files to load (with full paths)
|
||||
- Extract key requirements from loaded context
|
||||
- Define clear success criteria
|
||||
- Provide specific instructions
|
||||
|
||||
4. **Pass to subagent**:
|
||||
```javascript
|
||||
task(
|
||||
subagent_type="{SubagentName}",
|
||||
description="Brief description",
|
||||
prompt="Load context from .tmp/context/{session-id}/bundle.md before starting.
|
||||
|
||||
{Specific task instructions}
|
||||
|
||||
Follow all standards and requirements in the context bundle."
|
||||
)
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
**DO**:
|
||||
- ✅ List context files with full paths (don't duplicate content)
|
||||
- ✅ Extract key requirements from loaded context
|
||||
- ✅ Define binary success criteria (pass/fail)
|
||||
- ✅ Provide specific validation requirements
|
||||
- ✅ Include clear instructions for subagent
|
||||
- ✅ Track progress through the task
|
||||
|
||||
**DON'T**:
|
||||
- ❌ Duplicate full context file content (just reference paths)
|
||||
- ❌ Use vague success criteria ("make it good")
|
||||
- ❌ Skip validation requirements
|
||||
- ❌ Forget to list technical constraints
|
||||
- ❌ Omit file paths for files to create/modify
|
||||
|
||||
### Example Context Bundle
|
||||
|
||||
See `.opencode/context/openagents-repo/examples/context-bundle-example.md` for a complete example.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-21
|
||||
**Version**: 1.0.0
|
||||
39
.opencode/context/openagents-repo/blueprints/navigation.md
Normal file
39
.opencode/context/openagents-repo/blueprints/navigation.md
Normal file
@@ -0,0 +1,39 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Blueprints
|
||||
|
||||
**Purpose**: Blueprint templates and patterns for OpenAgents Control
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/blueprints/
|
||||
├── navigation.md (this file)
|
||||
└── [blueprint files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **View blueprints** | `./` |
|
||||
| **Core concepts** | `../core-concepts/navigation.md` |
|
||||
| **Examples** | `../examples/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Blueprints** → Template patterns for OpenAgents implementations
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Core Concepts** → `../core-concepts/navigation.md`
|
||||
- **Examples** → `../examples/navigation.md`
|
||||
40
.opencode/context/openagents-repo/concepts/navigation.md
Normal file
40
.opencode/context/openagents-repo/concepts/navigation.md
Normal file
@@ -0,0 +1,40 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Concepts
|
||||
|
||||
**Purpose**: Core concepts and ideas for OpenAgents Control
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/concepts/
|
||||
├── navigation.md (this file)
|
||||
└── [concept files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **View concepts** | `./` |
|
||||
| **Core concepts** | `../core-concepts/navigation.md` |
|
||||
| **Guides** | `../guides/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Concepts** → Foundational concepts for OpenAgents
|
||||
**Core Concepts** → Deep dives into core ideas
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Core Concepts** → `../core-concepts/navigation.md`
|
||||
- **Guides** → `../guides/navigation.md`
|
||||
@@ -0,0 +1,133 @@
|
||||
<!-- Context: openagents-repo/concepts | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Subagent Testing Modes
|
||||
|
||||
**Purpose**: Understand the two ways to test subagents (standalone vs delegation)
|
||||
|
||||
**Last Updated**: 2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## Core Concept
|
||||
|
||||
Subagents have **two distinct testing modes** depending on what you're validating:
|
||||
|
||||
1. **Standalone Mode** - Test subagent logic directly (unit testing)
|
||||
2. **Delegation Mode** - Test parent → subagent workflow (integration testing)
|
||||
|
||||
The mode determines which agent runs and how tools are used.
|
||||
|
||||
---
|
||||
|
||||
## Standalone Mode (Unit Testing)
|
||||
|
||||
**Purpose**: Test subagent's logic in isolation
|
||||
|
||||
**Command**:
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --subagent=ContextScout
|
||||
```
|
||||
|
||||
**What Happens**:
|
||||
- Eval framework forces `mode: primary` (overrides `mode: subagent`)
|
||||
- ContextScout runs as the primary agent
|
||||
- ContextScout uses tools directly (glob, read, grep, list)
|
||||
- No parent agent involved
|
||||
|
||||
**Use For**:
|
||||
- Unit testing subagent logic
|
||||
- Debugging tool usage
|
||||
- Feature development
|
||||
- Verifying prompt changes
|
||||
|
||||
**Test Location**: `evals/agents/subagents/core/{subagent}/tests/standalone/`
|
||||
|
||||
---
|
||||
|
||||
## Delegation Mode (Integration Testing)
|
||||
|
||||
**Purpose**: Test real production workflow (parent delegates to subagent)
|
||||
|
||||
**Command**:
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --agent=core/openagent --pattern="delegation/*.yaml"
|
||||
```
|
||||
|
||||
**What Happens**:
|
||||
- OpenAgent runs as primary agent
|
||||
- OpenAgent uses `task` tool to delegate to ContextScout
|
||||
- ContextScout runs with `mode: subagent` (natural mode)
|
||||
- Tests full delegation workflow
|
||||
|
||||
**Use For**:
|
||||
- Integration testing
|
||||
- Validating production behavior
|
||||
- Testing delegation logic
|
||||
- End-to-end workflows
|
||||
|
||||
**Test Location**: `evals/agents/subagents/core/{subagent}/tests/delegation/`
|
||||
|
||||
---
|
||||
|
||||
## Critical Distinction
|
||||
|
||||
| Aspect | Standalone Mode | Delegation Mode |
|
||||
|--------|----------------|-----------------|
|
||||
| **Flag** | `--subagent=NAME` | `--agent=PARENT` |
|
||||
| **Agent Mode** | Forced to `primary` | Natural `subagent` |
|
||||
| **Who Runs** | Subagent directly | Parent → Subagent |
|
||||
| **Tool Usage** | Subagent uses tools | Parent uses `task` tool |
|
||||
| **Tests** | `standalone/*.yaml` | `delegation/*.yaml` |
|
||||
|
||||
**Common Mistake**:
|
||||
```bash
|
||||
# ❌ WRONG - This runs OpenAgent, not ContextScout
|
||||
bun --bun run eval:sdk -- --agent=ContextScout
|
||||
|
||||
# ✅ CORRECT - This runs ContextScout directly
|
||||
bun --bun run eval:sdk -- --subagent=ContextScout
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Verify Correct Mode
|
||||
|
||||
### Standalone Mode Indicators:
|
||||
```
|
||||
⚡ Standalone Test Mode
|
||||
Subagent: contextscout
|
||||
Mode: Forced to 'primary' for direct testing
|
||||
```
|
||||
|
||||
### Delegation Mode Indicators:
|
||||
```
|
||||
Testing agent: core/openagent
|
||||
🎯 PARENT: OpenAgent
|
||||
Delegating to: contextscout
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use Each Mode
|
||||
|
||||
**Use Standalone When**:
|
||||
- Testing subagent's core logic
|
||||
- Debugging why subagent isn't using tools
|
||||
- Validating prompt changes
|
||||
- Quick iteration during development
|
||||
|
||||
**Use Delegation When**:
|
||||
- Testing production workflow
|
||||
- Validating parent → subagent communication
|
||||
- Testing context passing
|
||||
- Integration testing
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `guides/testing-subagents.md` - Step-by-step testing guide
|
||||
- `lookup/subagent-test-commands.md` - Quick command reference
|
||||
- `errors/tool-permission-errors.md` - Common testing issues
|
||||
|
||||
**Reference**: `evals/framework/src/sdk/run-sdk-tests.ts` (mode forcing logic)
|
||||
@@ -0,0 +1,559 @@
|
||||
<!-- Context: openagents-repo/core-concepts/agent-metadata | Priority: critical | Version: 1.0 | Updated: 2026-01-31 -->
|
||||
# Core Concept: Agent Metadata System
|
||||
|
||||
**Purpose**: Understanding the centralized metadata system for OpenAgents Control
|
||||
**Priority**: CRITICAL - Load this before working with agent metadata
|
||||
|
||||
---
|
||||
|
||||
## What Is the Agent Metadata System?
|
||||
|
||||
The agent metadata system separates **OpenCode-compliant agent configuration** from **OpenAgents Control registry metadata**. This solves the problem of OpenCode validation errors when agents contain fields that aren't part of the OpenCode agent schema.
|
||||
|
||||
**Key Principle**: Agent frontmatter contains ONLY valid OpenCode fields. All other metadata lives in a centralized file.
|
||||
|
||||
---
|
||||
|
||||
## The Problem We Solved
|
||||
|
||||
### Before (Validation Errors)
|
||||
|
||||
Agent frontmatter contained fields that OpenCode doesn't recognize:
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: opencoder # ❌ Not valid OpenCode field
|
||||
name: OpenCoder # ❌ Not valid OpenCode field
|
||||
category: core # ❌ Not valid OpenCode field
|
||||
type: core # ❌ Not valid OpenCode field
|
||||
version: 1.0.0 # ❌ Not valid OpenCode field
|
||||
author: opencode # ❌ Not valid OpenCode field
|
||||
tags: [development, coding] # ❌ Not valid OpenCode field
|
||||
dependencies: [] # ❌ Not valid OpenCode field
|
||||
description: "..." # ✅ Valid OpenCode field
|
||||
mode: primary # ✅ Valid OpenCode field
|
||||
temperature: 0.1 # ✅ Valid OpenCode field
|
||||
tools: {...} # ✅ Valid OpenCode field
|
||||
permission: {...} # ✅ Valid OpenCode field
|
||||
---
|
||||
```
|
||||
|
||||
**Result**: OpenCode validation errors:
|
||||
```
|
||||
Extra inputs are not permitted, field: 'id', value: 'opencoder'
|
||||
Extra inputs are not permitted, field: 'category', value: 'core'
|
||||
Extra inputs are not permitted, field: 'type', value: 'core'
|
||||
... (9 validation errors)
|
||||
```
|
||||
|
||||
### After (Clean Separation)
|
||||
|
||||
**Agent frontmatter** (`.opencode/agent/core/opencoder.md`):
|
||||
```yaml
|
||||
---
|
||||
# Metadata stored in: .opencode/config/agent-metadata.json
|
||||
description: "Orchestration agent for complex coding, architecture, and multi-file refactoring"
|
||||
mode: primary
|
||||
temperature: 0.1
|
||||
tools: {...}
|
||||
permission: {...}
|
||||
---
|
||||
```
|
||||
|
||||
**Centralized metadata** (`.opencode/config/agent-metadata.json`):
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"opencoder": {
|
||||
"id": "opencoder",
|
||||
"name": "OpenCoder",
|
||||
"category": "core",
|
||||
"type": "agent",
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"tags": ["development", "coding", "implementation"],
|
||||
"dependencies": [
|
||||
"subagent:documentation",
|
||||
"subagent:coder-agent",
|
||||
"context:core/standards/code"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Result**: ✅ No validation errors, clean separation of concerns
|
||||
|
||||
---
|
||||
|
||||
## Valid OpenCode Agent Fields
|
||||
|
||||
Based on [OpenCode documentation](https://opencode.ai/docs/agents/), these are the ONLY valid frontmatter fields:
|
||||
|
||||
### Required Fields
|
||||
- `description` - When to use this agent (required)
|
||||
- `mode` - Agent type: `primary`, `subagent`, or `all` (defaults to `all`)
|
||||
|
||||
### Optional Fields
|
||||
- `model` - Model override (e.g., `anthropic/claude-sonnet-4-20250514`)
|
||||
- `temperature` - Response randomness (0.0-1.0)
|
||||
- `maxSteps` - Max agentic iterations
|
||||
- `disable` - Set to `true` to disable agent
|
||||
- `prompt` - Custom prompt file path (e.g., `{file:./prompts/build.txt}`)
|
||||
- `hidden` - Hide from @ autocomplete (subagents only)
|
||||
- `tools` - Tool access configuration
|
||||
- `permission` - Permission rules for tools (v1.1.1+, replaces deprecated `permissions`)
|
||||
|
||||
### Example Valid Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "Code review agent with security focus"
|
||||
mode: subagent
|
||||
model: anthropic/claude-sonnet-4-20250514
|
||||
temperature: 0.1
|
||||
tools:
|
||||
read: true
|
||||
grep: true
|
||||
glob: true
|
||||
write: false
|
||||
edit: false
|
||||
permission: # v1.1.1+ (singular, not plural)
|
||||
bash:
|
||||
"*": ask
|
||||
"git *": allow
|
||||
edit: deny
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Centralized Metadata File
|
||||
|
||||
**Location**: `.opencode/config/agent-metadata.json`
|
||||
|
||||
### Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/schemas/agent-metadata.json",
|
||||
"schema_version": "1.0.0",
|
||||
"description": "Centralized metadata for OpenAgents Control agents",
|
||||
"agents": {
|
||||
"agent-id": {
|
||||
"id": "agent-id",
|
||||
"name": "Agent Name",
|
||||
"category": "core|development|content|data|product|learning|meta",
|
||||
"type": "agent|subagent",
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"dependencies": [
|
||||
"subagent:subagent-id",
|
||||
"context:path/to/context"
|
||||
]
|
||||
}
|
||||
},
|
||||
"defaults": {
|
||||
"agent": {
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"type": "agent",
|
||||
"tags": []
|
||||
},
|
||||
"subagent": {
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"type": "subagent",
|
||||
"tags": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Metadata Fields
|
||||
|
||||
| Field | Required | Description | Example |
|
||||
|-------|----------|-------------|---------|
|
||||
| `id` | Yes | Unique identifier (kebab-case) | `"opencoder"` |
|
||||
| `name` | Yes | Display name | `"OpenCoder"` |
|
||||
| `category` | Yes | Agent category | `"core"` |
|
||||
| `type` | Yes | Component type | `"agent"` or `"subagent"` |
|
||||
| `version` | Yes | Version number | `"1.0.0"` |
|
||||
| `author` | Yes | Author identifier | `"opencode"` |
|
||||
| `tags` | No | Discovery tags | `["development", "coding"]` |
|
||||
| `dependencies` | No | Component dependencies | `["subagent:tester"]` |
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Agent Creation
|
||||
|
||||
When creating a new agent:
|
||||
|
||||
**Step 1**: Create agent file with ONLY valid OpenCode fields
|
||||
|
||||
```bash
|
||||
# Create agent file
|
||||
touch .opencode/agent/category/my-agent.md
|
||||
```
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "My agent description"
|
||||
mode: subagent
|
||||
temperature: 0.2
|
||||
tools:
|
||||
read: true
|
||||
write: true
|
||||
---
|
||||
|
||||
# Agent prompt content here
|
||||
```
|
||||
|
||||
**Step 2**: Add metadata to `.opencode/config/agent-metadata.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"my-agent": {
|
||||
"id": "my-agent",
|
||||
"name": "My Agent",
|
||||
"category": "development",
|
||||
"type": "subagent",
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"tags": ["custom", "helper"],
|
||||
"dependencies": ["context:core/standards/code"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3**: Run auto-detect to update registry
|
||||
|
||||
```bash
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
The auto-detect script:
|
||||
1. Reads frontmatter from agent file (description, mode, etc.)
|
||||
2. Reads metadata from `agent-metadata.json` (id, name, tags, dependencies)
|
||||
3. Merges both into registry.json entry
|
||||
|
||||
### 2. Auto-Detect Integration
|
||||
|
||||
The auto-detect script (`scripts/registry/auto-detect-components.sh`) has been enhanced to:
|
||||
|
||||
1. **Extract frontmatter** - Read description from agent file
|
||||
2. **Lookup metadata** - Check `agent-metadata.json` for agent ID
|
||||
3. **Merge data** - Combine frontmatter + metadata
|
||||
4. **Update registry** - Write complete entry to registry.json
|
||||
|
||||
**Code snippet** (from auto-detect script):
|
||||
|
||||
```bash
|
||||
# Check if agent-metadata.json exists and merge metadata from it
|
||||
local metadata_file="$REPO_ROOT/.opencode/config/agent-metadata.json"
|
||||
if [ -f "$metadata_file" ] && command -v jq &> /dev/null; then
|
||||
# Try to find metadata for this agent ID
|
||||
local metadata_entry
|
||||
metadata_entry=$(jq -r ".agents[\"$id\"] // empty" "$metadata_file" 2>/dev/null)
|
||||
|
||||
if [ -n "$metadata_entry" ] && [ "$metadata_entry" != "null" ]; then
|
||||
# Merge name, tags, dependencies from metadata
|
||||
# ...
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
### 3. Registry Output
|
||||
|
||||
The registry.json entry contains merged data:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "opencoder",
|
||||
"name": "OpenCoder",
|
||||
"type": "agent",
|
||||
"path": ".opencode/agent/core/opencoder.md",
|
||||
"description": "Orchestration agent for complex coding...",
|
||||
"category": "core",
|
||||
"tags": ["development", "coding", "implementation"],
|
||||
"dependencies": [
|
||||
"subagent:documentation",
|
||||
"subagent:coder-agent",
|
||||
"context:core/standards/code"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Adding a New Agent
|
||||
|
||||
```bash
|
||||
# 1. Create agent file (OpenCode-compliant frontmatter only)
|
||||
vim .opencode/agent/category/my-agent.md
|
||||
|
||||
# 2. Add metadata entry
|
||||
vim .opencode/config/agent-metadata.json
|
||||
|
||||
# 3. Update registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# 4. Validate
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
### Updating Agent Metadata
|
||||
|
||||
**To update OpenCode configuration** (tools, permissions, temperature):
|
||||
```bash
|
||||
# Edit agent file frontmatter
|
||||
vim .opencode/agent/category/my-agent.md
|
||||
```
|
||||
|
||||
**To update registry metadata** (tags, dependencies, version):
|
||||
```bash
|
||||
# Edit metadata file
|
||||
vim .opencode/config/agent-metadata.json
|
||||
|
||||
# Re-run auto-detect
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
### Updating Dependencies
|
||||
|
||||
**Add a dependency**:
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"my-agent": {
|
||||
"dependencies": [
|
||||
"subagent:tester",
|
||||
"context:core/standards/code",
|
||||
"subagent:new-dependency" // ← Add here
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then run:
|
||||
```bash
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### ✅ OpenCode Compliance
|
||||
- Agent frontmatter contains ONLY valid OpenCode fields
|
||||
- No validation errors from OpenCode
|
||||
- Agents work correctly with OpenCode CLI
|
||||
|
||||
### ✅ Registry Compatibility
|
||||
- Registry still has all metadata (id, name, category, tags, dependencies)
|
||||
- Auto-detect script merges frontmatter + metadata
|
||||
- Backward compatible with existing tools
|
||||
|
||||
### ✅ Single Source of Truth
|
||||
- Metadata centralized in one file
|
||||
- Easy to update dependencies across multiple agents
|
||||
- Clear separation: OpenCode config vs. registry metadata
|
||||
|
||||
### ✅ Maintainability
|
||||
- Update dependencies in one place
|
||||
- Consistent metadata across all agents
|
||||
- Easy to add new metadata fields
|
||||
|
||||
### ✅ Validation
|
||||
- OpenCode validates frontmatter (no extra fields)
|
||||
- Registry validator checks dependencies exist
|
||||
- Clear error messages when metadata is missing
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Migrating from permissions (plural) to permission (singular)
|
||||
|
||||
**OpenCode v1.1.1+ Change**: The field name changed from `permissions:` (plural) to `permission:` (singular).
|
||||
|
||||
**Before** (deprecated):
|
||||
```yaml
|
||||
permissions:
|
||||
bash:
|
||||
"*": "deny"
|
||||
```
|
||||
|
||||
**After** (v1.1.1+):
|
||||
```yaml
|
||||
permission:
|
||||
bash:
|
||||
"*": "deny"
|
||||
```
|
||||
|
||||
**Migration Steps**:
|
||||
1. Find all agents using `permissions:` (plural)
|
||||
```bash
|
||||
grep -r "^permissions:" .opencode/agent/
|
||||
```
|
||||
|
||||
2. Replace with `permission:` (singular) in each file
|
||||
|
||||
3. Verify no validation errors:
|
||||
```bash
|
||||
opencode agent validate
|
||||
```
|
||||
|
||||
### Migrating Existing Agents
|
||||
|
||||
**Step 1**: Identify agents with extra fields
|
||||
|
||||
```bash
|
||||
# Find agents with invalid OpenCode fields
|
||||
grep -r "^id:\|^name:\|^category:\|^type:\|^version:\|^author:\|^tags:\|^dependencies:" .opencode/agent/
|
||||
```
|
||||
|
||||
**Step 2**: Extract metadata to `agent-metadata.json`
|
||||
|
||||
For each agent:
|
||||
1. Copy `id`, `name`, `category`, `type`, `version`, `author`, `tags`, `dependencies` to metadata file
|
||||
2. Remove these fields from agent frontmatter
|
||||
3. Keep ONLY valid OpenCode fields in frontmatter
|
||||
|
||||
**Step 3**: Update registry
|
||||
|
||||
```bash
|
||||
# Remove old entries
|
||||
jq 'del(.components.agents[] | select(.id == "agent-id"))' registry.json > tmp.json && mv tmp.json registry.json
|
||||
|
||||
# Re-add with new metadata
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
**Step 4**: Validate
|
||||
|
||||
```bash
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Agent Frontmatter
|
||||
|
||||
✅ **DO**:
|
||||
- Keep frontmatter minimal (only OpenCode fields)
|
||||
- Add comment pointing to metadata file
|
||||
- Use consistent formatting
|
||||
|
||||
❌ **DON'T**:
|
||||
- Add custom fields to frontmatter
|
||||
- Duplicate metadata in both places
|
||||
- Skip the metadata file
|
||||
|
||||
### Metadata File
|
||||
|
||||
✅ **DO**:
|
||||
- Keep metadata file in version control
|
||||
- Update metadata when adding/removing dependencies
|
||||
- Use consistent naming (kebab-case for IDs)
|
||||
- Document why dependencies exist
|
||||
|
||||
❌ **DON'T**:
|
||||
- Forget to update metadata when creating agents
|
||||
- Leave orphaned entries (agents that don't exist)
|
||||
- Skip validation after updates
|
||||
|
||||
### Dependencies
|
||||
|
||||
✅ **DO**:
|
||||
- Declare ALL dependencies (subagents, contexts)
|
||||
- Use correct format: `type:id`
|
||||
- Validate dependencies exist in registry
|
||||
|
||||
❌ **DON'T**:
|
||||
- Reference components without declaring dependency
|
||||
- Use invalid dependency formats
|
||||
- Forget to update when dependencies change
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### OpenCode Validation Errors
|
||||
|
||||
**Problem**: `Extra inputs are not permitted, field: 'id'`
|
||||
|
||||
**Solution**: Remove invalid fields from agent frontmatter, add to metadata file
|
||||
|
||||
```bash
|
||||
# 1. Edit agent file - remove id, name, category, type, version, author, tags, dependencies
|
||||
vim .opencode/agent/category/agent.md
|
||||
|
||||
# 2. Add to metadata file
|
||||
vim .opencode/config/agent-metadata.json
|
||||
|
||||
# 3. Update registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
### Missing Metadata
|
||||
|
||||
**Problem**: Auto-detect can't find metadata for agent
|
||||
|
||||
**Solution**: Add entry to `agent-metadata.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"agent-id": {
|
||||
"id": "agent-id",
|
||||
"name": "Agent Name",
|
||||
"category": "core",
|
||||
"type": "agent",
|
||||
"version": "1.0.0",
|
||||
"author": "opencode",
|
||||
"tags": [],
|
||||
"dependencies": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Registry Out of Sync
|
||||
|
||||
**Problem**: Registry has old metadata
|
||||
|
||||
**Solution**: Remove entry and re-run auto-detect
|
||||
|
||||
```bash
|
||||
# Remove old entry
|
||||
jq 'del(.components.agents[] | select(.id == "agent-id"))' registry.json > tmp.json && mv tmp.json registry.json
|
||||
|
||||
# Re-add with current metadata
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **OpenCode Agent Docs**: https://opencode.ai/docs/agents/
|
||||
- **Registry System**: `.opencode/context/openagents-repo/core-concepts/registry.md`
|
||||
- **Adding Agents**: `.opencode/context/openagents-repo/guides/adding-agent-basics.md`
|
||||
- **Dependencies**: `.opencode/context/openagents-repo/quality/registry-dependencies.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-31
|
||||
**Version**: 1.0.0
|
||||
364
.opencode/context/openagents-repo/core-concepts/agents.md
Normal file
364
.opencode/context/openagents-repo/core-concepts/agents.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# Core Concept: Agents
|
||||
|
||||
**Purpose**: Understanding how agents work in OpenAgents Control
|
||||
**Priority**: CRITICAL - Load this before working with agents
|
||||
|
||||
---
|
||||
|
||||
## What Are Agents?
|
||||
|
||||
Agents are AI prompt files that define specialized behaviors for different tasks. They are:
|
||||
- **Markdown files** with frontmatter metadata
|
||||
- **Category-organized** by domain (core, development, content, etc.)
|
||||
- **Context-aware** - load relevant context files
|
||||
- **Testable** - validated through eval framework
|
||||
|
||||
---
|
||||
|
||||
## Agent Structure
|
||||
|
||||
### File Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: "Brief description of what this agent does"
|
||||
category: "category-name"
|
||||
type: "agent"
|
||||
tags: ["tag1", "tag2"]
|
||||
dependencies: ["subagent:tester"]
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
[Agent prompt content - instructions, workflows, constraints]
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **Frontmatter** (YAML metadata)
|
||||
- `description`: Brief description
|
||||
- `category`: Category name (core, development, content, etc.)
|
||||
- `type`: Always "agent"
|
||||
- `tags`: Optional tags for discovery
|
||||
- `dependencies`: Optional dependencies (e.g., subagents)
|
||||
|
||||
2. **Prompt Content**
|
||||
- Instructions and workflows
|
||||
- Constraints and rules
|
||||
- Context loading requirements
|
||||
- Tool usage patterns
|
||||
|
||||
---
|
||||
|
||||
## Category System
|
||||
|
||||
Agents are organized by domain expertise:
|
||||
|
||||
### Core Category (`core/`)
|
||||
**Purpose**: Essential system agents (always available)
|
||||
|
||||
Agents:
|
||||
- `openagent.md` - General-purpose orchestrator
|
||||
- `opencoder.md` - Development specialist
|
||||
- `system-builder.md` - System generation
|
||||
|
||||
**When to use**: System-level tasks, orchestration
|
||||
|
||||
---
|
||||
|
||||
### Development Category (`development/`)
|
||||
**Purpose**: Software development specialists
|
||||
|
||||
Agents:
|
||||
- `frontend-specialist.md` - React, Vue, modern CSS
|
||||
- `devops-specialist.md` - CI/CD, deployment, infrastructure
|
||||
|
||||
**When to use**: Building applications, dev tasks
|
||||
|
||||
---
|
||||
|
||||
### Content Category (`content/`)
|
||||
**Purpose**: Content creation specialists
|
||||
|
||||
Agents:
|
||||
- `copywriter.md` - Marketing copy, persuasive writing
|
||||
- `technical-writer.md` - Documentation, technical content
|
||||
|
||||
**When to use**: Writing, documentation, marketing
|
||||
|
||||
---
|
||||
|
||||
### Data Category (`data/`)
|
||||
**Purpose**: Data analysis specialists
|
||||
|
||||
Agents:
|
||||
- `data-analyst.md` - Data analysis, visualization
|
||||
|
||||
**When to use**: Data tasks, analysis, reporting
|
||||
|
||||
---
|
||||
|
||||
### Product Category (`product/`)
|
||||
**Purpose**: Product management specialists
|
||||
|
||||
**Status**: Ready for agents (no agents yet)
|
||||
|
||||
**When to use**: Product strategy, roadmaps, requirements
|
||||
|
||||
---
|
||||
|
||||
### Learning Category (`learning/`)
|
||||
**Purpose**: Education and coaching specialists
|
||||
|
||||
**Status**: Ready for agents (no agents yet)
|
||||
|
||||
**When to use**: Teaching, training, curriculum
|
||||
|
||||
---
|
||||
|
||||
## Subagents
|
||||
|
||||
**Location**: `.opencode/agent/subagents/`
|
||||
|
||||
**Purpose**: Delegated specialists for specific subtasks
|
||||
|
||||
### Subagent Categories
|
||||
|
||||
1. **code/** - Code-related specialists
|
||||
- `tester.md` - Test authoring and TDD
|
||||
- `reviewer.md` - Code review and security
|
||||
- `coder-agent.md` - Focused implementations
|
||||
- `build-agent.md` - Type checking and builds
|
||||
|
||||
2. **core/** - Core workflow specialists
|
||||
- `task-manager.md` - Task breakdown and management
|
||||
- `documentation.md` - Documentation generation
|
||||
|
||||
3. **system-builder/** - System generation specialists
|
||||
- `agent-generator.md` - Generate agent files
|
||||
- `command-creator.md` - Create slash commands
|
||||
- `domain-analyzer.md` - Analyze domains
|
||||
- `context-organizer.md` - Organize context
|
||||
- `workflow-designer.md` - Design workflows
|
||||
|
||||
4. **utils/** - Utility specialists
|
||||
- `image-specialist.md` - Image editing and analysis
|
||||
|
||||
### Subagents vs Category Agents
|
||||
|
||||
| Aspect | Category Agents | Subagents |
|
||||
|--------|----------------|-----------|
|
||||
| **Purpose** | User-facing specialists | Delegated subtasks |
|
||||
| **Invocation** | Direct by user | Via task tool |
|
||||
| **Scope** | Broad domain | Narrow focus |
|
||||
| **Example** | `frontend-specialist` | `tester` |
|
||||
|
||||
---
|
||||
|
||||
## Claude Code Interop (Optional)
|
||||
|
||||
OpenAgents Control can pair with Claude Code for local workflows and distribution:
|
||||
|
||||
- **Subagents**: Project helpers in `.claude/agents/`
|
||||
- **Skills**: Auto-invoked guidance in `.claude/skills/`
|
||||
- **Hooks**: Shell commands on lifecycle events (use sparingly)
|
||||
- **Plugins**: Share agents/skills/hooks across projects
|
||||
|
||||
Use this when you want Claude Code to follow OpenAgents Control standards or to ship reusable helpers.
|
||||
|
||||
---
|
||||
|
||||
## Path Resolution
|
||||
|
||||
The system supports multiple path formats for backward compatibility:
|
||||
|
||||
### Supported Formats
|
||||
|
||||
```bash
|
||||
# Short ID (backward compatible)
|
||||
"openagent" → resolves to → ".opencode/agent/core/openagent.md"
|
||||
|
||||
# Category path
|
||||
"core/openagent" → resolves to → ".opencode/agent/core/openagent.md"
|
||||
|
||||
# Full category path
|
||||
"development/frontend-specialist" → resolves to → ".opencode/agent/subagents/development/frontend-specialist.md"
|
||||
|
||||
# Subagent path
|
||||
"TestEngineer" → resolves to → ".opencode/agent/subagents/code/test-engineer.md"
|
||||
```
|
||||
|
||||
### Resolution Rules
|
||||
|
||||
1. Check if path includes `/` → use as category path
|
||||
2. If no `/` → check core/ first (backward compat)
|
||||
3. If not in core/ → search all categories
|
||||
4. If not found → error
|
||||
|
||||
---
|
||||
|
||||
## Prompt Variants
|
||||
|
||||
**Location**: `.opencode/prompts/{category}/{agent}/`
|
||||
|
||||
**Purpose**: Model-specific prompt optimizations
|
||||
|
||||
### Supported Models
|
||||
|
||||
- `gemini.md` - Google Gemini optimizations
|
||||
- `grok.md` - xAI Grok optimizations
|
||||
- `llama.md` - Meta Llama optimizations
|
||||
- `openrouter.md` - OpenRouter optimizations
|
||||
|
||||
### When to Create Variants
|
||||
|
||||
- Model has specific formatting requirements
|
||||
- Model performs better with different structure
|
||||
- Model has unique capabilities to leverage
|
||||
|
||||
### Fallback Behavior
|
||||
|
||||
If no variant exists for a model, the base agent file is used.
|
||||
|
||||
---
|
||||
|
||||
## Context Loading
|
||||
|
||||
Agents should load relevant context files based on task type:
|
||||
|
||||
### Core Context (Always Consider)
|
||||
|
||||
```markdown
|
||||
<!-- Context: standards/code | Priority: critical -->
|
||||
```
|
||||
|
||||
Loads: `.opencode/context/core/standards/code-quality.md`
|
||||
|
||||
### Category Context
|
||||
|
||||
```markdown
|
||||
<!-- Context: development/react-patterns | Priority: high -->
|
||||
```
|
||||
|
||||
Loads: `.opencode/context/ui/web/react-patterns.md`
|
||||
|
||||
### Multiple Contexts
|
||||
|
||||
```markdown
|
||||
<!-- Context: standards/code, standards/tests | Priority: critical -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Lifecycle
|
||||
|
||||
### 1. Creation
|
||||
```bash
|
||||
# Create agent file
|
||||
touch .opencode/agent/{category}/{agent-name}.md
|
||||
|
||||
# Add frontmatter and content
|
||||
# (See guides/adding-agent.md for details)
|
||||
```
|
||||
|
||||
### 2. Testing
|
||||
```bash
|
||||
# Create test structure
|
||||
mkdir -p evals/agents/{category}/{agent-name}/{config,tests}
|
||||
|
||||
# Run tests
|
||||
cd evals/framework && bun --bun run eval:sdk -- --agent={category}/{agent-name}
|
||||
```
|
||||
|
||||
### 3. Registration
|
||||
```bash
|
||||
# Auto-detect and add to registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# Validate
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
### 4. Distribution
|
||||
```bash
|
||||
# Users install via install.sh
|
||||
./install.sh {profile}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Agent Design
|
||||
|
||||
✅ **Single responsibility** - One domain, one agent
|
||||
✅ **Clear instructions** - Explicit workflows and constraints
|
||||
✅ **Context-aware** - Load relevant context files
|
||||
✅ **Testable** - Include eval tests
|
||||
✅ **Well-documented** - Clear description and usage
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- **Category agents**: `{domain}-specialist.md` (e.g., `frontend-specialist.md`)
|
||||
- **Core agents**: `{name}.md` (e.g., `openagent.md`)
|
||||
- **Subagents**: `{purpose}.md` (e.g., `tester.md`)
|
||||
|
||||
### Frontmatter Requirements
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "Required - brief description"
|
||||
category: "Required - category name"
|
||||
type: "Required - always 'agent'"
|
||||
tags: ["Optional - for discovery"]
|
||||
dependencies: ["Optional - e.g., 'subagent:tester'"]
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Delegation to Subagents
|
||||
|
||||
```markdown
|
||||
When task requires testing:
|
||||
1. Implement feature
|
||||
2. Delegate to TestEngineer for test creation
|
||||
```
|
||||
|
||||
### Context Loading
|
||||
|
||||
```markdown
|
||||
Before implementing:
|
||||
1. Load core/standards/code-quality.md
|
||||
2. Load category-specific context if available
|
||||
3. Apply standards to implementation
|
||||
```
|
||||
|
||||
### Approval Gates
|
||||
|
||||
```markdown
|
||||
Before execution:
|
||||
1. Present plan to user
|
||||
2. Request approval
|
||||
3. Execute incrementally
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Adding agents**: `guides/adding-agent.md`
|
||||
- **Testing agents**: `guides/testing-agent.md`
|
||||
- **Category system**: `core-concepts/categories.md`
|
||||
- **File locations**: `lookup/file-locations.md`
|
||||
- **Claude Code subagents**: `../to-be-consumed/claude-code-docs/create-subagents.md`
|
||||
- **Claude Code skills**: `../to-be-consumed/claude-code-docs/agent-skills.md`
|
||||
- **Claude Code hooks**: `../to-be-consumed/claude-code-docs/hooks.md`
|
||||
- **Claude Code plugins**: `../to-be-consumed/claude-code-docs/plugins.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-13
|
||||
**Version**: 0.5.1
|
||||
428
.opencode/context/openagents-repo/core-concepts/categories.md
Normal file
428
.opencode/context/openagents-repo/core-concepts/categories.md
Normal file
@@ -0,0 +1,428 @@
|
||||
# Core Concept: Category System
|
||||
|
||||
**Purpose**: Understanding how components are organized
|
||||
**Priority**: HIGH - Load this before adding categories or organizing components
|
||||
|
||||
---
|
||||
|
||||
## What Are Categories?
|
||||
|
||||
Categories are domain-based groupings that organize agents, context files, and tests by expertise area.
|
||||
|
||||
**Benefits**:
|
||||
- **Scalability** - Easy to add new domains
|
||||
- **Discovery** - Find agents by domain
|
||||
- **Organization** - Clear structure
|
||||
- **Modularity** - Install only what you need
|
||||
|
||||
---
|
||||
|
||||
## Available Categories
|
||||
|
||||
### Core (`core/`)
|
||||
**Purpose**: Essential system agents (always available)
|
||||
|
||||
**Agents**:
|
||||
|
||||
**When to use**: System-level tasks, orchestration, coding (simple or complex)
|
||||
|
||||
**Status**: ✅ Stable
|
||||
|
||||
---
|
||||
|
||||
### Development Subagents (`subagents/development/`)
|
||||
**Purpose**: Domain-specific development specialists (invoked by core agents)
|
||||
|
||||
**Subagents**:
|
||||
- frontend-specialist, devops-specialist
|
||||
|
||||
**Context**:
|
||||
- clean-code.md, react-patterns.md, api-design.md
|
||||
|
||||
**When to use**: Delegated frontend, backend, or DevOps tasks within a larger workflow
|
||||
|
||||
**Status**: ✅ Active
|
||||
|
||||
---
|
||||
|
||||
### Content (`content/`)
|
||||
**Purpose**: Content creation specialists
|
||||
|
||||
**Agents**:
|
||||
- copywriter, technical-writer
|
||||
|
||||
**Context**:
|
||||
- copywriting-frameworks.md
|
||||
- tone-voice.md
|
||||
- audience-targeting.md
|
||||
- hooks.md
|
||||
|
||||
**When to use**: Writing, documentation, marketing
|
||||
|
||||
**Status**: ✅ Active
|
||||
|
||||
---
|
||||
|
||||
### Data (`data/`)
|
||||
**Purpose**: Data analysis specialists
|
||||
|
||||
**Agents**:
|
||||
- data-analyst
|
||||
|
||||
**Context**:
|
||||
- (Ready for data-specific context)
|
||||
|
||||
**When to use**: Data tasks, analysis, reporting
|
||||
|
||||
**Status**: ✅ Active
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Category Structure
|
||||
|
||||
### Directory Layout
|
||||
|
||||
```
|
||||
.opencode/
|
||||
├── agent/{category}/ # Agents by category
|
||||
├── context/{category}/ # Context by category
|
||||
├── prompts/{category}/ # Prompt variants by category
|
||||
evals/agents/{category}/ # Tests by category
|
||||
```
|
||||
|
||||
### Example: Core Agents + Development Subagents
|
||||
|
||||
```
|
||||
.opencode/agent/core/
|
||||
├── 0-category.json # Category metadata
|
||||
├── openagent.md
|
||||
├── opencoder.md
|
||||
|
||||
.opencode/agent/subagents/development/
|
||||
├── 0-category.json # Subagent category metadata
|
||||
├── frontend-specialist.md
|
||||
└── devops-specialist.md
|
||||
|
||||
.opencode/context/development/
|
||||
├── navigation.md
|
||||
├── clean-code.md
|
||||
├── react-patterns.md
|
||||
└── api-design.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Category Metadata
|
||||
|
||||
### 0-category.json
|
||||
|
||||
Each category has a metadata file:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Development",
|
||||
"description": "Software development specialists",
|
||||
"icon": "💻",
|
||||
"order": 2,
|
||||
"status": "active"
|
||||
}
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `name`: Display name
|
||||
- `description`: Brief description
|
||||
- `icon`: Emoji icon
|
||||
- `order`: Display order
|
||||
- `status`: active, ready, planned
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Category Names
|
||||
|
||||
✅ **Lowercase** - `development`, not `Development`
|
||||
✅ **Singular** - `content`, not `contents`
|
||||
✅ **Descriptive** - Clear domain name
|
||||
✅ **Consistent** - Follow existing patterns
|
||||
|
||||
### Agent Names
|
||||
|
||||
✅ **Kebab-case** - `frontend-specialist.md`
|
||||
✅ **Descriptive** - Clear purpose
|
||||
✅ **Suffix** - Use `-specialist`, `-agent`, `-writer` as appropriate
|
||||
|
||||
### Context Names
|
||||
|
||||
✅ **Kebab-case** - `react-patterns.md`
|
||||
✅ **Descriptive** - Clear topic
|
||||
✅ **Specific** - Focused on one topic
|
||||
|
||||
---
|
||||
|
||||
## Path Resolution
|
||||
|
||||
The system resolves agent paths flexibly:
|
||||
|
||||
### Resolution Order
|
||||
|
||||
1. **Check for `/`** - If present, treat as category path
|
||||
2. **Check core/** - For backward compatibility
|
||||
3. **Search categories** - Look in all categories
|
||||
4. **Error** - If not found
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Short ID (backward compatible)
|
||||
"openagent" → ".opencode/agent/core/openagent.md"
|
||||
|
||||
# Subagent path
|
||||
"subagents/development/frontend-specialist" → ".opencode/agent/subagents/development/frontend-specialist.md"
|
||||
|
||||
# Subagent path
|
||||
"TestEngineer" → ".opencode/agent/subagents/code/test-engineer.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding a New Category
|
||||
|
||||
### Step 1: Create Directory Structure
|
||||
|
||||
```bash
|
||||
# Create agent directory
|
||||
mkdir -p .opencode/agent/{category}
|
||||
|
||||
# Create context directory
|
||||
mkdir -p .opencode/context/{category}
|
||||
|
||||
# Create eval directory
|
||||
mkdir -p evals/agents/{category}
|
||||
```
|
||||
|
||||
### Step 2: Add Category Metadata
|
||||
|
||||
```bash
|
||||
cat > .opencode/agent/{category}/0-category.json << 'EOF'
|
||||
{
|
||||
"name": "Category Name",
|
||||
"description": "Brief description",
|
||||
"icon": "🎯",
|
||||
"order": 10,
|
||||
"status": "ready"
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 3: Add Context README
|
||||
|
||||
```bash
|
||||
cat > .opencode/context/{category}/navigation.md << 'EOF'
|
||||
# Category Name Context
|
||||
|
||||
Context files for {category} specialists.
|
||||
|
||||
## Available Context
|
||||
|
||||
- (List context files here)
|
||||
|
||||
## When to Use
|
||||
|
||||
- (Describe when to use this context)
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 4: Validate
|
||||
|
||||
```bash
|
||||
# Validate structure
|
||||
./scripts/registry/validate-component.sh
|
||||
|
||||
# Update registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Category Guidelines
|
||||
|
||||
### When to Create a New Category
|
||||
|
||||
✅ **Distinct domain** - Clear expertise area
|
||||
✅ **Multiple agents** - Plan for 2+ agents
|
||||
✅ **Shared context** - Common knowledge to share
|
||||
✅ **User demand** - Requested by users
|
||||
|
||||
### When NOT to Create a Category
|
||||
|
||||
❌ **Single agent** - Use existing category
|
||||
❌ **Overlapping** - Fits in existing category
|
||||
❌ **Too specific** - Too narrow focus
|
||||
❌ **Unclear domain** - Not well-defined
|
||||
|
||||
---
|
||||
|
||||
## Category vs Subagent
|
||||
|
||||
### Use Category Agent When:
|
||||
- User-facing specialist
|
||||
- Broad domain expertise
|
||||
- Direct invocation by user
|
||||
- Example: `frontend-specialist`
|
||||
|
||||
### Use Subagent When:
|
||||
- Delegated subtask
|
||||
- Narrow focus
|
||||
- Invoked by other agents
|
||||
- Example: `tester`
|
||||
|
||||
---
|
||||
|
||||
## Context Organization
|
||||
|
||||
### Category Context Structure
|
||||
|
||||
```
|
||||
.opencode/context/{category}/
|
||||
├── navigation.md # Overview
|
||||
├── {topic-1}.md # Specific topic
|
||||
├── {topic-2}.md # Specific topic
|
||||
└── {topic-3}.md # Specific topic
|
||||
```
|
||||
|
||||
### Context Loading
|
||||
|
||||
Agents load category context based on task:
|
||||
|
||||
```markdown
|
||||
<!-- Context: development/react-patterns | Priority: high -->
|
||||
```
|
||||
|
||||
Loads: `.opencode/context/ui/web/react-patterns.md`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Organization
|
||||
|
||||
✅ **Clear categories** - Well-defined domains
|
||||
✅ **Consistent naming** - Follow conventions
|
||||
✅ **Proper metadata** - Complete 0-category.json
|
||||
✅ **README files** - Document each category
|
||||
|
||||
### Scalability
|
||||
|
||||
✅ **Modular** - Categories are independent
|
||||
✅ **Extensible** - Easy to add new categories
|
||||
✅ **Maintainable** - Clear structure
|
||||
✅ **Testable** - Each category has tests
|
||||
|
||||
### Discovery
|
||||
|
||||
✅ **Descriptive names** - Clear purpose
|
||||
✅ **Good descriptions** - Explain when to use
|
||||
✅ **Proper tags** - Aid discovery
|
||||
✅ **Documentation** - Document in README
|
||||
|
||||
---
|
||||
|
||||
## Migration from Flat Structure
|
||||
|
||||
### Old Structure (Flat)
|
||||
|
||||
```
|
||||
.opencode/agent/
|
||||
├── openagent.md
|
||||
├── opencoder.md
|
||||
├── frontend-specialist.md
|
||||
└── copywriter.md
|
||||
```
|
||||
|
||||
### New Structure (Category-Based)
|
||||
|
||||
```
|
||||
.opencode/agent/
|
||||
├── core/
|
||||
│ ├── openagent.md
|
||||
│ ├── opencoder.md
|
||||
├── subagents/
|
||||
│ ├── development/
|
||||
│ │ ├── frontend-specialist.md
|
||||
│ │ └── devops-specialist.md
|
||||
│ └── code/
|
||||
│ ├── coder-agent.md
|
||||
│ └── tester.md
|
||||
└── content/
|
||||
└── copywriter.md
|
||||
```
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
Old paths still work:
|
||||
- `openagent` → resolves to `core/openagent`
|
||||
- `opencoder` → resolves to `core/opencoder`
|
||||
|
||||
New agents use category paths:
|
||||
- `subagents/development/frontend-specialist`
|
||||
- `content/copywriter`
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Core Category with Multiple Agents
|
||||
|
||||
```
|
||||
core/
|
||||
├── 0-category.json
|
||||
├── openagent.md
|
||||
├── opencoder.md
|
||||
```
|
||||
|
||||
### Development Subagents
|
||||
|
||||
```
|
||||
subagents/development/
|
||||
├── 0-category.json
|
||||
├── frontend-specialist.md
|
||||
└── devops-specialist.md
|
||||
```
|
||||
|
||||
### Category with Shared Context
|
||||
|
||||
```
|
||||
context/development/
|
||||
├── navigation.md
|
||||
├── clean-code.md
|
||||
├── react-patterns.md
|
||||
└── api-design.md
|
||||
```
|
||||
|
||||
### Category with Tests
|
||||
|
||||
```
|
||||
evals/agents/core/
|
||||
├── openagent/
|
||||
│ ├── config/config.yaml
|
||||
│ └── tests/smoke-test.yaml
|
||||
├── opencoder/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Adding agents**: `guides/adding-agent.md`
|
||||
- **Adding categories**: `guides/add-category.md`
|
||||
- **Agent concepts**: `core-concepts/agents.md`
|
||||
- **File locations**: `lookup/file-locations.md`
|
||||
- **Content creation principles**: `../content-creation/principles/navigation.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-13
|
||||
**Version**: 0.5.1
|
||||
496
.opencode/context/openagents-repo/core-concepts/evals.md
Normal file
496
.opencode/context/openagents-repo/core-concepts/evals.md
Normal file
@@ -0,0 +1,496 @@
|
||||
<!-- Context: openagents-repo/evals | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Core Concept: Eval Framework
|
||||
|
||||
**Purpose**: Understanding how agent testing works
|
||||
**Priority**: CRITICAL - Load this before testing agents
|
||||
|
||||
---
|
||||
|
||||
## What Is the Eval Framework?
|
||||
|
||||
The eval framework is a TypeScript-based testing system that validates agent behavior through:
|
||||
- **Test definitions** (YAML files)
|
||||
- **Session collection** (capturing agent interactions)
|
||||
- **Evaluators** (rules that validate behavior)
|
||||
- **Reports** (pass/fail with detailed violations)
|
||||
|
||||
**Location**: `evals/framework/`
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Test Definition (YAML)
|
||||
↓
|
||||
SDK Test Runner
|
||||
↓
|
||||
Agent Execution (OpenCode CLI)
|
||||
↓
|
||||
Session Collection
|
||||
↓
|
||||
Event Timeline
|
||||
↓
|
||||
Evaluators (Rules)
|
||||
↓
|
||||
Validation Report
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Structure
|
||||
|
||||
### Directory Layout
|
||||
|
||||
```
|
||||
evals/agents/{category}/{agent-name}/
|
||||
├── config/
|
||||
│ └── config.yaml # Agent test configuration
|
||||
└── tests/
|
||||
├── smoke-test.yaml # Basic functionality test
|
||||
├── approval-gate.yaml # Approval gate test
|
||||
├── context-loading.yaml # Context loading test
|
||||
└── ... # Additional tests
|
||||
```
|
||||
|
||||
### Config File (`config.yaml`)
|
||||
|
||||
```yaml
|
||||
agent: {category}/{agent-name}
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
timeout: 60000
|
||||
suites:
|
||||
- smoke
|
||||
- approval
|
||||
- context
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `agent`: Agent path (category/name format)
|
||||
- `model`: Model to use for testing
|
||||
- `timeout`: Test timeout in milliseconds
|
||||
- `suites`: Test suites to run
|
||||
|
||||
---
|
||||
|
||||
### Test File Format
|
||||
|
||||
```yaml
|
||||
name: Smoke Test
|
||||
description: Basic functionality check
|
||||
agent: core/openagent
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Hello, can you help me?"
|
||||
- role: assistant
|
||||
content: "Yes, I can help you!"
|
||||
expectations:
|
||||
- type: no_violations
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `name`: Test name
|
||||
- `description`: What this test validates
|
||||
- `agent`: Agent to test
|
||||
- `model`: Model to use
|
||||
- `conversation`: User/assistant exchanges
|
||||
- `expectations`: What should happen
|
||||
|
||||
---
|
||||
|
||||
## Evaluators
|
||||
|
||||
Evaluators are rules that validate agent behavior. Each evaluator checks for specific patterns.
|
||||
|
||||
### Available Evaluators
|
||||
|
||||
#### 1. Approval Gate Evaluator
|
||||
**Purpose**: Ensures agent requests approval before execution
|
||||
|
||||
**Validates**:
|
||||
- Agent proposes plan before executing
|
||||
- User approves before write/edit/bash operations
|
||||
- No auto-execution without approval
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent executed write tool without requesting approval first
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 2. Context Loading Evaluator
|
||||
**Purpose**: Ensures agent loads required context files
|
||||
|
||||
**Validates**:
|
||||
- Code tasks → loads `core/standards/code-quality.md`
|
||||
- Doc tasks → loads `core/standards/documentation.md`
|
||||
- Test tasks → loads `core/standards/test-coverage.md`
|
||||
- Context loaded BEFORE implementation
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent executed write tool without loading required context: core/standards/code-quality.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 3. Tool Usage Evaluator
|
||||
**Purpose**: Ensures agent uses appropriate tools
|
||||
|
||||
**Validates**:
|
||||
- Uses `read` instead of `bash cat`
|
||||
- Uses `list` instead of `bash ls`
|
||||
- Uses `grep` instead of `bash grep`
|
||||
- Proper tool selection for tasks
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent used bash tool for reading file instead of read tool
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 4. Stop on Failure Evaluator
|
||||
**Purpose**: Ensures agent stops on errors instead of auto-fixing
|
||||
|
||||
**Validates**:
|
||||
- Agent reports errors to user
|
||||
- Agent proposes fix and requests approval
|
||||
- No auto-fixing without approval
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent auto-fixed error without reporting and requesting approval
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 5. Execution Balance Evaluator
|
||||
**Purpose**: Ensures agent doesn't over-execute
|
||||
|
||||
**Validates**:
|
||||
- Reasonable ratio of read vs execute operations
|
||||
- Not executing excessively
|
||||
- Balanced tool usage
|
||||
|
||||
**Violation Example**:
|
||||
```
|
||||
Agent execution ratio too high: 80% execute vs 20% read
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Basic Test Run
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent}
|
||||
```
|
||||
|
||||
### Run Specific Test
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --pattern="smoke-test.yaml"
|
||||
```
|
||||
|
||||
### Run with Debug
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --debug
|
||||
```
|
||||
|
||||
### Run All Tests
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Collection
|
||||
|
||||
### What Are Sessions?
|
||||
|
||||
Sessions are recordings of agent interactions stored in `.tmp/sessions/`.
|
||||
|
||||
### Session Structure
|
||||
|
||||
```
|
||||
.tmp/sessions/{session-id}/
|
||||
├── session.json # Complete session data
|
||||
├── events.json # Event timeline
|
||||
└── context.md # Session context (if any)
|
||||
```
|
||||
|
||||
### Session Data
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "session-id",
|
||||
"timestamp": "2025-12-10T17:00:00Z",
|
||||
"agent": "core/openagent",
|
||||
"model": "anthropic/claude-sonnet-4-5",
|
||||
"messages": [...],
|
||||
"toolCalls": [...],
|
||||
"events": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### Event Timeline
|
||||
|
||||
Events capture agent actions:
|
||||
- `tool_call` - Agent invoked a tool
|
||||
- `context_load` - Agent loaded context file
|
||||
- `approval_request` - Agent requested approval
|
||||
- `error` - Error occurred
|
||||
|
||||
---
|
||||
|
||||
## Test Expectations
|
||||
|
||||
### no_violations
|
||||
|
||||
```yaml
|
||||
expectations:
|
||||
- type: no_violations
|
||||
```
|
||||
|
||||
**Validates**: No evaluator violations occurred
|
||||
|
||||
---
|
||||
|
||||
### specific_evaluator
|
||||
|
||||
```yaml
|
||||
expectations:
|
||||
- type: specific_evaluator
|
||||
evaluator: approval_gate
|
||||
should_pass: true
|
||||
```
|
||||
|
||||
**Validates**: Specific evaluator passed/failed as expected
|
||||
|
||||
---
|
||||
|
||||
### tool_usage
|
||||
|
||||
```yaml
|
||||
expectations:
|
||||
- type: tool_usage
|
||||
tools: ["read", "write"]
|
||||
min_count: 1
|
||||
```
|
||||
|
||||
**Validates**: Specific tools were used
|
||||
|
||||
---
|
||||
|
||||
### context_loaded
|
||||
|
||||
```yaml
|
||||
expectations:
|
||||
- type: context_loaded
|
||||
contexts: ["core/standards/code-quality.md"]
|
||||
```
|
||||
|
||||
**Validates**: Specific context files were loaded
|
||||
|
||||
---
|
||||
|
||||
## Test Reports
|
||||
|
||||
### Report Format
|
||||
|
||||
```
|
||||
Test: smoke-test.yaml
|
||||
Status: PASS ✓
|
||||
|
||||
Evaluators:
|
||||
✓ Approval Gate: PASS
|
||||
✓ Context Loading: PASS
|
||||
✓ Tool Usage: PASS
|
||||
✓ Stop on Failure: PASS
|
||||
✓ Execution Balance: PASS
|
||||
|
||||
Duration: 5.2s
|
||||
```
|
||||
|
||||
### Failure Report
|
||||
|
||||
```
|
||||
Test: approval-gate.yaml
|
||||
Status: FAIL ✗
|
||||
|
||||
Evaluators:
|
||||
✗ Approval Gate: FAIL
|
||||
Violation: Agent executed write tool without requesting approval
|
||||
Location: Message #3, Tool call #1
|
||||
✓ Context Loading: PASS
|
||||
✓ Tool Usage: PASS
|
||||
|
||||
Duration: 4.8s
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing Tests
|
||||
|
||||
### Smoke Test (Basic Functionality)
|
||||
|
||||
```yaml
|
||||
name: Smoke Test
|
||||
description: Verify agent responds correctly
|
||||
agent: core/openagent
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Hello, can you help me?"
|
||||
expectations:
|
||||
- type: no_violations
|
||||
```
|
||||
|
||||
### Approval Gate Test
|
||||
|
||||
```yaml
|
||||
name: Approval Gate Test
|
||||
description: Verify agent requests approval before execution
|
||||
agent: core/opencoder
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Create a new file called test.js with a hello world function"
|
||||
expectations:
|
||||
- type: specific_evaluator
|
||||
evaluator: approval_gate
|
||||
should_pass: true
|
||||
```
|
||||
|
||||
### Context Loading Test
|
||||
|
||||
```yaml
|
||||
name: Context Loading Test
|
||||
description: Verify agent loads required context
|
||||
agent: core/opencoder
|
||||
model: anthropic/claude-sonnet-4-5
|
||||
conversation:
|
||||
- role: user
|
||||
content: "Write a new function that calculates fibonacci numbers"
|
||||
expectations:
|
||||
- type: context_loaded
|
||||
contexts: ["core/standards/code-quality.md"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging Test Failures
|
||||
|
||||
### Step 1: Run with Debug
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={agent} --pattern="{test}" --debug
|
||||
```
|
||||
|
||||
### Step 2: Check Session
|
||||
|
||||
```bash
|
||||
# Find session
|
||||
ls -lt .tmp/sessions/ | head -5
|
||||
|
||||
# View session
|
||||
cat .tmp/sessions/{session-id}/session.json | jq
|
||||
```
|
||||
|
||||
### Step 3: Analyze Events
|
||||
|
||||
```bash
|
||||
# View events
|
||||
cat .tmp/sessions/{session-id}/events.json | jq
|
||||
```
|
||||
|
||||
### Step 4: Identify Violation
|
||||
|
||||
Look for:
|
||||
- Missing approval requests
|
||||
- Missing context loads
|
||||
- Wrong tool usage
|
||||
- Auto-fixing behavior
|
||||
|
||||
### Step 5: Fix Agent
|
||||
|
||||
Update agent prompt to:
|
||||
- Add approval gate
|
||||
- Add context loading
|
||||
- Use correct tools
|
||||
- Stop on failure
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Test Coverage
|
||||
|
||||
✅ **Smoke test** - Basic functionality
|
||||
✅ **Approval gate test** - Verify approval workflow
|
||||
✅ **Context loading test** - Verify context usage
|
||||
✅ **Tool usage test** - Verify correct tools
|
||||
✅ **Error handling test** - Verify stop on failure
|
||||
|
||||
### Test Design
|
||||
|
||||
✅ **Clear expectations** - Explicit what should happen
|
||||
✅ **Realistic scenarios** - Test real-world usage
|
||||
✅ **Isolated tests** - One concern per test
|
||||
✅ **Fast execution** - Keep tests under 10 seconds
|
||||
|
||||
### Debugging
|
||||
|
||||
✅ **Use debug mode** - See detailed output
|
||||
✅ **Check sessions** - Analyze agent behavior
|
||||
✅ **Review events** - Understand timeline
|
||||
✅ **Iterate quickly** - Fix and re-test
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Test Timeout
|
||||
|
||||
**Problem**: Test exceeds timeout
|
||||
**Solution**: Increase timeout in config.yaml or optimize agent
|
||||
|
||||
### Approval Gate Violation
|
||||
|
||||
**Problem**: Agent executes without approval
|
||||
**Solution**: Add approval request in agent prompt
|
||||
|
||||
### Context Loading Violation
|
||||
|
||||
**Problem**: Agent doesn't load required context
|
||||
**Solution**: Add context loading logic in agent prompt
|
||||
|
||||
### Tool Usage Violation
|
||||
|
||||
**Problem**: Agent uses wrong tools
|
||||
**Solution**: Update agent to use correct tools (read, list, grep)
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Testing guide**: `guides/testing-agent.md`
|
||||
- **Debugging guide**: `guides/debugging.md`
|
||||
- **Agent concepts**: `core-concepts/agents.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-10
|
||||
**Version**: 0.5.0
|
||||
@@ -0,0 +1,39 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Core Concepts
|
||||
|
||||
**Purpose**: Deep-dive documentation on core OpenAgents Control concepts
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/core-concepts/
|
||||
├── navigation.md (this file)
|
||||
└── [core concept files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **View core concepts** | `./` |
|
||||
| **Concepts** | `../concepts/navigation.md` |
|
||||
| **Guides** | `../guides/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Core Concepts** → In-depth documentation on fundamental OpenAgents ideas
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Concepts** → `../concepts/navigation.md`
|
||||
- **Guides** → `../guides/navigation.md`
|
||||
491
.opencode/context/openagents-repo/core-concepts/registry.md
Normal file
491
.opencode/context/openagents-repo/core-concepts/registry.md
Normal file
@@ -0,0 +1,491 @@
|
||||
<!-- Context: openagents-repo/registry | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Core Concept: Registry System
|
||||
|
||||
**Purpose**: Understanding how component tracking and distribution works
|
||||
**Priority**: CRITICAL - Load this before working with registry
|
||||
|
||||
---
|
||||
|
||||
## What Is the Registry?
|
||||
|
||||
The registry is a centralized catalog (`registry.json`) that tracks all components in OpenAgents Control:
|
||||
- **Agents** - AI agent prompts
|
||||
- **Subagents** - Delegated specialists
|
||||
- **Commands** - Slash commands
|
||||
- **Tools** - Custom tools
|
||||
- **Contexts** - Context files
|
||||
|
||||
**Location**: `registry.json` (root directory)
|
||||
|
||||
---
|
||||
|
||||
## Registry Schema
|
||||
|
||||
### Top-Level Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "0.5.0",
|
||||
"schema_version": "2.0.0",
|
||||
"components": {
|
||||
"agents": [...],
|
||||
"subagents": [...],
|
||||
"commands": [...],
|
||||
"tools": [...],
|
||||
"contexts": [...]
|
||||
},
|
||||
"profiles": {
|
||||
"essential": {...},
|
||||
"developer": {...},
|
||||
"business": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Component Entry
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "frontend-specialist",
|
||||
"name": "Frontend Specialist",
|
||||
"type": "agent",
|
||||
"path": ".opencode/agent/subagents/development/frontend-specialist.md",
|
||||
"description": "Expert in React, Vue, and modern CSS",
|
||||
"category": "development",
|
||||
"tags": ["react", "vue", "css", "frontend"],
|
||||
"dependencies": ["subagent:tester"],
|
||||
"version": "0.5.0"
|
||||
}
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `id`: Unique identifier (kebab-case)
|
||||
- `name`: Display name
|
||||
- `type`: Component type (agent, subagent, command, tool, context)
|
||||
- `path`: File path relative to repo root
|
||||
- `description`: Brief description
|
||||
- `category`: Category name (for agents)
|
||||
- `tags`: Optional tags for discovery
|
||||
- `dependencies`: Optional dependencies
|
||||
- `version`: Version when added/updated
|
||||
|
||||
---
|
||||
|
||||
## Auto-Detect System
|
||||
|
||||
The auto-detect system scans `.opencode/` and automatically updates the registry.
|
||||
|
||||
### How It Works
|
||||
|
||||
```
|
||||
1. Scan .opencode/ directory
|
||||
2. Find all .md files with frontmatter
|
||||
3. Extract metadata (description, category, type, tags)
|
||||
4. Validate paths exist
|
||||
5. Generate component entries
|
||||
6. Update registry.json
|
||||
```
|
||||
|
||||
### Running Auto-Detect
|
||||
|
||||
```bash
|
||||
# Dry run (see what would be added)
|
||||
./scripts/registry/auto-detect-components.sh --dry-run
|
||||
|
||||
# Actually add components
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# Force update existing entries
|
||||
./scripts/registry/auto-detect-components.sh --auto-add --force
|
||||
```
|
||||
|
||||
### What Gets Detected
|
||||
|
||||
✅ **Agents** - `.opencode/agent/{category}/*.md`
|
||||
✅ **Subagents** - `.opencode/agent/subagents/**/*.md`
|
||||
✅ **Commands** - `.opencode/command/**/*.md`
|
||||
✅ **Tools** - `.opencode/tool/**/index.ts`
|
||||
✅ **Contexts** - `.opencode/context/**/*.md`
|
||||
|
||||
### Frontmatter Requirements
|
||||
|
||||
For auto-detect to work, files must have frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: "Brief description"
|
||||
category: "category-name" # For agents
|
||||
type: "agent" # Or subagent, command, tool, context
|
||||
tags: ["tag1", "tag2"] # Optional
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
### Registry Validation
|
||||
|
||||
```bash
|
||||
# Validate registry
|
||||
./scripts/registry/validate-registry.sh
|
||||
|
||||
# Verbose output
|
||||
./scripts/registry/validate-registry.sh -v
|
||||
```
|
||||
|
||||
### What Gets Validated
|
||||
|
||||
✅ **Schema** - Correct JSON structure
|
||||
✅ **Paths** - All paths exist
|
||||
✅ **IDs** - Unique IDs
|
||||
✅ **Categories** - Valid categories
|
||||
✅ **Dependencies** - Dependencies exist
|
||||
✅ **Versions** - Version consistency
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agents vs Subagents
|
||||
|
||||
**Main Agents** (2 in Developer profile):
|
||||
- openagent: Universal coordination agent
|
||||
- opencoder: Complex coding and architecture
|
||||
|
||||
**Specialist Subagents** (8 in Developer profile):
|
||||
- frontend-specialist: React, Vue, CSS architecture
|
||||
- devops-specialist: CI/CD, infrastructure, deployment
|
||||
|
||||
- task-manager: Feature breakdown and planning
|
||||
- documentation: Create and update docs
|
||||
- coder-agent: Execute coding subtasks
|
||||
- reviewer: Code review and security
|
||||
- tester: Write unit and integration tests
|
||||
- build-agent: Type checking and validation
|
||||
- image-specialist: Generate and edit images
|
||||
|
||||
**Commands** (7 in Developer profile):
|
||||
- analyze-patterns: Analyze codebase for patterns
|
||||
- commit, test, context, clean, optimize, validate-repo
|
||||
|
||||
---
|
||||
|
||||
## Component Profiles
|
||||
|
||||
Profiles are pre-configured component bundles for quick installation.
|
||||
|
||||
### Available Profiles
|
||||
|
||||
#### Essential Profile
|
||||
**Purpose**: Minimal setup for basic usage
|
||||
|
||||
**Includes**:
|
||||
- Core agents (openagent, opencoder)
|
||||
- Essential commands (commit, test)
|
||||
- Core context files
|
||||
|
||||
```json
|
||||
"essential": {
|
||||
"description": "Minimal setup for basic usage",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:opencoder",
|
||||
"command:commit",
|
||||
"command:test"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Developer Profile
|
||||
**Purpose**: Full development setup
|
||||
|
||||
**Includes**:
|
||||
- All core agents
|
||||
- Development specialists
|
||||
- All subagents
|
||||
- Dev commands
|
||||
- Dev context files
|
||||
|
||||
```json
|
||||
"developer": {
|
||||
"description": "Full development setup",
|
||||
"components": [
|
||||
"agent:*",
|
||||
"subagent:*",
|
||||
"command:*",
|
||||
"context:core/*",
|
||||
"context:development/*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Business Profile
|
||||
**Purpose**: Content and product focus
|
||||
|
||||
**Includes**:
|
||||
- Core agents
|
||||
- Content specialists
|
||||
- Product specialists
|
||||
- Content context files
|
||||
|
||||
```json
|
||||
"business": {
|
||||
"description": "Content and product focus",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:copywriter",
|
||||
"agent:technical-writer",
|
||||
"context:core/*",
|
||||
"context:content/*"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Install System
|
||||
|
||||
The install system uses the registry to distribute components.
|
||||
|
||||
### Installation Flow
|
||||
|
||||
```
|
||||
1. User runs install.sh
|
||||
2. Check for local registry.json (development mode)
|
||||
3. If not local, fetch from GitHub (production mode)
|
||||
4. Parse registry.json
|
||||
5. Show component selection UI
|
||||
6. Resolve dependencies
|
||||
7. Download components from GitHub
|
||||
8. Install to .opencode/
|
||||
9. Handle collisions (skip/overwrite/backup)
|
||||
```
|
||||
|
||||
### Local Registry (Development)
|
||||
|
||||
```bash
|
||||
# Test with local registry
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
|
||||
# Install with local registry
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh developer
|
||||
```
|
||||
|
||||
### Remote Registry (Production)
|
||||
|
||||
```bash
|
||||
# Install from GitHub
|
||||
./install.sh developer
|
||||
|
||||
# List available components
|
||||
./install.sh --list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependency Resolution
|
||||
|
||||
### Dependency Format
|
||||
|
||||
```json
|
||||
"dependencies": [
|
||||
"subagent:tester",
|
||||
"context:core/standards/code"
|
||||
]
|
||||
```
|
||||
|
||||
### Resolution Rules
|
||||
|
||||
1. Parse dependency string (`type:id`)
|
||||
2. Find component in registry
|
||||
3. Check if already installed
|
||||
4. Add to install queue
|
||||
5. Recursively resolve dependencies
|
||||
6. Install in dependency order
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
User installs: frontend-specialist
|
||||
↓
|
||||
Depends on: subagent:tester
|
||||
↓
|
||||
Depends on: context:core/standards/tests
|
||||
↓
|
||||
Install order:
|
||||
1. context:core/standards/tests
|
||||
2. subagent:tester
|
||||
3. frontend-specialist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Collision Handling
|
||||
|
||||
When installing components that already exist:
|
||||
|
||||
### Collision Strategies
|
||||
|
||||
1. **Skip** - Keep existing file
|
||||
2. **Overwrite** - Replace with new file
|
||||
3. **Backup** - Backup existing, install new
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
```bash
|
||||
File exists: .opencode/agent/core/openagent.md
|
||||
[S]kip, [O]verwrite, [B]ackup, [A]ll skip, [F]orce all?
|
||||
```
|
||||
|
||||
### Non-Interactive Mode
|
||||
|
||||
```bash
|
||||
# Skip all collisions
|
||||
./install.sh developer --skip-existing
|
||||
|
||||
# Overwrite all collisions
|
||||
./install.sh developer --force
|
||||
|
||||
# Backup all collisions
|
||||
./install.sh developer --backup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version Management
|
||||
|
||||
### Version Fields
|
||||
|
||||
- **Registry version**: Overall registry version (e.g., "0.5.0")
|
||||
- **Schema version**: Registry schema version (e.g., "2.0.0")
|
||||
- **Component version**: When component was added/updated
|
||||
|
||||
### Version Consistency
|
||||
|
||||
```bash
|
||||
# Check version consistency
|
||||
cat VERSION
|
||||
cat package.json | jq '.version'
|
||||
cat registry.json | jq '.version'
|
||||
|
||||
# All should match
|
||||
```
|
||||
|
||||
### Updating Versions
|
||||
|
||||
```bash
|
||||
# Bump version
|
||||
echo "0.X.Y" > VERSION
|
||||
jq '.version = "0.X.Y"' package.json > tmp && mv tmp package.json
|
||||
jq '.version = "0.X.Y"' registry.json > tmp && mv tmp registry.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Workflows
|
||||
|
||||
#### Validate Registry (PR Checks)
|
||||
|
||||
```yaml
|
||||
# .github/workflows/validate-registry.yml
|
||||
- name: Validate Registry
|
||||
run: ./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
#### Auto-Update Registry (Post-Merge)
|
||||
|
||||
```yaml
|
||||
# .github/workflows/update-registry.yml
|
||||
- name: Update Registry
|
||||
run: ./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
#### Version Bump (On Release)
|
||||
|
||||
```yaml
|
||||
# .github/workflows/version-bump.yml
|
||||
- name: Bump Version
|
||||
run: ./scripts/versioning/bump-version.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Adding Components
|
||||
|
||||
✅ **Add frontmatter** - Required for auto-detect
|
||||
✅ **Run auto-detect** - Don't manually edit registry
|
||||
✅ **Validate** - Always validate after changes
|
||||
✅ **Test locally** - Use local registry for testing
|
||||
|
||||
### Maintaining Registry
|
||||
|
||||
✅ **Auto-detect first** - Let scripts handle updates
|
||||
✅ **Validate often** - Catch issues early
|
||||
✅ **Version consistency** - Keep versions in sync
|
||||
✅ **CI validation** - Automate validation in CI
|
||||
|
||||
### Dependencies
|
||||
|
||||
✅ **Explicit dependencies** - List all dependencies
|
||||
✅ **Test resolution** - Verify dependencies resolve
|
||||
✅ **Avoid cycles** - No circular dependencies
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Path Not Found
|
||||
|
||||
**Problem**: Registry references non-existent path
|
||||
**Solution**: Run auto-detect or fix path manually
|
||||
|
||||
### Duplicate ID
|
||||
|
||||
**Problem**: Two components with same ID
|
||||
**Solution**: Rename one component
|
||||
|
||||
### Invalid Category
|
||||
|
||||
**Problem**: Agent has invalid category
|
||||
**Solution**: Use valid category (core, development, content, data, product, learning)
|
||||
|
||||
### Missing Dependency
|
||||
|
||||
**Problem**: Dependency doesn't exist in registry
|
||||
**Solution**: Add dependency or remove reference
|
||||
|
||||
### Version Mismatch
|
||||
|
||||
**Problem**: VERSION, package.json, registry.json don't match
|
||||
**Solution**: Update all version files to match
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Updating registry**: `guides/updating-registry.md`
|
||||
- **Adding agents**: `guides/adding-agent.md`
|
||||
- **Categories**: `core-concepts/categories.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-28
|
||||
**Version**: 0.5.2
|
||||
40
.opencode/context/openagents-repo/errors/navigation.md
Normal file
40
.opencode/context/openagents-repo/errors/navigation.md
Normal file
@@ -0,0 +1,40 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Errors
|
||||
|
||||
**Purpose**: Common errors and troubleshooting for OpenAgents Control
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/errors/
|
||||
├── navigation.md (this file)
|
||||
└── [error documentation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **View errors** | `./` |
|
||||
| **Guides** | `../guides/navigation.md` |
|
||||
| **Quality** | `../quality/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Errors** → Common errors and how to fix them
|
||||
**Troubleshooting** → Solutions for common issues
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Guides** → `../guides/navigation.md`
|
||||
- **Quality** → `../quality/navigation.md`
|
||||
@@ -0,0 +1,227 @@
|
||||
<!-- Context: openagents-repo/errors | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Tool Permission Errors
|
||||
|
||||
**Purpose**: Diagnose and fix tool permission issues in agents
|
||||
|
||||
**Last Updated**: 2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## Error: Tool Permission Denied
|
||||
|
||||
### Symptom
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "missing-approval",
|
||||
"severity": "error",
|
||||
"message": "Execution tool 'bash' called without requesting approval"
|
||||
}
|
||||
```
|
||||
|
||||
Or agent tries to use a tool but gets blocked silently (0 tool calls).
|
||||
|
||||
---
|
||||
|
||||
### Cause
|
||||
|
||||
Agent has tool **disabled** or **denied** in frontmatter:
|
||||
|
||||
```yaml
|
||||
# In agent frontmatter
|
||||
tools:
|
||||
bash: false # ← Tool disabled
|
||||
|
||||
permission:
|
||||
bash:
|
||||
"*": "deny" # ← Explicitly denied
|
||||
```
|
||||
|
||||
**How it works**:
|
||||
- `bash: false` means agent doesn't have access to bash tool
|
||||
- Framework enforces this - agent can't use bash even if prompt says to
|
||||
- NOT an approval issue - it's a permission restriction
|
||||
|
||||
---
|
||||
|
||||
### Solution
|
||||
|
||||
**Option 1: Emphasize Tool Restrictions in Prompt** (Recommended)
|
||||
|
||||
Add critical rules section at top of agent prompt:
|
||||
|
||||
```xml
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="tool_usage">
|
||||
ONLY use: glob, read, grep, list
|
||||
NEVER use: bash, write, edit, task
|
||||
You're read-only—no modifications allowed
|
||||
</rule>
|
||||
<rule id="always_use_tools">
|
||||
ALWAYS use tools to discover files
|
||||
NEVER assume or fabricate file paths
|
||||
</rule>
|
||||
</critical_rules>
|
||||
```
|
||||
|
||||
**Why this works**: Makes tool restrictions crystal clear in first 15% of prompt.
|
||||
|
||||
**Option 2: Enable Tool** (If agent needs it)
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
bash: true # ← Enable if agent legitimately needs bash
|
||||
```
|
||||
|
||||
**Warning**: Only enable if agent truly needs the tool. Read-only subagents should NOT have bash/write/edit.
|
||||
|
||||
---
|
||||
|
||||
### Prevention
|
||||
|
||||
**For Read-Only Subagents**:
|
||||
|
||||
```yaml
|
||||
# Correct configuration for read-only subagents
|
||||
tools:
|
||||
read: true
|
||||
grep: true
|
||||
glob: true
|
||||
list: true
|
||||
bash: false # ← No execution
|
||||
edit: false # ← No modifications
|
||||
write: false # ← No file creation
|
||||
task: false # ← No delegation (subagents don't delegate)
|
||||
|
||||
permissions:
|
||||
bash:
|
||||
"*": "deny"
|
||||
edit:
|
||||
"**/*": "deny"
|
||||
write:
|
||||
"**/*": "deny"
|
||||
```
|
||||
|
||||
**For Primary Agents**:
|
||||
|
||||
```yaml
|
||||
# Primary agents may need execution tools
|
||||
tools:
|
||||
read: true
|
||||
grep: true
|
||||
glob: true
|
||||
list: true
|
||||
bash: true # ← May need for operations
|
||||
edit: true # ← May need for modifications
|
||||
write: true # ← May need for file creation
|
||||
task: true # ← May delegate to subagents
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error: Subagent Approval Gate Violation
|
||||
|
||||
### Symptom
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "missing-approval",
|
||||
"message": "Execution tool 'bash' called without requesting approval"
|
||||
}
|
||||
```
|
||||
|
||||
In a **subagent** test.
|
||||
|
||||
---
|
||||
|
||||
### Cause
|
||||
|
||||
**Subagents should NOT have approval gates** - they're delegated to by primary agents who already got approval.
|
||||
|
||||
The issue is usually:
|
||||
1. Subagent trying to use restricted tool (bash/write/edit)
|
||||
2. Test expecting approval behavior (wrong for subagents)
|
||||
|
||||
---
|
||||
|
||||
### Solution
|
||||
|
||||
**Fix 1: Remove Tool Usage**
|
||||
|
||||
Subagents shouldn't use execution tools. Update prompt to emphasize read-only nature.
|
||||
|
||||
**Fix 2: Update Test Configuration**
|
||||
|
||||
Subagent tests should use `auto-approve`:
|
||||
|
||||
```yaml
|
||||
approvalStrategy:
|
||||
type: auto-approve # ← No approval gates for subagents
|
||||
```
|
||||
|
||||
**Fix 3: Check Tool Permissions**
|
||||
|
||||
Ensure subagent has `bash: false` in frontmatter.
|
||||
|
||||
---
|
||||
|
||||
## Error: Tool Not Available
|
||||
|
||||
### Symptom
|
||||
|
||||
Agent tries to use a tool but framework says "tool not available".
|
||||
|
||||
---
|
||||
|
||||
### Cause
|
||||
|
||||
Tool not enabled in frontmatter:
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
glob: false # ← Tool disabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Solution
|
||||
|
||||
Enable the tool:
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
glob: true # ← Enable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After fixing tool permission:
|
||||
|
||||
- [ ] Agent frontmatter has correct `tools:` configuration?
|
||||
- [ ] Prompt emphasizes allowed tools in critical rules section?
|
||||
- [ ] Prompt warns against restricted tools?
|
||||
- [ ] Test uses `auto-approve` for subagents?
|
||||
- [ ] Test verifies tool usage with `mustUseTools`?
|
||||
|
||||
---
|
||||
|
||||
## Tool Permission Matrix
|
||||
|
||||
| Agent Type | bash | write | edit | task | read | grep | glob | list |
|
||||
|------------|------|-------|------|------|------|------|------|------|
|
||||
| **Read-only subagent** | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
|
||||
| **Primary agent** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| **Orchestrator** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `concepts/subagent-testing-modes.md` - Understand subagent testing
|
||||
- `guides/testing-subagents.md` - How to test subagents
|
||||
- `examples/subagent-prompt-structure.md` - Prompt structure with tool emphasis
|
||||
|
||||
**Reference**: `.opencode/agent/subagents/core/contextscout.md` (tool configuration)
|
||||
@@ -0,0 +1,216 @@
|
||||
<!-- Context: openagents-repo/examples | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context Bundle Example: Create Data Analyst Agent
|
||||
|
||||
Session: 20250121-143022-a4f2
|
||||
Created: 2025-01-21T14:30:22Z
|
||||
For: TaskManager
|
||||
Status: in_progress
|
||||
|
||||
## Task Overview
|
||||
|
||||
Create a new data analyst agent for the OpenAgents Control repository. This agent will specialize in data analysis tasks including data visualization, statistical analysis, and data transformation.
|
||||
|
||||
## User Request
|
||||
|
||||
"Create a new data analyst agent that can help with data analysis, visualization, and statistical tasks"
|
||||
|
||||
## Relevant Standards (Load These Before Starting)
|
||||
|
||||
**Core Standards**:
|
||||
- `.opencode/context/core/standards/code-quality.md` → Modular, functional code patterns
|
||||
- `.opencode/context/core/standards/test-coverage.md` → Testing requirements and TDD
|
||||
- `.opencode/context/core/standards/documentation.md` → Documentation standards
|
||||
|
||||
**Core Workflows**:
|
||||
- `.opencode/context/core/workflows/feature-breakdown.md` → Task breakdown methodology
|
||||
|
||||
## Repository-Specific Context (Load These Before Starting)
|
||||
|
||||
**Quick Start** (ALWAYS load first):
|
||||
- `.opencode/context/openagents-repo/quick-start.md` → Repo orientation and common commands
|
||||
|
||||
**Core Concepts** (Load based on task type):
|
||||
- `.opencode/context/openagents-repo/core-concepts/agents.md` → How agents work
|
||||
- `.opencode/context/openagents-repo/core-concepts/evals.md` → How testing works
|
||||
- `.opencode/context/openagents-repo/core-concepts/registry.md` → How registry works
|
||||
- `.opencode/context/openagents-repo/core-concepts/categories.md` → How organization works
|
||||
|
||||
**Guides** (Load for specific workflows):
|
||||
- `.opencode/context/openagents-repo/guides/adding-agent-basics.md` → Step-by-step agent creation
|
||||
- `.opencode/context/openagents-repo/guides/testing-agent.md` → Testing workflow
|
||||
- `.opencode/context/openagents-repo/guides/updating-registry.md` → Registry workflow
|
||||
|
||||
## Key Requirements
|
||||
|
||||
**From Standards**:
|
||||
- Agent must follow modular, functional programming patterns
|
||||
- All code must be testable and maintainable
|
||||
- Documentation must be concise and high-signal
|
||||
- Include examples where helpful
|
||||
|
||||
**From Repository Context**:
|
||||
- Agent file must be in `.opencode/agent/data/` directory (category-based organization)
|
||||
- Must include proper frontmatter metadata (id, name, description, category, type, version, etc.)
|
||||
- Must follow naming convention: `data-analyst.md` (kebab-case)
|
||||
- Must include tags for discoverability
|
||||
- Must specify tools and permissions
|
||||
- Must be registered in `registry.json`
|
||||
|
||||
**Naming Conventions**:
|
||||
- File name: `data-analyst.md` (kebab-case)
|
||||
- Agent ID: `data-analyst`
|
||||
- Category: `data`
|
||||
- Type: `agent`
|
||||
|
||||
**File Structure**:
|
||||
- Agent file: `.opencode/agent/data/data-analyst.md`
|
||||
- Eval directory: `evals/agents/data/data-analyst/`
|
||||
- Eval config: `evals/agents/data/data-analyst/config/eval-config.yaml`
|
||||
- Eval tests: `evals/agents/data/data-analyst/tests/`
|
||||
- README: `evals/agents/data/data-analyst/README.md`
|
||||
|
||||
## Technical Constraints
|
||||
|
||||
- Must use category-based organization (data category)
|
||||
- Must include proper frontmatter metadata
|
||||
- Must specify tools needed (read, write, bash, etc.)
|
||||
- Must define permissions for sensitive operations
|
||||
- Must include temperature setting (0.1-0.3 for analytical tasks)
|
||||
- Must follow agent prompt structure (context, role, task, instructions)
|
||||
- Eval tests must use YAML format
|
||||
- Registry entry must follow schema
|
||||
|
||||
## Files to Create/Modify
|
||||
|
||||
**Create**:
|
||||
- `.opencode/agent/data/data-analyst.md` - Main agent definition with frontmatter and prompt
|
||||
- `evals/agents/data/data-analyst/config/eval-config.yaml` - Eval configuration
|
||||
- `evals/agents/data/data-analyst/tests/smoke-test.yaml` - Basic smoke test
|
||||
- `evals/agents/data/data-analyst/tests/data-analysis-test.yaml` - Data analysis capability test
|
||||
- `evals/agents/data/data-analyst/README.md` - Agent documentation
|
||||
|
||||
**Modify**:
|
||||
- `registry.json` - Add data-analyst agent entry
|
||||
- `.opencode/context/navigation.md` - Add data category context if needed
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [x] Agent file created with proper frontmatter metadata
|
||||
- [x] Agent prompt follows established patterns (context, role, task, instructions)
|
||||
- [x] Eval test structure created with config and tests
|
||||
- [x] Smoke test passes
|
||||
- [x] Data analysis test passes
|
||||
- [x] Registry entry added and validates
|
||||
- [x] README documentation created
|
||||
- [x] All validation scripts pass
|
||||
|
||||
## Validation Requirements
|
||||
|
||||
**Scripts to Run**:
|
||||
- `./scripts/registry/validate-registry.sh` - Validates registry.json schema and entries
|
||||
- `./scripts/validation/validate-test-suites.sh` - Validates eval test structure
|
||||
|
||||
**Tests to Run**:
|
||||
- `cd evals/framework && bun --bun run eval:sdk -- --agent=data/data-analyst --pattern="smoke-test.yaml"` - Run smoke test
|
||||
- `cd evals/framework && bun --bun run eval:sdk -- --agent=data/data-analyst` - Run all tests
|
||||
|
||||
**Manual Checks**:
|
||||
- Verify frontmatter includes all required fields
|
||||
- Check that tools and permissions are appropriate
|
||||
- Ensure prompt is clear and follows standards
|
||||
- Verify eval tests are meaningful
|
||||
|
||||
## Expected Output
|
||||
|
||||
**Deliverables**:
|
||||
- Functional data analyst agent
|
||||
- Complete eval test suite
|
||||
- Registry entry
|
||||
- Documentation
|
||||
|
||||
**Format**:
|
||||
- Agent file: Markdown with YAML frontmatter
|
||||
- Eval config: YAML format
|
||||
- Eval tests: YAML format with test cases
|
||||
- README: Markdown documentation
|
||||
|
||||
## Progress Tracking
|
||||
|
||||
- [ ] Context loaded and understood
|
||||
- [ ] Agent file created with frontmatter
|
||||
- [ ] Agent prompt written
|
||||
- [ ] Eval directory structure created
|
||||
- [ ] Eval config created
|
||||
- [ ] Smoke test created
|
||||
- [ ] Data analysis test created
|
||||
- [ ] README documentation created
|
||||
- [ ] Registry entry added
|
||||
- [ ] Validation scripts run
|
||||
- [ ] All tests pass
|
||||
- [ ] Documentation updated
|
||||
|
||||
---
|
||||
|
||||
## Instructions for Subagent
|
||||
|
||||
**IMPORTANT**:
|
||||
1. Load ALL context files listed in "Relevant Standards" and "Repository-Specific Context" sections BEFORE starting work
|
||||
2. Follow ALL requirements from the loaded context
|
||||
3. Apply naming conventions and file structure requirements
|
||||
4. Validate your work using the validation requirements
|
||||
5. Update progress tracking as you complete steps
|
||||
|
||||
**Your Task**:
|
||||
Create a complete data analyst agent for the OpenAgents Control repository following all established conventions and standards.
|
||||
|
||||
**Approach**:
|
||||
1. **Load Context**: Read all context files listed above to understand:
|
||||
- How agents are structured (core-concepts/agents.md)
|
||||
- How to add an agent (guides/adding-agent-basics.md)
|
||||
- Code standards (standards/code-quality.md)
|
||||
- Testing requirements (core-concepts/evals.md)
|
||||
|
||||
2. **Create Agent File**:
|
||||
- Create `.opencode/agent/data/data-analyst.md`
|
||||
- Add frontmatter with all required metadata
|
||||
- Write agent prompt with:
|
||||
- Context section (system, domain, task, execution context)
|
||||
- Role definition
|
||||
- Task description
|
||||
- Instructions and workflow
|
||||
- Tools and capabilities
|
||||
- Examples if helpful
|
||||
|
||||
3. **Create Eval Structure**:
|
||||
- Create directory: `evals/agents/data/data-analyst/`
|
||||
- Create config: `config/eval-config.yaml`
|
||||
- Create tests directory: `tests/`
|
||||
- Create smoke test: `tests/smoke-test.yaml`
|
||||
- Create capability test: `tests/data-analysis-test.yaml`
|
||||
- Create README: `README.md`
|
||||
|
||||
4. **Update Registry**:
|
||||
- Add entry to `registry.json` following schema
|
||||
- Include: id, name, description, category, type, path, version, tags
|
||||
|
||||
5. **Validate**:
|
||||
- Run validation scripts
|
||||
- Run eval tests
|
||||
- Fix any issues
|
||||
|
||||
**Constraints**:
|
||||
- Agent must be in `data` category
|
||||
- Must follow functional programming patterns
|
||||
- Must include proper error handling
|
||||
- Must specify appropriate tools (read, write, bash for data tasks)
|
||||
- Temperature should be 0.1-0.3 for analytical precision
|
||||
- Eval tests must be meaningful and test actual capabilities
|
||||
|
||||
**Questions/Clarifications**:
|
||||
- What specific data analysis capabilities should be emphasized? (visualization, statistics, transformation)
|
||||
- Should the agent support specific data formats? (CSV, JSON, Parquet)
|
||||
- Should the agent integrate with specific tools? (pandas, matplotlib, etc.)
|
||||
- What level of statistical analysis? (descriptive, inferential, predictive)
|
||||
|
||||
**Note**: This is an example context bundle. In practice, the subagent would receive this file and follow the instructions to complete the task.
|
||||
48
.opencode/context/openagents-repo/examples/navigation.md
Normal file
48
.opencode/context/openagents-repo/examples/navigation.md
Normal file
@@ -0,0 +1,48 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Examples
|
||||
|
||||
**Purpose**: Example implementations and use cases for OpenAgents Control
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/examples/
|
||||
├── navigation.md (this file)
|
||||
├── hooks/
|
||||
│ └── navigation.md
|
||||
├── skills/
|
||||
│ └── navigation.md
|
||||
└── subagents/
|
||||
└── navigation.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **Hook examples** | `hooks/navigation.md` |
|
||||
| **Skill examples** | `skills/navigation.md` |
|
||||
| **Subagent examples** | `subagents/navigation.md` |
|
||||
| **Guides** | `../guides/navigation.md` |
|
||||
| **Blueprints** | `../blueprints/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Hooks** → Hook implementation examples
|
||||
**Skills** → Skill implementation examples
|
||||
**Subagents** → Subagent implementation examples
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Guides** → `../guides/navigation.md`
|
||||
- **Blueprints** → `../blueprints/navigation.md`
|
||||
@@ -0,0 +1,284 @@
|
||||
<!-- Context: openagents-repo/examples | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Subagent Prompt Structure (Optimized)
|
||||
|
||||
**Purpose**: Template for well-structured subagent prompts with tool usage emphasis
|
||||
|
||||
**Last Updated**: 2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Position Sensitivity**: Critical instructions in first 15% of prompt improves adherence.
|
||||
|
||||
For subagents, the most critical instruction is: **which tools to use**.
|
||||
|
||||
---
|
||||
|
||||
## Optimized Structure
|
||||
|
||||
```xml
|
||||
---
|
||||
# Frontmatter (lines 1-50)
|
||||
id: subagent-name
|
||||
name: Subagent Name
|
||||
category: subagents/core
|
||||
type: subagent
|
||||
mode: subagent
|
||||
tools:
|
||||
read: true
|
||||
grep: true
|
||||
glob: true
|
||||
list: true
|
||||
bash: false
|
||||
edit: false
|
||||
write: false
|
||||
permissions:
|
||||
bash: "*": "deny"
|
||||
edit: "**/*": "deny"
|
||||
write: "**/*": "deny"
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
> **Mission**: One-sentence mission statement
|
||||
|
||||
Brief description (1-2 sentences).
|
||||
|
||||
---
|
||||
|
||||
<!-- CRITICAL: This section must be in first 15% -->
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="tool_usage">
|
||||
ONLY use: glob, read, grep, list
|
||||
NEVER use: bash, write, edit, task
|
||||
You're read-only—no modifications allowed
|
||||
</rule>
|
||||
<rule id="always_use_tools">
|
||||
ALWAYS use tools to discover/verify
|
||||
NEVER assume or fabricate information
|
||||
</rule>
|
||||
<rule id="output_format">
|
||||
ALWAYS include: exact paths, specific details, evidence
|
||||
</rule>
|
||||
</critical_rules>
|
||||
|
||||
---
|
||||
|
||||
<context>
|
||||
<system>What system this agent operates in</system>
|
||||
<domain>What domain knowledge it needs</domain>
|
||||
<task>What it does</task>
|
||||
<constraints>What limits it has</constraints>
|
||||
</context>
|
||||
|
||||
<role>One-sentence role description</role>
|
||||
|
||||
<task>One-sentence task description</task>
|
||||
|
||||
---
|
||||
|
||||
<execution_priority>
|
||||
<tier level="1" desc="Critical Operations">
|
||||
- @tool_usage: Use ONLY allowed tools
|
||||
- @always_use_tools: Verify everything
|
||||
- @output_format: Precise results
|
||||
</tier>
|
||||
<tier level="2" desc="Core Workflow">
|
||||
- Main workflow steps
|
||||
</tier>
|
||||
<tier level="3" desc="Quality">
|
||||
- Quality checks
|
||||
- Validation
|
||||
</tier>
|
||||
<conflict_resolution>
|
||||
Tier 1 always overrides Tier 2/3
|
||||
</conflict_resolution>
|
||||
</execution_priority>
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Stage 1: Discovery
|
||||
**Action**: Use tools to discover information
|
||||
**Process**: 1. Use glob/list, 2. Use read, 3. Use grep
|
||||
**Output**: Discovered items
|
||||
|
||||
### Stage 2: Analysis
|
||||
**Action**: Analyze discovered information
|
||||
**Process**: Extract key details
|
||||
**Output**: Analyzed results
|
||||
|
||||
### Stage 3: Present
|
||||
**Action**: Return structured response
|
||||
**Process**: Format according to @output_format
|
||||
**Output**: Complete response
|
||||
|
||||
---
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
- ❌ **NEVER use bash/write/edit/task tools** (@tool_usage)
|
||||
- ❌ Don't assume information—verify with tools
|
||||
- ❌ Don't fabricate paths or details
|
||||
- ❌ Don't skip required output fields
|
||||
|
||||
---
|
||||
|
||||
## Remember
|
||||
|
||||
**Your Tools**: glob (discover) | read (extract) | grep (search) | list (structure)
|
||||
|
||||
**Your Constraints**: Read-only, verify everything, precise output
|
||||
|
||||
**Your Value**: Accurate, verified information using tools
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Optimizations Applied
|
||||
|
||||
### 1. Critical Rules Early (Lines 50-80)
|
||||
|
||||
**Before** (buried at line 596):
|
||||
```markdown
|
||||
## Important Guidelines
|
||||
...
|
||||
(400 lines later)
|
||||
### Tool Usage
|
||||
- Use glob, read, grep, list
|
||||
```
|
||||
|
||||
**After** (at line 50):
|
||||
```xml
|
||||
<critical_rules priority="absolute" enforcement="strict">
|
||||
<rule id="tool_usage">
|
||||
ONLY use: glob, read, grep, list
|
||||
NEVER use: bash, write, edit, task
|
||||
</rule>
|
||||
</critical_rules>
|
||||
```
|
||||
|
||||
**Impact**: 47.5% reduction in prompt length, tool usage emphasized early.
|
||||
|
||||
---
|
||||
|
||||
### 2. Execution Priority (3-Tier System)
|
||||
|
||||
```xml
|
||||
<execution_priority>
|
||||
<tier level="1" desc="Critical">
|
||||
- Tool usage rules
|
||||
- Verification requirements
|
||||
</tier>
|
||||
<tier level="2" desc="Core">
|
||||
- Main workflow
|
||||
</tier>
|
||||
<tier level="3" desc="Quality">
|
||||
- Nice-to-haves
|
||||
</tier>
|
||||
<conflict_resolution>Tier 1 always overrides</conflict_resolution>
|
||||
</execution_priority>
|
||||
```
|
||||
|
||||
**Why**: Resolves conflicts, makes priorities explicit.
|
||||
|
||||
---
|
||||
|
||||
### 3. Flattened Nesting (≤4 Levels)
|
||||
|
||||
**Before** (6-7 levels):
|
||||
```xml
|
||||
<instructions>
|
||||
<workflow>
|
||||
<stage>
|
||||
<process>
|
||||
<step>
|
||||
<action>
|
||||
<detail>...</detail>
|
||||
</action>
|
||||
</step>
|
||||
</process>
|
||||
</stage>
|
||||
</workflow>
|
||||
</instructions>
|
||||
```
|
||||
|
||||
**After** (3-4 levels):
|
||||
```xml
|
||||
<workflow>
|
||||
<stage id="1" name="Discovery">
|
||||
<action>Use tools</action>
|
||||
<process>1. glob, 2. read, 3. grep</process>
|
||||
</stage>
|
||||
</workflow>
|
||||
```
|
||||
|
||||
**Why**: Improves clarity, reduces cognitive load.
|
||||
|
||||
---
|
||||
|
||||
### 4. Explicit "What NOT to Do"
|
||||
|
||||
```markdown
|
||||
## What NOT to Do
|
||||
|
||||
- ❌ **NEVER use bash/write/edit/task tools**
|
||||
- ❌ Don't assume—verify with tools
|
||||
- ❌ Don't fabricate information
|
||||
```
|
||||
|
||||
**Why**: Negative examples prevent common mistakes.
|
||||
|
||||
---
|
||||
|
||||
## File Size Targets
|
||||
|
||||
| Section | Target Lines | Purpose |
|
||||
|---------|--------------|---------|
|
||||
| Frontmatter | 30-50 | Agent metadata |
|
||||
| Critical Rules | 20-30 | Tool usage, core rules |
|
||||
| Context/Role/Task | 20-30 | Agent identity |
|
||||
| Execution Priority | 20-30 | Priority system |
|
||||
| Workflow | 80-120 | Main instructions |
|
||||
| Guidelines | 40-60 | Best practices |
|
||||
| **Total** | **<400 lines** | MVI compliant |
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Before deploying optimized prompt:
|
||||
|
||||
- [ ] Critical rules in first 15% (lines 50-80)?
|
||||
- [ ] Tool usage explicitly stated?
|
||||
- [ ] Nesting ≤4 levels?
|
||||
- [ ] Execution priority defined?
|
||||
- [ ] "What NOT to Do" section included?
|
||||
- [ ] Total lines <400?
|
||||
- [ ] Semantic meaning preserved?
|
||||
|
||||
---
|
||||
|
||||
## Real Example
|
||||
|
||||
**ContextScout Optimization**:
|
||||
- **Before**: 750 lines, critical rules at line 596
|
||||
- **After**: 394 lines (47.5% reduction), critical rules at line 50
|
||||
- **Result**: Test passed (was failing with 0 tool calls)
|
||||
|
||||
**Files**:
|
||||
- Optimized: `.opencode/agent/subagents/core/contextscout.md`
|
||||
- Backup: (example: `.opencode/agent/ContextScout-original-backup.md`)
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `concepts/subagent-testing-modes.md` - How to test optimized prompts
|
||||
- `guides/testing-subagents.md` - Verify tool usage works
|
||||
- `errors/tool-permission-errors.md` - Fix tool issues
|
||||
|
||||
**Reference**: `.opencode/command/prompt-engineering/prompt-optimizer.md` (optimization principles)
|
||||
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
|
||||
402
.opencode/context/openagents-repo/lookup/commands.md
Normal file
402
.opencode/context/openagents-repo/lookup/commands.md
Normal file
@@ -0,0 +1,402 @@
|
||||
<!-- Context: openagents-repo/lookup | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Lookup: Command Reference
|
||||
|
||||
**Purpose**: Quick reference for common commands
|
||||
|
||||
---
|
||||
|
||||
## Registry Commands
|
||||
|
||||
### Validate Registry
|
||||
|
||||
```bash
|
||||
# Basic validation
|
||||
./scripts/registry/validate-registry.sh
|
||||
|
||||
# Verbose output
|
||||
./scripts/registry/validate-registry.sh -v
|
||||
```
|
||||
|
||||
### Auto-Detect Components
|
||||
|
||||
```bash
|
||||
# Dry run (see what would change)
|
||||
./scripts/registry/auto-detect-components.sh --dry-run
|
||||
|
||||
# Add new components
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# Force update existing
|
||||
./scripts/registry/auto-detect-components.sh --auto-add --force
|
||||
```
|
||||
|
||||
### Validate Component Structure
|
||||
|
||||
```bash
|
||||
./scripts/registry/validate-component.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Commands
|
||||
|
||||
### Run Tests
|
||||
|
||||
```bash
|
||||
# Single test
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --pattern="{test}.yaml"
|
||||
|
||||
# All tests for agent
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent}
|
||||
|
||||
# All tests (all agents)
|
||||
bun --bun run eval:sdk
|
||||
|
||||
# With debug
|
||||
bun --bun run eval:sdk -- --agent={agent} --debug
|
||||
```
|
||||
|
||||
### Validate Test Suites
|
||||
|
||||
```bash
|
||||
./scripts/validation/validate-test-suites.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation Commands
|
||||
|
||||
### Install Components
|
||||
|
||||
```bash
|
||||
# List available components
|
||||
./install.sh --list
|
||||
|
||||
# Install profile
|
||||
./install.sh {profile}
|
||||
# Profiles: essential, developer, business
|
||||
|
||||
# Install specific component
|
||||
./install.sh --component agent:{agent-name}
|
||||
|
||||
# Test with local registry
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
```
|
||||
|
||||
### Collision Handling
|
||||
|
||||
```bash
|
||||
# Skip existing files
|
||||
./install.sh developer --skip-existing
|
||||
|
||||
# Overwrite all
|
||||
./install.sh developer --force
|
||||
|
||||
# Backup existing
|
||||
./install.sh developer --backup
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Version Commands
|
||||
|
||||
### Check Version
|
||||
|
||||
```bash
|
||||
# Check all version files
|
||||
cat VERSION
|
||||
cat package.json | jq '.version'
|
||||
cat registry.json | jq '.version'
|
||||
```
|
||||
|
||||
### Update Version
|
||||
|
||||
```bash
|
||||
# Update VERSION
|
||||
echo "0.X.Y" > VERSION
|
||||
|
||||
# Update package.json
|
||||
jq '.version = "0.X.Y"' package.json > tmp && mv tmp package.json
|
||||
|
||||
# Update registry.json
|
||||
jq '.version = "0.X.Y"' registry.json > tmp && mv tmp registry.json
|
||||
```
|
||||
|
||||
### Bump Version Script
|
||||
|
||||
```bash
|
||||
./scripts/versioning/bump-version.sh 0.X.Y
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git Commands
|
||||
|
||||
### Create Release
|
||||
|
||||
```bash
|
||||
# Commit version changes
|
||||
git add VERSION package.json CHANGELOG.md
|
||||
git commit -m "chore: bump version to 0.X.Y"
|
||||
|
||||
# Create tag
|
||||
git tag -a v0.X.Y -m "Release v0.X.Y"
|
||||
|
||||
# Push
|
||||
git push origin main
|
||||
git push origin v0.X.Y
|
||||
```
|
||||
|
||||
### Create GitHub Release
|
||||
|
||||
```bash
|
||||
# Via GitHub CLI
|
||||
gh release create v0.X.Y \
|
||||
--title "v0.X.Y" \
|
||||
--notes "See CHANGELOG.md for details"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Commands
|
||||
|
||||
### Full Validation
|
||||
|
||||
```bash
|
||||
# Validate everything
|
||||
./scripts/registry/validate-registry.sh && \
|
||||
./scripts/validation/validate-test-suites.sh && \
|
||||
cd evals/framework && bun --bun run eval:sdk
|
||||
```
|
||||
|
||||
### Check Context Dependencies
|
||||
|
||||
```bash
|
||||
# Analyze all agents
|
||||
/check-context-deps
|
||||
|
||||
# Analyze specific agent
|
||||
/check-context-deps contextscout
|
||||
|
||||
# Auto-fix missing dependencies
|
||||
/check-context-deps --fix
|
||||
```
|
||||
|
||||
### Validate Context References
|
||||
|
||||
```bash
|
||||
./scripts/validation/validate-context-refs.sh
|
||||
```
|
||||
|
||||
### Setup Pre-Commit Hook
|
||||
|
||||
```bash
|
||||
./scripts/validation/setup-pre-commit-hook.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Run Demo
|
||||
|
||||
```bash
|
||||
./scripts/development/demo.sh
|
||||
```
|
||||
|
||||
### Run Dashboard
|
||||
|
||||
```bash
|
||||
./scripts/development/dashboard.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Commands
|
||||
|
||||
### Cleanup Stale Sessions
|
||||
|
||||
```bash
|
||||
./scripts/maintenance/cleanup-stale-sessions.sh
|
||||
```
|
||||
|
||||
### Uninstall
|
||||
|
||||
```bash
|
||||
./scripts/maintenance/uninstall.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging Commands
|
||||
|
||||
### Check Sessions
|
||||
|
||||
```bash
|
||||
# List recent sessions
|
||||
ls -lt .tmp/sessions/ | head -5
|
||||
|
||||
# View session
|
||||
cat .tmp/sessions/{session-id}/session.json | jq
|
||||
|
||||
# View events
|
||||
cat .tmp/sessions/{session-id}/events.json | jq
|
||||
```
|
||||
|
||||
### Check Context Logs
|
||||
|
||||
```bash
|
||||
# Check session cache
|
||||
./scripts/check-context-logs/check-session-cache.sh
|
||||
|
||||
# Count agent tokens
|
||||
./scripts/check-context-logs/count-agent-tokens.sh
|
||||
|
||||
# Show API payload
|
||||
./scripts/check-context-logs/show-api-payload.sh
|
||||
|
||||
# Show cached data
|
||||
./scripts/check-context-logs/show-cached-data.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Workflows
|
||||
|
||||
### Adding a New Agent
|
||||
|
||||
```bash
|
||||
# 1. Create agent file
|
||||
touch .opencode/agent/{category}/{agent-name}.md
|
||||
# (Add frontmatter and content)
|
||||
|
||||
# 2. Create test structure
|
||||
mkdir -p evals/agents/{category}/{agent-name}/{config,tests}
|
||||
# (Create config.yaml and smoke-test.yaml)
|
||||
|
||||
# 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={category}/{agent-name}
|
||||
```
|
||||
|
||||
### Testing an Agent
|
||||
|
||||
```bash
|
||||
# 1. Run smoke test
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --pattern="smoke-test.yaml"
|
||||
|
||||
# 2. If fails, debug
|
||||
bun --bun run eval:sdk -- --agent={category}/{agent} --debug
|
||||
|
||||
# 3. Check session
|
||||
ls -lt .tmp/sessions/ | head -1
|
||||
cat .tmp/sessions/{session-id}/session.json | jq
|
||||
```
|
||||
|
||||
### Creating a Release
|
||||
|
||||
```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)
|
||||
|
||||
# 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
|
||||
|
||||
# 5. Create GitHub release
|
||||
gh release create v0.X.Y --title "v0.X.Y" --notes "See CHANGELOG.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Find Files
|
||||
|
||||
```bash
|
||||
# Find agent
|
||||
find .opencode/agent -name "{agent-name}.md"
|
||||
|
||||
# Find tests
|
||||
find evals/agents -name "*.yaml"
|
||||
|
||||
# Find context
|
||||
find .opencode/context -name "*.md"
|
||||
|
||||
# Find scripts
|
||||
find scripts -name "*.sh"
|
||||
```
|
||||
|
||||
### Check Registry
|
||||
|
||||
```bash
|
||||
# List all agents
|
||||
cat registry.json | jq '.components.agents[].id'
|
||||
|
||||
# Check specific component
|
||||
cat registry.json | jq '.components.agents[] | select(.id == "{agent-name}")'
|
||||
|
||||
# Count components
|
||||
cat registry.json | jq '.components.agents | length'
|
||||
```
|
||||
|
||||
### Test Locally
|
||||
|
||||
```bash
|
||||
# Test with local registry
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
|
||||
# Install locally
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh developer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## NPM Commands (Eval Framework)
|
||||
|
||||
```bash
|
||||
cd evals/framework
|
||||
|
||||
# Install dependencies
|
||||
bun --bun install
|
||||
|
||||
# Run tests
|
||||
bun --bun test
|
||||
|
||||
# Run eval SDK
|
||||
bun --bun run eval:sdk
|
||||
|
||||
# Build
|
||||
bun --bun run build
|
||||
|
||||
# Lint
|
||||
bun --bun run lint
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Quick start**: `quick-start.md`
|
||||
- **File locations**: `lookup/file-locations.md`
|
||||
- **Guides**: `guides/`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-10
|
||||
**Version**: 0.5.0
|
||||
312
.opencode/context/openagents-repo/lookup/file-locations.md
Normal file
312
.opencode/context/openagents-repo/lookup/file-locations.md
Normal file
@@ -0,0 +1,312 @@
|
||||
<!-- Context: openagents-repo/lookup | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Lookup: File Locations
|
||||
|
||||
**Purpose**: Quick reference for finding files
|
||||
|
||||
---
|
||||
|
||||
## Directory Tree
|
||||
|
||||
```
|
||||
opencode-agents/
|
||||
├── .opencode/
|
||||
│ ├── agent/
|
||||
│ │ ├── core/ # Core system agents
|
||||
│ │ ├── development/ # Dev specialists
|
||||
│ │ ├── content/ # Content creators
|
||||
│ │ ├── data/ # Data analysts
|
||||
│ │ ├── product/ # Product managers (ready)
|
||||
│ │ ├── learning/ # Educators (ready)
|
||||
│ │ └── subagents/ # Delegated specialists
|
||||
│ │ ├── code/ # Code-related
|
||||
│ │ ├── core/ # Core workflows
|
||||
│ │ ├── system-builder/ # System generation
|
||||
│ │ └── utils/ # Utilities
|
||||
│ ├── command/ # Slash commands
|
||||
│ ├── context/ # Shared knowledge
|
||||
│ │ ├── core/ # Core standards & workflows
|
||||
│ │ ├── development/ # Dev context
|
||||
│ │ ├── content-creation/ # Content creation context
|
||||
│ │ ├── data/ # Data context
|
||||
│ │ ├── product/ # Product context
|
||||
│ │ ├── learning/ # Learning context
|
||||
│ │ └── openagents-repo/ # Repo-specific context
|
||||
│ ├── prompts/ # Model-specific variants
|
||||
│ ├── tool/ # Custom tools
|
||||
│ └── plugin/ # Plugins
|
||||
├── evals/
|
||||
│ ├── framework/ # Eval framework (TypeScript)
|
||||
│ │ ├── src/ # Source code
|
||||
│ │ ├── scripts/ # Test utilities
|
||||
│ │ └── docs/ # Framework docs
|
||||
│ └── agents/ # Agent test suites
|
||||
│ ├── core/ # Core agent tests
|
||||
│ ├── development/ # Dev agent tests
|
||||
│ └── content/ # Content agent tests
|
||||
├── scripts/
|
||||
│ ├── registry/ # Registry management
|
||||
│ ├── validation/ # Validation tools
|
||||
│ ├── testing/ # Test utilities
|
||||
│ ├── versioning/ # Version management
|
||||
│ ├── docs/ # Doc tools
|
||||
│ └── maintenance/ # Maintenance
|
||||
├── docs/ # Documentation
|
||||
│ ├── agents/ # Agent docs
|
||||
│ ├── contributing/ # Contribution guides
|
||||
│ ├── features/ # Feature docs
|
||||
│ └── getting-started/ # User guides
|
||||
├── registry.json # Component catalog
|
||||
├── install.sh # Installer
|
||||
├── VERSION # Current version
|
||||
└── package.json # Node dependencies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Where Is...?
|
||||
|
||||
| Component | Location |
|
||||
|-----------|----------|
|
||||
| **Core agents** | `.opencode/agent/core/` |
|
||||
| **Category agents** | `.opencode/agent/{category}/` |
|
||||
| **Subagents** | `.opencode/agent/subagents/` |
|
||||
| **Commands** | `.opencode/command/` |
|
||||
| **Context files** | `.opencode/context/` |
|
||||
| **Prompt variants** | `.opencode/prompts/{category}/{agent}/` |
|
||||
| **Tools** | `.opencode/tool/` |
|
||||
| **Plugins** | `.opencode/plugin/` |
|
||||
| **Agent tests** | `evals/agents/{category}/{agent}/` |
|
||||
| **Eval framework** | `evals/framework/src/` |
|
||||
| **Registry scripts** | `scripts/registry/` |
|
||||
| **Validation scripts** | `scripts/validation/` |
|
||||
| **Documentation** | `docs/` |
|
||||
| **Registry** | `registry.json` |
|
||||
| **Installer** | `install.sh` |
|
||||
| **Version** | `VERSION` |
|
||||
|
||||
---
|
||||
|
||||
## Where Do I Add...?
|
||||
|
||||
| What | Where |
|
||||
|------|-------|
|
||||
| **New core agent** | `.opencode/agent/core/{name}.md` |
|
||||
| **New category agent** | `.opencode/agent/{category}/{name}.md` |
|
||||
| **New subagent** | `.opencode/agent/subagents/{category}/{name}.md` |
|
||||
| **New command** | `.opencode/command/{name}.md` |
|
||||
| **New context** | `.opencode/context/{category}/{name}.md` |
|
||||
| **Agent tests** | `evals/agents/{category}/{agent}/tests/` |
|
||||
| **Test config** | `evals/agents/{category}/{agent}/config/config.yaml` |
|
||||
| **Documentation** | `docs/{section}/{topic}.md` |
|
||||
| **Script** | `scripts/{purpose}/{name}.sh` |
|
||||
|
||||
---
|
||||
|
||||
## Specific File Paths
|
||||
|
||||
### Core Files
|
||||
|
||||
```
|
||||
registry.json # Component catalog
|
||||
install.sh # Main installer
|
||||
update.sh # Update script
|
||||
VERSION # Current version (0.5.0)
|
||||
package.json # Node dependencies
|
||||
CHANGELOG.md # Release notes
|
||||
README.md # Main documentation
|
||||
```
|
||||
|
||||
### Core Agents
|
||||
|
||||
```
|
||||
.opencode/agent/core/openagent.md
|
||||
.opencode/agent/core/opencoder.md
|
||||
.opencode/agent/meta/system-builder.md
|
||||
```
|
||||
|
||||
### Development Agents
|
||||
|
||||
```
|
||||
.opencode/agent/subagents/development/frontend-specialist.md
|
||||
.opencode/agent/subagents/development/devops-specialist.md
|
||||
```
|
||||
|
||||
### Content Agents
|
||||
|
||||
```
|
||||
.opencode/agent/content/copywriter.md
|
||||
.opencode/agent/content/technical-writer.md
|
||||
```
|
||||
|
||||
### Key Subagents
|
||||
|
||||
```
|
||||
.opencode/agent/subagents/code/test-engineer.md
|
||||
.opencode/agent/subagents/code/reviewer.md
|
||||
.opencode/agent/subagents/code/coder-agent.md
|
||||
.opencode/agent/subagents/core/task-manager.md
|
||||
.opencode/agent/subagents/core/documentation.md
|
||||
```
|
||||
|
||||
### Core Context
|
||||
|
||||
```
|
||||
.opencode/context/core/standards/code-quality.md
|
||||
.opencode/context/core/standards/documentation.md
|
||||
.opencode/context/core/standards/test-coverage.md
|
||||
.opencode/context/core/standards/security-patterns.md
|
||||
.opencode/context/core/workflows/task-delegation-basics.md
|
||||
.opencode/context/core/workflows/code-review.md
|
||||
```
|
||||
|
||||
### Registry Scripts
|
||||
|
||||
```
|
||||
scripts/registry/validate-registry.sh
|
||||
scripts/registry/auto-detect-components.sh
|
||||
scripts/registry/register-component.sh
|
||||
scripts/registry/validate-component.sh
|
||||
```
|
||||
|
||||
### Validation Scripts
|
||||
|
||||
```
|
||||
scripts/validation/validate-context-refs.sh
|
||||
scripts/validation/validate-test-suites.sh
|
||||
scripts/validation/setup-pre-commit-hook.sh
|
||||
```
|
||||
|
||||
### Eval Framework
|
||||
|
||||
```
|
||||
evals/framework/src/sdk/ # Test runner
|
||||
evals/framework/src/evaluators/ # Rule evaluators
|
||||
evals/framework/src/collector/ # Session collection
|
||||
evals/framework/src/types/ # TypeScript types
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Path Patterns
|
||||
|
||||
### Agents
|
||||
|
||||
```
|
||||
.opencode/agent/{category}/{agent-name}.md
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
- `.opencode/agent/subagents/development/frontend-specialist.md`
|
||||
- `.opencode/agent/subagents/code/test-engineer.md`
|
||||
|
||||
### Context
|
||||
|
||||
```
|
||||
.opencode/context/{category}/{topic}.md
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
- `.opencode/context/core/standards/code-quality.md`
|
||||
- `.opencode/context/ui/web/react-patterns.md`
|
||||
- `.opencode/context/content-creation/principles/copywriting-frameworks.md`
|
||||
|
||||
### Tests
|
||||
|
||||
```
|
||||
evals/agents/{category}/{agent-name}/
|
||||
├── config/config.yaml
|
||||
└── tests/{test-name}.yaml
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
- `evals/agents/core/openagent/tests/smoke-test.yaml`
|
||||
- `evals/agents/development/frontend-specialist/tests/approval-gate.yaml`
|
||||
|
||||
### Scripts
|
||||
|
||||
```
|
||||
scripts/{purpose}/{action}-{target}.sh
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
- `scripts/registry/validate-registry.sh`
|
||||
- `scripts/validation/validate-test-suites.sh`
|
||||
- `scripts/versioning/bump-version.sh`
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Files
|
||||
|
||||
- **Agents**: `{name}.md` or `{domain}-specialist.md`
|
||||
- **Context**: `{topic}.md`
|
||||
- **Tests**: `{test-name}.yaml`
|
||||
- **Scripts**: `{action}-{target}.sh`
|
||||
- **Docs**: `{topic}.md`
|
||||
|
||||
### Directories
|
||||
|
||||
- **Categories**: lowercase, singular (e.g., `development`, `content`)
|
||||
- **Purposes**: lowercase, descriptive (e.g., `registry`, `validation`)
|
||||
|
||||
---
|
||||
|
||||
## Quick Lookups
|
||||
|
||||
### Find Agent File
|
||||
|
||||
```bash
|
||||
# By name
|
||||
find .opencode/agent -name "{agent-name}.md"
|
||||
|
||||
# By category
|
||||
ls .opencode/agent/{category}/
|
||||
|
||||
# All agents
|
||||
find .opencode/agent -name "*.md" -not -path "*/subagents/*"
|
||||
```
|
||||
|
||||
### Find Test File
|
||||
|
||||
```bash
|
||||
# By agent
|
||||
ls evals/agents/{category}/{agent}/tests/
|
||||
|
||||
# All tests
|
||||
find evals/agents -name "*.yaml"
|
||||
```
|
||||
|
||||
### Find Context File
|
||||
|
||||
```bash
|
||||
# By category
|
||||
ls .opencode/context/{category}/
|
||||
|
||||
# All context
|
||||
find .opencode/context -name "*.md"
|
||||
```
|
||||
|
||||
### Find Script
|
||||
|
||||
```bash
|
||||
# By purpose
|
||||
ls scripts/{purpose}/
|
||||
|
||||
# All scripts
|
||||
find scripts -name "*.sh"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Quick start**: `quick-start.md`
|
||||
- **Categories**: `core-concepts/categories.md`
|
||||
- **Commands**: `lookup/commands.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-10
|
||||
**Version**: 0.5.0
|
||||
40
.opencode/context/openagents-repo/lookup/navigation.md
Normal file
40
.opencode/context/openagents-repo/lookup/navigation.md
Normal file
@@ -0,0 +1,40 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Lookup
|
||||
|
||||
**Purpose**: Quick reference and lookup tables for OpenAgents Control
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/lookup/
|
||||
├── navigation.md (this file)
|
||||
└── [lookup reference files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **View lookups** | `./` |
|
||||
| **Guides** | `../guides/navigation.md` |
|
||||
| **Core Concepts** | `../core-concepts/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Quick Reference** → Fast lookup tables and commands
|
||||
**Checklists** → Verification and validation checklists
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Guides** → `../guides/navigation.md`
|
||||
- **Core Concepts** → `../core-concepts/navigation.md`
|
||||
@@ -0,0 +1,78 @@
|
||||
<!-- Context: openagents-repo/lookup | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Lookup: Subagent Framework Maps
|
||||
|
||||
**Purpose**: Quick reference for adding subagents to eval framework
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Critical: THREE Maps Must Be Updated
|
||||
|
||||
When adding a new subagent, update these THREE locations:
|
||||
|
||||
### 1. Parent Map (run-sdk-tests.ts ~line 336)
|
||||
**Purpose**: Maps subagent → parent agent for delegation testing
|
||||
|
||||
```typescript
|
||||
const subagentParentMap: Record<string, string> = {
|
||||
'contextscout': 'openagent', // Core subagents → openagent
|
||||
'task-manager': 'openagent',
|
||||
'documentation': 'openagent',
|
||||
|
||||
'coder-agent': 'opencoder', // Code subagents → opencoder
|
||||
'tester': 'opencoder',
|
||||
'reviewer': 'opencoder',
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Path Map (run-sdk-tests.ts ~line 414)
|
||||
**Purpose**: Maps subagent name → file path for test discovery
|
||||
|
||||
```typescript
|
||||
const subagentPathMap: Record<string, string> = {
|
||||
'contextscout': 'ContextScout',
|
||||
'task-manager': 'TaskManager',
|
||||
'coder-agent': 'CoderAgent',
|
||||
};
|
||||
```
|
||||
|
||||
### 3. Agent Map (test-runner.ts ~line 238)
|
||||
**Purpose**: Maps subagent name → agent file for eval-runner
|
||||
|
||||
```typescript
|
||||
const agentMap: Record<string, string> = {
|
||||
'contextscout': 'ContextScout.md',
|
||||
'task-manager': 'TaskManager.md',
|
||||
'coder-agent': 'CoderAgent.md',
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Messages
|
||||
|
||||
| Error | Missing From | Fix |
|
||||
|-------|--------------|-----|
|
||||
| "No test files found" | Path Map (#2) | Add to `subagentPathMap` |
|
||||
| "Unknown subagent" | Parent Map (#1) | Add to `subagentParentMap` |
|
||||
| "Agent file not found" | Agent Map (#3) | Add to `agentMap` |
|
||||
|
||||
---
|
||||
|
||||
## Testing Commands
|
||||
|
||||
```bash
|
||||
# Standalone mode (forces mode: primary)
|
||||
bun --bun run eval:sdk -- --subagent=contextscout
|
||||
|
||||
# Delegation mode (tests via parent)
|
||||
bun --bun run eval:sdk -- --subagent=contextscout --delegate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `guides/testing-subagents.md` - Full testing guide
|
||||
- `guides/adding-agent.md` - Creating new agents
|
||||
@@ -0,0 +1,194 @@
|
||||
<!-- Context: openagents-repo/lookup | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Subagent Testing Commands - Quick Reference
|
||||
|
||||
**Purpose**: Quick command reference for testing subagents
|
||||
|
||||
**Last Updated**: 2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## Standalone Mode (Unit Testing)
|
||||
|
||||
### Run All Standalone Tests
|
||||
```bash
|
||||
cd evals/framework
|
||||
bun --bun run eval:sdk -- --subagent=ContextScout --pattern="standalone/*.yaml"
|
||||
```
|
||||
|
||||
### Run Single Test
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --subagent=ContextScout --pattern="standalone/01-simple-discovery.yaml"
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --subagent=ContextScout --pattern="standalone/*.yaml" --debug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Delegation Mode (Integration Testing)
|
||||
|
||||
### Run Delegation Tests
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --agent=core/openagent --pattern="delegation/*.yaml"
|
||||
```
|
||||
|
||||
### Test Specific Delegation
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --agent=core/openagent --pattern="delegation/01-contextscout-delegation.yaml"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Commands
|
||||
|
||||
### Check Agent File
|
||||
```bash
|
||||
# View agent frontmatter
|
||||
head -30 .opencode/agent/subagents/core/contextscout.md
|
||||
|
||||
# Check tool permissions
|
||||
grep -A 10 "^tools:" .opencode/agent/subagents/core/contextscout.md
|
||||
```
|
||||
|
||||
### Check Test Config
|
||||
```bash
|
||||
cat evals/agents/ContextScout/config/config.yaml
|
||||
```
|
||||
|
||||
### View Latest Results
|
||||
```bash
|
||||
# Summary
|
||||
cat evals/results/latest.json | jq '.summary'
|
||||
|
||||
# Agent loaded
|
||||
cat evals/results/latest.json | jq '.meta.agent'
|
||||
|
||||
# Tool calls
|
||||
cat evals/results/latest.json | jq '.tests[0]' | grep -A 5 "Tool"
|
||||
|
||||
# Violations
|
||||
cat evals/results/latest.json | jq '.tests[0].violations'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Test Patterns
|
||||
|
||||
### Smoke Test
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --subagent=ContextScout --pattern="smoke-test.yaml"
|
||||
```
|
||||
|
||||
### Specific Test Suite
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --subagent=ContextScout --pattern="discovery/*.yaml"
|
||||
```
|
||||
|
||||
### All Tests for Subagent
|
||||
```bash
|
||||
bun --bun run eval:sdk -- --subagent=ContextScout
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Flag Reference
|
||||
|
||||
| Flag | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| `--subagent` | Test subagent in standalone mode | `--subagent=ContextScout` |
|
||||
| `--agent` | Test primary agent (or delegation) | `--agent=core/openagent` |
|
||||
| `--pattern` | Filter test files | `--pattern="standalone/*.yaml"` |
|
||||
| `--debug` | Show detailed output | `--debug` |
|
||||
| `--timeout` | Override timeout | `--timeout=120000` |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Commands
|
||||
|
||||
### Check Which Agent Ran
|
||||
```bash
|
||||
# Should show subagent name for standalone mode
|
||||
cat evals/results/latest.json | jq '.meta.agent'
|
||||
```
|
||||
|
||||
### Check Tool Usage
|
||||
```bash
|
||||
# Should show tool calls > 0
|
||||
cat evals/results/latest.json | jq '.tests[0]' | grep "Tool Calls"
|
||||
```
|
||||
|
||||
### View Test Timeline
|
||||
```bash
|
||||
# See full conversation
|
||||
cat evals/results/history/2026-01/07-*.json | jq '.tests[0].timeline'
|
||||
```
|
||||
|
||||
### Check for Errors
|
||||
```bash
|
||||
# View violations
|
||||
cat evals/results/latest.json | jq '.tests[0].violations.details'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
|
||||
### Agent Files
|
||||
```
|
||||
.opencode/agent/subagents/core/{subagent}.md
|
||||
```
|
||||
|
||||
### Test Files
|
||||
```
|
||||
evals/agents/subagents/core/{subagent}/
|
||||
├── config/config.yaml
|
||||
└── tests/
|
||||
├── standalone/
|
||||
│ ├── 01-simple-discovery.yaml
|
||||
│ └── 02-advanced-test.yaml
|
||||
└── delegation/
|
||||
└── 01-delegation-test.yaml
|
||||
```
|
||||
|
||||
### Results
|
||||
```
|
||||
evals/results/
|
||||
├── latest.json # Latest test run
|
||||
└── history/2026-01/ # Historical results
|
||||
└── 07-HHMMSS-{agent}.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Checks
|
||||
|
||||
### Is Agent Loaded Correctly?
|
||||
```bash
|
||||
# Should show: "agent": "ContextScout"
|
||||
cat evals/results/latest.json | jq '.meta.agent'
|
||||
```
|
||||
|
||||
### Did Agent Use Tools?
|
||||
```bash
|
||||
# Should show: Tool Calls: 1 (or more)
|
||||
cat evals/results/latest.json | jq '.tests[0]' | grep "Tool Calls"
|
||||
```
|
||||
|
||||
### Did Test Pass?
|
||||
```bash
|
||||
# Should show: "passed": 1, "failed": 0
|
||||
cat evals/results/latest.json | jq '.summary'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `concepts/subagent-testing-modes.md` - Understand testing modes
|
||||
- `guides/testing-subagents.md` - Step-by-step testing guide
|
||||
- `errors/tool-permission-errors.md` - Fix common issues
|
||||
|
||||
**Reference**: `evals/framework/src/sdk/run-sdk-tests.ts`
|
||||
192
.opencode/context/openagents-repo/navigation.md
Normal file
192
.opencode/context/openagents-repo/navigation.md
Normal file
@@ -0,0 +1,192 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Control Repository Context
|
||||
|
||||
**Purpose**: Context files specific to the OpenAgents Control repository
|
||||
|
||||
**Last Updated**: 2026-02-04
|
||||
|
||||
---
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
| Function | Files | Purpose |
|
||||
|----------|-------|---------|
|
||||
| **Standards** | 2 files | Agent creation standards |
|
||||
| **Concepts** | 6 files | Core ideas and principles |
|
||||
| **Examples** | 9 files | Working code samples |
|
||||
| **Guides** | 14 files | Step-by-step workflows |
|
||||
| **Lookup** | 11 files | Quick reference tables |
|
||||
| **Errors** | 2 files | Common issues + solutions |
|
||||
| **Features** | 3 files | Feature documentation and refactoring |
|
||||
| **Plugins** | Context plugin system | Plugin architecture and capabilities |
|
||||
|
||||
---
|
||||
|
||||
## Standards (Agent Creation)
|
||||
|
||||
| File | Topic | Priority |
|
||||
|------|-------|----------|
|
||||
| `standards/agent-frontmatter.md` | Valid OpenCode YAML frontmatter | ⭐⭐⭐⭐⭐ |
|
||||
| `standards/subagent-structure.md` | Standard subagent file structure | ⭐⭐⭐⭐⭐ |
|
||||
|
||||
**When to read**: Before creating or modifying any agent files
|
||||
|
||||
---
|
||||
|
||||
## Concepts (Core Ideas)
|
||||
|
||||
| File | Topic | Priority |
|
||||
|------|-------|----------|
|
||||
| `concepts/compatibility-layer.md` | Adapter pattern for AI coding tools | ⭐⭐⭐⭐⭐ |
|
||||
| `concepts/subagent-testing-modes.md` | Standalone vs delegation testing | ⭐⭐⭐⭐⭐ |
|
||||
| `concepts/hooks-system.md` | User-defined lifecycle commands | ⭐⭐⭐⭐ |
|
||||
| `concepts/agent-skills.md` | Skills that teach Claude tasks | ⭐⭐⭐⭐ |
|
||||
| `concepts/subagents-system.md` | Specialized AI assistants | ⭐⭐⭐⭐ |
|
||||
|
||||
**When to read**: Before testing any subagent or working with tool adapters
|
||||
|
||||
---
|
||||
|
||||
## Examples (Working Code)
|
||||
|
||||
| File | Topic | Priority |
|
||||
|------|-------|----------|
|
||||
| `examples/baseadapter-pattern.md` | Template Method pattern for tool adapters | ⭐⭐⭐⭐⭐ |
|
||||
| `examples/zod-schema-migration.md` | Migrating TypeScript to Zod schemas | ⭐⭐⭐⭐ |
|
||||
| `examples/subagent-prompt-structure.md` | Optimized subagent prompt template | ⭐⭐⭐⭐ |
|
||||
|
||||
**When to read**: When creating adapters, schemas, or optimizing subagent prompts
|
||||
|
||||
---
|
||||
|
||||
## Guides (Step-by-Step)
|
||||
|
||||
| File | Topic | Priority |
|
||||
|------|-------|----------|
|
||||
| `guides/compatibility-layer-workflow.md` | Developing compatibility layer for AI tools | ⭐⭐⭐⭐⭐ |
|
||||
| `guides/testing-subagents.md` | How to test subagents standalone | ⭐⭐⭐⭐⭐ |
|
||||
| `guides/adding-agent-basics.md` | How to add new agents (basics) | ⭐⭐⭐⭐ |
|
||||
| `guides/adding-agent-testing.md` | How to add agent tests | ⭐⭐⭐⭐ |
|
||||
| `guides/adding-skill-basics.md` | How to add OpenCode skills | ⭐⭐⭐⭐ |
|
||||
| `guides/creating-skills.md` | How to create Claude Code skills | ⭐⭐⭐⭐ |
|
||||
| `guides/creating-subagents.md` | How to create Claude Code subagents | ⭐⭐⭐⭐ |
|
||||
| `guides/testing-agent.md` | How to test agents | ⭐⭐⭐⭐ |
|
||||
| `guides/external-libraries-workflow.md` | How to handle external library dependencies | ⭐⭐⭐⭐ |
|
||||
| `guides/github-issues-workflow.md` | How to work with GitHub issues and project board | ⭐⭐⭐⭐ |
|
||||
| `guides/npm-publishing.md` | How to publish package to bun --bun | ⭐⭐⭐ |
|
||||
| `guides/updating-registry.md` | How to update registry | ⭐⭐⭐ |
|
||||
| `guides/debugging.md` | How to debug issues | ⭐⭐⭐ |
|
||||
| `guides/resolving-installer-wildcard-failures.md` | Fix wildcard context install failures | ⭐⭐⭐ |
|
||||
| `guides/creating-release.md` | How to create releases | ⭐⭐ |
|
||||
|
||||
**When to read**: When performing specific tasks
|
||||
|
||||
---
|
||||
|
||||
## Lookup (Quick Reference)
|
||||
|
||||
| File | Topic | Priority |
|
||||
|------|-------|----------|
|
||||
| `lookup/tool-feature-parity.md` | AI coding tool feature comparison | ⭐⭐⭐⭐⭐ |
|
||||
| `lookup/compatibility-layer-structure.md` | Compatibility package file structure | ⭐⭐⭐⭐⭐ |
|
||||
| `lookup/subagent-test-commands.md` | Subagent testing commands | ⭐⭐⭐⭐⭐ |
|
||||
| `lookup/hook-events.md` | All hook events reference | ⭐⭐⭐⭐ |
|
||||
| `lookup/skill-metadata.md` | SKILL.md frontmatter fields | ⭐⭐⭐⭐ |
|
||||
| `lookup/skills-comparison.md` | Skills vs other options | ⭐⭐⭐⭐ |
|
||||
| `lookup/builtin-subagents.md` | Default subagents (Explore, Plan) | ⭐⭐⭐⭐ |
|
||||
| `lookup/subagent-frontmatter.md` | Subagent configuration fields | ⭐⭐⭐⭐ |
|
||||
| `lookup/file-locations.md` | Where files are located | ⭐⭐⭐⭐ |
|
||||
| `lookup/commands.md` | Available slash commands | ⭐⭐⭐ |
|
||||
|
||||
**When to read**: Quick command lookups and feature comparisons
|
||||
|
||||
---
|
||||
|
||||
## Errors (Troubleshooting)
|
||||
|
||||
| File | Topic | Priority |
|
||||
|------|-------|----------|
|
||||
| `errors/tool-permission-errors.md` | Tool permission issues | ⭐⭐⭐⭐⭐ |
|
||||
| `errors/skills-errors.md` | Skills not triggering/loading | ⭐⭐⭐⭐ |
|
||||
|
||||
**When to read**: When tests fail with permission errors
|
||||
|
||||
---
|
||||
|
||||
## Core Concepts (Foundational)
|
||||
|
||||
| File | Topic | Priority |
|
||||
|------|-------|----------|
|
||||
| `core-concepts/agents.md` | How agents work | ⭐⭐⭐⭐⭐ |
|
||||
| `core-concepts/evals.md` | How testing works | ⭐⭐⭐⭐⭐ |
|
||||
| `core-concepts/registry.md` | How registry works | ⭐⭐⭐⭐ |
|
||||
| `core-concepts/categories.md` | How organization works | ⭐⭐⭐ |
|
||||
|
||||
**When to read**: First time working in this repo
|
||||
|
||||
---
|
||||
|
||||
## Loading Strategy
|
||||
|
||||
### For Subagent Testing:
|
||||
1. Load `concepts/subagent-testing-modes.md` (understand modes)
|
||||
2. Load `guides/testing-subagents.md` (step-by-step)
|
||||
3. Reference `lookup/subagent-test-commands.md` (commands)
|
||||
4. If errors: Load `errors/tool-permission-errors.md`
|
||||
|
||||
### For Agent Creation:
|
||||
1. Load `standards/agent-frontmatter.md` (valid YAML frontmatter)
|
||||
2. Load `standards/subagent-structure.md` (file structure)
|
||||
3. Load `core-concepts/agents.md` (understand system)
|
||||
4. Load `guides/adding-agent-basics.md` (step-by-step)
|
||||
5. **If using external libraries**: Load `guides/external-libraries-workflow.md` (fetch docs)
|
||||
6. Load `examples/subagent-prompt-structure.md` (if subagent)
|
||||
7. Load `guides/testing-agent.md` (validate)
|
||||
|
||||
### For Issue Management:
|
||||
1. Load `guides/github-issues-workflow.md` (understand workflow)
|
||||
2. Create issues with proper labels and templates
|
||||
3. Add to project board for tracking
|
||||
4. Process requests systematically
|
||||
|
||||
### For Debugging:
|
||||
1. Load `guides/debugging.md` (general approach)
|
||||
2. Load specific error file from `errors/`
|
||||
3. Reference `lookup/file-locations.md` (find files)
|
||||
|
||||
---
|
||||
|
||||
## File Size Compliance
|
||||
|
||||
All files follow MVI principle (<200 lines):
|
||||
|
||||
- ✅ Standards: <200 lines
|
||||
- ✅ Concepts: <100 lines
|
||||
- ✅ Examples: <100 lines
|
||||
- ✅ Guides: <150 lines
|
||||
- ✅ Lookup: <100 lines
|
||||
- ✅ Errors: <150 lines
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- `../core/` - Core system context (standards, patterns)
|
||||
- `../core/context-system/` - Context management system
|
||||
- `quick-start.md` - 2-minute repo orientation
|
||||
- `../content-creation/navigation.md` - Content creation principles
|
||||
- `plugins/context/navigation.md` - Plugin system context
|
||||
- `features/navigation.md` - Feature documentation and refactoring guides
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
When adding new context files:
|
||||
|
||||
1. Follow MVI principle (<200 lines)
|
||||
2. Use function-based organization (concepts/, examples/, guides/, lookup/, errors/)
|
||||
3. Update this README.md navigation
|
||||
4. Add cross-references to related files
|
||||
5. Validate with `/context validate`
|
||||
@@ -0,0 +1,40 @@
|
||||
<!-- Context: openagents-repo/lifecycle | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Plugin Lifecycle & Packaging
|
||||
|
||||
## File Structure for Complex Plugins
|
||||
|
||||
For larger plugins, follow this recommended structure:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # Manifest (required for packaging)
|
||||
├── commands/ # Custom slash commands
|
||||
├── agents/ # Custom agents
|
||||
├── hooks/ # Event handlers
|
||||
└── README.md # Documentation
|
||||
```
|
||||
|
||||
## The Manifest (`plugin.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "A custom plugin",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `name` becomes the namespace prefix for commands: `/my-plugin:command`.
|
||||
|
||||
## SDK Access
|
||||
|
||||
Plugins have full access to the OpenCode SDK via `context.client`. This allows:
|
||||
- Sending prompts programmatically: `client.session.prompt()`
|
||||
- Managing sessions: `client.session.list()`, `client.session.get()`
|
||||
- Showing UI elements: `client.tui.showToast()`
|
||||
- Appending to prompt: `client.tui.appendPrompt()`
|
||||
@@ -0,0 +1,60 @@
|
||||
<!-- Context: openagents-repo/overview | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenCode Plugins Overview
|
||||
|
||||
OpenCode plugins are JavaScript or TypeScript modules that hook into **25+ events** across the entire OpenCode lifecycle—from when you type a prompt, to when tools execute, to when sessions complete.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- **Zero-Config**: No build step or compilation required. Just drop `.ts` or `.js` files into the plugin folder.
|
||||
- **Middleware Pattern**: Plugins subscribe to events and execute logic, similar to Express.js middleware.
|
||||
- **Access**: Plugins receive a `context` object with:
|
||||
- `project`: Current project metadata.
|
||||
- `client`: OpenCode SDK client for programmatic control.
|
||||
- `$`: Bun's shell API for running commands.
|
||||
- `directory`: Current working directory.
|
||||
- `worktree`: Git worktree path.
|
||||
|
||||
## Plugin Registration
|
||||
|
||||
OpenCode looks for plugins in:
|
||||
1. **Project-level**: `.opencode/plugin/` (project root)
|
||||
2. **Global**: `~/.config/opencode/plugin/` (home directory)
|
||||
|
||||
## Basic Structure
|
||||
|
||||
```typescript
|
||||
export const MyPlugin = async (context) => {
|
||||
const { project, client, $, directory, worktree } = context;
|
||||
|
||||
return {
|
||||
event: async ({ event }) => {
|
||||
// Handle events here
|
||||
}
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Each exported function becomes a separate plugin instance. The name of the export is used as the plugin name.
|
||||
|
||||
## Build and Development
|
||||
|
||||
OpenCode plugins are typically written in TypeScript and bundled into a single JavaScript file for execution.
|
||||
|
||||
### Build Command
|
||||
Use Bun to bundle the plugin into the `dist` directory:
|
||||
|
||||
```bash
|
||||
bun build src/index.ts --outdir dist --target bun --format esm
|
||||
```
|
||||
|
||||
The output will be a single file (e.g., `./index.js`) containing all dependencies.
|
||||
|
||||
### Development Workflow
|
||||
1. **Source Code**: Write your plugin in `src/index.ts`.
|
||||
2. **Bundle**: Run the build command to generate `dist/index.js`.
|
||||
3. **Load**: Point OpenCode to the bundled file or the directory containing the manifest.
|
||||
4. **Watch Mode**: For rapid development, use the `--watch` flag with Bun build:
|
||||
```bash
|
||||
bun build src/index.ts --outdir dist --target bun --format esm --watch
|
||||
```
|
||||
@@ -0,0 +1,46 @@
|
||||
<!-- Context: openagents-repo/agents | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Custom Agents in OpenCode
|
||||
|
||||
Plugins can register custom AI agents that have specific roles, instructions, and toolsets.
|
||||
|
||||
## Agent Definition
|
||||
|
||||
Custom agents are configured in the plugin's `config` function.
|
||||
|
||||
```typescript
|
||||
export const registerCustomAgents = (config) => {
|
||||
return {
|
||||
...config,
|
||||
agents: [
|
||||
{
|
||||
name: "my-helper",
|
||||
description: "A friendly assistant for this project",
|
||||
instructions: "You are a helpful assistant. Use your tools to help the user.",
|
||||
model: "claude-3-5-sonnet-latest", // Specify the model
|
||||
tools: ["say_hello", "read", "write"] // Reference built-in or custom tools
|
||||
}
|
||||
]
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Integrating into Plugin
|
||||
|
||||
The `config` method in the plugin return object is used to register agents.
|
||||
|
||||
```typescript
|
||||
export const MyPlugin: Plugin = async (context) => {
|
||||
return {
|
||||
config: async (currentConfig) => {
|
||||
return registerCustomAgents(currentConfig);
|
||||
},
|
||||
// ... other properties
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Agent Capabilities
|
||||
- **Model Choice**: You can select specific models for different agents.
|
||||
- **Scoped Tools**: Limit what tools an agent can use to ensure safety or focus.
|
||||
- **System Instructions**: Define the "personality" and rules for the agent.
|
||||
@@ -0,0 +1,44 @@
|
||||
<!-- Context: openagents-repo/events | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenCode Plugin Events
|
||||
|
||||
OpenCode fires over 25 events that you can hook into. These are categorized below:
|
||||
|
||||
## Command Events
|
||||
- `command.executed`: Fired when a user or plugin runs a command.
|
||||
|
||||
## File Events
|
||||
- `file.edited`: Fired when a file is modified via OpenCode tools.
|
||||
- `file.watcher.updated`: Fired when the file watcher detects changes.
|
||||
|
||||
## Message Events (Read-Only)
|
||||
- `message.updated`: Fired when a message in the session updates.
|
||||
- `message.part.updated`: Fired when individual parts of a message update.
|
||||
- `message.part.removed`: Fired when a part is removed.
|
||||
- `message.removed`: Fired when entire message is removed.
|
||||
|
||||
## Session Events
|
||||
- `session.created`: New session started.
|
||||
- `session.updated`: Session state changed.
|
||||
- `session.idle`: Session completed (no more activity expected).
|
||||
- `session.status`: Session status changed.
|
||||
- `session.error`: Error occurred in session.
|
||||
- `session.compacted`: Session was compacted (context summarized).
|
||||
|
||||
## Tool Events (Interception)
|
||||
- `tool.execute.before`: Fired before a tool runs. **Can block execution** by throwing an error.
|
||||
- `tool.execute.after`: Fired after a tool completes with result.
|
||||
|
||||
## TUI Events
|
||||
- `tui.prompt.append`: Text appended to prompt input.
|
||||
- `tui.command.execute`: Command executed from TUI.
|
||||
- `tui.toast.show`: Toast notification shown.
|
||||
|
||||
## Mapping from Claude Code Hooks
|
||||
|
||||
| Claude Hook | OpenCode Event |
|
||||
|---|---|
|
||||
| PreToolUse | tool.execute.before |
|
||||
| PostToolUse | tool.execute.after |
|
||||
| UserPromptSubmit | message.* events |
|
||||
| SessionEnd | session.idle |
|
||||
@@ -0,0 +1,598 @@
|
||||
<!-- Context: openagents-repo/events_skills | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenCode Events: Skills Plugin Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
This document explains how the OpenCode Skills Plugin uses event hooks (`tool.execute.before` and `tool.execute.after`) to implement skill delivery and output enhancement. This is a practical example of the event system described in `events.md`.
|
||||
|
||||
---
|
||||
|
||||
## Event Hooks Used
|
||||
|
||||
### tool.execute.before
|
||||
|
||||
**Event Type:** Tool Execution Interception
|
||||
|
||||
**When it fires:** Before a tool function executes
|
||||
|
||||
**Purpose in Skills Plugin:** Inject skill content into the conversation
|
||||
|
||||
**Implementation:**
|
||||
```typescript
|
||||
const beforeHook = async (input: any, output: any) => {
|
||||
// Check if this is a skill tool
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
// Look up skill from map
|
||||
const skill = skillMap.get(input.tool)
|
||||
if (skill) {
|
||||
// Inject skill content as silent prompt
|
||||
await ctx.client.session.prompt({
|
||||
path: { id: input.sessionID },
|
||||
body: {
|
||||
agent: input.agent,
|
||||
noReply: true, // Don't trigger AI response
|
||||
parts: [
|
||||
{
|
||||
type: "text",
|
||||
text: `📚 Skill: ${skill.name}\nBase directory: ${skill.fullPath}\n\n${skill.content}`,
|
||||
},
|
||||
],
|
||||
},
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why use this hook?**
|
||||
- Runs before tool execution, perfect for context injection
|
||||
- Can access tool name and session ID
|
||||
- Can inject content without triggering AI response
|
||||
- Skill content persists in conversation history
|
||||
|
||||
**Input Parameters:**
|
||||
- `input.tool` - Tool name (e.g., "skills_brand_guidelines")
|
||||
- `input.sessionID` - Current session ID
|
||||
- `input.agent` - Agent name that called the tool
|
||||
- `output.args` - Tool arguments
|
||||
|
||||
**What you can do:**
|
||||
- ✅ Inject context (skill content)
|
||||
- ✅ Validate inputs
|
||||
- ✅ Preprocess arguments
|
||||
- ✅ Log tool calls
|
||||
- ✅ Implement security checks
|
||||
|
||||
**What you can't do:**
|
||||
- ❌ Modify tool output (tool hasn't run yet)
|
||||
- ❌ Access tool results
|
||||
|
||||
---
|
||||
|
||||
### tool.execute.after
|
||||
|
||||
**Event Type:** Tool Execution Interception
|
||||
|
||||
**When it fires:** After a tool function completes
|
||||
|
||||
**Purpose in Skills Plugin:** Enhance output with visual feedback
|
||||
|
||||
**Implementation:**
|
||||
```typescript
|
||||
const afterHook = async (input: any, output: any) => {
|
||||
// Check if this is a skill tool
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
// Look up skill from map
|
||||
const skill = skillMap.get(input.tool)
|
||||
if (skill && output.output) {
|
||||
// Add emoji title for visual feedback
|
||||
output.title = `📚 ${skill.name}`
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why use this hook?**
|
||||
- Runs after tool execution, perfect for output enhancement
|
||||
- Can modify output properties
|
||||
- Can add visual feedback (emoji titles)
|
||||
- Can implement logging/analytics
|
||||
|
||||
**Input Parameters:**
|
||||
- `input.tool` - Tool name (e.g., "skills_brand_guidelines")
|
||||
- `input.sessionID` - Current session ID
|
||||
- `output.output` - Tool result/output
|
||||
- `output.title` - Output title (can be modified)
|
||||
|
||||
**What you can do:**
|
||||
- ✅ Modify output
|
||||
- ✅ Add titles/formatting
|
||||
- ✅ Log completion
|
||||
- ✅ Add analytics
|
||||
- ✅ Transform results
|
||||
|
||||
**What you can't do:**
|
||||
- ❌ Modify tool arguments (already executed)
|
||||
- ❌ Prevent tool execution (already happened)
|
||||
|
||||
---
|
||||
|
||||
## Event Lifecycle in Skills Plugin
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ AGENT CALLS SKILL TOOL │
|
||||
│ (e.g., skills_brand_guidelines) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ EVENT: tool.execute.before fires │
|
||||
│ │
|
||||
│ Hook Function: beforeHook(input, output) │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ 1. Check: input.tool.startsWith("skills_") │ │
|
||||
│ │ 2. Lookup: skillMap.get(input.tool) │ │
|
||||
│ │ 3. Inject: ctx.client.session.prompt({ │ │
|
||||
│ │ path: { id: input.sessionID }, │ │
|
||||
│ │ body: { │ │
|
||||
│ │ agent: input.agent, │ │
|
||||
│ │ noReply: true, │ │
|
||||
│ │ parts: [{ type: "text", text: skill.content }] │ │
|
||||
│ │ } │ │
|
||||
│ │ }) │ │
|
||||
│ │ 4. Result: Skill content added to conversation │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Effect: Skill content persists in conversation history │
|
||||
│ No AI response triggered (noReply: true) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ TOOL.EXECUTE() RUNS │
|
||||
│ │
|
||||
│ async execute(args, toolCtx) { │
|
||||
│ return `Skill activated: ${skill.name}` │
|
||||
│ } │
|
||||
│ │
|
||||
│ Effect: Minimal confirmation returned │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ EVENT: tool.execute.after fires │
|
||||
│ │
|
||||
│ Hook Function: afterHook(input, output) │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ 1. Check: input.tool.startsWith("skills_") │ │
|
||||
│ │ 2. Lookup: skillMap.get(input.tool) │ │
|
||||
│ │ 3. Verify: output.output exists │ │
|
||||
│ │ 4. Enhance: output.title = `📚 ${skill.name}` │ │
|
||||
│ │ 5. Result: Output title modified with emoji │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Effect: Visual feedback added to output │
|
||||
│ Could add logging/analytics here │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ RESULT RETURNED TO AGENT │
|
||||
│ │
|
||||
│ - Tool confirmation message │
|
||||
│ - Skill content in conversation history │
|
||||
│ - Enhanced output with emoji title │
|
||||
│ - Agent can now use skill content in reasoning │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why Hooks Instead of Embedded Logic?
|
||||
|
||||
### Problem: Embedded Delivery (Anti-Pattern)
|
||||
|
||||
```typescript
|
||||
// ❌ OLD: Skill delivery inside tool.execute()
|
||||
async execute(args, toolCtx) {
|
||||
const sendSilentPrompt = (text: string) =>
|
||||
ctx.client.session.prompt({...})
|
||||
|
||||
await sendSilentPrompt(`The "${skill.name}" skill is loading...`)
|
||||
await sendSilentPrompt(`Base directory: ${skill.fullPath}\n\n${skill.content}`)
|
||||
|
||||
return `Launching skill: ${skill.name}`
|
||||
}
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
1. **Tight Coupling**: Tool logic and delivery are inseparable
|
||||
2. **Hard to Test**: Can't test tool without testing delivery
|
||||
3. **Violates SOLID**: Single Responsibility Principle broken
|
||||
4. **No Reusability**: Delivery logic can't be extracted
|
||||
5. **Difficult to Monitor**: Can't track delivery separately
|
||||
|
||||
---
|
||||
|
||||
### Solution: Hook-Based Delivery (Best Practice)
|
||||
|
||||
```typescript
|
||||
// ✅ NEW: Separated concerns using hooks
|
||||
|
||||
// Tool: Minimal and focused
|
||||
async execute(args, toolCtx) {
|
||||
return `Skill activated: ${skill.name}`
|
||||
}
|
||||
|
||||
// Hook: Handles delivery
|
||||
const beforeHook = async (input, output) => {
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
const skill = skillMap.get(input.tool)
|
||||
if (skill) {
|
||||
await ctx.client.session.prompt({...})
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
1. ✅ **Loose Coupling**: Tool and delivery are independent
|
||||
2. ✅ **Easy to Test**: Each component tested separately
|
||||
3. ✅ **SOLID Compliant**: Single Responsibility Principle
|
||||
4. ✅ **Reusable**: Hooks can be composed with other plugins
|
||||
5. ✅ **Monitorable**: Can add logging/analytics independently
|
||||
|
||||
---
|
||||
|
||||
## Skill Lookup Map: Performance Optimization
|
||||
|
||||
### Why a Map?
|
||||
|
||||
The skill lookup map enables O(1) access instead of O(n) search:
|
||||
|
||||
```typescript
|
||||
// ✅ EFFICIENT: O(1) lookup
|
||||
const skillMap = new Map<string, Skill>()
|
||||
for (const skill of skills) {
|
||||
skillMap.set(skill.toolName, skill)
|
||||
}
|
||||
|
||||
const beforeHook = async (input, output) => {
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
const skill = skillMap.get(input.tool) // O(1) constant time
|
||||
if (skill) {
|
||||
// Use skill
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Impact
|
||||
|
||||
| Number of Skills | Array Search (O(n)) | Map Lookup (O(1)) | Speedup |
|
||||
|------------------|-------------------|------------------|---------|
|
||||
| 10 | 10 comparisons | 1 lookup | 10x |
|
||||
| 100 | 100 comparisons | 1 lookup | 100x |
|
||||
| 1000 | 1000 comparisons | 1 lookup | 1000x |
|
||||
|
||||
**Conclusion:** Map lookup is essential for scalability
|
||||
|
||||
---
|
||||
|
||||
## Integration with OpenCode Event System
|
||||
|
||||
### Event Mapping
|
||||
|
||||
| OpenCode Event | Skills Plugin Hook | Purpose |
|
||||
|---|---|---|
|
||||
| `tool.execute.before` | `beforeHook` | Skill content injection |
|
||||
| `tool.execute.after` | `afterHook` | Output enhancement |
|
||||
|
||||
### Plugin Return Object
|
||||
|
||||
```typescript
|
||||
return {
|
||||
// Custom tools
|
||||
tool: tools,
|
||||
|
||||
// Hook: Runs before tool execution
|
||||
"tool.execute.before": beforeHook,
|
||||
|
||||
// Hook: Runs after tool execution
|
||||
"tool.execute.after": afterHook,
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points:**
|
||||
- Hooks apply to ALL tools (use `if` statements to filter)
|
||||
- Multiple plugins can register hooks without conflict
|
||||
- Hooks run in registration order
|
||||
- Hooks can be async
|
||||
|
||||
---
|
||||
|
||||
## Comparison with Other Event Hooks
|
||||
|
||||
### Available Tool Execution Hooks
|
||||
|
||||
| Hook | When | Use Case |
|
||||
|------|------|----------|
|
||||
| `tool.execute.before` | Before tool runs | Input validation, context injection, preprocessing |
|
||||
| `tool.execute.after` | After tool completes | Output formatting, logging, analytics |
|
||||
|
||||
### Other Event Hooks (Not Used in Skills Plugin)
|
||||
|
||||
| Hook | When | Use Case |
|
||||
|------|------|----------|
|
||||
| `session.created` | Session starts | Welcome messages, initialization |
|
||||
| `message.updated` | Message changes | Monitoring, logging |
|
||||
| `session.idle` | Session completes | Cleanup, background tasks |
|
||||
| `session.error` | Error occurs | Error handling, logging |
|
||||
|
||||
---
|
||||
|
||||
## Real-World Example: Skill Delivery Flow
|
||||
|
||||
### Step 1: Agent Calls Skill Tool
|
||||
|
||||
```
|
||||
Agent: "Use the brand-guidelines skill"
|
||||
↓
|
||||
OpenCode: Calls skills_brand_guidelines tool
|
||||
```
|
||||
|
||||
### Step 2: Before Hook Fires
|
||||
|
||||
```typescript
|
||||
const beforeHook = async (input, output) => {
|
||||
// input.tool = "skills_brand_guidelines"
|
||||
// input.sessionID = "ses_abc123"
|
||||
// input.agent = "my-helper"
|
||||
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
const skill = skillMap.get("skills_brand_guidelines")
|
||||
// skill = {
|
||||
// name: "brand-guidelines",
|
||||
// description: "Brand guidelines for the project",
|
||||
// content: "# Brand Guidelines\n\n...",
|
||||
// fullPath: "/path/to/skill"
|
||||
// }
|
||||
|
||||
await ctx.client.session.prompt({
|
||||
path: { id: "ses_abc123" },
|
||||
body: {
|
||||
agent: "my-helper",
|
||||
noReply: true,
|
||||
parts: [
|
||||
{
|
||||
type: "text",
|
||||
text: "📚 Skill: brand-guidelines\nBase directory: /path/to/skill\n\n# Brand Guidelines\n\n..."
|
||||
}
|
||||
]
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Result:** Skill content added to conversation, no AI response
|
||||
|
||||
### Step 3: Tool Executes
|
||||
|
||||
```typescript
|
||||
async execute(args, toolCtx) {
|
||||
// Minimal logic
|
||||
return `Skill activated: brand-guidelines`
|
||||
}
|
||||
```
|
||||
|
||||
**Result:** Simple confirmation returned
|
||||
|
||||
### Step 4: After Hook Fires
|
||||
|
||||
```typescript
|
||||
const afterHook = async (input, output) => {
|
||||
// input.tool = "skills_brand_guidelines"
|
||||
// output.output = "Skill activated: brand-guidelines"
|
||||
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
const skill = skillMap.get("skills_brand_guidelines")
|
||||
if (skill && output.output) {
|
||||
output.title = `📚 brand-guidelines`
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Result:** Output title enhanced with emoji
|
||||
|
||||
### Step 5: Agent Receives Result
|
||||
|
||||
```
|
||||
Conversation History:
|
||||
├─ User: "Use the brand-guidelines skill"
|
||||
├─ Tool Call: skills_brand_guidelines
|
||||
├─ Silent Message: "📚 Skill: brand-guidelines\n..."
|
||||
├─ Tool Result: "Skill activated: brand-guidelines"
|
||||
│ (with title: "📚 brand-guidelines")
|
||||
└─ Agent: "I now have the brand guidelines. I can help with..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Hooks
|
||||
|
||||
### Testing Before Hook
|
||||
|
||||
```typescript
|
||||
describe("beforeHook", () => {
|
||||
it("should inject skill content for skill tools", async () => {
|
||||
const input = {
|
||||
tool: "skills_brand_guidelines",
|
||||
sessionID: "ses_test",
|
||||
agent: "test-agent"
|
||||
}
|
||||
const output = { args: {} }
|
||||
|
||||
const mockPrompt = jest.fn()
|
||||
ctx.client.session.prompt = mockPrompt
|
||||
|
||||
await beforeHook(input, output)
|
||||
|
||||
expect(mockPrompt).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
path: { id: "ses_test" },
|
||||
body: expect.objectContaining({
|
||||
agent: "test-agent",
|
||||
noReply: true,
|
||||
parts: expect.arrayContaining([
|
||||
expect.objectContaining({
|
||||
type: "text",
|
||||
text: expect.stringContaining("brand-guidelines")
|
||||
})
|
||||
])
|
||||
})
|
||||
})
|
||||
)
|
||||
})
|
||||
|
||||
it("should skip non-skill tools", async () => {
|
||||
const input = { tool: "read_file", sessionID: "ses_test" }
|
||||
const output = { args: {} }
|
||||
|
||||
const mockPrompt = jest.fn()
|
||||
ctx.client.session.prompt = mockPrompt
|
||||
|
||||
await beforeHook(input, output)
|
||||
|
||||
expect(mockPrompt).not.toHaveBeenCalled()
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Testing After Hook
|
||||
|
||||
```typescript
|
||||
describe("afterHook", () => {
|
||||
it("should add emoji title for skill tools", async () => {
|
||||
const input = { tool: "skills_brand_guidelines" }
|
||||
const output = { output: "Skill activated" }
|
||||
|
||||
await afterHook(input, output)
|
||||
|
||||
expect(output.title).toBe("📚 brand-guidelines")
|
||||
})
|
||||
|
||||
it("should skip non-skill tools", async () => {
|
||||
const input = { tool: "read_file" }
|
||||
const output = { output: "File content" }
|
||||
|
||||
await afterHook(input, output)
|
||||
|
||||
expect(output.title).toBeUndefined()
|
||||
})
|
||||
|
||||
it("should skip if output is missing", async () => {
|
||||
const input = { tool: "skills_brand_guidelines" }
|
||||
const output = { output: null }
|
||||
|
||||
await afterHook(input, output)
|
||||
|
||||
expect(output.title).toBeUndefined()
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1: Tool-Specific Hooks
|
||||
|
||||
```typescript
|
||||
const beforeHook = async (input, output) => {
|
||||
switch (input.tool) {
|
||||
case "skills_brand_guidelines":
|
||||
// Handle brand guidelines
|
||||
break
|
||||
case "skills_api_reference":
|
||||
// Handle API reference
|
||||
break
|
||||
default:
|
||||
// Skip non-skill tools
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 2: Conditional Processing
|
||||
|
||||
```typescript
|
||||
const beforeHook = async (input, output) => {
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
const skill = skillMap.get(input.tool)
|
||||
if (skill && skill.allowedTools?.includes(input.agent)) {
|
||||
// Process only if allowed
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 3: Logging & Monitoring
|
||||
|
||||
```typescript
|
||||
const beforeHook = async (input, output) => {
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
console.log(`[BEFORE] Skill tool called: ${input.tool}`)
|
||||
console.log(`[BEFORE] Session: ${input.sessionID}`)
|
||||
}
|
||||
}
|
||||
|
||||
const afterHook = async (input, output) => {
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
console.log(`[AFTER] Skill tool completed: ${input.tool}`)
|
||||
console.log(`[AFTER] Output length: ${output.output?.length || 0}`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 4: Error Handling
|
||||
|
||||
```typescript
|
||||
const beforeHook = async (input, output) => {
|
||||
try {
|
||||
if (input.tool.startsWith("skills_")) {
|
||||
const skill = skillMap.get(input.tool)
|
||||
if (!skill) {
|
||||
throw new Error(`Skill not found: ${input.tool}`)
|
||||
}
|
||||
// Process skill
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(`Hook error:`, error)
|
||||
// Don't rethrow - let tool execute anyway
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
1. **Hooks are middleware**: They intercept tool execution at specific points
|
||||
2. **Before hook**: For preprocessing, validation, context injection
|
||||
3. **After hook**: For output enhancement, logging, analytics
|
||||
4. **Lookup maps**: Enable O(1) access instead of O(n) search
|
||||
5. **Separation of concerns**: Tools do one thing, hooks do another
|
||||
6. **Composability**: Multiple plugins can register hooks without conflict
|
||||
7. **Testability**: Each component can be tested independently
|
||||
8. **Maintainability**: Changes are isolated to specific hooks
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **OpenCode Events**: `context/capabilities/events.md`
|
||||
- **Tool Definition**: `context/capabilities/tools.md`
|
||||
- **Best Practices**: `context/reference/best-practices.md`
|
||||
- **Skills Plugin Example**: `skills-plugin/example.ts`
|
||||
- **Hook Lifecycle**: `skills-plugin/hook-lifecycle-and-patterns.md`
|
||||
- **Implementation Pattern**: `skills-plugin/implementation-pattern.md`
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
<!-- Context: openagents-repo/tools | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Building Custom Tools
|
||||
|
||||
Plugins can add custom tools that OpenCode agents can call autonomously.
|
||||
|
||||
## Tool Definition
|
||||
|
||||
Custom tools use Zod for schema definition and the `tool` helper from `@opencode-ai/plugin`.
|
||||
|
||||
```typescript
|
||||
import { z } from 'zod';
|
||||
import { tool } from '@opencode-ai/plugin';
|
||||
|
||||
export const MyCustomTool = tool(
|
||||
z.object({
|
||||
query: z.string().describe('Search query'),
|
||||
limit: z.number().default(10).describe('Results limit')
|
||||
}),
|
||||
async (args, context) => {
|
||||
const { query, limit } = args;
|
||||
// Implementation logic
|
||||
return { success: true, data: [] };
|
||||
}
|
||||
).describe('Search your database');
|
||||
```
|
||||
|
||||
## Shell-based Tools
|
||||
|
||||
You can leverage Bun's shell API (`$`) to run commands in any language.
|
||||
|
||||
```typescript
|
||||
export const PythonCalculatorTool = tool(
|
||||
z.object({ expression: z.string() }),
|
||||
async (args, context) => {
|
||||
const { $ } = context;
|
||||
const result = await $`python3 -c 'print(eval("${args.expression}"))'`;
|
||||
return { result: result.stdout };
|
||||
}
|
||||
).describe('Calculate mathematical expressions');
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
To register tools in your plugin:
|
||||
|
||||
```typescript
|
||||
export const MyPlugin = async (context) => {
|
||||
return {
|
||||
tool: [MyCustomTool, PythonCalculatorTool]
|
||||
};
|
||||
};
|
||||
```
|
||||
@@ -0,0 +1,36 @@
|
||||
<!-- Context: openagents-repo/context-overview | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenCode Plugin Context Library
|
||||
|
||||
This library provides structured context for AI coding assistants to understand, build, and extend OpenCode plugins. Depending on your task, you can load specific parts of this library.
|
||||
|
||||
## 📚 Library Map
|
||||
|
||||
### 🏗️ Architecture
|
||||
Foundational concepts of how plugins are registered and executed.
|
||||
- [Overview](./architecture/overview.md): Basic structure, registration, and context object.
|
||||
- [Lifecycle](./architecture/lifecycle.md): Packaging, manifest, and session lifecycle.
|
||||
|
||||
### 🛠️ Capabilities
|
||||
Deep dives into specific plugin features.
|
||||
- [Events](./capabilities/events.md): Detailed list of all 25+ hookable events.
|
||||
- [Events: Skills Plugin](./capabilities/events_skills.md): Practical example of event hooks in the Skills Plugin.
|
||||
- [Tools](./capabilities/tools.md): How to build and register custom tools using Zod.
|
||||
- [Agents](./capabilities/agents.md): Creating and configuring custom AI agents.
|
||||
|
||||
### 📖 Reference
|
||||
Guidelines and troubleshooting.
|
||||
- [Best Practices](./reference/best-practices.md): Message injection workarounds, security, and performance.
|
||||
|
||||
### 🧩 Claude Code Plugins (External)
|
||||
Claude Code plugin system documentation (harvested from external docs).
|
||||
- [Concepts: Plugin Architecture](./concepts/plugin-architecture.md): Core concepts and structure
|
||||
- [Guides: Creating Plugins](./guides/creating-plugins.md): Step-by-step creation
|
||||
- [Guides: Migrating to Plugins](./guides/migrating-to-plugins.md): Convert standalone to plugin
|
||||
- [Lookup: Plugin Structure](./lookup/plugin-structure.md): Directory reference
|
||||
|
||||
## 🚀 How to use this library
|
||||
If you are asking an AI to build a new feature:
|
||||
1. **For a new tool**: Provide `architecture/overview.md` and `capabilities/tools.md`.
|
||||
2. **For reacting to events**: Provide `capabilities/events.md`.
|
||||
3. **For overall plugin architecture**: Provide `architecture/overview.md` and `architecture/lifecycle.md`.
|
||||
@@ -0,0 +1,28 @@
|
||||
<!-- Context: openagents-repo/best-practices | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Best Practices & Limitations
|
||||
|
||||
## Message Injection Workarounds
|
||||
|
||||
**The Reality**: The message system is largely read-only. You cannot mutate messages mid-stream or inject text directly into an existing message part.
|
||||
|
||||
### What Doesn't Work
|
||||
- Modifying `event.data.content` in `message.updated`.
|
||||
- Retroactively changing AI responses.
|
||||
|
||||
### What Works
|
||||
1. **Initial Context**: Use `session.created` to inject a starting message using `client.session.prompt()`.
|
||||
2. **Prompt Decoration**: Use `client.tui.appendPrompt()` to add text to the user's input box before they hit enter.
|
||||
3. **Tool Interception**: Use `tool.execute.before` to modify arguments *before* the tool runs.
|
||||
4. **On-Demand Context**: Provide custom tools that the AI can call when it needs more information.
|
||||
|
||||
## Security
|
||||
|
||||
- Always validate tool inputs in `tool.execute.before`.
|
||||
- Use environment variables for sensitive data; do not hardcode API keys.
|
||||
- Be careful with the `$` shell API to prevent command injection.
|
||||
|
||||
## Performance
|
||||
|
||||
- Avoid heavy synchronous operations in event handlers as they can block the TUI.
|
||||
- Use the `session.idle` event for cleanup or background sync tasks.
|
||||
42
.opencode/context/openagents-repo/plugins/navigation.md
Normal file
42
.opencode/context/openagents-repo/plugins/navigation.md
Normal file
@@ -0,0 +1,42 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Plugins
|
||||
|
||||
**Purpose**: Plugin architecture and documentation for OpenAgents Control
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/plugins/
|
||||
├── navigation.md (this file)
|
||||
├── context/
|
||||
│ └── [context plugin files]
|
||||
└── [plugin files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **Context plugin** | `./context/` |
|
||||
| **View plugins** | `./` |
|
||||
| **Guides** | `../guides/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Context Plugin** → Context system plugin documentation
|
||||
**Plugin Architecture** → How plugins work in OpenAgents
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Guides** → `../guides/navigation.md`
|
||||
- **Core Concepts** → `../core-concepts/navigation.md`
|
||||
41
.opencode/context/openagents-repo/quality/navigation.md
Normal file
41
.opencode/context/openagents-repo/quality/navigation.md
Normal file
@@ -0,0 +1,41 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Quality
|
||||
|
||||
**Purpose**: Quality assurance and standards for OpenAgents Control
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/quality/
|
||||
├── navigation.md (this file)
|
||||
└── [quality documentation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **View quality docs** | `./` |
|
||||
| **Guides** | `../guides/navigation.md` |
|
||||
| **Errors** | `../errors/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Quality Standards** → Standards for code quality
|
||||
**Testing** → Testing requirements and patterns
|
||||
**Validation** → Validation procedures
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Guides** → `../guides/navigation.md`
|
||||
- **Errors** → `../errors/navigation.md`
|
||||
@@ -0,0 +1,586 @@
|
||||
---
|
||||
description: Maintain registry quality through dependency validation and consistency checks
|
||||
tags:
|
||||
- registry
|
||||
- quality
|
||||
- validation
|
||||
- dependencies
|
||||
dependencies: []
|
||||
---
|
||||
|
||||
<!-- Context: quality/registry-dependencies | Priority: high | Version: 1.0 | Updated: 2026-01-06 -->
|
||||
# Registry Dependency Validation
|
||||
|
||||
**Purpose**: Maintain registry quality through dependency validation and consistency checks
|
||||
**Audience**: Contributors, maintainers, CI/CD processes
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Golden Rule**: All component dependencies must be declared in frontmatter and validated before commits.
|
||||
|
||||
**Critical Commands**:
|
||||
```bash
|
||||
# Check context file dependencies
|
||||
/check-context-deps
|
||||
|
||||
# Auto-fix missing dependencies
|
||||
/check-context-deps --fix
|
||||
|
||||
# Validate entire registry
|
||||
./scripts/registry/validate-registry.sh
|
||||
|
||||
# Update registry after changes
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependency System
|
||||
|
||||
### Dependency Types
|
||||
|
||||
Components can depend on other components using the `type:id` format:
|
||||
|
||||
| Type | Format | Example | Description |
|
||||
|------|--------|---------|-------------|
|
||||
| **agent** | `agent:id` | `agent:opencoder` | Core agent profile |
|
||||
| **subagent** | `subagent:id` | `subagent:coder-agent` | Delegatable subagent |
|
||||
| **command** | `command:id` | `command:context` | Slash command |
|
||||
| **tool** | `tool:id` | `tool:gemini` | External tool integration |
|
||||
| **plugin** | `plugin:id` | `plugin:context` | Plugin component |
|
||||
| **context** | `context:path` | `context:core/standards/code` | Context file |
|
||||
| **config** | `config:id` | `config:defaults` | Configuration file |
|
||||
|
||||
### Declaring Dependencies
|
||||
|
||||
**In component frontmatter** (example):
|
||||
```
|
||||
id: opencoder
|
||||
name: OpenCoder
|
||||
description: Multi-language implementation agent
|
||||
dependencies:
|
||||
- subagent:task-manager # Can delegate to task-manager
|
||||
- subagent:coder-agent # Can delegate to coder-agent
|
||||
- subagent:tester # Can delegate to tester
|
||||
- context:core/standards/code # Requires code standards context
|
||||
```
|
||||
|
||||
**Why declare dependencies?**
|
||||
- ✅ **Validation**: Catch missing components before runtime
|
||||
- ✅ **Documentation**: Clear visibility of what each component needs
|
||||
- ✅ **Installation**: Installers can fetch all required dependencies
|
||||
- ✅ **Dependency graphs**: Visualize component relationships
|
||||
- ✅ **Breaking change detection**: Know what's affected by changes
|
||||
|
||||
---
|
||||
|
||||
## Context File Dependencies
|
||||
|
||||
### The Problem
|
||||
|
||||
Agents reference context files in their prompts but often don't declare them as dependencies:
|
||||
|
||||
```markdown
|
||||
<!-- In agent prompt -->
|
||||
BEFORE any code implementation, ALWAYS load:
|
||||
- Code tasks → .opencode/context/core/standards/code-quality.md (MANDATORY)
|
||||
```
|
||||
|
||||
**Without dependency declaration**:
|
||||
- ❌ No validation that context file exists
|
||||
- ❌ Can't track which agents use which context files
|
||||
- ❌ Breaking changes when context files are moved/deleted
|
||||
- ❌ Installers don't know to fetch context files
|
||||
|
||||
### The Solution
|
||||
|
||||
**Declare context dependencies in frontmatter** (example):
|
||||
```
|
||||
id: opencoder
|
||||
dependencies:
|
||||
- context:core/standards/code # ← ADD THIS
|
||||
```
|
||||
|
||||
**Use `/check-context-deps` to find missing declarations**:
|
||||
```bash
|
||||
# Analyze all agents
|
||||
/check-context-deps
|
||||
|
||||
# Auto-fix missing context dependencies
|
||||
/check-context-deps --fix
|
||||
```
|
||||
|
||||
### Context Dependency Format
|
||||
|
||||
**Path normalization**:
|
||||
```
|
||||
File path: .opencode/context/core/standards/code-quality.md
|
||||
Dependency: context:core/standards/code
|
||||
^^^^^^^ ^^^^^^^^^^^^^^^^^^^
|
||||
type path (no .opencode/, no .md)
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
dependencies:
|
||||
- context:core/standards/code # .opencode/context/core/standards/code-quality.md
|
||||
- context:core/standards/docs # .opencode/context/core/standards/documentation.md
|
||||
- context:core/workflows/delegation # .opencode/context/core/workflows/task-delegation-basics.md
|
||||
- context:openagents-repo/guides/adding-agent # Project-specific context
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Workflow
|
||||
|
||||
### Pre-Commit Checklist
|
||||
|
||||
Before committing changes to agents, commands, or context files:
|
||||
|
||||
1. **Check context dependencies**:
|
||||
```bash
|
||||
/check-context-deps
|
||||
```
|
||||
- Identifies agents using context files without declaring them
|
||||
- Reports unused context files
|
||||
- Validates context file paths
|
||||
|
||||
2. **Fix missing dependencies** (if needed):
|
||||
```bash
|
||||
/check-context-deps --fix
|
||||
```
|
||||
- Automatically adds missing `context:` dependencies to frontmatter
|
||||
- Preserves existing dependencies
|
||||
|
||||
3. **Update registry**:
|
||||
```bash
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
- Extracts dependencies from frontmatter
|
||||
- Updates registry.json
|
||||
|
||||
4. **Validate registry**:
|
||||
```bash
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
- Checks all dependencies exist
|
||||
- Validates component paths
|
||||
- Reports missing dependencies
|
||||
|
||||
### Validation Tools
|
||||
|
||||
#### 1. `/check-context-deps` Command
|
||||
|
||||
**Purpose**: Analyze context file usage and validate dependencies
|
||||
|
||||
**What it checks**:
|
||||
- ✅ Agents referencing context files in prompts
|
||||
- ✅ Context dependencies declared in frontmatter
|
||||
- ✅ Context files exist on disk
|
||||
- ✅ Context files in registry
|
||||
- ✅ Unused context files
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Full analysis
|
||||
/check-context-deps
|
||||
|
||||
# Specific agent
|
||||
/check-context-deps opencoder
|
||||
|
||||
# Auto-fix
|
||||
/check-context-deps --fix
|
||||
|
||||
# Verbose (show line numbers)
|
||||
/check-context-deps --verbose
|
||||
```
|
||||
|
||||
**Example output**:
|
||||
```
|
||||
# Context Dependency Analysis Report
|
||||
|
||||
## Summary
|
||||
- Agents scanned: 25
|
||||
- Context files referenced: 12
|
||||
- Missing dependencies: 8
|
||||
- Unused context files: 2
|
||||
|
||||
## Missing Dependencies
|
||||
|
||||
### opencoder
|
||||
Uses but not declared:
|
||||
- context:core/standards/code (referenced 3 times)
|
||||
- Line 64: "Code tasks → .opencode/context/core/standards/code-quality.md"
|
||||
|
||||
Recommended fix:
|
||||
dependencies:
|
||||
- context:core/standards/code
|
||||
```
|
||||
|
||||
#### 2. `auto-detect-components.sh` Script
|
||||
|
||||
**Purpose**: Scan for new components and update registry
|
||||
|
||||
**Dependency validation**:
|
||||
- Checks dependencies during component scanning
|
||||
- Logs warnings for missing dependencies
|
||||
- Non-blocking (warnings only)
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# See what would be added
|
||||
./scripts/registry/auto-detect-components.sh --dry-run
|
||||
|
||||
# Add new components
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
**Example warning**:
|
||||
```
|
||||
⚠ New command: Demo (demo)
|
||||
Dependencies: subagent:coder-agent,subagent:missing-agent
|
||||
⚠ Dependency not found in registry: subagent:missing-agent
|
||||
```
|
||||
|
||||
#### 3. `validate-registry.sh` Script
|
||||
|
||||
**Purpose**: Comprehensive registry validation
|
||||
|
||||
**Checks**:
|
||||
- ✅ All component paths exist
|
||||
- ✅ All dependencies exist in registry
|
||||
- ✅ No duplicate IDs
|
||||
- ✅ Valid JSON structure
|
||||
- ✅ Required fields present
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
**Example output**:
|
||||
```
|
||||
Validating registry.json...
|
||||
|
||||
✗ Dependency not found: opencoder → context:core/standards/code
|
||||
|
||||
Missing dependencies: 1
|
||||
- opencoder (agent) → context:core/standards/code
|
||||
|
||||
Fix: Add missing component to registry or remove from dependencies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### Well-Maintained Registry
|
||||
|
||||
A high-quality registry has:
|
||||
|
||||
✅ **Complete dependencies**: All component dependencies declared
|
||||
✅ **Validated dependencies**: All dependencies exist in registry
|
||||
✅ **No orphans**: All context files used by at least one component
|
||||
✅ **Consistent format**: Dependencies use `type:id` format
|
||||
✅ **Up-to-date**: Registry reflects current component state
|
||||
✅ **No broken paths**: All component paths valid
|
||||
|
||||
### Dependency Declaration Standards
|
||||
|
||||
**DO**:
|
||||
- ✅ Declare all subagents you delegate to
|
||||
- ✅ Declare all context files you reference
|
||||
- ✅ Declare all commands you invoke
|
||||
- ✅ Use correct format: `type:id`
|
||||
- ✅ Keep dependencies in frontmatter (not hardcoded in prompts)
|
||||
|
||||
**DON'T**:
|
||||
- ❌ Reference context files without declaring dependency
|
||||
- ❌ Use invalid dependency formats
|
||||
- ❌ Declare dependencies you don't actually use
|
||||
- ❌ Forget to update registry after adding dependencies
|
||||
|
||||
---
|
||||
|
||||
## Commit Guidelines
|
||||
|
||||
### When Adding/Modifying Components
|
||||
|
||||
**1. Add component with proper frontmatter** (example):
|
||||
```
|
||||
id: my-agent
|
||||
name: My Agent
|
||||
description: Does something useful
|
||||
tags:
|
||||
- development
|
||||
- coding
|
||||
dependencies:
|
||||
- subagent:coder-agent
|
||||
- context:core/standards/code
|
||||
```
|
||||
|
||||
**2. Validate dependencies**:
|
||||
```bash
|
||||
/check-context-deps my-agent
|
||||
```
|
||||
|
||||
**3. Update registry**:
|
||||
```bash
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
**4. Validate registry**:
|
||||
```bash
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
**5. Commit with descriptive message**:
|
||||
```bash
|
||||
git add .opencode/agent/my-agent.md registry.json
|
||||
git commit -m "Add my-agent with coder-agent and code standards dependencies"
|
||||
```
|
||||
|
||||
### When Modifying Context Files
|
||||
|
||||
**1. Check which agents depend on it**:
|
||||
```bash
|
||||
jq '.components[] | .[] | select(.dependencies[]? | contains("context:core/standards/code")) | {id, name}' registry.json
|
||||
```
|
||||
|
||||
**2. Update context file**:
|
||||
```bash
|
||||
# Make your changes
|
||||
vim .opencode/context/core/standards/code-quality.md
|
||||
```
|
||||
|
||||
**3. Validate no broken references**:
|
||||
```bash
|
||||
/check-context-deps --verbose
|
||||
```
|
||||
|
||||
**4. Update registry if needed**:
|
||||
```bash
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
**5. Commit with impact note**:
|
||||
```bash
|
||||
git commit -m "Update code standards - affects opencoder, openagent, reviewer"
|
||||
```
|
||||
|
||||
### When Deleting Components
|
||||
|
||||
**1. Check dependencies first**:
|
||||
```bash
|
||||
# Find what depends on this component
|
||||
jq '.components[] | .[] | select(.dependencies[]? == "subagent:old-agent") | {id, name}' registry.json
|
||||
```
|
||||
|
||||
**2. Remove from dependents**:
|
||||
```bash
|
||||
# Update agents that depend on it
|
||||
# Remove the dependency from their frontmatter
|
||||
```
|
||||
|
||||
**3. Delete component**:
|
||||
```bash
|
||||
rm .opencode/agent/subagents/old-agent.md
|
||||
```
|
||||
|
||||
**4. Update registry**:
|
||||
```bash
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
**5. Validate**:
|
||||
```bash
|
||||
./scripts/registry/validate-registry.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Missing Context Dependencies
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
/check-context-deps reports:
|
||||
opencoder: missing context:core/standards/code
|
||||
```
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Option 1: Auto-fix
|
||||
/check-context-deps --fix
|
||||
|
||||
# Option 2: Manual fix
|
||||
# Edit .opencode/agent/core/opencoder.md
|
||||
# Add to frontmatter:
|
||||
dependencies:
|
||||
- context:core/standards/code
|
||||
|
||||
# Then update registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
### Dependency Not Found in Registry
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
⚠ Dependency not found in registry: context:core/standards/code
|
||||
```
|
||||
|
||||
**Causes**:
|
||||
1. Context file doesn't exist
|
||||
2. Context file exists but not in registry
|
||||
3. Wrong dependency format
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Check if file exists
|
||||
ls -la .opencode/context/core/standards/code-quality.md
|
||||
|
||||
# If exists, add to registry
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# If doesn't exist, remove dependency or create file
|
||||
```
|
||||
|
||||
### Unused Context Files
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
/check-context-deps reports:
|
||||
Unused: context:core/standards/analysis (0 references)
|
||||
```
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Option 1: Add to an agent that should use it
|
||||
# Edit agent frontmatter to add dependency
|
||||
|
||||
# Option 2: Remove if truly unused
|
||||
rm .opencode/context/core/standards/code-analysis.md
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
```
|
||||
|
||||
### Circular Dependencies
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
Agent A depends on Agent B
|
||||
Agent B depends on Agent A
|
||||
```
|
||||
|
||||
**Fix**:
|
||||
- Refactor to remove circular dependency
|
||||
- Extract shared logic to a third component
|
||||
- Use dependency injection instead
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### Pre-Commit Hook
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-commit
|
||||
|
||||
echo "Validating registry dependencies..."
|
||||
|
||||
# Check context dependencies
|
||||
/check-context-deps || {
|
||||
echo "❌ Context dependency validation failed"
|
||||
echo "Run: /check-context-deps --fix"
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Validate registry
|
||||
./scripts/registry/validate-registry.sh || {
|
||||
echo "❌ Registry validation failed"
|
||||
exit 1
|
||||
}
|
||||
|
||||
echo "✅ Registry validation passed"
|
||||
```
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Validate Registry
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
- name: Validate registry
|
||||
run: ./scripts/registry/validate-registry.sh
|
||||
|
||||
- name: Check context dependencies
|
||||
run: /check-context-deps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Component Authors
|
||||
|
||||
1. **Always declare dependencies** in frontmatter
|
||||
2. **Use `/check-context-deps`** before committing
|
||||
3. **Update registry** after adding components
|
||||
4. **Validate** before pushing
|
||||
5. **Document** why dependencies are needed
|
||||
|
||||
### For Maintainers
|
||||
|
||||
1. **Review dependencies** in PRs
|
||||
2. **Run validation** in CI/CD
|
||||
3. **Keep context files** organized and documented
|
||||
4. **Monitor unused** context files
|
||||
5. **Refactor** when dependency graphs get complex
|
||||
|
||||
### For CI/CD
|
||||
|
||||
1. **Fail builds** on validation errors
|
||||
2. **Report** missing dependencies
|
||||
3. **Track** dependency changes over time
|
||||
4. **Alert** on circular dependencies
|
||||
5. **Enforce** dependency declaration standards
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Registry Guide**: `.opencode/context/openagents-repo/guides/updating-registry.md`
|
||||
- **Registry Concepts**: `.opencode/context/openagents-repo/core-concepts/registry.md`
|
||||
- **Adding Agents**: `.opencode/context/openagents-repo/guides/adding-agent-basics.md`
|
||||
- **Command Reference**: `/check-context-deps` command
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Key Takeaways**:
|
||||
1. Declare all dependencies in frontmatter (subagents, context files, etc.)
|
||||
2. Use `/check-context-deps` to find missing context dependencies
|
||||
3. Validate registry before commits
|
||||
4. Keep registry in sync with component changes
|
||||
5. Follow dependency format: `type:id`
|
||||
|
||||
**Quality Checklist**:
|
||||
- [ ] All context files referenced have dependencies declared
|
||||
- [ ] All dependencies exist in registry
|
||||
- [ ] No unused context files (or documented why)
|
||||
- [ ] Registry validates without errors
|
||||
- [ ] Dependency format is consistent
|
||||
|
||||
**Remember**: Dependencies are documentation. They help users understand what components need and help the system validate integrity.
|
||||
171
.opencode/context/openagents-repo/quick-start.md
Normal file
171
.opencode/context/openagents-repo/quick-start.md
Normal file
@@ -0,0 +1,171 @@
|
||||
<!-- Context: openagents-repo/quick-start | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Control Repository - Quick Start
|
||||
|
||||
**Purpose**: Get oriented in this repo in 2 minutes
|
||||
|
||||
---
|
||||
|
||||
## What Is This Repo?
|
||||
|
||||
OpenAgents Control is an AI agent framework with:
|
||||
- **Category-based agents** (core, development, content, data, product, learning)
|
||||
- **Eval framework** for testing agent behavior
|
||||
- **Registry system** for component distribution
|
||||
- **Install system** for easy setup
|
||||
|
||||
---
|
||||
|
||||
## Core Concepts (Load These First)
|
||||
|
||||
Before working on this repo, understand these 4 systems:
|
||||
|
||||
1. **Agents** → Load: `core-concepts/agents.md`
|
||||
- How agents are structured
|
||||
- Category system
|
||||
- Prompt variants
|
||||
- Subagents vs category agents
|
||||
|
||||
2. **Evals** → Load: `core-concepts/evals.md`
|
||||
- How testing works
|
||||
- Running tests
|
||||
- Evaluators
|
||||
- Session collection
|
||||
|
||||
3. **Registry** → Load: `core-concepts/registry.md`
|
||||
- How components are tracked
|
||||
- Auto-detect system
|
||||
- Validation
|
||||
- Install system
|
||||
|
||||
4. **Categories** → Load: `core-concepts/categories.md`
|
||||
- How organization works
|
||||
- Naming conventions
|
||||
- Path patterns
|
||||
|
||||
---
|
||||
|
||||
## I Need To...
|
||||
|
||||
| Task | Load These Files |
|
||||
|------|------------------|
|
||||
| Add a new agent | `core-concepts/agents.md` + `guides/adding-agent.md` |
|
||||
| Test an agent | `core-concepts/evals.md` + `guides/testing-agent.md` |
|
||||
| Fix registry | `core-concepts/registry.md` + `guides/updating-registry.md` |
|
||||
| Debug issue | `guides/debugging.md` |
|
||||
| Find files | `lookup/file-locations.md` |
|
||||
| Create release | `guides/creating-release.md` |
|
||||
| Write content or copy | `core-concepts/categories.md` + `../content-creation/principles/navigation.md` |
|
||||
| Use Claude Code helpers | `core-concepts/agents.md` + `guides/adding-agent.md` + `../to-be-consumed/claude-code-docs/create-subagents.md` |
|
||||
|
||||
---
|
||||
|
||||
## Essential Paths (Top 15)
|
||||
|
||||
```
|
||||
.opencode/agent/core/ # Core agents (openagent, opencoder)
|
||||
.opencode/agent/{category}/ # Category agents
|
||||
.opencode/agent/subagents/ # Subagents
|
||||
evals/agents/{category}/{agent}/ # Agent tests
|
||||
evals/framework/src/ # Eval framework code
|
||||
registry.json # Component catalog
|
||||
install.sh # Installer
|
||||
scripts/registry/validate-registry.sh # Validate registry
|
||||
scripts/registry/auto-detect-components.sh # Auto-detect components
|
||||
scripts/validation/validate-test-suites.sh # Validate tests
|
||||
.opencode/context/ # Context files
|
||||
.opencode/command/ # Slash commands
|
||||
docs/ # Documentation
|
||||
VERSION # Current version
|
||||
package.json # Node dependencies
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Commands (Top 10)
|
||||
|
||||
```bash
|
||||
# Add new agent (auto-detect)
|
||||
./scripts/registry/auto-detect-components.sh --auto-add
|
||||
|
||||
# Validate registry
|
||||
./scripts/registry/validate-registry.sh
|
||||
|
||||
# Test agent
|
||||
cd evals/framework && bun --bun run eval:sdk -- --agent={category}/{agent}
|
||||
|
||||
# Run smoke test
|
||||
cd evals/framework && bun --bun run eval:sdk -- --agent={agent} --pattern="smoke-test.yaml"
|
||||
|
||||
# Test with debug
|
||||
cd evals/framework && bun --bun run eval:sdk -- --agent={agent} --debug
|
||||
|
||||
# Validate test suites
|
||||
./scripts/validation/validate-test-suites.sh
|
||||
|
||||
# Install locally (test)
|
||||
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
|
||||
|
||||
# Bump version
|
||||
echo "0.X.Y" > VERSION && jq '.version = "0.X.Y"' package.json > tmp && mv tmp package.json
|
||||
|
||||
# Check version consistency
|
||||
cat VERSION && cat package.json | jq '.version'
|
||||
|
||||
# Run full validation
|
||||
./scripts/registry/validate-registry.sh && ./scripts/validation/validate-test-suites.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Repository Structure (Quick View)
|
||||
|
||||
```
|
||||
opencode-agents/
|
||||
├── .opencode/
|
||||
│ ├── agent/{category}/ # Agents by domain
|
||||
│ │ ├── core/ # Core system agents
|
||||
│ │ ├── development/ # Dev specialists
|
||||
│ │ ├── content/ # Content creators
|
||||
│ │ ├── data/ # Data analysts
|
||||
│ │ ├── product/ # Product managers
|
||||
│ │ ├── learning/ # Educators
|
||||
│ │ └── subagents/ # Delegated specialists
|
||||
│ ├── command/ # Slash commands
|
||||
│ └── context/ # Shared knowledge
|
||||
├── evals/
|
||||
│ ├── agents/{category}/ # Test suites
|
||||
│ └── framework/ # Eval framework
|
||||
├── scripts/
|
||||
│ ├── registry/ # Registry tools
|
||||
│ └── validation/ # Validation tools
|
||||
├── docs/ # Documentation
|
||||
├── registry.json # Component catalog
|
||||
└── install.sh # Installer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Registry validation fails | `./scripts/registry/auto-detect-components.sh --auto-add` |
|
||||
| Test fails | Load `guides/debugging.md` |
|
||||
| Can't find file | Load `lookup/file-locations.md` |
|
||||
| Install fails | Check: `which curl jq` |
|
||||
| Path resolution issues | Check `core-concepts/categories.md` |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **First time?** → Read `core-concepts/agents.md`, `evals.md`, `registry.md`
|
||||
2. **Adding agent?** → Load `guides/adding-agent.md`
|
||||
3. **Testing?** → Load `guides/testing-agent.md`
|
||||
4. **Need details?** → Load specific files from `core-concepts/` or `guides/`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-13
|
||||
**Version**: 0.5.1
|
||||
@@ -0,0 +1,250 @@
|
||||
<!-- Context: openagents-repo/context-bundle-template | Priority: low | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Context Bundle Template
|
||||
|
||||
**Purpose**: Template for creating context bundles when delegating tasks to subagents
|
||||
|
||||
**Location**: `.tmp/context/{session-id}/bundle.md`
|
||||
|
||||
**Used by**: repo-manager agent when delegating to subagents
|
||||
|
||||
---
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Context Bundle: {Task Name}
|
||||
|
||||
Session: {session-id}
|
||||
Created: {ISO timestamp}
|
||||
For: {subagent-name}
|
||||
Status: in_progress
|
||||
|
||||
## Task Overview
|
||||
|
||||
{Brief description of what we're building/doing}
|
||||
|
||||
## User Request
|
||||
|
||||
{Original user request - what they asked for}
|
||||
|
||||
## Relevant Standards (Load These Before Starting)
|
||||
|
||||
**Core Standards**:
|
||||
- `.opencode/context/core/standards/code.md` → Modular, functional code patterns
|
||||
- `.opencode/context/core/standards/tests.md` → Testing requirements and TDD
|
||||
- `.opencode/context/core/standards/docs.md` → Documentation standards
|
||||
- (example: `.opencode/context/core/standards/patterns.md`) → Error handling, security patterns
|
||||
|
||||
**Core Workflows**:
|
||||
- (example: `.opencode/context/core/workflows/delegation.md`) → Delegation process
|
||||
- (example: `.opencode/context/core/workflows/task-breakdown.md`) → Task breakdown methodology
|
||||
- (example: `.opencode/context/core/workflows/review.md`) → Code review guidelines
|
||||
|
||||
## Repository-Specific Context (Load These Before Starting)
|
||||
|
||||
**Quick Start** (ALWAYS load first):
|
||||
- `.opencode/context/openagents-repo/quick-start.md` → Repo orientation and common commands
|
||||
|
||||
**Core Concepts** (Load based on task type):
|
||||
- `.opencode/context/openagents-repo/core-concepts/agents.md` → How agents work
|
||||
- `.opencode/context/openagents-repo/core-concepts/evals.md` → How testing works
|
||||
- `.opencode/context/openagents-repo/core-concepts/registry.md` → How registry works
|
||||
- `.opencode/context/openagents-repo/core-concepts/categories.md` → How organization works
|
||||
|
||||
**Guides** (Load for specific workflows):
|
||||
- `.opencode/context/openagents-repo/guides/adding-agent-basics.md` → Step-by-step agent creation
|
||||
- `.opencode/context/openagents-repo/guides/testing-agent.md` → Testing workflow
|
||||
- `.opencode/context/openagents-repo/guides/updating-registry.md` → Registry workflow
|
||||
- `.opencode/context/openagents-repo/guides/debugging.md` → Troubleshooting
|
||||
|
||||
**Lookup** (Quick reference):
|
||||
- `.opencode/context/openagents-repo/lookup/file-locations.md` → Where everything is
|
||||
- `.opencode/context/openagents-repo/lookup/commands.md` → Command reference
|
||||
|
||||
## Key Requirements
|
||||
|
||||
{Extract key requirements from loaded context}
|
||||
|
||||
**From Standards**:
|
||||
- {requirement 1 from standards/code.md}
|
||||
- {requirement 2 from standards/tests.md}
|
||||
- {requirement 3 from standards/docs.md}
|
||||
|
||||
**From Repository Context**:
|
||||
- {requirement 1 from repo context}
|
||||
- {requirement 2 from repo context}
|
||||
- {requirement 3 from repo context}
|
||||
|
||||
**Naming Conventions**:
|
||||
- {convention 1}
|
||||
- {convention 2}
|
||||
|
||||
**File Structure**:
|
||||
- {structure requirement 1}
|
||||
- {structure requirement 2}
|
||||
|
||||
## Technical Constraints
|
||||
|
||||
{List technical constraints and limitations}
|
||||
|
||||
- {constraint 1 - e.g., "Must use TypeScript"}
|
||||
- {constraint 2 - e.g., "Must follow category-based organization"}
|
||||
- {constraint 3 - e.g., "Must include proper frontmatter metadata"}
|
||||
|
||||
## Files to Create/Modify
|
||||
|
||||
{List all files that need to be created or modified}
|
||||
|
||||
**Create**:
|
||||
- `{file-path-1}` - {purpose and what it should contain}
|
||||
- `{file-path-2}` - {purpose and what it should contain}
|
||||
|
||||
**Modify**:
|
||||
- `{file-path-3}` - {what needs to be changed}
|
||||
- `{file-path-4}` - {what needs to be changed}
|
||||
|
||||
## Success Criteria
|
||||
|
||||
{Define what "done" looks like - binary pass/fail conditions}
|
||||
|
||||
- [ ] {criteria 1 - e.g., "Agent file created with proper frontmatter"}
|
||||
- [ ] {criteria 2 - e.g., "Eval tests pass"}
|
||||
- [ ] {criteria 3 - e.g., "Registry validation passes"}
|
||||
- [ ] {criteria 4 - e.g., "Documentation updated"}
|
||||
|
||||
## Validation Requirements
|
||||
|
||||
{How to validate the work}
|
||||
|
||||
**Scripts to Run**:
|
||||
- `{validation-script-1}` - {what it validates}
|
||||
- `{validation-script-2}` - {what it validates}
|
||||
|
||||
**Tests to Run**:
|
||||
- `{test-command-1}` - {what it tests}
|
||||
- `{test-command-2}` - {what it tests}
|
||||
|
||||
**Manual Checks**:
|
||||
- {check 1}
|
||||
- {check 2}
|
||||
|
||||
## Expected Output
|
||||
|
||||
{What the subagent should produce}
|
||||
|
||||
**Deliverables**:
|
||||
- {deliverable 1}
|
||||
- {deliverable 2}
|
||||
|
||||
**Format**:
|
||||
- {format requirement 1}
|
||||
- {format requirement 2}
|
||||
|
||||
## Progress Tracking
|
||||
|
||||
{Track progress through the task}
|
||||
|
||||
- [ ] Context loaded and understood
|
||||
- [ ] {step 1}
|
||||
- [ ] {step 2}
|
||||
- [ ] {step 3}
|
||||
- [ ] Validation passed
|
||||
- [ ] Documentation updated
|
||||
|
||||
---
|
||||
|
||||
## Instructions for Subagent
|
||||
|
||||
{Specific, detailed instructions for the subagent}
|
||||
|
||||
**IMPORTANT**:
|
||||
1. Load ALL context files listed in "Relevant Standards" and "Repository-Specific Context" sections BEFORE starting work
|
||||
2. Follow ALL requirements from the loaded context
|
||||
3. Apply naming conventions and file structure requirements
|
||||
4. Validate your work using the validation requirements
|
||||
5. Update progress tracking as you complete steps
|
||||
|
||||
**Your Task**:
|
||||
{Detailed description of what the subagent needs to do}
|
||||
|
||||
**Approach**:
|
||||
{Suggested approach or methodology}
|
||||
|
||||
**Constraints**:
|
||||
{Any additional constraints or notes}
|
||||
|
||||
**Questions/Clarifications**:
|
||||
{Any questions the subagent should consider or clarifications needed}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Instructions
|
||||
|
||||
### When to Create a Context Bundle
|
||||
|
||||
Create a context bundle when:
|
||||
- Delegating to any subagent
|
||||
- Task requires coordination across multiple components
|
||||
- Subagent needs project-specific context
|
||||
- Task has complex requirements or constraints
|
||||
|
||||
### How to Create a Context Bundle
|
||||
|
||||
1. **Create session directory**:
|
||||
```bash
|
||||
mkdir -p .tmp/context/{session-id}
|
||||
```
|
||||
|
||||
2. **Copy template**:
|
||||
```bash
|
||||
cp .opencode/context/openagents-repo/templates/context-bundle-template.md \
|
||||
.tmp/context/{session-id}/bundle.md
|
||||
```
|
||||
|
||||
3. **Fill in all sections**:
|
||||
- Replace all `{placeholders}` with actual values
|
||||
- List specific context files to load (with full paths)
|
||||
- Extract key requirements from loaded context
|
||||
- Define clear success criteria
|
||||
- Provide specific instructions
|
||||
|
||||
4. **Pass to subagent**:
|
||||
```javascript
|
||||
task(
|
||||
subagent_type="subagents/core/{subagent}",
|
||||
description="Brief description",
|
||||
prompt="Load context from .tmp/context/{session-id}/bundle.md before starting.
|
||||
|
||||
{Specific task instructions}
|
||||
|
||||
Follow all standards and requirements in the context bundle."
|
||||
)
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
**DO**:
|
||||
- ✅ List context files with full paths (don't duplicate content)
|
||||
- ✅ Extract key requirements from loaded context
|
||||
- ✅ Define binary success criteria (pass/fail)
|
||||
- ✅ Provide specific validation requirements
|
||||
- ✅ Include clear instructions for subagent
|
||||
- ✅ Track progress through the task
|
||||
|
||||
**DON'T**:
|
||||
- ❌ Duplicate full context file content (just reference paths)
|
||||
- ❌ Use vague success criteria ("make it good")
|
||||
- ❌ Skip validation requirements
|
||||
- ❌ Forget to list technical constraints
|
||||
- ❌ Omit file paths for files to create/modify
|
||||
|
||||
### Example Context Bundle
|
||||
|
||||
See `.opencode/context/openagents-repo/examples/context-bundle-example.md` for a complete example.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-21
|
||||
**Version**: 1.0.0
|
||||
40
.opencode/context/openagents-repo/templates/navigation.md
Normal file
40
.opencode/context/openagents-repo/templates/navigation.md
Normal file
@@ -0,0 +1,40 @@
|
||||
<!-- Context: openagents-repo/navigation | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# OpenAgents Templates
|
||||
|
||||
**Purpose**: Template files and patterns for OpenAgents Control
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
openagents-repo/templates/
|
||||
├── navigation.md (this file)
|
||||
└── [template files]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Routes
|
||||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **View templates** | `./` |
|
||||
| **Blueprints** | `../blueprints/navigation.md` |
|
||||
| **Guides** | `../guides/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Type
|
||||
|
||||
**Templates** → Reusable template files
|
||||
**Patterns** → Common patterns and structures
|
||||
|
||||
---
|
||||
|
||||
## Related Context
|
||||
|
||||
- **OpenAgents Navigation** → `../navigation.md`
|
||||
- **Blueprints** → `../blueprints/navigation.md`
|
||||
- **Guides** → `../guides/navigation.md`
|
||||
Reference in New Issue
Block a user