diff --git a/.adr-dir b/.adr-dir
new file mode 100644
index 00000000..c73b64ae
--- /dev/null
+++ b/.adr-dir
@@ -0,0 +1 @@
+docs/adr
diff --git a/README.md b/README.md
index c4c8480b..57033a31 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,15 @@ Find a working example of a new-style providers in the [Palo Alto Firewall modul
 
 ## [Find the full Resource API documentation here](https://puppet.com/docs/puppet/latest/custom_resources.html)
 
+## Design Decisions
+
+<!-- adrlog -->
+
+* [ADR-0001](docs/adr/0001-test-the-resource-api-again-jruby-as-well-as-ruby-engines.md) - Test the resource api again jruby as well as ruby engines
+* [ADR-0002](docs/adr/0002-split-gemfile-dependencies-by-jruby-and-ruby-engines.md) - Split Gemfile dependencies by jruby and ruby engines
+
+<!-- adrlogstop -->
+
 ## Related Documents
 
 * The [Resource API specs](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) describes details of all the capabilities of this gem.
@@ -26,8 +35,27 @@ The `puppet-resource_api` gem is part of Puppet from version 6 onward.
 
 
 ## Contributing
+
 We welcome bug reports and pull requests on the Resource API so that we can continue to improve it to the best of our ability. If you would like to contribute, [have a look at our GitHub](https://github.com/puppetlabs/puppet-resource_api) and the [Resource API Backlog](https://github.com/puppetlabs/puppet-resource_api/projects/1).
 
+If making a change to code warrants more explanation, then consider adding a separate design decision document or `ADR`:
+
+* [adr-tools](https://github.com/npryce/adr-tools)
+* [adr-log](https://github.com/adr/adr-log)
+
+Follow these steps to add a new design decision and update the README:
+
+```bash
+# create a new design decision, e.g., `adr new "Title of your design decision"`
+adr new "Do whiteboard wednesday talks" 
+
+# fill in the "Context", "Decision", and "Consequences" of the new doc
+vim doc/adr/0002-do-whiteboard-wednesday-talks.md
+
+# update the `README.md` table of contents to include the newest design decision
+adr-log -i README.md -d doc
+```
+
 
 ## Known Issues
 
diff --git a/docs/adr/0001-test-the-resource-api-again-jruby-as-well-as-ruby-engines.md b/docs/adr/0001-test-the-resource-api-again-jruby-as-well-as-ruby-engines.md
new file mode 100644
index 00000000..3601c1aa
--- /dev/null
+++ b/docs/adr/0001-test-the-resource-api-again-jruby-as-well-as-ruby-engines.md
@@ -0,0 +1,23 @@
+# 1. Test the resource api again jruby as well as ruby engines
+
+Date: 2024-06-17
+
+## Status
+
+Accepted
+
+## Context
+
+The issue motivating this decision, and any context that influences or constrains the decision.
+
+  # since the Resource API runs inside the puppetserver, test against the JRuby versions we ship
+  # these require special dependencies to have everything load properly
+  # rubocop 1.48 supports JRuby 9.3+, which includes coverage for versions we support
+
+## Decision
+
+The change that we're proposing or have agreed to implement.
+
+## Consequences
+
+What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.
diff --git a/docs/adr/0002-split-gemfile-dependencies-by-jruby-and-ruby-engines.md b/docs/adr/0002-split-gemfile-dependencies-by-jruby-and-ruby-engines.md
new file mode 100644
index 00000000..7ee0dad7
--- /dev/null
+++ b/docs/adr/0002-split-gemfile-dependencies-by-jruby-and-ruby-engines.md
@@ -0,0 +1,19 @@
+# 2. Split Gemfile dependencies by jruby and ruby engines
+
+Date: 2024-06-17
+
+## Status
+
+Accepted
+
+## Context
+
+The issue motivating this decision, and any context that influences or constrains the decision.
+
+## Decision
+
+The change that we're proposing or have agreed to implement.
+
+## Consequences
+
+What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.