@ikieaneh/opencode-kit 0.5.0 → 0.5.2

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>
@@ -28,6 +28,7 @@
   </p>
 
   <p>
+    <b>npm:</b> <code>@ikieaneh/opencode-kit</code> &middot;
     <b>macOS M-Series</b> — Apple Silicon (arm64)
   </p>
 </div>
@@ -123,14 +124,14 @@ git --version     # any recent version
 
 ### Installation
 
-#### Option 1: Install as plugin (recommended v0.4+)
+#### Option 1: Install as plugin (recommended)
 
 Add to your project's `opencode.json`:
 
 ```json
 {
   "plugin": [
-    "opencode-kit",      ← MUST be first
+    "@ikieaneh/opencode-kit",      ← MUST be first
     "other-plugins..."
   ]
 }
@@ -139,10 +140,12 @@ Add to your project's `opencode.json`:
 Then install:
 
 ```sh
-npm install opencode-kit
+npm install @ikieaneh/opencode-kit
 ```
 
-The plugin auto-loads on next session. Skills `orchestration-template`, `scoring-pipeline`, `adr-generator` become available. The orchestration contract is injected into every session automatically.
+The plugin auto-loads on next session. All 8 skills become available. The orchestration contract is injected into every session automatically.
+
+> **Plugin ordering**: opencode-kit MUST be first in the plugin array. Its system prompt transform is foundational — other plugins may add behavior, but opencode-kit enforces the workflow.
 
 > **Plugin ordering**: opencode-kit MUST be first in the plugin array. Its system prompt transform is foundational — other plugins may add behavior, but opencode-kit enforces the workflow.
 
@@ -370,10 +373,17 @@ After every subagent delegation, scoring runs automatically:
 - [x] Integration tests (7/7 passing)
 - [x] CI integration test job
 
-### v0.6 — Publish & Polish (next)
-- [ ] npm publish
-- [ ] Test plugin end-to-end on clean macOS M-series machine
-- [ ] Web UI for contract overview
+### v0.6 — Polish ✅
+- [x] README updated for @ikieaneh/opencode-kit plugin mode
+- [x] Updated agent config schema (fallback_models, explorer, librarian, architect)
+- [x] End-to-end tests (9 tests, plugin lifecycle + auto-init)
+- [x] Quickstart example (`docs/examples/QUICKSTART.md`)
+- [x] npm published as `@ikieaneh/opencode-kit`
+- [x] CI: integration + e2e test jobs
+
+### Future
+- [ ] Web UI for contract overview (deferred — no current need)
+- [ ] Plugin hardening: `experimental.chat.messages.transform` API is marked experimental — monitor OpenCode updates
 
 See the [open issues](https://github.com/RizkiRachman/opencode-kit/issues) for full list.
 
@@ -398,6 +408,12 @@ Distributed under the MIT License. See `LICENSE` for more information.
 <!-- CONTACT -->
 ## Contact
 
+## Known Limitations
+
+- **Plugin hook API**: The `experimental.chat.messages.transform` hook is marked as experimental in the OpenCode plugin SDK. It may change in future versions. If it breaks, the plugin falls back to per-project agent .md files (`.opencode/agents/*.md`), which remain functional.
+- **Package name**: Currently published as `@ikieaneh/opencode-kit` (scoped). Requires `npm install @ikieaneh/opencode-kit`.
+- **Contract auto-init**: Requires a git repository. Non-git projects use absolute path as hash fallback.
+
 Rizki Rachman — [GitHub](https://github.com/RizkiRachman)
 
 Project Link: [https://github.com/RizkiRachman/opencode-kit](https://github.com/RizkiRachman/opencode-kit)

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/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,7 +1,7 @@
 {
   "name": "@ikieaneh/opencode-kit",
-  "version": "0.5.0",
-  "description": "Standardized OpenCode orchestration framework \u2014 contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
+  "version": "0.5.2",
+  "description": "Standardized OpenCode orchestration framework — contract-based, rules-enforced, zero-touch agent workflow. Install as plugin.",
   "license": "MIT",
   "author": "RizkiRachman",
   "type": "module",
@@ -20,7 +20,8 @@
     "src/",
     "rules/",
     "templates/",
-    "skills/"
+    "skills/",
+    "docs/"
   ],
   "publishConfig": {
     "access": "public"
@@ -44,4 +45,4 @@
     "url": "https://github.com/RizkiRachman/opencode-kit/issues"
   },
   "homepage": "https://github.com/RizkiRachman/opencode-kit#readme"
-}
+}

package/skills/java-developer/SKILL.md

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

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": "sumopod/deepseek-v4-flash",
+  "plugin": [
+    "@ikieaneh/opencode-kit",
+    "superpowers"
+  ],
+  "agent": {
+    "orchestrator": {
+      "model": "sumopod/deepseek-v4-flash",
+      "skills": ["orchestration-template", "scoring-pipeline", "verification-before-completion"],
+      "steps": 50
+    },
+    "planner": {
+      "model": "sumopod/deepseek-v4-flash",
+      "skills": ["brainstorming", "writing-plans", "system-analyst"],
+      "steps": 80
+    },
+    "task-manager": {
+      "model": "sumopod/deepseek-v4-flash",
+      "skills": ["subagent-driven-development", "executing-plans", "test-driven-development"],
+      "steps": 100
+    },
+    "code-reviewer": {
+      "model": "sumopod/deepseek-v4-flash",
+      "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/opencode-kit.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema#",
   "title": "opencode-kit Plugin Config",
-  "description": "Configuration schema for opencode-kit plugin. Add to your opencode.json to enable orchestration agents.",
+  "description": "Configuration schema for @ikieaneh/opencode-kit plugin. Add to your opencode.json to enable orchestration agents.",
   "type": "object",
   "properties": {
     "plugin": {
@@ -9,7 +9,7 @@
       "description": "opencode-kit MUST be listed FIRST in the plugin array to ensure its system prompt transform takes priority.",
       "items": {
         "type": "string",
-        "examples": ["opencode-kit", "superpowers", "oh-my-opencode-slim"]
+        "examples": ["@ikieaneh/opencode-kit", "superpowers", "oh-my-opencode-slim"]
       },
       "minItems": 1
     },
@@ -23,11 +23,12 @@
           "properties": {
             "skills": {
               "type": "array",
-              "description": "Recommended skills: orchestration-template, scoring-pipeline, adr-generator",
+              "description": "Recommended skills: orchestration-template, scoring-pipeline, adr-generator, verification-before-completion",
               "items": { "type": "string" },
               "default": ["orchestration-template", "scoring-pipeline", "verification-before-completion"]
             },
-            "steps": { "type": "integer", "default": 50, "description": "Max agent steps" }
+            "steps": { "type": "integer", "default": 50, "description": "Max agent steps" },
+            "fallback_models": { "type": "array", "items": { "type": "string" }, "description": "Fallback models if primary fails" }
           }
         },
         "planner": {
@@ -40,7 +41,8 @@
               "items": { "type": "string" },
               "default": ["brainstorming", "writing-plans", "system-analyst"]
             },
-            "steps": { "type": "integer", "default": 80 }
+            "steps": { "type": "integer", "default": 80 },
+            "fallback_models": { "type": "array", "items": { "type": "string" } }
           }
         },
         "task-manager": {
@@ -52,7 +54,8 @@
               "items": { "type": "string" },
               "default": ["subagent-driven-development", "executing-plans", "test-driven-development"]
             },
-            "steps": { "type": "integer", "default": 100 }
+            "steps": { "type": "integer", "default": 100 },
+            "fallback_models": { "type": "array", "items": { "type": "string" } }
           }
         },
         "code-reviewer": {
@@ -64,16 +67,61 @@
               "items": { "type": "string" },
               "default": ["qa-expert", "security-expert", "devops-expert"]
             },
-            "steps": { "type": "integer", "default": 80 }
+            "steps": { "type": "integer", "default": 80 },
+            "fallback_models": { "type": "array", "items": { "type": "string" } }
           }
         },
         "learner": {
           "type": "object",
           "description": "Post-execution learning. Extracts lessons, persists knowledge.",
-          "skills": {
-            "type": "array",
-            "items": { "type": "string" },
-            "default": ["verification-before-completion", "qa-expert"]
+          "properties": {
+            "skills": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": ["verification-before-completion", "qa-expert"]
+            },
+            "fallback_models": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "explorer": {
+          "type": "object",
+          "description": "Fast codebase search specialist. Read-only — no edits.",
+          "properties": {
+            "skills": { "type": "array", "items": { "type": "string" }, "default": [] },
+            "steps": { "type": "integer", "default": 30 },
+            "tools": {
+              "type": "object",
+              "description": "Disable write-heavy tools: context7, memory, postgres",
+              "default": { "postgres_*": false, "memory_*": false, "context7_*": false }
+            },
+            "fallback_models": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "librarian": {
+          "type": "object",
+          "description": "External docs and API references. Read-only — no edits.",
+          "properties": {
+            "skills": { "type": "array", "items": { "type": "string" }, "default": [] },
+            "steps": { "type": "integer", "default": 30 },
+            "tools": {
+              "type": "object",
+              "description": "Disable tools not needed for docs research",
+              "default": { "postgres_*": false, "memory_*": false, "graphify_*": false }
+            },
+            "fallback_models": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "architect": {
+          "type": "object",
+          "description": "Strategic technical advisor. Architecture trade-offs, system-level debugging, simplification.",
+          "properties": {
+            "skills": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": ["simplify", "systematic-debugging", "system-analyst"]
+            },
+            "steps": { "type": "integer", "default": 60 },
+            "fallback_models": { "type": "array", "items": { "type": "string" } }
           }
         }
       }