Architecture decisions
Decisions that shape Axx’s public contracts are recorded as ADRs in docs/adr, in MADR format. A change to step text, the CLI JSON output or exit codes, the axx.yaml schema, or the release and versioning policy needs a new ADR.
| ADR | Decision | In short |
|---|---|---|
| 0001 | Build Axx in Go with its own Cucumber executor | One static binary; built on the official Cucumber Go libraries; step text is public API. |
| 0002 | Language-agnostic step protocol: JSON-RPC 2.0 over stdio | Superseded by 0009. |
| 0003 | CLI contract: JSON envelope, exit codes, error codes | Frozen exit codes, one --json envelope for every command, stable AXX-Exxxx codes, compact output for agents. |
| 0004 | Versioning and release: v0.x pre-releases via release-please and GoReleaser |
Every 0.x release is a GitHub pre-release; signed, SBOM’d binaries, container images and a Homebrew cask; the criteria for v1.0.0. |
| 0005 | Docs platform: Starlight, generated reference, agent-first outputs | This site: Starlight, reference generated from the binary, Markdown twins (which agents asking for Markdown get at a page’s address, from CloudFront), llms.txt, skills and an MCP server. |
| 0006 | License Apache-2.0 with DCO | Apache-2.0, contributions signed off with the DCO. |
| 0007 | Value semantics of the established Java libraries, verified by recorded oracles | JSONPath, regular expressions and number formatting follow Jayway JsonPath, java.util.regex and Jackson; the few deliberate deviations are listed in one place. What a step’s value means is ADR 0014’s. |
| 0008 | Publish every component from release.yml, gated on release-please outputs |
The CLI, the WireMock image and the IntelliJ plugin publish from one workflow; nothing publishes unless the AXX_PUBLISH repository variable is true. |
| 0009 | Custom steps are Go packs; the axx executable loads the packs a project uses |
Packs are opt-in per project (axx-packs.yaml), and axx builds itself with them; custom packs work on the same public contexts as Axx’s own. |
| 0010 | Setting a payload property creates the objects its path lacks | recipient.name in a payload without recipient creates it, unlike Jayway JsonPath; paths through arrays still need the array. |
| 0011 | Desktop apps are tested through the operating system’s accessibility tree | Drivers axx writes in Go read the tree every app publishes for screen readers, on all three operating systems: black-box, with no change to the app. |
| 0012 | Every app is driven with the same steps, and everything under test has a file context | app-core words the steps every app takes once, over the mobile and desktop packs; a folder says whose it is, so files resolve in that service’s or app’s own context. |
| 0013 | Phones are driven through their own drivers by axx, and served by device hosts (proposed) | axx installs and talks to the drivers on the devices itself, built around a host boundary, so the same code drives a device in the axx process or serves it to runs elsewhere. |
| 0014 | A value means what it says, in every pack | 42 is an integer and "42" the string, in every pack, set or checked; checks are strict, nothing is inferred, and an empty cell or a number JSON lacks (01067) fails with the explicit forms. |
Related pages: Roadmap, Exit and error codes, JSON output.