archkit

╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║                  ▄▀█ █▀█ █▀▀ █ █ █▄▀ █ ▀█▀                   ║
║                  █▀█ █▀▄ █▄▄ █▀█ █ █ █  █                    ║
║                                                              ║
║             ◆ Context Engineering for AI Agents              ║
║            Give AI the blueprint, then the task.             ║
╚══════════════════════════════════════════════════════════════╝

The Problem

AI coding agents generate code that works in isolation but doesn't fit. They don't know your layer boundaries, naming conventions, package gotchas, or API contracts — so you end up reviewing and rewriting what was supposed to save you time.

archkit solves this by compiling your architecture into structured files the agent reads before writing a single line.

  +--------------+        +---------------------------+        +---------------+
  |              |        |         .arch/            |        |               |
  |  Your        | -----> |  SYSTEM.md    rules       | -----> |  AI Agent     |
  |  Codebase    |        |  INDEX.md     routing     |        |  writes code  |
  |              |        |  clusters/    graphs      |        |  that fits    |
  |              |        |  skills/      gotchas     |        |               |
  +--------------+        |  apis/        contracts   |        +---------------+
                          |  lenses/      overlays    |
                          +---------------------------+

Highlights

• Clear Goal Run (CGR) (v1.7+) — decompose a sprawling ask into discrete, one-per-fresh-context goals, then advance the queue with a single keystroke. A goal-aware Stop hook keeps the agent on the current goal until its exit-criteria are met. See below.
• Full MCP server — 31 tools (review, resolve, drift, doctor, boundaries, decisions, goals…), 4 prompts (the CGR relay slash commands), and MCP resources (@archkit: handles for .arch/ source). Native for Claude Code, Cursor, Continue.
• CGR test gate + deferred-goal proposals (v1.9) — every goal carries an auto-detected verify-command, and archkit_goal_complete refuses to finish a goal whose tests are red. Follow-up work spotted mid-goal is captured as a proposed goal (archkit_goal_defer + Stop-hook auto-drafting) and reviewed later instead of lost. See below.
• Continuous-guardrail hooks (v1.6+) — SessionStart, UserPromptSubmit, PostToolUse, and a goal-aware Stop hook fire every turn so archkit stays in working memory even on long sessions. Self-installing via archkit_install_hooks or the plugin.
• Static review engine — categorized check modules (imports, DB, API, frontend, event, cache/queue, production, completeness, app-specific) with required-justification suppression and language gating.
• Live runtime signal — preflight surfaces recent commits, scoped gotchas, active drift, and related ADRs per feature/layer, so agents see current state and prior decisions, not yesterday's snapshot.
• Institutional memory — log architectural decisions (archkit_log_decision) and read them back (archkit_decisions_search) so settled choices survive context resets.
• Lean footprint — 1 runtime dependency (inquirer), 82 source modules, 49 integration test suites.

Quick Start

git clone https://github.com/kenandrewmiranda/archkit.git
cd archkit && npm install
npm link                   # expose the archkit CLI globally

# Greenfield — 7-step interactive wizard
archkit

# Existing codebase — auto-detect architecture
archkit init

# With Claude Code native integration
archkit --claude

archkit --claude emits CLAUDE.md, .claude/rules/, .claude/skills/, a pre-commit review hook, and a PreToolUse guard — fully integrated out of the box.

MCP server (Claude Code, Cursor, Continue)

archkit ships a Model Context Protocol server so AI agents can call archkit's review/resolve/stats tools natively, without shell-outs.

Install — Claude Code plugin (recommended)