@ikieaneh/opencode-kit 0.5.8 → 0.5.9

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-kit",
   "description": "Standardized orchestration framework — contract-based, rules-enforced, zero-touch agent workflow",
-  "version": "0.4.0",
+  "version": "0.5.8",
   "author": {
     "name": "Rizki Rachman",
     "url": "https://github.com/RizkiRachman"

package/.opencode/plugins/opencode-kit.js

@@ -184,7 +184,6 @@ export const OpencodeKitPlugin = async ({ client, directory }) => {
 
       // Register user project skills FIRST (higher priority)
       const userSkillsDir = path.join(projectDir, '.opencode/skills');
-      const userSkillsDir = path.join(projectDir, '.opencode/skills');
       if (fs.existsSync(userSkillsDir) && !config.skills.paths.includes(userSkillsDir)) {
         config.skills.paths.push(userSkillsDir);
         log('info', `Registered user skills: ${userSkillsDir}`);

package/README.md

@@ -59,25 +59,67 @@
 <!-- ABOUT THE PROJECT -->
 ## About The Project
 
-`opencode-kit` is a portable orchestration framework for OpenCode-based AI agents. It solves one core problem:
+`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.
 
-**Agents skip the workflow and jump straight to implementation.**
+### The Problem
 
-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.
+AI agents (Claude, Copilot, etc.) are powerful but **unpredictable**. When given a task, they often:
 
-### How it works (v0.4 — Plugin Mode)
+- 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
 
-With `opencode-kit` installed as an OpenCode plugin, enforcement is **global**. No per-project scaffolding needed.
+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.
 
-1. **Plugin injects enforcement** — every session auto-loads the orchestration contract before any work
-2. **`contract.json`** — shared state machine every agent MUST read/write (local or global)
-3. **`rules.json`** — machine-readable rules with CRITICAL/HIGH severity
-4. **3 auto-registered skills** — `orchestration-template`, `scoring-pipeline`, `adr-generator`
-5. **Config resolution** — `.opencode/` → `~/.config/opencode-kit/` → plugin defaults
+### The Solution
 
-### Built for macOS M-Series
+`opencode-kit` replaces prose conventions with **machine-readable enforcement**:
 
-Developed and tested on Apple Silicon (M1/M2/M3/M4). All scripts use portable POSIX shell with zero Linux-specific dependencies.
+| Instead of ... | opencode-kit uses ... |
+|:---------------|:----------------------|
+| "read the state file" | `contract.json` — a JSON state machine agents MUST read/write |
+| "follow the rules" | `rules.json` — CRITICAL rules BLOCK agents, HIGH rules FLAG them |
+| "check before editing" | `preflight.sh` — an enforcement gate that fails if rules aren't met |
+| "review your work" | **Scoring pipeline** — every output is scored (≥70 PASS, <50 BLOCK) |
+| "remember what you learned" | `postflight.sh` — auto-persists state + telemetry + lessons learned |
+
+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:
+
+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
+3. **Contract protocol** — shared state machine (`contract.json`) tracks phase, decisions, scores, telemetry
+4. **Scoring pipeline** — every subagent output scored. ≥70 PASS, 50-69 RETRY, <50 BLOCKED
+5. **ADR logging** — every architectural decision recorded in `decisions.adr_log[]`
+6. **Extension model** — project-specific skills in `.opencode/skills/` override plugin defaults
+
+### The 9 Built-in Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `orchestration-template` | Contract protocol, state machine, persistence rules |
+| `scoring-pipeline` | Tier 1 rule checks + Tier 2 LLM judge + verdict |
+| `adr-generator` | Architecture Decision Record format and auto-ID |
+| `qa-expert` | Test standards, edge cases, coverage goals |
+| `system-analyst` | Impact analysis, execution tracing, architecture checks |
+| `token-optimize` | Efficient reading, batching, and delegation |
+| `verification-before-completion` | Quality gates — formatting, compile, test, verify |
+| `learner` | Post-execution learning, memory persistence |
+| *(extensible)* | Create your own skills in `.opencode/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`, `graphify`
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
@@ -122,6 +164,17 @@ node --version    # ≥ 18
 git --version     # any recent version
 ```
 
+### Documentation Guides
+
+| Guide | Description |
+|-------|-------------|
+| [Contract Protocol](docs/guides/contract-protocol.md) | State machine, fields, resolution order |
+| [Scoring Pipeline](docs/guides/scoring-pipeline.md) | Tier 1 + Tier 2 + verdict |
+| [Troubleshooting](docs/guides/troubleshooting.md) | Common issues and solutions |
+| [Quickstart](docs/examples/QUICKSTART.md) | 6-step setup from scratch |
+| [Extension Skills](docs/examples/extension-skill-template.md) | Create project-specific skills |
+| [Model Configs](docs/examples/model-configs.md) | Provider configuration examples |
+
 ### Installation
 
 #### Option 1: Install as plugin (recommended)
@@ -252,24 +305,42 @@ Once installed, run these from the project root:
 opencode-kit/
  ├── rules/
  │   ├── rules.json              ← Machine-enforceable rules (CRITICAL/HIGH/state machine)
- │   └── validation.sh           ← Validates agent actions against rules (future)
+ │   └── validation.sh           ← Validates agent actions against rules
  ├── 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
+ │   ├── postflight.sh           ← Auto-persist + scoring pipeline + contract migration
+ │   ├── doctor.sh               ← Diagnostic command
+ │   ├── status.sh               ← Dashboard view
+ │   ├── diff.sh                 ← Compare contract across branches
+ │   ├── analytics.sh            ← Telemetry aggregation
+ │   ├── adr.sh                  ← ADR auto-generator
+ │   ├── telemetry.sh            ← Phase telemetry viewer
+ │   ├── new-skill.sh            ← Skill template generator
+ │   ├── update.sh               ← Pull latest from GitHub
+ │   ├── verify.sh               ← Installation health check
+ │   ├── platform.sh             ← Cross-platform detection
+ │   ├── global-config.sh        ← Config resolution chain
+ │   └── cli.js                  ← --version / --help
+ ├── skills/                     ← 9 auto-registered skills
  ├── 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
+ │   ├── contract.json           ← Shared state contract
+ │   ├── opencode-kit.schema.json ← Agent config schema
+ │   ├── judge-prompt.md          ← LLM judge prompt template
+ │   └── agents/                  ← 6 agent .md templates
+ ├── docs/
+ │   ├── guides/                  ← Usage guides (contract, scoring, troubleshooting)
+ │   ├── examples/                ← Quickstart, model configs, extension skills
+ │   └── plans/                   ← Implementation plans
+ ├── test/                       ← Integration + E2E tests (16 total)
+ ├── .github/workflows/          ← CI (ShellCheck + scaffold + tests)
+ ├── .opencode/plugins/          ← Plugin entry point
+ ├── .claude-plugin/             ← Plugin metadata
+ ├── package.json                ← npm publish
+ ├── CHANGELOG.md
+ ├── CONTRIBUTING.md
+ ├── RELEASE.md
+ └── ROADMAP.md
 ```
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>

package/docs/guides/contract-protocol.md

@@ -0,0 +1,67 @@
+# Contract Protocol
+
+The orchestrator contract (`contract.json`) is the single source of truth for every agent session.
+
+## What it does
+
+- Tracks **state** — what phase the workflow is in (INIT → PLAN → ... → COMPLETE)
+- Stores **requirements** — the goal, acceptance criteria, and constraints
+- Logs **decisions** — Architecture Decision Records (ADRs)
+- Records **scores** — quality metrics from the scoring pipeline
+- Captures **telemetry** — elapsed time, phases completed, agents used
+
+## State Machine
+
+```
+INIT → PLAN → PLAN_SCORED → EXECUTE → EXECUTE_SCORED → REVIEW → REVIEW_SCORED → COMPLETE
+                                                                                         ↘
+                                      BLOCKED (any phase) → user intervention → retry
+```
+
+**Transition rules:**
+- Each phase transition requires score ≥ 70
+- Score < 50 → BLOCKED
+- Max 3 retry attempts before escalation
+
+## Key Fields
+
+```json
+{
+  "state": "INIT",
+  "contract_version": "0.5.8",
+  "requirements": {
+    "goal": "What we're building",
+    "acceptance_criteria": ["testable condition 1"],
+    "constraints": ["must not..."]
+  },
+  "governance": {
+    "active_agent": "orchestrator",
+    "current_guidance": "Instructions for this session",
+    "extension_skills": ["java-conventions"],
+    "permissions": { "do": [], "dont": ["push to main"] }
+  },
+  "decisions": {
+    "adr_log": [
+      { "id": "ADR-001", "date": "2026-06-11", "title": "Use contract protocol", ... }
+    ]
+  },
+  "score": {
+    "combined": 85,
+    "verdict": "PASS"
+  },
+  "metrics": {
+    "phases_completed": ["INIT", "PLAN", "PLAN_SCORED"]
+  }
+}
+```
+
+## Resolution Order
+
+1. `.opencode/orchestration/contract.json` — project override
+2. `~/.config/opencode-kit/contract.json` — global defaults
+3. Plugin `templates/contract.json` — shipped defaults
+
+## CLI
+
+View contract state: `bash .opencode/src/status.sh`
+Compare across branches: `bash .opencode/src/diff.sh [branch1] [branch2]`

package/docs/guides/scoring-pipeline.md

@@ -0,0 +1,60 @@
+# Scoring Pipeline
+
+Every subagent output is scored before the next phase begins.
+
+## Tier 1 — Rule Checks
+
+Automatic checks run by the orchestrator. Start at 100, deduct per violation:
+
+| Check | Deduction |
+|-------|:---------:|
+| Schema valid (required fields present) | -15 |
+| Permissions violated | -40 |
+| Blast radius HIGH/CRITICAL | -40 |
+| Writing order wrong | -15 |
+| Fields missing | -15 |
+
+If subtotal < 70 → skip Tier 2, use subtotal as combined score.
+
+## Tier 2 — LLM Judge
+
+If Tier 1 score ≥ 70, the orchestrator runs a judge via `subtask()`.
+
+```json
+{
+  "score": 85,
+  "rationale": "All requirements met. Writing order correct.",
+  "missing_items": ["Test for null boundary case"]
+}
+```
+
+**Dimensions:**
+| Dimension | Max | What it evaluates |
+|-----------|:---:|-------------------|
+| Requirements | 40 | Does output satisfy goal + acceptance criteria? |
+| Governance | 30 | Follows rules.json + writing order? |
+| Completeness | 20 | All files created? Edge cases documented? |
+| Edge cases | 10 | Nulls, errors, boundaries covered? |
+
+## Tier 3 — Verdict
+
+| Combined Score | Verdict | Action |
+|:--------------:|:-------:|--------|
+| ≥ 70 | **PASS** | Advance to next phase |
+| 50–69 | **RETRY** | Increment retry count, re-delegate |
+| < 50 | **BLOCKED** | Escalate to user |
+
+## Configuration
+
+Thresholds and deductions are in `rules.json` → `scoring`:
+
+```json
+{
+  "scoring": {
+    "tier1": { "schema_valid_deduction": 15, ... },
+    "thresholds": { "pass": 70, "retry": 50, "max_attempts": 3 }
+  }
+}
+```
+
+Projects can override rule severity via `contract.json` → `validation.rule_overrides`.

package/docs/guides/troubleshooting.md

@@ -0,0 +1,78 @@
+# Troubleshooting Guide
+
+## Common Issues
+
+### Plugin doesn't load
+
+**Symptom**: Skills not available, contract not injected.
+
+**Checks:**
+1. Is `@ikieaneh/opencode-kit` in `opencode.json` plugin array? Must be **first**.
+2. Is it installed? `ls node_modules/@ikieaneh/opencode-kit`
+3. Is the plugin array syntax correct? `"plugin": ["@ikieaneh/opencode-kit"]`
+
+### Agent jumps straight to implementation
+
+**Symptom**: Agent starts working without loading contract.
+
+**Fix:** The plugin's `messages.transform` hook injects the bootstrap. Make sure:
+1. Plugin is first in the array
+2. No other plugin overrides the same hook
+3. Run `bash .opencode/src/doctor.sh` to verify
+
+### Contract not found
+
+**Symptom**: "Contract not found" error from preflight.
+
+**Solution:**
+```sh
+bash .opencode/src/doctor.sh
+# Or manually:
+mkdir -p .opencode/orchestration
+cp node_modules/@ikieaneh/opencode-kit/templates/contract.json .opencode/orchestration/contract.json
+```
+
+### Score below threshold
+
+**Symptom**: Workflow keeps retrying or gets blocked.
+
+**Check:**
+- Tier 1 violations (blast radius, permissions)
+- Tier 2 judge feedback — read `judge.missing_items`
+- Retry count — max 3 attempts before BLOCKED
+
+### ShellCheck fails in CI
+
+**Symptom**: GitHub Actions ShellCheck job fails.
+
+**Fix:** Run locally:
+```sh
+shellcheck src/*.sh rules/*.sh
+```
+Look for SC1091 (source path) or SC2001 (sed style) — most are info-level.
+
+### Scaffold test fails in CI
+
+**Symptom**: init.sh exits with error.
+
+**Check:**
+- Are all `mkdir -p` paths created before `cp`?
+- Run locally: `cd /tmp && git init && bash /path/to/init.sh`
+
+### Custom skill not loading
+
+**Symptom**: Skill referenced in opencode.json not available.
+
+**Solution:**
+1. Place skill at `.opencode/skills/<name>/SKILL.md`
+2. Verify frontmatter has `description:` field
+3. Verify SKILL.md starts with `---` (YAML frontmatter)
+4. Run `bash .opencode/src/doctor.sh` to verify
+
+## Diagnostics
+
+```sh
+bash .opencode/src/doctor.sh       # Full health check
+bash .opencode/src/status.sh       # Dashboard view
+bash .opencode/src/analytics.sh    # Telemetry analysis
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikieaneh/opencode-kit",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "Standardized OpenCode orchestration framework — contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
   "license": "MIT",
   "author": "RizkiRachman",

package/rules/rules.json

@@ -88,7 +88,7 @@
     },
     {
       "id": "WRITE_001",
-      "severity": "CRITICAL",
+      "severity": "HIGH",
       "description": "Agent MUST follow writing order: Port → Service → Mapper → Adapter → Constants → Events → Tests",
       "condition": "writing_order_violation",
       "action": "FLAG",

package/src/adr.sh

@@ -86,31 +86,42 @@ if [ -n "$DUP" ]; then
   exit 0
 fi
 
-# --- Build ADR entry ---
-# --- Build ADR entry via heredoc to avoid nested quote issues ---
-# shellcheck disable=SC2001
+# --- Build ADR entry via temp JSON file (avoids shell injection) ---
+# Write ADR fields to temp file to avoid shell interpolation into Python
+ADR_DATA=$(mktemp /tmp/opencode-adr-data-XXXXX.json)
+cat > "$ADR_DATA" << ADRDATA
+{
+  "title": "$TITLE",
+  "context": "$CONTEXT",
+  "decision": "$DECISION",
+  "alternatives": "$ALTERNATIVES",
+  "consequences": "$CONSEQUENCES"
+}
+ADRDATA
+
 $PYTHON_CMD -c "
-import json, sys, os
+import json
 
-title = '$TITLE'
-date_val = '$(date +%Y-%m-%d)'
-next_id = '$NEXT_ID'
+with open('$ADR_DATA') as f:
+    data = json.load(f)
 
 entry = {
-  'id': next_id,
-  'date': date_val,
-  'title': title,
-  'context': '''$(echo "$CONTEXT" | sed "s/'/\\\\'/g")''',
-  'decision': '''$(echo "$DECISION" | sed "s/'/\\\\'/g")''',
-  'alternatives': '''$(echo "$ALTERNATIVES" | sed "s/'/\\\\'/g")''',
-  'consequences': '''$(echo "$CONSEQUENCES" | sed "s/'/\\\\'/g")'''
+  'id': '$NEXT_ID',
+  'date': '$(date +%Y-%m-%d)',
+  'title': data['title'],
+  'context': data['context'],
+  'decision': data['decision'],
+  'alternatives': data['alternatives'],
+  'consequences': data['consequences']
 }
 
 with open('/tmp/opencode-adr-entry.json', 'w') as f:
-  json.dump(entry, f, indent=2)
+    json.dump(entry, f, indent=2)
 print('Entry written')
 "
 
+rm -f "$ADR_DATA"
+
 # --- Inject into contract.json ---
 $PYTHON_CMD -c "
 import json

package/src/analytics.sh

@@ -69,7 +69,7 @@ for p in phases:
     frm = p.get('from', '?')
     to = p.get('to', '?')
     ms = p.get('elapsed_ms', 0)
-    bar = '█' * max(1, int(ms / max(1, total_ms) * 30))
+    bar = '#' * max(1, int(ms / max(1, total_ms) * 30))
     print(f'    {frm:16s} → {to:16s}  {ms/1000:6.1f}s  {bar}')
 
 # Cost estimate (rough: ~$0.15/1M tokens, ~1000 tok/s)

package/src/diff.sh

@@ -65,7 +65,7 @@ b = get_state('''$CONTRACT_B''') if '''$CONTRACT_B''' else None
 
 if a and b:
     print(f'  Field                   $BRANCH_A          $BRANCH_B')
-    print(f'  {"─"*50}')
+    print(f'  {"-"*50}')
     for field in ['state', 'goal', 'score', 'version']:
         va = str(a.get(field, '?'))[:20]
         vb = str(b.get(field, '?'))[:20]

package/src/init.sh

@@ -180,9 +180,9 @@ echo ""
 echo "[opencode-kit] Running verification..."
 if "$KIT_DIR/src/verify.sh"; then
   echo ""
-  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-  echo -e "${GREEN}  ✅ opencode-kit v0.5.0 initialized${NC}"
-  echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+  echo -e "${GREEN}========================================${NC}"
+  echo -e "${GREEN}  ✅ opencode-kit initialized (version: $(cat "$KIT_DIR/package.json" | grep '"version"' | head -1 | cut -d'"' -f4))${NC}"
+  echo -e "${GREEN}========================================${NC}"
   echo ""
   echo "  Next steps:"
   echo "  1. Set GOAL & SCOPE in .opencode/orchestration/contract.json"

package/src/status.sh

@@ -19,9 +19,9 @@ BOLD='\033[1m'
 NC='\033[0m'
 
 echo ""
-echo -e "${CYAN}${BOLD}╔══════════════════════════════════════════╗${NC}"
-echo -e "${CYAN}${BOLD}║        opencode-kit Dashboard            ║${NC}"
-echo -e "${CYAN}${BOLD}╚══════════════════════════════════════════╝${NC}"
+echo -e "${CYAN}${BOLD}##══════════════════════════════════════════╗${NC}"
+echo -e "${CYAN}${BOLD}#        opencode-kit Dashboard            #${NC}"
+echo -e "${CYAN}${BOLD}##══════════════════════════════════════════╝${NC}"
 echo ""
 
 # === Contract State ===
@@ -94,10 +94,8 @@ with open('$RULES_FILE') as f:
 rules = r.get('rules', [])
 critical = [x for x in rules if x.get('severity') == 'CRITICAL']
 high = [x for x in rules if x.get('severity') == 'HIGH']
-required_mcps = list(r.get('required_mcps', {}).keys())
-required_mcps = [m for m in required_mcps if m != 'description']
-mcps = list(r.get('required_mcps', {}).keys())
-mcps = [m for m in mcps if m != 'description']
+    mcps = list(r.get('required_mcps', {}).keys())
+    mcps = [m for m in mcps if m != 'description']
 print(f'  {len(critical)} CRITICAL rules, {len(high)} HIGH rules')
 if mcps:
     print(f'  Required MCPs: {\", \".join(mcps)}')

package/src/telemetry.sh

@@ -37,7 +37,7 @@ case "$MODE" in
         FROM=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('from','?'))" 2>/dev/null)
         TO=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('to','?'))" 2>/dev/null)
         MS=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('elapsed_ms',0))" 2>/dev/null)
-        printf "  %-20s → %-20s  %5.1fs\n" "$FROM" "$TO" "$(echo "scale=1; $MS/1000" | bc 2>/dev/null || echo "$((MS/1000)).$((MS%1000/100))")"
+        printf "  %-20s → %-20s  %5.1fs\n" "$FROM" "$TO" "$($PYTHON_CMD -c "print($MS/1000)" 2>/dev/null || echo "0.0")"
       done
     else
       echo -e "${YELLOW}No phase data yet.${NC}"

package/templates/contract.json

@@ -68,7 +68,7 @@
     "rules": { "pass": 0, "fail": 0, "deduction": 0, "subtotal": 0 },
     "judge": { "score": 0, "rationale": "", "missing_items": [] },
     "combined": 0,
-    "verdict": "PENDING"
+    "verdict": "INIT"
   },
   "retry": {
     "current_phase": null,