refacil-sdd-ai 4.4.1 → 4.5.1

package/README.md

@@ -2,16 +2,16 @@
 
 **SDD-AI** (Specification-Driven Development with AI) packaged as a CLI.
 
-Installs **skills** and **sub-agents** for **Claude Code** and **Cursor** that guide the developer through a structured AI-assisted development workflow, using **`refacil-sdd/`** as the specification store, plus a **local bus** so agents across different repos can communicate with each other.
+Installs **skills** and **sub-agents** for **Claude Code**, **Cursor**, and **OpenCode** that guide the developer through a structured AI-assisted development workflow, using **`refacil-sdd/`** as the specification store, plus a **local bus** so agents across different repos can communicate with each other.
 
 ---
 
 ## Requirements
 
 - **Node.js >= 20.0.0**
-- **Claude Code >= 2.1.89** (required by the `compact-bash` hook for silent rewrite via `updatedInput`) or **Cursor**
+- One or more supported IDEs: **Claude Code >= 2.1.89**, **Cursor**, or **OpenCode**
 
-`refacil-sdd-ai init` checks the Claude Code version and warns if it is below 2.1.89. With an older version the rest of the methodology works, but `compact-bash` will have no effect.
+`refacil-sdd-ai init` checks the Claude Code version and warns if it is below 2.1.89. With an older version the rest of the methodology works, but `compact-bash` will have no effect (Claude Code only — OpenCode and Cursor have their own hook delivery mechanisms).
 
 ---
 
@@ -25,10 +25,12 @@ npm install -g refacil-sdd-ai
 
 # 2. In the repo root
 refacil-sdd-ai init
-#    Copies skills to .claude/ and .cursor/, creates CLAUDE.md + .cursorrules, configures hooks
-#    Creates/updates .claudeignore and .cursorignore with base exclusions
+#    Interactive IDE selector (Claude Code / Cursor / OpenCode) — pre-selects IDEs
+#    whose folder already exists. Use --all to install for all three without prompting.
+#    Copies skills and sub-agents to the selected IDEs, configures hooks,
+#    and creates/updates .claudeignore, .cursorignore and .opencodeignore.
 
-# 3. Restart your Claude Code or Cursor session
+# 3. Restart your IDE session
 #    (new skills are not detected until you restart)
 
 # 4. In the IDE
@@ -43,12 +45,12 @@ npm update -g refacil-sdd-ai
 refacil-sdd-ai update          # in each repo where it is used
 ```
 
-In Claude Code / Cursor the `check-update` hook (every session) syncs skills and `compact-guidance`. Only if the automatic detection (`lib/methodology-migration-pending.js`) finds a pending methodology migration does it write the flag and allow `notify-update` to prompt `/refacil:update`. If there is no migration, the user is not interrupted. The `/refacil:update` skill uses `refacil-sdd-ai migration-pending` as the same criterion.
+`update` detects which IDEs are installed by folder presence (`.claude/`, `.cursor/`, `.opencode/`) and only updates those — it never creates IDE directories that did not exist before. In Claude Code and Cursor the `check-update` hook (every session) syncs skills and `compact-guidance`. In OpenCode the equivalent runs via the `session.created` handler of the embedded plugin (`.opencode/plugins/refacil-hooks.js`). Only if the automatic detection (`lib/methodology-migration-pending.js`) finds a pending methodology migration does it write the flag and allow `notify-update` / `tui.prompt.append` to prompt `/refacil:update`. If there is no migration, the user is not interrupted. The `/refacil:update` skill uses `refacil-sdd-ai migration-pending` as the same criterion.
 
 ### Uninstall
 
 ```bash
-refacil-sdd-ai clean           # in the repo (removes skills + SDD-AI hooks)
+refacil-sdd-ai clean           # in the repo (removes skills + SDD-AI hooks for all IDEs)
 npm uninstall -g refacil-sdd-ai
 ```
 
@@ -133,7 +135,7 @@ Run **`refacil-sdd-ai help`** for the full list including `bus` and `compact` su
 
 ## Available IDE Skills
 
-All invoked as `/refacil:<name>` in Claude Code or Cursor.
+All invoked as `/refacil:<name>` in Claude Code, Cursor, or OpenCode.
 
 ### SDD cycle
 
@@ -170,7 +172,7 @@ Some skills delegate their heavy work to **sub-agents** that run in isolated con
 
 **Model**: `refacil-proposer` runs with `model: opusplan` (uses Opus during plan mode for highest-stakes planning, then switches to Sonnet for execution). Other sub-agents use `model: sonnet` by default.
 
-**Dual-platform**: `.claude/agents/refacil-*.md` uses `tools:` (granular allowlist). `.cursor/agents/refacil-*.md` is auto-generated: `readonly: true` for agents without `Edit`/`Write`, `readonly: false` for those that have them; always `model: inherit`. The installer transforms the frontmatter automatically.
+**Triple-platform**: `.claude/agents/refacil-*.md` uses `tools:` (granular allowlist). `.cursor/agents/refacil-*.md` is auto-generated: `readonly: true` for agents without `Edit`/`Write`, `readonly: false` for those that have them; always `model: inherit`. `.opencode/agents/refacil-*.md` is auto-generated via `transformFrontmatterForOpenCode()`: converts `tools:` to a `permission:` block (`edit: allow/deny`, `bash: allow/deny`, `webfetch: deny`), adds `mode: subagent`, adds `hidden: true` for internal agents, and removes `model:`. The installer transforms the frontmatter automatically for all three IDEs.
 
 **Two-pass `refacil:bug` flow**: the wrapper first invokes the sub-agent in `investigation` mode (writes nothing) → the user confirms the hypothesis and approves the fix → the wrapper validates the working branch → invokes the sub-agent in `fix` mode to implement.
 
@@ -259,16 +261,23 @@ From there, the full cycle is:
 
 ## Automatic Hooks
 
-Installed in `.claude/settings.json` **and** `.cursor/settings.json` during `init` / `update`. Apply to both **Claude Code** and **Cursor**.
+Installed during `init` / `update` for each selected IDE. The same four behaviors are active in Claude Code, Cursor, and OpenCode — each through its own delivery mechanism.
 
-| Hook | Event | What it does |
-|---|---|---|
-| `check-update` | `SessionStart` | On startup deletes `.refacil-pending-update` if no migration is pending (stale flags). Then: npm check, sync skills, **compact-guidance**. If skills were synced **and** a migration is pending, writes the flag for `notify-update`. |
-| `notify-update` | `UserPromptSubmit` (Claude Code) / `beforeSubmitPrompt` (Cursor) | If the flag exists **and** a methodology migration is pending (same table as `/refacil:update`), injects the instruction or pauses the first message; if the sync happened without a migration, the flag is not created or is discarded silently. |
-| `compact-bash` | `PreToolUse` (Bash) | Silently rewrites bare Bash commands via `updatedInput`. No extra turns, the IDE does not see the change. Requires Claude Code >= 2.1.89. |
-| `check-review` | `PreToolUse` (Bash) | Intercepts `git push` and blocks if `.review-passed` is missing in any active change. |
+| Behavior | Claude Code | Cursor | OpenCode |
+|---|---|---|---|
+| **check-update** | `SessionStart` hook in `.claude/settings.json` | `SessionStart` hook in `.cursor/settings.json` | `session.created` handler in `.opencode/plugins/refacil-hooks.js` |
+| **notify-update** | `UserPromptSubmit` hook | `beforeSubmitPrompt` hook | `tui.prompt.append` handler |
+| **compact-bash** | `PreToolUse` (Bash) hook | `PreToolUse` (Bash) hook | `tool.execute.before` handler for bash tool |
+| **check-review** | `PreToolUse` (Bash) hook | `PreToolUse` (Bash) hook | `tool.execute.before` handler for bash tool |
+
+| Behavior | What it does |
+|---|---|
+| `check-update` | On startup: deletes `.refacil-pending-update` if no migration is pending (stale flags). Then: npm check, sync skills, **compact-guidance**. If skills were synced **and** a migration is pending, writes the flag for `notify-update`. Always refreshes the flag content when a migration is pending (keeps the `to` version current). |
+| `notify-update` | If the flag exists **and** a methodology migration is pending (same table as `/refacil:update`), injects the instruction before the agent processes the next user message; if the sync happened without a migration, the flag is not created or is discarded silently. |
+| `compact-bash` | Silently rewrites bare Bash commands. No extra turns, the IDE does not see the change. Requires Claude Code >= 2.1.89 for the `updatedInput` path. |
+| `check-review` | Intercepts `git push` and blocks if `.review-passed` is missing in any active change. |
 
-All four hooks are installed in `.claude/settings.json` (Claude Code) and `.cursor/settings.json` (Cursor) with the same parametric logic.
+> **OpenCode plugin**: a single file (`.opencode/plugins/refacil-hooks.js`) implements all four behaviors. It loads `lib/compact/rules.js` from the package to reuse the same rewrite rules — no duplicated logic. If the rules file is not resolvable, compact-bash is disabled gracefully with a warning to stderr; the plugin never crashes the session.
 
 > **Why two hooks for updates?** `SessionStart` does the silent sync when opening the session without user interaction. `notify-update` on `UserPromptSubmit` / `beforeSubmitPrompt` injects the instruction just before the agent processes the next user message, ensuring it is not ignored.
 
@@ -406,18 +415,35 @@ Local bus (WebSocket over `127.0.0.1`) so agents across different repos can comm
 
 ## What Gets Installed in Your Repo
 
+Only the IDEs selected during `init` (or detected during `update`) receive files. The three IDE targets are independent — selecting only `.opencode` does not create `.claude/` or `.cursor/` directories.
+
 ```
-.claude/skills/refacil-*/    # Claude Code skills (includes refacil-prereqs: METHODOLOGY-CONTRACT.md, BUS-CROSS-REPO.md, …)
+# Claude Code (if selected)
+.claude/skills/refacil-*/    # Skills (includes refacil-prereqs: METHODOLOGY-CONTRACT.md, BUS-CROSS-REPO.md, …)
 .claude/agents/refacil-*.md  # Read-only sub-agents: auditor, investigator, validator
                              # Write sub-agents: tester, implementer, debugger, proposer
-.claude/settings.json        # Hooks: check-update + check-review + compact-bash
+.claude/settings.json        # Hooks: check-update + notify-update + check-review + compact-bash
+.claude/.sdd-version         # Installed methodology version (used by check-update)
+
+# Cursor (if selected)
 .cursor/skills/refacil-*/    # Cursor skills (equivalent)
-.cursor/agents/refacil-*.md  # Cursor sub-agents (readonly:true/false + model:inherit auto-generated)
-.cursor/settings.json        # Hooks: check-update + check-review + compact-bash (mirror of .claude/)
+.cursor/agents/refacil-*.md  # Cursor sub-agents (readonly:true/false + model:inherit, auto-generated)
+.cursor/settings.json        # Hooks: check-update + notify-update + check-review + compact-bash
+.cursor/.sdd-version         # Installed methodology version
+
+# OpenCode (if selected)
+.opencode/skills/refacil-*/       # OpenCode skills (byte-for-byte copy — same spec as Claude Code)
+.opencode/agents/refacil-*.md    # OpenCode sub-agents (permission block + mode:subagent, auto-generated)
+.opencode/plugins/refacil-hooks.js  # Embedded plugin: session.created + tui.prompt.append + tool.execute.before
+.opencode/opencode.json          # Created/merged with $schema (user keys preserved)
+.opencode/.sdd-version           # Installed methodology version
+
+# Shared (IDE-agnostic)
 CLAUDE.md                    # Minimal index → points to AGENTS.md
-.cursorrules                 # Same in Cursor format
+.cursorrules                 # Cursor format equivalent of CLAUDE.md
 .claudeignore                # Base exclusions (node_modules, dist, .env, *.key, etc.)
 .cursorignore                # Same content as .claudeignore
+.opencodeignore              # Same content as .claudeignore
 AGENTS.md                    # Project index → generated by /refacil:setup
                              # Points to .agents/ + includes auto-managed blocks
                              # (compact-guidance and bus presentation)
@@ -436,6 +462,7 @@ refacil-sdd/                 # SDD artifacts store
 - [AGENTS.md](https://agents.md/) — universal AI instructions standard
 - [Claude Code](https://claude.ai/code) — Anthropic CLI
 - [Cursor](https://cursor.sh) — AI IDE
+- [OpenCode](https://opencode.ai) — open-source AI development agent
 
 ## License
 

package/agents/validator.md

@@ -1,6 +1,6 @@
 ---
 name: refacil-validator
-description: Validates implementation against SDD specs (CA/CR) and tests. Delegated by /refacil:verify — do not invoke directly. Read-only: does not apply fixes.
+description: Validates implementation against SDD specs (CA/CR) and tests. Delegated by /refacil:verify — do not invoke directly. Never modifies files.
 tools: Read, Grep, Glob, Bash
 model: sonnet
 ---

package/bin/cli.js

@@ -12,7 +12,9 @@ const compactBash = require('../lib/compact/bash');
 const {
   installSkills,
   installAgents,
+  installOpenCodeJson,
   removeSkills,
+  removeOpenCodeArtifacts,
   removeOpenspecLegacyAssets,
   createClaudeMd,
   createCursorRules,
@@ -22,7 +24,7 @@ const {
   checkNodeVersion,
   checkClaudeCodeVersion,
 } = require('../lib/installer');
-const { installHooks, uninstallHooks, cleanLegacySettingsHooks } = require('../lib/hooks');
+const { installHooks, uninstallHooks, cleanLegacySettingsHooks, installOpenCodePlugin, uninstallOpenCodePlugin } = require('../lib/hooks');
 const { handleCompact } = require('../lib/commands/compact');
 const { handleBus } = require('../lib/commands/bus');
 const { handleSdd, autoMigrateOpenspec, findProjectRoot } = require('../lib/commands/sdd');
@@ -119,10 +121,108 @@ function notifyUpdate() {
 function repoIsInitialized() {
   return (
     fs.existsSync(path.join(projectRoot, '.claude', 'skills')) ||
-    fs.existsSync(path.join(projectRoot, '.cursor', 'skills'))
+    fs.existsSync(path.join(projectRoot, '.cursor', 'skills')) ||
+    fs.existsSync(path.join(projectRoot, '.opencode', 'skills'))
   );
 }
 
+/**
+ * Inline readline-based multi-select for IDE targets.
+ * Shows a checklist of available IDEs and returns the selected ones.
+ * Falls back to all IDEs if stdin is not a TTY.
+ * @param {Array<{label: string, value: string, selected: boolean}>} options
+ * @returns {Promise<string[]>} selected values
+ */
+function readlineMultiSelect(options) {
+  return new Promise((resolve) => {
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+    const selected = options.map((o) => o.selected);
+    let renderCount = 0;
+
+    function render() {
+      if (renderCount > 0) {
+        process.stdout.write(`\x1B[${options.length + 7}A\x1B[J`);
+      }
+      renderCount++;
+      console.log('\n  Select IDEs to install refacil-sdd-ai into:');
+      console.log('  (space = toggle, enter = confirm, a = toggle all)\n');
+      for (let i = 0; i < options.length; i++) {
+        const check = selected[i] ? '[x]' : '[ ]';
+        console.log(`  ${check} ${options[i].label}`);
+      }
+      console.log('\n  Enter numbers to toggle (e.g. 1,2,3) or "a" for all, then Enter to confirm:');
+    }
+
+    render();
+
+    rl.on('line', (line) => {
+      const input = line.trim().toLowerCase();
+      if (input === '') {
+        rl.close();
+        resolve(options.filter((_, i) => selected[i]).map((o) => o.value));
+        return;
+      }
+      if (input === 'a') {
+        const anySelected = selected.some(Boolean);
+        for (let i = 0; i < selected.length; i++) selected[i] = !anySelected;
+      } else {
+        const nums = input.split(/[\s,]+/).map(Number).filter((n) => !isNaN(n) && n >= 1 && n <= options.length);
+        for (const n of nums) selected[n - 1] = !selected[n - 1];
+      }
+      render();
+    });
+
+    rl.on('close', () => {
+      resolve(options.filter((_, i) => selected[i]).map((o) => o.value));
+    });
+  });
+}
+
+/**
+ * Show interactive IDE selector if TTY and --all not in args.
+ * Pre-selects IDEs by folder presence.
+ * Returns selected IDE dirs (e.g. ['.claude', '.cursor', '.opencode']).
+ */
+async function selectIDEs() {
+  const allFlag = process.argv.includes('--all');
+  const allIDEs = ['.claude', '.cursor', '.opencode'];
+
+  // --all or non-TTY: install all three
+  if (allFlag || !process.stdout.isTTY) {
+    return allIDEs;
+  }
+
+  const options = [
+    { label: 'Claude Code (.claude/)', value: '.claude', selected: fs.existsSync(path.join(projectRoot, '.claude')) },
+    { label: 'Cursor (.cursor/)', value: '.cursor', selected: fs.existsSync(path.join(projectRoot, '.cursor')) },
+    { label: 'OpenCode (.opencode/)', value: '.opencode', selected: fs.existsSync(path.join(projectRoot, '.opencode')) },
+  ];
+
+  // Try @clack/prompts first, fall back to inline readline
+  let selected;
+  try {
+    // @clack/prompts is an optional peer dep — try to load it without crashing if absent
+    const clack = require('@clack/prompts');
+    const result = await clack.multiselect({
+      message: 'Select IDEs to install refacil-sdd-ai into:',
+      options: options.map((o) => ({ label: o.label, value: o.value, selected: o.selected })),
+      required: false,
+    });
+    if (clack.isCancel(result)) {
+      console.log('\n  Installation cancelled.\n');
+      process.exit(0);
+    }
+    selected = result;
+  } catch (_) {
+    // @clack/prompts not available — use inline readline fallback
+    selected = await readlineMultiSelect(options);
+  }
+
+  return selected;
+}
+
 function semverGt(a, b) {
   if (!a || !b) return false;
   const pa = a.split('.').map(Number);
@@ -297,7 +397,7 @@ function checkReview() {
 
 // --- High-level commands ---
 
-function init() {
+async function init() {
   console.log('\n  refacil-sdd-ai: Initializing SDD-AI methodology...\n');
 
   const nodeOk = checkNodeVersion();
@@ -313,35 +413,69 @@ function init() {
     console.log('  Update with: npm install -g @anthropic-ai/claude-code\n');
   }
 
-  const count = installSkills(packageRoot, projectRoot);
-  console.log(`  ${count} skills installed in .claude/skills/ and .cursor/skills/`);
+  // Select target IDEs (interactive selector or --all / non-TTY)
+  const selectedIDEs = await selectIDEs();
+
+  if (selectedIDEs.length === 0) {
+    console.log('\n  No IDEs selected. Nothing installed.\n');
+    console.log('  Re-run with: refacil-sdd-ai init --all   to install for all IDEs');
+    process.exit(0);
+    return;
+  }
+
+  const installClaude = selectedIDEs.includes('.claude');
+  const installCursor = selectedIDEs.includes('.cursor');
+  const installOpenCode = selectedIDEs.includes('.opencode');
 
-  const agentsCount = installAgents(packageRoot, projectRoot);
+  const count = installSkills(packageRoot, projectRoot, selectedIDEs);
+  const ideList = selectedIDEs.map((d) => `${d}/skills/`).join(', ');
+  console.log(`  ${count} skills installed in ${ideList}`);
+
+  const agentsCount = installAgents(packageRoot, projectRoot, selectedIDEs);
   if (agentsCount > 0) {
-    console.log(`  ${agentsCount} sub-agents installed in .claude/agents/ and .cursor/agents/`);
+    const agentList = selectedIDEs.map((d) => `${d}/agents/`).join(', ');
+    console.log(`  ${agentsCount} sub-agents installed in ${agentList}`);
   }
 
   writeRepoVersion(projectRoot, getPackageVersion(packageRoot));
 
-  if (createClaudeMd(packageRoot, projectRoot)) console.log('  CLAUDE.md OK');
-  if (createCursorRules(packageRoot, projectRoot)) console.log('  .cursorrules OK');
+  if (installClaude) {
+    if (createClaudeMd(packageRoot, projectRoot)) console.log('  CLAUDE.md OK');
+    if (installHooks('.claude', projectRoot)) {
+      console.log('  Hook check-update added to .claude/settings.json');
+    }
+  }
 
-  if (installHooks('.claude', projectRoot)) {
-    console.log('  Hook check-update added to .claude/settings.json');
+  if (installCursor) {
+    if (createCursorRules(packageRoot, projectRoot)) console.log('  .cursorrules OK');
+    if (installHooks('.cursor', projectRoot)) {
+      console.log('  Hook check-update added to .cursor/hooks.json');
+    }
   }
-  if (installHooks('.cursor', projectRoot)) {
-    console.log('  Hook check-update added to .cursor/settings.json');
+
+  if (installOpenCode) {
+    try {
+      installOpenCodeJson(projectRoot);
+      console.log('  .opencode/opencode.json created/updated');
+    } catch (err) {
+      console.error(`  Warning: could not create opencode.json: ${err.message}`);
+    }
+    if (installHooks('.opencode', projectRoot)) {
+      console.log('  OpenCode plugin installed to .opencode/plugins/refacil-hooks.js');
+    }
   }
 
   try {
-    const ignoreResult = syncIgnoreFiles(projectRoot);
-    const s = ignoreResult.claude;
-    if (s.status === 'created') {
-      console.log('  .claudeignore and .cursorignore created');
-    } else if (s.status === 'updated') {
-      console.log(`  .claudeignore and .cursorignore updated (${s.added} entries added)`);
-    } else {
-      console.log('  .claudeignore and .cursorignore are up to date');
+    const IDE_TO_IGNORE = { '.claude': '.claudeignore', '.cursor': '.cursorignore', '.opencode': '.opencodeignore' };
+    const ignoreResult = syncIgnoreFiles(projectRoot, selectedIDEs);
+    const ignoreNames = selectedIDEs.map((d) => IDE_TO_IGNORE[d]).filter(Boolean).join(', ');
+    const s = ignoreResult.claude || ignoreResult.cursor || ignoreResult.opencode;
+    if (s && s.status === 'created') {
+      console.log(`  ${ignoreNames} created`);
+    } else if (s && s.status === 'updated') {
+      console.log(`  ${ignoreNames} updated (${s.added} entries added)`);
+    } else if (ignoreNames) {
+      console.log(`  ${ignoreNames} are up to date`);
     }
   } catch (err) {
     console.error(`  Warning: could not sync ignore files: ${err.message}`);
@@ -359,7 +493,7 @@ function init() {
   }
 
   console.log('\n  Next steps:\n');
-  console.log('  1. RESTART your Claude Code or Cursor session');
+  console.log('  1. RESTART your IDE session');
   console.log('     (new skills are not detected until the session is restarted)\n');
   console.log('  2. Run: /refacil:setup');
   console.log('     (generates AGENTS.md for your project)\n');
@@ -368,12 +502,29 @@ function init() {
 function update() {
   console.log('\n  refacil-sdd-ai: Updating skills...\n');
 
-  const count = installSkills(packageRoot, projectRoot);
-  console.log(`  ${count} skills updated in .claude/skills/ and .cursor/skills/`);
+  // Detect installed IDEs by folder presence
+  const hasClaudeDir = fs.existsSync(path.join(projectRoot, '.claude'));
+  const hasCursorDir = fs.existsSync(path.join(projectRoot, '.cursor'));
+  const hasOpenCodeDir = fs.existsSync(path.join(projectRoot, '.opencode'));
 
-  const agentsCount = installAgents(packageRoot, projectRoot);
+  const detectedIDEs = [
+    hasClaudeDir && '.claude',
+    hasCursorDir && '.cursor',
+    hasOpenCodeDir && '.opencode',
+  ].filter(Boolean);
+
+  const count = installSkills(packageRoot, projectRoot, detectedIDEs);
+  const installedDirs = detectedIDEs.map((d) => `${d}/skills/`);
+  console.log(`  ${count} skills updated in ${installedDirs.join(', ') || '(none detected)'}`);
+
+  const agentsCount = installAgents(packageRoot, projectRoot, detectedIDEs);
   if (agentsCount > 0) {
-    console.log(`  ${agentsCount} sub-agents updated in .claude/agents/ and .cursor/agents/`);
+    const agentDirs = [
+      hasClaudeDir && '.claude/agents/',
+      hasCursorDir && '.cursor/agents/',
+      hasOpenCodeDir && '.opencode/agents/',
+    ].filter(Boolean);
+    console.log(`  ${agentsCount} sub-agents updated in ${agentDirs.join(', ')}`);
   }
 
   try {
@@ -387,25 +538,42 @@ function update() {
 
   writeRepoVersion(projectRoot, getPackageVersion(packageRoot));
 
-  createClaudeMd(packageRoot, projectRoot);
-  createCursorRules(packageRoot, projectRoot);
+  if (hasClaudeDir) {
+    createClaudeMd(packageRoot, projectRoot);
+    if (installHooks('.claude', projectRoot)) {
+      console.log('  Hook check-update added to .claude/settings.json');
+    }
+  }
 
-  if (installHooks('.claude', projectRoot)) {
-    console.log('  Hook check-update added to .claude/settings.json');
+  if (hasCursorDir) {
+    createCursorRules(packageRoot, projectRoot);
+    if (installHooks('.cursor', projectRoot)) {
+      console.log('  Hook check-update added to .cursor/hooks.json');
+    }
   }
-  if (installHooks('.cursor', projectRoot)) {
-    console.log('  Hook check-update added to .cursor/settings.json');
+
+  if (hasOpenCodeDir) {
+    try {
+      installOpenCodeJson(projectRoot);
+    } catch (err) {
+      console.error(`  Warning: could not update opencode.json: ${err.message}`);
+    }
+    if (installHooks('.opencode', projectRoot)) {
+      console.log('  OpenCode plugin updated at .opencode/plugins/refacil-hooks.js');
+    }
   }
 
   try {
-    const ignoreResult = syncIgnoreFiles(projectRoot);
-    const s = ignoreResult.claude;
-    if (s.status === 'created') {
-      console.log('  .claudeignore and .cursorignore created');
-    } else if (s.status === 'updated') {
-      console.log(`  .claudeignore and .cursorignore updated (${s.added} entries added)`);
-    } else {
-      console.log('  .claudeignore and .cursorignore are up to date');
+    const IDE_TO_IGNORE = { '.claude': '.claudeignore', '.cursor': '.cursorignore', '.opencode': '.opencodeignore' };
+    const ignoreResult = syncIgnoreFiles(projectRoot, detectedIDEs);
+    const ignoreNames = detectedIDEs.map((d) => IDE_TO_IGNORE[d]).filter(Boolean).join(', ');
+    const s = ignoreResult.claude || ignoreResult.cursor || ignoreResult.opencode;
+    if (s && s.status === 'created') {
+      console.log(`  ${ignoreNames} created`);
+    } else if (s && s.status === 'updated') {
+      console.log(`  ${ignoreNames} updated (${s.added} entries added)`);
+    } else if (ignoreNames) {
+      console.log(`  ${ignoreNames} are up to date`);
     }
   } catch (err) {
     console.error(`  Warning: could not sync ignore files: ${err.message}`);
@@ -422,7 +590,7 @@ function update() {
     console.error(`  Warning: could not sync compact-guidance: ${err.message}`);
   }
 
-  console.log('\n  RESTART your Claude Code or Cursor session to apply the changes.\n');
+  console.log('\n  RESTART your IDE session to apply the changes.\n');
 }
 
 function clean() {
@@ -440,6 +608,19 @@ function clean() {
     console.log('  SDD-AI hooks removed from .cursor/settings.json');
   }
 
+  // Clean OpenCode artifacts if .opencode/ directory is present
+  if (fs.existsSync(path.join(projectRoot, '.opencode'))) {
+    try {
+      removeOpenCodeArtifacts(projectRoot);
+      console.log('  OpenCode skills and agents removed from .opencode/');
+    } catch (err) {
+      console.error(`  Warning: could not remove OpenCode artifacts: ${err.message}`);
+    }
+    if (uninstallOpenCodePlugin(projectRoot)) {
+      console.log('  OpenCode plugin removed from .opencode/plugins/');
+    }
+  }
+
   try {
     const result = removeCompactGuidance(projectRoot);
     if (result.status === 'removed') {
@@ -460,8 +641,10 @@ function help() {
   refacil-sdd-ai — SDD-AI Methodology
 
   Commands:
-    init          Install skills in .claude/ and .cursor/, create CLAUDE.md and .cursorrules
-    update        Re-copy skills (to update to a new package version)
+    init          Install skills in .claude/, .cursor/ and/or .opencode/ (interactive IDE selector).
+                  Use --all to install for all three IDEs without prompting.
+                  Creates CLAUDE.md, .cursorrules and .opencode/opencode.json as appropriate.
+    update        Re-copy skills for all detected IDEs (.claude/, .cursor/, .opencode/)
     migration-pending  Same validation as hooks/notify-update: list migrations (exit 1 if any; --json)
     check-update   Sync skills and compact-guidance at session start (SessionStart hook)
     notify-update  Notify methodology migration only if applicable (UserPromptSubmit hook)
@@ -496,18 +679,24 @@ function help() {
                     sdd mark-reviewed <name>       Write .review-passed (requires --verdict and --summary)
                     sdd tasks-update <name>        Mark task N as completed (--task N --done)
                     sdd validate-name <name>       Validate change name format
-    clean         Remove skills and SDD-AI hooks from .claude/settings.json and .cursor/settings.json
+    clean         Remove skills and SDD-AI hooks from all detected IDEs
+                  (.claude/settings.json, .cursor/hooks.json, .opencode/plugins/)
     help          Show this help
 
   Full flow:
     1. npm install -g refacil-sdd-ai
     2. refacil-sdd-ai init
-    3. RESTART the Claude Code or Cursor session
+    3. RESTART your IDE session (Claude Code, Cursor, or OpenCode)
     4. Run: /refacil:setup (generates AGENTS.md for your project)
 
+  IDE support:
+    - Claude Code: .claude/skills/, .claude/agents/, .claude/settings.json hooks
+    - Cursor:      .cursor/skills/, .cursor/agents/, .cursor/hooks.json hooks
+    - OpenCode:    .opencode/skills/, .opencode/agents/, .opencode/plugins/refacil-hooks.js
+
   Requirements:
     - Node.js >= 20.0.0
-    - Claude Code >= 2.1.89 (required by compact-bash for silent rewrite) or Cursor
+    - Claude Code >= 2.1.89 (required by compact-bash for silent rewrite), Cursor, or OpenCode
   `);
 }
 
@@ -522,7 +711,10 @@ if (command === '--version' || command === '-v') {
 
 switch (command) {
   case 'init':
-    init();
+    init().catch((err) => {
+      console.error(`  Error during init: ${err.message}`);
+      process.exit(1);
+    });
     break;
   case 'update':
     update();

package/lib/hooks.js

@@ -219,18 +219,54 @@ function cleanLegacySettingsHooks(projectRoot) {
   }
 }
 
+// ── OpenCode: plugin file ────────────────────────────────────────────────────
+
+function installOpenCodePlugin(projectRoot) {
+  const pluginsDir = path.join(projectRoot, '.opencode', 'plugins');
+  fs.mkdirSync(pluginsDir, { recursive: true });
+
+  const srcPlugin = path.join(__dirname, 'opencode-plugin', 'index.js');
+  const destPlugin = path.join(pluginsDir, 'refacil-hooks.js');
+
+  try {
+    fs.copyFileSync(srcPlugin, destPlugin);
+    return true;
+  } catch (err) {
+    process.stderr.write(`[refacil-sdd-ai] Could not install OpenCode plugin: ${err.message}\n`);
+    return false;
+  }
+}
+
+function uninstallOpenCodePlugin(projectRoot) {
+  const pluginPath = path.join(projectRoot, '.opencode', 'plugins', 'refacil-hooks.js');
+  if (!fs.existsSync(pluginPath)) return false;
+  try {
+    fs.unlinkSync(pluginPath);
+    return true;
+  } catch (err) {
+    process.stderr.write(`[refacil-sdd-ai] Could not remove OpenCode plugin: ${err.message}\n`);
+    return false;
+  }
+}
+
 // ── Fachada pública ──────────────────────────────────────────────────────────
 
 function installHooks(ideDir, projectRoot) {
-  return ideDir === '.cursor'
-    ? installCursorHooks(projectRoot)
-    : installClaudeHooks(projectRoot);
+  if (ideDir === '.cursor') return installCursorHooks(projectRoot);
+  if (ideDir === '.opencode') return installOpenCodePlugin(projectRoot);
+  return installClaudeHooks(projectRoot);
 }
 
 function uninstallHooks(ideDir, projectRoot) {
-  return ideDir === '.cursor'
-    ? uninstallCursorHooks(projectRoot)
-    : uninstallClaudeHooks(projectRoot);
+  if (ideDir === '.cursor') return uninstallCursorHooks(projectRoot);
+  if (ideDir === '.opencode') return uninstallOpenCodePlugin(projectRoot);
+  return uninstallClaudeHooks(projectRoot);
 }
 
-module.exports = { installHooks, uninstallHooks, cleanLegacySettingsHooks };
+module.exports = {
+  installHooks,
+  uninstallHooks,
+  cleanLegacySettingsHooks,
+  installOpenCodePlugin,
+  uninstallOpenCodePlugin,
+};

package/lib/ignore-files.js

@@ -79,10 +79,19 @@ function syncIgnoreFile(filePath) {
   return { status: 'updated', added: missing.length };
 }
 
-function syncIgnoreFiles(projectRoot) {
-  const claude = syncIgnoreFile(path.join(projectRoot, '.claudeignore'));
-  const cursor = syncIgnoreFile(path.join(projectRoot, '.cursorignore'));
-  return { claude, cursor };
+function syncIgnoreFiles(projectRoot, ideDirs) {
+  const dirs = ideDirs || ['.claude', '.cursor', '.opencode'];
+  const result = {};
+  if (dirs.includes('.claude')) {
+    result.claude = syncIgnoreFile(path.join(projectRoot, '.claudeignore'));
+  }
+  if (dirs.includes('.cursor')) {
+    result.cursor = syncIgnoreFile(path.join(projectRoot, '.cursorignore'));
+  }
+  if (dirs.includes('.opencode')) {
+    result.opencode = syncIgnoreFile(path.join(projectRoot, '.opencodeignore'));
+  }
+  return result;
 }
 
 module.exports = { syncIgnoreFiles, BASE_ENTRIES };

package/lib/installer.js

@@ -35,7 +35,18 @@ const AGENTS = [
   'proposer',
 ];
 
-const REPO_VERSION_FILES = ['.claude/.sdd-version', '.cursor/.sdd-version'];
+// All 7 refacil agents are internal sub-agents — hidden from the agent picker in OpenCode
+const INTERNAL_AGENTS = [
+  'investigator',
+  'validator',
+  'auditor',
+  'tester',
+  'implementer',
+  'debugger',
+  'proposer',
+];
+
+const REPO_VERSION_FILES = ['.claude/.sdd-version', '.cursor/.sdd-version', '.opencode/.sdd-version'];
 
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -51,23 +62,59 @@ function copyDir(src, dest) {
   }
 }
 
-function installSkills(packageRoot, projectRoot) {
+function installSkills(packageRoot, projectRoot, ideDirs) {
+  const dirs = ideDirs || ['.claude', '.cursor', '.opencode'];
   let installed = 0;
   for (const skill of SKILLS) {
     const srcDir = path.join(packageRoot, 'skills', skill);
     if (!fs.existsSync(srcDir)) continue;
 
-    const claudeDest = path.join(projectRoot, '.claude', 'skills', `refacil-${skill}`);
-    copyDir(srcDir, claudeDest);
-
-    const cursorDest = path.join(projectRoot, '.cursor', 'skills', `refacil-${skill}`);
-    copyDir(srcDir, cursorDest);
+    if (dirs.includes('.claude')) {
+      copyDir(srcDir, path.join(projectRoot, '.claude', 'skills', `refacil-${skill}`));
+    }
+    if (dirs.includes('.cursor')) {
+      copyDir(srcDir, path.join(projectRoot, '.cursor', 'skills', `refacil-${skill}`));
+    }
+    if (dirs.includes('.opencode')) {
+      // OpenCode: byte-for-byte copy (same as Claude Code — no transformation needed)
+      copyDir(srcDir, path.join(projectRoot, '.opencode', 'skills', `refacil-${skill}`));
+    }
 
     installed++;
   }
   return installed;
 }
 
+// Create or safely merge .opencode/opencode.json with SDD-AI managed keys
+// Preserves any pre-existing keys — never destructive
+function installOpenCodeJson(projectRoot) {
+  const ocDir = path.join(projectRoot, '.opencode');
+  fs.mkdirSync(ocDir, { recursive: true });
+  const ocJsonPath = path.join(ocDir, 'opencode.json');
+
+  let existing = {};
+  if (fs.existsSync(ocJsonPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(ocJsonPath, 'utf8'));
+    } catch (_) {
+      existing = {};
+    }
+  }
+
+  // SDD-AI managed keys (minimal — only $schema)
+  const sddKeys = {
+    '$schema': 'https://opencode.ai/config.json',
+  };
+
+  const merged = Object.assign({}, sddKeys, existing);
+  // Ensure $schema is always the SDD-AI value if not already set by user
+  if (!existing['$schema']) {
+    merged['$schema'] = sddKeys['$schema'];
+  }
+
+  fs.writeFileSync(ocJsonPath, JSON.stringify(merged, null, 2) + '\n');
+}
+
 // Claude Code: tools allowlist granular, model: sonnet|opus|haiku
 // Cursor: readonly: true|false (booleano), model: inherit (default)
 function transformFrontmatterForCursor(content) {
@@ -113,13 +160,72 @@ function transformFrontmatterForCursor(content) {
   return `---\n${out.join('\n')}\n---\n${body}`;
 }
 
-function installAgents(packageRoot, projectRoot) {
+// OpenCode: tools → permission mapping, adds mode: subagent, hidden: true for internal agents, removes model:
+// tools:[Edit,Write,NotebookEdit] → edit:allow, tools:[Bash] → bash:allow, WebFetch → always deny
+function transformFrontmatterForOpenCode(content) {
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return content;
+
+  const [, frontmatterRaw, body] = match;
+  const lines = frontmatterRaw.split('\n');
+  const out = [];
+  let toolsLine = null;
+  let agentName = null;
+
+  for (const line of lines) {
+    if (line.startsWith('tools:')) {
+      toolsLine = line;
+      // Do not emit tools: line — OpenCode uses permission block instead
+      continue;
+    }
+    if (line.startsWith('model:')) {
+      // Remove model: line — OpenCode manages model selection separately
+      continue;
+    }
+    if (line.startsWith('name:')) {
+      const nameVal = line.slice('name:'.length).trim();
+      // Extract the base agent name from "refacil-<name>" or plain "<name>"
+      const nameMatch = nameVal.match(/refacil-(\S+)/);
+      agentName = nameMatch ? nameMatch[1] : nameVal;
+      out.push(line);
+      continue;
+    }
+    out.push(line);
+  }
+
+  // Determine permission values from tools list
+  const toolsList = toolsLine ? toolsLine.slice('tools:'.length).trim() : '';
+  const canEdit = /\b(Edit|Write|NotebookEdit)\b/.test(toolsList);
+  const canBash = /\bBash\b/.test(toolsList);
+
+  // Build permission block
+  out.push(`permission:`);
+  out.push(`  edit: ${canEdit ? 'allow' : 'deny'}`);
+  out.push(`  bash: ${canBash ? 'allow' : 'deny'}`);
+  out.push(`  webfetch: deny`);
+
+  // Add mode: subagent
+  out.push(`mode: subagent`);
+
+  // Add hidden: true for internal agents
+  if (agentName && INTERNAL_AGENTS.includes(agentName)) {
+    out.push(`hidden: true`);
+  }
+
+  return `---\n${out.join('\n')}\n---\n${body}`;
+}
+
+function installAgents(packageRoot, projectRoot, ideDirs) {
+  const dirs = ideDirs || ['.claude', '.cursor', '.opencode'];
   let installed = 0;
 
   const claudeDir = path.join(projectRoot, '.claude', 'agents');
   const cursorDir = path.join(projectRoot, '.cursor', 'agents');
-  fs.mkdirSync(claudeDir, { recursive: true });
-  fs.mkdirSync(cursorDir, { recursive: true });
+  const openCodeDir = path.join(projectRoot, '.opencode', 'agents');
+  if (dirs.includes('.claude')) fs.mkdirSync(claudeDir, { recursive: true });
+  if (dirs.includes('.cursor')) fs.mkdirSync(cursorDir, { recursive: true });
+  if (dirs.includes('.opencode')) fs.mkdirSync(openCodeDir, { recursive: true });
 
   for (const agent of AGENTS) {
     const srcFile = path.join(packageRoot, 'agents', `${agent}.md`);
@@ -127,11 +233,21 @@ function installAgents(packageRoot, projectRoot) {
 
     const content = fs.readFileSync(srcFile, 'utf8');
 
-    fs.writeFileSync(path.join(claudeDir, `refacil-${agent}.md`), content);
-    fs.writeFileSync(
-      path.join(cursorDir, `refacil-${agent}.md`),
-      transformFrontmatterForCursor(content),
-    );
+    if (dirs.includes('.claude')) {
+      fs.writeFileSync(path.join(claudeDir, `refacil-${agent}.md`), content);
+    }
+    if (dirs.includes('.cursor')) {
+      fs.writeFileSync(
+        path.join(cursorDir, `refacil-${agent}.md`),
+        transformFrontmatterForCursor(content),
+      );
+    }
+    if (dirs.includes('.opencode')) {
+      fs.writeFileSync(
+        path.join(openCodeDir, `refacil-${agent}.md`),
+        transformFrontmatterForOpenCode(content),
+      );
+    }
 
     installed++;
   }
@@ -139,6 +255,50 @@ function installAgents(packageRoot, projectRoot) {
   return installed;
 }
 
+function removeOpenCodeArtifacts(projectRoot) {
+  // Remove .opencode/skills/refacil-*/
+  for (const skill of SKILLS) {
+    const skillDir = path.join(projectRoot, '.opencode', 'skills', `refacil-${skill}`);
+    if (fs.existsSync(skillDir)) {
+      try { fs.rmSync(skillDir, { recursive: true }); } catch (_) {}
+    }
+  }
+
+  // Remove .opencode/agents/refacil-*.md
+  const agentsDir = path.join(projectRoot, '.opencode', 'agents');
+  if (fs.existsSync(agentsDir)) {
+    try {
+      const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.startsWith('refacil-') && entry.name.endsWith('.md')) {
+          fs.unlinkSync(path.join(agentsDir, entry.name));
+        }
+      }
+    } catch (_) {}
+  }
+
+  // Remove .opencode/plugins/refacil-hooks.js
+  const pluginFile = path.join(projectRoot, '.opencode', 'plugins', 'refacil-hooks.js');
+  if (fs.existsSync(pluginFile)) {
+    try { fs.unlinkSync(pluginFile); } catch (_) {}
+  }
+
+  // Revert SDD-AI keys from .opencode/opencode.json (currently only $schema key, leave file if other keys remain)
+  const ocJsonPath = path.join(projectRoot, '.opencode', 'opencode.json');
+  if (fs.existsSync(ocJsonPath)) {
+    try {
+      const json = JSON.parse(fs.readFileSync(ocJsonPath, 'utf8'));
+      delete json['$schema'];
+      const remaining = Object.keys(json);
+      if (remaining.length === 0) {
+        fs.unlinkSync(ocJsonPath);
+      } else {
+        fs.writeFileSync(ocJsonPath, JSON.stringify(json, null, 2) + '\n');
+      }
+    } catch (_) {}
+  }
+}
+
 function writeGuideFile(destPath, header, label) {
   const content =
     `# ${header}\n\n` +
@@ -309,10 +469,14 @@ function checkNodeVersion() {
 module.exports = {
   SKILLS,
   AGENTS,
+  INTERNAL_AGENTS,
   copyDir,
   installSkills,
+  installOpenCodeJson,
   transformFrontmatterForCursor,
+  transformFrontmatterForOpenCode,
   installAgents,
+  removeOpenCodeArtifacts,
   createClaudeMd,
   createCursorRules,
   readRepoVersion,

package/lib/opencode-plugin/index.js

@@ -0,0 +1,262 @@
+'use strict';
+
+/**
+ * refacil-sdd-ai OpenCode plugin
+ *
+ * Provides 4 hook equivalents for OpenCode:
+ *   - session.created       → check-update logic (sync compact-guidance, flag pending migrations)
+ *   - tui.prompt.append     → notify-update logic (prompt user to run /refacil:update if pending)
+ *   - tool.execute.before   → check-review + compact-bash logic
+ *
+ * This file is installed as .opencode/plugins/refacil-hooks.js.
+ * It resolves lib/compact/rules.js relative to its own __dirname at install time.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// ── Resolve compact rules ────────────────────────────────────────────────────
+// When installed, this file lives at .opencode/plugins/refacil-hooks.js.
+// The compact rules live at <package>/lib/compact/rules.js.
+// We walk up from __dirname looking for the package (node_modules/refacil-sdd-ai or
+// the package root directly), falling back gracefully if not found.
+
+let findRule = null;
+
+(function loadCompactRules() {
+  const candidates = [
+    // Installed as plugin in .opencode/plugins/ — package is in node_modules
+    path.resolve(__dirname, '..', '..', 'node_modules', 'refacil-sdd-ai', 'lib', 'compact', 'rules.js'),
+    // Running from source (lib/opencode-plugin/index.js)
+    path.resolve(__dirname, '..', 'compact', 'rules.js'),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) {
+        const rules = require(candidate);
+        if (typeof rules.findRule === 'function') {
+          findRule = rules.findRule;
+          break;
+        }
+      }
+    } catch (_) {
+      // Try next candidate
+    }
+  }
+
+  if (!findRule) {
+    process.stderr.write('[refacil-sdd-ai] WARNING: Could not load compact/rules.js — compact-bash hook disabled.\n');
+  }
+})();
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function getPendingUpdateFlagPath(projectRoot) {
+  return path.join(projectRoot, '.refacil-pending-update');
+}
+
+function readPendingUpdateFlag(projectRoot) {
+  const flagPath = getPendingUpdateFlagPath(projectRoot);
+  if (!fs.existsSync(flagPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(flagPath, 'utf8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+function writePendingUpdateFlag(projectRoot, from, to) {
+  try {
+    fs.writeFileSync(getPendingUpdateFlagPath(projectRoot), JSON.stringify({ from, to }));
+  } catch (_) {}
+}
+
+function clearPendingUpdateFlag(projectRoot) {
+  try {
+    const flagPath = getPendingUpdateFlagPath(projectRoot);
+    if (fs.existsSync(flagPath)) fs.unlinkSync(flagPath);
+  } catch (_) {}
+}
+
+function readRepoVersion(projectRoot) {
+  const versionFiles = ['.opencode/.sdd-version', '.claude/.sdd-version', '.cursor/.sdd-version'];
+  for (const rel of versionFiles) {
+    try {
+      const raw = fs.readFileSync(path.join(projectRoot, rel), 'utf8').trim();
+      if (raw) return raw;
+    } catch (_) {}
+  }
+  return null;
+}
+
+function methodologyMigrationPending(projectRoot) {
+  // Look for refacil-sdd/changes with active (non-archived) tasks that still have pending migrations
+  // This is a lightweight check: look for changes that have tasks.md but no .review-passed
+  const changesDir = path.join(projectRoot, 'refacil-sdd', 'changes');
+  if (!fs.existsSync(changesDir)) return { pending: false, reasons: [] };
+
+  let entries;
+  try {
+    entries = fs.readdirSync(changesDir, { withFileTypes: true });
+  } catch (_) {
+    return { pending: false, reasons: [] };
+  }
+
+  const reasons = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === 'archive') continue;
+    const tasksPath = path.join(changesDir, entry.name, 'tasks.md');
+    const tasksContent = fs.existsSync(tasksPath) ? fs.readFileSync(tasksPath, 'utf8') : '';
+    // Look for unchecked tasks: "- [ ]" pattern
+    if (/- \[ \]/.test(tasksContent)) {
+      reasons.push(`Change '${entry.name}' has pending tasks`);
+    }
+  }
+
+  return { pending: reasons.length > 0, reasons };
+}
+
+// ── Hook handlers ────────────────────────────────────────────────────────────
+
+/**
+ * session.created — equivalent of check-update (SessionStart hook)
+ * Checks if the installed skills are out of date and flags a pending update.
+ */
+async function checkUpdateHandler(event) {
+  const projectRoot = event.projectRoot || process.cwd();
+
+  // Check if there is a pending methodology migration
+  try {
+    const mig = methodologyMigrationPending(projectRoot);
+    const repoVersion = readRepoVersion(projectRoot);
+
+    // Try to get the current package version via refacil-sdd-ai CLI
+    let packageVersion = null;
+    try {
+      const { execSync } = require('child_process');
+      packageVersion = execSync('refacil-sdd-ai --version', {
+        encoding: 'utf8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+    } catch (_) {}
+
+    const existingFlag = readPendingUpdateFlag(projectRoot);
+
+    if (mig.pending) {
+      writePendingUpdateFlag(projectRoot, repoVersion, packageVersion);
+    } else if (existingFlag) {
+      clearPendingUpdateFlag(projectRoot);
+    }
+  } catch (err) {
+    process.stderr.write(`[refacil-sdd-ai] check-update handler error: ${err.message}\n`);
+  }
+}
+
+/**
+ * tui.prompt.append — equivalent of notify-update (UserPromptSubmit hook)
+ * Returns an instruction string if there is a pending update, otherwise returns nothing.
+ * Also clears the flag if the user is running /refacil:update.
+ */
+async function notifyUpdateHandler(event) {
+  const projectRoot = event.projectRoot || process.cwd();
+  const prompt = (event.prompt || '').trim().toLowerCase();
+
+  // If user is running /refacil:update, clear the flag and let it through
+  if (prompt.includes('refacil:update') || prompt.includes('refacil/update')) {
+    clearPendingUpdateFlag(projectRoot);
+    return;
+  }
+
+  const flagInfo = readPendingUpdateFlag(projectRoot);
+  if (!flagInfo) return;
+
+  const mig = methodologyMigrationPending(projectRoot);
+  if (!mig.pending) {
+    clearPendingUpdateFlag(projectRoot);
+    return;
+  }
+
+  const fromLabel = flagInfo.from ? `v${flagInfo.from}` : 'previous version';
+  const toLabel = flagInfo.to ? `v${flagInfo.to}` : 'latest';
+
+  return (
+    `[refacil-sdd-ai] Methodology update detected (${fromLabel} → ${toLabel}). ` +
+    `Run /refacil:update to apply pending migrations before continuing.`
+  );
+}
+
+/**
+ * tool.execute.before — handles Bash tool calls:
+ *   (a) check-review: blocks git push if any active change is missing .review-passed
+ *   (b) compact-bash: rewrites matched commands to reduce token usage
+ */
+async function toolExecuteBeforeHandler(event) {
+  // Only handle Bash tool calls
+  if (!event || !event.tool || event.tool !== 'bash') return;
+
+  const command = (event.input && event.input.command) || (event.params && event.params.command) || '';
+  if (!command) return;
+
+  const projectRoot = event.projectRoot || process.cwd();
+
+  // (a) check-review: block git push if missing .review-passed
+  if (/git\s+push/.test(command)) {
+    const sddChangesDir = path.join(projectRoot, 'refacil-sdd', 'changes');
+    if (fs.existsSync(sddChangesDir)) {
+      let entries;
+      try {
+        entries = fs.readdirSync(sddChangesDir, { withFileTypes: true });
+      } catch (_) {
+        entries = [];
+      }
+
+      const activeChanges = entries.filter(
+        (e) => e.isDirectory() && e.name !== 'archive',
+      );
+
+      if (activeChanges.length > 0) {
+        const missing = activeChanges.filter(
+          (e) => !fs.existsSync(path.join(sddChangesDir, e.name, '.review-passed')),
+        );
+
+        if (missing.length > 0) {
+          const names = missing.map((e) => e.name).join(', ');
+          const reason =
+            missing.length === 1
+              ? `[refacil-sdd-ai] Review pending for: ${names}. ` +
+                'Stop the push and run /refacil:review on that change before pushing code. ' +
+                'If the review passes, retry the git push.'
+              : `[refacil-sdd-ai] Multiple changes without approved review: ${names}. ` +
+                'Stop the push and ask the user to explicitly select which change they want to push. ' +
+                'Then run /refacil:review <change-name> for that specific change and retry the push.';
+
+          throw new Error(reason);
+        }
+      }
+    }
+  }
+
+  // (b) compact-bash: rewrite matched commands to reduce token usage
+  // Skip if COMPACT=0 is set or findRule is not available
+  if (!findRule) return;
+  if (/\bCOMPACT=0\b/.test(command)) return;
+
+  const rule = findRule(command);
+  if (!rule) return;
+
+  const rewritten = rule.rewrite(command);
+  // Return the rewritten command for OpenCode to use instead
+  return { command: rewritten };
+}
+
+// ── Plugin export ────────────────────────────────────────────────────────────
+
+module.exports = {
+  hooks: {
+    'session.created': checkUpdateHandler,
+    'tui.prompt.append': notifyUpdateHandler,
+    'tool.execute.before': toolExecuteBeforeHandler,
+  },
+};

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "4.4.1",
-  "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code and Cursor",
+  "version": "4.5.1",
+  "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code, Cursor and OpenCode",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"
   },
   "files": [
     "bin/",
     "lib/",
+    "lib/opencode-plugin/",
     "skills/",
     "agents/",
     "templates/",
@@ -35,9 +36,12 @@
     "node": ">=20.0.0"
   },
   "scripts": {
-    "test": "node --test test/hooks.test.js test/installer.test.js test/ignore-files.test.js test/methodology-migration-pending.test.js test/sdd.test.js test/refactor-integrar-openspec-nativo.test.js test/refactor-rutas-refacil-sdd.test.js test/refactor-agents-english.test.js test/remove-openspec-legacy.test.js test/find-project-root.test.js"
+    "test": "node --test test/hooks.test.js test/installer.test.js test/ignore-files.test.js test/methodology-migration-pending.test.js test/sdd.test.js test/refactor-integrar-openspec-nativo.test.js test/refactor-rutas-refacil-sdd.test.js test/refactor-agents-english.test.js test/remove-openspec-legacy.test.js test/find-project-root.test.js test/opencode-installer.test.js test/opencode-plugin.test.js"
   },
   "dependencies": {
     "ws": "^8.18.0"
+  },
+  "optionalDependencies": {
+    "@clack/prompts": "^0.9.0"
   }
 }