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, 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, number formatting and value coercion follow Jayway JsonPath, java.util.regex and Jackson; the few deliberate deviations are listed in one place. |
| 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. |
Related pages: Roadmap, Exit and error codes, JSON output.