@hiai-gg/hiai-opencode 0.2.0 → 0.2.2

package/docs/hiai-opencode/migration.md

@@ -0,0 +1,209 @@
+# Migration Guide
+
+**hiai-opencode** — upgrading from legacy configurations and handling agent name changes.
+
+---
+
+## Agent Name Migrations
+
+Three agent names have been deprecated and replaced. The migration is handled automatically by `src/shared/migration/agent-names.ts` — old names are resolved to their canonical replacements at config load time.
+
+| Deprecated | Replacement | Deprecated since |
+|---|---|---|
+| `guard` | `manager` | 2026-04-11 |
+| `brainstormer` | `writer` | 2026-04-11 |
+| `multimodal` | `vision` | 2026-04-11 |
+
+### `guard` → `manager`
+
+`guard` was the delegation orchestrator with an emphasis on error verification. `manager` is the same role but focused on delegation, TODO tracking, session handoffs, and memory stewardship. Error verification is now `critic`'s explicit job.
+
+**Config before:**
+```json
+{
+  "models": {
+    "guard": { "model": "opencode-go/qwen3.6-plus", "recommended": "middle" }
+  }
+}
+```
+
+**Config after:**
+```json
+{
+  "models": {
+    "manager": { "model": "opencode-go/qwen3.6-plus", "recommended": "middle" }
+  }
+}
+```
+
+**Prompt call before:**
+```typescript
+task(subagent_type="guard", description="Coordinate the review sprint", prompt="...")
+```
+
+**Prompt call after:**
+```typescript
+task(subagent_type="manager", description="Coordinate the review sprint", prompt="...")
+```
+
+---
+
+### `brainstormer` → `writer`
+
+`brainstormer` owned ideation and creative exploration. `writer` owns all copy, content, positioning, SEO, and ideation work. The capability set is the same; the name is more precise.
+
+**Config before:**
+```json
+{
+  "models": {
+    "brainstormer": { "model": "openrouter/mistralai/mistral-small-2603", "recommended": "writing" }
+  }
+}
+```
+
+**Config after:**
+```json
+{
+  "models": {
+    "writer": { "model": "openrouter/mistralai/mistral-small-2603", "recommended": "writing" }
+  }
+}
+```
+
+**Prompt call before:**
+```typescript
+task(subagent_type="brainstormer", load_skills=["website-copywriting"], description="Draft landing page hero", prompt="...")
+```
+
+**Prompt call after:**
+```typescript
+task(subagent_type="writer", load_skills=["website-copywriting"], description="Draft landing page hero", prompt="...")
+```
+
+---
+
+### `multimodal` → `vision`
+
+`multimodal` was the PDF/image/diagram extraction and browser UI verification role. `vision` is the canonical name for this role.
+
+**Config before:**
+```json
+{
+  "models": {
+    "multimodal": { "model": "openrouter/google/gemma-4-26b-a4b-it", "recommended": "vision" }
+  }
+}
+```
+
+**Config after:**
+```json
+{
+  "models": {
+    "vision": { "model": "openrouter/google/gemma-4-26b-a4b-it", "recommended": "vision" }
+  }
+}
+```
+
+**Prompt call before:**
+```typescript
+task(subagent_type="multimodal", description="Extract diagrams from the architecture PDF", prompt="...")
+```
+
+**Prompt call after:**
+```typescript
+task(subagent_type="vision", description="Extract diagrams from the architecture PDF", prompt="...")
+```
+
+---
+
+## Auto-Migration
+
+The plugin resolves legacy names automatically. If your config or prompt uses a deprecated name, it will be remapped to the canonical replacement at runtime via `migrateAgentNames()` in `src/shared/migration/agent-names.ts`.
+
+Explicitly migrating to the new names is recommended to avoid relying on the compatibility layer.
+
+---
+
+## Config File Changes
+
+### Schema Requirement: 10 Explicit Model Slots
+
+The config schema requires these 10 keys in `models`:
+
+```
+bob, coder, strategist, guard, critic, designer, researcher, manager, brainstormer, vision
+```
+
+The schema still accepts the legacy `guard` and `brainstormer` keys alongside `manager` and `writer` for backward compatibility, but the runtime resolves them to the same slots.
+
+If you have a minimal config with only the 5 legacy keys, you must add the missing 5 slots before the schema will validate.
+
+### MCP Object Key Changes
+
+| Old key | New key | Notes |
+|---|---|---|
+| `mcp.playwright` | `mcp.agentBrowser` | Playwright is forbidden; use `/agent-browser` skill instead |
+
+---
+
+## Breaking Changes in Recent Versions
+
+### v0.x → v1.0 (2026-04-11)
+
+- **Agent names:** `guard` → `manager`, `brainstormer` → `writer`, `multimodal` → `vision`
+- **Config schema:** 10-key `models` object is now required; 5-key configs are no longer valid
+- **Playwright removed:** All browser automation now uses `/agent-browser` skill; `mcp.playwright` is replaced by `mcp.agentBrowser`
+- **CLOSURE protocol mandatory:** All agents must emit a `<CLOSURE>` block on every response; responses without it are rejected
+- **Skill discovery defaults hardened:** Global OpenCode, Claude, and Agents skill folders are now `false` by default
+
+### Before v0.x
+
+- MCP servers were listed directly in `opencode.json` plugin config
+- Now: MCP configuration lives exclusively in `hiai-opencode.json` under the `mcp` object
+- Agent prompts did not include the mandatory CLOSURE protocol
+
+---
+
+## How to Downgrade If Needed
+
+### Temporary Rollback via Config Override
+
+If a new version causes issues, you can pin to a specific npm version:
+
+```bash
+opencode plugin @hiai-gg/hiai-opencode@<version> --global
+```
+
+Check available versions:
+
+```bash
+npm view @hiai-gg/hiai-opencode versions --json
+```
+
+### Restoring a Compatible Config
+
+Before downgrading, restore a compatible `hiai-opencode.json`:
+
+1. The 5-key model config (before the 10-key requirement) is only valid on versions before `2026-04-11`
+2. Remove `vision`, `writer`, `manager` slots if present
+3. Keep `guard`, `brainstormer`, `multimodal` slots
+
+Example pre-v1.0 config:
+
+```json
+{
+  "models": {
+    "bob": { "model": "kimi-for-coding/k2p6", "recommended": "high" },
+    "coder": { "model": "minimax-coding-plan/MiniMax-M2.7", "recommended": "fast" },
+    "strategist": { "model": "deepseek/deepseek-v4-pro", "recommended": "xhigh" },
+    "guard": { "model": "opencode-go/qwen3.6-plus", "recommended": "middle" },
+    "critic": { "model": "opencode-go/mimo-v2.5-pro", "recommended": "high" }
+  }
+}
+```
+
+### Known Regressions When Downgrading
+
+- **From v1.0 to pre-v1.0:** The `manager`, `writer`, `vision` model slots in your config will be ignored; agents route to the legacy `guard`/`brainstormer`/`multimodal` slots instead
+- **Compaction hooks:** Pre-v1.0 did not have `compaction-context-injector` or `compaction-todo-preserver`; todo state is not preserved across compaction on older versions
+- **CLOSURE enforcement:** Pre-v1.0 does not validate `<CLOSURE>` blocks; agents may produce responses that are now rejected after upgrading back

package/docs/quickstart.md

@@ -57,4 +57,4 @@ When Bob or Manager delegates to sub-agents, check the system reminders for `<sy
 - Read [AGENTS.md](../AGENTS.md) to understand each agent's role
 - Read [ARCHITECTURE.md](../ARCHITECTURE.md) to understand the plugin internals
 - Edit `hiai-opencode.json` (or `.opencode/hiai-opencode.json`) to customize model slots and MCP enable/disable flags
-- Run `hiai-opencode export-mcp .mcp.json` if you need `opencode mcp list` to show hiai MCP servers
+- Run `hiai-opencode export-mcp .opencode/.mcp.json` if you need `opencode mcp list` to show hiai MCP servers

package/docs/skill-discovery.md

@@ -0,0 +1,288 @@
+# Skill Discovery
+
+Skill discovery controls which folders OpenCode scans for skill definitions. Skills are `.md` files under known directories that provide specialized instructions for agent tasks.
+
+## Source Files
+
+- **Schema**: `src/config/schema/skill-discovery.ts`
+- **Routing logic**: `src/plugin/skill-context.ts`
+- **Config resolution**: `src/plugin/skill-discovery-config.ts`
+
+## Configuration Options
+
+The `skill_discovery` object accepts 7 independent boolean flags. All default to safe, reproducible values.
+
+```typescript
+interface SkillDiscoveryConfig {
+  config_sources: boolean   // default: true
+  project_opencode: boolean // default: true
+  global_opencode: boolean // default: false
+  project_claude: boolean  // default: false
+  global_claude: boolean   // default: false
+  project_agents: boolean  // default: false
+  global_agents: boolean   // default: false
+}
+```
+
+| Option | Default | Scanned folder | When to enable |
+|--------|---------|----------------|----------------|
+| `config_sources` | `true` | `hiai-opencode`-bundled skills + explicit `skills.sources` entries in config | Always on — this is the plugin's own skill library |
+| `project_opencode` | `true` | `.opencode/skills/` in project root | Project-local skills shipped with this repo. Safe to keep on. |
+| `global_opencode` | `false` | `~/.config/opencode/skills/` | Global OpenCode skill library. Enable if you want OpenCode's community skill collection. |
+| `project_claude` | `false` | `.claude/skills/` at project root | Project-level Claude-coded skills. Disabled to avoid mixing Codex/Claude skill collections. |
+| `global_claude` | `false` | `~/.claude/skills/` | Global Claude skill library. Disabled to keep installs clean. |
+| `project_agents` | `false` | `agents/` at project root | Project-level Agents skills. Disabled to avoid accidental pollution from unrelated agent definitions. |
+| `global_agents` | `false` | `~/.agents/skills/` | Global Agents skill library. Disabled to keep installs reproducible. |
+
+### Default (deterministic)
+
+```json
+{
+  "skill_discovery": {
+    "config_sources": true,
+    "project_opencode": true,
+    "global_opencode": false,
+    "project_claude": false,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  }
+}
+```
+
+This is the recommended configuration. It loads hiai-opencode bundled skills, generated builtin helpers (browser, review, git, etc.), explicit config sources, and project-local `.opencode/skills`. No external skill collections are mixed in.
+
+## Preset Variant Combinations
+
+The four named variants below are **convenience presets** — combinations of the 7 boolean flags that produce specific behaviors. They are not separate enum values in the schema; you set the individual flags to achieve each effect.
+
+### `all` — Load Everything
+
+Loads hiai-opencode skills plus every external skill folder. Useful when exploring what's available or migrating from another setup.
+
+```json
+{
+  "skill_discovery": {
+    "config_sources": true,
+    "project_opencode": true,
+    "global_opencode": true,
+    "project_claude": true,
+    "global_claude": true,
+    "project_agents": true,
+    "global_agents": true
+  }
+}
+```
+
+**When to use**: Initial exploration, comparing skill quality across sources, or when you have a curated global collection you want to expose.
+
+**Performance implications**: Highest startup cost. Every configured skill folder is scanned. If global folders contain hundreds of skills, OpenCode prompt context warm-up is measurably slower. Also increases the chance of skill name collisions or contradictory skill behaviors.
+
+---
+
+### `minimal` — Only Built-in Skills
+
+Loads only `config_sources` (hiai-opencode bundled skills and generated builtin helpers). No project-local or external folders.
+
+```json
+{
+  "skill_discovery": {
+    "config_sources": true,
+    "project_opencode": false,
+    "global_opencode": false,
+    "project_claude": false,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  }
+}
+```
+
+**When to use**: Minimalist deployments, CI/build environments where repeatability is paramount, or embedded contexts where external skills would be inappropriate.
+
+**Performance implications**: Lowest startup cost. Only the plugin's internal skill manifests are loaded. Fastest possible skill context initialization. You lose project-local `.opencode/skills` — enable `project_opencode: true` alongside this if you need those.
+
+---
+
+### `registry` — Config Sources Only
+
+Loads skills explicitly listed in `skills.sources` in `hiai-opencode.json`, plus the plugin's built-in skills. No automatic folder scanning beyond what you configure.
+
+```json
+{
+  "skill_discovery": {
+    "config_sources": true,
+    "project_opencode": false,
+    "global_opencode": false,
+    "project_claude": false,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  }
+}
+```
+
+With a `skills.sources` entry:
+
+```json
+{
+  "skill_discovery": {
+    "config_sources": true,
+    "project_opencode": false,
+    "global_opencode": false,
+    "project_claude": false,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  },
+  "skills": {
+    "sources": [
+      { "path": "/absolute/path/to/my-custom-skill" }
+    ]
+  }
+}
+```
+
+**When to use**: When you want explicit, auditable skill sources only. No accidental skill injection from global folders. Each skill is a deliberate `skills.sources` entry.
+
+**Performance implications**: Medium startup cost — proportional to how many explicit `skills.sources` entries you add. No surprise folder scans. Scales with your explicit list, not with global folder contents.
+
+---
+
+### `none` — No Skills Loaded
+
+Disables all skill loading including hiai-opencode's own bundled skills. Agents operate without any skill context.
+
+```json
+{
+  "skill_discovery": {
+    "config_sources": false,
+    "project_opencode": false,
+    "global_opencode": false,
+    "project_claude": false,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  }
+}
+```
+
+**When to use**: Rare. Troubleshooting skill-related issues, forced zero-context prompts, or embedding the plugin without its skill infrastructure.
+
+**Performance implications**: Minimal memory footprint for skills. However, agents lose access to all bundled skill instructions (`agent-browser`, `frontend-ui-ux`, `review-work`, `git-master`, etc.). This will degrade any workflow that depends on those skills.
+
+## Per-Skill Disable
+
+To disable individual skills without changing folder scanning, use `skills.disable`:
+
+```json
+{
+  "skills": {
+    "disable": ["claude-md-management", "some-noisy-skill"]
+  }
+}
+```
+
+This filters skills by name after folder scanning is complete, regardless of which variant or flag combination is used.
+
+## Examples in opencode.json
+
+### Minimal (recommended baseline)
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@hiai-gg/hiai-opencode"],
+  "skill_discovery": {
+    "config_sources": true,
+    "project_opencode": true,
+    "global_opencode": false,
+    "project_claude": false,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  }
+}
+```
+
+### All external sources enabled
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@hiai-gg/hiai-opencode"],
+  "skill_discovery": {
+    "config_sources": true,
+    "project_opencode": true,
+    "global_opencode": true,
+    "project_claude": true,
+    "global_claude": true,
+    "project_agents": true,
+    "global_agents": true
+  }
+}
+```
+
+### Registry-style with explicit sources only
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@hiai-gg/hiai-opencode"],
+  "skill_discovery": {
+    "config_sources": true,
+    "project_opencode": false,
+    "global_opencode": false,
+    "project_claude": false,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  },
+  "skills": {
+    "sources": [
+      { "path": "/home/user/.config/opencode/skills/my-custom-skill" }
+    ]
+  }
+}
+```
+
+### Zero skills (debug/troubleshoot)
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@hiai-gg/hiai-opencode"],
+  "skill_discovery": {
+    "config_sources": false,
+    "project_opencode": false,
+    "global_opencode": false,
+    "project_claude": false,
+    "global_claude": false,
+    "project_agents": false,
+    "global_agents": false
+  }
+}
+```
+
+## Quick Reference
+
+| Variant | config_sources | project_opencode | global_opencode | project_claude | global_claude | project_agents | global_agents |
+|---------|---------------|-----------------|----------------|---------------|--------------|---------------|--------------|
+| **default** | true | true | false | false | false | false | false |
+| **all** | true | true | true | true | true | true | true |
+| **minimal** | true | false | false | false | false | false | false |
+| **registry** | true | false | false | false | false | false | false |
+| **none** | false | false | false | false | false | false | false |
+
+## Mapping: Config Flags to Skill Loader Scopes
+
+The 7 config flags map to the 4 internal scopes used by the skill loader. Multiple flags can collapse into a single scope when they share the same priority level.
+
+| Skill Loader Scope | Priority | Config Flags That Control It |
+|---|---|---|
+| **Project** (`.opencode/skills/`) | 1 (highest) | `project_opencode` |
+| **OpenCode config** (`~/.config/opencode/skills/`) | 2 | `global_opencode` |
+| **User** (`~/.config/opencode/hiai-opencode/skills/`) | 3 | `config_sources` (includes bundled skills + explicit `skills.sources`) |
+| **Global** (built-in skills) | 4 (lowest) | `config_sources` (always includes plugin built-ins when true) |
+
+Additional flags `project_claude`, `global_claude`, `project_agents`, and `global_agents` add scanned folders that merge into the **Global** scope at the lowest priority. Same-named skills from higher-priority scopes override lower ones.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hiai-gg/hiai-opencode",
-  "version": "0.2.0",
-  "description": "Unified OpenCode plugin — canonical 12-agent model with bundled skills, MCP integrations, LSP, and permissions in one install.",
+  "version": "0.2.2",
+  "description": "Unified OpenCode plugin — 14-agent model (9 visible + 5 hidden) with MCP integrations, browser automation, bundled skills, LSP, and safer defaults.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",