Decision CLI

Track architectural decisions with AI assistance. Organize by domain, manage team workflows, integrate seamlessly with any MCP client.

A comprehensive CLI tool and MCP server for managing Architectural Decision Records (ADRs). Works standalone via command line or integrates directly with AI tools like Claude Code, Codex, Cursor, Windsurf, and any MCP-compatible client.

Skip to Quick Setup

Key Advantages

Simplicity: Zero-config initialization with smart defaults Organization: Domain-based structure keeps decisions discoverable Workflow: Built-in team review process (draft → proposed → accepted) AI-Native: 11 MCP tools enable AI agents to manage decisions directly

Simple Setup & Operation

• One command init - decision init creates everything you need
• Smart ID generation - Automatic sequential IDs with customizable prefixes
• Subdirectory-friendly - Run from anywhere in your repo, auto-finds .decision/
• Git-aware user identity - Auto-detects your name/email for approvals

Team Workflow Support

• Status lifecycle - draft → proposed → accepted/rejected → deprecated/superseded
• Approval tracking - Records who approved/rejected and when
• Relationship linking - Connect related decisions, track supersession chains
• Validation checks - Ensure decisions have required sections before acceptance

AI Agent Integration

• 11 MCP tools - Complete CRUD + workflow operations for AI agents
• Works with any MCP client - Claude Code, Codex, Cursor, Windsurf, Cline, etc.
• AGENTS.md generation - Auto-generated summary for AI context
• User identity management - Configured approver used automatically by AI

Complete Feature Set

Core Decision Management

• Create decisions interactively or programmatically with templates
• List and filter by status, domain, or tags
• Search across all decision content with relevance scoring
• Show full decision details with frontmatter and content
• Export to JSON or HTML for external tools

Status Workflow

• Propose - Submit draft for team review
• Accept/Reject - Record approval with approver identity
• Reopen - Return rejected decisions to draft
• Deprecate - Mark outdated decisions
• Supersede - Replace old decisions with new ones (auto-links both)

Organization & Discovery

• Domain-based folders - Group by area (auth, frontend, backend, etc.)
• Custom templates - Default and security templates included
• Relationship graph - Visualize decision connections (ASCII, DOT, JSON)
• Git history - View change history for any decision

Configuration & Validation

• Customizable ID format - PRJ-0001, ADR-0001, etc.
• Domain management - Add/remove domains dynamically
• Validation rules - Check for missing sections, empty content
• Format normalization - Consistent formatting for clean diffs

---

Working with AI Agents

Decision CLI is designed for seamless AI collaboration. Once configured, you can ask your AI assistant to manage decisions using natural language.

Why Use AI for Decision Management?

• Faster documentation - AI drafts decisions from conversation context
• Consistent format - AI follows templates automatically
• Instant search - AI finds relevant decisions before suggesting changes
• Automatic relationships - AI links related decisions as it creates them
• Review assistance - AI validates decisions before proposing

Natural Language Examples

Once the MCP server is configured, you can simply ask:

Creating decisions:

"Create a decision to use Redis for caching in the backend domain"

"Document our choice to use TypeScript strict mode"

"Add an architectural decision for the new authentication flow we just discussed"

Querying decisions:

"What decisions have we made about authentication?"

"Show me all accepted backend decisions"

"Are there any decisions related to caching?"

"List deprecated decisions that might need review"

Updating decisions:

"Update the JWT decision to include the new refresh token strategy"

"Mark decision 5 as accepted"

"Link the Redis caching decision to the session management decision"

"Deprecate the old MongoDB decision since we switched to PostgreSQL"

Workflow management:

"Propose decision 3 for team review"

"Accept all proposed decisions in the auth domain"

"What decisions are waiting for approval?"

The AGENTS.md Summary

The AGENTS.md file is a special summary designed specifically for AI agents. It provides:

Instant Context

• Complete catalog of all decisions organized by domain
• Status overview (how many accepted, proposed, deprecated)
• Recent decisions for quick reference

AI-Optimized Format

• Structured for fast parsing by language models
• Includes decision relationships and supersession chains
• Tags and metadata for semantic search

Always Current

• Regenerate anytime with decision summary
• Only updates when decisions actually change (unless --force)
• Tracks last generation timestamp

How AI Uses AGENTS.md

When you ask an AI assistant about your project's architecture:

1. AI reads .decision/AGENTS.md for complete decision context
2. AI understands what choices have been made and why
3. AI avoids suggesting approaches that contradict existing decisions
4. AI references relevant decisions when proposing changes

Example AGENTS.md content:

# Decision Records Summary

> Auto-generated summary for AI agents. Last updated: 2024-01-30T10:30:00Z

## Overview

- **Total Decisions:** 15
- **Accepted:** 12
- **Proposed:** 2
- **Draft:** 1

## By Domain

### auth (3 decisions)
- [PRJ-0001] Use JWT for Authentication (accepted)
- [PRJ-0005] Implement MFA with TOTP (accepted)
- [PRJ-0010] Session Management Strategy (proposed)

### backend (4 decisions)
- [PRJ-0003] Use PostgreSQL for Primary Database (accepted)
- [PRJ-0007] Use Redis for Caching (accepted)
...

## Recent Decisions

1. PRJ-0015: API Versioning Strategy (2024-01-28) - proposed
2. PRJ-0014: Error Handling Standards (2024-01-25) - accepted
...

## Relationships

- PRJ-0010 supersedes PRJ-0001
- PRJ-0007 related to PRJ-0003, PRJ-0010

Generating the Summary

# Generate/update AGENTS.md
decision summary

# Force regeneration (updates timestamp even if unchanged)
decision summary --force

Via MCP:

{ "name": "decision_summary", "arguments": { "force": true } }

Best Practices for AI Collaboration

1. Initialize user identity first

   decision user setup

   This ensures AI-created approvals use your real name/email.

2. Keep AGENTS.md in version control The summary helps all team members' AI assistants stay consistent.

3. Reference decisions in prompts "According to PRJ-0003, we use PostgreSQL. How should we handle..."

4. Let AI validate before accepting Ask: "Validate all proposed decisions and show any issues"

5. Use domains consistently Well-organized domains help AI find relevant context faster.

---

Quick Setup

Prerequisites

• Node.js >= 20.19.0

Installation

Using npx (no install required):

npx @aitool/decision-cli init
npx @aitool/decision-cli new
npx @aitool/decision-cli list

Global installation:

npm install -g @aitool/decision-cli

# Now use 'decision' command anywhere
decision init
decision new
decision list

Initialize Your Project

# Initialize with auto-detected prefix from package.json
decision init

# Or specify a custom prefix
decision init --prefix ADR

This creates:

.decision/
├── config.yaml           # Configuration
├── templates/
│   ├── default.md        # Standard template
│   └── security.md       # Security-focused template
└── general/              # Default domain folder

Configure User Identity

Set up your identity for decision approvals:

# Auto-detect from git config
decision user setup

# Or specify manually
decision user setup --name "Your Name" --email "you@example.com"

---

CLI Usage

Creating Decisions

# Interactive mode (prompts for title, domain, template)
decision new

# Non-interactive with options
decision new --title "Use Redis for Caching" --domain backend --no-interactive

Listing & Viewing

# List all decisions
decision list

# Filter by status
decision list --status accepted

# Filter by domain
decision list --domain auth

# Show specific decision (by ID or number)
decision show 1
decision show PRJ-0001

# Search across all decisions
decision search "authentication"

Status Workflow

# Submit for review
decision propose 1

# Accept (uses configured user identity)
decision accept 1

# Reject with reason
decision reject 1 --reason "Needs more analysis"

# Reopen rejected decision
decision reopen 1

# Mark as deprecated
decision deprecate 1

# Supersede with new decision
decision supersede 1 2

Relationships

# Link related decisions
decision link 1 2

# Remove link
decision unlink 1 2

# View relationship graph
decision graph
decision graph --format dot  # For GraphViz

Validation & Export

# Validate all decisions
decision validate

# Validate specific decision
decision validate --id 1

# Generate AGENTS.md summary
decision summary

# Export to JSON
decision export --format json --output decisions.json

Configuration

# Show all config
decision config

# Get specific value
decision config get id-format

# Set value
decision config set default-domain backend

# Add new domain
decision config add-domain infrastructure

# Repair next-id cache
decision config repair

---

MCP Integration

The MCP server allows AI tools to manage decisions directly through the Model Context Protocol.

Starting the MCP Server

# Global install
decision mcp

# Using npx
npx @aitool/decision-cli mcp

Claude Code

# Add MCP server (recommended — uses npx, no global install needed)
claude mcp add decision -- npx @aitool/decision-cli mcp

# Or if installed globally
claude mcp add decision -- decision mcp

# Verify it's registered
claude mcp list

# Remove when no longer needed
claude mcp remove decision

Once added, just talk to Claude naturally:

You: "Create a decision to use Redis for caching in the backend domain"
You: "What decisions have we made about authentication?"
You: "Mark decision 3 as accepted"

Codex (OpenAI)

# Add MCP server
codex mcp add decision -- npx @aitool/decision-cli mcp

# Or if installed globally
codex mcp add decision -- decision mcp

# Verify
codex mcp list

Then use naturally in your Codex sessions:

You: "List all accepted decisions in the auth domain"
You: "Create a decision for the new authentication flow"

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "decision": {
      "command": "npx",
      "args": ["@aitool/decision-cli", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "decision": {
      "command": "decision",
      "args": ["mcp"]
    }
  }
}

Cursor / Windsurf / Cline / Other MCP Clients

Most MCP clients use the same JSON configuration format. Add to your MCP settings:

{
  "mcpServers": {
    "decision": {
      "command": "npx",
      "args": ["@aitool/decision-cli", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Key settings for any MCP client:

• Command: npx (or decision if installed globally)
• Args: ["@aitool/decision-cli", "mcp"] (or ["mcp"] if global)
• CWD: Your project root (where .decision/ exists or should be created)

Available MCP Tools

Tool	Description
decision_list	List decisions with optional status/domain/tag filter
decision_get	Get decision by ID (full or numeric shorthand)
decision_create	Create new decision (non-interactive)
decision_update	Update frontmatter and/or content
decision_status	Change status (propose/accept/reject/etc.)
decision_search	Search by free-text query
decision_summary	Generate/update AGENTS.md
decision_validate	Validate decisions and return issues
decision_graph	Get relationship graph (JSON or DOT)
decision_user_setup	Configure user identity for approvals
decision_user_show	Display current user configuration

MCP Tool Examples

List accepted decisions:

{ "name": "decision_list", "arguments": { "status": "accepted" } }

Create a new decision:

{
  "name": "decision_create",
  "arguments": {
    "title": "Use PostgreSQL for Primary Database",
    "domain": "backend",
    "content": "## Context\n\nWe need a reliable relational database...\n\n## Decision\n\nUse PostgreSQL...\n\n## Consequences\n\n### Positive\n- ACID compliance..."
  }
}

Accept a decision (uses configured user identity):

{ "name": "decision_status", "arguments": { "id": "1", "status": "accepted" } }

---

Decision Record Format

Decisions are stored as Markdown files with YAML frontmatter:

---
id: PRJ-0001
title: Use JWT for Authentication
status: accepted
date: 2024-01-28
domain: auth
deciders: [john, sarah]
tags: [security, api]
related: [PRJ-0003]
approved-by: [John Doe <john@example.com>]
approved-date: 2024-01-30
---

## Context

Our API needs stateless authentication for horizontal scaling...

## Decision

We will use JWT tokens with RS256 signing algorithm...

## Consequences

### Positive

- Stateless authentication scales horizontally
- No session storage required

### Negative

- Token revocation requires deny-list implementation

Decision Lifecycle

draft → proposed → accepted → [deprecated | superseded]
              ↘ rejected → draft (reopen)

---

Folder Structure

.decision/
├── config.yaml           # Project configuration
├── user.yaml             # User identity (git-ignored)
├── AGENTS.md             # Auto-generated AI summary
├── templates/
│   ├── default.md        # Standard template
│   └── security.md       # Security template
├── auth/                 # Domain: auth
│   ├── PRJ-0001-jwt-auth.md
│   └── PRJ-0005-mfa.md
├── frontend/             # Domain: frontend
│   └── PRJ-0002-use-react.md
├── backend/              # Domain: backend
│   └── PRJ-0003-use-postgres.md
└── general/              # Default domain
    └── PRJ-0004-coding-standards.md

---

Configuration Reference

.decision/config.yaml:

version: 1
project-name: my-project
id-format: "PRJ-{number}"
id-padding: 4
domains:
  - auth
  - frontend
  - backend
  - general
default-domain: general
templates:
  default: templates/default.md
  security: templates/security.md
domain-templates:
  auth: security
summary:
  auto-generate: false
  include-insights: true
  include-recent: 5

Configuration Options

Key	Description	Default
project-name	Project identifier	From package.json
id-format	ID pattern ({number} placeholder)	PRJ-{number}
id-padding	Zero-padding for numbers	4
domains	Available domain categories	[general]
default-domain	Domain when not specified	general
templates	Named template mappings	default, security
domain-templates	Default template per domain	-

---

Development

npm install
npm run build
node bin/decision.js --help

npm run build        # Build TypeScript
npm run dev          # Watch mode
npm test             # Run tests
npm run test:watch   # Tests in watch mode
npm run lint         # Lint code
npm run check        # Lint + type check

Local Testing

npm link
decision --help      # Now available globally
npm unlink -g @aitool/decision-cli  # When done

---

License

MIT - see LICENSE

Created by Kurdin