@ikieaneh/opencode-kit 0.5.2 → 0.5.4

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/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/package.json

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

package/rules/rules.json

@@ -3,6 +3,26 @@
   "strict": true,
   "description": "Machine-enforceable rules for OpenCode agents. CRITICAL = BLOCK agent. HIGH = FLAG orchestrator. LOW = advisory.",
 
+  "required_mcps": {
+    "description": "MCPs required for the framework to function. Preflight.sh checks these dynamically.",
+    "lean-ctx": {
+      "description": "Context persistence — contract storage and retrieval",
+      "severity": "required",
+      "check_cli": "command -v lean-ctx",
+      "check_tool": "lean-ctx ctx_knowledge recall"
+    },
+    "gitnexus": {
+      "description": "Code intelligence — impact analysis before edits",
+      "severity": "required",
+      "check_cli": "npx --yes gitnexus --version"
+    },
+    "graphify": {
+      "description": "Knowledge graph — codebase exploration",
+      "severity": "optional",
+      "check_cli": "npx --yes gitnexus analyze --help"
+    }
+  },
+
   "state_machine": {
     "transitions": [
       { "from": "INIT", "to": "PLAN", "require_score": null },

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

@@ -180,29 +180,29 @@ if [ "$SAMPLE" = true ]; then
   else
     cat > opencode.json << 'SAMPLEEOF'
 {
-  "model": "sumopod/deepseek-v4-flash",
+  "model": "your-model",
   "plugin": [
     "@ikieaneh/opencode-kit",
     "superpowers"
   ],
   "agent": {
     "orchestrator": {
-      "model": "sumopod/deepseek-v4-flash",
+      "model": "your-model",
       "skills": ["orchestration-template", "scoring-pipeline", "verification-before-completion"],
       "steps": 50
     },
     "planner": {
-      "model": "sumopod/deepseek-v4-flash",
+      "model": "your-model",
       "skills": ["brainstorming", "writing-plans", "system-analyst"],
       "steps": 80
     },
     "task-manager": {
-      "model": "sumopod/deepseek-v4-flash",
+      "model": "your-model",
       "skills": ["subagent-driven-development", "executing-plans", "test-driven-development"],
       "steps": 100
     },
     "code-reviewer": {
-      "model": "sumopod/deepseek-v4-flash",
+      "model": "your-model",
       "skills": ["qa-expert", "security-expert"],
       "steps": 80
     }

package/src/postflight.sh

@@ -11,6 +11,9 @@ CONTRACT_FILE=".opencode/orchestration/contract.json"
 STATE_FILE="STATE.md"
 TELEMETRY_DIR=".opencode/telemetry"
 START_TIME_FILE=".opencode/telemetry/.phase_start"
+STATE_BACKUP_DIR=".opencode/state"
+
+mkdir -p "$TELEMETRY_DIR" "$STATE_BACKUP_DIR"
 
 echo "[opencode-kit] Post-flight: persisting state..."
 
@@ -34,16 +37,28 @@ print(d.get('state','UNKNOWN'))
   rm -f "$START_TIME_FILE"
 fi
 
-# --- Step 1: Re-read contract from lean-ctx (the source of truth) ---
-CURRENT_CONTRACT=$(lean-ctx ctx_knowledge recall --query "$CONTRACT_KEY" 2>/dev/null || cat "$CONTRACT_FILE")
+# --- Step 1: Read contract (try lean-ctx first, fall back to file) ---
+CURRENT_CONTRACT=$(lean-ctx ctx_knowledge recall --query "$CONTRACT_KEY" 2>/dev/null || cat "$CONTRACT_FILE" 2>/dev/null || echo "")
+if [ -z "$CURRENT_CONTRACT" ]; then
+  echo "  ⚠️  No contract found in lean-ctx or file. Creating new from template..."
+  if [ -f "$TEMPLATE_FILE" ]; then
+    CURRENT_CONTRACT=$(cat "$TEMPLATE_FILE")
+  fi
+fi
 
-# --- Step 2: Write back to lean-ctx ---
-lean-ctx ctx_knowledge remember \
+# --- Step 2: Persist (try lean-ctx first, fall back to file) ---
+PERSISTED=false
+if lean-ctx ctx_knowledge remember \
   category architecture \
   key "$CONTRACT_KEY" \
-  value "$CURRENT_CONTRACT" 2>/dev/null && \
-  echo "  ✅ Contract persisted to lean-ctx" || \
-  echo "  ⚠️  lean-ctx persist failed"
+  value "$CURRENT_CONTRACT" 2>/dev/null; then
+  echo "  ✅ Contract persisted to lean-ctx"
+  PERSISTED=true
+fi
+
+# File fallback: write to .opencode/state/contract.json
+echo "$CURRENT_CONTRACT" > "$STATE_BACKUP_DIR/contract.json"
+echo "  ✅ Contract persisted to file: $STATE_BACKUP_DIR/contract.json"
 
 # --- Step 3: Sync STATE.md ---
 mkdir -p "$(dirname "$STATE_FILE")"

package/src/preflight.sh

@@ -33,55 +33,71 @@ if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
 fi
 echo "  ✅ Branch: $BRANCH (safe)"
 
-# --- Check 3: MCP Availability ---
+# --- Check 3: MCP Availability (from rules.json) ---
 echo ""
-echo "  Checking MCP availability..."
+echo "  Checking MCP availability from rules.json..."
 
 MCP_FAIL=0
 
-# 3a. lean-ctx
-LEAN_CTX_AVAILABLE=false
-if command -v lean-ctx &>/dev/null; then
-  echo "  ✅ lean-ctx MCP: available (cli)"
-  LEAN_CTX_AVAILABLE=true
-elif lean-ctx ctx_knowledge recall --query "$CONTRACT_KEY" &>/dev/null; then
-  echo "  ✅ lean-ctx MCP: available (tool)"
-  LEAN_CTX_AVAILABLE=true
-else
-  echo -e "${YELLOW}  ⚠️  lean-ctx MCP: NOT DETECTED — contract persistence will fail${NC}"
-  echo -e "${YELLOW}     → Ensure lean-ctx is configured in opencode.json MCP servers${NC}"
-  MCP_FAIL=1
-fi
-
-# 3b. gitnexus
-if npx --yes gitnexus --version &>/dev/null; then
-  echo "  ✅ gitnexus MCP: available"
-elif npx --yes gitnexus list-repos &>/dev/null; then
-  echo "  ✅ gitnexus MCP: available"
-else
-  echo -e "${YELLOW}  ⚠️  gitnexus MCP: NOT DETECTED — impact analysis will fail${NC}"
-  echo -e "${YELLOW}     → Ensure gitnexus is configured in opencode.json MCP servers${NC}"
-  MCP_FAIL=1
-fi
-
-# 3c. graphify (check via gitnexus index since graphify consumes gitnexus data)
-GRAPHIFY_AVAILABLE=false
-if npx --yes gitnexus analyze --help &>/dev/null; then
-  # gitnexus is available — check if index exists
-  GITNEXUS_DIR=$(find . -name "gitnexus-out" -type d 2>/dev/null | head -1)
-  if [ -n "$GITNEXUS_DIR" ]; then
-    echo "  ✅ graphify: available (gitnexus index found)"
-    GRAPHIFY_AVAILABLE=true
-  else
-    echo -e "${YELLOW}  ⚠️  graphify: gitnexus index not built yet. Run: npx gitnexus analyze${NC}"
-  fi
-else
-  echo -e "${YELLOW}  ⚠️  graphify: gitnexus not available — graphify depends on gitnexus index${NC}"
-fi
-
-# 3d. context7 (library docs — soft check, non-blocking)
-if command -v curl &>/dev/null; then
-  echo "  ✅ context7 MCP: curl available (http transport)"
+if [ -n "$PYTHON_CMD" ] && [ -f "$RULES_FILE" ]; then
+  # Parse required_mcps from rules.json
+  $PYTHON_CMD -c "
+import json, sys, subprocess, os
+
+with open('$RULES_FILE') as f:
+    rules = json.load(f)
+
+mcps = rules.get('required_mcps', {})
+if not isinstance(mcps, dict) or 'description' in mcps:
+    # Skip the meta-description field
+    mcps = {k: v for k, v in mcps.items() if k != 'description' and isinstance(v, dict)}
+
+if not mcps:
+    print('  ℹ️  No required_mcps defined in rules.json — skipping MCP checks')
+    sys.exit(0)
+
+failures = []
+for name, cfg in mcps.items():
+    cli_check = cfg.get('check_cli', '')
+    tool_check = cfg.get('check_tool', '')
+    severity = cfg.get('severity', 'optional')
+    desc = cfg.get('description', name)
+
+    available = False
+    # Try CLI check first
+    if cli_check:
+        try:
+            result = subprocess.run(cli_check, shell=True, capture_output=True, timeout=5)
+            if result.returncode == 0:
+                available = True
+        except:
+            pass
+
+    # Try tool check as fallback
+    if not available and tool_check:
+        try:
+            result = subprocess.run(tool_check, shell=True, capture_output=True, timeout=5)
+            if result.returncode == 0:
+                available = True
+        except:
+            pass
+
+    if available:
+        print(f'  ✅ {name}: available — {desc}')
+    elif severity == 'required':
+        print(f'  ❌ {name}: NOT DETECTED — {desc}')
+        failures.append(name)
+    else:
+        print(f'  ⚠️  {name}: not detected — {desc} (optional)')
+
+if failures:
+    print('')
+    for name in failures:
+        print(f'  → Ensure {name} is configured in opencode.json MCP servers')
+    sys.exit(1)
+else:
+    sys.exit(0)
+" 2>&1 || MCP_FAIL=1
 fi
 
 echo ""

package/templates/agents/orchestrator.md

@@ -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 (verification-before-completion skill)
+Run quality gates (format, compile, test, verify)
 If CRITICAL findings → BLOCK, fix, re-review. Max 3 iterations.
 
 ### 6. Ship

package/templates/contract.json

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

package/templates/opencode-kit.schema.json

@@ -23,7 +23,7 @@
           "properties": {
             "skills": {
               "type": "array",
-              "description": "Recommended skills: orchestration-template, scoring-pipeline, adr-generator, verification-before-completion",
+              "description": "Skills to load for this agent (e.g., orchestration, scoring, quality gates)",
               "items": { "type": "string" },
               "default": ["orchestration-template", "scoring-pipeline", "verification-before-completion"]
             },
@@ -37,7 +37,7 @@
           "properties": {
             "skills": {
               "type": "array",
-              "description": "Recommended skills: brainstorming, writing-plans, system-analyst",
+              "description": "Skills for analysis, requirements gathering, plan writing",
               "items": { "type": "string" },
               "default": ["brainstorming", "writing-plans", "system-analyst"]
             },
@@ -51,6 +51,7 @@
           "properties": {
             "skills": {
               "type": "array",
+              "description": "Skills for implementation, execution, testing",
               "items": { "type": "string" },
               "default": ["subagent-driven-development", "executing-plans", "test-driven-development"]
             },
@@ -64,6 +65,7 @@
           "properties": {
             "skills": {
               "type": "array",
+              "description": "Skills for code quality, security, performance review",
               "items": { "type": "string" },
               "default": ["qa-expert", "security-expert", "devops-expert"]
             },
@@ -77,6 +79,7 @@
           "properties": {
             "skills": {
               "type": "array",
+              "description": "Skills for verification, quality checks, post-analysis",
               "items": { "type": "string" },
               "default": ["verification-before-completion", "qa-expert"]
             },
@@ -117,6 +120,7 @@
           "properties": {
             "skills": {
               "type": "array",
+              "description": "Skills for architecture analysis, simplification, debugging",
               "items": { "type": "string" },
               "default": ["simplify", "systematic-debugging", "system-analyst"]
             },

package/skills/java-developer/SKILL.md

@@ -1,66 +0,0 @@
----
-description: Java/Spring Boot conventions for opencode-kit projects. Hexagonal architecture, ArchUnit, Maven build.
----
-
-# Java Developer
-
-Load this skill if your project uses **Java + Spring Boot + Maven**.
-
-## Build & Test
-
-Replace generic `npm` commands with Maven equivalents:
-
-| Generic | Java Equivalent |
-|---------|-----------------|
-| `npm test` | `mvn test` |
-| `npm run build` | `mvn compile` |
-| `npm run format` | `mvn spotless:apply` |
-| `npm test -- --all` | `mvn verify` |
-
-## Quality Gates (run in order)
-
-```sh
-mvn spotless:apply        # Formatting (Google Java Style)
-mvn test                  # ArchUnit (7 rules) + unit tests
-mvn verify                # SpotBugs + PMD CPD + full tests
-```
-
-## Agent Permission Overrides
-
-In `opencode.json`, add Maven permissions to agents:
-
-```json
-"bash": {
-  "mvn test*": "allow",
-  "mvn compile*": "allow",
-  "mvn verify": "allow",
-  "mvn spotless:apply": "allow",
-  "git diff*": "allow",
-  "git log*": "allow"
-}
-```
-
-## Conventions
-
-### Hexagonal Architecture
-```
-application/       → domain model, ports, domain services
-infrastructure/    → web adapters, persistence, event handlers
-```
-
-### Writing Order
-Port → Service → Mapper → Adapter → Constants → Events → Tests
-
-### Domain Models
-- `@Builder @Getter @Setter` — zero JPA annotations
-- Ports return **nullable**, never `Optional<T>`
-- No JPA relationship annotations (`@ManyToOne`, `@OneToMany`, etc.)
-
-### ArchUnit Rules (7)
-1. domainMustNotDependOnInfrastructure
-2. domainModelsMustNotHaveJpaAnnotations
-3. portsMustNotReturnOptional
-4. entitiesMustNotUseJpaRelationshipAnnotations
-5. layeredArchitectureShouldRespectHexagonalBoundaries
-6. domainServicesMustBeAnnotatedWithService
-7. repositoryAdaptersMustBeAnnotatedWithComponent