Specialized skill for generating and managing Architecture Decision Records (ADRs). Supports Nygard, MADR, and custom templates with auto-numbering, linking, and status management.
Generates and manages Architecture Decision Records using Nygard, MADR, and custom templates with auto-numbering and status tracking.
npx claudepluginhub a5c-ai/babysitterThis skill is limited to using the following tools:
README.mdYou are adr-generator - a specialized skill for generating and managing Architecture Decision Records. This skill enables AI-powered decision documentation following industry-standard templates and practices.
This skill enables comprehensive ADR management including:
Generate ADRs using the classic Nygard format:
# 1. Record architecture decisions
Date: 2026-01-24
## Status
Accepted
## Context
We need to record the architectural decisions made on this project.
## Decision
We will use Architecture Decision Records, as described by Michael Nygard in his article.
## Consequences
See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools.
Generate ADRs using the Markdown Any Decision Records (MADR) format:
---
status: accepted
date: 2026-01-24
decision-makers: [John Doe, Jane Smith]
consulted: [Architecture Team, Security Team]
informed: [Engineering]
---
# Use PostgreSQL as Primary Database
## Context and Problem Statement
We need to select a primary database for the application. The database needs to handle OLTP workloads with complex queries and support ACID transactions.
## Decision Drivers
* Performance requirements: <100ms query latency at P99
* Data consistency requirements for financial transactions
* Developer familiarity and ecosystem support
* Operational complexity and cost
## Considered Options
* PostgreSQL
* MySQL
* MongoDB
* CockroachDB
## Decision Outcome
Chosen option: "PostgreSQL", because it best meets our requirements for complex queries, ACID compliance, and has strong team familiarity.
### Consequences
* Good, because PostgreSQL supports complex queries and joins efficiently
* Good, because ACID compliance ensures data integrity
* Good, because team has existing PostgreSQL expertise
* Bad, because horizontal scaling requires additional complexity (Citus/partitioning)
* Neutral, because operational costs are similar to alternatives
### Confirmation
We will measure query performance during load testing and review database operations after 3 months of production use.
## Pros and Cons of the Options
### PostgreSQL
* Good, because excellent query optimizer and JSON support
* Good, because mature ecosystem with many tools
* Bad, because complex replication setup
* Neutral, because licensing is permissive (PostgreSQL License)
### MySQL
* Good, because simple replication
* Bad, because limited JSON query capabilities
* Bad, because less sophisticated query optimizer
### MongoDB
* Good, because easy horizontal scaling
* Bad, because no ACID transactions across documents
* Bad, because eventual consistency issues
### CockroachDB
* Good, because distributed ACID by default
* Bad, because higher operational complexity
* Bad, because less mature ecosystem
## More Information
* [PostgreSQL Documentation](https://www.postgresql.org/docs/)
* Related to ADR-001: Use microservices architecture
* Supersedes ADR-003: Use MySQL (draft, never accepted)
# Directory structure
docs/
decisions/
0001-record-architecture-decisions.md
0002-use-postgresql-database.md
0003-adopt-event-sourcing.md
0004-use-kubernetes-deployment.md
index.md
graph.md
// Status transitions
const adrLifecycle = {
statuses: ['proposed', 'accepted', 'deprecated', 'superseded'],
transitions: {
proposed: ['accepted', 'rejected'],
accepted: ['deprecated', 'superseded'],
deprecated: [],
superseded: []
}
};
// Supersession linking
const supersessionExample = {
adr: 'ADR-0010',
status: 'superseded',
supersededBy: 'ADR-0015',
reason: 'Technology migration to new platform'
};
Generate an index of all ADRs:
# Architecture Decision Records
## Index
| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [ADR-0001](0001-record-architecture-decisions.md) | Record architecture decisions | Accepted | 2026-01-24 |
| [ADR-0002](0002-use-postgresql-database.md) | Use PostgreSQL as Primary Database | Accepted | 2026-01-24 |
| [ADR-0003](0003-adopt-event-sourcing.md) | Adopt Event Sourcing | Proposed | 2026-01-24 |
| [ADR-0004](0004-use-kubernetes-deployment.md) | Use Kubernetes for Deployment | Accepted | 2026-01-24 |
## By Status
### Accepted
- ADR-0001: Record architecture decisions
- ADR-0002: Use PostgreSQL as Primary Database
- ADR-0004: Use Kubernetes for Deployment
### Proposed
- ADR-0003: Adopt Event Sourcing
## Relationships
```mermaid
graph TD
ADR0001[ADR-0001: Record decisions]
ADR0002[ADR-0002: PostgreSQL]
ADR0003[ADR-0003: Event Sourcing]
ADR0004[ADR-0004: Kubernetes]
ADR0002 --> ADR0003
ADR0004 --> ADR0002
### 6. ADR Search and Analysis
```bash
# Search ADRs by keyword
adr-generator search "database" --status accepted
# List ADRs affecting a component
adr-generator list --tag database --tag persistence
# Show ADR history
adr-generator history ADR-0002
# Validate all ADRs
adr-generator validate --strict
This skill can leverage the following MCP servers:
| Server | Description | Installation |
|---|---|---|
| ADR Analysis MCP | AI-powered ADR analysis | mcpmarket.com |
| ADR Creator Skill | MADR template with AI extensions | mcpmarket.com |
anti_patterns:
- name: "Missing context"
description: "Decision without explaining the problem"
fix: "Always describe the context and forces"
- name: "No alternatives"
description: "Only one option considered"
fix: "Document at least 2-3 alternatives"
- name: "Orphaned ADR"
description: "ADR not linked to related decisions"
fix: "Always link related ADRs"
- name: "Never updated"
description: "Outdated ADR never superseded"
fix: "Review and update status regularly"
| Template | Use Case | Complexity |
|---|---|---|
| Nygard | Quick decisions, simple context | Low |
| MADR | Detailed analysis, multiple stakeholders | Medium |
| Y-Statements | Technical trade-offs | Low |
| Custom | Organization-specific requirements | Variable |
This skill integrates with the following processes:
adr-documentation.js - Primary ADR workflowsystem-design-review.js - Decision capture during reviewstech-stack-evaluation.js - Technology selection decisionsmigration-strategy.js - Migration decision documentationWhen generating ADRs, provide structured output:
{
"operation": "create",
"template": "madr",
"status": "success",
"adr": {
"number": "0005",
"title": "Use Redis for Caching",
"status": "proposed",
"path": "./docs/decisions/0005-use-redis-for-caching.md",
"date": "2026-01-24"
},
"relationships": {
"relatedTo": ["ADR-0002"],
"supersedes": null,
"supersededBy": null
},
"validation": {
"valid": true,
"warnings": [],
"errors": []
},
"artifacts": ["0005-use-redis-for-caching.md", "index.md"]
}
| Error | Cause | Resolution |
|---|---|---|
Duplicate ADR number | Number already exists | Use next available number |
Invalid status transition | Status change not allowed | Follow lifecycle rules |
Missing required field | Template field empty | Fill all required fields |
Broken reference | Referenced ADR not found | Fix or remove reference |
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.