@nfinitmonkeys/clan-engine

@nfinitmonkeys/clan-engine

The deterministic setup engine for Nfinit Monkeys clans — the single template + reconciliation authority. The published CLIs (@nfinitmonkeys/clan, @nfinitmonkeys/clan-claude) and the internal fleet tooling all render from here, so their output can never drift apart again.

Non-destructive by construction. It merges into an existing .claude/ + .mcp.json instead of clobbering, backs up every file it touches, and journals every run so it can be undone exactly.

Tiers

As of 0.3.0 the engine is authoritative for clan, district, and jungle tiers — one template source renders the right /clan:*, /district:*, or /jungle:* pack from the repo's declared <!-- geo-tier: X -->. Biome is unbuilt: asking for a biome pack throws (no pack template for tier biome yet) rather than emitting something half-real.

Verbs

clan-engine inspect     [--repo .] [--json]     # map a repo's state (never mutates)
clan-engine plan        [--repo .] --alpha X --name Y [--tier clan] [--json]
clan-engine apply       [--repo .] --alpha X --name Y     # write it (backups + journal)
clan-engine brain-build [--repo .] [--write] [--memory] [--json]   # mine the brain
clan-engine undo        [--repo .] [--journal <path>]     # reverse the last apply
clan-engine doctor      [--repo .] [--json]     # validate the whole loop

plan is a dry run; apply writes. Both are idempotent — a second apply is all skips. --json output masks live key values as [redacted] everywhere.

What it authors

• CLAUDE.md — geo-tier declaration + identity block (existing prose is never rewritten; only the <!-- geo-tier: X --> marker is ensured).
• .claude/skills/clan-awareness/SKILL.md — the awareness skill in the directory format Claude Code actually loads (a flat file never loads).
• .claude/commands/<tier>/*.md — tier-named slash-command pack, including /<tier>:up — the wizard door. Clan tier gets the full conversational setup/convert/repair playbook (Claude Code improvises the conversation; the engine does every write); district/jungle get a short repair wizard (their identity is provisioned by node-up, never interviewed). Generated wizard text version-pins the engine (npx -y @nfinitmonkeys/clan-engine@0.3) so an older published engine can never overwrite the pack that invoked it.
• .mcp.json — a correctly-named jungle-local server merged alongside any servers you already have, and gitignored (it holds a live key). Never the bare name jungle (it collides with the global council server).
• .claude/settings.json — a cross-platform Node SessionStart hook that hydrates the brain and self-noops when there's no brain (safe to commit).
• .brain/ — a versioned vault (.brain-meta.json carries layoutVersion so future engines can migrate it).
• .clan/inventory.json — the user's EXISTING agents/skills/commands/hooks, so the Alpha works with them instead of duplicating.

brain-build

Mines README, docs/ (recursive), CLAUDE.md, package manifests, code structure, the inventory, and (--memory) Claude Code session memory into brain pages. Every source passes scanSensitive first — secrets, infra identifiers, and PHI are held back and reported, never written. Dry-run by default; --write to save; create-only (your accumulated pages are never touched).

LLM curation is API-only. The engine itself has no LLM and the CLI has no --curate flag. Callers pass a hook:

const res = await brainBuild(repo, identity, { curate: async ({ pages, identity, sourceNotes }) => curatedPages });

The caller brings the LLM (this is what clan brain build --curate does with the clan's configured provider); the engine re-gates every curated page through scanSensitive + create-only, and falls back to the mechanical pages with a note if the curator throws. Sanitization is not optional at any layer.

Existing-vault detection

inspect finds the repo's REAL vault so setup and brain-build never scaffold a tier-default duplicate nothing loads. Precedence:

1. the vault a live load-brain SessionStart hook already hydrates — wins outright (the hook is ground truth for what sessions actually load);
2. vaults containing wiki/identity.md, in order .district/brain > tier-default root > .brain > .brains/<alpha> > other .brains/* (preferring obsidian) — a real identity beats debris;
3. bare-existing vaults in the same order;
4. none → the tier default applies.

Reconciliation

Every generated file carries a clan-engine@<v> + layout: <n> marker. That's how the engine tells its own output (safe to update) from a file you wrote at the same path (backed up, then replaced). Brain pages are create-only — your accumulated memory is never clobbered.

ENGINE_VERSION (in src/types.ts) always equals the package version — the test suite fails on drift. LAYOUT_VERSION bumps only when generated output changes shape (that's what triggers migrations); ENGINE_VERSION bumps freely.

Programmatic API

import { inspect, reconcile, apply, undo, doctor, setup, brainBuild } from '@nfinitmonkeys/clan-engine';

const { plan, result } = setup(repo, identity, { at, today });   // inspect → reconcile → apply

The conversational setup wizard (/clan:up) drives these verbs — the LLM improvises the conversation, the engine does every write.

License

MIT