refacil-sdd-ai 4.5.0 → 4.5.2

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
@@ -36,6 +38,18 @@ refacil-sdd-ai init
 #    Generates AGENTS.md and the .agents/ directory for the project
 ```
 
+### Adding a new IDE to an existing installation
+
+If you already have the methodology installed for Claude Code or Cursor and want to add OpenCode (or any other IDE), just run `init` again from the repo root:
+
+```bash
+refacil-sdd-ai init
+```
+
+The selector will pre-select the IDEs whose folders already exist (`.claude/`, `.cursor/`). Check the new IDE you want to add (e.g. OpenCode), leave the existing ones checked, and confirm — only the newly selected IDE will receive files; existing installations are refreshed in place.
+
+> **`update` does not add new IDEs** — it only updates IDEs already installed. Use `init` to add a new one.
+
 ### Update
 
 ```bash
@@ -43,23 +57,15 @@ 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
 ```
 
-### Legacy `openspec/` directory
-
-Older repos may still have **`openspec/changes/`**. The package **migrates automatically** to **`refacil-sdd/`** the first time you run any **`refacil-sdd-ai sdd …`** subcommand or when **`check-update`** runs at session start. After you confirm the tree under **`refacil-sdd/`**, you can remove the leftover **`openspec/`** folder.
-
-Some teams still install the **OpenSpec CLI** for **`opsx:*`** commands; those can coexist with SDD-AI. The **supported** path for changes, review markers, and archiving is **`refacil-sdd/`** plus **`refacil-sdd-ai sdd`** and **`/refacil:*`** skills.
-
----
-
 ## CLI Commands
 
 ### Package management
@@ -133,7 +139,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 +176,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 +265,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 |
 
-All four hooks are installed in `.claude/settings.json` (Claude Code) and `.cursor/settings.json` (Cursor) with the same parametric logic.
+| 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. |
+
+> **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 +419,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 +466,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/bin/cli.js

@@ -207,7 +207,8 @@ async function selectIDEs() {
     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 })),
+      options: options.map((o) => ({ label: o.label, value: o.value })),
+      initialValues: options.filter((o) => o.selected).map((o) => o.value),
       required: false,
     });
     if (clack.isCancel(result)) {
@@ -466,14 +467,16 @@ async function init() {
   }
 
   try {
-    const ignoreResult = syncIgnoreFiles(projectRoot);
-    const s = ignoreResult.claude;
-    if (s.status === 'created') {
-      console.log('  .claudeignore, .cursorignore and .opencodeignore created');
-    } else if (s.status === 'updated') {
-      console.log(`  .claudeignore, .cursorignore and .opencodeignore updated (${s.added} entries added)`);
-    } else {
-      console.log('  .claudeignore, .cursorignore and .opencodeignore 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}`);
@@ -562,14 +565,16 @@ function update() {
   }
 
   try {
-    const ignoreResult = syncIgnoreFiles(projectRoot);
-    const s = ignoreResult.claude;
-    if (s.status === 'created') {
-      console.log('  .claudeignore, .cursorignore and .opencodeignore created');
-    } else if (s.status === 'updated') {
-      console.log(`  .claudeignore, .cursorignore and .opencodeignore updated (${s.added} entries added)`);
-    } else {
-      console.log('  .claudeignore, .cursorignore and .opencodeignore 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}`);

package/lib/ignore-files.js

@@ -79,11 +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'));
-  const opencode = syncIgnoreFile(path.join(projectRoot, '.opencodeignore'));
-  return { claude, cursor, opencode };
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "4.5.0",
+  "version": "4.5.2",
   "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"
@@ -21,6 +21,7 @@
     "methodology",
     "claude-code",
     "cursor",
+    "opencode",
     "sdd",
     "specification-driven",
     "testing",