Vibing Worker

---
name: vibing-worker
description: Use when this chat's system prompt states it was started by another vibing.nvim chat (an orchestrator). Covers where and when to report back, the report's shape, and what not to do — the full version of the protocol summarized in that system-prompt line.
user-invocable: false
---

# vibing-worker

This chat is a worker: some other vibing.nvim chat (its orchestrator) created it and is waiting to
hear back. Your system prompt already names that chat and gives you the exact call to make — this
skill is the detail behind that line, not a replacement for it. If the two ever disagree, the
system-prompt line wins: it is generated fresh for this turn, this file can go stale.

## Where and how to report

Call `nvim_chat_send_message` with:

- `file_path`: the orchestrator's path, exactly as given in your system prompt. If your system
  prompt names more than one orchestrator, call this tool once per one — a single call reaches
  only the `file_path` it names.
- `from_bufnr`: your own chat buffer number, also given in your system prompt.
- `queue_if_busy: true`. Without it, the send is refused outright whenever the orchestrator
  happens to be mid-turn, and the report is simply lost — not retried, not queued.
- `message`: the report itself (shape below).

This is the only path that reaches the orchestrator. Writing your findings in your own chat
buffer and stopping does not report anything — nothing reads that buffer unless the orchestrator
calls `nvim_get_buffer` on it, which it only does after being told something is worth reading.

## When to report

**When the task is done.** The ordinary case: finish the work, then send the report before ending
your turn.

**Before you act on something you expect will need approval.** A tool-approval prompt stops you
inside the tool call — nothing of yours runs again until somebody answers it, so you cannot report
_while_ one is open. If you can see one coming (a destructive command, an edit outside what the brief covers),
send a heads-up first, in the same turn, before making that call. The orchestrator (or the user,
depending on `agent.orchestration.delegated_approval`) is who clears it either way; a heads-up
just means they aren't finding out from a cold watchdog notice with no context.

**The moment you find you cannot proceed.** Not "eventually, once you've tried everything" — as
soon as you know the task can't be finished as briefed (missing information, a conflicting
constraint, a brief that turns out to be ambiguous), report that and ask, rather than guessing or
grinding on it silently. A worker that stops normally after writing only "couldn't do this" in its
own buffer produces no notification at all: `idle` looks identical whether the task succeeded or
was abandoned halfway.

## When the brief does not match the code

Your orchestrator wrote the brief from what it remembered reading; you are reading the code now.
So a brief can be wrong in a way its author could not have seen, and the wrongness is concentrated
in the parts that say **how**: over one 15-PR run, three briefs named a fix that did not address
the actual cause, and a fourth named a symbol that existed only on another branch. The workers
were right in all four.

**Follow the brief's goal; treat its implementation steps as a guess, and say so when they
diverge.**

- **A symbol, file or line the brief names that is not here**: do not quietly substitute the
  nearest match, and do not create it. Find the current name, use it, and say in your report that
  the brief named something else — that is how the orchestrator learns its picture is stale before
  it briefs the next worker from the same memory.
- **An implementation the brief dictates that would not achieve the invariant the brief also
  states**: the invariant wins. Do what satisfies it, and report both what was asked for and why
  you did something else.
- **A test assertion the brief dictates that cannot fail**: write one that can, and report the
  substitution. An assertion handed down from outside gets written whether or not it tests
  anything.
- **A brief whose goal itself does not survive the code** — the bug is elsewhere, the constraint
  is impossible, two requirements contradict: that is "cannot proceed as briefed". Report it now
  (above) rather than redesigning the task alone.

Deviating is safe only when it is visible. An unreported deviation leaves the orchestrator
aggregating against a plan that no longer describes what you built, and it will brief the next
worker from that same plan.

## When the user speaks to you directly

Not every turn here comes from the orchestrator. A turn delivered from another chat opens by
naming the chat that sent it ("Another chat sent you this:" with a `### From <path>` line, or a
watchdog notice listing chats); a turn with no such marker was typed by the user directly into
this chat buffer.

The reporting duty above is about orchestrated work. For a user-initiated turn:

- If the outcome affects the orchestrated task — its scope, its files, its conclusion — report
  it, and say explicitly that the user directed it. Without that line the orchestrator reads
  your report as the answer to its own brief.
- Otherwise send no completion report. The user who started the turn is already looking at this
  buffer; waking the orchestrator spends one of its turns on work it never dispatched.

An answer to a question you asked, or to a tool-approval prompt, is not a new task — it resumes
briefed work, so the ordinary duty applies to whatever that work concludes. The same goes for an
automatic continuation after a usage limit ("Continue from where you left off." or similar): it
carries no sender line, but it merely resumes whatever the interrupted turn was doing, so it
keeps that work's provenance. When in doubt, ask what started the work the turn is finishing,
not what started the turn.

## Report shape

**A few lines, not a document.** The orchestrator reads your transcript when it wants detail; the
report only has to tell it what to do next. Every line it does not need is paid for twice — once
when you write it, once when it is read — and pushes the line it does need further down.

```text
Done. <one-line conclusion>
Unresolved: <only if any>
Need: <decision or input — only if any>
```

- **Conclusion**: done, partially done, or blocked — one line. Name a PR or branch if there is
  one; do not list every file touched.
- **Unresolved / Need**: write them only when they exist. An empty section is not written as
  "none". A deviation from the brief (above) or a handoff item is one line each: what, and why in
  a clause.
- **A question is the question.** When you need a decision, state it with the options and your
  recommendation — no background the orchestrator already gave you in the brief.
- **Leave out**: how you got there, test counts and command output, what you checked and found
  fine, restating the brief, and any closing summary of the summary.

## Do not

- **End your turn with only a prose report in your own chat buffer.** That is not a report; it is
  a transcript nobody was told to read. If you wrote something worth knowing, send it.
- **Edit `.claude/rules/**`** even if the task seems to call for it. Those files are this
  project's own invariants, kept deliberately small and reviewed as such — a worker changing them
  mid-task bypasses that review. Note the need in your report instead and let the orchestrator (or
  the user) decide.
- **Forward your own subagent- or worker-launch calls to the orchestrator as if they were your
  report.** If you dispatch a subagent or create worker chats of your own (see `vibing-orchestrate`
  for that case), "I launched X" is not an outcome — it tells the orchestrator what you did, not
  what happened. Wait for the outcome and report that, holding your own **completion** report
  until your own workers have reported back to you. That hold applies only to the completion
  report — a heads-up before an approval-prone action, or a report that you yourself are blocked,
  still goes out immediately under "When to report" above, whether or not your own workers have
  finished.