@remixhq/claude-plugin 0.1.21 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixhq/claude-plugin",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Claude Code plugin for Remix collaboration workflows",
   "homepage": "https://github.com/RemixDotOne/remix-claude-plugin",
   "license": "MIT",
@@ -34,12 +34,12 @@
     "postbuild": "node -e \"const fs=require('node:fs'); for (const p of ['dist/mcp-server.cjs','dist/hook-pre-git.cjs','dist/hook-user-prompt.cjs','dist/hook-post-collab.cjs','dist/hook-stop-collab.cjs']) fs.chmodSync(p, 0o755);\"",
     "dev": "tsx src/mcp-server.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --import tsx --test src/**/*.test.ts",
+    "test": "node --import tsx --test 'src/**/*.test.ts'",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@remixhq/core": "^0.1.15",
-    "@remixhq/mcp": "^0.1.16"
+    "@remixhq/core": "^0.1.17",
+    "@remixhq/mcp": "^0.1.17"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",

package/skills/init-or-remix/SKILL.md

@@ -5,11 +5,13 @@ description: Use when deciding whether to bind the current repo to Remix or crea
 
 # Init, Remix, Or Checkout
 
-## Silent-init rule
+## Mid-turn unbound branch is hook-owned
 
-If during any turn you find yourself on an unbound branch in a Remix-bound repo — whether the user mentioned Remix or not, whether the prompt is trivial or not — **silently run `remix_collab_init` on the current branch without asking**. This is not a decision point. Do not present init as one option among several. Do not switch to a bound branch to avoid init. Init the branch you are on.
+When the current branch is unbound in a Remix-bound repo — whether the user mentioned Remix or not, whether the prompt is trivial or not — **the Remix `UserPromptSubmit` hook detects this and spawns `remix collab init` for you, detached, in the background**. You do not need to call `remix_collab_init` yourself for that case, and you should not present init as a decision point. The prompt context will include a Remix note when init is in flight; treat it as informational.
 
-The user-facing decision tree below (init vs. remix vs. checkout) only applies when the user is explicitly choosing how to bring a repo into Remix for the first time. Mid-turn unbound-branch recovery is always silent init.
+If the user explicitly asks you to initialize the current branch, you may call `remix_collab_init` to give them an immediate synchronous result instead of waiting for the hook. Otherwise, leave it to the hook.
+
+The user-facing decision tree below (init vs. remix vs. checkout) applies when the user is explicitly choosing how to bring a repo into Remix for the first time, or when the repo has no Remix binding at all (no `.remix/config.json`). The hook's auto-init path only fires when the repo already has a binding for some other branch.
 
 Use this skill when onboarding a repository into Remix, starting from an existing Remix app lineage, or checking out an exact existing Remix app.
 

package/skills/safe-collab-workflow/SKILL.md

@@ -9,11 +9,18 @@ In a Remix-bound repo, treat Remix MCP tools as the authoritative workflow layer
 
 ## Runtime override (read this first)
 
-When this turn's context contains a Remix runtime status note (recognizable by the literal `[Remix runtime status]` prefix from the Remix `UserPromptSubmit` hook), recording and queue draining for **this** turn are handled automatically by the runtime hooks. In that case:
+In a Remix-bound repo, the Remix plugin hooks own all "plumbing" for recording: turn finalize, branch init when the current branch is unbound, baseline repair when the local anchor diverged, and safe sync recovery when the server moved ahead. These run automatically, detached, in the background. You are not the recovery layer.
 
-- Do **not** call a finalize MCP tool for this turn. The MCP surface does not expose one; the runtime is recording it.
+Concretely:
+
+- Do **not** call `remix_collab_init` to "fix" an unbound branch. The `UserPromptSubmit` hook detects an unbound current branch and spawns `remix collab init` itself; the prompt context will tell you when this is in progress. Only call `remix_collab_init` when the user explicitly asks you to initialize a repo or when the runtime surfaces an unrecoverable error pointing at it.
+- Do **not** call any MCP tool to "re-anchor" or "repair the baseline". The `Stop` hook auto-dispatches `remix collab re-anchor` when the server returns `re_anchor_required`; the next prompt will surface progress or failure.
+- Do **not** call `remix_collab_sync_apply` purely as a precondition for recording. The `Stop` hook auto-dispatches `remix collab sync` when the server returns `pull_required`. Sync remains the right tool when the **user** asks to pull or when status shows divergence the user wants to act on.
+- Do **not** call a finalize MCP tool for the current turn. The MCP surface does not expose one; the `Stop` hook is recording it.
 - Do **not** call `remix_collab_drain_finalize_queue` as a precondition for anything. The runtime drains the queue automatically in the background; mutation tools (`remix_collab_request_merge`, `remix_collab_reconcile_apply`) also drain internally before they run.
 
+When the prompt context includes a `[Remix recovery]` note from a previous turn, treat it as informational. The runtime is already retrying or has already failed and surfaced the log path; do not race it with another MCP call unless the user asks you to.
+
 The runtime status note is authoritative for automatic recording. Use queue drain only for **explicit recovery flows**, such as status reporting `await_finalize` before a merge-related operation.
 
 Canonical rules:
@@ -21,9 +28,9 @@ Canonical rules:
 - In a bound repo, Remix tools are the required workflow layer for collaboration work.
 - In a bound repo, branch switches are collaboration-state transitions because each branch can resolve to its own Remix lane and app lineage.
 - Never switch git branches on your own. Branch switches are user-initiated only. If a Remix tool points at a different branch, do not "fix" it by switching — run `remix_collab_status` and follow its recommendation for the current branch.
-- An unbound branch is always a silent-init situation. Run `remix_collab_init` without asking. The user's intent when working on a branch is that the branch be bound.
+- An unbound current branch is handled automatically by the `UserPromptSubmit` hook. Do not call `remix_collab_init` for the current branch unless the user explicitly asks; the hook spawns it detached and surfaces progress on the next prompt.
 - Historical intent questions go to Remix memory before raw git history.
-- Remix is source-blind: any local content change since the last recorded turn — whether you typed it, the user typed it, a merge produced it, `git pull` brought it in, or an IDE saved it — is captured by exactly one completed-turn hook recording. Do not pick a different command based on what produced the change. `re-anchor` is for the narrow missing-baseline case only (status reports `re_anchor`).
+- Remix is source-blind: any local content change since the last recorded turn — whether you typed it, the user typed it, a merge produced it, `git pull` brought it in, or an IDE saved it — is captured by exactly one completed-turn hook recording. Do not pick a different command based on what produced the change. Baseline repair (`re-anchor`) is hook-owned: when the runtime needs it, the `Stop` hook spawns it and the next prompt explains it in plain language.
 - Raw git mutation is allowed in a bound repo, but it never substitutes for automatic hook recording. After raw git mutations, run `remix_collab_status` if you need to inspect state; `recommendedAction: record` means the completed-turn hook will capture the boundary.
 - The runtime records the exact user prompt and final assistant response automatically at turn completion.
 - Hook recording is queued. A remote change step does not exist yet until the finalize queue drains.
@@ -53,7 +60,7 @@ After switching branches:
 
 1. Run `remix_collab_status`.
 2. If the branch is healthy and bound, continue with the requested workflow.
-3. If the branch is unbound, silently run `remix_collab_init` on that branch before mutation commands. Do not ask, do not offer to switch back to another branch — init the branch you are on.
+3. If the branch is unbound, do not call `remix_collab_init` yourself. The next `UserPromptSubmit` will trigger the hook-owned init for that branch automatically. Continue with read-only work; mutations land in the deferred-turn queue and replay once the branch binds.
 4. If status reports a branch mismatch, stop and recover the correct branch binding before recording, syncing, reconciling, or opening a merge request.
 5. Do not assume another branch's binding is safe to reuse on the current checkout.
 
@@ -72,12 +79,12 @@ Branch state can change between turns by means you did not initiate — external
 
 **NEVER end your response with an unhandled Remix error.** If a Remix tool fails and you cannot resolve it this turn, at minimum: run `remix_collab_status`, report the real state to the user, and explicitly ask how to proceed. Silently giving up is not an option in a bound repo.
 
-**NEVER switch branches to "recover" from an unexpected binding state.** If status shows the current branch is unbound or mismatched, the recovery is `remix_collab_init` (silent) or a user-facing question — never `git checkout` another branch. Branch switches belong to the user.
+**NEVER switch branches to "recover" from an unexpected binding state.** If status shows the current branch is unbound or mismatched, the recovery is hook-owned (the next `UserPromptSubmit` spawns init automatically) or a user-facing question — never `git checkout` another branch. Branch switches belong to the user.
 
 Important rules:
 
-- If the repo is unbound, use `remix_collab_init` for the current repo, `remix_collab_remix` for a new fork from an existing app lineage, or `remix_collab_checkout` to materialize an existing app as-is.
-- In a bound repo, raw git mutations (`commit`, `pull`, `merge`, `rebase`, `reset`) are allowed but never replace automatic hook recording. After any raw git mutation, run `remix_collab_status` if you need to inspect state; `recommendedAction: record` means the completed-turn hook will capture the boundary. Do not assume `re-anchor` is the recovery — that command is only for missing-baseline cases (`recommendedAction: re_anchor`).
+- If the repo has no Remix binding at all (no `.remix/config.json`), use `remix_collab_init` for the current repo, `remix_collab_remix` for a new fork from an existing app lineage, or `remix_collab_checkout` to materialize an existing app as-is. The `UserPromptSubmit` hook only auto-spawns init when a binding exists for some other branch on the same repo; it does not initialize a brand-new repo for you.
+- In a bound repo, raw git mutations (`commit`, `pull`, `merge`, `rebase`, `reset`) are allowed but never replace automatic hook recording. After any raw git mutation, run `remix_collab_status` if you need to inspect state; `recommendedAction: record` means the completed-turn hook will capture the boundary. Do not call `remix_collab_re_anchor`, `remix_collab_init`, or `remix_collab_sync_apply` purely to "satisfy" recording — the `Stop` hook auto-dispatches each of those when finalize reports the matching preflight code.
 - In a bound repo, do not start why/history/failed-attempt questions with raw git `log`, `show`, `blame`, or `diff`; start with Remix memory reads instead.
 - In a bound repo, rely on automatic hook recording for the completed turn.
 - Do not treat queued hook recording as proof that the turn is already available for merge-request or remote-history workflows. Drain and re-check when status reports `await_finalize`.

package/skills/submit-change-step/SKILL.md

@@ -13,18 +13,21 @@ This skill is specifically about the automatic hook recording model. The MCP sur
 
 Remix records turns source-blind. Any local content change since the last recorded turn — whether you typed it, the user typed it, a `git pull` brought it in, a `git merge` or `git rebase` produced it, or an IDE saved it — is captured by exactly one completed-turn hook recording. The recording automatically attaches `preTurnEvents` metadata describing any commits, merges, or uncommitted state captured at the boundary; you do not need to summarize that yourself.
 
-Do **not** pick a different command (`re-anchor`, `sync`, `reconcile`) based on what produced the local change. Those commands are only correct when `remix_collab_status.recommendedAction` explicitly names them:
+Do **not** call `remix_collab_re_anchor_*`, `remix_collab_init`, or `remix_collab_sync_apply` purely as preconditions for recording. The runtime's `Stop` hook auto-dispatches each of those when finalize reports the matching preflight code:
 
-- `record` (or `repoState: local_only_changed`) → no manual MCP action. The completed-turn hook will capture the boundary.
-- `re_anchor` → `remix_collab_re_anchor_*`. Only when no local Remix baseline exists for this lane (fresh clone, deleted `.remix/`, or first init didn't seed). Re-anchor seeds the baseline; it is not a recovery for "the local content changed."
-- `pull` → `remix_collab_sync_*`. Only when the server lane advanced and local did not.
-- `reconcile` → `remix_collab_reconcile_*`. Only when both sides changed since the agreed baseline.
+- `branch_binding_missing` → hook spawns `remix collab init`.
+- `re_anchor_required` → hook spawns `remix collab re-anchor`.
+- `pull_required` → hook spawns `remix collab sync`.
+
+Each fix runs detached, logs to `.remix/<command>.log`, and writes a marker the next prompt surfaces. If you see a `[Remix recovery]` note in the next prompt's context, it is the runtime telling you what already happened — not a request for you to retry.
+
+The recommended-action codes from `remix_collab_status` (`record`, `re_anchor`, `pull`, `reconcile`) remain meaningful when the **user** is reasoning about state or explicitly asks for a sync, a re-anchor, or a reconcile. Don't pre-emptively invoke them just to "satisfy" recording.
 
 ## Runtime recording
 
-When a Remix runtime status note appears in this turn's context — recognizable by the literal `[Remix runtime status]` prefix and originating from the Remix `UserPromptSubmit` hook — recording and queue draining for **this** turn are handled automatically by the runtime's hooks.
+In a Remix-bound repo, the `Stop` hook is the authoritative recorder for every completed turn:
 
-- Do **not** call a finalize MCP tool. The MCP surface does not expose one; the runtime is recording the turn.
+- Do **not** call a finalize MCP tool. The MCP surface does not expose one.
 - Do **not** call `remix_collab_drain_finalize_queue` for this turn. The runtime drains the queue automatically in the background. Mutation tools (`remix_collab_request_merge`, `remix_collab_reconcile_apply`) drain internally before they run, so manual draining is never required as a precondition.
 
 Use `remix_collab_drain_finalize_queue` only for explicit recovery flows, such as status reporting `await_finalize` before a merge-related operation.
@@ -51,12 +54,10 @@ Use the live worktree as the source of truth for recorded work. If the repo is n
 
 ## Branch recovery
 
-If status shows the current branch is unbound:
+If status shows the current branch is unbound, **the next `UserPromptSubmit` hook will spawn `remix collab init` for you, detached, in the background.** Continue the requested work. The current turn lands in the deferred-turn queue and replays automatically once init completes; if init fails, the next prompt's context will explain it in plain language and point at `.remix/collab-init.log`.
 
-1. Call `remix_collab_status` to confirm the current branch is unbound (not mismatched, not in another recoverable state).
-2. **Silently run `remix_collab_init` on the current branch.** Do not ask the user first. Do not offer alternatives. Do not switch branches. An unbound branch in a Remix-bound repo is always a silent-init situation — that is the entire point of the init-on-demand contract.
-3. Continue the requested work. The completed-turn hook will record after the branch is ready.
+You should not call `remix_collab_init` yourself for this case unless the user explicitly asks for an immediate, synchronous result. Calling it eagerly races the hook and produces no observable benefit.
 
-**NEVER switch git branches to resolve a recording issue.** Branch switching is a user-initiated action and requires explicit user instruction. If status shows the current branch is unbound, init it — do not switch to some other bound branch to avoid the init. Silently initing the current branch is always correct; silently switching branches is always wrong.
+**NEVER switch git branches to resolve a recording issue.** Branch switching is a user-initiated action and requires explicit user instruction. If status shows the current branch is unbound, leave it for the hook — do not switch to some other bound branch to avoid the init.
 
 The triviality of the user's current prompt is irrelevant. "Say hello world" does not exempt the turn from recording if the bound repo was touched. The hooks handle routine recording automatically.