📐 Axioma

The Spec-Driven Development Framework for AI Agents. Rigor over speed. Engineering over impulsivity.

Axioma is an architectural framework and methodology designed to transform AI agents into rigorous software engineers. It is built on the premise that ambiguity is a system failure and the Specification (Spec) is the only non-negotiable source of truth.

---

💥 Why Axioma?

If you've iterated on a project using Vibe Coding, you've probably experienced this: you ask an AI agent to add a new feature, and it silently modifies or breaks features that were already working. The agent has no memory of the system's contracts — it sees code and charges forward.

That is the problem Axioma was built to solve.

With Axioma, you don't talk to code — you talk to specifications. In natural language. Your system's behavior is defined in .spec.md files, and you evolve them through a controlled pipeline where:

• ✅ Each change is scoped to explicit file boundaries (context_bounds).
• ✅ Every feature has acceptance criteria validated by tests before implementation.
• ✅ An antagonistic auditor (The Censor) rejects vague or overreaching changes.
• ✅ If implementation fails, the system rolls back automatically.

Axioma is the first step toward a future where complex systems are built by chatting with their specs — safely, incrementally, and without regressions.

---

🌟 The Vision: Code Slaves vs. Software Engineers

AI-assisted development today suffers from "hyper-activity":

• ❌ Current State (Agents as Code Slaves): Agents write code before fully understanding the problem, leading to technical debt, hallucinations, and regressions.
• ✅ Axioma (Agents as Software Engineers): Enforces an engineering workflow based on contracts and the 🟢🔴🟢 cycle (TDD for Agents). No single line of code is allowed to be written without prior validation of logic, scope, and testability.

---

🔄 The Axiomatic Flow: Vibe Coding meets Autonomy

Axioma bridges the gap between conversational brainstorming ("Vibe Coding") and strict software engineering ("Fire and Forget"). It executes a strict trust protocol mediated by specialized agents and divided by a critical Human Approval Boundary:

graph TD
    User([Petición del Usuario]) --> A
    
    subgraph "Fase 1: Vibe Coding (Chatbot Interactivo)"
    A[The Archivist] -- MCP --> Repo[(Repositorio)]
    A -.->|Aclarar Ambigüedad| User
    A --> B[The Blueprint]
    B --> Spec[.spec.md / Ledger]
    B -.->|Refinar Diseño| User
    end
    
    Spec ===>|Frontera de Aprobación Humana| C
    
    subgraph "Fase 2: Fire and Forget (Flujo Autónomo)"
    C{The Censor} -->|Veto| A
    C -->|Aprobado| J[The Justice]
    J --> Tests((Tests))
    Tests -->|Debe Fallar 🔴| M
    M[The Mason] --> Src{src/}
    Src -->|Tests Pasan 🟢| Done([Código Desplegable])
    Src -->|Tests Fallan 🔴| M
    end

Loading

🎭 The Cast: Specialized Agents

Axioma operates through a hierarchy of agents with non-negotiable roles and honors:

🗣️ The Chatbot / Design Agents (Phase 1):

1. The Archivist (The Context Guardian): Reduces uncertainty to zero. Interviews the user, analyzes the repository via MCP, and detects dependencies. It doesn't assume; it asks.
2. The Blueprint (The Architect): Translates intent into a structured .spec.md file and defines the fixtures (synthetic data).

🤖 The Autonomous Builders (Phase 2): 3. The Censor (The Auditor): Holds veto power. Rejects the Spec if it is ambiguous, if the scope is too large, or if it breaks system invariants. 4. The Justice (The Judge): Creates the tests and ensures they fail (Red Step) before allowing any implementation. It is the guarantor of truth. 5. The Mason (The Builder): The artisan who implements the minimum code necessary to satisfy The Justice.

---

🛠️ Technical Stack

Axioma is designed to be agnostic but powered by a high-performance core:

• Engine: Google Gen AI SDK (Gemini 2.0+).
• Capability: Native Model Context Protocol (MCP) support to safely interact with Filesystem, Git, and Runtime.
• Safety: State control via a Ledger injected into the Spec itself for total traceability.

---

📂 Project Structure

Project structure overview:

/your-project
├── .axioma/
│   └── prompts/       # Customizable Agent System Prompts
├── docs/specs/        # Source of Truth (.spec.md)
├── docs/fixtures/     # Synthetic data linked to specs
└── src/               # Implemented and validated code

---

📚 Deep Dive (Architecture)

If you want to understand the rigorous mechanics behind Axioma, read our core architectural documents:

1. The Manifest Standard & Ledger: Why .spec.md is the only source of truth.
2. The Cast of Agents: Deep dive into the invariants of each specialized agent.
3. MCP Integration & Security: How we isolate access to prevent system destruction.
4. The Red-Green-Refactor Loop: The mandatory TDD flow and automatic git rollback.

---

🤝 Join the Discussion (RFC)

Axioma is currently an RFC (Request For Comments). We are not just looking for code; we are looking for critical thinking and visionaries.

Who are we looking for?

• Software Architects to help define the .spec.md Manifest Standard.
• Prompt Engineers to calibrate The Censor and its veto criteria.
• MCP Developers to build secure write-access servers.

Do you believe in a future where AI writes industrial-grade code? Help us define the standard.

👉 Jump to GitHub Discussions to participate.

---

📄 License

This project is licensed under the Apache License 2.0.