[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![npm][npm-shield]][npm-url]
[![PRs Welcome][prs-shield]][prs-url]
[![CI][ci-shield]][ci-url]
Table of Contents
- About
-
Getting Started
- Usage
- What You Get
- Architecture
- Roadmap
- Contributing
- License
- Contact
---
## 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](https://nodejs.org/), [OpenCode](https://opencode.ai/), [lean-ctx](https://github.com/RizkiRachman/lean-ctx), [graphify](https://github.com/RizkiRachman/graphify), and [GitNexus](https://github.com/RizkiRachman/gitnexus).
(back to top)
## Getting Started
### Prerequisites
- **Node.js** >= 18
- **Git**
- **OpenCode** installed and configured
```sh
node --version # >= 18
git --version # any recent version
```
### Installation
**Step 1 — Install globally (one-time)**
```sh
npm install -g @ikieaneh/opencode-kit
```
**Step 2 — Add to your project**
```json
{
"plugin": ["@ikieaneh/opencode-kit"]
}
```
Add the snippet above to your project's `opencode.json`. Open your project in OpenCode — the plugin handles everything else.
(back to top)
## Usage
After installation, verify everything loaded:
```sh
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`.
(back to top)
## 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.
(back to top)
### 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:
```sh
cd /path/to/stale-project
rm -rf .opencode/
```
The plugin re-provisions all files on the next session open.
(back to top)
## Architecture
### Inheritance Model
opencode-kit uses class inheritance: projects extend the base, not replace it.
```json
{
"_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](docs/inheritance-model.md) for full architecture.
(back to top)
## 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](ROADMAP.md) for full details.
(back to top)
## Contributing
See [CONTRIBUTING.md](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
**RizkiRachman** — [GitHub](https://github.com/RizkiRachman)
Project Link: [https://github.com/RizkiRachman/opencode-kit](https://github.com/RizkiRachman/opencode-kit)
(back to top)
[contributors-shield]: https://img.shields.io/github/contributors/RizkiRachman/opencode-kit.svg?style=for-the-badge
[contributors-url]: https://github.com/RizkiRachman/opencode-kit/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/RizkiRachman/opencode-kit.svg?style=for-the-badge
[forks-url]: https://github.com/RizkiRachman/opencode-kit/network/members
[stars-shield]: https://img.shields.io/github/stars/RizkiRachman/opencode-kit.svg?style=for-the-badge
[stars-url]: https://github.com/RizkiRachman/opencode-kit/stargazers
[issues-shield]: https://img.shields.io/github/issues/RizkiRachman/opencode-kit.svg?style=for-the-badge
[issues-url]: https://github.com/RizkiRachman/opencode-kit/issues
[license-shield]: https://img.shields.io/github/license/RizkiRachman/opencode-kit.svg?style=for-the-badge
[license-url]: https://github.com/RizkiRachman/opencode-kit/blob/main/LICENSE
[npm-shield]: https://img.shields.io/npm/v/@ikieaneh/opencode-kit.svg?style=for-the-badge&logo=npm
[npm-url]: https://www.npmjs.com/package/@ikieaneh/opencode-kit
[prs-shield]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
[prs-url]: https://github.com/RizkiRachman/opencode-kit/pulls
[ci-shield]: https://github.com/rickyrijalul-opencode/opencode-kit/actions/workflows/validate.yml/badge.svg
[ci-url]: https://github.com/rickyrijalul-opencode/opencode-kit/actions/workflows/validate.yml
