⚡ OpenCode + Ruflo Swarm Workspace

Hermetic Development Harness & Multi-Agent Swarm Environment Powered by OpenCode and Ruflo, routed natively through AWS Bedrock.

---

🎨 Overview

This workspace provides an isolated environment for orchestration and coding. It pairs OpenCode's terminal interface with Ruflo's multi-agent swarm architecture and 300+ MCP tools.

All source code, compiled binaries, global state, vector databases, and logs reside inside the Script / Installation Directory (SCRIPT_DIR), keeping system-level paths (~/.config, ~/.local) clean. When you launch opencode inside any Target Project Directory, only minimal, non-polluting project metadata is initialized.

flowchart TD
    A["OpenCode TUI<br/><i>(Launched from /path/to/your/project/dir)</i>"] -->|Translated Commands & Agents| B["Ruflo MCP Server<br/><i>(300+ tools)</i>"]
    B -->|AWS SDK| C["AWS Bedrock (Claude Sonnet 4)"]
    D["ruflo-plugin-translator<br/><i>(Build-time, static)</i>"] -->|writes .opencode/| A

Loading

---

🚀 Quick Start

1. Initialize & Build Environment (One-Time Setup)

Navigate to your central installation directory, source the script, and run setup:

cd /path/to/installation/dir
source activate.sh
opencode_setup

This will:

• Clone OpenCode and Ruflo repositories
• Compile OpenCode into a native binary
• Build the Ruflo CLI engine
• Compile the Ruflo Plugin Translator into a standalone binary
• Run smoke tests on all three binaries

2. Launch Workspace in Your Project Directory

Navigate to your target project folder, source the script, and launch OpenCode:

cd /path/to/your/project/dir
source /path/to/installation/dir/activate.sh
opencode

3. Stop Services

To gracefully terminate background daemons and OpenCode instances:

opencode_stop

---

📋 Example: Build a Python Tkinter Calculator

Assumes opencode_setup has already been run once.

Terminal (outside OpenCode):

mkdir ~/calculator && cd ~/calculator
source ~/opencode-ruflo/activate.sh
opencode

Inside OpenCode TUI — type these commands in order:

Step 1. Check Ruflo is healthy:

/ruflo-status

Step 2. Initialize a swarm session:

/swarm init --topology hierarchical --max-agents 4 --strategy specialized

Step 3. Switch to the architect agent:

/agent architect

Step 4. Ask it to design the app:

Design a Python Tkinter calculator app. Single file calculator.py. GUI with buttons 0-9, +, -, *, /, =, C. Display area at top. Handle division by zero. Support keyboard input. Store the design in memory.

Step 5. Switch to the coder agent:

/agent coder

Step 6. Ask it to implement:

Implement the calculator based on the architect's design stored in memory. Write it to calculator.py. Use the hooks pre-edit and post-edit lifecycle. Store successful patterns in memory when done.

Step 7. Exit OpenCode: press Ctrl+C

Back in terminal:

python3 calculator.py

Calculator window opens.

---

Once inside the OpenCode interface, Ruflo commands and agents are available natively — translated ahead of time into OpenCode's .opencode/ format.

Step 1: Use Slash Commands Directly

Ruflo commands are translated into native OpenCode slash commands:

/ruflo-status
/swarm-init
/witness
/arena --rounds 3 --task "build a calculator"

Step 2: Switch to a Ruflo Agent

Select a specialized Ruflo agent from the agent picker, or switch via:

/agent coder
/agent architect
/agent reviewer
/agent researcher

Each agent has full access to Ruflo's 300+ MCP tools (memory, swarm orchestration, hooks, browser automation, neural learning, AgentDB, and more).

Step 3: Describe Your Task

With a Ruflo agent selected, describe what you want built:

Build a simple Python Tkinter calculator app. It should have a clean GUI,
basic arithmetic operations (+, -, *, /), a clear display, and keyboard input support.
Write the code to the project directory.

🏗️ What Happens Behind the Scenes

1. Plugin Translator (build-time): Scans Ruflo plugin directories and writes native OpenCode command/agent markdown files into .opencode/.
2. OpenCode loads these files natively — no runtime plugin, no bridge, no dynamic registration.
3. Ruflo MCP Server provides 300+ tools to all translated agents via the tools: { ruflo: true } config.
4. Architect Agent reads your request, drafts structural specifications, and selects design patterns.
5. Coder Agent writes production-ready code with complete logic and zero placeholders.
6. Tester Agent executes synthetic syntax checks and unit tests to verify correctness.

---

🧠 System Architecture

The system operates via a static translation pipeline — no runtime bridge, no dynamic plugin loading:

flowchart TD
    subgraph "Build Time (opencode_setup)"
        T["ruflo-plugin-translator<br/><i>(compiled binary)</i>"] -->|scans| P["Ruflo Plugins<br/>plugins/ruflo-*/"]
        T -->|writes| CMD[".opencode/command/*.md"]
        T -->|writes| AGT[".opencode/agent/*.md"]
    end

    subgraph "Runtime (opencode)"
        OC["OpenCode TUI<br/><i>(native binary)</i>"] -->|reads| CMD
        OC -->|reads| AGT
        AGT -->|tool calls| MCP["Ruflo MCP Server<br/><i>(ruflo mcp)</i>"]
        MCP --> Tools["300+ Ruflo Tools"]
    end

    Tools --> Memory["Memory & Embeddings"]
    Tools --> Swarm["Swarm Orchestration"]
    Tools --> Hooks["Hooks & Lifecycle"]
    Tools --> Browser["Browser Automation"]
    Tools --> AgentDB["Agent Database"]
    Tools --> Neural["Neural Learning"]

    OC -->|LLM calls| Bedrock["AWS Bedrock<br/>Claude Sonnet 4"]

Loading

Translation Pipeline

┌────────┐    ┌───────┐    ┌───────────┐    ┌───────┐    ┌───────┐
│  Scan  │ →  │ Parse │ →  │ Translate │ →  │ Write │ →  │ Clean │
└────────┘    └───────┘    └───────────┘    └───────┘    └───────┘

• Scan: Discover plugins with valid .claude-plugin/plugin.json manifests
• Parse: Extract commands (name, description, body) and agents (name, model, body)
• Translate: Map to OpenCode format — model shorthands resolved, constant fields applied
• Write: Atomic writes (temp + rename), skip if byte-identical (idempotent)
• Clean: Remove orphaned files from previous runs

---

🗄️ File Structure

Central Installation Directory (SCRIPT_DIR)

/path/to/installation/dir/           (SCRIPT_DIR)
├── activate.sh                      # Functions: opencode_setup, opencode, opencode_stop
│
├── github/                          # Source repositories (self-contained, no shared deps)
│   ├── anomalyco/opencode/          # OpenCode source (v1.18.4)
│   │   └── packages/opencode/dist/
│   │       └── opencode-*/bin/opencode   ← compiled native binary
│   └── ruvnet/ruflo/                # Ruflo source (v3.32.9)
│       ├── bin/cli.js               ← Ruflo CLI (shebang executable)
│       ├── plugins/                 # Ruflo plugin directories (translation source)
│       └── node_modules/            # Ruflo's own dependencies
│
├── ruflo-plugin-translator/         # Static translator tool
│   ├── src/                         # TypeScript source
│   ├── dist/                        # Compiled JS
│   └── bin/
│       └── ruflo-plugin-translator  ← compiled standalone binary (bun)
│
└── .local/                          # Isolated Global State
    ├── logs/ruflo.log               # Daemon execution log
    └── ruflo-global/                # Vector DB, Memory, AgentDB storage

Active Project Directory

/path/to/your/project/dir/
├── .env                             # AWS credentials (optional)
├── .gitignore                       # Auto-generated
├── opencode.json                    # Auto-generated runtime config (MCP, model, provider)
├── .opencode/                       # Translated commands & agents (created by translator)
│   ├── command/
│   │   ├── ruflo-status.md
│   │   ├── swarm-init.md
│   │   └── ...
│   └── agent/
│       ├── coder.md
│       ├── architect.md
│       └── ...
├── .claude/                         # Local Ruflo workspace settings
└── .ruflo/                          # Local Ruflo project state

---

🔐 Credentials & Authentication Order

AWS Bedrock credentials are dynamically loaded when opencode runs:

1. Active Shell Environment Variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION)
2. Project-Local .env File inside your project directory
3. System AWS Credentials File (~/.aws/credentials)

💡 Default Region: If AWS_REGION is omitted, the environment defaults to us-east-1.

---

🛠️ Troubleshooting

Action	Command	Purpose
Clean Start	opencode_stop && opencode	Restarts daemon and reloads credentials
Inspect Logs	cat $SCRIPT_DIR/.local/logs/ruflo.log	View daemon execution output
Check Processes	ps aux | grep ruflo	Verify daemon is active
Re-translate	Run opencode again (translator runs each launch)	Picks up plugin changes
Rebuild All	opencode_setup	Full clean rebuild of all binaries