joakimp
9c87ee843f
The cheat-sheet listed Fork first (with "balanced … default: exploration/ impl/test") and Task as the exception, and it lost to the fork tool's self-recommending description every time it mattered (five of five fork briefs in one 2026-09-17 session carried "do not"). This file is the one copy of the rule in the SYSTEM PROMPT — the skill is gone after the first compaction — so it now carries: the one discriminator (what the child sees), task as the default for anything that writes or must obey a rule, fork only for read-only exploration against this conversation or parallel opinions, a three-question pre-flight before any fork(...), a copy-paste minimal task(...) call with the roots contract (write_allowed ⊆ roots, never nested in a watched root), and a note that fork-gate now enforces the split. README: pi-task is now also the `task` tool (pi-extensions task.ts) with fork-gate alongside; where the wrapper looks for this script.
3.4 KiB
Global agent instructions
Session start: load the pi-extensions skill
If the fork, task and/or recall tools are present in your tool list (you
are running inside the pi harness with the pi-fork / pi-extensions /
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.
Delegating work: task first, fork second
Two ways to run a child agent. They differ in ONE thing, and it decides the quality of the result: what the child sees.
task(tool; wraps thepi-taskCLI) — the child sees only your spec (L0–L2: goal + named files + curated facts). Immutable spec, machine-checked PASS/FAIL envelope, every root diffed before/after (a write outsidewrite_allowedFAILS), audit dir under~/.pi/agent/pi-task/. Default for any delegated work that changes files or must obey a rule.fork(tool) — the child inherits your entire branch (L4) with the brief as its last message. Measured on this fleet: in a long session the parent narrative outweighs the brief — forks ignored prohibitions, invented quotes, answered in the user's voice, and left no audit trail (their temp dir is deleted on exit). Use only for read-only exploration that needs this conversation's context, or N parallel opinions on one question.
Pre-flight before any fork(...) — one yes makes it a task:
- Does the brief say do not / only / never / must not?
- Will the child write, edit, commit or push anything?
- Do I want a PASS/FAIL I can check, rather than prose?
The fork tool's own description recommends itself for "implementation"; it is
wrong about that, and fork-gate (a tool_call hook) will block a fork whose
brief trips the three questions and hand back the task(...) to make instead.
This paragraph is in the system prompt and survives compaction; the skill does
not — that is why the rule lives here.
Minimal task call (pi-task schema lists every field):
task(id="slug", goal="…verbatim, the child has NO other context…",
deliverable="…exact shape wanted…", effort="fast|balanced|deep",
read_only=false,
roots=["/abs/repo/docs", "/abs/repo/src"], # WATCHED, each diffed alone
write_allowed=["/abs/repo/docs"], # exact subset of roots; never nested in a watched root
facts=["verified fact"], files=["/abs/path/to/read"])
Result = the CLI report (verdict, problems, deliverable, evidence pointers,
audit dir). Spot-check the pointers: the envelope proves shape, not truth.
Tasks with overlapping roots run one at a time (the tool serialises them).
Tiers: fast=haiku (mechanical/lookups), balanced=sonnet (default),
deep=opus (architecture, security, ambiguous debugging).
CLI fallback if the tool is missing: /opt/pi-toolkit/bin/pi-task run <spec.json>.
- 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 the context ladder, brief design, boundary discipline, and the observational-memory model, read the full skill.