AXIOM: A Local-First Workflow Layer for Coding Agents

AXIOM is a deterministic CLI tool built around task files, providing a local-first workflow layer for coding agents. It addresses challenges faced in the development of AI coding assistants, such as workflow management, task traceability, and output quality assurance. Its core design principles are local-first and deterministic execution, supporting git worktree isolation, stage artifact persistence, mandatory validation and review gates, and a transparent release model based on GitHub Releases. It aims to enhance the capabilities of human developers rather than replace their judgment.

With the rapid development of AI coding assistants and agents, development teams face new challenges such as workflow management, task traceability, and output quality assurance. AXIOM proposes a "local-first" solution that does not rely on cloud connections or specific model providers, building a reliable workflow layer through local files and deterministic CLI. Its core idea is to save workflow states in the local file system, bringing portability (migration across agent hosts), auditability (files record all state decisions), and offline availability (execution without network). AXIOM differs from traditional prompt packages or large autonomous IDEs; it is not a collection of preset prompts or an all-in-one IDE, but a deterministic workflow engine centered on task files, whose responsibility is to enforce workflow discipline.

AXIOM creates a Markdown-format task file for each task, stored in the .axiom/tasks/ directory, serving as the source of truth for work and recording the complete lifecycle of the task (creation, design, planning, execution, validation, review). The task lifecycle is managed via CLI commands: make to create a task, run to execute specific stages (design/plan/execute/verify/review), finish to complete a task, list to view the task list, show to display details, and diff to view change comparisons. Explicit stage division ensures work progresses according to the established process, with clear entry and exit conditions for each stage.

For git-supported code repositories, AXIOM automatically configures an independent git worktree for each task, ensuring that code changes from different tasks do not interfere with each other and each task is executed in an isolated environment. An immutable base_commit is recorded when a task is created, and subsequent changes are tracked relative to this baseline. Task-scoped diff comparisons and change file tracking help reviewers understand the actual modified files, ensuring changes are within the planned scope—even untracked new files are included in the diff evidence.

AXIOM sets mandatory validation and review gates before task completion. The validation phase supports running automated test commands, executed via tool agents, with features like policy checks, timeout control, and output capture limits. The review phase compares the planned write scope with the actual change scope and records the matching status. These gates are real blocking points: if validation fails, documentation is unresolved, there are no task differences, or changes exceed the planned scope, AXIOM returns a "changes_requested" or "blocked" status to ensure work quality and prevent insufficiently validated code from entering the completed state.

AXIOM provides a command adapter protocol that allows integration of local model wrappers or host agents. Adapters receive structured JSON requests via standard input and return JSON responses via standard output. Currently, adapters can be called in the run plan, run execute, and optional run review stages. The project provides multiple reference adapter implementations: static plan adapters, file write execution adapters, OpenAI-compatible plan/review wrappers, etc., enabling integration with various local models or agent frameworks without binding to specific providers. Note: Command adapters are considered trusted local commands and are not in a sandbox environment. For locked environments, it is recommended to use adapter whitelists or hash locking to ensure security.

AXIOM adopts a "source-first" release transparency model based on GitHub Releases and GitHub Actions. Each tagged version releases wheels, source code distribution packages, SHA256SUMS, SBOM.spdx.json, and GitHub artifact proofs, allowing users to verify the source of binary files and review dependencies to enhance supply chain security. Application scenarios include coding projects requiring structured workflow management (multiple parallel tasks, strict change reviews, consistent work norms). Deployment modes supported: PATH central installation, internal mirror or companion repository, project local vendoring. For enterprise teams that want to introduce AI-assisted coding but are worried about losing control, AXIOM balances agent capabilities with human supervision.

Currently, AXIOM has implemented core features: local workflow and release transparency (task file lifecycle, git worktree configuration, stage artifact persistence, command adapter protocol, validation and review gates, etc.). The project is still under active development, with planned features including more complete local model server integration, reproducible builds, and native macOS signature support. AXIOM represents a prudent attitude towards AI-assisted development tools: technology should enhance the capabilities of human developers rather than replace their judgment and responsibility. Through local state preservation, mandatory gates, and release transparency, it provides a solid foundation for collaborative models.