Skip to content

Check Your Project

Run a full quality check against the AXM gold standard.

Basic Usage

axm-init check

Score your project out of 100 with a grade from A (≥90) to F (<40).

Check a Specific Path

axm-init check /path/to/project

Filter by Category

Run only one category of checks:

axm-init check --category pyproject
axm-init check --category ci
axm-init check --category tooling
axm-init check --category docs
axm-init check --category structure
axm-init check --category deps
axm-init check --category changelog
axm-init check --category workspace

JSON Output for CI

axm-init check --json

Use in CI to enforce quality gates:

axm-init check --json | jq -e '.score >= 90'

Agent Output for AI

axm-init check --agent

Returns compact JSON optimized for AI agents: passed checks are summarized in one line, failed checks include full detail with fix hints.

Verbose Output

axm-init check --verbose

Shows every individual check with its status and weight:

pyproject (27/27)
    ✅ pyproject.exists               4/4  pyproject.toml found
    ✅ pyproject.urls                  3/3  All 4 URLs present
    ✅ pyproject.dynamic_version       3/3  Dynamic version with hatch-vcs
    ...

By default, only failures are displayed.

What Gets Checked (49 Checks)

Category Checks Points
pyproject exists, urls, dynamic_version, mypy, ruff, pytest, coverage, classifiers, ruff_rules 27
ci workflow, lint job, test job, security job, coverage upload, trusted publishing, dependabot 18
tooling pre-commit (×5), hooks installed, Makefile targets 16
docs mkdocs.yml, Diátaxis nav, plugins, gen_ref_pages, README, README badges 16
structure src/ layout, py.typed, tests/, CONTRIBUTING, LICENSE, uv.lock, .python-version 17
deps dev group, docs group 5
changelog git-cliff config, no manual CHANGELOG 5
workspace packages layout, members consistent, monorepo plugin, matrix packages, requires-python compat, root name collision, pytest importmode, pytest testpaths, quality workflow 19

Workspace Context

axm-init check auto-detects the project context (STANDALONE, WORKSPACE, or MEMBER) and displays it in the report header. Workspace members have CI checks excluded automatically, and per-package exclusions can be configured via [tool.axm-init].exclude.

Reading the Report

Each failed check includes:

  • Problem: What's wrong
  • Details: Specific missing items
  • Fix: Actionable remediation step

Example:

❌ docs.readme (3 pts)
   Problem: README missing 1 section(s)
   Missing: Development
   Fix:     Add Development section(s) to README.md.

CI Badge

Projects scaffolded with axm-init scaffold include an automated check badge powered by GitHub Actions. The badge displays your check score and updates on every push to main.

How It Works

  1. Push to main triggers .github/workflows/axm-quality.yml
  2. The workflow runs axm-init check --json and extracts the score
  3. A shields.io JSON badge is generated and pushed to gh-pages
  4. Your README displays the score via a shields.io endpoint badge

Badge in Your README

The scaffolded README already includes the badge. It looks like this:

<a href="https://your-org.github.io/your-project/">
  <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/your-org/your-project/gh-pages/badges/axm-init.json" alt="axm-init">
</a>

Adding to an Existing Project

If your project wasn't scaffolded with axm-init scaffold, you can add the badge manually:

  1. Copy the workflow from any scaffolded project (.github/workflows/axm-quality.yml)
  2. Add the badge markup to your README
  3. Push to main — the badge appears after the first workflow run

First run

The badge will show "resource not found" until the first workflow run pushes axm-init.json to gh-pages. Just push to main and wait for the action to complete.