5.3 KiB

Raw Blame History

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:

Agents → Load: core-concepts/agents.md
- How agents are structured
- Category system
- Prompt variants
- Subagents vs category agents
Evals → Load: core-concepts/evals.md
- How testing works
- Running tests
- Evaluators
- Session collection
Registry → Load: core-concepts/registry.md
- How components are tracked
- Auto-detect system
- Validation
- Install system
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)

# 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 && npm run eval:sdk -- --agent={category}/{agent}

# Run smoke test
cd evals/framework && npm run eval:sdk -- --agent={agent} --pattern="smoke-test.yaml"

# Test with debug
cd evals/framework && npm 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

First time? → Read core-concepts/agents.md, evals.md, registry.md
Adding agent? → Load guides/adding-agent.md
Testing? → Load guides/testing-agent.md
Need details? → Load specific files from core-concepts/ or guides/

Last Updated: 2026-01-13
Version: 0.5.1

5.3 KiB Raw Blame History