@rallycry/conveyor-skills 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-skills",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "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,9 @@ 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
 
@@ -216,6 +215,27 @@ behavior — do not go looking for why "unrelated" tests are running.
 > more broadly; if it does, let CI finish before merging. Confirm which case
 > you are in rather than assuming, since the two lead to opposite behavior.
 
+## A plan that turns on an unsettled question
+
+A plan you cannot execute correctly because a product choice was never made is
+not a blocker by itself. Check `list_decisions(card: "<slug>")` and the owning
+tag's overview first — the answer is often already there, and citing it is the
+whole point of the type. When it genuinely is not:
+
+- **Most of the time, decide and say so.** Write the choice into the plan as a
+  GIVEN / WHEN / THEN line under "Assumed behaviours" and keep building. A
+  reviewer who disagrees says so, and it costs one comment.
+- **Raise a decision when the answer changes what you build** and getting it
+  wrong means rework rather than a follow-up commit. `create_decision` blocks
+  this card by default, so proceed on the decision's default option and mark
+  the plan `Planned: <default> pending <decision url>` — the answer is written
+  back onto this card's plan when it settles.
+- **Park only when building on the default would be thrown away.** That is the
+  Blocked path below.
+
+The bar, and how to write options somebody can actually choose between, is in
+[../conveyor-plan/references/product-decisions.md](../conveyor-plan/references/product-decisions.md).
+
 ## Not every task ends in a PR
 
 `create_pull_request` is for work that changes code. Plenty of cards don't:

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>`.
 
@@ -162,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,
@@ -224,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
@@ -238,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.
 
@@ -248,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-consensus/SKILL.md

@@ -30,7 +30,8 @@ Announce a one-line plan naming the sources you found, then sweep. **Say what yo
 | Source | How |
 | ------ | --- |
 | Work channels | `read_channel_messages` per registered readable channel, paging back with `olderCursor` until the window covers the question. `authorIsBot` separates the team's discussion from Conveyor's own card feed — check it before treating a message as a teammate's. Read thread replies (`threadTs`) where a thread carries the argument. |
-| Conveyor cards | `search_tasks` with ALL `typeFilters` (task, incident, suggestion) and several keyword variants — the term, the term plus symptom words, the adjacent nouns people actually use. Incidents carry fingerprint dedup, so an incident's upvote count is itself a frequency signal. Check whether a decision card already exists; the doc is usually its input. |
+| Conveyor cards | `search_tasks` with ALL `typeFilters` (task, incident, suggestion) and several keyword variants — the term, the term plus symptom words, the adjacent nouns people actually use. Incidents carry fingerprint dedup, so an incident's upvote count is itself a frequency signal. |
+| Decisions | `list_decisions` — open ones are the questions on the table, Decided ones carry their resolution and are the project's own record of what it already settled. A verdict that contradicts a Decided decision has to say so and say why. `list_project_integrations` reports `decisions.openCount` / `decidedCount`, so you know whether there is a log here before you search it. |
 | Tags | `list_tags` then `get_tag` on the relevant ones — the overview is the project's own domain vocabulary, and it names the subsystems your categories should line up with. |
 | Card chat | `read_task_chat` on the cards the search surfaced. The argument usually lives in the chat, not the description. |
 | Meetings | If the meeting tools exist, list and read the ones in the window. A transcript is the densest source of "what people actually said" you will find. |
@@ -83,6 +84,48 @@ Chart rules that repeatedly matter: plain div/CSS charts over JS; one strong cha
 4. **Local sessions may also publish an Artifact** for a shareable URL, and `SendUserFile` the HTML — both are additive. In a pod neither exists; the attachment is the deliverable.
 5. **Revisions re-upload to the SAME card.** The doc is living; never fork it into `report-v2.html`.
 
+## Decision mode
+
+When the argument IS a decision card — the user named one, or the sweep found
+an open decision that this question is about — the shape changes. The doc is
+not a survey of opinion; it is the input to settling a specific question that
+has options, a deadline, and a default that wins if nobody acts.
+
+**Sources, in place of the Phase 1 table:**
+
+| Source | How |
+| ------ | --- |
+| The decision | `get_decision` — the context, every option's GIVEN / WHEN / THEN, every vote with who cast it and why, the running tally, and the cards it blocks. |
+| The thread | `read_task_chat` on the decision. The Slack and Discord replies already mirror here, so this is the whole discussion in one read. |
+| The impacted cards | Their plans say what each option would cost to build. A clean option that nobody can implement is not the cheap one. |
+| Everything else | The ordinary sweep above, scoped to the question. |
+
+**Weigh reasons, not counts.** Two people giving the same reason are one
+argument. A single vote with a concrete failure case outranks three with none.
+Say so explicitly in the verdict — a decision settled on a head count that
+contradicted the reasoning is the thing this mode exists to prevent.
+
+**Then settle it, in this order:**
+
+1. Attach the verdict HTML. **Where it lands depends on the surface**, and the
+   difference matters: a local MCP session's `upload_attachment` takes a
+   `taskId`, so send it to the DECISION card, titled with the question. The
+   in-pod tool takes no card argument and always posts to the session's own
+   card — so in a pod, attach it there and put the link in the resolution
+   notes rather than pretending it reached the decision.
+2. `resolve_decision` with the winning option, a resolution of one or two
+   plain sentences (255 characters), and `notes` linking wherever the
+   attachment actually landed.
+
+Step 2 is what makes it real: the resolution is written into the plan and the
+chat of every card the decision blocked and into the owning tags' overviews,
+and those cards become startable. Do not stop at the doc.
+
+**If the evidence does not settle it**, say that and do not resolve. Extend the
+deadline with `update_decision` and post what would settle it. A verdict of
+"this needs one more data point, and here is which" is a real answer; picking
+an option to look decisive is not.
+
 ## Phase 5: the consensus loop
 
 The doc is the midpoint, not the end. Expect and serve:

package/skills/conveyor-plan/SKILL.md

@@ -121,6 +121,17 @@ Ask the user only decisions that change the plan's shape — scope cuts, UX
 choices, irreversible tradeoffs. Batch them in one round; never drip. Facts
 the repo can answer are yours to find, not theirs.
 
+**Search the decision log first, and raise one when the user is not there.**
+`list_decisions(status: "Decided", tag: "<tag>")` often answers the question
+outright — an answered decision is the answer, and re-asking it is the waste
+this exists to stop. When it does not, and you are running headless, prefer
+`create_decision` over blocking on `AskUserQuestion`: a decision has a
+deadline, so it settles on its default rather than stalling, and it links the
+cards it blocks. Most forks are not decisions at all — see
+[references/product-decisions.md](references/product-decisions.md) for the bar,
+how to write options a person can actually choose between, and how to keep
+building while one is open.
+
 ## Phase 3 — Draft the plan
 
 Use the plan format in [references/plan-format.md](references/plan-format.md):

package/skills/conveyor-plan/references/product-decisions.md

@@ -0,0 +1,103 @@
+# Product decisions
+
+A product decision is a fork the plan cannot be right without — where two
+answers lead to two different, both-defensible builds, and picking one silently
+means somebody finds out at review. Conveyor has a card type for it:
+`create_decision` raises one with two or three options, a default, and a
+deadline; `list_decisions` finds the answer next time.
+
+Shared by the plan, triage, build, and review skills. The rules are the same
+wherever you are.
+
+## 1. Search before you ask
+
+A decision that was settled once must never be re-litigated. Before planning
+anything in an area:
+
+1. Read the owning tag's overview (`get_tag`) — a settled decision is written
+   into a `## Decisions` section there.
+2. `list_decisions(status: "Decided", tag: "<tag>")` — every row carries its
+   resolution, so the list IS the decision log.
+3. `list_decisions(card: "<slug>")` — what is blocking this card right now.
+
+Cite what you find. "We decided this on 2026-09-19: <resolution>" ends the
+question; re-opening it without new information wastes everybody's time.
+
+## 2. Most forks are not decisions
+
+The common case is an assumption you can simply state. Write it in the plan
+under **Assumed behaviours**, one GIVEN / WHEN / THEN line each:
+
+```
+## Assumed behaviours
+- GIVEN a decision with no votes, WHEN its deadline passes, THEN the default option wins.
+```
+
+A reviewer who disagrees says so, and it costs one comment. That is cheaper
+than a card, a deadline, and three people's attention.
+
+Raise a decision only when **all** of these hold:
+
+- Two or three options are genuinely defensible — you cannot pick on merit.
+- Getting it wrong means rework, not a follow-up commit.
+- Somebody other than you has to live with the answer.
+
+## 3. Writing one that is answerable
+
+- **The question is one plain sentence**, ending in a question mark. If it
+  needs two, it is two decisions.
+- **Two or three options.** More than three means the question is not framed
+  yet: narrow it, or split it.
+- **Each option is GIVEN / WHEN / THEN** — what the product does, concretely,
+  if this option wins. "Option B: use a queue" is not an option; "GIVEN a
+  second build request, WHEN one is already running, THEN it queues rather
+  than being refused" is.
+- **Mark the status quo.** The option describing what the code does today gets
+  `kind: "current"`; an already-agreed-but-unbuilt one gets `kind: "planned"`.
+  A reader six months later needs to know whether the winner was a change.
+- **Name the default and what it costs if wrong.** The default wins on
+  silence. If silence would be dangerous, say so in the context — and set a
+  shorter deadline.
+- **Link the cards it blocks.** They cannot start until it settles, and they
+  un-block the moment it does. In a pod this includes your own card by
+  default.
+- **Tag it.** The settled answer is written into each tag's overview, which is
+  how the next agent finds it without knowing the decision exists.
+
+## 4. Keep moving
+
+Raising a decision is not a reason to stop. Either:
+
+- **Proceed on the default.** Mark the plan: `Planned: <default option>
+  pending <decision url>`. If the decision settles differently, the write-back
+  lands on this card's plan and the card is un-blocked with the correct answer.
+- **Park**, per the parked protocol in
+  `conveyor-build/references/pack-path.md`, when building on the default would
+  be actively unsafe or would be thrown away.
+
+Never sit idle waiting for a vote.
+
+## 5. Settling one
+
+`resolve_decision` is not a formality. The resolution is written into the plan
+and the chat of every card the decision blocked, and into the overview of every
+tag it carries — and those cards become startable. So:
+
+- Write the resolution as one or two plain sentences a non-engineer can read.
+  A reader months later should not have to open the thread.
+- Weigh the reasons, not the count. Two people with the same reason are one
+  argument.
+- Put the reasoning in `notes`, and link any verdict attachment there.
+
+**A reviewer does not settle decisions.** A review runs against a diff that
+already exists. If the diff turns on an unsettled decision, say so on the PR
+and cite it — `resolve_decision` is refused in review mode for that reason.
+
+## 6. When nobody answers
+
+At the deadline, the sweeper settles it: the plurality winner, or the default
+on a tie or an empty ballot, stamped `resolvedHow: "deadline"`. Silence becomes
+a decision rather than a stall. A reminder lands in the thread a day before.
+
+That is why the default is required, and why it has to be the answer you can
+live with.

package/skills/conveyor-review/SKILL.md

@@ -115,6 +115,17 @@ You have write access. Use it in proportion:
 
 Fixing something you do not fully understand is worse than flagging it.
 
+**A finding that turns on a product choice is neither.** When the diff is
+defensible and the disagreement is really "should the product do X or Y", check
+`list_decisions` first: if it was settled, cite the resolution and the diff is
+either right or wrong on the record. If it was never settled, say so in the
+verdict and name the fork — do NOT settle it yourself. `resolve_decision` is
+refused in review mode for that reason: a review runs on a fixed budget against
+a diff that already exists, and settling a decision writes that answer into
+every card it was blocking. Raising one is fine if the fork is real; the author
+or a moderator settles it. See
+[../conveyor-plan/references/product-decisions.md](../conveyor-plan/references/product-decisions.md).
+
 ## The verdict
 
 > **Environment — the tools differ, and only one pair exists per surface.**
@@ -151,8 +162,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
@@ -173,6 +184,19 @@ is the reviewer, and the independent review happens later on the pack's PR into
 - 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

package/skills/conveyor-triage/SKILL.md

@@ -144,6 +144,14 @@ is still unknown — including what evidence would resolve it. Then move it to
 `Open`. "Needs a repro with the console open" is an actionable handoff;
 "couldn't reproduce" is not.
 
+**When the unknown is a product choice, not missing evidence**, the handoff is
+a decision rather than a triage note. "The code does X, the reporter expected
+Y, and both are defensible" is not something more logs will settle — raise it
+with `create_decision`, two or three options written GIVEN / WHEN / THEN, and
+link this card as impacted so it un-blocks the moment the question is answered.
+See
+[../conveyor-plan/references/product-decisions.md](../conveyor-plan/references/product-decisions.md).
+
 **Cancelling:** explain the actual behavior, then cancel.
 
 ## 7. File at least one suggestion — always

package/skills/conveyor-workflows/SKILL.md

@@ -38,9 +38,22 @@ and let Conveyor's own automation do the linking.
   it (post your context to its chat) rather than forking a duplicate.
 - **Classify**: buildable work → `mcp__conveyor__create_task`; an
   idea/improvement you are NOT committing to build →
-  `mcp__conveyor__create_suggestion`; incidents (production breakage) are
-  filed by monitoring and users through Conveyor's incident tooling — you
-  will usually *work* incident cards, not create them.
+  `mcp__conveyor__create_suggestion`; a product fork that has to be settled
+  before the work can be planned correctly → `mcp__conveyor__create_decision`;
+  incidents
+  (production breakage) are filed by monitoring and users through Conveyor's
+  incident tooling — you will usually *work* incident cards, not create them.
+- **Decisions**: a decision card holds one question, two or three options
+  written GIVEN / WHEN / THEN, a default that wins on silence, and a deadline.
+  It BLOCKS the cards it names until it settles, and un-blocks them the moment
+  it does — the answer is written into each of their plans and into the owning
+  tags' overviews, so the next agent finds it without knowing the decision
+  existed. Search with `mcp__conveyor__list_decisions` BEFORE planning in an
+  area: a settled
+  decision is the answer, and re-asking it is the waste the type exists to
+  stop. Most forks are not decisions — an assumption you can simply state
+  belongs in the plan as a GIVEN / WHEN / THEN line. The full bar is in
+  [../conveyor-plan/references/product-decisions.md](../conveyor-plan/references/product-decisions.md).
 - **Mechanics**: `create_task` takes the title, description, `plan`
   (markdown), and optional status/tags; cards start in `Planning`. Every
   status change you make goes through `mcp__conveyor__update_task`