FAI Primitive Primer

What Are FAI Primitives?

FAI primitives are the atomic building blocks of the FrootAI ecosystem. Each primitive is a self-contained unit — a Markdown file, a JSON config, or a folder with assets — that teaches GitHub Copilot a specific capability. Unlike standalone config files that work in isolation, every FAI primitive is context-aware: it declares which knowledge modules it references, which Well-Architected Framework (WAF) pillars it enforces, and which solution plays it is compatible with.

Primitives operate in two modes. In standalone mode (LEGO block), a single primitive enhances your editor immediately — drop an agent file into .github/agents/ and Copilot gains that expertise. In wired mode (solution play), the fai-manifest.json orchestrates multiple primitives into a cohesive architecture with shared context, guardrails, and evaluation thresholds.

This dual-mode design is what makes the FAI Protocol unique. Every primitive is useful on its own, yet becomes dramatically more powerful when composed into a play.

The 9 Protocol Primitive Types at a Glance

The FAI Protocol defines nine composable types. GitHub's repository customization model groups related capabilities into seven surfaces; fai-manifest.json is the wiring contract, not a tenth primitive.

1. Agents — AI Personas

An agent file gives Copilot a specialized role. When you invoke @fai-rag-architect in Copilot Chat, it loads the agent's system prompt, restricts which tools it can call, and applies its WAF alignment. Agents are the most visible primitive — they change who Copilot acts as.

---description: "RAG architecture expert using Azure AI Search + OpenAI"model: gpt-4otools:  - file_search  - read_file  - semantic_searchwaf:  - security  - reliability  - cost-optimizationplays:  - "01-enterprise-rag"  - "03-multimodal-rag"---
You are an expert RAG architect. When designing retrieval pipelines:
1. Always use hybrid search (vector + keyword) for recall2. Apply semantic ranker for precision at query time3. Use managed identity for all Azure service connections4. Set max_tokens budgets per query tier (simple: 500, complex: 2000)5. Include citation grounding in every response

2. Instructions — Persistent Coding Standards

Instructions activate automatically when you edit files matching the applyTo glob pattern. They are passive — Copilot absorbs them silently and applies the rules to every suggestion. No explicit invocation required.

---description: "Python standards with WAF security and reliability"applyTo: "**/*.py"waf:  - security  - reliability---
- Use DefaultAzureCredential for all Azure SDK clients- Never hardcode connection strings — use Key Vault references- Wrap external calls in retry with exponential backoff (max 3)- Log with structlog using correlation_id from request context

3. Skills — Step-by-Step Procedures

Skills are folder-based primitives. Each skill lives in a named folder containing SKILL.md (the procedure) plus optional bundled assets like templates, scripts, or example configs. The folder name must match the name frontmatter field.

---name: fai-play-initializerdescription: "Scaffold a new FAI solution play with all required files"---
## Steps
1. Create the play folder: `solution-plays/NN-kebab-name/`2. Generate fai-manifest.json with context, primitives, guardrails3. Add config/openai.json with model defaults (gpt-4o, temp 0.1)4. Add config/guardrails.json with safety thresholds5. Create README.md with play overview and architecture diagram6. Run `npm run validate:primitives` to verify schema compliance

4. Hooks — Lifecycle Event Automation

The shipped hook manifests use five lifecycle events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop. They run deterministic commands to enforce policies, scan for secrets, or record audit trails.

{  "version": 1,  "hooks": {    "Stop": [      {        "type": "command",        "command": "bash hooks/fai-secrets-scanner/scan-secrets.sh",        "windows": "powershell -File hooks/fai-secrets-scanner/scan-secrets.ps1",        "cwd": ".",        "timeout": 30      }    ]  }}

5. Plugins — Themed Bundles

A plugin packages related primitives into a single installable unit. The plugin.json manifest declares metadata (name, version, author, license) and references the agents, instructions, skills, and hooks it bundles. Install a plugin with one command:

{  "name": "enterprise-rag",  "version": "1.0.0",  "description": "Complete RAG primitive bundle for enterprise deployments",  "author": { "name": "FrootAI" },  "license": "MIT",  "primitives": {    "agents": ["fai-rag-architect", "fai-azure-ai-search-expert"],    "instructions": ["python-waf", "bicep-waf"],    "skills": ["deploy-01-enterprise-rag"],    "hooks": ["fai-secrets-scanner"]  }}

6. Workflows — Automated Task Chains

Workflows define multi-step automated tasks with safe-outputs constraints. Each step specifies which tools can be called and what outputs are permitted. Workflows are ideal for CI/CD integrations, bulk code migrations, and release processes.

7. Tools — Bounded Capabilities

Tools expose callable capabilities through explicit schemas and permission boundaries. A tool may come from MCP, a local extension, or a host runtime; agents should receive only the tools required for their role.

8. Prompts — Reusable Task Entry Points

Prompt files package a repeatable task, expected inputs, and supporting context in .github/prompts/*.prompt.md. They are user-invoked entry points, while instructions remain passive and agents provide persistent specialist roles.

9. Guardrails — Measurable Boundaries

Guardrails declare quality, safety, policy, and cost boundaries that a runtime can evaluate. They complement deterministic hooks: hooks control lifecycle actions, while guardrails decide whether an output meets its release thresholds.

The Wiring Manifest — FAI Protocol Glue

The fai-manifest.json is the crown jewel. It declares context (knowledge modules, WAF pillars), lists all primitives in a play, sets guardrail thresholds, and defines infrastructure requirements. The FAI Engine reads this single file to orchestrate an entire solution play.

{  "play": "01-enterprise-rag",  "version": "1.0.0",  "context": {    "knowledge": ["F1", "F2", "R2", "O4"],    "waf": ["security", "reliability", "cost-optimization"]  },  "primitives": {    "agents": ["fai-rag-architect"],    "instructions": ["python-waf", "bicep-waf"],    "skills": ["fai-play-initializer"],    "hooks": ["fai-secrets-scanner"]  },  "guardrails": {    "groundedness": 0.85,    "relevance": 0.80,    "coherence": 0.90  }}

WAF Alignment System

Every primitive can declare one or more of the 6 WAF pillars in its frontmatter. This connects coding primitives to architecture governance — a capability unique to FrootAI.

Naming Conventions

All FAI primitives follow lowercase-hyphen naming. No underscores, no camelCase. The file name must match the primitive's identity:

# Agentsfai-rag-architect.agent.md         ✅frootai_rag_architect.agent.md         ❌ (underscores)FrootaiRagArchitect.agent.md           ❌ (camelCase)
# Instructionspython-waf.instructions.md             ✅
# Skills (folder name = frontmatter name)skills/fai-play-initializer/SKILL.md  ✅
# Hooks (folder with hooks.json + script)hooks/fai-secrets-scanner/hooks.json  ✅
# Plugins (folder with plugin.json)plugins/enterprise-rag/plugin.json        ✅

Quick Start

Install the essentials plugin to get started with pre-configured agents, instructions, skills, and hooks for enterprise use:

# Install the essentials pluginnpx frootai install fai-essentials
# Validate all primitives in your reponpm run validate:primitives
# Check ecosystem scorecardnpm run scorecard