# Archcodex

> ArchCodex Specs and Guardrails for Coding agents

- **Type:** MCP server
- **Install:** `agentstack add mcp-archcodexorg-archcodex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ArchCodexOrg](https://agentstack.voostack.com/s/archcodexorg)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ArchCodexOrg](https://github.com/ArchCodexOrg)
- **Source:** https://github.com/ArchCodexOrg/archcodex
- **Website:** https://medium.com/@stefanvanegmond

## Install

```sh
agentstack add mcp-archcodexorg-archcodex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ArchCodex

[](https://github.com/ArchCodexOrg/archcodex/actions/workflows/ci.yml)
[](https://codecov.io/gh/ArchCodexOrg/archcodex)
[](https://opensource.org/licenses/MIT)

**The Architectural Compiler for LLM Agents**

> **Research Project:** This is an experimental tool exploring whether explicit architectural constraints and context hydration can prevent architectural drift in AI-assisted codebases and produce more predictable, consistent agent output.

ArchCodex enforces architectural constraints through context hydration. Developers write minimal `@arch` tags; LLM agents retrieve fully hydrated headers with constraints, hints, and documentation references via the `archcodex read` command.

```
Developer writes:  /** @arch domain.payment.processor */
Agent retrieves:   archcodex read file.ts --format ai → Full constraints, hints, documentation
```

## Why ArchCodex?

LLM agents are good at writing code that *works*. They're bad at writing code that *belongs*.

Every codebase has an implicit architecture: conventions, patterns, module boundaries, the "how we do things here" that experienced developers carry as tribal knowledge. LLMs can't read tribal knowledge. They write code that compiles and passes tests, but violates architectural boundaries — using manual permission checks instead of the centralized helper, importing across layer boundaries, reinventing utilities that already exist.

Worse, **drift compounds**. When inconsistency creeps into a codebase — multiple ways of doing the same thing, competing patterns, duplicate utilities — LLMs perform *worse*. They copy the wrong pattern because it appeared more recently in context. Each drifted commit makes the next one more likely. The codebase doesn't drift all at once; it drifts one "working" commit at a time.

ArchCodex solves this by:

- **Hydrating constraints** via the `archcodex read` command for AI agents
- **Validating compliance** on save, commit, and CI
- **Guiding new file creation** with discovery and scaffolding
- **Documenting exceptions** with auditable overrides

## Installation

> **Note:** ArchCodex is not yet published to npm. Install from source:

```bash
# Clone the repository
git clone https://github.com/ArchCodexOrg/archcodex.git
cd archcodex

# Install dependencies and build
npm install
npm run build

# Link globally (optional)
npm link
```

## Quick Start

### 1. Initialize your project

```bash
archcodex init
```

Creates `.arch/` directory with configuration files.

### 2. Define architectures

In `.arch/registry/` (or a single `.arch/registry.yaml`):

```yaml
domain:
  description: "Base domain constraints"
  rationale: "Foundation for all domain code"
  constraints:
    - rule: forbid_import
      value: [console]
      severity: error
      why: "Use Logger service instead"

domain.payment:
  inherits: domain
  description: "Payment domain - PCI compliance"
  rationale: "Use for any code handling payment data"
  constraints:
    - rule: forbid_import
      value: [http, axios]
      severity: error
      why: "Use ApiClient for PCI-compliant logging"
  hints:
    - "Redact CVV/PAN before logging"
```

### 3. Tag your files

```typescript
/** @arch domain.payment */
export class PaymentService {
  // ...
}
```

### 4. Validate

```bash
archcodex check src/**/*.ts
```

> **New to ArchCodex?** See the [Getting Started Guide](docs/getting-started.md) for a comprehensive tutorial covering new projects and existing codebase adoption.

## Core Concepts

### @arch Tags

Every source file should have an `@arch` tag declaring its architecture:

```typescript
/**
 * @arch domain.payment.processor
 */
```

Use `archcodex discover "description"` to find the right architecture for new files.

### Constraints

Rules enforced on files:

| Constraint            | Description               |
| --------------------- | ------------------------- |
| `forbid_import`       | Block specific imports    |
| `require_import`      | Require specific imports  |
| `require_decorator`   | Require class decorators  |
| `max_file_lines`      | Limit file length         |
| `require_test_file`   | Require companion tests   |
| `require_call_before` | Require permission checks |

See [Constraint Reference](docs/constraint-reference.md) for all 28 constraint types.

### Inheritance & Mixins

Architectures inherit from parents and compose mixins:

```yaml
domain.payment.processor:
  inherits: domain.payment
  mixins: [tested, srp]
```

### Overrides

When a legitimate exception is needed:

```typescript
/**
 * @arch domain.payment.processor
 * @override forbid_import:http
 * @reason Legacy API requires direct HTTP access
 * @expires 2026-06-01
 */
```

### Semantic Intents

Declare intentional patterns that satisfy constraints. Intents work at file-level or function-level:

```typescript
// File-level intent (applies to entire file)
/**
 * @arch domain.query
 * @intent:includes-deleted
 */

// Function-level intent (applies to specific function)
/** @intent:cli-output */
function printReport() {
  console.log(report);  // ✓ allowed
}
```

See [Semantic Intents](docs/intents.md) for details.

## CLI Quick Reference

| Category        | Commands                                                              | Description                      |
| --------------- | --------------------------------------------------------------------- | -------------------------------- |
| **Validation**  | `check`, `verify`, `health`, `why`, `test-pattern`                    | Validate files and check health  |
| **Discovery**   | `discover`, `decide`, `resolve`, `diff-arch`, `schema`, `graph`       | Find and explore architectures   |
| **Scaffolding** | `scaffold`, `action`, `feature`, `tag`, `infer`, `bootstrap`, `learn` | Create and tag files             |
| **Analysis**    | `read`, `neighborhood`, `types`, `garden`                             | Analyze code with context        |
| **Registry**    | `reindex`, `sync-index`, `migrate-registry`, `audit`, `intents`       | Manage registry and index        |
| **Versioning**  | `diff`, `migrate`, `simulate`, `watch`, `init`, `fetch`, `feedback`   | Version control and migrations   |
| **SpecCodex**   | `spec list`, `spec generate`, `spec verify`, `spec infer`, `spec drift` | AI and token friendly Specifications with determenistic test generation           |

### Essential Commands

```bash
# Discover architecture for new file
archcodex discover "payment processor"

# Read file with architectural context (AI-optimized)
archcodex read src/payment/processor.ts --format ai

# Check import boundaries before adding imports
archcodex neighborhood src/payment/processor.ts

# Validate files
archcodex check src/**/*.ts --json

# Generate new file from template
archcodex scaffold domain.payment.processor --name RefundProcessor

# View architecture health
archcodex health
```

## Configuration

### `.arch/config.yaml`

```yaml
version: "1.0"

files:
  untagged:
    policy: warn  # allow | warn | deny

validation:
  fail_on_warning: false
  precommit:
    max_errors: 0
    output_format: compact
```

See [Configuration Reference](docs/configuration.md) for all options.

### `.archignore`

Exclude files from validation (gitignore syntax):

```gitignore
dist/
node_modules/
**/*.test.ts
```

## AI Integration

ArchCodex integrates with AI coding assistants:

- **AI-optimized output** - `archcodex read --format ai`
- **MCP Server** - Native Claude Code integration
- **Pattern registry** - Canonical implementations
- **Actionable errors** - Structured fix suggestions

See [AI Integration Guide](docs/ai-integration.md) for setup.

## SpecCodex: Specification by Example

ArchCodex validates **structure** — imports, layer boundaries, naming patterns. SpecCodex validates **behavior** — function contracts, examples, invariants. Together they catch both structural drift and behavioral drift: code that compiles but violates boundaries *and* code that passes tests but doesn't match its documented contract.

### How It Works

```
Write spec → Validate → Generate tests → Verify implementation → Detect drift
```

| Phase | Command | What it does |
|-------|---------|-------------|
| **Write** | Manual or `spec infer` | Define behavioral contract in YAML |
| **Validate** | `spec check` | Verify spec structure, inheritance, mixins |
| **Generate** | `spec generate` | Deterministic test generation (unit, property, integration) |
| **Verify** | `spec verify` | Check implementation matches spec (bidirectional) |
| **Drift** | `spec drift` | Find specs without implementations and vice versa |

### Spec Structure

```yaml
spec.product.create:
  inherits: spec.mutation                              # Inherits auth defaults
  implementation: src/domain/products/mutations.ts#create

  # Strategic — why this exists
  goal: "Create a new product with validation"
  intent: "User creates a product listing"

  # Contract — inputs, outputs, security
  inputs:
    name: { type: string, required: true, max: 200 }
    price: { type: number, required: true }
    category: { type: enum, values: [electronics, clothing, food] }

  outputs:
    _id: { type: id, table: products }
    name: { type: string }
    createdAt: { type: number }

  security:
    authentication: required
    authorization:
      - { resource: products, access_level: edit }

  # Behavioral rules that must always hold
  invariants:
    - "createdAt must be within 5 seconds of request time"
    - "price must be greater than 0"

  # Concrete test cases — deterministic test generation
  examples:
    success:
      - name: "create with valid data"
        given: { name: "Widget", price: 29.99, category: "electronics" }
        then:
          result._id: "@defined"
          result.name: "Widget"
          result.createdAt: "@gte(@now() - 5000)"
    errors:
      - name: "missing name"
        given: { price: 29.99 }
        then: { error: "INVALID_INPUT" }
      - name: "unauthenticated"
        given: { user: null, name: "Test", price: 10 }
        then: { error: "NOT_AUTHENTICATED" }
```

### Inheritance & Mixins

Specs inherit from base types and compose reusable behavioral patterns:

```yaml
# Base specs provide defaults
spec.function    # Pure functions, no auth
spec.mutation    # Authenticated writes (inherits security defaults)
spec.query       # Authenticated reads
spec.action      # External API calls with side effects

# Mixins add cross-cutting concerns
spec.product.create:
  inherits: spec.mutation
  mixins:
    - requires_auth
    - logs_audit: { action: "product.create", resource: "product" }
    - rate_limited: { requests: 60, window: "15m" }
```

Mixins inject security rules, error examples, effects, and invariants automatically. `requires_auth` adds the "unauthenticated" error example. `logs_audit` adds an audit log effect. Variable substitution (`${action}`) makes mixins parameterizable.

### Placeholders

Specs use placeholders for value generation and assertions:

| Category | Placeholder | Generated code |
|----------|------------|----------------|
| **Values** | `@string(50)`, `@uuid`, `@now` | `"a".repeat(50)`, UUID, `Date.now()` |
| **Auth** | `@authenticated`, `@no_access` | Mock user objects |
| **Assertions** | `@defined`, `@length(3)`, `@gt(0)` | `toBeDefined()`, `toHaveLength(3)`, `toBeGreaterThan(0)` |
| **Content** | `@contains("x")`, `@matches("re")` | `toContain("x")`, `toMatch(/re/)` |
| **Composite** | `@all(@gt(0), @lt(100))` | Both assertions must pass |
| **Collections** | `@hasItem("x")`, `@hasProperties({...})` | `toContain("x")`, `toMatchObject({...})` |

### Architecture + Spec Integration

The analysis engine cross-validates architectural constraints against spec claims:

```bash
archcodex analyze
```

```
SEC-1: Spec claims authentication required but implementation
       is in utility layer (no auth enforcement)
       → spec.product.create declares security.authentication: required
       → but @arch tag is archcodex.util (utility layer forbids auth)

CON-2: Spec claims audit logging but architecture has no logging constraint
       → Move to a layer with audit requirements, or add constraint

DAT-3: Spec output 'discount' is nullable but no example tests the null case
       → Add an error example where discount is null
```

This is the key differentiator: structural analysis meets behavioral contracts. Issues that neither linting nor unit tests can catch — like a security claim that the architecture doesn't enforce — are detected automatically.

### Commands

```bash
# Initialize SpecCodex in your project
archcodex spec init

# Validate spec structure
archcodex spec check .arch/specs/products/create.spec.yaml

# Generate tests (unit, property, or integration)
archcodex spec generate spec.product.create --type unit

# Verify implementation matches spec (bidirectional)
archcodex spec verify spec.product.create

# Detect unwired specs and missing implementations
archcodex spec drift

# View fully resolved spec (with inheritance + mixins expanded)
archcodex spec resolve spec.product.create

# Generate spec from existing code (reverse workflow)
archcodex spec infer src/utils/helpers.ts#formatDate \
  --output .arch/specs/utils/helpers.spec.yaml

# Find spec by intent
archcodex spec discover "create a product"
```

### Reverse Workflow

When code exists before the spec:

```bash
# 1. Infer spec from implementation (detects patterns, types, errors)
archcodex spec infer src/domain/products/mutations.ts#create \
  --output .arch/specs/products/create.spec.yaml

# 2. Fill in TODOs — goal, intent, examples, invariants

# 3. Generate deterministic tests
archcodex spec generate spec.product.create --type unit
```

When implementation changes, update the spec preserving hand-written content:

```bash
archcodex spec infer src/domain/products/mutations.ts#create \
  --update spec.product.create
```

See [SpecCodex Guide](docs/speccodex.md) for comprehensive documentation.

## Documentation Generation

Generate Architecture Decision Records (ADRs) and API documentation from your architectures and specs.

```bash
# Generate ADR for an architecture
archcodex doc adr domain.service -o docs/adr/

# Generate all ADRs with index
archcodex doc adr --all -o docs/adr/

# Generate API docs from spec
archcodex spec doc spec.product.create --type all

# Watch mode for development
archcodex doc watch --type all -o docs/

# CI verification (exit 1 if stale)
archcodex doc verify --type all -o docs/
```

See [Documentation Generation](docs/cli/documentation.md) for details.

## Pre-Commit Integration

```bash
# Husky (after linking archcodex globally with npm link)
archcodex check --staged --format compact --max-errors 0
```

> **Note:** CI integration examples assume `archcodex` is available in PATH (via `npm link` or added to project).

See [CI Integration Guide](docs/ci-integration.md) for full setup.

## Documentation

| Document                                             | Description                                             |
| ---------------------------------------------------- | ------------------------------------------------------- |
| **CLI Reference**                                    |                                                         |
| [Validation](docs/cli/validation.md)                 | check, verify, health, why                              |
| [Discovery](docs/cli/discovery.md)                   | discover, decide, resolve, diff-arch, schema, graph     |
| [Scaffolding](docs/cli/scaffolding.md)               | scaffold, action, feature, tag, infer, bootstrap, learn |
| [Analysis](docs/cli/analysis.md)                     | read, neighborhood, types, garden                       |
| [Registry](docs/cli/registry.md)                     | reindex, sync-index, migrate-registry, audit, intents   |
| [Versioning](docs/cli/versioning.md)                 | diff, migrate, simulate, watch, init, fetch, feedback   |
| [SpecCodex](docs/cli/speccodex.md)

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ArchCodexOrg](https://github.com/ArchCodexOrg)
- **Source:** [ArchCodexOrg/archcodex](https://github.com/ArchCodexOrg/archcodex)
- **License:** MIT
- **Homepage:** https://medium.com/@stefanvanegmond

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-archcodexorg-archcodex
- Seller: https://agentstack.voostack.com/s/archcodexorg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.