pilot-workers 0.5.3__tar.gz → 0.5.4__tar.gz

{pilot_workers-0.5.3/src/pilot_workers.egg-info → pilot_workers-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pilot-workers
-Version: 0.5.3
+Version: 0.5.4
 Summary: Dispatch bounded tasks to isolated LLM workers (GLM, Kimi, and more)
 License-Expression: MIT
 Requires-Python: >=3.11
@@ -119,12 +119,12 @@ Reserved keys (cannot be used as provider key): `runner`, `all`, `on`, `for`, `k
 
 ## Host integration
 
-The **host** is whatever AI agent acts as the planner. Each host ships ONE `pilot-workers` playbook skill (a doctrine playbook, not provider-specific syntax):
+The **host** is whatever AI agent acts as the planner. Each host ships ONE `pilot-workers` playbook skill (a doctrine playbook, not provider-specific syntax) — a core `SKILL.md` plus five on-demand `modes/<mode>.md` playbooks, so triggering loads the core only and mode craft is read per dispatch:
 
 - **`claude-host/skills/pilot-workers/`**: playbook skill for Claude Code (installed to `~/.claude/skills/pilot-workers/`)
 - **`codex-host/skills/pilot-workers/`**: the same playbook skill for Codex (installed to `$CODEX_HOME/skills/pilot-workers/`)
 
-`pilot-workers install <provider> on <host>` copies the skill into the host's skill directory and regenerates its worker table from that host's configuration; the doctrine itself carries no engine-specific knowledge. Removing the last provider deletes the skill, so a host with nothing configured has none and the planner does the work itself. (The v0.4.0 12-agents + 8-commands matrix is gone.)
+`pilot-workers install <provider> on <host>` copies the skill into the host's skill directory and regenerates its worker table from that host's configuration; the doctrine itself carries no engine-specific knowledge. The deployed tree is a build artifact — every install re-renders it from the packaged template, so upgrading is `pip` upgrade + `pilot-workers install <host|all>` (hosts with nothing configured are untouched). Removing the last provider deletes the skill, so a host with nothing configured has none and the planner does the work itself. (The v0.4.0 12-agents + 8-commands matrix is gone.)
 
 Adding a new host: create `integrations/<name>-host/skills/pilot-workers/`, put whatever config your host needs, point it at `pilot-workers dispatch`. See `integrations/README.md`.
 

{pilot_workers-0.5.3 → pilot_workers-0.5.4}/README.md

@@ -104,12 +104,12 @@ Reserved keys (cannot be used as provider key): `runner`, `all`, `on`, `for`, `k
 
 ## Host integration
 
-The **host** is whatever AI agent acts as the planner. Each host ships ONE `pilot-workers` playbook skill (a doctrine playbook, not provider-specific syntax):
+The **host** is whatever AI agent acts as the planner. Each host ships ONE `pilot-workers` playbook skill (a doctrine playbook, not provider-specific syntax) — a core `SKILL.md` plus five on-demand `modes/<mode>.md` playbooks, so triggering loads the core only and mode craft is read per dispatch:
 
 - **`claude-host/skills/pilot-workers/`**: playbook skill for Claude Code (installed to `~/.claude/skills/pilot-workers/`)
 - **`codex-host/skills/pilot-workers/`**: the same playbook skill for Codex (installed to `$CODEX_HOME/skills/pilot-workers/`)
 
-`pilot-workers install <provider> on <host>` copies the skill into the host's skill directory and regenerates its worker table from that host's configuration; the doctrine itself carries no engine-specific knowledge. Removing the last provider deletes the skill, so a host with nothing configured has none and the planner does the work itself. (The v0.4.0 12-agents + 8-commands matrix is gone.)
+`pilot-workers install <provider> on <host>` copies the skill into the host's skill directory and regenerates its worker table from that host's configuration; the doctrine itself carries no engine-specific knowledge. The deployed tree is a build artifact — every install re-renders it from the packaged template, so upgrading is `pip` upgrade + `pilot-workers install <host|all>` (hosts with nothing configured are untouched). Removing the last provider deletes the skill, so a host with nothing configured has none and the planner does the work itself. (The v0.4.0 12-agents + 8-commands matrix is gone.)
 
 Adding a new host: create `integrations/<name>-host/skills/pilot-workers/`, put whatever config your host needs, point it at `pilot-workers dispatch`. See `integrations/README.md`.
 

{pilot_workers-0.5.3 → pilot_workers-0.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pilot-workers"
-version = "0.5.3"
+version = "0.5.4"
 description = "Dispatch bounded tasks to isolated LLM workers (GLM, Kimi, and more)"
 readme = "README.md"
 license = "MIT"

{pilot_workers-0.5.3 → pilot_workers-0.5.4}/src/pilot_workers/cli/install.py

@@ -495,23 +495,48 @@ def apply_generated_region(skill_text: str, region: str) -> str:
     return before + GENERATED_BEGIN + inner + GENERATED_END + after
 
 
+# Example requests per mode, spliced into the generated description so the
+# trigger has surface area that RESEMBLES real prompts — policy prose shares
+# no tokens with an actual request like asking to trace a flow. Bilingual
+# because users prompt in Chinese too; only ROUTED modes get their examples
+# advertised (the sibling rule to not advertising an unassigned mode's
+# routing). No ": " anywhere — the description must stay a valid plain YAML
+# scalar. resume is planner-internal recovery, so it has no user phrasing.
+MODE_TRIGGER_EXAMPLES: dict[str, tuple[str, ...]] = {
+    "explore": ('"how does X work"', '"trace this flow"',
+                '"探索/梳理/读一下这块代码"'),
+    "code": ('"implement/fix/refactor X"', '"改一下/实现/修复"'),
+    "test": ('"run the tests"', '"跑一下测试"'),
+    "review": ('"review this change"', '"review 一下这次改动"'),
+}
+
+
 def render_trigger_sentence(provider_keys: list[str],
                             modes: dict[str, str]) -> str:
     """The frontmatter's trigger clause, generated from the host's ROUTING.
 
     This is the only part of the skill a model sees before deciding whether to
-    load it, so it decides what the whole feature can do. It used to read
-    "Trigger when the user names a worker provider — ds, kimi-k3", which is the
-    most specific clause in the description and therefore the operative one — so
-    "explore this codebase" never loaded the skill, and the mode -> provider table
-    (which lives in the BODY) was never read. The assignment recorded by
-    ``install ds on claude for explore`` was unreachable at trigger time: stored,
-    displayed by ``status``, rendered into the skill, and unable to fire.
-
-    The point of the assignment is that the user does NOT name a provider. So the
-    modes come first, in an explicit ``mode, mode -> provider`` form, and naming a
-    provider stays as an additional path. A host with no assignments routes
-    nothing and must not claim otherwise.
+    load it, so it decides what the whole feature can do. Two failure modes are
+    on record, both found live:
+
+    - v0.5.2 read "Trigger when the user names a worker provider — ds, kimi-k3",
+      the most specific clause in the description and therefore the operative
+      one — so "explore this codebase" never loaded the skill, and the
+      mode -> provider table (which lives in the BODY) was never read.
+    - v0.5.3 routed by mode but left the judgment open: the surrounding static
+      text still said "worth delegating ... Not for small tweaks", so a small
+      exploration was judged not worth a worker and the skill never loaded.
+      Routing is a MANDATE — ``install ... for <mode>`` is the user making the
+      delegation decision once; the sentence must close the per-task
+      re-judgment, and the only stated override is explicit user input (the
+      top of the priority chain: user input, then config, then do-it-yourself
+      fallback).
+
+    Also load-bearing: NO unquoted colon-space anywhere in the sentence. The
+    clause is spliced into a plain YAML scalar, and a mid-value ": " is a
+    scanner error in strict YAML — v0.5.3's "Route by MODE, not by name:
+    explore" made the whole deployed frontmatter unparseable. A host with no
+    assignments routes nothing and must not claim otherwise.
     """
     names = ", ".join(provider_keys)
     routed: dict[str, list[str]] = {}
@@ -521,13 +546,28 @@ def render_trigger_sentence(provider_keys: list[str],
     if not routed:
         return (f"No mode is routed on this host yet, so nothing is delegated "
                 f"automatically; naming a provider ({names}) triggers this skill.")
-    groups = "; ".join(
-        f"{', '.join(sorted(mode_list))} \u2192 {key}"
-        for key, mode_list in sorted(routed.items()))
-    return (f"Route by MODE, not by name: {groups}. A request for that kind of "
-            f"work triggers this skill even when the user names no provider — "
-            f"which is the point of the routing — and naming one ({names}) "
-            f"triggers it too.")
+    parts = []
+    for key, mode_list in sorted(routed.items()):
+        head = ", ".join(sorted(mode_list))
+        examples = ", ".join(
+            ex for m in sorted(mode_list)
+            for ex in MODE_TRIGGER_EXAMPLES.get(m, ()))
+        suffix = f" (e.g. {examples})" if examples else ""
+        parts.append(f"{head} \u2192 {key}{suffix}")
+    groups = "; ".join(parts)
+    return (f"This host routes work by mode — {groups}. A request for a routed "
+            f"kind of work MUST be dispatched through this skill to its "
+            f"assigned provider, even when the task looks too small to be "
+            f"worth a worker. Never do routed work in this session and never "
+            f"weigh whether delegation is worth it — the `install ... for "
+            f"<mode>` that created the route already made that decision. The "
+            f"route also binds your own mid-task moves — realizing you need "
+            f"to read code to understand it, write code, run tests, or "
+            f"review a diff means dispatching, not doing it here; only "
+            f"verifying a known location (a cited file, a returned diff or "
+            f"verdict) stays local. Explicit user input is the only override "
+            f"— naming a provider ({names}) selects it, and an explicit "
+            f"request to do the work here keeps it here.")
 
 
 def substitute_trigger_placeholder(skill_text: str,
@@ -564,36 +604,27 @@ def _packaged_skill_text(host: str) -> str:
             / "SKILL.md").read_text(encoding="utf-8")
 
 
-def _render_deployed_skill(installs: dict, host: str, base_text: str) -> str:
-    """The deployed SKILL.md text: worker region + trigger list from config.
+def _render_deployed_skill(installs: dict, host: str) -> str:
+    """The deployed SKILL.md text, rendered from the PACKAGED template.
 
-    ``base_text`` supplies the hand-editable doctrine, so hand edits outside
-    the markers and the frontmatter survive a refresh. The frontmatter is
-    re-derived from package data on every render: the trigger token is
-    consumed by the first deploy, so re-substituting ``base_text`` alone
-    could never drop a provider that was uninstalled later.
+    The deployed tree is a build artifact: every render starts from package
+    data plus the recorded config, so a packaged doctrine update propagates on
+    the next install of any form. It used to rebase on the already-deployed
+    file to preserve hand edits — which meant a package upgrade could never
+    deliver a body update to an existing deployment, while the frontmatter,
+    the generated region and every sibling file were rewritten anyway: half a
+    promise, and the delivered half was permanent staleness. Custom doctrine
+    belongs in the packaged template, where it survives upgrades properly.
+
+    A packaged template without a marker pair makes ``apply_generated_region``
+    raise loudly: that is a packaging bug, never an upgrade state.
     """
     provider_keys = host_providers(installs, host)
     modes = host_modes(installs, host)
     region = render_worker_region(provider_keys, modes)
-    try:
-        out = apply_generated_region(base_text, region)
-    except RuntimeError:
-        # No usable marker pair in the deployed text. That is the normal state
-        # when upgrading from a release whose skill predates the markers, and it
-        # also covers a deployment whose markers were lost to hand-editing —
-        # they are HTML comments, invisible in rendered markdown. Fall back to
-        # the packaged text, which always carries them. Hand edits in the old
-        # file cannot be preserved here: there is no boundary left to preserve
-        # them against.
-        out = apply_generated_region(_packaged_skill_text(host), region)
-    new_front = _frontmatter_block(
-        substitute_trigger_placeholder(_packaged_skill_text(host),
-                                       provider_keys, modes))
-    old_front = _frontmatter_block(out)
-    if new_front is not None and old_front is not None:
-        out = new_front + out[len(old_front):]
-    return out
+    text = substitute_trigger_placeholder(
+        _packaged_skill_text(host), provider_keys, modes)
+    return apply_generated_region(text, region)
 
 
 def _host_config_entry(installs: dict, host: str) -> dict:
@@ -777,33 +808,31 @@ def _deployed_skill_path(entry) -> Path | None:
     return None
 
 
-def _splice_region_into_deployed(installs: dict, host: str) -> None:
-    """Regenerate the worker region of the host's already-deployed SKILL.md.
+def _rerender_deployed_skill(installs: dict, host: str) -> None:
+    """Rewrite the host's already-deployed SKILL.md from the current render.
 
-    Splices into the existing deployed file, so hand edits outside the markers
-    AND outside the frontmatter survive (the frontmatter is re-derived from
-    package data on every render — see ``_render_deployed_skill``). No-op when
-    the host has no deployed skill on record.
+    Full re-render from package data (see ``_render_deployed_skill``), written
+    to the RECORDED path — this is the path routine provider install/uninstall
+    takes, which must not guess a target directory. Sibling files (modes/*.md)
+    are converged by the host-form install; this rewrites the one file whose
+    content depends on the recorded config. No-op when the host has no
+    deployed skill on record.
     """
     skill = _deployed_skill_path(installs.get(host))
     if skill is None or not skill.is_file():
         return
-    # Atomic like every other skill write: this is the path routine provider
-    # install/uninstall takes, and a truncating write_text here would leave a
-    # crash as a half-written doctrine file that nothing detects or repairs.
-    _write_skill_atomically(
-        skill,
-        _render_deployed_skill(installs, host, skill.read_text(encoding="utf-8")))
+    # Atomic like every other skill write: a truncating write_text here would
+    # leave a crash as a half-written doctrine file nothing detects or repairs.
+    _write_skill_atomically(skill, _render_deployed_skill(installs, host))
 
 
 def _deploy_skill_tree(installs: dict, host: str, target: Path | None) -> None:
-    """Deploy/refresh the host's skill tree and splice the current region.
+    """Deploy/refresh the host's skill tree, rendered from package data.
 
     Records ``installed_at``/``package_version``/``files``/``created_dirs``
-    on the host's manifest entry exactly as the host-install path does. On a
-    refresh the region is spliced into the EXISTING deployed SKILL.md text,
-    so hand edits outside the markers and the frontmatter survive a
-    regeneration (the frontmatter is always re-derived from package data).
+    on the host's manifest entry exactly as the host-install path does. The
+    deployed tree is a build artifact: a refresh converges every file to the
+    current packaged render, so package upgrades propagate.
     """
     entry = installs[host]
     # A legacy v1/v2 nesting must be cleaned by whichever install touches the
@@ -816,18 +845,16 @@ def _deploy_skill_tree(installs: dict, host: str, target: Path | None) -> None:
         for key in [k for k in entry
                     if k not in ("providers", "modes")]:
             del entry[key]
+    # The previously deployed SKILL.md path: not a render input (the render
+    # is pure package data + config), but the orphan sweep below must treat
+    # the previous location as in-bounds when --target moves a deployment.
     previous_skill = _deployed_skill_path(entry)
-    previous_text: str | None = None
-    if previous_skill is not None and previous_skill.is_file():
-        previous_text = previous_skill.read_text(encoding="utf-8")
 
     # Render BEFORE anything on disk changes. Copying first and rendering after
     # means a render failure leaves the host with a half-updated skill — or none
     # at all on the purge path. Rendering needs no file, so nothing forces that
     # order.
-    rendered = _render_deployed_skill(
-        installs, host, previous_text if previous_text is not None
-        else _packaged_skill_text(host))
+    rendered = _render_deployed_skill(installs, host)
 
     previous_files = set(entry.get("files") or [])
     result = install_host(host, target, skill_text=rendered)
@@ -1285,7 +1312,7 @@ def _install_provider_on_host(
                     or not existing.is_file()):
                 _deploy_skill_tree(installs, host, target)
             else:
-                _splice_region_into_deployed(installs, host)
+                _rerender_deployed_skill(installs, host)
             if mode is None:
                 if added:
                     print(f"  recorded: {provider_key} on {host}")
@@ -1346,18 +1373,9 @@ def main(argv: list[str] | None = None) -> int:
                     print(f"{host}: no workers configured — nothing to install.")
                     print(f"  next: pilot-workers install <provider> on {host}")
                     continue
-                # Capture the deployed text BEFORE the purge+recopy below, or the
-                # freshly copied package template becomes the splice base and any
-                # prose the user added outside the markers is lost.
-                previous_skill = _deployed_skill_path(previous)
-                previous_text: str | None = None
-                if previous_skill is not None and previous_skill.is_file():
-                    previous_text = previous_skill.read_text(encoding="utf-8")
                 # Render before destroying: a render failure must not leave the host
                 # with a purged skill and nothing to replace it.
-                rendered = _render_deployed_skill(
-                    installs, host, previous_text if previous_text is not None
-                    else _packaged_skill_text(host))
+                rendered = _render_deployed_skill(installs, host)
                 # Migration / reinstall: purge every previous entry for this host
                 # (v3/v4 flat reinstall OR legacy v1 __all__ + v2 providers), then
                 # write a clean host-level v4 entry.
@@ -1380,9 +1398,8 @@ def main(argv: list[str] | None = None) -> int:
                         new_entry["modes"] = previous["modes"]
                 installs[host] = new_entry
                 # The deployed skill reflects the recorded configuration; the copy
-                # above already wrote the text rendered from it (spliced into the
-                # previous text when there was one, so hand edits outside the
-                # markers and the frontmatter survive).
+                # above already wrote the text rendered from package data plus
+                # that configuration.
             # The manifest is committed ONCE, when the transaction exits — not
             # per host. A crash mid-``install all`` therefore records no hosts,
             # rather than some: the deployed files of the completed hosts are
@@ -1421,7 +1438,7 @@ def _uninstall_provider_on_host(provider_key: str, host: str) -> int:
                 return 0
             entry = installs.get(host)
             if host_providers(installs, host):
-                _splice_region_into_deployed(installs, host)
+                _rerender_deployed_skill(installs, host)
             elif isinstance(entry, dict) and isinstance(entry.get("files"), list):
                 # That was the last provider: purge the deployed skill and drop
                 # the host's manifest entry entirely.
@@ -1458,7 +1475,7 @@ def _uninstall_default_on_host(mode: str, host: str) -> int:
     try:
         with manifest_transaction(delete_when_empty=True) as installs:
             if clear_host_mode(installs, host, mode):
-                _splice_region_into_deployed(installs, host)
+                _rerender_deployed_skill(installs, host)
                 print(f"  removed: {mode} assignment on {host}")
             else:
                 print(f"note: no provider assigned to mode {mode!r} on {host}")

pilot_workers-0.5.4/src/pilot_workers/integrations/claude-host/skills/pilot-workers/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: pilot-workers
+description: Dispatch bounded tasks (code, explore, test, review, resume) to isolated LLM workers via the pilot-workers CLI and harvest their structured verdicts. {{PILOT_PROVIDER_TRIGGERS}}
+---
+
+# pilot-workers Playbook
+
+You are the planner. Workers are separate OpenCode processes that **cannot see
+this conversation**. Planning, task decomposition, and final verification stay
+with you; workers get only settled decisions.
+
+## When this skill applies
+
+Two kinds of moments route here; match either, then choose the provider by
+the priority chain below.
+
+| Moment | Mode |
+| --- | --- |
+| "how does X work" / "trace this flow" / "探索、梳理、理解、读一下这块代码" — or YOU need to read code to build understanding before planning | explore |
+| "implement/fix/refactor X" / "改一下、实现、修复" — or the plan is settled and edits would begin | code |
+| "run the tests" / "跑一下测试" — or you want a suite run to verify a change | test |
+| "review this change" / "review 一下这次改动" — or a rewrite-scale diff just landed | review |
+| a prior dispatch failed or stopped short | resume |
+
+The self-initiated rows draw the line by PURPOSE, never by size: reading to
+LEARN (trace a flow, understand a module, gather context for a change) is an
+explore dispatch no matter how few files; verifying a KNOWN location (a cited
+file:line, a returned diff, a verdict) is local reading and needs no worker.
+
+## Quick Reference
+
+```bash
+pilot-workers template <mode> > /tmp/<provider>-<mode>-<slug>-<timestamp>.md   # fill it in — self-contained
+pilot-workers dispatch --provider <key> --mode <mode> --workdir "$PWD" --task-file <file>   # background Bash
+```
+
+**Choose `<key>` by priority.** (1) Explicit user input always wins: a provider
+the user names is used even where the Workers table assigns another, and an
+explicit request to do the work here ("don't dispatch", "do it yourself") keeps
+it in this session. (2) Otherwise the **Workers table** at the bottom of this
+file decides: a routed mode is ALWAYS dispatched to its assigned provider —
+never done in this session, and never weighed for whether it is worth a worker.
+`install ... for <mode>` was the user making that economics decision once; it
+is not yours to remake per task. If a routed dispatch seems wasteful, dispatch
+anyway and say so afterwards — the user can
+`pilot-workers uninstall for <mode> on <host>`. (3) **A mode with no provider
+assigned is not an invitation to guess: do it yourself, in this session.** No
+assignment means the user never delegated that kind of work; picking a worker
+by its advertised strengths would delegate something they chose to keep. If a
+mode looks worth delegating, say so and let them run
+`pilot-workers install <provider> on <host> for <mode>`. Never dispatch to a
+provider absent from the table: it was not configured here.
+
+**Then Read `modes/<mode>.md`** (next to this file in the skill directory)
+before writing the task file — it is that mode's task recipe and verification
+contract. Never dispatch a mode whose playbook you have not read in this
+session.
+
+- stdout is exactly two JSON lines: first `worker_runner.started` (record
+  run_id and log paths), last `worker_runner.verdict`. **The completion signal
+  = the background Bash exiting on its own.** Never poll by process name;
+  never judge from the shared log (`latest.log` is for humans only). Fewer than
+  two lines means the run died before starting — read its stderr, because an
+  early failure (missing credential, runner not installed) emits no JSON at all.
+- **Dispatch from the main session only, in a background Bash.** Subagents die
+  at turn end and their background tasks are never harvested — never dispatch
+  from a subagent, never "wait" by ending your turn.
+- Consumption contract: read `verdict.result` first (the parsed PILOT_RESULT
+  block). Read `final_text_path` at most once, only when
+  `parse_state != "parsed"` or a finding requires surrounding context. Never
+  auto-redispatch on parse failure alone.
+- Resume-first recovery: on failure or non-convergence, resume with
+  `--session <session_id>` + `--run-id <resume_run_id>` from the original verdict
+  before considering a cold redispatch. A `credential missing` error is not a
+  worker failure and resume will not fix it — the provider has no API key yet:
+  tell the user to run
+  `pilot-workers install <provider> on <host> --global-key`, which prompts for
+  it. The key belongs to the provider, so it is configured once for every host.
+  Never handle a key yourself.
+
+## Verdict matrix
+
+The `verdict` state string and the sibling flags `timed_out` / `idle_timed_out` /
+`interrupted` are set independently — **check the flags even on `completed`**.
+
+| state | meaning | action |
+|---|---|---|
+| `completed` | usable report (`parse_state` parsed, or long unstructured text) | consume `result` first; flags may still be set — say so |
+| `step_capped_partial` | step cap hit | partial coverage; a parsed partial block is still salvaged into `result` — report the uncovered scope truthfully |
+| `error` | summary-error or crash with no usable text | `stderr_tail` first; open `jsonl_path` only if it does not explain the death |
+| `empty` | no usable output | same: `stderr_tail`, then `jsonl_path` if needed |
+
+Never draw a conclusion without reading the evidence.
+
+`duration_s` / `tokens` / `final_text_len` are for your next decision, not the
+report: cost so far, and whether `final_text_path` is worth opening at all
+(`parse_state: parsed` means `result` already has everything).
+
+`parse_state` values: `parsed` (consume `result`), `malformed` (the worker DID
+write a result block and it did not parse — the work is real, read
+`final_text_path`), `unstructured` (a block that was cut off mid-write — treat as
+partial), `unavailable` (no block at all — the worker ignored the contract).
+
+Synthesized fanout verdicts carry `synthesized: true` + `reason`
+(`crash|timeout|idle_timeout|interrupted`) + `stderr_tail`; `result` and
+`final_text_path` are null. Consume rule: synthesized → read `reason` +
+`stderr_tail` only.
+
+## Task files
+
+- The worker sees nothing but the task file: it must be **self-contained** —
+  explicit file paths, completion criteria, do-not-touch boundaries. Never
+  "that file" or "the module mentioned above".
+- Unique `/tmp` names (`<provider>-<mode>-<slug>-<timestamp>.md`) so parallel
+  sessions never clobber each other.
+- **Never any credentials** in a task file — it is sent verbatim to a
+  third-party endpoint. Dispatch refuses obvious key shapes and any key
+  configured on this machine, but that check **cannot catch every secret**:
+  it is a backstop, not permission to paste config. Reference a value by
+  env var and let the worker read it.
+- **The worker can see the whole workdir.** Opening an `auth.json` or `.env` is
+  denied for both the shell and the read tool, but a path deny cannot stop a
+  recursive content search from returning a line out of one. If the project holds
+  live secrets in untracked files, dispatch with `--worktree`: a detached
+  worktree materialises tracked files only, so a gitignored `.env` is not there
+  at all — a boundary rather than a pattern.
+- General discipline does not need to be written — dispatch injects
+  `prompts/*.md` automatically, including the `PILOT_RESULT` output block the
+  worker must end with.
+
+<!--PILOT_GENERATED_BEGIN-->
+<!--PILOT_GENERATED_END-->
+
+## Providers
+
+Provider strengths and suitable modes live in the provider YAML registry,
+not here — run `pilot-workers status <host>` when you need them (status
+renders each provider's `strengths`, `suitable_modes`, and `notes` live).
+
+## Timeouts
+
+- `--timeout <sec>` caps the whole job; the fanout parent watchdog
+  enforces it plus a grace period.
+- **`--timeout 0` forfeits the parent watchdog** for that job (no deadline,
+  no silence kill); the child's `--idle-timeout` remains the only liveness
+  bound.
+- `--timeout 0 --idle-timeout 0` together make a job **fully unbounded** —
+  avoid unless you are watching it yourself.

pilot_workers-0.5.4/src/pilot_workers/integrations/claude-host/skills/pilot-workers/modes/code.md

@@ -0,0 +1,41 @@
+# Mode: code — dispatch playbook
+
+(Read this before every code dispatch. The core SKILL.md holds the
+priority chain, the red lines and the verdict contract; this file
+holds the craft for this one mode.)
+
+- **Shape the task; the dispatch decision is already made.** Routing (or the
+  user naming a provider) decided who does code work — what stays yours is
+  making the task carryable: settle every judgment call before dispatch
+  (workers get only settled decisions) and hand over specs, not questions. A
+  change that would need mid-course judgment at every step is a planning gap —
+  settle more, then dispatch.
+- One worker call bundles at most 2-3 related fix points; split larger
+  batches into multiple workers (they can run in parallel).
+- **Parallel code jobs require `--worktree`** so each worker gets an isolated
+  git worktree; one worker per background Bash; batch similar durations per
+  fanout and split mixed durations. Clean up with
+  `pilot-workers maintain worktrees remove <path>`.
+- Verify once, and verify what is cheap to verify COMPLETELY. `git diff --stat`
+  plus `git status --short` settle one whole property for a few hundred tokens:
+  which files changed. Compare that set against the spec's whitelist — anything
+  outside it is a boundary violation, and a stray untracked file is worth
+  catching too. Reconcile the worker's own `FILES_CHANGED` against that set too — a
+  mismatch means it misreported its work, which colours everything else it
+  claimed. Also read `exit_code` / `session_id` / `steps` / `tool_errors`
+  from the verdict.
+- **Do not sample the diff.** Reading a few hunks of a large change licenses
+  nothing about the rest; it costs attention and buys confidence you have not
+  earned. Correctness comes from the test run, from exercising the behaviour
+  end to end, and — for rewrite-scale diffs — from the cross-model review below.
+  Never treat the worker's completion claim as proof. **The test run goes to whichever provider is
+  assigned to `test` in the Workers table**, as a `test`-mode dispatch; running
+  it here would void that assignment. You still read the counts and failures and
+  decide what they mean.
+- **Cross-model review for rewrite-scale diffs** (several hundred lines or more):
+  dispatch a *different* provider in review mode before verifying — the two
+  models' errors are uncorrelated, so the second catches the first's
+  systematic blind spots at cheap quota. Skip for small changes.
+- Do not edit a worker's target files while it is running. Deletion,
+  migration, CI/keys/production config changes: do not dispatch; a human does
+  those.

pilot_workers-0.5.4/src/pilot_workers/integrations/claude-host/skills/pilot-workers/modes/explore.md

@@ -0,0 +1,25 @@
+# Mode: explore — dispatch playbook
+
+(Read this before every explore dispatch. The core SKILL.md holds the
+priority chain, the red lines and the verdict contract; this file
+holds the craft for this one mode.)
+
+Reading code is the bulk of token spend (read-to-write ratio roughly 50:1), so
+exploration is a top dispatch candidate. Write the question straight into the
+task file; do not read the code yourself first — that wastes the saving.
+
+- List what to investigate item by item; pin the scope to specific
+  directories/file types to shrink roaming room.
+- **Planning is the verification — do not sample.** Sampling a couple of
+  conclusions proves nothing about the rest and manufactures confidence in it.
+  Instead take the report into planning; the gaps surface as you use it:
+  a broad gap (wrong subsystem, missing the leads you need) goes back as a
+  rewritten explore dispatch, while three or five lines you still need — read
+  them here, a round-trip costs more than the read.
+- Conclusions carrying no `file:line` are untrusted: you cannot plan on them and
+  cannot check them, so treat them as absent.
+- Bring conclusions back **with their file:line references, verbatim** — the
+  main thread requires those references to plan; losing them ruins everything.
+- Boundary: judgment/trade-off questions ("which approach is better") are your
+  job, not the worker's. Mixed explore+change tasks: explore first, plan,
+  then dispatch code.

pilot_workers-0.5.4/src/pilot_workers/integrations/claude-host/skills/pilot-workers/modes/resume.md

@@ -0,0 +1,27 @@
+# Mode: resume — dispatch playbook
+
+(Read this before every resume dispatch. The core SKILL.md holds the
+priority chain, the red lines and the verdict contract; this file
+holds the craft for this one mode.)
+
+- **Resume-first recovery.** When a run fails or does not converge, prefer
+  resume — it reuses the full prior-session context and saves minute-scale
+  round-trips versus a cold restart:
+
+  ```bash
+  pilot-workers dispatch --provider <key> --mode resume \
+      --session <session_id from the verdict> --run-id <resume_run_id from the verdict> \
+      --workdir <workdir from started> --task "Previous task incomplete: <what is missing, how to fix>"
+  ```
+
+  Take `--session` from the verdict and `--run-id` from its **`resume_run_id`**,
+  not its `run_id`: a resumed run gets a fresh `run_id` for its own log, so
+  resuming twice off `run_id` names a sandbox that never existed and fails as
+  "session expired". `resume_run_id` is the sandbox, and for a cold run the two
+  are equal — so read that one field either way. No template for resume — pass
+  `--task` with what remains and how to fix it.
+- **Two obstacles, then take over**: if the worker hits the same obstacle
+  twice and still does not pass → the main session takes over and wraps up.
+- The resume window == the sandbox retention window. A loud "session expired
+  past retention" error means the sandbox was reaped — redispatch cold. A
+  loud "run is still active" error means a live lock; do not force it.

pilot_workers-0.5.4/src/pilot_workers/integrations/claude-host/skills/pilot-workers/modes/review.md

@@ -0,0 +1,37 @@
+# Mode: review — dispatch playbook
+
+(Read this before every review dispatch. The core SKILL.md holds the
+priority chain, the red lines and the verdict contract; this file
+holds the craft for this one mode.)
+
+- **Axis-splitting is your judgment call.** Fix 2-4 orthogonal axes
+  (correctness/boundary conditions, security, performance, consistency with
+  codebase conventions); one instance handles exactly one axis. Write each
+  axis as its own self-contained task file.
+- **Parallel fanout recipe**: one job per axis, launched together —
+
+  ```bash
+  pilot-workers fanout --job <providerA>:review:/tmp/review-correctness-<ts>.md \
+                       --job <providerB>:review:/tmp/review-security-<ts>.md
+  ```
+
+  (`--job PROVIDER:MODE:TASK_FILE`; mixing providers distributes load across
+  quotas.) Each job collects its verdict independently.
+- **Aggregation is your job.** Merge and dedupe findings across axes, sort by
+  severity, report directly. **Verify every finding you intend to act on,
+  before acting** — not a sample of them. A review finding is a claim you will
+  answer by editing code, so a false positive turns into a wrong edit; open its
+  cited `file:line` and confirm the defect is real. Findings you are NOT acting
+  on need no verification: say they are unverified. Findings with no `file:line`
+  are untrusted.
+- **Try to REFUTE each high before acting on it, and refute its fix too.**
+  Reviewers cannot run code (interpreters are denied in review mode), so their
+  findings are readings — plausible and sometimes wrong. Run the thing: the
+  input against the regex, the race with the lock disabled, the command in a
+  scratch copy. A proposed fix is a separate claim and has been wrong even when
+  the diagnosis was right. For a high you cannot settle by running something,
+  dispatch a *different* provider in review mode to argue against it.
+- Review mode cannot edit; fixes go through your planning — small fixes
+  yourself, bulk mechanical fixes via a code dispatch.
+- Axis too broad ("review the entire repo") → split axes first; unclear diff
+  baseline → clarify the two versions being compared first.

pilot_workers-0.5.4/src/pilot_workers/integrations/claude-host/skills/pilot-workers/modes/test.md

@@ -0,0 +1,15 @@
+# Mode: test — dispatch playbook
+
+(Read this before every test dispatch. The core SKILL.md holds the
+priority chain, the red lines and the verdict contract; this file
+holds the craft for this one mode.)
+
+- The task states the exact test command, directory, preconditions, and any
+  known pre-existing failures. Run-and-gather only; fixes are your job.
+- **Anti-false-positive**: counts + raw error text → trust it. "All passed"
+  with no counts → suspicious → read `jsonl_path` to see what command
+  actually ran, and redispatch if needed. Run `git status` to confirm the
+  worker left no junk changes behind.
+- Bring counts and the failure list (test name, raw error text, `file:line`)
+  back verbatim; do not interpret root cause or propose fixes on the worker's
+  behalf.