Skip to content

notque/vexjoy-agent / skills/code-quality/code-quality

code-quality

Unverified

Code quality: cleanup, linting, formatting, quality gates.

Code Quality

Four modes. Select by request signal:

SignalMode
Dead code, stale TODOs, unused imports, technical debtCleanup
Lint Python/JS/TS, run ruff, run biome, format codeLinting
Python quality checks, ruff+pytest+mypy+banditPython Quality Gate
Multi-language quality gate, general "quality check"Universal Quality Gate

Default: Python-specific requests run Python Quality Gate. General requests run Universal Quality Gate.


Mode A: Cleanup

Scan for 9 categories of technical debt: stale TODOs, unused imports, dead code, missing type hints, deprecated functions, naming inconsistencies, high complexity, duplicate code, missing docstrings. Follow references/code-cleanup.md for the full 3-phase workflow (SCOPE, SCAN, REPORT).

Key principles:

  • Read CLAUDE.md first for project conventions
  • Scan only what was requested; ask for a target rather than scanning everything
  • Exclude vendor/, node_modules/, .venv/, build/, dist/, generated/, .git/
  • Prioritize findings by impact/effort: Quick Wins (auto-fixable, <5 min) > Important (bugs, security) > Polish (style)
  • Apply auto-fixes only with explicit user permission; check first, fix, review diff, rerun checks

Mode B: Linting

Check or fix Python with Ruff and JavaScript/TypeScript with Biome. Read project instructions, pyproject.toml, and biome.json first; preserve configured rules.

TaskPythonJavaScript/TypeScript
Checkruff check .npx @biomejs/biome check src/
Format checkruff format --check .Included in Biome check
Fix lintruff check --fix .npx @biomejs/biome check --write src/
Formatruff format .npx @biomejs/biome format --write src/

Use project environment (./venv/bin/ruff). If configured, use make lint or make lint-fix. Check first; apply fixes only within requested scope. Review git diff, undo incorrect fixes, rerun checks. Do not change rules or install new tooling to get a pass.

Common fixes: F401 = remove/use import. I001 = sort imports. E501 = shorten lines. Biome noVar = use let/const. useConst = mark unchanged bindings.


Mode C: Python Quality Gate

Run checks in order. Read repository configuration first; project commands and thresholds override defaults.

Detect: Find pyproject.toml, setup.py, .python-version. Check tool availability: ruff and pytest required; mypy and bandit optional unless project requires them.

Execute:

OrderCommandCondition
1ruff check . --output-format=groupedRequired
2ruff format --check .Required
3mypy . --ignore-missing-imports --show-error-codesIf available
4pytest -v --tb=short --cov=src --cov-report=term-missingCoverage only when configured
5bandit -r src/ -ll --format=screenIf available

Run all checks even after one fails. Do not skip tests to get a pass.

Assess: Prioritize syntax/undefined errors, failing tests, security findings before style. Report per-tool status with actionable file:line diagnostics.

Fix: When authorized, run ruff check . --fix and ruff format ., review diff, rerun checks.


Mode D: Universal Quality Gate

Auto-detect languages and run configured checks. Read repository instructions first.

python3 ~/.claude/skills/code-quality/scripts/run_quality_gate.py

Options: --staged (pre-commit), --lang python (single language), --fix (apply fixes), -v (verbose).

Language detection uses hooks/lib/language_registry.json:

LanguageMarkersTools
Pythonpyproject.toml, requirements.txtruff, mypy, bandit
Gogo.modgofmt, golangci-lint, go vet
JavaScriptpackage.jsoneslint, biome
TypeScripttsconfig.jsontsc, eslint, biome
RustCargo.tomlclippy, cargo fmt
Shell*.shshellcheck

A gate pass means required tools passed; it does not prove tests, builds, or business behavior passed.


Deep References

Load on demand when the signal matches.

SignalReferenceContent
Full cleanup workflow (9 categories)references/code-cleanup.md3-phase cleanup: SCOPE, SCAN, REPORT
Language-specific scan commandsreferences/cleanup-scan-commands.mdPer-language commands and expected output
Cleanup report formattingreferences/cleanup-report-template.mdStructured report template
Ruff rules, F401/E711/B006references/ruff-rules-reference.mdRuff rule reference by category
Biome rules, ESLint migrationreferences/biome-rules-reference.mdBiome rule reference by category
Python quality tool commandsreferences/python-tool-commands.mdDetailed tool command options
Python quality reportreferences/python-report-template.mdStructured report template
pyproject.toml templatereferences/pyproject-template.tomlTool configuration template
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall