Epic: Architecture Decision Records (ADR) Tooling Support #289
Description
Priority: P2 - Medium Priority
Milestone: 2025-Q3
Estimated Effort: 4-6 weeks
Category: Developer Workflow Enhancement
Epic Overview
Implement comprehensive Architecture Decision Record (ADR) tooling that goes beyond basic file creation to provide analysis, validation, and AI-assisted features. This addresses a gap in the existing ADR tooling ecosystem where most tools focus solely on scaffolding markdown files.
Why ADRs Matter for MCP DevTools:
- ADRs document the reasoning behind architectural choices
- AI assistants benefit from understanding why code is structured a certain way
- MCP DevTools already surfaces project context (project_info, code_review) - ADRs are natural extension
Differentiation from Existing Tools:
| Existing Tools | MCP ADR Tools |
|---|---|
| File creation only | Analysis & intelligence |
| Single format | Multi-format support |
| CLI-only | AI-assistant integrated |
| No validation | Template compliance checking |
| No search | Semantic search across decisions |
Implementation Tasks
Phase 1: Foundation (Week 1-2, 20-28 hours)
- ADR: Project detection and initialization (adr_init) #290: ADR project detection and initialization (
adr_init) - ADR: Create new ADR with template support (adr_new) #291: Create new ADR with template support (
adr_new) - ADR: List and display ADRs with metadata (adr_list, adr_show) #292: List and display ADRs with metadata (
adr_list,adr_show) - ADR: Update ADR status and supersession (adr_status) #293: Update ADR status and supersession (
adr_status)
Phase 2: Analysis & Validation (Week 3-4, 24-32 hours)
- ADR: Template validation and auto-fix (adr_validate) #294: ADR template validation and auto-fix (
adr_validate) - ADR: Semantic search across ADR content (adr_search) #295: Semantic search across ADR content (
adr_search) - ADR: Decision relationship graph (adr_graph) #296: Decision relationship graph (
adr_graph) - ADR: Statistics and health metrics (adr_stats) #297: ADR statistics and health metrics (
adr_stats)
Phase 3: AI-Assisted Features (Week 5-6, 16-24 hours)
- ADR: Suggest related ADRs for current work (adr_suggest) #298: Suggest related ADRs for current work (
adr_suggest) - ADR: Draft ADR from natural language description (adr_draft) #299: Draft ADR from natural language description (
adr_draft) - ADR: Impact analysis for code changes (adr_impact) #300: Impact analysis for code changes (
adr_impact)
Architecture Reference
Supported ADR Formats
| Format | Source | Use Case |
|---|---|---|
| Nygard | adr-tools | Simple, traditional (default) |
| MADR | adr/madr | Options analysis, pros/cons |
| MADR-minimal | adr/madr | Streamlined MADR |
| Y-Statement | Context-driven | Brief, narrative format |
File Detection Patterns
const ADR_DIRECTORY_PATTERNS = [
"doc/adr", // adr-tools default
"docs/adr", // common variant
"docs/decisions", // MADR default
"docs/architecture-decisions",
"architecture/decisions",
];
const ADR_FILE_PATTERN = /^\d{4}-[a-z0-9-]+\.md$/; // NNNN-title.mdCache Strategy
// New cache namespace
"adrMetadata": {
ttl: 300000, // 5 minutes
invalidateOn: ["doc/adr/**/*.md", "docs/decisions/**/*.md"]
}Key Features
1. Multi-Format Support
- Auto-detect existing ADR format from directory
- Support Nygard, MADR, MADR-minimal, Y-Statement templates
- Maintain consistency within project (don't mix formats)
- Convert between formats on request
2. Pure Node.js Implementation
- No external adr-tools dependency (bash scripts not portable)
- Direct markdown parsing with consistent behavior
- Works on Windows, macOS, Linux
- Faster execution (no shell spawning for basic ops)
3. Validation & Compliance
- Check required sections present (Status, Context, Decision, Consequences)
- Validate status values match allowed set
- Detect broken supersession references
- Find orphaned ADRs (superseded but no superseder)
- Auto-fix common issues (missing dates, formatting)
4. Semantic Search
- Search across all ADR content (not just titles)
- Relevance scoring based on section matches
- Filter by status, date range
- Return snippets with match context
5. AI-Assisted Drafting
- Generate ADR structure from natural language
- Suggest consequences based on similar past decisions
- Recommend related ADRs to reference
- Extract decisions from issue/PR discussions
6. Impact Analysis
- Analyze git diff against existing ADRs
- Flag potential conflicts with accepted decisions
- Suggest relevant ADRs for PR descriptions
- Integrate with code_review tool
Dependencies
Code Changes Required:
src/utils/project-detector.ts- Add ADR directory detection.mcp-devtools.schema.json- Add ADR configuration optionssrc/index.ts- Register ADR tools with MCP serversrc/instructions.md- Document ADR tools
New Files:
src/tools/adr-tools.ts- Main ADR tools class (~600-800 lines)src/utils/adr-parser.ts- Markdown parsing utilities (~200-300 lines)src/__tests__/tools/adr-tools.test.ts- Comprehensive test suite (~600+ lines)src/__tests__/utils/adr-parser.test.ts- Parser tests (~300 lines)examples/adr-config.json- Example configuration
Documentation:
docs/tools/adr-tools.md- VitePress tool documentation- README.md - Add ADR tools section
- CLAUDE.md - Add ADR development notes
Acceptance Criteria
Feature Complete
- 11 ADR tools implemented across 3 phases
- All tools follow established MCP DevTools patterns
- ADR directory auto-detection works (all common patterns)
- Configuration schema supports ADR-specific options
- Multi-format support (Nygard, MADR, Y-Statement)
Quality Gates (MUST PASS)
- 85-90%+ test coverage for all ADR tools
-
make lintpasses with zero errors -
make testpasses with 100% success rate -
make buildcompletes successfully - All tests are meaningful (not AI slop - see CLAUDE.md)
- Comprehensive error handling with actionable messages
- JSDoc documentation for all public APIs
Integration Complete
- All tools registered in src/index.ts
- Example configurations in examples/
- VitePress documentation at docs/tools/adr-tools.md
- README.md updated
- CLAUDE.md updated with ADR patterns
Success Metrics
- ADR tools work with zero configuration on projects using adr-tools or MADR
- Validation catches 90%+ of common ADR issues
- Search returns relevant results for architectural queries
- AI-assisted features save 50%+ time in ADR creation
- Integration with code_review enhances PR descriptions
References
Internal:
- Go Tools Pattern:
src/tools/go-tools.ts - Git Tools (code_review integration):
src/tools/git-tools.ts - Project Detector:
src/utils/project-detector.ts - Cache Manager:
src/utils/cache-manager.ts
External:
- ADR Organization: https://adr.github.io/
- Nygard's Original Post: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- MADR Template: https://github.com/adr/madr
- adr-tools: https://github.com/npryce/adr-tools
- AWS ADR Best Practices: https://aws.amazon.com/blogs/architecture/master-architecture-decision-records-adrs-best-practices-for-effective-decision-making/
- Google Cloud ADR Guide: https://cloud.google.com/architecture/architecture-decision-records
- Azure ADR Guidance: https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record