ask-colleague

name	ask-colleague
type	command
description	Ask colleague — a *different* backend/model than you (e.g. a local vLLM Qwen) — to take a scoped repo task off your plate, then fold its answer back. The point isn't a stronger model; it's a second, independent mind, and that diversity is the value: `ask-colleague review` gets a candid second opinion on a diff, `ask-colleague explore` gets a fresh read of an area, `ask-colleague write` hands off a small implementation, `ask-colleague feedback` grades a finished work item (the ROI loop), and `ask-colleague clean` reaps stale/corrupt `colleague/*` branches a crashed run left behind (which can break `git fetch`). Pilot a running work item with `monitor`/`guide`/`stop`. Reach for it REFLEXIVELY, the way you'd lean over to the teammate at the next desk — not only when asked: before you present or open a PR on a non-trivial committed diff, run `review` for a diverse second opinion; for a fresh read of an unfamiliar area whose answer is independent of your current context, run `explore`. Both are read-only — isolated in a throwaway git worktree, zero side effects to your tree/branch — so the reflex is always safe; the side-effecting `write --apply` / `write --pr` still needs the user's go-ahead. Triggers when the user says "ask colleague", "ask a colleague to review/explore/write this", "have colleague take a look", "get a second opinion", "ask the other model", "rate that work item", "clean up a crashed colleague run" — and still on the legacy "outsource this". Colleague's output is a second opinion to verify and own, never authority.

ask-colleague — lean on colleague as a different mind

ask-colleague drives the colleague CLI so a Claude agent can hand a scoped task to a different backend (default: a local vLLM Qwen3.8-27B on :8001). Colleague's model is not assumed to be stronger than you — its value is diversity. A second, independent mind catches things the author's mind glides past, which is why review is the headline verb. Treat it the way you'd turn to the colleague at the next desk: a quick, low-ceremony ask, not a heavyweight handoff.

This skill is the operator: a portable wrapper that resolves the CLI and turns each verb into a colleague work, then prints the work item's result summary.

The reflex — when to ask colleague unprompted

Don't wait to be told. The two read-only verbs have zero side effects (throwaway worktree, can't touch your tree), so reaching for them is always safe — make it a habit on tasks that fit:

GO (reach out on your own — default to the read-only verbs):

• review — the standing reflex. You (or a subagent) just produced a non-trivial committed diff and are about to present it or open a PR. Get a diverse second opinion first. A different mind catches what the author's mind glides past — that's the whole point. A real review on a local model takes tens of seconds to a few minutes (it reads the diff + touched files), so kick it off in the background and keep working rather than blocking on it; fold the findings in when it lands.
• explore — you need to understand an unfamiliar area whose answer is independent of your current context, and you could be doing something else meanwhile. Fan it out, fold the findings back.
• A scoped, verifiable subtask where a fresh pass raises your confidence and you can cheaply check the result.

NO-GO (just do it yourself):

• Work that needs your accumulated context, the user's intent, or cross-cutting design judgment — a context-free second mind will drift, not help.
• Anything outward-facing or destructive without a user nod: write --apply / write --pr, posting, deleting. The read-only verbs are the unprompted reflex; side-effecting ones are not.
• Trivial work that's faster to just do (a one-line edit) — the work item + fold-back costs more than the edit.
• Output you can't verify cheaply — if you can't check it, diversity is just noise.

Guardrails (always):

• One-glance readiness. colleague whoami names the live work engine + model; if it reports mock or you're unsure the server is up, run colleague doctor --probe. Don't burn time on a dead or no-op backend.
• Second opinion, not authority. colleague is a different mind, not a stronger one. Weigh its findings, verify its claims, own the decision. Diversity is the value; verification is the price.
• Close the loop. Occasionally ask-colleague feedback last --rating N so the ROI of asking colleague for this kind of task is measurable — and you learn when to stop.

How to run

The entry point is scripts/ask-colleague.sh. Invoke it from the repo you want colleague to work on:

bash .claude/skills/ask-colleague/scripts/ask-colleague.sh <verb> "<text>" [options]

It resolves the CLI portably — an installed colleague on PATH (the normal case), falling back to uv run colleague when inside the colleague checkout, else an install hint.

Verbs

Verb	What it does	Side effects
explore "<question or area>"	Read-only investigation of the repo; the model reads and reports findings.	None to your working tree / branch — runs in a throwaway worktree at HEAD; writes only a gradable run artifact under the gitignored .colleague/ bookkeeping dir.
review "<what to focus on>" [--base main]	A diverse second opinion on the committed diff (<base>...HEAD).	None to your working tree / branch — throwaway worktree, committed changes only; writes only a gradable run artifact under the gitignored .colleague/ bookkeeping dir.
write "<task>" [--apply|--pr]	Implement a change. Previews by default (throwaway worktree, prints the would-be diff); --apply lands a work branch in place; --pr pushes + opens a PR.	None to your working tree / branch by default (preview); a colleague/<id> work branch / PR only with --apply / --pr.
plan "<task>"	Colleague PLANS a complex task: it proposes a spec, then a split plan, then fans the waves out to a subagent-colleague workforce (colleague plan run … --yes). The inverse of /think — same arc, but colleague is the planning mind, not Claude. Needs a live backend.	Runs colleague plan in --repo (not a throwaway worktree): the workforce stage spawns isolated subagent worktrees and can land branches — treat like write --apply (gets a user nod).
feedback <id|last> [--rating N]	Grade a finished work item (the ROI loop). With --rating N (1–5, plus --notes) it records feedback; without, it shows the work item's existing feedback. last resolves the most recent work item in --repo.	Writes .colleague/<id>.feedback.json only when --rating is given; read-only otherwise.

Options

Option	Meaning
--repo PATH	Target repo (default: .).
--base BRANCH	Base for the review diff (default: main).
--engine NAME	Backend plugin (default: $COLLEAGUE_ENGINE or vllm-openai).
--model NAME	Model (default: $COLLEAGUE_MODEL or unsloth/Qwen3.8-27B-NVFP4).
--base-url URL	OpenAI base URL (default: $COLLEAGUE_BASE_URL or http://localhost:8001/v1).
--role NAME	Typed subagent role for the run (explorer, reviewer, validator, planner, writer). Since #416 a top-level --role explorer runs at thinking effort low (off selectable via --effort off); other top-level roles keep the acting seat's effort.
--effort RUNG	Thinking effort for the acting seat (#416): off | low | medium | high | xhigh | default. Unset = colleague's own table (acting seat medium). off sends enable_thinking:false — the measured win for small, well-specified briefs (same brief: off 24 s / xhigh 88 s / medium 129 s, all correct — docs/evidence/2026-08-22-per-seat-thinking-effort-416-results.md); xhigh for open-ended judgement; default = the kill-switch (send nothing, the pre-#416 wire). Exported as COLLEAGUE_CORTEX_REASONING_EFFORT + COLLEAGUE_WORKER_REASONING_EFFORT; validated before the run.
--seat-effort S=R[,S=R]	Per-seat override for the other seats (cortex, , , , , ) — e.g. . Exported as . Children keep their role table (writer/planner medium, reviewer/validator low, explorer off) unless the parent overrides per delegation.

The result printed to stdout is the work item's TaskResult.summary (plus changed_files / work branch for write), parsed from colleague work --json. Per-step progress streams to stderr while it runs. Pass --json to get the raw TaskResult on stdout instead of the human digest (the drive verbs emit the normalized TaskResult; feedback / clean forward --json to colleague), keeping stdout valid JSON for a machine consumer while diagnostics stay on stderr.

When to reach for which verb

• review — the standing use. You wrote (or an agent wrote) a change and you want a candid, independent pass over the committed diff before you trust it. Treat the output as a second opinion to weigh, not a verdict.
• explore — you want a fresh, unbiased read of an unfamiliar area ("how does X work here?") without anchoring on your own assumptions.
• write — a small, well-scoped implementation you're happy to delegate. It previews by default (runs in a throwaway worktree and prints the would-be diff without touching your tree); pass --apply to land it on a colleague/<id> work branch you can inspect, merge, or discard, or --pr to open a PR.
• feedback — after colleague finishes a work item, close the loop: record how good it was. Every work item's artifact already carries always-on stats (elapsed time, tokens read/generated, tools used, bytes written, reasoning-vs-answer sizes); feedback adds a 1–5 quality grade. Stats say what it cost, feedback says how good it was — together they let you compute the ROI of asking colleague and decide whether to ask again (and which backend). Grade the most recent work item with ask-colleague feedback last --rating 4 --notes "…".
• clean — recovery, not routine. A crashed / interrupted write --apply can leave a dangling colleague/<id> branch pointing at half-written (0-byte) objects that breaks git fetch / git pull. Run ask-colleague clean (or colleague clean) to reap it — start with --dry-run to see what it would remove. It only ever touches colleague/* refs and .colleague/ artifacts.

Thinking effort and resuming (#416)

Colleague resolves a per-seat thinking effort where each seat is built, never per turn — the acting seat defaults to medium, deepthink xhigh, senses/Talker off, children by role (writer/planner medium, reviewer/validator low, explorer off). The wrapper exposes the operator overrides as --effort (acting seat) and --seat-effort (any seat); a typo fails fast. Rule of thumb from the measurements: --effort off for small, well-specified briefs (5× faster, same result), leave the default for ordinary work, --effort xhigh for open-ended judgement (review of a subtle diff, a plan). Effort does not rescue a module-sized brief — split the request instead (#415).

A run cut by a timeout, SIGTERM or an exhausted budget is resumable: ask-colleague resume <task-id|last> continues it from its artifact on the same work branch; --detach keeps your shell free. Prefer resume over re-dispatch — the continuation carries the prior steps and lineage.

Piloting a flight

Dispatch a drive with --watch (on explore, review, or write) to make the work item watchable. While it runs you can:

• ask-colleague monitor <task-id> — watch the flight's live feed
• ask-colleague guide <task-id> "<message>" — send mid-flight guidance
• ask-colleague stop <task-id> — cooperatively ask the flight to stop

Control is applied at the running loop's next turn boundary, so guidance and stop requests take effect on the next iteration rather than interrupting mid-step.

Hard rules (do not violate)

• explore and review are read-only. They run in a throwaway git worktree at HEAD, so a stray write can't reach your working tree or branch; the prompts also tell the model not to modify anything. Don't route a change-making task through them — use write.
• write previews by default; applying refuses a dirty tree. A preview runs in an isolated worktree and never touches your tree, so it is safe even when dirty. --apply / --pr (the in-place path) refuses a dirty tree unless you pass --allow-dirty — this guards the dirty-tree hazard: committing uncommitted edits onto the work branch and leaving you there. Commit or stash first before applying. --allow-dirty is propagated to the runtime, which since colleague#149 enforces the same guard directly (a bare colleague work/drive also refuses uncommitted tracked changes).
• Colleague's output is a second opinion, not authority. The backend may be a smaller/different model; weigh its findings, verify its claims, and own the decision yourself.

Honest limits

• Read-only is enforced by worktree isolation + prompt constraint, not a sandbox — the loop always exposes write_file/run_command, so the model can still run arbitrary read-only commands.
• review covers committed changes only (<base>...HEAD). To review uncommitted work, commit it first.
• The default backend is whatever single model is running locally; a multi-model fleet (different model per verb) is separate infrastructure.
• Every verb writes bookkeeping under .colleague/ (run artifacts for explore/review/write; feedback records; the last_work pointer) — none of it in your tracked tree, but in a repo that does not already gitignore .colleague/ it shows up as untracked files. Add .colleague/ to your .gitignore (keep !/.colleague/commands/ if you commit command templates).
• A crashed run can wedge git fetch. A write --apply interrupted mid-commit can leave a dangling colleague/<id> branch + 0-byte artifacts; ask-colleague clean recovers it. A SIGKILL/OOM during the commit can still corrupt git objects (git/filesystem durability, not the skill's to guarantee) — which is exactly what clean is for.

Provenance

This is a first-party colleague skill — colleague is its origin. See docs/skill-sources.md for the consumer's per-repo skill ledger. The cite, don't import policy holds: downstream repos copy it, they don't symlink or depend on it.