Skip to content

Developer Workflow and Contributing

Jump to bottom
William Smith edited this page Jul 13, 2026 · 1 revision

Developer Workflow and Contributing

Relevant source files

The following files were used as context for generating this wiki page:

This page outlines the standards and procedures for contributing to AXIS. The project follows a strict 5-layer architectural hierarchy and maintains a small dependency surface to ensure portability and security. All development is guided by the Truth Rule: no generated output may present itself as cluster truth unless backed by a real snapshot or live probe AGENTS.md:11-14.

Build and Environment Setup

AXIS requires Go 1.26.1+ CONTRIBUTING.md:16-16. The build process uses ldflags to inject versioning metadata, which is critical for distinguishing development builds from official releases.

Target Command Description
Build make build Produces ./axis with commit, date, and Go version metadata Makefile:15-16.
Install make install-user Installs to ~/.local/bin/axis (recommended for Cranium) Makefile:23-28.
Legacy make install Copies binary to $GOPATH/bin Makefile:19-20.
Clean make clean Removes the local axis binary Makefile:48-49.

Versioning and Metadata Injection

The Makefile extracts the base version from internal/buildinfo/version.go Makefile:1-1 and injects the current git commit and build timestamp during compilation Makefile:7-11. Developers can verify their build using axis version, which must show the specific commit hash CONTRIBUTING.md:22-24.

Sources: Makefile:1-50, CONTRIBUTING.md:6-30

Quality Gates and CI Pipeline

AXIS enforces a "fail-closed" quality policy. If a diagnostic tool (like gofmt) fails to run, the entire gate fails hack/test-lint-failclosed.sh:22-29.

Local Validation

Before submitting a PR, developers must run the following suite:

  1. Linting: make lint checks code formatting via gofmt and runs go vet Makefile:36-43.
  2. Testing: make test runs all tests with a 180s timeout Makefile:30-31.
  3. Race Detection: make test-race runs the test suite with the Go race detector enabled Makefile:33-34.
  4. Coverage: make coverage executes hack/coverage-check.sh to enforce per-package coverage minimums Makefile:45-46.

CI Enforcement

The GitHub Actions pipeline (ci.yml) mirrors these checks and adds specific "Repo Truth" validations:

  • verify-repo-truth.sh: Ensures that README.md and docs/current-state.md do not reference unpublished tags AGENTS.md:24-32.
  • verify-doc-facts.sh: Validates that documentation matches code entities (e.g., command counts, exit codes, and MCP tool counts) AGENTS.md:78-79.

Sources: Makefile:30-46, AGENTS.md:68-80, hack/test-lint-failclosed.sh:1-49

Lifecycle Taxonomy and Dependency Rules

AXIS uses a formal lifecycle taxonomy to manage code maturity and prevent experimental features from destabilizing the core operator path. These rules are enforced by hack/lifecycle-check.go.

Taxonomy Definitions

Dependency Inheritance Rules

  1. Stability Direction: A Stable package must not transitively import Experimental or Dormant packages hack/lifecycle-check.go:93-94.
  2. Documentation: Experimental packages must contain a doc.go file explicitly including the string "EXPERIMENTAL" hack/lifecycle-check.go:123-141.
  3. Isolation: Dormant packages cannot be imported unless explicitly allow-listed in dormantAllowList hack/lifecycle-check.go:143-179.

Code Entity to Lifecycle Mapping

The following diagram bridges the natural language lifecycle concepts to the specific code packages they govern.

Diagram: Lifecycle Package Classification

graph TD
    subgraph "STABLE (Core Path)"
        P1["internal/facts"]
        P2["internal/discovery"]
        P3["internal/snapshot"]
        P4["internal/placement"]
        P5["internal/transport"]
    end

    subgraph "EXPERIMENTAL (Advisory Layer)"
        E1["internal/agent"]
        E2["internal/mcp"]
        E3["internal/chat"]
        E4["internal/safety"]
    end

    subgraph "INTERNAL_ONLY (Supporting)"
        I1["internal/models"]
        I2["internal/persist"]
        I3["internal/ui"]
    end

    P1 --> P5
    P3 --> P1
    E1 --> P3
    E2 --> P3
    
    style P1 stroke-dasharray: 0
    style E1 stroke-dasharray: 5 5
Loading

Sources: hack/lifecycle-check.go:14-62, AGENTS.md:90-147

AI-Assisted Development (AGENTS.md)

AXIS provides specific instructions for AI agents (Claude, Copilot) to ensure they respect the project's architectural boundaries.

  • Subordinate Advisory: AI surfaces like internal/agent and internal/chat are strictly advisory. They must never override the Fact Plane AGENTS.md:92-93.
  • Context Awareness: Agents should use docs/current-state.md for live release facts rather than assuming version numbers AGENTS.md:34-36.
  • Event Subscription: Agents may subscribe to internal/events, but these events are strictly observational AGENTS.md:22-22.

Sources: AGENTS.md:1-41

PR Review and Release Cycle

PR Review Script

The hack/pr-review-cycle.sh script assists maintainers by aggregating the state of a PR. It performs the following:

  1. Check Verification: Waits for required GitHub status checks to turn green hack/pr-review-cycle.sh:78-109.
  2. Thread Aggregation: Fetches all review threads and general comments via GraphQL hack/pr-review-cycle.sh:117-159.
  3. Resolution Check: Exits with code 2 if required checks are green but unresolved threads remain hack/pr-review-cycle.sh:194-196.

Release Workflow

Releases are automated via GitHub Actions and GoReleaser.

  1. Version Update: Increment Version in internal/buildinfo/version.go CONTRIBUTING.md:47-47.
  2. Fact Refresh: Run hack/refresh-current-state.sh to update docs/current-state.md with latest comparison data hack/refresh-current-state.sh:1-46.
  3. Tagging: Push a v* tag. The CI validates that the tag matches the internal version constant before publishing CONTRIBUTING.md:60-68.

Diagram: Contribution and Release Data Flow

sequenceDiagram
    participant Dev as Developer
    participant Local as Local Environment
    participant GH as GitHub Actions
    participant GR as GoReleaser

    Dev->>Local: make lint && make test
    Local->>Local: hack/lifecycle-check.go
    Dev->>GH: Push PR
    GH->>GH: ci.yml (verify-repo-truth.sh)
    Dev->>Local: hack/pr-review-cycle.sh <pr>
    Dev->>Dev: Update internal/buildinfo/version.go
    Dev->>Local: hack/refresh-current-state.sh
    Dev->>GH: git push origin vX.Y.Z
    GH->>GH: release.yml (Check Tag vs Version)
    GH->>GR: Run GoReleaser
    GR->>GH: Create GitHub Release + Assets
Loading

Sources: CONTRIBUTING.md:41-71, hack/pr-review-cycle.sh:1-198, hack/refresh-current-state.sh:1-123

AXIS Wiki

Architecture Artifacts

DeepWiki

Clone this wiki locally