Skip to content

Commit 0cb4a88

Browse files
yepzdkyepzdk
authored
Merge branch 'main' into feature/issue-7-drupal-skill
2 parents 0a422b0 + 3751e0a commit 0cb4a88

2 files changed

Lines changed: 155 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1010
### Added
1111

1212
- Drupal development skill for code auditing, module/theme development, and configuration management (Drupal 10/11)
13+
- ADR (Architecture Decision Record) skill for creating and managing architectural decisions
1314
- Auto-release workflow for MCP dependency updates
1415
- Daily scheduled check for new MCP releases (8:30 UTC)
1516
- Automated version bump and release creation when updates detected

‎skills/itkdev-adr.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
name: itkdev-adr
3+
description: Use when creating, updating, or managing Architecture Decision Records (ADRs), documenting architectural decisions, or when discussion reveals a significant technical decision that should be recorded.
4+
---
5+
6+
# Architecture Decision Records (ADR)
7+
8+
You are helping create and manage Architecture Decision Records. ADRs capture important architectural decisions along with their context and consequences.
9+
10+
For more information about ADRs, see [adr.github.io](https://adr.github.io/).
11+
12+
## Information Gathering
13+
14+
**Before writing an ADR, ask questions to gather the necessary information.** Use the AskUserQuestion tool to clarify:
15+
16+
1. **What decision needs to be documented?**
17+
- What is the problem or challenge being addressed?
18+
- What triggered this decision?
19+
20+
2. **Who is involved?**
21+
- Who is making the decision?
22+
- Who are the stakeholders (advisors and affected parties)?
23+
24+
3. **What options were considered?**
25+
- What alternatives were evaluated?
26+
- What are the pros and cons of each option?
27+
28+
4. **What was decided and why?**
29+
- Which option was chosen?
30+
- What is the rationale for this choice?
31+
32+
5. **What are the consequences?**
33+
- What are the benefits of this decision?
34+
- What are the trade-offs or risks?
35+
- Are there follow-up actions needed?
36+
37+
Ask these questions conversationally before drafting the ADR. This ensures all required fields can be properly filled in.
38+
39+
## When to Create an ADR
40+
41+
Create an ADR when making decisions about:
42+
- Technology or framework selection
43+
- Architectural pattern choices
44+
- Integration approach decisions
45+
- Security-related decisions
46+
- Breaking changes or deprecations
47+
- Cross-team impacting decisions
48+
- Any decision that would be useful to understand later
49+
50+
## ADR Template
51+
52+
Use this format for all ADRs:
53+
54+
```markdown
55+
# NNN: [Decision Title]
56+
57+
| Field | Value |
58+
|-------|-------|
59+
| **Created By** | [Author Name] |
60+
| **Date** | YYYY-MM-DD |
61+
| **Decision Maker** | [Name(s)] |
62+
| **Stakeholders** | [Advisors and affected parties] |
63+
| **Status** | Draft |
64+
65+
## Context
66+
67+
[Problem statement and background - what situation or challenge prompted this decision?]
68+
69+
### Drivers
70+
71+
- **Functional:** [Requirements that influence the decision]
72+
- **Non-functional:** [Quality attributes: performance, security, maintainability, etc.]
73+
74+
### Options Considered
75+
76+
1. **Option A**: [Description with pros/cons]
77+
2. **Option B**: [Description with pros/cons]
78+
3. **Option C**: [Description with pros/cons]
79+
80+
## Decision
81+
82+
[Chosen option and detailed rationale for why this option was selected over alternatives]
83+
84+
## Consequences
85+
86+
### Positive
87+
- [Benefit 1]
88+
- [Benefit 2]
89+
90+
### Negative / Trade-offs
91+
- [Trade-off 1]
92+
- [Trade-off 2]
93+
94+
### Follow-up Actions
95+
- [ ] [Action item if any]
96+
```
97+
98+
## File Organization
99+
100+
- **Location:** `docs/adr/` (create directory if needed)
101+
- **Naming:** `NNN-brief-title.md` (e.g., `001-database-selection.md`)
102+
- **Numbering:** Three-digit sequential numbers starting at 001
103+
- **Index:** Maintain a `docs/adr/README.md` listing all ADRs
104+
105+
### Index Template (docs/adr/README.md)
106+
107+
```markdown
108+
# Architecture Decision Records
109+
110+
This directory contains Architecture Decision Records (ADRs) for this project.
111+
112+
| Number | Title | Status | Date |
113+
|--------|-------|--------|------|
114+
| [001](001-example-decision.md) | Example Decision | Accepted | YYYY-MM-DD |
115+
```
116+
117+
## Status Values
118+
119+
- **Draft** - Decision is being discussed, not yet finalized
120+
- **Accepted** - Decision has been approved and should be followed
121+
- **Rejected** - Decision was considered but not adopted
122+
- **Deprecated by NNN** - Decision has been replaced (link to new ADR)
123+
- **Supersedes NNN** - This decision replaces a previous one (link to old ADR)
124+
125+
## Workflow
126+
127+
### Creating a New ADR
128+
129+
1. Determine the next ADR number by checking existing ADRs in `docs/adr/`
130+
2. Create the file with format `NNN-brief-title.md`
131+
3. Fill in all template sections
132+
4. Set status to "Draft"
133+
5. Update the index in `docs/adr/README.md`
134+
6. Create a PR for review
135+
136+
### Accepting an ADR
137+
138+
1. Update status from "Draft" to "Accepted"
139+
2. Ensure all sections are complete
140+
3. Verify stakeholders have reviewed
141+
142+
### Deprecating an ADR
143+
144+
1. Update the old ADR's status to "Deprecated by NNN"
145+
2. Create a new ADR that "Supersedes NNN"
146+
3. Update both entries in the index
147+
148+
## Integration with GitHub Workflow
149+
150+
When creating ADRs:
151+
- Follow `itkdev-github-guidelines` for commits and PRs
152+
- Reference related GitHub issues in the ADR context
153+
- Use commit message: `docs: add ADR NNN - brief title`
154+
- PR should explain why this decision is being documented

0 commit comments

Comments
 (0)