Files

T

History

Kai f25082223e docs: repository README, contributor rules, scenario template and authoring guide

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.

2026-08-26 23:19:19 -07:00

workspace/.pi

docs: repository README, contributor rules, scenario template and authoring guide

2026-08-26 23:19:19 -07:00

profile.toml

docs: repository README, contributor rules, scenario template and authoring guide

2026-08-26 23:19:19 -07:00

README.md

docs: repository README, contributor rules, scenario template and authoring guide

2026-08-26 23:19:19 -07:00

README.md

Scenario:

Live service: <name>.service. Live workspace: /home/claw/pi-workspaces/<name>.

Checklist for a new scenario

Copy scenarios/_template/ to scenarios/<name>/ and fill every <PLACEHOLDER> in profile.toml.
Write .pi/SYSTEM.md — all six sections. The replacement branch supplies no tool list and no guidelines.
Write .pi/APPEND_SYSTEM.md for durable domain responsibilities.
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.
Drive it from shared/lib/py/pi_rpc.py rather than spawning pi --print per message.

Verify before deploying:

scripts/deploy-scenario.sh <name>          # dry run
shared/extensions/tests/run-guard-checks.sh

Deploy and restart yourself:

scripts/deploy-scenario.sh <name> --apply
systemctl --user restart <name>.service

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).