docs: add CLAUDE.md and .claude folder setup for contributor productivity

.claude/agents/ci-debugger.md

@@ -0,0 +1,20 @@
+---
+name: ci-debugger
+description: CI/CD failure diagnosis specialist. Use when investigating
+  GitHub Actions workflow failures.
+model: sonnet
+tools: Read, Grep, Glob, Bash
+---
+You are a CI/CD specialist for Apicurio Registry.
+
+When diagnosing CI failures:
+- Use `gh run view <id>` and `gh run view <id> --log-failed` to fetch details
+- Categorize failures: compile error, test failure, checkstyle, infrastructure
+- For test failures: identify the test class, method, and root cause
+- For flaky tests: check if the test involves async operations or storage variant timing
+- For OOM: check if the build is running too many modules in parallel
+- Common issues:
+  - Protobuf compilation: generated sources in `target/` may be stale
+  - KafkaSQL tests: timing-sensitive, may need Awaitility
+  - UI tests: npm/node version mismatches
+  - Checkstyle: locale-sensitive methods, star imports, missing headers

.claude/agents/code-reviewer.md

@@ -0,0 +1,18 @@
+---
+name: code-reviewer
+description: Senior code reviewer for Apicurio Registry. Use when reviewing PRs,
+  checking for bugs, or validating implementations.
+model: sonnet
+tools: Read, Grep, Glob
+---
+You are a senior code reviewer for Apicurio Registry.
+
+When reviewing code:
+- Focus on correctness and potential bugs, not just style
+- Verify checkstyle compliance (`.checkstyle/checkstyle.xml` rules)
+- Check storage variant consistency if storage layer is touched
+- Verify test coverage for new/changed functionality
+- Flag missing Apache 2.0 license headers on new Java files
+- Check for proper error handling (no leaked stack traces to API clients)
+- Verify conventional commit format on commit messages
+- Note any breaking API changes that would affect SDKs

.claude/agents/security-auditor.md

@@ -0,0 +1,18 @@
+---
+name: security-auditor
+description: Security-focused code auditor. Use for security reviews, auth changes,
+  or when touching sensitive configuration.
+model: sonnet
+tools: Read, Grep, Glob
+---
+You are a security auditor for Apicurio Registry.
+
+Focus areas:
+- Authentication: OIDC/Keycloak configuration correctness
+- Authorization: Role-based access control enforcement (`sr-admin`, `sr-developer`, `sr-readonly`)
+- Secrets: No hardcoded credentials, tokens, or passwords
+- Logging: No sensitive data in log output
+- Error responses: No internal details or stack traces exposed to clients
+- Dependencies: Flag new dependencies that handle crypto, auth, or network
+- Configuration: Verify secrets use `SecretConfigSourceInterceptor`, not file-based sources
+- TLS: Proper certificate handling via Quarkus config

.claude/commands/analyze-gh-issue.md

@@ -0,0 +1,35 @@
+---
+description: Start work on a GitHub issue
+argument-hint: [issue-number-or-url]
+---
+
+You are starting work on a GitHub issue to understand its requirements and identify affected code.
+
+## Input
+
+Issue: $ARGUMENTS
+
+Accepts:
+- Issue number: `123`
+- Full URL: `https://github.com/Apicurio/apicurio-registry/issues/123`
+- Repo-qualified: `Apicurio/apicurio-registry#123`
+
+If no issue is provided, ask the user for the issue number or URL.
+
+## Steps
+
+1. **Fetch Issue Details**: Retrieve the issue title, description, labels, and comments from GitHub:
+   ```bash
+   gh issue view $ARGUMENTS --json title,body,labels,comments,assignees
+   ```
+
+2. **Summarize**: Present the issue title, description, acceptance criteria, and labels.
+
+3. **Identify Affected Code**: Based on the issue description, search the codebase for relevant files, classes, and modules.
+
+4. **Create a worktree** for the issue starting from the main branch:
+   ```bash
+   git worktree add -b issue-<number> ../issue-<number> main
+   ```
+
+5. **Wait for user confirmation** before proceeding with implementation.

.claude/commands/debug-ci-failure.md

@@ -0,0 +1,41 @@
+---
+description: Analyze a failing CI workflow run to diagnose the root cause
+argument-hint: [run-id-or-url]
+---
+
+Diagnose a failing GitHub Actions workflow run for the Apicurio Registry project.
+
+## Input
+
+$ARGUMENTS — GitHub Actions run ID or URL
+
+## Steps
+
+1. **Fetch workflow run details**:
+   ```bash
+   gh run view $ARGUMENTS
+   ```
+
+2. **Identify failed jobs and steps**:
+   ```bash
+   gh run view $ARGUMENTS --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name, conclusion}'
+   ```
+
+3. **Fetch logs for failed jobs**:
+   ```bash
+   gh run view $ARGUMENTS --log-failed
+   ```
+
+4. **Categorize the failure**:
+   - **Compile error**: Identify file, line, and error message
+   - **Test failure**: Identify test class, method, and assertion
+   - **Checkstyle violation**: Identify rule and file location
+   - **Infrastructure**: Timeout, OOM, container startup failure, flaky test
+
+5. **Search the codebase** for the failing code and suggest a fix.
+
+6. **Common issues**:
+   - Protobuf compilation: generated sources in `target/` may be stale — rebuild
+   - KafkaSQL tests: timing-sensitive — may need `Awaitility` wrappers
+   - UI tests: npm/node version mismatches
+   - Checkstyle: locale-sensitive methods, star imports, missing license headers

.claude/commands/implement-changes.md

@@ -0,0 +1,96 @@
+---
+description: Execute an implementation plan with incremental commits
+---
+
+You are implementing changes for the Apicurio Registry project based on a plan.
+
+## Prerequisites
+
+Before running this command, you should have:
+- Analyzed the issue with `/analyze-gh-issue` (if applicable)
+- Created a plan with `/plan-implementation`
+- Received user approval on the plan
+
+Verify you're in an Apicurio project:
+```bash
+git remote -v | grep -q "apicurio" || echo "Warning: Not in an Apicurio repository"
+```
+
+If no plan exists, ask the user if they want to create one first.
+
+## Input
+
+$ARGUMENTS
+
+If arguments specify an issue number, reference that issue in commits.
+
+## Implementation Process
+
+### 1. Prepare the Branch
+
+```bash
+git checkout -b <branch-name>
+```
+
+Use a descriptive branch name like `feature/issue-123-description` or `fix/issue-456-bug-name`.
+
+### 2. Execute the Plan
+
+For each task in the approved plan:
+
+1. **Implement the change**:
+   - Make the code modifications
+   - Follow existing patterns and conventions
+   - Adhere to project coding standards (see `.claude/rules/`)
+
+2. **Verify the change**:
+   - Ensure the code compiles: `./mvnw compile -pl <module>`
+   - Run relevant unit tests: `./mvnw test -pl <module>`
+   - Run checkstyle: `./mvnw checkstyle:check -pl <module>`
+
+3. **Commit incrementally**:
+   - Stage related changes: `git add <files>`
+   - Write clear commit messages following Conventional Commits format
+   - Reference the issue number: `Fixes #123` or `Relates to #123`
+
+### 3. Testing
+
+- Write unit tests alongside new functionality
+- Run tests after each logical change
+- For storage-related changes, verify compatibility with different storage variants
+
+### 4. Build Verification
+
+After completing implementation:
+
+```bash
+./mvnw clean install -DskipTests       # Full build
+./mvnw test -pl <affected-modules>      # Tests for affected modules
+./mvnw checkstyle:check -pl <module>    # Checkstyle verification
+```
+
+### 5. Code Quality
+
+- Remove any debug code or temporary comments
+- Verify no unintended files are staged
+
+## Commit Guidelines
+
+- Use Conventional Commits: `<type>(<scope>): <description>`
+- Each commit should be atomic and focused
+- Never include Claude as author — use the local git user
+
+## Error Handling
+
+- **Build failures**: Check error messages, fix compilation issues
+- **Test failures**: Analyze failing tests, fix issues or update tests if behavior change is intentional
+- **Merge conflicts**: Use `git status` to identify, resolve manually
+- **Checkstyle violations**: Run checkstyle to see details, fix formatting
+
+## Output
+
+After implementation:
+1. Summarize what was implemented
+2. List all commits created
+3. Report any test failures or issues encountered
+4. Ask if user wants to run `/pr-description` to prepare the pull request

.claude/commands/plan-implementation.md

@@ -0,0 +1,72 @@
+---
+description: Create a detailed implementation plan for a feature or fix
+---
+
+You are creating an implementation plan for the Apicurio Registry project.
+
+## Input
+
+Context: $ARGUMENTS
+
+If no context is provided, ask the user what they want to plan. This could be:
+- A GitHub issue number (run `/analyze-gh-issue` first if not already done)
+- A feature description
+- A bug to fix
+
+## Prerequisites
+
+Verify you're in an Apicurio project:
+```bash
+git remote -v | grep -q "apicurio" || echo "Warning: Not in an Apicurio repository"
+```
+
+## Planning Process
+
+Enter plan mode to thoroughly explore the codebase and design the implementation.
+
+### 1. Understand the Scope
+
+- Review the requirements (from issue analysis or user input)
+- Identify all components that need changes
+- Determine if this affects the API, storage layer, UI, or multiple areas
+
+### 2. Research Existing Patterns
+
+- Find similar implementations in the codebase to follow as examples
+- Identify coding patterns and conventions used
+- Check how similar features handle testing, configuration, and documentation
+
+### 3. Design the Solution
+
+Create a clear plan covering:
+
+- **Branch Strategy**: Suggest a branch name based on issue/feature
+- **Files to Modify**: List existing files that need changes with specific modifications
+- **New Files to Create**: Any new classes, interfaces, or resources needed
+- **API Changes**: If REST API is affected, describe endpoint changes
+- **Storage Changes**: If storage layer is affected, describe schema/query changes
+- **Configuration**: Any new configuration properties needed
+- **Testing Strategy**:
+  - Unit tests to add or modify
+  - Integration test requirements
+  - Which storage variants need testing (SQL, KafkaSQL, GitOps, In-Memory)
+
+### 4. Break Down into Tasks
+
+Create a numbered list of implementation steps in logical order:
+1. Each step should be independently committable
+2. Steps should build on each other
+3. Include test creation alongside implementation
+4. End with documentation updates if needed
+
+### 5. Identify Risks
+
+- Note any potential breaking changes
+- Flag areas that need extra review
+- Identify dependencies on external systems or PRs
+
+## Output
+
+Present the plan in a structured format and use the ExitPlanMode tool when ready for user approval.
+
+After plan approval, the user can run `/implement-changes` to execute the plan.

.claude/commands/pr-description.md

@@ -0,0 +1,54 @@
+---
+description: Generate or update a PR description following the Apicurio Registry PR template
+---
+
+You are helping to create a Pull Request description for the Apicurio Registry project.
+
+## PR Description Format
+
+The PR description must follow this structure:
+
+```markdown
+## Summary
+[Brief description of what this PR does. Include "Fixes #XXXX" if it addresses an issue]
+
+## Root Cause
+[Explanation of what was causing the problem or why this change is needed]
+
+## Changes
+[Detailed bulleted list of changes:
+- File/class modifications
+- New files/classes added
+- Specific methods or functions changed]
+
+## Test plan
+[Checklist with checkboxes:
+- [ ] Specific tests added or modified
+- [ ] Integration test results
+- [ ] Manual testing steps if applicable
+- [ ] Storage variant testing (SQL, KafkaSQL, etc.)]
+```
+
+## Steps
+
+1. **Gather context**:
+   - Read the git diff: `git diff main...HEAD`
+   - Check for associated issues (branch name, commit messages)
+   - Review commits: `git log main..HEAD --oneline`
+
+2. **Generate the PR description** with all four sections
+
+3. **Present to user** for review and approval
+
+4. **Create the PR** when approved:
+   ```bash
+   gh pr create --title "<title>" --body "<description>"
+   ```
+
+## Guidelines
+
+- Be specific — mention actual file names, class names, and method names
+- For bug fixes, clearly explain what was broken
+- For features, explain the motivation and design decisions
+- Use markdown checkboxes in test plan: `- [ ]` for uncompleted, `- [x]` for completed
+- Keep the title under 70 characters, conventional commit style