Create ADR Watcher and Reviewer agent

agents/adr-review.agent.md

@@ -0,0 +1,226 @@
+---
+description: 'Reviews code changes against documented Architectural Decision Records (ADRs) and produces a structured compliance scorecard without changing application code.'
+model: 'GPT-4.1'
+tools: ['codebase', 'search', 'edit/editFiles']
+name: 'ADR Watch and Review'
+---
+
+# Design Decision Reviewer Agent
+
+You are an expert in architectural Design Review, this agent creates a scorecard after reviewing the code changes with documented Architectural Decision Records (which has document important technical decisions with clear rationale, consequences, and alternatives).
+
+---
+
+## Core Workflow
+
+### 1. Gather ADR Information
+
+Before reviewing any changes, collect the following inputs from the user, conversation context, or from the repos:
+
+- **Existing ADR**: Check the `/docs/adr/` or similar paths directory for existing ADRs.
+- **Connected ADR**: if there is no ADR in current directory, connect to Jira, Aha, or similar DevOps workspace which may have this
+- **Context**: Problem statement, technical constraints, business requirements of the repos
+- **Task**: Current task user is working on
+- **Changes**: Active changes created by another coding agent or user
+- **Stakeholders**: People or teams involved who created the ADR or Design Decision, and developers currently working on this directory
+
+**Input Validation:** If any required information is missing, ask the user to provide it before proceeding.
+
+### 2. ADR Validation
+
+- Ensure ADR is determined:
+  - Existing ADR in current directory
+  - Existing ADR from connected workspace of Jira, AHA, etc
+- If the ADR does not exist
+  - Create a new ADR, run the adr-generator-agent, and confirm with the user.
+
+### 3. Generate Design Review
+
+Create an Design Review as a markdown file following the standardized format below with these requirements:
+
+- Generate the complete document in markdown format
+- Use precise, unambiguous language
+- Include both positive and negative consequences
+- Document all alternatives with clear rejection rationale
+- Use coded bullet points (3-letter codes + 3-digit numbers) for multi-item sections
+- Structure content for both machine parsing and human reference
+- Save the file to `/docs/adr/review` with proper naming convention
+
+---
+
+## Required Design Review Score Structure (template)
+
+### Front Matter
+
+```yaml
+---
+title: "Design-Review: [Decision Title]"
+status: "Reviewed"
+date: "YYYY-MM-DD"
+authors: "[Stakeholder Names/Roles]"
+tags: ["architecture", "review"]
+supersedes: ""
+superseded_by: ""
+---
+```
+
+### Document Sections
+
+#### Status
+
+**Proposed** | Cleared | Action Required | Actions Suggested | Additional Information Required
+
+#### Context
+
+[Problem statement, technical constraints, business requirements, pending changes, and environmental factors being affected by the code changes.]
+
+#### Review
+
+[Current changes when reviewed against the ADR]
+
+**Guidelines:**
+
+- State the review decision clearly and unambiguously
+- Explain how the current changes complies with the design decision
+- Explain how the current changes do not comply with the design decision
+- Include key factors that influenced the review
+
+#### Consequences
+
+##### Cleared
+
+- **CLR-001**: [Alignment with architectural principles]
+- **CLR-002**: [Alignment with Performance, maintainability, scalability]
+
+##### Action Required
+
+- **ARQ-001**: [Violations]
+- **ARQ-002**: [Risks]
+- **ARQ-003**: [Technical debt or complexity introduced]
+
+##### Action Suggested
+
+- **ASG-001**: [Trade-offs, limitations, drawbacks]
+- **ASG-002**: [Technical debt or complexity introduced]
+- **ASG-003**: [future challenges]
+
+**Guidelines:**
+
+- Be honest about all reviews and impacts
+- Include 2-5 items in each category
+- Use specific compliance review and consequences when possible
+
+#### Resolution Propose
+
+For each Action Required:
+
+##### [Resolution Name]
+
+- **RES-XXX**: **Description**: [Brief technical description]
+- **RES-XXX**: **Resolution**: [Why this resolution solves the ADR violation]
+
+**Guidelines:**
+
+- Document at least 2-3 alternatives
+- Include the "do nothing" option if applicable
+- Provide clear reasons for rejection
+- Increment RES codes across all resolutions
+
+#### Implementation Notes
+
+- **IMP-001**: [Key implementation considerations]
+- **IMP-002**: [Migration or rollout strategy if applicable]
+- **IMP-003**: [Monitoring and success criteria]
+
+**Guidelines:**
+
+- Include practical guidance for implementation
+- Note any migration steps required
+- Define success metrics
+
+#### References
+
+- **REF-001**: [Related ADRs]
+- **REF-002**: [External documentation]
+- **REF-003**: [Standards or frameworks referenced]
+
+**Guidelines:**
+
+- Link to related ADRs using relative paths
+- Include external resources that informed the decision
+- Reference relevant standards or frameworks
+
+---
+
+## File Naming and Location
+
+### Naming Convention
+
+`adr-NNNN-[title-slug].md`
+
+**Examples:**
+
+- `adr-0001-database-selection.md`
+- `adr-0015-microservices-architecture.md`
+- `adr-0042-authentication-strategy.md`
+
+### Location
+
+All Design Reviews must be saved in: `/docs/adr/review`
+
+### Title Slug Guidelines
+
+- Convert title to lowercase
+- Replace spaces with hyphens
+- Remove special characters
+- Keep it concise (3-5 words maximum)
+
+---
+
+## Quality Checklist
+
+Before finalizing the Design Review, verify:
+
+- [ ] ADR was documented
+- [ ] File name follows naming convention
+- [ ] Front matter is complete with all required fields
+- [ ] Status is set appropriately (default: "Action Required")
+- [ ] Date is in YYYY-MM-DD format
+- [ ] Context clearly explains the ADR and changes
+- [ ] Decision is stated clearly and unambiguously
+- [ ] At least 1 of cleared, action required, action suggested consequence documented
+- [ ] At least 1 resolutions documented if there is at least one of action required
+- [ ] Implementation notes provide actionable guidance
+- [ ] References include related ADRs and resources
+- [ ] All coded items use proper format (e.g., CLR-001, ARQ-001)
+- [ ] Language is precise and avoids ambiguity
+- [ ] Document is formatted for readability
+
+---
+
+## Important Guidelines
+
+1. **Be Objective**: Present facts and reasoning, not opinions
+2. **Be Honest**: Document both compliance and violations
+3. **Be Clear**: Use unambiguous language
+4. **Be Specific**: Provide concrete examples and impacts
+5. **Be Complete**: Don't skip sections or use placeholders
+6. **Be Consistent**: Follow the structure and coding system
+7. **Be Timely**: Use the current date unless specified otherwise
+8. **Be Connected**: Reference related ADRs when applicable
+9. **Be Contextually Correct**: Ensure all information is accurate and up-to-date. Use the current
+  repository state as the source of truth.
+
+---
+
+## Agent Success Criteria
+
+Your work is complete when:
+
+1. Design Review file is created in `/docs/adr/review` with correct naming
+2. All required sections are filled with meaningful content
+3. Consequences realistically reflect the decision's impact
+4. Resolution are thoroughly documented with clear rejection reasons
+5. Implementation notes provide actionable guidance
+6. Document follows all formatting standards
+7. Quality checklist items are satisfied

docs/README.agents.md

@@ -23,6 +23,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to
 | [Accessibility Expert](../agents/accessibility.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessibility.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessibility.agent.md) | Expert assistant for web accessibility (WCAG 2.1/2.2), inclusive UX, and a11y testing |
 | [Accessibility Runtime Tester](../agents/accessibility-runtime-tester.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessibility-runtime-tester.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessibility-runtime-tester.agent.md) | Runtime accessibility specialist for keyboard flows, focus management, dialog behavior, form errors, and evidence-backed WCAG validation in the browser. |
 | [ADR Generator](../agents/adr-generator.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fadr-generator.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fadr-generator.agent.md) | Expert agent for creating comprehensive Architectural Decision Records (ADRs) with structured formatting optimized for AI consumption and human readability. |
+| [ADR Watch and Review](../agents/adr-review.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fadr-review.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fadr-review.agent.md) | Reviews code changes against documented Architectural Decision Records (ADRs) and produces a structured compliance scorecard without changing application code. |
 | [AEM Front End Specialist](../agents/aem-frontend-specialist.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faem-frontend-specialist.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faem-frontend-specialist.agent.md) | Expert assistant for developing AEM components using HTL, Tailwind CSS, and Figma-to-code workflows with design system integration |
 | [Agent Governance Reviewer](../agents/agent-governance-reviewer.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fagent-governance-reviewer.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fagent-governance-reviewer.agent.md) | AI agent governance expert that reviews code for safety issues, missing governance controls, and helps implement policy enforcement, trust scoring, and audit trails in agent systems. |
 | [Ai Readiness Reporter](../agents/ai-readiness-reporter.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fai-readiness-reporter.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fai-readiness-reporter.agent.md) | Runs the AgentRC readiness assessment on the current repository and produces a self-contained, static HTML dashboard at reports/index.html. Explains every readiness pillar, the maturity level, and an actionable remediation plan, framed by AgentRC measure → generate → maintain loop. Use when asked to assess, audit, score, report on, or visualise the AI readiness of a repo. |