diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..876c06b
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,15 @@
+{
+  "extraKnownMarketplaces": {
+    "reqstool-ai": {
+      "source": {
+        "source": "github",
+        "repo": "reqstool/reqstool-ai"
+      },
+      "autoUpdate": true
+    }
+  },
+  "enabledPlugins": {
+    "reqstool@reqstool-ai": true,
+    "reqstool-openspec@reqstool-ai": true
+  }
+}
diff --git a/.gitignore b/.gitignore
index afad91f..f686b5d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,4 +39,5 @@ bin/
 .DS_Store
 
 ### Claude Code ###
-.claude/
+.claude/*
+!.claude/settings.json
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 075b1f7..c457d84 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,6 +8,8 @@ For DCO sign-off, commit conventions, and code review process, see the organizat
 
 - Java 21+
 - Gradle 9.3+ (use the wrapper)
+- [reqstool](https://github.com/reqstool/reqstool-client) (`pipx install reqstool`)
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) (`npm install -g @fission-ai/openspec`)
 
 ## Setup
 
@@ -16,6 +18,18 @@ git clone https://github.com/reqstool/reqstool-java-gradle-plugin.git
 cd reqstool-java-gradle-plugin
 ```
 
+If using Claude Code, opening this repo will prompt you to confirm adding the `reqstool-ai`
+marketplace and enabling the `reqstool`/`reqstool-openspec` plugins (configured in
+`.claude/settings.json`) — accept the prompt.
+
+Then regenerate the `opsx` slash commands and OpenSpec skills
+(`.claude/commands/opsx/`, `.claude/skills/openspec-*`) — they're CLI-generated tool scaffolding,
+not committed to the repo:
+
+```bash
+openspec update   # or: openspec init --tools claude --force
+```
+
 ## Build & Test
 
 ```bash