From 3a5c3f2554f87f7b4343692c35bb00569a52df65 Mon Sep 17 00:00:00 2001 From: stuckvgn Date: Tue, 17 Mar 2026 22:46:50 +0530 Subject: [PATCH] fix: resolve Claude Code issues #1, #2, #3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename code-review → advocacy-code-review and testing-strategy → advocacy-testing-strategy to prevent shadowing global skills (#1) - Add actual .claude/settings.json hook format with event names, matchers, and timeouts to hooks-template.md (#2) - Extract desloppify section to .claude/rules/desloppify.md, bringing CLAUDE.md from 70 lines to 50 (under 60 target) (#3) Closes #1, closes #2, closes #3 --- README.md | 2 +- claude-code/.claude/rules/desloppify.md | 23 +++++++++ claude-code/.claude/skills/README.md | 4 +- .../README.md | 0 .../SKILL.md | 2 +- .../README.md | 0 .../SKILL.md | 2 +- claude-code/CLAUDE.md | 24 +-------- claude-code/hooks-template.md | 49 ++++++++++++++++++- 9 files changed, 78 insertions(+), 28 deletions(-) create mode 100644 claude-code/.claude/rules/desloppify.md rename claude-code/.claude/skills/{code-review => advocacy-code-review}/README.md (100%) rename claude-code/.claude/skills/{code-review => advocacy-code-review}/SKILL.md (99%) rename claude-code/.claude/skills/{testing-strategy => advocacy-testing-strategy}/README.md (100%) rename claude-code/.claude/skills/{testing-strategy => advocacy-testing-strategy}/SKILL.md (99%) diff --git a/README.md b/README.md index 418fc15..d967882 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ For Claude Code specifically, see `hooks-template.md` for setting up determinist ## The 12 Tools -**Claude Code** -- `CLAUDE.md` at project root (under 60 lines), scoped rules in `.claude/rules/` with optional `paths:` frontmatter for file-targeted activation, process skills in `.claude/skills/` with YAML frontmatter. Supports hooks for deterministic enforcement of formatting, linting, and security scanning. +**Claude Code** -- `CLAUDE.md` at project root (under 60 lines), scoped rules in `.claude/rules/` with optional `paths:` frontmatter for file-targeted activation, process skills in `.claude/skills/` with YAML frontmatter (prefixed `advocacy-` to avoid shadowing global skills). Supports hooks for deterministic enforcement of formatting, linting, and security scanning. **Cursor** -- `.cursorrules` at project root (always loaded), scoped rules in `.cursor/rules/*.mdc` using MDC format with four activation modes: Always Apply, Auto Attached (glob-triggered), Agent Requested (description-triggered), and Manual (user invokes with @). diff --git a/claude-code/.claude/rules/desloppify.md b/claude-code/.claude/rules/desloppify.md new file mode 100644 index 0000000..891e9e1 --- /dev/null +++ b/claude-code/.claude/rules/desloppify.md @@ -0,0 +1,23 @@ +# Code Quality — desloppify + +Run desloppify to systematically identify and fix code quality issues. Install and configure before scanning (requires Python 3.11+): + +```bash +pip install --upgrade "desloppify[full]" +desloppify update-skill claude +``` + +Add `.desloppify/` to `.gitignore` — it contains local state that should not be committed. Before scanning, exclude directories that should not be analyzed (vendor, build output, generated code, worktrees) with `desloppify exclude `. Share questionable candidates with the project owner before excluding. + +```bash +desloppify scan --path . +desloppify next +``` + +`--path` is the directory to scan (use `.` for the whole project, or a subdirectory like `src/`). Your goal is to get the strict score as high as possible. The scoring resists gaming — the only way to improve it is to actually make the code better. + +**The loop:** run `next`. It is the execution queue from the living plan, not the whole backlog. It tells you what to fix now, which file, and the resolve command to run when done. Fix it, resolve it, run `next` again. This is your main job. Use `desloppify backlog` only when you need to inspect broader open work not currently driving execution. + +Do not be lazy. Large refactors and small detailed fixes — do both with equal energy. No task is too big or too small. Fix things properly, not minimally. + +Use `plan` / `plan queue` to reorder priorities or cluster related issues. Rescan periodically. The scan output includes agent instructions — follow them, do not substitute your own analysis. diff --git a/claude-code/.claude/skills/README.md b/claude-code/.claude/skills/README.md index 78eaafc..eef0382 100644 --- a/claude-code/.claude/skills/README.md +++ b/claude-code/.claude/skills/README.md @@ -11,8 +11,8 @@ Skills are invoked on demand -- they are not loaded automatically into every con | Directory | Skill Name | Purpose | |-----------|-----------|---------| | `git-workflow/` | git-workflow | Atomic commits per subtask, ephemeral branches, PR curation into reviewable chunks, AI-Assisted tagging, quality signal tracking | -| `testing-strategy/` | testing-strategy | Spec-first test generation, assertion quality review against three questions, mutation testing, five generation patterns, five anti-patterns to reject | +| `advocacy-testing-strategy/` | advocacy-testing-strategy | Spec-first test generation, assertion quality review against three questions, mutation testing, five generation patterns, five anti-patterns to reject | | `requirements-interview/` | requirements-interview | Structured stakeholder interview in six phases: purpose/users, threat modeling, coalition/data boundaries, user safety, technical constraints, synthesis | | `plan-first-development/` | plan-first-development | Read-plan-code-verify workflow with spec writing, subtask decomposition, comprehension checks, and context management | -| `code-review/` | code-review | Five-layer review pipeline: automated checks, AI-assisted first pass, Ousterhout red flags, AI failure patterns, advocacy-specific concerns | +| `advocacy-code-review/` | advocacy-code-review | Five-layer review pipeline: automated checks, AI-assisted first pass, Ousterhout red flags, AI failure patterns, advocacy-specific concerns | | `security-audit/` | security-audit | Ten-step audit: dependency verification, API retention, storage encryption, input validation, instruction file integrity, MCP servers, device seizure, ag-gag exposure, coalition boundaries, findings report | diff --git a/claude-code/.claude/skills/code-review/README.md b/claude-code/.claude/skills/advocacy-code-review/README.md similarity index 100% rename from claude-code/.claude/skills/code-review/README.md rename to claude-code/.claude/skills/advocacy-code-review/README.md diff --git a/claude-code/.claude/skills/code-review/SKILL.md b/claude-code/.claude/skills/advocacy-code-review/SKILL.md similarity index 99% rename from claude-code/.claude/skills/code-review/SKILL.md rename to claude-code/.claude/skills/advocacy-code-review/SKILL.md index 80380ab..e1b6e99 100644 --- a/claude-code/.claude/skills/code-review/SKILL.md +++ b/claude-code/.claude/skills/advocacy-code-review/SKILL.md @@ -1,5 +1,5 @@ --- -name: code-review +name: advocacy-code-review description: Layered code review pipeline — automated checks first, then AI-assisted review, then human review focused on Ousterhout red flags, AI failure patterns, silent failures, and advocacy-specific concerns --- # Code Review diff --git a/claude-code/.claude/skills/testing-strategy/README.md b/claude-code/.claude/skills/advocacy-testing-strategy/README.md similarity index 100% rename from claude-code/.claude/skills/testing-strategy/README.md rename to claude-code/.claude/skills/advocacy-testing-strategy/README.md diff --git a/claude-code/.claude/skills/testing-strategy/SKILL.md b/claude-code/.claude/skills/advocacy-testing-strategy/SKILL.md similarity index 99% rename from claude-code/.claude/skills/testing-strategy/SKILL.md rename to claude-code/.claude/skills/advocacy-testing-strategy/SKILL.md index 1bdf338..047d096 100644 --- a/claude-code/.claude/skills/testing-strategy/SKILL.md +++ b/claude-code/.claude/skills/advocacy-testing-strategy/SKILL.md @@ -1,5 +1,5 @@ --- -name: testing-strategy +name: advocacy-testing-strategy description: Spec-first test generation, assertion quality review, mutation testing, five anti-patterns to avoid — for AI-assisted advocacy development where silent test failures mean lost evidence or exposed activists --- # Testing Strategy diff --git a/claude-code/CLAUDE.md b/claude-code/CLAUDE.md index 81fe5dd..5866b26 100644 --- a/claude-code/CLAUDE.md +++ b/claude-code/CLAUDE.md @@ -41,29 +41,9 @@ See `.claude/rules/` for domain-specific guidance: testing, security, privacy, c See `hooks-template.md`. Hooks execute shell commands before/after agent actions — strictly superior to instruction-based enforcement for deterministic checks. Pre-commit: block sensitive data from git history. Post-edit: auto-format. Pre-push: full test suite. -## Code Quality — desloppify +## Code Quality -Run desloppify to systematically identify and fix code quality issues. Install and configure before scanning (requires Python 3.11+): - -```bash -pip install --upgrade "desloppify[full]" -desloppify update-skill claude -``` - -Add `.desloppify/` to `.gitignore` — it contains local state that should not be committed. Before scanning, exclude directories that should not be analyzed (vendor, build output, generated code, worktrees) with `desloppify exclude `. Share questionable candidates with the project owner before excluding. - -```bash -desloppify scan --path . -desloppify next -``` - -`--path` is the directory to scan (use `.` for the whole project, or a subdirectory like `src/`). Your goal is to get the strict score as high as possible. The scoring resists gaming — the only way to improve it is to actually make the code better. - -**The loop:** run `next`. It is the execution queue from the living plan, not the whole backlog. It tells you what to fix now, which file, and the resolve command to run when done. Fix it, resolve it, run `next` again. This is your main job. Use `desloppify backlog` only when you need to inspect broader open work not currently driving execution. - -Do not be lazy. Large refactors and small detailed fixes — do both with equal energy. No task is too big or too small. Fix things properly, not minimally. - -Use `plan` / `plan queue` to reorder priorities or cluster related issues. Rescan periodically. The scan output includes agent instructions — follow them, do not substitute your own analysis. +See `.claude/rules/desloppify.md` for desloppify setup and usage. ## MCP Servers diff --git a/claude-code/hooks-template.md b/claude-code/hooks-template.md index dd623e1..27aa52c 100644 --- a/claude-code/hooks-template.md +++ b/claude-code/hooks-template.md @@ -57,4 +57,51 @@ Replace with a grep-based script or dedicated PII scanner configured with your p ## How to Configure -Claude Code hooks are configured through the tool's settings interface or configuration files. Consult the Claude Code documentation for the exact format and available trigger points. Each hook definition specifies the trigger event, the shell command to run, and whether a non-zero exit code should block the action. +Add hooks to `.claude/settings.json` (project-level) or `.claude/settings.local.json` (personal, gitignored). The structure: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "YOUR_SECURITY_SCANNER --staged-files-only", + "timeout": 30000 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Edit|Write", + "hooks": [ + { + "type": "command", + "command": "YOUR_FORMATTER --file $CLAUDE_FILE_PATH", + "timeout": 10000 + } + ] + } + ], + "PreToolUse:Bash(git push*)": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "YOUR_TEST_RUNNER --full-suite", + "timeout": 300000 + } + ] + } + ] + } +} +``` + +**Event names:** `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, `Notification`. The `matcher` field is a regex matched against the tool name (or tool name + arguments). `timeout` is in milliseconds. A non-zero exit code from a `PreToolUse` hook blocks the action. + +Use `/hooks` in Claude Code to interactively add and test hooks.