One contract. One gate. One co-pilot.
Your AI writes most of the code. ArkGate keeps that code inside an architecture you can trust — and makes sure a “green” check means something real.
ArkGate 3.0 passed its independent beta-exit audit. The npm badge reports the version currently available in the registry.
If you remember nothing else:
1. npx arkgate start ← read-only preview: files + commands + projected coverage
npx arkgate start --apply ← apply exactly the previewed mutations
2. Compact router ← MCP/AGENTS routes place, validate, and architecture checks
/ark-autopilot ← optional full guided workflow after its skill pack is installed
3. npx arkgate-check --doctor ← “where am I?” anytime (one status screen)
| Stuck on… | Do this |
|---|---|
| Gate failed after an edit | /ark-fix |
| “Where does this new file go?” | /ark-place |
| Contract globs / layers wrong | /ark-contract |
| Messy / spaghetti code (even if the gate is green) | /ark-explore then /ark-autopilot — below |
| New ArkGate version | /ark-upgrade |
Everything else is optional. You do not need to learn “modes”, 11 skills, or the runtime
kernel to get value. The compact router is enough for normal work; install /ark-autopilot only
when you want the full guided workflow.
ArkGate = a machine-readable architecture file (ark.config.json) enforced at CI, with
host-specific protection while an agent writes:
Name note: this is the TypeScript architecture-enforcement package published as arkgate.
It is not affiliated with the separate Archgate CLI project.
| When | Tool |
|---|---|
| While the AI writes | Hard PreToolUse block on Claude/Grok; advisory MCP on Cursor/Codex |
| Before merge | arkgate-check CI check; merge blocking requires it as a required status |
Optional later: the experimental runtime kernel (createArkKernel) if you want to evaluate
event/intent governance. It is not required for gate adoption.
It is not a web framework, ORM, or job runner.
Same start for almost everyone: npx arkgate start → compact router (then
/ark-autopilot when you opt into the full skill pack).
| You are… | Same start, then… |
|---|---|
| Builder with AI | Use the compact router and doctor; add autopilot when you want guided remediation |
| Tech lead on a messy monorepo | Add autopilot (or deeper /ark-adopt for a focused brownfield pass) |
| Power user | Same flow; use ark-check --plan / --coverage when you want the raw sensor |
Not for: no TypeScript, “just one lint rule”, or looking for an app framework.
ark-check --doctor may say Suggest / Adapt / Enforce. That is a status light, not a
mode you configure:
| Light | Means | Your move |
|---|---|---|
| Suggest | New/thin project | Finish start + autopilot |
| Adapt | Not fully protected yet | Keep autopilot / adopt until clean |
| Enforce | Contract coverage is honest and checked edges are clean | Keep write path + CI. If the tree is still a mess → Shape flow |
| Enforce · design-weak | Edges clean, but doctor still sees design smells (designSmells / patternBets) |
/ark-explore (shape-focus) → /ark-autopilot for dual-plan B — not “done” |
You arrive at Enforce. You never “turn on Enforce”.
Enforce does not mean the design is elegant — only that the contract’s import edges are honest.
A green check can still leave god modules, SQL in routes, and three patterns at once. That residual is Shape work — plan B, never auto-applied as mechanical-safe.
1. /ark-explore ← map + dual-plan B + extraction cards (no apply)
2. /ark-autopilot ← apply A (edges); B only with your ok, one pilot at a time
3. npx arkgate-check --doctor
npx arkgate-check --plan --json ← designWeak + patternBets when residual remains
| If… | Skill |
|---|---|
| Need the map / “what’s the golden pattern?” | /ark-explore |
| Ready to execute the dual plan | /ark-autopilot |
| Contract still lies (false-green, wrong globs) | /ark-adopt first, then explore |
| One cluster only | /ark-fix (+ extraction card) |
| Only care about governed% / gates installed | /ark-coverage (not the Shape map) |
Phases: Align (honest contract) → Stabilize (real baseline) → Shape (golden pattern + pilot).
Details: docs/brownfield-adoption.md §6 · skills install: npx arkgate-check --install-agent-gates.
Same product, new package name. Config and /ark-* skills stay.
npm uninstall ark-runtime-kernel && npm install -D arkgate
npx arkgate-check --install-agent-gates --force
npx arkgate-check --doctorFull checklist (CI, MCP, Codex, imports): docs/migrate-from-ark-runtime-kernel.md.
npm install -D arkgate typescript
npx arkgate start # read-only preview: exact mutations + projected coverage
npx arkgate start --apply # apply the compact contract → active-host router → CI plan
# optional, after installing the full skill pack:
# /ark-autopilot
npx arkgate-check --doctor # status light + next actionAliases ark / ark-check / ark-mcp still work. npm / pnpm / yarn. No install lifecycle scripts.
What /ark-autopilot does under the hood (optional detail)
- Setup if needed (
ark start— compact contract + active-host router + CI gate; create an HTML/origin report explicitly when you need one). - Explore pass (decision-grade map of this product; field path when demos exist).
- Dual plan: A remediation from
--plan(mechanical-safe only by default); B pattern/evolution bets (never auto-applied as mechanical-safe). Empty plan ≠ “healthy” without explore/B. - Apply A → re-check; judgment only when you ask for full apply.
- Gates on + latest report (evolution vs frozen origin).
Standalone recon without applying: /ark-explore.
Manual / power-user CLI only
npx arkgate init
npx arkgate-check
npx arkgate-check --plan
npx arkgate-check --coverageInstall once: npx arkgate-check --install-agent-gates
(--tools claude,cursor,codex,grok to pick hosts.)
The compact router is the default; /ark-autopilot is the full guided option. The rest are
escapes, not a second curriculum. Full-install AGENTS.md includes a skill routing table
(trigger → skill). Skills are
dual-engine (CLI sensor + read real source) and end with a fixed completion contract;
critical handoffs say STOP and name the next skill (hosts must follow — markdown cannot chain calls).
When the host allows it, skills may fan out parallel subagents (disjoint scopes);
otherwise they fall back to sequential.
Write path (Track W): Prefer MCP ark_prepare_write when you have a snippet (place +
constrain + validate + optional autoPatch + judgmentBrief). PreToolUse hooks with
--hook-repair on Claude/Grok emit machine-readable repair payloads on deny (still hard block;
never silent write). Cursor/Codex MCP calls remain advisory. See
docs/ai-gates.md.
| Need | Skill | Not |
|---|---|---|
| Only the apply loop for plan A (edges) | /ark-loop |
empty A + design residual → explore |
| Empty greenfield shape/scaffold | /ark-architect |
brownfield → adopt |
| Brownfield contract match / baseline / manifest | /ark-adopt |
map-only → explore |
| Map / dual-plan seed / spaghetti Shape plan (no apply) | /ark-explore |
fitness-only → coverage |
| New file placement | /ark-place |
— |
| Gate violation on a change | /ark-fix |
bulk → loop/autopilot |
| One design decision (2–3 options) | /ark-think |
full dual-plan → explore |
Edit ark.config.json safely |
/ark-contract |
— |
| Plain-language tour / HTML report | /ark-explain |
recon → explore |
| Ark fitness (governed%, gates, install gaps) | /ark-coverage |
full recon → explore |
| Evaluate experimental runtime | /ark-runtime |
— |
| Bump ArkGate + refresh active host | /ark-upgrade |
— |
Brownfield phases: Align (honest contract) → Stabilize (real baseline) → Shape (golden pattern + pilot). ENFORCE with empty plan A can still be design-weak — that residual is explore/autopilot B, not “done.”
| Host | Local write boundary | MCP validation | CI / merge path | Repair payload |
|---|---|---|---|---|
| Claude Code | Hard block for PreToolUse Write / Edit / MultiEdit |
Advisory; the agent must call it | Available arkgate-check --strict-merge check |
Emitted on hook deny; host must re-inject |
| Grok Build | Hard block for PreToolUse write / search_replace (plus aliases) |
Advisory; the agent must call it | Available arkgate-check --strict-merge check |
Emitted on hook deny; host must re-inject |
| Cursor | No hard hook; MCP/rules are advisory | Advisory; the agent must call it | Available arkgate-check --strict-merge check |
No hard-boundary payload |
| OpenAI Codex | No hard hook; MCP/rules are advisory | Advisory; the agent must call it | Available arkgate-check --strict-merge check |
No hard-boundary payload |
This table describes the supported profile after its files are installed and the host loads/trusts them. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair payloads never write code silently: the host must re-inject the candidate and ArkGate revalidates it. Run arkgate-check --doctor for the evidence actually detected in the current repository.
Detailed setup: docs/ai-gates.md.
ark.config.json
│
├─► Write path (arkgate-mcp) — hard hook or advisory MCP, by host
├─► CI check (arkgate-check) — merge block only when status is required
└─► Runtime kernel — experimental opt-in; gates do not need it
- Presets: hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts (+ aliases clean-architecture / onion-architecture). Layers start optional; doctor suggests tightening populated cores. Cross-slice / cross-context bans use optional
peerIsolationrules. - Versioned config: generated contracts include
$schema+schemaVersion; CLI, MCP, and ESLint validate through the same loader. Unknown keys fail with their JSON path. See the configuration and editor guide. - Frameworks: Nest / Next / express / library layouts get sensible globs on init so day-one coverage is real.
- Brownfield: baseline ratchet, refuse to freeze a wrong contract,
/ark-adoptfor mature trees. - Agents:
ark startasks for (or detects) one active host and writes one compact router, not copied skill packs, in at most five project files and 25 KB. Useark-check --install-agent-gates --skills-only --tools <host>later when you explicitly want the full/ark-*skill set. Reports are opt-in withark-check --report. - Write protocol (2.10 / Track W): mechanical-safe autoPatch on the write gate (
import type); MCPark_prepare_write(place + validate + patch + judgmentBrief); opt-in hook--hook-repair(ARK_REPAIR_JSON); doctorwritePath(repair vs reject-only); loop-cost eval (npm run eval:loop-cost). Port-proof inject is judgment (arity change), not silent auto-apply. - Fail-closed CI (2.11):
--strict-mergecombines config coverage, shared gate-file presence, and bypass diagnostics for dynamic imports, TypeScript suppressions, explicitanycasts, InMemory runtime defaults, and disabled peer isolation.--strictis a compatibility alias. Neither requires an editor hook; use--require-write-hook claude|grokwhen that local guarantee is part of the check. - Trust / coverage (3.0 release baseline): package unit-test floors on the broad product surface (statements/lines ≥80%, branches/functions ≥85%; enforcement-critical modules ≥95% branch). The V05 beta-exit audit passed with 12 pinned public adoptions, 97% median governed coverage, and zero P0/P1 findings. Stable publication remains the signed-tag, GitHub Release, and provenance-backed npm workflow documented in the 3.0.0 release notes.
- TypeScript: project compilers 5.x / 6.x / 7.x — gate falls back to a nested JS-API TypeScript when TS 7’s main export is version-only (docs/typescript-support.md).
| ArkGate | Typical boundary linter | |
|---|---|---|
| CI import rules | ✅ | ✅ |
| Hard-block supported-host AI writes before they land | ✅ (Claude/Grok hooks) | ❌ |
Contract agents can read (ark://manifest) |
✅ | ❌ |
Placement tools (ark_place, …) |
✅ | ❌ |
| Honest governed % + adoption path | ✅ | ❌ |
Classified plan (mechanical-safe / judgment) |
✅ | ❌ |
| TypeScript 5 / 6 / 7 project compilers | ✅ | varies |
| Adoption scorecard (hosts / MCP / origin) | ✅ | ❌ |
| Editor ESLint same layer contract as CI | ✅ (arkgate/eslint) |
varies |
npx arkgate start # guided read-only preview
npx arkgate start --apply # apply the compact active-host setup (≤5 files)
npx arkgate start --tools codex --apply # select the host explicitly
npx arkgate start --install --apply # also add arkgate to package.json (explicit only)
npx arkgate start --remove-host codex # preview compact-host removal; add --apply to confirm
npx arkgate-check --doctor # health + Adoption gaps (not just fitness)
npx arkgate-check --doctor --json # machine-readable doctor.adoption
npx arkgate-check --strict # fail-closed CI + installed-gate/safety checks
npx arkgate-check --plan # safe-to-auto-fix vs your call
npx arkgate-check --coverage # Governed: N%
npx arkgate-check --report ark-report.html # showcase HTML (opens in browser on local TTY; --no-open to skip)
npx arkgate-check --baseline # only NEW violations fail
npx arkgate upgrade # package + gates/skills + MCP/Codex normalizeCI (example):
- run: npx arkgate-check --root . --config ark.config.json --strict
# or: uses: pedroknigge/arkgate@<tag-or-SHA> # runs that checked-out revisionGates need no app code changes. The runtime API is currently experimental and is not a production-readiness claim. If you want to evaluate runtime intent/event contracts, use the separate experimental package:
import { createStrictArkKernelFromConfig } from '@arkgate/runtime';
// see docs/production-hardening.md and docs/package-surface.mdThe stable arkgate package does not bundle runtime implementation. The deprecated
arkgate/runtime forwarding shim requires @arkgate/runtime and is removed in ArkGate 4.
NestJS: @arkgate/runtime/nestjs (optional peer @nestjs/common).
The kernel’s default stores (InMemoryEventBuffer, InMemoryAuditStore,
InMemoryReadModelStore, InMemoryWorkflowStore) are reference in-memory only:
fine for tests, demos, and single-process local work — they do not survive restarts
and are not production durability. Implement the store interfaces (or inject your own)
for real systems. Details: docs/production-hardening.md.
| Audience | Link |
|---|---|
| New builders (plain language) | docs/enthusiast/ |
| Package surface (stable vs experimental) | docs/package-surface.md |
| Wire Claude / Cursor / Codex / Grok + ESLint (CI-parity) | docs/ai-gates.md |
| TypeScript 5 / 6 / 7 support | docs/typescript-support.md |
Migrate from ark-runtime-kernel |
docs/migrate-from-ark-runtime-kernel.md |
| Messy existing repo | docs/brownfield-adoption.md |
| Agent / MCP tools | docs/agent-guide.md |
| Demos | docs/demos/ |
| Examples | examples/ |
| Release 3.0.0 | release notes and publication checklist |
| Roadmap | ROADMAP.md · Changelog |
npm ci && npm run build
npx vitest run
npm run typecheck
npm run check:architecture # Ark gates itselfWebsite: arkgate.online
npm: arkgate · formerly ark-runtime-kernel
Product: ArkGate — architecture co-pilot / gate for AI TypeScript (not a runtime kernel).
CLI: arkgate · arkgate-check · arkgate-mcp (aliases ark / ark-check / ark-mcp still work for one major).
MCP registry: io.github.pedroknigge/arkgate.
Source: github.com/pedroknigge/arkgate
Node ≥ 18 · MIT.
Ark doesn’t invent your product. It keeps AI-generated TypeScript inside an architecture you can trust — and tells you when it isn’t really enforcing anything yet.