From copilot-cli-toolkit
Orchestrates multi-agent debates to review and validate Architecture Decision Records (ADRs). Auto-triggers on ADR create/edit/delete in .agents/architecture or docs/architecture; manual via /adr-review or phrases like 'review this ADR'.
npx claudepluginhub rjmurillo/ai-agentsThis skill uses the workspace's default tool permissions.
Multi-agent debate pattern for rigorous ADR validation. Orchestrates 6 specialized agents through structured review rounds until consensus or 10 rounds maximum.
Orchestrates multi-agent debate to review Architecture Decision Records (ADRs). Auto-triggers on create/edit/delete of ADR Markdown files in .agents/architecture or docs/architecture, coordinating architect, critic, security, analyst agents to consensus.
Reviews Architecture Decision Records (ADRs) for quality and completeness: accept, reject, or revise proposed ones; deprecate accepted ones enforcing immutability. Use for reviewing proposed ADRs or deprecating accepted ones.
Guides authoring clear, enforceable Architectural Decision Records (ADRs) compatible with AI review systems and human teams. Useful for creating, improving, reviewing ADRs or PRs referencing them.
Share bugs, ideas, or general feedback.
Multi-agent debate pattern for rigorous ADR validation. Orchestrates 6 specialized agents through structured review rounds until consensus or 10 rounds maximum.
| Trigger Phrase | Operation |
|---|---|
review this ADR | Full 6-agent debate on specified ADR |
validate ADR-005 | Targeted review of specific ADR by number |
check architecture decision | ADR review with debate protocol |
ADR file created or modified | Auto-triggered via detect_adr_changes.py |
delete ADR-NNN | Deletion workflow (D1-D4) |
# Manual triggers:
/adr-review .agents/architecture/ADR-005-api-versioning.md
"review this ADR"
"validate ADR-005"
Automatic Detection: A Claude Code hook runs at session start and detects ADR changes, prompting you to invoke this skill. The pre-commit hook also detects staged ADR files and displays a reminder.
| Input | Output | Consensus Required |
|---|---|---|
| ADR file path | Debate log + Updated ADR | 6/6 Accept or D&C |
| Pattern | Location | Events |
|---|---|---|
ADR-*.md | .agents/architecture/ | create, update, delete |
ADR-*.md | docs/architecture/ | create, update, delete |
SESSION-PROTOCOL.md | .agents/ | create, update, delete |
Detection: .claude/skills/adr-review/scripts/detect_adr_changes.py
MANDATORY Triggers (automatic):
.agents/architecture/ADR-*.md.agents/SESSION-PROTOCOL.mdUser-Initiated Triggers (manual):
| Agent | Focus | Tie-Breaker Role |
|---|---|---|
| architect | Structure, governance, coherence, ADR compliance | Structural questions |
| critic | Gaps, risks, alignment, completeness | None |
| independent-thinker | Challenge assumptions, surface contrarian views | None |
| security | Threat models, security trade-offs | None |
| analyst | Root cause, evidence, feasibility | None |
| high-level-advisor | Priority, resolve conflicts, break ties | Decision paralysis |
| Phase | Purpose | Details |
|---|---|---|
| Phase 0 | Related work research | Search issues/PRs for context |
| Phase 1 | Independent review | Each agent reviews ADR using Zimmermann 7-question checklist |
| Phase 2 | Consolidation | Identify consensus and conflicts; flag review anti-patterns |
| Phase 3 | Resolution | Propose updates for P0/P1 issues |
| Phase 4 | Convergence check | Agents vote: Accept/D&C/Block |
Consensus: All 6 agents Accept OR Disagree-and-Commit. Max 10 rounds.
See references/debate-protocol.md for full phase details.
| Phase | Purpose |
|---|---|
| D1 | Detection - identify deleted ADR |
| D2 | Impact assessment - find dependencies |
| D3 | Archival decision - archive accepted ADRs |
| D4 | Cleanup - update references |
See references/deletion-workflow.md for full workflow.
| Priority | Requirement | Gate |
|---|---|---|
| P0 | Must resolve | BLOCKING |
| P1 | Resolve OR defer with issue | BLOCKING |
| P2 | Document | Non-blocking |
See references/issue-resolution.md for deferral protocol.
After structural and technical review, apply strategic lenses:
Overall Strategic Assessment: [APPROVED | CONCERNS | REJECTED]
Blocking Issues:
Recommendations:
| Script | Purpose |
|---|---|
detect_adr_changes.py | Detect ADR file changes for auto-trigger |
# Basic detection
python3 .claude/skills/adr-review/scripts/detect_adr_changes.py
# Compare to specific commit
python3 .claude/skills/adr-review/scripts/detect_adr_changes.py --since-commit abc123
# Include untracked ADR files
python3 .claude/skills/adr-review/scripts/detect_adr_changes.py --include-untracked
After skill invocation:
.agents/critique/ADR-NNN-debate-log.md| Avoid | Why | Instead |
|---|---|---|
| Single-agent ADR review | Misses domain expertise | Use full 6-agent debate |
| Skipping Phase 0 | Duplicates existing work | Always research first |
| Ignoring D&C dissent | Loses important context | Document all reservations |
| Manual ADR monitoring | Error-prone | Use detect_adr_changes.py |
| Deleting accepted ADRs without archive | Loses knowledge | Always archive accepted ADRs |
Each agent should self-check against these. Phase 2 consolidation flags violations.
| Anti-Pattern | Problem | Detection |
|---|---|---|
| Pass Through | Few/no comments, document barely read | Agent produces no substantive findings |
| Copy Edit | Focuses on wording, ignores content | All findings editorial, none architectural |
| Siding/Dead End | Comments switch topic, deviate from ADR | Agent drifts from decision at hand |
| Self Promotion | Recommends reviewer's preferred solution | Agent pushes technology without objective rationale |
| Power Game | Authority claims instead of technical arguments | Agent uses position over evidence |
| Offended Reaction | Defends criticized position subjectively | Agent reacts emotionally to rationale |
| Groundhog Day | Same message repeated across rounds | Agent re-raises resolved issues |
See zimmermann-review-guidance.md for full practices and pledges.
| Document | Content |
|---|---|
| debate-protocol.md | Full Phases 0-4 workflow |
| deletion-workflow.md | Phases D1-D4 workflow |
| issue-resolution.md | P0/P1/P2 handling and deferral |
| artifacts.md | Output formats and templates |
| agent-prompts.md | Detailed agent prompt templates |
| zimmermann-review-guidance.md | Review practices, 7 anti-patterns, checklist, reviewer pledge (Zimmermann 2023) |