The Binding Glue

FAI Protocol

The industry's first context-wiring standard for AI primitives. 7 JSON schemas that define how agents, skills, hooks, plugins, and knowledge connect into production-ready systems.

What is the FAI Protocol?

The AI ecosystem has standards for individual concerns — MCP for tool calling, A2A for agent delegation, AG-UI for rendering. But nothing wires them together. The FAI Protocol is the missing binding glue — a single JSON file (fai-manifest.json) that declares how agents, instructions, skills, hooks, workflows, plugins, tools, prompts, and guardrails connect into evaluated, deployed, production-ready systems.

Context Wiring

Share knowledge modules and WAF pillars across all primitives automatically

Quality Gates

Enforce groundedness, coherence, relevance, safety, and cost thresholds

Auto-Discovery

Engine resolves paths, validates schemas, and wires everything in milliseconds

The Two Protocol Files

Every solution play has a full fai-manifest.json. Standalone primitives use the lightweight fai-context.json.

Full Play Manifest

The complete wiring specification for a solution play. Declares shared context (knowledge modules + WAF pillars), all primitive paths, quality guardrails with numeric thresholds, Azure infrastructure references, and toolkit paths. The FAI Engine reads this single file to orchestrate everything — no other configuration needed.

fai-manifest.json — Play 01: Enterprise RAG

{
  "play": "01-enterprise-rag",
  "version": "1.0.0",
  "context": {
    "knowledge": [
      "R2-RAG-Architecture",
      "O3-MCP-Tools",
      "T3-Production-Patterns",
      "F1-GenAI-Foundations"
    ],
    "waf": [
      "security", "reliability",
      "cost-optimization", "operational-excellence",
      "responsible-ai"
    ],
    "scope": "enterprise-rag-qa"
  },
  "primitives": {
    "agents": [
      "agents/rag-orchestrator.agent.md",
      "agents/rag-evaluator.agent.md",
      "agents/rag-retriever.agent.md"
    ],
    "instructions": [
      "instructions/rag-chunking.instructions.md",
      "instructions/rag-grounding.instructions.md",
      "instructions/rag-security.instructions.md"
    ],
    "skills": ["skills/fai-rag-indexer/"],
    "hooks": [
      "hooks/fai-secrets-scanner/",
      "hooks/fai-content-safety/",
      "hooks/fai-license-checker/"
    ],
    "guardrails": {
      "groundedness": 0.95,
      "coherence": 0.90,
      "relevance": 0.85,
      "safety": 0,
      "costPerQuery": 0.01
    }
  },
  "infrastructure": { "bicep": "./infra/main.bicep" },
  "toolkit": {
    "devkit": ".github/",
    "tunekit": "config/",
    "speckit": "spec/"
  }
}

Manifest Field Reference

Every field in fai-manifest.json — the 4 required fields plus 10 optional fields.

Field	Type	Req	Description
play	string		Solution play identifier (e.g. 01-enterprise-rag). Two-digit prefix groups plays by category.
version	string		Semantic version. Bumped on schema, primitive, or guardrail changes.
context.knowledge	string[]		FROOT module IDs this play depends on. Engine resolves to actual knowledge documents.
context.waf	string[]		WAF pillars enforced for this play. All wired primitives must respect these.
context.scope	string	—	Scenario scope for context isolation. Prevents knowledge bleed between plays.
primitives.agents	string[]	—	Relative paths to .agent.md files. Engine discovers, validates, and wires them.
primitives.instructions	string[]	—	Relative paths to .instructions.md files with applyTo glob patterns.
primitives.skills	string[]	—	Relative paths to skill folders (each containing SKILL.md).
primitives.hooks	string[]	—	Relative paths to hook folders (each containing hooks.json + script).
primitives.guardrails	object	—	Quality gates: groundedness, coherence, relevance (0-1), safety (must be 0), costPerQuery (USD).
infrastructure.bicep	string	—	Path to Bicep IaC template for Azure deployment.
toolkit.devkit	string	—	Path to .github/ developer experience tools.
toolkit.tunekit	string	—	Path to config/ quality tuning configurations.
toolkit.speckit	string	—	Path to spec/ API and architecture specifications.

FAI Protocol vs Raw .github/ Files

What changes when you adopt the FAI Protocol for your AI solution.

Capability	Raw .github/	FAI Protocol
Context sharing	Manual copy-paste between files	Automatic via context.knowledge[]
WAF enforcement	No enforcement mechanism	Declared in manifest, validated by engine
Quality gates	None — hope for the best	Guardrails with thresholds (groundedness ≥ 0.95)
Primitive discovery	Grep the file system	Engine resolves paths, validates schemas
Composability	Copy files between repos	Plugins bundle + plays compose
Infrastructure	Separate IaC with no link	infrastructure.bicep linked in manifest
Evaluation	Run scripts manually	Engine evaluates after every change

How Auto-Wiring Works

The context resolution chain — from JSON file to production-ready wired system.

Engine reads fai-manifest.json

Parses the manifest, validates every field against the JSON schema. Invalid manifests are rejected with detailed error messages before any wiring occurs.

Context resolution

Resolves context.knowledge[] to FROOT module documents, loads context.waf[] pillar definitions, and establishes context.scope boundary for isolation between plays.

Primitive discovery & validation

Every path in primitives.agents[], .instructions[], .skills[], .hooks[] is resolved relative to the play directory. Each file is validated against its respective schema.

Context injection

Resolved knowledge modules, WAF pillars, and scope are injected into every primitive. Agents receive shared context automatically — no manual copy-paste needed.

Guardrail activation

primitives.guardrails thresholds become active quality gates. The engine evaluates every agent response: groundedness ≥ 0.95, coherence ≥ 0.90, safety = 0, cost ≤ $0.01.

Runtime ready

All primitives are wired, context is shared, guardrails are enforced. Hooks fire on lifecycle triggers (sessionStart, userPromptSubmitted, preToolUse). The play is production-ready.

7 JSON Schemas

Every primitive type has a JSON Schema for automated validation. The FAI Engine and CI/CD pipeline check every file on commit.

From Protocol to Marketplace

The FAI Protocol is layer 1. Each subsequent layer builds on the previous to create a full AI primitive ecosystem.

FAI Protocol1

The JSON specification — 7 schemas defining how primitives connect

FAI Layer2

The conceptual glue — context-wiring between all AI primitives

FAI Engine3

The runtime — reads manifests, resolves context, wires primitives, evaluates

FAI Factory4

CI/CD pipeline — validate, build, test, and deploy solution plays

FAI Packages5

Distribution — npm packages, VS Code extensions, Docker images

FAI Marketplace6

Discovery — browse, search, and install primitives and plugins

ProtocolLayerEngineFactoryPackagesMarketplace

Well-Architected Framework Integration

Every manifest declares which WAF pillars apply via context.waf[]. The engine enforces them across all wired primitives — agents, instructions, skills, and hooks all respect the declared architecture.

Security

Managed Identity, Key Vault, RBAC, content safety

Reliability

Retry, circuit breaker, health checks, graceful degradation

Cost Optimization

Model routing, token budgets, right-sizing

Operational Excellence

CI/CD, observability, IaC, incident management

Performance Efficiency

Caching, streaming, async, CDN optimization

Responsible AI

Content safety, groundedness, fairness, transparency

Validate Your Primitives

Schema validation checks every file against its JSON schema and reports errors with field paths.

CLI Commands

# Validate all primitives against 7 schemas
npm run validate:primitives

# Validate specific folders
node scripts/validate-primitives.js agents/
node scripts/validate-primitives.js plugins/

# Scaffold a new primitive (interactive)
npx frootai scaffold agent
npx frootai scaffold skill
npx frootai scaffold hook

# Full build pipeline: validate → marketplace → sync
npm run build

FAI Engine Browse Primitives Marketplace Solution Plays Back to FrootAI