📜 ADR Agent Specification¶

📌 Purpose¶

The ADR Agent is responsible for managing the full lifecycle of Architecture Decision Records (ADRs) within the ConnectSoft AI Software Factory — capturing the rationale behind technology choices, pattern selections, trade-off analyses, and design pivots.

It ensures that every significant architecture decision is recorded, contextualized, traceable, and discoverable — enabling teams and agents to understand why something was built a certain way, not just what was built.

🧾 Architecture decisions without recorded rationale become tribal knowledge that evaporates. This agent ensures they become permanent, queryable institutional memory.

🎯 Primary Goals¶

Goal	Description
📜 Capture architecture decisions	Record every significant technology choice, pattern selection, or design trade-off as a structured ADR
🧠 Preserve rationale and context	Document the why — alternatives considered, trade-offs evaluated, constraints applied
🔗 Integrate with log4brains	Generate ADRs in log4brains-compatible format for browsable decision history
🔄 Track decision lifecycle	Manage ADR statuses: proposed → accepted → deprecated → superseded
📎 Link to trace context	Connect ADRs to specific modules, editions, features, and agent execution traces
📚 Feed Knowledge Management	Embed ADR content as semantic memory for cross-agent retrieval and reasoning

🧠 Core Role in the Factory¶

The ADR Agent sits within the Documentation and Knowledge Management cluster, acting as the decision memory layer between architecture agents and the broader knowledge system.

Architecture decisions flow from Enterprise Architect, Solution Architect, and Tech Lead agents into the ADR Agent, which structures, validates, and publishes them into the documentation ecosystem and knowledge graph.

🧩 Position in the Documentation and Knowledge Management Cluster¶

Layer	Cluster	Description
📜 Decision Record Layer	Documentation & Knowledge Management	Captures and structures architecture decisions as ADRs
🔗 Rationale Preservation	Links decisions to alternatives, constraints, and outcomes
🧠 Knowledge Contributor	Feeds structured decision knowledge into Knowledge Management and doc sites

flowchart TD
    EA[🏛️ Enterprise Architect Agent] -->|architecture_decision_made| ADR[📜 ADR Agent]
    SA[🧩 Solution Architect Agent] -->|technology_selection_completed| ADR
    TL[🔧 Tech Lead Agent] -->|pattern_deviation_detected| ADR
    ADR --> KM[🧠 Knowledge Management Agent]
    ADR --> DOC_SITE[📦 Documentation Site Generator Agent]
    ADR --> DOC_WRITER[📝 Documentation Writer Agent]
    ADR --> STUDIO[📊 Studio Agent]

Hold "Alt" / "Option" to enable pan & zoom

⚡ Triggering Events¶

Event	Description
`architecture_decision_made`	An architect agent has finalized a technology or pattern choice requiring formal documentation
`technology_selection_completed`	A technology evaluation process has concluded with a selected option and rejected alternatives
`pattern_deviation_detected`	A code review or generator agent detects deviation from established architecture patterns
`adr_review_requested`	A human or agent requests review of an existing ADR's relevance or accuracy
`adr_supersession_triggered`	A new decision invalidates or replaces a previous ADR

📋 Responsibilities and Deliverables¶

🧰 Key Responsibilities¶

Responsibility	Description
📜 ADR Generation	Create structured ADRs from architecture decision events with full context and rationale
🧠 Rationale Capture	Document alternatives considered, evaluation criteria, trade-offs, and constraints
🔄 Lifecycle Management	Track ADR status transitions: proposed → accepted → deprecated → superseded
🔗 log4brains Integration	Generate ADRs in Markdown format compatible with log4brains tooling and navigation
📎 Trace Linking	Connect each ADR to `traceId`, `moduleId`, `editionId`, and originating agent
📚 Decision Log Maintenance	Maintain a chronological decision log index across all modules and editions
🔍 Impact Analysis	When a decision is superseded, identify downstream artifacts that may need updating

📤 Deliverables¶

Deliverable Type	Description
📜 `adr`	Individual Architecture Decision Record in log4brains-compatible Markdown
📋 `decision-log`	Chronological index of all ADRs with status, date, module, and summary
🔄 `adr-supersession-map.yaml`	Mapping of superseded ADRs to their replacements
📊 `adr-coverage.metrics.json`	Coverage metrics: decisions per module, status distribution, staleness indicators

📘 Example Output: ADR Document¶

# ADR-0042: Use MassTransit over NServiceBus for Message Broker Abstraction

## Status
Accepted

## Date
2026-03-15

## Context
The platform requires a message broker abstraction layer that supports
RabbitMQ and Azure Service Bus. Both MassTransit and NServiceBus were
evaluated against criteria of open-source licensing, Azure-native support,
Semantic Kernel compatibility, and community adoption.

## Decision
We will use **MassTransit** as the message broker abstraction for all
ConnectSoft microservices.

## Alternatives Considered
| Option | Pros | Cons |
|--------|------|------|
| MassTransit | OSS, strong Azure support, active community | Steeper learning curve |
| NServiceBus | Mature, enterprise features | Commercial license, heavier footprint |
| Raw Azure SDK | No abstraction overhead | Vendor lock-in, no broker portability |

## Consequences
- All microservice templates will use MassTransit consumers and sagas
- Message contracts will follow MassTransit conventions
- Test harnesses will use MassTransit InMemory transport

## Trace
- `traceId`: proj-900-v3
- `agentId`: EnterpriseArchitectAgent
- `moduleId`: PlatformMessaging
- `editionId`: core

🤝 Collaboration Interfaces¶

🔗 Upstream Agents (Inputs)¶

Agent	Input Provided
Enterprise Architect Agent	Strategic architecture decisions, technology evaluations, platform-wide patterns
Solution Architect Agent	Module-specific design decisions, integration pattern selections
Tech Lead Agent	Implementation-level decisions, pattern deviations, library selections
Code Reviewer Agent	Detected deviations from established ADRs that may trigger new decisions

📤 Downstream Agents (Outputs Consumed By)¶

Agent	Output Consumed
Documentation Site Generator Agent	Integrates ADRs into the MkDocs site under `/decisions/` navigation
Documentation Writer Agent	References ADRs in architecture overview and module documentation
Knowledge Management Agent	Indexes ADRs as semantic memory entries for cross-agent retrieval
Studio Agent	Displays ADR coverage, staleness metrics, and decision timelines

📊 Collaboration Flow¶

flowchart TD
    EA[🏛️ Enterprise Architect] --> ADR[📜 ADR Agent]
    SA[🧩 Solution Architect] --> ADR
    TL[🔧 Tech Lead] --> ADR
    REVIEWER[🔍 Code Reviewer] --> ADR

    ADR --> DOC_SITE[📦 Doc Site Generator]
    ADR --> DOC_WRITER[📝 Documentation Writer]
    ADR --> KM[🧠 Knowledge Management]
    ADR --> STUDIO[📊 Studio Dashboard]

Hold "Alt" / "Option" to enable pan & zoom

🧠 Memory and Knowledge¶

📚 Pre-Embedded Knowledge¶

Domain	Description
📜 ADR format standards	MADR (Markdown Any Decision Records), log4brains conventions, Nygard format
🧱 ConnectSoft architecture patterns	Established patterns for microservices, messaging, data access, and API design
🔄 Decision lifecycle model	Status transitions and supersession chain management
📘 Technology evaluation frameworks	Criteria for evaluating libraries, frameworks, cloud services, and patterns

🧠 Short-Term Memory¶

Capability	Description
📍 Active decision context	Holds the current architecture decision being documented with all evaluation data
🔗 Supersession chain	Tracks which existing ADRs are affected by the current decision
📎 Module and trace context	Temporarily caches related modules, editions, and trace metadata for linking

🧠 Long-Term Memory¶

Memory Type	Storage	Purpose
📜 ADR repository	File system + Vector DB	Full archive of all ADRs with semantic embeddings for similarity search
📋 Decision log index	`decision-log-index.yaml`	Chronological index with status, module, and summary per ADR
🔄 Supersession map	`adr-supersession-map.yaml`	Tracks replacement chains across ADR versions
📊 Coverage metrics	`adr-coverage.metrics.json`	Decision coverage per module, staleness scores, status distribution

✅ Validation¶

🧪 Validation Checks¶

Check	Description
📜 Structure compliance	ADR must follow the configured format (Context, Decision, Alternatives, Consequences)
🧠 Rationale completeness	At least two alternatives must be documented with pros/cons
🔗 Trace metadata presence	`traceId`, `agentId`, `moduleId` must be present
🔄 Supersession integrity	If superseding another ADR, the referenced ADR must exist and be marked as superseded
📎 log4brains compatibility	Output must be parseable by log4brains tooling
📊 No orphan decisions	Every ADR must be linked to at least one module or feature

🔁 Retry and Correction¶

Scenario	Correction
Missing alternatives section	Re-prompt architect agent for evaluation data
Broken supersession reference	Validate against ADR index and repair chain
Incomplete consequences	Enrich from architecture knowledge base and module impact analysis
log4brains format violation	Re-render using log4brains template with strict formatting

📊 Observability Hooks¶

Event	Trigger	Payload
`AdrCreated`	New ADR published	`adrId`, `traceId`, `moduleId`, `status`, `agentId`
`AdrStatusChanged`	ADR status transitioned	`adrId`, `fromStatus`, `toStatus`, `reason`
`AdrSuperseded`	ADR replaced by newer decision	`oldAdrId`, `newAdrId`, `traceId`
`AdrValidationFailed`	Validation error detected	`adrId`, `reason`, `traceId`
`AdrCoverageUpdated`	Coverage metrics recalculated	`totalAdrs`, `activeAdrs`, `modulesWithoutAdrs`

🧾 Summary and Positioning¶

The ADR Agent is the architectural memory guardian of the ConnectSoft platform, ensuring every significant design decision is:

📜 Recorded with full rationale, alternatives, and consequences
🔗 Traceable to modules, editions, features, and originating agents
🔄 Lifecycle-managed through proposal, acceptance, deprecation, and supersession
📚 Discoverable through log4brains navigation, semantic search, and knowledge graphs
🧠 Reusable as institutional memory that prevents repeated mistakes and preserves architectural intent

🧩 Position in the ConnectSoft Platform¶

flowchart TD
    ARCHITECTS[🏛️ Architecture Agents] --> ADR[📜 ADR Agent]
    TECH_LEADS[🔧 Tech Lead Agents] --> ADR
    ADR --> DOC_SITE[📦 Documentation Site]
    ADR --> KM[🧠 Knowledge Management]
    ADR --> STUDIO[📊 Studio Dashboard]
    ADR --> LOG4BRAINS[🧭 log4brains UI]

Hold "Alt" / "Option" to enable pan & zoom

Without this agent, architecture decisions live in Slack threads and meeting notes. With it, every decision becomes a permanent, navigable, and actionable record that shapes how the platform evolves.