Adr Writer

ADR Writer — Architecture Decision Record Pipeline

An agent team collaborates to execute the full workflow: context analysis, alternative comparison, tradeoff evaluation, decision documentation, and impact tracking for architecture decisions.

Execution Mode

Agent Team — Five agents communicate directly via SendMessage and perform cross-validation.

Agent Composition

Workflow

Phase 1: Preparation (Performed Directly by Orchestrator)

1. Extract from user input:
   • Decision Topic: What architecture decision is being made
   • Project Context (optional): Technology stack, team size, project phase
   • Constraints (optional): Budget, timeline, technical constraints
   • Existing ADRs (optional): Previously written ADR list or codebase
2. Create the _workspace/ directory in the project root
3. Organize inputs and save to _workspace/00_input.md
4. If a codebase is available, instruct the context analyst to explore it
5. Determine the execution mode based on the scope of the request (see "Execution Modes by Request Scope" below)

Phase 2: Team Assembly and Execution

Tasks 4a (ADR document) and 4b (impact assessment) are executed in parallel. Both depend only on Tasks 1-3, so they can start simultaneously.

Inter-agent Communication Flow:

• context-analyst completes -> Delivers constraints and technology stack to alternative-researcher; delivers quality attribute priorities to tradeoff-evaluator
• alternative-researcher completes -> Delivers alternatives list and data to tradeoff-evaluator
• tradeoff-evaluator completes -> Delivers recommendation to adr-author; delivers risk list to impact-tracker
• adr-author <-> impact-tracker: Cross-verify consistency between ADR document and impact assessment

Phase 3: Integration and Final Deliverables

1. Review all files in _workspace/
2. Validate consistency between the ADR document and impact assessment
3. Present the final summary to the user:
   • Technical Context — 01_context_analysis.md
   • Alternatives Research — 02_alternatives_report.md
   • Tradeoff Evaluation — 03_tradeoff_matrix.md
   • ADR Document — 04_adr_document.md
   • Impact Assessment — 05_impact_assessment.md

Execution Modes by Request Scope

Using Existing Files: If the user already provides analysis materials, copy them to _workspace/ and skip the corresponding agent's phase.

Data Transfer Protocol

Error Handling

Test Scenarios

Normal Flow

Prompt: "Write an ADR on whether to transition from monolith to microservices. We're currently on Java Spring Boot with a team of 5." Expected Results:

• Context Analysis: Monolith current state, transition triggers, team size constraints
• Alternatives: At least 3 options including microservices, modular monolith, and status quo
• Tradeoff: Weighted evaluation matrix considering the 5-person team's capabilities
• ADR: MADR format, including both decision rationale and rejection reasons
• Impact Assessment: Phased migration roadmap with rollback strategies

Existing Materials Flow

Prompt: "We already compared Redis vs Memcached. Please organize it into an ADR document." + comparison materials provided Expected Results:

• Copy provided comparison materials to _workspace/
• Skip or only supplement context-analyst and alternative-researcher phases
• Focus on adr-author + impact-tracker for documentation

Error Flow

Prompt: "Write a database selection ADR." Expected Results:

• Context is insufficient, so context-analyst suggests questions about requirements (data types, scale, access patterns)
• Proceed with work under general scenario assumptions; note assumptions in the ADR
• Add "assumption verification needed" items to the impact assessment

Agent Extension Skills

Extension skills that enhance each agent's domain expertise: