wilanis-js
CLAUDE.md1 starsChanged 57 days agoApache-2.0View on GitHub
This is the @wilanis/* workspace. Read this before changing anything; it says where things live and which direction dependencies may point. What is inside a package is read off the package, not kept here: ls packages/<name>/src for its modules, its README for what it is for, and for a plugin npx wilanis describe @<use>/plugin.json example for the settings it takes and what it grants and requires (the example names every plugin, so each resolves there). Dependencies point one way: engine…
- Installs packages
In this repository4 other files it gives its agents.
- coordinateSkill
- reviewSkill
- rfcSkill
- roadmapSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 72
Every directory meets the rules, so npm run lint is the whole story: it fails on a violation rather than warning about one.
- Very specific: line 104
Discoverability: Every refusal has a code, a file, an at path and a hint that names the command or the edit that fixes it.
- Very specific: line 112
A new rule: Add it to its family's module under packages/compiler/src/check/ -- project.ts (C, B at the project, startup), profiles.ts …
- Distinctive: line 213
Do not add features, document kinds, or plugin hooks beyond what a task asks for.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.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
Working on wilanis
This is the @wilanis/* workspace. Read this before changing anything; it says where things live and which
direction dependencies may point.
Layout
packages/ one npm package per directory: engine, core, compiler, runtime, view, and each plugin as plugin-<name>
libraries/ trees a project includes, published as @wilanis/<name>: pure JSON documents, each with its own test/
example/ a consumer project, JSON documents and a package.json; it includes @wilanis/access and uses every plugin
reserved/ names held on npm with no code under them; not workspace members, never built (reserved/README.md)
docs/ the language reference (model.md), the roadmap, the RFCs under rfcs/, the demos
fitness/ the decisions about the code, one claim per file; `ls fitness` is the index (fitness/README.md)What is inside a package is read off the package, not kept here: ls packages/<name>/src for its modules, its
README for what it is for, and for a plugin npx wilanis describe @<use>/plugin.json example for the settings
it takes and what it grants and requires (the example names every plugin, so each resolves there).
Dependencies point one way: engine ← core ← compiler ← runtime ← view, and plugins depend on core and
engine only. The viewer is a tool over a loaded tree, not a plugin: it grants nothing to a tree and
executes nothing; viewOf is pure and the page under client/ is one static file with no build step. A plugin never imports the compiler or the runtime. One plugin may import another only where that other is a contract it implements -- @storage says what a store is and an engine plugin answers it -- and the contract imports no engine, so the arrow still points one way. The runtime never reaches into a plugin's
internals; it sees the PluginModule contract in packages/core/src/plugin.ts. If a change needs an
import against this direction, the design is wrong, not the import rule. fitness/dependencies-point-one-way.fitness.ts
holds it against every manifest, and the engine and the compiler each have a narrower claim of their own.
Tests live beside what they test, in the package's own test/ (fitness/tests-live-beside-what-they-test.fitness.ts).
The compiler's rules have no tests of their own: every checker rule is exercised through the example and its
sabotaged variants in packages/runtime/test/example.test.ts, where a real tree can be broken, and
packages/compiler/test holds only what a tree that passes cannot show (the atomic scope). A test may reach
against the arrow -- the runtime's and the viewer's tests load every plugin, a plugin's tests load the compiler
and the runtime -- only because its package names what it reaches under devDependencies; a src/ file never
imports what its package names only there.
Commands
npm install # links the workspace
npm run build # tsc -b, project references, dependency order
npm run lint # biome: formatting and the house rules (biome.jsonc)
npm run lint:fix # the same, applying every safe fix
npm test # lint, build, then vitest; a plugin's tests only where the change touches that plugin
npm run test:all # the same, with every plugin's tests
npx wilanis check example # the CLI from the built runtime
npx wilanis check libraries/access # the access tree on its own, with its development binding
npx wilanis start example # run what its startup declares (the http listener among them)
npx wilanis-view example # the viewer, on http://127.0.0.1:4400/
npm run release # npm run test:all, then publishes every package in dependency order; refuses unless HEAD is tagged schemas-v1 (docs/roadmap.md, RFC 0008)npm test must pass before a commit. It always runs the tests of every package that is not a plugin, of
libraries/ and of fitness/. It runs the tests under packages/plugin-<name>/test only for a plugin with a
file that differs from the base: the merge base with origin/main locally; in CI (WILANIS_TEST_BASE) the
pull request's base, the merge queue's base, or for a push to main the previous tip of main. A change to core or engine alone runs no plugin's tests; that is a
decision (issue #828), and the runtime's and the viewer's tests still load every plugin as fixtures. The first
lines of the run say which plugins it tested and which it skipped; vitest.config.ts is the one place that
chooses. npm run test:all runs every plugin's tests, and so does a CI run with no base to compare with. Tests import the built
dist of sibling packages, so a change in core needs a build before its effect shows in a runtime test;
npm test does that.
Code quality
Biome lints and formats every src/ and test/ file; biome.jsonc is the one place the rules live, and says
why each is there. The house rules: a function under 50 lines and a cognitive complexity of 10; a file under
300 lines; at most 4 parameters (an options object beyond that); callbacks nested at most 3 deep; no nested
ternaries; no ! and no any outside a test; a name of at least 2 characters (_ for an ignored parameter).
A rule that bites is a design signal, not an obstacle: split the function along the steps it takes and name
each, or the file along the rule families it holds. The engine and the compiler are the reference: one class
or module per concern, a one-line doc comment on every public function saying what it answers.
Every directory meets the rules, so npm run lint is the whole story: it fails on a violation rather than
warning about one. The two overrides in biome.jsonc are not exemptions from the design but facts about the
code -- a test body is one long function and its describe/it nest, and the view model names a rule's
branches then and otherwise. Neither is a place to put new debt.
Principles, and what they mean here
- DRY. A rule lives in one place. Document kinds are declared once in
model.tsand once as a schema; the two mirror each other andvalidate.tsjoins them. Refusal codes are produced by the checker (D R L G P B T A I C S) or a plugin'scheck(X); never duplicate a check in the runtime. - Orthogonality. The engine knows nodes, sources and handlers; it never learns about files, shapes or
triggers. A file's bytes live in the blob registry (
packages/runtime/src/blobs.ts) and nowhere else: ablobvalue is a handle, codecs stream bodies in and out of the registry, and@bloboperations stream what they read. Never buffer a blob whole beside the store. The compiler knows documents and the engine; it never learns about HTTP. Keep it that way. A feature is three directories --edge/,domain/,data/-- and the directory is the layer: the checker reads it off the path rather than inferring a role from who references a document. A trigger fires a domain port operation through itsfirerun node and never names a graph, so the port is the one seam between the edge and the business. A binding says how a port is met and never cares which layer it is in. The context a trigger kind hands is read ascontext.*in three places only: a trigger'sfire.in, a policy'sdecide.in, and aresolversdocument (edge/) whose named reads a data graph or a binding uses as{{name}}. A resolver is a read, never an operation; the compiler lowers it to a source reference and nothing runs. Who is calling is the guard's business and what they may do is a policy's: the one plugin with aguard(@auth) verifies a credential before any graph runs and addscontext.principal,context.session,context.challengeto every kind's context; apolicy(edge/) fires a domain operation over those, and its graph refuses with a reason the policy maps todenyorchallenge. A trigger attaches its policies in order, and where it attaches one it gives the guard the credentials it verifies (in: { token: ... }), read from the kind's context like any input; the runtime's embedder runs the gate (gateinpackages/runtime/src/gate.ts), never a kind. No graph ever validates a token or a code, and no kind ever checks access. A tree may include trees (project.json → includes, npm packages only): the loader walks theirfeatures/as if local, marks each documentincluded, brings their aliases along, and leaves their connections, plugins and settings behind.libraries/holds such trees; they are pure JSON with their own tests, and depend on no path into this repository, since the packages will move to repositories of their own. - Discoverability. Every refusal has a code, a file, an
atpath and a hint that names the command or the edit that fixes it. Every document kind has a schema with descriptions. Every public function has a one-line doc comment that says what it answers. Who implements a thing is never a code detail: a domain port names its bindings, and a native port says which plugin grants it --wilanis describeprintsgranted by @http (@wilanis/plugin-http)and the viewer links its manifest.
How to change things
- A new rule. Add it to its family's module under
packages/compiler/src/check/--project.ts(C, B at the project, startup),profiles.ts(C017, C018; C024: a profile'sextendsnames a declared profile, not itself and not one that extends another; and, under each profile, B002, B003, B004, B011: what a profile chooses and whether every domain port is met and keeps its promises under it),contracts.ts(shapes, ports and what an operationlistenson, connection kinds and connections) withlisten-settings.tsbeside it (L017: the setting alistenspart reads is one the granting plugin declares, of the part's type; L018: a port the tree writes where alistensreads it is one a socket can bind; and the part helpers L015 shares),resolvers.ts(P),inputs.ts(a call site's inputs) withwithin.tsbeside it (G028: a static field markedwithinnames a path the bound type holds, of thereachestype),bindings.ts(B),required.ts(B009, B010: what a binding of a port a plugin requires may read and may reach),graph.tswithgraph-nodes.ts,graph-reads.ts,graph-whole.ts,graph-routing.ts(where a node sits in the routing, which G015 judges an effect by) andnarrowing.ts(G),graph-making.ts(L016: a data graph composing a value a field invariant guards that one of its effects reads, walked once over the tree after the graphs),triggers.ts(T) withbounds.tsfor the lists T008 finds unbounded anddelivery.ts(T009, T010: what a trigger's connection delivers),scenarios.ts(S),permits.ts(C021, C022, C023: what a profile'spermitsallows against whatreachOfsays it reaches),access.ts(A),invariants.ts(I: what an invariant states once and the whole tree is held to) withinvariant-holds.tsbeside it for the field form andprove.tsfor whether a rule already holds where a value is made -- what the checker and the guard the compiler lowers both ask, through the oneheldAt, so neither can prove a site the other would guard --,invariant-writes.tsbeside them (I007, I008: a write of a shape a field invariant is on takes the whole record, read whole from a site upstream of the effect, and never patches a field the rule reads),graph-nodes.tsagain for I006, which is a rule about the word arefusenode may name and so belongs with the node it judges rather than with the invariant it reserves the word for,attempts.ts(G017, G018, G019: what aretryon a data graph's node or a binding's operation is written over, each askingJudge.idempotentAtwhether the call is idempotent where it is made; G027: that the site'stimeoutMsand its retry'sbackoffMsare each at mostTIMER_MAX_MS, the longest a Node timer waits; a retry below an atomic graph is G020, inatomic.ts),atomic.ts(the L and G rules about what an atomic graph reaches: L009, L010, L011, G014 and G020, gathered there because each is a judgement over the one per-profile walk inatomic-reach.tsand not over a document) -- give it the next code, write the hint, and add a sabotage test inpackages/runtime/test/example.test.tsthat breaks the example and expects the code. What every family shares (typing a spec, visibility, the layer a type may name, settings that read secrets only) is a method ofJudgeincheck/judge.ts; a refusal is made throughjudge.refuser(file). The order the families run in isjudgeTreeinchecker.ts. - A new placement rule. Placement lives in one place:
HOMEinpackages/core/src/placement.ts, which says the layer (or top-level directory) each kind lives in and refuses the rest as D008. Add the kind there, add its row topackages/runtime/templates/CLAUDE.md, and teachinto()inscaffolds.tswherewilanis newshould write it. A document's layer is read off its path bylayerOfinmodel.ts-- never inferred from what references it. - A new document kind. Schema in
packages/core/schemas/(with$idunder the published base and$schemaaccepting both forms, and the optionallabelevery kind carries), a*Docinterface and theKindentry inmodel.ts, a row inpackages/runtime/templates/CLAUDE.md, the baseline inpackages/core/test/validate.test.ts, awilanis newscaffold inscaffolds.ts, and a page in the viewer'sclient/index.html(renderDocPage), since the viewer never shows raw JSON by default. - A new include. A directory under
libraries/, a workspace member, published as@wilanis/<name>:project.json(its own plugins and aliases; the host reads only the aliases),features/<name>/(what a host includes), a-devfeature andconnections/that let it check, rehearse and run alone, atest/that loads it throughloadTreewith the plugins it needs, and a README saying what the host binds and configures. The example includes it with"features": [...]and binds its ports in a feature of its own. The loader's include walk is inload.ts;resolveIncludesin the runtime'sproject.tsfinds the package; tests that copy the example hand the include in asResolvedIncludesince a copy has nonode_modules. - A new access rule. Policies and credentials are the
Afamily incheck/access.ts(checkPolicy,checkAccess); the guard's own reasons reach a trigger throughrefusalsOfTrigger. A rule about what the guard hands lives in the guard'splugin.json(guard.credentials,guard.context,guard.refuses), never in a trigger kind. What the@authplugin alone can judge (a challenge method, a session write against the session shape) is itscheck(X101-X103). - What a guard lowers to. A field invariant the checker could not prove at a site becomes a guard the author
never writes (RFC 0007):
guardsOfinpackages/compiler/src/guard.tsasksheldAt'sheldWhollyAtwhich sites those are and builds the three kernel nodes, andlowerGuardsinguard-lowering.tswrites them into the lowered spec -- the made node moved aside to<id>:madewith whatever routed it,<id>:checktesting the rule,<id>answering the value,<id>:violatedrefusing with the one reserved wordinvariant; a taken site is the same atin:okthroughRoots.aliasesinlower.ts, and a list of the shape amapover a nested spec. Those ids are a contract: the rehearsal,describeand the viewer all read a guard by them. The reason joins the walk inrefusals.ts, so T005 holds a trigger reaching a guard to map it and T006 refuses mapping it where nothing is guarded -- and a proved site adds nothing, which is the whole incentive to prove one. - A schema change. The pull request waits for the maintainer's approval in CI, as a change of decision
does, because
mainserves the schemas to every tree. Until 1.0: edit in place. After 1.0: compatible, edit in place; breaking, the base URL (SCHEMA_BASEinpublished.ts) and every$idmove to the tagschemas-v2, and theschemas-v1tag stays (RFC 0008). - A new plugin. A new package under
packages/, depending on core and engine only -- and, where it implements one, the contract plugin it answers -- exporting itsPluginModuleas default:root,docs(the directory of the JSON documents it ships, withplugin.json; listed in the package'sfiles, and alwaysdocs/beside its package.json, whichwilanis newreads without loading the plugin),handlers, and optionallytriggers,codecs,check(its X rules; it refuses with aRefusalobject: code, file, message, at, hint),postLoad, and -- for at most one plugin of a tree --guard. Every port, kind, codec or shape a plugin grants is a file underdocs/, never an object in code: what the DSL names, a reader can open. A project names the plugin inplugins[].from. Plugins that carry an external dependency are always their own package. - A new CLI command.
packages/runtime/src/cli.tsdispatches; the work goes intools.tsorserve.tsso it is callable without the CLI. - What a tree starts. Everything a tree starts is declared in
project.json → startup, never decided by the runtime:wilanis startruns the plugins'postLoad, then those steps, and stops. The HTTP server opens because a step names@http/server.port.json#listen, so a tree that names none serves nothing. An operation that starts something outliving its run is markedholdsin its port document (besidepureandrefuses); it readsenv.holdto hand back its teardown andenv.servingto reach the tree, and the runtime stops what was held, in reverse, before thepostLoadteardowns. Only a startup step may name one (L008 refuses a graph that runs one), and a nativeholdsoperation is the one native operation a startup step may name (B006 otherwise).runStartuplives inserve.tsandServedinserved.ts;checkStartupincheck/project.tsjudges the steps (B006, B007, B008) and runs last, after the resolvers documents are read. A plugin'spostLoadstays what it is: that plugin's own wiring, not the project's. - The project template.
packages/runtime/templates/is whatwilanis initwrites into a consumer tree. ItsCLAUDE.mdaddresses an agent that writes documents, not one that changes this repository. - A decision about the code. It is a file under
fitness/, one per decision:claim, the sentence its name spells;gather, which reads the repository;judge, pure, from what was gathered to the violations, each naming the offending file and the edit that fixes it; andsabotage, the cases that prove the judge bites.fitness/run.test.tsregisters a claim and its proof for every one;fitness/lib/holds readers only. A fitness function that bites is a design signal: the edit goes to the code, not tofitness/. Changing a decision is the maintainer's to make and to say -- theDecision:line is theirs to write, no tool adds it, and.githooks/commit-msgand thedecisionjob refuse a commit that changes one silently.fitness/README.mdand RFC 0027 are the whole story.
Do not add features, document kinds, or plugin hooks beyond what a task asks for. When a task seems to need one, stop and say so.
Commits
Messages are plain: what changed and why, in the imperative. No generated trailers, no tool or session
references. The one exception is a commit that touches fitness/, which carries a Decision: (adds |
reconfigures | retires) fitness/<file> because ... line saying what was decided and why. That line is the
maintainer's own words; no tool adds it, .githooks/commit-msg refuses the commit without it, and the
decision job in CI checks every such commit and then waits for the maintainer to approve the run. That job
waits only when there is something to approve: a change of decision, or of a schema under
packages/core/schemas/, which main serves to every tree; any other pull request skips it.
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.

