write-clj

write-clj

Write Clojure for the project. The standard is skills/write-clj/references/clj-style.md (read it first). The architecture it implements is Functional Core / Imperative Shell; the Clojure expression of that discipline, and the native boundary contract, live in skills/shared/references/architecture.md. Namespaces are placed by domain (recorded in the project's module map, the :architecture :modules entry in the descriptor), and each holds its own pure and effectful functions. The why behind the constraints is the ADR log: scan it before designing against an unexplained rule.

The discipline is load-bearing, not a preference. JVM Clojure semantics are the spec for the surface; check real Clojure behavior for every edge (nil, empty, laziness, arity, unsigned ranges) before writing.

1. Pure functions. Functions that take data and return data, do no IO, never shell out, never transact, hold no clock, thread, or atom. Model entities, specs, transactions, and operation chains as plain data; let pure functions transform them. This is the project's architectural identity: description, not instruction. A pure function may not call an effectful one; the dependency direction is into the pure logic, never out of it.

2. Effectful functions. Functions that own persistence, platform, and lifecycle: the database wiring, OS integration, the application composer, scan and update orchestration. An effectful function adapts inputs to data, calls pure functions, and applies the result as effects; it switches on values the pure functions return and carries no logic of its own. Mark effectful functions with a trailing ! (scan!, recompile!, ensure-library!).

3. Namespaces divide by domain. A namespace is named for the domain it owns (a single concept: cache, compiler, source), not for the pure/effectful split. A namespace routinely holds both pure functions and the !-marked effectful functions that drive them; the split is a function-level discipline (and the dependency rule of architecture.md §2), not a namespace boundary. Do not split one domain into a foo (pure) and a foo-store/foo-shell namespace; that fragments the domain and is a factoring bug.

4. Native wrappers. A thin Clojure layer over a foreign-function or native edge. Marshal data in, marshal data out, pass opaque handles back and forth. No domain logic on either side of the boundary: the pure functions decide what to call, the wrapper calls it, the result is consumed back in the pure logic.