Kai
f25082223e
README leads with the finding that motivated the repository -- pi emits the skills section only when a tool named 'read' is active, so Curator's --no-tools --skill combination made its policy unreachable -- with the measured before/after table and instructions to reproduce it at zero token cost. AGENTS.md sets seven rules for anyone changing this repository. The third is the one that matters most: verify pi's behaviour with a probe rather than inferring it from the docs. Three claims in the first draft of these documents were wrong and were only corrected by running one. The _template scenario carries the isolation defaults and inline warnings at the places where mistakes have already cost time: --no-tools disabling the skills mechanism, cwd anchoring .pi discovery, the read override being mandatory rather than optional, and allowed-tools frontmatter not being enforced in 0.84.3.
41 lines
1.6 KiB
Markdown
41 lines
1.6 KiB
Markdown
# Scenario: <name>
|
|
|
|
<One paragraph: what this agent does and for whom.>
|
|
|
|
Live service: `<name>.service`.
|
|
Live workspace: `/home/claw/pi-workspaces/<name>`.
|
|
|
|
## Checklist for a new scenario
|
|
|
|
1. Copy `scenarios/_template/` to `scenarios/<name>/` and fill every
|
|
`<PLACEHOLDER>` in `profile.toml`.
|
|
2. Write `.pi/SYSTEM.md` — all six sections. The replacement branch supplies no
|
|
tool list and no guidelines.
|
|
3. Write `.pi/APPEND_SYSTEM.md` for durable domain responsibilities.
|
|
4. Write the extension. Build it on `shared/extensions/pi-guard-base.ts`:
|
|
`registerRestrictedRead` (mandatory — it is what keeps skills reachable) and
|
|
`installGuard`. Give every tool a `promptSnippet`.
|
|
5. Drive it from `shared/lib/py/pi_rpc.py` rather than spawning `pi --print` per
|
|
message.
|
|
6. Verify before deploying:
|
|
```bash
|
|
scripts/deploy-scenario.sh <name> # dry run
|
|
shared/extensions/tests/run-guard-checks.sh
|
|
```
|
|
7. Deploy and restart yourself:
|
|
```bash
|
|
scripts/deploy-scenario.sh <name> --apply
|
|
systemctl --user restart <name>.service
|
|
```
|
|
8. Record the conformance row in `docs/isolation-baseline.md`.
|
|
|
|
## Gotchas that have already cost time
|
|
|
|
- `--no-tools` disables extension tools too, which removes `read`, which removes
|
|
the skills section. Never use it. Use `--no-builtin-tools`.
|
|
- `cwd` anchors `.pi` discovery. Launch with `cwd` set to the workspace or
|
|
`.pi/SYSTEM.md` is silently ignored.
|
|
- `--approve` is required for anything under `.pi/`.
|
|
- A tool without `promptSnippet` is callable but invisible in the prose tool list.
|
|
- Tools must truncate their own output (50 KB / 2000 lines).
|