{"_id":"@aitool/decision-cli","name":"@aitool/decision-cli","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aitool/decision-cli","version":"0.1.0","description":"CLI tool and MCP server for managing Architectural Decision Records (ADRs). Works with Claude Code, Codex, Cursor, and any MCP-compatible AI agent.","keywords":["adr","decision-records","cli","architecture","documentation","mcp","ai","agent","project-management","workflow"],"publishConfig":{"access":"public"},"license":"MIT","author":{"name":"Kurdin","url":"https://github.com/kurdin"},"repository":{"type":"git","url":"git+https://github.com/kurdin/decision-cli.git"},"homepage":"https://github.com/kurdin/decision-cli#readme","bugs":{"url":"https://github.com/kurdin/decision-cli/issues"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"bin":{"decision":"bin/decision.js","decision-cli":"bin/decision.js"},"scripts":{"lint":"eslint src/","lint:fix":"eslint src/ --fix","check":"npm run lint && tsc -p tsconfig.json --noEmit","build":"node build.js","dev":"tsc --watch","dev:cli":"npm run build && node bin/decision.js","test":"vitest run","test:watch":"vitest","test:ui":"vitest --ui","test:coverage":"vitest --coverage","prepublishOnly":"npm run build"},"engines":{"node":">=20.19.0"},"devDependencies":{"@types/node":"24.10.9","@vitest/ui":"^3.2.4","eslint":"^9.39.2","typescript":"^5.9.3","typescript-eslint":"^8.54.0","vitest":"^3.2.4"},"dependencies":{"@inquirer/core":"^10.3.2","@inquirer/prompts":"^7.10.1","@modelcontextprotocol/sdk":"^1.25.3","chalk":"^5.6.2","commander":"^14.0.2","fast-glob":"^3.3.3","gray-matter":"^4.0.3","ora":"^8.2.0","yaml":"^2.8.2","zod":"^4.3.6"},"_id":"@aitool/decision-cli@0.1.0","gitHead":"1394f5306b7ad6c7fceae2642bfdfe11f90a9341","_nodeVersion":"22.19.0","_npmVersion":"10.4.0","dist":{"integrity":"sha512-2eX4NMmdb7uL7OcOkyfWixOBSYuPrrAWrjSNxBhzEMYYKhxyI5zDdOP3H9lYbJgV+g8DyYGJd8yIjSl6GRbDXA==","shasum":"5cfab3ab2025b7ef3b5cdd41f8d3c0ecb8aa7de1","tarball":"https://registry.npmjs.org/@aitool/decision-cli/-/decision-cli-0.1.0.tgz","fileCount":74,"unpackedSize":202970,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICREciJKU9ZvronHkgubUEkB+1yf63qngSKy+pRuKy9VAiBu4j2jyHhu26F5VKC6laqpOx7Nb0zosqeuIiGj3unDmg=="}]},"_npmUser":{"name":"kurdin","email":"skurdin@yahoo.com"},"directories":{},"maintainers":[{"name":"kurdin","email":"skurdin@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/decision-cli_0.1.0_1770781899672_0.8988422895260841"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-11T03:51:39.579Z","0.1.0":"2026-02-11T03:51:39.825Z","modified":"2026-02-11T03:51:40.163Z"},"maintainers":[{"name":"kurdin","email":"skurdin@yahoo.com"}],"description":"CLI tool and MCP server for managing Architectural Decision Records (ADRs). Works with Claude Code, Codex, Cursor, and any MCP-compatible AI agent.","homepage":"https://github.com/kurdin/decision-cli#readme","keywords":["adr","decision-records","cli","architecture","documentation","mcp","ai","agent","project-management","workflow"],"repository":{"type":"git","url":"git+https://github.com/kurdin/decision-cli.git"},"author":{"name":"Kurdin","url":"https://github.com/kurdin"},"bugs":{"url":"https://github.com/kurdin/decision-cli/issues"},"license":"MIT","readme":"# Decision CLI\n\n**Track architectural decisions with AI assistance. Organize by domain, manage team workflows, integrate seamlessly with any MCP client.**\n\nA 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.\n\n##### [Skip to Quick Setup](#quick-setup)\n\n## Key Advantages\n\n**Simplicity**: Zero-config initialization with smart defaults\n**Organization**: Domain-based structure keeps decisions discoverable\n**Workflow**: Built-in team review process (draft → proposed → accepted)\n**AI-Native**: 11 MCP tools enable AI agents to manage decisions directly\n\n### Simple Setup & Operation\n\n- **One command init** - `decision init` creates everything you need\n- **Smart ID generation** - Automatic sequential IDs with customizable prefixes\n- **Subdirectory-friendly** - Run from anywhere in your repo, auto-finds `.decision/`\n- **Git-aware user identity** - Auto-detects your name/email for approvals\n\n### Team Workflow Support\n\n- **Status lifecycle** - draft → proposed → accepted/rejected → deprecated/superseded\n- **Approval tracking** - Records who approved/rejected and when\n- **Relationship linking** - Connect related decisions, track supersession chains\n- **Validation checks** - Ensure decisions have required sections before acceptance\n\n### AI Agent Integration\n\n- **11 MCP tools** - Complete CRUD + workflow operations for AI agents\n- **Works with any MCP client** - Claude Code, Codex, Cursor, Windsurf, Cline, etc.\n- **AGENTS.md generation** - Auto-generated summary for AI context\n- **User identity management** - Configured approver used automatically by AI\n\n## Complete Feature Set\n\n### Core Decision Management\n\n- **Create decisions** interactively or programmatically with templates\n- **List and filter** by status, domain, or tags\n- **Search** across all decision content with relevance scoring\n- **Show** full decision details with frontmatter and content\n- **Export** to JSON or HTML for external tools\n\n### Status Workflow\n\n- **Propose** - Submit draft for team review\n- **Accept/Reject** - Record approval with approver identity\n- **Reopen** - Return rejected decisions to draft\n- **Deprecate** - Mark outdated decisions\n- **Supersede** - Replace old decisions with new ones (auto-links both)\n\n### Organization & Discovery\n\n- **Domain-based folders** - Group by area (auth, frontend, backend, etc.)\n- **Custom templates** - Default and security templates included\n- **Relationship graph** - Visualize decision connections (ASCII, DOT, JSON)\n- **Git history** - View change history for any decision\n\n### Configuration & Validation\n\n- **Customizable ID format** - `PRJ-0001`, `ADR-0001`, etc.\n- **Domain management** - Add/remove domains dynamically\n- **Validation rules** - Check for missing sections, empty content\n- **Format normalization** - Consistent formatting for clean diffs\n\n---\n\n## Working with AI Agents\n\nDecision CLI is designed for seamless AI collaboration. Once configured, you can ask your AI assistant to manage decisions using natural language.\n\n### Why Use AI for Decision Management?\n\n- **Faster documentation** - AI drafts decisions from conversation context\n- **Consistent format** - AI follows templates automatically\n- **Instant search** - AI finds relevant decisions before suggesting changes\n- **Automatic relationships** - AI links related decisions as it creates them\n- **Review assistance** - AI validates decisions before proposing\n\n### Natural Language Examples\n\nOnce the MCP server is configured, you can simply ask:\n\n**Creating decisions:**\n```\n\"Create a decision to use Redis for caching in the backend domain\"\n\n\"Document our choice to use TypeScript strict mode\"\n\n\"Add an architectural decision for the new authentication flow we just discussed\"\n```\n\n**Querying decisions:**\n```\n\"What decisions have we made about authentication?\"\n\n\"Show me all accepted backend decisions\"\n\n\"Are there any decisions related to caching?\"\n\n\"List deprecated decisions that might need review\"\n```\n\n**Updating decisions:**\n```\n\"Update the JWT decision to include the new refresh token strategy\"\n\n\"Mark decision 5 as accepted\"\n\n\"Link the Redis caching decision to the session management decision\"\n\n\"Deprecate the old MongoDB decision since we switched to PostgreSQL\"\n```\n\n**Workflow management:**\n```\n\"Propose decision 3 for team review\"\n\n\"Accept all proposed decisions in the auth domain\"\n\n\"What decisions are waiting for approval?\"\n```\n\n### The AGENTS.md Summary\n\nThe `AGENTS.md` file is a special summary designed specifically for AI agents. It provides:\n\n**Instant Context**\n- Complete catalog of all decisions organized by domain\n- Status overview (how many accepted, proposed, deprecated)\n- Recent decisions for quick reference\n\n**AI-Optimized Format**\n- Structured for fast parsing by language models\n- Includes decision relationships and supersession chains\n- Tags and metadata for semantic search\n\n**Always Current**\n- Regenerate anytime with `decision summary`\n- Only updates when decisions actually change (unless `--force`)\n- Tracks last generation timestamp\n\n**How AI Uses AGENTS.md**\n\nWhen you ask an AI assistant about your project's architecture:\n\n1. AI reads `.decision/AGENTS.md` for complete decision context\n2. AI understands what choices have been made and why\n3. AI avoids suggesting approaches that contradict existing decisions\n4. AI references relevant decisions when proposing changes\n\n**Example AGENTS.md content:**\n\n```markdown\n# Decision Records Summary\n\n> Auto-generated summary for AI agents. Last updated: 2024-01-30T10:30:00Z\n\n## Overview\n\n- **Total Decisions:** 15\n- **Accepted:** 12\n- **Proposed:** 2\n- **Draft:** 1\n\n## By Domain\n\n### auth (3 decisions)\n- [PRJ-0001] Use JWT for Authentication (accepted)\n- [PRJ-0005] Implement MFA with TOTP (accepted)\n- [PRJ-0010] Session Management Strategy (proposed)\n\n### backend (4 decisions)\n- [PRJ-0003] Use PostgreSQL for Primary Database (accepted)\n- [PRJ-0007] Use Redis for Caching (accepted)\n...\n\n## Recent Decisions\n\n1. PRJ-0015: API Versioning Strategy (2024-01-28) - proposed\n2. PRJ-0014: Error Handling Standards (2024-01-25) - accepted\n...\n\n## Relationships\n\n- PRJ-0010 supersedes PRJ-0001\n- PRJ-0007 related to PRJ-0003, PRJ-0010\n```\n\n**Generating the Summary**\n\n```bash\n# Generate/update AGENTS.md\ndecision summary\n\n# Force regeneration (updates timestamp even if unchanged)\ndecision summary --force\n```\n\nVia MCP:\n```json\n{ \"name\": \"decision_summary\", \"arguments\": { \"force\": true } }\n```\n\n### Best Practices for AI Collaboration\n\n1. **Initialize user identity first**\n   ```bash\n   decision user setup\n   ```\n   This ensures AI-created approvals use your real name/email.\n\n2. **Keep AGENTS.md in version control**\n   The summary helps all team members' AI assistants stay consistent.\n\n3. **Reference decisions in prompts**\n   \"According to PRJ-0003, we use PostgreSQL. How should we handle...\"\n\n4. **Let AI validate before accepting**\n   Ask: \"Validate all proposed decisions and show any issues\"\n\n5. **Use domains consistently**\n   Well-organized domains help AI find relevant context faster.\n\n---\n\n## Quick Setup\n\n### Prerequisites\n\n- Node.js >= 20.19.0\n\n### Installation\n\n**Using npx (no install required):**\n\n```bash\nnpx @aitool/decision-cli init\nnpx @aitool/decision-cli new\nnpx @aitool/decision-cli list\n```\n\n**Global installation:**\n\n```bash\nnpm install -g @aitool/decision-cli\n\n# Now use 'decision' command anywhere\ndecision init\ndecision new\ndecision list\n```\n\n### Initialize Your Project\n\n```bash\n# Initialize with auto-detected prefix from package.json\ndecision init\n\n# Or specify a custom prefix\ndecision init --prefix ADR\n```\n\nThis creates:\n\n```\n.decision/\n├── config.yaml           # Configuration\n├── templates/\n│   ├── default.md        # Standard template\n│   └── security.md       # Security-focused template\n└── general/              # Default domain folder\n```\n\n### Configure User Identity\n\nSet up your identity for decision approvals:\n\n```bash\n# Auto-detect from git config\ndecision user setup\n\n# Or specify manually\ndecision user setup --name \"Your Name\" --email \"you@example.com\"\n```\n\n---\n\n## CLI Usage\n\n### Creating Decisions\n\n```bash\n# Interactive mode (prompts for title, domain, template)\ndecision new\n\n# Non-interactive with options\ndecision new --title \"Use Redis for Caching\" --domain backend --no-interactive\n```\n\n### Listing & Viewing\n\n```bash\n# List all decisions\ndecision list\n\n# Filter by status\ndecision list --status accepted\n\n# Filter by domain\ndecision list --domain auth\n\n# Show specific decision (by ID or number)\ndecision show 1\ndecision show PRJ-0001\n\n# Search across all decisions\ndecision search \"authentication\"\n```\n\n### Status Workflow\n\n```bash\n# Submit for review\ndecision propose 1\n\n# Accept (uses configured user identity)\ndecision accept 1\n\n# Reject with reason\ndecision reject 1 --reason \"Needs more analysis\"\n\n# Reopen rejected decision\ndecision reopen 1\n\n# Mark as deprecated\ndecision deprecate 1\n\n# Supersede with new decision\ndecision supersede 1 2\n```\n\n### Relationships\n\n```bash\n# Link related decisions\ndecision link 1 2\n\n# Remove link\ndecision unlink 1 2\n\n# View relationship graph\ndecision graph\ndecision graph --format dot  # For GraphViz\n```\n\n### Validation & Export\n\n```bash\n# Validate all decisions\ndecision validate\n\n# Validate specific decision\ndecision validate --id 1\n\n# Generate AGENTS.md summary\ndecision summary\n\n# Export to JSON\ndecision export --format json --output decisions.json\n```\n\n### Configuration\n\n```bash\n# Show all config\ndecision config\n\n# Get specific value\ndecision config get id-format\n\n# Set value\ndecision config set default-domain backend\n\n# Add new domain\ndecision config add-domain infrastructure\n\n# Repair next-id cache\ndecision config repair\n```\n\n---\n\n## MCP Integration\n\nThe MCP server allows AI tools to manage decisions directly through the Model Context Protocol.\n\n### Starting the MCP Server\n\n```bash\n# Global install\ndecision mcp\n\n# Using npx\nnpx @aitool/decision-cli mcp\n```\n\n### Claude Code\n\n```bash\n# Add MCP server (recommended — uses npx, no global install needed)\nclaude mcp add decision -- npx @aitool/decision-cli mcp\n\n# Or if installed globally\nclaude mcp add decision -- decision mcp\n\n# Verify it's registered\nclaude mcp list\n\n# Remove when no longer needed\nclaude mcp remove decision\n```\n\nOnce added, just talk to Claude naturally:\n\n```\nYou: \"Create a decision to use Redis for caching in the backend domain\"\nYou: \"What decisions have we made about authentication?\"\nYou: \"Mark decision 3 as accepted\"\n```\n\n### Codex (OpenAI)\n\n```bash\n# Add MCP server\ncodex mcp add decision -- npx @aitool/decision-cli mcp\n\n# Or if installed globally\ncodex mcp add decision -- decision mcp\n\n# Verify\ncodex mcp list\n```\n\nThen use naturally in your Codex sessions:\n\n```\nYou: \"List all accepted decisions in the auth domain\"\nYou: \"Create a decision for the new authentication flow\"\n```\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"decision\": {\n      \"command\": \"npx\",\n      \"args\": [\"@aitool/decision-cli\", \"mcp\"],\n      \"cwd\": \"/path/to/your/project\"\n    }\n  }\n}\n```\n\nOr if installed globally:\n\n```json\n{\n  \"mcpServers\": {\n    \"decision\": {\n      \"command\": \"decision\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n### Cursor / Windsurf / Cline / Other MCP Clients\n\nMost MCP clients use the same JSON configuration format. Add to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"decision\": {\n      \"command\": \"npx\",\n      \"args\": [\"@aitool/decision-cli\", \"mcp\"],\n      \"cwd\": \"/path/to/your/project\"\n    }\n  }\n}\n```\n\nKey settings for any MCP client:\n\n- **Command**: `npx` (or `decision` if installed globally)\n- **Args**: `[\"@aitool/decision-cli\", \"mcp\"]` (or `[\"mcp\"]` if global)\n- **CWD**: Your project root (where `.decision/` exists or should be created)\n\n### Available MCP Tools\n\n| Tool                  | Description                                          |\n| --------------------- | ---------------------------------------------------- |\n| `decision_list`       | List decisions with optional status/domain/tag filter |\n| `decision_get`        | Get decision by ID (full or numeric shorthand)       |\n| `decision_create`     | Create new decision (non-interactive)                |\n| `decision_update`     | Update frontmatter and/or content                    |\n| `decision_status`     | Change status (propose/accept/reject/etc.)           |\n| `decision_search`     | Search by free-text query                            |\n| `decision_summary`    | Generate/update AGENTS.md                            |\n| `decision_validate`   | Validate decisions and return issues                 |\n| `decision_graph`      | Get relationship graph (JSON or DOT)                 |\n| `decision_user_setup` | Configure user identity for approvals                |\n| `decision_user_show`  | Display current user configuration                   |\n\n### MCP Tool Examples\n\n**List accepted decisions:**\n\n```json\n{ \"name\": \"decision_list\", \"arguments\": { \"status\": \"accepted\" } }\n```\n\n**Create a new decision:**\n\n```json\n{\n  \"name\": \"decision_create\",\n  \"arguments\": {\n    \"title\": \"Use PostgreSQL for Primary Database\",\n    \"domain\": \"backend\",\n    \"content\": \"## Context\\n\\nWe need a reliable relational database...\\n\\n## Decision\\n\\nUse PostgreSQL...\\n\\n## Consequences\\n\\n### Positive\\n- ACID compliance...\"\n  }\n}\n```\n\n**Accept a decision (uses configured user identity):**\n\n```json\n{ \"name\": \"decision_status\", \"arguments\": { \"id\": \"1\", \"status\": \"accepted\" } }\n```\n\n---\n\n## Decision Record Format\n\nDecisions are stored as Markdown files with YAML frontmatter:\n\n```markdown\n---\nid: PRJ-0001\ntitle: Use JWT for Authentication\nstatus: accepted\ndate: 2024-01-28\ndomain: auth\ndeciders: [john, sarah]\ntags: [security, api]\nrelated: [PRJ-0003]\napproved-by: [John Doe <john@example.com>]\napproved-date: 2024-01-30\n---\n\n## Context\n\nOur API needs stateless authentication for horizontal scaling...\n\n## Decision\n\nWe will use JWT tokens with RS256 signing algorithm...\n\n## Consequences\n\n### Positive\n\n- Stateless authentication scales horizontally\n- No session storage required\n\n### Negative\n\n- Token revocation requires deny-list implementation\n```\n\n### Decision Lifecycle\n\n```\ndraft → proposed → accepted → [deprecated | superseded]\n              ↘ rejected → draft (reopen)\n```\n\n---\n\n## Folder Structure\n\n```\n.decision/\n├── config.yaml           # Project configuration\n├── user.yaml             # User identity (git-ignored)\n├── AGENTS.md             # Auto-generated AI summary\n├── templates/\n│   ├── default.md        # Standard template\n│   └── security.md       # Security template\n├── auth/                 # Domain: auth\n│   ├── PRJ-0001-jwt-auth.md\n│   └── PRJ-0005-mfa.md\n├── frontend/             # Domain: frontend\n│   └── PRJ-0002-use-react.md\n├── backend/              # Domain: backend\n│   └── PRJ-0003-use-postgres.md\n└── general/              # Default domain\n    └── PRJ-0004-coding-standards.md\n```\n\n---\n\n## Configuration Reference\n\n`.decision/config.yaml`:\n\n```yaml\nversion: 1\nproject-name: my-project\nid-format: \"PRJ-{number}\"\nid-padding: 4\ndomains:\n  - auth\n  - frontend\n  - backend\n  - general\ndefault-domain: general\ntemplates:\n  default: templates/default.md\n  security: templates/security.md\ndomain-templates:\n  auth: security\nsummary:\n  auto-generate: false\n  include-insights: true\n  include-recent: 5\n```\n\n### Configuration Options\n\n| Key               | Description                              | Default               |\n| ----------------- | ---------------------------------------- | --------------------- |\n| `project-name`    | Project identifier                       | From package.json     |\n| `id-format`       | ID pattern (`{number}` placeholder)      | `PRJ-{number}`        |\n| `id-padding`      | Zero-padding for numbers                 | 4                     |\n| `domains`         | Available domain categories              | `[general]`           |\n| `default-domain`  | Domain when not specified                | `general`             |\n| `templates`       | Named template mappings                  | `default`, `security` |\n| `domain-templates`| Default template per domain              | -                     |\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnode bin/decision.js --help\n```\n\n```bash\nnpm run build        # Build TypeScript\nnpm run dev          # Watch mode\nnpm test             # Run tests\nnpm run test:watch   # Tests in watch mode\nnpm run lint         # Lint code\nnpm run check        # Lint + type check\n```\n\n### Local Testing\n\n```bash\nnpm link\ndecision --help      # Now available globally\nnpm unlink -g @aitool/decision-cli  # When done\n```\n\n---\n\n## License\n\nMIT - see [LICENSE](./LICENSE)\n\nCreated by [Kurdin](https://github.com/kurdin)\n","readmeFilename":"README.md","_rev":"1-bf98e7777749e4422c0f3d633a764640"}