@ikieaneh/opencode-kit 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikieaneh/opencode-kit",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Standardized OpenCode orchestration framework — contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
   "license": "MIT",
   "author": "RizkiRachman",
@@ -16,12 +16,13 @@
   },
   "files": [
     ".opencode/plugins/",
-    ".claude-plugin/",
-    "src/",
-    "rules/",
     "templates/",
     "skills/",
-    "docs/"
+    "rules/",
+    "src/cli.js",
+    "src/init.sh",
+    "LICENSE",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -42,8 +43,9 @@
     "url": "git+https://github.com/RizkiRachman/opencode-kit.git"
   },
   "scripts": {
-    "lint": "eslint src/ test/",
-    "format": "prettier --check src/ test/"
+    "postinstall": "git config core.hooksPath .githooks 2>/dev/null || true",
+    "lint": "shellcheck src/*.sh rules/*.sh 2>/dev/null || true",
+    "format": "echo 'Formatting: not configured yet'"
   },
   "bugs": {
     "url": "https://github.com/RizkiRachman/opencode-kit/issues"

package/templates/opencode-kit.schema.json

@@ -3,6 +3,7 @@
   "title": "opencode-kit Plugin Config",
   "description": "Configuration schema for @ikieaneh/opencode-kit plugin. Add to your opencode.json to enable orchestration agents.",
   "type": "object",
+  "additionalProperties": false,
   "properties": {
     "plugin": {
       "type": "array",

package/templates/superpowers-contract.json

@@ -1,5 +1,6 @@
 {
   "version": "0.1.0",
+  "template_version": "0.6.2",
   "description": "Superpowers & MCP registry for opencode-kit",
   "plugins": ["superpowers"],
   "mcps": ["gitnexus", "graphify", "lean-ctx", "context7"],

package/.claude-plugin/plugin.json

@@ -1,23 +0,0 @@
-{
-  "name": "opencode-kit",
-  "description": "Standardized orchestration framework — contract-based, rules-enforced, zero-touch agent workflow",
-  "version": "0.6.2",
-  "author": {
-    "name": "Rizki Rachman",
-    "url": "https://github.com/RizkiRachman"
-  },
-  "homepage": "https://github.com/RizkiRachman/opencode-kit",
-  "repository": "https://github.com/RizkiRachman/opencode-kit",
-  "license": "MIT",
-  "keywords": [
-    "opencode",
-    "opencode-plugin",
-    "orchestration",
-    "workflow",
-    "agents",
-    "enforcement",
-    "contract",
-    "scoring",
-    "adr"
-  ]
-}

package/docs/examples/QUICKSTART.md

@@ -1,123 +0,0 @@
-# Quickstart: Using opencode-kit as a Plugin
-
-This guide creates a new project from scratch with opencode-kit as an OpenCode plugin.
-
-## Step 1: Create a project
-
-```sh
-mkdir my-agent-project
-cd my-agent-project
-git init
-```
-
-## Step 2: Install the plugin
-
-```sh
-npm install @ikieaneh/opencode-kit
-```
-
-## Step 3: Configure OpenCode
-
-Create `opencode.json`:
-
-```json
-{
-  "model": "your-model",
-  "plugin": [
-    "@ikieaneh/opencode-kit",
-    "superpowers"
-  ],
-  "agent": {
-    "orchestrator": {
-      "model": "your-model",
-      "skills": [
-        "orchestration-template",
-        "scoring-pipeline",
-        "verification-before-completion"
-      ],
-      "steps": 50,
-      "fallback_models": ["your-fallback-model"]
-    },
-    "planner": {
-      "model": "your-model",
-      "skills": ["brainstorming", "writing-plans", "system-analyst"],
-      "steps": 80,
-      "fallback_models": ["your-fallback-model"]
-    },
-    "task-manager": {
-      "model": "your-model",
-      "skills": ["subagent-driven-development", "executing-plans", "test-driven-development"],
-      "steps": 100,
-      "fallback_models": ["your-fallback-model"]
-    },
-    "code-reviewer": {
-      "model": "your-model",
-      "skills": ["qa-expert", "security-expert"],
-      "steps": 80,
-      "fallback_models": ["your-fallback-model"]
-    },
-    "explorer": {
-      "model": "your-model",
-      "steps": 30,
-      "tools": { "postgres_*": false, "memory_*": false, "context7_*": false }
-    },
-    "librarian": {
-      "model": "your-model",
-      "steps": 30,
-      "tools": { "postgres_*": false, "memory_*": false, "graphify_*": false }
-    },
-    "learner": {
-      "model": "your-model",
-      "skills": ["verification-before-completion", "qa-expert"]
-    }
-  }
-}
-```
-
-## Step 4: Start working
-
-Open the project in OpenCode. The plugin auto-loads:
-
-1. 8 skills registered automatically
-2. Orchestration contract injected into every session
-3. Pre-flight enforcement active (branch check, contract load)
-4. Scoring pipeline available after every delegation
-5. ADR generator for architectural decisions
-6. Telemetry tracking elapsed time per phase
-
-## Step 5: Set a goal
-
-Edit `.opencode/orchestration/contract.json`:
-
-```json
-{
-  "state": "INIT",
-  "requirements": {
-    "goal": "Add user authentication with JWT",
-    "acceptance_criteria": ["Users can register", "Users can login", "Tokens expire after 24h"]
-  }
-}
-```
-
-## Step 6: Workflow runs itself
-
-```
-INIT → PLAN → PLAN_SCORED → EXECUTE → EXECUTE_SCORED → REVIEW → REVIEW_SCORED → COMPLETE
-```
-
-Each phase transition requires score ≥ 70. Score < 50 → BLOCKED.
-
-## What you get
-
-| Feature | Provider |
-|---------|----------|
-| Contract protocol | orchestration-template skill |
-| Scoring pipeline | scoring-pipeline skill |
-| ADR records | adr-generator skill |
-| QA standards | qa-expert skill |
-| Impact analysis | system-analyst skill |
-| Token optimization | token-optimize skill |
-| Verification gates | verification-before-completion skill |
-| Post-task learning | learner skill |
-| Telemetry | src/telemetry.sh |
-| Rules enforcement | rules.json + validation.sh |

package/docs/examples/extension-skill-template.md

@@ -1,108 +0,0 @@
-# Extension Skill Template
-
-Create project-specific skills in `.opencode/skills/` to extend opencode-kit.
-
-## Resolution Order
-
-1. `.opencode/skills/<name>/SKILL.md` — user project skill (highest priority)
-2. `node_modules/@ikieaneh/opencode-kit/skills/<name>/SKILL.md` — plugin skill (fallback)
-
-If a user skill and plugin skill have the **same name**, the user's version takes priority.
-
-## Example: Java/Spring Conventions
-
-Create `.opencode/skills/java-conventions/SKILL.md`:
-
-```markdown
----
-description: Java 21 + Spring Boot 3.4 conventions for this project.
----
-
-# Java Conventions
-
-## Build & Test
-
-| Command | Action |
-|---------|--------|
-| `mvn spotless:apply` | Format (Google Java Style) |
-| `mvn test` | ArchUnit + unit tests |
-| `mvn verify` | SpotBugs + PMD CPD |
-
-## Hexagonal Architecture
-
-```
-application/      → domain model, ports, services (no Spring/JPA)
-infrastructure/   → web adapters, persistence, events
-```
-
-## Writing Order
-
-Port → Service → Mapper → Adapter → Constants → Events → Tests
-
-## Naming Rules
-
-| Concern | Suffix | Example |
-|---------|--------|---------|
-| API DTO | none | `Product` |
-| Domain Model | `Domain` | `ProductDomain` |
-| JPA Entity | `Entity` | `ProductEntity` |
-
-## ArchUnit Rules (7)
-
-1. domainMustNotDependOnInfrastructure
-2. domainModelsMustNotHaveJpaAnnotations
-3. portsMustNotReturnOptional
-4. entitiesMustNotUseJpaRelationshipAnnotations
-5. layeredArchitectureShouldRespectHexagonalBoundaries
-6. domainServicesMustBeAnnotatedWithService
-7. repositoryAdaptersMustBeAnnotatedWithComponent
-```
-
-## Example: Python/Django Conventions
-
-Create `.opencode/skills/python-conventions/SKILL.md`:
-
-```markdown
----
-description: Django REST Framework conventions for this project.
----
-
-# Python Conventions
-
-## Build & Test
-
-| Command | Action |
-|---------|--------|
-| `black .` | Format code |
-| `ruff check .` | Lint |
-| `pytest` | Run tests |
-| `mypy .` | Type check |
-
-## Architecture
-
-Apps follow clean architecture:
-- `models/` — domain models with business logic
-- `serializers/` — input/output validation
-- `views/` — HTTP handlers (thin)
-- `services/` — business logic layer
-- `tests/` — mirrors app structure
-```
-
-## How to Load
-
-In `opencode.json`, add to any agent's skills array:
-
-```json
-{
-  "agent": {
-    "task-manager": {
-      "skills": [
-        "verification-before-completion",
-        "java-conventions"
-      ]
-    }
-  }
-}
-```
-
-Or load it ad-hoc with: `/skill java-conventions`

package/docs/examples/model-configs.md

@@ -1,117 +0,0 @@
-# Model Provider Configurations
-
-Add these to your `opencode.json` to configure AI models for opencode-kit agents.
-
-## DeepSeek (via Sumopod)
-
-```json
-{
-  "model": "sumopod/deepseek-v4-flash",
-  "provider": {
-    "sumopod": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "Sumopod AI",
-      "options": {
-        "baseURL": "https://ai.sumopod.com/v1",
-        "apiKey": "sk-your-key"
-      },
-      "models": {
-        "deepseek-v4-flash": {
-          "name": "DeepSeek V4 Flash",
-          "options": {
-            "reasoningEffort": "high",
-            "textVerbosity": "low"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-## OpenAI
-
-```json
-{
-  "model": "gpt-4o",
-  "provider": {
-    "openai": {
-      "npm": "@ai-sdk/openai",
-      "models": {
-        "gpt-4o": { "name": "GPT-4o" },
-        "gpt-4o-mini": { "name": "GPT-4o Mini" }
-      }
-    }
-  }
-}
-```
-
-## Anthropic (Claude)
-
-```json
-{
-  "model": "claude-sonnet-4-20250514",
-  "provider": {
-    "anthropic": {
-      "npm": "@ai-sdk/anthropic",
-      "models": {
-        "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
-        "claude-haiku-3-5-20241022": { "name": "Claude Haiku 3.5" }
-      }
-    }
-  }
-}
-```
-
-## Google (Gemini)
-
-```json
-{
-  "model": "gemini-2.5-flash",
-  "provider": {
-    "google": {
-      "npm": "@ai-sdk/google",
-      "models": {
-        "gemini-2.5-flash": { "name": "Gemini 2.5 Flash" },
-        "gemini-2.5-pro": { "name": "Gemini 2.5 Pro" }
-      }
-    }
-  }
-}
-```
-
-## Agent Assignment Strategy
-
-Use **cheaper models** for simple agents, **better models** for complex reasoning:
-
-| Agent | Recommended Model | Why |
-|-------|------------------|-----|
-| orchestrator | Cheaper (orchestration, not deep thinking) | Delegates most work |
-| planner | Better (architecture, impact analysis) | Needs deep reasoning |
-| task-manager | Better (implementation, code quality) | Needs to write correct code |
-| code-reviewer | Better (security, edge cases) | Needs sharp analysis |
-| explorer | Cheaper (just searches) | Simple grep/glob |
-| librarian | Cheaper (fetches docs) | Simple fetch operations |
-| learner | Cheaper (analysis after the fact) | Post-processing only |
-| fixer | Cheaper (bounded edits) | Well-defined scope |
-
-Example with mixed models:
-
-```json
-{
-  "agent": {
-    "orchestrator": {
-      "model": "sumopod/deepseek-v4-flash",
-      "fallback_models": ["gpt-4o-mini"]
-    },
-    "planner": {
-      "model": "gpt-4o",
-      "fallback_models": ["sumopod/deepseek-v4-flash"]
-    },
-    "task-manager": {
-      "model": "gpt-4o",
-      "fallback_models": ["sumopod/deepseek-v4-flash"]
-    }
-  }
-}
-```

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>