Introduction to Archon Specs

Archon Specs is an AI-Native Architecture Compiler designed to turn high-level intent into hardened, production-ready codebases. Unlike generic LLM code generators, Archon Specs operates through a strict governance model that ensures consistency, type safety, and architectural integrity.

💡 Why Archon Specs?

Most AI agents hallucinate folder structures and forget manual edits. Archon Specs uses a DesignSpec to provide a deterministic source of truth and a Lineage Manifest to track every sync without overwriting your hard work.

🚀 Ready to build?

Skip the boilerplate and compile your first production-ready backend in minutes using the AI Architecture Compiler.

MCP Installation

To use Archon Specs in your AI assistant (e.g., Claude Desktop, Antigravity IDE), you must first install the client CLI globally using npm: 

npm install -g archon-mcp-client

Then, configure the MCP server in your favorite IDE. Important: AI agents often run without your system's PATH. You must use the absolute path to your Node executable and the installed CLI. 

{
  "mcpServers": {
    "archon-governance": {
      "command": "/opt/homebrew/bin/node", 
      "args": [
        "archon-mcp-client",
        "https://archonspecs.dev/mcp/sse?apiKey=sk_live_c5..."
      ]
    }
  }
}
⚠️ Troubleshooting: Connection Errors

If your IDE fails to connect, it is almost always because the AI cannot safely find Node.js to run the npm package. You must provide the exact absolute path based on your OS:

  • Mac: Run which node and npm root -g in your terminal to find your exact Homebrew or NVM paths.
  • Linux: Use which node and npm root -g. (e.g., /usr/local/bin/node).
  • Windows: Use where.exe node in Command Prompt and use Windows path formatting (e.g., C:\\Program Files\\nodejs\\node.exe).

Lineage & Governance

Every Archon Specs project contains a hidden governance file: .archon/lineage.json . This manifest is the "black box" of your system architecture, sealing the binding between your local code, the remote spec, and the generator versions.

Core Identifiers

  • projectId: A permanent ID for your architecture. It never changes, even as the code evolves.
  • revisionId: A unique hash representing the current approved version of the designspec.json .
  • lineageId: A unique identifier for the specific generation pass, used to prevent unauthorized drift. 
{
  "lineageVersion": "2.0",
  "projectId": "proj_a1b2c3d4",
  "revisionId": "rev_9z8y7x6w",
  "lineageId": "lin_m5n4o3p2",
  "generatedAt": "2026-03-18T12:00:00Z"
}

Manual Regions

Archon Specs respects your craft. We use Manual Regions to mark blocks of code that should never be overwritten during regeneration. This allows you to add custom logic, external integrations, or complex decorators while still benefiting from automated updates.

Usage Examples 

// @archon-manual-start:methods
async sendNotification(user: User) {
  // Archon Specs will NEVER touch this block
  await this.notifyService.send(user.id, "Welcome!");
}
// @archon-manual-end

Standard region IDs in Archon Specs templates include imports , methods , logic , and constructor .

Incremental Compiler

The Incremental Compiler is the engine that powers safe architectural evolution. When you update your spec, Archon Specs doesn't blindly rewrite the whole project. Instead, it:

  1. Computes a Spec Delta: Identifies exactly what changed (e.g., one field added to one entity).
  2. Maps Impacted Artifacts: Resolves the delta to a precise list of files to be regenerated.
  3. Preserves Local State: Merges manual regions and preserves file metadata (mtimes) for unchanged files.

Agent Swarm (Nexus)

Archon Specs isn't just an API—it is managed by a 5-agent autonomous team. To adopt the ultimate "Senior Architect" environment, we created a frictionless Zero-Setup Auto-Injection workflow.

✨ Zero-Friction Setup

Forget copy-pasting templates. Once you install the Archon MCP Server into your AI Assistant (like Cursor or Claude Desktop):

  1. Create a new, empty directory.
  2. Type to your AI: "Initialize my Archon workspace here."
  3. The AI automatically invokes the archon_initialize_workspace tool.

Instantly, your IDE is populated with AGENTS.md, IDE shims (like .cursorrules), and the mandatory .antigravity context environment. The AI wakes up natively as the Senior Engineer Agentic Architect!

The 5 Personas

Our injected workspace operates using specialized roles to prevent AI hallucinations and manage structural generation safely:

  • The Analyst: Defines the core requirements and system boundaries.
  • The Architect: Plans domains, evaluates impact across domains, and generates visual UML diagrams.
  • The Tech Lead: Authors the exact DesignSpec.json schema and forces architectural decision logging.
  • The Orchestrator: Auto-compiles the spec into production code and ensures documentation rot is prevented.
  • The Developer: Implements local code while protecting // @archon-manual blocks.

Tools Reference

Archon Specs provides a suite of specialized tools for your AI agent to manage the workspace and ensure architectural integrity.

archon_initialize_workspace

Zero-Friction Auto-Injection. Instantly scaffolds the complete Archon 5-Agent Swarm workspace (AGENTS.md, .cursorrules, .antigravity folder, etc.) into an empty directory. ALWAYS run this as the FIRST STEP in a new project to trigger the Senior Engineer Architect constraints.

archon_generate_from_uml

The fundamental starting point for any architect. Before writing code, software architects map out structural intent using diagrams. This tool takes a raw ASCII conceptual diagram (e.g., Domain entity relationships) and strictly translates it into a deterministic designspec.json. It is the primary, one-shot bootstrap pipeline to convert an idea into an enterprise-ready system schema.

uml_parse_ascii

A granular tool of the transaction pipeline. Agents use this to parse raw text structurally into an Intermediate Representation (IR).

uml_ir_to_designspec

Transforms an Intermediate Representation (IR) mapping cleanly into an Archon DesignSpec JSON.

archon_generate_diagram

Generates perfectly synchronized Markdown and Mermaid visualizations from a DesignSpec, representing the system's structural domains.

💡 IDE Visualization Tip

To correctly visualize the generated architectural diagrams directly inside your favorite IDE (like VSCode or Antigravity), we highly recommend installing the official Mermaid Chart extension:

📥 Install MermaidChart.vscode-mermaid-chart

validate_designspec

Validates a designspec.json against Archon Specs 's structural and semantic rules. It checks for missing entities, circular dependencies, and invalid type mappings before any code is generated.

generate_project

The core generation engine. It takes a validated DesignSpec and scaffolds a production-grade backend. It supports both full project generation and targeted artifact generation for specific files.

docker_smoke

Automated verification for your generated backend. It builds the Docker image, starts the container, and performs a health check on the /health endpoint to ensure the API is ready for use.

archon_diff_local

Preview architectural changes before they are applied. This tool computes the delta between the remote approved spec and your local state, listing exactly which artifacts will be created or updated.

archon_sync_local

The preferred way to update your project. It fetches the latest approved spec, runs the incremental compiler, and applies updates locally while ensuring your manual code is safe. Requires a clean Git workspace by default.

archon_verify_local

Audits your local project against the lineage manifest and current DesignSpec. Use this to ensure that no manual changes have drifted outside of the designated manual regions.

archon_read_local_lineage

Retrieves the projectId and revisionId from your workspace. Crucial for agents to identify the project context before suggesting mutations.

Learn more about our AI architecture compiler framework. AI architecture compiler