From project-toolkit
Generates Architectural Decision Records (ADRs) by detecting project template conventions, assigning sequential numbers, supporting MADR/Nygard/Alexandrian formats, and saving markdown files. Use for documenting technical decisions.
npx claudepluginhub rjmurillo/ai-agents --plugin project-toolkitThis skill uses the workspace's default tool permissions.
Create well-structured Architectural Decision Records that document technical decisions with clear context, rationale, consequences, and alternatives.
Generates Architectural Decision Records (ADRs) in MADR, Nygard, Alexandrian, or project formats. Researches directory for conventions, gathers context, numbers sequentially, validates, and saves. Use for documenting technical decisions.
Creates new Architecture Decision Records (ADRs) for architectural changes using repo conventions for naming, numbering, and storage. Use when documenting decisions, rationale, and trade-offs.
Creates Architecture Decision Records (ADRs) documenting technical decisions, context, alternatives considered, and consequences. Use for architectural choices, library/framework selections, or system component designs.
Share bugs, ideas, or general feedback.
Create well-structured Architectural Decision Records that document technical decisions with clear context, rationale, consequences, and alternatives.
| Trigger Phrase | Operation |
|---|---|
create an ADR | Full ADR generation workflow |
generate ADR | Full ADR generation workflow |
write an architecture decision record | Full ADR generation workflow |
new ADR for | Targeted ADR for a specific decision |
document this architecture decision | Full ADR generation workflow |
# These all work:
create an ADR for database selection
new ADR for authentication strategy
document this architecture decision about event sourcing
generate ADR for switching from REST to gRPC
| Situation | Use This Skill? |
|---|---|
| New architectural decision needs documenting | Yes |
| Changing an existing system or pattern | Yes (includes Prior Art Investigation) |
| Reviewing or validating an existing ADR | No, use adr-review skill |
| Minor implementation detail, not architectural | No |
Collect required information from the user:
If any required information is missing, ask the user before proceeding.
Significance check: Before proceeding, quickly assess whether the decision warrants an ADR using the ASR Test. If the decision is trivially reversible, purely local, and has no stakeholder concern, suggest skipping the ADR.
Readiness check: Verify the decision passes the START Definition of Ready: Stakeholders known, Time (Most Responsible Moment) has come, Alternatives exist, Requirements understood, Template will be determined in G2.
If the decision changes an existing system, trigger Prior Art Investigation using the chestertons-fence skill or manually gather: what exists, why it was built that way, and why change now.
Discover the ADR destination, naming convention, numbering, and template by exploring the codebase.
Explore the codebase to find where ADRs live. Do not assume a fixed location.
ADR-*.md, adr-*.md, 0*-*.md in directories named decisions, adr, architecture).agents/architecture/, docs/adr/, docs/architecture/, docs/decisions/, architecture/decisions/.adr-dir files (used by adr-tools) or ADR references in README, CONTRIBUTING, or project documentationNote: .agents/architecture/ and docs/architecture/ are monitored by adr-review for auto-triggered review. ADRs in other directories require manual adr-review invocation.
If the directory contains existing ADRs:
ADR-NNN-slug.md vs 0NNN-slug.md), and section structureadr-review auto-triggers only match uppercase ADR-*.md patterns. If existing ADRs use lowercase, warn the user that auto-review will not triggerADR-TEMPLATE.md, template.md) in the same directory or a parentIf no ADRs or template files exist anywhere in the codebase:
.agents/architecture/ADR-TEMPLATE.md exists) or MADR as a widely-adopted alternativePopulate the detected template with gathered content:
Self-check against the quality checklist before saving. All structural and content checks must pass.
Write the file to the destination directory determined in Phase G2:
| Rule | Example |
|---|---|
| Match existing naming convention | ADR-053-authentication-strategy.md or 0053-authentication-strategy.md |
| Zero-pad number to match existing pattern | ADR-001, 0001, etc. |
| Lowercase kebab-case slug (3-5 words) | database-selection, event-sourcing-pattern |
Status always set to Proposed | Changed only after adr-review debate |
After saving, recommend the user invoke the adr-review skill for multi-agent validation.
Avoid these when creating ADRs. Full catalog with 11+ creation and 7 review anti-patterns in AD Quality Frameworks.
| Avoid | Why | Instead |
|---|---|---|
| Skipping alternatives section | Decisions without alternatives lack rigor | Document at least 2 alternatives with pros/cons |
Setting status to Accepted | ADRs require review before acceptance | Always use Proposed, let adr-review change it |
| Duplicating an existing ADR | Causes governance confusion | Scan existing ADRs in G2, supersede if needed |
| Context that describes the solution | Context should explain the problem | Keep context focused on forces and constraints |
| Omitting negative consequences | Dishonest trade-off analysis ("Free Lunch Coupon") | Include at least 1 negative consequence |
| Skipping Prior Art when changing systems | Risk of removing structures without understanding | Use chestertons-fence skill |
| Sales Pitch language | Marketing language erodes trust | Use precise, quantifiable language |
| Dummy alternatives | Fake options to make preferred choice shine | Present genuine alternatives with honest pros/cons |
| Ignoring the template at the destination | Inconsistent ADR log | Detect template from existing ADRs in Phase G2 |
Before delivering, confirm all items in the quality checklist pass:
Proposed| Skill | Responsibility |
|---|---|
adr-generator | Creates a new ADR from scratch (Phases G1-G5) |
adr-review | Validates an existing ADR via 6-agent debate |
chestertons-fence | Investigates historical context before changing existing systems |