diff --git a/.claude/skills/quality-scan/SKILL.md b/.claude/skills/quality-scan/SKILL.md index 11014b4af..4dafcdf72 100644 --- a/.claude/skills/quality-scan/SKILL.md +++ b/.claude/skills/quality-scan/SKILL.md @@ -3,6 +3,8 @@ name: quality-scan description: > Runs iterative code quality scans on socket-cli, fixing all discovered issues and committing changes until zero issues remain or 5 iterations complete. + Use when improving code quality, investigating regressions, or before + releases. --- # quality-scan diff --git a/.claude/skills/security-scan/SKILL.md b/.claude/skills/security-scan/SKILL.md index f8eaf37ad..7f2fd77e8 100644 --- a/.claude/skills/security-scan/SKILL.md +++ b/.claude/skills/security-scan/SKILL.md @@ -1,6 +1,6 @@ --- name: security-scan -description: Runs a multi-tool security scan — AgentShield for Claude config, zizmor for GitHub Actions, and optionally Socket CLI for dependency scanning. Produces an A-F graded security report. +description: Runs a multi-tool security scan — AgentShield for Claude config, zizmor for GitHub Actions, and optionally Socket CLI for dependency scanning. Produces an A-F graded security report. Use after modifying `.claude/` config, hooks, agents, or GitHub Actions workflows, and before releases. user-invocable: true --- diff --git a/CLAUDE.md b/CLAUDE.md index 9f2a673c1..098dec654 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,56 +11,68 @@ **MANDATORY**: Review CLAUDE.md before any action. No exceptions. -- Before ANY structural refactor on a file >300 LOC: remove dead code, unused exports, unused imports first -- commit that cleanup separately -- Multi-file changes: break into phases (<=5 files each), verify each phase before the next -- When pointed to existing code as a reference: study it before building -- Work from raw error data, not theories -- if a bug report has no error output, ask for it +- Before ANY structural refactor on a file >300 LOC: remove dead code/unused exports/imports first — commit separately +- Multi-file changes: break into phases (≤5 files each), verify each phase before the next +- Study existing code before building +- Work from raw error data, not theories — if a bug report has no error output, ask for it - On "yes", "do it", or "go": execute immediately, no plan recap ## VERIFICATION PROTOCOL -**MANDATORY**: Before claiming any task is complete: - -1. Run the actual command -- execute the script, run the test, check the output +1. Run the actual command — execute, don't assume 2. State what you verified, not just "looks good" 3. **FORBIDDEN**: Claiming "Done" when any test output shows failures -4. If type-check or lint is configured, run it and fix ALL errors before reporting done -5. Re-read every file modified; confirm nothing references something that no longer exists +4. Run type-check/lint if configured; fix ALL errors before reporting done +5. Re-read every modified file; confirm nothing references removed items ## CONTEXT & EDIT SAFETY -- After 10+ messages: re-read any file before editing it -- Read files >500 LOC in chunks using offset/limit -- Before every edit: re-read the file. After every edit: re-read to confirm -- When renaming: search for direct calls, type references, string literals, dynamic imports, re-exports, test files -- one grep is not enough +- After 10+ messages: re-read files before editing +- Read files >500 LOC in chunks (offset/limit) +- Before every edit: re-read. After every edit: re-read to confirm +- When renaming: search direct calls, type refs, string literals, dynamic imports, re-exports, tests +- Tool results over 50K chars are silently truncated — narrow scope and re-run if incomplete +- For tasks touching >5 files: use sub-agents with worktree isolation - Never fix a display/rendering problem by duplicating state -## JUDGMENT & SCOPE +## JUDGMENT PROTOCOL + +- If the user's request is based on a misconception, say so before executing +- If you spot a bug adjacent to what was asked, flag it: "I also noticed X — want me to fix it?" +- You are a collaborator, not just an executor +- Fix warnings when you find them (lint, type-check, build, runtime) — don't leave them for later + +## SCOPE PROTOCOL -- If the request is based on a misconception, say so before executing -- If you spot a bug adjacent to what was asked, flag it - Do not add features, refactor, or make improvements beyond what was asked -- Try the simplest approach first; flag architecture issues and wait for approval -- When asked to "make a plan," output only the plan -- no code until given the go-ahead +- Simplest approach first; flag architectural flaws and wait for approval +- When asked to "make a plan," output only the plan — no code until given the go-ahead + +## COMPLETION PROTOCOL + +- NEVER claim done at 80% — finish 100% before reporting +- Fix forward: if an approach fails, analyze why, adjust, rebuild — not `git checkout` +- After EVERY code change: build, test, verify, commit as a single atomic unit +- Reverting requires explicit user approval ## SELF-EVALUATION -- Before calling anything done: present what a perfectionist would reject vs. what a pragmatist would ship +- Present two views before calling done: what a perfectionist would reject vs. what a pragmatist would ship - After fixing a bug: explain why it happened and what category of bug it represents -- If a fix doesn't work after two attempts: stop, re-read top-down, state where the mental model was wrong +- If a fix fails twice: stop, re-read top-down, state where the mental model was wrong - If asked to "step back": drop everything, rethink from scratch ## HOUSEKEEPING -- Before risky changes: offer to checkpoint -- If a file is getting unwieldy (>400 LOC): flag it +- Offer to checkpoint before risky changes +- Flag files >400 LOC for potential splitting -## Critical Rules +## ABSOLUTE RULES -- **Fix ALL issues when asked** -- never dismiss issues as "pre-existing" +- **Fix ALL issues when asked** — never dismiss as "pre-existing" - Never create files unless necessary; always prefer editing existing files - Forbidden to create docs unless requested -- 🚨 **NEVER use `npx`, `pnpm dlx`, or `yarn dlx`** -- use `pnpm exec ` for devDep binaries, or `pnpm run