# 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 the `pi-task` CLI) — 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 outside
  `write_allowed` FAILS), 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`:
1. Does the brief say *do not / only / never / must not*?
2. Will the child write, edit, commit or push anything?
3. 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.