Best Practice Driven
Development
Declare quality first. Then align everything to it.
BPDD is a Red-Green-Refactor compliance cycle powered by grimoire skills. Define what "good" looks like in grimoire.toml, run a compliance check to find gaps, apply the matching grimoire skill to fix them, and repeat until all practices pass.
The Problem
AI knows the practices. It won't enforce them.
- ✗ AI applies different standards each run
- ✗ No way to audit which practices were applied
- ✗ Quality depends on prompt quality
- ✗ Human review misses gaps that survived the chat
- ✓ Spec declared once in
grimoire.toml - ✓ Same criteria applied every run — no inconsistency
- ✓ LSP-compatible compliance reports for CI and editors
- ✓ Gaps that survive human review get caught by the check
The BPDD Cycle
Red → Green → Refactor → Commit
Identical to TDD — but for any artifact, any domain.
Red — run compliance check
Run /check-best-practice-compliance. Grimoire evaluates the artifact against your grimoire.toml spec and identifies every failing or partial practice.
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
~ apply-solid-principles 60% (3/5 criteria)
Coverage: 61.1% · Threshold: 80% · Result: FAIL Green — apply the grimoire skill
Invoke the matching grimoire skill for each failing practice. /fix-best-practice-finding targets a specific finding with location context. /apply-best-practice-driven-development drives the full cycle automatically until all practices pass.
Refactor — clean while staying green
Clean up the implementation while keeping the compliance check green. Suppressed findings appear as "status": "suppressed" in the JSON report — never silently dropped.
Commit — return to step 1
Record progress. Return to step 1 for the next gap. When the full compliance report passes the threshold, the artifact matches the spec.
How It Works
Grimoire as a linter — for any domain
check-best-practice-compliance works like ESLint or Rubocop — but for best practices across any domain. Encode quality criteria once in grimoire.toml. Same criteria every run.
grimoire.toml
[standards] profiles = ["oop"] [standards.engineering.architecture] practices = ["apply-solid-principles", "apply-law-of-demeter"] compliance-threshold = 80 compliance-threshold-error = 0 # fail if any errors remain
LSP-compatible JSON
Structured report with uri, range, severity — consumable by any editor, CI pipeline, or downstream skill.
HTML report
Browser-viewable compliance summary with per-practice breakdown. Uploadable as a CI artifact.
CI gating
Check threshold.status in the JSON to gate a pipeline. Incremental mode checks only changed lines for speed.
Three Core Workflows
Pick the right skill for the task
BPDD uses three skills depending on how much automation you want.
/check-best-practice-compliance One-off check against current spec. Produces compliance report. Use to audit any artifact at any time. Scope options: specific file, region, changed-only (for CI), or full project.
/fix-best-practice-finding Targeted fix for one specific compliance finding. Location-aware — passes the exact file, line range, and violation to the skill so it can fix the precise section.
/apply-best-practice-driven-development Full systematic alignment. Drives the Red-Green-Refactor cycle automatically until all declared practices pass. Shows what it's aligning to before starting. Use for a complete BPDD pass.
Domain-Agnostic
Works for any artifact, any domain
The cycle is identical regardless of domain. A legal clause is a text file; line/character still points to the problematic section. A training program is a document; the compliance check still identifies which best practices fail.
SOLID, DDD, OWASP, SRE runbooks, CI pipeline standards
Contract clauses, GDPR DPA requirements, ABA standards
Business plans, OKRs, competitive analysis frameworks
Clinical notes, WHO protocols, evidence-based guidelines
Campaign briefs, SEO audits, attribution models
Training programs, NSCA periodization standards
FAQ
Best Practice Driven Development — FAQ
What is Best Practice Driven Development (BPDD)?
BPDD is a Red-Green-Refactor compliance cycle powered by grimoire skills. Declare what "good" looks like in grimoire.toml, run check-best-practice-compliance to find gaps, apply grimoire skills to fix them, and repeat until all practices pass. Works for code, contracts, business plans, training programs — any work product.
How is BPDD different from TDD?
TDD is code-specific: write a failing test, make it pass, refactor. BPDD extends this pattern to any domain and any artifact. Instead of test files, the spec is grimoire.toml. Instead of a test runner, the check is check-best-practice-compliance. The artifact can be a legal clause, a workout plan, or a marketing brief — not just code.
How do I configure BPDD for my project?
Create grimoire.toml in your project root. Add profiles = ["oop"] under [standards] to activate skill bundles, or list practices explicitly under [standards.domain.subdomain]. Set compliance-threshold = 80 to gate CI at 80% minimum coverage.
Does BPDD work in CI?
Yes. Use incremental mode (changed-only scope) as a pre-commit hook or CI step. Check threshold.status in the JSON output to gate the pipeline. Set compliance-threshold-error = 0 to fail if any error-severity violations remain. The report follows the LSP Diagnostic schema.
Does BPDD only work for engineering?
No. BPDD works for any domain grimoire covers — engineering, law, medicine, finance, marketing, sports, and 21 more. The compliance cycle is identical regardless of domain. A legal clause is a text file; the compliance check still identifies which practices fail at which line.
Start using BPDD today
Install grimoire in 60 seconds. All BPDD skills are included.
curl -fsSL https://raw.githubusercontent.com/jeffreytse/grimoire/main/scripts/install.sh | bash grimoire update grimoire install
Works with every AI assistant