@remixhq/claude-plugin 0.1.12 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixhq/claude-plugin",
-  "version": "0.1.12",
+  "version": "0.1.15",
   "description": "Claude Code plugin for Remix collaboration workflows",
   "homepage": "https://github.com/RemixDotOne/remix-claude-plugin",
   "license": "MIT",
@@ -31,8 +31,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@remixhq/core": "^0.1.8",
-    "@remixhq/mcp": "^0.1.8"
+    "@remixhq/core": "^0.1.10",
+    "@remixhq/mcp": "^0.1.10"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",

package/skills/access-troubleshooting/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: access-troubleshooting
+description: Use when debugging Remix access, missing visibility, membership confusion, cwd-derived scope issues, or why a user can read an app but not its project or organization.
+---
+
+# Access Troubleshooting
+
+Use this skill when the question is why access works, fails, or only partially works in Remix.
+
+This skill is about access diagnosis, not the full collaboration workflow.
+
+Mental model:
+
+- App visibility is not the same thing as project or organization visibility.
+- A readable app can still have an unreadable project or organization.
+- Partial success with warnings is often the correct outcome for app-scoped diagnostics.
+
+Recommended sequence:
+
+1. Start with `remix_access_debug`.
+2. In a bound repo, prefer `scope=app` first unless the user explicitly asked about project or organization access.
+3. Use `access.appContext` and `access.effectiveAppAccess` to explain:
+   - how the app is visible,
+   - whether access is direct app membership or inherited project membership,
+   - whether project or organization context is intentionally unreadable.
+4. Only use project or organization scope when the question is explicitly about those scopes, or when an explicit id is provided.
+5. Use invite and member tools only after the scope is clear and the access path has been explained.
+
+Important rules:
+
+- Do not assume app visibility implies project visibility.
+- Do not treat unreadable project or organization context from an app-readable repo as a broken state by default.
+- Do not start access debugging from a bound repo with project or organization tools first.
+- If `scope=app` succeeds with warnings, use those warnings as part of the explanation rather than escalating immediately.
+- If explicit project or organization scope fails, report that as a real boundary for that scope, not as an app-level failure.

package/skills/app-ops-triage/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: app-ops-triage
+description: Use when inspecting Remix app health, recent activity, queue state, sandbox status, or operational context before deciding whether deeper debugging is needed.
+---
+
+# App Ops Triage
+
+Use this skill when the user is asking what is happening with a Remix app right now.
+
+This skill is for operational inspection order, not access diagnosis or collaboration mutation.
+
+Recommended sequence:
+
+1. Start with `remix_context_get_app_overview`.
+2. Use `remix_ops_list_timeline` for recent bounded activity and event discovery.
+3. Use `remix_ops_list_agent_runs` when you need to discover recent run ids for the app.
+4. Use `remix_ops_get_edit_queue` to inspect pending or empty edit work.
+5. Use `remix_ops_get_sandbox_status` to inspect sandbox existence, resumability, and latest migration status.
+6. Only use:
+   - `remix_ops_get_agent_run`
+   - `remix_ops_list_agent_run_events`
+   after a concrete `runId` has already been discovered from overview, timeline, `remix_ops_list_agent_runs`, or another returned object.
+
+Important rules:
+
+- Start broad, then drill down.
+- Do not start with agent-run detail tools unless a run id is already known or has just been discovered through `remix_ops_list_agent_runs`.
+- Treat empty queues, absent runs, or no recent events as meaningful states rather than tool failure.
+- If overview and timeline do not surface a run id, use `remix_ops_list_agent_runs` before concluding that run-level inspection is unavailable.
+- If no run id can be discovered from the available ops tools, treat that as a current MCP-surface limitation and say so plainly instead of implying the app is broken.
+- Prefer explaining the operational picture first, then expanding into one subsystem only if the evidence points there.
+- When cwd is available in a bound repo, use the bound app as the default target unless the user explicitly provides another id.

package/skills/historical-memory-routing/SKILL.md

@@ -7,6 +7,8 @@ description: Use when the user asks why something changed, what happened before,
 
 In a Remix-bound repo, treat Remix memory as the first stop for historical reasoning.
 
+This skill is specifically about historical lookup order, not the full collaboration workflow.
+
 Use this skill when the user is asking about:
 
 - why something changed

package/skills/identity-and-scope-routing/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: identity-and-scope-routing
+description: Use when the user asks who they are in Remix, what scope a bound repo maps to, which organization, project, or app is relevant, or when cwd-derived scope must be interpreted safely.
+---
+
+# Identity And Scope Routing
+
+Use this skill when identity, cwd context, or directory routing is the main question.
+
+This skill is about scope interpretation, not collaboration mutation.
+
+Recommended sequence:
+
+1. When cwd matters, start with `remix_identity_whoami`.
+2. If the question is about the bound repo, ground on the bound app first with:
+   - `remix_identity_whoami`
+   - `remix_directory_get_app`
+   - `remix_context_get_app_overview` when operational context helps
+3. Use project or organization reads only when:
+   - the user explicitly asked for those scopes,
+   - an explicit id was provided,
+   - or app-grounded context shows those broader scopes are readable and relevant.
+4. When the user asks about a scope outside the current repo context, prefer explicit ids over cwd inference.
+5. When listing apps, prefer scoped or ownership-aware discovery before broad readable discovery:
+   - prefer `organizationId` or `projectId` when the relevant tenant scope is known,
+   - otherwise use `ownership` and `accessScope="explicit_member"` when the user means “apps I can actually work on.”
+
+Important rules:
+
+- In a bound repo, treat the app as the default anchor for scope reasoning.
+- Do not assume the bound app's project or organization is readable just because the app is readable.
+- Treat warnings on cwd-derived results as meaningful partial context, not as failure.
+- If cwd inference cannot safely resolve a broader scope, prefer the app-level answer and explain the boundary.
+- Use explicit ids when switching from "what is this repo?" to "tell me about that other org/project/app".
+- Do not default to broad unscoped app listing when the task is work-oriented; reserve `accessScope="all_readable"` for explicit public or broad readable discovery.

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

@@ -23,9 +23,12 @@ Recommended sequence:
 
 1. If the current repo may already be bound, use `remix_collab_status` first.
 2. If the task is about the current local repo and it is unbound, prefer `remix_collab_init`.
-3. If the task starts from an existing app id and the user wants a new fork, prefer `remix_collab_remix`.
-4. If the task starts from an existing app id and the user wants the same app id locally, prefer `remix_collab_checkout`.
-5. After init, remix, or checkout, use `remix_collab_status` in the resulting repo to inspect readiness.
+3. If the user needs help choosing an app id, prefer scoped discovery first:
+   - use `remix_directory_list_apps` with an explicit `organizationId` or `projectId` when the relevant scope is known,
+   - otherwise prefer `ownership` and `accessScope="explicit_member"` so discovery stays work-oriented instead of pulling in public readable apps by default.
+4. If the task starts from an existing app id and the user wants a new fork, prefer `remix_collab_remix`.
+5. If the task starts from an existing app id and the user wants the same app id locally, prefer `remix_collab_checkout`.
+6. After init, remix, or checkout, use `remix_collab_status` in the resulting repo to inspect readiness.
 
 Important note:
 
@@ -34,6 +37,8 @@ Important note:
 - `remix_collab_remix` creates a new bound checkout in a newly created directory under the provided or current working directory.
 - `remix_collab_checkout` creates a new bound checkout for the exact existing app id without creating a new fork.
 - Do not treat remix as binding the current repository in place.
+- When app discovery is only about \"what can I actually work on?\", prefer membership-oriented listing (`accessScope=\"explicit_member\"`) over broad readable discovery.
+- Use broad readable discovery only when the user explicitly wants public catalog-style exploration.
 - If the user wants to start from an existing Remix app lineage with a new fork, use `remix_collab_remix`.
 - If the user wants to continue work on the same existing app id, use `remix_collab_checkout`.
-- After init, remix, or checkout, the bound repo is eligible for automatic end-of-response turn recording in this plugin setup.
+- After init, remix, or checkout, run `remix_collab_status` in the resulting repo and then follow the normal bound-repo workflow there.

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

@@ -32,4 +32,4 @@ Important rules:
 - Do not treat raw `git merge` as the way Remix merge requests are approved or applied.
 - 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.
-- Review-only turns with no repository diff should be captured by `remix_collab_record_turn`, not by `remix_collab_add`.
+- Before the final response, use `remix_collab_finalize_turn` to record the completed review turn.

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

@@ -7,23 +7,16 @@ description: Use when working in a repo that may be bound to Remix, especially f
 
 In a Remix-bound repo, treat Remix MCP tools as the authoritative workflow layer for collaboration state and historical reasoning.
 
-For normal Remix collaboration:
+Canonical rules:
 
-- use sync or reconcile tools to align local state with Remix,
-- use merge request tools for review and approval flows,
-- use memory summary/search/timeline tools when historical context is needed before broader repo inspection,
-- use the explicit change-step diff tool only after identifying a relevant `changeStepId`,
-- let the installed hook handle automatic per-turn recording.
-
-In this plugin setup, turn recording is automatic at the end of each completed assistant response in a bound repo:
-
-- changed turn => `remix_collab_add`
-- no-diff turn => `remix_collab_record_turn`
-
-Normal rule:
-
-- do not proactively call `remix_collab_add` or `remix_collab_record_turn` during ordinary work
-- use those tools manually only for explicit user intent, operational recovery, backfills, or debugging
+- In a bound repo, Remix tools are the required workflow layer for collaboration work.
+- Historical intent questions go to Remix memory before raw git history.
+- Raw git mutation is not the normal collaboration path in a bound repo.
+- Before the final response, you must record exactly one completed turn with `remix_collab_finalize_turn`.
+- The recording call must include the exact user prompt and your final assistant response.
+- Do not finish the response before recording the completed turn.
+- 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 must not be used for ordinary bound-repo collaboration work. Raw git reads are reserved for exact repository facts, not for normal collaboration-state or historical-reasoning flows.
 
@@ -34,21 +27,22 @@ Follow this order:
 3. Prefer preview tools before apply tools:
    - `remix_collab_sync_preview` before `remix_collab_sync_apply`
    - `remix_collab_reconcile_preview` before `remix_collab_reconcile_apply`
-4. Treat reconcile as high risk and only use it when sync is unavailable and clearly required.
-5. Prefer Remix merge request tools over raw git merge flows for collaboration review work.
-6. When you need historical context, hidden intent, failed attempts, merge/reconcile lineage, or pre-change risk context, check Remix memory before falling back to broader repo exploration:
+4. Prefer Remix merge request tools over raw git merge flows for collaboration review work.
+5. When you need historical context, hidden intent, failed attempts, merge/reconcile lineage, or pre-change risk context, check Remix memory before falling back to broader repo exploration:
    - `remix_collab_memory_summary`
    - `remix_collab_memory_search`
    - `remix_collab_memory_timeline`
+6. Only call `remix_collab_memory_change_step_diff` after you already have a specific `changeStepId`.
 7. 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.
-8. Only call `remix_collab_memory_change_step_diff` after you already have a specific `changeStepId`.
+8. Before the final response, call `remix_collab_finalize_turn`.
 
 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, do not use raw git `commit`, `push`, `pull`, `merge`, `rebase`, or `reset` for ordinary Remix collaboration work.
 - 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.
-- Do not manually fire per-turn recording calls during ordinary work. The end-of-response hook records one turn once per completed assistant response.
+- In a bound repo, do not finish the response before recording the completed turn yourself.
+- After the final recording call, avoid further repo mutations unless you intend to record another final 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

@@ -5,36 +5,28 @@ description: Use when code edits are complete in a Remix-bound repo and the work
 
 # Submit Remix Change Step
 
-Use this skill after edits are complete and the task should be captured as a Remix collaboration step.
+Use this skill after edits are complete and the task should be captured as the final recorded turn in a Remix-bound repo.
 
-In a Remix-bound repo, `remix_collab_add` is the authoritative Remix recording path for completed work instead of raw git commit or push.
-If the tool list is ambiguous, prefer the clearer alias `remix_collab_add_change_step` for manually recording a code-diff change step.
-It creates the next commit on the Remix side from the submitted diff, then syncs the local repo to that new commit when auto-sync succeeds.
-
-In this plugin setup, the preferred default is automatic end-of-response recording:
-
-- if the completed assistant response produced a repo diff, the hook records exactly one `remix_collab_add`
-- if the completed assistant response produced no repo diff, the hook records one `remix_collab_record_turn` instead
+This skill is specifically about what `remix_collab_finalize_turn` needs to record the completed work correctly.
 
 Workflow:
 
 1. Run `remix_collab_status` first to confirm the repo is bound and inspect current warnings.
-2. If the repo is not bound, stop and ask whether to initialize with `remix_collab_init`.
-3. Do not proactively call `remix_collab_add` during ordinary work.
-4. Only use `remix_collab_add` when the user explicitly asks for a manual recording step, or when doing operational recovery, backfills, or debugging.
+2. Use `remix_collab_finalize_turn` before the final response, with the exact user prompt and your final assistant response.
+3. Let `remix_collab_finalize_turn` choose the changed-turn path from the live worktree by default.
+4. Provide an explicit external diff only when the task requires recording a diff that is not present in the current worktree.
 
 Important behavior:
 
-- `remix_collab_add` defaults to auto-sync behavior in this Remix setup.
-- `remix_collab_record_turn` is for no-diff prompt/response history only and should not be used when the worktree has code changes.
-- During ordinary work, the hook is the normal automatic path for changed-turn recording.
-- In the automatic hook path, the `remix_collab_add` prompt is the exact user prompt for that completed turn.
-- The automatic hook may also attach the final assistant response so changed turns and no-diff turns share the same prompt/response chronology.
-- Do not use raw `git commit` or `git push` as collaboration-recording steps in a bound repo.
-- If automatic recording cannot complete safely, recover through Remix status, sync, reconcile, and manual recording flows rather than local git mutation.
+- `remix_collab_finalize_turn` is the authoritative recording path for completed work instead of raw git commit or push.
 - When the diff comes from the live worktree, Remix may discard tracked changes and captured untracked paths locally as part of auto-sync.
+- When the diff comes from an external source, automatic local discard+sync is skipped because the external diff may not match the current worktree.
 - The resulting git commit is created on the Remix side first and appears in the local repo after sync or auto-sync.
 - Surface these side effects clearly to the user when they matter.
 - 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.
+- If `remix_collab_finalize_turn` reports that the change step succeeded remotely but local sync failed, do not retry finalize immediately.
+- In that recovery case, treat the tool's `recommendedNextActions` and `error.hint` as authoritative, starting with `remix_collab_status`, then `remix_collab_sync_preview`, then `remix_collab_sync_apply` when appropriate.
+- If the error surfaces a preserved diff backup path, mention it explicitly and preserve it as the fallback recovery artifact while you repair local sync state.
 
 Use external diff input only when the task explicitly requires it. Otherwise prefer the current worktree.

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

@@ -7,12 +7,14 @@ description: Use when a Remix-bound repo needs to be aligned with remote app sta
 
 Use this skill when the user asks to sync, update, or recover alignment between a local repo and its Remix app state.
 
+This skill is only about repository alignment. Use the general collaboration workflow skill for recording, memory-first history routing, and other bound-repo rules.
+
 Mental model:
 
 - `remix_collab_sync_*` is for pulling Remix-known app state into the local repo when fast-forward sync is possible.
 - `remix_collab_reconcile_*` is for cases where local history exists that Remix cannot fast-forward from.
 - `remix_collab_sync_upstream` is for bringing new upstream app changes into a remix.
-- `remix_collab_record_turn` is not a sync tool. It records a no-diff completed turn and does not create a commit.
+- `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.
 
 Workflow: