@comergehq/claude-plugin 0.1.1

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

@@ -0,0 +1,34 @@
+---
+name: init-or-remix
+description: Use when deciding whether to bind the current repo to Comerge or create a new remix checkout from an existing app.
+---
+
+# Init Or Remix
+
+Use this skill when onboarding a repository into Comerge or starting work from an existing Comerge app lineage.
+
+This is the entry-point choice:
+
+- use init when the current repository should become the bound Comerge repo,
+- use remix when work should start from an existing Comerge app lineage in a fresh checkout.
+
+Decision rule:
+
+- Use `comerge_collab_init` when the user wants to bind the current local repository to Comerge.
+- Use `comerge_collab_remix` when the user wants a new local checkout forked from an existing Comerge app.
+
+Recommended sequence:
+
+1. If the current repo may already be bound, use `comerge_collab_status` first.
+2. If the task is about the current local repo and it is unbound, prefer `comerge_collab_init`.
+3. If the task starts from an existing app id, prefer `comerge_collab_remix`.
+4. After init or remix, use `comerge_collab_status` in the resulting repo to inspect readiness.
+
+Important note:
+
+- `comerge_collab_init` is a repo-level, history-preserving bind of the current git repository.
+- Do not treat init as a subdirectory import workflow.
+- `comerge_collab_remix` creates a new bound checkout in a newly created directory under the provided or current working directory.
+- Do not treat remix as binding the current repository in place.
+- If the user wants to start from an existing Comerge app lineage instead, use `comerge_collab_remix`.
+- After init or remix, the bound repo is eligible for automatic end-of-response turn recording in this plugin setup.

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

@@ -0,0 +1,28 @@
+---
+name: review-merge-request
+description: Use when reviewing, approving, rejecting, or summarizing Comerge merge requests.
+---
+
+# Review Comerge Merge Request
+
+Use Comerge merge request tools as the default review workflow.
+
+Comerge merge requests are app-lineage review flows, not git branch merges. Use raw git merge workflows only when the task is clearly about a separate GitHub-only branch workflow rather than Comerge MR handling.
+
+Recommended sequence:
+
+1. Use `comerge_collab_inbox` to list relevant merge requests when the target MR is not already known.
+2. Use `comerge_collab_view_merge_request` to inspect the request.
+3. Request bounded diff output first. Only request a larger diff if needed to answer the review task accurately.
+4. If approval is requested:
+   - use `comerge_collab_approve_remote` when local target repo sync is not needed
+   - use `comerge_collab_approve_and_sync_target` only when you are in the correct target repo context and the user wants local sync too
+5. Use `comerge_collab_reject` when the correct outcome is rejection.
+
+Important rules:
+
+- In a bound repo, use Comerge review tools as the default path for MR handling.
+- Do not treat raw `git merge` as the way Comerge 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 `comerge_collab_record_turn`, not by `comerge_collab_add`.

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

@@ -0,0 +1,53 @@
+---
+name: safe-collab-workflow
+description: Use when working in a repo that may be bound to Comerge, especially for collaboration, sync, merge request, or state-recovery tasks.
+---
+
+# Safe Comerge Collaboration Workflow
+
+In a Comerge-bound repo, treat Comerge MCP tools as the default workflow layer for collaboration state and historical reasoning.
+
+For normal Comerge collaboration:
+
+- use sync or reconcile tools to align local state with Comerge,
+- 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 => `comerge_collab_add`
+- no-diff turn => `comerge_collab_record_turn`
+
+Normal rule:
+
+- do not proactively call `comerge_collab_add` or `comerge_collab_record_turn` during ordinary work
+- use those tools manually only for explicit user intent, operational recovery, backfills, or debugging
+
+Raw git can still make sense for separate GitHub-only branch workflows or exact repository facts, but it is not the default way to manage Comerge collaboration state or answer why/history/failed-attempt questions.
+
+Follow this order:
+
+1. Start with `comerge_collab_status`.
+2. Use the returned recommendation and warnings to choose the next tool.
+3. Prefer preview tools before apply tools:
+   - `comerge_collab_sync_preview` before `comerge_collab_sync_apply`
+   - `comerge_collab_reconcile_preview` before `comerge_collab_reconcile_apply`
+4. Treat reconcile as high risk and only use it when sync is unavailable and clearly required.
+5. Prefer Comerge 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 Comerge memory before falling back to broader repo exploration:
+   - `comerge_collab_memory_summary`
+   - `comerge_collab_memory_search`
+   - `comerge_collab_memory_timeline`
+7. Use raw git history only after Comerge memory has narrowed the relevant change, or when the user explicitly asks for exact commit, blame, ancestry, or patch-level detail.
+8. Only call `comerge_collab_memory_change_step_diff` after you already have a specific `changeStepId`.
+
+Important rules:
+
+- If the repo is unbound, use `comerge_collab_init` for the current repo or `comerge_collab_remix` for an existing Comerge app lineage.
+- In a bound repo, do not use raw git `commit`, `push`, `pull`, `merge`, `rebase`, or `reset` as the default Comerge collaboration workflow.
+- In a bound repo, do not start why/history/failed-attempt questions with raw git `log`, `show`, `blame`, or `diff`; start with Comerge 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.
+- Use raw git only when the task is clearly about a separate GitHub-only branch workflow rather than Comerge state.
+- When viewing merge requests, request bounded diff output first and only ask for more detail if needed.

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

@@ -0,0 +1,37 @@
+---
+name: submit-change-step
+description: Use when code edits are complete in a Comerge-bound repo and the work should be recorded as a Comerge change step.
+---
+
+# Submit Comerge Change Step
+
+Use this skill after edits are complete and the task should be captured as a Comerge collaboration step.
+
+In a Comerge-bound repo, `comerge_collab_add` is the normal Comerge equivalent of commit + push for completed work.
+It creates the next commit on the Comerge 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 `comerge_collab_add`
+- if the completed assistant response produced no repo diff, the hook records one `comerge_collab_record_turn` instead
+
+Workflow:
+
+1. Run `comerge_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 `comerge_collab_init`.
+3. Do not proactively call `comerge_collab_add` during ordinary work.
+4. Only use `comerge_collab_add` when the user explicitly asks for a manual recording step, or when doing operational recovery, backfills, or debugging.
+
+Important behavior:
+
+- `comerge_collab_add` defaults to auto-sync behavior in this Comerge setup.
+- During ordinary work, the hook is the normal automatic path for changed-turn recording.
+- In the automatic hook path, the `comerge_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 treat raw `git commit` as the primary collaboration-recording step in a bound repo.
+- When the diff comes from the live worktree, Comerge may discard tracked changes and captured untracked paths locally as part of auto-sync.
+- The resulting git commit is created on the Comerge 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 `comerge_collab_status`.
+
+Use external diff input only when the task explicitly requires it. Otherwise prefer the current worktree.

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

@@ -0,0 +1,31 @@
+---
+name: sync-and-reconcile
+description: Use when a Comerge-bound repo needs to be aligned with remote app state and you must choose between sync and reconcile safely.
+---
+
+# Sync And Reconcile
+
+Use this skill when the user asks to sync, update, or recover alignment between a local repo and its Comerge app state.
+
+Mental model:
+
+- `comerge_collab_sync_*` is for pulling Comerge-known app state into the local repo when fast-forward sync is possible.
+- `comerge_collab_reconcile_*` is for cases where local history exists that Comerge cannot fast-forward from.
+- `comerge_collab_sync_upstream` is for bringing new upstream app changes into a remix.
+- `comerge_collab_record_turn` is not a sync tool. It records a no-diff completed turn and does not create a commit.
+
+Workflow:
+
+1. Start with `comerge_collab_status`.
+2. If sync looks available, use `comerge_collab_sync_preview`.
+3. Only use `comerge_collab_sync_apply` after preview indicates the fast-forward path is appropriate.
+4. If sync is not available because history diverged, use `comerge_collab_reconcile_preview`.
+5. Only use `comerge_collab_reconcile_apply` when reconcile is clearly required and the user understands the risk.
+
+Important rules:
+
+- Prefer sync over reconcile whenever sync is available.
+- Reconcile is a last-resort operation because it rewrites local history and creates backup branches.
+- Explain local mutation risk before any apply step.
+- For remix repos, use `comerge_collab_sync_upstream` when the task is specifically about bringing upstream changes into the remix rather than aligning the local repo with its current Comerge app head.
+- Do not treat no-diff turn recording as a substitute for sync, reconcile, or upstream sync.