Skip to main content

Primitives

Primitives are the building blocks of every FrootAI solution. There are 6 primitive types, each serving a distinct purpose. Every primitive works standalone and auto-wires when placed inside a solution play via the FAI Protocol.

The 6 Primitive Types​

TypeFile FormatCountPurpose
Agents.agent.md238AI personalities with tools, model preferences, and WAF alignment
Instructions.instructions.md176Auto-applied coding standards scoped by file glob patterns
SkillsSKILL.md folder322Multi-step procedures the agent can execute
Hookshooks.json10Event-driven guardrails triggered by lifecycle events
Pluginsplugin.json77Themed bundles of agents + skills + hooks
Workflows.yml13Multi-agent orchestration pipelines

Agents​

Agents are AI personalities defined in .agent.md files with YAML frontmatter. Each agent declares its description, tools, preferred models, WAF alignment, and compatible plays.

agents/fai-rag-architect.agent.md
---
description: "RAG pipeline design — chunking, indexing, retrieval, reranking"
tools: ["codebase", "terminal"]
model: ["gpt-4o", "gpt-4o-mini"]
waf: ["security", "reliability"]
plays: ["01-enterprise-rag", "21-agentic-rag"]
---

# FAI RAG Architect

You are the RAG Architect agent. Design retrieval-augmented generation
pipelines with optimal chunking strategies, hybrid search, and reranking.
Always cite the WAF pillar when making architecture decisions.
info

Every solution play ships with a builder → reviewer → tuner agent triad for the build-review-tune workflow.

Instructions​

Instructions are auto-applied coding standards in .instructions.md files. The applyTo glob pattern determines which files the instruction activates for.

instructions/waf-security.instructions.md
---
description: "Security best practices from Azure Well-Architected Framework"
applyTo: "**/*.{ts,js,py,bicep,json,yaml,yml}"
waf: ["security"]
---

# Security — Azure Well-Architected Framework

## Identity & Access
- NEVER hardcode secrets, API keys, or connection strings
- Use Azure Managed Identity for service-to-service auth
- Use Azure Key Vault for secrets management

Skills​

Skills are self-contained, multi-step procedures packaged in folders with a SKILL.md file. They provide step-by-step logic that an agent can follow to accomplish complex tasks.

skills/fai-play-initializer/SKILL.md
---
name: fai-play-initializer
description: "Scaffold a new FrootAI solution play with full FAI Protocol structure"
---

# FAI Play Initializer

## Steps

1. Pick a play number and kebab-case name
2. Scaffold the directory tree (DevKit, TuneKit, SpecKit, Infra)
3. Create fai-manifest.json with context and primitives
4. Create TuneKit config files (openai.json, guardrails.json)
5. Create DevKit agent (builder.agent.md)
6. Validate with `npm run validate:primitives`
tip

Skills must be 150+ lines with detailed step-by-step logic. Think runbook, not summary.

Hooks​

Hooks are event-driven scripts triggered by lifecycle events. They are defined in a hooks.json file inside a named folder.

hooks/frootai-secrets-scanner/hooks.json
{
  "version": 1,
  "hooks": [
    {
      "event": "SessionStart",
      "steps": [
        {
          "type": "shell",
          "command": "bash ${__dirname}/scan-secrets.sh"
        }
      ]
    }
  ]
}

Available lifecycle events:

EventWhen It Fires
SessionStartAgent session begins
UserPromptSubmitUser sends a message
PreToolUseBefore a tool is invoked
PostToolUseAfter a tool completes
PreCompactBefore context compaction
SubagentStartBefore a sub-agent launches
SubagentStopAfter a sub-agent completes
StopAgent session ends
warning

Never use PreToolUse hooks — they spawn a process per tool call, adding ~5 seconds of delay each time. Use SessionStart for validation and scanning.

Plugins​

Plugins are themed bundles that package agents, skills, and hooks into a single installable unit. Each plugin has a plugin.json manifest.

plugins/enterprise-rag/plugin.json
{
  "name": "enterprise-rag",
  "description": "Complete RAG pipeline with security hooks and evaluation",
  "version": "1.0.0",
  "author": { "name": "FrootAI" },
  "license": "MIT",
  "agents": ["./.github/agents/rag-builder.agent.md"],
  "skills": ["./.github/skills/rag-indexer/"],
  "hooks": ["../../hooks/frootai-secrets-scanner/"],
  "plays": ["01-enterprise-rag"]
}

Workflows​

Workflows are multi-agent orchestration pipelines defined in .yml files. They coordinate multiple agents to accomplish complex tasks.

workflows/safe-outputs.yml
name: safe-outputs
steps:
  - agent: builder
    task: "Generate the solution code"
  - agent: reviewer
    task: "Review for security and quality"
  - agent: tuner
    task: "Validate config and thresholds"

How Primitives Compose​

Primitives follow a standalone → auto-wire model:

  1. Standalone: Every primitive works independently. An agent in agents/ can be referenced directly by any AI coding assistant.

  2. Auto-wire: When a primitive is referenced in a play's fai-manifest.json, the FAI Engine injects shared context (knowledge modules + WAF pillars) into the primitive automatically.

Standalone Agent                    Inside a Play
┌─────────────┐                 ┌──────────────────┐
│ agent.md    │                 │ fai-manifest.json │
│  - tools    │    ──wired──▸   │   context:        │
│  - model    │                 │     knowledge ──▸ agent receives
│  - waf      │                 │     waf ──▸        domain knowledge
└─────────────┘                 └──────────────────┘

WAF Alignment​

Every primitive can declare which Well-Architected Framework pillars it supports via a waf array in its frontmatter. This enables automated governance — the FAI Engine verifies that a play's declared WAF pillars are covered by its primitives.

Validation​

Validate all primitives in the repository:

npm run validate:primitives

This checks:

  • File naming follows lowercase-hyphen convention
  • YAML frontmatter has required fields per type
  • Skill names match their parent folder
  • Hook events are valid lifecycle events
  • Plugin manifests are complete and valid

Next Steps​