Skip to content
/

FPF (First Principles Framework)

fpf · ailev/FPF · ★ 372 · last commit 2026-05-23

Provides a formal pattern language for making reasoning explicit, traceable, and publishable in mixed human/AI engineering work — addressing semantic drift, premature comparison, temporal claim staleness, and causal misuse.

Best whenRaw intelligence is insufficient when work crosses specialist boundaries or AI agents; meaning, claims, evidence, and decisions must be typed, bounded, and d…
Skip ifTreating FPF as a linear textbook (use the entry menu J.4), Using FPF when task is small and feedback is fast
vs seeds
spec-kit/openspec which define workflow phases and commands, FPF defines typed evidence, parity-enforced comparison, R_eff relia…
Primitive shape
No installable primitives
00

Summary

FPF (First Principles Framework) — Summary

FPF is a formal pattern language and core specification for "admissible action in problematic engineering, research, and mixed human/AI work." It is not a coding tool, CLI, or plugin — it is a 71KB structured text specification document (FPF-Spec.md) authored by Anatoly Levenchuk (with AI assistance) that defines reusable patterns (A.1–K.x) for making reasoning explicit, traceable, and shareable across engineering teams, researchers, and mixed human/AI systems. FPF addresses the problem that raw intelligence is insufficient when work is split across specialists, teams, or AI agents — meanings, claims, alternatives, evidence, and boundaries must remain stable across contexts. It defines formal constructs like Characteristic Spaces, Relational Precision Restoration (RPR), Decision Records (DRR), Unified Terminology Sheets (UTS), Temporal Adequacy, and a narrow quantum-like modeling vocabulary. With 372 stars and 64 forks, it is the most intellectually sophisticated framework in this batch. Compared to seeds, FPF differs from all of them: it is the only framework that operates at the epistemological rather than process-management level — it doesn't tell you which commands to run or which files to create, it provides a vocabulary for making reasoning defensible.

01

Overview

FPF (First Principles Framework) — Origin & Philosophy

Origin

Created by Anatoly Levenchuk, a Russian systems engineer and researcher, "with AI-agents assistance." Version: May 2026. Status: "Normative kernel, 'eternal alpha' — already used in working projects and development programmes, while still evolving." 372 stars, 64 forks, 3 contributors. No license specified (all rights reserved implied).

Core Philosophy (verbatim from Readme.md)

"FPF helps when insight is not enough by itself: meanings, claims, alternatives, evidence, boundaries, publication forms, and work decisions must remain stable across contexts, time, people, tools, or AI agents."

"FPF turns raw intelligence into work that is easier to align, review, evolve, publish, and delegate."

"FPF is not: a shrink-wrapped project methodology; a quick-answer cheat sheet; a demand to read the whole specification linearly before doing useful work. It is an amplifier for collaborative engineering thinking in human-only, mixed human/AI, and AI-agent-heavy work."

Core Use Cases (from Readme)

  1. Project alignment — separating responsibility, method, plan, and execution
  2. Partly-said / language-state discovery — preserving emerging ideas before they are fully formed
  3. Boundary unpacking / claim routing — making contract/API/SLA language precise
  4. Admissible comparison / local choice — comparing alternatives honestly
  5. Generator / state-of-the-art portfolio — maintaining a portfolio of novelty and quality-diversity
  6. Publication and rendering — ensuring explanations/summaries don't change what they claim
  7. Temporal claim adequacy — handling time-dependent claims correctly
  8. Causal-use / counterfactual-support repair — preventing correlation-as-causation errors

Key Mathematical/Formal Constructs

  • Characteristic Spaces: declared dimensions + scales over which comparison, measurement, and search operate
  • R_eff (Effective Reliability): a computed score from evidence verdicts (supports/weakens/refutes) + CL penalties + decay
  • RPR (Relational Precision Restoration): A.6 boundary discipline that unpacks contract/API sentences into atomic claims
  • DRR (Decision Rationale Record): E.9 normative format for durable decision documentation
  • UTS (Unified Terminology Sheet): F.17 vocabulary stabilization protocol
  • NQD/OEE (Novelty, Quality, Diversity): open-ended search and portfolio management with descriptor maps
  • Temporal Adequacy (C.27): formal treatment of time windows, effort/resistance, freshness decay
02

Architecture

FPF (First Principles Framework) — Architecture

Distribution

Standalone documentation repository. Two files:

  • Readme.md — high-recall overview + entry points (non-normative)
  • FPF-Spec.md — ~71KB core specification (normative)

No code, no CLI, no install process.

Install

None. This is a specification document, not software.

"Usage" (Reference Model)

FPF is used by reading the spec and applying the pattern language to engineering work. The README provides an "entry menu" — patterns to inspect first depending on the type of problem:

Pattern Entry Points (selection):
- A.1.1, A.15: project alignment
- C.2.2a, C.2.LS: partly-said/language-state discovery
- A.6, A.6.B: boundary unpacking
- A.19:0, A.17-A.19: admissible comparison
- E.17: publication/rendering discipline
- C.27: temporal claim adequacy
- C.28, A.10: causal-use repair

Document Structure (FPF-Spec.md)

Preface (non-normative)
Part A: Core patterns (A.0–A.19) — reasoning, alignment, boundaries, claims
Part B: Engineering justification (B.1–B.5)
Part C: Choice, search, evidence (C.1–C.28)
Part D: Distributed/multi-agent (D.1–D.5)
Part E: Publication forms (E.1–E.19)
Part F: Vocabulary (F.1–F.17)
Part G: Portfolio / NQD / OEE (G.0–G.9)
Part H: [unknown]
Part I: Reading guides (I.2 worked entries)
Part J: Navigation (J.4 compact canonical entry index)
Part K: [unknown]

Target AI Tools

FPF is AI-tool-agnostic. The spec includes "AI-assistant prompt recipes" for using FPF patterns in AI agent workflows. The quint-code/haft framework (also in this batch) explicitly references FPF as an architectural influence — its internal/fpf/ package is named for it.

Required Runtime

None — plain text/markdown.

03

Components

FPF (First Principles Framework) — Components

FPF has no software components. Its components are named patterns, each identified by a hierarchical ID.

Core Pattern Families

Part A — Core Reasoning Patterns

Pattern ID Name / Purpose
A.0 Generator/portfolio scaffold for search, harvest, novelty archive
A.1 Problem framing
A.1.1 Responsibility boundary alignment
A.3, A.3.3 Temporal claims
A.6 Boundary discipline and RPR (Relational Precision Restoration)
A.6.B Boundary claim routing
A.6.C Compliance/SLA boundary unpacking
A.6.P Overloaded quality/action language repair
A.6.T Temporal adequacy in boundary language
A.6.RSIG Description signal identification
A.10 Causal use
A.15 Responsibility/method/plan/execution separation
A.15.2/A.15.3 Alignment worksheets
A.15.4 Publication boundary note
A.16, A.16.1, A.16.2 Partly-said discovery
A.17–A.19 Admissible comparison and local choice
A.19:0, A.19.CN Comparison with declared characteristics + candidate pool

Part B — Engineering Justification

Pattern ID Name / Purpose
B.3 Evidence transport / trust
B.4.1, B.5.1 Starter decision records
B.5.2.0, B.5.2.1 Generator kits

Part C — Choice, Search, Evidence

Pattern ID Name / Purpose
C.2.2a, C.2.LS, C.2.4–C.2.7 Language-state preservation
C.11 Choose now vs probe more
C.16 Trend/delay claims
C.17–C.19 Creative search / explore-exploit policy
C.18, C.19 Selected-set publication
C.24 Call-planning / checkpoint return
C.27 Temporal adequacy (time window, effort, freshness, decay)
C.28 Causal-use / counterfactual repair

Part E — Publication Forms

Pattern ID Name / Purpose
E.1–E.9 Publication, explanation, repair, comparison notes
E.9 (DRR) Decision Rationale Record — durable canon rationale
E.17 Publication and use boundaries (screens, summaries, credentials)
E.19 Pattern writing and review

Part F — Vocabulary

Pattern ID Name / Purpose
F.9 Bridge discipline
F.11 Method/work vocabulary alignment
F.17 (UTS) Unified Terminology Sheet — vocabulary stabilization

Part G — Portfolio / NQD / OEE

Pattern ID Name / Purpose
G.0–G.9 Novelty, quality, diversity portfolio management; descriptor maps; shortlist-ready outputs

Key Formal Constructs (not patterns, but defined entities)

  • Characteristic Space — declared dimensions + scales for comparison
  • R_eff — effective reliability score from evidence verdicts + decay
  • RPR — Relational Precision Restoration (A.6 family)
  • ChoiceResult — output of a local decision record (A.19)
  • WorkCommission — bounded execution authority (referenced in quint-code/haft as implementation)
05

Prompts

FPF (First Principles Framework) — Formal Language & Prompts

Excerpt 1: Boundary Discipline / RPR (from FPF-Spec.md, pattern A.6)

The RPR (Relational Precision Restoration) pattern addresses blurred boundary language in contracts, APIs, and SLAs:

"FPF does not let one contract/API/SLA/protocol sentence carry rules, gates, duties, evidence, quality words, and action permission as one undifferentiated bundle; A.6 and A.6.P restore the exact relation before stronger use."

The A.6 pattern family:

  • A.6.B — routes boundary claims by type (obligation, permission, gate, evidence requirement)
  • A.6.C — compliance/SLA boundary unpacking
  • A.6.P — repairs overloaded quality/action language ("quality words" like "reliable," "fast," "secure" that hide comparison characteristics)
  • A.6.T — temporal adequacy check on boundary language
  • A.6.RSIG — identifies which description signals are present

Technique: Atomic claim decomposition — a single ambiguous sentence is unpacked into separate claims by type (obligation vs gate vs evidence requirement), each routed to the appropriate handling pattern.

Excerpt 2: Characteristic Spaces (from FPF-Spec.md)

"FPF treats comparison, measurement, search, and temporal change as work over declared characteristics and scales, not as loose talk about dimensions or scores."

A Characteristic Space is defined by:

  1. Declared characteristics (named dimensions)
  2. Scales for each characteristic (ordinal, cardinal, boolean, symbolic)
  3. Comparison operators (valid operations given scale type)
  4. Parity enforcement (all alternatives must be characterized on all dimensions before comparison is admissible)

Technique: Formal type system for comparison — prohibits comparison until all dimensions are declared and populated. Analogous to type-checking for decisions.

Excerpt 3: R_eff Formula (from FPF-Spec.md, pattern B.3 / evidence transport)

The framework defines R_eff (Effective Reliability):

R_eff = f(evidence verdicts, CL penalties, temporal decay)

Verdict vocabulary:
- supports    (alias: accepted)   → positive contribution to R_eff
- weakens     (alias: partial)    → attenuated contribution
- refutes     (alias: failed)     → negative/zero contribution
- superseded  → excluded from R_eff computation

Technique: Evidence accounting — formal ledger of evidence verdicts with decay over time. This is analogous to a credit score for claims, where each piece of evidence has a typed verdict and an expiry.

Excerpt 4: Temporal Adequacy (from FPF-Spec.md, pattern C.27)

"C.27 handles claims whose usability depends on window, rhythm, inertia/resistance, freshness, effort, and intervention-sensitive change rather than treating time as background decoration."

Temporal adequacy check requires specifying:

  • Live time window (how long is the claim valid?)
  • Effort/resistance relation (how hard is it to act within the window?)
  • Update rhythm (how often must the claim be refreshed?)
  • What must be rechecked before use

Technique: Temporal claim typing — claims are not timeless but carry expiry metadata. A claim without temporal adequacy metadata cannot be used in engineering decisions.

Prompting Techniques Summary

  1. Atomic claim decomposition (A.6/RPR)
  2. Formal type system for comparison (Characteristic Spaces)
  3. Evidence accounting with decay (R_eff / B.3)
  4. Temporal claim typing (C.27)
  5. Pattern-as-entry-point (hierarchical navigation by problem type, not linear reading)
09

Uniqueness

FPF (First Principles Framework) — Uniqueness & Positioning

differs_from_seeds

FPF differs from all 11 seeds and all batch peers: it is the only framework that operates at the epistemological layer rather than the process-management layer. Where every seed (superpowers, spec-kit, openspec, BMAD, etc.) defines workflows, commands, and artifacts for software development, FPF defines a vocabulary for making reasoning itself explicit, traceable, and publishable. The closest seed would be agent-os (both are methodology documents without CLIs), but agent-os provides CLAUDE.md templates for daily development while FPF provides formal pattern language for decisions, evidence, and claims in any engineering context. FPF is closer in spirit to academic work on formal methods than to any of the practical SDD frameworks in this corpus.

Unique Positioning

FPF is the only framework in this batch that:

  1. Defines a formal vocabulary for evidence quality (R_eff with verdicts + decay)
  2. Requires "parity enforcement" before comparisons are "admissible"
  3. Distinguishes temporal claim types by window/rhythm/resistance
  4. Has a separate implementing framework (quint-code/haft) that builds the software runtime for FPF concepts
  5. Contains no code whatsoever — just a structured pattern language

Observable Failure Modes

  1. High entry barrier: the README itself admits FPF "may be too heavy when the task is small, vocabulary is already stable, feedback is fast and cheap."
  2. No license: the repository has no license file; unknown rights situation.
  3. Single author: 3 contributors but Levenchuk is the primary author; evolution depends on one person.
  4. Eternal alpha: explicitly described as "eternal alpha" — stable enough to use but never fully frozen.
  5. Conceptual density: the pattern language has 100+ named patterns across 11 parts; onboarding time is measured in days, not minutes.
  6. Russian language academic tradition: some background concepts may be harder to follow for readers unfamiliar with Russian systems thinking schools (Schedrovitsky methodology, activity theory).

Explicit Antipatterns (from Readme)

  • Treating FPF as a linear textbook (it is an entry menu)
  • Using FPF when the task is small and vocabulary is already stable
  • Treating the README as the canonical entry (use J.4)
  • "Premature convergence on a single option" in comparison work
04

Workflow

FPF (First Principles Framework) — Workflow

FPF does not prescribe a fixed workflow. It is an entry menu, not a pipeline. The README explicitly states: "Use this repository as an entry menu, not as one universal starter trunk."

General Problem Resolution Flow

Identify type of problem (alignment? boundary? choice? publication?)
    ↓
Choose entry point from J.4 index
    ↓
Inspect the first 1-3 patterns named for that entry
    ↓
Apply pattern to produce a stabilizing artifact
    ↓
(Optional) Publish: select appropriate publication form (E.1–E.19)

Example Workflow: Admissible Decision (from README)

A vague project question: "Should we buy, fine-tune, or build an agent stack?"

With FPF:
1. Problem framing (A.1)
2. Bounded contexts: product / infrastructure / safety / evaluation
3. Decision criteria: cost / latency / controllability / risk / time-to-value (A.17–A.19)
4. Portfolio of alternatives: buy / fine-tune / build / hybrid
5. Evidence and test gaps (B.3)
6. Starter DRR when rationale must be published (E.9)
7. Starter UTS when vocabulary must be stabilized (F.17)
8. Aligned outputs for engineering / management / research / assurance (E.17)

Phase-to-Artifact Map

Activity Pattern Artifact
Alignment A.1.1, A.15 alignment frame, responsibility separation note
Vocabulary stabilization F.17 (UTS) Unified Terminology Sheet
Boundary unpacking A.6, A.6.B Claim Register, routed atomic claim set
Comparison A.17–A.19 ChoiceResult, comparison frame with declared characteristics
Decision rationale E.9 (DRR) Decision Rationale Record
Publication E.17 publication/use-boundary note
Temporal adequacy C.27 temporal adequacy note
Evidence transport B.3 engineering justification record

Approval Gates

FPF does not define approval gates in the process-management sense. However, the A.19 family (admissible comparison / local choice) defines explicit "stop conditions" before a choice can be made: all declared comparison characteristics must be populated, parity must hold across alternatives, and evidence must be present for each criterion.

06

Memory Context

FPF (First Principles Framework) — Memory & Context

State Storage

None — FPF is a reference specification, not a software system. It has no runtime state.

However: FPF Defines Multiple Persistent Artifact Types

When FPF is applied, the artifacts it prescribes are the memory layer:

Artifact Pattern Storage form
Alignment Frame A.1.1, A.15 Document (MD, structured text)
Claim Register A.6.B Tabular document
ChoiceResult A.19 Structured decision record
DRR (Decision Rationale Record) E.9 Normative document
UTS (Unified Terminology Sheet) F.17 Glossary document
Temporal Adequacy Note C.27 Annotated claim document
R_eff Evidence Ledger B.3 Evidence ledger with verdicts + timestamps

Cross-Session Handoff

Designed for it. The core motivation of FPF is that reasoning must remain "stable across contexts, time, people, tools, or AI agents." All artifacts are designed to be publishable and readable by any party at any time.

The quint-code/haft implementation

The framework at m0n0x41d/quint-code (also in this batch) implements FPF's artifact types as SQLite tables and markdown projections:

  • .haft/*.md files are derived projections of FPF artifacts
  • internal/fpf/ package implements FPF pattern computations
  • R_eff is computed from evidence verdicts stored in the database

This makes FPF the only framework in this batch that has a separate runtime implementation by another author.

07

Orchestration

FPF (First Principles Framework) — Orchestration

Multi-Agent

FPF addresses multi-agent coordination conceptually (Part D covers distributed/multi-agent patterns) but does not ship software for it.

Orchestration Pattern

Not applicable at the FPF level. FPF defines patterns for reasoning about work assignment, boundary drawing, and decision authority — which are the inputs to orchestration decisions — but not orchestration mechanisms themselves.

Execution Mode

Not applicable. FPF is a reference specification.

Isolation Mechanism

Not applicable.

Multi-Model

Not applicable. FPF is model-agnostic.

Consensus Mechanism

FPF defines formal prerequisites for "admissible comparison" (A.17–A.19), which can be thought of as a consensus-readiness check: a comparison is not admissible until all declared characteristics are populated for all alternatives and parity holds. This is a conceptual consensus protocol, not a software implementation.

Formal Constructs Relevant to Orchestration

WorkCommission

FPF defines WorkCommission as "bounded execution authority between a DecisionRecord and a runtime run" (referenced in spec, implemented in quint-code/haft). A WorkCommission:

  • Has explicit scope from a parent DecisionRecord
  • Carries invariants and claims as guardrails
  • Has lifecycle: created → claimed → executing → complete/failed

Decision Boundary (from AGENT_CONTRACT.md in quint-code)

"Agent may frame, explore, compare, and recommend when delegated. Agent must stop at Choose → Execute boundary and wait for human confirmation."

This is the core FPF principle on agent autonomy: agents can apply all reasoning patterns up to the moment of choice, but the choice itself requires human authorization.

Auto-Validators

None in the FPF spec itself. R_eff provides a formal framework for evidence quality assessment that could be implemented as an automated validator.

08

Ui Cli Surface

FPF (First Principles Framework) — UI & CLI Surface

CLI Binary

None. FPF ships no software.

Local UI

None.

Distribution Surface

Two markdown files in a GitHub repository:

  • Readme.md — entry navigation guide
  • FPF-Spec.md — ~71KB normative specification

Human Interface

Reading and applying the pattern language. The README provides:

  • Entry points organized by problem type (project alignment, boundary unpacking, admissible comparison, etc.)
  • Worked examples as prose narratives
  • Navigation via pattern IDs (A.1, B.3, C.27, E.9, etc.)

AI Integration

FPF includes "AI-assistant prompt recipes" within the spec for applying FPF patterns in AI agent workflows. No formal MCP integration or plugin format.

Primary Consumer: quint-code/haft

The quint-code/haft framework in this batch implements FPF programmatically:

  • haft_problem — MCP tool implementing FPF problem framing
  • haft_solution — implements FPF exploration with diversity checks
  • haft_decision — implements FPF decision contract with invariants and evidence
  • internal/fpf/ — Go package computing FPF quantities (R_eff, Pareto front, etc.)
  • .haft/*.md — markdown projections of FPF artifacts

Observability

None at the FPF level. The quint-code/haft implementation provides observability via its CLI (haft check, haft spec check, etc.).

Related frameworks

same archetype · same primary tool · same memory type

Context-Engineering Handbook ★ 9.0k

Provides a first-principles, research-grounded vocabulary and learning path for context engineering — the discipline of designing…

walkinglabs/learn-harness-engineering ★ 6.6k

Teach harness engineering from first principles (12 lectures + 6 projects) and provide a scaffolding skill (harness-creator) that…

Awesome Harness Engineering (walkinglabs) ★ 2.7k

Curate the authoritative reference list of articles, benchmarks, and tools for harness engineering — the practice of shaping the…

cline-memory-bank (nickbaumann98) ★ 581

Custom instructions + 6-file hierarchical Markdown memory bank so Cline maintains full project context across sessions, with a…

nexu-io/harness-engineering-guide ★ 134

Provide a practical, code-first reference guide to harness engineering — from first principles to production patterns —…

knowhub ★ 40

Synchronize AI coding-agent knowledge files (rules, guidelines, templates) from a central source to multiple AI-tool-specific…