@rallycry/conveyor-skills 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-skills",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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. 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.
+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; when the queue is empty it blocks on live board events via conveyor-wait and wakes seconds after a card becomes claimable, with a ~25 min fallback poll). 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
@@ -68,7 +68,7 @@ Each invocation does the FIRST of these that produces work, then paces:
    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.
+4. **Idle** — nothing claimable: arm the board-event wake (below), then pace long.
 
 ## Claiming
 
@@ -163,6 +163,62 @@ section only defines how it embeds in the loop:
   other cards. The user's chat reply un-parks it, and the next Recover tier
   retakes the slot.
 
+## Waking on board events
+
+An empty queue is not a quiet board. Rather than sleeping blind for 25 minutes,
+arm `conveyor-wait`: a CLI in `@rallycry/conveyor-mcp` that subscribes to the
+project's live card stream and exits the moment a card ENTERS a claimable
+state. A card created Open, a Cancelled card reopened, and a card reassigned to
+you all count; an edit to a card that already matched does not.
+
+Arm it on an idle iteration only (tier 4), and only when no wait from an earlier
+iteration is still running:
+
+```bash
+node_modules/.bin/conveyor-wait --scope mine,unclaimed --timeout 1740
+```
+
+Launch it with Bash `run_in_background: true` and end the turn. Its completion
+notification is the wake. The `ScheduleWakeup` you still arm is the fallback for
+the case where the wait dies silently — use the pacing table's background-gate
+row (1200–1800s), not a second, shorter timer.
+
+- Prefer `node_modules/.bin/conveyor-wait`. If it is absent, use
+  `npx -y -p @rallycry/conveyor-mcp@latest conveyor-wait`. The `-p` form
+  matters: inside the conveyor monorepo a bare
+  `npx @rallycry/conveyor-mcp` misresolves.
+- Narrow `--types` to whatever focus the user gave the loop invocation —
+  "focus on incidents" → `--types incident`. The default watches tasks,
+  incidents, and suggestions.
+- `--scope mine,unclaimed` mirrors the claiming filter: cards assigned to the
+  session owner plus unassigned cards. Use `--scope all` only when the user
+  asked the loop to watch the whole board.
+- `--statuses` defaults to `Open`, which is the claimable lane. Leave it alone
+  unless the user asked for something else.
+- Credentials come from the environment, then any `.mcp.json` from the working
+  directory up, then `~/.claude.json`. An agent Bash shell does not inherit the
+  MCP server's environment, so that file fallback is what makes this work at
+  all. Exit 1 means the wait could not run: no credentials, a rejected token, or
+  a project it cannot read. Read the stderr line, report it once, fall back to
+  plain timed polling, and do not re-arm it every iteration.
+
+**The result is advisory — the queue is still the source of truth.** The CLI
+prints one line of JSON and exits 0 in every non-error case:
+
+```
+{"reason":"event","card":{"id":…,"slug":…,"title":…,"type":…,"status":…,"assignedUserId":…}}
+{"reason":"timeout"}
+{"reason":"interrupted"}
+```
+
+On wake, run a normal iteration and re-enumerate with
+`mcp__conveyor__list_tasks`. By then the card may be claimed, cancelled, or
+blocked by a dependency — never claim straight from the wait payload.
+
+**Never arm a second wait.** On a wake where a wait process is still in flight
+and the queue is still empty, re-arm the fallback `ScheduleWakeup` and end the
+turn.
+
 ## Pacing (dynamic /loop only)
 
 Under `/loop` with no interval, end EVERY iteration with exactly one
@@ -170,9 +226,9 @@ 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" |
+| A background gate/agent/conveyor-wait 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 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 |
+| Queue enumerated as empty THIS iteration, all loop PRs green and quiet | 1200–1800s | queue empty; conveyor-wait armed, so this is only the fallback |
 | 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 |
 
 The long idle tier is EARNED, never defaulted: it requires having enumerated

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

@@ -68,8 +68,15 @@ run /conveyor-local-loop over the children instead.
 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.
+   else cut `ft/<parent-slug>` from `origin/dev`, push `-u`, and IMMEDIATELY
+   record it on the card — `mcp__conveyor__update_task` with
+   `githubBranch: <branch>` (the branch must already be pushed; the API
+   verifies the ref exists). This write is load-bearing, not bookkeeping:
+   identification mints a competing `conveyor/*` branch onto any branchless
+   card it processes, and every pack-child merge handler keys on the card's
+   recorded branch matching the PRs' real base — a drifted record strands
+   externally-merged children in ReviewPR. Name the branch in the claim post
+   too.
 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
@@ -138,7 +145,13 @@ that applies:
    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.
+   merged). Either way CONFIRM the child advanced to ReviewDev
+   (`mcp__conveyor__get_task`; allow ~1 min for the merge webhook). Still
+   ReviewPR after a local-merge fallback is an escalation, not a shrug — it
+   means the parent card's `githubBranch` has drifted from the real pack
+   branch: fix the parent record (`mcp__conveyor__update_task` with
+   `githubBranch: <pack>`), advance the child by hand (`update_task` →
+   ReviewDev), and post the drift to parent chat.
 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

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

@@ -29,8 +29,9 @@ patterns/design choices, **5 SP** only for hard work. Split anything larger.
 ## Packs (parent + child tasks)
 
 A **pack** is Conveyor's bundle shape: a parent card with child cards.
-`create_subtask(parentTaskId, ...)` is the **only** way to parent a card —
-`create_task`/`update_task` have no parent field. Each child is a full card
+`create_subtask(parentTaskId, ...)` creates a NEW child; to move an EXISTING
+card under a parent (or out of one) use `set_task_parent`. `create_task` /
+`update_task` have no parent field. Each child is a full card
 (own chat, plan, story points). Split into a pack only when the work is
 genuinely multiple independently buildable pieces (8-SP-tier); otherwise keep
 one card.

package/skills/conveyor-workflows/SKILL.md

@@ -56,7 +56,9 @@ and let Conveyor's own automation do the linking.
   `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__create_subtask` (new children) or
+  `mcp__conveyor__set_task_parent` (adopt an existing card into the pack, or
+  detach one with `parentTaskId: null`), 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
@@ -106,7 +108,9 @@ labels. Each tag carries a `description` (≤255 — the summary), an `overview`
   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.
+  a started task's agent will duplicate local work. That loop idles on
+  `conveyor-wait`, a CLI in `@rallycry/conveyor-mcp` that blocks until a card
+  becomes claimable, so an idle loop wakes on a board event instead of a timer.
 - **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.