FPF Spec Runtime

FPF helps when raw insight is not enough: meanings, claims, alternatives, evidence, boundaries, and outputs must remain stable across contexts, time, people, tools, or AI agents.

Quick links: Website · MCP setup · Hosted MCP endpoint

FPF vs MCP: FPF is the upstream specification; FPF Reference MCP (fpf_reference) is the hosted tool endpoint agents call to query it — not agent memory. Add the hosted URL to your client from mcp.fpf.sh.

📖 Live reference: fpf.sh — searchable pattern catalog, routes, and preface. Type an ID like A.2 or route:project-alignment in the search box to jump in.

🤖 Working with this repo as an agent? See AGENTS.md for the MCP tool guide and workspace conventions.

🧭 Coordinating repo automation? See the Automation Playbook for role boundaries, access rules, merge authority, and draft-only publishing packets.

About FPF

The First Principles Framework (FPF) is a structured framework for thinking and coordinating work. It is written more like a technical specification than like a management book: there are named patterns, definitions, and review rules. Its job is to help teams model complex work, make reasoning inspectable, and keep decisions stable across engineering, research, and management.

FPF is authored by Anatoly Levenchuk. The upstream publication source this runtime tracks is github.com/ailev/FPF, specifically FPF-Spec.md on main by default. This repository is a runtime + slim wiki projection of the published spec, not the spec itself.

What is this repo?

A local FPF spec runtime. Given a single markdown spec file, it compiles a deterministic, vectorless index of FPF IDs, routes, relations, and anchors, and exposes that as:

• an MCP server (public + optional full surface) for IDE agents like Codex
• a Bun CLI for queries, traces, and inspections
• a static docs site built from the same compiled artifacts

No vector database, no remote indexing, no Python, and no local LLM dependency. Answers are produced from deterministic retrieval over the compiled spec snapshot.

Claude Code plugin

This repository is also a Claude Code plugin marketplace. The fpf-reference plugin registers the hosted fpf_reference MCP server, ships the setup skill, and adds a /fpf-reference:validate first-call validation command:

/plugin marketplace add venikman/fpf-memory
/plugin install fpf-reference@fpf

Details: plugins/fpf-reference/README.md.

Quick start

bun install
cp .env.example .env             # see Configuration below
bun run spec:download            # fetch FPF-Spec.md into .fpf-upstream/
bun run publish:current          # refresh the committed published/current/** surface
bun run cli -- query --question "What is U.BoundedContext?" --mode verbose

To run the local MCP server (full surface, expert tools enabled):

FPF_MCP_SURFACE=full bun run mcp

To browse docs locally:

bun run docs:dev

How it works

On each refresh trigger the runtime:

1. hashes the spec file at FPF_SPEC_SOURCE_PATH and reuses the snapshot if the hash matches
2. otherwise recompiles a local vectorless index, writing snapshot.json, build-audit.json, index-map.json, indexing-view.json, pattern-graph.json, route-graph.json, lexicon.json, and anchor-map.json under FPF_RUNTIME_ARTIFACT_DIR (default .runtime/fpf-index/)
3. enriches the index with deterministic section descriptions plus per-node metadata (role, route-bearing status, …)
4. follows explicit references, route hints, and outline adjacency in a bounded frontier loop when the first anchor set is insufficient
5. optionally reuses a short-lived in-memory session context when query or trace is called with --session / sessionId
6. answers with IDs, citations, constraints, relations, and snapshot metadata

Stack

• Bun — preferred local runtime and package manager
• Zod — repo-authored MCP contracts and validation
• Model Context Protocol SDK — direct MCP server/transport runtime for local stdio and hosted HTTP
• Hono — hosted server engine
• Rstest, Rslint, Rspress — test, lint, docs

Scope

In:

• one markdown spec file as the runtime source set (default: published/current/FPF-Spec.md)
• a gitignored local publish source: .fpf-upstream/FPF-Spec.md, or any local checkout via FPF_PUBLISH_SOURCE_PATH
• generated pattern/route markdown under docs/generated/** (not committed; produced by bun run docs:generate)
• static docs build output under doc_build/ (deterministic, ignored)

Out:

• a vector database
• any remote indexing service
• any Python code
• a validation/tuning corpus inside the runtime path

Automated publication refresh

.github/workflows/sync-fpf.yml keeps both public surfaces current when FPF changes upstream in ailev/FPF:

• Fast path: a trusted origin notifier can send this repo a repository_dispatch event named fpf-origin-updated or fpf-sync-updated with client_payload.sha/after, client_payload.ref/branch, and optionally client_payload.spec_url.
• Backstops: .github/workflows/fpf-sync-monitor.yml runs daily (11:47 UTC) and triggers this worker when production is behind and no sync worker is already active; the worker can also be triggered manually with a branch, tag, commit SHA, or raw spec URL paired with an explicit upstream ref.
• Work performed: download FPF-Spec.md, run publish:current, validate published/current/**, build the static website deployment, build the separate hosted MCP deployment, and open a publication PR only when files changed.
• Hosted MCP handoff: before opening a new PR, the workflow closes superseded chore/sync-fpf-* PRs. After the review window and required checks pass, it squash-merges the current PR and deploys the website and MCP production bundles through the repo CLI scripts.
• Monitor: .github/workflows/fpf-sync-monitor.yml runs daily (11:47 UTC), checks ailev/FPF HEAD against https://mcp.fpf.sh/api/fpf/status, triggers sync-fpf.yml when upstream is ahead, and redispatches it when a current generated PR exists but no worker is queued or running. It fails only when drift exceeds the configured SLO or the hosted runtime is internally stale.
• Spend guardrail: .github/workflows/vercel-spend-monitor.yml runs every 6 hours with VERCEL_SPEND_MONITOR_TOKEN or VERCEL_TOKEN, checks Vercel Function Duration GB-hours, platform error-code rows, and legacy /api/mcp/fpf_memory function invocations, distinguishes ok, breach, config_error, metrics_unavailable, and expected_blocked_traffic, updates one open issue only when operator action is required, and closes it after a clean monitor window.
• Keepalive: .github/workflows/workflow-keepalive.yml runs weekly and keeps the whole scheduled fleet alive across GitHub's 60-day inactivity auto-disable for public repositories — it re-enables every active or auto-disabled workflow (resetting each one's inactivity clock, sparing manually disabled ones) and, after 45 days without a push to any branch, refreshes a marker file on the automation/keepalive branch so real repository activity exists even when upstream is quiet.

Minimal dispatch payload:

{
  "event_type": "fpf-origin-updated",
  "client_payload": {
    "sha": "<ailev/FPF commit sha>"
  }
}

Publication QA follows FPF anchors directly:

• B.5.1 separates exploration, shaping, evidence, and operation: sync PRs do publication work; monitor runs production evidence.
• A.10 and G.6 make SHA, manifest, source hash, runtime freshness, and check URLs the evidence graph.
• B.3, E.19, and E.21 keep quality gates explicit: source/ref coherence, runtime freshness, preview/E2E, CI, recoverability, and max drift are separate characteristics, not one vague "green" claim.

Configuration

Copy .env.example to .env. The most common settings:

| Variable | Default | Purpose | | ----------------------------------------- | ------------------------------------ | --------------------------------------------------------------------- | | FPF_SPEC_SOURCE_PATH | published/current/FPF-Spec.md | Local path to the spec the runtime reads (must be a filesystem path). | | FPF_PUBLISH_SOURCE_PATH | .fpf-upstream/FPF-Spec.md | Local source used by publish:current. | | FPF_UPSTREAM_OWNER | ailev | GitHub owner for upstream publication provenance and downloads. | | FPF_UPSTREAM_REPO | FPF | GitHub repo for upstream publication provenance and downloads. | | FPF_UPSTREAM_REF | main | Branch, tag, or SHA used by spec:download and publish:current. | | FPF_UPSTREAM_SPEC_PATH | FPF-Spec.md | Path to the spec inside the upstream repo. | | FPF_SYNC_MONITOR_STATUS_URL | https://mcp.fpf.sh/api/fpf/status | MCP production status endpoint checked by monitor:sync. | | FPF_CONTENT_QUALITY_BASE_URL | https://fpf.sh | Website production base URL checked by monitor:content --mode live. | | FPF_CONTENT_QUALITY_STATUS_URL | https://mcp.fpf.sh/api/fpf/status | Runtime status URL used for live content provenance checks. | | FPF_SYNC_MONITOR_MAX_DRIFT_HOURS | 26 | Hours a publishable upstream commit may stay unpublished before breach. | | FPF_VERCEL_PROJECT | fpf-reference-mcp | Vercel MCP/API project checked by monitor:vercel:spend. | | FPF_VERCEL_SCOPE | none (example: venikmans-projects) | Vercel team scope for metrics and deploy commands. No built-in code default; seeded in .env.example. | | FPF_VERCEL_SPEND_WINDOW_MINUTES | 30 | Metrics lookback window for spend guardrails. | | FPF_VERCEL_SPEND_MAX_FUNCTION_DURATION_GBHR | 0.25 | Maximum Function Duration GB-hours allowed in the lookback window. | | FPF_VERCEL_SPEND_MAX_LEGACY_INVOCATIONS | 0 | Maximum function invocations allowed for the legacy MCP route. | | FPF_VERCEL_SPEND_MAX_ERROR_INVOCATIONS | 0 | Maximum function invocations allowed with non-empty Vercel error_code. | | FPF_RUNTIME_ARTIFACT_DIR | .runtime/fpf-index | Where compiled artifacts are written. | | FPF_QUERY_DEFAULT_MODE | verbose | Default mode for query_fpf_spec and ask_fpf. | | FPF_HOSTED_MCP_DISABLED | false | Emergency hosted /api/mcp/* shutoff; returns 503 before loading the MCP runtime. | | FPF_RUNTIME_LOG_PATH | .runtime/logs/fpf-runtime.log | Structured runtime/MCP logs. |

<details> <summary>Detailed notes on these variables</summary>

FPF_SPEC_SOURCE_PATH must be a local filesystem path — the runtime does not fetch https:// URLs. The default is th