OpenWriterControle/docs/contributing/DEVELOPMENT.md

Development Guide

Complete guide for developing on the OpenAgents repository

This guide covers everything you need to know to develop agents, commands, tools, and contribute to the OpenAgents ecosystem.

Table of Contents

• Getting Started
• Repository Structure
• Development Workflow
• Creating New Agents
• Testing
• Best Practices
• Common Tasks
• Troubleshooting

---

Getting Started

Prerequisites

• OpenCode CLI installed (installation guide)
• Node.js 18+ (for testing framework)
• Git for version control
• Bash (macOS/Linux) or Git Bash (Windows)

Clone and Setup

# Clone the repository
git clone https://github.com/darrenhinde/OpenAgents.git
cd OpenAgents

# Install dependencies for testing framework
cd evals/framework
npm install
cd ../..

Verify Setup

# Validate registry
make validate-registry

# Run tests
cd evals/framework
npm test

---

Repository Structure

opencode-agents/
├── .opencode/                    # OpenCode configuration
│   ├── agent/                    # Agent prompts (category-based)
│   │   ├── core/
│   │   │   ├── openagent.md          # Universal orchestrator
│   │   │   └── opencoder.md          # Development specialist
│   │   ├── meta/
│   │   │   └── system-builder.md     # System architect
│   │   ├── development/
│   │   │   ├── frontend-specialist.md
│   │   │   └── backend-specialist.md
│   │   ├── content/
│   │   │   └── copywriter.md
│   │   └── subagents/            # Specialized subagents
│   │       ├── code/             # Code-related subagents
│   │       ├── core/             # Core functionality subagents
│   │       ├── system-builder/   # System building subagents
│   │       └── utils/            # Utility subagents
│   ├── command/                  # Slash commands
│   │   ├── openagents/           # OpenAgents-specific commands
│   │   │   └── new-agents/       # Agent creation system ⭐
│   │   └── prompt-engineering/   # Prompt optimization commands
│   ├── context/                  # Context files
│   │   ├── core/                 # Core context (standards, workflows)
│   │   ├── project/              # Project-specific context
│   │   └── system-builder-templates/  # Templates
│   ├── plugin/                   # Plugins and integrations
│   ├── prompts/                  # Prompt library (model variants, category-based)
│   │   ├── core/
│   │   │   ├── openagent/            # OpenAgent variants
│   │   │   └── opencoder/            # OpenCoder variants
│   │   └── development/
│   │       └── frontend-specialist/  # Frontend specialist variants
│   └── tool/                     # Utility tools
├── evals/                        # Testing framework
│   ├── agents/                   # Agent test suites
│   │   ├── openagent/            # OpenAgent tests
│   │   └── opencoder/            # OpenCoder tests
│   ├── framework/                # Test framework code
│   │   ├── src/                  # Framework source
│   │   └── scripts/              # Test utilities
│   └── results/                  # Test results
├── scripts/                      # Automation scripts
│   ├── registry/                 # Registry management
│   ├── prompts/                  # Prompt management
│   └── testing/                  # Test utilities
├── docs/                         # Documentation
│   ├── agents/                   # Agent documentation
│   ├── contributing/             # Contribution guides
│   ├── features/                 # Feature documentation
│   └── guides/                   # User guides
└── registry.json                 # Component registry

Key Directories Explained

.opencode/agent/

Main agent prompts organized by category. These are the "brains" of the system:

• core/openagent.md - Universal orchestrator with plan-first workflow
• core/opencoder.md - Development specialist for direct code execution
• meta/system-builder.md - System architecture generator
• development/ - Development specialist agents (frontend, backend, devops)
• content/ - Content creation agents (copywriter, technical-writer)
• subagents/ - Specialized helpers for specific tasks

.opencode/command/

Slash commands that users can invoke:

• openagents/new-agents/ - ⭐ NEW: Agent creation system with research-backed principles
• prompt-engineering/ - Prompt optimization tools

.opencode/context/

Context files that agents load on-demand:

• core/ - Standards, patterns, workflows
• project/ - Project-specific context (CLAUDE.md pattern)

.opencode/prompts/

Prompt library with model-specific variants (category-based structure):

• Allows experimentation without breaking main branch
• Each variant has test results documented
• Organized by category matching agent structure (core/, development/, etc.)

evals/

Comprehensive testing framework:

• agents/ - Test suites for each agent (8 essential tests)
• framework/ - Testing infrastructure
• results/ - Test results and reports

---

Development Workflow

1. Create a Feature Branch

git checkout -b feature/my-new-feature

2. Make Your Changes

Follow the appropriate guide:

• Creating New Agents
• Adding Commands
• Adding Tools
• Writing Tests

3. Test Your Changes

# Validate structure
./scripts/registry/validate-component.sh

# Run tests
cd evals/framework
npm test -- --agent=your-agent

# Test manually
opencode --agent=your-agent

4. Commit and Push

git add .
git commit -m "feat: add new feature"
git push origin feature/my-new-feature

5. Create Pull Request

• Use conventional commit format in PR title
• Fill out PR template completely
• Ensure CI passes

---

Creating New Agents

⭐ NEW: Research-Backed Agent Creation System

We now have a streamlined system for creating agents following Anthropic 2025 research best practices.

Quick Start

# Use the agent creation command
/create-agent my-agent-name

# Or invoke directly
opencode "Create a new agent called 'python-dev' for Python development"

What Gets Created

The system generates:

1. Minimal agent prompt (~500 tokens at "right altitude")
2. Project context file (CLAUDE.md pattern)
3. 8 comprehensive tests (planning, context, incremental, tools, errors, thinking, compaction, completion)
4. Test configuration
5. Registry entry

Research-Backed Principles

The agent creation system follows these proven patterns:

1. Single Agent + Tools > Multi-Agent for Coding

Why: Code changes are deeply dependent. Sub-agents can't coordinate edits to the same file.

Application:

• Use ONE lead agent with tool-based sub-functions
• NOT autonomous sub-agents for coding
• Multi-agent only for truly independent tasks (static analysis, test execution, code search)

2. Minimal Prompts at "Right Altitude" (~500 tokens)

Why: "Find the smallest possible set of high-signal tokens that maximize likelihood of desired outcome"

The Balance:

Too Vague	Right Altitude ✅	Too Rigid
"Write good code"	Clear heuristics + examples	50-line prompt with edge cases

Application:

• Clear heuristics, not exhaustive rules
• Examples > edge case lists
• Show ONE canonical example, not 20 scenarios

3. Just-in-Time Context Loading

Why: Prevents "drowning in irrelevant information"

Application:

• Tools load context on demand (not pre-loaded)
• CLAUDE.md pattern for project context
• File metadata guides behavior

4. Tool Clarity

Why: "Tool ambiguity is one of the biggest failure modes"

Application:

<tool name="read_file">
  <purpose>Load specific file for analysis or modification</purpose>
  <when_to_use>You need to examine or edit a file</when_to_use>
  <when_not_to_use>You already have the file content in context</when_not_to_use>
</tool>

5. Extended Thinking for Complex Tasks

Why: Improved instruction-following and reasoning efficiency

Application:

• Trigger thinking before complex tasks
• "Think hard about how to approach this problem..."
• Phrases mapped to thinking budget (think, think hard, think harder)

6. Compaction for Long Sessions

Why: Maintain context efficiency over long-horizon tasks

Application:

• Agent writes notes to persistent memory
• Summarizes when context fills
• Preserves: architectural decisions, unresolved bugs, implementation details
• Discards: redundant tool outputs

7. Parallel Tool Calling

Why: "Parallel tool calling cut research time by up to 90%"

Application:

• Can do in parallel: Run linter, execute tests, check type errors
• NOT in parallel: Apply fix, then test (sequential)

8. Outcome-Focused Evaluation

Why: "Token usage explains 80% of performance variance"

Measure:

• ✅ Does it solve the task?
• ✅ Token usage reasonable?
• ✅ Tool calls appropriate?
• ❌ NOT: "Did it follow exact steps I imagined?"

Manual Agent Creation

If you prefer manual creation, follow this structure:

1. Create Agent File (.opencode/agent/my-agent.md)

---
description: "Brief one-line description"
mode: primary
temperature: 0.1
tools:
  read: true
  write: true
  edit: true
  bash: true
  glob: true
  grep: true
permissions:
  bash:
    "rm -rf *": "ask"
    "sudo *": "deny"
  edit:
    "**/*.env*": "deny"
    "**/*.key": "deny"
---

# My Agent

<role>
Clear, concise role - what this agent does
</role>

<approach>
1. Read and understand the context
2. Think about the approach before acting
3. Implement changes incrementally
4. Verify each step with appropriate tools
5. Complete with clear summary
</approach>

<heuristics>
- Decompose problems before implementing
- Use tools intentionally (not speculatively)
- Verify outputs before claiming completion
- Stop on errors and report (don't auto-fix blindly)
</heuristics>

<output>
Always include:
- What you did
- Why you did it that way
- Test/validation results
</output>

<examples>
  <example name="Typical Use Case">
    **User**: "typical request"
    
    **Agent**:
    1. Read relevant files
    2. Think about approach
    3. Implement change
    4. Verify
    
    **Result**: Expected outcome
  </example>
</examples>

2. Create Context File (.opencode/context/project/my-agent-context.md)

# My Agent Context

## Key Commands
- command 1: what it does
- command 2: what it does

## File Structure
- path pattern: what goes here

## Code Style
- style rule 1
- style rule 2

## Workflow Rules
- workflow rule 1
- workflow rule 2

## Before Committing
1. check 1
2. check 2

3. Create Test Suite

Use the test generator:

/create-tests my-agent

Or manually create 8 tests in evals/agents/my-agent/tests/:

1. planning/planning-approval-001.yaml
2. context-loading/context-before-code-001.yaml
3. implementation/incremental-001.yaml
4. implementation/tool-usage-001.yaml
5. error-handling/stop-on-failure-001.yaml
6. implementation/extended-thinking-001.yaml
7. long-horizon/compaction-001.yaml
8. completion/handoff-001.yaml

4. Register Agent

The registry auto-updates on merge to main, or manually:

./scripts/registry/register-component.sh

Templates

Pre-built templates are available in:

.opencode/command/openagents/new-agents/templates/
├── agent-template.md              # Minimal agent template
├── context-template.md            # CLAUDE.md pattern
├── test-config-template.yaml      # Test configuration
└── test-*.yaml                    # 8 test templates

---

Adding Commands

Commands are slash commands users can invoke.

Structure

---
description: "What this command does"
---

# Command Name

<target_argument> $ARGUMENTS </target_argument>

<role>
What this command specializes in
</role>

<task>
Specific objective of this command
</task>

<workflow>
  <step_1>
    Action and process
  </step_1>
  
  <step_2>
    Action and process
  </step_2>
</workflow>

Example

See .opencode/command/openagents/new-agents/create-agent.md for a complete example.

---

Adding Tools

Tools are TypeScript utilities that agents can use.

Structure

/**
 * Tool Name
 * 
 * Brief description of what this tool does
 */

export function myTool(param: string): string {
  // Implementation
  return result;
}

Location

Place tools in .opencode/tool/my-tool/index.ts

---

Testing

Test Framework

We use a comprehensive evaluation framework in evals/framework/.

Running Tests

# Run all tests
cd evals/framework
npm test

# Run tests for specific agent
npm test -- --agent=openagent

# Run specific category
npm test -- --agent=openagent --category=planning

# Run single test
npm test -- --agent=openagent --test=planning-approval-001

# Verbose output
npm test -- --verbose

Writing Tests

Each agent should have 8 essential test types:

1. Planning & Approval - Verify plan-first approach
2. Context Loading - Ensure just-in-time context retrieval
3. Incremental Implementation - Verify step-by-step execution
4. Tool Usage - Check correct tool selection
5. Error Handling - Verify stop-on-failure behavior
6. Extended Thinking - Check decomposition before coding
7. Compaction - Verify long session handling
8. Completion - Check proper output and handoff

Test Structure

id: test-id-001
name: Test Name
description: |
  What this test verifies  

category: planning
agent: my-agent
model: anthropic/claude-sonnet-4-5

prompt: |
  Test prompt  

behavior:
  mustContain:
    - "expected text"
  mustNotContain:
    - "forbidden text"
  mustUseAnyOf: [[tool1], [tool2]]
  minToolCalls: 1

expectedViolations:
  - rule: rule-name
    shouldViolate: false
    severity: error

approvalStrategy:
  type: auto-approve

timeout: 30000

tags:
  - tag1
  - tag2

Test Templates

Use the templates in .opencode/command/openagents/new-agents/templates/ as starting points.

---

Best Practices

Agent Design

✅ Do:

• Keep system prompts minimal (~500 tokens)
• Use clear heuristics, not exhaustive rules
• Provide ONE canonical example
• Define tools with clear purpose and when to use/not use
• Load context on-demand (just-in-time)
• Measure outcomes: Does it solve the task?

❌ Don't:

• Create sub-agents for dependent tasks (code is sequential)
• Pre-load entire codebase into context
• Write exhaustive edge case lists in prompts
• Give vague tool descriptions
• Use multi-agent if you could use single agent + tools
• Minimize tool calls (some redundancy is fine)

Code Style

Markdown

• Use clear, concise language
• Include examples
• Add code blocks with syntax highlighting
• Use proper heading hierarchy

TypeScript

• Follow existing code style
• Add JSDoc comments
• Use TypeScript types (no any)
• Export functions explicitly

Bash Scripts

• Use set -e for error handling
• Add comments for complex logic
• Use meaningful variable names
• Include help text

File Naming

• kebab-case for file names: my-new-agent.md
• PascalCase for TypeScript types/interfaces
• camelCase for variables and functions

---

Common Tasks

Update an Existing Agent

# 1. Edit the agent file
vim .opencode/agent/my-agent.md

# 2. Test changes
cd evals/framework
npm test -- --agent=my-agent

# 3. Update tests if needed
vim evals/agents/my-agent/tests/...

# 4. Commit
git add .
git commit -m "feat: improve my-agent behavior"

Add a New Test

# 1. Create test file
vim evals/agents/my-agent/tests/new-category/new-test-001.yaml

# 2. Update config
vim evals/agents/my-agent/config/config.yaml
# Add new category to testPaths

# 3. Run test
cd evals/framework
npm test -- --agent=my-agent --test=new-test-001

Create a Prompt Variant

# 1. Copy template
cp .opencode/prompts/core/openagent/TEMPLATE.md .opencode/prompts/core/openagent/my-variant.md

# 2. Edit variant
vim .opencode/prompts/core/openagent/my-variant.md

# 3. Test variant
./scripts/prompts/test-prompt.sh core/openagent my-variant

# 4. Update README with results
vim .opencode/prompts/core/openagent/README.md

Validate Before PR

# Validate component structure
./scripts/registry/validate-component.sh

# Ensure using default prompts
./scripts/prompts/validate-pr.sh

# Run all tests
cd evals/framework
npm test

# Validate registry
make validate-registry

---

Troubleshooting

Tests Failing

Problem: Tests fail after making changes

Solution:

1. Check test output for specific failures
2. Run with --verbose flag for details
3. Verify agent follows expected behavior
4. Update tests if behavior intentionally changed

Registry Validation Fails

Problem: make validate-registry fails

Solution:

1. Check registry.json syntax
2. Ensure all referenced files exist
3. Verify frontmatter in agent files is valid YAML
4. Run ./scripts/registry/validate-component.sh for details

Agent Not Loading Context

Problem: Agent doesn't load context files

Solution:

1. Verify context file exists in .opencode/context/
2. Check agent has read tool enabled
3. Ensure context file path is correct
4. Test with simple prompt that requires context

Tool Not Working

Problem: Custom tool not accessible to agent

Solution:

1. Verify tool is in .opencode/tool/my-tool/index.ts
2. Check tool is exported properly
3. Ensure agent has tool enabled in frontmatter
4. Rebuild if needed: cd .opencode/tool && npm run build

---

Additional Resources

Documentation

• Contributing Guide - General contribution guidelines
• Agent Creation System - Detailed agent creation guide
• Research-Backed Prompt Design - Prompt engineering principles
• Test Design Guide - Writing effective tests

Examples

• OpenAgent - Universal orchestrator example
• OpenCoder - Development specialist example
• Subagents - Specialized subagent examples
• Test Suites - Comprehensive test examples

Tools

• Agent Creation Command
• Test Generator Command
• Prompt Optimizer

---

Questions?

• Issues: Open an issue for bugs or feature requests
• Discussions: Use GitHub Discussions for questions
• Security: Email security issues privately

---

Happy developing! 🚀