Contributing

The repository is private for now

Fynn-3D/entelechy is a private repository (the code is MIT-licensed; see License). This page summarizes how AGENTS.md and PROCESS.md say work is done, for contributors (people or agents) with access.

Reading order

AGENTS.md sets an order, each document answering one question:

#	Document	Answers
1	AGENTS.md	What Entelechy is and what the rules are
2	README.md	What it looks like from outside
3	ARCHITECTURE-PLAN.md	Which phase the work is in, and what accepts it
4	CORE-ARCHITECTURE.md	Where the boundaries are
5	docs/TYPED-FIELD-ARCHITECTURE.md	Why there is one resource
6	IMPLEMENTATION.md	Where the code and its evidence are
7	PROCESS.md	How to write, verify, commit and hand over
8	HANDOFF.md	What this repository holds, and the next action

By question: writing a Kernel or scene → docs/DOCUMENTS.md; which command → docs/USAGE.md; what an agent sends → docs/PROTOCOL.md; what rows a rig is → docs/RIGS.md; what a Kernel may call → entelechy help; why → docs/DECISIONS.md.

Repository state is authoritative. Do not rely on a previous session’s memory.

Code

Host → ABI → IR → Kernel Runtime → Graph Runtime

• Respect the layers; do not bypass them for convenience. One module, one responsibility; no god objects, hidden globals or cross-layer helpers.
• Every state has an owner, and every rule one. A rule found with a second owner is left with one, held by the compiler or a row in crates/interface/entelechy/tests/owners.rs.
• Do not silently recover from invalid runtime state; return meaningful errors. A failed hot reload keeps the previous valid Kernel alive.
• Stable boundaries: Capability ABI, Entelechy IR, KernelID, Serialized Graph Format — change them intentionally and test compatibility.
• The language and scene syntax grow only by the owner’s word; friction is met by a function, a package or an example.

Formatting is automatic. Architecture is deliberate.

Comments and documents

A comment or document states present facts: what a thing is, who owns it, what it guarantees. History is git’s; reasons are docs/DECISIONS.md’s. No “used to”, no narrative, comparison, hedging or dated observation. One fact, one place. Everything written into the repository is English (the conversation may be in any language).

Git

• main is the line. Work on a focused feat/*, fix/*, refactor/*, docs/*, test/* or chore/* branch, one round of work each.
• A branch holds one side of the line between the Rust build and what runs on it: IR/compiler/backends (crates/core, crates/frontend, crates/backends) one branch; the rest of the Rust another; .ent, .esn, replays and documents alone a third.
• Small logical commits in English (feat: add kernel registry). Record what was actually verified, limits included.
• Local-commit authorization is not authorization to push, merge or release. Merging to main is on the user’s word, a fast-forward. Never force-push or rewrite history unasked.

Verification: cargo xtask verify

cargo xtask verify
tail -f target/verify.log

xtask runs, in order (steps needing nothing of each other at once):

1. fmt, then packages (every package named, laid out, layered, and every Kernel reached by its own tests), then clippy over every target, clippy-wasm and clippy-page, warnings denied;
2. test-build;
3. tests and bridges;
4. the release build;
5. replays, wasi and against_main:
   • replays runs every example’s and package’s replays by the release build on each backend, then with --small 0, --no-fusion and --round-apart;
   • wasi builds for WASI and holds a stdin session and the file-reading replays to it;
   • against_main runs every example by main’s build and the branch’s and compares check, graph (the plan) and the picture — every difference must be one the branch means.

The log begins with the commit it verifies and ends passed.

Handoff

HANDOFF.md carries two things only: Context (the facts an agent must hold to act, and the surface verified) and Next (one executable action and its acceptance criteria). Replace what is stale; never append a diary. Before ending a session: inspect the diff, run the checks, replace Next.