A starter kit for configuring OpenCode with a product-development agent orchestration flow, Open Design integration, optional Impeccable design context, Superpowers workflow discipline, local process skills, a TUI token-usage plugin, and optional AHE observability sidecars.

This project is for developers who want a reproducible global OpenCode setup without hand-writing agents, commands, skills, tools, and Docker notes from scratch.

This repository is not affiliated with OpenCode, Open Design, Impeccable, or Superpowers.

Agentic coding workflows are becoming complex to configure and maintain. This kit provides a reproducible, documented OpenCode harness with role-based agents, process skills, validation scripts, Open Design integration, and safe installation defaults. The goal is to help developers and small teams adopt agent orchestration without starting from scratch.

By default, free-form messages open with lead as a bounded router. Lead quickly chooses developer, researcher, designer, or specifier, and asks the user when ambiguity changes the correct flow. Small, clear, low-risk changes are usually delegated straight to developer.

Core feature flow:

lead -> designer if applicable -> researcher -> specifier -> developer -> reviewer

Scoped research/spec flow:

scoper -> researcher -> scoper synthesis -> specifier

Plan-only flow:

lead -> researcher -> specifier -> reviewer

Design flow:

designer -> open-design

Optional harness-evolution flow:

evaluator -> debugger -> evolver -> lead approval -> developer -> evaluator -> debugger -> reviewer

Harness contracts are versioned inside the shipped OpenCode config:

• opencode/AGENTS.md: short index for agents.
• opencode/docs/ai/harness/: agent, command, evidence, and check contracts.
• opencode/docs/ai/evolution/: AHE benchmark and evolution records.
• opencode/scripts/check-harness.mjs: local mechanical validation for the harness.
• opencode/plugins/token-tree-usage.tsx: sidebar TUI plugin that reports lead tokens and total tokens across child/subagent sessions when the OpenCode TUI exposes session children.

Included locally:

• open-design: shipped in this repo at opencode/skills/open-design. It wraps Open Design workbench usage through OPEN_DESIGN_URL and the open_design_* tools.
• Process skills under opencode/skills/ for source-driven development, testing, debugging, API/interface design, review, simplification, security, performance, and documentation/ADRs. Agents use them as checklists, not as mandatory extra phases.

Referenced from upstream:

• superpowers: not vendored in this repo. It is enabled through the upstream OpenCode plugin superpowers@git+https://github.com/obra/superpowers.git, so OpenCode downloads/loads it from upstream when plugins are supported and network access is available.

Optional, user-installed:

• impeccable: not included in this repo. Install it from upstream if you want designer to use it when PRODUCT.md or DESIGN.md are missing.

git clone https://github.com/jcarlosrodicio/opencode-agent-orchestration-kit.git
cd opencode-agent-orchestration-kit
./install.sh

Then configure your environment:

cp env.example .env
source .env
(cd opencode && npm install)
opencode auth login
opencode

export OPENCODE_CONFIG_DIR="$PWD/opencode"
export OPEN_DESIGN_URL="https://open-design.example.com"
opencode

This is the safest way to test the kit before touching your global config.

./install.sh

The installer copies agents, commands, skills, and tools to ${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}. It creates a backup when existing files are present. It does not overwrite opencode.json or AGENTS.md unless you pass --force.

./install.sh --target "$HOME/.config/opencode"
./install.sh --force

If your existing opencode.json was preserved, add Superpowers manually. This references the upstream plugin; it does not copy Superpowers into this repository:

{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}

If your existing tui.json was preserved, add the bundled token usage plugin manually:

{
  "plugin": ["./plugins/token-tree-usage.tsx"]
}

For reproducibility you may pin a version:

{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.5"]
}

The example config reads models from environment variables:

export OPENCODE_MODEL="openai/gpt-5.5"
export OPENCODE_SMALL_MODEL="$OPENCODE_MODEL"
export OPENCODE_LEAD_MODEL="$OPENCODE_MODEL"
export OPENCODE_DEVELOPER_MODEL="$OPENCODE_MODEL"

See env.example for all role-specific variables.

Set OPEN_DESIGN_URL to the base URL of your Open Design workbench.

Valid:

export OPEN_DESIGN_URL="https://open-design.example.com"
export OPEN_DESIGN_URL="http://192.168.1.50:7456"

Invalid:

export OPEN_DESIGN_URL="https://open-design.example.com/projects/my-project"
export OPEN_DESIGN_URL="https://open-design.example.com/projects/my-project/files/index.html"

Do not expose Open Design directly to the Internet without authentication, VPN, Tailscale, WireGuard, or a secure reverse proxy.

/feature Create onboarding with plan selection and welcome screen
/plan Add a dry-run flag to the harness check without implementing it yet
/scope Research Stripe Checkout integration and generate an MVP spec
/mvp-spec Email notifications when an agent finishes a task
/design Read PRODUCT.md and DESIGN.md, create an editable Open Design project, and generate a first version
/test Reproduce the checkout regression with a focused test
/code-simplify Simplify the parser branch without changing behavior
/review

Without a slash command, simple implementation requests go directly through developer. Use /plan when you want research, spec, and reviewer feedback without implementation; use /feature when you want the full orchestration flow.

npm run check

This runs the repository checks plus the harness validator in opencode/scripts/check-harness.mjs.

cd docker/open-design
cp .env.example .env
docker compose up -d --build

Authenticate OpenCode inside the container if you want Open Design to use OpenCode as the design engine:

docker exec -it open-design bash
opencode auth login
opencode models openai --refresh
exit

Then set:

export OPEN_DESIGN_URL="http://192.168.1.50:7456"

• Do not commit .env, auth files, sessions, logs, or provider credentials.
• Do not commit private PRODUCT.md or DESIGN.md files unless intended.
• Open Design can run local agent CLIs and write files inside project workspaces.
• Prefer localhost, LAN, VPN, Tailscale, WireGuard, or authenticated HTTPS reverse proxy.

• OPEN_DESIGN_URL is not set: export the base URL, not a project URL.
• /api/health fails: check Open Design is running and reachable from your OpenCode process.
• OpenCode does not appear in Open Design agents: run opencode auth login and ensure opencode is on PATH.
• crypto.randomUUID fails on HTTP LAN: use HTTPS or the optional upstream frontend patch described in docs.
• Superpowers skills do not load: restart OpenCode and verify the plugin line in opencode.json.
• TUI token usage does not appear: verify tui.json, run npm install in the OpenCode config directory, and restart OpenCode.
• Designer cannot see Open Design: verify OPEN_DESIGN_URL, tool registration, and opencode/tools/open_design.ts.

Apache License 2.0. See LICENSE and NOTICE.md.