English | Português (Brasil)
Keep intent, decisions, code, and evidence connected.
Axiom is a development control plane for keeping software intent, architecture, implementation, validation, and operational evidence connected across human and AI work.
- Intent gets lost. Specifications preserve outcomes, constraints, and acceptance criteria before implementation.
- Context fragments. A Project can relate independent repositories without treating any one repository as the whole project.
- Decisions drift from code. Plans and architecture decisions give humans and agents durable references.
- Completion claims lack proof. Validation and Evidence make results inspectable and reproducible.
Spec-Driven Development connects the reason for a change to its implementation and acceptance evidence.
flowchart LR
I["Intent"] --> S["Specification"]
S --> P["Decisions<br/>and Plan"]
P --> X["Implementation"]
X --> V["Validation<br/>and Review"]
V --> E["Evidence<br/>and Reconciliation"]
E -. informs next intent .-> I
Implementation proceeds through bounded Executions. Human approval gates material choices. Evidence supports review and acceptance without replacing human judgment.
Axiom is under active development. This repository currently provides:
- a Codex-first harness with policies, skills, templates, and deterministic validation;
- a tested Go implementation of Project rules, portable and machine-local state, Codex Runtime installation, GitHub Work Items, and a bounded persistent Lingo workflow;
- canonical completion and provenance contracts, bounded detail artifacts, and fail-closed local publication and recovery foundations;
- versioned Specifications, architecture decisions, and implementation Evidence.
Current limitations include one supported Runtime (Codex), one Work Item provider (GitHub Issues), and a sequential single-agent workflow. The roadmap describes direction. The Specifications index owns detailed scope, approval, implementation, and acceptance state.
Requirements: Git, Bash, standard POSIX utilities, and Go 1.26 or later. The
first Go command may download the dependency pinned in go.mod.
git clone https://github.com/rgomids/axiom.git
cd axiom
./scripts/install-axiom.sh
export PATH="$HOME/.local/bin:$PATH"
lingo version
lingo first-run
lingo runtime codex install
./scripts/validate-repository.sh .
go test ./...The installer never edits shell profiles. Use the Getting Started guide for setup and the command reference for validation, build, archive, and dogfooding workflows.
| Concept | Meaning |
|---|---|
| Project | A logical project boundary, distinct from a Repository, that may associate multiple independent repositories. |
| Specification | Desired behavior, constraints, non-goals, and acceptance evidence. |
| Architecture / ADR | System boundaries and durable decisions with rationale and trade-offs. |
| Execution | A bounded attempt under known intent and approvals. |
| Evidence | An inspectable observation supporting a claim, such as a test, command result, diff, or review. |
| Authority | Explicit permission and approval boundaries; a proposal does not grant authority. |
| Agent / Runtime | An Agent participates in work; a Runtime supplies its execution environment and capabilities. |
| Lingo | Axiom's local executable control plane. |
Axiom separates product intent and domain rules from execution tools and external providers. Lingo conducts local workflows while Runtime and Provider adapters remain at the boundary.
flowchart TB
H["Humans"] -->|intent and approvals| A["Axiom"]
R["Codex Runtime / Agent"] -->|thin skills| L["Lingo"]
L -->|application workflow| A
A -->|project associations| G["Independent Repositories"]
L -->|bounded adapter| P["GitHub Issues"]
See the architecture overview, conceptual model, and provider boundaries.
| Topic | Start here |
|---|---|
| Product | Product Foundation · Roadmap |
| Governance | Documentation governance · Constitution |
| Architecture | Architecture overview · ADRs |
| Delivery | Specifications and Evidence |
| Research | Research index |
| Development | Getting Started · Commands |
| Community | Contributing · Code of Conduct · Support |
| Security | Security policy · Repository security |
| History | Changelog |
Notion discovery provides product discovery and research context. Versioned repository artifacts own technical contracts, decisions, and implementation evidence. Discovery does not imply approval.
.agents/ Codex harness: context, policies, skills, and templates
docs/ Product, architecture, specifications, decisions, and research
internal/ Go implementation and tests
scripts/ Repository, security, release, and validation tooling
Read CONTRIBUTING.md and the Code of Conduct. Use the repository's Issue forms and Pull Request template, follow approved scope, keep changes small, include reproducible validation, and reconcile affected documentation. Material changes require explicit human approval.
Report suspected vulnerabilities privately through SECURITY.md.
Axiom is licensed under the Apache License 2.0. See LICENSE.