adr-review
Multi-agent debate orchestration for Architecture Decision Records. Automatically triggers on ADR create/edit/delete. Coordinates architect, critic, independent-thinker, security, analyst, and high-level-advisor agents in structured debate rounds until consensus.
- License 许可
- MIT
- 最近更新
- 2026-03-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- adr-review
- model
- claude-opus-4-6[1m]
- agents
- [ "architect", "critic", "independent-thinker", "security", "analyst", "high-level-advisor" ]
- license
- MIT
- metadata
- { "type": "orchestrator", "inputs": [ "adr-file-path", "change-type" ], "domains": [ "architecture", "governance", "multi-agent", "consensus" ], "outputs": [ "debate-log", "updated-adr", "recommendations" ], "version": "1.0.0", "file_triggers": { "events": [ "create", "update", "delete" ], "patterns": [ "decisions/ADR-*.md" ], "auto_invoke": true } }
- description
- Multi-agent debate orchestration for Architecture Decision Records. Automatically triggers on ADR create/edit/delete. Coordinates architect, critic, independent-thinker, security, analyst, and high-level-advisor agents in structured debate rounds until consensus.
02 资源文件 7
- 参考文档references/agent-prompts.md11.8 KB
- 参考文档references/artifacts.md2.2 KB
- 参考文档references/debate-protocol.md5.9 KB
- 参考文档references/deletion-workflow.md2.4 KB
- 参考文档references/issue-resolution.md5.9 KB
- 脚本scripts/detect_adr_changes.ts8.6 KB
- 脚本tests/detect_adr_changes.test.ts7.8 KB
03 SKILL.md 正文
ADR Review
Multi-agent debate pattern for rigorous ADR validation. Orchestrates 6 specialized agents through structured review rounds until consensus or 10 rounds maximum.
Triggers
| 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.ts |
delete ADR-NNN |
Deletion workflow (D1-D4) |
Quick Start
# Manual triggers:
/adr-review decisions/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 |
File Triggers
| Pattern | Location | Events |
|---|---|---|
ADR-*.md |
decisions/ |
create, update, delete |
Detection: ${CLAUDE_SKILL_DIR}/scripts/detect_adr_changes.ts
When to Use
MANDATORY Triggers (automatic):
- Architect creates or updates an ADR
- ANY agent modifies
decisions/ADR-*.md
User-Initiated Triggers (manual):
- User requests ADR review ("review this ADR", "validate this decision")
- User requests multi-perspective validation for strategic decisions
Agent Roles
| 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 |
Process
| Phase | Purpose | Details |
|---|---|---|
| Phase 0 | Related work research | Search issues/PRs for context |
| Phase 1 | Independent review | Each agent reviews ADR |
| Phase 2 | Consolidation | Identify consensus and conflicts |
| 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.
Deletion Workflow
| 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.
Issue Resolution
| 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.
Phase 4: Strategic Review (Principal-Level Validation)
After structural and technical review, apply strategic lenses:
Strategic Validation Checklist
Chesterton's Fence (Change Justification)
- [ ] If removing/changing existing patterns: Original purpose documented
- [ ] Investigation evidence provided (git archaeology, interviews, documentation)
- [ ] Confirmation original problem no longer exists
- [ ] Assessment: [PASS | FAIL | N/A]
Path Dependence (Irreversibility Recognition)
- [ ] Historical constraints identified and documented
- [ ] Reversibility assessment complete (rollback capability, vendor lock-in)
- [ ] Migration/exit strategy defined if adding dependencies
- [ ] Irreversible decisions explicitly flagged and justified
- [ ] Assessment: [PASS | FAIL | N/A]
Core vs Context (Investment Prioritization)
- [ ] Capability classified as Core (differentiating) or Context (commodity)
- [ ] If building Context: Justification for not buying/outsourcing
- [ ] If Core: Competitive differentiation explained
- [ ] Assessment: [PASS | FAIL | N/A]
Second-System Effect (Over-Engineering Detection)
- [ ] If replacing existing system: Scope boundaries explicit
- [ ] Feature list justified (not "everything we didn't do last time")
- [ ] Simplicity preservation strategy documented
- [ ] Assessment: [PASS | FAIL | N/A]
Strategic Review Verdict
Overall Strategic Assessment: [APPROVED | CONCERNS | REJECTED]
Blocking Issues:
- [Strategic issue 1 with required mitigation]
- [Strategic issue 2 with required mitigation]
Recommendations:
- [Strategic improvement 1]
- [Strategic improvement 2]
Scripts
| Script | Purpose |
|---|---|
detect_adr_changes.ts |
Detect ADR file changes for auto-trigger |
# Basic detection
bun run ${CLAUDE_SKILL_DIR}/scripts/detect_adr_changes.ts
# Compare to specific commit
bun run ${CLAUDE_SKILL_DIR}/scripts/detect_adr_changes.ts --since-commit abc123
# Include untracked ADR files
bun run ${CLAUDE_SKILL_DIR}/scripts/detect_adr_changes.ts --include-untracked
Verification Checklist
After skill invocation:
- [ ] Debate log exists as Brain memory note
CRIT-{NNN}-debate-logincritique/folder - [ ] ADR status updated (proposed/accepted/needs-revision)
- [ ] All P0 issues addressed or documented
- [ ] Dissent captured for Disagree-and-Commit positions
- [ ] Recommendations provided to orchestrator
Anti-Patterns
| 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.ts |
| Deleting accepted ADRs without archive | Loses knowledge | Always archive accepted ADRs |
References
| 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 |
04 同仓库更多 Skills
validation-authority
Treat upstream validators as authoritative. Align local config to them. Use when validation fails unexpectedly, before modifying validator behavior, or when tempted to change upstream tool code.
using-brain-memory
Guidance for using Brain semantic memory effectively. Applies Zettelkasten atomic note principles with observations and relations. Use when deciding whether to query or create notes, structuring note content, or understanding the semantic knowledge graph.
threat-modeling
Structured security analysis using OWASP Four-Question Framework and STRIDE methodology. Generates threat matrices with risk ratings, mitigations, and prioritization. Use for attack surface analysis, security architecture review, or when asking what can go wrong.
taste-lints
Custom lints with agent-readable remediation instructions. Enforces taste invariants (file size, naming conventions, structured logging, complexity) and surfaces errors that agents can act on directly. Use when writing or reviewing code to catch style violations early.
style-enforcement
Validate code against style rules from .editorconfig, StyleCop.json, and Directory.Build.props. Detects line ending violations, naming convention issues, indentation problems, and charset mismatches across C#, Python, TypeScript, and JavaScript. Produces JSON reports for pre-commit hooks and CI pipelines.
steering-matcher
Match file paths against steering file glob patterns to determine applicable steering guidance. Use when orchestrator needs to inject context-aware guidance based on files being modified.