refacil-sdd-ai 5.2.2 → 5.3.0

package/skills/read-spec/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: refacil:read-spec
+description: Listen to SDD spec Markdown files in the browser with on-device TTS (Supertonic). Use after propose or on-demand for active changes and archived specs.
+user-invocable: true
+---
+
+# refacil:read-spec — Spec reader (TTS)
+
+Play a Markdown spec aloud in the local browser using on-device TTS. The CLI parses the file(s), stores a short-lived session on the broker, and opens `/read-spec`.
+
+**Prerequisites**: `sdd` profile from `refacil-prereqs/SKILL.md`.
+
+## CLI (always use this)
+
+Single file mode:
+```bash
+refacil-sdd-ai read-spec --file <path-relative-to-repo-root> [--lang es] [--voice M3] [--speed 1]
+```
+
+Folder mode (all SDD artifacts for a change in one browser panel with sidebar):
+```bash
+refacil-sdd-ai read-spec --change <changeName> [--select <file.md>] [--lang es] [--voice M3] [--speed 1]
+```
+
+- `--change <changeName>`: loads all `.md` files from `refacil-sdd/changes/<changeName>/` in order: `proposal.md → design.md → tasks.md → specs.md → (others alphabetically)`. Opens a sidebar for navigation between files.
+- `--select <file.md>`: pre-selects a specific file in the sidebar (default: `proposal.md`).
+- `--file` and `--change` are mutually exclusive.
+
+Defaults: `lang=es`, `voice=M3`, `speed=1`.
+
+## Post-propose flow (CA-24)
+
+The listen option is presented as **option B** in the `/refacil:propose` Step 3 review menu — handled directly by that skill. When the user selects B, run:
+
+```bash
+refacil-sdd-ai read-spec --change <changeName>
+```
+
+Language is auto-detected from the artifact content (no `--lang` flag needed). After playback, re-present the Step 3 review menu so the user can approve or request adjustments.
+
+## On-demand — archived specs only (CA-25)
+
+When there are **no** active folders under `refacil-sdd/changes/` (except `archive/`):
+
+1. Ask which archived spec folder under `refacil-sdd/specs/`.
+2. Run `read-spec --file refacil-sdd/specs/<name>/spec.md` (verify the folder exists first).
+
+## On-demand — active changes (CA-26)
+
+When there are active folders under `refacil-sdd/changes/`:
+
+1. List the active change names.
+2. Ask the user which change to listen to (and optionally which file to start from).
+3. Run:
+
+```bash
+refacil-sdd-ai read-spec --change <changeName> [--select <file.md>]
+```
+
+If the user specifies a particular file (e.g. "I want to hear specs.md"), add `--select specs.md`.
+
+## On-demand — active changes and archived (CA-27)
+
+When both active changes and `refacil-sdd/specs/` exist:
+
+1. Ask: open **change** or **archived spec**?
+2. List names from the chosen location.
+3. For a change: run `read-spec --change <changeName>` (with optional `--select`).
+4. For archived: `refacil-sdd/specs/<name>/spec.md` → run `read-spec --file <path>`.
+
+## Rules
+
+- Never send spec content to remote TTS APIs; only the CLI + local browser run.
+- If the path or change folder is missing, report clearly (CR-11, CR-12) — do not run the CLI silently.
+- `--file` must stay inside the project root (the CLI enforces this).
+- `--change` and `--file` are mutually exclusive — never pass both.

package/skills/reply/SKILL.md

@@ -15,7 +15,7 @@ Sends a response to the last question directed to this session. **$ARGUMENTS** =
 Run via `Bash`:
 
 ```bash
-refacil-sdd-ai bus reply --text "<response>"
+refacil-sdd-ai bus reply --text "[response]"
 ```
 
 The broker:
@@ -32,18 +32,51 @@ Report to the user that the response was sent.
 - **`reply`**: always when you are responding to something you were asked. This allows the other side in `ask --wait` to unblock automatically.
 - **`say`**: general announcement unrelated to a previous question.
 
+## Safe bus text delivery
+
+**Use `--text` for simple messages** (no special characters, single-line):
+```bash
+refacil-sdd-ai bus reply --text "Simple response here"
+```
+
+**Do NOT use `<` or `>` inside `--text`** — shells may interpret them as redirection operators and truncate or discard the message.
+
+For messages containing `<`, `>`, `|`, newlines, or other special characters, use `--from-env`:
+
+**PowerShell (Windows)**:
+```powershell
+$env:BUS_TEXT = "integrationPoint: POST /pay`noutputContract: {status<string>, id<uuid>}"
+refacil-sdd-ai bus reply --from-env BUS_TEXT
+Remove-Item Env:BUS_TEXT
+```
+
+**bash (inline, preferred — automatic cleanup)**:
+```bash
+BUS_TEXT="integrationPoint: POST /pay
+outputContract: {status<string>, id<uuid>}" refacil-sdd-ai bus reply --from-env BUS_TEXT
+```
+
+**bash (export + unset alternative)**:
+```bash
+export BUS_TEXT="response with <special> chars"
+refacil-sdd-ai bus reply --from-env BUS_TEXT
+unset BUS_TEXT
+```
+
+> Note: the CLI cannot perform cleanup itself — it runs as a child process and cannot modify the parent shell's environment. Cleanup (`Remove-Item` / `unset`) is the responsibility of the invoking script or shell.
+
 ## Contract-focused reply format (for integration questions)
 
 When replying to cross-repo integration clarifications, prefer this structure so the other side can continue without ambiguity:
 
 ```text
-integrationPoint: <confirmed endpoint/event/queue + direction>
-inputContract: <confirmed fields/validation>
-outputContract: <confirmed outputs/status/errors>
-compatibility: <version/constraints, or "unknown">
-sourceOfTruth: <file/path/symbol in this repo>
-confidence: <high|medium|low>
-openQuestions: <none | list of unresolved points>
+integrationPoint: [confirmed endpoint/event/queue + direction]
+inputContract: [confirmed fields/validation]
+outputContract: [confirmed outputs/status/errors]
+compatibility: [version/constraints, or "unknown"]
+sourceOfTruth: [file/path/symbol in this repo]
+confidence: [high|medium|low]
+openQuestions: [none | list of unresolved points]
 ```
 
 If you cannot confirm a field, answer with `unknown` and include the missing evidence in `openQuestions`.
@@ -57,5 +90,5 @@ If you cannot confirm a field, answer with `unknown` and include the missing evi
 - If there is no pending question directed to you and you do not want to link it, use `/refacil:say` instead.
 - If you were asked multiple questions and want to respond to a specific older one, pass `--correlation <id>` explicitly:
   ```bash
-  refacil-sdd-ai bus reply --text "..." --correlation <id>
+  refacil-sdd-ai bus reply --text "..." --correlation [id]
   ```

package/skills/review/SKILL.md

@@ -20,6 +20,8 @@ This skill is a **thin wrapper** that delegates the heavy review to the `refacil
   3) Uncommitted changes (`git diff`)
 - If there are multiple active changes in `refacil-sdd/changes/` and no `$ARGUMENTS`, **stop** and ask the user to explicitly select which change to review. **Do not invoke the sub-agent with ambiguous scope.**
 
+**Autopilot mode detection**: once `changeName` is resolved (and not null), try to read `refacil-sdd/.autopilot-active`. If the file exists and its `changeName` field matches → `autopilotMode = true`. Otherwise `autopilotMode = false` (normal mode, ask user as usual).
+
 ### Step 0.3: Git working tree snapshot (run once)
 
 After scope is unambiguous (you are **not** stopping for multiple active changes), collect git state **exactly once** for this skill invocation:
@@ -55,18 +57,26 @@ If `changeName` is not null, check whether `refacil-sdd/changes/<changeName>/.re
 
 ### Step 0.5: Build briefing for the sub-agent (reduces auditor tool calls)
 
-Before invoking the sub-agent, extract the context that the auditor would otherwise calculate on its own:
+Before invoking the sub-agent, extract the context that the auditor would otherwise calculate on its own.
+
+**3C criterion reference**: the auditor applies the 3D framework per **`METHODOLOGY-CONTRACT.md §3C — 3C Criterion: Completeness, Correctness, Coherence`** — include `codegraphAvailable` in the briefing so the auditor can use CodeGraph for Dimension 3 (Coherence) analysis when available. If `codegraphAvailable: true` and the change touches modules with high fan-out, `codegraph_impact` is recommended before approving (the auditor decides based on the briefing).
+
+**CodeGraph detection**: run `refacil-sdd-ai codegraph status --json` and extract:
+- `codegraphAvailable = true` if `installed === true` AND `initialized === true`
+- `codegraphAvailable = false` otherwise
 
 1. **Changed files** — use the scope resolved in Step 0.4 (`incrementalScope` if available, otherwise `changedFilesUnion`). Do not run `git diff` or `git status` again.
 
 2. **Project type** — read `package.json` (if it exists) and inspect the dependencies:
    - Backend indicators: `@nestjs/*`, `express`, `fastify`, `koa`, `typeorm`, `prisma`, `pg`, `mongoose`, `bullmq`, `amqplib`
    - Frontend indicators: `react`, `vue`, `angular`, `next`, `nuxt`, `svelte`, `vite`, `@tanstack/*`
-   - If both → `fullstack`; if only backend → `backend`; if only frontend → `frontend`; if no `package.json` or none applies → read the first 20 lines of `AGENTS.md` to infer.
+   - If both → `fullstack`; if only backend → `backend`; if only frontend → `frontend`.
+   - If `package.json` exists but none of the above apply (CLI/methodology package, minimal deps, no web/API framework) → `library`.
+   - If no `package.json` or still unclear → read the first 20 lines of `AGENTS.md` to infer.
 
 3. **Change objective** (only if there is an active change in `refacil-sdd/changes/`) — read the first section of `proposal.md`. Extract the objective in 1-2 sentences. If the scope is `git-diff` without an active change → `null`.
 
-4. **Cross-skill memory** — run `refacil-sdd-ai sdd get-memory <changeName> --json` and parse the JSON to extract `stackDetected` and `touchedFiles`. Include them in the briefing so the auditor skips re-discovery. If the command outputs `{}` or fails, omit — do not block (CR-04).
+4. **Cross-skill memory** — run `refacil-sdd-ai sdd get-memory <changeName> --json` and parse the JSON to extract `stackDetected`, `touchedFiles`, `commandsRun`, `criteriaRun`, and `lastStep`. Include them in the briefing so the auditor skips re-discovery and does **not** re-run the test suite (§3.2). If the command outputs `{}` or fails, omit — do not block (CR-04).
 
 5. **Mode** — default `concise`. If re-running after a prior `REQUIERE CORRECCIONES` (i.e., `.review-last-fails.json` was found with non-empty `failedFiles` in Step 0.4): set `mode: focused` — the auditor re-evaluates only the failing checklist items on the `failedFiles` (CR-05: focused mode still reads those files). Otherwise keep `concise`.
 
@@ -79,8 +89,13 @@ changedFiles: [path/file-1.ts, path/file-2.ts, ...]
 projectType: backend | frontend | fullstack | library
 changeObjective: <objective in 1-2 sentences, or null>
 mode: concise | detailed | focused
+codegraphAvailable: true | false      # from CodeGraph detection above
 stackDetected: <from memory.yaml, or omit>
 touchedFiles: [...]                   # from memory.yaml — omit if not present
+commandsRun: [<command>, ...]         # from memory.yaml — omit if not present
+criteriaRun: [CA-01, ...]             # from memory.yaml — omit if not present
+lastStep: test | verify | apply | ... # from memory.yaml — omit if not present
+testExecution: none                   # review never runs full suite by default (§3.2)
 ```
 
 ### Step 1: Delegate to the refacil-auditor sub-agent
@@ -95,6 +110,20 @@ The sub-agent:
 - Evaluates each item with PASS/FAIL/N/A + severity for each FAIL.
 - Returns ONE single message with the report + JSON block fenced as ` ```refacil-review-result `.
 
+### Step 1.5: Log CodeGraph telemetry (silent)
+
+After the sub-agent completes, run **once** (do not mention it to the user unless it fails):
+
+```bash
+refacil-sdd-ai compact log-codegraph-event --skill auditor --has-graph <true|false> --tool-calls <N> --tokens <N>
+```
+
+- `--has-graph`: the `codegraphAvailable` value from Step 0.5 of this skill.
+- `--tool-calls`: number of `codegraph_*` tool calls the sub-agent made (0 if it did not use the graph).
+- `--tokens`: conservative estimate of tokens saved (~800–1500 per useful tool call; 0 if no graph or no calls).
+
+Estimate `--tool-calls` and `--tokens` from the sub-agent's `<usage>` block using the same criteria as `explore/SKILL.md` Step 1.5. If the command fails, ignore it; it must not block the flow.
+
 ### Step 2: Process the sub-agent report
 
 Show the user the **concise report** (everything before the `refacil-review-result` block). Do not show the JSON block — it is internal metadata.
@@ -140,37 +169,46 @@ Where the values are extracted from the sub-agent's `refacil-review-result` bloc
 
 ### Step 3.5: Offer to apply corrections (only if REQUIERE CORRECCIONES)
 
-If `verdict` is `REQUIERE CORRECCIONES`, after showing the report present a numbered list of the findings (blockers first, then medium/low) and ask:
+If `verdict` is `REQUIERE CORRECCIONES`:
 
-```
-X corrections are needed. Do you want me to apply them?
-- "yes" / "all" — apply all
-- "1, 3" (numbers) — apply only those items
-- "no" / "skip" — you'll handle them manually
-```
+- `autopilotMode = false` (normal): show the report, present a numbered list of findings (blockers first, then medium/low) and ask:
+  ```
+  X corrections are needed. Do you want me to apply them?
+  - "yes" / "all" — apply all
+  - "1, 3" (numbers) — apply only those items
+  - "no" / "skip" — you'll handle them manually
+  ```
+  Apply according to the user's response (yes/all → all; N,M → selected; no/skip → none).
 
-**According to the user's response:**
-- **"yes" / "all"**: apply every correction using Edit/Write/Bash tools directly in this skill. After each correction, note it as applied.
-- **"N, M" (specific items)**: apply only those numbered items.
-- **"no" / "skip" / no answer**: do not apply anything — continue to Step 4.
+- `autopilotMode = true`: categorize findings automatically:
+  - **Auto-fixable** (formatting, naming, missing docstring, small refactor within scope): apply all in a single batch, then re-invoke `/refacil:review`. If pass 2 approves → continue to Step 4.
+  - **Requires human judgment** (architectural concern, scope question, business logic): abort — do not apply, return failure to the autopilot pipeline without asking the user. If pass 2 still does not approve → abort.
 
-After applying corrections (if any): summarize what was applied, then continue to Step 4.
+After applying corrections (if any):
+- **Do not** run the project's full or scoped test command from AGENTS.md §3.
+- If production code or tests were touched, summarize what was applied and recommend **`/refacil:test`** before another verify/review cycle.
+- Then continue to Step 4.
 
 ### Step 4: Recommend next step
 
-According to the parsed `verdict`, add at the end of your response:
+According to the parsed `verdict`:
 
 **If APROBADO or APROBADO CON OBSERVACIONES:**
-```
-The next step is to archive the change.
-Do you want me to continue with /refacil:archive?
-```
+- `autopilotMode = false` (normal): ask the user:
+  ```
+  The next step is to archive the change.
+  Do you want me to continue with /refacil:archive?
+  ```
+- `autopilotMode = true`: proceed to `/refacil:archive` immediately without asking.
 
 **If REQUIERE CORRECCIONES** (after Step 3.5):
-```
-The next step is to re-verify the implementation.
-Do you want me to continue with /refacil:verify?
-```
+- `autopilotMode = false` (normal): ask the user:
+  ```
+  The next step is to re-run tests for this change (/refacil:test), then re-verify.
+  Do you want me to continue with /refacil:test?
+  ```
+  (If the user prefers verify only without re-test, they may say so — default is test first per §3.2.)
+- `autopilotMode = true`: this is an abort condition — Step 3.5 already returned failure to the autopilot pipeline.
 
 ## Rules
 
@@ -180,5 +218,5 @@ Do you want me to continue with /refacil:verify?
 - If the sub-agent returned something out of format (no parseable JSON block and not `SCOPE_ERROR`), inform the user: "The reviewer returned an unstructured report — no marker was created. Review the report manually."
 - **Flow continuity**:
   - If verdict is APROBADO/APROBADO CON OBSERVACIONES and user confirms → immediately invoke `skill: "refacil:archive"`.
-  - If verdict is REQUIERE CORRECCIONES and user confirms verify (Step 4) → immediately invoke `skill: "refacil:verify"`.
+  - If verdict is REQUIERE CORRECCIONES and user confirms (Step 4) → immediately invoke `skill: "refacil:test"` (default per §3.2); invoke `refacil:verify` only if the user explicitly chose verify without re-test.
   - Do not describe the skill in text or wait for the user to type the command. (See `METHODOLOGY-CONTRACT.md §5`.)

package/skills/review/checklist.md

@@ -74,8 +74,8 @@
 - Tests validate **behavior**, not implementation details (they do not break when refactoring)
 - Mocks are minimal and necessary — do not mock what can be tested directly
 - Tests are independent of each other (do not depend on execution order or shared state)
-- Coverage >= 80% on new files
-- Tests pass without errors (run the test command indicated in AGENTS.md)
+- Coverage >= 80% on new files (rely on **`/refacil:test`** phase + `memory.commandsRun` / `criteriaRun` when present — **do not** run the AGENTS.md baseline test command via Bash unless the user explicitly requested re-execution)
+- Tests pass: **PASS** if test phase succeeded per memory or static review of test files finds no obvious failures; **FAIL** only with evidence (missing tests, broken assertions visible in file, contradictions with spec)
 
 ## 7. Security
 - No hardcoded secrets (passwords, API keys, tokens, internal service URLs)

package/skills/say/SKILL.md

@@ -8,6 +8,8 @@ user-invocable: true
 
 Sends a message visible to all members of the room this session is in. **$ARGUMENTS** = message text.
 
+> **WARNING**: `say` is ONLY for optional announcements with no expected response. It does NOT guarantee delivery to sessions that join the room after the message was sent, and `say` messages from other sessions do NOT appear in this session's inbox (or any other session's inbox). For actionable content, agreements, bug reports, or anything the recipient must act on, use `bus ask --to SESSION` instead.
+
 ## Instructions
 
 ### Step 1: Execute the broadcast
@@ -15,19 +17,51 @@ Sends a message visible to all members of the room this session is in. **$ARGUME
 Run via `Bash`:
 
 ```bash
-refacil-sdd-ai bus say --text "<text>"
+refacil-sdd-ai bus say --text "[text]"
 ```
 
-Where `<text>` is $ARGUMENTS (or what the user asked you to announce). Correctly quote the text.
+Where `[text]` is $ARGUMENTS (or what the user asked you to announce). Correctly quote the text.
 
 ### Step 2: Confirm
 
 Report to the user that the message was sent with its id.
 
+## Safe bus text delivery
+
+**Use `--text` for simple messages** (no special characters, single-line):
+```bash
+refacil-sdd-ai bus say --text "Simple announcement here"
+```
+
+**Do NOT use `<` or `>` inside `--text`** — shells may interpret them as redirection operators and truncate or discard the message.
+
+For messages containing `<`, `>`, `|`, newlines, or other special characters, use `--from-env`:
+
+**PowerShell (Windows)**:
+```powershell
+$env:BUS_TEXT = "Announcement with <special> chars"
+refacil-sdd-ai bus say --from-env BUS_TEXT
+Remove-Item Env:BUS_TEXT
+```
+
+**bash (inline, preferred — automatic cleanup)**:
+```bash
+BUS_TEXT="Announcement with <special> chars" refacil-sdd-ai bus say --from-env BUS_TEXT
+```
+
+**bash (export + unset alternative)**:
+```bash
+export BUS_TEXT="Announcement with <special> chars"
+refacil-sdd-ai bus say --from-env BUS_TEXT
+unset BUS_TEXT
+```
+
+> Note: the CLI cannot perform cleanup itself — it runs as a child process and cannot modify the parent shell's environment. Cleanup (`Remove-Item` / `unset`) is the responsibility of the invoking script or shell.
+
 ## When to use `say` vs other bus commands
 
-- **`say`**: general announcement to the room — "I finished my part", "I changed the X contract", "I'm going to restart the service"
-- **`ask`**: directed question to another specific session (use `/refacil:ask`)
+- **`say`**: general announcement to the room (optional, no response needed) — "I finished my part", "I'm going to restart the service". `say` does NOT guarantee delivery to sessions that join late and does NOT appear in other sessions' inboxes.
+- **`ask`**: directed question or actionable content to another specific session (use `/refacil:ask`). Use this for contracts, bug reports, agreements, anything the recipient must act on.
 - **`reply`**: respond to a question you were asked (use `/refacil:reply`)
 
 ## Rules
@@ -35,4 +69,6 @@ Report to the user that the message was sent with its id.
 - The session must be joined to a room; if not, the CLI will return an error.
 - Short and useful message — avoid bus spam.
 - If the user asks "tell the team ...", use `say`. If they ask "ask X ...", use `ask`.
+- **`say` is ONLY for optional announcements** — it does not guarantee delivery to late-joining sessions and does not appear in any session's inbox. Do not use `say` for contracts, bug reports, change requests, or any content that requires the recipient to act or confirm.
 - If a room thread **agrees on changes in this repo**, follow `refacil-prereqs/BUS-CROSS-REPO.md`: **`/refacil:propose`** and close via bus with whoever requested the work when done.
+- Do not use `<` or `>` inside `--text` arguments. Use `--from-env` instead (see "Safe bus text delivery" above).

package/skills/setup/SKILL.md

@@ -30,6 +30,58 @@ refacil-sdd-ai sdd 2>&1 || true
 
 Confirm that the subcommands `status`, `mark-reviewed`, `tasks-update`, and `archive` appear in the help.
 
+### Step 2b: CodeGraph early index (fire-and-forget)
+
+Start CodeGraph indexing **now**, before AGENTS.md is generated, so the call-graph is available or building while the rest of setup proceeds.
+
+Run:
+
+```bash
+refacil-sdd-ai sdd config --json
+```
+
+Parse the JSON. Check `codegraphMode` and its `sources.codegraphMode`:
+
+- **`disabled`**: skip this step entirely. Do not mention CodeGraph.
+
+- **`enabled`** (global or project setting):
+
+  - **CLI installed** (`installed: true`): fire indexing immediately in the background — **do not wait**:
+
+    ```bash
+    refacil-sdd-ai codegraph init
+    ```
+
+    Inform the user: "CodeGraph: indexing started in background. The `.codegraph/` directory will appear when complete (~30 s for small repos)."
+
+  - **CLI not installed** (`installed: false`): ask the user:
+
+    ```
+    CodeGraph is enabled but the CLI is not installed.
+    Do you want to install it now? This runs: npm install -g @colbymchenry/codegraph (~20 s)
+    (yes / no)
+    ```
+
+    - If **yes**: run `refacil-sdd-ai codegraph setup` and **show its full output**. This command installs the package and builds the index **synchronously** — it blocks until `.codegraph/` is fully ready. Wait for it to complete before continuing.
+    - If **no**: skip CodeGraph for now. Inform: "You can install it later by running `npm install -g @colbymchenry/codegraph` and then `/refacil:update`."
+
+- **`per-repo`**: ask the user once:
+
+  ```
+  Do you want to enable CodeGraph for this repo?
+  It indexes the call graph so exploratory sub-agents can query symbols instead of reading files (~71% token savings).
+  (yes / no)
+  ```
+
+  - If **yes**:
+    - **CLI installed**: run `refacil-sdd-ai codegraph init` in background, then persist the per-repo preference:
+      ```bash
+      refacil-sdd-ai sdd write-config --codegraph enabled
+      ```
+      Inform: "CodeGraph indexing started in background."
+    - **CLI not installed**: ask to install first (same flow as the `enabled` / not-installed branch above). If user installs: persist preference and init. If user skips: do not persist the enabled preference.
+  - If **no**: skip silently (per-repo decision, no global effect).
+
 ### Step 3: Create changes directory
 
 If `refacil-sdd/changes/` does not exist, create it:
@@ -156,7 +208,9 @@ Produce neutral placeholders (e.g. “Stack: unknown — see README / add manife
 | `/refacil:verify` | Verify implementation against the specs |
 | `/refacil:review` | Quality audit of the implemented code |
 | `/refacil:archive` | Archive the change and sync specs to the historical record |
-| `/refacil:up-code` | Update existing code to current patterns |
+| `/refacil:up-code` | Commit, push, and open PR for the current change |
+| `/refacil:autopilot` | Autonomous pipeline after approved propose: apply → test → verify → review → archive → up-code |
+| `/refacil:read-spec` | Listen to SDD spec Markdown in the browser with on-device TTS |
 | `/refacil:bug` | Create a fix proposal for a detected bug |
 | `/refacil:update` | Migrate documentation to the current methodology pattern |
 | `/refacil:join` | Join the cross-repo bus (first service setup) |
@@ -204,8 +258,8 @@ If the user wants extra exclusions beyond the base list, they may edit the ignor
 
 ### Step 6: Verify skills
 
-- Verify **`refacil-*`** folders under **global** IDE dirs (skills are installed per machine, not per repo): **`~/.claude/skills/`** when Claude is selected, **`~/.cursor/skills/`** when Cursor is selected (OpenCode / Codex: global dirs per upstream docs).
-  If missing: run **`refacil-sdd-ai init`** and restart the IDE session.
+- Verify **`refacil-*`** folders under **global** IDE dirs (skills are installed per machine, not per repo): **`~/.claude/skills/`**, **`~/.cursor/skills/`**, **`~/.config/opencode/skills/`** (or `OPENCODE_CONFIG_DIR`), **`~/.codex/skills/`** — only for IDEs selected in **`refacil-sdd-ai init`**.
+  If missing: run **`refacil-sdd-ai init`** and restart your IDE session.
 - Verify `sdd` subcommand: `refacil-sdd-ai sdd 2>&1 || true` — must show subcommands `status`, `mark-reviewed`, `tasks-update`, `archive`.
 
 ### Step 7: Final summary
@@ -214,11 +268,11 @@ If the user wants extra exclusions beyond the base list, they may edit the ignor
 === refacil:setup completed ===
  Node.js / refacil-sdd-ai / refacil-sdd/changes/ / branch config / AGENTS.md / sync-repo-ide (selected IDEs) / skills OK
 
- Restart Claude Code or Cursor session if this is the first skills installation.
+ Restart your IDE session (Claude Code, Cursor, OpenCode, or Codex) if this is the first skills installation.
  The next step is to review the available flow.
  Do you want me to continue with /refacil:guide?
 ```
 
 ## Rules
 
-- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 7, immediately invoke the **Skill tool** with `skill: "refacil:guide"`. Do not describe it in text or wait for the user to type `/refacil:guide`. (See `METHODOLOGY-CONTRACT.md §5`.)
+- **Flow continuity**: if the user confirms affirmatively ("yes", "ok", "go", "continue", etc.) the continuity question in Step 7, immediately execute `/refacil:guide`. Do not describe it in text or wait for the user to type it. (See `METHODOLOGY-CONTRACT.md §5`.)

package/skills/setup/troubleshooting.md

@@ -9,8 +9,16 @@ Consult this file **only** if a setup step fails. It is not part of the happy pa
 
 ## Skills `refacil-*` do not appear in the IDE
 
-- Run `refacil-sdd-ai init` at the repo root and **restart** the Claude Code or Cursor session.
-- If the skills are present in `.claude/skills/` but the IDE does not pick them up, restart the IDE (not just the session).
+- Run `refacil-sdd-ai init` at the repo root and **restart** the IDE session.
+- If the skills are present in the global IDE skills directory (e.g. `~/.claude/skills/`, `~/.cursor/skills/`, `~/.config/opencode/skills/`, `~/.codex/skills/`) but the IDE does not pick them up, restart the IDE (not just the session).
+
+## OpenCode hooks (global plugin)
+
+- OpenCode uses a **global** plugin at `~/.config/opencode/plugins/refacil-hooks.js` (not project `.opencode/plugins/`). Reinstall with `refacil-sdd-ai init` or `refacil-sdd-ai update` when OpenCode is selected, then restart OpenCode.
+
+## Codex hooks
+
+- Codex hooks merge into `~/.codex/config.toml` under `[hooks]` with `[features] codex_hooks = true`. Run `refacil-sdd-ai init` with Codex selected, then restart the Codex session.
 
 ## `refacil-sdd-ai init` creates files inside the wrong directory
 
@@ -43,7 +51,7 @@ Consult this file **only** if a setup step fails. It is not part of the happy pa
 
 ## Hook `check-update` not running at session start
 
-- Verify the hook is registered: check `.claude/settings.json` or `.cursor/settings.json` for a `hooks.SessionStart` entry that calls `refacil-sdd-ai check-update`.
+- Verify the hook is registered: Claude → `~/.claude/settings.json` (`SessionStart`); Cursor → `~/.cursor/hooks.json` (`sessionStart` when starting Agent chat — not duplicated on `workspaceOpen`). Both call `refacil-sdd-ai check-update`.
 - If missing, run `refacil-sdd-ai init` again (it is idempotent).
 
 ## `refacil-sdd/` not created after using SDD commands