madrkit 1.0.0
MADR Kit - A CLI tool for creating and managing Markdown Architecture Decision Records (MADR).
License: MIT
Requires Python: >=3.11
Keywords: adr, ai, architecture, cli, decision, madr, records

# MADR Kit

<div align="center">
    <h1>🏗️ MADR Kit</h1>
    <h3><em>Architecture Decision Records Made Simple</em></h3>
</div>

<p align="center">
    <strong>A CLI tool for creating and managing Markdown Architecture Decision Records (MADR) across multiple AI assistants.</strong>
</p>

---

## Table of Contents

- [🤔 What is MADR Kit?](#-what-is-madr-kit)
- [✨ Features](#-features)
- [🚀 Quick Start](#-quick-start)
- [🤖 Supported AI Assistants](#-supported-ai-assistants)
- [📖 Usage](#-usage)
- [🔗 ADR Format](#-adr-format)
- [🎯 Philosophy](#-philosophy)
- [📄 License](#-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](https://adr.github.io/madr/).

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](https://adr.github.io/madr/)
- 🔢 **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)

```bash
pip install madrkit
```

#### Option 2: Using uv

```bash
uv tool install madrkit
```

#### Option 3: One-time Usage

```bash
uvx madrkit init <PROJECT_NAME>
```

### 2. Initialize Your Project

```bash
# 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:

```bash
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

```bash
/madrkit.decide [optional: decision topic]
```

Examples:

```bash
# 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:

```bash
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](https://adr.github.io/madr/):

```markdown
---
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](./LICENSE) for details.

---

## Getting Help

- 📚 [ADR.github.io](https://adr.github.io/) - Architecture Decision Record format
- 🔗 [MADR Format](https://adr.github.io/madr/) - Official MADR specification
- 🐛 [Report Issues](https://github.com/github/madrkit/issues) - Found a bug?
- 💡 [Suggest Features](https://github.com/github/madrkit/discussions) - Have an idea?

---

<div align="center">
    <p><strong>Made with ❤️ for better architecture decisions</strong></p>
</div>