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).
35 lines
2.1 KiB
Markdown
35 lines
2.1 KiB
Markdown
# 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: `fork` is **L4** (child sees your
|
||
whole branch), `pi-task` is **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.
|