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

Medium Risk
Medium risk because it changes .claude/settings.json to add a PreToolUse hook and a tightened allow/deny list, which can affect contributor tooling behavior, but it does not touch runtime application code.

Overview
Adds a standardized Claude Code setup: new /preflight, /commit, /dco, /review-pr, and /adr skills plus a code-standards-enforcer agent to audit diffs against project rules/checklists and “patterns in transition”.

Wires in a new .claude/hooks/guard-protected-files.sh PreToolUse hook and expands .claude/settings.json permissions to warn on edits to protected infra files (DAL/common libs, migrations, CI/config, lockfiles, etc.).

Introduces an ADR workflow under docs/adr/ (README + template) and a scoped rule (.claude/rules/adr-format.md) to enforce ADR structure, alongside new repo-wide guidance rules for commit/PR conventions and skill suggestion routing.

^{Reviewed by Cursor Bugbot for commit 8a8c290. 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)`

[ulemons]

This function warns about critical files being touched but does not prevent the edit from proceeding. Should we consider exiting with code 1 here so that these files can only be modified intentionally, with an explicit user override?

[joanagmaia]

I didn't want this to become a blocker (at least for now). I don't want this to be another thing that you have to accept. I would initially simply flag it out, and we can see if it makes sense to expand it later on

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ 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 8a8c290. Configure here.}

[cursor]

Review skill invoked in Phase 6 does not exist

Medium Severity

Phase 6 Step 3 instructs Claude to "use the Skill tool to invoke review" after the user approves the draft, but no skill named review exists in the project. The defined skills are adr, commit, dco, preflight, review-pr, and scaffold-snowflake-connector. This means the final step of the review workflow — actually posting approved comments to the PR — will fail or produce unexpected behavior because the referenced /review skill cannot be resolved.

 

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

[cursor]

Missing wildcard on git status permission unlike all others

Low Severity

Bash(git status) is the only entry in the 23-item allow list without a trailing * wildcard. Every other entry uses a glob (e.g., Bash(git log*), Bash(git diff*)). This means only the bare git status command is auto-allowed — common variants like git status --porcelain or git status --short would unexpectedly trigger a permission prompt. The code-standards-enforcer agent instructs to "Use git status to identify changed files," which programmatically benefits from machine-readable flags that this permission now blocks.

 

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