Agent Installation
This guide covers installing SO1 agents for use with OpenCode or other compatible AI coding assistants.
Prerequisites
Before installing, ensure you have:
- OpenCode or compatible AI assistant installed
- Git for cloning the repository
- A project directory (for local install) or home directory (for global install)
Installation Methods
Step 1: Clone the Repository
git clone https://github.com/so1-io/so1-agents.git
cd so1-agents
Step 2: Run Installation Script
Local installation (project-specific):./scripts/install-opencode.sh /path/to/your/project
./scripts/install-opencode.sh --global
Step 3: Verify Installation
# For local install
ls -la /path/to/your/project/.opencode/agent/
# For global install
ls -la ~/.opencode/agent/
Step 1: Clone the Repository
git clone https://github.com/so1-io/so1-agents.git
cd so1-agents
Step 2: Create Agent Directory
# For local install
mkdir -p /path/to/your/project/.opencode/agent
# For global install
mkdir -p ~/.opencode/agent
Step 3: Copy Agent Files
# Copy all agents
cp agents/**/*.md /path/to/destination/.opencode/agent/
cp orchestration/*.md /path/to/destination/.opencode/agent/
Step 4: Verify Installation
ls -la /path/to/destination/.opencode/agent/
Future Installation
# Project-specific
npm install --save-dev @so1/agents
# Global
npm install -g @so1/agents
NPM package installation is not yet available. Use the script or manual installation for now.
Directory Structure
After installation, your .opencode/agent/ directory will contain:
.opencode/agent/
├── factory-orchestrator.md # Orchestration
├── forge-gatekeeper.md
├── workflow-architect.md # Automation
├── webhook-engineer.md
├── schedule-optimizer.md
├── hono-backend.md # Engineering
├── nextjs-frontend.md
├── typescript-shared.md
├── railway-deployer.md # DevOps
├── github-actions.md
├── pipeline-auditor.md
├── mintlify-author.md # Documentation
├── api-documenter.md
├── runbook-writer.md
├── prompt-refiner.md # Prompts
├── chain-architect.md
├── fragment-curator.md
├── incident-commander.md # Incident
├── triage-responder.md
└── postmortem-analyst.md
Configuration
OpenCode Configuration
Agents are automatically detected by OpenCode. You can reference them in your prompts:
Use the Workflow Architect agent to design an n8n workflow
Global vs. Local Installation
| Installation Type | Location | Scope |
|---|
| Global | ~/.opencode/agent/ | All projects |
| Local | <project>/.opencode/agent/ | Single project |
Recommendation: Use global installation for general use, local for project-specific customizations.
Validation
After installation, validate agents are correctly configured:
cd so1-agents
./scripts/validate-agents.sh
Validating 20 agents...
✓ factory-orchestrator.md (11 checks)
✓ forge-gatekeeper.md (11 checks)
✓ workflow-architect.md (11 checks)
✓ webhook-engineer.md (11 checks)
✓ schedule-optimizer.md (11 checks)
✓ hono-backend.md (11 checks)
✓ nextjs-frontend.md (11 checks)
✓ typescript-shared.md (11 checks)
✓ railway-deployer.md (11 checks)
✓ github-actions.md (11 checks)
✓ pipeline-auditor.md (11 checks)
✓ mintlify-author.md (11 checks)
✓ api-documenter.md (11 checks)
✓ runbook-writer.md (11 checks)
✓ prompt-refiner.md (11 checks)
✓ chain-architect.md (11 checks)
✓ fragment-curator.md (11 checks)
✓ incident-commander.md (11 checks)
✓ triage-responder.md (11 checks)
✓ postmortem-analyst.md (11 checks)
Results: 225 checks, 0 failures, 0 warnings
Troubleshooting
Agents not detected by OpenCode
Solution: Verify the .opencode/agent/ directory exists and contains agent files.# Check directory exists
ls -la .opencode/agent/
# Check files are markdown
file .opencode/agent/*.md
Installation script fails
Solution: Check permissions and directory existence.# Make script executable
chmod +x scripts/install-opencode.sh
# Check target directory is writable
ls -ld /path/to/target
Validation shows failures
Solution: Check for file corruption or incomplete installation.# Re-clone repository
rm -rf so1-agents
git clone https://github.com/so1-io/so1-agents.git
# Re-run validation
cd so1-agents
./scripts/validate-agents.sh
Updating Agents
To update to the latest version:
# Pull latest changes
cd so1-agents
git pull origin main
# Re-run installation
./scripts/install-opencode.sh /path/to/your/project
# Verify update
./scripts/validate-agents.sh
Uninstallation
To remove agents:
# Local installation
rm -rf /path/to/project/.opencode/agent/*.md
# Global installation
rm -rf ~/.opencode/agent/
Next Steps
