@lordcraymen/adr-toolkit

A batteries-included CLI to bootstrap, lint, and publish Architecture Decision Records (ADRs). You can just install it in any repository to automate ADR workflows and ship documentation alongside your code.

Installation

npm install --save-dev @lordcraymen/adr-toolkit

The package ships ESM builds and exposes the adrx executable via the bin field.

CLI usage

Run npx adrx --help to inspect the full help output.

adrx init

Idempotently scaffolds ADR directories and helper templates:

• docs/adr/ with a README and template copy (docs/adr/templates/ADR-0000-template.md).
• docs/ADR_GUIDELINES.md with AI assistant guidelines (prompts for overwrite if modified).
• .dependency-cruiser.js wired to the provided dependency-cruiser preset.
• .github/PULL_REQUEST_TEMPLATE.md for contributor guidance.

adrx build

Parses ADR Markdown files and emits machine-readable artifacts:

• docs/adr/index.json – metadata for every ADR (status, tags, summary, etc.).
• docs/adr/ACTIVE.md – Markdown table with currently active ADRs.
• dist/adr-digest.json – digest of accepted ADRs for use in CI or PR summaries.

adrx check

Validates ADR frontmatter:

• Ensures title, status, and summary are present.
• Validates against a configurable set of allowed statuses (default: accepted, approved, proposed, draft, rejected, deprecated, superseded).
• Enforces a 300-character summary limit.
• Uses .adrx.config.json configuration if available for custom validation rules.

adrx affected --base <ref>

Diffs the working tree against a git reference and reports ADRs affected by the change. ADRs are marked as affected when:

• The ADR file itself changed.
• A changed file matches one of the ADR modules entries (prefix match).
• A changed path contains one of the ADR tags strings.

adrx create

Create new ADRs programmatically from structured input:

CLI Options:

# Create with individual options
adrx create --title "Use TypeScript" --summary "We will use TypeScript for better type safety" --status "proposed"

# Include tags and modules
adrx create --title "Adopt GraphQL" --summary "GraphQL provides better API flexibility" --tags "api,graphql" --modules "src/api/"

# Create from JSON input
adrx create --json '{"title": "Use React", "summary": "React for frontend", "status": "accepted", "tags": ["frontend", "ui"]}'

# Read JSON from stdin
echo '{"title": "Migration Plan", "summary": "Database migration strategy"}' | adrx create --json-stdin

Required fields: title and summary
Optional fields: status (default: "Proposed"), tags, modules, date, custom content for Context, Decision, Consequences, and References sections.

This command enables coding agents and automation tools to create ADRs without manual markdown formatting, addressing the structured interface need mentioned in issue #34.

adrx pr-comment

Posts the accepted ADR digest as a pull request comment when GITHUB_TOKEN, GITHUB_REPOSITORY, and PR metadata are available (e.g., within GitHub Actions). Without the necessary secrets, it logs a short message and exits without failing the build.

adrx config

Manage ADR configuration through the .adrx.config.json file:

• adrx config init – Initialize a default configuration file with customizable status values and other settings.
• adrx config validate – Validate the current configuration file against the schema.
• adrx config show – Display the current effective configuration.

The configuration file allows you to customize allowed ADR statuses, validation rules, and output formats.

Presets and templates

• presets/depcruise.cjs – dependency-cruiser layering rules to keep UI, application, and domain code separated.
• presets/eslint-boundaries.cjs – minimal ESLint preset using the eslint-plugin-boundaries conventions.
• templates/adr/ADR-0000-template.md – MADR-inspired ADR template with YAML frontmatter.
• templates/ADR_GUIDELINES.md – AI assistant guidelines template for working with ADRs.
• templates/adrx.config.json – default configuration template with customizable settings.
• templates/.dependency-cruiser.js, templates/PULL_REQUEST_TEMPLATE.md – helper scaffolding applied during adrx init.

Import the presets from Node using the exposed export paths:

import depcruise from '@lordcraymen/adr-toolkit/presets/depcruise.cjs';

API

The toolkit also exposes programmatic helpers:

• loadAdrs() – parse ADR Markdown into structured objects.
• validateAdrs() and validateAdrsWithConfig() – return an array of validation errors, with optional custom configuration.
• createAdr() – programmatically create new ADRs from structured input.
• createDigest(), createDigestWithConfig() and buildArtifacts(), buildArtifactsWithConfig() – generate JSON/Markdown digests for custom pipelines, with optional configuration support.
• runAffected(), runCheck(), runBuild(), runBuildWithConfig(), runPrComment() – the same routines invoked by the CLI.
• Configuration helpers: loadConfig(), validateConfig() – load and validate .adrx.config.json files.

Each helper accepts an optional working directory argument so you can run the tooling from scripts or tests. The *WithConfig variants allow you to pass custom configuration objects for advanced use cases.

TypeScript Types

All key TypeScript types are exported from the main entry point for downstream tool integration:

import type {
  AdrIndex,
  AdrDigest,
  AdrDocument,
  AdrFrontmatter,
  CheckResult,
  BuildResult,
  AffectedResult,
  ValidationError,
  OutputFormat
} from '@lordcraymen/adr-toolkit';

These types enable auto-completion and validation in TypeScript projects that consume ADR artifacts or integrate with the toolkit's API.

Continuous Integration

A reusable GitHub Actions workflow lives at .github/workflows/ci.yml. It runs on Node.js 18, 20, and 22 using npm ci followed by lint, typecheck, test, and build.

Acknowledgments

This tool supports the Architectural Decision Records pattern as described by Michael Nygard in his influential blog post: "Documenting Architecture Decisions"

For more information about ADRs and related tooling, see:

• ADR GitHub Organization
• Architecture Decision Records

License

MIT © Florian "lordcraymen" Patzke