@rallycry/conveyor-agent 10.13.71 → 11.0.0

package/skills/conveyor-build/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: conveyor-build
+description: Execute a planned Conveyor card to a pull request — one task or a whole feature-branch pack — then stay wake-able for review feedback and CI. Use when the user says "/conveyor-build <card>", "build this card", "implement this card", "run this pack", or when a claudespace session is told to follow its card's plan. Works identically in a cloud pod and in a local checkout; the card is the spec and task chat is the log. For producing the plan in the first place use conveyor-plan; to work a whole queue of Open cards use conveyor-local-loop.
+---
+
+# Conveyor Build
+
+Take a card that already has a plan and drive it to a pull request, then stay
+reachable for review feedback and CI. The card IS the spec, task chat is the
+log, and the host repo's CLAUDE.md governs gates, verification, and PR
+mechanics. This skill adds routing, claiming, and the pack chain.
+
+**One skill, two environments.** Everything below applies in a cloud pod and in
+a local checkout alike. Where they genuinely differ, the difference is called
+out in an **Environment** note — never assume; check which one you are in.
+
+## Ground rules
+
+- **Conveyor is the state store.** A build spans hours or days and the session
+  gets compacted. Re-derive state from `mcp__conveyor__get_task` +
+  `mcp__conveyor__list_subtasks` at every decision point, never from
+  conversation memory.
+- **All Conveyor tools fully-qualified** — `mcp__conveyor__get_task`, not
+  `get_task`. Bare names fail.
+- **The card must stand alone.** If you find yourself relying on session
+  memory or on this conversation, stop and re-read the card. A plan that fails
+  the context-free-reader bar is a blocker, not something to wing: post what is
+  missing to chat and stop.
+- **Never approve or merge your own PR into `dev`.** Finish line = the card in
+  ReviewPR with CI started. The exception is narrow and lives in the pack path:
+  you ARE the reviewer of record for a pack's CHILD PRs into the pack branch,
+  because the automated reviewer skips those.
+- **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.
+
+## Environment
+
+Resolve which one you are in before touching git or the filesystem.
+`mcp__conveyor__get_connection_context` answers it: a pod session reports a
+task binding and no user account.
+
+**In a pod:**
+
+- Uncommitted work is auto-snapshotted to `conveyor-wip/<branch>` after every
+  turn, so a sleep or crash does not lose the tree. Commit and push anyway as
+  soon as a chunk is coherent — committed work never depends on that mechanism.
+- `mcp__conveyor__create_pull_request` stages, commits, and pushes for you.
+- Capture UI evidence with the repo's own harness (in this repo,
+  `scripts/agent/shot.ts`) and attach with `mcp__conveyor__upload_attachment`
+  before opening the PR.
+- The database and dev server belong to this pod alone — experiment freely.
+
+**Locally:**
+
+- There is NO WIP autosync. Committed-and-pushed is the only durable state:
+  push the branch (`-u origin`) the moment it exists, and always before a long
+  background job or a wait.
+- `mcp__conveyor__create_pull_request` opens a PR for a branch you have ALREADY
+  pushed. Push first.
+- Work in the main checkout, **never a git worktree** — the provisioned
+  workspace (installed dependencies, env/direnv auth wiring, a running dev
+  stack) is the entire value of local execution, and worktrees have none of it.
+  A dirty `git status` before any branch switch is a hard stop: report and let
+  the user commit or stash. Do not solve it with a second checkout.
+- The dev database and dev-server ports are shared with the user's own
+  sessions. No destructive experiments, never reset the dev DB, and reuse a
+  running dev stack rather than fighting over ports.
+
+## Resolve and route
+
+1. Resolve the card from the argument — slug, id, or URL. **None given → ask
+   which card.** Never infer one from the branch you happen to be on.
+2. `mcp__conveyor__get_task` for the full plan and
+   `mcp__conveyor__read_task_chat` for addenda and user answers. Consult
+   `mcp__conveyor__get_tag` on the card's tags before diving in — a tag's
+   overview and linked files are the fast path into the subsystem.
+3. Route on the card's shape:
+
+| Card shape | Path |
+| --- | --- |
+| No children | **Task path** — [references/task-path.md](references/task-path.md) |
+| Has children, children PR into a **feature branch** | **Pack path** — [references/pack-path.md](references/pack-path.md) |
+| Has children that PR straight into `dev` | Not a pack chain. Build the children one at a time via the task path; leave the parent alone. |
+| Has a `parentTaskId` | Task path, but **only while the parent is parked** (neither InProgress nor ReviewPR). The child's base is the parent's feature branch, never `dev`. |
+
+> **Environment — a pod's pack runs one branch, not one branch per child.** The
+> pod's `create_pull_request` takes no task argument: it always opens the PR for
+> the card the session is bound to. A pod bound to the pack PARENT therefore
+> cannot open a CHILD's pull request, and must not try. It implements each child
+> directly on the pack branch, commits per child, moves the child's status with
+> `mcp__conveyor__update_task` (`task_id` + `status`), and opens exactly ONE pull
+> request at the end — the parent's, into `dev`.
+>
+> **Locally** each child gets its own branch and its own PR into the pack
+> branch, which is what makes them individually reviewable. Read the pack path
+> with that substitution in mind: everywhere it says "the child's PR", a pod
+> means "the child's commits on the pack branch", and the merge step becomes a
+> status write rather than a merge.
+
+**The parked-parent rule is load-bearing, not bookkeeping.** An actively
+orchestrating parent reads a headless InProgress child as a dead agent
+environment and "recovers" it onto a cloud pod — duplicate implementation of
+the same child. If the parent is InProgress or ReviewPR, decline the child and
+say why.
+
+## Claim
+
+Re-confirm the card is still claimable, then `mcp__conveyor__update_task` →
+`status: "InProgress"`, then `mcp__conveyor__post_to_chat` with a claim marker
+naming where you are running. Status changed under you → someone else took it;
+stop.
+
+**A pack parent is claimed differently** — see the pack path. The parent stays
+parked and the chat marker IS the claim.
+
+## Work the plan
+
+Post to chat at real milestones only — claim, a blocking discovery, gates
+green, PR — never play-by-play. Your turn output is not visible to the team;
+chat is.
+
+**Saving the plan and card fields:** `mcp__conveyor__update_task` handles
+title, description, plan, status, and `githubBranch` on both surfaces. Story
+points and risk are the one split: the local `update_task` carries them, the
+pod's does not — in a pod they go through
+`mcp__conveyor__update_task_properties`. Correct them when the work turns out
+materially bigger or smaller than the estimate, in either direction; a stale
+estimate is worse than a corrected one. Never re-size a card to make a gate, a
+transition, or a review pass.
+
+> **Environment — exiting plan mode in a pod.** A pod in discovery mode cannot
+> leave plan mode until the card has a plan, a title, story points, AND a risk
+> level. `update_task` carries neither of the last two, so that step needs
+> `mcp__conveyor__update_task_properties`. A pod exposes it in `discovery`,
+> `auto`, `building` and `chat` modes — but NOT in `review`, and not to a pack
+> parent. If you hold neither tool, you are not the session that is supposed to
+> be sizing the card: say so in chat rather than trying to force the transition.
+
+## Verify
+
+Follow the host repo's CLAUDE.md verification policy — scope the gates to your
+diff rather than running everything. Never open a PR with known-failing gates,
+and never silence a failure with a filter, a `.skip`, or a "known flake" note:
+either your diff broke it, or the test is broken or environment-dependent and
+you fix the test.
+
+**A UI-visible change needs visual proof before the PR**, in both environments:
+capture a screenshot (static) or a short recording (interaction) with the host
+repo's own tooling and attach it with `mcp__conveyor__upload_attachment`, then
+embed the returned URL in the PR body. A UI PR without it is incomplete.
+
+**On a deep pack the gate surface grows, and that is expected.**
+`test:affected` diffs against `origin/dev`, so by the fourth child it also
+covers the three already merged into the pack branch. That is correct
+behavior — do not go looking for why "unrelated" tests are running.
+
+> **Repo config, not an environment difference — check it, don't assume it.**
+> Where CI is configured to run only on PRs into `dev`/`main` (this is the
+> Conveyor repo's config), a child PR into a pack branch gets **no automated
+> verification at all**, and your local gate pass is the ONLY gate before that
+> child merges — mandatory, never skippable. A consumer repo may trigger CI
+> 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.
+
+## Not every task ends in a PR
+
+`create_pull_request` is for work that changes code. Plenty of cards don't:
+support requests, config or credential help, answering a question,
+investigations, research whose deliverable is an answer or a file.
+
+If you finish with **no code changes** — an empty `git diff <base>..HEAD` —
+do NOT open a PR. An empty or throwaway PR exists only so a human can close it.
+Instead: post the answer, config, or findings with
+`mcp__conveyor__post_to_chat`, attach anything the user should keep with
+`mcp__conveyor__upload_attachment` (any file type, up to 25MB), and complete
+the card directly with `force_update_task_status("Complete")` — there is no PR
+or review step for a no-code task. Never publish a deliverable as an off-card
+link; the card is where it belongs.
+
+When unsure, check the diff: a real diff means open a PR, no diff means finish
+in chat and mark it Complete.
+
+## Open the PR
+
+Refresh against the card's base first, then gate, then open — in that order, so
+nothing invalidates the verification you just did:
+
+1. `git fetch origin <base> && git merge origin/<base> --no-edit`
+2. One verification pass, scoped to the diff.
+3. `mcp__conveyor__create_pull_request`, naming the base branch **explicitly**.
+   **The two surfaces spell these differently and unknown keys are silently
+   dropped, not rejected** — locally it is `head:` / `base:`; in a pod it is
+   `branch:` / `baseBranch:`. Passing the local names in a pod does not error,
+   it just leaves the base unset, and the server then falls back to the base
+   recorded on the card. That fallback is usually right and is exactly why the
+   mistake is invisible — until the card's recorded branch has drifted, and the
+   PR opens against `dev`.
+4. **Publish the PR guide** with `mcp__conveyor__publish_review_guide`, right
+   after `create_pull_request` succeeds — it is part of opening a PR, not a
+   follow-up. `sections` is a top-level array argument, not prose stuffed into
+   `overview`; keep `overview` a short intro and order the sections with core
+   behavior first, tests and generated files later. Reference only files this
+   diff actually changed, never context you merely read. Anchors are optional
+   and strict — `{"path": "..."}` alone is the safe form. Republish for the new
+   head SHA after any later push, or the card's Guide tab shows stale. It is
+   best-effort: if it still fails after one corrected retry, carry on — it
+   never blocks opening or updating the PR.
+5. Post a chat summary: what shipped, how it was verified, what a reviewer
+   should look at, and anything you did NOT do.
+
+Then confirm CI actually started (read-only `gh pr checks`). Do not wait on it.
+
+**Do not re-merge the base and do not re-run a gate that already passed.** If
+the base moved while the gates ran, open the PR anyway — CI validates against
+the merged base.
+
+## Aftercare
+
+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.
+
+When you are the one handling it:
+
+- **Red CI** → fix it now, on the same branch. Read the failure before
+  concluding it is yours: a suite that fails on a file your diff never touched
+  is usually environment-dependent, and the honest fix is to the test, in the
+  same PR or a dedicated one.
+- **Review comments or requested changes** → address them, then reply saying
+  what changed.
+- **Green and quiet** → leave it alone. Do not poll.
+
+## Blocked
+
+After two genuinely different failed approaches, or on a decision only the user
+can make: post the reason AND the specific question to chat, set the card back
+to `"Open"`, restore the tree (locally, `git checkout dev` — leaving a shared
+checkout parked on an abandoned feature branch is how the next session starts
+from the wrong base), and stop. A vague "this is hard" is not a handoff; the
+question is what makes it one.
+
+**A thin plan is a different case, and it does not stop a pack.** A card whose
+plan fails the context-free-reader bar: post what is missing to its chat and
+stop — but inside a pack, skip that child and take the next ready one instead
+of halting the whole chain.
+
+## Improve This Skill
+
+If this skill was insufficient or slowed the work down, file it with
+`mcp__conveyor__create_suggestion` on the Conveyor project: the issue,
+evidence, and proposed fix.

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

@@ -0,0 +1,224 @@
+# Pack path — a feature-branch pack, start to one PR
+
+The pack execution core of [conveyor-build](../SKILL.md). Read that first;
+ground rules, environment differences, verification, and aftercare live there.
+
+A feature-branch pack is a parent card whose children branch from and PR into a
+shared **pack branch**, and which lands on `dev` as ONE final PR. Children that
+PR straight into `dev` are not this — build those individually via the task
+path.
+
+**You are both the coordinator and every child's implementer.** One session
+owns all the state, serially. That is the whole point: the distributed
+alternative is where pack incidents come from.
+
+## Setup (first iteration only)
+
+1. Confirm the shape: the parent has (or will have) children, its status is
+   neither InProgress nor ReviewPR, and no agent session is live on it. A
+   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
+   IMMEDIATELY record it: `mcp__conveyor__update_task` with
+   `githubBranch: <branch>`.
+
+   That write is load-bearing, not bookkeeping. Identification mints a
+   competing `conveyor/*` branch name 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 merged children in
+   ReviewPR.
+
+   **Push the branch first, and verify it yourself.** The local surface
+   validates the ref; the pod's `update_task` does NOT — it writes the value
+   through with no check that the branch exists on origin, and no guard
+   against repointing the record away from the branch the pod is actually
+   running on, which strands the compute. A successful write is not evidence
+   the branch is pushed.
+3. **No children yet?** Break the work down first: explore, save the
+   parent-level plan with `mcp__conveyor__update_task`, then
+   `mcp__conveyor__create_subtask` each child with a standalone plan
+   (file:line citations, verification steps) and `dependsOn` edges wherever one
+   blocks another.
+4. Post the claim marker to the PARENT chat, naming the pack branch. Use a
+   stable, greppable prefix — `[pack] claimed — …` — because the Recover tier
+   above finds your in-flight work by searching for it. (Under
+   `conveyor-local-loop`, its `[local-loop]` prefix replaces this.)
+
+**Locally, the parent card stays PARKED for the entire run** — never set it
+InProgress, never Build it; the final `create_pull_request` is what moves it to
+ReviewPR. The mechanism: the pack watchdog and the child-event notifier both
+ignore a parked parent, whereas an ACTIVE parent treats a headless InProgress
+child as a dead agent environment and "recovers" it onto a cloud pod —
+duplicate implementation of a child you are already writing (observed
+2026-07-28).
+
+> **Environment.** In a pod the parent is honestly InProgress with a live
+> session, and this parking rule does not apply — it exists specifically to
+> dodge cloud recovery of headless children, which is not a risk when the
+> parent's own session is the thing implementing them.
+
+## Each iteration: re-derive, then do the first thing that applies
+
+Re-read the parent and `mcp__conveyor__list_subtasks` every time. Never trust
+session memory for pack state.
+
+1. **Recover** — a child carrying your claim marker, InProgress, with no PR.
+   Its branch may already exist locally or on origin; audit what landed before
+   re-implementing.
+2. **Merge** — a child in ReviewPR. See "Merge a child" below.
+3. **Promote** — a `Planning` child whose plan is solid →
+   `mcp__conveyor__update_subtask` to `Open`. Genuinely not plannable →
+   escalate to parent chat.
+4. **Implement** — the next `Open` child whose dependencies are all met.
+   **A dependency counts as met only at ReviewDev/Complete (merged into the
+   pack) or Cancelled. ReviewPR is NOT met** — an unmerged PR is not a
+   foundation to build on. No `dependsOn` anywhere → ordinal order.
+5. **Finale** — every child at ReviewDev/Complete. See below.
+6. **Babysit** — the final PR is open. Fix red CI and answer review comments
+   directly on the pack branch; never claim or work children once the parent is
+   in ReviewPR. **Green and quiet is the end:** post the wrap-up to parent chat
+   and stop.
+
+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.
+
+`conveyor-local-loop` supplies its own pacing table and its own claim-marker
+prefix; when running under it, those govern.
+
+## Implement a child
+
+Reload the child's full plan fresh every time (`mcp__conveyor__get_task` +
+`read_task_chat`) — never work from what you remember of it. **A plan too thin
+for a context-free reader does not halt the pack:** post what is missing to
+parent chat, skip that child, and take the next ready one.
+
+Then follow [task-path.md](task-path.md), with one substitution: the child
+branches from the **pack branch**, not `dev`, and its PR's base is the pack
+branch. Name that base explicitly — the default is `dev`, and the two surfaces
+spell the argument differently (`base:` locally, `baseBranch:` in a pod).
+
+> **Environment — a pod has no child branches and no child PRs.** Everything
+> above describes the LOCAL model, where each child gets its own branch and its
+> own PR into the pack branch. A pod pack runner has one checkout and one
+> branch, so a child's work is simply **commits on the pack branch**. Do not cut
+> a child branch, and do not call `create_pull_request` for a child: that call
+> 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.
+
+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,
+leave the branch pushed, and stop.
+
+## Merge a child
+
+> **Environment — in a pod there is nothing to merge.** The child's commits are
+> already on the pack branch, so "merge a child" collapses to one write:
+> `update_task(task_id: <child>, status: "ReviewDev")`. Nothing else moves a
+> child — no per-child build fires — so a status you do not write is a board
+> that silently lies. The reviewer-of-record pass below still applies to the
+> commits; only the PR mechanics drop away.
+
+1. **Reviewer-of-record pass.** The automated reviewer skips PRs that target a
+   pack branch, so this is the only review that child gets — the independent
+   review happens later, on the pack's final PR into `dev`. Re-read the child's
+   plan, then read the FULL diff (`git diff origin/<pack>...origin/<child>`)
+   with reviewer eyes: plan coverage, stray files, pattern consistency, and
+   whether the gate pass actually happened. Found a real problem → fix it on
+   the child branch (you are also the implementer), re-gate, then continue.
+
+   You wrote this code, which makes self-review the weak point. Consider an
+   independent reviewer — a subagent with the diff and no memory of writing it
+   catches what you cannot.
+2. **Merge** via `mcp__conveyor__approve_and_merge_pr`. That call QUEUES the
+   merge (a ~30s sweep) rather than merging inline, so always confirm the PR
+   actually landed instead of trusting the response.
+
+   A pack-branch PR carries no CI checks. **Give the queue a couple of minutes
+   before concluding it cannot land it** — `passesCheckGate` treats
+   `zero_checks` as passed once past `isPastZeroCheckSettling`, and the
+   pack-child skip writes a terminal `approved` that satisfies the review gate.
+   Confirmed 2026-08-20 (PR #4224, ~4 min) and again 2026-08-27 (two pack-child
+   PRs, ~2 min each). The `merge-queue` tag has carried this since 2026-08-20;
+   this file and the `pack` tag were the surfaces still asserting otherwise. Checking once
+   and falling back immediately costs a rejected push and a reset.
+
+   Note the merge is a **squash**, so the child's commits are not ancestors of
+   the pack branch: `git merge-base --is-ancestor` reads false even when every
+   byte landed. Compare content (`git diff origin/<pack> <child-head>`), not
+   ancestry.
+
+   If it genuinely stalls, merge locally instead — GitHub then marks the PR
+   merged:
+
+   ```bash
+   git checkout <pack> && git pull && git merge --no-ff <child-branch> && git push
+   ```
+
+   (Observed 2026-08-26: zero-check pack-branch PRs merged straight through the
+   queue twice in a row, so treat the fallback as a fallback, not the expected
+   path. Older guidance said the queue could NEVER merge them; that is not what
+   the queue does today.)
+
+   Either way, CONFIRM the child reached ReviewDev (allow ~1 minute for the
+   merge webhook). **Still ReviewPR after a local merge is an escalation, not a
+   shrug** — it means the parent's recorded `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 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.)
+
+   ```bash
+   git checkout <pack> && git pull && git fetch origin dev && git merge origin/dev --no-edit && git push
+   ```
+
+   **Merge, never rebase** — the pack branch is shared with open child PRs and
+   WIP refs, and rewriting it breaks them. Conflicts are yours to resolve
+   properly; you wrote the code.
+
+   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,
+   abort the merge and escalate rather than chasing the noise.
+4. Report the merge to parent chat in a line or two.
+
+## Finale
+
+1. **Cross-reference.** For the parent plan and EVERY child plan, check the
+   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
+   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,
+   `base:` `dev`. The parent moves to ReviewPR. Post the pack summary: what
+   shipped per child, how it was verified, what reviewers should look at.
+4. Confirm CI started. **Never approve or merge this PR** — it is the one that
+   gets independent review.
+
+## Parked protocol
+
+After two genuinely different failed approaches on a child, or a decision only
+the user can make: post the reason and the specific question to the child AND
+parent chats, set the child back to `Open`, restore the tree, and take the next
+child whose dependency chain does not run through the parked one. Everything
+remaining blocked → report and stop; the user's reply is the un-park signal.

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

@@ -0,0 +1,67 @@
+# Task path — one card to a PR
+
+The single-card execution core of [conveyor-build](../SKILL.md). Read that
+first: ground rules, environment differences, routing, verification, and
+aftercare all live there and are not repeated here.
+
+Use this path when the card has no children, or when it is a pack child whose
+parent is parked.
+
+## 1. Claim
+
+Re-confirm via `mcp__conveyor__get_task` that the card is still claimable —
+`Open` (or whatever status the user explicitly overrode), no assignee you do
+not expect, no active session. Then:
+
+1. `mcp__conveyor__update_task` → `status: "InProgress"`
+2. `mcp__conveyor__post_to_chat` → `[build] claimed — <where you are running>`
+
+If the status changed under you between the read and the write, someone else
+took it. Stop rather than compete.
+
+## 2. Branch from the card's base — never blindly `dev`
+
+The base is the card's `baseBranch`. **A pack child's base is the parent's
+feature branch**, and getting this wrong silently retargets the whole PR.
+
+```bash
+git fetch origin <base>
+git checkout -B <feat|fix|chore>/<slug> origin/<base>
+```
+
+Two cases that are not a fresh branch:
+
+- **The card already has a `githubBranch` with commits on origin.** Resume THAT
+  branch. A prior session may have landed real work — audit what is there
+  before re-implementing anything.
+- **The remote-tracking ref does not exist locally.** Many checkouts only
+  auto-fetch `dev` and the task branch, so `origin/<pack-branch>` may be
+  absent even though the branch exists on the remote. Fetch it explicitly
+  (`git fetch origin <branch>`) rather than concluding the branch is missing —
+  and note that a failed `checkout` leaves you on your PREVIOUS branch, where a
+  follow-up `git push` will push the wrong thing.
+
+Reinstall dependencies if the lockfile changed.
+
+## 3. Implement
+
+**Read the plan's closing `## Builder briefing` first, when it has one.** The
+planner wrote it for you specifically — where to start, what is already decided
+and must not be reopened, which traps look correct and are not, and the order to
+verify in. It is the only part of the planner's context that crosses the handoff,
+so reading it after you have picked an approach wastes the thing it exists for.
+A plan without one is not a blocker; just work the plan.
+
+Work the plan. Push early — locally that is the only durable state, and in a
+pod it is still what survives independent of WIP autosync.
+
+Chat at milestones, not per step.
+
+## 4. Gate, PR, aftercare
+
+These are identical to the SKILL.md sections of the same names. In particular:
+sync the base BEFORE the verification pass, pass `base:` explicitly to
+`mcp__conveyor__create_pull_request`, and confirm CI started without waiting on
+it.
+
+Finish line: the card in ReviewPR with CI started. You do not merge it.

package/skills/conveyor-consensus/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: conveyor-consensus
+description: Sweep everything a Conveyor project is connected to — work channels, cards, tags, meetings, Drive, logs, analytics, the repo — count what actually happened, score the proposals on the table against those counts, and ship an HTML verdict onto the card. Use when the user says "/conveyor-consensus <question>", "get us to consensus on X", "what are people actually complaining about", "does this plan hit the pain", "score these proposals", or when a new stakeholder proposal lands mid-thread and needs scoring against the evidence. Discovers its sources at runtime, so it runs the same in a pod and in a local MCP session.
+---
+
+# Conveyor Consensus
+
+The genre: **an uninterested observer pulls every relevant source, counts what actually happened, scores what people are proposing against those counts, and ships a doc the team can converge on.** The deliverable is a verdict with receipts, not a summary.
+
+## The stance
+
+- Write as the outside party with no stake. Verdicts, not summaries: "covered / partial / missed", "possible / not possible by design", "this suggestion doesn't solve anything, here's why."
+- Every claim carries a count and a receipt (card link, permalink, PR link, quote with author + date). Approximate tallies are fine when labeled as such; fabricated precision is not.
+- The evidence outranks the proposals: score proposals against the data, never the other way around.
+- Counter-analysis is part of the job. When a stakeholder idea doesn't survive the data, say so plainly, show the receipt that kills it, and name the nearest thing that does work.
+
+## Phase 0: discover what this project actually has
+
+**Do this before planning the sweep.** Which sources exist is a per-project fact, not a constant, and guessing wrong wastes a phase either way — assuming a channel that isn't registered, or skipping a Drive that is.
+
+1. `get_connection_context` — who and where. Same call in a pod and a local MCP session; it reports the card in a pod and the account/board in an MCP client.
+2. `list_project_integrations` — which of repository, Slack/Discord, email, GCP, Grafana, Google Analytics, Drive, Cloudflare, incidents are configured, plus the registered work channels. Credential-free booleans; this is the map.
+3. `list_project_channels` — the channels an admin registered as agent-reachable, each with a description of what happens there. **The description is the routing signal**: it is how you tell the channel where support complaints land from the one where releases are announced. Only registered channels are reachable at all; an unregistered channel does not exist for this skill regardless of what the bot can see.
+4. **ToolSearch for the optional surfaces** rather than assuming them: `drive_*`, meeting tools, `query_gcp_logs` / `query_grafana_logs`, `get_analytics_summary`. Also probe for supplemental local MCPs the user may have connected — a user-token Slack MCP is the notable one, because it enables true keyword search that Conveyor's own tools cannot do (see the Slack search note below).
+
+Announce a one-line plan naming the sources you found, then sweep. **Say what you did not find**, too: "no Drive, no meetings, no Grafana on this project" is information the reader needs to weigh the verdict.
+
+## Phase 1: sweep every spot that exists
+
+| 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. |
+| 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. |
+| Drive | `drive_list_files` + `drive_read_file` when the project has a folder — specs, retros, and operational sheets live there. A spreadsheet's columns are the incumbent data model and its stalest rows are the pain. |
+| Logs | `query_gcp_logs` / `query_grafana_logs` when the question is about failures rather than opinions. A frequency count from logs outranks any recollection of how often something breaks. |
+| Analytics | `get_analytics_summary` when the question touches traffic, adoption, or "did anyone use it". |
+| Repo | Prior-art check: has someone already built or started this? `rg`, `git log`, branches, the knowledge graph when present. **A negative result — "no trace of X in the codebase" — is a finding worth printing.** |
+| Vendor / product docs | Try `https://<docs-host>/llms.txt` first; many doc sites ship a full index. Verify every "possible / impossible" ruling against a primary page fetched THIS session and link it. Vendors often have more than one API surface (legacy + current); check both before ruling a capability gap. |
+
+**Slack keyword search is not available to this skill.** `search.messages` requires a USER token; Conveyor's bot cannot call it. `read_channel_messages` is history paging, not search. So either page the relevant channels and filter model-side, or — when the user has a personal Slack MCP connected — use that for search and say so. **The method footnote must state which mode ran**, because "I read the last 300 messages in two channels" and "I searched the workspace" are different evidence bases and a reader deserves to know which one is behind the counts.
+
+Sweep hygiene:
+
+- **Delegate bulk sweeps to a subagent** so oversized pages never enter the main thread. Give it the exact queries, pagination instructions, the tool-loading line, and a strict deliverable spec: categorized findings with counts, sources, a few dated example incidents each with a link, a raw-coverage note (queries run, volume reviewed, date range, dominant sources), and a surprises section. Cap the report length.
+- Record who reported each incident and when. Attribution splits ("their side vs ours", "process vs code defect") and time windows ("only since <month>") are the follow-up questions every single time; keep the underlying dated list so re-slicing is cheap.
+
+## Phase 2: analysis
+
+1. **Bin the evidence into named categories** with incident tallies — not message counts; one saga is one incident. Rank by frequency. Pull a few verbatim quotes that carry the tone, each with author, source, and date.
+2. **Capability map** when a vendor or tool is involved: their surface versus our wants, item by item, each with a link.
+3. **Score every stakeholder proposal** against the FULL category list: COVERED / PARTIAL (symptom yes, root cause no) / MISSED, with one sentence of why each. Score proposals separately, then head-to-head.
+4. **Verify the ambitious claims.** Any proposal line hinging on "the API can (or can't) do X" gets a primary-source check before scoring — these checks regularly flip verdicts.
+5. **Build the merged plan**: the union of the proposals plus the gaps nobody wrote down, every line carrying a feasibility ruling — supported by the vendor (with the doc link), configuration not code, our build, or not possible (say why, and whether the impossibility is actually desirable).
+6. **Separate policy decisions from features.** Some open items are rulings only humans can make; flag them explicitly rather than designing around them silently.
+
+## Phase 3: the doc
+
+Build from `references/doc-template.html` — a working skeleton with three-state theme tokens, a div bar chart, stacked scoreboards, verdict-chip tables, quote blocks, and a method footnote already styled. In a local session, load `artifact-design` and `dataviz` first; in a pod those skills are absent, and the template carries enough of their decisions to stand alone.
+
+**The template is self-contained on purpose and must stay that way.** The report is served from the API under a sandbox CSP (`sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:`), which blocks external stylesheets, webfonts, scripts, and remote images. A JS charting library cannot run; a linked font fails silently and the doc renders in a fallback face with no error. Inline CSS, div/CSS charts, and `data:` URIs only.
+
+Doc anatomy (drop sections that don't apply, keep the order):
+
+1. **Eyebrow + name + dek + meta line** — corpus size, date range, source count, what decision it feeds.
+2. **TL;DR box** — the verdict in 2-3 bold-led paragraphs. A reader who stops here can act.
+3. **The evidence** — frequency bar chart (single hue, direct value labels), a note naming dominant sources, then the tone quotes.
+4. **What already exists** — incumbent systems and prior art, including negative results.
+5. **Proposal scorecards** — one chip table per proposal, then a head-to-head stacked scoreboard including a "merged" row; it sells the synthesis.
+6. **The merged plan** with per-item feasibility chips and links.
+7. **The two cents** — a handful of numbered recommendations, each an argument, not a platitude.
+8. **Method footnote** — queries, counts, date range, which channels were paged versus searched, what was verified against primary sources, and **what was not done**.
+
+Chart rules that repeatedly matter: plain div/CSS charts over JS; one strong chart beats two mushy ones; never chart numbers you had to invent — a chip list or prose with "~" beats a fake-precise graph; status chips always carry text, never colour alone.
+
+## Phase 4: ship it onto the card
+
+1. **`upload_attachment`** with the HTML file — title it with the question, so the card's attachment list reads as a question rather than a filename. This is the required path and the only one that works in a pod.
+2. **Post the verdict to card chat**: the returned link plus a three-bullet summary. Someone scanning the card should get the answer without opening the report.
+3. **When the ask was "align the channel"**, post the summary and link into the relevant work channel with `post_channel_message` — but only into a channel whose registration grants posting, and only when the user asked for that. A consensus doc arriving unbidden in a team's channel is a different act from one attached to a card.
+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`.
+
+## Phase 5: the consensus loop
+
+The doc is the midpoint, not the end. Expect and serve:
+
+- **Follow-up slices**: "table of every incident with details", "only this quarter", "how many were X versus Y", "day-by-day with what would have prevented it". Answer from the kept evidence list; fold into the doc only what changes a verdict.
+- **Proposal reactions**: score new and revised proposals as they land, including negatively, with receipts, and re-upload.
+
+## Environment honesty
+
+State degradations in the method footnote rather than skipping them silently:
+
+- **No WebSearch/WebFetch in a pod** — vendor-doc claims cannot be verified against primary sources there. Print "not verified against primary docs" on the affected lines instead of dropping the check quietly.
+- **No registered work channels** — say so. It usually means the team's discussion is somewhere this skill cannot see, which is the single most important caveat a reader can have.
+- **Bot-visible history only** — the bot reads channels it was invited to. A channel the team talks in but never invited the bot to is invisible, and that absence does not show up as an error anywhere.