JSPM

opencode-kit

Standardized OpenCode orchestration framework — contract-based, rules-enforced, zero-touch agent workflow
Explore the docs »

Report Bug · Request Feature

npm: @ikieaneh/opencode-kit · macOS M-Series — Apple Silicon (arm64)

About The Project

opencode-kit is a workflow enforcement framework for AI coding agents. It ensures agents follow a structured process — plan, build, review, learn — instead of jumping straight to implementation.

The Problem

AI agents (Claude, Copilot, etc.) are powerful but unpredictable. When given a task, they often:

• Skip project conventions and jump directly to writing code
• Ignore shared state — each session starts from scratch
• Bypass quality gates — no review, no scoring, no learning
• Use different approaches on every run — inconsistent results

Traditional frameworks try to fix this with prose in .md files ("load the contract before any tool call"). But agents routinely ignore prose because there's no enforcement — it's a suggestion, not a requirement.

The Solution

opencode-kit replaces prose conventions with machine-readable enforcement:

The result: zero-touch agent workflow. Set a goal, and the system self-executes through Plan → Build → Review → Learn, pausing only when BLOCKED.

How It Works

As an OpenCode plugin, opencode-kit injects enforcement into every session globally via a 6-layer enforcement system:

1. Plugin bootstrap — every session auto-loads the orchestration contract before any work
2. Pre-flight gate — validates branch, contract state, and rule compliance. BLOCKs on CRITICAL violations. Includes state machine validation (transition legality, required fields)
3. Contract locking — prevents concurrent contract modifications via file-based locks (contract-lock.sh acquire/release)
4. Contract protocol — shared state machine (contract.json) tracks phase, decisions, scores, telemetry
5. Scoring pipeline — every subagent output scored via src/scoring-pipeline.sh. ≥70 PASS, 50-69 RETRY, <50 BLOCKED
6. Audit trail — JSONL compliance logging (audit-trail.sh) records every enforcement action, score, and phase transition for later analysis
7. ADR logging — every architectural decision recorded in decisions.adr_log[]
8. Extension model — project-specific skills in .opencode/skills/ override plugin defaults

The 8 Built-in Skills

Built for Cost-Efficient Models

opencode-kit was designed for teams using cost-optimized models (DeepSeek V4 Flash, Gemini Flash, GPT-4o Mini, etc.) who want to compete with premium models through process rigor, not raw intelligence. The scoring pipeline and pre-flight enforcement create a quality floor that cheap models can meet through architecture, not model power.

Platform Support

• macOS M-Series (Apple Silicon) — primary development target
• Linux (Ubuntu) — CI-verified via GitHub Actions
• Any OpenCode-compatible environment with lean-ctx, gitnexus, madar

(back to top)

Philosophy

Data-driven enforcement, not convention

Most agent frameworks say "please load the envelope first" in prose. Agents ignore prose. opencode-kit stores rules as JSON and validates them with shell scripts — the agent can't work around a failing preflight.sh.

Contract over envelope

The shared state is called a contract, not an envelope. A contract is legally binding — every agent agrees to its terms. Breaking the contract is a governance violation, not a suggestion.

Score or fail

Every subagent output is scored on a 0-100 scale:

• ≥70 → PASS, advance to next phase
• 50-69 → RETRY (up to 3 attempts)
• <50 → BLOCKED (escalate to user)

This creates a quality floor that cheap models can meet through architecture, not raw intelligence.

(back to top)

Getting Started

Prerequisites

• macOS on Apple Silicon (M1, M2, M3, or M4)
• Node.js ≥ 18 (for npx support)
• Git (for version control)
• OpenCode with the following MCPs configured:
  • lean-ctx (context persistence)
  • gitnexus (code intelligence)
  • madar (knowledge graph)
  • context7 (documentation lookup)
  • firecrawl (web scraping)
  • github (repository management)

# Verify prerequisites
node --version    # ≥ 18
git --version     # any recent version

Quick Start (5 minutes)

# 1. Clone this repo
git clone https://github.com/RizkiRachman/opencode-kit.git

# 2. Copy the env template
cp opencode-kit/.env.template my-project/.env
# Edit .env with your credentials

# 3. Copy the wrapper to your project
cp opencode-kit/opencode-run my-project/
chmod +x my-project/opencode-run

# 4. Launch opencode
cd my-project
./opencode-run

That's it. Everything loads automatically.

Architecture: How It Works as a Library

opencode-kit is designed as a common library — one plugin that provides everything to every project that uses it.

┌─────────────────────────────────────────────────────┐
│  @ikieaneh/opencode-kit (npm package)               │
│                                                     │
│  Provides:                                          │
│  ├─ opencode.json  → commands, agents, skills       │
│  ├─ .opencode/skills/ → orchestration workflows     │
│  ├─ .opencode/agents/ → agent definitions           │
│  └─ opencode-run   → launcher wrapper               │
└─────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────┐
│  Your Project                                       │
│                                                     │
│  Needs only:                                        │
│  └─ .env  → credentials (gitignored)                │
│                                                     │
│  Gets automatically:                                │
│  ├─ All commands (/opencode-kit:doctor, etc.)       │
│  ├─ All agents (orchestrator, planner, etc.)        │
│  ├─ All skills (orchestration-workflow, etc.)       │
│  └─ MCP config (lean-ctx, gitnexus, madar, context7, firecrawl, github)       │
└─────────────────────────────────────────────────────┘

Key principle: opencode.json is tracked in git with zero credentials. Secrets live only in .env. The wrapper injects them at runtime.

File ownership

How the wrapper works

./opencode-run
  │
  ├─ 1. Source .env → load credentials into shell
  ├─ 2. Validate env vars + binaries
  ├─ 3. Inject secrets into opencode.json (runtime patch)
  ├─ 4. Launch opencode
  └─ 5. On exit → restore original opencode.json

The wrapper ensures opencode.json stays clean in git while MCP servers get real credentials at runtime.

Documentation Guides

Installation

Option 1: Clone + use directly (recommended)

# Clone the library
git clone https://github.com/RizkiRachman/opencode-kit.git

# Copy what you need to your project
cp opencode-kit/opencode-run my-project/
cp opencode-kit/.env.template my-project/
chmod +x my-project/opencode-run

# Fill in credentials
cd my-project
$EDITOR .env

# Launch
./opencode-run

Everything loads automatically — commands, agents, skills, MCP config.

Option 2: Install as npm plugin

npm install @ikieaneh/opencode-kit

Add to your project's opencode.json:

{
  "plugin": [
    "@ikieaneh/opencode-kit",      ← MUST be first
    "other-plugins..."
  ]
}

Plugin ordering: opencode-kit MUST be first in the plugin array. Its system prompt transform is foundational — other plugins may add behavior, but opencode-kit enforces the workflow.

Option 3: Quick scaffold

npx opencode-kit init

This scaffolds the full framework into your current project directory.

Post-install verification

.opencode/src/verify.sh

Expected output:

✅ contract.json
✅ rules.json
✅ agents/orchestrator.md (has pre-flight gate)
✅ agents/planner.md (has pre-flight gate)
...
✅ All checks passed

(back to top)

Usage

1. Set a goal

Edit .opencode/orchestration/contract.json:

{
  "state": "INIT",
  "requirements": {
    "goal": "Add user authentication with JWT",
    "acceptance_criteria": [
      "Users can register with email + password",
      "Users can login and receive a JWT token",
      "Tokens expire after 24 hours"
    ],
    "constraints": ["No new dependencies", "Follow hexagonal architecture"]
  }
}

2. Start working

Every agent session automatically:

1. Loads the contract (BLOCKED if missing)
2. Validates branch (BLOCKED if on main)
3. Validates state (BLOCKED if wrong phase)
4. Checks rules (CRITICAL violations = BLOCK)

3. The workflow runs itself

INIT → PLAN → PLAN_SCORED → EXECUTE → EXECUTE_SCORED → REVIEW → REVIEW_SCORED → COMPLETE
                                        ↓
                                     BLOCKED ← user intervention → retry

Each phase transition requires a score ≥70 to proceed.

CLI Commands

Once installed, run these from the project root:

Slash Commands (TUI)

Use these directly in the opencode TUI with the opencode-kit: prefix:

All commands use lean-ctx ctx_shell internally (no bash permission required for agents).

(back to top)

Structure

opencode-kit/ (npm package)
├── opencode.json.template    # Framework config (no model/provider)
├── AGENTS.md                 # Agent instructions
├── contract.json             # Contract template (_meta.extends: null)
├── contract.schema.json      # Contract schema
├── superpowers-contract.json
├── agents/                   # 15 agent templates
├── skills/                   # 39 generic skills
├── rules/                    # 7 rule files
├── src/                      # 22 scripts (init, doctor, etc.)
├── docs/                     # Architecture docs
├── .github/workflows/        # CI/CD
└── package.json

What Projects Get (after init)

my-project/
├── opencode.json             # Kit merged (agents + commands + MCPs)
├── .opencode/
│   ├── agents/               # 15 agents
│   ├── skills/               # 39 skills
│   ├── rules/                # 4 rule files (_meta.extends: opencode-kit)
│   ├── orchestration/        # Contract (_meta.extends: opencode-kit)
│   └── src/                  # Scripts

(back to top)

The 6 Pillars

1. GitNexus — Code Intelligence

Rule: IMPACT_001 — CRITICAL. Agent MUST run impact analysis before editing any symbol.

# Before touching any code:
lean-ctx ctx_shell(command="gitnexus impact symbolName --direction upstream")
# If HIGH/CRITICAL risk → BLOCK, report to user

2. Madar — Knowledge Graph

Rule: Agents MUST explore unfamiliar code via graph queries, not linear file reads.

lean-ctx ctx_shell(command="madar pack '<task or question>' --task explain")     # Scoped subgraph exploration

3. Lean Ctx — Context Persistence

Rule: PERSIST_001 — HIGH. Contract MUST be persisted after every delegation/phase change.

lean-ctx ctx_knowledge remember key orchestration-contract value <updated JSON>

4. Workflow State — State Machine

Rule: STATE_001 — CRITICAL. Agents can only act in correct state.

{
  "transitions": [
    { "from": "INIT", "to": "PLAN" },
    { "from": "PLAN", "to": "PLAN_SCORED" },
    { "from": "PLAN_SCORED", "to": "EXECUTE", "require_score": 70 },
    ...
    { "from": "*", "to": "BLOCKED", "condition": "score < 50 OR attempts >= 3" }
  ]
}

5. ADR — Architecture Decision Records

Every decision is logged in contract.json.decisions.adr_log[] with structured format:

{
  "decisions": {
    "adr_log": [
      { "id": "ADR-001", "date": "2026-06-11", "title": "Orchestration framework",
        "context": "Agents bypassed envelope protocol", "decision": "Switch to contract + rules.json",
        "alternatives": ["Keep envelope", "Use script enforcement"],
        "consequences": "Stronger enforcement, more scaffolding on init" }
    ]
  }
}

6. Scoring — Quality Pipeline

After every subagent delegation, scoring runs automatically:

1. Tier 1 — Rule-based checks (schema valid, permissions OK, blast radius safe)
2. Tier 2 — LLM judge (fulfills requirements? follows governance? complete?)
3. Tier 3 — Combined verdict (PASS/RETRY/BLOCKED)

7. Inheritance — Extension Model

opencode-kit uses class inheritance — projects extend the base, not replace it.

// Project's contract.json
{
  "_meta": {
    "extends": "opencode-kit",
    "overrides": ["requirements.goal"],
    "appends": ["scope.included"]
  },
  "requirements": {
    "goal": "Project-specific goal (overrides base)"
  }
}

Merge Rules:

• Scalars: project overrides base
• Arrays: concatenated + deduplicated
• Objects: deep merged (project wins)
• Excludes: _meta.excludes removes inherited items

See docs/inheritance-model.md for full architecture.

(back to top)

Contributing

See CONTRIBUTING.md for full guidelines.

TL;DR: Fork → Feature branch → Commit → PR. Follow the 6-pillar architecture. All rules enforcements must be tested.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Known Limitations

• Plugin hook API: The experimental.chat.messages.transform hook is marked as experimental in the OpenCode plugin SDK. It may change in future versions. If it breaks, the plugin falls back to per-project agent .md files (.opencode/agents/*.md), which remain functional.
• Package name: Currently published as @ikieaneh/opencode-kit (scoped). Requires npm install @ikieaneh/opencode-kit.
• TUI plugin: @ikieaneh/opencode-kit/tui requires OpenCode with TUI support (version with TuiPluginApi). It registers commands in the Ctrl+P palette and as /-slash commands. Scripts are run synchronously via Node.js execSync — long-running scripts may block the UI temporarily.
• Contract auto-init: Requires a git repository. Non-git projects use absolute path as hash fallback.

Rizki Rachman — GitHub

Project Link: https://github.com/RizkiRachman/opencode-kit

(back to top)