JSPM – @ikieaneh/opencode-kit@0.5.1

Package Exports

@ikieaneh/opencode-kit

Readme

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)

Table of Contents

About The Project
Philosophy
Getting Started
- Prerequisites
- Installation
Usage
Structure
The 6 Pillars
Roadmap
Contributing
License
Contact

About The Project

opencode-kit is a portable orchestration framework for OpenCode-based AI agents. It solves one core problem:

Agents skip the workflow and jump straight to implementation.

Traditional agent frameworks use conventions (".md files say to load state first") but agents routinely bypass them because there's no enforcement. opencode-kit makes the workflow machine-enforced, not convention-based.

How it works (v0.4 — Plugin Mode)

With opencode-kit installed as an OpenCode plugin, enforcement is global. No per-project scaffolding needed.

Plugin injects enforcement — every session auto-loads the orchestration contract before any work
contract.json — shared state machine every agent MUST read/write (local or global)
rules.json — machine-readable rules with CRITICAL/HIGH severity
3 auto-registered skills — orchestration-template, scoring-pipeline, adr-generator
Config resolution — .opencode/ → ~/.config/opencode-kit/ → plugin defaults

Built for macOS M-Series

Developed and tested on Apple Silicon (M1/M2/M3/M4). All scripts use portable POSIX shell with zero Linux-specific dependencies.

(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)
- graphify (knowledge graph)

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

Installation

Option 1: Install as plugin (recommended)

Add to your project's opencode.json:

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

Then install:

npm install @ikieaneh/opencode-kit

The plugin auto-loads on next session. All 8 skills become available. The orchestration contract is injected into every session automatically.

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 2: Quick scaffold (pre-v0.4 style)

npx opencode-kit init

This scaffolds the full framework into your current project directory. Compatible with plugin mode — use both for maximum control.

Option 3: From source

git clone https://github.com/RizkiRachman/opencode-kit.git
cd your-project
/path/to/opencode-kit/src/init.sh

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:

Loads the contract (BLOCKED if missing)
Validates branch (BLOCKED if on main)
Validates state (BLOCKED if wrong phase)
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.

(back to top)

Structure

opencode-kit/
 ├── rules/
 │   ├── rules.json              ← Machine-enforceable rules (CRITICAL/HIGH/state machine)
 │   └── validation.sh           ← Validates agent actions against rules (future)
 ├── src/
 │   ├── init.sh                 ← Scaffold into target project
 │   ├── preflight.sh            ← Envelope load gate (zero deps, fails if rules violated)
 │   ├── postflight.sh           ← Auto-persist + scoring pipeline
 │   └── verify.sh               ← Installation health check
 ├── templates/
 │   ├── contract.json           ← Shared state contract (renamed from "envelope")
 │   ├── superpowers-contract.json
 │   └── agents/
 │       ├── orchestrator.md
 │       ├── planner.md
 │       ├── task-manager.md
 │       ├── code-reviewer.md
 │       ├── learner.md
 │       └── fixer.md
 ├── package.json                ← npm publish for `npx opencode-kit init`
 └── README.md                   ← You are here

(back to top)

The 6 Pillars

1. GitNexus — Code Intelligence

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

# Before touching any code:
gitnexus_impact({target: "symbolName", direction: "upstream"})
# If HIGH/CRITICAL risk → BLOCK, report to user

2. Graphify — Knowledge Graph

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

graphify query "<question>"     # 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:

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

(back to top)

Roadmap

v0.1 (current POC)

GitHub repo structure
contract.json — shared state machine
rules.json — 8 enforcement rules
preflight.sh — load contract, validate branch, check state
postflight.sh — persist contract, run scoring
init.sh — scaffold into target project
verify.sh — installation health check
6 agent .md templates with embedded pre-flight gates
npm package.json for npx opencode-kit init

v0.2 — Hardening ✅

Auto-detect MCP availability (lean-ctx, gitnexus, graphify)
rules/validation.sh — validate agent actions against rules
Test on clean macOS M-series machine (manual — see notes)
Edge cases: re-init over existing .opencode/ with --force + backup
ADR auto-generate on decision (src/adr.sh)

v0.3 — Production ✅

Cross-platform (Linux via src/platform.sh + $PYTHON_CMD)
GitHub Actions CI (ShellCheck + scaffold test + syntax check)
opencode-kit update — src/update.sh (pull latest from GitHub, preserve state)
Scoring Tier 2 — templates/judge-prompt.md + SCORE_002 rule
Telemetry — src/telemetry.sh (phases.jsonl, elapsed time, summary)

v0.4 — Plugin Architecture ✅

Plugin entry point (.opencode/plugins/opencode-kit.js)
3 auto-registered skills (orchestration-template, scoring-pipeline, adr-generator)
Global config resolution (local → ~/.config/opencode-kit/ → plugin defaults)
Plugin schema (templates/opencode-kit.schema.json)
Plugin-aware init.sh (detects plugin, skips redundant scaffolding)
Plugin metadata (.claude-plugin/plugin.json)

v0.5 — Gap Analysis ✅

5 new skills (qa-expert, system-analyst, token-optimize, verification-before-completion, learner)
Auto-init contract on first run
Contract uniqueness per project (hashed lean-ctx key)
Proper plugin logging
CLI version/help command
Logo placeholder
STATE.md auto-sync
Integration tests (7/7 passing)
CI integration test job

v0.6 — Polish ✅

README updated for @ikieaneh/opencode-kit plugin mode
Updated agent config schema (fallback_models, explorer, librarian, architect)
End-to-end tests (9 tests, plugin lifecycle + auto-init)
Quickstart example (docs/examples/QUICKSTART.md)
npm published as @ikieaneh/opencode-kit
CI: integration + e2e test jobs

Future

Web UI for contract overview (deferred — no current need)
Plugin hardening: experimental.chat.messages.transform API is marked experimental — monitor OpenCode updates

See the open issues for full list.

(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.
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)