@ikieaneh/opencode-kit 0.5.1 → 0.5.3

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

@@ -164,13 +164,24 @@ export const OpencodeKitPlugin = async ({ client, directory }) => {
   fs.mkdirSync(path.join(globalConfigDir, 'rules'), { recursive: true });
 
   return {
+    // Skill resolution order (first match wins):
+    //   1. .opencode/skills/<name>/  (user project — highest priority)
+    //   2. plugin skills/<name>/     (opencode-kit defaults — fallback)
     config: async (config) => {
       config.skills = config.skills || {};
       config.skills.paths = config.skills.paths || [];
 
+      // Register user project skills FIRST (higher priority)
+      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}`);
+      }
+
+      // Register plugin skills SECOND (fallback)
       if (!config.skills.paths.includes(SKILLS_DIR)) {
         config.skills.paths.push(SKILLS_DIR);
-        log('info', `Registered skills: ${SKILLS_DIR}`);
+        log('info', `Registered plugin skills: ${SKILLS_DIR}`);
       }
 
       // Register global config skills path

package/README.md

@@ -11,7 +11,7 @@
 <br />
 <div align="center">
   <a href="https://github.com/RizkiRachman/opencode-kit">
-    <img src="docs/images/logo.png" alt="Logo" width="80" height="80">
+    <img src="docs/images/logo.svg" alt="Logo" width="80" height="80">
   </a>
 
 <h3 align="center">opencode-kit</h3>

package/docs/examples/QUICKSTART.md

@@ -0,0 +1,123 @@
+# 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 }
+    },
+    "leaner": {
+      "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

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

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

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

@@ -0,0 +1,55 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikieaneh/opencode-kit",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Standardized OpenCode orchestration framework — contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
   "license": "MIT",
   "author": "RizkiRachman",
@@ -20,7 +20,8 @@
     "src/",
     "rules/",
     "templates/",
-    "skills/"
+    "skills/",
+    "docs/"
   ],
   "publishConfig": {
     "access": "public"

package/skills/verification-before-completion/SKILL.md

@@ -12,36 +12,39 @@ For any code change, run in order:
 
 ### 1. Formatting
 ```bash
-mvn spotless:apply  # or equivalent formatter
+# Format code (e.g., spotless, prettier, black, gofmt)
 ```
+Expected: zero files changed after formatting (idempotent).
 
 ### 2. Compilation
 ```bash
-mvn compile
-# Expected: BUILD SUCCESS
+# Build/tests — check for compilation errors
+# e.g., mvn compile, npm run build, cargo check, go build ./...
 ```
+Expected: BUILD SUCCESS.
 
-### 3. Architecture (if ArchUnit present)
+### 3. Architecture Rules (if applicable)
 ```bash
-mvn test -Dtest="*Architecture*"
-# Expected: all 7 ArchUnit rules pass
+# Architecture tests — e.g., ArchUnit, layered boundary checks
 ```
+Expected: all architecture rules pass.
 
 ### 4. Unit Tests
 ```bash
-mvn test
-# Expected: 0 failures, 0 errors
+# Run unit tests — e.g., mvn test, npm test, pytest, cargo test
 ```
+Expected: 0 failures, 0 errors.
 
 ### 5. Full Verification
 ```bash
-mvn verify
-# Expected: BUILD SUCCESS
+# Full suite — e.g., mvn verify, npm test -- --all
 ```
+Expected: BUILD SUCCESS.
 
 ### 6. Static Analysis (if configured)
 ```bash
-# SpotBugs, PMD CPD, OWASP dependency check
+# Linting, security scan, duplicate detection
+# e.g., SpotBugs, ESLint, Clippy, bandit
 ```
 
 ## Evidence Rules
@@ -53,7 +56,7 @@ mvn verify
 
 ## Checklist
 
-- [ ] Formatting passes (spotless)
+- [ ] Formatting passes (idempotent)
 - [ ] Compiles without errors
 - [ ] All tests pass (0 failures, 0 errors)
 - [ ] No new warnings (or documented)

package/src/init.sh

@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
 # opencode-kit init — scaffold orchestration framework into target project
-# Usage: npx opencode-kit init [--force]
+# Usage: npx opencode-kit init [--force] [--sample]
+#   --force    Overwrite existing .opencode/ (backs up to .opencode.bak.<timestamp>)
+#   --sample   Also create a sample opencode.json with @ikieaneh/opencode-kit plugin config
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -14,7 +16,14 @@ YELLOW='\033[1;33m'
 CYAN='\033[0;36m'
 NC='\033[0m'
 
-FORCE="${1:-}"
+FORCE=false
+SAMPLE=false
+for arg in "$@"; do
+  case "$arg" in
+    --force) FORCE=true ;;
+    --sample) SAMPLE=true ;;
+  esac
+done
 TARGET_DIR="${PWD}"
 TIMESTAMP=$(date +%Y%m%d%H%M%S)
 
@@ -64,7 +73,7 @@ fi
 
 # --- Handle existing .opencode/ ---
 if [ -d ".opencode" ]; then
-  if [ "$FORCE" = "--force" ]; then
+  if [ "$FORCE" = true ]; then
     BACKUP=".opencode.bak.$TIMESTAMP"
     echo ""
     echo -e "${YELLOW}⚠️  --force: Backing up existing .opencode/ to $BACKUP${NC}"
@@ -163,3 +172,43 @@ else
   echo -e "${RED}❌ Verification failed. Check errors above.${NC}"
   exit 1
 fi
+
+# --- Sample opencode.json ---
+if [ "$SAMPLE" = true ]; then
+  if [ -f "opencode.json" ]; then
+    echo -e "${YELLOW}  ⚠️  opencode.json already exists. Skipping sample.${NC}"
+  else
+    cat > opencode.json << 'SAMPLEEOF'
+{
+  "model": "your-model",
+  "plugin": [
+    "@ikieaneh/opencode-kit",
+    "superpowers"
+  ],
+  "agent": {
+    "orchestrator": {
+      "model": "your-model",
+      "skills": ["orchestration-template", "scoring-pipeline", "verification-before-completion"],
+      "steps": 50
+    },
+    "planner": {
+      "model": "your-model",
+      "skills": ["brainstorming", "writing-plans", "system-analyst"],
+      "steps": 80
+    },
+    "task-manager": {
+      "model": "your-model",
+      "skills": ["subagent-driven-development", "executing-plans", "test-driven-development"],
+      "steps": 100
+    },
+    "code-reviewer": {
+      "model": "your-model",
+      "skills": ["qa-expert", "security-expert"],
+      "steps": 80
+    }
+  }
+}
+SAMPLEEOF
+    echo "  ✅ Sample opencode.json created"
+  fi
+fi

package/templates/agents/code-reviewer.md

@@ -13,9 +13,9 @@ permission:
     "*": ask
     "git diff*": allow
     "git log*": allow
-    "mvn test*": allow
-    "mvn compile*": allow
-    "mvn verify": allow
+    "npm test": allow
+    "npm run build": allow
+    "npm test": allow
   task:
     "*": deny
 ---

package/templates/agents/fixer.md

@@ -11,9 +11,9 @@ permission:
   list: allow
   bash:
     "*": ask
-    "mvn spotless:apply": allow
-    "mvn test*": allow
-    "mvn compile*": allow
+    "npm run format": allow
+    "npm test": allow
+    "npm run build": allow
     "git diff*": allow
   task:
     "*": deny
@@ -36,7 +36,7 @@ permission:
 ## Permissions
 - Read: All project files
 - Write: Scoped to assigned task only
-- Execute: mvn spotless:apply, mvn test/compile, git diff
+- Execute: test commands, git diff, format/lint
 - Cannot: Spawn subagents, push to git, modify CI/CD
 
 You are a **fast implementation specialist for well-defined bounded tasks**. You do NOT research, make decisions, or expand scope.
@@ -45,7 +45,7 @@ You are a **fast implementation specialist for well-defined bounded tasks**. You
 1. Read assigned scope only
 2. Follow project conventions (writing order, naming)
 3. Make changes efficiently
-4. Run spotless:apply + mvn compile on affected modules
+4. Run format + compile on affected modules
 5. Do NOT expand scope or make unsolicited improvements
 
 ## Output Format

package/templates/agents/orchestrator.md

@@ -11,10 +11,10 @@ permission:
   webfetch: allow
   bash:
     "*": ask
-    "mvn test*": allow
-    "mvn compile*": allow
-    "mvn verify": allow
-    "mvn spotless:apply": allow
+    "npm test": allow
+    "npm run build": allow
+    "npm test": allow
+    "npm run format": allow
     "git diff*": allow
     "git log*": allow
   task:
@@ -94,7 +94,7 @@ Delegate to @code-reviewer. After return → Scoring Pipeline → update contrac
 3. **Tier 3 (Verdict)**: ≥70 PASS, 50-69 RETRY, <50 BLOCKED
 
 ### 5. Verify (loop)
-Run quality gates (mvn test, mvn verify, etc.)
+Run quality gates (verification-before-completion skill)
 If CRITICAL findings → BLOCK, fix, re-review. Max 3 iterations.
 
 ### 6. Ship

package/templates/agents/task-manager.md

@@ -11,10 +11,10 @@ permission:
   webfetch: allow
   bash:
     "*": ask
-    "mvn test*": allow
-    "mvn compile*": allow
-    "mvn verify": allow
-    "mvn spotless:apply": allow
+    "npm test": allow
+    "npm run build": allow
+    "npm test": allow
+    "npm run format": allow
     "git diff*": allow
     "git log*": allow
   task:
@@ -40,7 +40,7 @@ permission:
 ## Permissions
 - Read: All project files
 - Write: Source files, test files
-- Execute: mvn commands, git diff/log, spotless
+- Execute: git diff/log, spotless
 - Cannot: Push to git, modify .opencode/ config
 
 You implement plans step by step. Follow conventions exactly.
@@ -76,7 +76,7 @@ For each file:
 - Cover: happy path, empty, null, boundary, every error branch
 
 ### 5. Before Moving On
-- `mvn spotless:apply`
+- Format code (spotless, prettier, etc.)
 - Remove debug code, TODOs, commented-out code
 
 ### 6. Output Format

package/templates/contract.json

@@ -35,6 +35,7 @@
       { "source": ".opencode/rules/rules.json", "sections": ["all"] }
     ],
     "current_guidance": "",
+    "extension_skills": [],
     "permissions": {
       "do": [],
       "dont": [