archkit Documentation

Give AI the blueprint before you give it the task.

Installation

# Option 1: Clone (recommended)
git clone https://github.com/kenandrewmiranda/archkit.git
cd archkit && npm install

# Option 2: Global install
npm install -g github:kenandrewmiranda/archkit

# Option 3: One-shot
npx github:kenandrewmiranda/archkit

Quick Start

New project — interactive wizard

archkit                     # Scaffold .arch/ with 7-step wizard
archkit --claude            # + Claude Code native files (hooks, skills, rules)

Existing project — auto-detect

archkit init                # Reverse-engineer .arch/ from codebase
archkit init src --json     # Detection only, no file generation

Upgrade from 1.0

archkit update              # Self-update from GitHub
archkit migrate --dry-run   # Preview migration (safe)
archkit migrate             # Upgrade .arch/ without losing gotchas/rules

What Gets Generated

.arch/ Directory

Claude Code Native (--claude)

Skills skill

Skills teach AI agents about package-specific patterns and antipatterns. Each gotcha entry shows what the AI would generate by default (WRONG), the correct approach (RIGHT), and a one-line explanation (WHY).

# postgres.skill

## Meta
pkg: pg@8
docs: https://node-postgres.com
updated: 2026-04-04

## Use
PostgreSQL with Row-Level Security for multi-tenant SaaS.

## Gotchas
WRONG: SELECT * FROM users WHERE id = $1
RIGHT: SELECT id, email, name FROM users WHERE id = $1 AND tenant_id = $2
WHY: Missing tenant_id allows cross-tenant data access.

## Boundaries
Does not handle authorization logic — only tenant isolation.

## Snippets
```sql
CREATE POLICY tenant_isolation ON users
  USING (tenant_id = current_setting('app.tenant_id')::uuid);
```

Graphs graph

Graphs define feature architecture using a compact notation. Each node represents a code unit (controller, service, repository) with its layer, responsibility, and connections.

--- auth [feature] ---
AuthCont      [C]    : OAuth routes, /auth/sync, /auth/me | $auth → THIS → AuthSer
AuthSer       [S]    : Token exchange, user sync, ban check | AuthCont ← THIS → AuthRepo
AuthRepo      [R]    : users table lookup, create user | AuthSer ← THIS → $db
AuthType      [T]    : AuthContext, SyncUserInput
AuthVal       [V]    : Zod schemas for auth input
AuthTest      [X]    : unit + integration tests
---

Node Layers

Flow Notation

Presets preset

Presets configure archkit's scaffolding wizard. They define the app type, tech stack, features, and skills to install.

{
  "appName": "saas-starter",
  "appType": "saas",
  "stack": {
    "Frontend": "Next.js + Tailwind",
    "API": "Hono",
    "Database": "PostgreSQL (with RLS)"
  },
  "features": [
    { "id": "auth", "name": "Authentication" }
  ],
  "skills": ["postgres", "valkey", "keycloak"],
  "claudeMode": true
}

Run with: archkit init --preset saas-starter.json

Supported App Types

Scaffold & Setup

Context Resolution

All resolve commands return structured JSON on stdout (log output on stderr). Safe to pipe.

Code Review

App-type-aware review that checks against rules, boundaries, and gotchas.

Review Checks by App Type

Knowledge Capture

Health & Maintenance

Multi-Tool Export

Extensions

For AI Agents

All resolve, review, gotcha --json, drift, sync commands return structured JSON on stdout. Log output goes to stderr — safe to pipe.

# Agent workflow:
archkit resolve warmup                              # health check
archkit resolve context "add user notifications"    # get relevant files/rules
archkit resolve plan "add user notifications"       # get implementation steps
archkit review --staged --agent                     # pre-commit gate
archkit gotcha --json postgres "wrong" "right" "why" # capture learning

Token Budget

archkit shows token estimates for every generated file and warns when always-loaded context exceeds budget:

• EFFICIENT (<1000 tokens) — minimal overhead
• MODERATE (1000-2000) — good for always-loaded
• HIGH (2000-3000) — consider trimming
• OVER BUDGET (>3000) — use CONTEXT.compact.md for cheap-model calls

Upgrading from 1.0

archkit update              # Get latest code
archkit migrate --dry-run   # Preview changes (safe)
archkit migrate             # Apply upgrade

Migration preserves all user content (gotchas, learned rules, cross-refs) while adding:

• BOUNDARIES.md, CONTEXT.compact.md
• Built-in gotchas merged into existing skills
• Session Management table
• archkit-protocol skill + hooks (if --claude was used)