Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From project-toolkit
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.
npx claudepluginhub rjmurillo/ai-agents --plugin project-toolkitHow this skill is triggered — by the user, by Claude, or both
Slash command
/project-toolkit:adr-reviewclaude-opus-4-6The summary Claude sees in its skill listing — used to decide when to auto-load this skill
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 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'.
Evaluates architectural decisions and produces Architecture Decision Records (ADRs) following the project template. Useful when making trade-offs or formalizing decisions.
Writes Architecture Decision Records (ADRs) with structured format, numbering, indexing, status lifecycle, linking, and team review processes.
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) |