playmaker-cli 0.7.2__tar.gz → 0.9.0__tar.gz

{playmaker_cli-0.7.2 → playmaker_cli-0.9.0}/.gitignore

@@ -10,3 +10,5 @@ dist/
 build/
 .claude/
 .smoke/
+# review-board.sh writes its patches, prompts and verdicts here
+.playmaker/

{playmaker_cli-0.7.2 → playmaker_cli-0.9.0}/CHANGELOG.md

@@ -5,6 +5,87 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-08-24
+
+### Added
+
+- **`playmaker quotas` keeps itself fresh.** The snapshot in `quotas.json` is
+  re-probed automatically once it is older than `[quotas] max_age` (default
+  5m), and the header now prints how old the numbers are. A stale table was
+  worse than no table: the coach quotes it when it decides where to send work,
+  and nothing warned that "62% left" was four days old. `--refresh` still
+  probes on demand and `--cached` prints the stored snapshot without probing.
+
+- **`skill install` copies the whole skill directory.** The bundled skill has
+  outgrown a single file — `references/` the coach reads on demand, `scripts/`
+  it runs — and install only ever copied `SKILL.md`, so none of that reached
+  `~/.claude/skills`. It now walks the bundle, keeps the executable bit on
+  scripts, and deletes nothing the bundle does not own, so `--force` is an
+  upgrade rather than a reset of whatever you keep alongside it.
+
+- **The coach skill is a protocol plus references, and it ships a review board.**
+  `SKILL.md` was a 315-line monolith that cost 35 KB of context to activate,
+  which is its own argument against activating it. It is now a ~200-line
+  protocol, with the lanes, quota rules, per-agent traps, prompt templates and
+  command surface moved into `references/` and read on demand.
+
+- **`scripts/review-board.sh` — automatic multi-agent review of a work package.**
+  It snapshots the WP's diff, builds one refute-the-implementation prompt per
+  reviewer (distinct lens each: correctness, contracts, risk, conventions),
+  dispatches them `--read-only` under a single `--batch`, and collects their
+  verdicts as JSON with `--collect`. The roster comes from
+  `.playmaker/reviewers.conf` (repo) or `~/.playmaker/reviewers.conf` (global),
+  keyed by risk class, so which lanes review what is configuration rather than
+  something the coach improvises each round. The implementing lane is excluded
+  with `--impl-agent`.
+
+- **Policy overlay.** The coach reads `./.playmaker/policy.md` then
+  `~/.playmaker/policy.md` before planning, and lets them override the skill's
+  defaults — which quotas to spare, which lanes are contended, what juniors may
+  never touch in this repo, which commands are the acceptance gates. Personal
+  routing rules used to survive only as local edits to the installed
+  `SKILL.md`, which made upgrading the bundled skill destructive.
+
+- **Write-task no-change detection.** Every dispatch and continuation now takes
+  a before/after working-tree snapshot: git directories compare porcelain
+  state plus `HEAD`, while ordinary directories use a bounded mtime walk. A
+  successful write task that changed zero paths is stored as `no_changes`,
+  with the count and snapshot hashes available from `get`/`summary` and JSON.
+  `--expect-changes` forces the check; `--read-only` suppresses it for recon
+  and answer-only work.
+
+### Changed
+
+- **The skill's activation threshold is much lower.** It used to require 3+
+  independent work-streams and a >2x parallel speedup, which read as "not this
+  task" for most real requests; it now activates on any code change spanning
+  more than one file, anything that deserves an independent review pass, or any
+  request with two parallelizable parts — a single reviewed work package is an
+  expected shape, not overhead.
+
+- **`no_changes` is terminal but not success.** It appears as a warning in
+  watch and list filtering, pings immediately with the failure sound even in
+  a batch, and makes the batch report its agent as `⚠ no_changes` rather than
+  counting it among the completed workers.
+
+- **`summary --json` now wraps turns in `summary`.** Snapshot diagnostics share
+  the object with the former bare turn list, so JSON consumers should read
+  `summary` for the messages.
+
+## [0.8.0] - 2026-08-18
+
+### Added
+
+- **Ollama in the quota table.** `playmaker quotas` now carries an `ollama`
+  provider for work dispatched through `opencode -m ollama/<tag>`. It is an
+  availability signal rather than a quota: `ok` at 100% with the pulled chat
+  models listed when the daemon is up and a completion-capable model is
+  present; `unsupported` — naming the exact `ollama pull` to run — when Ollama
+  is down or holds only embedding models, so an idle daemon with
+  `nomic-embed-text` never reads as free 27B capacity. Models are classified by
+  `/api/show` `capabilities`, not by name. The renderer for the provider
+  shipped in 0.7.2 ahead of the probe.
+
 ## [0.7.2] - 2026-08-18
 
 ### Fixed

{playmaker_cli-0.7.2 → playmaker_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: playmaker-cli
-Version: 0.7.2
+Version: 0.9.0
 Summary: Playing-coach CLI for orchestrating Claude Code, Codex, Antigravity and opencode sub-agents in parallel.
 Project-URL: Homepage, https://github.com/vladsafedev/playmaker
 Project-URL: Repository, https://github.com/vladsafedev/playmaker
@@ -196,12 +196,45 @@ reviewing it is cheap — lives in
 that ships with the package:
 
 ```bash
-playmaker skill install     # ~/.claude/skills/playmaker-coach/SKILL.md
+playmaker skill install     # ~/.claude/skills/playmaker-coach/
 ```
 
-Then give any Claude Code session a multi-component task and it activates:
-proposes a split with per-model quota rationale, waits for your approval, fans
-out, and reviews what comes back.
+Then give any Claude Code session a task that changes code and it activates:
+proposes a split into work packages with per-model quota rationale, waits for
+your approval, fans out, and — this is the second half of the loop — puts every
+resulting diff through a **review board** before it lands.
+
+The skill installs as a directory: `SKILL.md` is the protocol, `references/`
+holds the parts the coach loads on demand, and `scripts/review-board.sh` is the
+review fan-out.
+
+### The review board
+
+Reviewing a diff carefully is the most expensive thing a coach can do with its
+own context, and it has an objective output — findings with evidence. So it is
+delegated too. One command snapshots the work package's diff, hands it to
+independent reviewer agents on different lanes (each with a distinct lens:
+correctness, contracts, risk, conventions), and asks each to *refute* the
+implementation against its acceptance criteria:
+
+```bash
+review-board.sh <wp> <base-ref> --risk normal --gate "npm run typecheck" --impl-agent codex
+review-board.sh --collect <wp>
+```
+
+Reviewers run `--read-only` and return a fixed JSON verdict — severity, file,
+line, and a concrete failure scenario per finding. The coach reads verdicts
+rather than code, arbitrates, and sends a numbered fix list back into the
+implementer's live session with `playmaker continue`. Which lanes review which
+risk class is configuration, in `.playmaker/reviewers.conf`.
+
+### Policy lives outside the skill
+
+Before planning, the coach reads `./.playmaker/policy.md` (repo) and
+`~/.playmaker/policy.md` (personal) and lets them override the skill's defaults
+— which quotas to spare, which lanes are contended, what juniors may never
+touch in this repo, which commands are the acceptance gates. Keep your own
+rules there and `playmaker skill install --force` stays a safe upgrade.
 
 ## Commands
 
@@ -213,13 +246,14 @@ playmaker dispatch <agent> --prompt "..."     # detached by default
                   [--model NAME]              # forwarded to the agent's own CLI
                   [--cwd DIR]
                   [--files PATH...]
+                  [--expect-changes|--read-only]
                   [--sync]                    # block and print the final answer
                   [--parent ID]               # link lineage to an earlier session
                   [--batch LABEL]             # group a fan-out; one summary ping
 playmaker continue <id> --prompt "..."        # follow-up inside the live session
-                  [--model NAME] [--files PATH...] [--sync]
+                  [--model NAME] [--files PATH...] [--expect-changes|--read-only] [--sync]
 
-playmaker list [--status running|done|failed] [--agent NAME] [--limit N]
+playmaker list [--status running|done|failed|no_changes] [--agent NAME] [--limit N]
 playmaker get <id> [--wait] [--poll SECONDS]
 playmaker summary <id>                        # last 2 assistant messages
 playmaker thread <id> [--last N] [--all] [--role assistant|user|tool]
@@ -233,6 +267,10 @@ playmaker skill install [--dir PATH] [--force]
 `dispatch`, `continue`, `list`, `get`, `thread` and `quotas` all take `--json`
 for scripting.
 
+Write-shaped prompts are checked for file changes at completion. A zero-change
+write task becomes `no_changes`; use `--read-only` for recon or answer-only
+work, or `--expect-changes` to force the check for an otherwise ambiguous prompt.
+
 **`continue` vs a fresh `dispatch`.** `continue` sends a follow-up into the
 agent's existing session, so its reasoning, tool history and file context are
 still live — that's the cheap path for "almost right, fix Y". Start fresh with

{playmaker_cli-0.7.2 → playmaker_cli-0.9.0}/README.md

@@ -169,12 +169,45 @@ reviewing it is cheap — lives in
 that ships with the package:
 
 ```bash
-playmaker skill install     # ~/.claude/skills/playmaker-coach/SKILL.md
+playmaker skill install     # ~/.claude/skills/playmaker-coach/
 ```
 
-Then give any Claude Code session a multi-component task and it activates:
-proposes a split with per-model quota rationale, waits for your approval, fans
-out, and reviews what comes back.
+Then give any Claude Code session a task that changes code and it activates:
+proposes a split into work packages with per-model quota rationale, waits for
+your approval, fans out, and — this is the second half of the loop — puts every
+resulting diff through a **review board** before it lands.
+
+The skill installs as a directory: `SKILL.md` is the protocol, `references/`
+holds the parts the coach loads on demand, and `scripts/review-board.sh` is the
+review fan-out.
+
+### The review board
+
+Reviewing a diff carefully is the most expensive thing a coach can do with its
+own context, and it has an objective output — findings with evidence. So it is
+delegated too. One command snapshots the work package's diff, hands it to
+independent reviewer agents on different lanes (each with a distinct lens:
+correctness, contracts, risk, conventions), and asks each to *refute* the
+implementation against its acceptance criteria:
+
+```bash
+review-board.sh <wp> <base-ref> --risk normal --gate "npm run typecheck" --impl-agent codex
+review-board.sh --collect <wp>
+```
+
+Reviewers run `--read-only` and return a fixed JSON verdict — severity, file,
+line, and a concrete failure scenario per finding. The coach reads verdicts
+rather than code, arbitrates, and sends a numbered fix list back into the
+implementer's live session with `playmaker continue`. Which lanes review which
+risk class is configuration, in `.playmaker/reviewers.conf`.
+
+### Policy lives outside the skill
+
+Before planning, the coach reads `./.playmaker/policy.md` (repo) and
+`~/.playmaker/policy.md` (personal) and lets them override the skill's defaults
+— which quotas to spare, which lanes are contended, what juniors may never
+touch in this repo, which commands are the acceptance gates. Keep your own
+rules there and `playmaker skill install --force` stays a safe upgrade.
 
 ## Commands
 
@@ -186,13 +219,14 @@ playmaker dispatch <agent> --prompt "..."     # detached by default
                   [--model NAME]              # forwarded to the agent's own CLI
                   [--cwd DIR]
                   [--files PATH...]
+                  [--expect-changes|--read-only]
                   [--sync]                    # block and print the final answer
                   [--parent ID]               # link lineage to an earlier session
                   [--batch LABEL]             # group a fan-out; one summary ping
 playmaker continue <id> --prompt "..."        # follow-up inside the live session
-                  [--model NAME] [--files PATH...] [--sync]
+                  [--model NAME] [--files PATH...] [--expect-changes|--read-only] [--sync]
 
-playmaker list [--status running|done|failed] [--agent NAME] [--limit N]
+playmaker list [--status running|done|failed|no_changes] [--agent NAME] [--limit N]
 playmaker get <id> [--wait] [--poll SECONDS]
 playmaker summary <id>                        # last 2 assistant messages
 playmaker thread <id> [--last N] [--all] [--role assistant|user|tool]
@@ -206,6 +240,10 @@ playmaker skill install [--dir PATH] [--force]
 `dispatch`, `continue`, `list`, `get`, `thread` and `quotas` all take `--json`
 for scripting.
 
+Write-shaped prompts are checked for file changes at completion. A zero-change
+write task becomes `no_changes`; use `--read-only` for recon or answer-only
+work, or `--expect-changes` to force the check for an otherwise ambiguous prompt.
+
 **`continue` vs a fresh `dispatch`.** `continue` sends a follow-up into the
 agent's existing session, so its reasoning, tool history and file context are
 still live — that's the cheap path for "almost right, fix Y". Start fresh with

{playmaker_cli-0.7.2 → playmaker_cli-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "playmaker-cli"
-version = "0.7.2"
+version = "0.9.0"
 description = "Playing-coach CLI for orchestrating Claude Code, Codex, Antigravity and opencode sub-agents in parallel."
 readme = "README.md"
 requires-python = ">=3.11"

playmaker_cli-0.9.0/skills/playmaker-coach/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: playmaker-coach
+description: Team-lead mode for coding work. Decompose the task into work packages, dispatch them to Claude/Codex/Antigravity(agy)/opencode workers through the `playmaker` CLI, then run an automatic multi-agent review board over every diff before it lands, and drive the fix cycles. Use for ANY request that will change code in more than one place, needs an independent review pass, or has two or more parts that can run at once — "implement", "add", "fix", "refactor", "wire up", "сделай", "почини", "добавь", "реализуй", "собери". NOT for answering a question, reading or explaining code, a single-line edit, or a git/ops command.
+---
+
+# playmaker-coach — you are the tech lead, not the typist
+
+`playmaker` dispatches sub-tasks to Codex / Antigravity (`agy`) / opencode / a sibling Claude,
+tracks them, and returns their threads. This skill is the judgment on top: what to split,
+who gets which slice, how to size it so verifying is cheap, and **how the review board runs**.
+
+**The coach produces plans, prompts, verdicts and integration — not feature diffs.** Your context
+window is the most expensive resource on the table. Every file you read yourself and every line you
+type yourself is one a cheaper worker could have produced. Push out implementation, recon,
+summarization, and even the drafting of worker prompts when the task is big enough.
+
+Two loops run under your hand, always both:
+
+```
+decompose → dispatch → prove on disk → REVIEW BOARD → adjudicate → continue → land
+                                            ↑______________________|
+                                                 max 2 cycles
+```
+
+## 1. Activation gate
+
+Run this gate on every request that touches code. It has three questions:
+
+1. **Will this change code in more than one file, or in one file in a way that deserves a second pair of eyes?**
+2. **Are there ≥2 slices that could run at the same time** (backend + frontend, code + tests, two modules)?
+3. **Is there a durable artefact** (a diff someone will have to live with), as opposed to an answer?
+
+**Any "yes" → activate.** The default is delegation; doing it yourself is the exception you justify.
+
+**Skip the skill** only for: a question, an explanation, reading/searching code, a one-line or
+one-symbol edit, a git/ops command, or a task the user explicitly asked you to do by hand
+("сам", "solo", "не делегируй", "just do it yourself").
+
+Borderline single-WP tasks still activate — with **one** worker and the review board. The board is
+the point: a single reviewed WP is a legitimate, common shape, not overhead.
+
+## 2. Load policy before planning
+
+Defaults in this file are the *mechanism*. The *policy* — which quota to spare, which lanes are
+contended, what this repo forbids juniors to touch, which commands are the objective gates — lives
+outside the skill so it survives `playmaker skill install --force`. Read, in this order, and let
+later files override earlier ones:
+
+```bash
+cat ./.playmaker/policy.md      2>/dev/null   # repo policy (gates, protected paths, conventions)
+cat ~/.playmaker/policy.md      2>/dev/null   # personal policy (quota economics, lane defaults)
+ls  ./.playmaker/agents/*.md    2>/dev/null || ls ~/.playmaker/agents/*.md 2>/dev/null
+```
+
+Agent profiles describe each lane's strengths, ceiling, and quota position — trust a profile over
+the generic defaults here. If no policy file exists, say so once in the plan and use these defaults.
+
+## 3. Protocol
+
+### 3.1 Recon — delegate it
+
+Codebase exploration is the highest-leverage thing to delegate: raw reading is exactly what the
+cheapest model does as well as you do. Before your own `grep`/`Read` sweep, dispatch a read-only
+recon with an explicit deliverable and `--sync`, and read a 200-word report instead of ten files:
+
+```bash
+playmaker dispatch agy --model <cheap-tier> --cwd "$(pwd)" --sync --read-only \
+  --prompt "Recon only — change nothing. Locate (a) …, (b) …, (c) …. Report under 200 words as a numbered list with file paths and line ranges."
+```
+
+Skip it for one-file, one-symbol lookups — just `Grep`.
+
+### 3.2 Quotas
+
+```bash
+playmaker quotas               # capacity per MODEL, not per agent; re-probes itself when stale
+```
+
+Read at model granularity: separate buckets inside one provider are separate capacity. The aim is
+**level-loading** — finish the week with every pool drawn down evenly, except the one reserved for
+the coach — not hoarding the pools other people also use. Details and per-provider quirks:
+`references/quotas.md`.
+
+### 3.3 Decompose into work packages
+
+2–5 WPs on the first pass. A WP is dispatchable only when all five hold — this is what makes review
+cheap and re-prompting rare:
+
+1. **Hard file boundary.** "Edit only `x.ts` and its spec" — never "do the backend part".
+2. **A gate the worker runs itself** — `tsc --noEmit`, a named spec file, a lint pass. It must exit 0
+   before the worker reports done, and its output goes in the final answer.
+3. **A one-sentence done-condition** you can confirm in seconds. Can't write it? The WP isn't sized
+   yet — split or specify first.
+4. **The context it lacks** pasted in: the spec excerpt, the neighbouring file to mirror, exact paths
+   of any notes worth reading.
+5. **Match to the lane's ceiling.** Pattern-following inside a tight scope → juniors. Architectural
+   judgment, cross-module integration, spec interpretation → senior lane or you.
+
+Smell test before dispatching: *"if this comes back done, do I verify it by running one command and
+reading one paragraph — or by reading the whole diff and thinking hard?"* If the latter, re-scope.
+
+Lane and tier selection: `references/lanes.md`. Risk classes and what juniors may never touch: repo
+policy first, then `references/lanes.md`.
+
+### 3.4 Propose, then wait
+
+Post the plan as: WP → lane+model → why → gate → done-condition, plus the reviewer pair per WP and
+the current per-model capacity. **Dispatch nothing until the user approves.** Approval may be
+partial ("go but reroute tests"); restate the modified plan in one line, then dispatch.
+
+### 3.5 Dispatch
+
+```bash
+B=<short-batch-label>
+playmaker dispatch <agent> --model <name> --batch "$B" --cwd "$(pwd)" --prompt "<WP prompt>"
+```
+
+Detached by default — that is the point; never `--sync` a whole fan-out. Always pass `--cwd`,
+`--batch` (one summary ping for the batch), and `--model` unless the profile says otherwise.
+Prompt shape: `references/prompt-templates.md`. Per-agent traps (agy scratch dir, opencode relative
+paths, codex model roster): `references/agent-gotchas.md`.
+
+Parallel WPs that touch the same files go in **git worktrees**, one per WP, or they will collide.
+
+### 3.6 Prove it on disk before you believe it
+
+`done` means "the process exited cleanly with text", not "code changed". playmaker ≥0.9 marks a
+zero-change write task `no_changes` — treat it exactly as a failure. On older builds, check yourself:
+
+```bash
+git -C "<cwd>" status --short        # empty tree on a write WP = NOT done
+```
+
+Then run the WP's own gate yourself, once, cheaply. A WP that fails its gate never reaches the
+review board — it goes straight back to the worker.
+
+### 3.7 Review board — the mandatory second loop
+
+**Every WP that changes code gets reviewed by agents, not by you reading the diff.** You read
+verdicts, not code. Composition, prompts, the verdict contract and the cycle rules are in
+`references/review-board.md`; the fan-out itself is one command:
+
+```bash
+pm-review <wp-label> <base-ref> [--risk routine|normal|high] --gate "<cmd>" --impl-agent <lane>
+pm-review --collect <wp-label>          # once the review batch drains
+```
+
+(`pm-review` is `scripts/review-board.sh` from this skill; without the shortcut on `PATH`, call
+`~/.claude/skills/playmaker-coach/scripts/review-board.sh` directly.)
+
+Non-negotiables:
+
+- **The implementer never reviews its own WP**, and reviewers do not see each other's verdicts.
+- Reviewers are **`--read-only`** and prompted to **refute** the WP against its acceptance criteria,
+  not to summarize it.
+- Every finding carries `file:line` + a concrete failure scenario. **No evidence → dropped.** You
+  arbitrate, and a reviewer's confidence is an input, not a verdict.
+- Fixes go back via `playmaker continue <impl-id>` as a numbered list — the worker still has its
+  context. Re-review runs on the **delta only**.
+- **Two cycles maximum.** Still blocking after two → stop and escalate to the user with both
+  verdicts. A third round at the same lane is the most expensive way to use a cheap model.
+- Land only at **zero blocking findings**.
+
+### 3.8 Keep a board file
+
+Long fan-outs outlive your context. Maintain `./.playmaker/board.md` — one row per WP:
+
+```
+| WP | lane/model | impl id | gate | reviewers (ids) | verdict | cycle | state |
+```
+
+Update it at dispatch, at gate, after each review round. On resume, read the board before anything
+else. It is also what you paste back to the user as the status report.
+
+### 3.9 Failures
+
+Surface them; never silently retry. A failed dispatch (missing binary, bad auth, rejected model)
+gets a re-routed plan proposed to the user, not a second attempt at the same string. Diagnosis per
+agent: `references/agent-gotchas.md`.
+
+## 4. What the coach may still type by hand
+
+Allowed: integration glue between WPs, conflict resolution, config/one-liners smaller than the
+prompt that would describe them, and the final commit. Everything else — including "it's faster if
+I just do it" — is the anti-pattern this skill exists to kill. If you catch yourself opening an
+editor on product code, ask whether that is a WP you failed to write.
+
+## 5. Reference index
+
+| File | Read it when |
+|---|---|
+| `references/lanes.md` | choosing an agent/model, junior-vs-senior routing, escalation |
+| `references/review-board.md` | any review round — composition, prompts, verdict contract, cycles |
+| `references/prompt-templates.md` | writing a WP, reviewer, or follow-up prompt |
+| `references/quotas.md` | reading `playmaker quotas`, per-provider bucket structure |
+| `references/agent-gotchas.md` | a dispatch behaved strangely, or before a first dispatch to a lane |
+| `references/commands.md` | exact CLI surface and flags |
+
+## 6. Anti-patterns
+
+- **Doing the work "because it's faster".** It isn't, once review is counted — and it burns the
+  scarcest bucket in the room.
+- **Skipping the review board on a small WP.** Small WPs are where unreviewed bugs hide; the board
+  costs one command.
+- **Reading diffs instead of verdicts.** Reviewers exist to keep the diff out of your context.
+- **Reviewing with the implementer's own lane**, or letting reviewers see each other's output.
+- **Trusting `done`** without a disk check and a gate.
+- **A third fix cycle.** Escalate instead.
+- **Dispatching a WP you cannot verify in one command and one paragraph.**
+- **Omitting `--model`** and letting a CLI default drain a top-tier bucket.
+- **Reading whole agent threads** when `summary` answers the question.

playmaker_cli-0.9.0/skills/playmaker-coach/references/agent-gotchas.md

@@ -0,0 +1,73 @@
+# Per-agent traps
+
+Read the entry for a lane before your first dispatch to it in a session, and whenever a dispatch
+behaves strangely.
+
+## Universal: proof on disk, not status
+
+`playmaker` marks a session `done` when the process exits cleanly with text output. On builds with
+the no-change check, a write task that touched nothing lands as **`no_changes`** — terminal, but not
+success: it pings immediately even inside a batch and is excluded from the batch's completed count.
+On older builds, check it yourself after every write task:
+
+```bash
+git -C "<cwd>" status --short      # empty tree on a write WP = NOT done
+```
+
+Batch summaries (`N/N done`) are transport truth, not result truth. Treat an empty tree exactly like
+a failure: read `summary`, then decide `continue` versus a re-dispatch to another lane.
+
+## Bad `--model` is the classic silent failure
+
+playmaker catches both known shapes — a codex model/auth failure raises `codex turn failed: …`, and
+an unknown agy model raises with the valid roster *before* dispatch. So a dispatch that comes back
+failed with a model message means: fix the string, do not retry it. For agy and opencode, copy the
+line from `agy models` / `opencode models` rather than typing it.
+
+## claude (sibling)
+
+- Runs with `--permission-mode acceptEdits`: it edits and runs commands freely **inside `--cwd`** and
+  is refused outside it. A WP that legitimately needs a sibling repo or a dotfile in `$HOME` comes
+  back refused — the fix is a different `--cwd`, not a re-prompt.
+- Zero changes usually means one of: it tried to write outside `--cwd`, or the run needed a
+  permission the configured mode does not grant (an "I need your permission" answer, not a crash).
+- Default `--model sonnet`; omitting `--model` can put mid-tier work on the scarce top bucket.
+
+## agy (Antigravity)
+
+- The agent's shell lives in a **private scratch directory**, not the workspace. playmaker prepends a
+  workspace preamble, but reinforce it: phrase file instructions as workspace-relative or absolute
+  paths, **never "the current directory"**.
+- A `done` with no file changes usually means the files landed in agy's scratch dir
+  (`~/.gemini/antigravity-cli/scratch/`). Re-dispatch with explicit paths.
+- Its own default model is top tier, so **always pass `--model`** on a dispatch meant to be cheap.
+- Its **5-hour** windows are what a fan-out drains first; the Gemini family and the Claude/GPT family
+  have separate ones.
+
+## codex
+
+- The model roster depends on the account plan, and an unavailable name fails the whole dispatch.
+  **Omitting `--model` is the safe default here** — it uses whatever the account actually has.
+
+## opencode
+
+- Models are `provider/model` and the default is invisible: without `--model` it falls through to
+  opencode's own last interactive pick, which is not written to its config file. Pin
+  `[agents.opencode] model` in `~/.playmaker/config.toml`, or pass `--model` every time.
+- **GLM drops the leading `/` of absolute paths.** `/tmp/x/hello.txt` becomes `tmp/x/hello.txt` and
+  lands under `<cwd>/tmp/x/…`, while the agent reports "Wrote file successfully". So: never put an
+  absolute path in an opencode prompt, open with *"Working directory is the repo root; use paths
+  RELATIVE to it for every file operation, never absolute"*, still pass `--cwd`, and after `done`
+  check for a directory named after the cwd's own path components (`<cwd>/Users/…`, `<cwd>/private/…`)
+  — that is where the writes went.
+- Second failure mode: on a large task it may produce ten minutes of good analysis and exit `done`
+  with zero writes. Size opencode write tasks to roughly 100 lines of output or split them.
+- Neither trap applies to **review** dispatches, which write nothing — which makes opencode a
+  perfectly good reviewer even where it is a shaky implementer.
+
+## Worktrees
+
+Parallel WPs that touch the same files collide. Give each its own git worktree and dispatch with
+`--cwd <worktree>`. In JS monorepos remember the worktree needs its `node_modules` (symlink the
+store and repoint workspace packages) or the WP's gate silently cannot run — and a gate that cannot
+run is a WP that was never verified.

playmaker_cli-0.9.0/skills/playmaker-coach/references/commands.md

@@ -0,0 +1,42 @@
+# Command surface
+
+```
+playmaker agents                                # who is installed and reachable
+playmaker quotas [--refresh]                    # capacity, per provider and per model
+playmaker dispatch <agent> --prompt "..."       # detached by default
+                  [--model NAME] [--cwd DIR] [--files PATH...]
+                  [--batch LABEL]               # group a fan-out into one summary ping
+                  [--parent ID]                 # link lineage to an earlier session
+                  [--read-only|--expect-changes]
+                  [--sync]                      # block and print the final answer
+playmaker continue <id> --prompt "..."          # follow-up inside the live session
+                  [--model NAME] [--files ...] [--read-only|--expect-changes] [--sync]
+playmaker list [--status running|done|failed|no_changes] [--agent NAME] [--limit N]
+playmaker get <id> [--wait] [--poll SECONDS]
+playmaker summary <id>                          # last 2 assistant messages
+playmaker thread <id> [--last N] [--all] [--role assistant|user|tool]
+                     [--include-tools] [--max-bytes N] [--follow]
+playmaker logs <id> [--follow]                  # subprocess stdout for detached runs
+playmaker kill <id>
+playmaker watch                                 # live TUI
+playmaker skill install [--dir PATH] [--force]
+```
+
+Every command takes `--json`.
+
+- `--model` is forwarded verbatim to the agent's own CLI and stored on the session row, so
+  `continue` and detached re-runs inherit it; `continue --model X` overrides one turn.
+- `--batch LABEL` on every dispatch of one fan-out suppresses per-agent success pings and fires a
+  single "N/N done" summary when the batch drains. Failures still ping immediately.
+- `--read-only` marks recon and review dispatches so the zero-change check does not flag them;
+  `--expect-changes` forces the check on an ambiguous write prompt.
+- `continue` beats a fresh `dispatch` for "almost right, fix Y" — the session still holds the
+  worker's reasoning, tool history and file context. Start fresh with `--parent <id>` only when that
+  context has become a liability (requirements moved, the worker is looping).
+
+## Reading discipline
+
+`summary` first — it usually answers "is it done and what does it claim". Escalate to
+`thread <id> --last N` only when summary is insufficient, and to `--all --include-tools` only when
+actively debugging why a worker went sideways. A long thread is tens of thousands of tokens;
+`--max-bytes` is a safety cap, not a substitute for deciding what you need first.