madrkit 1.0.0

MADR Kit - A CLI tool for creating and managing Markdown Architecture Decision Records (MADR).

MADR Kit

🏗️ MADR Kit

Architecture Decision Records Made Simple

A CLI tool for creating and managing Markdown Architecture Decision Records (MADR) across multiple AI assistants.

---

Table of Contents

• 🤔 What is MADR Kit?
• ✨ Features
• 🚀 Quick Start
• 🤖 Supported AI Assistants
• 📖 Usage
• 🔗 ADR Format
• 🎯 Philosophy
• 📄 License

🤔 What is MADR Kit?

MADR Kit is a command-line tool that helps you create and manage Architecture Decision Records (ADRs) using the MADR (Markdown Architecture Decision Record) format.

Architecture Decision Records are a lightweight way to document significant architectural decisions in your projects. They capture:

• The problem you faced
• Options you considered
• The decision you made
• Rationale for choosing that option
• Consequences of your decision

MADR Kit integrates with 15+ AI assistants (Claude, GitHub Copilot, Gemini, and more), allowing you to use AI to help guide the decision-making process interactively.

✨ Features

• 🤖 Multi-AI Support: Works with Claude, Gemini, GitHub Copilot, Cursor, and 15+ AI assistants
• 📝 MADR Compliant: Follows the official MADR format
• 🔢 Auto-numbering: Sequential ADR numbering across your project (0001, 0002, 0003...)
• 💬 Interactive Workflow: Guided questions help you build complete ADRs
• 🌐 Cross-platform: Supports both bash and PowerShell
• 📦 Simple Installation: One command to set up everything

🚀 Quick Start

1. Install MADR Kit

Option 1: Using pip (Recommended)

pip install madrkit

Option 2: Using uv

uv tool install madrkit

Option 3: One-time Usage

uvx madrkit init <PROJECT_NAME>

2. Initialize Your Project

# Create a new project
madrkit init my-project --ai claude

# Or initialize in the current directory
madrkit init --here --ai claude

This will:

• Create the project structure
• Set up templates for your AI assistant
• Initialize a git repository (unless --no-git is used)
• Create the /madrkit.decide command in your AI assistant

3. Create Your First ADR

Use your AI assistant to run:

/madrkit.decide Choose database for user data

The command will guide you through:

• Decision Title - A concise summary of what needs to be decided
• Context & Problem - Describe the situation requiring a decision
• Decision Drivers (optional) - Key factors influencing the decision
• Considered Options - At least 2 alternatives you evaluated
• Decision Outcome - Your chosen option and justification
• Consequences (optional) - Positive and negative impacts
• Confirmation (optional) - How you'll validate the decision

4. View Your ADRs

ADRs are stored in docs/decisions/ with sequential numbering:

docs/decisions/
├── 0001-choose-database-for-user-data.md
├── 0002-authentication-strategy.md
└── 0003-api-protocol-choice.md

🤖 Supported AI Assistants

MADR Kit works with any AI assistant that supports slash commands:

• Claude Code - Official Claude IDE extension
• GitHub Copilot - IDE-integrated AI
• Google Gemini CLI - Google's CLI-based AI
• Cursor - IDE with built-in AI
• Windsurf - AI-first IDE
• Qwen Code - Alibaba's code AI
• Qoder - Code AI platform
• And 10+ more...

📖 Usage

Creating an ADR

/madrkit.decide [optional: decision topic]

Examples:

# Create an ADR for database selection
/madrkit.decide Choose between PostgreSQL, MySQL, and MongoDB for our main database

# Create an ADR for authentication
/madrkit.decide Implement JWT-based authentication vs session-based

# Create an ADR with interactive guidance (no topic)
/madrkit.decide

Command Options

When initializing a project:

madrkit init [PROJECT_NAME] [OPTIONS]

Options:
  --here, -h           Initialize in current directory
  --ai ASSISTANT       Choose AI assistant (claude, gemini, copilot, etc.)
  --script sh|ps       Script type (bash or PowerShell)
  --no-git             Skip git initialization
  --force              Skip confirmation when directory is not empty

🔗 ADR Format

Each ADR follows the MADR standard format:

---
status: proposed | accepted | rejected | deprecated | superseded by ADR-0123
date: 2024-01-15
decision-makers: [optional team members]
consulted: [optional experts consulted]
informed: [optional stakeholders informed]
---

# [Short Title]

## Context and Problem Statement

[Describe the situation and problem]

## Decision Drivers

* [Force 1]
* [Force 2]

## Considered Options

* Option 1: [Title]
* Option 2: [Title]
* Option 3: [Title]

## Decision Outcome

Chosen option: "Option 1", because [justification]

### Consequences

* Good, because [positive impact]
* Bad, because [negative consequence]

### Confirmation

[How will this be validated?]

## Pros and Cons of the Options

### Option 1

* Good, because [argument]
* Bad, because [argument]

### Option 2

* Good, because [argument]
* Bad, because [argument]

## More Information

[Additional context or links]

🎯 Philosophy

Why ADRs Matter

• Captured Knowledge: Decisions aren't lost when team members leave
• Future Context: Future developers understand why choices were made
• Accountability: Clear record of who decided what and when
• Learning: Team learns from past decisions and consequences
• Alternatives Considered: Future changes understand previous options

MADR Principles

• Lightweight: Minimal overhead, easy to create and maintain
• Markdown: Simple format, easy to version control
• Sequential: ADRs are numbered and immutable (create new ones instead of editing)
• Focused: One decision per ADR
• Comprehensive: Captures enough context to understand the decision

📄 License

MIT License - See LICENSE for details.

---

Getting Help

• 📚 ADR.github.io - Architecture Decision Record format
• 🔗 MADR Format - Official MADR specification
• 🐛 Report Issues - Found a bug?
• 💡 Suggest Features - Have an idea?

---

Made with ❤️ for better architecture decisions