Architecture Intelligence for AI-Native Teams

Something shifted in the last six months. AI agents went from writing functions to writing entire services. Claude Code, Cursor, Codex — they're not assistants anymore. They're team members. They open PRs, review code, ship features.

But here's what keeps me up at night: these agents have no idea what the architecture looks like.

An agent can write a perfectly clean Go service in ten minutes. But it doesn't know that the team decided three months ago to route all inter-service communication through Kafka. It doesn't know that the payment service is off-limits for direct database access. It doesn't know that Python was moved to "hold" on the technology radar last quarter.

The result? Architecture drift at machine speed.

We built Archyl to solve this. And today, we're shipping the biggest update since launch: Architecture Intelligence — a complete ecosystem that makes Archyl the nervous system of AI-native development.

The Problem: Agents Code Fast, But Code Blind

When a human developer joins a team, they spend days reading docs, asking questions, building a mental model of the system. They learn the rules — written and unwritten. They understand the boundaries.

AI agents skip all of that. They receive a task, they write code, they open a PR. If nobody catches the architectural violation in review, it ships. Multiply that by ten agents working on ten services across three teams, and your carefully designed architecture erodes in weeks.

We've seen this happen. A team with a pristine C4 model in January had a drift score of 40% by March. Not because they stopped caring — because their agents didn't know the architecture existed.

The Solution: Architecture as Infrastructure

Architecture documentation shouldn't be a thing you maintain. It should be a thing that maintains itself — and that every agent consults before writing a single line of code.

That's what we built. Here's what's shipping today.

10 Agent Skills

The original archyl-developer skill gave agents access to 200+ MCP tools. But it was a toolbox without a workflow. Today, we're adding nine specialized skills that cover the full development lifecycle:

Before you code

archyl-preflight — Run this before implementing any feature. It checks your planned approach against the C4 model, conformance rules, technology radar, and API contracts. You get a clear PASS / WARN / FAIL verdict before writing a single line of code.

> I'm about to add a Redis cache to the user service. Is that okay?

Preflight Check: WARNING
- Redis is approved on the technology radar ✓
- User service exists in the C4 model ✓
- ⚠ No existing cache container documented — suggest creating one
- ⚠ The "No Direct DB Access from Handlers" rule applies — ensure cache is accessed through the service layer

After you ship

archyl-postship — Run this after shipping. It analyzes what you just built, updates the C4 model, creates ADRs for architectural decisions, and files Change Requests for architect review. Your documentation updates itself as a side effect of working.

During review

archyl-review — An architecture review bot. It checks your PR diff against the documented architecture and provides structured feedback: conformance violations, boundary crossings, unapproved technologies, missing API contracts. Think ESLint, but for architecture.

For visibility

archyl-changelog — Generates a readable timeline of all architecture changes: new services, modified relationships, ADR decisions, drift evolution. Perfect for architecture review meetings.

archyl-dora — Correlates DORA metrics with architecture changes. Did your microservice decomposition improve lead time? Did the drift spike precede the change failure rate increase? Now you have the data.

archyl-roi — Quantifies the financial impact of architecture decisions. "Our investment in conformance rules saved an estimated $23,000 last quarter by reducing rework." That's the kind of data that gets architecture budgets approved.

For prevention

archyl-predict — Forecasts architecture risks before they materialize. "At the current rate, your drift score will cross 50% by May. The PaymentService has 12 inbound dependencies — consider decomposition."

archyl-autofix — When drift is detected, proposes specific fixes. Either update the docs to match the code, or suggest code changes to re-align with the architecture. Creates Change Requests for human review.

For coordination

archyl-orchestrate — When multiple agents work on different services simultaneously, this skill negotiates API contracts, resolves dependency conflicts, and ensures cross-team changes don't break the architecture.

6 GitHub Actions

Architecture governance belongs in CI. We're shipping six GitHub Actions that run automatically on every PR and merge:

The recommended setup is one file:

name: Architecture
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-checks:
    if: github.event_name == 'pull_request'
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

  main-update:
    if: github.event_name == 'push'
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

Not on GitHub? We also ship templates for GitLab CI and Bitbucket Pipelines.

Conformance Rule Packs

Setting up architecture governance from scratch is tedious. So we built five pre-built rule packs that you can install in seconds:

Install via the agent skill: "Install the microservices conformance rules pack." Done.

SDKs

For teams building custom integrations, we're publishing official SDKs:

npm install @archyl/sdk    # Node.js 18+, zero dependencies
pip install archyl-sdk     # Python 3.10+

const archyl = new ArchylClient({ apiKey: 'arch_...', organizationId: 'uuid' });
const drift = await archyl.governance.computeDrift(projectId);
const predictions = await archyl.projects.getPredictions(projectId);

Three New AI-Powered APIs

Under the hood, we're shipping three new backend capabilities:

Predictive Analytics (GET /projects/:id/predict) — Real statistical analysis. Linear regression on drift scores, DORA metric trajectories, conformance decay rates, and complexity hotspot detection via fan-in/fan-out coupling analysis. Not vibes — math.

Architecture Diff Analysis (POST /projects/:id/architecture-diff) — Send a git diff, get back a structured C4 model delta. AI-powered analysis that detects new services, changed dependencies, and architectural decisions. Suggests ADRs when significant decisions are detected.

ROI Computation (GET /projects/:id/roi) — Quantifies architecture investment returns. Splits your DORA metrics before/after, computes productivity gains (hours saved × hourly cost), reliability gains (incidents avoided × incident cost), and ranks your ADRs by financial impact.

All three are available as MCP tools, so every agent skill can call them directly.

The Full Loop

Here's how it all fits together:

Agent receives task
       │
       ▼
  archyl-preflight ──── validates approach against architecture
       │
       ▼
  Agent writes code
       │
       ▼
  archyl-review ──────── reviews PR against C4 model
       │
       ▼
  CI: conformance-check ─ blocks violations
  CI: drift-score ──────── enforces alignment
       │
       ▼
  Merge to main
       │
       ▼
  CI: auto-cr ──────────── files Change Request
  CI: generate-context ─── updates archyl.txt
       │
       ▼
  archyl-postship ──────── updates C4 model + ADRs
       │
       ▼
  Next agent reads archyl.txt ← cycle repeats

Architecture isn't maintained. It maintains itself.

Getting Started

1. Install the skills:

/plugin marketplace add archyl-com/agent-skills
/plugin install archyl-preflight@archyl-com-agent-skills

2. Add the GitHub Actions: Copy the workflow above into .github/workflows/architecture.yml.

3. Generate your first archyl.txt: Run the generate-context action or ask your agent: "Generate the architecture context file for this project."

4. Start coding. Your agent now knows the architecture.

What's Next

This is the foundation. We're working on frontend dashboards for predictions and ROI, deeper integration with more coding agents, and a community marketplace for conformance rule packs.

Architecture documentation was always the thing teams meant to do but never got around to. When agents write the code, architecture becomes the only thing humans need to own. Archyl makes sure they don't have to do it alone.

Everything we shipped today is open source. We'd love your feedback.