FAI Agentic Workflows
12 workflows with safe-outputs, trigger types, and GitHub Actions compatibility — Copilot-driven automation with guardrails.
What Are Agentic Workflows?
Agentic workflows are Markdown files with YAML frontmatter that define multi-step automation tasks for GitHub Copilot. Unlike traditional GitHub Actions that run deterministic shell scripts, agentic workflows describe intent in natural language — the agent reads steps, reasons through them, and produces constrained outputs. The key distinction is that every output action is bounded by safe-outputs limits.
Each workflow lives in the .github/workflows/ directory and compiles to a GitHub Actions YAML that invokes Copilot as the executor. The agent is given the workflow steps as context and must produce results that satisfy the declared constraints — no more issues than allowed, no comments beyond the limit, no PR merges without approval.
FrootAI ships 12 production-ready workflows covering quality assurance, compliance validation, staleness detection, and ecosystem reporting. Each workflow is tested, documented, and wired into the FAI Protocol via manifest references.
Workflow Frontmatter Schema
Every agentic workflow begins with YAML frontmatter that declares metadata, triggers, and output constraints:
| Field | Required | Type | Purpose |
|---|---|---|---|
| name | Yes | string | Workflow display name in Actions UI |
| description | Yes | string | One-line summary of purpose |
| trigger | Yes | object | Schedule, dispatch, PR event, or slash command |
| safe-outputs | Yes | object | Output constraints (max issues, comments, etc.) |
| permissions | No | object | GitHub token permission scopes |
| waf | No | string[] | WAF pillars this workflow enforces |
| steps | Yes | string[] | Natural-language step descriptions |
Complete Workflow Example
Below is a full agentic workflow file. The agent reads the steps, executes them in order, and produces outputs that respect the declared limits:
---
name: FAI Primitive Quality Check
description: Validate all primitives against schema and naming conventions
trigger:
schedule:
cron: "0 6 * * 1" # Every Monday at 6am UTC
workflow_dispatch: true # Manual trigger via Actions UI
safe-outputs:
create-issue: { max: 1 }
add-comment: { max: 3 }
close-older-issues: true
permissions:
issues: write
contents: read
waf: [operational-excellence, reliability]
---
## Steps
1. Run `node scripts/validate-primitives.js --verbose` and capture output
2. Parse results — count errors, warnings, and passing primitives
3. If errors > 0: create a single GitHub issue titled
"Primitive Validation: {errorCount} errors found on {date}"
4. Add a comment with the full error details (truncate to 64KB)
5. If a previous validation issue exists and is now resolved,
close it with a comment: "All primitives passing ✅"
6. Post a summary comment on the latest commitSafe-Outputs Constraint Reference
Safe-outputs are the guardrail mechanism that prevents agent runaway. Every write action the agent can take must be declared and bounded. If the agent attempts an action not listed or exceeds the limit, the action is blocked.
| Constraint | Values | Default | Behavior |
|---|---|---|---|
| create-issue | { max: N } | max: 0 | Limits new issues created per run |
| add-comment | { max: N } | max: 0 | Limits comments on issues or PRs |
| close-older-issues | true / false | false | Auto-close stale issues from prior runs |
| create-pr | { max: N } | max: 0 | Limits pull requests created per run |
| add-label | { max: N } | max: 0 | Limits label additions per run |
| modify-files | { max: N, paths: [] } | max: 0 | Limits file edits to specific paths |
4 Trigger Types
Each workflow declares one or more triggers that determine when it runs:
Schedule (cron)
Runs on a cron schedule. Best for periodic checks like weekly quality audits or nightly staleness scans. Uses standard 5-field POSIX cron syntax. All times are UTC.
Manual (workflow_dispatch)
Triggered manually from the GitHub Actions UI or via API. Include optional inputs for parameters like target branch, scope, or verbosity level.
PR Event
Fires on pull request events — opened, synchronize, labeled. Used for PR quality checks, compliance validation, and automated reviews.
Slash Command
Triggered by a comment like /play-relevance on an issue or PR. The agent reads the issue context and responds inline. Great for on-demand analysis.
All 12 Workflows by Category
Quality (4 workflows)
Validates all agents, instructions, skills, hooks against schemas. Creates a single issue if errors found, closes it when resolved.
Runs on every PR that modifies primitives. Checks naming conventions, frontmatter, and WAF alignment. Adds review comments inline.
Compares current primitives against schema definitions weekly. Detects field additions or removals that break validation.
Cross-checks README counts, marketplace.json, website-data, and package.json for consistency. Reports mismatches.
Compliance (2 workflows)
Scans all solution plays for WAF pillar coverage. Flags plays missing security, reliability, or responsible AI alignment.
Validates that all new dependencies have compatible licenses. Blocks PRs that introduce GPL or unlicensed packages.
Staleness (3 workflows)
Finds solution plays not updated in 90+ days. Creates issues prompting maintainers to review or deprecate.
Checks npm, Python, and Bicep dependencies for outdated versions. Suggests pinned version bumps via issue comment.
Tracks Azure OpenAI model version deprecation dates. Alerts when a play references a model nearing end-of-life.
Reporting (3 workflows)
Generates weekly counts: agents, instructions, skills, hooks, plugins, plays. Posts summary to a pinned issue.
Triggered by /play-relevance on an issue. Analyzes the issue description and suggests matching solution plays.
Reads merged PRs since last release tag. Generates a categorized changelog grouped by primitives, plays, and infra.
Workflow Lifecycle
Every agentic workflow follows a 5-phase lifecycle from trigger to completion:
Scheduling & Cron Patterns
Schedule-triggered workflows use standard POSIX cron. All times are UTC. Common patterns:
# Weekly Monday 6am UTC — quality audits
cron: "0 6 * * 1"
# Daily midnight — staleness scans
cron: "0 0 * * *"
# Every 6 hours — ecosystem scorecard
cron: "0 */6 * * *"
# First of month — compliance reports
cron: "0 9 1 * *"Combine schedule with workflow_dispatch: true so workflows can also be triggered manually for debugging or on-demand runs.
Permissions Model
Workflows follow the principle of least privilege. Each workflow declares only the GitHub token scopes it needs:
permissions:
contents: read # Read repo files
issues: write # Create/close issues
pull-requests: read # Read PR metadata
# Never granted: admin, packages, actionsIf a workflow does not declare permissions, it defaults to contents: read only. Workflows that need write access must explicitly declare it — this is enforced by the FAI PR quality gate.
GitHub Integration
Agentic workflows integrate deeply with the GitHub ecosystem:
Status Badges
Each workflow generates a status badge that can be embedded in README files. Shows last run status: passing, failing, or skipped.
Issue Templates
Workflows that create issues use standardized templates with labels, assignees, and milestone references pre-configured.
Branch Protection
PR-triggered workflows can be set as required status checks. No merge until the quality gate passes.
Environments
Workflows can reference GitHub Environments for secrets and deployment protection rules. Production workflows require manual approval.