manifesto.md

Specificationv0.1Agentic Stack

12-Factor AI-enabled CLI (12fc)

claimed by its maintainer

Twelve testable factors for a command-line tool whose operator may be a human or an AI agent, from machine-readable capabilities to meaningful exit codes, with a conformance gate.

Canonical text: https://github.com/hop-top/spec-12fc/blob/main/specs/v0.1/spec.md, read against version 0.1.

The twelve factors

  1. Capability introspection. The CLI exposes its capabilities in a machine-readable format.
  2. Intent clarity. Commands express intent, not syntax.
  3. Structured I/O. Machine-readable output with a stable schema, strict channel discipline.
  4. Corrective error model. Errors carry a stable code, the failing input, a transience class and a suggested fix.
  5. Explicit contracts. Idempotency, side effects, retry semantics, schema versioning and partial failure are declared.
  6. Previewability. Every mutating operation can be previewed; nothing blocks on a prompt without a TTY.
  7. Idempotency by default, or declared otherwise with a safe retry strategy.
  8. State transparency. All implicit state is inspectable.
  9. Contextual guidance. Help that answers the situation, not the flag list.
  10. Delegation safety. Scoped permissions, confirmation policies, sandboxing, rate limits, policy enforcement.
  11. Exit code semantics. Zero means success, never a swallowed error; failure classes are distinguishable.
  12. Evolution guarantees. Changes announce themselves; renaming an error code is a breaking change.

Facts

Maintainer
hop.top, published by Idea Crafters
Repository
https://github.com/hop-top/spec-12fc
First published
2026-04
Status of the text
draft
Listing
claimed by the maintainer, 2026-10-25

Read with

Badge

manifesto.md: claimed

[![manifesto.md](https://img.shields.io/endpoint?url=https://manifesto.md/badge/12fc.json)](https://manifesto.md/12fc/)