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 7 Primitive Types at a Glance

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-4o
tools:
  - file_search
  - read_file
  - semantic_search
waf:
  - security
  - reliability
  - cost-optimization
plays:
  - "01-enterprise-rag"
  - "03-multimodal-rag"
---

You are an expert RAG architect. When designing retrieval pipelines:

1. Always use hybrid search (vector + keyword) for recall
2. Apply semantic ranker for precision at query time
3. Use managed identity for all Azure service connections
4. 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-initializer
description: "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, guardrails
3. Add config/openai.json with model defaults (gpt-4o, temp 0.1)
4. Add config/guardrails.json with safety thresholds
5. Create README.md with play overview and architecture diagram
6. Run `npm run validate:primitives` to verify schema compliance

4. Hooks — Lifecycle Event Automation

Hooks fire at specific session lifecycle events: sessionStart, sessionEnd, userPromptSubmitted, and preToolUse. They run shell scripts or Node.js modules to enforce security policies, scan for secrets, or log audit trails.

{
  "version": 1,
  "hooks": [
    {
      "event": "userPromptSubmitted",
      "command": "node scan-secrets.js",
      "description": "Scan prompt for accidental secret inclusion"
    }
  ]
}

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. Manifests — The 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-hyphennaming. No underscores, no camelCase. The file name must match the primitive's identity:

# Agents
fai-rag-architect.agent.md         ✅
frootai_rag_architect.agent.md         ❌ (underscores)
FrootaiRagArchitect.agent.md           ❌ (camelCase)

# Instructions
python-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 plugin
npx frootai install fai-essentials

# Validate all primitives in your repo
npm run validate:primitives

# Check ecosystem scorecard
npm run scorecard