Skip to content

FRACerqueira/AdrPlus

BranchesTags

Repository files navigation

icon

AdrPlus

CI NuGet NuGet Downloads License: MIT .NET

Many teams still document architectural decisions inconsistently (scattered Markdown files, no revision flow, and hard-to-track status changes).

AdrPlus was created to solve this problem with a practical CLI workflow that keeps ADRs standardized, traceable, and easy to evolve over time.

AdrPlus is a cross-platform .NET command-line tool for managing Architecture Decision Records (ADRs) directly from your terminal.

It supports versioning, revision cycles, status workflows (approve / reject / undo), and an interactive wizard — all driven by a lightweight JSON configuration file.

Table of Contents

Motivation and Benefits

Using AdrPlus in an engineering repository helps you:

  • 📚 Keep architectural decisions organized with a predictable structure
  • 🔍 Improve traceability with version, review, and supersede flows
  • ⚡ Reduce manual effort when creating and updating ADR files
  • 🛠️ Respect the repository's configuration for naming, structure, and ADR status for each team
  • 🤝 Improve collaboration by making decision history visible to the whole team
  • 🚀 Accelerate onboarding by exposing context behind technical choices

Features

  • 📝 Create new ADRs with auto-incremented sequential numbers
  • 🔢 Version and review existing ADRs (major version or revision bump)
  • 🔄 Supersede an ADR by creating a successor with a new number
  • ✅ Approve / ❌ Reject / ↩️ Undo ADR status changes
  • 🧙 Interactive wizard for guided, step-by-step operations
  • 🔍 Explorer for viewing or Generate reports and managing ADR files in your repository
  • ⚙️ Config editor for application ,repository settings and migration of existing ADRs to the standardized format
  • 📂 Customizable ADR structure with user-defined templates and naming conventions
  • 🔄 Migrate existing ADRs to the standardized format
  • 💾 Preserve settings and configuration across upgrades and reinitializations
  • 🗂️ Multiple ADR model options for different project needs and for each team
  • 🌍 Multi-language support (en-US, pt-BR) for messages and UX
    • ADR content can be written in any language!
  • 🖥️ Cross-platform (Windows, macOS, Linux)

Requirements

For running

AdrPlus can be used in repositories of any language or framework (C#, Java, Node.js, Python, Go, etc.), because it manages ADR files in Markdown and does not depend on your application stack.

For building and packaging from source

Installation

Install from NuGet (Recommended for .NET developers)

The easiest way to install AdrPlus is directly from NuGet.org:

dotnet tool install -g adrplus

To update to the latest version:

dotnet tool update -g adrplus

To uninstall:

dotnet tool uninstall -g adrplus

After installation, you can use adrplus from any terminal in any repository.

Build and install from source

If you prefer to build from the repository source code:

1. Build and generate a local package

# From repository root
dotnet restore
dotnet build -c Release
dotnet pack -c Release -o ./nupkg

2. Install from local package

# Install as global tool from local package folder
dotnet tool install -g adrplus --add-source ./nupkg

# If already installed, update from the same local source
dotnet tool update -g adrplus --add-source ./nupkg

Quick Start

AdrPlus automates the initial setup on first run!

When you run any command for the first time (except help), an interactive wizard will automatically guide you through:

  • Selecting your preferred language
  • Configuring your editor to open ADR files
  • Setting up your ADR repository structure and naming conventions
  • Creating your ADR folder and configuration files

To get started, simply run run without command, and the setup wizard will appear:

# Just run without command and the first-time setup will run
adrplus

# Or any other command - the first-time wizard will run before it executes
adrplus init --wizard

After initial setup completes, you can use any command directly:

# Create a new ADR with the wizard
adrplus new --wizard

# Or explore and manage your ADRs
adrplus explorer --path "path/to/repository"
adrplus approve --file "path/to/adr/ADR0001.md"

Note: If you have existing ADR files in a different format, see Migration Guide for detailed prerequisites and migration instructions before creating new ADRs with the tool.

For a detailed walkthrough, see the Step-by-Step Guide.

Advanced Configuration (Optional)

Note: The initial setup wizard runs automatically on first use. The commands below are optional if you want to reconfigure or adjust settings after the initial setup.

Reconfigure Application Settings

You can modify application settings at any time:

# Edit language, editor preferences, and other application settings
adrplus config --application

# Edit the default template used for new ADRs
adrplus config --template

# Edit patterns for migrating existing ADRs (used with the migrate command)
adrplus config --migrate

# Edit repository-specific settings (ADR naming, statuses, structure)
adrplus config --repository

Reinitialize or Update Repository Structure

The init command can be run multiple times to reinitialize or update your ADR repository structure:

# Initialize repository for the first time (or with wizard guidance)
adrplus init --wizard

# Reinitialize with specific configuration file
adrplus init --path "path/to/repository" --file "path/to/config"

# Reinitialize current directory
adrplus init --path "."

This is useful when:

  • You need to update the folder structure for scope changes
  • You want to recreate default configuration files
  • You're adjusting naming conventions or patterns

Individual Commands (without the wizard)

You can also execute commands directly, one by one, without the wizard and without interactive prompts.

# Configure the tool (optional, you can edit the config file directly or use the config command later)

    adrplus config --application --file "path/to/file-tool-config"
    adrplus config --template --file "path/to/file-template.md"
    # any mode can be used for repository config, the important part is to point to the correct file
    adrplus config --repository --file "path/to/file-adr-config"
    adrplus config --migrate --file "path/to/file-ard-config"

# Launch the ADR file viewer explorer

    adrplus explorer --path "path/to/repository"

# Initialize ADR structure (if the first time you set up the repository)

    adrplus init --path "path/to/repository"

# Create a new ADR directly

    # the parameter --open is optional and depends on the configuration for opening files after creation/update
    adrplus new --title "Use PostgreSQL as primary database" --path "path/to/repository" --open

# Approve or reject a specific ADR file

    adrplus approve --file "./doc/adr/ADR0001V01-use-postgresql.md"
    adrplus reject --file "./doc/adr/ADR0002V01-legacy-cache.md"

# Undo last status change

    adrplus undo --file "./doc/adr/ADR0001V01-use-postgresql.md"

# Create supersede flows

    adrplus approve --file "./doc/adr/ADR0001V01-use-postgresql.md"
    # the parameter --open is optional and depends on the configuration for opening files after creation/update
    adrplus supersede --file "./doc/adr/ADR0001V01-use-postgresql.md" --open

# Create review/version flows

    # the parameter --open is optional and depends on the configuration for opening files after creation/update
    adrplus review --file "./doc/adr/ADR0001V01-use-postgresql.md" --open
    adrplus version --file "./doc/adr/ADR0001V01-use-postgresql.md" --open

Use adrplus help <command> to check the available parameters for each command.

Commands

Command Description
help Display help information for all commands or a specific command
wizard Launch the interactive wizard for guided operations
config Application configuration editor,migrate repository,repository and default ADR template
explorer Launch the file viewer explorer and report for the ADR repository
migrate Migrate existing ADRs to use the tool
init Initialize or reinitialize the ADR repository folder structure (can be run multiple times)
new Create a new ADR with an incremental number
version Create a new version of an ADR (increment version)
review Create a new revision of an ADR (increment revision)
supersede Supersede an ADR by creating a successor with a new incremental number
approve Set an ADR status to Accepted
reject Set an ADR status to Rejected
undo Revert the last status change of an ADR

Run adrplus help <command> for detailed usage of any command.

Rules by ADR commands

The rules below describe what must be true for a command to select its target successfully (especially in wizard mode).

For file-based commands (approve, reject, undo, version, review, supersede), the file must exist, be a valid ADR .md, be under the configured FolderRepo, and the repository config file must be valid.

Command Successful selection rules
new title + domain must be unique. When scope is enabled , --scope must be valid; --domain is required unless scope is listed in skipdomain.
approve ADR must be eligible: not already approved/rejected and for the same sequence number not superseded.
reject ADR must be eligible: not already approved/rejected.
undo ADR must be eligible: already approved/rejected and for the same sequence not a superseded and not proposed.
version ADR must be eligible: latest(or last approved and last rejected) ADR for the same sequence number approved/rejected and not superseded.
review ADR must be eligible: latest(or last approved and last rejected) ADR for the same sequence number approved/rejected , not superseded and revision enabled.
supersede ADR must be eligible: already approved and not superseded.

Configuration

AdrPlus uses two configuration files:

  • adrplus.json: application-level settings (language and command to open ADR).
  • adr-config.adrplus: repository-level settings (ADR naming, template, statuses, and structure).

adrplus.json example

You can edit the application configuration with:

adrplus config --application
{
  "language": "en-US",
  "comandopenadr": "code {0}",
  "withoutargs": "Help"
}
Key Description
language UI language/culture used by the tool (en-US, pt-BR). Defines the language for all prompts and messages displayed in the wizard and command outputs.
comandopenadr Command to open an ADR file after creation/update when supported. See examples below.
withoutargs Behavior when no arguments are provided (Help, Wizard, or None). Default is Help.
Examples for comandopenadr
  • VS Code: code {0} — Opens the file in VS Code.
  • Visual Studio: devenv.exe {0} — Opens the file in the associated application (Windows only).
  • JetBrains Rider: rider {0} — Opens the file in Rider.
  • Sublime Text: subl {0} — Opens the file in Sublime Text.
  • Vim: vim {0} — Opens the file in Vim.
  • Nano: nano {0} — Opens the file in Nano.
  • Disabled: "" (empty string) — Disables automatic opening of ADR files.

Note: The command must be available as a global PATH variable in your system to work properly. Test it manually in your terminal before configuring it here.

Behavior when no arguments are provided (withoutargs)

The withoutargs setting determines how AdrPlus behaves when executed without any arguments or commands:

  • Help (default): Displays the help information with available commands and options.
  • Wizard: Launches the interactive wizard for guided operations (useful for agile experienced users).
  • None: Requires the user to explicitly provide a command; if no command is given, an error message is shown.

Example configurations:

{
  "withoutargs": "Help"    // Display help when no arguments provided
}
{
  "withoutargs": "Wizard"  // Launch wizard when no arguments provided
}
{
  "withoutargs": "None"    // Require explicit command
}

adr-config.adrplus example

AdrPlus uses the adr-config.adrplus file to control repository behavior, ADR naming, template content, and status labels.

You can edit it with:

adrplus config --repository
{
  "folderadr": "doc/adr",
  "migrationpattern": "...",
  "template": "...",
  "prefix": "ADR",
  "lenseq": 4,
  "lenversion": 2,
  "lenrevision": 0,
  "lenscope": 0,
  "separator": "-",
  "casetransform": "PascalCase",
  "statusnew": "Proposed",
  "statusacc": "Accepted",
  "statusrej": "Rejected",
  "statussup": "Superseded",
  "scopes": "",
  "folderbyscope": false,
  "skipdomain": "",
  "headerdisclaimer": "Do not remove this comment, lines and table",
  "headertitlefile": "ADR",
  "headerversion": "Version",
  "headerrevision": "Revision",
  "headerscope": "Scope",
  "headerdomain": "Domain",
  "headertitlestatuscreated": "Created",
  "headertitlestatuschanged": "Changed",
  "headertitlestatussuperseded": "Superseded",
  "headertablefields": "Fields",
  "headertablevalues": "Values",
  "headermigrated": "Migrated"
}
Key Description
folderadr Folder where ADR files are stored.
migrationpattern Pattern used for migrating ADR files (generated by the tool).
template Base Markdown template used when creating new ADR files (generated by the tool).
prefix Prefix used in ADR titles/identifiers (for example: ADR).
lenseq Number of digits for the sequential ADR number (for example: 4 => 0001).
lenversion Number of digits for major version formatting (for example: 2 => 01).
lenrevision Number of digits for revision formatting (for example: 2 => 01; 0 disables revision numbering).
lenscope Maximum scope segment length used in generated names (when scope is enabled, value > 0).
separator Separator character used in generated file names (valid values: -, _, or .).
casetransform Case style applied to generated name segments (for example: PascalCase, CamelCase, SnakeCase, or KebabCase).
statusnew Label used for newly created ADRs.
statusacc Label used for accepted ADRs.
statusrej Label used for rejected ADRs.
statussup Label used for superseded ADRs.
scopes Semicolon-separated list of allowed scopes for organizing ADRs (for example: Enterprise;Domain;Project; can be empty when lenscope = 0).
folderbyscope If true, ADR files are grouped by scope folders; if false, all ADRs remain in the flat folderadr directory.
skipdomain Semicolon-separated list of scope names for which the domain segment should be omitted from the generated filename (must be a subset of scopes).
headerdisclaimer Disclaimer header added to ADR template output.
headertitlefile Header label for the ADR file name field in the header.
headerversion Header label for ADR version field.
headerrevision Header label for ADR revision field.
headerscope Header label for ADR scope field.
headerdomain Header label for ADR domain field.
headertitlestatuscreated Header label for the "Created" status indicator.
headertitlestatuschanged Header label for the "Changed" status indicator.
headertitlestatussuperseded Header label for the "Superseded" status indicator.
headertablefields Table header label for displaying field names in the ADR.
headertablevalues Table header label for displaying field values in the ADR.
headermigrated Header label for the "Migrated" indicator (used for ADRs migrated via the migrate command).

Suggested settings per team profile

Understanding configuration concepts

Before selecting a team profile, understand these key concepts:

  • Scopes: Define organizational boundaries for your ADRs (e.g., "Enterprise", "Backend", "Frontend"). Scopes help organize decisions by domain or team responsibility. When enabled (lenscope > 0), the scope appears in the ADR filename.

  • Folder by Scope: When enabled, ADRs are organized into separate folders for each scope (e.g., doc/adr/enterprise/, doc/adr/backend/). When disabled, all ADRs stay in a flat structure under the configured folderadr folder.

  • Skip Domain: Some scopes may not need a domain segment in the filename. For example, a "Corporate" scope might skip the domain to keep filenames shorter. You can list multiple scopes separated by semicolons.

  • Case Transform: The style applied to the title portion of generated filenames:

    • PascalCase: UsePostgreSQLAsDatabase
    • CamelCase: usePostgreSQLAsDatabase
    • SnakeCase: use_postgresql_as_database
    • KebabCase: use-postgresql-as-database (default)

  • Separator: The character separating different parts of the filename:

    • - (hyphen): ADR0001V01-UsePostgreSQL.md
    • _ (underscore): ADR0001_UsePostgreSQL.md
    • . (period): ADR0001V01.UsePostgreSQL.md

  • Version vs. Revision:

    • Version: A major change to an ADR (e.g., V01, V02) that typically represents a significant decision update.
    • Revision: A minor change to an ADR (e.g., R01, R02) that represents clarifications or documentation improvements.

1) Monorepo (multiple apps/domains or enterprise architecture)

Use scopes and folder grouping to keep ADRs organized by area. Each team or domain maintains its own ADR sequence.

{
  "scopes": "Enterprise;Project;Backend;Frontend;Mobile;Data",
  "skipdomain": "Enterprise",
  "folderbyscope": true,
  "lenscope": 1,
  "separator": "-",
  "casetransform": "PascalCase",
  "lenversion": 2,
  "lenrevision": 0
}

Example filenames generated:

  • doc/adr/Enterprise/ADR0001V01E-UnifyAuthenticationStrategy.md
  • doc/adr/Backend/ADR0001V01B-UsePostgreSQ@MyBackEndScope.md
  • doc/adr/Frontend/ADR0001V01F-AdoptReactFramework@MyFrontEndScope.md

2) Simple repository

Use a simple flat structure with no scope folder split. Ideal for smaller projects or single-domain repositories.

{
  "scopes": "",
  "folderbyscope": false,
  "lenscope": 0,
  "separator": "-",
  "casetransform": "PascalCase",
  "lenversion": 2,
  "lenrevision": 0
}

Example filenames generated:

  • doc/adr/ADR0001V01-UsePostgreSQL.md
  • doc/adr/ADR0002V01-AdoptReactFramework.md

3) Product team with frequent revisions

Keep revision metadata visible and standardized. Useful for teams that frequently update ADR documentation or maintain multiple versions.

{
  "lenseq": 4,
  "lenversion": 2,
  "lenrevision": 2
}

Example filenames generated:

  • doc/adr/ADR0001V01R01-DecisionTitle.md (created)
  • doc/adr/ADR0001V02R01-DecisionTitle.md (after revision)
  • doc/adr/ADR0001V03R02-DecisionTitle.md (after version bump)
  • doc/adr/ADR0002V01R01-DecisionTitle--0001.md (after superseded bump)

4) Enterprise with department scopes

Organize ADRs by department with custom headers and folder structure.

{
  "scopes": "Infrastructure;Database;Platform;Security",
  "skipdomain": "Platform",
  "folderbyscope": true,
  "lenscope": 3,
  "separator": "-",
  "casetransform": "PascalCase",
  "lenversion": 2,
  "lenrevision": 0
}

Example filenames generated:

  • doc/adr/Infrastructure/ADR0001V01Inf-UseDockerContainers.md (Infrastructure)
  • doc/adr/Database/ADR0001V01Dat-AdoptPostgresql.md (Database)

Tip: start with one profile, run adrplus init, create a test ADR with adrplus new, and adjust the config iteratively.

Settings and configuration across upgrades

When you upgrade AdrPlus to a new version, all your settings and configurations are automatically preserved:

# Update to the latest version
dotnet tool update -g adrplus

Your configuration persists automatically:

  • ✅ Application settings (adrplus.json): Language, editor preferences, and interface behavior remain unchanged
  • ✅ Repository configuration (adr-config.adrplus): ADR naming patterns, folder structure, and scope definitions are maintained

No manual reconfiguration is needed after upgrading — simply update the tool and continue using it as before.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting pull requests or issues.

Code of Conduct

Please read and follow CODE_OF_CONDUCT.md.

Security

To report a vulnerability, please read SECURITY.md.

License

This project is licensed under the MIT License.

About

AdrPlus is a cross-platform .NET command-line tool for managing Architecture Decision Records (ADRs) directly from your terminal.

Topics

architecture cli-tool adrs dotnet-tools decision-record

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 8

AdrPlus v0.6.0 Latest
May 25, 2026
+ 7 releases

Contributors

Languages