agentleFS
ArylmeraArylmera/Geneseed/AGENTS.md

Geneseed

AGENTS.md1 starsChanged 34 days agoMITView on GitHub

Geneseed generates agent-harness configuration — laws, doctrines, skills, agents — from src/ and themes/, and installs it into host tools (Claude Code, OpenCode, Bob, OpenClaude). It ships as an npm package and as a plain git clone that self-updates with git pull. Start with js/README.md — the module map, and the "where do I add X" table. For what an addition costs, docs/extending.md is the standing answer. There is no npm test. Run these by hand. typecheck is tsc --noEmit…

  • Reads credentials
  • 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 repository2 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

7 rules. About 1 is common, 0 are distinctive, and 6 are very specific to this project.

  • ≈1

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After 30 minutes (GENESEED_HEAVY_WAIT_S) it gives up with exit 75 and QUEUE TIMEOUT — not a test failure: nothing ran, so nothing is red.

    line 41
  2. Very specific:

    Run it after touching an OpenCode plugin, a host emitter or the hook binary.

    line 86
  3. Common:

    No real model is ever called, and there are no credentials in the sandbox.

    line 91
  4. Very specific:

    Expected values are written out, not recorded: Every table in tests/ states its answers in the file — tests/unit/text_layout.test.mjs and …

    line 125
  5. Very specific:

    After a rebuild, geneseed web restart, not a browser refresh: the daemon serves the index.html it launched with.

    line 134
  6. Very specific:

    Rule ids are permanent; numbers are positional: Every law and doctrine rule is declared ### {{LAW:<id>}} <Principle> / ### …

    line 211
  7. Very specific:

    Never rename an id; a removed one goes into RETIRED_RULE_IDS (js/build/source.mjs) so it is never reused.

    line 215

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Geneseed — working in this repo

Geneseed generates agent-harness configuration — laws, doctrines, skills, agents — from src/ and themes/, and installs it into host tools (Claude Code, OpenCode, Bob, OpenClaude). It ships as an npm package and as a plain git clone that self-updates with git pull.

Start with js/README.md — the module map, and the "where do I add X" table. For what an addition costs, docs/extending.md is the standing answer.


The three binaries, and how to tell them apart

bin/geneseed-cli.mjsgeneseed — the user-facing CLI. 20+ verbs, parsed from js/cli-table.json. May not spawn (transitive child_process ban; doctor's node --check is the one allow-listed exception)
bin/geneseed-hook.mjsgeneseed-hook — what the emitted settings.json invokes on every tool call. Six verbs, refuses everything else by name, ~14 ms to load
bin/build-driver.mjsgeneseed-build — the generator. Render flags (--emit/--theme/--footprint/--out/--sync-themes) and the emit targets. Also under a hard child_process ban

Proving a change

There is no npm test. Run these by hand.

npm run lint
npm run typecheck

typecheck is tsc --noEmit with checkJs over js/ and bin/: nothing is emitted, a fix is a JSDoc annotation, and strict is off (tsconfig.json says why).

node tests/heavy.mjs suite

One heavy proof per machine. The suite, the fuzz run, host_canary.mjs, golden.mjs and mutate.mjs --all each go through tests/heavy.mjs, which holds a machine-wide lock (~/.cache/geneseed/heavy.lock) while it runs them. Several agents once ran three suites and an eight-shard golden.mjs --cli at once: the PC stopped answering, and a suite went red on load timeouts. A second heavy proof now waits its turn and then runs, printing the holder as it waits. After 30 minutes (GENESEED_HEAVY_WAIT_S) it gives up with exit 75 and QUEUE TIMEOUT — not a test failure: nothing ran, so nothing is red. A lock it cannot make (an unwritable ~/.cache) exits 71 with SETUP ERROR — not a test failure. Because it may queue, launch a heavy proof with run_in_background (it counts for the done gate once its notification says it finished) or with a long timeout. -- <node args…> passes any other command through verbatim. CI keeps the raw commands below: it runs one job per machine.

suite runs node --test --test-concurrency=8 --test-reporter=tap "tests/**/*.test.mjs". Quote the glob — node expands it, not the shell — and keep --test-reporter=tap: CI gates on the reported count, not the exit code, because node --test over a glob that matches nothing prints # tests 0 and exits 0. A gate that fails open. --test-concurrency=8 because the suite mostly waits on child processes: the default (cores − 1) took 151 s on 4 cores, 8 took 100 s. On Windows it buys nothing (spawning is CPU-bound there), so CI and suite leave Windows at the default.

node tests/shim_intact.mjs

Right after the suite: the only check that no test touched the machine tier (~/.config/geneseed) or left the machine-wide hook shim pointing at a deleted temp directory (which silently kills every hook on the machine).

node tests/heavy.mjs -- --test --test-reporter=tap "fuzz/*.fuzz.mjs"

Fuzzes the hook gates' stdin through the real entry point (a process per case, so it is outside the unit glob). Run it after touching anything under js/hosts/hooks* or bin/geneseed-hook.mjs; FUZZ_RUNS=500 for a longer search. Coverage runs in CI (c8, informational).

node tests/heavy.mjs -- tests/host_canary.mjs

Installs the real hosts from npm (~600 MB): OpenCode V1 and V2, Claude Code, and OpenClaude. It points each at a throwaway home holding what this checkout installs, and fails on the host's own verdict:

  • OpenCode logs failed to load plugin for one of ours.
  • OpenCode writes a key file the guard must refuse. A scripted model on loopback (tests/helpers/fake_model.mjs) asks opencode run for .ssh/id_rsa and then allowed.txt: the first must be absent, the second must hold ok, and the model must be sent the refusal. --no-guard is the mutation proof.
  • claude doctor lists an invalid setting in our settings.json. Claude otherwise ignores a bad hook entry silently.
  • A logged-out -p run shows no SessionStart running our context hook.

Run it after touching an OpenCode plugin, a host emitter or the hook binary; --only <host> narrows it. It is the only check that meets the hosts themselves: every other gate compares the code with itself or with a mock, which is why OpenCode 2 refusing all seven plugins survived a whole-repo refactor pass. CI runs it weekly against latest (.github/workflows/host-canary.yml).

No real model is ever called, and there are no credentials in the sandbox. On OpenCode the only provider is that loopback stub, so the guard's deny runs for real on V1 (a thrown error) and on V2 (a renamed tool call, which depends on the host). On Claude Code and OpenClaude every provider URL points at a closed port: the canary proves what loads there, and no gate verdict that needs a model turn is exercised. Bob is not covered, because IBM does not publish Bob Shell on npm.

node bin/geneseed-cli.mjs doctor --all
node tests/heavy.mjs -- tests/golden.mjs

Runs all 268 emit configurations and requires each to render without crashing. Run it after anything that touches the emit path. Its --idempotent mode re-emits into the same tree and requires the second pass to change nothing; --deletion covers the prune phase. All three are self-comparisons — nothing is measured against a stored answer. --cli runs the ~280-cell CLI/hook matrix against the expectations written in each cell; run it after changing anything a verb prints. --jobs N (default: min(8, cores)) fans the cells out across processes.

node tests/mutate.mjs --verify

Answers only "does every mutation anchor still resolve", writes nothing, takes ~50 ms. Run it after any refactor that moves code — a moved anchor makes a row unappliable, which the matrix scores as a SURVIVOR. --all runs the real 42-row matrix and takes minutes, editing product files as it goes: run it as node tests/heavy.mjs -- tests/mutate.mjs --all. A mode is required (--verify, --list, --all, --only <id>); anything else is refused. An interrupted run leaves one file mutated: the next start of the script, in any mode, restores it from its journal and says so. Check git status all the same before doing anything else.

What bites

Expected values are written out, not recorded. Every table in tests/ states its answers in the file — tests/unit/text_layout.test.mjs and tests/unit/settings_jsonc.test.mjs are the pattern. There is no snapshot directory and no --record: if a change makes a row wrong, change the row and the sentence above it explaining the rule, in the same commit, and say why in the message. A test whose expectation nobody can defend in words is a test nobody can maintain.

web/dist/ is tracked, and must be rebuilt and committed whenever web/src/ changes. It ships in files[] so an install never has to build the UI. git diff alone is not enough to check — vite content-hashes every chunk, so a new lazy chunk is an untracked file git diff cannot see. After a rebuild, geneseed web restart, not a browser refresh: the daemon serves the index.html it launched with.

Runtime dependencies must be vendored, never installed. js/vendor/<name>/, tracked source, relative import. tests/unit/dependency_policy.test.mjs gates it and docs/extending.md §4bis says why — the short version is that fixtures run from the OS temp root and cannot resolve a bare specifier, and neither can a fresh git clone. devDependencies are fine.

The hook path costs ~14 ms per tool call. Anything bin/geneseed-hook.mjs imports is paid on every tool call of every session. And a stray console.log there does not warn you — the hooks signal through stdout JSON and return 0 on every path, so a printed byte turns a blocking gate silently permissive.

A hook's stdout is capped by the host, not by us. Claude Code saves a hook output past roughly 10k characters to a file and hands the model a 2 KB preview — no warning, everything after the cut is gone (observed 2026-10 on 16.5 KB and 25.6 KB SessionStart outputs; the exact threshold is undocumented). So cmdContext keeps its whole payload under OUTPUT_BUDGET (9 000), counting each line at +2 because stdout is \r\n on Windows — a line-per-entry listing overran by its line count before that. Measure a hook change with node bin/geneseed-hook.mjs context --root <install> | wc -c. The OpenCode plugin injects a synthetic user message on every request (experimental.chat.messages.transform on V1, with a visible fallback for the first turn; session.hook("context") on V2), never the system prompt, and has no stdout-style cap at all, which is why its budget stays 48 KB. The Claude hook renders the wiki as the OpenCode plugin does, with the same header lines, inside its own budget: its lazy listing folds and cuts with a count, and it reads no note headings.

Gate logic is copied into the OpenCode plugins by a tool. A plugin is one self-contained file and cannot import js/ or a sibling, so whatever can be byte-identical to its original is a row of TWINS in tests/twins.mjs — that table is the list, do not restate it. Three kinds: a block between marker comments (the loss gate, the gate texts, the shell-write reader with shellReading, the test-weakening rules, the done-check tables, the ownership manifests and refusal texts), one named declaration (runsUnpiped, the fs-only git readers of js/hosts/gitref.mjs) and a one-line constant (.geneseed/.gitignore's text, WIKI_NAMES). The original is in js/, except for the helpers the plugins share among themselves (resolvePath, sovereignBypass, readsTier, …), whose home is geneseed-guard.js. After changing an original, node tests/twins.mjs --write; --check names a copy that drifted, and tests/plugins/helper_parity.test.mjs fails on it. A copy carries its source's house style, so semicolons inside a plugin mark tool-kept text: edit the original, never the copy. What cannot be byte-identical stays a hand twin that names its original in a comment — another payload shape, async where the hook is sync, or deliberately narrower (ownershipBlock, gateConfig, protectedCheck, inferDoneChecks, usageOf) — and a behaviour table in tests/plugins/ holds it.

Every OpenCode plugin serves two plugin APIs from one file. OpenCode 2 loads only export default { id, setup }; V1 (>= 1.3.4) loads { id, server }; each ignores the other's key. So each adapters/opencode/plugins/*.js exports { id: <file stem>, server, setup }, and tests/plugins/helper_parity.test.mjs pins that shape. Nothing can be shared through an extra file: V2 loads every .js in plugins/ as a plugin. And a V2 hook or tool execute that throws is a defect that fails the whole agent step, so every V2 callback swallows its own errors (the guard blocks by renaming the call, not by throwing). adapters/opencode/HOW-OPENCODE-LOADS.md maps each V1 hook to its V2 counterpart.

Uninstall never needs a backup, by construction. A user's root file gets a delimited <!-- BEGIN/END GENESEED --> block (managedBlockWrite/managedBlockRemove, js/hosts/settings.mjs); settings and opencode.json(c) are merged key by key and refused when commented; skills, agents and .gitignore are claim-on-create (claimer, js/hosts/native.mjs) and uninstall deletes only manifest-owned paths. The user decided (2026-10) that this is enough — do not add a snapshot/restore layer.

--force reaches only a path Geneseed ships. It is one build's instruction, never recorded. It turns claimer's two refusals into overwrites and removes retired leftovers, each named. A file under a name Geneseed does not ship is the user's and no forced path may write or remove it (the user decided, 2026-11). An emit records what it kept (kept in the manifest, kept/stale in a bundle's marker); leftoversOf reads that for the console's notice and its forced rebuild.

--exclude-skills filters in ONE place: renderAll (js/build/render.mjs). Every host's emit, the command layer and the plain bundle read the filtered items, so a new host gets the exclusion for free — do not add a second filter in an emitter. The marker line (Excluded skills:) is written only when something is excluded, so default builds stay byte-identical; excludedSkillsOfDir reads it back and setupBuildArgs elides an empty list. Protected skills are scanned, not listed: linkedSkillIds (js/build/source.mjs) finds every {{DIR_SKILLS}}/<name> link outside the §4 catalogue table, so writing a new link protects its target automatically.

Adding any tracked file fails the packaging suite until it has a row, with a written reason, in the SHIPS or WITHHELD partition of tests/unit/package_manifest.test.mjs.

Rule ids are permanent; numbers are positional. Every law and doctrine rule is declared ### {{LAW:<id>}} <Principle> / ### {{DOCTRINE:<id>}} <Principle> and cited {{LAW:<id>}} / {{DOCTRINE:<id>}} — never by number, which the doctor refuses. The render computes the number from position and renders a citation as the principle's name, so removing a rule rewires nothing. Never rename an id; a removed one goes into RETIRED_RULE_IDS (js/build/source.mjs) so it is never reused. Append anyway where you can: LAW_CLASS, exclusions and the hook ledger keys are still number-keyed (doctor-pinned) — docs/extending.md §2e.

--footprint defaults to lean. A law's lean text is the authored LEAN:else half of its block in src/laws/universal.md — amend both halves, or the amendment does not exist for most installs. A doctrine rule carries the same block in src/doctrines/<pack>.md — amend both halves there too, or the amendment does not exist for most installs either.

Counts are computed — never type one. {N_*} tokens substitute at request time, and only on kind: "concept" pages. README badges and SHIPPED.md are the hand-written exceptions, each with its own doctor arm.

Nothing propagates by itself. Editing src/ changes nothing on any machine until something re-emits, and geneseed rebuild-all is best-effort by contract.

Text adapted from outside is credited, or it is invisible. src/upstreams.json is the one home of each upstream's repo, pinned commit, author, licence and licenseFile. A ported skill or agent carries {{CREDIT:<key>:<upstream path>}} under its purpose line, and the render turns it into an "Adapted from … modified." line in every install. A credited skill also ships skills/<stem>/LICENSE-<key>.txt, a copy of the entry's licenseFile; an agent gets the line only. A vendored folder ships its upstream's own LICENSE and names its key in VENDOR.md (**Upstream key:**). creditProblems (js/inspect/checks-repo.mjs) gates keys both ways, plus the commit and the licence file, and the README ## 🙏 Credits list must name exactly the keys. None of that sees a port nobody marked: unmarked, it is indistinguishable from first-party text. So the token and the entry go in the same commit as the ported text — docs/extending.md §3.

Conventions

Docs format: markdown

ESM only, .mjs, zero runtime dependencies. Docblocks in this repo carry why, not what — they are the reason a maintainer can still understand a decision, and they are worth reading before editing the code under them. When one contradicts the code, the code wins and the docblock is a bug.

Sharpen before you add. Skills rot really fast; keep them lean and sharp. Before adding a skill or an agent, merge, refine or delete one; prefer a lever that already exists (<!-- invocation: user -->, --exclude-skills, --doctrines) to a new mechanism; measure the gain before designing for it. Fewer skills means a shorter always-on list, clearer routing and less to rot.

Ownership

mode: off # Geneseed develops its own ownership Rite; its sessions opt out

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.