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 pack API, the CLI JSON output or exit codes, the axx.yaml schema, or the release 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; signed, SBOM’d binaries; the criteria for v1.0.0. |
| 0005 | Docs platform | This site: Starlight, reference generated from the binary, Markdown twins, llms.txt, skills and an MCP server. |
| 0006 | License | 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 exactly. |
| 0008 | Publish every component from release.yml |
The CLI, the WireMock image and the IntelliJ plugin publish from one workflow, gated on release-please outputs. |
| 0009 | Custom steps are Go packs; the axx executable loads the packs a project uses |
Packs are opt-in per project (axx-packs.yaml); custom packs work on the same public contexts as Axx’s own. |
Related pages: Roadmap, Exit and error codes, JSON output.