@rallycry/conveyor-skills 0.1.0 → 0.1.2

package/README.md

@@ -6,6 +6,16 @@ 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-task` | `/conveyor-local-task <card>` | Complete ONE card on this machine, from claim to PR |
+| `conveyor-local-pack` | `/loop /conveyor-local-pack <card>` | Drive one pack on this machine: every child, then the final parent PR |
+| `conveyor-local-loop` | `/loop /conveyor-local-loop` | Run this machine as a serial local agent: claim Open cards and packs, 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.2",
   "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

@@ -1,6 +1,6 @@
 ---
 name: conveyor-local-loop
-description: Run this machine as a serial local claudespace — pick the session owner's highest-priority Open Conveyor card, claim it, execute its plan to the PR finish line, repeat. One invocation = one iteration; run continuously with "/loop /conveyor-local-loop" (no interval) and it self-paces (~1-2 min between cards while the queue has work, ~25 min idle polls when empty). Use when the user says "/conveyor-local-loop", "start the local loop", "work my open cards locally", or wants planned cards executed with full local CPU/RAM instead of spawning claudespaces.
+description: Run this machine as a serial local claudespace — pick the session owner's highest-priority Open Conveyor card, claim it, execute its plan to the PR finish line, repeat. Handles single cards AND whole packs (an Open pack parent is driven end-to-end per conveyor-local-pack, then the loop moves on once the pack's final PR is open). One invocation = one iteration; run continuously with "/loop /conveyor-local-loop" (no interval) and it self-paces (~1-2 min between cards while the queue has work, ~25 min idle polls when empty). Use when the user says "/conveyor-local-loop", "start the local loop", "work my open cards locally", or wants planned cards executed with full local CPU/RAM instead of spawning claudespaces. For exactly one card use conveyor-local-task; for one pack and nothing else, conveyor-local-pack.
 ---
 
 # Conveyor Local Loop
@@ -26,20 +26,27 @@ adds only selection, claiming, cadence, and local-machine hygiene.
 - **Only cards created by the session owner** (match against
   `mcp__conveyor__get_connection_context`), status Open, unassigned. Teammates'
   cards and pod-claimed cards are off limits.
-- **Pack cards: parents never; children only while the pack is parked.** A
-  card with children is the coordinator itself — never claimable. A card with
-  a `parentTaskId` IS claimable, but only while the parent's status is neither
-  InProgress nor ReviewPR: the pack watchdog and the child-event notifier both
-  ignore parked parents, but an actively-orchestrating parent reads a headless
-  InProgress child as a dead agent environment and "recovers" it onto a cloud
-  pod (observed 2026-07-28 — duplicate implementation). Working a pack locally
-  means: leave the parent parked (never Build/start it), work the children
-  serially in dependency order, and the user merges each child PR into the
-  pack branch to unblock the next.
-- **Clean tree before any branch switch — hard rule.** Dirty `git status` at
-  iteration start → touch nothing, report, and idle: the cwd is probably the
-  user's interactive checkout. Recommend a dedicated checkout once
-  (`git worktree add ../<repo>-loop dev`) and running the loop session there.
+- **Pack cards: claim the whole pack; the parent card stays parked.** An Open
+  feature-branch pack parent that passes the claiming filters is claimable as
+  a PACK: enter pack mode (below) and drive every child to the final parent
+  PR per [conveyor-local-pack](../conveyor-local-pack/SKILL.md). Throughout,
+  the parent card itself stays PARKED — never Build/`start_task` it, never
+  set it InProgress; the finale `create_pull_request` is what moves it to
+  ReviewPR. A parent already InProgress/ReviewPR has (or had) an active
+  coordinator — hands off it AND its children: an actively-orchestrating
+  parent reads a headless InProgress child as a dead agent environment and
+  "recovers" it onto a cloud pod (observed 2026-07-28 — duplicate
+  implementation). A NON-feature-branch pack — children PR straight into dev,
+  so there is no pack branch to coordinate — is never claimed as a pack:
+  /conveyor-local-pack explicitly does not apply to it. Claim those children
+  individually, one per iteration, and only while the parent is parked.
+- **Run in the main workspace checkout — never a git worktree.** The fully
+  provisioned main workspace (installed `node_modules`, `.env`/direnv auth
+  wiring, the running dev stack) is the whole value of local execution;
+  worktrees miss all of it and have consistently degraded agent sessions.
+  Clean tree before any branch switch is still a hard rule: dirty
+  `git status` at iteration start → touch nothing, report, and idle — the
+  resolution is the user committing or stashing, not a second checkout.
 - **Push early.** There is no pod WIP-autosync locally; committed-and-pushed is
   the only durable state. Push the branch (`-u origin`) as soon as it exists.
 
@@ -49,10 +56,17 @@ Each invocation does the FIRST of these that produces work, then paces:
 
 1. **Recover** — a card with my `[local-loop] claimed` chat marker still
    InProgress without a PR? Resume it. The branch may already exist locally or
-   on origin — check both before re-implementing anything.
-2. **Babysit** — my loop-opened PRs (ReviewPR cards): red CI → fix now;
-   request-changes or unanswered review comments → address now; green and
-   quiet → leave alone.
+   on origin — check both before re-implementing anything. A pack parent
+   whose chat carries my `[local-loop] claimed — driving this pack` marker
+   and isn't yet in ReviewPR? Resume pack mode — re-derive where it left off
+   from `mcp__conveyor__list_subtasks`, never from session memory. Skip a
+   parent whose LATEST marker is `[local-loop] parked:` with no human reply
+   after it — that pack yielded the WIP slot and stays yielded until the user
+   replies; fall through to the next tier.
+2. **Babysit** — my loop-opened PRs (ReviewPR cards, pack finale PRs
+   included): red CI → fix now (on a pack finale, directly on the pack
+   branch); request-changes or unanswered review comments → address now;
+   green and quiet → leave alone.
 3. **Claim** the next card (below).
 4. **Idle** — nothing claimable: pace long.
 
@@ -62,17 +76,25 @@ Each invocation does the FIRST of these that produces work, then paces:
    priority-then-newest ordered; board priority IS the intelligence, don't
    invent your own ranking. Walk top-down, `mcp__conveyor__get_task` each until
    one passes: created by me, no assignee or active session, an executable
-   plan, all `mcp__conveyor__get_dependencies` blockers Complete, no
-   `[local-loop] parked:` chat marker without a later human reply (a reply
-   un-parks), no child tasks of its own, and — if it has a `parentTaskId` —
-   the parent's status is neither InProgress nor ReviewPR (see ground rules).
+   plan (a pack parent that still needs breakdown is fine — breakdown is
+   pack-mode work), all `mcp__conveyor__get_dependencies` blockers Complete,
+   no `[local-loop] parked:` chat marker without a later human reply (a reply
+   un-parks), and the pack rules hold: a FEATURE-BRANCH pack parent (children
+   branch from and PR into a pack branch — including one planned as a pack
+   that has no children yet) is claimed as a PACK → pack mode below; a
+   non-feature-branch parent, whose children PR straight into dev, is never
+   claimable — take its children one at a time instead; a card with a
+   `parentTaskId` only while the parent's status is neither InProgress nor
+   ReviewPR (see ground rules).
    Skip `followParentStatus` mirror children. A blocker counts as met only
    when merged-or-beyond (ReviewDev/ReviewLive/Complete) or Cancelled — a
    blocker sitting in ReviewPR is NOT met until its PR merges.
 2. Claim: re-confirm via `get_task` it is still Open, then
    `mcp__conveyor__update_task` → `status: "InProgress"`, then
    `mcp__conveyor__post_to_chat`: `[local-loop] claimed — working locally on
-   <hostname>`. Status changed under you → someone else took it; next
+   <hostname>`. Claiming a PACK is different — never set the parent
+   InProgress: leave it Open and post the pack claim marker instead (see Pack
+   mode). Status changed under you → someone else took it; next
    candidate.
 3. Plan missing or failing the context-free-reader bar → don't wing it: post
    what's missing to chat, leave the card Open, skip it.
@@ -81,7 +103,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
@@ -111,6 +136,33 @@ specific question>`, set status back to `"Open"`, restore the tree
 (`git checkout dev`), move on. The user's next chat reply is the un-park
 signal.
 
+## Pack mode
+
+Claiming an Open pack parent means driving the ENTIRE pack, exactly per
+[conveyor-local-pack](../conveyor-local-pack/SKILL.md) — setup (pack branch on
+origin, child breakdown if the parent has none yet), children serially in
+dependency order, reviewer-of-record review + merge of each child PR into the
+pack branch, dev→pack sync after every merge, cross-reference, then the finale
+parent PR into dev. That skill is the source of truth for the procedure; this
+section only defines how it embeds in the loop:
+
+- The pack occupies the loop's single WIP slot from claim until the finale PR
+  opens. Do not interleave unrelated cards mid-pack — that thrashes branch
+  state.
+- Claim marker goes to the PARENT chat: `[local-loop] claimed — driving this
+  pack locally on <hostname>, pack branch <branch>`. The parent's status
+  stays Open (parked); the marker is the claim.
+- Once the finale PR is open (parent in ReviewPR), the pack leaves the WIP
+  slot: its PR joins the Babysit tier like any other loop-opened PR, and the
+  loop resumes claiming other cards. This is the one difference from
+  standalone /conveyor-local-pack, which stops when the pack is done.
+- Parked children follow conveyor-local-pack's parked protocol. If every
+  remaining child is blocked on the user, the pack yields the WIP slot: post
+  `[local-loop] parked: <what it is waiting on>` to the PARENT chat — that
+  marker is what makes the Recover tier skip the pack — and the loop claims
+  other cards. The user's chat reply un-parks it, and the next Recover tier
+  retakes the slot.
+
 ## Pacing (dynamic /loop only)
 
 Under `/loop` with no interval, end EVERY iteration with exactly one
@@ -119,7 +171,7 @@ Under `/loop` with no interval, end EVERY iteration with exactly one
 | State | Delay | Reason should say |
 |-------|-------|-------------------|
 | A background gate/agent is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs — its notification wakes me sooner" |
-| ANY actionable work exists: claimable cards, a PR still to open, red/pending CI, review comments | 60–90s | queue depth / which item is next |
+| ANY actionable work exists: claimable cards or packs, a pack child to implement/merge, a PR still to open, red/pending CI, review comments | 60–90s | queue depth / which item is next |
 | Queue enumerated as empty THIS iteration, all loop PRs green and quiet | 1200–1800s | queue empty, idle poll |
 | 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 |
 
@@ -146,9 +198,9 @@ depth each iteration so the user can offload manually.
   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.
-- Not a parallel executor: one card at a time is the point (the full machine
-  per gate). Backlogged? That is what claudespaces — or the offload valve —
-  are for.
+- Not a parallel executor: one card (or one pack) at a time is the point (the
+  full machine per gate). Backlogged? That is what claudespaces — or the
+  offload valve — are for.
 
 ## Improve This Skill
 

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

@@ -0,0 +1,210 @@
+---
+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. For a single non-pack card use conveyor-local-task; to work the whole Open queue (packs included) use conveyor-local-loop.
+---
+
+# 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.
+- **Run in the main workspace checkout — never a git worktree.** The fully
+  provisioned main workspace (installed `node_modules`, `.env`/direnv auth
+  wiring, the running dev stack) is the whole value of local execution;
+  worktrees miss all of it and have consistently degraded agent sessions.
+  Clean tree before any branch switch is still a hard rule: dirty
+  `git status` at iteration start → touch nothing, report, idle — the
+  resolution is the user committing or stashing, not a second checkout.
+- **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-local-task/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: conveyor-local-task
+description: Complete ONE linked Conveyor card on this machine, start to ReviewPR — claim it, execute its plan in the main workspace, gate, open the PR, report, done. Use when the user says "/conveyor-local-task <card>", "do this card locally", or "complete this task on my machine". One card only, no queue and no loop — for a whole pack use conveyor-local-pack; to work everything Open (packs included) use conveyor-local-loop.
+---
+
+# Conveyor Local Task
+
+Execute one Conveyor card exactly as a claudespace agent would, using this
+machine instead of a pod: 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 adds only claiming, routing, and local-machine hygiene. Finish line =
+card in ReviewPR with CI started; the user reviews and merges.
+
+## Ground rules
+
+- **All Conveyor tools fully-qualified** (`mcp__conveyor__get_task`; bare
+  names fail).
+- **Run in the main workspace checkout — never a git worktree.** The fully
+  provisioned main workspace (installed `node_modules`, `.env`/direnv auth
+  wiring, the running dev stack) is the whole value of local execution;
+  worktrees miss all of it and have consistently degraded agent sessions.
+  Clean tree before any branch switch is a hard rule: dirty `git status` →
+  touch nothing and report — the resolution is the user committing or
+  stashing, not a second checkout.
+- **Never `mcp__conveyor__start_task`** — that boots a cloud pod and
+  duplicates the work you're about to do locally.
+- **Never approve or merge your own PR.** ReviewPR with green-or-running CI
+  is where you stop.
+- **Push early.** There is no pod WIP-autosync locally; committed-and-pushed
+  is the only durable state. Push the branch (`-u origin`) as soon as it
+  exists.
+- **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.
+
+## Resolve and route
+
+1. Resolve the card from the argument (slug, id, or URL; none given → ask
+   which card). `mcp__conveyor__get_task` for the full plan +
+   `mcp__conveyor__read_task_chat` for addenda and user answers. Consult
+   `mcp__conveyor__get_tag` on the card's tags before diving in — the
+   overview + linked files are the fast path into the subsystem.
+2. Route pack cards away:
+   - Card **has children** → it's a pack coordinator; point the user at
+     `/conveyor-local-pack` and stop. Children that PR straight into dev are
+     not a feature-branch pack — point at `/conveyor-local-loop` instead, or
+     run this skill on one child card.
+   - Card **has a `parentTaskId`** and the parent is InProgress or ReviewPR →
+     decline: an actively-orchestrating parent reads a headless InProgress
+     child as a dead agent environment and "recovers" it onto a cloud pod
+     (duplicate implementation). Parent parked → proceed; the child's base is
+     the parent's feature branch.
+3. Plan missing or failing the context-free-reader bar → don't wing it: post
+   what's missing to chat and stop. The card must stand alone.
+
+## Claim and execute
+
+1. Re-confirm via `mcp__conveyor__get_task` that the card is claimable (Open —
+   or whatever the user explicitly overrode — with no assignee or active
+   session), then `mcp__conveyor__update_task` → `status: "InProgress"` and
+   `mcp__conveyor__post_to_chat`: `[local-task] claimed — working locally on
+   <hostname>`.
+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
+   branch — a prior pod may have landed real work; audit it before
+   re-implementing anything. Else `git fetch origin <base> && git checkout -B
+   <feat|fix|chore>/<slug> origin/<base>`. Reinstall deps if the lockfile
+   changed.
+3. Work the plan. Post chat updates at real milestones only (claim, blocking
+   discovery, gates green, PR) — not play-by-play.
+4. Verify per the host repo's CLAUDE.md policy (scoped gates). UI-visible
+   change → capture screenshot/recording evidence with the repo's tooling and
+   attach via `mcp__conveyor__upload_attachment` before opening the PR.
+5. Refresh against the base (`git fetch origin <base> && git merge
+   origin/<base> --no-edit && git push`), then
+   `mcp__conveyor__create_pull_request` with `head:` your branch and — always
+   explicitly — `base:` the card's base branch. The card moves to ReviewPR.
+   Post a chat summary: what shipped, how verified, what to look at.
+6. Confirm CI actually started (read-only `gh pr checks`); do NOT wait on it.
+   Report the card + PR state to the user — done. No pacing, no loop, no
+   babysitting: follow-up CI fixes are a fresh ask.
+
+**Blocked** — after 2 genuinely different failed approaches, or on a decision
+only the user can make: post to chat the reason + the specific question, set
+the card back to `"Open"`, restore the tree (`git checkout dev`), and report.
+
+## 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.