feat: add Claude Code config with hooks, skills, and rules

Signed-off-by: Joana Maia <jmaia@contractor.linuxfoundation.org>

Author: joanagmaia

.claude/agents/code-standards-enforcer.md

@@ -0,0 +1,145 @@
+---
+name: code-standards-enforcer
+description: "Audits recently written or modified code against CLAUDE.md rules, patterns-in-transition, and checklist files. Covers CDP-specific patterns: pg-promise over Sequelize, functional services over classes, single-tenant via DEFAULT_TENANT_ID, Auth0 auth, Zod + validateOrThrow for public endpoints, query performance, and Temporal workflow rules. Invoked in background by review-pr."
+model: inherit
+color: red
+memory: none
+---
+
+# Code Standards Enforcer
+
+You are an elite code standards enforcement specialist. Your singular mission is to audit recently written or modified code against the project's CLAUDE.md guidelines, rule files, and checklist files, catching violations before they enter the codebase.
+
+## Your Primary Directive
+
+Read and internalize every rule, convention, pattern, and guideline described in CLAUDE.md. These are law. When CLAUDE.md references other documents (rule files in `.claude/rules/`, checklist files under `.claude/skills/review-pr/references/`), read and enforce those too.
+
+## Enforcement Process
+
+### Step 1: Load All Reference Documents
+
+- Read the project's `CLAUDE.md` thoroughly
+- Read the user's global CLAUDE.md at `~/.claude/CLAUDE.md` if it exists
+- Glob `.claude/rules/*.md` and read every rule file
+- Read all checklists under `.claude/skills/review-pr/references/`
+- Build a mental checklist of every enforceable rule
+
+### Step 2: Identify Recently Changed Code
+
+- Use `git status` or `git diff` to identify changed files
+- Categorize changes: backend (`backend/`), frontend (`frontend/`), services (`services/apps/*`, `services/libs/*`), migrations, SQL
+
+### Step 3: Systematic Audit
+
+For each changed file, check against ALL applicable rules. The patterns-in-transition from CLAUDE.md are the highest priority:
+
+#### Patterns in Transition (enforce on ALL new code)
+
+- [ ] **No new Sequelize usage** — all new DB code uses `queryExecutor` from `@crowd/data-access-layer`. Legacy Sequelize in `backend/src/database/repositories/` and `backend/src/services/` is exempt.
+- [ ] **No new class-based services or repositories** — plain functions only
+- [ ] **No new multi-tenant logic** — use `DEFAULT_TENANT_ID` from `@crowd/common`
+- [ ] **New public endpoints use Zod + `validateOrThrow`** from `@crowd/common`
+- [ ] **Auth0 patterns** — no new legacy JWT patterns
+- [ ] **No `any` types** in new code
+
+#### Backend Rules
+
+- [ ] New DAL functions checked against existing equivalents (blast-radius risk)
+- [ ] Parameterized queries only — no string interpolation with user input
+- [ ] `$N` placeholder count matches bind values array length
+- [ ] No secrets hardcoded — env vars only
+- [ ] Query performance: indexes considered for WHERE clauses on large tables
+
+#### Services Rules (Temporal/Kafka/Redis workers)
+
+- [ ] Temporal workflows are deterministic — no I/O, no `Math.random()`, no `Date.now()` inside workflow code
+- [ ] Kafka/Redis calls are in Activities only, not Workflows
+- [ ] Activities are idempotent where possible
+- [ ] Logger from `@crowd/logging` — no `console.log`
+
+#### Frontend Rules
+
+- [ ] `<script setup>` Composition API — no Options API
+- [ ] TanStack Vue Query for server state — no raw `axios` in `onMounted`
+- [ ] Pinia for shared client state
+- [ ] `ref()` / `computed()` for reactive state
+
+#### Migration Rules
+
+- [ ] Migrations are append-only — never modify an applied migration
+- [ ] Filename format: `V{epoch}__{description}.sql`
+- [ ] Production-safe: no dangerous `DROP TABLE`, no adding NOT NULL without default/backfill
+
+#### Protected Files Check
+
+Flag if any of these protected infrastructure files were modified — they require code owner approval:
+
+- `services/libs/data-access-layer/**`
+- `services/libs/common/**`
+- `backend/src/database/migrations/**`
+- `scripts/cli`, `scripts/scaffold.yaml`
+- `.husky/*`, `commitlint.config.js`
+- `.github/workflows/**`, `.github/actions/**`
+- `tsconfig*.json`, `.eslintrc*`, `.prettierrc*`
+- `pnpm-lock.yaml`, `package.json`, `*/package.json`
+- `CLAUDE.md`, `.claude/settings.json`
+
+### Step 4: Report Findings
+
+For each violation found, report:
+
+1. **File and line number** (or approximate location)
+2. **Rule violated** — cite the specific CLAUDE.md section, rule file, or checklist
+3. **What's wrong** — explain the violation clearly
+4. **How to fix** — provide the corrected code snippet
+5. **Severity** — CRITICAL / SHOULD FIX / NIT
+
+### Step 5: Summary
+
+After auditing all files, provide:
+
+- Total violations found grouped by severity
+- A PASS / FAIL verdict
+- Top 3 most important fixes to prioritize
+- Confirmation of which rules and documents were checked
+
+## Behavior Rules
+
+1. **Be thorough** — check every applicable rule
+2. **Be specific** — always cite the exact rule source
+3. **Be actionable** — always provide corrected code, not just descriptions
+4. **Be fair** — acknowledge when code correctly follows guidelines
+5. **Do not flag legacy code in already-legacy files** — only flag new violations in new or modified files
+6. **If you cannot quote the rule from a loaded document, drop the finding** — hallucinated rules are worse than missed ones
+
+## Output Format
+
+```text
+## Code Standards Audit Report
+
+### Documents Referenced
+- [List all CLAUDE.md files, rule files, and checklists consulted]
+
+### Files Audited
+- [List of files checked]
+
+### Protected Files
+- [List any protected files that were modified, or "None modified"]
+
+### Violations Found
+
+#### CRITICAL
+[Violations that break core patterns or introduce security/data issues]
+
+#### SHOULD FIX
+[Deviations from documented conventions]
+
+#### NIT
+[Minor style issues, protected-file awareness]
+
+### Correctly Followed
+[Notable rules that were correctly followed]
+
+### Verdict: PASS / FAIL
+[Summary and priority fixes]
+```

.claude/hooks/guard-protected-files.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Copyright The Linux Foundation and each contributor to CDP.
+# SPDX-License-Identifier: MIT
+#
+# Guard hook: warns when editing protected infrastructure files.
+# Used by Claude Code PreToolUse hook on Edit and Write operations.
+# Exit code 0 = allow (with warning message printed to stderr).
+
+set -euo pipefail
+
+# Read tool input from stdin (JSON with file_path field)
+INPUT=$(cat)
+
+# Extract file_path from the JSON input
+FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//' || true)
+
+# If no file_path found, allow the operation
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Normalize: strip leading ./ if present
+FILE_PATH="${FILE_PATH#./}"
+
+# Also handle absolute paths by stripping the repo root
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+if [ -n "$REPO_ROOT" ] && [[ "$FILE_PATH" == "$REPO_ROOT"/* ]]; then
+  FILE_PATH="${FILE_PATH#$REPO_ROOT/}"
+fi
+
+# Helper: warn about a protected file (allows the edit to proceed)
+warn() {
+  local reason="$1"
+  echo "" >&2
+  echo "⚠ WARNING: This file is part of the project's core infrastructure." >&2
+  echo "File: $FILE_PATH" >&2
+  echo "Reason: $reason" >&2
+  echo "Ensure this change is intentional and reviewed by a code owner." >&2
+  echo "" >&2
+  exit 0
+}
+
+# ── Data Access Layer ──────────────────────────────────────────────
+if [[ "$FILE_PATH" == services/libs/data-access-layer/* ]]; then
+  warn "Shared DAL — high blast radius. Check for existing functions before adding new ones (CLAUDE.md: 'duplicates are already a problem')."
+fi
+
+# ── Common / Shared Utilities ──────────────────────────────────────
+if [[ "$FILE_PATH" == services/libs/common/* ]]; then
+  warn "Shared utility library — changes affect all services and the backend."
+fi
+
+# ── Database Migrations ────────────────────────────────────────────
+if [[ "$FILE_PATH" == backend/src/database/migrations/* ]]; then
+  warn "Flyway migration — append-only. Never modify an existing migration that has been applied."
+fi
+
+# ── Dev CLI & Scaffold ─────────────────────────────────────────────
+case "$FILE_PATH" in
+  scripts/cli)
+    warn "Dev CLI entrypoint — changes affect all contributors' local setup." ;;
+  scripts/scaffold.yaml|scripts/scaffold.insights.yaml)
+    warn "Docker scaffold config — changes affect how local services are started." ;;
+esac
+
+# ── Git Hooks & Commit Standards ──────────────────────────────────
+if [[ "$FILE_PATH" == .husky/* ]]; then
+  warn "Git hooks — changes affect pre-commit validation for all contributors."
+fi
+
+case "$FILE_PATH" in
+  commitlint.config.js|commitlint.config.*)
+    warn "Commitlint config — changes affect commit message validation for all contributors." ;;
+esac
+
+# ── CI / GitHub Actions ────────────────────────────────────────────
+if [[ "$FILE_PATH" == .github/workflows/* ]] || [[ "$FILE_PATH" == .github/actions/* ]]; then
+  warn "CI/CD pipeline — changes affect automated checks run on every PR."
+fi
+
+# ── Lint / Format / TypeScript Config ─────────────────────────────
+case "$FILE_PATH" in
+  tsconfig*.json|*/tsconfig*.json)
+    warn "TypeScript configuration — changes affect compilation across the monorepo." ;;
+  .eslintrc*|*/eslintrc*|eslint.config*|*/eslint.config*)
+    warn "ESLint configuration — changes affect code quality rules for the project." ;;
+  .prettierrc*|*/.prettierrc*)
+    warn "Prettier configuration — changes affect code formatting standards." ;;
+esac
+
+# ── Package Files ──────────────────────────────────────────────────
+if [[ "$FILE_PATH" == pnpm-lock.yaml ]]; then
+  warn "Lock file — changes affect resolved dependency versions for all contributors."
+fi
+if [[ "$FILE_PATH" == package.json ]] || [[ "$FILE_PATH" == */package.json ]]; then
+  warn "Package manifest — changes affect dependencies and scripts for this workspace."
+fi
+
+# ── Claude Config ─────────────────────────────────────────────────
+case "$FILE_PATH" in
+  CLAUDE.md)
+    warn "Project instructions — changes affect AI assistant behavior for all users." ;;
+  .claude/settings.json)
+    warn "Claude Code settings — changes affect hooks, permissions, and plugins for all users." ;;
+esac
+if [[ "$FILE_PATH" == .claude/hooks/* ]]; then
+  warn "Claude Code hook — changes affect automated pre-tool validations."
+fi
+
+# If none of the protected patterns matched, allow the operation
+exit 0

.claude/rules/adr-format.md

@@ -0,0 +1,52 @@
+---
+description: Enforce Nygard ADR template structure on files written under docs/adr/
+paths:
+  - 'docs/adr/**/*.md'
+---
+
+# ADR Format Enforcement
+
+When writing or editing any `.md` file under `docs/adr/`, enforce these rules:
+
+## Exempt files
+
+`README.md` and `template.md` are index/template files — they are **not** ADRs
+and are exempt from the section requirements below.
+
+## Mandatory sections for ADR files
+
+Every file matching `docs/adr/[0-9]*.md` **must** contain all of the following,
+in this order:
+
+1. `# ADR-NNNN: [Title]` — H1 heading with 4-digit sequential ID
+2. `**Date**:` — ISO date (YYYY-MM-DD)
+3. `**Status**:` — one of: `proposed`, `accepted`, `deprecated`, `superseded by ADR-NNNN`
+4. `**Deciders**:` — who was involved in the decision
+5. `## Context` — 2–5 sentences on the situation and forces
+6. `## Decision` — 1–3 sentences stating the change
+7. `## Alternatives Considered` — at least one alternative with Pros, Cons, Why not
+8. `## Consequences` — with sub-sections `### Positive`, `### Negative`, `### Risks`
+
+If any mandatory section is missing, **stop and ask the user** to provide the
+missing information before writing the file. Do not write a partial ADR.
+
+## Numbering
+
+- IDs are zero-padded to 4 digits: `0001`, `0002`, `0003`, …
+- Assign the next sequential number by scanning existing files with `Glob docs/adr/[0-9]*.md`.
+- Never reuse a number, even if a previous ADR is deprecated.
+
+## File naming
+
+`docs/adr/NNNN-kebab-case-title.md` — all lowercase, words separated by hyphens.
+
+## Index maintenance
+
+After writing or changing the status of an ADR, update the index table in
+`docs/adr/README.md`:
+
+```markdown
+| [ADR-NNNN](./NNNN-kebab-title.md) | Title | accepted | YYYY-MM-DD |
+```
+
+Remove the `_none yet_` placeholder row once the first real ADR is added.

.claude/rules/commit-workflow.md

@@ -0,0 +1,69 @@
+---
+description: Commit conventions, branch naming, PR format, PR size guidelines, sign-off + GPG signing, and JIRA tracking workflow
+paths:
+  - '*'
+---
+
+# Commit & PR Workflow
+
+## Commit Conventions
+
+- Follow the [Conventional Commits](https://www.conventionalcommits.org/) format: `type: description`
+- A scope is **optional** — most commits in this repo do not use one
+- Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
+- Use present tense, imperative mood: "add feature" not "added feature"
+- Include the JIRA ticket **inline at the end** of the description, in parentheses
+- Examples:
+  - `feat: add github discussions integration (CM-1164)`
+  - `fix: improve member merge suggestions (CM-1137)`
+  - `chore: update stale dependency versions`
+
+## Commit Signing
+
+All commits must be both DCO-signed and GPG-signed:
+
+- **DCO sign-off (`--signoff`)** — required by LF governance; validated by the Probot DCO check in CI. The `Signed-off-by: Name <email>` trailer is appended automatically when you pass `--signoff` (or `-s`).
+- **GPG signature (`-S`)** — required by repo policy. Configure a signing key once:
+
+  ```bash
+  git config --global user.signingkey <KEY_ID>
+  git config --global commit.gpgsign true
+  ```
+
+Standard commit command:
+
+```bash
+git commit --signoff -S -m "type: description (CM-XXX)"
+```
+
+If signing fails, fix the underlying issue — do not push unsigned commits. To verify signature status on a branch's commits:
+
+```bash
+git log --format='%G? %h %s' origin/main..HEAD
+```
+
+Acceptable `%G?` codes: `G` (good signature) or `U` (good signature, key not in local trust db). Codes `N`, `B`, or `E` need investigation.
+
+## Branch Naming
+
+- Format: `type/CM-<number>-short-description` (e.g. `feat/CM-1164-github-discussions`)
+- The JIRA key in the branch name lets `/commit` include it automatically in the message
+
+## PR Titles
+
+- PR titles must contain a JIRA key — validated by CI (`.github/workflows/pr-title-jira-key-lint.yml`)
+- Format: `type: description (CM-XXX)` — Conventional Commits format with the JIRA key in parens at the end
+- Example: `feat: add github discussions source (CM-1164)`
+
+## PR Size & Focus
+
+- **Target under 1000 lines of diff** — one feature, one bug fix, or one refactor per PR
+- **Don't bundle unrelated changes** — keeps reviews focused and rollbacks clean
+
+## JIRA Tracking
+
+Before starting any work:
+
+1. Check if there is a JIRA ticket in the `CM` project
+2. Create one if untracked work
+3. Include `CM-XXX` in commit messages and PR title