guild-cli 0.22.0__tar.gz → 0.22.2__tar.gz

{guild_cli-0.22.0 → guild_cli-0.22.2}/.claude/skills/ask-colleague/SKILL.md

@@ -7,24 +7,27 @@ description: >
   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, and `ask-colleague feedback` grades a finished
-  work item (the ROI loop). Reach for it REFLEXIVELY, the way you'd lean over to the
+  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 — so the reflex is always safe; the side-effecting
-  `write --apply` / `write --pr` still needs the user's go-ahead. Triggers when the
+  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" — and still on the legacy "outsource this". Colleague's output is a second
-  opinion to verify and own, never authority.
+  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.6-27B` on
+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
@@ -95,10 +98,13 @@ else an install hint.
 
 | Verb | What it does | Side effects |
 |------|--------------|--------------|
-| `explore "<question or area>"` | Read-only investigation of the repo; the model reads and reports findings. | **None** — runs in a throwaway worktree at HEAD. |
-| `review "<what to focus on>" [--base main]` | A diverse second opinion on the **committed** diff (`<base>...HEAD`). | **None** — throwaway worktree; reviews committed changes only. |
-| `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** by default (preview); a `colleague/<id>` work branch / PR only with `--apply` / `--pr`. |
+| `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. |
+| `resume <task-id\|last> [--detach]` | **Resume a cut run** — a timed-out / SIGTERM'd / budget-exhausted work item picked back up from its persisted artifact (`colleague work --continue`, lineage on `TaskResult.continued_from`). `last` resolves the most recent work item in `--repo`. `--detach` runs it under `setsid`/`nohup` and returns at once (not `--background`, which drops the continue id — colleague#418). | Continues the ORIGINAL run's `colleague/<id>` work branch; never touches your tree / branch. |
+| `clean [--dry-run]` | **Reap what a crashed run left behind** (#162): stale/corrupt `colleague/*` branches + orphaned 0-byte `.colleague/` artifacts that can wedge `git fetch`. Scoped strictly to `colleague/*` (never touches an unrelated branch); conservative with `.git/objects` (reports 0-byte loose objects + suggests `git prune`, never deletes them). A thin pass-through to `colleague clean`. | Deletes corrupt `colleague/<id>` refs + 0-byte `.colleague/` artifacts in `--repo`; `--dry-run` changes nothing. |
 
 ### Options
 
@@ -107,19 +113,28 @@ else an install hint.
 | `--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 `sakamakismile/Qwen3.6-27B-Text-NVFP4-MTP`). |
+| `--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`). |
-| `--max-steps N` | Loop step budget (default: 20). |
+| `--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`, `worker`, `deepthink`, `senses`, `evaluator`, `design`) — e.g. `--seat-effort senses=off,deepthink=xhigh`. Exported as `COLLEAGUE_<SEAT>_REASONING_EFFORT`. Children keep their role table (writer/planner medium, reviewer/validator low, explorer off) unless the parent overrides per delegation. |
+| `--detach` | (`resume`) run detached and return at once; pilot with `monitor` / `guide` / `stop` once the log names the new flight id. |
+| `--max-steps N` | Loop step budget (default: 20). `explore`/`review` select colleague's own native **`explore`**/**`review`** mode profile (`colleague/profiles.py`, applied via `colleague work --mode`) instead of a wrapper-side override — today that profile defaults to 30, since read-only mapping fans out across more files. An explicit `--max-steps N` always overrides the profile's default, in either direction. If the resolved `colleague` predates `--mode` (a stale install on `PATH`), the wrapper falls back to the old caller-side `--max-steps 30` + reserved-steps behavior so it keeps working. |
 | `--apply` | (`write`) apply the change in place (work branch) instead of previewing. |
 | `--allow-dirty` | (`write`) allow running on a dirty tree (only matters with `--apply` / `--pr`). |
 | `--pr` | (`write`) push + open a PR instead of a local work branch (implies `--apply`). |
 | `--rating N` | (`feedback`) record a 1–5 quality rating for the work item. |
 | `--notes "..."` | (`feedback`) free-text notes stored with the rating. |
 | `--by NAME` | (`feedback`) who is grading (default: colleague's resolved identity). |
+| `--dry-run` | (`clean`) report what would be reaped without changing anything. |
+| `--json` | (any verb) machine-readable output: stdout carries **only** the result JSON, every diagnostic/digest line goes to stderr. |
 
 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.
+--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
 
@@ -140,6 +155,41 @@ The result printed to stdout is the work item's `TaskResult.summary` (plus
   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)
 
@@ -168,11 +218,20 @@ The result printed to stdout is the work item's `TaskResult.summary` (plus
   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 — `agentculture/colleague` is its
-origin. guildmaster **re-broadcasts** it to the mesh (the same inbound pattern as
-the devague-origin workflow skills), tracking it in `docs/skill-sources.md`. The
-`cite, don't import` policy holds: downstream repos copy it, they don't symlink
-or depend on it.
+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.

{guild_cli-0.22.0 → guild_cli-0.22.2}/.claude/skills/ask-colleague/prompts/explore.md

@@ -18,8 +18,18 @@ Rules:
   report (or you are within a few steps of the budget), STOP reading and call
   `finish`. Err on the side of finishing early — a focused finding beats endless
   reading.
+- For a WIDE codebase map (many folders/modules), do NOT read every file in series
+  — that exhausts the step budget. Partition the surface by folder and delegate the
+  per-folder sub-surveys to the `subagents` tool (one child per folder/subtree, each
+  returning its findings), then synthesize their results into your report.
+- NARRATE PROGRESS: with EVERY tool call, write one short line of plain text
+  first — what you just learned and what you are checking next. That line rides
+  the run's flight feed, so the operator can see where you are instead of a
+  silent turn. A long think with nothing written looks like a stall. If you are
+  within ~3 steps of the budget, STOP and write the answer-so-far (partial is
+  fine, mark it partial) rather than reading one more file.
 
 When you are done, call finish with a structured findings report:
 1. What it is / how it works (with file:line references).
 2. Notable details, edge cases, or surprises.
-3. Open questions or risks worth a closer look.
+3. Open questions or risks worth a closer look.

{guild_cli-0.22.0 → guild_cli-0.22.2}/.claude/skills/ask-colleague/prompts/review.md

@@ -5,13 +5,8 @@ Focus the review on:
 
 $ARGUMENTS
 
-The change under review is the committed diff on this branch versus its base
-(`$BASE`). Start by running, read-only:
-
-    git diff $BASE...HEAD --stat
-    git diff $BASE...HEAD
-
-then read the touched files for the context you need.
+The diff for this change is ALREADY PROVIDED below the instructions (filtered +
+capped). Read specific files only if you need more context.
 
 Rules:
 - READ-ONLY. Do NOT modify, create, or delete any file. Only read and run
@@ -29,8 +24,14 @@ Rules:
   NOTHING and wastes the entire drive — so the moment you have enough to write a
   useful review (or you are within a few steps of the budget), STOP reading and
   call `finish`. Err on the side of finishing early.
+- NARRATE PROGRESS: with EVERY tool call, write one short line of plain text
+  first — what you just learned and what you are checking next. That line rides
+  the run's flight feed, so the operator can see where you are instead of a
+  silent turn. A long think with nothing written looks like a stall. If you are
+  within ~3 steps of the budget, STOP and write the answer-so-far (partial is
+  fine, mark it partial) rather than reading one more file.
 
 When you are done, call finish with a structured review:
 1. Correctness risks / likely bugs (with file:line).
 2. Design, clarity, or maintainability concerns.
-3. Concrete, actionable suggestions (ranked; most important first).
+3. Concrete, actionable suggestions (ranked; most important first).

{guild_cli-0.22.0 → guild_cli-0.22.2}/.claude/skills/ask-colleague/prompts/write.md

@@ -10,6 +10,12 @@ Rules:
   text file with exactly one trailing newline.
 - You may read, create, modify files, and run commands as needed.
 - Don't widen the scope: do exactly what was asked, nothing more.
+- NARRATE PROGRESS: with EVERY tool call, write one short line of plain text
+  first — what you just learned and what you are checking next. That line rides
+  the run's flight feed, so the operator can see where you are instead of a
+  silent turn. A long think with nothing written looks like a stall. If you are
+  within ~3 steps of the budget, STOP and write the answer-so-far (partial is
+  fine, mark it partial) rather than reading one more file.
 
 When you are done, call finish with a short summary of exactly what you changed
-and why.
+and why.