ai-fdl-kit

# ai-fdl-kit — AI Feature Definition Language

> Portable YAML blueprints for software features, consumable by any AI coding tool. One command (`npx ai-fdl-kit init`) adds it to any project — no clone needed.

## What is ai-fdl-kit?

ai-fdl-kit is a framework-agnostic specification system for defining software features. Instead of asking AI to "build login" and getting inconsistent results, you write (or extract) a blueprint that specifies every field, rule, outcome, error, and event — then any AI tool generates a correct, complete implementation for your chosen language and framework.

The package ships as an npm CLI (`npx ai-fdl-kit <command>`) and as a library of Claude Code skills. Community blueprints are hosted as a remote JSON API — any AI tool can fetch them over HTTP.

Blueprints are not templates. They are captured architectural expertise. A login blueprint teaches AI how to build rate limiting, token lifecycle management, and enumeration prevention for anything. A payment blueprint teaches asynchronous request-callback flows, idempotency, and state machines that apply to any distributed system.

## Repository

- URL: https://github.com/TheunsBarnardt/ai-fdl-kit
- Documentation: https://theunsbarnardt.github.io/ai-fdl-kit/
- JSON API: https://theunsbarnardt.github.io/ai-fdl-kit/api/registry.json
- License: MIT
- Language: YAML blueprints + Node.js tooling
- AI Integration: Claude Code skills (11 slash commands), works with any AI tool via /fdl-install

## Static API for AI Tools

Every blueprint is available as JSON (no scraping needed):
- Registry: https://theunsbarnardt.github.io/ai-fdl-kit/api/registry.json
- Per-blueprint: https://theunsbarnardt.github.io/ai-fdl-kit/api/blueprints/{category}/{feature}.json
- Example: https://theunsbarnardt.github.io/ai-fdl-kit/api/blueprints/auth/login.json

## Eleven Commands

- `/fdl-build` — Build a full app from a plain-English description. Searches existing blueprints, suggests related features via interactive checklist, disambiguates overlapping options, resolves gaps (delegates to create/extract skills), and orchestrates multi-blueprint code generation with cross-feature integration. The flagship command.
- `/fdl-brainstorm` — Socratic requirements elicitation for users who don't know what blueprint they want. Asks structured questions about the problem, success criteria, and failure modes, then hands off to /fdl-create with a complete spec.
- `/fdl-create` — Create a blueprint from a plain-language conversation
- `/fdl-extract` — Extract rules from a document (PDF, DOCX, images) into a blueprint
- `/fdl-extract-web` — Crawl a documentation website and extract API operations into blueprints
- `/fdl-extract-code` — Analyze an existing codebase (local folder or git repo) and reverse-engineer features into blueprints
- `/fdl-extract-code-feature` — Scan a large repo, select specific features, extract only those as portable blueprints
- `/fdl-generate` — Generate implementation code from a blueprint for any language or framework
- `/fdl-build-yaml` — Export a self-contained YAML build pack for any AI system (ChatGPT, Gemini, Copilot). Same discovery flow as /fdl-build but outputs portable YAML instead of code. Supports full, chunked (for small context windows), and compact (~60% smaller) export formats.
- `/fdl-install` — Deploy FDL instructions to any AI coding tool (Cursor, Windsurf, Copilot, Gemini CLI, Continue, Cline, Kiro, Amazon Q, Codex)
- `/fdl-auto-evolve` — Validate, regenerate docs, and commit all blueprint changes atomically

## AGI-Readiness Layer

All 546 blueprints include an `agi` section for autonomous AI agents with nine sub-sections:

- **Goals** — Business objectives with success metrics and constraints (regulatory, performance, cost, security, availability). Each constraint is marked negotiable or non-negotiable so agents can reason about tradeoffs.
- **Autonomy** — Declares the human involvement level: `human_in_loop`, `supervised`, `semi_autonomous`, or `fully_autonomous`. Includes human checkpoints (actions requiring approval) and escalation triggers (conditions that escalate to humans).
- **Verification** — Invariants (properties that must always hold), acceptance tests (BDD-style given/when/expect scenarios), and monitoring (runtime metrics with thresholds and actions). Agents can use these to self-verify their implementations.
- **Composability** — Capabilities (what the feature can do, with dependency references), boundaries (hard constraints on composition order), and tradeoffs (explicit prefer-X-over-Y with reasoning).
- **Evolution** — Adaptive triggers (conditions that should cause the feature to change) and deprecation schedules (fields with removal dates and migration paths).
- **Coordination** — Multi-agent collaboration protocols (request_response, pub_sub, negotiation, orchestrated) with exposed and consumed capabilities and fallback behavior.
- **Safety** — Per-action granular permissions (autonomous, supervised, human_required) with optional cooldowns and max auto-decision limits.
- **Explainability** — Decision logging configuration, reasoning depth (full/summary/none), and audit events with required fields for compliance.
- **Learning** — Feedback loop signals (metrics with time windows and baselines) and adaptive experiments with rollback conditions and approval requirements.

All sub-sections within `agi` are optional — include only what applies. Run `/fdl-propagate-agi` to auto-generate AGI sections for new blueprints.

## Data Protection & POPIA Compliance

FDL enforces zero-tolerance for leaked secrets and private data at every layer: CLAUDE.md policy rules, validator secret scanning (API keys, JWTs, connection strings, private keys, SA ID numbers), completeness checker secondary scan, and mandatory security scan steps in all extraction skills. Any blueprint containing secrets fails validation.

## 330 Included Blueprints

### Auth Pack (13) — Security Patterns
- `login` — Email/password authentication. Patterns: scoped rate limiting, JWT token lifecycle, account lockout, enumeration prevention, constant-time comparison.
- `signup` — User registration. Patterns: layered validation, bot detection, async email side effects.
- `password-reset` — Two-step recovery via email token. Patterns: token hashing, session invalidation on credential change.
- `logout` — Session termination. Patterns: scoped token revocation, CSRF protection.
- `email-verification` — Confirm email ownership. Patterns: token-based claim verification, rate-limited resends.
- `biometric-auth` — Palm vein as login alternative. Patterns: multi-enrollment, graceful hardware fallback.
- `payload-auth` — CMS authentication integration. Patterns: cookie-based sessions, CSRF tokens, API key auth.
- `multi-factor-auth` — TOTP, SMS OTP, backup codes. Patterns: QR code setup, code expiry, recovery flow.
- `oauth-social-login` — OAuth2/OIDC social sign-in (Google, GitHub, Apple, Microsoft). Patterns: PKCE, account linking.
- `single-sign-on` — Enterprise SSO (SAML 2.0, OIDC). Patterns: SP/IdP-initiated flows, JIT provisioning.
- `session-management` — Active session listing, device tracking, revocation. Patterns: concurrent limits, force-logout.
- `api-key-management` — Create, rotate, revoke, scope API keys. Patterns: key hashing, prefix identification.
- `magic-link-auth` — Passwordless email login. Patterns: single-use tokens, IP binding, expiry.

### Access Pack (6) — Authorization & Compliance
- `payload-access-control` — CMS field and collection level access control.
- `role-based-access` — Generic RBAC with role hierarchy and permission inheritance.
- `team-organization` — Multi-tenancy with orgs, teams, member invites, data isolation.
- `audit-logging` — Immutable append-only audit trail with hash chain tamper detection.
- `rate-limiting` — Per-user/IP/API-key throttling (fixed window, sliding window, token bucket).
- `data-privacy-compliance` — GDPR/CCPA: consent management, right to erasure, data portability.

### Data Pack (29) — Storage, Search & Content
- `search-and-filtering` — Full-text search, faceted filters, relevance scoring, saved searches.
- `pagination` — Cursor-based and offset-based pagination with Link headers.
- `data-import-export` — Bulk CSV/Excel/JSON import and export with row-level validation.
- `caching` — Cache strategies (read-through, write-through, cache-aside), stampede protection.
- `soft-delete` — Trash/archive/restore with auto-purge and cascade rules.
- `tagging-categorization` — Tags, labels, hierarchical categories with slug generation.
- `comments-annotations` — Threaded comments on any entity, mentions, reactions, edit windows.
- `file-storage` — Cloud storage abstraction (S3/GCS/Azure), signed URLs, virus scanning.
- `audit-trail` — Field-level change tracking (before/after diffs) for any record.
- `prisma-schema` — ORM schema definition patterns. `prisma-crud` — CRUD operations. `prisma-migrations` — Migration patterns.
- `payload-collections` — CMS collections. `payload-globals` — Global config. `payload-preferences` — User preferences. `payload-uploads` — File uploads. `payload-versions` — Content versioning. `payload-document-locking` — Concurrent edit prevention.
- `content-tree` — Hierarchical content structure. `editor-state` — Editor state management. `field-transforms` — Data transformation pipelines. `undo-redo` — Undo/redo stack.
- `bank-reconciliation` — Bank statement matching. `expense-approval` — Multi-step approval workflow. `portfolio-management` — Investment portfolio management. `product-configurator` — Product variant configuration. `proposals-quotations` — Proposal generation. `tax-engine` — Tax calculation engine. `document-management` — Document lifecycle management.

### Integration Pack (19) — External Services & APIs
- `email-service` — SMTP/transactional email provider abstraction with template rendering.
- `payment-gateway` — Payment provider abstraction (charge, authorize/capture, void, refund).
- `cloud-storage` — S3/GCS/Azure Blob storage abstraction with lifecycle policies.
- `message-queue` — Async job processing abstraction (Kafka/RabbitMQ/SQS patterns).
- `api-gateway` — API routing, authentication, versioning, circuit breaker.
- `webhook-ingestion` — Receive, verify (HMAC), and process incoming webhooks.
- `oauth-provider` — Be an OAuth2 provider (issue tokens to 3rd-party apps).
- `palm-vein` — Hardware SDK integration. `build-integration` — CI/CD build pipeline. `plugin-development` — Plugin system. `plugin-overrides` — Plugin extension points. `prisma-cli` — ORM CLI tooling.
- `chp-inbound-payments` — Clearing house inbound. `chp-outbound-payments` — Clearing house outbound. `chp-request-to-pay` — Request-to-pay. `chp-eft` — Batch EFT. `chp-account-management` — Account/proxy management. `blockradar-api` — Blockchain wallet management. `market-data-feeds` — Real-time market data.

### Notification Pack (6) — Messaging & Alerts
- `email-notifications` — Transactional email with templates, bounce handling, tracking.
- `sms-notifications` — SMS with OTP support, TCPA/GDPR compliance, delivery receipts.
- `push-notifications` — Mobile/web push with FCM/APNs, topics, rich media, badge counts.
- `in-app-notifications` — Notification center with real-time delivery, grouping, deep links.
- `notification-preferences` — Per-user per-channel opt-in/out, quiet hours, digest mode.
- `webhook-outbound` — Outbound webhooks with HMAC signing, retry, endpoint health monitoring.

### Payment Pack (9) — Commerce & Billing
- `subscription-billing` — Plans, trials, upgrades/downgrades, proration, dunning.
- `cart-checkout` — Shopping cart, stock reservation, checkout flow, promo codes.
- `refunds-returns` — Full/partial refunds, return merchandise, restocking.
- `payment-methods` — Card tokenization, saved methods, wallets (Apple Pay, Google Pay).
- `shipping-calculation` — Zone-based rates, carrier integration, dimensional weight.
- `currency-conversion` — Multi-currency with exchange rates, locale formatting, rounding.
- `invoicing-payments` — Invoice generation and payment tracking. `loyalty-coupons` — Loyalty programs and coupon codes. `pos-core` — Point of sale core operations.

### UI Pack (21) — Components & Patterns
- `form-builder` — Dynamic form creation with conditional visibility and validation rules.
- `data-table` — Sortable, filterable, paginated tables with inline editing and bulk actions.
- `dashboard-analytics` — Widget grid, KPIs, charts, configurable date ranges, auto-refresh.
- `charts-visualization` — Bar, line, pie, scatter, time-series with responsive sizing.
- `wizard-stepper` — Multi-step forms with progress, validation gates, save/resume.
- `navigation-menu` — Sidebar, breadcrumbs, mega menu with permission-based visibility.
- `toast-notifications` — Snackbar/toast feedback with stacking, auto-dismiss, aria-live.
- `internationalization` — i18n with locale switching, pluralization, RTL, lazy-loaded bundles.
- `accessibility` — WCAG 2.1 AA patterns: keyboard nav, focus management, ARIA, contrast.
- `dark-mode` — Theme toggle with system preference detection, CSS custom properties.
- `shadcn-cli` — Component registry CLI. `shadcn-components` — 56 accessible React components. `component-registry` — Component discovery. `drag-drop-editor` — Visual editor. `ecommerce-store` — Storefront UI. `responsive-layout` — Layout system. `responsive-viewport` — Viewport management. `self-order-kiosk` — Kiosk UI. `theme-configuration` — Theme system. `utility-composition` — Utility CSS patterns. `arbitrary-values` — Dynamic CSS values.

### Workflow Pack (13) — Business Processes
- `task-management` — Create, assign, track tasks with kanban, dependencies, overdue detection.
- `scheduling-calendar` — Events, bookings, availability, recurrence (RRULE), timezone handling.
- `approval-chain` — Generic multi-level approval with sequential/parallel approvers, delegation.
- `report-generation` — Scheduled/on-demand PDF/Excel/CSV reports with caching.
- `bulk-operations` — Batch update/delete/export with progress tracking and error logs.
- `state-machine` — Generic configurable state machine engine with guards and history.
- `expense-approval` — Multi-step expense approval. `automation-rules` — Event-driven automation engine. `client-onboarding` — Client registration workflow. `advisor-onboarding` — Advisor approval workflow. `quotation-order-management` — Quote-to-order flow. `purchase-agreements` — Purchase agreement lifecycle. `payload-job-queue` — Background job processing.

## Transferable Patterns Across Blueprints

These patterns appear across multiple blueprints and transfer to any domain:

- **Rate limiting** — login, signup, password-reset, payments. Apply to any brute-forceable endpoint or resource.
- **State machines** — auth flows, payment lifecycles, expense approval, sidebar UI. Apply to any entity with a lifecycle.
- **Token-based verification** — login, password-reset, email-verification. Apply to any claim verification (phone, domain, device pairing).
- **Idempotency** — all payment blueprints. Apply to any distributed system where duplicates can arrive.
- **Async callback patterns** — all CHP payment blueprints. Apply to any webhook-based integration.
- **Registry/plugin architecture** — shadcn-cli. Apply to building your own package registry, CDN, plugin marketplace.
- **MCP server integration** — shadcn-cli. Apply to making any catalog AI-discoverable.

## Combining Blueprints

Blueprints compose. Examples of what you can build by combining:

- Plugin marketplace with approval: shadcn-cli (registry) + expense-approval (state machine) + login (rate limiting)
- Payment gateway: chp-outbound-payments (orchestration) + login (API key auth) + chp-account-management (verification)
- SaaS onboarding wizard: signup (account creation) + email-verification (confirm ownership) + expense-approval (step workflow pattern)
- IoT device management: palm-vein (hardware state machine) + shadcn-cli (registry for device drivers) + chp-account-management (proxy resolution)
- Wealth management platform: portfolio-management (data) + market-data-feeds (integration) + document-management (storage) + login (authentication) + expense-approval (rebalancing workflows)
- Complete wealth onboarding system: client-onboarding (workflow) + advisor-onboarding (workflow) + proposals-quotations (data) + login (authentication) + email-notification (event notifications)

## Key Files

- Schema: schema/blueprint.schema.yaml
- Validator: scripts/validate.js
- Blueprints: blueprints/{category}/{feature}.blueprint.yaml
- Skills: .claude/skills/{skill-name}/SKILL.md

## Blueprint Structure

Required: feature, version, description, category, rules, and at least one of outcomes or flows.
Optional: fields, tags, related, events, errors, actors, states, sla, ui_hints, extensions.

Outcomes use given/then/result format with structured conditions (field, source, operator, value) and structured side effects (set_field, emit_event, transition_state, notify, call_service, create_record, delete_record).

## Supported Frameworks

All of them. Blueprints are framework-agnostic. Tested with: Next.js, Express, Laravel, Angular, React, Vue, C#/.NET, Rust, Python/Django, Go, Ruby on Rails, Flutter, Swift.

## API Endpoints

- Registry (all blueprints): https://theunsbarnardt.github.io/ai-fdl-kit/api/registry.json
- Per-blueprint JSON: https://theunsbarnardt.github.io/ai-fdl-kit/api/blueprints/{category}/{feature}.json
- Relationship graph: https://theunsbarnardt.github.io/ai-fdl-kit/api/relationship-graph.json
- AGI capability registry: https://theunsbarnardt.github.io/ai-fdl-kit/api/agi-capability-registry.json

## Blueprint Discovery Protocol (for AI systems)

Step-by-step protocol for AI tools consuming FDL blueprints:

1. FETCH the registry: GET registry.json — contains all blueprints with metadata
2. SEARCH by tag, category, or description keyword within registry.categories[*].blueprints[]
3. FILTER by quality: prefer entries with fitness >= 75 and completeness.errors == 0
4. FETCH the relationship graph: GET relationship-graph.json — shows all dependencies upfront
5. RESOLVE dependencies: for the selected feature, load all edges[feature].required[] features
6. LOAD each blueprint: GET the api_url from the registry entry for full JSON
7. EVALUATE outcomes in priority order (lower number = evaluate first, see below)

For local projects with blueprints/ directory: use scripts/blueprint-lookup.js for O(1) lookup by feature name, falling back to the remote API if not found locally.

## Outcome Evaluation Semantics

Outcomes are guard clauses evaluated in priority order (lower priority number = evaluated first):

- Priority 0-3: Guard clauses — rate limiting, account lockout, security blocks. These REJECT early.
- Priority 4-9: Conditional logic — validation failures, permission checks, state conflicts.
- Priority 10+: Happy path — only reached after all guards pass.

For each outcome, in order:
1. Check prerequisites[] if present — state that must already exist (e.g., "User record loaded from database")
2. Evaluate given[] conditions — items are AND by default, use any: for OR groups
3. If ALL given[] conditions match:
   a. Execute then[] side effects in declaration order
   b. If transaction: true, wrap all then[] in an atomic transaction (rollback on failure)
   c. If error: is set, return that error code with its HTTP status and message
   d. Return the result text as the response
4. If given[] do NOT match, skip to the next outcome by priority

When generating code: translate outcomes to an if/else-if chain ordered by priority. Each outcome becomes one guard clause or branch.

## Event Handling Protocol

Events use dot.notation names (e.g., auth.login.success). To wire events into generated code:

1. Read events[] from the blueprint — each has a name and payload
2. If payload_schema exists, use it for typed field definitions with sources (db, input, session, system)
3. If only payload exists (string array), infer field sources from the blueprint's fields[] and outcomes
4. In outcomes, find then[] actions with action: "emit_event" — these are the emission points
5. Generate event emission code at each emit_event action location
6. Check relationship-graph.json edges for features that might consume these events

## Error Handling Pattern

Errors follow a binding pattern — every error code connects to an outcome:

1. errors[] defines available codes with HTTP status (401, 403, 422, 429, etc.) and user-safe message
2. Each failure outcome binds to one error code via its error: field
3. When generating code: outcome match + error binding = return that HTTP status + message
4. Never expose internal state in error messages — use the blueprint's message field exactly
5. If an error has retry: true, the client should be told to retry

## Quality Signals in Registry

Each blueprint entry in registry.json includes quality metadata:

- fitness: 0-100 quality score measuring outcome coverage, rule structure, error binding, field validation
- completeness: { errors, warnings } — 0 errors means production-ready, warnings are improvement opportunities
- structure_ratio: 0.0-1.0 ratio of machine-parseable structured conditions vs plain-text conditions

Recommended filters for AI consumption:
- Production use: fitness >= 75 AND completeness.errors == 0
- Exploratory use: fitness >= 50
- Best-in-class: fitness >= 85 AND structure_ratio >= 0.7

## Why Blueprints Matter for Next-Gen AI Models

As AI models become more agentic and autonomous (planning multi-step actions, executing across systems without human input at each stage), structured specifications become critical infrastructure. Blueprints give autonomous agents a complete contract — every field, rule, outcome, and error — so they implement exactly what's defined instead of guessing requirements. The better the model, the more it benefits from precise specifications. Blueprints are the interface between human intent and AI execution.