@rallycry/conveyor-skills 1.0.4 → 1.0.5

package/package.json

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

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

@@ -96,18 +96,39 @@ 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.)
+  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 must 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. Never end a turn "to report
-progress" — chat is where progress goes, and posting there does not end the
-pack.
+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

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.