ark-runtime-kernel

Ark — Architecture Co-pilot for AI TypeScript

Write gate · CI gate · co-pilot for TypeScript projects that use AI agents.

Your AI writes most of the code. Ark keeps that code inside an architecture you can trust — and makes sure a “green” check means something real.

What it is

Ark is a machine-readable architecture contract for TypeScript, enforced in three places:

When	Tool	What happens
While the AI writes	ark-mcp (write gate)	Blocks bad edits; agent self-corrects
Before merge	ark-check (CI)	Full TypeScript import graph + rules
At runtime (optional)	createArkKernel()	Event/intent governance if you opt in

One file drives all of it: ark.config.json.

It is not a web framework, ORM, or job runner — and the optional runtime kernel is not the product. The product is the agent-native architecture gate (write path + CI + plan/loop) plus tools agents can read before generating code (ark_place, ark://manifest, …).

Who it’s for

You are…	You want…	Start with
Builder with AI (not necessarily an architect)	Order without learning “hexagonal” first	npx ark start → /ark-autopilot
Engineer / tech lead	A strict contract, CI, baselines, precise control	ark init + ark-check + write gate
Team on a messy repo	Truth about coverage + a cleanup path, not a false green	ark-check --coverage → /ark-adopt

Not for: projects with no TypeScript, people who only want a one-off lint rule and no agent workflow, or anyone looking for an app framework.

What you get (in plain language)

• A shape — Ark looks at your repo (Nest, Next, API, library, …) and suggests how to organize it.
• Guardrails — config + agent gates + CI so new code can’t quietly break layers.
• A plan — what’s safe for an agent to fix vs what needs your decision.
• Honesty — if Ark only governs 10% of the tree, it says so. “Clean” with almost no coverage is not success.

Three operating modes (not “user types”) on the same contract:

Mode	Meaning
Suggest	Install a starting shape
Adapt	Match the contract to real folders / raise coverage
Enforce	Gates actually protect you

Start in one minute

npm install -D ark-runtime-kernel typescript
npx ark start          # look at the project → setup → plan (plain language)

Then, in your agent (Claude / Cursor / Codex / Grok / …):

/ark-autopilot

That is the co-pilot: set up → plan → apply safe fixes (validated, reversible) → propose the rest → leave gates on.

Prefer manual control?

npx ark init           # config + gates
npx ark-check          # CI gate
npx ark-check --plan   # classified fix list
npx ark-check --coverage

Works with npm, pnpm, and yarn. No install lifecycle scripts (safe for hardened CI).

Agent skills (/ark-*)

Install with agent gates:

npx ark-check --install-agent-gates
# or pick hosts: --tools claude,cursor,codex,grok

Skill	What it does
/ark-autopilot	End-to-end co-pilot: setup → plan → safe auto-fixes → propose the rest → leave gates on
/ark-loop	Drive the remediation plan in a discardable worktree; only mechanical-safe steps auto-apply
/ark-architect	Greenfield: pick application shape, phase-1 layers, scaffold, verify honestly
/ark-adopt	Brownfield: match contract to reality, raise coverage, freeze only real debt
/ark-contract	Safely edit ark.config.json (smallest change, strict re-check)
/ark-place	Where does this new artifact go? Layer, path, naming — then scaffold
/ark-fix	Fix violations at the source (no disable comments, no gate weakening)
/ark-explain	Explain the current contract, coverage, and report in plain language
/ark-coverage	Audit which Ark capabilities you are not using yet
/ark-runtime	Opt-in: migrate hand-rolled bus/outbox/sagas onto the runtime kernel
/ark-upgrade	Bump the package and refresh gates + skills for every agent host

Supported agent hosts for full MCP/hook gates: Claude Code, Cursor, OpenAI Codex, Grok Build. Instruction-tier hosts (Windsurf, Cline, Copilot, …) get rule files. See docs/ai-gates.md.

How it works (short)

ark.config.json
      │
      ├─► Write gate (ark-mcp)     — agent PreToolUse / MCP tools
      ├─► CI gate (ark-check)      — PR / main
      └─► Runtime kernel (opt-in)  — only if you call it

• Presets: hexagonal, layered, feature-sliced, monorepo (all layers optional).
• 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-adopt for mature trees.
• Agents: skills above install into Claude / Cursor / Codex / Grok command locations.

Why not only ESLint / dependency-cruiser / Nx?

	Ark	Typical boundary linter
CI import rules	✅	✅
Block AI writes before they land	✅	❌
Contract agents can read (ark://manifest)	✅	❌
Placement tools (ark_place, …)	✅	❌
Honest governed % + adoption path	✅	❌
Zero runtime dependencies	✅	varies

Common commands

npx ark start                         # guided setup + plan
npx ark-check --doctor                # health + operating mode
npx ark-check --plan                  # safe-to-auto-fix vs your call
npx ark-check --coverage              # Governed: N%
npx ark-check --report ark-report.html  # showcase HTML + origin/latest snapshots
npx ark-check --baseline              # only NEW violations fail
npx ark upgrade                       # update package + refresh gates/skills

CI (example):

- run: npx ark-check --root . --config ark.config.json --strict-config
# or: uses: pedroknigge/ark-runtime-kernel@main

Optional: runtime kernel

Gates need no app code changes. If you also want runtime intent/event contracts:

import { createStrictArkKernelFromConfig } from 'ark-runtime-kernel';
// see docs/production-hardening.md and package exports

NestJS: ark-runtime-kernel/nestjs (optional peer @nestjs/common).

Documentation

Audience	Link
New builders (plain language)	docs/enthusiast/
Wire Claude / Cursor / Codex / Grok	docs/ai-gates.md
Messy existing repo	docs/brownfield-adoption.md
Agent / MCP tools	docs/agent-guide.md
Demos	docs/demos/
Examples	examples/
Roadmap	ROADMAP.md · Changelog

Develop this repo

npm ci && npm run build
npx vitest run
npm run typecheck
npm run check:architecture   # Ark gates itself

npm package name (historical): ark-runtime-kernel — install path and GitHub repo stay on that name for now. Product name is Ark (architecture co-pilot / gate). A clearer package name is planned for a future major; this line is not the product identity.

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.