@rallycry/conveyor-agent 10.13.72 → 11.0.0

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.

package/skills/conveyor-triage/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: conveyor-triage
+description: Investigate an unverified report — an incident, a bug card, a machine-filed error — until the root cause is either named or honestly declared unknown, then hand it to a Builder as a planned card. Use when the user says "/conveyor-triage <card>", "triage this incident", "what's causing this report", or when a triage session boots on a report card. Ends in a plan and a handoff, never in a pull request.
+---
+
+# Conveyor Triage
+
+Turn a report into either a **named root cause with a fix plan**, a **precise
+statement of what is still unknown**, or a **cancellation with an explanation**.
+
+**Triage does not ship code.** Even when you find the cause and the fix is
+obvious, you write it down and hand it off — the card goes to a Builder with a
+plan, story-point recommendation, and your evidence. A triager that starts
+implementing loses the thing that makes triage valuable: an honest account of
+what is actually known.
+
+**Default to triage.** A precise "here is what I ruled out and what I could not
+determine" is more useful than a confident wrong fix.
+
+## Ground rules
+
+- **All Conveyor tools fully-qualified** — `mcp__conveyor__get_task`, not
+  `get_task`.
+- **Reports are not infallible, and many are machine-filed** — error
+  boundaries and internal reporters produce titles that are whatever the
+  throwing code said, not a considered bug report. Read the code before
+  believing the description.
+- **Repo-specific commands are the host repo's business.** Gate commands, log
+  queries, rule paths, and database access all live in its CLAUDE.md and rules.
+  This skill says *what to establish*, not which command establishes it.
+
+## 1. Claim it
+
+Move the card to `InProgress` with `mcp__conveyor__update_task` and say in chat
+that you are investigating. The status move is the claim — it is what stops a
+second session picking up the same report.
+
+## 2. Check whether this is a repeat
+
+**Incident dedup reopens closed cards.** A report you are reading as new may be
+the third occurrence, with the original investigation already in its chat. Read
+`mcp__conveyor__read_task_chat` before trusting the description's timeline — a
+reopen changes what the evidence means, and "nobody noticed the reopen" is
+itself worth a suggestion.
+
+## 3. Gather telemetry before reading code
+
+Pull what the report actually carries first — its attachments
+(`mcp__conveyor__list_task_files`, `mcp__conveyor__get_attachment`), the stack,
+the structured context, and the card's own chat.
+
+> **Environment — the log tooling is NOT the same on both surfaces, and this
+> is the difference that decides how far triage can get.**
+>
+> **Locally** (conveyor-mcp) you have the full set:
+> `mcp__conveyor__query_gcp_logs` and `mcp__conveyor__query_grafana_logs` for
+> production telemetry, `mcp__conveyor__get_task_logs` for a card's agent
+> history, and `mcp__conveyor__get_task_sessions` for compute state.
+>
+> **In a pod, none of those exist.** The only equivalent is
+> `mcp__conveyor__get_execution_logs`, which reads *this* card's own CLI
+> history — not production, and not another card's. A pod triage session
+> therefore cannot reach production telemetry at all.
+>
+> That is a limit on your CONCLUSION, not just on your tooling. If naming the
+> root cause requires production logs and you are in a pod, the honest outcome
+> is a triage handoff that says exactly which query would settle it — not a
+> guess dressed as a finding.
+
+Note which environment the report came from before querying; asking the wrong
+one produces confident nonsense.
+
+**Write down what the report does NOT contain.** Missing route, missing user,
+missing build revision, missing screenshot — each gap is both a limit on your
+conclusion and a suggestion to file in step 7.
+
+## 4. Locate and reproduce
+
+Find the code path the report implicates and, where you can, reproduce it. A
+diagnosis grounded only in reading is a hypothesis; a reproduction makes it a
+finding. Attach evidence to the card with `mcp__conveyor__upload_attachment` —
+a screenshot, a log excerpt, a short recording — so the Builder inherits proof
+rather than your assertion.
+
+## 5. Decide
+
+### Hand off for a fix — only if ALL of these hold
+
+- You can name the root cause **in code** — not "something in permissions", not
+  "probably a race".
+- The fix is self-contained: no unverifiable migration, no multi-service
+  redesign.
+- You are confident it will not regress adjacent behavior, checked against the
+  domain's rules.
+- **That confidence is grounded in telemetry or a reproduction, not in code
+  reading alone.** If neither backs the diagnosis, triage instead.
+
+### Triage — if ANY of these hold
+
+- The description is vague: no specific element, action, or expected-vs-actual.
+- No clear cause after a genuine investigation.
+- Intermittent, and telemetry does not explain it.
+- Needs a repro environment, design input, production-data access, or infra
+  changes you cannot make safely.
+
+### Cancel — if ANY of these hold
+
+- The code behaves as designed and the reporter's expectation was wrong.
+- The "bug" describes functionality that does not exist yet — that is a feature
+  request; file it with `mcp__conveyor__create_suggestion`.
+- The reporter appears confused about how the feature works.
+
+Post a clear, non-dismissive explanation **before** cancelling. A cancellation
+with no explanation reads as dismissal and the report will come back.
+
+### Before you call it "already fixed" or "stale pre-fix data" — verify both halves
+
+This verdict needs two facts, each **checked**, never assumed:
+
+1. **Was the fix actually deployed in the code the report ran against?**
+   Establish which environment and which branch, then check whether the fix
+   commit is an ancestor of what was running, and compare its merge time
+   against the card's creation **and any reopen timestamps**.
+2. **Does the data predate the fix?** Look up the subject entity's age; the
+   report does not carry it.
+
+The self-contradiction that signals a bad diagnosis: *"the fix is deployed"*
+and *"the data predates the fix"* cannot both be true for an entity created
+after the deploy. A report filed today, on an environment carrying the fix for
+days, about an entity created today, is a **live bug** — reproduce it on
+current code rather than writing it off. And never inherit a previous
+investigation's "this predates the fix" conclusion without re-running check 1.
+
+## 6. Write the outcome onto the card
+
+**Handing off for a fix:** save a plan with `mcp__conveyor__update_task` that
+names the root cause with `file.ts:line` citations, states the fix and the
+files it touches, lists the verification a Builder should run, and recommends
+story points and risk. Then move the card to `Open` so a Builder can claim it.
+Do **not** cut a branch, and do **not** open a PR.
+
+**Triaging:** post what you established, what you ruled out, and precisely what
+is still unknown — including what evidence would resolve it. Then move it to
+`Open`. "Needs a repro with the console open" is an actionable handoff;
+"couldn't reproduce" is not.
+
+**Cancelling:** explain the actual behavior, then cancel.
+
+## 7. File at least one suggestion — always
+
+Every triage produces at least one `mcp__conveyor__create_suggestion`, in
+parallel with the outcome above. Investigation is the only time the gaps in
+your own reporting pipeline are visible; the moment passes.
+
+| What you observed | What to suggest |
+| --- | --- |
+| The report carried only a message and a stack | Enrich reports with route, user, and build revision |
+| No trace id, so it could not be correlated to server spans | Propagate trace context from client to server |
+| No console output captured | Capture browser console output in reports |
+| Visual bug with no screenshot | Add viewport capture to the report form |
+| A reopened dedup hit that nobody noticed | Surface reopen count and timestamps on the card |
+| A generic title that deduped wrongly | Tune the report fingerprint for that source |
+| No expected-vs-actual in the description | Add structured expected/actual fields to the form |
+| You read five or more files to understand a domain with no rule doc | Add a rule doc for that domain |
+| A test would have caught this | Add coverage for that path — found by report, not CI |
+
+Use `mcp__conveyor__list_tags` to pick real tag names; unknown names come back
+in the result rather than failing the call.
+
+## 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-workflows/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: conveyor-workflows
+description: How to work with Conveyor from any repo it manages — connect or repair the Conveyor MCP, create and plan cards, decide task vs suggestion vs incident, build packs, start or monitor agent builds, open PRs the non-duplicating way, and review completed work. Use when asked "how do I use conveyor", "create a card", "file this in conveyor", "start a build", "review this conveyor task", when Conveyor MCP tools are missing or erroring, or when a PR was auto-closed or a duplicate card appeared.
+---
+
+# Conveyor Workflows
+
+Conveyor is the task source of truth for this repo. Cards must let the next
+agent or human pick up cold: search before creating, keep task chat current,
+and let Conveyor's own automation do the linking.
+
+## Connect and resolve context
+
+- All Conveyor tools are called fully-qualified (`mcp__conveyor__get_task`);
+  bare names fail with "No such tool available".
+- Start with `mcp__conveyor__get_connection_context`. No default project?
+  `mcp__conveyor__list_projects` and match `githubRepoOwner/Name` against the
+  cwd's `git remote`. Conveyor MCP is multi-project — pass `projectId`
+  explicitly when working across projects.
+- **A mistyped `projectId` surfaces as "Insufficient permissions", not "not
+  found".** Re-check the ID character-for-character before concluding you lack
+  access.
+- MCP missing, stale, or unauthenticated → [references/mcp-setup.md](references/mcp-setup.md).
+- Two MCP surfaces exist with different arg shapes: the in-pod agent tools
+  (`post_to_chat` takes `message`) and the standalone `@rallycry/conveyor-mcp`
+  server for external clients (`content`, plus `taskId`/`comment` variants).
+  You are on the in-pod surface when Conveyor provisioned your workspace;
+  external when the MCP was configured by hand. Each accepts the other's
+  field name as an alias where possible, but read the tool's schema — don't
+  guess across surfaces.
+
+## Cards: create, classify, plan
+
+- **Search first**: `mcp__conveyor__search_tasks` on 2-3 keyword variants
+  (`typeFilters` to include incidents/suggestions); use
+  `mcp__conveyor__list_tasks` when filtering by status/assignee instead of
+  text (results are priority-ordered). A card may already exist — attach to
+  it (post your context to its chat) rather than forking a duplicate.
+- **Classify**: buildable work → `mcp__conveyor__create_task`; an
+  idea/improvement you are NOT committing to build →
+  `mcp__conveyor__create_suggestion`; incidents (production breakage) are
+  filed by monitoring and users through Conveyor's incident tooling — you
+  will usually *work* incident cards, not create them.
+- **Mechanics**: `create_task` takes the title, description, `plan`
+  (markdown), and optional status/tags; cards start in `Planning`. Every
+  status change you make goes through `mcp__conveyor__update_task`
+  (`status: "Open"` / `"InProgress"` / `"Cancelled"`, plus plan/description
+  edits). Review-side transitions are NOT yours — see the PR section.
+- **Description vs plan**: the description is capped at 255 chars — 1-2 plain
+  sentences a non-engineer can read. All technical detail goes in the plan.
+- **Plan quality bar**: a context-free reader must be able to execute — exact
+  repo-relative files and symbols, runnable testing commands, decisions
+  already made recorded in Notes. Format and sizing:
+  [../conveyor-plan/references/plan-format.md](../conveyor-plan/references/plan-format.md).
+  For research-backed planning, use the `conveyor-plan` skill — it is the first
+  half of the pair below.
+- **One card per deliverable/PR** (mirror packs below are the documented
+  exception). Multi-PR work becomes a pack: children via
+  `mcp__conveyor__create_subtask` (new children) or
+  `mcp__conveyor__set_task_parent` (adopt an existing card into the pack, or
+  detach one with `parentTaskId: null`), with
+  `mcp__conveyor__add_dependency` edges. Orchestration packs run children as
+  their own builds/PRs; mirror packs (children created with
+  `followParentStatus: true` on `create_subtask`) document already-done work
+  shipping in ONE PR on the parent. Don't pack below
+  genuinely-multiple-independent-pieces scope.
+- **Identification is Conveyor's job**: moving a card beyond Planning
+  (`update_task` → `status: "Open"`) auto-fills story points, icon, agent,
+  and tags — for pack children too. Post your SP/tag recommendation to chat
+  BEFORE the flip; never set icon or points yourself.
+
+## Tags are the project glossary
+
+Tags are the shared vocabulary humans and agents align on, not just board
+labels. Each tag carries a `description` (≤255 — the summary), an `overview`
+(the full markdown spec: philosophy, mechanics, invariants), `contextPaths`
+(where the code/rules live), and parent/child tags (a sub-type taxonomy).
+
+- **Read**: `mcp__conveyor__list_tags` for the inventory (names, descriptions,
+  hierarchy, `contextPaths`, `hasOverview`) — the context links ship inline, so
+  auditing what the glossary wires up takes one call, not one per tag;
+  `mcp__conveyor__get_tag` (id or exact name) for one term's full entry —
+  overview, linked files, hierarchy, and recent revisions with their reasons. When a card or chat message deep-links a term
+  (`@[tag:<id>]` — the web composer offers this when you type a tag name),
+  `get_tag` is how you pull its full context. To deep-link a term yourself,
+  write `@[tag:<name>]` with the tag's exact name — chat posts and card
+  plans/descriptions are canonicalized to the id token at write time, so you
+  never need the id. An unknown name stays plain text.
+- **Write**: `mcp__conveyor__manage_tags` (Moderate+). Whenever your work
+  changes how a tagged system behaves, update that tag's `overview` and pass a
+  one-line `reason` — it lands in the tag's revision history (in-pod agents
+  get their current card auto-stamped too), so the team sees why the glossary
+  changed. Any loaded term worth a definition deserves a tag.
+- **The PR nudge**: `create_pull_request` may append a "Touched glossary
+  areas" line — your diff's files matched against tag `contextPaths`. Treat it
+  as a checklist prompt, not an order: update a listed tag's
+  overview/description only when your change altered what the term means, add
+  the tag to the card only when the work is genuinely about that area, and
+  skip freely otherwise. Never bulk-assign tags from path matches alone.
+
+## Execute
+
+- **Status reflects reality**: claiming a card = `update_task` →
+  `status: "InProgress"` plus a chat note saying who/where is working it.
+  Never hand-move a card to `ReviewPR` or set its PR link — that transition
+  belongs to `create_pull_request` / the PR sync.
+- **One skill per lifecycle phase, and they mean the same thing everywhere.** A
+  cloud pod running a card and a local session working one read the SAME skill
+  text; the handful of genuine environment differences (WIP autosync, whether
+  `create_pull_request` pushes for you, which verdict tools exist, shared vs
+  dedicated dev stack) are called out inline.
+
+  | Phase | Skill |
+  | --- | --- |
+  | Investigate an unverified report | `conveyor-triage` → hands off a planned card, never a PR |
+  | Plan the work | `conveyor-plan` → writes an executable plan onto the card |
+  | Hand it to the cloud | `conveyor-start` → starts a pod and confirms it came up (local surface only — `start_task` does not exist in a pod) |
+  | Do the work here | `conveyor-build` → follows the plan to a PR |
+  | Judge the work | `conveyor-review` → one verdict, with risk |
+  | Work a whole queue locally | `conveyor-local-loop` → selection and pacing over the above |
+
+  `conveyor-start` and `conveyor-build` are the same phase reached two ways —
+  hand the card off, or do it in this checkout — so the choice is about where
+  the work runs, not about what happens to the card. `conveyor-build` routes a
+  childless card to its task path and a feature-branch pack to its pack path on
+  its own; you do not pick. And an
+  incident goes to `conveyor-triage` before `conveyor-plan` — planning a fix
+  from a symptom is how the wrong thing gets built confidently.
+- **Cloud or local**: `mcp__conveyor__start_task` boots a cloud agent
+  environment for an Open card (that agent run is the card's "build" —
+  `mcp__conveyor__get_build_status` reports it), and that agent runs
+  `conveyor-build` itself. To execute cards on the local machine instead, use
+  `conveyor-build` directly for one card, or `conveyor-local-loop` to work a
+  whole queue. Don't do both — a started task's agent will duplicate local
+  work. The loop idles on `conveyor-wait`, a CLI in `@rallycry/conveyor-mcp`
+  that blocks until a card becomes claimable, so an idle loop wakes on a board
+  event instead of a timer.
+- **Reserved-branch trap**: a card with an assigned agent may have a reserved
+  `githubBranch`. Check `get_task` before pushing: if set, push to THAT
+  branch; a PR from any other branch gets auto-closed and unlinked.
+- **Chat is the log**: post at real milestones — claim, blocking discovery,
+  decisions, gates green, PR — not play-by-play. Findings (root causes, dead
+  ends, verification results) belong in task chat, not just your session.
+- **Files**: `mcp__conveyor__upload_attachment` hosts images/video/files on
+  the card; the returned URL is reusable in PR bodies. Attach visual evidence
+  for UI changes before opening the PR.
+- **Found-but-not-fixed** → a follow-up card with enough context to execute
+  cold, not a TODO in chat.
+
+## Open the PR — two paths, pick exactly ONE
+
+| Situation | Path |
+| --- | --- |
+| A card exists (found or created) | `mcp__conveyor__create_pull_request` — one call opens the PR, links the card, moves it to ReviewPR. Pass `head:` if the card has no branch. |
+| No card exists | Open the PR with your git host's normal tooling and STOP — Conveyor's PR sync spawns and links a card itself. |
+
+Card linking belongs to exactly one actor, never you by hand. Mixing paths is
+the known failure mode: a hand-moved card linked to nothing plus a
+sync-spawned duplicate.
+
+## Monitor and review
+
+- Monitor with `mcp__conveyor__get_task`, `mcp__conveyor__read_task_chat`,
+  and `mcp__conveyor__get_build_status`.
+- Reviewing a ReviewPR card: inspect the diff and task chat; approve with
+  `mcp__conveyor__approve_task` only if the PR implements the plan and
+  follows repo patterns — it advances the card through the review pipeline
+  (and, per project settings, approves/merges the PR). Otherwise
+  `mcp__conveyor__request_changes` with specific feedback, which returns the
+  card to the builder. Manual test checklists ride
+  `mcp__conveyor__set_manual_tests` and surface for human sign-off at the
+  review stage.
+- Don't approve or merge your own PRs unless the project's policy explicitly
+  allows it.
+- Remote workspace access (SSH/preview) goes through
+  `mcp__conveyor__workspace_start_tunnel` / `workspace_stop_tunnel` — one
+  canonical tunnel per task, torn down when done.
+
+## Reliability gotchas
+
+- **A mutating call that errors may have already landed.** "Session not
+  found" / timeout on `create_*`, `post_*`, `approve_*`, merge → check the
+  effect (`read_task_chat`, `get_task`, the PR) before re-firing; cap
+  identical retries at one. Blind re-fires double-post and double-approve.
+- **Git ground truth is remote-first** in agent pods and shared workspaces:
+  on a surprising conflict, failed push, or dirty tree, run `git ls-remote
+  origin <branch>` and `git merge-base --is-ancestor` before rebuilding
+  anything locally — platform autosync may have already pushed for you, and a
+  dirty tree may belong to a concurrent session.
+
+## Improve This Skill
+
+If this skill was insufficient or slowed the work down, file it with
+`mcp__conveyor__create_suggestion` on your current project: the issue,
+evidence, and proposed fix.