@rallycry/conveyor-agent 10.13.71 → 11.0.0

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.

package/skills/conveyor-workflows/references/mcp-setup.md

@@ -0,0 +1,43 @@
+# Conveyor MCP Setup
+
+Use this when Conveyor MCP tools are missing, stale, or unauthenticated.
+
+## Preferred install path
+
+Ask the user to open Conveyor, choose the target project, then go to
+**Settings → User Settings** (`/projects/<project>/user-settings`). The
+**Connect Claude Code** section generates the exact install command / MCP JSON
+for their account and project — use that, not Project Settings and not the
+MCP Tools reference page.
+
+## Manual repair (Claude Code)
+
+```bash
+claude mcp remove conveyor -s local 2>/dev/null;
+claude mcp add conveyor -s local \
+  -e CONVEYOR_API_URL=<api-url> \
+  -e CONVEYOR_USER_TOKEN=<user-token> \
+  -e CONVEYOR_PROJECT_ID=<project-id> \
+  -- npx -y @rallycry/conveyor-mcp@latest
+```
+
+- Run from the repo folder; `-s local` scopes the server there.
+- The `remove` prefix makes token rotation idempotent.
+- Keep `@latest`; avoid unbuilt local packages.
+- `CONVEYOR_API_URL` and `CONVEYOR_USER_TOKEN` are required;
+  `CONVEYOR_PROJECT_ID` sets the default project (omit it to pass `projectId`
+  per call).
+- Non-Claude MCP hosts use the same command/env/package shape in their own
+  config format.
+
+After install, restart or reload MCP servers, then verify with
+`mcp__conveyor__get_connection_context` or `mcp__conveyor__list_tasks`.
+
+## Auth failure vs permission failure
+
+- Expired/invalid token → tools error with authentication failures; re-run
+  the connect flow above to mint a fresh token.
+- "Insufficient permissions" on a call that should work → check the
+  `projectId` first (a typo produces this exact error), then ask a project
+  admin about your role: mutations (tasks, builds, PRs) need Moderate access
+  or higher.