@ikieaneh/opencode-kit 0.5.6 → 0.5.8

package/README.md

@@ -224,6 +224,25 @@ INIT → PLAN → PLAN_SCORED → EXECUTE → EXECUTE_SCORED → REVIEW → REVI
 
 Each phase transition requires a score ≥70 to proceed.
 
+### CLI Commands
+
+Once installed, run these from the project root:
+
+| Command | Purpose |
+|---------|---------|
+| `bash .opencode/src/status.sh` | Dashboard — contract state, telemetry, rules |
+| `bash .opencode/src/doctor.sh` | Diagnostics — MCPs, contract, git, persistence |
+| `bash .opencode/src/analytics.sh` | Telemetry aggregation — phase times, cost estimates |
+| `bash .opencode/src/diff.sh` [branch1] [branch2] | Compare contract state between branches |
+| `bash .opencode/src/adr.sh` | Record a new Architecture Decision Record |
+| `bash .opencode/src/telemetry.sh` | View telemetry details |
+| `bash .opencode/src/new-skill.sh` <name> | Scaffold a new skill SKILL.md |
+| `bash .opencode/rules/validation.sh` | Validate rules compliance |
+| `npx opencode-kit --version` | Print version |
+| `npx opencode-kit --help` | Print help |
+
+
+
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
 <!-- STRUCTURE -->

package/package.json

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

package/src/adr.sh

@@ -5,6 +5,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 CONTRACT_FILE=".opencode/orchestration/contract.json"
@@ -87,6 +88,7 @@ fi
 
 # --- Build ADR entry ---
 # --- Build ADR entry via heredoc to avoid nested quote issues ---
+# shellcheck disable=SC2001
 $PYTHON_CMD -c "
 import json, sys, os
 

package/src/analytics.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 TELEMETRY_DIR=".opencode/telemetry"

package/src/diff.sh

@@ -0,0 +1,95 @@
+#!/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)"

package/src/doctor.sh

@@ -5,6 +5,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 . "$SCRIPT_DIR/global-config.sh"
 

package/src/global-config.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 PLUGIN_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"

package/src/init.sh

@@ -6,6 +6,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 . "$SCRIPT_DIR/global-config.sh"
 KIT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -88,7 +89,7 @@ if [ -d ".opencode" ]; then
 fi
 
 # --- Scaffold directories ---
-mkdir -p .opencode/orchestration .opencode/rules .opencode/agents .opencode/src
+mkdir -p .opencode/orchestration .opencode/rules .opencode/agents .opencode/src .opencode/templates
 
 # --- Copy templates ---
 echo ""
@@ -154,6 +155,10 @@ if [ "$PLUGIN_MODE" = false ]; then
   chmod +x .opencode/src/analytics.sh
   echo "  ✅ analytics.sh (executable)"
 
+  cp "$KIT_DIR/src/diff.sh" .opencode/src/diff.sh
+  chmod +x .opencode/src/diff.sh
+  echo "  ✅ diff.sh (executable)"
+
   # --- Copy agent templates (pre-flight gates) ---
   for agent in orchestrator planner task-manager code-reviewer learner fixer; do
     if [ -f "$KIT_DIR/templates/agents/$agent.md" ]; then

package/src/postflight.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 CONTRACT_KEY="orchestration-contract"
@@ -12,6 +13,7 @@ STATE_FILE="STATE.md"
 TELEMETRY_DIR=".opencode/telemetry"
 START_TIME_FILE=".opencode/telemetry/.phase_start"
 STATE_BACKUP_DIR=".opencode/state"
+TEMPLATE_FILE=".opencode/templates/contract.json"
 
 mkdir -p "$TELEMETRY_DIR" "$STATE_BACKUP_DIR"
 
@@ -46,6 +48,46 @@ if [ -z "$CURRENT_CONTRACT" ]; then
   fi
 fi
 
+# --- Step 1b: Contract migration (auto-upgrade old schema) ---
+if [ -n "$CURRENT_CONTRACT" ] && [ -f "$TEMPLATE_FILE" ] && [ -n "$PYTHON_CMD" ]; then
+  MIGRATED=$($PYTHON_CMD -c "
+import json
+
+try:
+    contract = json.loads('''$CURRENT_CONTRACT''')
+    with open('$TEMPLATE_FILE') as f:
+        template = json.load(f)
+
+    # Check version
+    old_ver = contract.get('contract_version', '0.0.0')
+    new_ver = template.get('contract_version', '0.5.2')
+
+    if old_ver == new_ver and all(k in contract for k in ['state','requirements','governance','score']):
+        print('NO_MIGRATION')
+    else:
+        # Merge missing top-level fields from template
+        for key in template:
+            if key not in contract:
+                contract[key] = template[key]
+        # Merge governance.extension_skills if missing
+        if 'extension_skills' not in contract.get('governance', {}):
+            if 'governance' not in contract:
+                contract['governance'] = {}
+            contract['governance']['extension_skills'] = []
+        # Update version
+        contract['contract_version'] = new_ver
+        print(json.dumps(contract))
+except Exception as e:
+    print('MIGRATE_ERROR:'+str(e))
+" 2>/dev/null || echo "MIGRATE_ERROR")
+
+  if [ -n "$MIGRATED" ] && [ "$MIGRATED" != "NO_MIGRATION" ] && [ "$MIGRATED" != "MIGRATE_ERROR" ]; then
+    CURRENT_CONTRACT="$MIGRATED"
+    echo "$MIGRATED" > "$CONTRACT_FILE"
+    echo "  🔄 Contract migrated to v$(echo "$MIGRATED" | $PYTHON_CMD -c "import sys,json; print(json.load(sys.stdin).get('contract_version','?'))" 2>/dev/null)"
+  fi
+fi
+
 # --- Step 2: Persist (try lean-ctx first, fall back to file) ---
 PERSISTED=false
 if lean-ctx ctx_knowledge remember \

package/src/preflight.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 CONTRACT_KEY="orchestration-contract"

package/src/status.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 CONTRACT_FILE=".opencode/orchestration/contract.json"

package/src/telemetry.sh

@@ -4,6 +4,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 TELEMETRY_DIR=".opencode/telemetry"

package/src/update.sh

@@ -5,6 +5,7 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=./platform.sh
 . "$SCRIPT_DIR/platform.sh"
 
 RED='\033[0;31m'