joakimp
adfb553f5c
The pi-task section already explained the tool in depth. What was missing was the decision: given a subtask, which mechanism, and why. Adds an end-user section built on the L0-L4 ladder — the child's context volume is the axis that explains nearly every observed good and bad behaviour — plus when to use neither. Carries the measured cost so the choice is priced, not guessed: 9 runs, $0.669 total, $0.0027 (fast, refused an over-budget spec in 2.5s) to $0.165 (balanced, 87s). Includes the jq one-liner, and the warning that a crashed run leaves no result.json — one of the ten here is exactly that, so a rollup must tolerate missing files rather than assume runs == directories. Records that fork spend is NOT in that tree (pi-fork aggregates from the parent's own toolResult entries into the status bar), so the two mechanisms report spend in two different places and nothing adds them up today. pi-global-AGENTS.md gets one cheat-sheet bullet so the choice is visible without loading a skill, and names pi-task as a CLI rather than a tool. Both files also carry the inverted capability-floor trap ([] = floor on, null = floor off).
2.1 KiB
2.1 KiB
Global agent instructions
Session start: load the pi-extensions skill
If the fork and/or recall tools are present in your tool list (you are
running inside the pi harness with the pi-fork / pi-observational-memory
packages), read ~/.agents/skills/pi-extensions/SKILL.md before doing any
non-trivial work. These extensions are routinely under-utilised when left to
on-demand description matching; reading the skill up front fixes that.
Core triggers (cheat-sheet — the skill has the full guidance):
- Fork (
fork(task=..., effort=fast|balanced|deep)) when a subtask needs reading many files you won't keep, runs in parallel, or is a well-scoped one-shot whose detail would pollute the main thread. Tiers:fast=haiku (mechanical/lookups),balanced=sonnet (default: exploration/impl/test),deep=opus (architecture, security, ambiguous debugging). Always state decision authority, pass verified context, specify the deliverable, ask for an "unsure about" section. Don't fork trivial or iterative work. - Task (
pi-task, a CLI at/opt/pi-toolkit/bin/pi-task— not a tool in your list, you invoke it with bash) when the child must NOT inherit your session: any brief containing a prohibition, anything needing a machine-checked pass/fail envelope, a durable audit trail, or write-boundary enforcement over named roots. Same ladder, different rung:forkis L4 (child sees your whole branch),pi-taskis L0–L2 (nothing / named files / curated facts). Pick the lowest rung that can do the job. L3 (truncated branch) is not built. - Recall (
recall(<12-char-hex-id>)) before a load-bearing action (edit code, ship a change, assert a fact) that rests on a[high]/[critical]observation or a reflection you did not produce this turn. The compaction summary is lossy by design; one recall is cheap, redoing finished work is not. Not a search tool — you must already have the ID.
For depth on tier selection, fork-brief design, boundary discipline, and the observational-memory model, read the full skill.