Agentic OS Architecture
Six capability layers, five repository planes, one operating system. This page shows what FFC has today in each layer, what is planned, and the phased roadmap that gets there — the full detail lives in the blueprint docs.
The six layers
The layers are the standard anatomy of an agentic operating system; the planes (see overview) are the FFC repos that implement them.
| Layer | What FFC has today | What is planned |
|---|---|---|
| 1 · Connections (tools & MCP) | MCP servers wired per repo: GitHub, Cloudflare, Playwright, Sentry, Microsoft Learn. Copilot MCP config in .copilot/mcp-config.json. | A single org-maintained MCP baseline distributed from FFC-IN-AI-Management so every repo exposes the same tools. |
| 2 · Memory & shared context | CLAUDE.md / AGENTS.md / GEMINI.md instruction files, freshness-stamped snapshot docs, and the PR audit trail as the durable session record. | A lessons-learned loop: periodic reflection sessions that mine merged agent PRs and propose CLAUDE.md/agent-prompt updates. |
| 3 · Agents | Custom subagents in .claude/agents/ (dns-audit, site-health, pr-reviewer, copilot-review-cycle, cross-repo-sync, onboarding, session-archivist, org-inventory-auditor) plus the Antigravity reviewer/coder loop. | The agent set versioned and distributed org-wide from AI-Management; charity-site repos get the site-focused subset. |
| 4 · Orchestration | The issue → branch → PR runbook (docs/agent-issue-pr-workflow.md), fan-out skills in .claude/skills/, and the numbered ops workflow catalog. | Event-driven runs on the Max subscription: Routine GitHub triggers for PR and Release events, plus @claude mentions via the subscription-authenticated claude-code-action — all under a dedicated automation account, never API billing. |
| 5 · Governance & guardrails | Permission allow/deny policy in .claude/settings.json, secret rules, approval-gated write workflows with dry-run defaults, no-self-merge PR review. | A written org governance doc (docs/agentic-os/06-governance.md) adopted across repos; a dedicated automation account for unattended runs. |
| 6 · Observability | The session inventory snapshot + dashboard, CI status and data feeds on this site, freshness conventions on every snapshot doc. | Quarterly inventory refreshes, per-plane health checks via the /agentic-os-status skill, and session/run budgets on automated runs (subscription capacity, not token spend). |
The roadmap
Phase 0 — Capture (this site)
DeliveredInventory every agent session across the org, document the architecture and governance model, and ship the reference skills/agents in this repo.
Phase 1 — Distribute
NextFFC-IN-AI-Management templates the session-archivist/auditor agents and the agentic-os skills into its base + overlay model and syncs them to all ~30 managed repos.
Phase 2 — Automate
In progressOrg plugin marketplace + Max-subscription event automation (Routine GitHub triggers, subscription-authenticated claude-code-action) so every new charity site is born with the full agent toolkit; a dedicated automation account for unattended runs. Already operating from the hub: the Conductor loop and the daily agentic-os status feed rendered on the Agentic OS status page.
Phase 3 — Operate
PlannedQuarterly inventory refresh cadence, reflection sessions feeding instruction-file improvements, and observability budgets — the OS as routine operations.
Per-repo actions and the issues to file are enumerated in docs/agentic-os/05-roadmap.md.
Governance highlights
- Every agent change is a pull request. Agents never push to
main; a human maintainer reviews and merges. The PR trail is the audit log. - No self-merge. The agent that authored a change cannot approve it — the same separation of duties the ops workflows enforce with approval environments.
- Snapshot, don't scan.This site publishes committed snapshots of other repos' state with freshness stamps; live scanning and write automation belong to the ops and control planes.
- Bounded autonomy. Write workflows default to dry-run behind approval gates; unattended agent runs need explicit identity, scope, and turn budgets.
- Volunteer-sized cadence. Refresh rhythms (90-day inventory, 30-day standards) are sized so a small volunteer team can actually sustain them.
Full model: docs/agentic-os/06-governance.md · Related: Session Inventory · Automation