axm-init 0.16.0

axm-init — Project scaffolding, quality checks & governance tools

axm-init scaffolds projects, checks their governance artefacts and reserves PyPI names. Its three AXMTools are available through the shared axm CLI and an MCP server with the package installed.

Features

• 🚀 Scaffold — Generate Python projects, workspaces and member packages; additional templates support Node/Svelte and research projects
• 📋 Check — Score any project against the AXM gold standard (context-selected checks, A–F grade)
• 📦 Reserve — Claim a package name on PyPI before you're ready to publish

Installation

Requires Python 3.12 or newer. Install the shared CLI with this provider:

uv tool install --with axm-init axm

For a dependency inside an existing uv project, use uv add axm-init, then invoke uv run axm ....

Quick Start

# Scaffold a new project
axm init_scaffold my-project \
  --org axm-protocols \
  --author "Your Name" --email "you@example.com"

# Check the generated project against AXM standards
axm init_check my-project

The first command creates my-project; the second reports its applicable checks, score and grade. The score depends on the generated files and the check context; scaffolding does not guarantee a perfect score.

Usage

CLI Commands

axm init_scaffold

Scaffold a Python project with src layout, PEP 621 metadata, CI and docs.

Note: --workspace and --member are mutually exclusive.

axm init_check

Score a project against the context- and framework-selected AXM checks.

Python categories: pyproject, ci, tooling, docs, structure, deps, changelog, workspace, paper, experiment. Node/React/Svelte use their own registries.

axm init_reserve

Reserve a package name on PyPI with a minimal placeholder. Preview without publishing:

axm init_reserve my-cool-lib --author "Your Name" --email "you@example.com" --dry-run

Note: --author and --email fall back to git config user.name / user.email. Fallback occurs only if both flags are omitted. If one is supplied, the other must be supplied too; an incomplete identity is rejected.

See the complete CLI reference for framework and protocol options, output schemas and exit policy. The generated CLI has no short aliases.

Workspace Support

axm-init detects five project contexts and adapts checks accordingly:

Per-Package Check Exclusions

Workspace members can exclude inapplicable checks via pyproject.toml. Each entry is a prefix of a canonical check name — the category.function_name_without_check_ form shown in the report (e.g. ci.ci_steps_executable). A bare category like "ci" excludes the whole category:

[tool.axm-init]
exclude = ["ci.ci_steps_executable", "tooling.makefile"]

Scaffold Modes

# Standalone package (default)
axm init_scaffold my-project --org myorg --author A --email e@e.com

# UV workspace
axm init_scaffold my-workspace --workspace --org myorg --author A --email e@e.com

# Member sub-package (run from inside workspace)
axm init_scaffold --member my-lib --org myorg --author A --email e@e.com

The --member flag auto-detects the workspace root, creates the package under packages/<name>/, and attempts to patch root files (Makefile, mkdocs.yml, pyproject.toml, CI workflows). Inspect skipped_root_files and failed_root_files in the JSON result: a created member does not guarantee that every root integration succeeded.

CI Check Badge

Python project templates include an automated check badge workflow. It publishes score data to gh-pages after a successful workflow run on main.

push → axm init_check → badge JSON → gh-pages → shields.io

The README badge resolves once the workflow has published its JSON. Repository permissions and workflow execution must allow publication to gh-pages.

Existing projects can add the badge too — copy .github/workflows/axm-quality.yml from a scaffolded project and add the badge markup. See the howto guide for details.

Documentation

• Getting started
• Scaffold a project
• Check project quality
• Reserve a package name
• Use via MCP and Python entry points
• Published documentation

The MkDocs home page is docs/index.md, separate from this README.

Development

This package is part of the axm-forge workspace.

git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-packages --all-groups
uv run --package axm-init --directory packages/axm-init pytest -x -q

With the docs dependencies installed, build the standalone documentation from packages/axm-init using mkdocs build --strict.

License

Licensed under Apache-2.0. See LICENSE.