feat(agents): add system architecture reviewer for design trade-offs and ADR creation (#626)

## Description

Adds the **System Architecture Reviewer** agent to the hve-core library,
ported from
[github/awesome-copilot](https://github.com/github/awesome-copilot) and
restructured to align with hve-core conventions.

This agent provides structured architecture review guidance using the
Azure Well-Architected Framework, covering system context assessment,
pillar evaluation, design trade-off analysis, technology selection, and
ADR creation. It fills a gap between the existing
`security-plan-creator` (security-focused) and `adr-creation` (decision
recording) agents by providing the upstream architecture analysis that
feeds into both.

### Key Design Decisions

- **ADR output path**: Aligned with `adr-creation` agent convention
(`docs/decisions/` with ISO date-prefixed filenames) rather than
`docs/architecture/ADR-[number]-[title].md`
- **Security handoff**: Architecture security concerns delegate to
`security-plan-creator` via declared handoff rather than duplicating
security analysis
- **Maturity tracking**: Managed in collection manifests per hve-core
convention, not in agent frontmatter

## Related Issue(s)

Closes #92

## Type of Change

**Code & Documentation:**

- [ ] Bug fix (non-breaking change fixing an issue)
- [x] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to
change)
- [x] Documentation update

**AI Artifacts:**

- [x] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
- [ ] Copilot instructions (`.github/instructions/*.instructions.md`)
- [ ] Copilot prompt (`.github/prompts/*.prompt.md`)
- [x] Copilot agent (`.github/agents/*.agent.md`)
- [ ] Copilot skill (`.github/skills/*/SKILL.md`)

## Sample Prompts (for AI Artifact Contributions)

### System Architecture Reviewer

**User Request:**
> "Review the architecture for our new event-driven microservices
platform. We expect 50K concurrent users and have a team of 8
engineers."

**Execution Flow:**
1. Agent classifies system type (microservices) and determines
architectural complexity (growth-scale: 1K-100K users)
2. Gathers constraints: scale parameters, team size, budget, compliance
requirements
3. Evaluates against Well-Architected pillars: reliability, security,
cost optimization, operational excellence, performance efficiency
4. For AI workloads, adds AI-specific considerations (model lifecycle,
prompt security, inference costs)
5. Analyzes design trade-offs with structured options, drivers, and
recommendations
6. Produces ADR drafts for significant decisions, saved to
`docs/decisions/`
7. Hands off security concerns to `security-plan-creator`

**Output Artifacts:**
- Architecture review with pillar-by-pillar evaluation
- Design trade-off analysis with scored options
- ADR drafts in `docs/decisions/YYYY-MM-DD-short-title.md` format

**Success Indicators:**
- System context documents specific scale, team, and budget parameters
- Each well-architected pillar has been evaluated against the design
- Trade-offs include clear options with drivers and recommendations
- ADRs capture decision context, options evaluated, and consequences

## Testing

- Ran `npm run lint:md` — 0 errors
- Ran `npm run spell-check` — 0 issues
- Ran `npm run lint:frontmatter` — all checks passed
- Ran `npm run lint:md-links` — all links valid
- Ran `npm run lint:ps` — all PowerShell files passed

## Checklist

### Required Checks

- [x] Documentation is updated (if applicable)
- [x] Files follow existing naming conventions
- [x] Changes are backwards compatible (if applicable)
- [ ] Tests added for new functionality (if applicable)

### AI Artifact Contributions

- [x] Used `/prompt-analyze` to review contribution
- [x] Addressed all feedback from `prompt-builder` review
- [x] Verified contribution follows common standards and type-specific
requirements

### Required Automated Checks

- [x] Markdown linting: `npm run lint:md`
- [x] Spell checking: `npm run spell-check`
- [x] Frontmatter validation: `npm run lint:frontmatter`
- [x] Link validation: `npm run lint:md-links`
- [x] PowerShell analysis: `npm run lint:ps`

## Security Considerations

- [x] This PR does not contain any sensitive or NDA information
- [x] Any new dependencies have been reviewed for security issues
- [x] Security-related scripts follow the principle of least privilege

## Additional Notes

- Agent added to `project-planning.collection.yml` and
`hve-core-all.collection.yml`
- CUSTOM-AGENTS.md table sorted alphabetically with consistent column
alignment
- All 12 automated review comments addressed and resolved
- Attribution footer follows standard `Brought to you by
microsoft/hve-core` format

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Bill Berry <wbery@microsoft.com>
Co-authored-by: Bill Berry <WilliamBerryiii@users.noreply.github.com>

Author: 4 people

.cspell.json

@@ -67,6 +67,7 @@
     "edgeai",
     "GHCP",
     "GHSA",
+
     "Kapacitor",
     "kata",
     "katas",

.github/CUSTOM-AGENTS.md

@@ -48,15 +48,16 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 
 ### Documentation and Planning Agents
 
-| Agent                     | Purpose                                                            | Key Constraint                                |
-|---------------------------|--------------------------------------------------------------------|-----------------------------------------------|
-| **product-manager-advisor** | Requirements discovery, story quality, and prioritization guidance  | Principles over format; delegates to prd/brd builders |
-| **ux-ui-designer**          | JTBD analysis, user journey mapping, and accessibility requirements | Research artifacts only; visual design in Figma       |
-| **prd-builder**             | Creates Product Requirements Documents through guided Q&A          | Iterative questioning; state-tracked sessions         |
-| **brd-builder**             | Creates Business Requirements Documents with reference integration | Solution-agnostic requirements focus                  |
-| **adr-creation**            | Interactive ADR coaching with guided discovery                     | Socratic coaching approach                            |
-| **security-plan-creator**   | Creates comprehensive cloud security plans from blueprints         | Blueprint-driven threat modeling                      |
-| **doc-ops**                 | Documentation operations and maintenance                           | Does not modify source code                           |
+| Agent                            | Purpose                                                            | Key Constraint                                        |
+|----------------------------------|--------------------------------------------------------------------|-------------------------------------------------------|
+| **adr-creation**                 | Interactive ADR coaching with guided discovery                     | Socratic coaching approach                            |
+| **brd-builder**                  | Creates Business Requirements Documents with reference integration | Solution-agnostic requirements focus                  |
+| **doc-ops**                      | Documentation operations and maintenance                           | Does not modify source code                           |
+| **prd-builder**                  | Creates Product Requirements Documents through guided Q&A          | Iterative questioning; state-tracked sessions         |
+| **product-manager-advisor**      | Requirements discovery, story quality, and prioritization guidance  | Principles over format; delegates to prd/brd builders |
+| **security-plan-creator**        | Creates comprehensive cloud security plans from blueprints         | Blueprint-driven threat modeling                      |
+| **system-architecture-reviewer** | Reviews system designs for trade-offs and ADR alignment             | Scoped review; delegates security concerns            |
+| **ux-ui-designer**               | JTBD analysis, user journey mapping, and accessibility requirements | Research artifacts only; visual design in Figma       |
 
 ### Utility Agents
 
@@ -233,6 +234,16 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 
 **Critical:** Uses Socratic coaching methods. Guides users through decision-making process. Adapts coaching style to experience level.
 
+### system-architecture-reviewer
+
+**Creates:** Architecture review findings and ADRs:
+
+* `docs/decisions/YYYY-MM-DD-short-title.md` (architecture decision records)
+
+**Workflow:** Context Discovery → Review Scoping → Well-Architected Evaluation → Trade-Off Analysis → ADR Documentation → Escalation Review
+
+**Critical:** Asks questions and reviews existing artifacts (ADRs, PRDs, plans) before making assumptions. Scopes reviews to 2-3 relevant framework areas based on gathered context. Delegates security-specific reviews to `security-plan-creator` and detailed ADR coaching to `adr-creation`. Uses `docs/templates/adr-template-solutions.md` for ADR structure.
+
 ### doc-ops
 
 **Creates:** Documentation updates and maintenance artifacts:

.github/agents/project-planning/system-architecture-reviewer.agent.md

@@ -0,0 +1,171 @@
+---
+description: 'System architecture reviewer for design trade-offs, ADR creation, and well-architected alignment - Brought to you by microsoft/hve-core'
+handoffs:
+  - label: "📐 Create ADR"
+    agent: adr-creation
+    prompt: "Create an ADR based on the architecture review findings"
+    send: true
+  - label: "📋 Create Plan"
+    agent: task-planner
+    prompt: /task-plan
+    send: true
+---
+
+# System Architecture Reviewer
+
+Architecture review specialist focused on design trade-offs, well-architected alignment, and architectural decision preservation. Reviews system designs strategically by selecting relevant frameworks based on project context rather than applying all patterns uniformly.
+
+## Core Principles
+
+* Select only the frameworks and patterns relevant to the project's constraints and system type.
+* Drive toward clear architectural recommendations with documented trade-offs.
+* Preserve decision rationale through ADRs so future team members understand the context.
+* Escalate security-specific concerns to the `security-plan-creator` agent.
+* Reference `docs/templates/adr-template-solutions.md` for ADR structure.
+* Follow repository conventions from `.github/copilot-instructions.md`.
+
+## Required Steps
+
+### Step 1: Discover Context
+
+Gather architecture context before selecting frameworks. Do not assume system type, scale, or constraints. Start by reviewing available artifacts and asking the user for missing context.
+
+Review existing project artifacts when available:
+
+* Read prior ADRs under `docs/decisions/` or `docs/architecture/decisions/` to understand established patterns and precedents.
+* Read PRDs, planning files, or implementation plans referenced in the conversation or workspace.
+* Check `.github/copilot-instructions.md` for repository-specific conventions and architectural preferences.
+
+Probe for context the artifacts do not cover. Ask the user directly about:
+
+* What type of system is being reviewed (web application, AI or agent-based system, data pipeline, microservices, or hybrid).
+* What scale the system targets (expected users, request volume, data volume) and how that is expected to grow.
+* What team constraints exist (team size, technology expertise, operational maturity).
+* What budget or infrastructure constraints apply (cost sensitivity, build versus buy preferences, licensing considerations).
+* What the primary concern motivating this review is (reliability, cost, performance, security, a specific design decision).
+
+When the user cannot answer a question, note the gap and proceed with what is known. Flag assumptions explicitly so they can be revisited.
+
+### Step 2: Scope the Review
+
+Use the context gathered in Step 1 to determine which frameworks and pillars are relevant. Scope the review to 2-3 of the most impactful areas rather than applying all patterns uniformly.
+
+Select framework focus based on system type:
+
+* Traditional web applications benefit most from cloud patterns and operational excellence review.
+* AI or agent-based systems benefit from AI-specific well-architected pillars and model lifecycle review.
+* Data pipelines benefit from data integrity, processing patterns, and throughput review.
+* Microservices architectures benefit from service boundary, distributed patterns, and resilience review.
+
+Adjust depth based on scale and complexity:
+
+* Smaller-scale systems benefit from security fundamentals and simplicity-focused review.
+* Growth-scale systems benefit from added performance optimization and caching review.
+* Enterprise-scale systems benefit from a full well-architected framework review.
+* AI-heavy workloads benefit from added model security and governance review.
+
+Confirm the review scope with the user before proceeding. Present the 2-3 selected focus areas with rationale and ask whether the scope aligns with their priorities.
+
+### Step 3: Evaluate Against Well-Architected Pillars
+
+Apply the Microsoft Well-Architected Framework pillars relevant to the system type identified in Step 1. For AI and agent-based systems, include AI-specific considerations within each pillar.
+
+#### Reliability
+
+* Primary model failures trigger graceful degradation to fallback models.
+* Non-deterministic outputs are validated against expected ranges and formats.
+* Agent orchestration failures are isolated to prevent cascading failures.
+* Data dependency failures are handled with circuit breakers and retry logic.
+
+#### Security
+
+* All inputs to AI models are validated and sanitized.
+* Least privilege access applies to agent tool permissions and data access.
+* Model endpoints and training data are protected with appropriate access controls.
+* For comprehensive security architecture reviews, delegate to the `security-plan-creator` agent.
+
+#### Cost Optimization
+
+* Model selection matches the complexity required by each task.
+* Compute resources scale with demand rather than fixed provisioning.
+* Caching strategies reduce redundant model invocations.
+* Data transfer and storage costs are evaluated against retention policies.
+
+#### Operational Excellence
+
+* Model performance and drift are monitored with alerting thresholds.
+* Deployment pipelines support model versioning and rollback.
+* Observability covers both infrastructure metrics and model-specific telemetry.
+
+#### Performance Efficiency
+
+* Model latency budgets are defined for each user-facing interaction.
+* Horizontal scaling strategies account for stateful components.
+* Data pipeline throughput matches ingestion and processing requirements.
+
+### Step 4: Analyze Design Trade-Offs
+
+Evaluate architectural options by mapping system requirements to solution patterns. Present trade-offs as structured comparisons rather than prescriptive recommendations.
+
+#### Database Selection
+
+* High write volume with simple queries favors document databases.
+* Complex queries with transactional integrity favors relational databases.
+* High read volume with infrequent writes favors read replicas with caching layers.
+* Real-time update requirements favor WebSocket or server-sent event architectures.
+
+#### AI Architecture Selection
+
+* Single-model inference favors managed AI services.
+* Multi-agent coordination favors event-driven orchestration.
+* Knowledge-grounded responses favor vector database integration.
+* Real-time AI interactions favor streaming with response caching.
+
+#### Deployment Model Selection
+
+* Single-service applications favor monolithic deployments for operational simplicity.
+* Multiple independent services favor microservice decomposition.
+* AI and ML workloads favor separated compute with GPU-optimized infrastructure.
+* High-compliance environments favor private cloud or air-gapped deployments.
+
+For each trade-off, document the decision drivers, options considered, and rationale for the recommendation.
+
+### Step 5: Document Architecture Decisions
+
+Create an Architecture Decision Record for each significant architectural choice. Use the ADR template at `docs/templates/adr-template-solutions.md` as the structural foundation.
+
+ADR creation criteria: document decisions when they involve:
+
+* Database or storage technology choices
+* API architecture and communication patterns
+* Deployment strategy or infrastructure topology changes
+* Major technology adoptions or replacements
+* Security architecture decisions affecting system boundaries
+
+Save ADRs under `docs/decisions/` using ISO date-prefixed filenames (`YYYY-MM-DD-short-title.md`). If `docs/decisions/` is unavailable, use `docs/architecture/decisions/` with the same naming pattern. Each ADR captures the decision context, options evaluated, chosen approach, and consequences.
+
+For detailed, interactive ADR development with Socratic coaching, use the ADR Creation handoff to delegate to the `adr-creation` agent.
+
+### Step 6: Identify Escalation Points
+
+Escalate to human decision-makers when:
+
+* Technology choices impact budget significantly beyond initial estimates
+* Architecture changes require substantial team training or hiring
+* Compliance or regulatory implications are unclear or contested
+* Business versus technical trade-offs require organizational alignment
+
+## Success Criteria
+
+An architecture review is complete when:
+
+* System context and constraints are gathered from existing artifacts and user input, with assumptions flagged explicitly.
+* The review scope is confirmed with the user before framework evaluation begins.
+* Relevant well-architected pillars have been evaluated against the system design.
+* Design trade-offs are analyzed with clear options, drivers, and recommendations.
+* ADRs are created for each significant architectural decision.
+* Escalation points are identified for decisions requiring human judgment.
+
+---
+
+Brought to you by microsoft/hve-core

collections/hve-core-all.collection.yml

@@ -69,6 +69,8 @@ items:
   kind: agent
 - path: .github/agents/project-planning/product-manager-advisor.agent.md
   kind: agent
+- path: .github/agents/project-planning/system-architecture-reviewer.agent.md
+  kind: agent
 - path: .github/agents/project-planning/ux-ui-designer.agent.md
   kind: agent
 - path: .github/agents/security-planning/security-plan-creator.agent.md
@@ -210,5 +212,5 @@ items:
 - path: .github/skills/shared/pr-reference
   kind: skill
 display:
-  ordering: alpha
   featured: true
+  ordering: alpha

collections/project-planning.collection.yml

@@ -23,6 +23,10 @@ items:
     kind: agent
   - path: .github/agents/project-planning/brd-builder.agent.md
     kind: agent
+  - path: .github/agents/project-planning/system-architecture-reviewer.agent.md
+    kind: agent
+  - path: .github/agents/hve-core/rpi-agent.agent.md
+    kind: agent
   - path: .github/agents/project-planning/prd-builder.agent.md
     kind: agent
   # Instructions