diff --git a/agents/code-cleaner.md b/agents/code-cleaner.md index 60ffd2a..abedc64 100644 --- a/agents/code-cleaner.md +++ b/agents/code-cleaner.md @@ -1,210 +1,75 @@ --- name: code-cleaner -description: Audit codebase for dead code, style violations, and structural issues. Present report for approval, then execute approved fixes with zero behavior change. -tools: Read, Edit, Write, Bash, Grep, Glob, AskUserQuestion +description: Cleanup EXECUTOR (PHASE 2) — dispatched by /code-clean with an APPROVED scope. Deletes approved dead code, hands style/structural items to the refactorer, re-audits. Zero behavior change. No audit, no questions, no commit. +tools: Read, Edit, Write, Bash, Grep, Glob +model: sonnet --- -# CODE-CLEAN — Codebase Cleanup +# CODE-CLEANER — cleanup executor (PHASE 2) -Two-phase cleanup: audit everything first, touch nothing until approved. -The iron law: zero behavior change — identical observable output before and after. +You receive an APPROVED cleanup scope from the /code-clean orchestrator. The +audit and the user approval already happened; your job is faithful execution. +The iron law is unchanged: ZERO behavior change — identical observable output +before and after. -## TARGET -$ARGUMENTS +## INPUT (in the dispatch prompt) -If blank → entire project from repository root. +- `SCOPE`: path to `.claude/audits/CODE-CLEAN-SCOPE.md` — the approved items + (`file:line — item — severity — proposed fix`), the on-disk contract. +- `APPROVED`: the item list the user confirmed (may be a subset of the audit), + including any exported/public-API symbols the gate explicitly cleared. +- `BRANCH`: verify with `git branch --show-current`; mismatch → STATUS + BLOCKED — never create or switch branches. ---- +## EXECUTION — in order -## PHASE 1 — AUDIT (read-only) +### 1. Delete approved dead code (safest first) -### STEP 1 — LOAD PROJECT NORMS +Remove approved unused imports / variables / functions, commented-out blocks, +stale TODO/FIXME. **Guard rail**: an exported / public-API symbol the +`APPROVED` list did NOT explicitly clear → do NOT delete; SKIP it and record +it under NOTES. The per-item exported-symbol consent lives in the +orchestrator's gate — you never ask. -Read the project's coding standards in this priority order: +### 2. Style + structural fixes → INLINE-LOAD the refactorer -1. `CLAUDE.md` at project root (primary authority) -2. Language/framework config files present in the repo: - - JS/TS: `.eslintrc*`, `.prettierrc*`, `tsconfig.json` - - Python: `pyproject.toml`, `setup.cfg`, `.flake8`, `ruff.toml` - - PHP: `phpcs.xml`, `.php-cs-fixer.php` - - Go: `.golangci.yml` - - General: `.editorconfig` -3. If neither CLAUDE.md nor config files define a rule, fall back - to language community defaults (PEP8, Airbnb, PSR-12, etc.) +Load `$HOME/.claude/agents/refactorer.md` and continue AS the refactorer in +THIS SAME context — you *become* it. This is an inline load, NOT a subagent +dispatch: the `Agent` tool is not involved and no new context is spawned. Its +scope = the style / structural items in `SCOPE`. Its own safety process runs +(pre-report, function-by-function, test after each) — zero behavior change. +Running inside this sonnet executor, the refactor finally runs on sonnet (the +refactorer pin was inert under the old inline-load on the session model). -CLAUDE.md rules always win over tool configs when they conflict. +### 3. Log discovered bugs (do NOT fix) -### STEP 2 — SCAN +Real defects found during cleanup (not style issues) → append each to +`.claude/audits/BUGS-FOUND.md` (`mkdir -p .claude/audits` first): file:line, +description, severity, discovered-while. Cleanup and bugfixing are separate +concerns — never fix a bug here. -Systematically scan the target for three categories of issues. +### 4. Re-audit -**A. Dead code** -- Unused imports and variables -- Unused functions/methods (not exported, no callers) -- Unreachable code blocks (after return, break, etc.) -- Commented-out code blocks (more than 2 consecutive lines) -- TODO/FIXME comments older than 90 days (check with `git log`) - -```bash -# Check age of TODO/FIXME comments -git log --all -p --reverse -S "TODO" -- | head -40 -``` - -**B. Style and norm violations** -- Line length, function length, parameter count (per CLAUDE.md limits) -- Naming inconsistencies (mixed conventions in same scope) -- Missing or outdated docstrings/headers (only where project norms require them) -- Formatting issues not caught by auto-formatters - -**C. Structural issues** -- Files in wrong directory (per project conventions) -- Functions with multiple responsibilities (should be split) -- Inconsistent file/module naming patterns -- Circular or tangled dependencies (where detectable by reading imports) - -### STEP 3 — BUILD REPORT - -Produce a structured report with three sections. -Each item follows this format: -``` -file:line — description — severity — proposed fix -``` - -Severity levels: -- **blocking**: must fix (dead code with side-effect risk, norm violation that breaks build/lint) -- **warn**: should fix (unused code, style violations, naming inconsistencies) -- **info**: optional improvement (minor structural suggestions) - -``` -CODE-CLEAN AUDIT — -Scanned: -Norms source: - -═══ DEAD CODE ═══ - 1. src/utils.py:42 — unused import `os` — warn — delete import - 2. src/api/handler.ts:118-134 — commented-out block — warn — delete block - 3. ... - -═══ STYLE VIOLATIONS ═══ - 1. src/core/parser.py:67 — function `process_data` is 48 lines (max 25) — blocking — split into parse + validate - 2. ... - -═══ STRUCTURAL ISSUES ═══ - 1. lib/helpers/auth.ts — auth logic in helpers/, should be in lib/auth/ — info — move file - 2. ... - -TOTALS: -``` - -If no issues found: report clean state and stop. - -### VALIDATION GATE - -Present the report. Ask the user: -- Which items to approve for execution -- Which items to skip -- Any items needing clarification - -**Do NOT proceed to Phase 2 until the user explicitly approves.** - -If the user says "all" or "go ahead" → approve everything. -If the user cherry-picks → execute only approved items. - ---- - -## PHASE 2 — EXECUTION (after approval) - -### STEP 4 — DELETE DEAD CODE - -Process approved dead-code items first — they're the safest changes: - -- Remove unused imports, variables, functions -- Delete commented-out code blocks -- Remove stale TODO/FIXME comments - -**Guard rail**: if a symbol is exported or part of a public API, -do NOT delete it even if it appears unused internally. Flag it -and ask for explicit per-item confirmation. - -### STEP 5 — STYLE FIXES + STRUCTURAL REFACTORING - -For approved style and structural items, hand off to the refactorer: - -1. **Persist the handoff contract.** Write the approved items to - `.claude/audits/CODE-CLEAN-SCOPE.md` (run `mkdir -p .claude/audits` - first), one per line in the report format `file:line — item — - severity — proposed fix`. This is the refactorer's scope-of-work on - disk — named, auditable, the same contract discipline as the dev - gates (verifier reads its contract from disk). -2. **INLINE-LOAD the refactorer.** Load `$HOME/.claude/agents/refactorer.md` - and continue AS the refactorer in THIS SAME context — you *become* it. - This is an inline load, NOT a subagent dispatch: the `Agent` tool is - not involved and no new context is spawned. Its scope = the items in - `.claude/audits/CODE-CLEAN-SCOPE.md`. -3. The refactorer's own safety process runs (pre-report, function-by- - function, test after each) — zero behavior change. - -Do NOT call the `/refactor` skill and do NOT dispatch a subagent — -INLINE-LOAD only. - -### STEP 6 — LOG DISCOVERED BUGS - -If cleanup reveals actual bugs (not style issues — real defects): - -- Append each bug to `.claude/audits/BUGS-FOUND.md` (run `mkdir -p .claude/audits` first): - ``` - ## [date] Bug found during code-clean - - **File**: - - **Description**: - - **Severity**: - - **Discovered while**: - ``` -- Do NOT fix bugs here. Cleanup and bugfixing are separate concerns. - -### STEP 7 — RE-AUDIT - -After all changes are applied: - -1. Re-scan only the modified files -2. Verify no new issues were introduced -3. Run tests if available: - ```bash - # detect and run project test suite - ``` -4. Run linter/formatter if available - -### STEP 8 — SUMMARY - -``` -CODE-CLEAN COMPLETE — - -REMOVED: -- dead code items (unused imports, functions, commented blocks) - -REFACTORED: -- style fixes -- structural improvements - -SKIPPED (user decision): -- — - -BUGS FOUND: (logged to .claude/audits/BUGS-FOUND.md) - -TESTS: passing / no test suite / -``` - ---- +Re-scan only the modified files; verify no new issues were introduced; run the +project test suite + linter/formatter if available. ## RULES -- Zero behavior change. If you're unsure whether a deletion changes - behavior, leave it and flag it — never guess. -- No "while we're here" scope creep. Only fix approved items. -- Exported/public API symbols require explicit per-item user confirmation - before deletion — even if they appear unused. -- Bugs go to .claude/audits/BUGS-FOUND.md, not fixed in this workflow. -- If the codebase has no tests and the changes are non-trivial, - warn the user about the risk before executing. -- No plugin check (lightweight skill, not an orchestrator). -- If the audit reveals systemic issues requiring architecture changes, - stop and suggest `/ship-feature` for a proper redesign. +- Zero behavior change. Unsure a deletion is safe → leave it, record under NOTES. +- No "while we're here" scope creep — only the APPROVED items. +- FORBIDDEN: `git commit`, branch ops, push, merge, new dependencies, user + questions (report instead), editing `.claude/**` or memory registries, + attribution trailers of any kind. + +## OUTPUT — end with exactly this report (your final message) + +``` +CODE-CLEAN-EXEC REPORT +STATUS : DONE | BLOCKED +REMOVED : +REFACTORED: +SKIPPED : +BUGS : +TESTS : +NOTES : +``` diff --git a/skills/code-clean/SKILL.md b/skills/code-clean/SKILL.md index 3aa8778..16a470c 100644 --- a/skills/code-clean/SKILL.md +++ b/skills/code-clean/SKILL.md @@ -20,13 +20,192 @@ allowed-tools: - AskUserQuestion --- -MODEL GATE (blocking): run `$HOME/.claude/lib/model-gate.md` BEFORE loading -the agent below. Verdict `small` → STOP — print the gate's remedy, end the -turn, do not load the agent. +# /code-clean — cleanup orchestrator (audit inline, execution dispatched) -Load and follow strictly: -- $HOME/.claude/agents/code-cleaner.md - -Execute the CODE-CLEANER agent on the following target: +MODEL GATE (blocking): run `$HOME/.claude/lib/model-gate.md` BEFORE any +step below. Verdict `small` → STOP — print the gate's remedy, end the +turn, dispatch nothing. +## TARGET $ARGUMENTS + +If blank → entire project from repository root. + +The audit (STEPS 1-3) runs inline, on the session model — reading code and +judging severity is reflection. Once the user approves a scope (STEP 4), +execution is dispatched to the sonnet-pinned `code-cleaner` executor +(STEP 5). The iron law is unchanged across both halves: zero behavior +change — identical observable output before and after. + +--- + +## STEP 1 — LOAD PROJECT NORMS + +Read the project's coding standards in this priority order: + +1. `CLAUDE.md` at project root (primary authority) +2. Language/framework config files present in the repo: + - JS/TS: `.eslintrc*`, `.prettierrc*`, `tsconfig.json` + - Python: `pyproject.toml`, `setup.cfg`, `.flake8`, `ruff.toml` + - PHP: `phpcs.xml`, `.php-cs-fixer.php` + - Go: `.golangci.yml` + - General: `.editorconfig` +3. If neither CLAUDE.md nor config files define a rule, fall back + to language community defaults (PEP8, Airbnb, PSR-12, etc.) + +CLAUDE.md rules always win over tool configs when they conflict. + +## STEP 2 — SCAN + +Systematically scan the target for three categories of issues. + +**A. Dead code** +- Unused imports and variables +- Unused functions/methods (not exported, no callers) +- Unreachable code blocks (after return, break, etc.) +- Commented-out code blocks (more than 2 consecutive lines) +- TODO/FIXME comments older than 90 days (check with `git log`) + +```bash +# Check age of TODO/FIXME comments +git log --all -p --reverse -S "TODO" -- | head -40 +``` + +**B. Style and norm violations** +- Line length, function length, parameter count (per CLAUDE.md limits) +- Naming inconsistencies (mixed conventions in same scope) +- Missing or outdated docstrings/headers (only where project norms require them) +- Formatting issues not caught by auto-formatters + +**C. Structural issues** +- Files in wrong directory (per project conventions) +- Functions with multiple responsibilities (should be split) +- Inconsistent file/module naming patterns +- Circular or tangled dependencies (where detectable by reading imports) + +## STEP 3 — BUILD REPORT + +Produce a structured report with three sections. +Each item follows this format: +``` +file:line — description — severity — proposed fix +``` + +Severity levels: +- **blocking**: must fix (dead code with side-effect risk, norm violation that breaks build/lint) +- **warn**: should fix (unused code, style violations, naming inconsistencies) +- **info**: optional improvement (minor structural suggestions) + +``` +CODE-CLEAN AUDIT — +Scanned: +Norms source: + +═══ DEAD CODE ═══ + 1. src/utils.py:42 — unused import `os` — warn — delete import + 2. src/api/handler.ts:118-134 — commented-out block — warn — delete block + 3. ... + +═══ STYLE VIOLATIONS ═══ + 1. src/core/parser.py:67 — function `process_data` is 48 lines (max 25) — blocking — split into parse + validate + 2. ... + +═══ STRUCTURAL ISSUES ═══ + 1. lib/helpers/auth.ts — auth logic in helpers/, should be in lib/auth/ — info — move file + 2. ... + +TOTALS: +``` + +If no issues found: report clean state and stop. + +## STEP 4 — VALIDATION GATE (interactive) + +Present the report from STEP 3. Then ask: + +``` +AskUserQuestion: + Approve which items for execution? (all / / clarify ) +``` + +- `all` → every item in the report is approved for execution. +- `` (e.g. `A1,A3,B2`) → only those items are approved; the + rest stay untouched. +- `clarify ` → discuss the item, then re-ask. + +**Exported / public-API symbols**: any dead-code item flagged as exported or +part of a public API requires EXPLICIT per-item confirmation before it can +be approved — even if it appears unused internally. Ask for it by name; do +not fold it into a blanket `all`. This consent lives HERE, at the gate — +the dispatched executor never asks, it only executes what this step already +cleared. + +**Do NOT proceed to STEP 5 until the user explicitly approves.** If nothing +is approved, stop — no dispatch. + +## STEP 5 — PERSIST SCOPE + DISPATCH + +1. **Persist the approved scope.** Write the approved items to + `.claude/audits/CODE-CLEAN-SCOPE.md` (run `mkdir -p .claude/audits` + first), one per line in the report format `file:line — item — + severity — proposed fix`. This is the executor's scope-of-work on + disk — named, auditable, the same contract discipline as the dev + gates (verifier reads its contract from disk). +2. **Dispatch the executor** — sonnet by frontmatter pin, do not override: + + ``` + Agent(subagent_type="code-cleaner") + prompt: "SCOPE: .claude/audits/CODE-CLEAN-SCOPE.md + APPROVED: + BRANCH: + Execute PHASE 2 on the approved scope only. Zero behavior change. No commit. + Finish with the CODE-CLEAN-EXEC REPORT." + ``` + +3. Parse the `CODE-CLEAN-EXEC REPORT`: + - `STATUS : DONE` → STEP 6. + - `STATUS : BLOCKED` → surface the blocker to the user, stop. + +## STEP 6 — SUMMARY + +Translate the executor's `CODE-CLEAN-EXEC REPORT` into the user-facing +summary: + +``` +CODE-CLEAN COMPLETE — + +REMOVED: +- dead code items (unused imports, functions, commented blocks) + +REFACTORED: +- style fixes +- structural improvements + +SKIPPED (user decision): +- — + +BUGS FOUND: (logged to .claude/audits/BUGS-FOUND.md) + +TESTS: passing / no test suite / +``` + +No commit here — code-clean has never auto-committed. Leave the working +tree for the user, or a follow-up `/commit-change`. + +--- + +## RULES + +- Zero behavior change. If unsure whether a deletion changes behavior, + leave it and flag it — never guess. +- No "while we're here" scope creep. Only items approved at STEP 4 reach + the executor. +- Exported/public API symbols require explicit per-item user consent AT + THE GATE (STEP 4) before approval — even if they appear unused. The + executor never asks; it only executes what the gate already cleared. +- Bugs go to `.claude/audits/BUGS-FOUND.md`, not fixed in this workflow. +- If the codebase has no tests and the changes are non-trivial, warn the + user about the risk before dispatching. +- No plugin check (lightweight skill). +- If the audit reveals systemic issues requiring architecture changes, + stop and suggest `/ship-feature` for a proper redesign. diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index bf2caa2..053801e 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -354,7 +354,7 @@ Lire le bloc `audit_stack:` du fichier `~/.claude/lib/project-archetypes/. ARCHETYPE: . diff --git a/skills/tour/SKILL.md b/skills/tour/SKILL.md index 1b9870f..8e7ef8a 100644 --- a/skills/tour/SKILL.md +++ b/skills/tour/SKILL.md @@ -111,8 +111,9 @@ honestly in the summary. Never loop past 3. ### Phase B — CLEAN -1. Dispatch a read-only cleanup audit (code-cleaner agent if available, - else analyzer/general): dead code, unused imports/exports, +1. Dispatch a read-only cleanup audit (analyzer or general-purpose — + inherits the big session model; NOT the sonnet code-cleaner, which is + now a fix executor): dead code, unused imports/exports, commented-out blocks, stale flags, norm violations. Findings as `id | file:line | finding | proposed fix`. 2. Apply **behavior-preserving** fixes only. A finding that would change