Skip to main content

​
Quick Start

This guide will help you install SO1 agents and create your first automation workflow.
Prerequisites: You’ll need OpenCode or another compatible AI coding assistant, plus a GitHub account.

​
Installation

1

Clone the repository

git clone https://github.com/so1-io/so1-agents.git
cd so1-agents
2

Install to your project

Run the installation script to copy agents to your project:
./scripts/install-opencode.sh /path/to/your/project
Or install globally for all projects:
./scripts/install-opencode.sh --global
3

Verify installation

Check that agents are available:
ls -la .opencode/agent/
You should see all 20 agent markdown files.

​
Option 2: Manual Installation

Copy agent files directly to your project’s agent directory: 
# Copy all agents
cp so1-agents/agents/**/*.md /path/to/project/.opencode/agent/
cp so1-agents/orchestration/*.md /path/to/project/.opencode/agent/

​
Your First Agent Interaction

Once installed, activate agents by referencing them in your AI assistant: 
Use the Workflow Architect agent to design an n8n workflow that:
1. Triggers on GitHub push events
2. Runs tests and linting
3. Notifies Slack on failure

​
What Happens Next

When you invoke an agent, it will:
  1. Validate FORGE gate entry conditions - Ensures prerequisites are met
  2. Reference Veritas prompts - Uses curated prompt fragments
  3. Generate structured output - Creates schema-compliant deliverables
  4. Log decisions in ADR format - Documents rationale for choices
  5. Validate FORGE gate exit conditions - Confirms deliverables are complete

​
Example Output

Here’s what the Workflow Architect produces for a GitHub webhook: 
{
  "name": "GitHub Push to Slack",
  "nodes": [
    {
      "id": "webhook_trigger",
      "type": "n8n-nodes-base.webhook",
      "position": [250, 300],
      "parameters": {
        "httpMethod": "POST",
        "path": "github-push"
      }
    },
    {
      "id": "slack_notification",
      "type": "n8n-nodes-base.slack",
      "position": [500, 300],
      "parameters": {
        "channel": "#deployments",
        "text": "New push to {{ $json.repository.full_name }}"
      }
    }
  ],
  "connections": {
    "webhook_trigger": {
      "main": [[{ "node": "slack_notification", "type": "main", "index": 0 }]]
    }
  }
}

​
Validation

Validate your agent installation: 
# Validate all agents
./scripts/validate-agents.sh

# Validate specific agent
./scripts/validate-agents.sh agents/automation/workflow-architect.md

# Strict mode (warnings = errors)
./scripts/validate-agents.sh --strict
Expected output: 
Validating 20 agents...
✓ factory-orchestrator.md (11 checks)
✓ forge-gatekeeper.md (11 checks)
✓ workflow-architect.md (11 checks)
... (17 more)

Results: 225 checks, 0 failures, 0 warnings

​
Next Steps

Concepts

Learn about FORGE stages, Veritas, and agent architecture

Agent Catalog

Explore all 20 agents and their capabilities

Runbooks

Operational guides for using agents effectively

API Reference

Integrate SO1 programmatically