@rallycry/conveyor-skills 1.0.4 → 1.0.6

package/package.json

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

@@ -33,10 +33,45 @@ out in an **Environment** note — never assume; check which one you are in.
 - **Never boot another environment for work you are doing.** Locally that
   means never `mcp__conveyor__start_task` (it exists only on the local/MCP
   surface, and it spawns a cloud pod that duplicates you). In a pod driving a
-  pack it means never `mcp__conveyor__start_child_cloud_build` /
-  `mcp__conveyor__stop_child_build` — you implement the children yourself,
-  serially. Parallel fan-out is a deliberate choice the user makes by pressing
-  Build on the parent, not something a build session opts into.
+  pack there is no tool that fires a child build at all — you implement the
+  children yourself, serially. A pack has one execution model in both
+  environments: one session owns all the state.
+
+## 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
 

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

@@ -19,7 +19,8 @@ alternative is where pack incidents come from.
    parent already InProgress/ReviewPR has a coordinator — report and stop
    rather than compete.
 2. **Ensure the pack branch exists on origin.** Use the card's `githubBranch`
-   if set; otherwise cut `ft/<parent-slug>` from `origin/dev`, push `-u`, and
+   if set; otherwise cut `ft/<parent-slug>` from `origin/<base>` (the card's base
+   branch — usually `dev`), push `-u`, and
    IMMEDIATELY record it: `mcp__conveyor__update_task` with
    `githubBranch: <branch>`.
 
@@ -96,18 +97,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
@@ -141,6 +163,12 @@ spell the argument differently (`base:` locally, `baseBranch:` in a pod).
 > always opens the PR for the card the session is bound to, so mid-pack it would
 > open the PARENT's PR early and strand every remaining child. One commit per
 > child keeps the single final PR reviewable child by child.
+>
+> Every child status write carries the child's id: claim with
+> `mcp__conveyor__update_task(task_id: <child>, status: "InProgress")` and land
+> with `update_task(task_id: <child>, status: "ReviewDev")`. Without `task_id`
+> the write targets the PARENT card you are bound to. No per-child build fires
+> in a pod, so a status you do not write is a board that silently lies.
 
 Before opening the child's PR, re-check the parent's status. If it went
 InProgress or ReviewPR, a coordinator took over: post that you are yielding,
@@ -203,12 +231,11 @@ leave the branch pushed, and stop.
    `githubBranch: <pack>`), advance the child by hand (`update_task` →
    `ReviewDev`), and post the drift to parent chat so it is visible.
 3. **Sync `dev` into the pack branch — yours to do, in either environment.**
-   (The fan-out cloud path had the server do this before each child launch; a
-   session driving the pack itself gets no such help and resolves conflicts
-   in-session.)
+   Nothing server-side syncs the pack branch for you; a session driving the
+   pack resolves conflicts in-session.
 
    ```bash
-   git checkout <pack> && git pull && git fetch origin dev && git merge origin/dev --no-edit && git push
+   git checkout <pack> && git pull && git fetch origin <base> && git merge origin/<base> --no-edit && git push
    ```
 
    **Merge, never rebase** — the pack branch is shared with open child PRs and
@@ -217,7 +244,7 @@ leave the branch pushed, and stop.
 
    If the merge drags in unrelated changes or errors, `dev` may have been
    rewound (a revert or force-push). Verify the previous sync point is still an
-   ancestor of `origin/dev` (`git merge-base --is-ancestor`); if it is not,
+   ancestor of `origin/<base>` (`git merge-base --is-ancestor`); if it is not,
    abort the merge and escalate rather than chasing the noise.
 4. Report the merge to parent chat in a line or two.
 
@@ -227,7 +254,7 @@ leave the branch pushed, and stop.
    pack branch's actual state against the acceptance and verification criteria
    — a real checklist pass, not a vibe. Small gap → fix on the pack branch.
    Substantial gap → a new child card with a plan, and the loop continues.
-2. Pre-PR protocol on the pack branch: sync `origin/dev` FIRST, then ONE
+2. Pre-PR protocol on the pack branch: sync `origin/<base>` FIRST, then ONE
    verification pass scoped to the pack's cumulative diff against `dev`
    (cross-package packs earn the full suite).
 3. `mcp__conveyor__create_pull_request` on the PARENT: `head:` the pack branch,

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
@@ -127,8 +151,8 @@ which no pod reviewer could follow. Same defect the story-points paragraph below
 already records.
 
 Story points are deliberately NOT yours to change. `update_task`'s agent
-surface omits `storyPointValue` on purpose, and a pod review session has no
-tool that carries it — so this used to be an instruction no reviewer could
+surface omits `storyPointValue` on purpose, and no pod tool carries the card's
+OWN story points — so this used to be an instruction no reviewer could
 follow. It is also a gate you sit behind rather than above: story points set
 the card's graduated merge minimum, so a reviewer that could lower them would
 be lowering the bar for merging the very PR under review. Flag a mis-sized
@@ -142,11 +166,26 @@ 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.
 
+## Reviewing a pack's finale PR
+
+A pack parent's PR into the base branch is an ordinary review of the pack's
+cumulative diff — there is no coordination job. The parent's own session
+implemented every child, so read the whole diff against the base and render one
+verdict as above. Child cards have no merge gate of their own, so correcting a
+CHILD's story points with `mcp__conveyor__update_subtask` (`storyPointValue`)
+when the actual work diverged from the estimate is legitimate here, in either
+direction — where the tool exists: a pod's review runner and a local session
+carry it, a task session flipped to review does not (flag the mis-size in the
+verdict instead). The parent card's own story points stay off-limits per the
+note above.
+
 ## Blocked
 
 If the PR cannot be reviewed as it stands — the plan is missing, the diff is