From 2cfac8c23c0aa5c7bd222dd6650f93a2192c4930 Mon Sep 17 00:00:00 2001 From: alfredorubin96 Date: Mon, 4 May 2026 03:22:13 +0200 Subject: [PATCH] chore(config): audit and improve Claude Code skills, agents, hooks, and CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md: - Fix SonarQube → SonarCloud reference - Remove stale TESTING_APPROACH.md reference - Add release branch exception to Git & PRs section - Add "Automated Guardrails (Hooks)" section documenting all hook protections - Update Playwright CLI reference to include all 4 browser agents Agents: - project-architect: fix Next.js 15 → 16, /grill → /drill (4 occurrences) - code-reviewer: add CodeRabbit/SonarCloud checking steps, fix vitest → npm test Skills: - code: add mandatory /drill step before implementation - next (autopilot): add /drill step, replace broken npm run lint:fix with correct per-package commands, add E2E test step - test: fix HEAD~1 → origin/dev..HEAD for multi-commit branch detection - pr: add branch conventions, release branch exception, E2E step, fix SonarQube ref - issue: add commit scopes - Remove github-workflow skill (content consolidated into pr + issue skills) Hooks: - New check-migration-guard.sh: blocks edits to existing migration files (forward-only) - session-context.sh: add Docker health check at session start - settings.json: register migration guard hook Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/agents/code-reviewer.md | 8 ++++-- .claude/agents/project-architect.md | 8 +++--- .claude/hooks/check-migration-guard.sh | 26 +++++++++++++++++++ .claude/hooks/session-context.sh | 11 +++++++++ .claude/settings.json | 6 +++++ .claude/skills/code/SKILL.md | 7 +++--- .claude/skills/github-workflow/SKILL.md | 13 ---------- .claude/skills/issue/SKILL.md | 5 ++-- .claude/skills/next/SKILL.md | 23 +++++++++++------ .claude/skills/pr/SKILL.md | 11 +++++++-- .claude/skills/test/SKILL.md | 4 +-- CLAUDE.md | 33 ++++++++++++++++++++++--- 12 files changed, 116 insertions(+), 39 deletions(-) create mode 100755 .claude/hooks/check-migration-guard.sh delete mode 100644 .claude/skills/github-workflow/SKILL.md diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md index d1ea16ea..0a40ebe0 100644 --- a/.claude/agents/code-reviewer.md +++ b/.claude/agents/code-reviewer.md @@ -14,8 +14,12 @@ Senior reviewer for NeoBoard. Check staged/unstaged changes against rules, then 1. Run `git diff` and `git diff --cached` to get all changes. 2. Read each changed file to understand full context. 3. Check against the rules below. -4. After code review, run `cd app && npx vitest run` and `cd component && npx vitest run` to verify tests pass. -5. If any UI files changed (`*.tsx` in pages, components, or settings), recommend running `@feature-reviewer` on the affected feature. +4. After code review, run `cd app && npm test` and `cd component && npm test` to verify tests pass. +5. Check external review feedback: + - CodeRabbit: `gh pr view --comments | grep -A10 'coderabbitai'` + - SonarCloud: `gh pr checks` — verify quality gate passes + - Flag any unaddressed CRITICAL/MAJOR findings +6. If any UI files changed (`*.tsx` in pages, components, or settings), recommend running `@feature-reviewer` on the affected feature. ## Rules (priority order) diff --git a/.claude/agents/project-architect.md b/.claude/agents/project-architect.md index f2e04093..df6e6d71 100644 --- a/.claude/agents/project-architect.md +++ b/.claude/agents/project-architect.md @@ -17,7 +17,7 @@ Read these files for project rules and architecture: ## Tech Stack -Next.js 15 (App Router), React 19, TypeScript, shadcn/ui, Tailwind CSS, ECharts, Neo4j NVL, Leaflet, Zustand, TanStack Query, Auth.js v5, Drizzle ORM. +Next.js 16 (App Router), React 19, TypeScript, shadcn/ui, Tailwind CSS, ECharts, Neo4j NVL, Leaflet, Zustand, TanStack Query, Auth.js v5, Drizzle ORM. ## Three Packages (STRICT boundaries) @@ -30,7 +30,7 @@ Next.js 15 (App Router), React 19, TypeScript, shadcn/ui, Tailwind CSS, ECharts, You may receive: - An issue number to fetch -- A `REQUIREMENTS BRIEF` from a `/grill` session — if provided, this is your primary source of truth for what the user wants. It contains answers to detailed clarifying questions about scope, UX, data model, security, edge cases, and testing. +- A `REQUIREMENTS BRIEF` from a `/drill` session — if provided, this is your primary source of truth for what the user wants. It contains answers to detailed clarifying questions about scope, UX, data model, security, edge cases, and testing. ## Steps @@ -51,7 +51,7 @@ You may receive: # Implementation Plan: ## Requirements Summary -<2-3 sentences summarizing what was agreed during the grilling session — scope, MVP, key decisions> +<2-3 sentences summarizing what was agreed during the drill session — scope, MVP, key decisions> ## Impact Analysis - Packages affected: [app, component, connection] @@ -90,7 +90,7 @@ You may receive: - Unit tests: [what to cover, which files] - Integration tests: [what to cover] - E2E tests: [critical user flows to cover] -- Edge cases from brief: [list specific edge cases identified during grilling] +- Edge cases from brief: [list specific edge cases identified during drill] ## Risks - [Risk] — Mitigation diff --git a/.claude/hooks/check-migration-guard.sh b/.claude/hooks/check-migration-guard.sh new file mode 100755 index 00000000..85754753 --- /dev/null +++ b/.claude/hooks/check-migration-guard.sh @@ -0,0 +1,26 @@ +#!/bin/bash +# Hook: Prevent editing existing migration files (forward-only migrations) +# Rule: "Forward-only. Idempotent." — CLAUDE.md +INPUT=$(cat) +FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty') +[ -z "$FILE_PATH" ] && exit 0 + +# Only check migration files +case "$FILE_PATH" in + *migrations/*.sql|*migrations/*.ts) + # Allow creating NEW migration files (Write tool with no existing file) + TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty') + if [ "$TOOL_NAME" = "Write" ] && [ ! -f "$FILE_PATH" ]; then + exit 0 + fi + # Block editing existing migration files + if [ -f "$FILE_PATH" ]; then + echo "BLOCKED: Cannot edit existing migration file: $(basename "$FILE_PATH")" >&2 + echo "Rule: Migrations are forward-only. Create a new migration instead." >&2 + echo "Use: npm run db:generate" >&2 + exit 2 + fi + ;; +esac + +exit 0 diff --git a/.claude/hooks/session-context.sh b/.claude/hooks/session-context.sh index df056b5d..09782f65 100755 --- a/.claude/hooks/session-context.sh +++ b/.claude/hooks/session-context.sh @@ -8,6 +8,17 @@ cd "$PROJECT_DIR" echo "=== Session Context ===" +# Docker health check +if command -v docker >/dev/null 2>&1; then + if docker info >/dev/null 2>&1; then + echo "Docker: running" + else + echo "WARNING: Docker is installed but not running. Tests requiring Docker (connection/, E2E) will fail." + fi +else + echo "WARNING: Docker not found. Tests requiring Docker (connection/, E2E) will fail." +fi + # Current branch & tracking BRANCH=$(git branch --show-current 2>/dev/null) echo "Branch: $BRANCH" diff --git a/.claude/settings.json b/.claude/settings.json index d9a0b82c..8098d710 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -63,6 +63,12 @@ "timeout": 5, "statusMessage": "Checking credential logging..." }, + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-migration-guard.sh", + "timeout": 5, + "statusMessage": "Checking migration file safety..." + }, { "type": "command", "command": "INPUT=$(cat); FILE_PATH=$(echo \"$INPUT\" | jq -r '.tool_input.file_path // .tool_input.filePath // empty'); NEW_CONTENT=$(echo \"$INPUT\" | jq -r '.tool_input.new_string // .tool_input.content // empty'); [ -z \"$NEW_CONTENT\" ] && exit 0; if echo \"$NEW_CONTENT\" | grep -qE \"import \\* as echarts from ['\\\"]echarts['\\\"]|from ['\\\"]echarts['\\\"]\" && ! echo \"$NEW_CONTENT\" | grep -q 'echarts/core'; then echo 'BLOCKED: Never import * from echarts. Use echarts/core + specific modules.' >&2; exit 2; fi", diff --git a/.claude/skills/code/SKILL.md b/.claude/skills/code/SKILL.md index bb979a69..f436cf6f 100644 --- a/.claude/skills/code/SKILL.md +++ b/.claude/skills/code/SKILL.md @@ -15,9 +15,10 @@ allowed-tools: Read, Write, Edit, MultiEdit, Bash(npm *), Bash(npx *), Bash(git ## Before coding 1. If issue number: `gh issue view ` -2. If existing PR: `gh pr view --comments` — check CodeRabbit & SonarQube feedback -3. Identify package: component/ (UI only), connection/ (DB only), app/ (orchestration) -4. Read relevant docs in `claude_code_docs/` +2. **Run `/drill `** — mandatory requirements gathering before implementation. No exceptions. +3. If existing PR: `gh pr view --comments` — check CodeRabbit & SonarCloud feedback +4. Identify package: component/ (UI only), connection/ (DB only), app/ (orchestration) +5. Read relevant docs in `claude_code_docs/` ## TDD Workflow (mandatory — no exceptions) diff --git a/.claude/skills/github-workflow/SKILL.md b/.claude/skills/github-workflow/SKILL.md deleted file mode 100644 index a978e5f6..00000000 --- a/.claude/skills/github-workflow/SKILL.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -name: github -description: GitHub conventions, labels, branching for NeoBoard. -model: haiku ---- - -# Branch: feat/, fix/, chore/, docs/, refactor/, security/ - -# Commits: type(scope): description - -# Scopes: app, component, connection, auth, encryption, migration, api, widget, chart - -# Labels: type (bug/enhancement/security/...) + package (pkg:app/pkg:component/pkg:connection) + area diff --git a/.claude/skills/issue/SKILL.md b/.claude/skills/issue/SKILL.md index 705cba8f..a065fa13 100644 --- a/.claude/skills/issue/SKILL.md +++ b/.claude/skills/issue/SKILL.md @@ -10,11 +10,12 @@ model: haiku Create a GitHub issue based on $ARGUMENTS. +Title format: `type(scope): description` +Scopes: app, component, connection, auth, encryption, migration, api, widget, chart + Labels — always apply type + package + area: - Type: bug, enhancement, security, documentation, performance, urgent - Package: pkg:app, pkg:component, pkg:connection - Area: area:auth, area:connectors, area:widgets, area:charts, area:query-exec, area:dashboard, area:api - Special: enterprise, breaking-change, good-first-issue - -Title format: `type(scope): description` diff --git a/.claude/skills/next/SKILL.md b/.claude/skills/next/SKILL.md index 276800a6..36ba5410 100644 --- a/.claude/skills/next/SKILL.md +++ b/.claude/skills/next/SKILL.md @@ -35,32 +35,39 @@ git checkout -b / Branch prefix from labels: bug → fix/, enhancement → feat/, security → security/, docs → docs/. -## Step 3 — Read the issue and relevant docs +## Step 3 — Run /drill + +Before implementing, run `/drill ` to gather requirements, edge cases, and acceptance criteria. This is mandatory per CLAUDE.md. + +## Step 4 — Read the issue and relevant docs Read the full issue body. Check `claude_code_docs/` for relevant context. Identify which package(s) are affected: app/, component/, connection/. -## Step 4 — Implement +## Step 5 — Implement Follow all CLAUDE.md rules. Respect package boundaries. If building UI, check existing components first (`find component/src -name '*.tsx'`). -## Step 5 — Test and lint +## Step 6 — Test and lint ```bash -npm run lint:fix +cd app && npx next lint --fix +npm run lint npm run build -npm run test +cd app && npm test +cd component && npm test +cd app && npx playwright test ``` Fix any failures. Do not skip. -## Step 6 — Commit +## Step 7 — Commit Use Conventional Commits: `type(scope): description` Reference the issue: `Closes #` -## Step 7 — Push and create PR +## Step 8 — Push and create PR ```bash git push -u origin HEAD @@ -71,7 +78,7 @@ gh pr create \ --label '' ``` -## Step 8 — Report +## Step 9 — Report Output: diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md index e47b0cdc..5b9ff961 100644 --- a/.claude/skills/pr/SKILL.md +++ b/.claude/skills/pr/SKILL.md @@ -12,13 +12,20 @@ allowed-tools: Bash(gh *), Bash(git *), Bash(npm *) - Commits: !`git log origin/dev..HEAD --oneline 2>/dev/null || echo 'No upstream'` - Changed: !`git diff origin/dev --name-only 2>/dev/null || git diff --name-only` +## Conventions + +- Branch prefixes: `feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `security/` +- Commits: `type(scope): description` +- Scopes: app, component, connection, auth, encryption, migration, api, widget, chart + ## Pre-flight (fix failures before creating PR) -1. `git fetch origin && git rebase origin/dev` (PRs always target `dev`) +1. `git fetch origin && git rebase origin/dev` (PRs always target `dev`; exception: target `release/X.Y` if active) 2. `npm run lint` 3. `npm run build` 4. Run tests for affected packages (`cd app && npm test`, `cd component && npm test`) -5. If updating existing PR: `gh pr view --comments` — address CodeRabbit/SonarQube feedback +5. Run E2E if UI changed: `cd app && npx playwright test` +6. If updating existing PR: `gh pr view --comments` — address CodeRabbit/SonarCloud feedback ## Labels (required: type + package) diff --git a/.claude/skills/test/SKILL.md b/.claude/skills/test/SKILL.md index 308cc005..e9fefd1d 100644 --- a/.claude/skills/test/SKILL.md +++ b/.claude/skills/test/SKILL.md @@ -11,7 +11,7 @@ allowed-tools: Bash(npm *), Bash(npx *), Bash(git *), Bash(cd *) ## State - Branch: !`git branch --show-current` -- Changed files: !`git diff --name-only HEAD~1 2>/dev/null || git diff --name-only` +- Changed files: !`git diff --name-only origin/dev..HEAD 2>/dev/null || git diff --name-only` ## Instructions @@ -21,7 +21,7 @@ Detect which packages have changes and run the appropriate test suites. ```bash # Check which packages have changes -CHANGED=$(git diff --name-only HEAD~1 2>/dev/null || git diff --name-only) +CHANGED=$(git diff --name-only origin/dev..HEAD 2>/dev/null || git diff --name-only) RUN_APP=false RUN_COMPONENT=false RUN_CONNECTION=false diff --git a/CLAUDE.md b/CLAUDE.md index 025de86d..ca8e9f57 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,7 +47,6 @@ Rules: - Run the relevant test suite before and after every change to confirm Red → Green. - Every new behavior, bug fix, and edge case gets a test. - Tests live in `__tests__/` next to the file under test, same package. -- See `claude_code_docs/TESTING_APPROACH.md` for suite structure, commands, and patterns. ## Testing Boundaries (app/ package) @@ -94,6 +93,7 @@ Playwright E2E with **server-side coverage collection** (`collectServer: true` i - Conventional Commits: `type(scope): description`. - Branch from `dev`: `feat/issue--`, `fix/issue--`, `chore/`, etc. +- **Exception**: when a `release/X.Y` branch is active, branch from and target it instead of `dev`. - PRs target `dev` (integration) before merging to `main`. - Do not push if tests are failing. - PRs need labels: type + package + area. See `/github` skill. @@ -103,7 +103,7 @@ Playwright E2E with **server-side coverage collection** (`collectServer: true` i - Read `gh pr view --comments` when resuming work on an existing PR. - Address all CodeRabbit suggestions or dismiss with justification. -- SonarQube quality gate must pass (coverage, duplications, code smells). +- SonarCloud quality gate must pass (coverage, duplications, code smells). ## Query Safety — DO NOT VIOLATE @@ -146,6 +146,33 @@ Includes: SSO, Custom Roles, Connector Labels, Bulk Import, Connector CRUD API, Forward-only. Idempotent. Advisory lock prevents concurrent runs. Test version-skip paths. `--skip-migrations` flag exists for emergency debugging. +## Automated Guardrails (Hooks) + +The `.claude/settings.json` hooks enforce critical rules automatically: + +**PreToolUse (Edit/Write):** +- Package boundary enforcement — blocks cross-package imports +- Query interpolation guard — blocks `${...}` near SQL/Cypher keywords +- Credential logging guard — blocks `console.log` of sensitive variables +- Migration file guard — blocks edits to existing migration files (forward-only) +- ECharts import guard — blocks `import * from 'echarts'` +- SSR guard — blocks chart components without `ssr: false` +- Main branch guard — blocks edits on `main` + +**PreToolUse (Bash):** +- Dependency install guard — blocks `npm install/uninstall` without approval +- E2E enforcement — blocks `git commit` if UI files edited but Playwright not run + +**PostToolUse:** +- Auto-format + lint on every TypeScript file edit +- E2E marker tracking (marks UI files as needing E2E, clears after playwright runs) +- Coverage threshold warning after test runs + +**Session/Lifecycle:** +- SessionStart: branch status, PR info, Docker health check +- Stop: completion checklist (tests run? lint run? screenshots taken?) +- PreCompact: re-injects critical rules after context compaction + ## Design Review Before touching any UI code, read `.claude/skills/design-review/skill.md` — tokens, spacing, typography, color, chart patterns. @@ -174,4 +201,4 @@ Agents work together in a pipeline. Each stage gates the next: ### Playwright CLI (for browser agents) -`feature-reviewer` and `ux-crawler` use `npx @playwright/cli` to interact with the running app at `http://localhost:3000`. Ensure Docker is running before invoking them. +`feature-reviewer`, `ux-crawler`, `user-sim-admin`, and `user-sim-creator` use `npx @playwright/cli` to interact with the running app at `http://localhost:3000`. Ensure Docker is running before invoking them.