@remixhq/claude-plugin 0.1.20 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixhq/claude-plugin",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Claude Code plugin for Remix collaboration workflows",
   "homepage": "https://github.com/RemixDotOne/remix-claude-plugin",
   "license": "MIT",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@remixhq/core": "^0.1.15",
-    "@remixhq/mcp": "^0.1.15"
+    "@remixhq/mcp": "^0.1.16"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",

package/skills/review-merge-request/SKILL.md

@@ -31,7 +31,7 @@ Important rules:
 - In a bound repo, use Remix review tools as the default path for MR handling.
 - Choose an explicit queue instead of treating merge requests as one broad inbox.
 - Do not treat raw `git merge` as the way Remix merge requests are approved or applied.
-- Do not assume a successful `remix_collab_finalize_turn` already created a remote change step; drain and re-check when status reports `await_finalize`.
+- Do not assume queued hook recording already created a remote change step; drain and re-check when status reports `await_finalize`.
 - If approval would mutate the local target repo, explain that before applying it.
 - If the repo context is unclear, stay in remote-only review mode until the target repo is confirmed.
-- Before the final response, use `remix_collab_finalize_turn` to record the completed review turn.
+- Rely on automatic hook recording to capture the completed review turn.

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

@@ -9,12 +9,12 @@ 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's `Stop` hook. In that case:
+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:
 
-- Do **not** call `remix_collab_finalize_turn` for this turn — the runtime is recording it. Calling it would create a duplicate record.
+- Do **not** call a finalize MCP tool for this turn. The MCP surface does not expose one; the runtime 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.
 
-The runtime status note is authoritative for the override. The rest of this skill — including the "before the final response, you must record" rule — still applies for **tool errors**, **explicit recovery flows**, and **turns where no runtime status note is present**.
+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:
 
@@ -23,16 +23,14 @@ Canonical rules:
 - 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.
 - 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 `remix_collab_finalize_turn`. 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`).
-- Raw git mutation is allowed in a bound repo, but it never substitutes for `remix_collab_finalize_turn`. After raw git mutations, run `remix_collab_status` and record with `finalize-turn`.
-- Before the final response, you must record exactly one completed turn with `remix_collab_finalize_turn` — **unless the runtime override at the top of this skill applies** (a `[Remix runtime status]` note from the Remix hook stating that the Stop hook will record this turn).
-- `remix_collab_finalize_turn` is queued only. It captures the local boundary first; a remote change step does not exist yet until the finalize queue drains.
-- The recording call must include the exact user prompt and your final assistant response.
-- Do not finish the response before recording the completed turn (subject to the runtime override).
+- 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`).
+- 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.
 - Prefer preview tools before apply tools whenever both exist.
 - Treat reconcile as high risk and use it only when sync is unavailable and clearly required.
 
-Raw git mutation commands are not the normal collaboration path, but they are allowed. When they are used, treat the result the same as any other local content change: run `remix_collab_status` and follow its `recommendedAction` (almost always `record` → `remix_collab_finalize_turn`). Raw git reads are reserved for exact repository facts, not for normal collaboration-state or historical-reasoning flows.
+Raw git mutation commands are not the normal collaboration path, but they are allowed. When they are used, treat the result the same as any other local content change: run `remix_collab_status` if you need to inspect state; `recommendedAction: record` means the completed-turn hook will capture the boundary. Raw git reads are reserved for exact repository facts, not for normal collaboration-state or historical-reasoning flows.
 
 Follow this order:
 
@@ -49,7 +47,7 @@ Follow this order:
    - `remix_collab_memory_timeline`
 7. Only call `remix_collab_memory_change_step_diff` after you already have a specific `changeStepId`.
 8. Use raw git history only after Remix memory has narrowed the relevant change, or when the user explicitly asks for exact commit, blame, ancestry, or patch-level detail.
-9. Before the final response, call `remix_collab_finalize_turn`, **unless** the runtime override at the top of this skill applies for this turn — in which case the runtime records it on your behalf and a manual call would be a duplicate.
+9. Before merge-related or recovery flows, drain and re-check only if status reports `await_finalize`; routine completed-turn recording is automatic.
 
 After switching branches:
 
@@ -79,11 +77,11 @@ Branch state can change between turns by means you did not initiate — external
 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 `remix_collab_finalize_turn`. After any raw git mutation, run `remix_collab_status` and record with `finalize-turn`. Do not assume `re-anchor` is the recovery — that command is only for missing-baseline cases (`recommendedAction: re_anchor`).
+- 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`).
 - 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, do not finish the response before recording the completed turn yourself.
-- Do not treat a successful `remix_collab_finalize_turn` call as proof that the turn is already available for merge-request or remote-history workflows. Drain and re-check when status reports `await_finalize`.
-- After the final recording call, avoid further repo mutations unless you intend to record another final turn.
+- 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`.
+- After the final response, avoid further repo mutations unless you intend to capture them in a later turn.
 - Use raw git reads only when the task is clearly about exact repository facts or a separate GitHub-only branch workflow rather than Remix state.
 - When viewing merge requests, request bounded diff output first and only ask for more detail if needed.
 - For merge-request listing, choose the explicit queue that matches the intent: `remix_collab_review_queue`, `remix_collab_my_merge_requests`, or `remix_collab_list_app_merge_requests` with required `queue` set to `app_reviewable`, `app_outgoing`, or `app_related_visible`.

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

@@ -1,91 +1,62 @@
 ---
-name: finalize-turn-workflow
-description: Use when code edits or review work are complete in a Remix-bound repo and the turn should be recorded with `remix_collab_finalize_turn`.
+name: turn-recording-workflow
+description: Use when code edits or review work are complete in a Remix-bound repo and the completed turn should be captured by automatic hook recording.
 ---
 
-# Finalize A Remix Turn
+# Record A Remix Turn
 
 Use this skill after edits or review work are complete and the task should be captured as the final recorded turn in a Remix-bound repo.
 
-This skill is specifically about the queued-finalize model behind `remix_collab_finalize_turn`.
+This skill is specifically about the automatic hook recording model. The MCP surface does not expose a manual finalize tool.
 
 ## Source-blind recording rule
 
-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 `remix_collab_finalize_turn`. `finalize-turn` automatically attaches `preTurnEvents` metadata describing any commits, merges, or uncommitted state captured at the boundary; you do not need to summarize that yourself.
+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:
 
-- `record` (or `repoState: local_only_changed`) → `remix_collab_finalize_turn`. This is the catch-all and the most common case.
+- `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.
 
-## Runtime override (read this first)
+## 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 `Stop` hook. In that case:
+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.
 
-- Do **not** call `remix_collab_finalize_turn` for this turn. The runtime is recording it. A redundant call would create a duplicate record.
+- Do **not** call a finalize MCP tool. The MCP surface does not expose one; the runtime is recording the turn.
 - 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.
 
-The runtime status note is authoritative for the override. Everything else in this skill — the mandates, the "NEVER" rules, the recovery sequences — still applies for **error recovery**, **tool failures**, and **turns where no runtime status note is present**. Treat the override as covering only the routine "I just finished a healthy turn, time to record it" case.
+Use `remix_collab_drain_finalize_queue` only for explicit recovery flows, such as status reporting `await_finalize` before a merge-related operation.
 
 Workflow:
 
 1. Run `remix_collab_status` first to confirm the repo is bound and inspect current warnings.
-2. If status recommends `await_finalize`, do not record again and do not request a merge yet. Use `remix_collab_drain_finalize_queue`, then re-check `remix_collab_status`.
-3. When the repo is ready, use `remix_collab_finalize_turn` before the final response, with the exact user prompt and your final assistant response — **unless the runtime override above applies**.
-4. Treat `remix_collab_finalize_turn` as capturing the local workspace boundary and queueing remote processing, not as immediate proof that a remote change step already exists.
+2. If status recommends `await_finalize`, do not request a merge yet. Use `remix_collab_drain_finalize_queue`, then re-check `remix_collab_status`.
+3. When status recommends `record`, continue the turn normally. The completed-turn hook captures the exact user prompt, final assistant response, and local workspace boundary.
+4. Treat hook recording as local capture plus queued remote processing, not as immediate proof that a remote change step already exists.
 
 Important behavior:
 
-- `remix_collab_finalize_turn` is the authoritative recording path for completed work instead of raw git commit or push.
-- `remix_collab_finalize_turn` is queued only. A remote change step does not exist yet until the finalize queue drains successfully.
-- A successful finalize call means local capture and queueing succeeded. It does not mean merge-request or remote-history workflows can assume the turn is already materialized remotely.
+- Automatic hook recording is the authoritative path for completed work instead of raw git commit or push.
+- Hook recording is queued. A remote change step does not exist yet until the finalize queue drains successfully.
 - If `remix_collab_status` reports `await_finalize`, use `remix_collab_drain_finalize_queue` and re-check status before merge-related or recovery flows.
-- If the user wants to understand current repo state before recording, re-run `remix_collab_status`.
-- Do not make further repo mutations after the final recording call unless you intend to record another completed turn.
-- Do not retry finalize immediately just because a remote record is not visible yet; queue drain is the next step, not a second finalize.
-- If finalize or drain returns `recommendedNextActions` or an `error.hint`, those fields are **authoritative and mandatory**. Do not ignore them. Do not improvise around them. Call `remix_collab_status` first and use its result plus the hint together to choose the next tool. Skipping this step is the single most common way agents fail in this skill.
+- If the user wants to understand current repo state before the turn ends, re-run `remix_collab_status`.
+- Do not make further repo mutations after the final response unless you intend them to be captured by a later completed turn.
+- Do not retry recording just because a remote record is not visible yet; queue drain is the next step, not another recording attempt.
+- If drain returns `recommendedNextActions` or an `error.hint`, those fields are **authoritative and mandatory**. Do not ignore them. Do not improvise around them. Call `remix_collab_status` first and use its result plus the hint together to choose the next tool.
 - If the tool surfaces a preserved local recovery artifact, mention it explicitly and keep it available while you repair repo state.
 
-Use the live worktree as the source of truth for finalized work. If the repo is not ready, fix the preflight state first rather than trying to bypass it.
+Use the live worktree as the source of truth for recorded work. If the repo is not ready, fix the preflight state first rather than trying to bypass it.
 
-## Finalize errors — non-negotiable rules
+## Branch recovery
 
-When `remix_collab_finalize_turn` returns an error, you are in a state-recovery situation. You do not have permission to end your turn until it is resolved.
-
-**NEVER, UNDER ANY CIRCUMSTANCES, END A TURN WITH AN UNHANDLED FINALIZE ERROR.**
-
-This means:
-
-- Do not decide "finalize isn't applicable here" because the user's prompt was trivial (e.g. "hello world"). The recording rule fires on any turn that touches the bound repo — including the very finalize call that just failed. The call touched the repo. You must record.
-- Do not skip finalize because the error seems like a state problem outside your control. State problems are exactly what the error's `hint` and `recommendedNextActions` fields are there to resolve. Read them. Follow them.
-- Do not run a random bash command to "check what happened" and then give up. That is the failure pattern. `remix_collab_status` is the correct first tool, every time, without exception.
-
-**Mandatory recovery sequence when finalize errors:**
-
-1. Read the error's `message`, `hint`, and `recommendedNextActions` fields in full. They are authoritative. If the hint names a tool, that tool is almost certainly the next correct call.
-2. Call `remix_collab_status` immediately. The hint from status supersedes anything you inferred from the error alone — status sees the actual current binding, branch, worktree, alignment, and queue state.
-3. Based on status, pick the correct recovery tool:
-   - `local_only_changed` (or `recommendedAction: record`) → `remix_collab_finalize_turn`. This is the catch-all for any local mutation, including raw `git commit`, `git pull`, `git merge`, `git rebase`, or `git reset`. The source of the change does not matter.
-   - `baseline_missing` or `external_local_base_changed` (or `recommendedAction: re_anchor`) → commit any pending edits, then `remix_collab_re_anchor_preview` → `remix_collab_re_anchor_apply`. This applies only when no local Remix baseline exists for this lane yet, not whenever local content moved.
-   - `await_finalize` → `remix_collab_drain_finalize_queue`, then re-check status.
-   - Unbound or mismatched branch → follow the branch-recovery rules below.
-   - `delta_ready` for sync (or `recommendedAction: pull`) → `remix_collab_sync_preview` → `remix_collab_sync_apply`.
-   - `both_changed` (or `recommendedAction: reconcile`) → `remix_collab_reconcile_preview` → `remix_collab_reconcile_apply`.
-4. Retry `remix_collab_finalize_turn` only after status confirms the blocker is cleared.
-5. Only then produce your final user-facing response.
-
-**If finalize fails because the current branch is unbound:**
-
-The error hint will explicitly name the branch (e.g., `"Run remix collab init on branch X"`). That hint is the answer. Sequence:
+If status shows the current branch is unbound:
 
 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. Retry `remix_collab_finalize_turn`. Only after it succeeds, respond.
-
-**NEVER switch git branches to resolve a finalize error.** 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.
+3. Continue the requested work. The completed-turn hook will record after the branch is ready.
 
-**Cross-branch finalize** (`allowBranchMismatch: true`) applies only when the user has explicitly asked for it. Do not infer it from status.
+**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.
 
-**The triviality of the user's current prompt is irrelevant.** "Say hello world" does not exempt you from the protocol. Neither does "what time is it", "thanks", or any other small talk. If the bound repo was touched — including by a failing Remix tool call — you finalize. No exceptions, **except** the explicit runtime override at the top of this skill (a `[Remix runtime status]` note from the runtime hook stating that the Stop hook will record this turn automatically). The runtime override is the **only** sanctioned way to skip a finalize call; nothing else exempts you.
+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.

package/skills/sync-and-reconcile/SKILL.md

@@ -14,8 +14,8 @@ Mental model:
 - `remix_collab_sync_*` is for pulling Remix-known app state into the local repo when fast-forward sync is possible (i.e. `recommendedAction: pull`, `repoState: server_only_changed`).
 - `remix_collab_reconcile_*` is for the rare case where both the local workspace and the server lane changed since the last agreed baseline (i.e. `recommendedAction: reconcile`, `repoState: both_changed`).
 - `remix_collab_sync_upstream` is for bringing new upstream app changes into a remix.
-- `remix_collab_finalize_turn` is not a sync tool. It records the completed turn, but it does not replace sync, reconcile, or upstream-sync workflows.
-- `re-anchor` is **not** a sync or recovery tool for diverged history. It only seeds a missing local Remix baseline (`recommendedAction: re_anchor`). See the finalize-turn-workflow skill for full handling. If status reports `local_only_changed` (or `recommendedAction: record`), the answer is `finalize-turn`, never reconcile.
+- Automatic hook recording is not a sync tool. It records the completed turn, but it does not replace sync, reconcile, or upstream-sync workflows.
+- `re-anchor` is **not** a sync or recovery tool for diverged history. It only seeds a missing local Remix baseline (`recommendedAction: re_anchor`). If status reports `local_only_changed` (or `recommendedAction: record`), routine completed-turn hook recording is the answer, never reconcile.
 
 Workflow: