opencode-config

Configuration, guidelines, and skills for OpenCode AI assistant.

Install as a Git Submodule

git submodule add git@github.com:michael-conrad/opencode-config.git .opencode

Overview

This repository provides a comprehensive framework for configuring and extending OpenCode with:

• Guidelines - Core rules and protocols for AI agent behavior
• Skills - Self-contained task-specific workflows
• Tools - Utility scripts for session management
• Tests - Enforcement test framework

Features

• Spec-Driven Development - All code changes require approved specs
• Authorization Gates - Explicit approval required before implementation
• Pair Mode - Collaborative development on pair-* branches
• Session Enforcement - TypeScript plugin validates agent identity and triggers
• Git Workflow - Trunk-based development: feature → $DEFAULT_BRANCH → main
• Verification Gates - Evidence-based completion verification
• Fragment Registry - Synchronized content blocks across skills

Runtime Dependencies

Model Provider: Ollama / Ollama-Cloud

The entire skilldeck is hard-wired to use Ollama as its model provider — both locally (via the ollama CLI) and via ollama-cloud (Ollama's cloud-hosting service). There is no abstraction layer or alternate provider. If Ollama is not installed and ollama-cloud is not accessible, the skilldeck cannot dispatch agents.

Layer	Ollama Footprint
Agent definitions (agents/auditor-*.md)	All 4 auditor agents hard-code model: ollama/:cloud
Behavioral tests (tests-v2/behaviors/)	Default test model: ollama/qwen3.6:35b-256k (from default-model.sh); helpers.sh sources default-model.sh
Content-verification tests (test-enforcement.sh)	Default model: ollama/qwen3.6:35b-256k (from default-model.sh)
Auditor pool (tests-v2/qualification/qualified-auditor-pool.sh)	4 audited models, all :cloud-suffixed via Ollama
Adversarial audit (skills/audit/)	Cross-family cross-validation dispatches dual Ollama models per audit via resolve-models
Tooling (tools/ollama-probe, tools/resolve-models)	Dedicated tools for probing local Ollama server and resolving auditor model pairs
Guidelines (020-go-prohibitions.md)	References ollama-probe hw as mandatory hardware assessment step

Prerequisites

Requirement	Minimum	Recommended
Ollama (local)	Installed, reachable at localhost:11434	curl -fsSL https://ollama.com/install.sh | sh
ollama-cloud	Token configured (via ollama login or env) for cloud model access	Verified via ollama list — cloud models show SIZE of "-"
VRAM (for local models)	8 GB for a ≥7B model	16 GB+ for multiple concurrent models
Hardware probe	ollama-probe hw must return VRAM ≥ 8 GB	Run at session start to validate capacity

Model Configuration

Setting	Mechanism	Default
Default test model	DEFAULT_TEST_MODEL env var (sourced from tests-v2/default-model.sh)	ollama/qwen3.6:35b-256k
Auditor agent models	model: field in agents/auditor-*.md YAML frontmatter	Per-card (e.g., ollama/deepseek-v4-flash:cloud)
Qualified auditor pool	tests-v2/qualification/qualified-auditor-pool.sh	4 models (deepseek-v4-flash, gemma4, mistral-large-3, qwen3.5)
Auditor pair resolution	tools/resolve-models scans cards + pool	Selects 2 auditors from different families

Model name convention: ollama/:cloud (agent definitions, test helpers) and ollama-cloud/ (content-verification tests) both resolve to the same Ollama cloud model namespace.

Directory Structure

.
├── AGENTS.md              # Main guidelines for AI agents
├── opencode.jsonc         # OpenCode configuration
├── dispatch-table.yaml   # DEPRECATED skill dispatch (historical)
├── guidelines/            # Core rule definitions
├── skills/                # Self-contained skill modules
├── tools/                 # Utility scripts
├── scripts/               # Session context scripts
├── plugins/               # TypeScript plugins
├── hooks/                 # Git hooks
├── tests-v2/              # Enforcement test suite
├── docs/                  # Documentation
└── .guidelines/           # Fragment registry

Guidelines (guidelines/)

Core rules organized by series:

Series	Category	Files
000-099	Core Rules	critical-rules, approval-gate, go-prohibitions, scope-autonomy, tool-usage, environment, incremental-build
100-199	Planning	planning-spec-creation, planning-status-tracking, planning-archive-workflow, planning-spec-templates, planning-spec-examples
200-299	Error Handling	exception-handling, missing-data, logging-vs-raising, domain-exceptions

Skills (skills/)

Self-contained modules with YAML frontmatter for self-discovery:

Category	Skills
Workflow	approval-gate, git-workflow, executing-plans, writing-plans, finishing-a-development-branch
Planning	brainstorming, spec-creation
Quality	spec-auditor, guideline-auditor, coherence-auditor, code-size-enforcement, plan-fidelity-auditor
Review	requesting-code-review, receiving-code-review, issue-review
Debug	systematic-debugging, conflict-resolution
Development	test-driven-development, programming-principles, engineering-approach
Operations	mcp-tool-usage, issue-operations, git-workflow-pr
Maintenance	skill-creator, fragment-manager, sync-guidelines, changelog-generator
Audit	verification, verification-before-completion, verification-enforcement
Other	correspondence, multimodal-dispatch, sre-runbook, research

Tools (tools/)

Tool	Purpose
session-init	Emit session context (owner, repo, platform). Canonical source for identity data including Sub-folder Repo Mappings.
guidelines	Guideline management
md	Markdown utilities
py	Python utilities
jupyter, jupyter-start, jupyter-stop	Jupyter notebook management
memory	Memory/state persistence
symbolic	Symbolic link management
help	Help documentation

Plugins (plugins/)

Plugin	Purpose
session-enforcement.ts	Identity validation, trigger injection, hook installation
env-loader.ts	Environment variable loading

Scripts (scripts/)

Script	Purpose
session_context_triggers.py	Trigger warning generation
validate-release-tags.sh	Release tag validation
validate-submodule-refs.sh	Submodule reference validation

Configuration

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    ".opencode/AGENTS.md",
    ".opencode/guidelines/000-critical-rules.md",
    ".opencode/guidelines/010-approval-gate.md",
    ".opencode/guidelines/020-go-prohibitions.md",
    ".opencode/guidelines/060-tool-usage.md"
  ],
  "mcp": {
    "the-notebook-mcp": { ... },
    "srclight": { ... }
  }
}

Session Context

At session start:

1. Identity section - github.owner, github.repo, github.platform, credential status
2. Identity-echo directive - Mandatory identity echo
3. Trigger alerts - Warnings for special states (main branch, uncommitted work, merge conflicts, etc.)

Pair Mode

When branch starts with pair-, agent operates in collaborative mode:

Branch Pattern	Mode	Working Directory
pair-feature/123-xyz	Dev-pair	Main project dir
feature/789-xyz	Autonomous	.worktrees/

Testing

Skill Enforcement Tests

# Run all enforcement tests
bash tests/test-enforcement.sh

# Run by scenario
bash tests/test-enforcement.sh --scenario NAME

# Run by tag
bash tests/test-enforcement.sh --tag TAG

# Run for changed files
bash tests/test-enforcement.sh --changed [--base BRANCH]

# List scenarios
bash tests/test-enforcement.sh --list

Behavioral Tests

Behavioral tests generate model-run artifacts. Run individual scenario scripts:

bash tests/behaviors/<scenario>.sh

Isolated Testing

# Run opencode in isolated environment
bash tests-v2/with-test-home opencode run '<message>'

# Clean test artifacts
bash tests-v2/with-test-home --clean

Critical Rules

Authorization Workflow

1. Branch Before Edit - Create feature branch BEFORE any filesystem change
2. Explicit Authorization - Wait for "approved" or "go" before implementing
3. Spec Required - No implementation without approved spec
4. HALT After Tasks - Silently halt after completing a task

Multi-Task Spec Workflow

When parent issue has sub-issues, authorization cascades to ALL sub-issues:

• User authorizes parent issue
• Verify parent has sub-issues
• Authorization cascades to ALL sub-issues
• Complete ALL phases in sequence (NO HALT between phases)
• Report ONCE after ALL phases complete
• HALT ONCE at the end

Verification Gates

Before completion claims:

1. verification-before-completion - Evidence verification
2. finishing-a-development-branch - Branch readiness check
3. git-workflow review-prep - Push and prepare for review

Fragment Registry

Duplicate content blocks synchronized across skills via .guidelines/registry.yaml.

Use fragment-manager skill for CRUD operations:

# Create fragment from duplicate content
`skill({name: "fragment-manager"})` then `task(..., prompt: "execute create-fragment task from fragment-manager")`

# Sync fragment to destinations
`skill({name: "fragment-manager"})` then `task(..., prompt: "execute sync-fragment task from fragment-manager with fragment-id <id>")`

# Check for drift
`skill({name: "fragment-manager"})` then `task(..., prompt: "execute check-drift task from fragment-manager")`

Submodule Tracking

When this repository is consumed as a submodule (e.g., .opencode/), it must track the $DEFAULT_BRANCH branch — never detached HEAD and never main.

Why

• $DEFAULT_BRANCH is the active development branch with the latest guidelines, skills, and tools
• main is reserved for stable releases and will lag behind ongoing work
• Detached HEAD prevents git pull from receiving updates and makes local changes fragile

Verification

git submodule status          # Should show branch name, not a bare SHA
cat .gitmodules               # branch = $DEFAULT_BRANCH
cd .opencode && git branch --show-current  # Must print "$DEFAULT_BRANCH"

Recovery

If a submodule is detached or tracking main:

cd .opencode
git checkout $DEFAULT_BRANCH
git pull
cd ..
git add .opencode
git commit -m "chore: fix submodule tracking to $DEFAULT_BRANCH"

License

MIT

See Also

• AGENTS.md - Main guidelines
• tests/README.md - Test documentation
• .guidelines/README.md - Fragment registry docs