Help us improve
Share bugs, ideas, or general feedback.
From grimoire
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.
npx claudepluginhub jeffreytse/grimoire --plugin grimoireHow this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:apply-best-practice-driven-developmentThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Systematically align any project or artifact to its stated best practice preferences using a Red-Green-Refactor cycle driven by `settings.toml` and profiles. Works for codebases, legal documents, business plans, training programs, marketing campaigns — any work product with declared practices.
Checks any artifact or work product against stated best practice preferences from settings.toml. Outputs LSP-compatible JSON diagnostics and an HTML coverage report.
Produces a conformance verdict (OK/WARN/FAIL) with gap roadmap and adversarial debate proof. Audit code against industry best practices.
Facilitates structured conversation to define clean code principles for a repository, producing clean-code.md override for clean-code atom. Use for coding standards or quality rules.
Share bugs, ideas, or general feedback.
Systematically align any project or artifact to its stated best practice preferences using a Red-Green-Refactor cycle driven by settings.toml and profiles. Works for codebases, legal documents, business plans, training programs, marketing campaigns — any work product with declared practices.
Adopted by: Architecture fitness functions (Ford, Parsons, Kua — "Building Evolutionary Architectures", O'Reilly 2017) encode quality criteria as executable checks and validate continuously — the same inversion as TDD: define the check before the implementation. Netflix, Thoughtworks, and Amazon use fitness functions to enforce architectural constraints at CI time. The same principle applies beyond code: quality management systems (ISO 9001) and legal compliance frameworks define compliance criteria before auditing against them.
Impact: Without BPDD, teams apply best practices opportunistically — gaps accumulate and preferences drift silently from reality. TDD reduces defect density 40–80% (Nagappan et al., IEEE 2008) not because tests catch bugs, but because the write-test-first discipline prevents gaps from forming. BPDD applies the same mechanism to best practices across any domain.
Why best: review-best-practice-fit identifies gaps reactively, after implementation. BPDD inverts this: the preferences declared in settings are the specification; the artifact follows. The cycle continues until artifact and spec agree — leaving no gaps to discover later.
Sources: Beck (2003) "Test-Driven Development: By Example"; Ford, Parsons, Kua (2017) "Building Evolutionary Architectures"; Nagappan et al. (2008) "Realizing Quality Improvement Through Test Driven Development"
Read all settings layers in precedence order and produce the single effective spec:
session pins
↓ overrides
.grimoire/settings.local.toml (project-personal)
↓ overrides
.grimoire/settings.toml (project-shared)
↓ overrides
~/.config/grimoire/settings.toml (global)
profiles = [...] to skill lists (tag query or file)[engineering.architecture] overrides [engineering])disabled entries — remove those skills from the specDisplay the effective spec before running — the user must see what they're aligning to:
Effective spec — 5 practices
apply-solid-principles [profile: oop → .grimoire/settings.toml]
apply-domain-driven-design [profile: oop → .grimoire/settings.toml]
apply-kiss-principle [engineering.architecture → global]
apply-pyramid-principle [writing → .grimoire/settings.toml]
audit-gdpr-compliance [law → global]
⊘ apply-law-of-demeter [disabled by .grimoire/settings.toml]
Wait for confirmation. If settings are empty, stop and direct user to pin-best-practice-preference or apply-best-practice-profile first.
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
[a] Full project — everything in scope of the settings
Call check-best-practice-compliance against the selected scope using the resolved spec. Read the JSON output to classify each practice:
Compliance baseline
✓ apply-kiss-principle PASS (3/3 criteria)
✗ apply-solid-principles FAIL (2/5 criteria, 40% coverage)
~ apply-pyramid-principle PARTIAL (2/3 criteria, 67% coverage)
✗ apply-domain-driven-design FAIL (0/4 criteria, 0% coverage)
✓ audit-gdpr-compliance PASS (5/5 criteria)
Overall: 55.0% criteria coverage · threshold: 80% · STATUS: FAIL
2 passing · 2 failing · 1 partial
If all pass and threshold met: codebase already aligns with spec. Report and stop.
Priority order (explicit, shown to user):
Next: apply-solid-principles (FAIL, 40% coverage)
Reason: causing threshold failure + listed before apply-domain-driven-design
✗ SRP: UserService handles auth, email, and billing (3 concerns)
✗ DIP: direct dependency on MySQLUserRepository
✓ OCP, LSP, ISP — already passing
Read the "practice" field from each failing diagnostic in the JSON report — that value is the grimoire skill to invoke. "practice": "apply-solid-principles" → /apply-solid-principles; "practice": "apply-domain-driven-design" → /apply-domain-driven-design; and so on. Re-run check-best-practice-compliance for this practice after each change until it passes.
Clean up the implementation while keeping the check green. Re-run to confirm no regression.
Record progress. Return to step 5 for the next failing practice. Continue until all practices pass and threshold is met.
✓ BPDD complete — 5/5 practices aligned · 92% criteria coverage
✓ apply-solid-principles (fixed: 3 violations resolved)
✓ apply-domain-driven-design (fixed: domain model extracted)
✓ apply-pyramid-principle (fixed: 1 remaining gap closed)
✓ apply-kiss-principle (was already passing)
✓ audit-gdpr-compliance (was already passing)
Threshold: 92% ≥ 80% ✓
Artifact now aligns with .grimoire/settings.toml
Running BPDD without reviewing the resolved spec first. Always show step 2 — the user must confirm what spec they're aligning to. A misconfigured settings file means fixing the wrong things.
Skipping commit between cycles. Each Green must be committed before moving to the next practice — same discipline as TDD.
Ignoring suppressed findings. Suppressed violations (via # grimoire-ignore) still appear in the JSON report. Review them periodically — suppressed ≠ resolved.
review-best-practice-fit instead; BPDD is for systematic, committed alignmentpin-best-practice-preference or apply-best-practice-profile