workledger-cli 0.6.1__tar.gz → 0.8.0__tar.gz

{workledger_cli-0.6.1 → workledger_cli-0.8.0}/.claude/skills/ask-colleague/SKILL.md

@@ -27,7 +27,7 @@ description: >
 # 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
@@ -101,7 +101,9 @@ else an install hint.
 | `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
@@ -111,9 +113,13 @@ 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`). |
@@ -155,6 +161,24 @@ keeping stdout valid JSON for a machine consumer while diagnostics stay on stder
   (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
@@ -207,7 +231,7 @@ stop requests take effect on the next iteration rather than interrupting mid-ste
 
 ## Provenance
 
-This is a **first-party** colleague skill — colleague is its origin. It is
-the inverse of the other skills under `.claude/skills/`, which workledger-cli
-vendors *from* guildmaster. See `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.

{workledger_cli-0.6.1 → workledger_cli-0.8.0}/.claude/skills/ask-colleague/prompts/explore.md

@@ -18,6 +18,16 @@ 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).

{workledger_cli-0.6.1 → workledger_cli-0.8.0}/.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,6 +24,12 @@ 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).

{workledger_cli-0.6.1 → workledger_cli-0.8.0}/.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.