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.
75 lines
3.1 KiB
Markdown
75 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.
|