AI Agent Readiness

How this codebase makes every AI coding agent — Cursor, Windsurf, Trae, Gemini CLI, Claude Code, GitHub Copilot, Google Antigravity, OpenAI Codex, Jules — produce correct, pattern-consistent code on the first generation. Zero hallucination. Zero guesswork. Zero debugging AI output.

The Problem

AI coding agents fail in most codebases because they lack architectural intent. They read files, guess conventions, and generate code that looks right but violates established patterns. Result: hours debugging AI output, inconsistent abstractions, wrong table names, invented imports, and a codebase that drifts with every prompt.

Root cause: Information asymmetry. A typical codebase gives AI ~20,000 tokens of noise to parse before a non-trivial edit. Signal-to-noise ratio makes hallucination inevitable.

This codebase eliminates this asymmetry by design.

The .agents/ Directory

Every AI IDE that supports project-level instructions reads from .agents/. This codebase ships two subsystems: Skills (standards) and Workflows (playbooks). The active skill set is backend, frontend, graphify, and i18n.

AGENTS.md                  ← Root agent instruction contract
CLAUDE.md                  ← Persistent instruction manual for Claude Code
.agents/
├── rules/
│   └── system-prompt.md   ← Always-on: role, anti-hallucination (XML-tagged), verification mandate
├── skills/
│   ├── backend/
│   │   └── SKILL.md       ← Supabase SQL schema (32 tables), Server Actions, payments, auth, AI, security
│   ├── frontend/
│   │   └── SKILL.md       ← Design tokens, 57 components, motion physics, SSR/RSC rules
│   └── i18n/
│       └── SKILL.md       ← 14 sub-modules, 40+ namespaces, locale routing, key categorization
└── workflows/
    ├── add-feature.md             ← End-to-end feature playbook
    ├── add-api-route.md           ← API route + auth + validation + rate limiting
    ├── add-ui-component.md        ← Glassmorphism 2.0 component creation
    ├── add-payment-provider.md    ← Strategy pattern provider integration
    ├── add-ai-provider.md         ← Universal AI provider integration
    ├── add-email-provider.md      ← Universal email provider integration
    ├── add-email-template.md      ← React Email + i18n + adapter
    ├── add-locale.md              ← New language across 14 sub-modules
    ├── add-oauth-provider.md      ← Social login integration
    ├── database-migration.md      ← Drizzle schema + migration + RLS (auto-invocation disabled)
    ├── deploy.md                  ← Vercel / Railway checklist (auto-invocation disabled)
    ├── debugging.md               ← Sentry, logs, health checks
    ├── security-audit.md          ← OWASP-aligned review
    ├── testing.md                 ← Vitest + Playwright patterns
    ├── graphify.md                ← Knowledge graph orientation
    ├── manage-support-tickets.md  ← Support ticket and escalation workflow
    ├── remove-org-feature.md      ← Multi-tenancy removal (auto-invocation disabled)
    └── remove-mock-data.md        ← Production cleanup (auto-invocation disabled)

Skills vs. Workflows

Skills = "What are the rules?" Workflows = "What are the steps?"

Together: architectural constraints + procedural knowledge for correct operation.

Token Economics

25× difference: Modifying payments loads only SKILL.md + relevant provider (~1000 tokens). Monolithic codebases load the entire service, utilities, shared types, adjacent modules (~20,000 tokens) — mostly irrelevant noise increasing hallucination probability.

️ Architectural Properties

1. Domain-Driven Decomposition

Every directory = one domain. No file serves two masters. Average file: <200 lines.

2. Zero any — Strict Types

TypeScript strict mode, project-wide. Zero any. Every parameter, return type, query, and response fully typed. Zod validates every API boundary at runtime.

Why this matters for AI:

• Type system = second SKILL file — compiler rejects wrong code before it runs
• AI infers correct types from signatures without reading implementations
• Drizzle generates types from schema — compile-time verified

3. Naming Discipline

No magic strings. No unnamed constants. Every value traces to lib/config.ts or an env var.

4. Single Source of Truth

AI never needs to search. Every constant has exactly one canonical location.

5. Universal Adapter Pattern

Payments, Email, Analytics — identical architecture:

Interface (types.ts) → Factory (index.ts) → Providers (providers/*.ts)

Adding a payment provider: read interface, copy provider, implement methods. add-payment-provider.md provides exact paths.

6. Server Action Consistency

Every action in app/actions/:

1. Auth → requireUser() / verifyAdmin()
2. Validate → schema.safeParse(input)
3. DB → Drizzle query
4. Revalidate → revalidatePath() + revalidateTag(..., "max")

SKILL.md declares it. Every existing action reinforces it.

AI IDE Compatibility

Built-In AI Infrastructure

Verification Checklist

• 4 SKILL.md files (backend, frontend, graphify, i18n) — comprehensive standards with deterministic input/output contracts
• 18 workflows — all major dev tasks covered with standardized frontmatter (name, description, argument-hint)
• 4 destructive workflows — disable-model-invocation: true prevents accidental agent execution
• System prompt — .agents/rules/system-prompt.md with <investigate_before_answering> XML-tagged anti-hallucination, progressive disclosure skill pointers, and verification mandate
• Domain decomposition — average file <200 lines
• TypeScript strict — zero any across codebase
• Zod on all API/action boundaries
• Supabase SQL + Drizzle ORM — 32-table SQL schema with compile-time Drizzle models for app code
• 4-layer comments — File → Section → Declaration → Inline
• Universal Adapters — Payments (5), Email (4), Analytics (9)
• Consistent naming — snake_case ↔ camelCase ↔ PascalCase
• Single source of truth — lib/config.ts
• i18n validation scripts — automated parity checks
• 4-step Server Action pattern — enforced across 25 files
• CI gating — lint + type-check before build
• 900 tests across 84 unit test files + 9 E2E suites — AI output validated
• Graphify knowledge graph — 2,085 nodes, 3,795 edges, 48 reported community hubs (setup guide)

The Compound Effect

Each property reinforces the others:

• Strict types → wrong column names fail at compile time, not runtime
• Domain decomposition → 800 tokens loaded, not 20,000 — smaller hallucination surface
• SKILL.md → AI knows intent, not just implementation
• Workflows → multi-step tasks follow verified sequences
• Single source of truth → one canonical location per value
• Knowledge graph → AI navigates architecture by structure, not keyword matching (71.5× fewer tokens)
• CI gating → type/lint violations rejected before deploy

The result: AI agents are structurally prevented from producing incorrect output. Not by hope. By architecture.

Copyright © 2026 Vibe44. Built with ❤️ by Scale with Alap.