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.
Its MVP centers on one journey: configure a Project and its workflow, then deliver a Work Item through bounded Codex and Claude agents running on your locally authenticated CLIs. Axiom owns workflow state, authority, agent coordination and Evidence; you review the delivery and explicitly accept it or send it back for rework.
- 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.
Using Axiom needs no clone, Go toolchain, or build.
Install the latest stable release on Linux or macOS:
curl -fsSL https://raw.githubusercontent.com/rgomids/axiom/main/scripts/install.sh | shSupported hosts: macOS arm64 and Linux amd64/arm64.
For prerequisites, platforms, PATH, upgrades, and diagnostics, see the installation guide.
axiom version
axiom helpaxiom first-runThis configures Axiom's global skills for Codex and Claude found on PATH.
It does not install Runtimes or sign you in. With no Runtime it succeeds;
install one separately and rerun when needed.
Configure a Project, inspect it, create a Work Item, and start its workflow:
axiom project configure
axiom project list
axiom project show --selector my-project
axiom work-item create --project my-project --repository main \
--provider-repository owner/repository
axiom workflow start --project my-project --repository main --number 123
axiom workflow status --project my-project --repository main --number 123Replace my-project, main, owner/repository, and 123 with your
configured values and the created Issue number. Configure the GitHub provider
in the Project; Work Item operations require an authenticated
GitHub CLI. Guided configuration and creation show a
preview and ask for confirmation before writing.
You can also invoke four skills: axiom-project selects the workflow,
axiom-workflow configures its definitions, and axiom-work-item runs and plans
Work Items; axiom-runtime manages local bindings and Profiles. Use $<skill-name> in Codex or /<skill-name> in Claude. See skills and Runtimes
and the command reference for details.
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.
Each Project selects the workflow it follows: the default SDD workflow or a
validated custom revision with its own stages, agents, Runtime choices and human
gates. Every Execution stays pinned to the revision it started with, so editing
a workflow never changes work in progress or history. Definition authoring and
explicit selection are available through axiom project workflow; see the
authoring commands.
Configurable Execution binding and dispatch remain in delivery; today the
execution surface runs the fixed, bounded sequential workflow.
Axiom is under active development. Published availability and human acceptance are separate decisions.
- Latest stable release: GitHub Releases. The installer resolves it automatically; the Changelog lists what each version adds.
- Available today / stable: checksum-verified Linux and macOS distribution; guided Project configuration, listing, and resolution; GitHub Work Item creation and classification; Codex/Claude bootstrap; persistent workflow, Evidence, recovery, and owned-install upgrades. This includes foundations for multi-runtime and bounded multi-agent execution with an Execution Graph; S8 Evidence records scope and limitations without establishing full MVP human acceptance.
- MVP in delivery: configurable Project workflows (default SDD or validated custom revisions); stage-specific agents with per-agent Runtime, Model Profile and reasoning effort; Executions pinned to a workflow revision; public Codex/Claude orchestration with structured coordination from either Runtime; and one reviewed delivery with explicit acceptance or rework. Tracked by Epic #15 under the accepted Specification 007. None of it is available until delivered and accepted.
- Beyond the MVP: a graphical control plane, cloud or multi-machine orchestration, an arbitrary Runtime ecosystem, and token/cost budget governance require their own specification and authority.
See Changelog, Specifications, and Roadmap for history, Evidence, acceptance, and direction.
| 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 / Claude 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 |
|---|---|
| Using Axiom | Getting Started · Installation · Command reference |
| Product | Product Foundation · Roadmap |
| Governance | Documentation governance · Constitution |
| Architecture | Architecture overview · ADRs |
| Delivery | Specifications and Evidence |
| Research | Research index |
| Development | Developing Axiom · Development setup · Commands · Development and release flow |
| Community | Contributing · Code of Conduct · Support |
| Security | Security policy · Repository security |
| History | Changelog |
Notion is the home of product and system documentation, concepts, and user-oriented navigation; the former GitHub Wiki is retired. Versioned repository artifacts own technical contracts, decisions, implementation evidence, and references that must evolve with code. Discovery does not imply approval.
To work on Axiom itself: Git, Bash, standard POSIX utilities, and Go 1.26+.
git clone https://github.com/rgomids/axiom.git
cd axiom
./scripts/install-axiom.sh
./scripts/validate-repository.sh .
go test ./...The script installs a development build from the checkout. See development setup and the command reference for build and dogfooding details.
Explore the Axiom website.
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.