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

[joanagmaia]

Adds a set of Claude Code skills, rules, and a guard hook so contributors get consistent preflight, commit, review, and ADR workflows out of the box. Also introduces Architecture Decision Records (ADRs) with enforcement baked into the Claude config. No app code touched — everything lives under .claude/ and docs/adr/.

What's new

.claude/
├── agents/
│   └── code-standards-enforcer.md  # Red subagent that audits code against patterns-in-transition
├── hooks/
│   └── guard-protected-files.sh    # Warns before edits to protected infra files (DAL, migrations, CI, lockfiles, etc.)
├── rules/
│   ├── adr-format.md               # Scoped rule (docs/adr/**) — enforces Nygard template on every write
│   ├── commit-workflow.md          # Commit message, branch naming, PR size, sign-off + GPG conventions
│   └── skill-guidance.md           # Tells Claude which skill to suggest based on user intent
├── settings.json                   # Wires the guard hook into PreToolUse + permissions allow/deny list
└── skills/
    ├── adr/SKILL.md                # /adr — record or query architecture decisions interactively
    ├── commit/SKILL.md             # Generates a commit message and runs git commit -s -S
    ├── dco/SKILL.md                # Recovers commits missing a DCO sign-off (amend / rebase / cherry-pick)
    ├── preflight/SKILL.md          # Pre-PR check: lint, format-check, tsc — workspace-aware
    └── review-pr/
        ├── SKILL.md                # Reviews a PR against CDP architecture standards (6-phase, human gate)
        └── references/
            ├── backend-checklist.md    # Express + pg-promise review criteria
            ├── frontend-checklist.md   # Vue 3 + TanStack Query review criteria
            ├── services-checklist.md   # Temporal worker + shared libs review criteria
            └── sql-checklist.md        # Flyway migration + DAL query review criteria

docs/adr/
├── README.md                       # Index table of all ADRs
└── template.md                     # Blank Nygard template (copied by the /adr skill)

AGENTS.md                           # Symlink → CLAUDE.md (Cursor / agent-IDE compatibility)

Key design decisions vs. the crowd.dev stack

Workspace-aware preflight — /preflight detects changed paths and runs only the relevant workspace's scripts (backend/ → pnpm lint && pnpm format-check && pnpm tsc-check; frontend/ → npm run lint; services/apps/* and services/libs/* → pnpm lint && pnpm format-check && pnpm tsc-check). Matches how CI is split across workspaces.

patterns-in-transition enforcement — The code-standards-enforcer agent and four review checklists codify the CLAUDE.md rules: no new Sequelize (use queryExecutor), no new class-based services (plain functions), no new multi-tenant logic (use DEFAULT_TENANT_ID), new public endpoints require Zod + validateOrThrow. These are CRITICAL findings in /review-pr.

Temporal / Kafka guardrails — services-checklist.md adds determinism rules for Temporal workflows and I/O-in-activity enforcement for the 25+ workers in services/apps/.

ADR directory — The codebase has several documented "patterns in transition". Each is a textbook ADR. docs/adr/ gives them a permanent, queryable home.

How to try it

Run any of the new skills in Claude Code on this branch:

• /preflight — validate your branch before opening a PR
• /commit — generate a conventional commit message and commit with sign-off
• /dco — fix missing DCO sign-off on one or more commits
• /review-pr <N> — review a PR against CDP standards (presents a draft, never auto-posts)
• /adr — record or query an architecture decision in docs/adr/

🤖 Generated with Claude Code

---

Note

Low Risk
Low risk to production since this PR only adds Claude Code configuration, workflows, and docs; the main risk is developer-tooling friction or unintended warnings/permission restrictions during local AI-assisted edits.

Overview
Adds a comprehensive Claude Code configuration suite under .claude/, including guided skills (/preflight, /commit, /dco, /review-pr, /adr), rule documents, and review checklists to standardize commit/PR workflows and enforce “patterns-in-transition” during PR review.

Wires in a new PreToolUse guard hook (.claude/hooks/guard-protected-files.sh) via .claude/settings.json to warn on edits to protected, high-blast-radius files (migrations, shared libs, CI/config, lockfiles), and sets an allow/deny list for permitted shell commands.

Introduces ADR scaffolding in docs/adr/ (README + template) plus an .claude/rules/adr-format.md rule to enforce ADR structure, and adds AGENTS.md pointing to CLAUDE.md for agent-IDE compatibility.

^{Reviewed by Cursor Bugbot for commit 2282894. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

⚠️ Jira Issue Key Missing

Your PR title doesn't contain a Jira issue key. Consider adding it for better traceability.

Example:

• feat: add user authentication (CM-123)
• feat: add user authentication (IN-123)

Projects:

• CM: Community Data Platform
• IN: Insights

Please add a Jira issue key to your PR title.

[Copilot]

Pull request overview

This PR introduces a standardized Claude Code contributor workflow for the repo by adding guided skills (preflight, commit, DCO recovery, PR review, ADR authoring), repository rules, a protected-files guard hook, and an ADR directory/template under docs/adr/.

Changes:

• Add Claude Code skills for preflight checks, commit/DCO workflows, PR review, and ADR creation/querying.
• Add enforceable Claude rules (commit workflow, ADR format enforcement, skill routing guidance) plus a protected-files guard hook.
• Introduce docs/adr/ with a README index and an ADR template.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/adr/template.md	Adds a Nygard-style ADR template for consistent decision recording.
docs/adr/README.md	Adds ADR index + rationale for ADR usage in this repo.
.claude/skills/review-pr/SKILL.md	Defines a multi-phase PR review workflow, including background enforcement and metadata checks.
.claude/skills/review-pr/references/backend-checklist.md	Adds backend review checklist aligned to “patterns in transition”.
.claude/skills/review-pr/references/frontend-checklist.md	Adds Vue/TanStack Query frontend review checklist.
.claude/skills/review-pr/references/services-checklist.md	Adds Temporal/Kafka/Redis determinism and service review checklist.
.claude/skills/review-pr/references/sql-checklist.md	Adds migration + DAL SQL safety/performance checklist.
.claude/skills/preflight/SKILL.md	Adds workspace-aware preflight guidance for lint/format/typecheck/protected files.
.claude/skills/dco/SKILL.md	Adds guidance for repairing missing DCO sign-offs across common scenarios.
.claude/skills/commit/SKILL.md	Adds a guided conventional-commit + sign-off signing flow.
.claude/skills/adr/SKILL.md	Adds ADR authoring/query workflow tied to docs/adr/.
.claude/settings.json	Wires protected-files guard hook into PreToolUse and introduces a Bash allow/deny permission list.
.claude/rules/skill-guidance.md	Adds a routing table mapping user intent to the right skill.
.claude/rules/commit-workflow.md	Adds documented conventions for commits/branches/PR titles/signing/JIRA linkage.
.claude/rules/adr-format.md	Adds scoped enforcement rules for ADR structure + naming/index updates.
.claude/hooks/guard-protected-files.sh	Adds a warning hook for edits to high-blast-radius infrastructure/config files.
.claude/agents/code-standards-enforcer.md	Adds a review sub-agent definition for enforcing project standards during PR review.

Comments suppressed due to low confidence (1)

.claude/settings.json:42

• The deny pattern Bash(git push --force *) won’t match git push --force when it’s invoked without additional arguments (no trailing space), so a destructive force-push can slip through the denylist. Consider denying Bash(git push --force*) (and potentially --force-with-lease if you don’t want Claude to push at all).

    "deny": [
      "Bash(git reset --hard*)",
      "Bash(git push --force *)",
      "Bash(rm -rf*)"

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

.claude/rules/commit-workflow.md:56

• This rule says PR title Jira key is “validated by CI”, but the referenced workflow (pr-title-jira-key-lint.yml) creates a neutral check when the key is missing. That wording can be misleading if the check isn’t actually blocking merges. Consider rephrasing to match the workflow behavior (warns/comments, and may be required depending on branch protection) rather than implying a hard validation/failure.

## 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)`

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2282894. Configure here.}