TL;DR: faf_agents and faf_gemini used to write thin stub files. They now author the full, family-standard AGENTS.md and GEMINI.md — the same shape every other FAF tool produces, because they call the same authoring tool. New faf_migrate brings an old .faf up to the current format so it has current input.

In Plain English

Old state. faf_agents gave you four headings — ## Project, ## Context, ## Stack — with "N/A" in most of them, plus who/why marketing copy that has no business in an agent's operating file. faf_gemini wrote YAML frontmatter and an embedded score. Every FAF tool that authored these files did it a little differently.

Fix. Both tools now call one authoring tool that lives in faf-python-sdk — a Python port of the same logic faf-cli uses, kept in parity. The AGENTS.md you get is the full shape: setup, tests, where things live, conventions, a three-tier guardrails ladder, definition of done, when stuck, security, commit & PR, stack. No "who/why" section — that belongs in your README and your .faf, not your agent ops file. GEMINI.md follows Gemini CLI's own hierarchical, @file-importable convention.

New state. The AGENTS.md faf-cli writes and the one gemini-faf-mcp writes are the same document shape, because they are the same code. One implementation, one standard, across the family.

uvx gemini-faf-mcp

uvx is the try. Zero-install, fetched straight from PyPI. For a permanent install: pip3 install gemini-faf-mcp==2.7.0.

What happened since The Agent Card Edition

One blog, one arc. Last write-up was v2.6.0 — The Agent Card Edition (a real agent.fafa passport, MCP Server Card, AI Catalog entry). 2.7.0 is the next log entry — the doc tools got real.

"The Interop Edition" is a shared name. faf-python-sdk 1.3.0 shipped the same day with the same title — it is where the shared AGENTS.md / GEMINI.md authoring tool now lives. gemini-faf-mcp 2.7.0 is the first server to wrap it. Same work, two packages.

What 2.7.0 is

Lesson: a file your tools write for you is only useful if every tool writes the same one.

faf_agents and faf_gemini are now three-line wrappers over one authoring tool in faf-python-sdk. The projection is deterministic — same .faf in, same Markdown out — and it is the BETTER shape faf-cli's faf export already produced. Commands are classified and ordered (install → build → dev), the guardrails render as a three-tier ladder (Always OK / Ask first / Never), and there is a Definition of Done and a "When stuck" section. Human Context is deliberately left out.

faf_migrate is the new thirteenth tool. It bumps a .faf to the current format version, ensures the section roots exist, and re-serializes — legacy slot names still score through the registry's aliases. Pass dry_run to preview the change without writing. It is parity with faf-cli's faf migrate.

Also in this release: fastmcp floor moved to 4.0.0, Python 3.10 is dropped (requires-python >=3.11), and the 245-test suite now runs in CI on 3.11 / 3.12 / 3.13 on every push — it used to run only locally.

Try it

Try (zero-install, not the permanent install):

uvx gemini-faf-mcp

Install (PyPI):

pip3 install gemini-faf-mcp==2.7.0

Add to Gemini CLI:

gemini extensions install https://github.com/Wolfe-Jam/gemini-faf-mcp

Then, in Gemini CLI:

Run faf_agents to write my AGENTS.md Run faf_migrate --dry-run on my project.faf

More depth: The Agent Card Edition (v2.6.0) · repo · PyPI.

Technical details

  • Version: 2.7.0 (September 6, 2026)
  • Identity: one.faf/gemini-faf-mcp
  • Framework: FastMCP 4 (floor >=4.0.0)
  • Runtime: Python 3.11+ (3.10 dropped)
  • Depends on: faf-python-sdk >=1.3.0 — where the authoring tool lives
  • Tools: 13 (+1 — faf_migrate)
  • Tests: 245 passing — now in CI on 3.11 / 3.12 / 3.13
  • Score: Trophy 100%, 17/17 slots
  • Changed: faf_agents / faf_gemini rewritten as SDK wrappers; faf_init / faf_auto templates emit faf_version: "3.0"

Built with .faf ☑️ One authoring tool. One standard. Every FAF surface. 🏎️