@rallycry/conveyor-skills 0.1.0 → 0.1.1

package/README.md

@@ -6,6 +6,14 @@ and linking it once gives every Claude Code session in your repo the Conveyor
 workflow skills (`/conveyor-plan`, `/conveyor-local-loop`, …), and updates
 arrive through normal dependency bumps — no git submodules, no manual syncing.
 
+## Skills
+
+| Skill | Invoke | What it does |
+| --- | --- | --- |
+| `conveyor-workflows` | auto-triggers on Conveyor questions | The guide: connect/repair the MCP, create and classify cards, packs, builds, the two PR paths, review flows, reliability gotchas |
+| `conveyor-plan` | `/conveyor-plan <idea>` | Research an idea into a context-free, immediately-buildable Conveyor card |
+| `conveyor-local-loop` | `/loop /conveyor-local-loop` | Run this machine as a serial local agent: claim Open cards, build to PR, repeat |
+
 ## Install (once per repo)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-skills",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared Claude Code skills for Conveyor consumer repos, linked into .claude/skills via the conveyor-skills CLI",
   "keywords": [
     "claude",

package/skills/conveyor-local-loop/SKILL.md

@@ -81,7 +81,10 @@ Each invocation does the FIRST of these that produces work, then paces:
 
 1. `mcp__conveyor__get_task` (full plan) + `mcp__conveyor__read_task_chat`
    (addenda, user answers). The card must stand alone — if you find yourself
-   relying on loop-session memory, stop and re-read the card instead.
+   relying on loop-session memory, stop and re-read the card instead. Consult
+   `mcp__conveyor__get_tag` for the card's assigned/mentioned tags before
+   diving in — the overview + linked files are the fast path into the
+   subsystem.
 2. Branch from the card's base, never blindly dev: `base` = the card's
    `baseBranch` (a pack child's base is the PARENT's feature branch). If the
    card already has a `githubBranch` with commits on origin, resume THAT

package/skills/conveyor-local-pack/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: conveyor-local-pack
+description: Drive one Conveyor pack (parent card + children) on this machine start to finish — this session is BOTH the pack coordinator and every child's implementer. Work children serially in dependency order, PR each into the pack branch, review + merge locally, sync dev after every merge, then land the whole pack as one final parent PR into dev. The local alternative to pressing Build on a parent card. Use when the user says "/conveyor-local-pack <card>", "drive this pack locally", or "run the whole pack on my machine". One invocation = one step (next child, a merge, or the finale); run continuously with "/loop /conveyor-local-pack <card>" (no interval) and it self-paces until the final PR is green, then stops itself.
+---
+
+# Conveyor Local Pack
+
+The cloud pack runner's autonomous loop (`pack-runner-prompt.ts`), adapted to
+one machine. Two deliberate differences from the pod version:
+
+- **No coordination-only rule.** The cloud runner fires child pods and never
+  writes code; here the same session implements each child itself.
+- **No server-side base sync.** The server merges dev into the pack branch
+  before each cloud child launch; locally that sync is your job, after every
+  child merge.
+
+Everything else carries over: the card is the spec, task chat is the log, and
+the host repo's CLAUDE.md governs gates, verification, and PR mechanics. This
+skill assumes a feature-branch pack — children branch from and PR into the
+pack branch, and the pack lands on dev in ONE final PR. If the parent has no
+feature branch (children PR straight into dev), this skill does not apply:
+run /conveyor-local-loop over the children instead.
+
+## Ground rules
+
+- **The parent card stays PARKED until the final PR.** Never
+  `mcp__conveyor__start_task` the parent and never set it InProgress: the pack
+  watchdog and child-event notifier ignore parked parents, but an ACTIVE
+  parent treats a headless InProgress child as a dead agent environment and
+  "recovers" it onto a cloud pod — duplicate implementation (observed
+  2026-07-28). The final `create_pull_request` is what moves the parent to
+  ReviewPR. Parent already InProgress/ReviewPR at setup → a coordinator is (or
+  was) active; report and stop rather than compete.
+- **Conveyor is the state store.** A pack spans days and the session gets
+  compacted; every iteration re-derives state from `mcp__conveyor__get_task` +
+  `mcp__conveyor__list_subtasks`, never from conversation memory.
+- **All Conveyor tools fully-qualified** (`mcp__conveyor__get_task`; bare
+  names fail).
+- **WIP = 1, strictly serial.** One child at a time, in dependency order. No
+  cloud offload: never `start_task` a child — a pod would duplicate the local
+  work. Want parallel fan-out? Press Build on the parent instead.
+- **You are the reviewer of record for child PRs** — the automated code
+  reviewer skips PRs that target the pack branch. Review each child diff for
+  real before merging; the independent review happens on the pack's final PR
+  into dev (automated reviewer + human).
+- **Never approve or merge the FINAL parent PR.** Finish line = parent in
+  ReviewPR with green CI; the user takes it from there.
+- **Child PRs into the pack branch get NO CI** (Conveyor runs CI on PRs to
+  dev/main only) — the local gate pass is the ONLY verification before a
+  child merges. Mandatory, never skippable. In a repo that does run CI on
+  pack-branch PRs, let it finish before merging.
+- **Clean tree before any branch switch — hard rule.** Dirty `git status` at
+  iteration start → touch nothing, report, idle: the cwd is probably the
+  user's interactive checkout. Recommend a dedicated worktree once
+  (`git worktree add ../<repo>-pack dev`) and run the pack session there.
+- **Push early.** No pod WIP-autosync locally; committed-and-pushed is the
+  only durable state. Push child branches (`-u origin`) as soon as they
+  exist, and the pack branch after every merge/sync.
+
+## Setup (first iteration only)
+
+1. Resolve the parent card from the argument (slug/id/URL — required; without
+   one, ask which pack). `mcp__conveyor__get_task` +
+   `mcp__conveyor__read_task_chat`.
+2. Confirm it is a parked feature-branch pack: has (or will have) children,
+   status not InProgress/ReviewPR, no active agent session.
+3. Ensure the pack branch exists on origin: use the card's branch if set;
+   else cut `ft/<parent-slug>` from `origin/dev`, push `-u`, and name it in
+   the claim post so the record is on the card.
+4. No children yet? Break the work down first, exactly as a fresh cloud
+   parent would: explore the codebase, save the parent-level plan on the card
+   (`mcp__conveyor__update_task`), then `mcp__conveyor__create_subtask` each
+   child with a detailed standalone plan (file:line citations, verification
+   steps) and `dependsOn` wherever one blocks on another.
+5. Post to parent chat: `[local-pack] claimed — driving this pack locally on
+   <hostname>, pack branch <branch>`.
+
+## Iteration order
+
+Each invocation re-reads the parent + `list_subtasks`, then does the FIRST
+that applies:
+
+1. **Recover** — a child with my `[local-pack] claimed` marker sitting
+   InProgress without a PR? Resume it. Its branch may exist locally or on
+   origin — audit what already landed before re-implementing anything.
+2. **Merge** — a child in ReviewPR: merge path below.
+3. **Promote** — a Planning child whose plan is solid:
+   `mcp__conveyor__update_subtask` → status Open (+ story points/agent if
+   unset). Genuinely not plannable → escalate to parent chat.
+4. **Implement** — the next Open child with all dependencies met (a
+   dependency counts as met at ReviewDev/Complete — i.e. merged into the
+   pack — or Cancelled; ReviewPR is NOT met). No `dependsOn` set anywhere →
+   ordinal order. Implement path below.
+5. **Finale** — every child ReviewDev/Complete: cross-reference + final PR,
+   below.
+6. **Babysit** — final PR open: red CI or review comments → address directly
+   on the pack branch (never claim or work children once the parent is in
+   ReviewPR); green and quiet → post the wrap-up to parent chat and STOP the
+   loop.
+
+## Implement a child
+
+1. `mcp__conveyor__get_task` on the child — reload the full plan fresh every
+   time — + `read_task_chat` for addenda. Plan too thin for a context-free
+   reader → post what's missing to parent chat, skip it, take the next ready
+   child.
+2. Claim: `mcp__conveyor__update_task` → InProgress, then chat marker
+   `[local-pack] claimed — working locally on <hostname>`.
+3. Branch from the PACK branch, never dev: `git fetch origin <pack> && git
+   checkout -B <feat|fix|chore>/<child-slug> origin/<pack>`. If the child
+   already has a branch with commits on origin, resume THAT branch — audit it
+   first. Reinstall deps if the lockfile changed.
+4. Work the plan. Chat updates at real milestones only, not play-by-play.
+5. Verify per the host CLAUDE.md (scoped gates: `bun run check` +
+   `bun run test:affected`). Note `test:affected` diffs vs origin/dev, so on
+   a deep pack it naturally also covers previously merged children — that is
+   fine, not a bug to fix. UI-visible change → capture evidence and
+   `mcp__conveyor__upload_attachment` before the PR.
+6. Refresh vs the pack branch (`git fetch origin <pack> && git merge
+   origin/<pack> --no-edit && git push`), then
+   `mcp__conveyor__create_pull_request` with `head:` the child branch and —
+   ALWAYS EXPLICITLY — `base:` the pack branch. The default base is dev;
+   omitting `base` opens the child against the wrong branch. Post a summary
+   to the child's chat.
+
+## Merge a child (ReviewPR)
+
+1. Reviewer-of-record pass: re-read the child's plan, then the FULL diff
+   (`git fetch origin <pack> <child> && git diff
+   origin/<pack>...origin/<child>`) with reviewer eyes — plan coverage,
+   stray files, pattern consistency, and that the gate pass actually
+   happened. Found a real problem → fix it on the child branch first (you are
+   also the implementer), re-gate, then continue.
+2. Merge: `mcp__conveyor__approve_and_merge_pr`. Known trap: the merge queue
+   can NEVER auto-merge a zero-check pack-branch PR — if the merge queues
+   without landing, merge locally instead (`git checkout <pack> && git pull
+   && git merge --no-ff <child-branch> && git push`; GitHub then marks the PR
+   merged). Either way confirm the child advanced to ReviewDev.
+3. **Sync dev into the pack branch** — the local stand-in for the server-side
+   base sync: `git checkout <pack> && git pull && git fetch origin dev && git
+   merge origin/dev --no-edit && git push`. Merge, never rebase: the pack
+   branch is shared (open child PRs, WIP refs) and rewriting it breaks them.
+   Conflicts are yours to resolve properly — you wrote the code. If the merge
+   drags in unrelated changes or errors, dev may have been rewound
+   (revert/force-push): verify the previous sync point is still an ancestor
+   of `origin/dev` (`git merge-base --is-ancestor`), and if not, abort the
+   merge and escalate instead of chasing the noise.
+4. Report the merge to parent chat in one line. Next iteration begins the
+   next child.
+
+## Finale (all children ReviewDev/Complete)
+
+1. **Cross-reference:** for the parent plan and EVERY child plan, check the
+   pack branch's actual state against the plan's acceptance and verification
+   criteria — a real checklist pass, not a vibe. Small gap → fix directly on
+   the pack branch. Substantial gap → new child card with a plan
+   (`create_subtask`); the loop continues.
+2. Pre-PR protocol on the pack branch, per the host CLAUDE.md: sync
+   `origin/dev` FIRST, then ONE verification pass scoped to the pack's
+   cumulative diff vs dev (cross-package packs → full `bun run test`).
+3. `mcp__conveyor__create_pull_request` on the PARENT: `head:` pack branch,
+   `base:` dev. The parent moves to ReviewPR. Post the pack summary to parent
+   chat: what shipped per child, how it was verified, what reviewers should
+   look at.
+4. Confirm CI actually started (read-only `gh pr checks`); do NOT wait on it
+   — the babysit tier owns it from here.
+
+**Parked protocol** — after 2 genuinely different failed approaches on a
+child, or a decision only the user can make: post `[local-pack] parked:
+<reason + the specific question>` to the child AND the parent chat, set the
+child back to Open, restore the tree, and take the next child whose
+dependency chain doesn't run through the parked one. Everything remaining
+blocked → idle long; the user's chat reply is the un-park signal.
+
+## Pacing (dynamic /loop only)
+
+Under `/loop` with no interval, end EVERY iteration with exactly one
+`ScheduleWakeup` (prompt = the original /loop input verbatim, card argument
+included):
+
+| State | Delay | Reason should say |
+|-------|-------|-------------------|
+| A background gate is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs" |
+| Any actionable work: a child to implement/merge/promote, finale pending, red CI or comments on the final PR | 60–90s | which child / which step is next |
+| Blocked on the user: parked children only, or a pack-level question posted | 1200–1800s | what it's waiting on |
+| Loop-fatal: MCP dead after 2 tries, dirty tree, broken repo | notify the user (PushNotification if available), then 1800s — or `stop: true` if continuing is unsafe | what is wrong |
+| Final PR green and quiet, wrap-up posted | `stop: true` | pack done |
+
+Invoked bare (no /loop)? Run one iteration, report, and suggest
+`/loop /conveyor-local-pack <card>` — don't self-schedule.
+
+## What this is not
+
+- Not a cloud coordinator: never `start_task` and never fire pods, for the
+  parent or a child. Serial local execution is the point; for parallel
+  fan-out, press Build on the parent instead of using this skill.
+- Not the final reviewer: `approve_and_merge_pr` is for CHILD PRs into the
+  pack branch only — never the parent's PR into dev.
+- Not a pod: the dev DB and dev-server ports are shared with the user's
+  interactive sessions — no destructive experiments, never reset the dev DB,
+  reuse a running dev stack rather than fighting over ports.
+
+## Improve This Skill
+
+If this skill was insufficient or slowed the work down, file it with
+`mcp__conveyor__create_suggestion` on the Conveyor project: the issue,
+evidence, and proposed fix.

package/skills/conveyor-plan/SKILL.md

@@ -27,6 +27,12 @@ icon or story points yourself, and never `start_task` unless the user asks.
 
 Scale to the idea's size; a one-file tweak needs minutes, not a survey.
 
+- **Glossary first**: `mcp__conveyor__get_tag` on every tag the idea's text
+  mentions (`@[tag:id]` deep-links or plain loaded terms — "task", "school",
+  an entity name) before searching the codebase. A tag's overview + linked
+  files often replace a grep sweep, and the description catches
+  wrong-term-for-the-concept early (`mcp__conveyor__list_tags` shows the
+  inventory with hierarchy).
 - **Codebase**: use a code-graph or architecture skill if the repo provides
   one for architecture/flow questions; `rg` for exact strings. Fan out
   Explore subagents for broad sweeps.

package/skills/conveyor-plan/references/plan-format.md

@@ -38,9 +38,10 @@ one card.
 - **Orchestration packs** (future work): `start_task` on the parent boots a
   *pack runner* that starts each ready child's own build/PR, honoring
   `add_dependency` edges (independent children run in parallel). Give each
-  child a detailed plan with a **Testing / Verification** section and a
-  `storyPointValue`. The parent's `featureBranch` toggle (default on) makes
-  children branch off and PR back into the parent's branch instead of dev.
+  child a detailed plan with a **Testing / Verification** section —
+  identification sizes children like any other card. The parent card's
+  `featureBranch` setting (default on) makes children branch off and PR back
+  into the parent's branch instead of the default base.
 - **Mirror packs** (already-done work shipping in ONE PR on the parent's
   branch): create children with **`followParentStatus: true`** — title and a
   plain-language description only. A follower mirrors its parent's status

package/skills/conveyor-workflows/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: conveyor-workflows
+description: How to work with Conveyor from any repo it manages — connect or repair the Conveyor MCP, create and plan cards, decide task vs suggestion vs incident, build packs, start or monitor agent builds, open PRs the non-duplicating way, and review completed work. Use when asked "how do I use conveyor", "create a card", "file this in conveyor", "start a build", "review this conveyor task", when Conveyor MCP tools are missing or erroring, or when a PR was auto-closed or a duplicate card appeared.
+---
+
+# Conveyor Workflows
+
+Conveyor is the task source of truth for this repo. Cards must let the next
+agent or human pick up cold: search before creating, keep task chat current,
+and let Conveyor's own automation do the linking.
+
+## Connect and resolve context
+
+- All Conveyor tools are called fully-qualified (`mcp__conveyor__get_task`);
+  bare names fail with "No such tool available".
+- Start with `mcp__conveyor__get_connection_context`. No default project?
+  `mcp__conveyor__list_projects` and match `githubRepoOwner/Name` against the
+  cwd's `git remote`. Conveyor MCP is multi-project — pass `projectId`
+  explicitly when working across projects.
+- **A mistyped `projectId` surfaces as "Insufficient permissions", not "not
+  found".** Re-check the ID character-for-character before concluding you lack
+  access.
+- MCP missing, stale, or unauthenticated → [references/mcp-setup.md](references/mcp-setup.md).
+- Two MCP surfaces exist with different arg shapes: the in-pod agent tools
+  (`post_to_chat` takes `message`) and the standalone `@rallycry/conveyor-mcp`
+  server for external clients (`content`, plus `taskId`/`comment` variants).
+  You are on the in-pod surface when Conveyor provisioned your workspace;
+  external when the MCP was configured by hand. Each accepts the other's
+  field name as an alias where possible, but read the tool's schema — don't
+  guess across surfaces.
+
+## Cards: create, classify, plan
+
+- **Search first**: `mcp__conveyor__search_tasks` on 2-3 keyword variants
+  (`typeFilters` to include incidents/suggestions); use
+  `mcp__conveyor__list_tasks` when filtering by status/assignee instead of
+  text (results are priority-ordered). A card may already exist — attach to
+  it (post your context to its chat) rather than forking a duplicate.
+- **Classify**: buildable work → `mcp__conveyor__create_task`; an
+  idea/improvement you are NOT committing to build →
+  `mcp__conveyor__create_suggestion`; incidents (production breakage) are
+  filed by monitoring and users through Conveyor's incident tooling — you
+  will usually *work* incident cards, not create them.
+- **Mechanics**: `create_task` takes the title, description, `plan`
+  (markdown), and optional status/tags; cards start in `Planning`. Every
+  status change you make goes through `mcp__conveyor__update_task`
+  (`status: "Open"` / `"InProgress"` / `"Cancelled"`, plus plan/description
+  edits). Review-side transitions are NOT yours — see the PR section.
+- **Description vs plan**: the description is capped at 255 chars — 1-2 plain
+  sentences a non-engineer can read. All technical detail goes in the plan.
+- **Plan quality bar**: a context-free reader must be able to execute — exact
+  repo-relative files and symbols, runnable testing commands, decisions
+  already made recorded in Notes. Format and sizing:
+  [../conveyor-plan/references/plan-format.md](../conveyor-plan/references/plan-format.md).
+  For research-backed planning that ends in a handoff card, use the
+  `conveyor-plan` skill.
+- **One card per deliverable/PR** (mirror packs below are the documented
+  exception). Multi-PR work becomes a pack: children via
+  `mcp__conveyor__create_subtask` (the ONLY way to parent a card) with
+  `mcp__conveyor__add_dependency` edges. Orchestration packs run children as
+  their own builds/PRs; mirror packs (children created with
+  `followParentStatus: true` on `create_subtask`) document already-done work
+  shipping in ONE PR on the parent. Don't pack below
+  genuinely-multiple-independent-pieces scope.
+- **Identification is Conveyor's job**: moving a card beyond Planning
+  (`update_task` → `status: "Open"`) auto-fills story points, icon, agent,
+  and tags — for pack children too. Post your SP/tag recommendation to chat
+  BEFORE the flip; never set icon or points yourself.
+
+## Tags are the project glossary
+
+Tags are the shared vocabulary humans and agents align on, not just board
+labels. Each tag carries a `description` (≤255 — the summary), an `overview`
+(the full markdown spec: philosophy, mechanics, invariants), `contextPaths`
+(where the code/rules live), and parent/child tags (a sub-type taxonomy).
+
+- **Read**: `mcp__conveyor__list_tags` for the inventory (names, descriptions,
+  hierarchy, `contextPaths`, `hasOverview`) — the context links ship inline, so
+  auditing what the glossary wires up takes one call, not one per tag;
+  `mcp__conveyor__get_tag` (id or exact name) for one term's full entry —
+  overview, linked files, hierarchy, and recent revisions with their reasons. When a card or chat message deep-links a term
+  (`@[tag:<id>]` — the web composer offers this when you type a tag name),
+  `get_tag` is how you pull its full context. To deep-link a term yourself,
+  write `@[tag:<name>]` with the tag's exact name — chat posts and card
+  plans/descriptions are canonicalized to the id token at write time, so you
+  never need the id. An unknown name stays plain text.
+- **Write**: `mcp__conveyor__manage_tags` (Moderate+). Whenever your work
+  changes how a tagged system behaves, update that tag's `overview` and pass a
+  one-line `reason` — it lands in the tag's revision history (in-pod agents
+  get their current card auto-stamped too), so the team sees why the glossary
+  changed. Any loaded term worth a definition deserves a tag.
+- **The PR nudge**: `create_pull_request` may append a "Touched glossary
+  areas" line — your diff's files matched against tag `contextPaths`. Treat it
+  as a checklist prompt, not an order: update a listed tag's
+  overview/description only when your change altered what the term means, add
+  the tag to the card only when the work is genuinely about that area, and
+  skip freely otherwise. Never bulk-assign tags from path matches alone.
+
+## Execute
+
+- **Status reflects reality**: claiming a card = `update_task` →
+  `status: "InProgress"` plus a chat note saying who/where is working it.
+  Never hand-move a card to `ReviewPR` or set its PR link — that transition
+  belongs to `create_pull_request` / the PR sync.
+- **Cloud or local**: `mcp__conveyor__start_task` boots a cloud agent
+  environment for an Open card (that agent run is the card's "build" —
+  `mcp__conveyor__get_build_status` reports it). To execute cards on the
+  local machine instead, use the `conveyor-local-loop` skill. Don't do both —
+  a started task's agent will duplicate local work.
+- **Reserved-branch trap**: a card with an assigned agent may have a reserved
+  `githubBranch`. Check `get_task` before pushing: if set, push to THAT
+  branch; a PR from any other branch gets auto-closed and unlinked.
+- **Chat is the log**: post at real milestones — claim, blocking discovery,
+  decisions, gates green, PR — not play-by-play. Findings (root causes, dead
+  ends, verification results) belong in task chat, not just your session.
+- **Files**: `mcp__conveyor__upload_attachment` hosts images/video/files on
+  the card; the returned URL is reusable in PR bodies. Attach visual evidence
+  for UI changes before opening the PR.
+- **Found-but-not-fixed** → a follow-up card with enough context to execute
+  cold, not a TODO in chat.
+
+## Open the PR — two paths, pick exactly ONE
+
+| Situation | Path |
+| --- | --- |
+| A card exists (found or created) | `mcp__conveyor__create_pull_request` — one call opens the PR, links the card, moves it to ReviewPR. Pass `head:` if the card has no branch. |
+| No card exists | Open the PR with your git host's normal tooling and STOP — Conveyor's PR sync spawns and links a card itself. |
+
+Card linking belongs to exactly one actor, never you by hand. Mixing paths is
+the known failure mode: a hand-moved card linked to nothing plus a
+sync-spawned duplicate.
+
+## Monitor and review
+
+- Monitor with `mcp__conveyor__get_task`, `mcp__conveyor__read_task_chat`,
+  and `mcp__conveyor__get_build_status`.
+- Reviewing a ReviewPR card: inspect the diff and task chat; approve with
+  `mcp__conveyor__approve_task` only if the PR implements the plan and
+  follows repo patterns — it advances the card through the review pipeline
+  (and, per project settings, approves/merges the PR). Otherwise
+  `mcp__conveyor__request_changes` with specific feedback, which returns the
+  card to the builder. Manual test checklists ride
+  `mcp__conveyor__set_manual_tests` and surface for human sign-off at the
+  review stage.
+- Don't approve or merge your own PRs unless the project's policy explicitly
+  allows it.
+- Remote workspace access (SSH/preview) goes through
+  `mcp__conveyor__workspace_start_tunnel` / `workspace_stop_tunnel` — one
+  canonical tunnel per task, torn down when done.
+
+## Reliability gotchas
+
+- **A mutating call that errors may have already landed.** "Session not
+  found" / timeout on `create_*`, `post_*`, `approve_*`, merge → check the
+  effect (`read_task_chat`, `get_task`, the PR) before re-firing; cap
+  identical retries at one. Blind re-fires double-post and double-approve.
+- **Git ground truth is remote-first** in agent pods and shared workspaces:
+  on a surprising conflict, failed push, or dirty tree, run `git ls-remote
+  origin <branch>` and `git merge-base --is-ancestor` before rebuilding
+  anything locally — platform autosync may have already pushed for you, and a
+  dirty tree may belong to a concurrent session.
+
+## Improve This Skill
+
+If this skill was insufficient or slowed the work down, file it with
+`mcp__conveyor__create_suggestion` on your current project: the issue,
+evidence, and proposed fix.

package/skills/conveyor-workflows/references/mcp-setup.md

@@ -0,0 +1,43 @@
+# Conveyor MCP Setup
+
+Use this when Conveyor MCP tools are missing, stale, or unauthenticated.
+
+## Preferred install path
+
+Ask the user to open Conveyor, choose the target project, then go to
+**Settings → User Settings** (`/projects/<project>/user-settings`). The
+**Connect Claude Code** section generates the exact install command / MCP JSON
+for their account and project — use that, not Project Settings and not the
+MCP Tools reference page.
+
+## Manual repair (Claude Code)
+
+```bash
+claude mcp remove conveyor -s local 2>/dev/null;
+claude mcp add conveyor -s local \
+  -e CONVEYOR_API_URL=<api-url> \
+  -e CONVEYOR_USER_TOKEN=<user-token> \
+  -e CONVEYOR_PROJECT_ID=<project-id> \
+  -- npx -y @rallycry/conveyor-mcp@latest
+```
+
+- Run from the repo folder; `-s local` scopes the server there.
+- The `remove` prefix makes token rotation idempotent.
+- Keep `@latest`; avoid unbuilt local packages.
+- `CONVEYOR_API_URL` and `CONVEYOR_USER_TOKEN` are required;
+  `CONVEYOR_PROJECT_ID` sets the default project (omit it to pass `projectId`
+  per call).
+- Non-Claude MCP hosts use the same command/env/package shape in their own
+  config format.
+
+After install, restart or reload MCP servers, then verify with
+`mcp__conveyor__get_connection_context` or `mcp__conveyor__list_tasks`.
+
+## Auth failure vs permission failure
+
+- Expired/invalid token → tools error with authentication failures; re-run
+  the connect flow above to mint a fresh token.
+- "Insufficient permissions" on a call that should work → check the
+  `projectId` first (a typo produces this exact error), then ask a project
+  admin about your role: mutations (tasks, builds, PRs) need Moderate access
+  or higher.