feat(agents): add BLOCKING gate for automatic ADR review (#467)

* feat(agents): add BLOCKING gate for automatic ADR review

Ensure adr-review skill is ALWAYS triggered when ADRs are created/updated:

## Changes
- architect.md: Add ADR Creation/Update Protocol (BLOCKING) section
- orchestrator.md: Add ADR Review Enforcement rule (#4) and detection patterns
- AGENTS.md: Add global ADR Review Requirement with enforcement table
- adr-review SKILL.md: Update with MANDATORY triggers and anti-patterns

## Enforcement Flow
1. Architect signals orchestrator: "MANDATORY: invoke adr-review"
2. Orchestrator detects signal and invokes adr-review skill
3. Workflow continues only after adr-review completes

## Background
Session 91 discovered ADR-021 was created without automatic adr-review.
The skill documentation was aspirational, not enforced.
This fix adds explicit blocking gates to ensure 100% compliance.

Addresses P1 follow-up from Session 91 (#357)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs(session): update Session 92 log with outcome and limitation note

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(agents): update templates and regenerate platform agents

Update shared templates with ADR Review Enforcement:
- templates/agents/architect.shared.md: Add BLOCKING gate
- templates/agents/orchestrator.shared.md: Add ADR Review Enforcement

Regenerate all platform-specific agent files (36 files).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: rjmurillo[bot] <rjmurillo-bot@users.noreply.github.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: rjmurillo-bot

.agents/sessions/2025-12-27-session-92-adr-review-auto-trigger.md

@@ -0,0 +1,66 @@
+# Session 92: ADR Review Auto-Trigger Fix
+
+**Date**: 2025-12-27
+**Branch**: `feat/adr-review-auto-trigger`
+**Issue**: Follow-up from Session 91 (P1 action item)
+
+## Outcome
+
+**Status**: SUCCESS - PR #467 created
+
+## Objective
+
+Ensure adr-review skill is ALWAYS triggered automatically when an ADR is created or updated, regardless of which agent performs the operation.
+
+## Customer Impact (Working Backwards)
+
+**Before**: Users must manually request ADR review after architect creates ADRs (discovered in Session 91 with ADR-021).
+
+**After**: ADR review is automatic - architect signals orchestrator with MANDATORY routing, orchestrator enforces the gate.
+
+**Result**: All ADRs receive multi-agent validation without manual intervention.
+
+## Implementation Plan
+
+Based on analysis at `.agents/analysis/adr-review-trigger-fix.md`:
+
+| Change | File | Purpose |
+|--------|------|---------|
+| 1 | `src/claude/architect.md` | Add BLOCKING gate to handoff protocol |
+| 2 | `src/claude/orchestrator.md` | Add ADR Review Enforcement section |
+| 3 | `AGENTS.md` | Add global ADR Review Requirement |
+| 4 | `.claude/skills/adr-review/SKILL.md` | Update with MANDATORY enforcement language |
+
+## Limitation Note
+
+The user correctly identified that this fix is a workaround, not a fundamental solution:
+
+**Root Cause**: Claude Code skills are **pull-based**, not **push-based**. There's no automatic skill invocation based on file operations or context detection.
+
+**Why This Matters**: The skill documentation said "triggers on...when architect creates ADR" but this was aspirational documentation, not implemented behavior.
+
+**This Fix**: Adds explicit BLOCKING gates in agent prompts so they signal and invoke the skill manually.
+
+**True Solution** (out of scope): Would require Claude Code framework changes:
+
+- Event-driven skill invocation
+- File pattern matching for automatic activation
+- Push-based skill triggering
+
+## Protocol Compliance
+
+### Session End Checklist
+
+| Step | Status | Evidence |
+|------|--------|----------|
+| [x] Session log created | PASS | This file |
+| [x] All changes committed | PASS | 4d61706 |
+| [x] PR created | PASS | #467 |
+| [ ] HANDOFF context stored | Pending | |
+| [x] Markdownlint run | PASS | 0 errors in changed files |
+| [ ] Validation script | Pending | |
+
+## References
+
+- [Session 91 Analysis](/.agents/analysis/adr-review-trigger-fix.md) - Root cause and fix design
+- [Session 91 Log](/.agents/sessions/2025-12-27-session-91-issue-357-quality-gate-prompts.md) - Discovery context

.claude/skills/adr-review/SKILL.md

@@ -11,10 +11,37 @@ Multi-agent debate pattern for rigorous ADR validation. Orchestrates 6 specializ
 
 ## When to Use
 
-- User requests ADR review ("review this ADR", "validate this decision")
-- Architect creates or updates an ADR
-- Orchestrator detects ADR file changes
-- Strategic decisions require multi-perspective validation
+**MANDATORY Triggers** (automatic, non-negotiable):
+
+- Architect creates or updates an ADR and signals orchestrator
+- ANY agent creates or updates a file matching `.agents/architecture/ADR-*.md`
+- Orchestrator detects ADR creation/update signal from agent output
+
+**User-Initiated Triggers** (manual):
+
+- User explicitly requests ADR review ("review this ADR", "validate this decision")
+- User requests multi-perspective validation for strategic decisions
+
+**Enforcement**:
+
+The architect agent is configured to ALWAYS signal orchestrator with MANDATORY routing when ADR files are created/updated. Orchestrator is configured to BLOCK workflow continuation until adr-review completes.
+
+**Scope**:
+
+- Primary location: `.agents/architecture/ADR-*.md`
+- Secondary location: `docs/architecture/ADR-*.md` (if project uses this structure)
+
+**Anti-Pattern**:
+
+- Architect routes to planner without adr-review
+- Orchestrator proceeds to next agent without invoking adr-review
+- User must manually request adr-review after ADR creation
+
+**Correct Pattern**:
+
+- Architect signals orchestrator: "MANDATORY: invoke adr-review"
+- Orchestrator invokes adr-review skill
+- Workflow continues only after adr-review completes
 
 ## Agent Roles
 

AGENTS.md

@@ -852,6 +852,46 @@ analyst → high-level-advisor → independent-thinker → critic → roadmap 
 
 ---
 
+### ADR Review Requirement (MANDATORY)
+
+**Rule**: ALL ADRs created or updated MUST trigger the adr-review skill before workflow continues.
+
+**Scope**: Applies to ADR files matching `.agents/architecture/ADR-*.md` and `docs/architecture/ADR-*.md`
+
+**Enforcement**:
+
+| Agent | Responsibility |
+|-------|----------------|
+| **architect** | Signal MANDATORY routing to orchestrator when ADR created/updated |
+| **orchestrator** | Detect signal and invoke adr-review skill before routing to next agent |
+| **implementer** | If creating ADR, signal MANDATORY routing to orchestrator |
+| **All agents** | Do NOT bypass adr-review by directly routing to next agent |
+
+**Blocking Gate**:
+
+```text
+IF ADR created/updated:
+  1. Agent returns to orchestrator with MANDATORY routing signal
+  2. Orchestrator invokes adr-review skill
+  3. adr-review completes (may take multiple rounds)
+  4. Orchestrator routes to next agent only after adr-review PASS
+
+VIOLATION: Routing to next agent without adr-review is a protocol violation.
+```
+
+**Skill Invocation**:
+
+```bash
+# Orchestrator invokes adr-review skill
+Skill(skill="adr-review", args="[path to ADR file]")
+```
+
+**Rationale**: All ADRs benefit from multi-agent validation (architect, critic, independent-thinker, security, analyst, high-level-advisor) coordinated by adr-review skill.
+
+**Related**: See `.claude/skills/adr-review/SKILL.md` for debate protocol details.
+
+---
+
 ### Planner – Implementation Planning
 
 **Role**: Turns epics into concrete, implementation-ready plans. Orchestrates impact analysis consultations for multi-domain changes.

src/claude/architect.md

@@ -442,7 +442,31 @@ mcp__cloudmcp-manager__memory-create_entities
 
 **As a subagent, you CANNOT delegate**. Return results to orchestrator.
 
-When review is complete:
+### ADR Creation/Update Protocol (BLOCKING)
+
+When you create or update an ADR file matching `.agents/architecture/ADR-*.md`:
+
+1. Save ADR to `.agents/architecture/ADR-NNNN-[title].md`
+2. Update architecture changelog if needed
+3. Store decision in memory
+4. Return to orchestrator with **MANDATORY routing**:
+
+```text
+ADR created/updated: [path to ADR file]
+
+MANDATORY: Orchestrator MUST invoke adr-review skill before proceeding.
+
+Command:
+  Skill(skill="adr-review", args="[path to ADR file]")
+
+Rationale: All ADRs require multi-agent validation per adr-review protocol.
+```
+
+**BLOCKING REQUIREMENT**: You MUST NOT recommend routing to any other agent (planner, implementer, etc.) until adr-review completes. Orchestrator is responsible for enforcing this gate.
+
+### Non-ADR Review Handoff
+
+When review is complete and NO ADR was created/updated:
 
 1. Save findings to `.agents/architecture/`
 2. Update architecture changelog if decisions made

src/claude/orchestrator.md

@@ -663,6 +663,40 @@ Assess complexity BEFORE selecting agents:
 1. **Security agent ALWAYS for**: Files matching `**/Auth/**`, `.githooks/*`, `*.env*`
 2. **QA agent ALWAYS after**: Any implementer changes
 3. **Critic agent BEFORE**: Multi-domain implementations
+4. **adr-review skill ALWAYS after**: ADR creation/update (see below)
+
+### ADR Review Enforcement (BLOCKING)
+
+When ANY agent returns output indicating ADR creation/update:
+
+**Detection Pattern**:
+
+- Agent output contains: "ADR created/updated: .agents/architecture/ADR-*.md"
+- Agent output contains: "MANDATORY: Orchestrator MUST invoke adr-review"
+
+**Enforcement**:
+
+```text
+BLOCKING GATE: ADR Review Required
+
+1. Verify ADR file exists at specified path
+2. Invoke adr-review skill:
+
+   Skill(skill="adr-review", args="[ADR file path]")
+
+3. Wait for adr-review completion
+4. Only after adr-review completes, route to next agent per original plan
+
+DO NOT route to next agent until adr-review completes.
+```
+
+**Failure Handling**:
+
+| Condition | Action |
+|-----------|--------|
+| ADR file not found | Report error to user, halt workflow |
+| adr-review skill unavailable | Report error to user, document gap, proceed with warning |
+| adr-review fails | Review failure output, decide to retry or escalate to user |
 
 ### Consistency Checkpoint (Pre-Critic)
 

src/copilot-cli/architect.agent.md

@@ -382,7 +382,33 @@ mcp__cloudmcp-manager__memory-create_entities
 
 ## Handoff Protocol
 
-When review is complete:
+**As a subagent, you CANNOT delegate**. Return results to orchestrator.
+
+### ADR Creation/Update Protocol (BLOCKING)
+
+When you create or update an ADR file matching `.agents/architecture/ADR-*.md`:
+
+1. Save ADR to `.agents/architecture/ADR-NNNN-[title].md`
+2. Update architecture changelog if needed
+3. Store decision in memory
+4. Return to orchestrator with **MANDATORY routing**:
+
+```text
+ADR created/updated: [path to ADR file]
+
+MANDATORY: Orchestrator MUST invoke adr-review skill before proceeding.
+
+Command:
+  Skill(skill="adr-review", args="[path to ADR file]")
+
+Rationale: All ADRs require multi-agent validation per adr-review protocol.
+```
+
+**BLOCKING REQUIREMENT**: You MUST NOT recommend routing to any other agent (planner, implementer, etc.) until adr-review completes. Orchestrator is responsible for enforcing this gate.
+
+### Non-ADR Review Handoff
+
+When review is complete and NO ADR was created/updated:
 
 1. Save findings to `.agents/architecture/`
 2. Update architecture changelog if decisions made

src/copilot-cli/orchestrator.agent.md

@@ -590,6 +590,40 @@ Assess complexity BEFORE selecting agents:
 1. **Security agent ALWAYS for**: Files matching `**/Auth/**`, `.githooks/*`, `*.env*`
 2. **QA agent ALWAYS after**: Any implementer changes
 3. **Critic agent BEFORE**: Multi-domain implementations
+4. **adr-review skill ALWAYS after**: ADR creation/update (see below)
+
+### ADR Review Enforcement (BLOCKING)
+
+When ANY agent returns output indicating ADR creation/update:
+
+**Detection Pattern**:
+
+- Agent output contains: "ADR created/updated: .agents/architecture/ADR-*.md"
+- Agent output contains: "MANDATORY: Orchestrator MUST invoke adr-review"
+
+**Enforcement**:
+
+```text
+BLOCKING GATE: ADR Review Required
+
+1. Verify ADR file exists at specified path
+2. Invoke adr-review skill:
+
+   Skill(skill="adr-review", args="[ADR file path]")
+
+3. Wait for adr-review completion
+4. Only after adr-review completes, route to next agent per original plan
+
+DO NOT route to next agent until adr-review completes.
+```
+
+**Failure Handling**:
+
+| Condition | Action |
+|-----------|--------|
+| ADR file not found | Report error to user, halt workflow |
+| adr-review skill unavailable | Report error to user, document gap, proceed with warning |
+| adr-review fails | Review failure output, decide to retry or escalate to user |
 
 ## Consistency Checkpoint (Pre-Critic)
 

src/vs-code-agents/architect.agent.md

@@ -382,7 +382,33 @@ mcp__cloudmcp-manager__memory-create_entities
 
 ## Handoff Protocol
 
-When review is complete:
+**As a subagent, you CANNOT delegate**. Return results to orchestrator.
+
+### ADR Creation/Update Protocol (BLOCKING)
+
+When you create or update an ADR file matching `.agents/architecture/ADR-*.md`:
+
+1. Save ADR to `.agents/architecture/ADR-NNNN-[title].md`
+2. Update architecture changelog if needed
+3. Store decision in memory
+4. Return to orchestrator with **MANDATORY routing**:
+
+```text
+ADR created/updated: [path to ADR file]
+
+MANDATORY: Orchestrator MUST invoke adr-review skill before proceeding.
+
+Command:
+  Skill(skill="adr-review", args="[path to ADR file]")
+
+Rationale: All ADRs require multi-agent validation per adr-review protocol.
+```
+
+**BLOCKING REQUIREMENT**: You MUST NOT recommend routing to any other agent (planner, implementer, etc.) until adr-review completes. Orchestrator is responsible for enforcing this gate.
+
+### Non-ADR Review Handoff
+
+When review is complete and NO ADR was created/updated:
 
 1. Save findings to `.agents/architecture/`
 2. Update architecture changelog if decisions made

src/vs-code-agents/orchestrator.agent.md

@@ -590,6 +590,40 @@ Assess complexity BEFORE selecting agents:
 1. **Security agent ALWAYS for**: Files matching `**/Auth/**`, `.githooks/*`, `*.env*`
 2. **QA agent ALWAYS after**: Any implementer changes
 3. **Critic agent BEFORE**: Multi-domain implementations
+4. **adr-review skill ALWAYS after**: ADR creation/update (see below)
+
+### ADR Review Enforcement (BLOCKING)
+
+When ANY agent returns output indicating ADR creation/update:
+
+**Detection Pattern**:
+
+- Agent output contains: "ADR created/updated: .agents/architecture/ADR-*.md"
+- Agent output contains: "MANDATORY: Orchestrator MUST invoke adr-review"
+
+**Enforcement**:
+
+```text
+BLOCKING GATE: ADR Review Required
+
+1. Verify ADR file exists at specified path
+2. Invoke adr-review skill:
+
+   Skill(skill="adr-review", args="[ADR file path]")
+
+3. Wait for adr-review completion
+4. Only after adr-review completes, route to next agent per original plan
+
+DO NOT route to next agent until adr-review completes.
+```
+
+**Failure Handling**:
+
+| Condition | Action |
+|-----------|--------|
+| ADR file not found | Report error to user, halt workflow |
+| adr-review skill unavailable | Report error to user, document gap, proceed with warning |
+| adr-review fails | Review failure output, decide to retry or escalate to user |
 
 ## Consistency Checkpoint (Pre-Critic)