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.
3.1 KiB
Working in pi-agent-config
Rules for any agent or person changing this repository.
1. Never commit a credential
models.json, auth.json, trust.json, *.env, *.pem, private keys and any
*.rendered* file are ignored, and scripts/verify-no-secrets.sh blocks them as
a pre-commit hook. Do not use --no-verify. If the guard fires on a genuine
false positive, fix the file (use a ${PLACEHOLDER} and a *.template suffix) or
add a narrow, commented exception to the guard — do not widen it broadly.
Backups contain plaintext keys and must be written outside the work tree.
scripts/pi-backup.sh refuses in-repo destinations.
2. This repository is the source of truth, with one exception
Configuration flows out of here via scripts/deploy-*.sh. Do not edit
~/.pi/agent or ~/pi-workspaces/* directly and then forget to bring the change
back; scripts/pi-diff.sh exists to catch exactly that.
The exception is a scenario whose profile.toml says deploy = "mirror". A
mirror records what a running service already does. It is diffable but not
deployable, and deploy-scenario.sh refuses --apply for it. Promote a mirror
to managed only as a deliberate, separately reviewed step.
3. Verify pi's behaviour; do not infer it from the docs
Several claims in this repository were wrong on the first pass and were only
corrected by running a probe. Examples: AGENTS.override.md does not block
parent-directory context files; PI_CODING_AGENT_DIR does not cover
~/.agents/skills; --no-tools silently disables the entire skills mechanism.
Before asserting a mechanism, prove it:
docs/evidence/probe-harness/collect-evidence.sh
shared/extensions/tests/run-guard-checks.sh
python3 shared/lib/py/tests/test_pi_rpc_smoke.py
All three cost zero model tokens: a single RPC get_state starts the agent,
fires session_start and exits without contacting the provider. Record new
findings in docs/pi-runtime-notes.md with a source quote or a probe result, and
date them — they are version-specific.
Re-run all three after every pi update and update the version banner.
4. Do not restart services from a script
Restarting interrupts a live conversation. Scripts print the command; a human or an explicitly instructed agent runs it.
5. Keep enumerations in code, not in prose
Intent values, verdict scales, field names and tool schemas must have one owner.
The scenario backend defines them, exports JSON Schema, and the extension
consumes that schema (registerTool accepts a plain JSON Schema object). Prose
describes policy; code defines shape.
A rule written in three places will drift. It already did once: the recommendation enum had four values in one file and five in another.
6. Language
Documentation and code comments: English. Anything the model reads as
instructions — SYSTEM.md, APPEND_SYSTEM.md, SKILL.md, prompts — Chinese,
matching the user-facing language.
7. Explain why in commits
These are configuration and security boundaries. A commit that says what changed but not which failure mode it prevents is not reviewable. Reference the measured evidence where one exists.