Skip to main content

Architectural Decision Records (ADRs)

This directory contains the Architectural Decision Records for the MCP ADR Analysis Server project.

ADR Index​

ADRTitleStatusDateCategory
ADR-001MCP Protocol Implementation StrategyDeprecated2024-01-15Architecture
ADR-002AI Integration and Advanced Prompting StrategyAccepted2024-01-15AI/ML
ADR-003Memory-Centric ArchitectureAccepted2024-01-15Architecture
ADR-004Security and Content Masking StrategyAccepted2024-01-15Security
ADR-005Testing and Quality Assurance StrategyAccepted2024-01-15Quality
ADR-006Tree-Sitter Integration StrategyAccepted2024-01-15Architecture
ADR-007CI/CD Pipeline StrategyAccepted2024-01-15DevOps
ADR-008Development Workflow StrategyAccepted2024-01-15Process
ADR-009Package Distribution StrategyAccepted2024-01-15Distribution
ADR-010Bootstrap Deployment ArchitectureSuperseded in part2025-01-23Deployment
ADR-011ADR Timeline Tracking and Context-Aware AnalysisAccepted2025-11-19Architecture
ADR-012Validated Patterns FrameworkSuperseded in part2025-01-16Deployment
ADR-013Documentation Platform StrategyAccepted2025-11-21Documentation
ADR-014CE-MCP ArchitectureAccepted2025-12-09Architecture
ADR-015APE Optimization StrategyAccepted2025-12-12AI/ML
ADR-017Tree-Sitter Version StrategyAccepted2025-12-13Architecture
ADR-018Atomic Tools ArchitectureAccepted2025-12-16Architecture
ADR-019Migrate from Jest to Vitest for TestingAccepted2024-12-16Testing
ADR-020MCP Tasks Integration StrategySuperseded in part2025-12-16Architecture
ADR-021Disposition of the legacy AI execution layerAccepted2026-08-26Architecture
ADR-022Adopt MADR as the default decision-record formatAccepted2026-08-27Documentation
ADR-023Which of the 75 tools should still existAccepted2026-08-27Architecture
ADR-025Retire the bootstrap pattern-execution engineAccepted2026-08-28Deployment
ADR-026Tool-call best-practices conformanceProposed2026-09-02Architecture

ADR-016 was never written. ADR-017 cites it twice as a predecessor decision ("Replace ripgrep with tree-sitter"), and tree-sitter-code-tools.ts cited it in an @see. The switch was decided and implemented; the record was not. The number is left unused rather than reassigned — renumbering a later ADR into the gap would fabricate a history that did not happen. ADR-006 holds the tree-sitter rationale.

tree-sitter-code-tools.ts itself was deleted under #1540 on 2026-08-29: 864 lines that nothing in src/, tests/ or scripts/ referenced. Tree-sitter is still a real capability here; that file was not how it was delivered.

The note that stood here claimed this index "stops at ADR-018, omits ADR-019 and ADR-020, and lists ADR-012, ADR-013 and ADR-014 as Proposed". None of that is true any more — a note announcing its own staleness, which had itself gone stale. Removed as part of #1415, which is the issue it pointed at.

Legacy ADRs (Sample Project)​

The following ADRs exist in the sample-project/docs/adrs/ directory and serve as examples:

ADRTitleStatusCategory
001Database Architecture SelectionAcceptedDatabase
002API Authentication StrategyProposedSecurity
003Legacy Data Migration StrategyDeprecatedMigration

ADR Categories​

Architecture​

  • ADR-001: MCP Protocol Implementation Strategy
  • ADR-003: Memory-Centric Architecture
  • ADR-006: Tree-Sitter Integration Strategy
  • ADR-011: ADR Timeline Tracking and Context-Aware Analysis
  • ADR-014: CE-MCP Architecture (Code Execution with MCP)
  • ADR-017: Tree-Sitter Version Strategy
  • ADR-018: Atomic Tools Architecture

AI/ML​

  • ADR-002: AI Integration and Advanced Prompting Strategy
  • ADR-015: APE Optimization Strategy

Security​

  • ADR-004: Security and Content Masking Strategy

Quality​

  • ADR-005: Testing and Quality Assurance Strategy
  • ADR-018: Atomic Tools Architecture (Testing Infrastructure)

DevOps​

  • ADR-007: CI/CD Pipeline Strategy

Process​

  • ADR-008: Development Workflow Strategy

Distribution​

  • ADR-009: Package Distribution Strategy

Deployment​

  • ADR-010: Bootstrap Deployment Architecture
  • ADR-012: Validated Patterns Framework

Documentation​

  • ADR-013: Documentation Platform Strategy

ADR Relationships​

This section documents the dependencies and relationships between ADRs.

ADR-001 (MCP Protocol) ─────┬──► ADR-002 (AI Integration)
                            │
                            ├──► ADR-003 (Memory Architecture)
                            │
                            └──► ADR-011 (Timeline Tracking)

ADR-003 (Memory) ───────────┬──► ADR-011 (Timeline Tracking)
                            │
                            └──► ADR-012 (Validated Patterns)

ADR-004 (Security) ─────────┬──► ADR-006 (Tree-Sitter)
                            │
                            └──► ADR-008 (Dev Workflow)

ADR-010 (Bootstrap) ────────┬──► ADR-001 (MCP Protocol)
                            │
                            ├──► ADR-002 (AI Integration)
                            │
                            └──► ADR-012 (Validated Patterns)

ADR-012 (Validated Patterns) ──► ADR-010 (Bootstrap)

ADR-013 (Documentation) ────────┬──► ADR-007 (CI/CD Pipeline)
                                │
                                └──► ADR-008 (Dev Workflow)

ADR-014 (CE-MCP Architecture) ──┬──► ADR-001 (MCP Protocol) [EVOLVES]
                                │
                                ├──► ADR-002 (AI Integration) [EVOLVES]
                                │
                                ├──► ADR-010 (Bootstrap) [ALIGNS]
                                │
                                └──► ADR-012 (Validated Patterns) [ALIGNS]

ADR-015 (APE Optimization) ─────┬──► ADR-002 (AI Integration) [OPTIMIZES]
                                │
                                └──► ADR-014 (CE-MCP) [ALIGNS]

ADR-017 (Tree-Sitter Version) ─────► ADR-006 (Tree-Sitter Integration) [EVOLVES]

ADR-018 (Atomic Tools) ─────────┬──► ADR-003 (Memory Architecture) [EVOLVES]
                                │
                                ├──► ADR-005 (Testing Strategy) [EVOLVES]
                                │
                                └──► ADR-014 (CE-MCP) [ALIGNS]

Cross-Reference Matrix​

ADRDepends OnInfluences
ADR-001-ADR-002, ADR-003, ADR-010, ADR-011
ADR-002ADR-001ADR-010
ADR-003ADR-001ADR-011, ADR-012
ADR-004-ADR-006, ADR-008
ADR-005ADR-007ADR-008
ADR-006ADR-004ADR-004
ADR-007-ADR-005, ADR-008, ADR-010
ADR-008ADR-005, ADR-007-
ADR-009ADR-007-
ADR-010ADR-001, ADR-002, ADR-007ADR-012
ADR-011ADR-001, ADR-003-
ADR-012ADR-003, ADR-010ADR-010
ADR-013ADR-007, ADR-008-
ADR-014ADR-001, ADR-002ADR-010, ADR-012 (evolves ADR-001, ADR-002)
ADR-015ADR-002, ADR-014- (optimizes APE from ADR-002)
ADR-017ADR-006- (evolves Tree-Sitter integration)
ADR-018ADR-003, ADR-005, ADR-014- (evolves testing and architecture)

Archived/Test ADRs​

The following files exist for testing purposes and should not be considered production ADRs:

FilePurposeStatus
adr-0001-test-decision.mdUnit test fixtureTest Only
adr-0001-integration-test-decision.mdIntegration test fixtureTest Only

ADR Template​

We use the NYGARD template for our ADRs:

# ADR-XXX: [Title]

## Status

[Proposed | Accepted | Deprecated | Superseded]

## Context

[Description of the problem and context]

## Decision

[Description of the architectural decision]

## Consequences

**Positive:**

- [Positive consequence 1]
- [Positive consequence 2]

**Negative:**

- [Negative consequence 1]
- [Negative consequence 2]

Contributing​

When creating new ADRs:

  1. Use the next available ADR number
  2. Follow the NYGARD template format
  3. Include clear context, decision, and consequences
  4. Update this README.md index
  5. Link related ADRs where appropriate

Tools​

This project includes MCP tools for ADR management:

  • mcp0_discover_existing_adrs: Discover and catalog existing ADRs
  • mcp0_suggest_adrs: Suggest new ADRs based on code analysis
  • mcp0_generate_adr_from_decision: Generate ADRs from decision data
  • mcp0_review_existing_adrs: Review ADRs against implementation
  • mcp0_generate_adr_todo: Generate implementation tasks from ADRs