Agent context

Do not edit managed blocks in AGENTS.md or provisioned files under .agents/. To change shared guidance, update Prayfile and run pray install.

Shared instructions

• package sources in this repository are shared prayers: fragments under exports/, skill bodies, prompt templates, and files under prayers/ follow the same prose and formatting rules as writing-prose and docs-conventions; agents and humans authoring them must not treat prayer text as exempt from plain-prose discipline;
• plain prose readable without a rendered preview: no markdown tables, bold, italic, or other styling; use headings, bullet lists, backticks for technical names, YAML frontmatter, and code fences when the contract needs them; prefer labeled bullets over tables for multi-field rows;
• prefer characters typed from a normal keyboard; no special Unicode punctuation or symbols for structure (arrows, em dashes, ellipsis characters, not-equal signs, curly quotes, section signs); use ASCII (->, -, ..., !=, straight quotes) or plain words; pipelines and flow diagrams are numbered or bulleted lists, or ASCII-only text fences;
• investigation and skill deliverable templates must teach the same plain-prose shape; do not ship emphasis, table scaffolding, or inaccessible glyphs that consumers will copy into docs/ notes or reports;

• when fixing or refactoring code, add or update tests first to expose the current bug/regression path (or missing contract), then implement the fix, then run focused and broader checks, and do not ship behavior changes without proving before/after via specs;
• test only executable logic and user-facing behavior; tests should affect coverage metrics;
• avoid tests that only assert implementation details; avoid file/page content/ordering/regex assertions; avoid duplicating tests;
• user interface texts should never mention implementation technical details;
• prefer files around <=150 LOC when cohesion allows; split only when it improves ownership, readability, and reviewability;
• do not use abbreviations or short names unless they are very common;
• avoid explanatory comments, but allow intent comments for non-obvious constraints, invariants, concurrency edges, or external contract requirements;
• readability, structure, and clarity are product qualities;
• pull request description answers what problem is solved, why it matters, how the solution works, and relevant context; non-trivial changes include reproduction steps or a changelog entry with intent;
• pull request checklist: changelog entry with intent or reproduction steps when relevant, test coverage, and quality checks done;
• follow docs-conventions for docs timestamp-tree filenames and layout;
• report completed actions only with observed evidence; validation output must list exact commands run and observed results;
• ignore style-only dust unless it harms correctness, operability, maintainability, or auditability under realistic load;
• sibling files and executable checks beat shared defaults; mixed styles stay a split until a path boundary explains both;
• fix the cause of a race, not a retry around it; prefer positive names; compute at write when a read cannot paginate; do not change production design only so tests can reach it;
• if process state and local cache files are both cleared, name what must be rebuilt and from which durable source;
• side effects read committed state from a cursor; they are not steps of the write;
• on a store or network hot path, name the expensive unit and keep a before-and-after budget;
• after changing a published number, identifier, or contract field, search dependents and mark them stale or update them; when a published identifier shape changes, search path helpers that pass a string id, not only those that pass a record.

Credentials and Secrets

• Prefer a secret store or OS credential helper over embedding live secrets in config files, scripts, or documentation. Named managers (for example 1Password, Bitwarden, KeePassXC) are fine; the requirement is isolation, not a specific vendor.
• Config and project files may hold references (vault paths, item ids, redacted fingerprints). They must not hold live tokens, API keys, passwords, or client secrets. The same prohibition applies to skill files, prompt templates, and MCP environment settings.
• Do not pass secrets on command lines or in other process-visible arguments. Prefer secret-store lookup, short-lived credentials, or stdin/file descriptors that do not persist in shell history.
• Do not commit secrets, paste them into issues or pull requests, or write them to logs. Rotate anything that may have been exposed.
• if a live secret, credential, or confidential trace appears in this session, treat it as a security event: tell the person, do not quote the value, and do not send it to another third party; the inference provider already saw what reached this session

Tracking and identification

• A redacted fingerprint above is a hash of a secret for config references. A device fingerprint is fields that combine to identify a person or device across sessions or observers.
• Identifiers, IP addresses, device marks, and combined attributes are personal data. They can unmask a person, a location, or a session secret. Emit them only when the feature they asked for this session needs them and they were shown that this product would.
• Silent analytics ids, leftover marks after logout, and canvas or hardware probes are security events. They can locate a person, stitch sessions, or leak a credential-shaped token.

Ownership and destinations

• Lookups go through an ownership set; request parameters pick which row; fail closed when access cannot be proven.
• Treat user-supplied URLs as untrusted; rate-limit authentication and abuse-prone endpoints.
• An invalid or expired credential gets a protocol-level failure status. A hop's own credential is never the caller's. Modes that relax access controls must remain disabled when their configuration is missing or invalid.
• Crawl preferences in robots.txt and Content-Signal style directives declare intent to cooperative clients. They are not authentication, ownership proof, or a technical block. They do not replace rate limits or fail-closed access checks.

Related: engineering-audit security mode asks whether a parameter establishes access and whether a worker skipped policy.

• docs/ holds maintained explanations and working records; use stable descriptive filenames for guides; placement does not imply polish or currency;
• keep inference input (AGENTS.md, .agents/) separate from docs/; conventions that matter fail a command;
• usr/ is the workshop for working tools and operational material;
• usr/scripts/ holds maintainer scripts invoked from a checkout, Makefile, CI, or a runner on a named path; not paste-into-live-console support or migrate work;
• usr/reports/ holds read-only analysis and investigation console scripts; no mutations;
• usr/support/ holds product and customer support console scripts that mutate or write; a person pastes or runs them after review; programmable agents do not run them against a live process;
• usr/migrate/ holds schema and data migration scripts for manual running before new code is on the process; later schema migrate is schema-only and idempotent;
• six docs/ timestamp trees, no README index, filename YYYYMMDDHHMMSS_<kebab-case-title>.md: plans (uncertain future: design-only notes before work is committed), issues (certain current: live work in play; contract, findings, open next; the open queue stays here), reviews (one review episode: session or CI scope, coverage, recommendations, outcome), changelogs (factual past: what shipped), meetings (one sitting: who was there and what they agreed), dependencies (upstream defects from real work);
• issues, reviews, changelogs, and meetings make five things findable with ## headings or equivalent: Participants (humans), Decisions (what was agreed), Effects (done, failed, recovered, rolled back), Next (todo, planned, open questions), Source (links upstream and downstream);
• name the current operator under Participants when the current session provides their display name or that person confirms it; solo sessions still get one Participants line;
• if the current operator cannot be identified without inference, omit Participants rather than guess from git configuration, commit history, filesystem paths, OS accounts, or login names;
• list other humans who decided or reported in that episode when known; do not list agents, tools, binaries, or every person who touched related code;
• omit other empty sections; git history is the edit log; add an explicit note only when a later pass changes meaning (scope cut, rollback, decision reversed);
• Problem / Fix and similar ticket outlines do not replace the five headings; map that content into Decisions and Effects; keep Participants, Next, and Source as their own headings;
• mention software, tools, agents, or binaries in a note only when that detail is needed for execution or later analysis; put it under Decisions, Effects, or Source, not under Participants;
• never put local absolute paths or private material in docs/ or under usr/: no home-directory or machine-specific filesystem paths, secrets, credentials, tokens, API keys, or personal private data; prefer repository-relative paths;
• one home per fact; link, do not duplicate; goal and acceptance live apart from operating rules; when a decision changes shape, supersede it in place; name what the product does not do next to what it does;

Writing and changelog prose checks

Review for marketing language, invented objections, empty contrasts, stray em dashes, and paragraph flow; keep notes and metadata honest and plain.

• docs timestamp trees, shared prayer sources (fragments, skill bodies, prompt templates, files under prayers/), and agent deliverable templates: plain prose readable without a rendered preview. No markdown tables, bold, italic, or other styling. Prioritize factual accuracy over presentation.
• Prefer characters typed from a normal keyboard layout. Do not use special Unicode punctuation or symbols for structure or emphasis: no Unicode arrows, em or en dashes, ellipsis characters, not-equal signs, curly quotes, section signs, or similar. Use ASCII stand-ins (->, -, ..., !=, straight " / ') or plain words (then, section). Do not draw pipelines or diagrams with inaccessible glyphs; use a numbered or bulleted list, or a text fence with ASCII only.
• Ease, lexical diversity, coherence, mechanics, and claim integrity are separate constructs. Automated matches, readability grades, similarity, and model preference are review prompts; preserve meaning, necessary negation, scope, and uncertainty when editing.
• Keep agency on the person who acts. Tools and process nouns do mechanical work.
• Technical names, APIs, CLI verbs, RFC titles, identifiers, and UI copy use instrument and protocol words: check-in, last-seen, probe, monitor, expected tick. Body and organism metaphors such as heartbeat, pulse, and organ stay out of contracts and code. HTTP /health remains the liveness probe until a later RFC.
• One sentence holds one beat. Consecutive short sentences that only restated the same beat are a punchline stack.
• For material external claims, quotations, dates, or research summaries, use the claims-audit skill.
• signed comments on a public tracker speak as the account holder to the named person; chat stays in chat
• cite only what a public reader can open and check; confidential traces, unique working locators, and unverifiable session evidence stay in chat; do not expose source material that is not already public, and do not post source material without the person's consent
• greeting names the person, then a short body, a close, and the name from the tracker identity; first person when that person did the work
• one primary commit, pull request, or release link; comment when asked; do not close, assign, or reopen unless asked

Related: security forbids secrets in issues and owns the session notice when confidential material hits inference.

Likely rejected changes

• features whose complexity outweighs user value
• giant refactors
• non-trivial changes without tests
• style-only rewrites without behavior change
• AI-generated-looking code the author does not understand
• compatibility aliases, shims, and legacy input shapes that remain accepted even though the change should remove them

Checks before publish (engineering)

• verify the change is wanted; discuss first for unconfirmed larger features
• describe what problem is solved and why it matters
• include tests
• add screenshots or screen recordings for UI changes
• keep one pull request to one concern
• understand any AI-assisted code you submit
• review generated changes before requesting revisions; write review replies from the author's own understanding

Collaboration workflow

• record durable project value in the live-work queue, including improvements to shared guidance or a skill;
• keep only decision-bearing material; omit generic notes, copied chat, and filler;
• use the lightest trace that preserves context; design-only work needs no branch unless implementation starts; put that exploration under docs/plans;
• follow docs-conventions for docs/ and usr/; when encoding how this tree writes, use infer-conventions.

Dependency policy

Rules for adding, changing, or removing third-party packages. Apply across languages. Names vary by ecosystem; concepts do not.

Terminology:

• package manifest - declares intent (gemspec, package.json, Cargo.toml, mix.exs, etc.)
• lockfile - pins the resolved graph CI and developers install
• registry - published versions consumers resolve (RubyGems, npm, crates.io, Hex, etc.)
• hot path - code on the security, auth, crypto, IO, or request/response boundary users rely on

Stop until one of these applies before adding a dependency:

• stdlib or the framework for this tree already covers it;
• an installed transitive dependency already covers it without a second library for the same job;
• the feature needs a new package and tests will prove behavior.

Run dependency-audit for direct dependency changes, graph audits, releases with hot-path package changes, and plausible dependency vulnerability or exploitation signals found during ordinary work. Keep the evidence and assessment in the live-work or dependency record.

On resolved lockfile graph or runtime-pin upgrades (automated or human), gather before/after resource samples for install or graph storage, resident memory, CPU or a stated proxy, and shipped bundle or image size when the product ships bytes. The reviewing agent uses isolated checkouts and the same small consumer-owned measurement commands for both revisions. It reports the comparison and writes to a change request only when authorized. Cheaper or smaller without comparable samples is inference. Continuous absolute ship-path ceilings stay in delivery-budgets.

Related: dependency-issues records upstream defects found during real work; minimal-implementation covers YAGNI before adding deps; engineering-audit covers code and pipeline review; delivery-budgets owns continuous size and build-timing gates; pressure-benchmarking owns load ladders and ceiling ratchet episodes, not one-change upgrade deltas.