@rallycry/conveyor-skills 0.1.1 → 0.1.2

package/README.md

@@ -12,7 +12,9 @@ arrive through normal dependency bumps — no git submodules, no manual syncing.
 | --- | --- | --- |
 | `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 |
+| `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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-skills",
-  "version": "0.1.1",
+  "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.
@@ -114,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
@@ -122,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 |
 
@@ -149,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

@@ -1,6 +1,6 @@
 ---
 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.
+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
@@ -49,10 +49,13 @@ run /conveyor-local-loop over the children instead.
   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.
+- **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.

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.