@cognizant/adr-reviewer

AI-powered Architecture Decision Record reviewer using Claude CLI

Automatically reviews ADRs for completeness, consistency, risk coverage and scores them 1-5 against a rubric — triggered on every GitHub Pull Request.

Quick Start

# Install
npm install -g @cognizant/adr-reviewer

# Login with Claude subscription (one time)
claude login

# Setup your repo (adds GitHub Action + skills + rubric)
npx adr-reviewer setup

# Review an ADR locally
npx adr-reviewer review ADR-001

# Review all ADRs
npx adr-reviewer review --all

# Just get the score
npx adr-reviewer score ADR-001

What It Does

Every ADR gets reviewed across 4 specialist skills:

| Skill | What It Checks | |-------|----------------| | Gap Analysis | All 8 required sections present and meaningful | | Consistency Check | Cross-references all ADRs for contradictions | | Risk Assessment | 5 risk categories — operational, security, scalability, vendor, team | | Scoring | 1-5 score with rubric applied and reason per dimension |

GitHub Action Setup

Run npx adr-reviewer setup to automatically add:

• .github/workflows/adr-review.yml
• CLAUDE.md (review rubric)
• skills/ (4 specialist skills)
• docs/adr/ADR-000-template.md

Then add your Claude OAuth token to GitHub Secrets:

Settings → Secrets and Variables → Actions → New Secret
Name:  CLAUDE_OAUTH_TOKEN
Value: (run: claude config get oauthToken)

Push a change to any docs/adr/*.md file and open a PR — Claude will review automatically!

Sample PR Comment Output

# ADR Review: ADR-001

## Overall Score: 3.8/5 🟡
Good — minor improvements needed

## 📏 Scoring Breakdown
| Section      | Score | Reason |
|--------------|-------|--------|
| Completeness | 4/5   | All sections present |
| Clarity      | 4/5   | Context precise |
| Alternatives | 4/5   | 2 alternatives compared |
| Risk Coverage| 3/5   | Missing security risks |
| Consistency  | 4/5   | No contradictions |
| Overall      | 3.8/5 | (4+4+4+3+4) ÷ 5 = 3.8/5 |

## 🔍 Gap Analysis
## 🔗 Consistency Check
## ⚠️ Risk Assessment
## 🎯 Recommended Actions

Quality Gate

ADRs scoring below 3/5 automatically block the PR from merging until improved.

Customisation

Override the default rubric by adding your own CLAUDE.md to your repo root.

Override skills by adding your own skills/ folder — the package will use yours instead of the defaults.

Requirements

• Node.js 18+
• Claude CLI: npm install -g @anthropic-ai/claude-code
• Claude subscription (login with claude login)

Built by

Cognizant × Anthropic Claude Enterprise POC Team — UC-04 ADR Reviewer