---
name: safe-collab-workflow
description: Use when working in a repo that may be bound to Remix, especially for collaboration, sync, merge request, or state-recovery tasks.
---

# Safe Remix Collaboration Workflow

In a Remix-bound repo, treat Remix MCP tools as the authoritative workflow layer for collaboration state and historical reasoning.

## Runtime override (read this first)

In a Remix-bound repo, the Cursor plugin hooks own all recording plumbing: completed-turn finalization, branch init when the current branch is unbound, baseline repair when the local anchor is missing or stale, deferred-turn replay, and safe queue draining. These run automatically in the background. You are not the recovery layer.

Concretely:

- Do **not** call `remix_collab_init` just to repair an unbound branch or missing baseline. The `beforeSubmitPrompt` hook detects an unbound current branch and spawns `remix collab init` detached; finalize-time baseline failures are routed through hook-owned auto-fix. Only call `remix_collab_init` when the user explicitly asks you to initialize a repo, or when the runtime surfaces an unrecoverable error that asks for a manual init.
- Do **not** call baseline repair, init, sync, or reconcile tools purely as preconditions for recording. Use those tools when the user explicitly asks for that state transition or when a Remix status/recovery message says manual action is required.
- Do **not** call a finalize MCP tool for this turn. The MCP surface does not expose one; Cursor records through `afterAgentResponse`, with `stop` as a sweep and retry backstop.
- Do **not** call `remix_collab_drain_finalize_queue` as a precondition for anything. The runtime drains queues automatically in the background; mutation tools (`remix_collab_request_merge`, `remix_collab_reconcile_apply`) also drain internally before they run.

When a prompt surfaces a Remix recovery note or `.remix/<command>.log` path, treat it as informational unless it explicitly asks for manual action. Do not race the hook with another MCP recovery call.

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 current branch is hook-owned recovery. Do not call `remix_collab_init` yourself unless the user explicitly asks; the hook spawns it detached and deferred turns replay once the branch binds.
- 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. Missing local revision baselines route through init/sync, not routine recording recovery.
- 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` 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:

1. Start with `remix_collab_status`.
2. Use the returned recommendation and warnings to choose the next tool.
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. If status reports `await_finalize`, use `remix_collab_drain_finalize_queue`, then re-check `remix_collab_status` before merge-related or recovery flows.
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:
   - `remix_collab_memory_summary`
   - `remix_collab_memory_search`
   - `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 merge-related or recovery flows, drain and re-check only if status reports `await_finalize`; routine completed-turn recording is automatic.

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, do not call `remix_collab_init` yourself. The hook-owned recovery path will spawn init for the current branch and defer/replay turns once binding lands.
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.

Detecting an unexpected branch or binding state:

Branch state can change between turns by means you did not initiate — external git operations, IDE actions, or hook side effects. You must detect and recover, not assume continuity.

**Treat any of the following as a mandatory trigger to run `remix_collab_status` before any other Remix mutation or response:**

- A Remix tool returns an error mentioning a branch name you did not just switch to.
- A Remix tool returns an error mentioning "not yet bound", "branch mismatch", "binding missing", or "baseline missing".
- `git status` or a bash command reveals a branch that does not match your mental model of the session.
- Any hook reminder, system-reminder, or preflight message flags an unexpected binding condition.

**NEVER skip `remix_collab_status` on one of these triggers.** Do not work around the error by calling the next tool in the expected sequence, stashing, switching branches blindly, or declaring the situation unresolvable. The status tool is the only source of truth for the current lane binding, and every recovery decision must be grounded in its output — not in your memory of an earlier state, not in the error message alone, not in shell output.

**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 hook-owned branch init or a user-facing question when recovery failed — never `git checkout` another branch. Branch switches belong to the user.

Important rules:

- If the repo has no Remix binding at all, 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. Hook-owned branch init only applies when the repo already has a binding for another branch.
- 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.
- 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`.
- 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`.
