pi-state-flow
AGENTS.md7 starsChanged 2 months agoMITView on GitHub
The relocation ledger maps every pre-compaction paragraph to its owning contract or test. Keep this file as durable development policy, not a second copy of the product manuals.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- .agents/skills/domain-dag/AGENTS.mdAGENTS.md
- domain-dagSkill
- state-flow-guideSkill
- state-flow-memorySkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Keep one opaque composed causal lineage, anchored checkpoint/tail materialization, configured hot-history folding and independent owner …
- Distinctive: line 17
Keep the public module registration boundary native-host-scoped and revocable.
- Distinctive: line 23
Keep exact regular-file, byte-CAS and lock-serialized publication with cancelable waits, single-use callback-scoped capabilities and …
- Distinctive: line 38
Keep Skill acquisition optional and exact-path/provenance-derived.
- Distinctive: line 40
Keep opt-in diagnostic categories, failure elision/privacy and barrier-only names-only records outside canonical state.
- Distinctive: line 41
Keep public patch outputs and staged drafts detached from caller/accepted values.
- Distinctive: line 42
Do not add project schemas, state/patch byte caps, dynamic growth pressure, action authorization, automatic reference hydration or strict …
- Very specific: line 49
Keep opt-in measurements under benchmarks/, excluded from normal tests/packaging, with source-bound workload identities.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Instructions
The relocation ledger maps every pre-compaction paragraph to its owning contract or test. Keep this file as durable development policy, not a second copy of the product manuals.
Ownership and semantics
- Require matching Pi coding-agent, agent-core, AI and TUI packages at ≥1.0.0; pin the local verification stack to 1.0.0 and preserve the documented limits of fixture evidence.
- Keep
index.tsminimal, independent domains inlib/with same-named tests, architecture checks intests/invariants.test.ts, and Pi lifecycle composition inlib/extension.ts; delegate low-level mechanics to their owners. Keep domain cases in their owning mirrored test surface, not new root suites named after features, selection modes, checkpoints or individual bugs. Admit only a small explicit set of genuinely cross-domain/compatibility exceptions with ownership reasons; fixtures are support, not hidden test suites. Enforce both module-to-test presence and test-to-owner/justified-exception placement in the existing invariant checks. See composition. - Keep Off the genuinely new-session default, with Passive and Active opt-in; Off removes State Flow model tools/context without deleting memory. Modes belong to the current session; global mode is only a new-session default. Passive declares both tools even without memory, but contributes protocol/projected state only with a validated view. See mode behavior and configuration.
- Preserve Pi's native tool loop, trace and foreign context; the context domain alone projects the raw scope overlay. Freeze/rebase the head only at specified boundaries, retain current-run trajectory and stable-position tail notices, and never give projection IDs or guessed user anchors publication/compaction authority. See Pi lifecycle and projection evidence.
- Store only present built-in
intents,strategy,tactics,artifacts,response,lazyfields plus metadata4-declared external object planes; preserve nonempty nested data and retained causal identities. Normalize empty object fields/planes only in supplied scopes and response-owned Session, before ownership and after cascades/compilation; preserve array slots and exact current/historical reads. Model projection may omit legacy empty branches. Missing planes and empty response do not become fabricated stored defaults; malformed evidence fails closed. Keep lazy bodies out of automatic projection and Session as the sole author of new responses. See semantic state and temporal model. - Respect global → CWD → session ownership, scope-local deletion and inherited fallbacks; scope does not confer instruction authority. Registered Skill ownership follows Pi source provenance, not path shape. See semantic state and artifact routing.
- Artifacts name exact registered source paths; observe only regular non-symlink files, never discover directories or read unrelated bodies. Preserve hidden per-scope provenance, exact-owner compilation, stable fingerprint checks and separate Skill hashes; unavailable sources are not proof of deletion. See artifact routing.
- Preserve session config/runtime, per-scope metadata, lineage and provenance outside model-patchable state; decode legacy mode evidence read-only, never mix representations or normalize storage eagerly. See storage and identity and mode compatibility.
- Keep one opaque composed causal lineage, anchored checkpoint/tail materialization, configured hot-history folding and independent owner revisions; never invent earlier history or rebuild discarded offsets. Historical reads are observational, and
effective[n]/owner materializations select the same causal boundary. See temporal model and model tools. - Keep the internal semantic-module contract package-owned and separate from storage/native authority. Module candidates are not accepted publications; immutable means main-agent read-only, not producer-frozen. Preserve the single intent-first engine and current dialect; no runtime discovery, public registration authority or automatic inference follows from an internal module identity.
- Keep the public module registration boundary native-host-scoped and revocable. A registration/catalog grants no source, private or publication authority. Follow its explicit compatibility decision before admitting external stored roots; unavailable-module data must never be dropped through filtering or normalization. Pi remains the loader.
Publication and lifecycle
- Keep one Strategy/Tactics model/API across metadata3 core cohorts and metadata4 retained-module cohorts. Translate declared legacy v1/v2 cohorts before filtering; reject raw collisions and target-format retired roots. Only owned semantic acceptance may convert, after verified exact-byte backup and CAS; inspection and runtime-only mode persistence cannot. Preserve revisions/causal identities and opaque recovery bytes; semantic decoding must reject invalid UTF-8. Quiesce unsupported old writers. See migration and backup.
- Treat canonical scope files as semantic authority and Git only as optional backup. Classify complete, wholly absent, partial and malformed cohorts before recovery; absent shared pairs may initialize only under accepted authority, while incomplete/private evidence fails closed. Never repair through ad-hoc writes. See storage recovery and transaction rule.
- Keep exact regular-file, byte-CAS and lock-serialized publication with cancelable waits, single-use callback-scoped capabilities and guarded rollback. Never hold exclusion across inference, source acquisition or Git; do not steal interrupted locks, claim kernel-atomic multi-file publication or promise power-loss durability. See asynchronous transaction and durability boundary.
- Attach Off branches through native policy bookkeeping only, deferring memory acquisition and recovery diagnostics until explicit Passive/Active. Preserve pending Off forks across cold reload with child-owned native markers, without reading the parent header/store until acquisition. Memory never depends on the Pi step: it is the current same-session JSON state, advanced only by accepted
state_flow_patch/lifecycle publications. Startup, reload, resume and tree navigation validate and accept current same-session memory; native checkpoints supply only mode and run lifecycle, never a revision to rewind to. A fork copies its parent's current memory into a fresh child owner. Never substitute empty, Git, foreign or fabricated memory when current files are missing, corrupt or contradictory. Only accepted candidates install cache, checkpoint and mode. Unreadable current memory under Active retains Active policy, visibly reportsactive (blocked)and fences live inference through public Abort until accepted Active/Passive or explicit Off; never silently expose native history or an inactive indicator as fallback. See Pi lifecycle and fork contract. - Persist each material semantic change and its affected revisions exactly once, including accepted Session responses. Optional settled-turn Git backup may capture only already-accepted owned files, leave unrelated index/worktree data intact and push without force or semantic side effects. Defer busy backup when the host provides no settlement operation signal rather than blocking Abort; never move it to
turn_endor add a durable push queue. Off cancels owned captures/pushes and suppresses late reporting; normal agent-operation completion must not cancel an independently admitted push, and foreign callers' pushes retain ownership. See optional Git backup. - Accept one atomic
state_flow_patchcohort across supplied scopes against current shared memory; reject empty scopes, unknown/retired grammar and model-authoredresponse. Correct no-ops create no transition. Enforce the single-call inference barrier before sibling tools execute and retain conservative model-facing reconciliation when a result cannot be predicted. See model tools and Pi lifecycle. - Reconcile the actual accepted ordinary answer at
turn_endwith response-owned cancellation and one accepted lifecycle publication; do not request private repair inference, ceremonial finalization patches or roll back accepted memory after cancellation. See Pi lifecycle. - Capture specifications without writes at
before_agent_start, then await one cancellable preparation acceptance before active inference; abort failed context preparation through Pi's public hook. Keep user text at user authority and state as fallible data. Preserve an existing conversation for exactly one bootstrap run, not forever. See Pi lifecycle and pre-inference cancellation. - Make Start await coherent current-head acceptance; unaccepted Off-to-Active retains deferred history and cannot confer current-memory authority on a superseding Passive choice. Passive selects local policy before asynchronous runtime-only persistence; preserve its independently owned fork/restoration work. Off instead cancels owned memory waits, clears semantic caches and records only native mode/continuation/fork bookkeeping without canonical I/O. Preserve already accepted publications and carried write fences; failed Passive persistence uses a native fence, never a substitute semantic checkpoint; a later explicit Passive retries current-memory acceptance and clears the fence only after acceptance. Off exposes no frozen handoff. See lifecycle planes and lifecycle operations.
- Request completed-history native compaction only after an accepted non-bootstrap settled run, public usage ≥24,000 tokens and a uniquely captured first-user anchor; retain the complete latest run and foreign context. Use per-request owned markers, cancel stale/inactive owned hooks without default summary fallback, and prevent old completion from clearing a new plan. Await its native callback before returning, and leave Pi manual/threshold compaction and append-only history alone. See lifecycle planes.
- Contribute only State Flow's compact normative system-prompt section through Pi's section membrane; refresh it with current mode without overwriting foreign sections, forced-prompt precedence or native message identities. Never invent a continuation scheduler. See lifecycle planes and host context compatibility.
Model and operator boundaries
- Advertise only
state_flow_readandstate_flow_patch; retain explicitread_state/patch_statedispatch compatibility. Both spellings are one owned read/mutation operation for selection, schema refresh, activation, exact native admission, nested refusal and the Active single-mutation barrier, including mixed aliases. Do not rewrite historical calls or treat tool-name compatibility as semantic-field aliases. See tool-name compatibility. - Treat state as a decision-relevant handoff, not a transcript: distinguish user requirements, confirmed decisions, observations, hypotheses, chosen intents and remaining checks. Revalidate volatile external effects before repeating actions; memory is neither an action ledger nor proof of current reality. See operational guidance and the memory Skill.
- Resolve semantic
$paths and structured references only when needed; never confer authority or existence by reference alone, scan to find broken references, automatically search all history or restore deleted values from hints. Sole exception: a structured{"$ref"}inside anintentsentry owns its same-scopestrategy/tactics/lazyobject-key target. In fixed semantic order independent of JSON insertion order, apply intents first, clear deleted intents' eligible targets unless a final remaining/new same-scope intent references the target, an ancestor or a descendant, then apply remaining authored planes before existing compilation/normalization and atomic publication. A rewrite at a cleared same/new path is fresh knowledge without old fields; unowned entries remain legal.cascadedrecords intermediate cleared paths even if recreated; final effective values are authoritative. Replay accepted explicit net patches without rerunning cascade; existing strategy references own future accepted intent deletions, never rewrite history. That bounded read of one scope'sintentsplane never validates, rejects, warns, archives or crosses scopes; textual$pathmentions and structured references outsideintentsstay non-owning. See model tools, intent ownership and lazy navigation. - Keep Skill acquisition optional and exact-path/provenance-derived; successful reads alone are volatile, and attempted durable compilations require scoped validated output plus runtime-owned hash evidence. See artifact routing.
- Reconcile touched state without automatic whole-store audits. Dedicated curation needs a user request; intra-store moves use one verified multi-scope patch, and external transfers need verified destination acceptance before source deletion. See operational guidance and the memory Skill.
- Keep opt-in diagnostic categories, failure elision/privacy and barrier-only names-only records outside canonical state; logging failures cannot change accepted state. Preserve a blank line between every tool name and its output. See diagnostic privacy and barrier diagnostics.
- Keep public patch outputs and staged drafts detached from caller/accepted values; private path-copying must not leak mutable objects or weaken CAS. Reject stored null in documented semantic planes while preserving valid nested object-key deletions. See storage and identity and model tools.
- Do not add project schemas, state/patch byte caps, dynamic growth pressure, action authorization, automatic reference hydration or strict boundedness claims for state, the turn specification, the current-run trajectory or Pi's external trace. See model tools and operational boundaries.
- Keep terminal status observational and mode-derived; no source maintenance or invented empty view on inspection. Explicit Off inspection uses disposable current-store readers, validates private/Effective authority, and must not install cache or alter deferred branch/fork policy; automatic callbacks and rejected queued tools remain memory-inert even with logging enabled. Optional Git, Telegram and diagnostics degrade without fabricated success or weakened memory ownership. The optional
lib/telegram.tspresentation leaf alone may consume pi-telegram's public membranes; core semantics/storage/inference remain transport-agnostic. See status and controls and observability.
Delivery discipline
- Keep temporary task briefs, reviews, checkpoints, validation logs and reusable evidence under the project-local ignored
temp/directory, not OS/tmp. Usetemp/README.mdfor human navigation; BACKLOG remains the sole open-work surface and owning/docsretain final contracts. Preserve exact historical bytes and external paths needed by active actors or frozen evidence until they settle; archive their project-local copies without rewriting primary reports. - Keep the exact-tag release workflow as sole npm Trusted Publisher and GitHub Release owner; align version, lockfile, tag and changelog, with no long-lived npm-token fallback. Keep generated
dist/tracked, rebuild after final source/package edits and verify source/build parity and npm inventory. See validation boundaries. - Keep opt-in measurements under
benchmarks/, excluded from normal tests/packaging, with source-bound workload identities. Native scripted-provider tests assert callback completion outside the provider; startup/tree and cancellation fixtures await the right ownership boundary. See benchmark guide and temporal witnesses. - Keep README/docs current rather than copying chronology out of CHANGELOG; preserve SKILL.state attribution for inherited explicit-state ideas. Exercise malformed/predecessor storage only in temporary repositories, never the user's active data. Run
npm run validateafter retained code changes and the canonical ABCd context validator after context edits. See documentation index and validation procedure.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

