Skip to content

Commit 68c6c2a

Browse files
devmarkprodevmarkpro
committed
feat: add mk-adr skill for architecture decision records
Manages ADRs using the Michael Nygard template with auto-discovery of the ADR directory, adr-tools fallbacks, and mk-humanizer prose validation. Covers creation, querying, linking, health checks, git cross-references, and relationship diagrams. Ported from a project-specific skill with all internal references removed.
1 parent 985830f commit 68c6c2a

5 files changed

Lines changed: 720 additions & 1 deletion

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@
1717
"skills": [
1818
"./skills/mk-skill-creator",
1919
"./skills/mk-humanizer",
20-
"./skills/mk-conventional-commits"
20+
"./skills/mk-conventional-commits",
21+
"./skills/mk-adr"
2122
]
2223
}
2324
]

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ ln -s ~/mk-agent-tools/skills/mk-<skill-name> ~/.claude/skills/mk-<skill-name>
5757
| [mk-skill-creator](skills/mk-skill-creator/) | Dual-mode skill factory: create new skills from natural language or audit existing skills against SKILL_SCHEMA v2.0 | `swe`, `tooling`, `devex`, `planning` |
5858
| [mk-humanizer](skills/mk-humanizer/) | Remove AI writing patterns from text with focus on technical writing and diagram-as-code | `writing`, `docs`, `code-review`, `devex` |
5959
| [mk-conventional-commits](skills/mk-conventional-commits/) | Write git commit messages following the Conventional Commits v1.0.0 spec | `git`, `swe`, `devex` |
60+
| [mk-adr](skills/mk-adr/) | Create, query, manage, and maintain Architecture Decision Records using the Nygard template | `docs`, `swe`, `planning`, `devex` |
6061

6162
## Creating a New Skill
6263

‎skills/mk-adr/SKILL.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
---
2+
name: mk-adr
3+
description: >
4+
Create, query, manage, and maintain Architecture Decision Records using the
5+
Michael Nygard template. Proactively suggests ADR creation on architecture
6+
changes. Validates prose with mk-humanizer. Trigger when user mentions ADR,
7+
architecture decisions, or asks "why" about architecture choices.
8+
metadata:
9+
tags:
10+
- docs
11+
- swe
12+
- planning
13+
- devex
14+
author: devmarkpro
15+
version: "1.0.0"
16+
---
17+
18+
# Mk ADR
19+
20+
Create, query, manage, validate, and improve Architecture Decision Records using the Michael Nygard template. Validates all ADR prose through mk-humanizer when available. Falls back to manual formatting rules when it's not.
21+
22+
ADRs are living documentation — this skill doesn't just create them, it keeps them healthy, surfaces them in conversation, cross-references with git history, and suggests improvements when they fall behind reality.
23+
24+
## When to Use This Skill
25+
26+
**Trigger when:**
27+
- User asks to create, update, or manage an ADR
28+
- User mentions "ADR", "architecture decision record", or "decision record"
29+
- User asks "why" a particular architecture choice was made
30+
- User asks to list, search, summarize, or query ADRs
31+
- User asks for an ADR health check or consistency review
32+
- User asks about history or evolution of an architecture component
33+
34+
**Proactively suggest** (don't block) creating an ADR when the user is:
35+
- Adding, replacing, or removing a major dependency
36+
- Changing the API style or communication pattern
37+
- Introducing new infrastructure components
38+
- Modifying the deployment strategy
39+
- Changing the authentication/authorization approach
40+
- Restructuring the project layout or module boundaries
41+
42+
Frame as: "This looks like an architecture decision worth recording. Want me to create an ADR for it?"
43+
44+
**Do NOT trigger when:**
45+
- Bug fixes, minor refactors, or cosmetic changes (not architectural)
46+
- Configuration changes that don't affect architecture (not this skill)
47+
48+
## Prerequisites
49+
50+
| Requirement | Details |
51+
|---|---|
52+
| ADR directory | Discover by checking: `.adr-dir` file, then `doc/adr/`, `docs/adr/`, `adr/` — create if none found |
53+
| Nygard template | `${CLAUDE_SKILL_DIR}/references/nygard-template.md` — every ADR must use this structure |
54+
| `adr-tools` CLI | Optional — see `${CLAUDE_SKILL_DIR}/references/adr-tools-reference.md` for fallbacks |
55+
| mk-humanizer skill | Validates ADR prose — required when available, skip gracefully when not installed |
56+
57+
Read both reference files before any ADR operation.
58+
59+
---
60+
61+
## Humanizer Validation Rule
62+
63+
**All ADR prose must be validated by mk-humanizer.** This applies to:
64+
- New ADRs: validate Context, Decision, and Consequences before finalizing
65+
- Updated ADRs: validate changed sections before saving
66+
- Health checks: scan all ADRs and report humanizer issue counts
67+
68+
**Process:**
69+
1. Check if mk-humanizer is available (invoke `/mk-humanizer` — if it loads, it's available)
70+
2. If available: run it against the prose sections, fix any flagged patterns
71+
3. If not available: apply these minimum checks manually:
72+
- No promotional language or puffed-up significance
73+
- No vague attributions ("experts believe", "industry observers")
74+
- Active voice in Decision section ("We will..." not "It was decided...")
75+
- No filler phrases, no em dash overuse, no rule-of-three padding
76+
- Consequences include real trade-offs, not generic optimism
77+
78+
---
79+
80+
## Workflow
81+
82+
### Phase 1: Create a New ADR
83+
84+
**Goal:** Record an architecture decision in a well-structured, humanized ADR file.
85+
86+
**Steps:**
87+
1. **Gather context** — Ask about: what decision was made, what forces led to it, what alternatives were considered, what consequences are expected
88+
2. **Find the ADR directory** — Check for `.adr-dir` file, then common locations (`doc/adr/`, `docs/adr/`, `adr/`). If none exists, ask user where to store ADRs and create the directory
89+
3. **Check for related ADRs** — Scan existing ADRs for keyword overlap; suggest linking if related ADRs exist
90+
4. **Determine numbering** — Find the highest existing ADR number and increment
91+
5. **Check for superseded decisions** — Ask if this replaces a previous ADR
92+
6. **Create the file** — Use `adr-tools` if available, otherwise create manually. Must follow the Nygard template from `${CLAUDE_SKILL_DIR}/references/nygard-template.md`:
93+
- **Title**: `# <number>. <Short noun phrase>`
94+
- **Date**: today (YYYY-MM-DD)
95+
- **Status**: Proposed, Accepted, Deprecated, or Superseded
96+
- **Context**: forces at play, constraints, problem description
97+
- **Decision**: active voice declaration ("We will...")
98+
- **Consequences**: what becomes easier/harder, trade-offs
99+
7. **Validate with mk-humanizer** — Run mk-humanizer on the Context, Decision, and Consequences sections. Fix any AI-writing patterns before finalizing. If mk-humanizer is not available, apply the minimum manual checks from the Humanizer Validation Rule above
100+
8. **Update the index** — Regenerate the ADR directory's README or TOC if one exists
101+
102+
**Acceptance:** ADR file created with correct numbering, valid Nygard template structure, and prose that passes humanizer validation.
103+
104+
### Phase 2: Query and Read ADRs
105+
106+
**Goal:** Answer questions about architecture decisions by finding and synthesizing from existing ADRs.
107+
108+
| Query type | Approach |
109+
|-----------|----------|
110+
| "What are the last N ADRs?" | List files by number, present title/status/date table |
111+
| "Why was X decided?" | Search ADRs for keywords, synthesize from Context/Decision, cite ADR number |
112+
| "Show ADRs about \<topic\>" | Keyword search, present matches with one-line summaries |
113+
| "Show ADRs with status \<status\>" | Filter by status, present matches |
114+
| "Show relationship graph" | Parse Status sections for links, generate Mermaid diagram |
115+
116+
**Acceptance:** Specific ADR numbers cited in every answer. If no ADR covers the topic, say so and offer to create one.
117+
118+
### Phase 3: Link and Supersede ADRs
119+
120+
**Goal:** Maintain bidirectional links between related ADRs.
121+
122+
**Linking** (amends, extends, conflicts with):
123+
- Update the Status section of both ADRs with the appropriate link type
124+
- See `${CLAUDE_SKILL_DIR}/references/adr-tools-reference.md` for link types and procedures
125+
126+
**Superseding:**
127+
- Create new ADR with `Supersedes [N. Old Title](old-file.md)` in Status
128+
- Update old ADR status to `Superseded by [N. New Title](new-file.md)`
129+
130+
**After any content update**, validate changed prose sections with mk-humanizer.
131+
132+
**Acceptance:** Both ADRs updated with bidirectional links. Prose passes humanizer validation.
133+
134+
### Phase 4: Health Check
135+
136+
**Goal:** Assess the quality and consistency of all ADRs.
137+
138+
Run these checks across all ADRs in the ADR directory:
139+
140+
1. **Template consistency** — Verify each has: Title (with number), Date, Status, Context, Decision, Consequences. Flag extra or missing sections.
141+
2. **Stale proposals** — Find "Proposed" ADRs older than 30 days; prompt for resolution.
142+
3. **Broken supersession chains** — If "Superseded by X" but X doesn't exist or doesn't reference back, flag it.
143+
4. **Missing links** — If ADRs reference each other in text but have no formal Status link, suggest adding one.
144+
5. **Prose quality** — Run mk-humanizer against each ADR's Context, Decision, and Consequences sections. Report issue count per ADR. Offer to fix automatically.
145+
146+
**Acceptance:** Report listing all issues found, grouped by ADR and category.
147+
148+
### Phase 5: Git History Cross-Reference
149+
150+
**Goal:** Enrich ADR answers with implementation evidence from git history.
151+
152+
When answering "why" questions or reviewing ADR health:
153+
- Search git history around the ADR's date for related commits
154+
- Present a timeline combining the ADR decision date with implementing commits
155+
- If an accepted ADR has no implementation evidence, flag it
156+
- When creating a new ADR, show recent git history to inform the Context section
157+
158+
**Acceptance:** Timeline with commit hashes and dates when git evidence is available.
159+
160+
### Phase 6: Improvement Suggestions
161+
162+
**Goal:** Continuously improve ADR quality during every read operation.
163+
164+
| Issue | Suggestion |
165+
|-------|-----------|
166+
| Thin Context (< 2 sentences) | "Consider adding alternatives evaluated and constraints" |
167+
| One-sided Consequences | "Adding trade-offs makes the record more useful" |
168+
| Vague Decision (no active voice) | "Rewrite as firm declaration: 'We will...'" |
169+
| Stale Accepted ADR | "ADR says X but codebase shows Y — supersede or update" |
170+
| Missing date or wrong format | "Add or fix the Date field" |
171+
| Title doesn't match content | "Title suggests X but Decision describes Y" |
172+
173+
Be specific, batch per ADR, prioritize by impact. Always frame as suggestions.
174+
175+
### Phase 7: Index and Diagram Generation
176+
177+
**Summary index** — Generate or update the ADR directory's README with a table: number, title (linked), status, date.
178+
179+
**Relationship diagram** — Generate Mermaid diagram with status indicators and link types between ADRs.
180+
181+
---
182+
183+
## Edge Cases
184+
185+
| Situation | Handling |
186+
|-----------|----------|
187+
| `adr-tools` not installed | Use fallback procedures from `${CLAUDE_SKILL_DIR}/references/adr-tools-reference.md` |
188+
| No ADR directory exists | Ask user for preferred location, create it, suggest ADR-0001 "Record architecture decisions" |
189+
| User asks about topic no ADR covers | Say so honestly, offer to create one |
190+
| Ambiguous query matches multiple ADRs | Present all matches with summaries, let user choose |
191+
| ADR uses non-standard template | Warn about inconsistency, suggest updating to Nygard format |
192+
| Broken supersession chain | Flag the broken link during health check |
193+
| mk-humanizer not available | Apply minimum manual prose checks from the Humanizer Validation Rule |
194+
| ADR directory in non-standard location | Check `.adr-dir` file first, then ask user |
195+
196+
## Tools
197+
198+
**Built-in:**
199+
- Read — reading ADR files and references
200+
- Bash — running `adr-tools` commands, git log, file operations
201+
- Edit — updating ADR content and status links
202+
- Write — creating new ADR files
203+
204+
**External (optional):**
205+
- `adr-tools` CLI — streamlines create, link, supersede operations
206+
207+
**Skills:**
208+
- mk-humanizer — validates ADR prose (required when available, graceful fallback when not)
209+
210+
## Examples
211+
212+
### Triggering Prompts
213+
- `Create an ADR for switching from PostgreSQL to CockroachDB`
214+
- `/mk-adr`
215+
- `Why did we decide to use JWT for authentication?`
216+
- `What are the last 3 ADRs about?`
217+
- `Run an ADR health check`
218+
- `Generate the ADR relationship diagram`
219+
- `Show me all ADRs related to the database`
220+
- `When was the decision to use event sourcing actually implemented?`
221+
222+
### Non-Triggering Prompts
223+
- `Fix the typo in the health check endpoint` (not architectural)
224+
- `Update the logging format` (configuration, not architecture)
225+
- `Write a commit message` (use mk-conventional-commits)
226+
- `Review this pull request` (not this skill)
227+
228+
### Proactive Suggestion Scenario
229+
230+
```
231+
User: Let's replace the REST API with GraphQL for the new endpoints
232+
Agent: This is an architectural change worth documenting.
233+
Want me to create an ADR for the decision to adopt GraphQL?
234+
```
235+
236+
## Success Criteria
237+
238+
1. Every new ADR follows the Nygard template exactly (Title, Date, Status, Context, Decision, Consequences)
239+
2. ADR numbering is sequential with no gaps or duplicates
240+
3. The Status field contains a valid value (Proposed, Accepted, Deprecated, Superseded)
241+
4. Supersession chains are bidirectional (old points to new, new points to old)
242+
5. Historical "why" queries cite specific ADR numbers and titles
243+
6. Git cross-references include commit hashes and dates when available
244+
7. Health checks flag stale proposals, broken links, and template deviations
245+
8. The ADR index stays current after each creation
246+
9. Improvement suggestions are specific and actionable
247+
10. ADR prose passes mk-humanizer validation on create and update
248+
11. When mk-humanizer is unavailable, minimum manual prose checks are applied
249+
12. Health check reports humanizer issue count per ADR
250+
251+
## Reference Files
252+
253+
| File | Purpose |
254+
|------|---------|
255+
| `references/nygard-template.md` | Mandatory ADR template structure with field descriptions and examples |
256+
| `references/adr-tools-reference.md` | CLI reference and bash fallback commands for all ADR operations |
257+
258+
## Tips
259+
260+
1. Keep titles as short noun phrases — "Use PostgreSQL for storage" not "We decided to use PostgreSQL"
261+
2. Context describes forces at play, not the solution
262+
3. Decision uses active voice: "We will..." not "It was decided..."
263+
4. Consequences should include both positive and negative outcomes
264+
5. When answering historical "why" questions, always cite the ADR number and title
265+
6. Treat every interaction with ADRs as an opportunity to improve them
266+
7. Cross-reference git history whenever it adds value — commit evidence makes answers more credible

0 commit comments

Comments
 (0)