@rallycry/conveyor-agent 10.13.71 → 11.0.0

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`.

package/skills/conveyor-review/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: conveyor-review
+description: Review a Conveyor card's pull request and render a verdict — correctness, pattern consistency, security, performance, error handling, test coverage, typing, readability — fixing small issues directly and flagging the rest. Use when the user says "/conveyor-review <card or PR>", "review this PR", "do a code review", when a claudespace session boots in review mode, or when acting as reviewer of record for a pack child. Works in a cloud pod and a local checkout; the verdict tools differ per environment and the skill says which.
+---
+
+# Conveyor Review
+
+Read a PR against the plan it claims to implement, fix what is small, flag what
+is not, and render exactly one verdict. The card is the spec, the diff is the
+evidence, and task chat is where the team sees your reasoning.
+
+**This skill is the mechanics.** Your *persona* — tone, how many issues to
+raise, what this project cares about — comes from the reviewer agent's own
+instructions, and from the host repo's CLAUDE.md. Where the two disagree about
+process, this skill loses: a project's own rules outrank a general one.
+
+## Ground rules
+
+- **All Conveyor tools fully-qualified** — `mcp__conveyor__get_task`, not
+  `get_task`. Bare names fail.
+- **Exactly one verdict per review.** Not zero (the card waits forever), not
+  two (the first one wins and the second is noise).
+- **Substantive issues only.** Linting and formatting have their own gates;
+  spending a verdict on style spends the team's attention on the wrong thing.
+- **Review the diff, not the repository.** Pre-existing problems in a file the
+  PR touches are not this PR's job — note them in chat if they matter, or file
+  a suggestion, but do not block on them.
+
+## Read the change
+
+1. `mcp__conveyor__get_task` for the plan — you cannot judge "does this do what
+   it says" without the "what it says".
+2. **Ask the PR what you are reviewing, BEFORE any diff:**
+   `gh pr view <pr> --json state,baseRefName,headRefOid,files`. The PR's base is
+   often not the project default branch, and asking costs one call instead of
+   six spent guessing.
+3. Get the diff with the **merge-base** form, never two-dot, and **fetch the
+   base first** — a pod clones single-branch, so `origin/<base>` does not exist
+   until you ask for it and the diff fails or silently compares against nothing:
+
+   ```
+   git fetch origin <base> -q && git diff $(git merge-base origin/<base> HEAD)..HEAD
+   ```
+
+   Two-dot (`git diff <base>..HEAD`) compares against the base TIP, so it
+   reports already-merged commits as part of this change and sends you reviewing
+   code nobody here wrote.
+4. **When the diff and the PR disagree, the PR wins.** Diff the head SHA
+   directly instead (`git diff <headSha>^ <headSha>`). Your checkout can be
+   stale and so can the remote branch tip — a merged PR's commit may be
+   reachable only by SHA. If the PR reports `MERGED` or `CLOSED`, say so and
+   review the recorded head SHA rather than assuming your tree matches it.
+5. **Read the code under review out of the PR's commit, not the working tree:**
+   `git show <sha>:<path>` and `git grep <pattern> <sha>`. Grepping the working
+   tree when the PR is based elsewhere returns confident, wrong answers — it has
+   produced false review findings.
+6. Read the surrounding code before judging consistency. A pattern is only a
+   pattern if the neighbours share it.
+7. `mcp__conveyor__get_tag` on the card's tags — a tag's overview and linked
+   rules are what "follows existing patterns" actually means in this project.
+
+## Criteria
+
+- **Correctness** — does it do what the plan says? Logic errors, off-by-one,
+  race conditions.
+- **Pattern consistency** — does it match nearby code and the card's tag rules?
+- **Security** — no hardcoded secrets, no injection, input validated at
+  boundaries.
+- **Performance** — no needless loops, no N+1 queries, nothing blocking in an
+  async context.
+- **Error handling** — handled at system boundaries, nothing swallowed.
+- **Test coverage** — are new paths tested? Edge cases covered? A test that
+  asserts nothing is worse than no test, because it reads as coverage.
+- **Typing** — proper types, no unnecessary `any`, correct async/await.
+- **Naming and readability** — clear names, and no comment that says something
+  the code does not do.
+
+**If previous review feedback is in the chat history, verify those specific
+issues were addressed before raising new ones.** Re-litigating a resolved point
+while the actual fix goes unchecked is the most common way a second review
+wastes everyone's time.
+
+## Fix or flag
+
+You have write access. Use it in proportion:
+
+- **Small and unambiguous** → fix it, commit, push, then re-review your own
+  change as part of the diff. After pushing, wait for CI before approving.
+- **Larger, or a judgment call the author should make** → flag it in the
+  verdict with the file, the line, what is wrong, and a suggested direction.
+
+Fixing something you do not fully understand is worse than flagging it.
+
+## The verdict
+
+> **Environment — the tools differ, and only one pair exists per surface.**
+> In a **pod** (review-mode session): `mcp__conveyor__approve_code_review` or
+> `mcp__conveyor__request_code_changes`. **Locally** via conveyor-mcp:
+> `mcp__conveyor__approve_task` or `mcp__conveyor__request_changes`. The pod
+> pair does not exist locally and the local pair does not exist in a pod, so
+> reaching for the wrong one fails outright rather than degrading.
+
+Every verdict carries a **risk** level, judged by the surface the change
+touches — not by how large the diff is:
+
+- `critical` — auth, billing, data integrity, migrations
+- `high` — important surface with broad blast radius
+- `medium` — moderate, contained
+- `low` — small or isolated
+
+The card may already carry a risk level, and **whether you can correct it
+depends on where you are running** — the same environment split as the verdict
+tools above:
+
+- **Locally** (conveyor-mcp): `update_task` takes `risk`. If your review
+  disagrees with the card, set what you believe is correct — you have the
+  authority to override in either direction, and a stale risk level is worse
+  than a changed one.
+- **In a pod** (review-mode session): you cannot. `update_task`'s agent surface
+  omits `risk` on purpose, and `update_task_properties` — the only pod tool that
+  carries it — is not in a review session's toolset. **State the risk you judge
+  correct in your verdict** and let a human or identification apply it.
+
+That asymmetry is deliberate, not an oversight, and it is written down because
+the instruction used to read "set what you believe is correct" unconditionally —
+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
+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
+card in the verdict and let identification or a human re-size it.
+
+## Reviewer of record for a pack child
+
+A PR into a **pack branch** gets no automated review — the pack's own session
+is the reviewer, and the independent review happens later on the pack's PR into
+`dev`. When you are that reviewer:
+
+- Apply the same criteria above. The absence of an automated pass makes this
+  review more load-bearing, not less.
+- There is **no verdict tool** — merging the child PR is the approval. Say what
+  you checked in chat so the record exists.
+- 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.
+
+## Blocked
+
+If the PR cannot be reviewed as it stands — the plan is missing, the diff is
+empty, CI never ran, or the branch does not match the card — say so in chat
+with the specific blocker and do NOT render a verdict. An approval issued
+because you could not see the code is worse than no review at all.
+
+## 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-start/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: conveyor-start
+description: Hand a planned Conveyor card to the cloud — start its build, confirm the environment actually came up, and report where to watch it. Use when the user says "/conveyor-start <card>", "start this card", "build this in the cloud", "kick off a pod for this", or asks to hand work off rather than do it locally. Local/MCP surface only; inside a pod the skill says so instead of failing.
+---
+
+# Conveyor Start
+
+The handoff verb. `/conveyor-plan` produces a buildable card and `/conveyor-build`
+executes one **here**; this one hands the card to a cloud pod and gets you back
+a place to watch it.
+
+Its whole job is the gap between "I pressed start" and "something is actually
+running." A start that silently did nothing looks identical to a start that
+worked, until you check an hour later.
+
+> **Environment — this skill does not apply inside a pod.** `start_task` exists
+> only on the external `conveyor-mcp` surface, never on the in-pod agent
+> surface, and that is deliberate (recorded in `agent-modes.md`, "pods never run
+> the conveyor-mcp binary"). If you are running inside a claudespace pod, say
+> so and stop: you cannot start a build from in here, and a pod that wants
+> parallel work creates child cards and lets the pack path fire them. Do not
+> hunt for an equivalent tool — there isn't one.
+
+## Ground rules
+
+- **All Conveyor tools fully-qualified** — `mcp__conveyor__start_task`, not
+  `start_task`. Bare names fail.
+- **Never start a card you have not read.** A start mints compute against a
+  human's subscription key and reassigns the card; doing that to the wrong card
+  is expensive and confusing to undo.
+- **One card per invocation.** Starting several is a decision about spend and
+  concurrency that belongs to a person, not to a convenience loop.
+
+## 1. Resolve and qualify the card
+
+`mcp__conveyor__get_task` (or `get_card_by_slug` for a `/cards/<slug>` URL).
+Then check it is genuinely startable, and say which check failed rather than
+starting anyway:
+
+- **Status is `Open`.** A `Planning` card is not ready — it has no agreed plan.
+  A card already `InProgress` has an environment; you want `resume_task`, and
+  starting again would duplicate the work.
+- **It has an executable plan.** Not a title and a sentence — a plan a
+  context-free reader could build from. If it does not, **stop and offer
+  `/conveyor-plan` first**: starting a pod against a thin plan burns an hour to
+  produce the wrong thing, and the agent cannot ask you a clarifying question
+  mid-build.
+- **Its dependencies are met.** `mcp__conveyor__get_dependencies` — a blocker
+  counts as met only at ReviewDev or beyond. Starting a blocked card produces an
+  agent that cannot finish.
+
+If any check fails, report which one and what would fix it. Do not start.
+
+## 2. Start it
+
+```
+mcp__conveyor__start_task(taskId)
+```
+
+The build runs on **your** account and key, and starting reassigns the card to
+you — that is the documented contract, not a side effect. If you are starting
+something on someone else's behalf, say so, because their name comes off the
+card.
+
+## 3. Confirm it actually started
+
+**This is the step the verb exists for.** `start_task` returns once the intent
+is written; the environment converges afterwards, so a successful call is not a
+running pod.
+
+Poll `mcp__conveyor__get_build_status` until the workspace reports it is
+provisioning or running, and give it a couple of minutes — a cold pod takes
+longer than a warm one. Then report the outcome honestly:
+
+- **Running / provisioning** → started; go to step 4.
+- **Still pending well past the boot window** → say it has not come up yet and
+  point at the card's setup log rather than declaring success.
+- **Failed** → report the failure reason from the card. A provision failure
+  posts its cause to the card (quota denials, missing credentials); read it
+  instead of guessing, and do not immediately retry — a terminal cause will
+  fail the same way.
+
+Never report "started" from the tool call alone.
+
+## 4. Hand back a place to watch
+
+Give the person, in one short message:
+
+- the card URL,
+- that the agent posts progress to the card's chat,
+- `mcp__conveyor__get_connect_urls` for the preview/attach links when they want
+  to look inside,
+- and `mcp__conveyor__stop_task` if they want it back.
+
+Then stop. You are not the build's babysitter — the card is where it reports,
+and a loop that watches a cloud build from a local session just spends tokens
+narrating something the card already shows.
+
+## What this skill is not
+
+- **Not a builder.** If the work should happen in this checkout, that is
+  `/conveyor-build`. Starting a pod to avoid doing a two-minute local edit is
+  slower, not faster.
+- **Not a planner.** A card that needs a plan gets `/conveyor-plan` first; this
+  skill refuses rather than starting into ambiguity.
+- **Not a merger.** The pod opens a PR; review and merge are their own verbs.