One contract. One gate. One co-pilot.

You do not need to study clean architecture first. Install, apply start, run doctor—then do primary next action #1 when stuck.

In one minute

Install and doctor

npm install -D arkgate typescript

npx arkgate start

npx arkgate start --apply

npx arkgate-check --doctor

Doctor is the control plane. Full skill pack is optional expert depth. Day-to-day: compact router + doctor.

Full quickstart

What you get

While you write and before merge

When	What happens
While the AI writes	Host write gate or advisory MCP (depends on host)
Before merge	`arkgate-check` — make it a required CI status
Anytime	Doctor: Suggest / Adapt / Enforce (+ design-weak if residual)

ArkGate is not a web framework, ORM, or app runtime. It is architecture enforcement and co-pilot for AI TypeScript.

Dual plane

Layers always · ArkRules optional

Plane	Plain English	Enforces
Layers	Who may talk to whom	Import direction, purity, forbidden globals, capabilities, peer isolation
ArkRules (optional)	Habits inside a layer + named policies	Structure heuristics; invariant catalog + coverage evidence—not full business proof

Green Layers ≠ perfect design. Covered invariants ≠ “the business always does the right thing”—they mean a named policy is declared and has symbol/test evidence.

Status lights

Not settings you pick

Suggest

New or thin

Finish start, re-run doctor.

Adapt

Not fully protected

Doctor action #1 until clean.

Enforce

Edges honest

Keep write path + CI.

Enforce · design-weak

Design still messy

Shape door—not “done.”

Shape residual

When the gate is green but the code is still messy

That is Shape work (plan B)—suggested, never auto-applied as silent magic.

Doctor confirms design-weak
Guided map / dual plan (optional skill pack: /ark-explore then /ark-autopilot with your OK)
One pilot at a time · re-run doctor

npx arkgate-check --install-agent-gates --skills-only --force

More depth: Develop path · How it works · Full use.md on GitHub ↗