dorf
AGENTS.md3 starsChanged 5 days agoApache-2.0View on GitHub
The North Star owns the product, its shape, vocabulary and boundaries, and what was deleted with the conditions to add it back. Push back on changes outside it. Slices owns the plan, each slice's proof, and carry-over facts. - TypeScript on Node, with Bun for installs and scripts. Pin dependencies exactly and install with bun install --frozen-lockfile --ignore-scripts. - Build on Pi Durable the way its README and packages/durable/test/examples do. Read the matching example before adding host-side state or a…
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.
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 16
Only the gate (apps/gate) and deployment files use Substrate terms (Actor, Worker, Atespace, ActorTemplate).
- Very specific: line 22
Use gh for GitHub repository operations.
- Distinctive: line 27
Run these from the repository root.
- Distinctive: line 48
Commit with the Sandbox's git identity, in Conventional Commits whose subject states the impact.
- Very specific: line 49
When the change touches only apps/agent, apps/web, docs or .agents/skills, adds no bunfig.toml or .npmrc, and check and proof pass, push to …
- Very specific: line 58
When something about Dorf got in your way, or you found a problem you did not fix, file it with gh issue create --label friction, …
- Distinctive: line 69
Before committing, review the staged diff for confidential information.
≈ “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
Dorf Guidance
Authorities
The North Star owns the product, its shape, vocabulary and boundaries, and what was deleted with the conditions to add it back. Push back on changes outside it. Slices owns the plan, each slice's proof, and carry-over facts.
Development
- TypeScript on Node, with Bun for installs and scripts. Pin dependencies exactly and install with
bun install --frozen-lockfile --ignore-scripts. - Build on Pi Durable the way its README and
packages/durable/test/examplesdo. Read the matching example before adding host-side state or a new mechanism. The package ships no examples; read them inearendil-works/piat the tag of the pinned version, sincemainhas features it lacks. - Only the gate (
apps/gate) and deployment files use Substrate terms (Actor, Worker, Atespace, ActorTemplate). - One concept per file. Keep a module as a file until a second caller needs it; extract a package only when a second app imports it.
- Tests use Pi's faux model. Never put real model keys in tests, examples or CI.
- Prove a slice with the one command its row in Slices names.
- Use
ghfor GitHub repository operations. Write Markdown issue and PR bodies to a temporary file and pass it with--body-file.
Check and prove
Run these from the repository root.
| Command | What it does | Time in a Sandbox |
.agents/setup | Installs every package from its lockfile; safe to run again | seconds |
bun run check | Types of every app, and oxlint with the anti-slop rules in tools/oxlint over all of them | seconds |
bun run proof | The proofs its script in apps/agent/package.json names, with the faux model, against local stand-ins of the gate | under a minute |
deploy/proof.sh <name> | One file of apps/agent/test against a cluster running Substrate; needs kubectl | minutes |
bun run proof needs no cluster and no credentials, and CI runs it on every push. Its stand-ins
give each Sandbox a folder on one machine, so it proves the agent, not Substrate. What only
Substrate does is proved by the test files that call needSubstrate(). Say which you ran.
In a Sandbox
A Thread working on Dorf runs in a gVisor Sandbox: Node, Bun, git, gh, curl, and a headless Chromium
that the browser-harness skill drives; no kubectl, no Docker and no namespaces, and no way into
the cluster. Run bun run check and bun run proof as you work.
Ship
- Commit with the Sandbox's git identity, in Conventional Commits whose subject states the impact.
- When the change touches only
apps/agent,apps/web,docsor.agents/skills, adds nobunfig.tomlor.npmrc, and check and proof pass, push tomainand follow its CI run withgh run watch.deploy/follow.shholds every other unsigned change, and every commit after it, until the owner signs. If CI fails, fix it forward at once. Main deploys on its own a minute or two after CI passes; the newest ofgh api repos/{owner}/{repo}/deploymentsand its statuses say whether your commit is live, held or rolled back. - Push any other change to a branch and say which Substrate proof it needs: the gate, the Sandbox image,
deploy/, CI and this file wait for the owner until staging exists. - Reply with the
show-meskill: the smallest picture that proves the change, sized to it, with as little text as it needs. Write commit messages with theproseskill. - When something about Dorf got in your way, or you found a problem you did not fix, file it with
gh issue create --label friction, describing the behavior in generic terms.
Public repository confidentiality
This repository is public. Commit only reusable product code, documentation, and synthetic verification data. Keep private application or customer names, repository and issue links, conversation or task details, operational identifiers, deployment addresses, and cleanup records out of tracked files and commit messages. Store deployment-specific evidence in the owning private repository or untracked local receipts; describe the reusable behavior here in generic terms.
Before committing, review the staged diff for confidential information. Before pushing, review all unpublished commits, including earlier versions of changed files. Removing private details from the latest tree alone does not remove them from Git history. If unpublished history contains private details, sanitize that history before publication. Never publish credentials or user content.
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.

