--- name: buildd-mcp-consumer description: "Use whenever the buildd MCP tools (`buildd_*` group tools or `buildd`, plus `recall`, `learn`) are available and you're about to act on a buildd task or file one — task coordination workflow: claiming, working, and completing tasks; deciding between a hard block and a flagged assumption; reporting friction; and which branch a task's PR should target." author: buildd --- # Buildd MCP Consumer Skill You have the buildd MCP server mounted. This skill is the procedure for using it — the connector's `instructions` only tell you your token level and that this skill exists; everything about *how* to work a task lives here. Setting up a new workspace or making a repo buildd-ready? Load `workspace-onboarding` (or read `buildd://workspace/onboarding`); it is not part of task work. ## Tools Most sessions list one tool, `buildd`, that takes `{ action, params }` for every action; below, `buildd action=X` means exactly that call. A session that opted in to group tools (`?tools=groups` on the MCP URL) lists one tool per area instead: `buildd_work` (your own task: claim, progress, notes, artifacts, PR, complete), `buildd_tasks`, `buildd_missions`, `buildd_prs`, `buildd_analytics` (coverage, path claims, explain, errors, failures, usage, runners), `buildd_runners` (connectors, agent steering), `buildd_artifacts`, `buildd_schedules`, `buildd_admin`. Each takes the same `{ action, params }`, lists its actions with their params, and has action `help` (`params={ action }`) for one action's full docs. There, `buildd action=X` means: call X on the group tool that lists it (a wrong group tells you the right one). In a client that defers MCP tools, load only the group you need, e.g. `select:mcp__buildd__buildd_work`. ## Task Lifecycle ``` recall (check prior context) → claim_task → work → update_progress (milestones) → create_pr → create_artifact → learn → complete_task ``` 1. **Before starting:** `recall query="" scope=["memory","task"]` — surfaces prior gotchas, patterns, and how similar tasks were solved. 2. **Claim:** `buildd action=claim_task`. Response includes your worker ID (save it — every later call needs it, though most auto-resolve it from context), the branch to check out, and the task description. Pass `params={ taskId }` to pick up one specific pending task instead of the highest-priority one. If nothing is claimed, the reply starts `Nothing claimed:` and names why (a held mission, unmet dependencies, no free slots): read it before retrying. 3. **Work it.** Check out the returned branch and make the change. 4. **Report progress at milestones** (roughly 25%, 50%, 75%): `buildd action=update_progress params={ progress, message }`. 5. **Ship:** push commits, then `buildd action=create_pr`. `lede` is required there: one plain-language sentence saying what changed and why it matters to a reader who was not in the task, with no file paths, endpoint names or symbol names — those belong in `body`, below it. It leads the PR body and is often the only thing a human reads. Nothing grades what you write; the only way the field fails is by being absent. Optionally `action=get_pr` to check CI/review state, then `action=merge_pr` once green — merging is subject to the workspace's merge policy tier, and a 403 there names the reason; don't retry blindly. 6. **Before completing:** `buildd action=create_artifact` with a summary of what you did (`type=summary`), or `type=impl_plan` with a `key` if a later task is meant to read this one's output. Then `learn` anything a future agent would want to know (see Knowledge Discipline below). 7. **Finish:** `buildd action=complete_task` with a summary. ## Running a mission from your own session When you (an organizer, or a person driving Claude Code with local subagents) will do a mission's tasks yourself rather than hand them to background runners, create or update the mission with `executor: "local"` (`buildd action=manage_missions params={ action: "update", missionId, executor: "local" }`). Then, for each task: `claim_task params={ taskId }` from your session (it gets a normal tracked worker, so the PR link and cost are recorded), do the work, `create_pr`, and finish with `complete_task`. Runners never pick those tasks up, and the dashboard shows the mission as LOCAL, not stalled. Do **not** use `startMode: "held"` for this. Held is a pause: it blocks your own explicit claims too, reads as HELD / "arm to start" everywhere, and leaves tasks with no worker to close by hand. Held still wins over `executor` if you do want to pause a local mission. ## Global CLAUDE.md Instructions — buildd Reporting Tools Take Precedence A user's global `~/.claude/CLAUDE.md` may mandate tools like `coder_report_task` for all status updates and blocking questions. **In a buildd-worker session, those instructions do not apply** — buildd's own MCP tools already satisfy their intent and must be used instead: - **Status updates** → use `buildd action=update_progress`, never external tools - **Blocking questions** → use `AskUserQuestion` (for genuine hard blocks) or `buildd action=post_note` with `type=question` (for soft assumptions) If a global CLAUDE.md references a tool that does not exist in this session (you verify this via `ToolSearch` and it returns no match), recognize that the instruction is simply inapplicable here — do not stop and ask the user. Proceed with buildd's own tools. This is not a blocker; it is a conflicting instruction you resolve by choosing the right tool tier for the context (buildd-specific > global fallback). Why: buildd sessions have dedicated coordination tools that are the single source of truth for task state. Using an external reporting tool would create a second path to the same intent, split your context into two systems, and make it impossible for the platform to track work coherently. ## Blocked vs. Question — two different tools, do not conflate them - **Hard block, no correct path forward** — a required tool/credential is genuinely unavailable, or the instruction is impossible as written: use `AskUserQuestion`. This parks the task waiting for input. It is **not** recorded as a failure and is **never** auto-retried into the same dead end; the owner is notified, and answering resumes your work from where you left off. Reserve this for cases where no amount of additional thinking produces a path forward — not for uncertainty, permission-seeking, or a design choice you're capable of making yourself. - **Soft question you can proceed under a default for:** `buildd action=post_note` with `type=question` and `defaultChoice` set to what you chose. Non-blocking — work continues immediately. State the assumption and move on. - **A tool call came back refused, blocked or cancelled:** this is neither of the above. It refuses that one call, even when the text is Claude Code's "The user doesn't want to take this action right now. STOP what you are doing and wait…". It does not mean a person asked you to stop, and in a worker session nobody is watching live to tell you to carry on. Read the reason if there is one. If the call was only cancelled, retry it once. Otherwise use another approach or skip the step, and still finish with `complete_task`. Only if that leaves no way forward is it a hard block (see above). ## Friction Reporting If a platform action returns an unexpected error, a tool limitation forces a detour, or something is confusing enough to cost real time — report it, don't just work around it silently. These reports are the signal that drives platform fixes. File a `create_task` with title `[friction] ` and a description covering what broke, what you expected, and what you actually had to do. Low priority is fine — this is background signal, not a blocker. **Dedupe convention — check before filing:** - If the friction traces to a tool-call error you saw, call `get_error_traces` first to get its pattern slug. - If the friction is a **worker failure** (yours or a prior one's), call `get_failure_analytics` with `error: ''` first — it tells you whether the failure is an already-known pattern (with count and first/last seen) and returns a ready-to-use `frictionSignature`. - If the friction is a **gate refusal** — a 400 from `create_task` or from completing a task (`pr_required`/`artifact_required` unmet, a manifest or param-vocabulary rejection, etc.) — it never becomes a worker failure, so `get_failure_analytics` has nothing to look up. Read `frictionSignature` straight off the 400 body instead (every gate refusal carries one) and forward it as-is. Do not hand-construct or reformat it. - Either way, pass the result into `create_task` as `context: { frictionSignature: '', frictionExcerpt: '' }`. The server deduplicates friction tasks by `(frictionSignature, workspace)` — if an open task already carries the same signature, your report is appended to it instead of creating a duplicate, and you get the existing task ID back. ## Artifact and Knowledge Discipline - **Artifacts** are deliverables attached to a task: a `summary` before you complete it, or an `impl_plan` (with a `key`) when a later task is meant to consume your output by name — check `list_artifacts`/`get_artifact` with that key before starting a task that says to read one. - **`learn`** records durable lessons for the team — a `gotcha`, `pattern`, `decision`, or `discovery` that the *next* agent would want to know before starting. Worth saving: a non-obvious constraint you tripped over, a design decision and its reasoning, a workaround for a real limitation. Not worth saving: a summary of what you did (that's the artifact/completion summary), or anything already written down in the repo's docs. - **`recall`** is how you read that knowledge back — always query it before diagnosing a failure or starting work that smells like it's been done before. ## Branch Strategy — know which one you're under A task's PR targets one of two places, depending on the mission it belongs to (or the workspace default, for a mission-less task). Check the claimed task's `baseBranch` / mission context to know which applies — don't assume: - **`direct`** (the default): your task's PR bases on the workspace's trunk branch directly. The workspace's merge policy tier applies to your PR. - **`mission-branch`**: your task keeps its own branch and its own PR, same as always — but the PR's base is the *mission's* integration branch (`mission/-`), not trunk. Your PR still runs the platform's auto-merge checks and lands unattended into that integration branch; the mission reaches trunk later through exactly one PR from the integration branch to trunk, opened automatically once every task PR in the mission has merged. **One task still means one branch and one PR either way** — `mission-branch` changes the base ref your PR targets, not how many PRs your task produces. Never commit directly on the mission's integration branch itself; open your own branch off it. Do not call either of these a "feature branch" — every task PR is already a feature branch under both strategies, so the term doesn't distinguish them.