What are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?
| Rating | Summary | |
|---|---|---|
| Quality | weak (11/24) | Massive adoption and strong engineering signals are undercut by no releases, an 8-month commit gap, no license, and a README that navigates rather than teaches. |
| PAI Relevance | study (0.63) | Factor 12 (stateless reducer) and Factor 3 (own your context window) map directly onto PAI's Algorithm loop and context subsystem architecture — worth deep study, not installation. |
11/24 — dormant-or-abandoned / under-documented / solid
Failed:
Passed:
Failed:
npx/uvx create-12-factor-agent CLI is referenced only as a community discussion thread, not a working commandPassed:
Failed:
Passed:
| Dimension | Score | Assessment |
|---|---|---|
| Harvest Value | 2 | Factor 12 (stateless reducer) maps directly onto PAI's Algorithm 7-phase execution loop design; Factor 3 (own your context window) is directly applicable to PAI's file-based memory and context-building patterns across WORK/, LEARNING/, and KNOWLEDGE/. |
| Integration Readiness | 1 | TypeScript aligns with PAI's stack but this repo is a documentation guide, not a bun-installable package; the planned create-12-factor-agent CLI scaffolding does not yet exist, so integration requires manually extracting and applying patterns rather than importing code. |
| Overlap Risk | 1 | Partial overlap with PAI's Loop skill (iterative agent cycles), Agents orchestration subsystem, and the Algorithm's observe-verify-learn structure — the principles mirror PAI's existing design without being redundant. |
| Gap Fill | 1 | PAI has no codified architectural principles document; the 12-factor vocabulary (stateless reducer, compact errors into context, unify execution and business state) would formalize implicit design decisions currently embedded across 46 hooks and 27 agents without a central reference. |
Composite: 0.63
Capture-to-Knowledge Pipeline design phase: Read Factor 3 (Own Your Context Window) at 12-factor-agents.com and draft an explicit context schema for each Haiku validation call — listing exactly what gets included, in what order, and what gets excluded. The outcome is that each pipeline stage has a documented context contract rather than an implicit one, making the "clean-room" validation reproducible and diagnosable when Haiku produces unexpected output.
Capture-to-Knowledge Pipeline's manual validation step: Read the stateless reducer factor (agents as pure functions over event logs) and redesign the validation stage as a (state, event) => newState shape rather than a mutable session. This makes each validation run replayable from its event log — drop-in replacement for manual re-checking without re-running the full capture chain.
Fabric Recommender's LLM call structure: Read the human-in-the-loop tool call factor, which articulates when to pause for approval versus when to proceed automatically. Apply the decision criteria it describes to fab's current flow: identify which pattern recommendations warrant a confirmation prompt before acting and which are safe to execute silently. The outcome is a deliberate approval boundary rather than a binary "always ask / never ask" default.
Category: AI Agent Frameworks
In this category: VoltAgent--voltagent (excellent, integrate)
Standing: 12-factor-agents is the conceptual reference layer — a principles guide — while VoltAgent--voltagent is the runnable platform; they occupy complementary positions and neither obsoletes the other.
Density: 6/10 — README (first 8KB) available; star/fork/issue counts available; creation and last-commit dates available; language confirmed; dependency manifest not available; CI configuration not available; individual factor content files not available; release history absent
The 8-month commit gap (last commit Sep 2025, appraisal May 2026) is notable given this repo's trajectory — either the guide is considered complete, or it has quietly stalled. The lack of any formal license (NOASSERTION) creates an ambiguity for any derivative work or create-12-factor-agent CLI built on top of it, despite the README badges citing Apache 2.0 for code and CC BY-SA 4.0 for content. The principles themselves — particularly Factors 3, 6, 7, 8, and 12 — are worth studying as a design vocabulary independent of whether the repo is actively maintained.