ontology-atlas
AGENTS.md156 starsChanged 5 days agoMITView on GitHub
Read only the task's authority. Ontology Atlas is a local-first codebase ontology: what code builds, why it is structured that way, and what changes affect. People and agents maintain the same Markdown frontmatter graph; Git is truth. Atlas adds reviewed product meaning to source evidence. Structural health is not accepted meaning. - docs/ONTOLOGY-ATLAS-SPEC.md §2/§5 is the sole public meta-model. Surfaces must offer typed agent facts and evidence a human can judge and correct. - No backend, login, auth, seed data,…
- Deletes or force-pushes
- Commits and pushes
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 33,315 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 repository28 other files it gives its agents.
- app/AGENTS.mdAGENTS.md
- cli/AGENTS.mdAGENTS.md
- mcp/AGENTS.mdAGENTS.md
- scripts/AGENTS.mdAGENTS.md
- src/AGENTS.mdAGENTS.md
- src-tauri/AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- delegateSkill
- gate-probeSkill
- mergeSkill
- ontology-bootstrapSkill
- ontology-extractSkill
- ontology-field-trialSkill
- ontology-syncSkill
- security-auditSkill
- ui-buildSkill
- ui-proofSkill
- delegateSkill
- gate-probeSkill
- mergeSkill
- ontology-bootstrapSkill
- ontology-extractSkill
- ontology-field-trialSkill
- ontology-syncSkill
- security-auditSkill
- ui-buildSkill
- ui-proofSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
14 rules. About 0 are common, 5 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
9
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
- Distinctive: line 3
Read only the task's authority.
- Very specific: line 14
No backend, login, auth, seed data, API routes, or server actions.
- Distinctive: line 34
Check git status; preserve unrelated changes and active processes.
- Very specific: line 37
Use pnpm checks:changed for candidates.
- Distinctive: line 42
Write a report for a reader who saw none of the tool calls or files: lead with what is now true, use full sentences and the same word for …
- Very specific: line 49
Write no plans, retrospectives, handoffs or notes into the repository or ~/scratch.
- Very specific: line 75
Before reversing an existing product or architecture choice, find it with pnpm decisions:find <terms> and cite or explicitly overturn it, …
- Distinctive: line 84
Read the named authority only for its subject:
- Very specific: line 104
Before unfamiliar meaningful work, read list_kinds, narrow list_concepts, and get_concept.
- Very specific: line 117
Keep the owner document current: public behavior in README.md and docs/FEATURES.md.
- Very specific: line 121
Never edit frozen history (docs/records/README.md).
- Very specific: line 125
Use English conventional commit subjects.
- Very specific: line 136
Run pnpm agents:check after editing agent files.
- Distinctive: line 139
Do not change Claude files while optimizing Codex instructions.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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
AGENTS.md — ontology-atlas
Read only the task's authority.
Product and architecture
Ontology Atlas is a local-first codebase ontology: what code builds, why it is structured that way, and what changes affect. People and agents maintain the same Markdown frontmatter graph; Git is truth. Atlas adds reviewed product meaning to source evidence. Structural health is not accepted meaning.
docs/ONTOLOGY-ATLAS-SPEC.md§2/§5 is the sole public meta-model. Surfaces must offer typed agent facts and evidence a human can judge and correct.- No backend, login, auth, seed data, API routes, or server actions.
output: 'export'is intentional. The macOS app carries MCP;mcp/andcli/also run from source. There is no npm package. src/follows app → views → widgets → features → entities → shared; rootapp/is thin Next routing.- The renderer is custom canvas-2D
ontology-map; one WebGL2 light layer draws light only; three.js paints Neural alone, canvas 2D its fallback; Graphology supplies ForceAtlas2 only. Another renderer needs a decision. - MCP internals split by responsibility.
- State is React/URL/in-memory; IndexedDB stores only the vault handle. App and web share parser/data contracts, not identical screens.
Working and finishing
Deliver what was asked, at the scope intended. Make routine judgment calls yourself; ask only when readings lead to materially different work or new authority is needed, and name the decision and rule that cause the pause. If a better approach exists, say so in one sentence and continue as asked. Reuse decisions and approval while their content and conditions still hold.
Check git status; preserve unrelated changes and active processes. Use native
search and targeted file reads for source and change-impact questions.
Use pnpm checks:changed for candidates; run only checks needed for the
change and its risks. Escalate on evidence, keep required CI, and do not repeat
passing checks. This overrides conflicting test instructions.
.claude/rules/testing.md owns test shape. Report evidence and limits.
Write a report for a reader who saw none of the tool calls or files: lead with what is now true, use full sentences and the same word for the same thing, define any name coined during the work, and say what was not done or checked. During a long turn, say in a line what you are doing every few tool calls.
A fact the source can answer comes from a script: run or extend the pnpm
command (README's command table) and read its output instead of re-deriving it.
Write no plans, retrospectives, handoffs or notes into the repository or
~/scratch; reasons go in commit bodies and pull requests, working files in the
session scratchpad. Skill design: docs/engineering/agent-instructions.md.
Choose the relevant workflow
| Task | Entry and required scope |
| Mechanical maintenance | Technical checks only |
| One-way change: a public MCP, CLI or vault contract; a route added or removed; what leaves the machine; what an agent may write or approve; first-contact positioning | pnpm decisions:find; the person, moment and proof in the pull request; one reviewer; one decision record |
| Any other product behavior or copy | Build it and verify the behavior |
| UI, interaction, topology, responsive, motion, or macOS workbench | /ui-build: build from the primitives and look at each slice with pnpm ui:look; /ui-proof only for the classes its table lists |
| A new or changed automated gate | /gate-probe |
| Initial ontology or explicit rebuild | /ontology-bootstrap; general code analysis alone does not request construction |
| Meaningful code change in an existing vault | /ontology-sync |
| Requested extraction from prose or wiki | /ontology-extract; a wiki page only through the user's registered third-party MCP |
| Construction rules or MCP behavior that can change vault quality | /ontology-field-trial; wording-only changes that keep evidence/approval/write contracts skip it |
| Authorized parallel work | /delegate |
| Returned or ready branches | /merge; your own branch merges with pnpm pr:land |
Delegate only large, independent, parallelizable work; finish what a handful of
tool calls can do yourself, and never delegate to verify or double-check your
own work. Opus builds and investigates; Fable plans, specs, reviews and gives
design verdicts (docs/engineering/agent-effort.md). Disclose shared-context reviews. Subagents do not stash,
delete worktrees, or run git add -A.
Before reversing an existing product or architecture choice, find
it with pnpm decisions:find <terms> and cite or explicitly overturn it, keeping
dissent and a falsifier. A record is context from its date, not proof it still
holds: recheck its conditions and figures against the present before relying on
it. When a document and the code disagree, the code is the fact: fix the
document in the same change. pnpm record:new creates immutable fragments; routine work needs none.
Rendered work and source authorities
Read the named authority only for its subject:
| Subject | Authority |
| Product and inventory | docs/PRODUCT-DIRECTION.md, docs/FEATURES.md |
| Architecture/routes/module ownership | docs/ARCHITECTURE.md, .claude/rules/architecture.md |
| UI values and the rendered-work loop | docs/DESIGN-SYSTEM.md, docs/PRODUCT-DESIGN-OPERATING-SYSTEM.md, .claude/rules/design.md |
| Gates | .claude/rules/design-gates.md |
| Storage/surface boundaries | .claude/rules/local-first.md, .claude/rules/surfaces.md, .claude/rules/forbidden.md |
| Tests, docs, Git | .claude/rules/testing.md, .claude/rules/documentation.md, .claude/rules/git.md |
Routes are locale-prefixed; use @/i18n/navigation. / chooses gateway or
vault-bearing map/first-run; a wiki without nodes opens /library. The app must
not offer its own download. /topology owns map/relation review; ACP writes wait
for allow_once or reject_once. Route additions/removals require a decision
fragment. /ontology, /ontology/edit, /ontology/studio, /ontology/insights and
/mcp are redirects. Check the forbidden rule before reviving a retired namespace.
Source authority and ontology loop
Before unfamiliar meaningful work, read list_kinds, narrow list_concepts,
and get_concept; use find_backlinks before renames and find_path for an
existing relation. Avoid full-vault dumps.
mcp/src/schema.mjs owns schema. UID is immutable and writer-minted; slug may
change. Canonical names use title; localization uses display_<locale>.
Project containment is implicit; do not add project:. Vault writes go through
/ontology-sync and its MCP write contract. A code rename does not authorize a
vault rename, and write success is not meaning acceptance. Typos, comments,
isolated style, lint, and fixtures without meaning changes skip the sync.
Documentation, merging, and instruction integrity
Keep the owner document current: public behavior in README.md and
docs/FEATURES.md; architecture/routes in docs/ARCHITECTURE.md; MCP/CLI
contracts in their READMEs. Authored prose is English; display_ko,
cli/templates/vault-ko/** and README.{ko,ja,zh}.md are localized data.
Never edit frozen history (docs/records/README.md); never edit or stage
generated src/entities/docs-vault/data/ or public/docs-vault/, which
pnpm docs-vault:build writes.
Use English conventional commit subjects. Open pull requests as drafts and merge
only with pnpm pr:land <number>. Never use --no-verify, force-push main,
git reset --hard, or git push --force without explicit user authority.
Publishing needs an explicit request and npm pack --dry-run first.
CLAUDE.md imports this file and owns Claude loading details. Keep root plus
the largest nested instruction file below 32 KiB; nested AGENTS.md files only
point to the .claude/rules/ relevant to their paths, which Codex does not
auto-load. Keep host-specific skill metadata and agent briefs separate. Shared
procedures may have one owner; byte identity is not required. Codex briefs
inherit the caller's model, effort and tools; access defines scope, not a grant.
Run pnpm agents:check after editing agent
files. .claude/settings.json owns Claude hooks and .codex/hooks.json Codex
hooks; Codex skips a new or changed entry until a person trusts it in /hooks.
Do not change Claude files while optimizing Codex instructions.
<!-- BEGIN:nextjs-agent-rules -->This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.
This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
<!-- END:nextjs-agent-rules -->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.

