JSPM

opencode-kit

Plugin that auto-provisions agents, skills, rules, and configs for OpenCode. Zero-config — just add the plugin.
Explore the docs »

Report Bug · Request Feature

npm: @ikieaneh/opencode-kit · Cross-platform — macOS, Linux, Windows

About

opencode-kit is an OpenCode plugin that auto-provisions a complete agent workflow framework. Install the plugin, and every session gets 15 agents, 39 skills, 7 rule files, 6 MCP configs, and 15 slash commands — automatically.

The Problem

AI coding agents are powerful but inconsistent. Without structure, they:

• Skip conventions and jump to implementation
• Ignore shared state — each session starts fresh
• Bypass quality gates — no review, no scoring, no learning
• Use different approaches every run

The Solution

opencode-kit replaces prose conventions with machine-readable enforcement. It injects a contract-based orchestration framework into every OpenCode session via a plugin hook — no manual setup required.

(back to top)

Getting Started

Prerequisites

• Node.js ≥ 18
• Git
• OpenCode installed
• MCP servers configured: lean-ctx, gitnexus, madar, context7, firecrawl, github

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

Installation

Step 1: Install globally (one-time)

npm install -g @ikieaneh/opencode-kit

Step 2: Add to your project

Create or edit opencode.json in your project root:

{
  "plugin": ["@ikieaneh/opencode-kit"]
}

That's it. On next session, the plugin auto-provisions everything:

• .opencode/agents/ — 15 agents
• .opencode/skills/ — 39 skills
• .opencode/rules/ — 7 rule files
• config.agent — 15 agent configs injected at runtime
• config.command — 15 slash commands
• config.mcp — 6 MCP servers
• config.permission — 18 permissions
• tui.json — TUI plugin auto-registered

Verification

After installation, verify everything loaded:

npx opencode-kit doctor

Expected output:

✅ contract.json
✅ rules.json
✅ 15 agents provisioned
✅ 39 skills provisioned
✅ 7 rule files loaded
✅ All checks passed

(back to top)

How It Works

Plugin Auto-Provision Flow

When OpenCode starts with @ikieaneh/opencode-kit in the plugin array, the plugin hook fires and:

1. Auto-provisions files from the package:
   • .opencode/agents/ — 15 agent templates
   • .opencode/skills/ — 39 skills
   • .opencode/rules/ — 7 rule files
   • .opencode/orchestration/contract.json
2. Auto-injects configs at runtime (no opencode.json edits needed):
   • 15 agent configs (skills + tools)
   • 15 slash command configs
   • 6 MCP server configs
   • 18 permission configs
3. Auto-registers @ikieaneh/opencode-kit/tui in tui.json for slash commands

No manual copying. No wrapper scripts. Just install and go.

What Projects Get

my-project/
├── .opencode/
│   ├── agents/       (auto-provisioned: 15 agents)
│   ├── skills/       (auto-provisioned: 39 skills)
│   ├── rules/        (auto-provisioned: 7 rule files)
│   ├── orchestration/ (auto-provisioned: contract.json)
│   └── plugins/      (plugin entry points)

Inheritance 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)

Structure

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

(back to top)

Enforcement System

1. Plugin Bootstrap

Every session auto-loads the orchestration contract before any work begins.

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 Protocol

Shared state machine (contract.json) tracks phase, decisions, scores, and telemetry. Every agent reads and writes to the contract.

4. Scoring Pipeline

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)

5. Audit Trail

JSONL compliance logging records every enforcement action, score, and phase transition for later analysis.

6. ADR Logging

Every architectural decision recorded in decisions.adr_log[] with structured format.

7. Extension Model

Project-specific skills in .opencode/skills/ override plugin defaults via _meta.extends.

(back to top)

Agents & Skills

15 Agents

39 Skills

Skills provide specialized instructions and workflows for specific tasks. Highlights include:

• orchestration-workflow — Contract protocol, state machine, persistence rules
• firecrawl-* — Web search, scraping, interaction, monitoring (15 skills)
• superpowers — brainstorming, TDD, debugging, code review, parallel agents, and more
• gitnexus-* — Code intelligence, impact analysis, debugging, refactoring
• quality-checks — Linting, formatting, static analysis
• testing-strategies — Test planning and coverage

Full list: see skills/ directory or load via the skill tool in OpenCode.

(back to top)

Slash Commands

All 15 commands available in the OpenCode TUI:

(back to top)

Known Limitations

• Plugin hook API: The experimental.chat.messages.transform hook is marked experimental in the OpenCode plugin SDK. If it breaks, the plugin falls back to per-project agent .md files, which remain functional.
• TUI plugin: @ikieaneh/opencode-kit/tui requires OpenCode with TUI support. Scripts run synchronously via 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.

(back to top)

Contributing

See CONTRIBUTING.md for full guidelines.

Fork → Feature branch → Commit → PR. Follow the enforcement architecture. All rule enforcements must be tested.

(back to top)

License

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

(back to top)

Contact

Rizki Rachman — GitHub

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

(back to top)