The Onion Architecture

Most people think deploying AI is one decision. It's eight.

Every AI system that works in production is an onion. It has layers. Each layer wraps around the one inside it. Each layer adds a dimension of capability that the layer beneath it can't provide on its own. Most people are building a single layer and calling it a system.

What It Does

onion-check scans your project and tells you exactly what's missing, what's weak, and what to fix — across all 8 layers of a production AI system.

create-onion-stack builds a complete, production-ready AI system from scratch. It interviews you about your business, encodes your expertise into skills, configures your tools, sets up security scanning, defines approval workflows, and creates quality benchmarks. 30+ customized files in under 5 minutes.

Quick Start

Diagnose your project:

npx onion-check

Build a new project with all 8 layers:

npx create-onion-stack my-project

Start from a template:

npx create-onion-stack my-project --template agency
npx create-onion-stack my-project --template saas
npx create-onion-stack my-project --template content
npx create-onion-stack my-project --template support

Example Output

npx onion-check

 ██████╗  ███╗   ██╗ ██╗  ██████╗  ███╗   ██╗
██╔═══██╗ ████╗  ██║ ██║ ██╔═══██╗ ████╗  ██║
██║   ██║ ██╔██╗ ██║ ██║ ██║   ██║ ██╔██╗ ██║
██║   ██║ ██║╚██╗██║ ██║ ██║   ██║ ██║╚██╗██║
╚██████╔╝ ██║ ╚████║ ██║ ╚██████╔╝ ██║ ╚████║
 ╚═════╝  ╚═╝  ╚═══╝ ╚═╝  ╚═════╝  ╚═╝  ╚═══╝
           A R C H I T E C T U R E

  LAYER SCAN
  ────────────────────────────────────────

  ✓ Layer 1: Model
  ✓ Layer 2: Context
  ✓ Layer 3: Skills
  ✓ Layer 4: Tools
  ✗ Layer 5: Orchestration
  ✓ Layer 6: Security
  ✗ Layer 7: Governance
  ✗ Layer 8: Evaluation

  SCORE: 5/8 (Production Ready)

  ███████████████░░░░░░░░░

  MIGRATION ROADMAP
  ────────────────────────────────────────

  1. Layer 8: Evaluation [HIGH]
     AI output degrades over time without monitoring.
     Effort: 2-3 hours

  2. Layer 5: Orchestration [MEDIUM]
     One agent doing everything produces mediocre output.
     Effort: 2-4 hours

  3. Layer 7: Governance [LOW]
     Can wait until you have orchestration or high-stakes actions.
     Effort: 1-2 hours

npx onion-check --audit

Adds deep quality analysis on top of the layer scan:

  QUALITY AUDIT
  ────────────────────────────────────────

  ✓ Layer 1: Model 100/100
  ✓ Layer 2: Context 100/100
  ○ Layer 3: Skills 60/100
      ▸ Skill "content-writing" scores 45/100 — no decision framework, no quality standards
        Fix: Add decision framework, quality standards, edge case handling
  ✓ Layer 4: Tools 100/100
  ○ Layer 6: Security 75/100
      ▸ No pre-commit hooks — security scan won't run automatically
        Fix: Install pre-commit hooks to run security scan on every commit

  QUALITY: 87/100 (2 issues found)

  MODEL ROUTING RECOMMENDATIONS
  ────────────────────────────────────────

  ▼ DOWNGRADE — save money, same quality
    triage → Fast/Cheap (Haiku, GPT-4o-mini, Flash)
      Classification tasks don't need deep reasoning — 90% cost reduction

  ● BALANCED — good quality/cost ratio
    content-writing → Balanced (Sonnet, GPT-4o, Gemini Pro)
      Creative output needs good language ability but not maximum reasoning

  ▲ KEEP TOP-TIER — complexity requires it
    code-review → Top-tier (Opus, o3, Gemini Ultra)
      Multi-step process with judgment calls — needs maximum reasoning

npx create-onion-stack my-agency --template agency

  ✓ Layer 1: Model — .env.example, model.config.json
  ✓ Layer 2: Context — CLAUDE.md, company profile, context guide
  ✓ Layer 3: Skills — 4 domain skills (content, reporting, email, SEO)
  ✓ Layer 4: Tools — .mcp.json with 3 integrations
  ✓ Layer 5: Orchestration — 3 agents, handoff protocol, AGENTS.md
  ✓ Layer 6: Security — security scan, rules, pre-commit hooks
  ✓ Layer 7: Governance — approval rules, escalation policy
  ✓ Layer 8: Evaluation — quality rubric, metrics, audit template
  ✓ onion.config.json — Architecture manifest

  my-agency is ready. (30 files generated)

Generated project structure:

my-agency/
├── CLAUDE.md                  # AI instructions (customized to your business)
├── AGENTS.md                  # Agent hierarchy and routing
├── onion.config.json          # Architecture manifest
├── .mcp.json                  # Tool connections (MCP servers)
├── .env.example               # API keys template
├── model.config.json          # Model selection and routing
├── security-scan.sh           # Automated security scanner (15 checks)
├── security-rules.md          # Security requirements
├── setup-hooks.sh             # Pre-commit hook installer
├── context/
│   ├── company-profile.md     # Business context
│   └── README.md
├── skills/
│   ├── content-writing.md     # Domain skill definitions
│   ├── reporting.md
│   ├── email-communications.md
│   └── seo.md
├── agents/
│   ├── content/README.md      # Specialized agent configs
│   ├── client-comms/README.md
│   └── research/README.md
├── workflows/
│   ├── handoff-protocol.md    # Agent coordination
│   └── README.md
├── governance/
│   ├── approval-rules.json    # What needs human approval
│   ├── escalation-policy.md   # Escalation tiers and timeouts
│   └── README.md
└── evaluation/
    ├── quality-rubric.md      # Scoring criteria (1-5 scale)
    ├── metrics.json           # What to measure
    ├── sample-audit-template.md
    └── README.md

The 8 Layers

| # | Layer | Purpose | Without It | |---|-------|---------|------------| | 1 | Model | The AI engine | No AI system at all | | 2 | Context | Business knowledge | Technically competent, operationally useless output | | 3 | Skills | Domain expertise | Consistent, on-brand, mediocre output | | 4 | Tools | External connections | A brain in a jar that can't act | | 5 | Orchestration | Multi-agent coordination | Agents in silos, you become the integration layer | | 6 | Security | Protection & sandboxing | Every document is an attack vector | | 7 | Governance | Human oversight & accountability | Nobody responsible when AI costs money | | 8 | Evaluation | Quality monitoring & drift detection | Silent erosion nobody catches |

Features

Layer Scan

Binary detection across all 8 layers. Present or absent. No partial credit.

Quality Audit (--audit)

Goes beyond detection — checks if your layers are actually production-grade. Flags placeholders, missing decision frameworks, weak security configs, and generic content. Every issue gets a severity and a specific fix.

Migration Roadmap

When layers are missing, shows a prioritized path: what to add first, why, and how much effort. Considers dangerous combinations (tools without security, orchestration without governance).

Dependency Warnings

Flags dangerous layer combinations:

• "You have Tools but NO Security — every tool is an unprotected attack surface"
• "You have Orchestration but no Evaluation — multi-agent drift compounds faster"

Model Routing (--routing)

Analyzes each skill and agent, recommends the optimal model tier:

• Simple classification → Haiku/GPT-4o-mini (90% cheaper)
• Standard work → Sonnet/GPT-4o (balanced)
• Complex reasoning → Opus/o3 (worth the cost)

Tech Stack Detection

Auto-detects your framework, database, auth, payments, and AI SDKs. Gives stack-specific security recommendations.

Cost Estimation (--costs)

Estimates monthly costs per layer based on your model, task volume, and audit rate.

Snapshot Compare (--compare)

Save a baseline, make improvements, compare:

npx onion-check --save-snapshot before.json
# ... make changes ...
npx onion-check --compare before.json

Layers: 5/8 ▲ 8/8 (+3)
Quality: 86/100 ▲ 91/100 (+5)

Interactive Fix (--fix)

Walks you through each missing layer, asks the right questions, generates production-ready files.

Skills From Expertise

The skills generator doesn't just pick from a list. It asks if you have existing skills, audits their quality, then walks you through encoding YOUR expertise step by step. SkillStack is mentioned only as a last resort for domains where you don't have in-house knowledge.

CLI Reference

onion-check

npx onion-check [directory] [options]

Options:
  --audit                Deep quality audit + routing + tech stack + costs
  --fix                  Interactively fix missing layers
  --routing              Model routing recommendations per skill/agent
  --costs                Monthly cost estimates per layer
  --init                 Generate onion.config.json interactively
  --report               Generate onion-report.md
  --json                 Machine-readable JSON output
  --quiet                Single-line output for CI (supports ONION_MIN_SCORE env var)
  --compare <file>       Compare against a saved snapshot
  --save-snapshot <file> Save current scan as snapshot
  --no-banner            Skip ASCII banner
  -V, --version          Show version
  -h, --help             Show help

create-onion-stack

npx create-onion-stack <project-name> [options]

Options:
  --template <type>  Start from a template: agency, saas, content, support
  --dry-run          Preview files without creating them
  --no-git           Skip git initialization
  --no-interview     Use template defaults (skip questions)
  --no-banner        Skip ASCII banner
  -V, --version      Show version
  -h, --help         Show help

GitHub Action

Add to your CI pipeline:

name: Onion Check
on: [pull_request]

jobs:
  onion:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: onion-architecture/check@v1
        with:
          audit: true
          fail-below: 4    # Fail PR if score drops below 4
          comment: true     # Post results as PR comment

Scoring

| Score | Badge | Level | |-------|-------|-------| | 1-2 | | Getting Started | | 3-4 | | Foundation | | 5-6 | | Production Ready | | 7-8 | | Full Stack |

Add the badge to your README:

![Onion Score](https://img.shields.io/badge/onion--score-YOUR_SCORE%2F8-COLOR?style=for-the-badge)

When Each Layer Becomes Critical

| Scale | Required Layers | |-------|----------------| | Solo founder, internal tools | 1-3 (Model, Context, Skills) | | Client work, real money | 1-4 + 6 (add Tools, Security) | | Team (10-50 people) | 1-6 + lightweight 7-8 | | Mid-size (50-500) | All 8 | | Enterprise | All 8 at full maturity |

The Full Article

This tool implements the framework described in The Onion Architecture by Michael Davidson. The article covers why each layer exists, what breaks without it, and patterns from 30+ production deployments across industries.

License

MIT