adr-check

Validates proposed code changes against Architecture Decision Records and platform map constraints.

1|Updated Apr 8, 2026
One-click install
npx skills add https://github.com/jp5labs/forge-workflow --skill adr-check-jp5labs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: adr-check
Source: https://github.com/jp5labs/forge-workflow/tree/main/forge_workflow/templates/skills/adr-check
Command: npx skills add https://github.com/jp5labs/forge-workflow --skill adr-check-jp5labs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams with Architecture Decision Records (ADRs) often ship changes that silently violate documented architectural constraints because no one re-reads every ADR before each PR. This Skill automates that compliance check so violations are caught before delivery. ## Core Features & Use Cases - ADR Compliance Validation: Reads all ADR documents and flags violations of normative clauses (must, must not, required, denied, always, never) in proposed changes. - Platform Map Anti-Pattern Detection: Identifies attempts to build custom versions of governed platform components such as model gateways, vector stores, or workflow engines. - Structured Compliance Report: Produces a PASS/FAIL verdict with per-ADR violation details, warnings, and escalation guidance for human decision-making. - Use Case: Before merging a PR that introduces a custom caching layer, run this Skill to confirm the change does not conflict with ADRs mandating use of the existing queue/cache primitives. ## Quick Start Ask the AI to check the staged git diff or a described change against the ADRs in docs/architecture before opening the pull request.

Frequently Asked Questions about adr-check

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if a code change violates an Architecture Decision Record?

Run an ADR compliance check that reads all adr-*.md files and cross-references the proposed changes against normative clauses like must, must not, required, and denied. The result is a structured report with a PASS or FAIL verdict and per-ADR violation details.

When should I run an ADR compliance check?

Run it before architecture-affecting PRs, when implementing stories with ADR dependencies, or before delivery of changes touching ADR-governed boundaries. Catching violations early avoids rework after review.

What counts as an ADR violation during review?

Violations are conflicts with normative language in ADRs: must, must not, required, denied, prohibited, always, and never used as rules. Non-normative drift from ADR intent is reported as a warning rather than a failure.

Can this detect anti-patterns against a platform architecture map?

Yes, it checks changes against the platform map and flags building custom versions of governed components such as model gateways, vector stores, observability dashboards, workflow engines, and secret managers.

What happens when an ADR violation is found?

The full compliance report is presented to a human operator who decides whether to revise the change, update the ADR with new rationale, or accept the violation with a documented exception. The Skill does not auto-resolve conflicts.