Help us improve
Share bugs, ideas, or general feedback.
From grimoire
Checks any artifact or work product against stated best practice preferences from settings.toml. Outputs LSP-compatible JSON diagnostics and an HTML coverage report.
npx claudepluginhub jeffreytse/grimoire --plugin grimoireHow this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:check-best-practice-complianceThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Run a compliance check against any artifact using the resolved effective preferences from settings.toml. Outputs LSP-compatible JSON (machine-readable, editor-consumable) and an HTML coverage report (human-readable).
Systematically aligns any project or artifact to declared best practice preferences using a Red-Green-Refactor cycle driven by settings.toml and profiles. Works for codebases, legal docs, business plans, and more.
Produces a conformance verdict (OK/WARN/FAIL) with gap roadmap and adversarial debate proof. Audit code against industry best practices.
Pre-commit quality gate validating logic correctness, error handling, regressions, and completeness in code changes. Auto-fires before commit via cook or on large diffs.
Share bugs, ideas, or general feedback.
Run a compliance check against any artifact using the resolved effective preferences from settings.toml. Outputs LSP-compatible JSON (machine-readable, editor-consumable) and an HTML coverage report (human-readable).
Adopted by: Linters (ESLint, Checkstyle, Rubocop), architecture validation tools (ArchUnit), and policy-as-code frameworks (OPA, Conftest) encode quality criteria once and run them repeatedly against any artifact. Google's Tricorder runs 30+ analyzers on every CL and blocks 15–20% that would have passed human review; false-positive rate kept below 5% by restricting to well-defined criteria (Sadowski et al., ICSE 2015).
Impact: Manual best-practice review is inconsistent — what gets checked depends on who reviews and when. A compliance check applies the same criteria every run and produces a structured, comparable result. Coverage metrics make progress visible: teams that track compliance coverage improve it (Hawthorne effect for quality metrics, confirmed in code review studies at Microsoft Research).
Why best: review-best-practice-fit is one-shot and subjective. check-best-practice-compliance is repeatable, explicit, and machine-readable — it runs against the user's actual stated preferences (resolved from settings), producing LSP-compatible diagnostics that any editor or CI system can consume directly.
Sources: Sadowski et al. (2015) "Tricorder: Building a Program Analysis Ecosystem Inside Google"; Ford, Parsons, Kua (2017) "Building Evolutionary Architectures"; ESLint architecture documentation
Apply all settings layers in precedence order (session > project-local > project-shared > global). Expand profiles, apply domain overrides, remove disabled entries. The resolved spec is the check suite — not any individual layer.
Scope:
[s] Specific artifact — a file, document, section, or component
[r] Region / scope — a directory, chapter, module, or area
[c] Changed only — diff-based, checks only modified parts (fast, for CI/pre-commit)
[a] Full project — everything in scope of the settings
For each practice in the resolved spec, check the target artifact against its observable criteria. Each criterion: pass, fail, partial, or suppressed (via inline annotation).
False positive suppression — any finding can be suppressed inline. Suppressed findings are never dropped from output — they appear as "status": "suppressed" in JSON.
# grimoire-ignore: apply-solid-principles/srp
class LegacyAdapter: ... # intentional god class — refactor blocked by contract
# grimoire-ignore-start: apply-low-coupling
... third-party integration block ...
# grimoire-ignore-end
Always written to .grimoire/reports/compliance-<timestamp>.json and .grimoire/reports/compliance-latest.json.
LSP-compatible schema — consumable by editors, CI pipelines, LSP servers, dashboards:
{
"version": "1",
"timestamp": "2026-06-09T14:32:00Z",
"mode": "full",
"scope": "src/contracts/VendorAgreement.md",
"spec": {
"sources": [".grimoire/settings.toml", "~/.config/grimoire/settings.toml"],
"resolved_from": "project-shared + global"
},
"result": "fail",
"coverage": {
"overall_pct": 61.1,
"practices": { "total": 4, "passing": 1, "partial": 1, "failing": 2, "coverage_pct": 37.5 },
"criteria": { "total": 18, "passing": 11, "failing": 7, "suppressed": 1, "coverage_pct": 61.1 }
},
"threshold": { "required": 80, "actual": 61.1, "status": "fail" },
"summary": { "error": 2, "warning": 1, "info": 0, "pass": 11, "suppressed": 1 },
"diagnostics": [
{
"uri": "file:///project/src/contracts/VendorAgreement.md",
"range": { "start": { "line": 42, "character": 0 }, "end": { "line": 58, "character": 0 } },
"severity": 1,
"code": "audit-gdpr-compliance/dpa-required",
"source": "grimoire",
"message": "No data processing agreement section found — GDPR Art.28 requires one before processing EU customer data",
"practice": "audit-gdpr-compliance",
"criterion": "dpa-required",
"status": "fail",
"coverage": { "total": 5, "passing": 2, "coverage_pct": 40.0 }
},
{
"uri": "file:///project/src/UserService.ts",
"range": { "start": { "line": 12, "character": 0 }, "end": { "line": 45, "character": 1 } },
"severity": 2,
"code": "apply-solid-principles/srp",
"source": "grimoire",
"message": "UserService handles auth, email, and billing (3 concerns) — violates SRP",
"practice": "apply-solid-principles",
"criterion": "srp",
"status": "suppressed",
"suppressed_by": "inline",
"coverage": { "total": 5, "passing": 3, "coverage_pct": 60.0 }
}
]
}
LSP severity: 1 = Error (FAIL) · 2 = Warning (PARTIAL) · 3 = Information · 4 = Hint
Incremental mode ([c] changed only): output includes "mode": "incremental" and "base_ref": "HEAD~1" so downstream tools know what was checked.
Always generated alongside JSON at .grimoire/reports/compliance-<timestamp>.html.
Structure:
Color coding: green (pass) · red (fail) · amber (partial) · grey (suppressed). Suitable for browser viewing or CI artifact upload.
Compliance report — src/contracts/VendorAgreement.md
✓ apply-kiss-principle 100% (3/3 criteria)
✗ audit-gdpr-compliance 40% (2/5 criteria)
ERROR §42–58: No DPA section — GDPR Art.28 requires one
ERROR §12: Liability cap missing — required for processor agreements
~ apply-solid-principles 60% (3/5 criteria, 1 suppressed)
✗ apply-domain-driven-design 0% (0/4 criteria)
Coverage: 61.1% · Threshold: 80% · Result: FAIL
Reports: .grimoire/reports/compliance-2026-06-09T14-32.json
.grimoire/reports/compliance-2026-06-09T14-32.html
For each FAIL, offer to invoke the relevant grimoire skill, or run the full BPDD cycle:
Fix with:
[1] audit-gdpr-compliance — add DPA section and liability clause
[2] apply-domain-driven-design — extract domain model
[a] Run full BPDD cycle → /apply-best-practice-driven-development
Checking against a single settings layer instead of the resolved spec. Always resolve the full precedence chain — project overrides global.
Treating suppressed findings as passing. Suppressed findings are excluded from coverage calculation but counted separately. Review suppressions periodically — suppressed ≠ acceptable.
Setting threshold to 100% on legacy projects. Start with the current coverage as baseline, improve incrementally. A threshold below current = no gate; set it at current + 10% to enforce improvement without blocking work.
review-best-practice-fit to discover what practices apply; use this when you know your spec and want to verify alignment