# Decision Cli

> CLI tool and MCP server for managing Architectural Decision Records (ADRs). Works with Claude Code, Codex, Cursor, and any MCP-compatible AI agent.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kurdin-decision-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kurdin](https://agentstack.voostack.com/s/kurdin)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kurdin](https://github.com/kurdin)
- **Source:** https://github.com/kurdin/decision-cli

## Install

```sh
agentstack add mcp-kurdin-decision-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](#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:**

```markdown
# 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**

```bash
# Generate/update AGENTS.md
decision summary

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

Via MCP:
```json
{ "name": "decision_summary", "arguments": { "force": true } }
```

### Best Practices for AI Collaboration

1. **Initialize user identity first**
   ```bash
   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):**

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

**Global installation:**

```bash
npm install -g @aitool/decision-cli

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

### Initialize Your Project

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

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

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

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

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

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

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

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

```bash
# Global install
decision mcp

# Using npx
npx @aitool/decision-cli mcp
```

### Claude Code

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

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

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

Or if installed globally:

```json
{
  "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:

```json
{
  "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:**

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

**Create a new decision:**

```json
{
  "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):**

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

---

## Decision Record Format

Decisions are stored as Markdown files with YAML frontmatter:

```markdown
---
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 ]
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`:

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

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kurdin](https://github.com/kurdin)
- **Source:** [kurdin/decision-cli](https://github.com/kurdin/decision-cli)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kurdin-decision-cli
- Seller: https://agentstack.voostack.com/s/kurdin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.