@rallycry/conveyor-agent 10.13.72 → 11.0.0

package/skills/conveyor-local-loop/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: conveyor-local-loop
+description: Run this machine as a serial local claudespace — pick the session owner's highest-priority Open Conveyor card, claim it, execute its plan to the PR finish line, repeat. Handles single cards AND whole packs (an Open pack parent is driven end-to-end per conveyor-build's pack path, then the loop moves on once the pack's final PR is open). One invocation = one iteration; run continuously with "/loop /conveyor-local-loop" (no interval) and it self-paces (~1-2 min between cards while the queue has work; when the queue is empty it blocks on live board events via conveyor-wait and wakes seconds after a card becomes claimable, with a ~25 min fallback poll). Use when the user says "/conveyor-local-loop", "start the local loop", "work my open cards locally", or wants planned cards executed with full local CPU/RAM instead of spawning claudespaces. For exactly one card, or one pack and nothing else, use conveyor-build.
+---
+
+# Conveyor Local Loop
+
+Turn a queue of researched Open cards (usually authored via `/conveyor-plan`)
+into review-ready PRs using this machine, one card at a time. Behave exactly as
+a claudespace agent would: 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 only selection, claiming, cadence, and local-machine hygiene.
+
+## Ground rules
+
+- **Conveyor is the state store.** The loop session spans days and gets
+  compacted; at each iteration re-derive state from MCP reads, never from
+  conversation memory.
+- **All Conveyor tools fully-qualified** (`mcp__conveyor__get_task`; bare names
+  fail).
+- **WIP = 1.** At most one card claimed by this loop at a time.
+- **Never `start_task`** — that boots a cloud pod and duplicates the work. Only
+  exception: the opt-in offload valve below.
+- **Never approve or merge your own PRs.** Finish line = card in ReviewPR with
+  green CI; the user takes it from there.
+- **Only cards created by the session owner** (match against
+  `mcp__conveyor__get_connection_context`), status Open, unassigned. Teammates'
+  cards and pod-claimed cards are off limits.
+- **Pack cards: claim the whole pack; the parent card stays parked.** An Open
+  feature-branch pack parent that passes the claiming filters is claimable as
+  a PACK: enter pack mode (below) and drive every child to the final parent
+  PR per [conveyor-build's pack path](../conveyor-build/references/pack-path.md). Throughout,
+  the parent card itself stays PARKED — never Build/`start_task` it, never
+  set it InProgress; the finale `create_pull_request` is what moves it to
+  ReviewPR. A parent already InProgress/ReviewPR has (or had) an active
+  coordinator — hands off it AND its children: an actively-orchestrating
+  parent reads a headless InProgress child as a dead agent environment and
+  "recovers" it onto a cloud pod (observed 2026-07-28 — duplicate
+  implementation). A NON-feature-branch pack — children PR straight into dev,
+  so there is no pack branch to coordinate — is never claimed as a pack:
+  conveyor-build's pack path explicitly does not apply to it. Claim those children
+  individually, one per iteration, and only while the parent is parked.
+- **Run in the main workspace checkout — never a git worktree.** The fully
+  provisioned main workspace (installed `node_modules`, `.env`/direnv auth
+  wiring, the running dev stack) is the whole value of local execution;
+  worktrees miss all of it and have consistently degraded agent sessions.
+  Clean tree before any branch switch is still a hard rule: dirty
+  `git status` at iteration start → touch nothing, report, and idle — the
+  resolution is the user committing or stashing, not a second checkout.
+- **Push early.** There is no pod WIP-autosync locally; committed-and-pushed is
+  the only durable state. Push the branch (`-u origin`) as soon as it exists.
+
+## Iteration order
+
+Each invocation does the FIRST of these that produces work, then paces:
+
+1. **Recover** — a card with my `[local-loop] claimed` chat marker still
+   InProgress without a PR? Resume it. The branch may already exist locally or
+   on origin — check both before re-implementing anything. A pack parent
+   whose chat carries my `[local-loop] claimed — driving this pack` marker
+   and isn't yet in ReviewPR? Resume pack mode — re-derive where it left off
+   from `mcp__conveyor__list_subtasks`, never from session memory. Skip a
+   parent whose LATEST marker is `[local-loop] parked:` with no human reply
+   after it — that pack yielded the WIP slot and stays yielded until the user
+   replies; fall through to the next tier.
+2. **Babysit** — my loop-opened PRs (ReviewPR cards, pack finale PRs
+   included): red CI → fix now (on a pack finale, directly on the pack
+   branch); request-changes or unanswered review comments → address now;
+   green and quiet → leave alone.
+3. **Claim** the next card (below).
+4. **Idle** — nothing claimable: arm the board-event wake (below), then pace long.
+
+## Claiming
+
+1. `mcp__conveyor__list_tasks` with `status: "Open"` — results are already
+   priority-then-newest ordered; board priority IS the intelligence, don't
+   invent your own ranking. Walk top-down, `mcp__conveyor__get_task` each until
+   one passes: created by me, no assignee or active session, an executable
+   plan (a pack parent that still needs breakdown is fine — breakdown is
+   pack-mode work), all `mcp__conveyor__get_dependencies` blockers Complete,
+   no `[local-loop] parked:` chat marker without a later human reply (a reply
+   un-parks), and the pack rules hold: a FEATURE-BRANCH pack parent (children
+   branch from and PR into a pack branch — including one planned as a pack
+   that has no children yet) is claimed as a PACK → pack mode below; a
+   non-feature-branch parent, whose children PR straight into dev, is never
+   claimable — take its children one at a time instead; a card with a
+   `parentTaskId` only while the parent's status is neither InProgress nor
+   ReviewPR (see ground rules).
+   Skip `followParentStatus` mirror children. A blocker counts as met only
+   when merged-or-beyond (ReviewDev/ReviewLive/Complete) or Cancelled — a
+   blocker sitting in ReviewPR is NOT met until its PR merges.
+2. Claim: re-confirm via `get_task` it is still Open, then
+   `mcp__conveyor__update_task` → `status: "InProgress"`, then
+   `mcp__conveyor__post_to_chat`: `[local-loop] claimed — working locally on
+   <hostname>`. Claiming a PACK is different — never set the parent
+   InProgress: leave it Open and post the pack claim marker instead (see Pack
+   mode). Status changed under you → someone else took it; next
+   candidate.
+3. Plan missing or failing the context-free-reader bar → don't wing it: post
+   what's missing to chat, leave the card Open, skip it.
+
+## Execute and finish
+
+**Execution is [conveyor-build](../conveyor-build/SKILL.md)** — resolving the
+card, branching from its base, working the plan, gating, and opening the PR
+with an explicit `base:`. That skill is the source of truth; do not re-derive
+its procedure here. It routes a childless card to its task path and a
+feature-branch pack to its pack path automatically.
+
+This section adds only what the LOOP changes:
+
+- **Chat markers carry the loop's prefix**, `[local-loop]` rather than
+  `[build]`, because the Recover tier greps for them to find its own work.
+- **A pack child yields to a live coordinator.** Before opening a child's PR,
+  re-check the parent's status; if it went InProgress or ReviewPR, post
+  `[local-loop] parked: pack coordinator active — yielding`, leave the branch
+  pushed, and let the coordinator take over.
+- **Do not wait on CI.** Confirm it started (read-only `gh pr checks`) and end
+  the iteration — the Babysit tier owns it from there. This is the loop's one
+  real departure from a standalone build, which stays with its PR.
+
+**Parked protocol** — after 2 genuinely different failed approaches, or on a
+decision only the user can make: post `[local-loop] parked: <reason + the
+specific question>`, set status back to `"Open"`, restore the tree
+(`git checkout dev`), move on. The user's next chat reply is the un-park
+signal.
+
+## Pack mode
+
+Claiming an Open pack parent means driving the ENTIRE pack, exactly per
+[conveyor-build's pack path](../conveyor-build/references/pack-path.md) —
+setup (pack branch on origin, the `githubBranch` write-through, child breakdown
+if the parent has none yet), children serially in dependency order,
+reviewer-of-record review + merge of each child PR into the pack branch,
+dev→pack sync after every merge, cross-reference, then the finale parent PR
+into dev. That reference is the source of truth for the procedure; this section
+only defines how it embeds in the loop:
+
+- The pack occupies the loop's single WIP slot from claim until the finale PR
+  opens. Do not interleave unrelated cards mid-pack — that thrashes branch
+  state.
+- Claim marker goes to the PARENT chat: `[local-loop] claimed — driving this
+  pack locally on <hostname>, pack branch <branch>`. The parent's status
+  stays Open (parked); the marker is the claim.
+- Once the finale PR is open (parent in ReviewPR), the pack leaves the WIP
+  slot: its PR joins the Babysit tier like any other loop-opened PR, and the
+  loop resumes claiming other cards. This is the one difference from
+  a standalone conveyor-build pack run, which stops when the pack is done.
+- Parked children follow the pack path's parked protocol. If every
+  remaining child is blocked on the user, the pack yields the WIP slot: post
+  `[local-loop] parked: <what it is waiting on>` to the PARENT chat — that
+  marker is what makes the Recover tier skip the pack — and the loop claims
+  other cards. The user's chat reply un-parks it, and the next Recover tier
+  retakes the slot.
+
+## Waking on board events
+
+An empty queue is not a quiet board. Rather than sleeping blind for 25 minutes,
+arm `conveyor-wait`: a CLI in `@rallycry/conveyor-mcp` that subscribes to the
+project's live card stream and exits the moment a card ENTERS a claimable
+state. A card created Open, a Cancelled card reopened, and a card reassigned to
+you all count; an edit to a card that already matched does not.
+
+Arm it on an idle iteration only (tier 4), and only when no wait from an earlier
+iteration is still running:
+
+```bash
+node_modules/.bin/conveyor-wait --scope mine,unclaimed --timeout 1740
+```
+
+Launch it with Bash `run_in_background: true` and end the turn. Its completion
+notification is the wake. The `ScheduleWakeup` you still arm is the fallback for
+the case where the wait dies silently — use the pacing table's background-gate
+row (1200–1800s), not a second, shorter timer.
+
+- Prefer `node_modules/.bin/conveyor-wait`. If it is absent, use
+  `npx -y -p @rallycry/conveyor-mcp@latest conveyor-wait`. The `-p` form
+  matters: inside the conveyor monorepo a bare
+  `npx @rallycry/conveyor-mcp` misresolves.
+- Narrow `--types` to whatever focus the user gave the loop invocation —
+  "focus on incidents" → `--types incident`. The default watches tasks,
+  incidents, and suggestions.
+- `--scope mine,unclaimed` mirrors the claiming filter: cards assigned to the
+  session owner plus unassigned cards. Use `--scope all` only when the user
+  asked the loop to watch the whole board.
+- `--statuses` defaults to `Open`, which is the claimable lane. Leave it alone
+  unless the user asked for something else.
+- Credentials come from the environment, then any `.mcp.json` from the working
+  directory up, then `~/.claude.json`. An agent Bash shell does not inherit the
+  MCP server's environment, so that file fallback is what makes this work at
+  all. Exit 1 means the wait could not run: no credentials, a rejected token, or
+  a project it cannot read. Read the stderr line, report it once, fall back to
+  plain timed polling, and do not re-arm it every iteration.
+
+**The result is advisory — the queue is still the source of truth.** The CLI
+prints one line of JSON and exits 0 in every non-error case:
+
+```
+{"reason":"event","card":{"id":…,"slug":…,"title":…,"type":…,"status":…,"assignedUserId":…}}
+{"reason":"timeout"}
+{"reason":"interrupted"}
+```
+
+On wake, run a normal iteration and re-enumerate with
+`mcp__conveyor__list_tasks`. By then the card may be claimed, cancelled, or
+blocked by a dependency — never claim straight from the wait payload.
+
+**Never arm a second wait.** On a wake where a wait process is still in flight
+and the queue is still empty, re-arm the fallback `ScheduleWakeup` and end the
+turn.
+
+## Pacing (dynamic /loop only)
+
+Under `/loop` with no interval, end EVERY iteration with exactly one
+`ScheduleWakeup` (prompt = the original /loop input verbatim):
+
+| State | Delay | Reason should say |
+|-------|-------|-------------------|
+| A background gate/agent/conveyor-wait is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs — its notification wakes me sooner" |
+| ANY actionable work exists: claimable cards or packs, a pack child to implement/merge, a PR still to open, red/pending CI, review comments | 60–90s | queue depth / which item is next |
+| Queue enumerated as empty THIS iteration, all loop PRs green and quiet | 1200–1800s | queue empty; conveyor-wait armed, so this is only the fallback |
+| Loop-fatal: MCP dead after 2 tries, dirty tree, broken repo | notify the user (PushNotification if available), then 1800s — or `stop: true` if continuing is unsafe | what is wrong |
+
+The long idle tier is EARNED, never defaulted: it requires having enumerated
+the queue this very iteration and found zero actionable work. When unsure
+which tier applies, take the short one — a wasted 60s wake costs less than a
+30-minute stall on live work.
+
+Invoked bare (no /loop)? Run one iteration, report, and suggest
+`/loop /conveyor-local-loop` — don't self-schedule.
+
+## Offload valve (opt-in)
+
+Only with an explicit `offload=N` argument: when 4+ claimable cards queue up,
+`mcp__conveyor__start_task` up to N of the smallest into claudespaces and say
+so in the iteration summary. Without the argument, never — just report backlog
+depth each iteration so the user can offload manually.
+
+## What this is not
+
+- Not a reviewer of anything headed for `dev`: never `approve_task`,
+  `request_changes`, or `approve_and_merge_pr` on a PR into `dev` — including
+  a pack's final parent PR. **The one exception is a pack's CHILD PRs into the
+  pack branch**, where you are the reviewer of record because the automated
+  reviewer skips that target; the pack path spells out that duty.
+- Not a pod: no sandbox, no WIP snapshots, and the dev DB + dev-server ports
+  are shared with the user's interactive sessions — no destructive
+  experiments, never reset the dev DB, reuse a running dev stack rather than
+  fighting over ports.
+- Not a parallel executor: one card (or one pack) at a time is the point (the
+  full machine per gate). Backlogged? That is what claudespaces — or the
+  offload valve — are for.
+
+## 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-meeting-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: conveyor-meeting-review
+description: Turn a Conveyor meeting into confirmed cards, packs, and glossary updates — read the meeting and its transcript, cross-reference what already exists, draft proposals at the plan-quality bar, and create only what a human confirms item by item. Use when the user says "/conveyor-meeting-review <meeting>", "turn that meeting into cards", "what should we do about yesterday's call", or asks for the follow-ups from a meeting. Never creates anything unasked.
+---
+
+# Conveyor Meeting Review
+
+A meeting becomes work only when a person says which parts should. This skill does the reading, the cross-referencing, and the drafting — and then **stops and asks**.
+
+## The one rule
+
+**Never create, edit, or tag anything before a human confirms that specific item.** Not "shall I proceed?" and then everything — item by item, so "create 1 and 3, skip 2" is a normal answer.
+
+This is not caution for its own sake. A meeting transcript is full of things that *sound* like decisions: someone thinking out loud, an idea that was argued down two minutes later, a "we should probably…" that nobody agreed to. An agent that creates cards from those is manufacturing work the team never chose, on a board they have to clean up. The summary's `## Proposed Next Steps` is a **starting point, not a mandate** — it was written by a model reading the same ambiguous transcript.
+
+## 1 — Read
+
+1. `mcp__conveyor__get_connection_context` — where you are. Same call in a pod and a local MCP session.
+2. `mcp__conveyor__get_meeting` — the overview, the decisions, the proposed next steps, and the participants. **This usually answers the question.** It costs a fraction of the transcript.
+3. `mcp__conveyor__read_meeting_transcript` — only when you need exact wording: a quote, a caveat, the reasoning behind a decision the summary merely states, or a check on whether something was actually agreed. Page with `offset`/`nextOffset` rather than pulling the whole thing.
+
+If `status` is `processing` the summary is still being written — read the transcript, or say so and offer to come back. If `status` is `failed`, `summaryError` says why; the transcript is still complete and readable.
+
+## 2 — Cross-reference before drafting anything
+
+Skipping this is how a meeting review produces four cards that duplicate work already in flight.
+
+- `mcp__conveyor__list_tags` — the project's vocabulary. Use its words in your proposals; a card that names the same thing differently is a card nobody finds.
+- `mcp__conveyor__search_tasks` — **two or three keyword variants per proposed topic**, across `task`, `incident` and `suggestion`. One search misses the card that used the other word for it.
+- `mcp__conveyor__read_task_chat` on anything that looks close. The overlap is usually in the discussion, not the title.
+
+Then say what you found, including the negatives: "this one already exists as `fix-the-thing`", "nothing on the board covers this", "there is a suggestion arguing the opposite".
+
+## 3 — Draft at the plan-quality bar
+
+Each proposal a context-free reader could execute: what changes, where (file paths where you know them), and how it is verified. The `/conveyor-plan` skill's `references/plan-format.md` is the bar. A one-line card that says "improve onboarding" is not a proposal, it is a note.
+
+Classify honestly:
+
+- **A card** — one coherent piece of work.
+- **A pack** — a parent plus children, when the work has real internal ordering. Do not inflate a card into a pack for ceremony.
+- **An edit to an existing card** — usually better than a new one when something is already in flight. Say which card and what changes.
+- **A tag update** — the glossary learned a word.
+- **A suggestion** — the meeting raised something worth recording that nobody has decided to do. This is the honest home for "we should look into X someday", and it keeps the board clean.
+- **Nothing** — some meetings produce no work. Say so rather than finding something.
+
+## 4 — Present and wait
+
+Number the proposals. For each: the type, the title, one sentence of what it is, and — critically — **what in the meeting supports it**, with a speaker and roughly when. A proposal whose evidence you cannot name is one you inferred, and it should be labelled as such or dropped.
+
+Flag separately:
+
+- **Decisions that need a human**, which a card cannot settle.
+- **Contradictions** — where the meeting disagreed with itself, or with a card already on the board.
+- **Things you deliberately did not propose**, and why. That is often the most useful part.
+
+Then wait. If the reply is partial ("1 and 3"), create exactly those.
+
+## 5 — Create, and stamp the provenance
+
+Only the confirmed items, through the normal card tools — `create_task`, `create_subtask`, `add_dependency`, `update_task`, `manage_tags`, `create_suggestion`. There is no meeting-specific write path, on purpose: a card born from a meeting should be indistinguishable from any other card, and reviewable the same way.
+
+**Stamp every created card with the meeting link** from `get_meeting`'s `url` field, in the description or the plan. Six weeks later "why does this card exist" is a real question, and the answer should be one click away.
+
+Report back with what was created and what was skipped.
+
+## Environment notes
+
+- All Conveyor tools are **fully qualified** (`mcp__conveyor__get_meeting`); bare names fail.
+- The meeting tools are **deferred** — reach them via ToolSearch rather than expecting them preloaded.
+- They appear only for a project that HAS meetings. If they are absent, the project has none; say so instead of hunting.
+- A pod and a local MCP session run this identically. The only difference is where you report: in a pod, card chat.

package/skills/conveyor-plan/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: conveyor-plan
+description: Produce the plan for a Conveyor card — research-backed and immediately buildable by someone with zero session context. Use when the user says "/conveyor-plan <idea>", "plan this as a conveyor card", "write this up for a claudespace agent", or when a session is asked to plan the card it is on. Runs plan-mode-quality research (codebase + prior Conveyor cards + prod logs), asks clarifying questions only when scope is genuinely ambiguous, then writes the plan onto the card. Works in a cloud pod and a local checkout alike; to execute a plan that already exists use conveyor-build.
+---
+
+# Conveyor Plan
+
+Produce ONE artifact: a Conveyor card whose plan an executor with zero session
+context can follow. Everything they need must be ON the card — they never see
+this conversation, and that executor may be a cloud pod, a local session, or
+you tomorrow.
+
+The research and drafting below are identical everywhere. Only the two ends
+differ — resolving which project you are in, and where the finished plan lands
+— and both carry an **Environment** note.
+
+The division of labor is fixed: **you research and recommend; Conveyor's
+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.
+
+## Phase 0 — Resolve context
+
+1. `mcp__conveyor__get_connection_context` (all Conveyor tools fully-qualified;
+   bare names fail). It also tells you which environment you are in: a pod
+   session reports a task binding and no user account.
+
+   > **Environment.** In a **pod** you are already bound to one project and one
+   > card — there is nothing to resolve, and `mcp__conveyor__list_projects`
+   > does not exist there. **Locally**, if the connection reports no default
+   > project, use `mcp__conveyor__list_projects` and match
+   > `githubRepoOwner/Name` to the cwd's `git remote`. Ambiguous → ask.
+
+2. Copy project IDs exactly — a mistyped `projectId` surfaces as
+   "Insufficient permissions", not "not found". Verify the ID before
+   concluding you lack access.
+
+## Phase 0.5 — What KIND of card is this?
+
+The research below is the same for all three, but what counts as a finished
+plan is not:
+
+- **Task** — the default. Someone has decided the work should happen; your job
+  is to make it executable. Proceed as written below.
+- **Suggestion** — someone thinks this *should* happen. Establish that the ask
+  is real and unmet **before** planning it: does the feature already exist in
+  some form, was it tried and cancelled before (and why), and is the underlying
+  need better served another way? A plan for something already shipped is worse
+  than no plan, because it will be built twice.
+- **Incident, or any unverified report** — do **NOT** plan a fix from the
+  description. A report names a symptom, and the symptom is often not the bug;
+  machine-filed reports carry whatever the throwing code said. If the root
+  cause has not been established with telemetry or a reproduction, this card
+  needs **`/conveyor-triage`** first. Plan the fix only once triage has named
+  the cause.
+
+## Phase 1 — Research (parallelize)
+
+Scale to the idea's size; a one-file tweak needs minutes, not a survey.
+
+- **Glossary first**: `mcp__conveyor__get_tag` on every tag the idea's text
+  mentions (`@[tag:id]` deep-links or plain loaded terms — "task", "school",
+  an entity name) before searching the codebase. A tag's overview + linked
+  files often replace a grep sweep, and the description catches
+  wrong-term-for-the-concept early (`mcp__conveyor__list_tags` shows the
+  inventory with hierarchy).
+- **Codebase**: use a code-graph or architecture skill if the repo provides
+  one for architecture/flow questions; `rg` for exact strings. Fan out
+  Explore subagents for broad sweeps. Investigate deliberately rather than
+  reading around: search first and read second, start from 3-5 critical files,
+  form a hypothesis, then validate it with targeted reads. Never re-read a file
+  already in your context. **Stop when you can cite a specific `file.ts:line`
+  and a symbol name for every step your plan will contain** — that is the
+  threshold, and more reading past it buys nothing.
+- **Prior art**: `mcp__conveyor__search_tasks` on 2-3 keyword variants
+  (`typeFilters` to include incidents/suggestions when relevant), then
+  `mcp__conveyor__get_task` on the closest hits. You're looking for duplicates
+  (stop and surface), related shipped work (reuse its patterns), and
+  cancelled attempts (learn why before re-proposing).
+- **Prod signals** (only when the feature touches live behavior):
+  `mcp__conveyor__query_gcp_logs` / `mcp__conveyor__query_grafana_logs` for
+  error rates, actual usage, current behavior. **Environment:** these are
+  local/MCP only — a pod has no log tools, so state the question the logs would
+  answer in the plan's Notes instead of guessing at the answer.
+- **Blast radius**: enumerate callers/consumers of every surface the plan
+  touches (shared packages, DB schema, published packages, webhooks, other
+  cards in flight on the same files). Unintended impact goes in the plan's
+  Notes, not in your head.
+
+## Phase 2 — Clarify (only if needed)
+
+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.
+
+## Phase 3 — Draft the plan
+
+Use the plan format in [references/plan-format.md](references/plan-format.md):
+Objective / Approach / Implementation Steps / Testing / Notes / Builder briefing.
+
+Actionability bar — every step must survive a context-free reader:
+
+- Name exact repo-relative files and symbols, with the pattern to follow
+  ("mirror `apps/api/src/services/task/methods/mutations.ts`").
+- Testing = runnable commands + observable acceptance criteria.
+- Notes = risks, blast radius, dependencies, and decisions already made (so
+  the executor doesn't relitigate them).
+- No "as discussed", no links to this chat, no TODOs the executor must
+  research from scratch.
+
+**Close with the Builder briefing, and write it for the NEXT session.** Every
+other section addresses a reader; this one addresses the agent that will inherit
+this card having read the card and nothing else — no research, no dead ends, no
+memory of this conversation. Four lines, ~10 max: where to start, what is already
+decided (and why, so it is not reopened), which traps look correct and are not,
+and the order to verify in. Write it last, when you know which parts were hard.
+
+It is not optional and it is not a summary. It is the only channel your context
+has across the handoff, because handoffs carry the card and never the session.
+
+Size it: 1 SP default, 2 multi-file, 3 complex patterns/design, 5 hard. Larger
+→ propose a pack (parent + `mcp__conveyor__create_subtask` children) instead of
+one mega-card. **Child→child ordering rides `create_subtask`/`update_subtask`'s
+own `dependsOn` field, NOT `mcp__conveyor__add_dependency`** — on the pod surface
+that tool is scoped to the session's own task and cannot draw an edge between two
+children.
+
+Show the user title + description + plan + SP/tag recommendation before
+touching Conveyor, unless they asked you to just ship it.
+
+## Phase 4 — Create and hand off (order matters)
+
+> **Environment — a pod plans the card it is already on.** The steps below
+> create a NEW card, which is the local/MCP shape; `mcp__conveyor__create_task`
+> 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, and stop —
+> a pod does not promote its own card to Open. If the pod also has to leave
+> plan mode, note that `update_task` carries no story points or risk; those go
+> through `mcp__conveyor__update_task_properties`. Everything in Phases 1-3 is
+> identical in both environments. To break a large pod card into a pack, use
+> `mcp__conveyor__create_subtask` rather than `create_task`, and set child→child
+> ordering through its `dependsOn` field — `mcp__conveyor__add_dependency` is
+> scoped to the session's OWN task in a pod and cannot draw an edge between two
+> children.
+>
+> **In a pod, create every child BEFORE you save the parent plan.** The parent
+> plan save is what triggers the handoff, and the handoff reads the card's child
+> count at that instant to decide what to spawn: children present → a pack
+> coordinator that works them serially; none → a single leaf builder. Save the
+> parent plan first and you hand a whole pack to a leaf builder. Order is
+> therefore: children (with their plans and `dependsOn` edges) → parent plan
+> LAST.
+
+Identification fires the moment the card lands beyond Planning and reads task
+chat for your recommendation — so chat BEFORE the status flip:
+
+1. `mcp__conveyor__create_task` — `status: "Planning"`, concise imperative
+   title, 2-4 sentence description (the board-card summary), full plan.
+   Optionally `tags`: only names from `mcp__conveyor__list_tags` that clearly
+   fit (unknown names are rejected; pre-set tags make identification skip tag
+   assignment — when unsure, omit and let it choose).
+2. `mcp__conveyor__post_to_chat` — one message: recommended SP + one-line
+   rationale, tag suggestion, any executor warnings.
+3. `mcp__conveyor__update_task` — `status: "Open"` (+ `risk` when the plan
+   touches critical surface). This triggers identification.
+4. Verify with `mcp__conveyor__get_task`: status Open, `agentId` set. SP and
+   tags are NOT in the `get_task` response — confirm on the board if needed.
+5. Report the card URL (`<project url>/cards/<slug>`), what identification
+   filled, and that it's ready for `start_task`. Park-in-Planning instead if
+   the user wants to review first; offer (don't run) `start_task`.
+
+## 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-plan/references/plan-format.md

@@ -0,0 +1,134 @@
+# Conveyor Plan Format & Sizing
+
+## Plan Format
+
+```markdown
+## Objective
+One sentence: what this task accomplishes and why.
+
+## Approach
+High-level strategy with relevant files/patterns/APIs.
+
+## Implementation Steps
+1. Concrete step.
+2. Concrete step.
+
+## Testing
+- Commands and manual checks.
+- Edge cases.
+
+## Notes
+- Dependencies, risks, blockers, or files likely touched.
+
+## Builder briefing
+- **Start here:** the one or two files to open first.
+- **Already decided:** choices the builder should not reopen, one line of why each.
+- **Traps:** what looks right and is not.
+- **Verify in this order:** cheapest disqualifying check first.
+```
+
+## Citations — ground every code step in the code
+
+A plan an executor can follow names locations, not areas. For every step that
+touches code:
+
+- Cite the exact location as `path/from/repo/root.ts:lineNumber` (e.g.
+  `packages/conveyor-agent/src/execution/mode-prompt.ts:129`). Ranges are fine
+  for larger edits (`foo.ts:120-145`); a whole file with no line is not.
+- Name the specific function, class, constant, or JSX element being touched.
+- When behavior hinges on a short piece of code, quote 1–3 lines inline rather
+  than paraphrasing it.
+- For a file that does not exist yet, write `NEW: path/to/new-file.ts` and
+  describe the module it fits into.
+
+## The Testing section is a definition of done
+
+The executor treats it as the acceptance criteria, so enumerate:
+
+- The scoped verification for this change — the repo's own lint/typecheck and
+  affected-test commands — naming the specific package suites the diff will
+  touch. A docs-only plan should say plainly that no local gates are needed and
+  that CI validates on the PR.
+- Any task-specific end-to-end check: a manual UI walk-through, an API smoke
+  test, a migration dry-run.
+
+A planner working read-only is not expected to RUN these. Describe them.
+
+## The Builder briefing is written for the NEXT session
+
+The section that closes the plan is the only one not addressed to a reader — it
+is addressed to the session that inherits this card, which has read **this card
+and nothing else**. It has none of your research, none of your dead ends, and no
+memory of the conversation that produced any of it.
+
+That is deliberate. Handoffs carry the card, never the session (see the decision
+record in `.claude/rules/agent-modes.md`), so this section is where a planner's
+hard-won context survives the boundary — and it is the whole reason forking the
+planner's session was not needed.
+
+Four lines, one each:
+
+- **Start here** — where to open the code, not a summary of it.
+- **Already decided** — what NOT to reopen, with one line of why. This is the
+  highest-value line: without it a builder re-litigates a choice you already
+  made, and usually lands somewhere worse because it has less context.
+- **Traps** — what looks correct and is not. Anything that cost you a wrong
+  turn will cost the builder the same one.
+- **Verify in this order** — cheapest disqualifying check first, so a wrong
+  approach dies in seconds instead of at the gate.
+
+**Bounded at ~10 lines.** If it runs longer, that is a signal about the plan
+body, not about the briefing: something belonged in Approach, Implementation
+Steps, or Testing and did not get there. Do not use it as an appendix, and do
+not restate the steps — a briefing that repeats the plan is one more thing to
+keep in sync.
+
+Write it last, when you know which parts were hard.
+
+## Sizing
+
+Default **1 SP**. Use **2 SP** for multi-file work, **3 SP** for complex
+patterns/design choices, **5 SP** only for hard work. Split anything larger.
+
+## Packs (parent + child tasks)
+
+A **pack** is Conveyor's bundle shape: a parent card with child cards.
+`create_subtask(parentTaskId, ...)` creates a NEW child; to move an EXISTING
+card under a parent (or out of one) use `set_task_parent`. `create_task` /
+`update_task` have no parent field. Each child is a full card
+(own chat, plan, story points). Split into a pack only when the work is
+genuinely multiple independently buildable pieces (8-SP-tier); otherwise keep
+one card.
+
+- **Orchestration packs** (future work): `start_task` on the parent boots a
+  *pack runner* that works each ready child, honoring dependency edges. Give
+  each child a detailed plan with a **Testing / Verification** section —
+  identification sizes children like any other card. The parent card's
+  `featureBranch` setting (default on) makes children branch off and PR back
+  into the parent's branch instead of the default base.
+
+  **Every child needs a real plan, held to the same bar as a standalone card:**
+  a multi-step implementation guide with `file.ts:line` citations, the
+  function/symbol names it touches, a pattern to follow where one exists
+  ("mirror `src/services/foo.ts`"), testing requirements, and acceptance
+  criteria. A one-line description is not a plan, and the executor cannot ask
+  you what you meant.
+
+  **Express cross-child ordering as `dependsOn` metadata, never as prose.**
+  Pass `dependsOn` (sibling ids or slugs) on `create_subtask` for any child
+  that blocks on another; leave genuinely independent children with none. A
+  runner schedules off those edges — "do this after step 2" written in plan
+  text is invisible to it, and the child will be picked up out of order.
+- **Mirror packs** (already-done work shipping in ONE PR on the parent's
+  branch): create children with **`followParentStatus: true`** — title and a
+  plain-language description only. A follower mirrors its parent's status
+  automatically through the whole pipeline, identification sizes it, and it
+  never posts its own Slack card. Evidence rolls up to the **parent**. Never
+  `start_task` a mirror pack's parent, and leave children's PR fields empty —
+  the parent owns the PR.
+
+## Status Flow
+
+`Planning -> Open -> InProgress -> ReviewPR -> ReviewDev -> ReviewLive -> Complete`
+
+`Cancelled` is terminal. A task must be `Open` before `start_task`.