@rallycry/conveyor-skills 1.0.3 → 1.0.5

package/package.json

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

package/skills/conveyor-build/SKILL.md

@@ -38,6 +38,42 @@ out in an **Environment** note — never assume; check which one you are in.
   serially. Parallel fan-out is a deliberate choice the user makes by pressing
   Build on the parent, not something a build session opts into.
 
+## Goal and finish line
+
+Which goal applies depends on the route below. State it once, then hold it: a
+run ends when its finish line is true, not earlier.
+
+**Task path goal:** a pull request for this card.
+**Finish line:** the card in ReviewPR, the PR open, CI started. Then aftercare
+per `## Aftercare` — in a pod you stay wake-able; standalone locally you stop.
+**A task turn may end only when:** a harness-tracked background gate is in
+flight (Claude Code only); you are blocked on a human with the question posted;
+or the finish line is true.
+
+**Pack path goal:** the WHOLE pack, not one child. Per child the goal covers
+the full cycle: plan reviewed and promoted → implemented on the pack branch →
+gated → reviewer-of-record pass → merged (locally) or
+`mcp__conveyor__update_task` → ReviewDev (pod) → base synced. Then
+cross-reference, then the finale.
+**Finish line:** every child is ReviewDev, Complete, or Cancelled AND the
+parent's finale PR into the base branch is open with CI started. One child done
+is not the finish line. A turn that ends with a ready child and no wake armed
+is the failure this section exists to prevent.
+**A pack turn may end only when:** a harness-tracked background gate is in
+flight (Claude Code only — Codex holds the gate's command session open
+instead); you are blocked on a human with the parked protocol posted; or the
+finale PR is open and green-and-quiet. Nothing else. Anything else is a stalled
+run, not a paused one.
+
+**Runtime:** *Codex CLI* — before the first step (Setup step 1 on the pack
+path), create a thread goal with your goal tool whose objective is the finish
+line sentence for this route, naming the card slug. Call `update_goal` with
+`complete` only when that finish line is true (for a pack: the finale PR is
+open); `blocked` only per the parked protocol; never because the budget is
+low. *Claude Code* — there is no goal tool; the pacing rule in
+[references/pack-path.md](references/pack-path.md) is the loop, and its pack
+heartbeat is the fallback.
+
 ## Environment
 
 Resolve which one you are in before touching git or the filesystem.
@@ -236,13 +272,14 @@ the merged base.
 
 The card is in ReviewPR. What happens next depends on who is driving:
 
-> **Environment — a pod is woken; a standalone local run is not.** In a **pod**
-> you stay wake-able: the system wakes you on CI results and review comments,
-> so go idle rather than polling. In a **standalone local run** there is no
-> wake mechanism — report the card and PR state to the user and STOP. No
-> pacing, no loop, no babysitting; a follow-up CI fix is a fresh ask. Under
-> `conveyor-local-loop` the loop's own Babysit tier owns aftercare instead, and
-> its pacing rules govern.
+> **Environment — a pod is woken; a standalone local run is not.** In a
+> **pod** you stay wake-able: the system wakes you on CI results and review
+> comments, so go idle rather than polling. That holds only once the PR exists
+> — mid-pack, nothing wakes either environment (see the pack path's pacing
+> rule). In a **standalone local run** there is no wake mechanism — report the
+> card and PR state to the user and STOP. No pacing, no loop, no babysitting;
+> a follow-up CI fix is a fresh ask. Under `conveyor-local-loop` the loop's
+> own Babysit tier owns aftercare instead, and its pacing rules govern.
 
 When you are the one handling it:
 

package/skills/conveyor-build/references/pack-path.md

@@ -82,23 +82,65 @@ session memory for pack state.
 
 Work children **one at a time**. Interleaving them thrashes branch state.
 
-## Pacing — a pack is many turns, not one
-
-A pack of any size will not fit in a single turn, and there is no partial
-credit for a tree left mid-child. Treat **one iteration = one step** (implement
-one child, or merge one, or the finale) and end the turn on a committed,
-pushed state.
-
-- Driven by `/loop` (locally) or woken by events (in a pod): do one step, then
-  end the turn. Under `/loop` with no interval, arm the next wake before
-  ending — short (60–90s) while there is a child ready to work, long
-  (1200–1800s) while waiting on something external, and **stop the loop** once
-  the finale PR is open and quiet.
-- Invoked bare with no loop: do one step, report where the pack stands and what
-  the next step is, and stop. Do not self-schedule.
+## Pacing — a pack is many steps, not many turns
+
+A child boundary is not a turn boundary. Keep driving the pack in the same
+turn: merge, implement the next child, merge, cross-reference, finale. Nothing
+wakes a pack session between children — not locally, and not in a pod, where
+children have no PRs, no builds, and no CI to generate an event. A turn that
+ends with a child still ready is a stalled pack, not a paused one: locally it
+sits until a human re-runs the skill; in a pod it idles out, sleeps, and waits
+on the pack watchdog — roughly an hour lost per occurrence.
+
+End a turn with children remaining ONLY when a wake is guaranteed:
+
+- **A background gate is in flight.** Its completion notification re-invokes
+  you. (Launch it with the harness's `run_in_background`; hand-rolled
+  backgrounding wakes nothing.) *Codex CLI substitution:* Codex has no
+  background gate. Hold the gate's command session open until it returns an
+  exit result, then continue in the same turn — ending the turn is not how a
+  Codex runner waits.
+- **You are blocked on a human** — the parked protocol below. The user's chat
+  reply is the wake.
+- **The finale PR is open and quiet** — the Babysit tier. Green and quiet is
+  the end.
+
+Any other end-of-turn is runtime-specific:
+
+**Claude Code.** Arm `ScheduleWakeup` first: 60–90s, prompt restating which
+child comes next. That is the pod-sanctioned mechanism (the pod prompt allows
+`ScheduleWakeup` exactly when nothing else will notify you), and it is a rare
+exception, not the cadence. On top of it, run a **pack heartbeat**: at Setup,
+before the first child, arm ONE long fallback wake (`ScheduleWakeup`,
+1200–1500s) whose prompt is the pack continuation — "re-derive with
+`mcp__conveyor__list_subtasks` and take the next ready child; if nothing is
+ready and no gate is in flight, stop" — and re-arm it at every child boundary
+so exactly one is outstanding. A heartbeat that fires mid-work re-derives
+state and is a no-op. This is NOT the "insurance wakeup" the pod prompt
+forbids: that rule is about a background job's own completion notification,
+which does fire. Nothing at all notifies a pack between children, so the
+heartbeat is the only guaranteed wake a Claude pack has. Do not delete it.
+
+**Codex CLI.** There is no `ScheduleWakeup` and no `/loop`. The thread goal
+created per the SKILL.md *Goal and finish line* section is the continuation:
+an idle thread is re-prompted to keep working toward it. The only way to leave
+a child ready is therefore to keep working in the same turn — merge, next
+child, merge. Mark the goal complete only when the finale PR is open.
+
+Never end a turn "to report progress" — in either runtime, chat is where
+progress goes, and posting there does not end the pack.
+
+**Pre-exit invariant.** Before ending ANY turn, re-run
+`mcp__conveyor__list_subtasks`. A child that is `Open` with its dependencies
+met, or `InProgress` under your claim, plus no background job in flight and no
+parked question outstanding, means you are not done: continue, or arm the
+wake. Ending a turn in that state without a wake is the bug this section
+exists to prevent.
 
 `conveyor-local-loop` supplies its own pacing table and its own claim-marker
-prefix; when running under it, those govern.
+prefix; when running under it, those govern. Under `/loop` the invariant above
+still holds — the loop's re-invocation is a fallback for a dropped wake, never
+a reason to stop after one child.
 
 ## Implement a child
 

package/skills/conveyor-plan/SKILL.md

@@ -19,6 +19,34 @@ identification decides.** Moving the card to Open fires identification
 automatically (story points, icon, agent, and tags if you set none). Never set
 icon or story points yourself, and never `start_task` unless the user asks.
 
+## Goal and finish line
+
+**Goal:** a plan on this card that a context-free executor can build, or one
+batched round of questions for a human when scope is genuinely ambiguous.
+**Finish line:** the plan is saved with `mcp__conveyor__update_task` AND the
+recommendation is posted with `mcp__conveyor__post_to_chat` and
+`milestone: "plan_ready"`. In a pod, story points and risk are also set
+(`mcp__conveyor__update_task_properties`) and plan mode is exited.
+**A turn may end only when:** (a) the finish line above is true, or (b) an
+`AskUserQuestion` is pending. Nothing else. Anything else is a stalled run, not
+a paused one.
+
+**Never ask whether to start building, and never offer to.** Once the plan is
+saved, the handoff is not yours: in the cloud the system spawns a separate
+Builder session for the card, and locally a human runs `/conveyor-build` when
+they are ready. Until one of those happens, every further turn on this card is
+a plan iteration — read the feedback, revise, re-save, re-post `plan_ready`.
+Do not claim the card, do not touch the tree, and do not invoke
+`/conveyor-build` unprompted. (Locally the user may ask for it in the same
+session; that request is the only trigger.)
+
+**Runtime:** *Codex CLI* — before Phase 0, create a thread goal with your goal
+tool whose objective is: "Save a plan on card <slug> that a context-free
+builder can execute, or ask the blocking questions; do not start
+implementation." Mark it complete only when the finish line is true, never
+because the budget is low. *Claude Code* — there is no goal tool; the finish
+line and the two turn endings above are the loop.
+
 ## Phase 0 — Resolve context
 
 1. `mcp__conveyor__get_connection_context` (all Conveyor tools fully-qualified;
@@ -135,7 +163,10 @@ touching Conveyor, unless they asked you to just ship it.
 > does not exist in a pod. In a pod, the card exists and you are on it: save
 > the plan with `mcp__conveyor__update_task` (`plan`, and `description` if it
 > needs sharpening), post the same recommendation message to chat with
-> `milestone: "plan_ready"`, and stop — a pod does not promote its own card to
+> `milestone: "plan_ready"`, and stop. "Stop" means end the turn with no
+> question about starting work — per *Goal and finish line*, the Builder is a
+> separate session the system spawns, and every later turn here is a plan
+> iteration. A pod does not promote its own card to
 > Open. A parked plan is never `blocked`: that milestone means you cannot
 > continue until a human acts, and it pages nobody. To page a person, ask them
 > with AskUserQuestion. If the pod also has to leave

package/skills/conveyor-review/SKILL.md

@@ -26,6 +26,30 @@ process, this skill loses: a project's own rules outrank a general one.
   PR touches are not this PR's job — note them in chat if they matter, or file
   a suggestion, but do not block on them.
 
+## Goal and finish line
+
+**Goal:** one verdict on this PR.
+**Finish line:** the environment's verdict tool returned success —
+`mcp__conveyor__approve_code_review` / `mcp__conveyor__request_code_changes`
+in a pod, `mcp__conveyor__approve_task` / `mcp__conveyor__request_changes`
+locally — OR a blocked note is posted with the specific blocker and no verdict
+(the `## Blocked` case).
+**A turn may end only when:** (a) the verdict call succeeded — read the
+response; a "superseded by a newer review cycle" error is not success; (b) the
+blocked note is posted; or (c) you pushed your own fix and are waiting for CI
+before approving. Nothing else. Findings posted with no verdict called is a
+stalled review, not a paused one.
+
+**Reviewer of record for a pack child** has no verdict tool: its finish line is
+the merge (locally) or the `mcp__conveyor__update_task` → ReviewDev write
+(pod), and the pack path's goal wording in conveyor-build governs instead.
+
+**Runtime:** *Codex CLI* — before reading the change, create a thread goal with
+your goal tool: "Render exactly one review verdict on PR <n> for card <slug>."
+Mark it complete only after the verdict call succeeded, never because the
+budget is low. *Claude Code* — there is no goal tool; the finish line above is
+the loop.
+
 ## Read the change
 
 1. `mcp__conveyor__get_task` for the plan — you cannot judge "does this do what
@@ -142,8 +166,10 @@ is the reviewer, and the independent review happens later on the pack's PR into
 
 - Apply the same criteria above. The absence of an automated pass makes this
   review more load-bearing, not less.
-- There is **no verdict tool** — merging the child PR is the approval. Say what
-  you checked in chat so the record exists.
+- There is **no verdict tool** — merging the child PR (locally) or the
+  `mcp__conveyor__update_task` → ReviewDev write (pod) is the approval, and
+  that write or merge is this review's finish line; the pack path's goal
+  wording applies. Say what you checked in chat so the record exists.
 - You wrote this code, which makes self-review the weak point. An independent
   reviewer with the diff and no memory of writing it catches what you cannot.