My Opencode Setup: Guardrails, Intelligence, and Skill-Driven AI Workflows

The Superpowers Pipeline

Skills follow a priority hierarchy. Process skills fire first because they determine how to approach the task. Implementation skills guide execution. Review skills ensure quality:

1. Process skills — brainstorming, systematic-debugging, TDD, writing-plans. These determine HOW to approach the task.
2. Implementation skills — frontend-design, find-docs, accessibility-a11y. These guide execution.
3. Review skills — verification-before-completion, requesting-code-review. These ensure quality.

The Brainstorming Flow

When I type /brainstorming add a dark mode toggle, the skill:

1. Asks clarifying questions one at a time (scope, constraints, preferences)
2. For UI work, requests a design reference (Figma mockup, reference site, HTML sketch)
3. Generates a structured implementation plan via writing-plans
4. Offers execution choice: subagents (parallel) vs current session (sequential)
5. Runs TDD per task
6. Triggers verification (tests, lint, impact check)
7. Hands off to finishing (review, commit, merge)

Greenfield vs Brownfield

The pipeline looks different depending on whether you’re starting from scratch or working in an existing codebase:

Configuration

1
{
2
  "plugin": [
3
    "superpowers@git+https://github.com/obra/superpowers.git"
4
  ]
5
}

Installation:

1
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

Key point: This pipeline is the core. Every other layer exists to make it work reliably.

The Problem

Models trained 6 months ago don’t know about Astro 6 breaking changes or Tailwind v4 APIs. They hallucinate confidently.

The Philosophy

Skills should query live docs, not rely on stale training data.

Context7 — Live Library Documentation

Context7 solves this by providing a CLI that queries live library documentation on demand. The AI runs a resolve step to find the right library, then queries current docs. No stale training data, no guessing.

Installation:

1
bun i -g ctx7
2
ctx setup  # installs find-docs skill
3
ctx login

How it works:

1. ctx7 library <name> "<question>" — find the right library ID
2. ctx7 docs <libraryId> "<question>" — get current docs

The find-docs skill provides the same workflow for contexts where the AI uses its native skill system. Both enforce the same pattern: resolve first, then query.

Tavily — Web Research Escalation

The web research problem splits into distinct modes: sometimes you need a quick answer, sometimes you need to pull content from a known URL, and sometimes you need a full multi-source analysis with citations.

Installation:

1
curl -fsSL https://cli.tavily.com/install.sh | bash
2
tvly login
3
tvly skills install

Escalation pattern:

The seven Tavily skills:

Why This Enables the Workflow

The writing-plans skill generates accurate implementation steps when it has current docs. The brainstorming skill answers questions correctly when it can research live.

The Problem

Raw MCP tool outputs dump directly into context. A single Playwright snapshot is 56 KB. Five of those and the session dies before the skill pipeline can complete.

The Philosophy

Raw data should never enter the context window unless you’re editing it.

The Solution — context-mode

context-mode is an MCP plugin that intercepts tool outputs and routes them through an isolated subprocess. Only a condensed summary enters the context window. The full data stays in a searchable FTS5 database, available on demand through query tools.

Configuration

1
{
2
  "plugin": ["superpowers@...", "context-mode"],
3
  "mcp": {
4
    "context-mode": {
5
      "type": "local",
6
      "command": ["context-mode"]
7
    }
8
  }
9
}

AGENTS.md Routing Rules

The plugin alone isn’t enough. The real enforcement comes from routing rules written into AGENTS.md:

Tool Hierarchy

1. GATHER: ctx_batch_execute — run multiple commands + search in ONE call. This is the primary tool. One call replaces 30+ individual tool invocations.
2. FOLLOW-UP: ctx_search — query previously indexed content with natural language.
3. PROCESSING: ctx_execute / ctx_execute_file — run code in a sandboxed subprocess. Only stdout enters context.
4. WEB: ctx_fetch_and_index — fetch a URL, convert to markdown, chunk, index, then query. Raw HTML never touches context.
5. INDEX: ctx_index — store arbitrary content in the FTS5 knowledge base for later retrieval.

Why This Enables the Workflow

Without context protection, the skill pipeline dies halfway through. ctx_batch_execute lets the brainstorming and writing-plans skills research your codebase without burning the session.

For the deep dive on how context-mode works, see my earlier article.

The Problem

In a brownfield project, editing a function without knowing what calls it is Russian roulette. You fix one thing and break three others.

The Philosophy

Never edit code without understanding its blast radius.

The Solution — GitNexus

GitNexus builds a knowledge graph of your codebase from git history and AST analysis. Functions, classes, imports, call chains — everything becomes a queryable graph. Instead of grepping for callers and hoping you found them all, you ask the graph and get an exact answer with blast radius estimates.

Configuration

1
{
2
  "mcp": {
3
    "gitnexus": {
4
      "type": "local",
5
      "command": ["npx", "-y", "gitnexus", "mcp"]
6
    }
7
  }
8
}

AGENTS.md Enforcement Rules

These aren’t suggestions. They’re checked before every edit and every commit:

• MUST run gitnexus_impact before editing any symbol
• MUST run gitnexus_detect_changes before committing
• MUST warn if impact analysis returns HIGH or CRITICAL risk
• NEVER edit a function, class, or method without impact analysis first
• NEVER rename symbols with find-and-replace — use gitnexus_rename instead

Tool Mappings

Risk Levels

Why This Enables the Workflow

The TDD and verification skills can’t work safely without knowing what they’re affecting. gitnexus_impact runs automatically before edits. gitnexus_detect_changes confirms scope before finishing merges.

Practical Note

After committing, the GitNexus index goes stale. Run npx gitnexus analyze to refresh it. If the index previously included embeddings, add --embeddings to preserve them.

The Problem

In a brownfield project, editing a function without knowing what calls it is Russian roulette. You fix one thing and break three others.

The Philosophy

Never edit code without understanding its blast radius.

The Solution — GitNexus

GitNexus builds a knowledge graph of your codebase from git history and AST analysis. Functions, classes, imports, call chains — everything becomes a queryable graph. Instead of grepping for callers and hoping you found them all, you ask the graph and get an exact answer with blast radius estimates.

Configuration

1
{
2
  "mcp": {
3
    "gitnexus": {
4
      "type": "local",
5
      "command": ["npx", "-y", "gitnexus", "mcp"]
6
    }
7
  }
8
}

AGENTS.md Enforcement Rules

These aren’t suggestions. They’re checked before every edit and every commit:

• MUST run gitnexus_impact before editing any symbol
• MUST run gitnexus_detect_changes before committing
• MUST warn if impact analysis returns HIGH or CRITICAL risk
• NEVER edit a function, class, or method without impact analysis first
• NEVER rename symbols with find-and-replace — use gitnexus_rename instead

Tool Mappings

Risk Levels

Why This Enables the Workflow

The TDD and verification skills can’t work safely without knowing what they’re affecting. gitnexus_impact runs automatically before edits. gitnexus_detect_changes confirms scope before finishing merges.

Practical Note

After committing, the GitNexus index goes stale. Run npx gitnexus analyze to refresh it. If the index previously included embeddings, add --embeddings to preserve them.

The Problem

You paste descriptions like “there’s a red box with some text” and hope the AI understands. It can’t see the broken layout.

The Philosophy

Skills should diagnose from screenshots, not descriptions.

The Solution — Two-Stage Pipeline

1. agent-browser — captures browser screenshots
2. zai-mcp-server — analyzes (OCR, error diagnosis, UI diff)

Configuration

1
bun i -g agent-browser
2
agent-browser install
3
npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser -y -g

Why This Enables the Workflow

The verification skill can compare the implemented UI against the design reference from brainstorming. Instead of “does it look right?”, it’s “here’s the pixel diff.”

The Problem

Not all tasks need a frontier model. Routing, summarization, and classification waste money on overpowered models.

The Philosophy

Dual-model setup — right tool for each job.

Configuration

1
{
2
  "model": "zai-coding-plan/glm-5-turbo",
3
  "small_model": "zai-coding-plan/glm-4.5-air"
4
}

Model Roles

MCP Servers

Why This Enables the Workflow

The skill pipeline runs cheaper when routing and summarization use glm-4.5-air. Complex reasoning and code generation fire glm-5-turbo only when needed.

Configuration Highlights from tui.json

• Leader key: ctrl+x (Emacs-style)
• Input motions: ctrl+b/ctrl+f (word), ctrl+a/ctrl+e (line)
• Session management: <leader>n (new), <leader>l (list), <leader>g (timeline)
• Agent cycling: Tab / Shift+Tab

Key Highlights