A living knowledge substrate for AI-assisted engineering

What is emerik

As you build software with AI agents, the reasons behind the code — why a value is what it is, which invariant must hold, what was tried and rejected — evaporate. emerik captures that knowledge as small, content-addressed artifacts committed alongside your code, and gives you commands to reach it, verify it, and keep it from rotting.

Everything lives in a .emerik/ directory in your repo, stored append-only. There is no external service: your git remote is the only source of truth, so knowledge travels with the code and is versioned by the same history.

The mental model

Four ideas carry the whole system. Learn these and every command reads naturally.

The load-bearing promise is honesty: a check that guards an invariant must be able to fail when the invariant breaks. You will see this proven end-to-end in the honesty loop.

Requirements

• Node.js 20 or newer. The CLI is tested on Node 20 and 22.
• git. emerik is git-native — every command operates on a git repository.
• pnpm. The project's package manager; the lockfile is committed. Install it with corepack enable or from pnpm.io.

Installation

emerik v0.1.0 installs from source. Clone the repository, install dependencies, and build the CLI bundle.

Copygit clone <emerik-repo-url> emerik
cd emerik
pnpm install
pnpm build          # tsc --noEmit + tsup + oclif manifest → dist/

Copy./bin/run.js --version   # → emerik/0.1.0 …
./bin/run.js --help      # show the full command tree

So you can call emerik from any repository instead of the full path:

Copy# option A — symlink the launcher into a directory already on PATH
ln -s "$(pwd)/bin/run.js" /usr/local/bin/emerik

# option B — npm link (from the emerik project root)
npm link

Quickstart

From inside any git repository, three commands take you from nothing to a verified knowledge graph.

Copycd your-project
emerik init                 # create .emerik/, ignore rules, git hooks + wire your agent
git commit -am "chore: emerik init"
emerik harvest              # harvest source-bound Pins from HEAD
emerik verify               # run the convention + Anchor gate (exit 0 = clean)

Working inside a coding agent? The guided path is the front door — start with emerik-guide (orient, tour, or step-through). Starting from an empty repo? Start a new project walks the greenfield front door — brainstorm to first Goal, on emerik alone.

Start a new project

emerik is the greenfield front door too: from an empty directory to a first implemented, harvested, verified Goal on emerik alone — no separate planning tool, no document that rots away from the code. The five planning skills carry an idea down to sequenced Goal briefs the engineering loop picks up directly. ⎯ Each step deposits durable substrate: a committed session doc harvested into Pins, constraint-Anchors on their stewards, the brief / prd / architecture heads, and the sequenced Goal briefs.

Start from nothing but an empty directory and wire emerik in.

Copymkdir task-inbox && cd task-inbox
git init
emerik init                 # store, hooks + the planning skills, wired into your agent

An empty substrate — a fresh repo with zero Pins — is a valid entry state, not a special mode. Greenfield is simply what it looks like when the grounding reads come back empty.

Inside the coding agent, run emerik-brainstorm. It facilitates an honest ideation session grounded in whatever the substrate already says (nothing, on a fresh repo — stated plainly, never fabricated), and lands two things: a committed session doc under .emerik-planning/brainstorm-<slug>.md that the harvest hook captures as Pins, and any constraint stated in-session deposited as a constraint-Anchor on its steward at the moment it is stated — queryable the instant it lands.

Three skills turn the idea into durable, append-only planning heads — each a committed markdown body the hook harvests, plus a minted artifact that references it:

• emerik-brief — the idea becomes a committed brief artifact: problem, users, outcome, scope fence.
• emerik-prd — the brief grows into a prd, and each binding requirement is offered as a candidate constraint-Anchor at the moment of statement.
• emerik-architect — the prd becomes a durable architecture, and each decision that governs a code region lands as a governing Anchor (inverted CODEOWNERS) — the design document and the enforcement surface are the same thing.

A revision never edits in place: a changed head is a superseding artifact (--supersedes), so the old one stays replayable in lineage.

emerik-breakdown converts the live prd and architecture into an ordered sequence: one committed initiative brief under .emerik-planning/initiative-<slug>.md, then delivery-sized Goal briefs under .emerik-goals/, each opening with a Sequence block (Initiative: / Priority: P0/P1/P2 / Depends on:) so the order and the dependencies are explicit.

Now the planning path meets the engineering loop you already know. Pick up a brief with emerik-goal (one brief → one Goal, its priority read from the Sequence block), or hand the whole sequence to emerik-orchestrate to fan the briefs out in dependency order. From there it is the shipped loop: plan grounded in retrieved Pins and Anchors, implement test-first under a Lease, and emerik verify as the green gate — then complete the Goal. That closes the path: mkdir to a first implemented, harvested, verified Goal, on emerik alone.

Initialize a repo

emerik init is idempotent — safe to run again. It creates:

• .emerik/ — the append-only, content-addressed store (committed with your code).
• .emerik/.gitignore and a root .gitignore rule for the ephemeral local index.
• a post-commit hook (auto-harvest) and a pre-push hook (freshness re-derive).

It also wires your coding agent (additive and idempotent — pass --no-agents to skip):

• .claude/skills/ — the fourteen shipped skills, loaded by Claude Code and by Cursor (2.4+, which reads .claude/skills/ natively): emerik-brainstorm, emerik-brief, emerik-prd, emerik-architect, emerik-breakdown, emerik-discover, emerik-goal, emerik-plan, emerik-implement, emerik-review, emerik-guide, emerik-retro, emerik-orchestrate and emerik-onboard.
• .claude/agents/ — the four reviewer roles the emerik-review skill fans out: blind-hunter, edge-case-hunter, acceptance-auditor and substrate-auditor.
• .mcp.json — registers the emerik mcp server for Claude Code (merged additively, other servers untouched).
• .cursor/mcp.json — the same emerik mcp server for Cursor, same mcpServers shape, merged additively the same way.
• a delimited <!-- emerik:begin -->…<!-- emerik:end --> block in AGENTS.md (created if absent) and in CLAUDE.md (only when it already exists), describing the substrate and the skills. Content outside the markers is never touched, and re-running init heals a missing piece without duplicating anything.

$ emerik init
✓ initialized .emerik/ — Pin, Anchor and Glacier store ready
  created .emerik/config.yaml
  created .emerik/pins/.gitkeep
  created .emerik/anchors/.gitkeep
  created .emerik/glacier/.gitkeep
  created .emerik/goals/.gitkeep
  created .emerik/dependencies/.gitkeep
  created .emerik/reviews/.gitkeep
  created .emerik/briefs/.gitkeep
  created .emerik/prds/.gitkeep
  created .emerik/architectures/.gitkeep
  created .emerik/.gitignore
  created .gitignore
  created .git/hooks/post-commit
  created .git/hooks/pre-push
  created .claude/skills/emerik-plan/SKILL.md
  created .claude/skills/emerik-plan/template.md
  created .claude/skills/emerik-implement/SKILL.md
  created .claude/skills/emerik-discover/SKILL.md
  created .claude/skills/emerik-guide/SKILL.md
  created .claude/skills/emerik-guide/steps/orient.md
  created .claude/skills/emerik-guide/steps/step-through.md
  created .claude/skills/emerik-guide/steps/tour.md
  created .claude/skills/emerik-goal/SKILL.md
  created .claude/skills/emerik-goal/checklist.md
  created .claude/skills/emerik-goal/template.md
  created .claude/skills/emerik-review/SKILL.md
  created .claude/skills/emerik-review/checklist.md
  created .claude/skills/emerik-review/template.md
  created .claude/skills/emerik-retro/SKILL.md
  created .claude/skills/emerik-retro/checklist.md
  created .claude/skills/emerik-retro/template.md
  created .claude/skills/emerik-orchestrate/SKILL.md
  created .claude/skills/emerik-brainstorm/SKILL.md
  created .claude/skills/emerik-brainstorm/template.md
  created .claude/skills/emerik-brief/SKILL.md
  created .claude/skills/emerik-brief/checklist.md
  created .claude/skills/emerik-brief/template.md
  created .claude/skills/emerik-prd/SKILL.md
  created .claude/skills/emerik-prd/checklist.md
  created .claude/skills/emerik-prd/template.md
  created .claude/skills/emerik-architect/SKILL.md
  created .claude/skills/emerik-architect/checklist.md
  created .claude/skills/emerik-architect/template.md
  created .claude/skills/emerik-breakdown/SKILL.md
  created .claude/skills/emerik-breakdown/checklist.md
  created .claude/skills/emerik-breakdown/template.md
  created .claude/skills/emerik-onboard/SKILL.md
  created .claude/skills/emerik-onboard/checklist.md
  created .claude/skills/emerik-onboard/template.md
  created .claude/agents/blind-hunter.md
  created .claude/agents/edge-case-hunter.md
  created .claude/agents/acceptance-auditor.md
  created .claude/agents/substrate-auditor.md
  created .mcp.json
  created .cursor/mcp.json
  created AGENTS.md

Prefer just the substrate, no agent wiring? Run emerik init --no-agents.

Works with Cursor. One emerik init wires both harnesses. Cursor 2.4+ loads the shipped skills through its native .claude/skills/ support (the Agent Skills standard), and AGENTS.md is first-class in Cursor, so the same substrate context, lexicon and skills reach a Cursor agent unchanged. Two caveats worth knowing: the emerik-review fan-out uses the host's native subagents where present, else the documented prompt-file fallback (one prompt per reviewer under .emerik-local/reviews/, run manually) — that fallback is the guaranteed path on any harness; and emerik exposes thirty-five MCP tools, comfortably under Cursor's historically undocumented per-server tool cap. Leases, hooks and harvest are plain git, so a Cursor agent and a Claude Code agent on the same repo coordinate through the same leases and the same harvest hooks.

The harvest hook resolves emerik robustly: it prefers a global emerik on your PATH, and otherwise falls back to the absolute CLI path baked in at init time — so a commit auto-harvests even when emerik is not installed globally. The hook swallows its own output and always exits 0, so it never blocks a commit or push. If emerik cannot be resolved at all — no global install and no reachable fallback (a moved clone or a deleted build) — the hook prints one stderr line (emerik: harvest skipped — emerik not found …) so a missed harvest is visible rather than silent; it still exits 0 and never blocks the commit.

Harvest Pins

emerik harvest reads a commit, extracts source-bound Pins, and re-derives any Pin whose source changed. With the post-commit hook installed it runs automatically on every commit; you can also invoke it directly.

$ emerik harvest
{"level":"info","message":"harvest: committed run","harvested":1,"rederived":0,"invalidated":0}
✓ harvested 1 Pin

Freshness — the honest part

Every Pin is bound to the bytes it came from. On the next harvest:

• Source changed → the Pin is re-derived; the stale predecessor is superseded.
• Source deleted / became binary → the Pin is invalidated with a tombstone.
• Nothing changed → no-op (re-harvest is idempotent).

This is why a Pin never silently drifts out of sync with the code it describes.

Harvest never pins emerik's own scaffolding: the .emerik/ store, the whole .claude/ tree, and the root-level .mcp.json, AGENTS.md and CLAUDE.md that init wrote are excluded — so a git add -A right after init mints Pins only for your real source, never for the wiring outputs. A nested CLAUDE.md (your own knowledge file) is still harvested.

Anchors & verify

An Anchor is a reviewed contract with a machine-checkable assertion. You choose a subtype, an enforcement level, and a check.

Author a block-level constraint guarded by a grep pattern:

Copyemerik anchor author \
  --content "Auth token TTL must remain 3600s to match the gateway." \
  --subtype constraint --enforcement block --steward you \
  --check-kind grep --check-ref "TOKEN_TTL_SECONDS = 3600"

List what exists, and run the gate:

Copyemerik anchor list        # inventory of Anchors + lineage
emerik verify             # check every Anchor + convention lint

Promote a Pin into an Anchor

A load-bearing Pin can be promoted through a review gate. Without --approve it is a no-write preview; with it, a reviewed Anchor is minted carrying promotedFrom lineage.

Copyemerik anchor author --from-pin <pin-ulid> --subtype contract \
  --enforcement block --steward you \
  --check-kind grep --check-ref "requireAuth" --approve

The honesty loop

This is the whole promise in one worked example: a green check must go red the moment the invariant it guards is broken. Start from the constraint Anchor above.

$ emerik verify                          # invariant holds
✓ conventions OK — no violations
✓ BLOCK  constraint 01KWH64…  grep — grep matched: TOKEN_TTL_SECONDS = 3600
1 Anchor(s) checked · 1 ✓ · 0 blocking
exit 0

$ sed -i '' 's/3600/7200/' src/auth.ts   # break the invariant

$ emerik verify                          # drift introduced
⛔ BLOCK  constraint 01KWH64…  grep — grep found no match for: TOKEN_TTL_SECONDS = 3600
1 Anchor(s) checked · 0 ✓ · 1 blocking
exit 1

Retrieve context

emerik retrieve answers a query with a cost-tiered cascade: it reaches for hot Pins (semantic search) first, falls through to Anchors, then to raw code — stopping as soon as it has enough. This is what an AI agent calls to get the right context cheaply.

Copyemerik retrieve "how is the auth token TTL enforced?"
emerik retrieve "auth token TTL" --limit 5 --json

Results carry a heat bar (▁▂▃▅▇) showing how frequently each Pin is referenced.

The local index

Semantic retrieval is powered by a local, ephemeral index built from your committed Pins. It lives under .emerik-local/ (gitignored) and is rebuilt from the source of truth on demand — the index is disposable, the Pins are not.

Heat & glacier

Every Pin has heat — a score blending recency-decay with how often it is referenced. Cold Pins can be frozen into a lossless glacier archive to keep the active index lean, and thawed back when they matter again. Freezing is a relocation, never a deletion: the Pin's identity and bytes are preserved.

Copyemerik glacier freeze --threshold <heat>   # freeze Pins colder than a threshold
emerik glacier list                        # what's archived
emerik glacier thaw <pin-ulid>              # bring one back

Goals

A Goal is the concurrent work-unit: a team pursues one active Goal against the shared decision graph while other teams pursue theirs — many Goals run at once with no single-tree bottleneck. A Goal is a first-class, content-addressed, append-only artifact under .emerik/goals/: starting one mints an active Goal; advancing supersedes it with a progress entry; completing supersedes it with a completion stamp. The committed markdown brief under .emerik-goals/ stays the durable narrative — the Goal links it with --brief; they coexist.

A Goal carries a first-class priority — P0, P1, or P2, set with goal start --priority (default P1). It is the attention rank the orchestrator's simple-priority mode orders assignments by (P0 before P1 before P2), and it is carried through advance unchanged. The field is optional for append-only compatibility: a Goal committed before priority existed carries none and reads as P1.

Contract-dependencies

When your team builds on another team's work, you depend on the published Anchor — the contract — not on their live, leased-out code. It is the microservice-contract version pin: you declare a dependency on the contract you built against, and when the steward supersedes it, that change is an explicit coordination event you are notified about. The surface accepts only an Anchor id — it structurally cannot name live code, a path, or a leased territory, so “never against live code under lease” is a property of the shape, not a convention.

Declared against the contract, notified when it changes

A dependency is an append-only artifact naming a published Anchor's id. It is recorded once; when the steward supersedes the contract, you find out four ways:

• The event log. The emerik(anchor): supersede <id> commit is the coordination event — a git-native, durable record, replayable via emerik history.
• Your read surface. emerik dependency status (and the dependency_status MCP tool) reports a moved contract as changed and names the new head — the pull-based notification the dependent polls.
• The author's render. When the steward runs emerik anchor author --supersedes, the human output names the dependent teams affected — a courtesy heads-up at change time (the --json envelope is unchanged; the notification surface for agents is the pull-based status).
• At Goal start. emerik goal start renders the coordination event automatically (human output) for any depended-on contract that moved — sync before building on it. It is a heads-up, not a gate: the Goal starts regardless. Agents on the MCP path pull the same report via dependency_status right after starting.

Sync is a re-declare

There is no separate sync verb: re-declaring on the new head mints a superseding Dependency (append-only), which dependency status tells you the exact command for. A same-head re-declare is refused (DEPENDENCY_EXISTS) — it is never a silent no-op. If two machines race that declare for the same team and anchor and both land, the byte-identical duplicates dedup at projection (kept: earliest) and count as one dependent — append-only, both files stay on disk.

Exclusive-write leases

When several agents or machines write to the same repo, a lease gives one of them exclusive rights to a territory for a bounded time. Leases are recorded on a dedicated git ref (refs/emerik/leases) via compare-and-swap push — your git remote is the serialization point, so no lock server is needed. A lease expires on crash or stall, so turf never deadlocks.

Territories collide by path overlap, not just exact string — so mutual exclusion is mechanical, not a naming convention. A lease on src/auth/ blocks a claim on src/auth/login.ts (and the reverse), and glob forms like src/auth/** collide the same way. A bare token with no / or glob metachar (e.g. payments) is opaque — it collides on exact match only. The refusal names the overlapping lease so an agent's routing reads it unmistakably.

Two machines, one territory

Run this on two clones of the same remote at nearly the same instant. Exactly one wins.

This is signed off end-to-end: two clones with distinct git identities, driven over both the CLI and the MCP twins, exercise cross-machine claim, territory overlap, version-skew tolerance, and goal/fork/dedup races against a shared remote — each producing exactly one winner or one surfaced, reconcilable fork. Since the git ref CAS is client-agnostic, the serialization holds identically across physical machines — the executed pass ran against a local bare remote (a hosted remote and a literal second physical machine are a documented follow-up; see the committed sign-off record).

A$ emerik lease claim payments --holder machineA --retries 0
⛔ BLOCK  territory 'payments' contended — another machine claimed it first   exit 1

B$ emerik lease claim payments --holder machineB --retries 0
▣ LEASED  payments · holder machineB · expires in 15m                        exit 0

Stigmergic self-deconfliction

Agents coordinate the way ants do — by reading shared state and routing around each other, with no direct messaging and no orchestrator. Before it chooses where to work, an agent reads the trail — emerik trail status (MCP trail_status):

• The heat trail. A recently-worked path is hot — a signal that someone is active there. This is FR-4's heat read as a pheromone: one mechanism, two uses, the same heat number retrieval ranks by, never a second subsystem. Recency travels through git (a fresh Pin's committed createdAt), so "someone just worked here" is visible cross-machine; reference counts add same-machine reinforcement. Heat never blocks — a hot zone is a routing signal, not an error.
• The lease markers. The active Leases on refs/emerik/leases are the authoritative contested signal — territory · holder · expiry, shown so others route around them.

Declaring a territory turns the trail into a guard. When an author declares the territory it holds — emerik anchor author … --territory <t> (MCP anchor_author territory) — the write is consulted against the live Leases before it lands using the same path-overlap check a claim uses: a declared territory that path-overlaps another holder's live Lease refuses the write (LEASE_HELD, exit 1, no partial write) in coordination-event voice — never "conflict", never "locked". Your own or an open territory proceeds. Heat is never consulted at write time; only a live Lease arbitrates.

Onboard a brownfield repo

Adopting emerik on an existing codebase is an agent workflow, not a manual runbook. Point your coding agent at the emerik-onboard skill and it drives the whole cold start: ensure the store is initialized, emerik seed --analyze, emerik seed, build the index, and land a committed onboarding summary grounded in the seeded graph — with each phase's landing verified from the live surface (via the --json reports and emerik index status) before the next phase starts. Retrieval works warm from the first query.

A repo with nothing to seed is not forced through the pipeline: when the analyzer reports codeUnits === 0 (or there is no HEAD), emerik-onboard says so and routes to the greenfield planning path (emerik-brainstorm + emerik-guide) instead of seeding nothing — the store is still left initialized with a fresh index.

Deterministic seed content is a code/comment excerpt. When a coding agent drives the cold start it can do better: after the first analyze pass, it reads the enumerated code units and writes a short synthesized understanding of each file it can genuinely improve into a gitignored handshake file .emerik-seed/synthesis.json (keyed by repo-relative path), then re-analyzes with --synthesis. Those files' Pin content becomes the agent's understanding — provenance-marked synthesis: agent, a record of how the content was produced, not a trust upgrade — while the binding stays on the code, so re-derive keeps it fresh from there. No live agent or model is ever loaded into the engine: the intelligence arrives as data through the same extractor seam the deterministic pass uses.

Documents get the same two-tier treatment. Instead of admitting a whole file as one 2000-character dump, the analyzer splits each doc on its markdown headings into per-section candidates — the deterministic fallback, always available. When a coding agent drives the cold start it extracts the actual decision each section states (an ADR's "use PostgreSQL", not its prose) into a second handshake file .emerik-seed/doc-decisions.json and re-analyzes with --doc-decisions; those per-decision candidates replace the section chunks, marked synthesis: agent. Admission is then a real per-candidate review: bare emerik seed --json returns docCandidates — each with a stable candidateKey, its source and section, full content, and a proposed enforcement — and the steward admits them individually through an admissions manifest (below), each with its own steward and enforcement level. Two documents stating the same decision collapse to one candidate (and one Anchor). No Anchor is ever written without --approve-docs and a named steward — the machine still never mints an Anchor on its own.

Two ways in

A skill cannot be its own delivery vehicle — its premise is pre-init — so there are two documented doors:

• Door 1 (recommended). Install emerik globally, run emerik init as the one manual command (it installs all fourteen skills), then invoke emerik-onboard in your agent. Its first phase detects the store, records init as already landed, and continues with analyze.
• Door 2 (fully agent-driven). Point the agent at the packaged assets/skills/emerik-onboard/SKILL.md inside the globally-installed package and follow it — the skill drives emerik init itself as phase 1, self-installing for every future session.

The manual runbook advanced

Prefer to drive it yourself (or running in CI / a non-agent harness)? The same pipeline is two review-gated steps. It requires an initialized store — run emerik init first.

Copy# 1) analyze — walks HEAD + ingests docs into a gitignored .emerik-seed/
emerik seed --analyze

# 2) seed — bulk-write the analysis into the graph (code → Pins)
# bare seed also lists per-candidate doc previews (docCandidates) in --json
emerik seed

# admit ALL doc candidates under one steward (the bulk gate)
emerik seed --approve-docs --steward you

# or review per candidate: admit only the keys in an admissions manifest,
# each with its own steward + enforcement (see below)
emerik seed --approve-docs --admissions .emerik-seed/admissions.json

Seed from generated behavior docs

Already documented the codebase with a tool that emits a coverage.json feature index (mapping each feature to its docs and the code paths they describe)? Point --analyze at it and each covered code file's Pin content becomes that feature's behavior contract — bound to the code, so re-derive keeps it fresh from there.

Copy# enrich covered code Pins with feature contracts (auto-discovers
# the index via doc-agent.config.json when --coverage is omitted)
emerik seed --analyze --coverage docs/features/coverage.json
emerik seed

Seed with agent-synthesized understanding

Have an agent (or a script) that can describe each file? Write its output as a handshake file — a { formatVersion, entries } map of repo-relative path to synthesized text — and point --analyze at it with --synthesis. Covered files are seeded with that text, stamped synthesis: agent; every uncovered file falls back to the deterministic excerpt. The named file must exist (a missing --synthesis path is a hard error, unlike auto-discovered --coverage).

Copy# swap agent understanding in through the extractor seam
emerik seed --analyze --synthesis .emerik-seed/synthesis.json
emerik seed

Extract per-decision doc candidates

Without a handshake, each document is split on its markdown headings into per-section candidates. To capture the actual decision a section states (rather than its prose), write a { formatVersion, decisions } map of doc sourcePath to the decisions it states — an empty array is the honest "no decisions here" signal — and point --analyze at it with --doc-decisions. A matched doc's candidates are replaced, stamped synthesis: agent; a handshake path matching no ingested doc is reported as unmatchedDocDecisions, never silently dropped. The named file must exist.

Copy# replace section chunks with the agent's per-decision candidates
emerik seed --analyze --doc-decisions .emerik-seed/doc-decisions.json
emerik seed

Admit per candidate

Bare emerik seed --json lists every admittable candidate under docCandidates with a stable candidateKey. To admit a reviewed subset — each with its own steward and enforcement level — write an admissions manifest and pass it with --admissions. Listed keys are admitted; unlisted candidates stay pending; an unknown key is a hard error before anything is written. All three enforcement levels are accepted (you chose), but an admitted doc Anchor is checkless, so even block/warn still surfaces as ⚠ WARN in emerik verify — admission records a decision, it does not add a runnable contract.

Copy# .emerik-seed/admissions.json
# { "formatVersion": 1, "admit": [ { "key": "<candidateKey>", "steward": "data", "enforcement": "advisory" } ] }
emerik seed --approve-docs --admissions .emerik-seed/admissions.json

History & time

Because the substrate is append-only on git, the commit history is the decision log. Three read-and-maintain commands operate over time.

Copyemerik history <artifact-ulid>     # lineage + why
emerik compact --dry-run           # preview the GC, mutate nothing
emerik compact                     # report the before→after .emerik/ byte delta

Use with an AI agent

emerik is built to be an extension of your coding agent. When you run emerik init, it wires the repo so Claude Code (and other harnesses) can reach the substrate through a small, safe tool surface — the agent grounds its plan in your team's committed Pins and Anchors before it writes a line, then works one territory at a time under a Lease.

Start here — the guided path

Inside the coding agent, the front door is emerik-guide. It turns the suite of skills into a guided method — just say what you need:

• Orient — “orient me”, “where am I?”, “what should I do next?” It derives where the repo stands from live substrate facts (index_status, anchor_list, lease_list, a committed Goal brief) and the installed skills' own declarations, then recommends the next step as a short menu — never a hardcoded script.
• Tour — “give me the emerik tour”, “show me how this works”. A hands-on walkthrough of the whole loop, each leg delegating to the real skill.
• Step-through — “walk me through emerik-goal step by step”. It wraps any suite skill with its gates made explicit, confirms at each gate, and reports what was read from and deposited into the graph.

What emerik init wired

• .mcp.json — registers the emerik mcp stdio server as an MCP server named emerik ({ "command": "emerik", "args": ["mcp"] }), merged additively so your other servers are untouched.
• .claude/skills/ — the fourteen shipped skills: emerik-brainstorm, emerik-brief, emerik-prd, emerik-architect, emerik-breakdown, emerik-discover, emerik-goal, emerik-plan, emerik-implement, emerik-review, emerik-guide, emerik-retro, emerik-orchestrate and emerik-onboard.
• .claude/agents/ — the four reviewer roles emerik-review fans out (blind-hunter, edge-case-hunter, acceptance-auditor, substrate-auditor).
• a delimited <!-- emerik:begin -->…<!-- emerik:end --> block in AGENTS.md (and CLAUDE.md when present) so a non-Claude harness (Codex, Cursor) reads the same context.

The thirty-five tools

The MCP surface is exactly thirty-five noun_verb tools, each a thin wrapper over the same engine the CLI calls:

emerik verify stays a shell gate, not a tool — it is the CI / verification step (exit 1 on any block-level failure), so an agent runs it from the terminal.

The fourteen shipped skills

The reviewer roles emerik-review fans out over ship under .claude/agents/ (blind-hunter, edge-case-hunter, acceptance-auditor, substrate-auditor) — each a subagent with only its allowed inputs, so a defect one reviewer rationalizes away another cannot. Those reviewers are the agent quorum — their verdicts feed the risk-tiered routing record below; the steward's batched digest of those records ships too — emerik review [domain] collapses a day of output into a few team-level rows.

A worked example — goal to verified change

The loop opens with emerik-goal: you hand it an intent, and it shapes a Goal brief — Goal statement, testable acceptance criteria, and guardrails that cite the live Pins and Anchors they must honor — committed under .emerik-goals/, then started as a first-class Goal with goal_start --brief and handed to the plan skill. (You can also state a Goal and its acceptance criteria inline to the plan skill; the committed brief, the first-class Goal, or the pasted-in version all work.) From there the loop runs end-to-end:

# Goal Add rate-limiting to the login route.
# Acceptance criteria
#  1. Repeated failed logins are throttled.
#  2. Credentials are never written to a log.

emerik-plan calls index_refresh so the plan reflects the latest committed facts, runs graph_retrieve for the Goal and each criterion, and lists live Anchors with anchor_list. A recently-moved Anchor is surfaced as a coordination note (a heads-up, not an alarm). It drafts checkbox steps that cite what they stand on, then commits the plan beside the Goal brief — the durable input to implementation, not chat:

✓ plan grounded in 3 Pins, 2 Anchors

- [ ] Step 1 — Add a retry counter to the login handler. Relies on Pin
         01J…A7 (login flow). Must honor constraint-Anchor 01J…D9
         "no unbounded retries" (BLOCK). P1.
- [ ] Step 2 — Redact credentials before logging. Relies on Pin 01J…B3
         (logger). Must honor antibody-Anchor 01J…E4 "never log
         credentials" (BLOCK). P0.

# the engineer commits the plan — the harvest hook fires
✓ .emerik-goals/rate-limit-login-plan.md

A step that cites no Pin or Anchor is grounded in raw code, not the substrate — the skill sends it back to the cascade. The committed doc means the next session (or a cheaper model) resumes from the first unchecked box — no need to keep this window open.

emerik-implement picks up the first unchecked step from the committed plan doc (via goal_status — a fresh session needs nothing else), claims a Lease on the territory before writing, then writes the failing test first and watches it fail — implementing to green (red-green-refactor) only once the test proves the behavior is missing. It commits with the step's checkbox flipped (the post-commit hook harvests the new Pins for you — you never hand-craft them), runs emerik verify, and releases the Lease. The step is done only when the new tests exist and pass and verify is green — never on claimed-but-unrun tests.

next step: - [ ] Step 1 — Add a retry counter …   (.emerik-goals/rate-limit-login-plan.md)

▣ LEASED  auth/login · holder plan-agent · expires in 15m

# … edit, flip the box to [x], then commit — the harvest hook fires automatically …

$ emerik verify
✓ 2 Anchor checks passed · no drift                                 exit 0

✓ released auth/login

Continuous integration

emerik verify is the gate. It exits 1 when any block-level Anchor check fails, so it drops straight into CI as a required step.

Copy- name: emerik verify
  run: |
    pnpm install --frozen-lockfile
    pnpm build
    ./bin/run.js verify        # fails the job on drift (exit 1)

The pre-push hook installed by emerik init re-derives Pin freshness before a push; pair it with the CI gate above for defence in depth.

Conventions

• Command grammar is emerik <noun> <verb>; flags are kebab-case; the global flags --json, --quiet, and --no-color work everywhere.
• JSON is camelCase everywhere — artifacts, --json output, and any future MCP surface.
• IDs are ULIDs; the source content hash lives inside the artifact, never in the filename.
• Append-only: a change is a new artifact with supersedes; a deletion is a tombstone.
• --quiet suppresses success output only — failures always print.

Command reference

Every command supports --help. Run emerik <command> --help for the full flag list.