Developer Workflow and Contributing

Developer Workflow and Contributing

Relevant source files

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

• .github/copilot-instructions.md
• .github/copilot/skills/pr-review-responder.yml
• AGENTS.md
• CONTRIBUTING.md
• Makefile
• cmd/axis/summary_test.go
• cmd/axis/testdata/summary_daemon_cache.golden
• cmd/axis/testdata/summary_with_nodes.golden
• hack/lifecycle-check.go
• hack/pr-review-cycle.sh
• hack/refresh-current-state.sh
• hack/test-lint-failclosed.sh
• internal/discovery/discovery.go
• internal/multipath/prober.go
• internal/transport/ssh.go
• internal/transport/ssh_config_test.go
• internal/transport/ssh_lifecycle_test.go
• internal/transport/ssh_security_test.go

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

• Stable: Production-ready, part of the core operator path (e.g., internal/facts, internal/placement) hack/lifecycle-check.go:15-15.
• Experimental: New features subject to change (e.g., internal/agent, internal/mcp) hack/lifecycle-check.go:16-16.
• Scaffolded: Placeholder structures for planned features hack/lifecycle-check.go:17-17.
• Dormant: Code not currently in use but preserved for context hack/lifecycle-check.go:18-18.

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

---