@ikieaneh/opencode-kit 0.6.1 → 0.6.3

package/docs/guides/contract-protocol.md

@@ -1,67 +0,0 @@
-# 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

@@ -1,60 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# 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/docs/images/logo.svg

@@ -1,9 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80" fill="none">
-  <rect width="80" height="80" rx="16" fill="#1a1a2e"/>
-  <path d="M20 25h40v30H20z" stroke="#e94560" stroke-width="2" fill="none"/>
-  <path d="M20 40h40" stroke="#e94560" stroke-width="2"/>
-  <circle cx="30" cy="35" r="3" fill="#0f3460"/>
-  <circle cx="50" cy="35" r="3" fill="#0f3460"/>
-  <path d="M25 48l10-10M45 48l10-10" stroke="#16213e" stroke-width="2"/>
-  <text x="40" y="62" text-anchor="middle" font-size="8" fill="#e94560" font-family="monospace">KIT</text>
-</svg>

package/docs/plans/2026-06-11-plugin-architecture.md

@@ -1,55 +0,0 @@
-# Plugin Architecture — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
-
-**Goal:** Convert opencode-kit from a per-project scaffold to a global OpenCode plugin with local-override config
-
-**Architecture:** Pure JS plugin (superpowers pattern) using `@opencode-ai/plugin` SDK. Global config at `~/.config/opencode-kit/`, project override at `.opencode/`. Plugin registers skills + system prompt transform.
-
-**Tech Stack:** Node.js, @opencode-ai/plugin SDK, shell scripts
-
----
-
-### Task 1: Plugin Entry Point
-
-**Files:**
-- Create: `.opencode/plugins/opencode-kit.js` — main plugin JS
-- Create: `.claude-plugin/plugin.json` — metadata
-- Modify: `package.json` — add plugin entry, `@opencode-ai/plugin` dependency
-
-- [ ] Create `.opencode/plugins/opencode-kit.js` — system prompt transform hook that injects contract loading + preflight
-- [ ] Create `.claude-plugin/plugin.json` — name, description, version, author
-- [ ] Update `package.json` — `"main": ".opencode/plugins/opencode-kit.js"`, add `@opencode-ai/plugin` dep
-
-### Task 2: Global Config Resolution
-
-**Files:**
-- Create: `src/global-config.sh` — resolve config from local → global → plugin default
-
-- [ ] Write resolution chain: `.opencode/` → `~/.config/opencode-kit/` → plugin `templates/`
-- [ ] Add `init-global` command to copy plugin defaults to `~/.config/opencode-kit/`
-
-### Task 3: Plugin Schema
-
-**Files:**
-- Create: `templates/opencode-kit.schema.json` — validate opencode.json agent config
-
-- [ ] Schema defines default agents (orchestrator, planner, task-manager, etc.)
-- [ ] Documents plugin ordering requirement (must be first in plugin array)
-
-### Task 4: Init Coexistence
-
-**Files:**
-- Modify: `src/init.sh` — detect plugin, skip plugin-handled tasks
-
-- [ ] If plugin detected (via `.opencode/plugins/opencode-kit.js`), skip skill/agent scaffolding
-- [ ] Only scaffold per-project data: contract.json goal/scope, STATE.md, PROJECT.md
-
-### Task 5: Documentation
-
-**Files:**
-- Modify: `README.md` — plugin installation, ordering requirement
-- Modify: `CHANGELOG.md`
-
-- [ ] Add "Install as plugin" section to README
-- [ ] Document global vs local resolution

package/src/adr.sh

@@ -1,152 +0,0 @@
-#!/usr/bin/env bash
-# opencode-kit ADR — auto-generate Architecture Decision Record
-# Usage: bash src/adr.sh <title>
-# Then enter context, decision, alternatives, consequences interactively.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=./platform.sh
-. "$SCRIPT_DIR/platform.sh"
-
-CONTRACT_FILE=".opencode/orchestration/contract.json"
-
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-CYAN='\033[0;36m'
-NC='\033[0m'
-
-# --- Check contract exists ---
-if [ ! -f "$CONTRACT_FILE" ]; then
-  echo -e "${RED}❌ $CONTRACT_FILE not found. Run 'opencode-kit init' first.${NC}"
-  exit 1
-fi
-
-# --- Parse args ---
-TITLE=""
-CONTEXT=""
-DECISION=""
-ALTERNATIVES=""
-CONSEQUENCES=""
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --title|-t) TITLE="$2"; shift 2 ;;
-    --context|-c) CONTEXT="$2"; shift 2 ;;
-    --decision|-d) DECISION="$2"; shift 2 ;;
-    --alternatives|-a) ALTERNATIVES="$2"; shift 2 ;;
-    --consequences|-q) CONSEQUENCES="$2"; shift 2 ;;
-    *) TITLE="$1"; shift ;;
-  esac
-done
-
-# --- Interactive mode if no title provided ---
-if [ -z "$TITLE" ]; then
-  echo -e "${CYAN}[opencode-kit ADR]${NC} Interactive mode"
-  echo ""
-  read -r -p "Title: " TITLE
-  [ -z "$TITLE" ] && { echo -e "${RED}Title required${NC}"; exit 1; }
-  read -r -p "Context (why this decision?): " CONTEXT
-  read -r -p "Decision (what we decided): " DECISION
-  read -r -p "Alternatives considered: " ALTERNATIVES
-  read -r -p "Consequences (positive + negative): " CONSEQUENCES
-fi
-
-# --- Validate required fields ---
-if [ -z "$TITLE" ]; then
-  echo -e "${RED}❌ Title is required. Use: bash src/adr.sh \"Your Decision Title\"${NC}"
-  exit 1
-fi
-
-# --- Compute next ADR ID ---
-NEXT_ID=$($PYTHON_CMD -c "
-import json
-with open('$CONTRACT_FILE') as f: d = json.load(f)
-log = d.get('decisions', {}).get('adr_log', [])
-if not log:
-  print('ADR-001')
-else:
-  last = max(int(entry.get('id','ADR-000').replace('ADR-','')) for entry in log)
-  print(f'ADR-{last+1:03d}')
-")
-
-# --- Check for duplicate title ---
-DUP=$($PYTHON_CMD -c "
-import json
-with open('$CONTRACT_FILE') as f: d = json.load(f)
-log = d.get('decisions', {}).get('adr_log', [])
-for entry in log:
-  if entry.get('title','').lower().strip() == '$TITLE'.lower().strip():
-    print(entry.get('id',''))
-    break
-" 2>/dev/null)
-if [ -n "$DUP" ]; then
-  echo -e "${YELLOW}⚠️  Duplicate title found: $DUP — '$TITLE'${NC}"
-  echo "  Skipping. Update existing ADR instead."
-  exit 0
-fi
-
-# --- 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
-
-with open('$ADR_DATA') as f:
-    data = json.load(f)
-
-entry = {
-  '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)
-print('Entry written')
-"
-
-rm -f "$ADR_DATA"
-
-# --- Inject into contract.json ---
-$PYTHON_CMD -c "
-import json
-
-with open('$CONTRACT_FILE') as f:
-  contract = json.load(f)
-
-with open('/tmp/opencode-adr-entry.json') as f:
-  entry = json.load(f)
-
-if 'decisions' not in contract:
-  contract['decisions'] = {}
-if 'adr_log' not in contract['decisions']:
-  contract['decisions']['adr_log'] = []
-
-contract['decisions']['adr_log'].append(entry)
-
-with open('$CONTRACT_FILE', 'w') as f:
-  json.dump(contract, f, indent=2)
-
-print(json.dumps(entry, indent=2))
-"
-
-echo ""
-echo -e "${GREEN}[opencode-kit] ✅ ADR recorded: $NEXT_ID${NC}"
-echo "  Title:        $TITLE"
-echo "  File:         $CONTRACT_FILE"
-echo "  Next:         Persist via: lean-ctx ctx_knowledge remember key orchestration-contract value \"\$(cat $CONTRACT_FILE)\""

package/src/analytics.sh

@@ -1,80 +0,0 @@
-#!/usr/bin/env bash
-# opencode-kit analytics — aggregate telemetry across phases
-# Usage: bash src/analytics.sh [--json]
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=./platform.sh
-. "$SCRIPT_DIR/platform.sh"
-
-TELEMETRY_DIR=".opencode/telemetry"
-CONTRACT_FILE=".opencode/orchestration/contract.json"
-
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-CYAN='\033[0;36m'
-NC='\033[0m'
-
-MODE="${1:-table}"
-
-echo -e "${CYAN}📊 opencode-kit Analytics${NC}"
-echo ""
-
-if [ ! -f "$TELEMETRY_DIR/phases.jsonl" ] || [ ! -f "$TELEMETRY_DIR/summary.json" ]; then
-  echo -e "${YELLOW}No telemetry data yet. Run a few phases first.${NC}"
-  exit 0
-fi
-
-if [ -z "$PYTHON_CMD" ]; then
-  echo -e "${RED}Python required for analytics.${NC}"
-  exit 1
-fi
-
-$PYTHON_CMD -c "
-import json
-
-# Load phases
-phases = []
-try:
-    with open('$TELEMETRY_DIR/phases.jsonl') as f:
-        for line in f:
-            line = line.strip()
-            if line:
-                phases.append(json.loads(line))
-except:
-    pass
-
-# Load summary
-summary = {}
-try:
-    with open('$TELEMETRY_DIR/summary.json') as f:
-        summary = json.load(f)
-except:
-    pass
-
-if not phases:
-    print('  No phases recorded')
-    exit(0)
-
-total_ms = sum(p.get('elapsed_ms', 0) for p in phases)
-avg_ms = total_ms / len(phases) if phases else 0
-
-print(f'  Total sessions:  {len(phases)}')
-print(f'  Total time:      {total_ms/1000:.1f}s ({total_ms/60000:.1f}m)')
-print(f'  Avg per phase:   {avg_ms/1000:.1f}s')
-print('')
-print(f'  Phase Breakdown:')
-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))
-    print(f'    {frm:16s} → {to:16s}  {ms/1000:6.1f}s  {bar}')
-
-# Cost estimate (rough: ~$0.15/1M tokens, ~1000 tok/s)
-est_tokens = int(total_ms / 1000 * 1000)  # rough: 1000 tok/sec
-est_cost = est_tokens / 1_000_000 * 0.15
-print(f'')
-print(f'  Estimated tokens: {est_tokens:,} (~{est_cost:.4f} USD at $0.15/1M tok)')
-" 2>/dev/null || echo "  ⚠️  Analytics failed"

package/src/diff.sh

@@ -1,95 +0,0 @@
-#!/usr/bin/env bash
-# opencode-kit diff — compare contract state between branches
-# Usage: bash src/diff.sh [branch1] [branch2]
-#   Default: compares current branch vs main
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=./platform.sh
-. "$SCRIPT_DIR/platform.sh"
-
-CONTRACT_FILE=".opencode/orchestration/contract.json"
-BRANCH_A="${1:-main}"
-BRANCH_B="${2:-HEAD}"
-
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-CYAN='\033[0;36m'
-NC='\033[0m'
-
-echo -e "${CYAN}📋 opencode-kit diff: $BRANCH_A ↔ $BRANCH_B${NC}"
-echo ""
-
-# Extract contract from a git ref
-get_contract_state() {
-  local branch="$1"
-  local content
-  content=$(git show "$branch:$CONTRACT_FILE" 2>/dev/null || echo "")
-  if [ -z "$content" ]; then
-    echo ""
-    return 1
-  fi
-  echo "$content"
-}
-
-CONTRACT_A=$(get_contract_state "$BRANCH_A")
-CONTRACT_B=$(get_contract_state "$BRANCH_B")
-
-if [ -z "$CONTRACT_A" ] && [ -z "$CONTRACT_B" ]; then
-  echo -e "${YELLOW}No contract found in either branch.${NC}"
-  exit 0
-fi
-
-# Show state diff
-if [ -n "$PYTHON_CMD" ]; then
-  $PYTHON_CMD -c "
-import json, sys
-
-def get_state(c):
-    try:
-        d = json.loads(c)
-        return {
-            'state': d.get('state', '?'),
-            'goal': (d.get('requirements', {}) or {}).get('goal', '?'),
-            'score': (d.get('score', {}) or {}).get('combined', '?'),
-            'phases': (d.get('metrics', {}) or {}).get('phases_completed', []),
-            'adrs': len((d.get('decisions', {}) or {}).get('adr_log', [])),
-            'version': d.get('contract_version', '?')
-        }
-    except:
-        return None
-
-a = get_state('''$CONTRACT_A''') if '''$CONTRACT_A''' else None
-b = get_state('''$CONTRACT_B''') if '''$CONTRACT_B''' else None
-
-if a and b:
-    print(f'  Field                   $BRANCH_A          $BRANCH_B')
-    print(f'  {"-"*50}')
-    for field in ['state', 'goal', 'score', 'version']:
-        va = str(a.get(field, '?'))[:20]
-        vb = str(b.get(field, '?'))[:20]
-        marker = ' ←→' if va != vb else '   '
-        print(f'  {field:20s}  {va:20s} {marker} {vb:20s}')
-    print(f'  phases                 {len(a.get(\"phases\",[])):3d} completed     {len(b.get(\"phases\",[])):3d} completed')
-    print(f'  ADRs                   {a.get(\"adrs\",0):3d} recorded      {b.get(\"adrs\",0):3d} recorded')
-elif a and not b:
-    print(f'  Contract exists in $BRANCH_A but NOT in $BRANCH_B')
-    print(f'  State: {a.get(\"state\",\"?\")}')
-elif b and not a:
-    print(f'  Contract exists in $BRANCH_B but NOT in $BRANCH_A')
-    print(f'  State: {b.get(\"state\",\"?\")}')
-" 2>/dev/null || echo -e "${YELLOW}Could not parse contract JSON${NC}"
-fi
-
-# Raw git diff
-echo ""
-echo -e "${CYAN}Raw diff:${NC}"
-if git diff "$BRANCH_A" "$BRANCH_B" -- "$CONTRACT_FILE" 2>/dev/null | head -40; then
-  if ! git diff --exit-code "$BRANCH_A" "$BRANCH_B" -- "$CONTRACT_FILE" &>/dev/null; then
-    :
-  fi
-fi
-echo ""
-echo -e "Run: ${GREEN}bash .opencode/src/diff.sh${NC} (default: main vs HEAD)"
-echo -e "     ${GREEN}bash .opencode/src/diff.sh staging feature-x${NC} (custom branches)"