refacil-sdd-ai 5.0.10 → 5.1.1

package/README.md

@@ -89,10 +89,10 @@ npm uninstall -g refacil-sdd-ai
 
 | Command | Description |
 |---|---|
-| `refacil-sdd-ai init` | Install skills and hooks in the current repo |
-| `refacil-sdd-ai update` | Re-copy skills and hooks to the latest version |
+| `refacil-sdd-ai init` | Install skills and hooks into global IDE user directories |
+| `refacil-sdd-ai update` | Re-copy skills and hooks to the latest version (global) |
 | `refacil-sdd-ai migration-pending [--json]` | Same detection as hooks/`notify-update`; exit 1 if migration is pending; on exit 0 also deletes obsolete `.refacil-pending-update` (same as at the start of `check-update`) |
-| `refacil-sdd-ai clean` | Remove SDD-AI skills and hooks from the repo |
+| `refacil-sdd-ai clean` | Remove SDD-AI skills and hooks from global IDE user directories |
 | `refacil-sdd-ai help` | Show help |
 
 ### Internal hooks (invoked automatically — not for manual use)
@@ -184,7 +184,7 @@ refacil-sdd-ai sdd config --json
 
 > The `join/leave/say/ask/reply/attend/inbox` subcommands also exist as **IDE skills** (`/refacil:join`, etc.). In most cases use the skills; the CLI commands are for scripting or debugging.
 >
-> **Cross-repo coordination** (ask requests, room agreements, `/refacil:propose`, closing to the requester): after `init`, the file **`BUS-CROSS-REPO.md`** is available in `.claude/skills/refacil-prereqs/` and `.cursor/skills/refacil-prereqs/`.
+> **Cross-repo coordination** (ask requests, room agreements, `/refacil:propose`, closing to the requester): after `init`, the file **`BUS-CROSS-REPO.md`** is available in `~/.claude/skills/refacil-prereqs/` and `~/.cursor/skills/refacil-prereqs/`.
 
 ---
 
@@ -320,7 +320,7 @@ Installed during `init` / `update` for each selected IDE. The same four behavior
 
 | 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` |
+| **check-update** | `SessionStart` hook in `~/.claude/settings.json` | `SessionStart` hook in `~/.cursor/hooks.json` | `session.created` handler in the global OpenCode plugin |
 | **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 |
@@ -332,7 +332,7 @@ Installed during `init` / `update` for each selected IDE. The same four behavior
 | `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.
+> **OpenCode plugin**: a single file installed in the global OpenCode plugins directory 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.
 
@@ -470,31 +470,41 @@ Local bus (WebSocket over `127.0.0.1`) so agents across different repos can comm
 
 ---
 
-## What Gets Installed in Your Repo
+## What Gets Installed
 
-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.
+### Global user directories (once, shared across all repos)
+
+Skills, sub-agents, and hooks are installed into the user's global IDE directories — not into any project repo. Only the IDEs selected during `init` receive files.
 
 ```
 # 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 + notify-update + check-review + compact-bash
-.claude/.sdd-version         # Installed methodology version (used by check-update)
+~/.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        # SDD hooks merged in: check-update, notify-update, check-review, compact-bash
 
 # 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 + 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
+~/.cursor/skills/refacil-*/    # Cursor skills (auto-transformed frontmatter: readonly + model:inherit)
+~/.cursor/agents/refacil-*.md  # Cursor sub-agents (readonly:true/false + model:inherit, auto-generated)
+~/.cursor/hooks.json           # SDD hooks merged in (same four behaviors)
+
+# OpenCode (if selected)  — macOS/Linux: ~/.config/opencode/   Windows: %APPDATA%\opencode
+~/.config/opencode/skills/refacil-*/    # OpenCode skills
+~/.config/opencode/agents/refacil-*.md  # OpenCode sub-agents (permission block + mode:subagent)
+~/.config/opencode/plugins/refacil-hooks.js  # Plugin: session.created + tui.prompt.append + tool.execute.before
+
+# refacil-sdd-ai state
+~/.refacil-sdd-ai/
+  selected-ides.json           # IDE selection saved on init, reused by update
+  config.yaml                  # Global config: baseBranch, protectedBranches, artifactLanguage
+  sdd-version                  # Installed methodology version (used by check-update)
+```
+
+### Per repo (generated by `/refacil:setup`)
 
+The only per-repo step is running `/refacil:setup` once per project. It generates the project index — no IDE skills or hooks are written to the repo.
+
+```
 # Shared (IDE-agnostic)
 CLAUDE.md                    # Minimal index → points to AGENTS.md
 .cursorrules                 # Cursor format equivalent of CLAUDE.md
@@ -512,6 +522,8 @@ refacil-sdd/                 # SDD artifacts store
   specs/                     # Persistent specifications synced from archived changes
 ```
 
+> **Migration from project-level installs**: the `check-update` hook (SessionStart) automatically detects and removes any leftover project-level `refacil-*` skills, agents, hooks, and empty IDE directories from older versions.
+
 ---
 
 ## Technologies

package/lib/hooks.js

@@ -332,8 +332,8 @@ function removeProjectLevelHooks(projectRoot) {
   if (fs.existsSync(claudeSettingsPath)) {
     try {
       const settings = JSON.parse(fs.readFileSync(claudeSettingsPath, 'utf8'));
+      let changed = false;
       if (settings && settings.hooks) {
-        let changed = false;
         for (const event of Object.keys(settings.hooks)) {
           if (!Array.isArray(settings.hooks[event])) continue;
           const before = settings.hooks[event].length;
@@ -344,7 +344,16 @@ function removeProjectLevelHooks(projectRoot) {
           if (settings.hooks[event].length === 0) delete settings.hooks[event];
         }
         if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
-        if (changed) fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + '\n');
+      } else if (settings && Object.keys(settings).length === 0) {
+        // Already empty stub — treat as changed so it gets deleted below
+        changed = true;
+      }
+      if (changed) {
+        if (Object.keys(settings).length === 0) {
+          fs.unlinkSync(claudeSettingsPath);
+        } else {
+          fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + '\n');
+        }
       }
     } catch (_) {}
   }
@@ -386,6 +395,16 @@ function removeProjectLevelHooks(projectRoot) {
       }
     } catch (_) {}
   }
+
+  // Remove IDE root dirs if now empty (hooks cleanup may have been the last file)
+  for (const ideDir of ['.claude', '.cursor', '.opencode']) {
+    const idePath = path.join(projectRoot, ideDir);
+    try {
+      if (fs.existsSync(idePath) && fs.readdirSync(idePath).length === 0) {
+        fs.rmdirSync(idePath);
+      }
+    } catch (_) {}
+  }
 }
 
 // ── Fachada pública ──────────────────────────────────────────────────────────

package/lib/installer.js

@@ -356,13 +356,15 @@ function removeProjectLevelArtifacts(projectRoot) {
       fs.rmdirSync(ocPluginsDir);
     }
   } catch (_) {}
-  // Remove .opencode/ itself if now empty
-  const ocDir = path.join(projectRoot, '.opencode');
-  try {
-    if (fs.existsSync(ocDir) && fs.readdirSync(ocDir).length === 0) {
-      fs.rmdirSync(ocDir);
-    }
-  } catch (_) {}
+  // Remove IDE root dirs if now empty
+  for (const ideDir of ['.opencode', '.cursor', '.claude']) {
+    const idePath = path.join(projectRoot, ideDir);
+    try {
+      if (fs.existsSync(idePath) && fs.readdirSync(idePath).length === 0) {
+        fs.rmdirSync(idePath);
+      }
+    } catch (_) {}
+  }
 
   return removed;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "5.0.10",
+  "version": "5.1.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"