microduck-cli 0.7.0__tar.gz

microduck_cli-0.7.0/.claude/skills/agent-config/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: agent-config
+description: >
+  Show a Culture agent's full configuration in one read-only view: its
+  system-prompt file (CLAUDE.md / AGENTS.md / GEMINI.md), the parallel
+  culture.yaml, and the agent's local .claude/skills index. Use when an
+  operator says "show agent <name>", "what does <agent> look like", or before
+  teaching/onboarding an agent and you need to see its current kit + config.
+  Backs the `guild show` verb. Vendored from steward (cite-don't-import);
+  inventory only — it reports, it does not judge alignment or drift.
+type: command
+---
+
+# agent-config — surface a Culture agent's config in one view
+
+guildmaster is the mesh's skills supplier and owns the **inventory** surfaces:
+"what kit + config does this agent have?" This skill answers exactly that for a
+single agent, showing the three artifacts that together define it:
+
+1. **System-prompt file** (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`) — the
+   prompt-side guidance for the agent's backend. The script detects which file
+   is present from a backend-fingerprint registry.
+2. **`culture.yaml`** — the runtime-side config (`agents:` list with `suffix`,
+   `backend`, `model`, `system_prompt`, `channels`, `tags`, `acp_command`,
+   `extras`). Lives parallel to the prompt file at the project root.
+3. **`.claude/skills/*/SKILL.md`** — the per-project skills the agent can
+   invoke, one line each (name + truncated description).
+
+This is the **inventory half** of the steward → guildmaster split
+([issue #12](https://github.com/agentculture/guildmaster/issues/12)): it reports
+the config, it does **not** interpret drift or judge alignment. The relationship
+graph and the "is this agent aligned?" judgment stay with `steward overview` /
+`steward doctor`.
+
+## When to use
+
+- Before `guild teach` / `guild onboard` — see an agent's current kit + config.
+- When an operator asks "show me agent `<name>`" or "what does `<agent>` run".
+- Read it, don't guess — before answering a question about what an agent does.
+
+## How to run
+
+One script, two ways to call it (or just run `guild show`, which wraps it):
+
+```bash
+# Path mode — point at any directory with a prompt file + culture.yaml
+.claude/skills/agent-config/scripts/show.sh ../culture
+
+# Suffix mode — resolve a registered agent suffix via the Culture server's
+# manifest (location set by culture_server_yaml in skills.local.yaml)
+.claude/skills/agent-config/scripts/show.sh daria
+```
+
+Output is three sections: the detected system-prompt file, `culture.yaml` (or
+`(missing)`), and a one-line summary per local skill (name + description,
+truncated to 120 chars).
+
+## What to look at in `culture.yaml`
+
+| Field | Why it matters |
+|-------|----------------|
+| `suffix` | Identifies the agent on the mesh. |
+| `backend` | One of `claude` / `codex` / `copilot` / `acp`. The all-backends rule means a feature in one must land in all four. |
+| `model` | Drift here changes behavior silently. |
+| `system_prompt` | Should not contradict the prompt file. |
+| `channels` | Where the agent listens. |
+| `tags`, `extras`, `acp_command` | Backend-specific. |
+
+## Notes
+
+- **Read-only.** The script never edits agent files. It reports; it does not
+  flag or fix drift — that judgment is steward's lane.
+- **Backend-aware.** Prompt-file detection comes from
+  `data/backend-fingerprints.yaml` (the `prompt:` mapping), falling back to the
+  built-in `(CLAUDE.md AGENTS.md GEMINI.md)` list if the registry is absent.
+- **Per-machine config.** Suffix mode reads `culture_server_yaml` from
+  `.claude/skills.local.yaml` (git-ignored), falling back to
+  `.claude/skills.local.yaml.example`.
+- **Vendored from steward** (`agent-config`). guildmaster owns this copy and may
+  diverge; re-sync from steward's canonical copy when it changes. Divergences:
+  the SKILL.md is reframed for guildmaster's inventory role and adds
+  `type: command` for the culture backend's skill loader.

microduck_cli-0.7.0/.claude/skills/agent-config/data/backend-fingerprints.yaml

@@ -0,0 +1,30 @@
+# Canonical backend fingerprint registry. Vendored from steward's agent-config
+# skill (cite-don't-import); guildmaster owns this copy. Read by the agent-config
+# show.sh (bash), which `guild show` shells out to. Upstream steward also reads
+# it from a Python detector; guildmaster has no parallel detector, so only the
+# `backends:` prompt mapping below is load-bearing here. Keep that mapping in
+# sync with upstream when re-syncing.
+#
+# `prompt`        — the backend's system-prompt filename at the repo root.
+# `steering`      — files/dirs distinctive enough to attribute to this backend.
+# `shared_steering` — files/dirs that belong to NO specific backend. A repo
+#                   declared as any backend may have these without triggering a
+#                   mismatch. `.agents` is a generic Culture agent-config
+#                   convention. `.claude/settings.json` and
+#                   `.claude/settings.local.json` are generic Claude Code
+#                   (editor/CLI) workspace config files — they appear in any
+#                   repo that uses Claude Code as the development tool,
+#                   regardless of the agent backend, so they must never be used
+#                   to infer the backend or flag a mismatch. The claude backend
+#                   is identified solely by its `CLAUDE.md` prompt file.
+#                   `.github/copilot-instructions.md` is generic GitHub Copilot
+#                   editor/IDE config — any repo may have it regardless of the
+#                   declared agent backend, so it must not trigger a mismatch.
+backends:
+  claude:  { prompt: CLAUDE.md, steering: [] }
+  codex:   { prompt: AGENTS.md, steering: [".codex"] }
+  acp:     { prompt: AGENTS.md, steering: [".kiro"] }
+  copilot: { prompt: AGENTS.md, steering: [] }
+  gemini:  { prompt: GEMINI.md, steering: [".gemini"] }
+shared_steering: [".agents", ".claude/settings.json", ".claude/settings.local.json", ".github/copilot-instructions.md"]
+prompt_fallback: AGENTS.md

microduck_cli-0.7.0/.claude/skills/agent-config/scripts/show.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Show a Culture agent's full configuration in one view:
+# the detected system-prompt file (CLAUDE.md / AGENTS.md / GEMINI.md), the
+# parallel culture.yaml, and the .claude/skills/ index.
+#
+# Usage: show.sh <path-or-agent-suffix>
+#
+# Path mode:   show.sh ../culture
+# Suffix mode: show.sh daria   (resolved via culture_server_yaml in skills.local.yaml)
+#
+# Exit codes:
+#   0   success
+#   1   environment error (missing manifest, missing PyYAML for suffix mode)
+#   2   user error (no target given, unknown suffix, target path doesn't exist)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$SKILL_DIR/../../.." && pwd)"
+
+CFG="$REPO_ROOT/.claude/skills.local.yaml"
+[ -f "$CFG" ] || CFG="$REPO_ROOT/.claude/skills.local.yaml.example"
+
+# Read a top-level YAML scalar from CFG. Schema is intentionally tiny:
+#   key: value     (with optional surrounding quotes / trailing comment)
+# No PyYAML dependency.
+read_cfg() {
+    awk -v key="$1" '
+        $0 ~ ("^" key ":[[:space:]]*") {
+            sub("^" key ":[[:space:]]*", "")
+            sub(/[[:space:]]*#.*$/, "")
+            sub(/^[[:space:]]+/, ""); sub(/[[:space:]]+$/, "")
+            sub(/^["\047]/, ""); sub(/["\047]$/, "")
+            print
+            exit
+        }
+    ' "$CFG"
+}
+
+target="${1:-}"
+if [ -z "$target" ]; then
+    echo "Usage: $(basename "$0") <path-or-agent-suffix>" >&2
+    exit 2
+fi
+
+if [ -d "$target" ]; then
+    DIR="$target"
+else
+    SERVER_YAML_RAW="$(read_cfg culture_server_yaml)"
+    SERVER_YAML="${SERVER_YAML_RAW/#\~/$HOME}"
+    if [ ! -f "$SERVER_YAML" ]; then
+        echo "no server manifest at $SERVER_YAML — set culture_server_yaml in $CFG" >&2
+        echo "or pass an explicit path instead of suffix '$target'" >&2
+        exit 1
+    fi
+    # Suffix mode parses Culture's server manifest, whose schema is dictated by
+    # Culture (not by us) and includes nested mappings — too rich for awk.
+    # We use python+PyYAML here, with a friendly install hint if it's missing.
+    if ! python3 -c 'import yaml' 2>/dev/null; then
+        echo "suffix mode needs Python + PyYAML to parse $SERVER_YAML" >&2
+        echo "  install: pip install --user pyyaml   (or: uv pip install pyyaml)" >&2
+        echo "  or pass an explicit path instead of suffix '$target'" >&2
+        exit 1
+    fi
+    # Use a dedicated exit code (2) for "unknown suffix" so the steward CLI
+    # wrapper can distinguish user errors (typo'd suffix) from env errors
+    # (missing manifest / PyYAML).
+    if ! DIR=$(python3 - "$SERVER_YAML" "$target" <<'PY'
+import sys, yaml, pathlib
+manifest_path, suffix = sys.argv[1], sys.argv[2]
+m = yaml.safe_load(pathlib.Path(manifest_path).read_text()) or {}
+agents = m.get('agents', {})
+entry = agents.get(suffix)
+if entry is None:
+    print(f"no agent registered with suffix {suffix!r} in {manifest_path}", file=sys.stderr)
+    sys.exit(2)
+print(entry['directory'] if isinstance(entry, dict) else entry)
+PY
+); then
+        exit 2
+    fi
+fi
+
+DIR="${DIR/#\~/$HOME}"
+
+# Recognized prompt filenames come from the shared registry (single source
+# of truth with the Python detector). Fall back to the built-in list if the
+# registry isn't present (e.g. skill vendored without the data file).
+REGISTRY="$SKILL_DIR/data/backend-fingerprints.yaml"
+prompt_files=()
+if [ -f "$REGISTRY" ]; then
+    while IFS= read -r pf; do
+        [ -n "$pf" ] && prompt_files+=("$pf")
+    done < <(grep -oE 'prompt:[[:space:]]*[^,}[:space:]]+' "$REGISTRY" | awk '{print $NF}' | sort -u)
+fi
+[ ${#prompt_files[@]} -eq 0 ] && prompt_files=(CLAUDE.md AGENTS.md GEMINI.md)
+
+shown=0
+for pf in "${prompt_files[@]}"; do
+    if [ -f "$DIR/$pf" ]; then
+        echo "=== $DIR/$pf ==="
+        cat "$DIR/$pf"
+        echo
+        shown=1
+    fi
+done
+if [ "$shown" -eq 0 ]; then
+    echo "=== $DIR (system prompt) ==="
+    echo "(no recognized prompt file: ${prompt_files[*]})"
+    echo
+fi
+echo "=== $DIR/culture.yaml ==="
+if [ -f "$DIR/culture.yaml" ]; then cat "$DIR/culture.yaml"; else echo "(missing)"; fi
+echo
+echo "=== $DIR/.claude/skills/ ==="
+found=0
+for s in "$DIR"/.claude/skills/*/SKILL.md; do
+    [ -f "$s" ] || continue
+    found=1
+    name=$(awk '/^name:/{print $2; exit}' "$s")
+    desc=$(awk '
+        /^description:/ {
+            sub(/^description:[[:space:]]*/, "")
+            buf = $0
+            flag = 1
+            next
+        }
+        flag && /^[a-z_-]+:/ { flag = 0 }
+        flag { buf = buf " " $0 }
+        END { gsub(/^[[:space:]]+|[[:space:]]+$/, "", buf); print buf }
+    ' "$s")
+    printf "  %-30s %s\n" "$name" "${desc:0:120}"
+done
+if [ "$found" -eq 0 ]; then
+    echo "  (no skills)"
+fi

microduck_cli-0.7.0/.claude/skills/ask-colleague/SKILL.md

@@ -0,0 +1,237 @@
+---
+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
+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. |
+| `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
+
+| 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`, `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. 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.

microduck_cli-0.7.0/.claude/skills/ask-colleague/prompts/explore.md

@@ -0,0 +1,35 @@
+You are a second, independent mind brought in for a fresh read of this repository.
+You are NOT the original author — your value is a different perspective, not authority.
+
+Investigate the following and report what you find:
+
+$ARGUMENTS
+
+Rules:
+- This is READ-ONLY. Use read_file, list_dir, and read-only run_command only
+  (e.g. `git log`, `git grep`, `ls`, `rg`). Do NOT create, modify, or delete any
+  file, and do NOT run any command that changes state.
+- Be concrete: cite file paths and line numbers; quote the key code you rely on.
+- Surface what's surprising, risky, or unclear — not just a tidy summary.
+- Search efficiently: don't repeat near-identical searches — once a search
+  points you at the relevant file, READ it instead of re-grepping for synonyms.
+- You have a limited step budget, and a report that never calls `finish` returns
+  NOTHING — wasting the whole drive. The moment you have enough to write a useful
+  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.

microduck_cli-0.7.0/.claude/skills/ask-colleague/prompts/review.md

@@ -0,0 +1,37 @@
+You are an independent reviewer — a different mind from whoever wrote this change.
+Your job is a candid second opinion, not a rubber stamp.
+
+Focus the review on:
+
+$ARGUMENTS
+
+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
+  read-only commands.
+- Review by READING, not by executing. Reason about correctness from the diff
+  and the source — do NOT try to import, build, install, or run the project to
+  "verify" behavior. The checkout may not be installed, and chasing that burns
+  your whole step budget for nothing.
+- Every command runs from the repository ROOT in a fresh shell, so `cd` has no
+  lasting effect and only wastes a step — never `cd`; use repo-relative paths
+  (`colleague/config.py`, not `/repo/...`).
+- Be terse and prioritized — lead with what actually matters. Don't pad.
+- Call out real problems; if it's genuinely fine, say so and say why.
+- You have a limited step budget. A review that never calls `finish` returns
+  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).

microduck_cli-0.7.0/.claude/skills/ask-colleague/prompts/write.md

@@ -0,0 +1,21 @@
+$ARGUMENTS
+
+Implement the task above in this repository.
+
+Rules:
+- Make the SMALLEST change that correctly satisfies the task.
+- Follow the repository's existing patterns, style, and conventions — read the
+  neighbouring files first so your change reads like the surrounding code.
+- Keep edits lint-clean: respect the project's maximum line length and end every
+  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.