About

AI coding agents are inconsistent. Without structure, they skip conventions, ignore shared state, and bypass quality gates.

opencode-kit is an OpenCode plugin that replaces prose conventions with machine-readable enforcement. Install once — every project session gets agents, skills, MCPs, slash commands, and contract-based orchestration automatically.

Built with Node.js, OpenCode, lean-ctx, graphify, and GitNexus.

Getting Started

Prerequisites

• Node.js >= 18
• Git
• OpenCode installed and configured

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

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

Add the snippet above to your project's opencode.json. Open your project in OpenCode — the plugin handles everything else.

Usage

After installation, verify everything loaded:

npx opencode-kit doctor

Expected output:

✅ contract.json
✅ rules.json
✅ 18 agents provisioned
✅ 40 skills provisioned
✅ 7 rule files loaded
✅ All checks passed

Slash Commands (18)

| Category | Commands | |:---------|:---------| | Health & Status | doctor, status, preflight, verify | | Analytics & Scoring | analytics, score | | Contract | contract-lint, diff, lock | | Checkpoints | checkpoint, checkpoint-save | | Project Tools | audit, init, update, update-version, version | | ADRs | adr | | Logs | logs |

All commands are prefixed with /opencode-kit: — e.g., /opencode-kit:doctor.

What You Get

Agents (18)

| Agent | Purpose | |:------|:--------| | orchestrator | Delegates, validates, drives state machine | | planner | Analyzes requests, traces impact, produces plans | | task-manager | Breaks plans into tasks, implements each step | | code-reviewer | Read-only code review — quality, security, performance | | explorer | Fast codebase search across the entire project | | librarian | Authoritative source for library docs and API references | | architect | Strategic technical advisor for high-stakes decisions | | fixer | Fast implementation for well-defined bounded tasks | | learner | Post-execution learning — extracts lessons, persists knowledge | | observer | System state monitor — read-only | | database-specialist | Schema design, queries, migrations, optimization | | devops-agent | CI/CD, deployment, infrastructure, automation | | documentation-agent | Maintains README, API docs, inline documentation | | security-reviewer | Vulnerability assessment and security best practices | | testing-specialist | Unit tests, integration tests, test strategies | | council | Multi-LLM consensus engine for high-stakes decisions | | designer | UI/UX design, review, and implementation | | oracle | Strategic technical advisor for architecture and debugging |

Skills (40)

| Category | Skills | |:---------|:-------| | Orchestration | orchestration-template, orchestration-workflow, dispatching-parallel-agents, executing-plans, subagent-driven-dev | | Quality | test-driven-dev, systematic-debugging, verification-before-completion, quality-checks, receiving-code-review, requesting-code-review, simplify | | Planning | writing-plans, brainstorming, using-git-worktrees | | Web Research | firecrawl-search, firecrawl-scrape, firecrawl-deep-research, firecrawl-knowledge-base, firecrawl-knowledge-ingest, firecrawl-map, firecrawl-qa, firecrawl-workflows | | Code Intelligence | gitnexus-exploring, codemap, token-optimize | | Domain | database-design, sql-optimization, ci-cd, deployment, infrastructure, security-audit, testing-strategies | | Learning | learner, using-superpowers, system-analyst, scoring-pipeline, qa-expert | | Content | humanizer | | Workflow | adr-generator |

MCPs (5)

| MCP | Purpose | |:----|:--------| | lean-ctx | Token-compressed file/shell gateway (mandatory) | | gitnexus | Code intelligence and impact analysis | | context7 | Library documentation lookup | | firecrawl | Web search, scraping, and interaction | | github | GitHub API access |

Plus graphify (CLI tool, not MCP) for codebase graph intelligence.

.opencode-kit/ Storage

The plugin provisions agent templates, skills, rules, and contract files into .opencode-kit/ — all auto-managed, no manual setup needed.

Contract Enforcement

• 7-layer contract enforcement — Machine-readable workflow rules in contract.json that agents cannot bypass. Orchestrator forced to delegate (exploration→@explorer, implementation→@fixer), scoring thresholds (≥70 PASS), mandatory checkpoints + audit trail at every step.

Auto-Update & Version Staleness

The plugin self-updates on every session start. Before loading, autoUpdate checks the npm registry for the latest version and installs it automatically if a newer version is available.

To prevent stale cached versions from persisting across sessions, autoUpdate clears these cache paths:

| Cache Path | Purpose | Cleared? | |:-----------|:--------|:---------| | ~/.cache/opencode/packages/@ikieaneh/ | Extracted plugin cache | ✅ | | ~/.cache/opencode/pkgs/ | Transient npm fetch cache | ✅ | | ~/.cache/opencode/bun.lock | Bun lockfile | ✅ | | npm cache clean @ikieaneh/opencode-kit | npm content-addressable cache | ✅ | | /opt/homebrew/.../node_modules/@ikieaneh/opencode-kit | Brew-installed global module | ✅ | | npm root -g/@ikieaneh/opencode-kit | npm global install (dynamic path) | ✅ |

Manual cleanup (nuclear option): If a project's .opencode/ directory is stale or corrupted, remove it and restart:

cd /path/to/stale-project
rm -rf .opencode/

The plugin re-provisions all files on the next session open.

Architecture

Inheritance Model

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

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

| Layer | Extend Via | Example | |:------|:-----------|:--------| | Contract | _meta.overrides / _meta.appends | Override goal, append scope | | Agents | _meta.append_skills | Add project-specific skills | | Rules | _meta.appends: ["rules"] | Add custom rules | | Skills | Add to .opencode/skills/ | Create my-api-client/SKILL.md |

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.

Roadmap

• [x] Auto-provision agents, skills, rules
• [x] Auto-config opencode.json
• [x] ADR reports and session summaries
• [x] Task complexity detection
• [x] Graphify integration
• [x] MCP availability checks
• [x] Inheritance model with overrides and appends
• [x] Scoring pipeline (PASS/RETRY/BLOCKED)
• [ ] Multi-language agent support
• [ ] Web-based dashboard
• [ ] VS Code extension

See ROADMAP.md for full details.

Contributing

See CONTRIBUTING.md for full guidelines.

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

License

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

Contact

RizkiRachman — GitHub

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