Your Diagram Just Learned to Audit Your Code: Architecture Drift Detection with spec.json + an Agent Skill 🛡️🔍

Every architecture diagram tells a beautiful story. Then the code ships, deadlines bite, and someone takes a shortcut: the frontend reads the cache directly "just this once," a service opens its own database connection "for the fast path." Six months later the diagram is fiction and nobody can say when it stopped being true. 📉

That gap has a name — architecture drift — and until now, catching it meant either expensive static-analysis tooling wired up per language, or a very patient architect doing code review archaeology.

We think there's a better way. Your AI coding agent is already sitting in your repo, and it's very good at reading code. It just never knew what the architecture was supposed to be. So now, every FloDraw handoff bundle teaches it.

The Bundle Grew a Brain: spec.json + a Conformance Skill

When you generate an AI Handoff Bundle — the one-click package of CLAUDE.md, Cursor rules, architecture docs, and ADRs compiled from your diagram — it now includes two new files:

• .agents/spec.json — a machine-readable manifest of your architecture: every component, its suggested code location, the allowed connections, boundary groups, and the ADR decisions as checkable claims. The policy is deny-by-default: if two components aren't connected on your canvas, they're forbidden from talking in code.
• .agents/skills/flodraw/SKILL.md — a validation skill that teaches any coding agent how to audit the repo against that manifest: map components to the real code layout, hunt for forbidden imports and calls, verify each ADR decision, and report findings with evidence.

✏️ Try it yourself: open this exact architecture in FloDraw — edit it, then generate your own bundle with the conformance pack included. Free, no sign-up needed.

The best part: these files are deterministic compiler output. No AI credits, no extra clicks. Draw the boxes, and the enforcement artifacts fall out of the same compilation that builds your rules files and ADRs.

One Click from Canvas to Repo 🚀

A spec that lives in a zip on your laptop enforces nothing. So the bundle now travels: connect GitHub (or GitHub Enterprise) to FloDraw, and Push to GitHub commits the whole bundle — atomically, as a single commit or a ready-to-review pull request on a flodraw/* branch.

Your architecture now lives where your code lives. When the diagram changes, regenerate and push again — the PR diff is your architecture change review.

Then Ask Your Agent: "Check Architecture Conformance"

Here's where it gets fun. Open the repo with Claude Code (or Cursor, or any agent that reads your rules files — they all get pointed at the skill), and ask it to check conformance. The skill walks the agent through a disciplined audit:

1. Parse spec.json and note the deny-by-default policy.
2. Map components to reality. The suggested paths are hints, not gospel — the agent inspects your actual repo layout and builds a mapping table first, reporting anything it can't find instead of guessing.
3. Hunt forbidden coupling. For every component pair not in the allowed list: imports, HTTP calls, queue names, env vars — any evidence of a relationship your diagram never approved.
4. Verify ADR decisions — including hand-written ADRs in docs/adr/ that were never in the diagram — with file:line evidence for every verdict.
5. Report, don't touch. The skill is strictly read-only: findings with severity, evidence, the violated rule, and the smallest remediation. Your agent audits; you decide.

This is what it looks like when we ran it against a repo with two deliberate shortcuts in it:

Both violations are the classic kind that slip through human review: a "temporary" cache read in the frontend, a "fast path" database query that bypasses the owning service. The agent caught both in seconds, cited the exact lines, matched the ioredis import against the spec's package hints, and — because the skill forbids it — fixed nothing without asking.

Why a Skill Beats a Static Analyzer Here

We deliberately did not build a per-language linter. A dependency-graph analyzer knows JavaScript imports; it doesn't know that an env var named DATABASE_URL in the wrong service is a boundary breach, or that a queue name in a config file couples two services. An agent reading your code does — in any language, in config, in IaC, in docker-compose. The spec gives it ground truth; the skill gives it method; your agent supplies the comprehension. Language-agnostic drift detection, zero new infrastructure.

The Full Loop, End to End 🔄

This closes the loop we've been building all along:

1. Design the system visually — drag shapes, prompt the AI, or magic-wand a whiteboard photo.
2. Review it with the AI Architect until the design holds up.
3. Compile the handoff bundle — agent rules, docs, ADRs, and now the conformance pack.
4. Push it to GitHub in one click — commit or pull request, github.com or Enterprise.
5. Build with your AI coding agent, guardrails loaded.
6. Audit any time: "check architecture conformance" — and drift gets caught while it's still one file, not one quarter, old.

Design is no longer a suggestion your codebase slowly ignores. The diagram is the contract — and now the contract has an auditor. 🤝

Try It in Five Minutes

Open FloDraw, sketch your system (or load the payments platform example), hit AI Spec Writer → AI Handoff → Generate Handoff Bundle, and push it to a repo. Then open that repo with your favorite coding agent and ask the question your architecture has been waiting for someone to ask:

"Does the code still match the design?" 🕵️