Development

Development and validation guidance for AI Grid Network (AGN).

Requirements

• Rust stable 1.96+; edition 2024 and resolver 3.
• nightly-2026-03-28 with rustfmt, matching NIGHTLY_RUSTFMT in the Makefile.
• Clippy, cargo-machete, cargo-audit, and cargo-deny for the Rust gates.
• typos, taplo, shellcheck, and actionlint for make lint-extra.
• jq and Mike Farah’s yq v4 for CRD generation.
• Go 1.24+ for make generate-go-types and make go-types-check.
• cargo-llvm-cov and llvm-tools-preview for optional coverage runs.
• Docker or Podman, kind, kubectl, Helm, and the topology-specific prerequisites for live integration checks. Individual harnesses may require Docker.

Node/npm are needed for the dashboard web application and Markdown lint tools. Read the relevant component guide before installing or running its tooling.

Conventions

Development Conventions is the canonical AGN policy. It covers coding style, documentation, tests, human review, and commit attribution, including the differences from the pinned shared Conventions baseline.

Workspace map

Run root Make targets from this repository’s top-level directory. Cargo package names stay the same regardless of their directory location. Root workspace crates live under crates/; Gateway is a separate workspace within that directory.

crates/gateway/ is a separate Cargo workspace with its own lockfile. It contains gateway (the grid-gateway binary) and ai-grid-filters. Root cargo --workspace commands do not include it. Keep its TLS feature choices and production no-ring check intact when changing shared dependencies.

Forge is an upstream tool. Install it with ./scripts/forge.sh install before running environment qualifications. Grid pins its source revision and resolves the executable through a shared wrapper. See Forge tooling for installation, cache verification, development overrides, and upgrade checks.

Development images

make container, make images, and make dev-push build the operator using deploy/operator/Containerfile. Their default PROJECT_IMAGE is now grid-operator:dev, replacing praxis-grid:dev; update scripts that load the old tag. To keep an existing local tag, pass PROJECT_IMAGE=praxis-grid:dev to those targets. make dev-push also loads the image into the selected kind cluster.

Verification

make all runs build, formatting, lint, rustdoc, root tests, and root audit. When go is found in PATH it also runs go-types-check, which regenerates the Go API types from the deployed CRD schemas and fails if the committed files differ. The check rewrites go/api/v1alpha1/zz_generated_*.go in place, so run it before staging. Without Go in PATH the check is skipped silently; CI always runs it via the go-types-check step regardless. Run make lint-extra separately for spelling, TOML, shell, and workflow checks. The make all aggregate does not run coverage, Gateway tests, FIPS checks, container builds, dashboard web checks, or live cluster qualifications. Run those when the changed contract requires them. The release guide records the integration qualification matrix.

Tests and Coverage workflows skip their Rust jobs for documentation-only PRs; rustdoc and MSRV still run. The Gateway, Helm, and dashboard workflows have their own triggers and scopes. A skipped or absent job is not a passing test result. The canonical conventions require the local test suite before submitting any PR, including README or Markdown prose changes. Changes to examples, generated contracts, or executable commands also need checks appropriate to the affected behavior.

Formatting and documentation

make fmt
make lint
make doc

Nightly is required for rustfmt’s group_imports and imports_granularity. All public and private items need documentation under the workspace lint policy; see the canonical policy for test-function exceptions. .cargo/config.toml also sets rustdocflags = ["-D", "warnings"], including outside Make.

Markdown style is configured in .markdownlint.yaml; external link-check settings are in lychee.toml. These checks are not part of make lint-extra or checked-in CI. Review relative links and anchors when moving or rewriting docs, and report whether automated Markdown/link checks were run.

Generated manifests

make generate-crds writes deploy/crds/ and charts/grid-operator/templates/crds/ from crates/operator/src/crd/. make generate-api-types writes enrollment Rust types from api/enrollment-v1alpha1.yaml. Edit the sources and regenerate; do not edit the generated output directly. CRD doc-comment changes also affect field descriptions and require regeneration.

make generate-go-types derives go/api/v1alpha1/zz_generated_*.go from deploy/crds/. Run it after any make generate-crds pass and commit the result. make go-types-check re-runs the generator and fails if the committed files differ; CI runs this step regardless of whether Go is in your local PATH.

make generate-crds
make crds-check
make generate-api-types
make codegen-check
make generate-go-types
make go-types-check

Coverage and supply chain

make coverage writes an HTML report under target/coverage; make coverage-check writes coverage.json. See the coverage policy for the measured-scope limits and the path toward the shared 90% line / 80% region target. No threshold increase should be claimed without a report from the actual commands.

cargo audit checks known advisories. cargo deny check enforces deny.toml, including license and source policy. Documented advisory exceptions belong to their actual dependency paths; refreshing a template must not silently remove or broaden them. Gateway has its own lockfile and deny.toml.

Hooks and worktrees

Enable signing with your own Git identity and key before committing. Running make setup-hooks selects .hooks through core.hooksPath, which works when .git is a file in a linked worktree. This is repository Git configuration and can affect its other worktrees. The hook checks that signing is enabled, then runs make lint; it does not run tests or the complete make all aggregate.

Keep build outputs, cluster names, ports, and qualification evidence isolated when working in parallel. Worktrees isolate source edits, not Git configuration or container-daemon resources. Do not run cleanup against another run’s state.

Project Management

All repositories in the praxis-proxy organization use a consistent workflow for planning, prioritizing, and tracking work.

Milestones

Milestones represent a body of work toward a shared goal (e.g. a release, a feature area, or a hardening pass). Every issue and pull request should belong to a milestone. Milestones provide scope boundaries and help answer “what ships together?”

Priority Labels

Priority labels indicate the order in which work within a milestone should be addressed. Every issue should have exactly one priority label:

When picking up work, address issues in priority order: critical first, then high, medium, and low.

Project Boards

GitHub project boards visualize the state of work across milestones. Use boards to track issues through their lifecycle (backlog, in progress, in review, done). Boards are the primary tool for stand-ups and status checks.