AXIOM

Open source · Under active development

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.

View on GitHub Explore Documentation
  • Specification before code
  • Human approval on every material decision
  • Evidence you can reproduce, not just read

What it is

Rationale that survives the handoff

AI agents help write code, but the reasoning behind it often stays in prompts, chats, and disconnected documents. Axiom defines the domain, policies, and workflows that keep those connections — exercised in this repository through Codex and Claude harnesses and a Go implementation.

  • 01

    Intent gets lost

    Specifications

    Outcomes, constraints, and acceptance criteria are recorded before code is written.

  • 02

    Context fragments

    Projects

    A Project relates independent repositories without treating any single one as the whole.

  • 03

    Decisions drift

    Plans & ADRs

    Plans and architecture decisions become durable references for humans and agents alike.

  • 04

    Completion lacks proof

    Evidence

    Validation and Evidence make results inspectable and reproducible, not merely asserted.

Spec-Driven Development. The reason for a change stays connected to its implementation and its acceptance evidence.

How it works

One lifecycle, for people and for agents

Each step produces the context the next step consumes.

Intent → Orchestration → Delivery
  • Request & goalIntent • specification
  • ArchitectureDecisions • plan
  • Context & codeRepositories • documentation
Development control plane
  • CodeImplementation • tests
  • ReportValidation • evidence
  • FeatureDelivered for review
Specify Plan Execute Validate
  1. 01

    Specify

    Intent becomes a Specification with outcomes, constraints, and acceptance criteria, before any code.

  2. 02

    Plan

    Decisions and the plan are recorded; architecture choices with lasting impact become ADRs.

  3. 03

    Execute

    Implementation runs in bounded Executions on Codex or Claude, and material choices wait for human approval.

  4. 04

    Validate

    Validation and review produce Evidence and reconcile the docs. Acceptance remains a human decision.

Today Axiom runs one fixed, bounded sequential workflow. The MVP in delivery makes the workflow configurable per Project and coordinates bounded Codex and Claude agents under Axiom-owned state, authority, and Evidence.

Installer

Install from the terminal

The commands from the Getting Started guide, from install to your first workflow.

# macOS or Linux: install the latest stable release

curl -fsSL https://raw.githubusercontent.com/rgomids/axiom/main/scripts/install.sh | sh

# verify the installation

axiom version
axiom help

# install or upgrade user-global skills

axiom first-run

# relate repositories to one Project

axiom project configure
axiom project show --selector my-project

# create a Work Item as a GitHub Issue

axiom work-item create --project my-project --repository main --provider-repository owner/repository

# run the bounded workflow for Issue #123

axiom workflow start --project my-project --repository main --number 123
axiom workflow status --project my-project --repository main --number 123

Supported hosts: macOS arm64 and Linux amd64/arm64. Numeric OS versions are not installation filters. Full Getting Started guide.

Getting started

From install to your first workflow

Using Axiom needs no clone, Go toolchain, or build.

  1. 01

    Install

    The installer verifies the SHA-256 checksum before extracting and installs axiom into $HOME/.local/bin, without sudo.

  2. 02

    Verify

    axiom version reports the installed version and revision.

  3. 03

    First run

    axiom first-run finds Codex and Claude on your PATH and installs Axiom's skills for each. It never installs a Runtime or touches credentials.

  4. 04

    Configure a Project

    Guided: it previews the exact change and writes nothing until you answer yes.

  5. 05

    Run the workflow

    Create a Work Item as a GitHub Issue, then start and inspect its bounded workflow.

Runtime skills

axiom-project

Configure, list, show, validate, archive or reactivate a Project, and manage its Integrations.

Every change shows a read-only preview first and writes nothing until you approve that exact preview; it never infers a Project from the current directory.

Invoke it in Codex as $axiom-project or in Claude as /axiom-project. For example, from the terminal:

axiom project configure
Click a skill to see what it does. Codex and Claude Runtimes call the same CLI through skills, one per domain.

Foundation & discovery

A solid foundation — and room to evolve

Axiom already connects intent, execution, and evidence in a controlled flow. The MVP in delivery makes that flow configurable and coordinated across agents; what comes after is explored through discovery before it becomes a product commitment.

Available foundation

What Axiom already provides.

  • Local, deterministic control plane

    Axiom governs the workflow while agents act within explicit limits;

  • Projects independent of Repositories

    Organise a product's context without confusing the logical project with source code;

  • Intent-driven workflow

    Connecting Specification, decisions, planning, implementation, validation, and Evidence;

  • Agent runtime integration

    Skills and adapters that keep the process rules inside Axiom;

  • Work Items in the development flow

    Preserving traceability between request, execution, and result;

  • Evidence and provenance as part of delivery

    Review what happened without relying only on the agent's claim;

  • Local installation and state

    Keeping configuration, execution, and control close to the operator's environment.

MVP in delivery

Specified and accepted as MVP scope; not available yet.

  • Configurable Project workflows

    Select the default SDD workflow or author and validate a custom revision, with stages, inputs, outputs, criteria, validators, and human gates;

  • Per-stage agents and controls

    Define each stage's agents, dependencies, and parallelism, with Runtime, Model Profile, and reasoning effort per agent;

  • Revisions pinned per Execution

    Each Execution keeps the revision it started with; evolving the workflow never changes work in progress or history;

  • Coordinated Codex and Claude delivery

    Start from the CLI or a skill in either Runtime and run bounded agents on locally authenticated CLIs, with structured questions, blockers, and results;

  • Reviewed delivery, acceptance, and rework

    Inspect one delivery packet, authorize the PR separately, and explicitly accept it or reject it for bounded rework.

Evolutions in discovery

Hypotheses under research, not promised features.

  • Dynamic Runtime and model routing

    Switch agents, Runtimes, and models during execution by cost, budget, availability, and policy, beyond the choices pinned in the workflow;

  • QA as a first-class capability

    Run specialised validation — functional, integration, security, accessibility, and UI automation tests — with structured Evidence;

  • Graphical control plane

    Follow Projects, Work Items, Executions, agents, gates, Evidence, failures, and many active jobs through a visual interface;

  • Isolated workspaces for parallel executions

    Explore Git worktrees so several agents can work at once without sharing the same working directory;

  • Secrets and operator identity

    Manage credentials securely, with protected storage, authentication, auditing, and access control;

  • Specialised probabilistic decisions

    Explore mechanisms such as Jev/System One for routing, agent selection, classification, and confidence-based gates, without replacing deterministic rules;

  • Documentation for humans and agents

    Evolve the public documentation into a Git-native experience, navigable by people and efficient for AI agents to consume.

Discovery is not a commitment to implement. Future capabilities are researched, tried, and validated before they are promoted to Specifications and versioned decisions.

Read the specs. Run the checks

Everything Axiom claims is versioned in the repository, next to the Evidence that proves it.

View on GitHub Explore Documentation