CommunityCoding & Developmentgithub.com

CodeQuality

Code quality loop for any repo, seen through two lenses — a tool lens (linters, type checkers, security, dead-code and duplication scanners; fix by P0 security → P1 correctness → P2 maintainability) and a principle lens (SOLID + Clean Code smells; one principle at a time, propose → confirm → apply behind characterization tests). One manifest of free local tools, one scan, one fix loop, one mandatory Quality Improvement Report. USE WHEN improve code quality, analyze code, fix linting, reduce duplication, add types, security scan, test coverage, refactor, improve code design, apply SOLID, clean code refactor, reduce complexity, kill code smells, make code maintainable, refactor legacy code, single responsibility, dependency inversion, remediation sprint, install quality tools, quality baseline, smell report, refactoring roadmap, what should we fix first. NOT FOR the issue lifecycle, branches, PRs or merging (use IssueFlow; its Remediation workflow calls this skill to pick and scope the w

What is CodeQuality?

CodeQuality is a Claude Code agent skill that code quality loop for any repo, seen through two lenses — a tool lens (linters, type checkers, security, dead-code and duplication scanners; fix by P0 security → P1 correctness → P2 maintainability) and a principle lens (SOLID + Clean Code smells; one principle at a time, propose → confirm → apply behind characterization tests). One manifest of free local tools, one scan, one fix loop, one mandatory Quality Improvement Report. USE WHEN improve code quality, analyze code, fix linting, reduce duplication, add types, security scan, test coverage, refactor, improve code design, apply SOLID, clean code refactor, reduce complexity, kill code smells, make code maintainable, refactor legacy code, single responsibility, dependency inversion, remediation sprint, install quality tools, quality baseline, smell report, refactoring roadmap, what should we fix first. NOT FOR the issue lifecycle, branches, PRs or merging (use IssueFlow; its Remediation workflow calls this skill to pick and scope the w.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/juanmherrerav/agent-workday-skills/tree/main/skills/CodeQuality

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Customization

Optional personal preferences: ${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/CodeQuality/PREFERENCES.md.

If that file exists, read and apply it; otherwise proceed with skill defaults. Personal preferences only: anything that is a fact about a repo or product belongs in that repo (its .claude/workflow-profile.sh or tool configs), never here.

What does CodeQuality do?

One loop, two lenses. The loop is always detect → pick one item → fix behind tests → verify → repeat. The tool lens fixes what scanners flag, in priority order, with existing tests as the guard. The principle lens fixes what makes code hard to change (god classes, duplication, untestable cores), one SOLID / Clean Code principle at a time, and never applies a design move without showing it first. Both lenses read the same tool manifest, write to the same report directory, and end with the same Quality Improvement Report.

Two lenses

Tool lensPrinciple lens
Driverscanner output (summary.md)design smells mapped to Principles.md (smell-inventory.md, roadmap.md)
Unit of workone finding: one rule at one file:lineone principle on one bounded hotspot: one Extract, one class split, one dependency inversion
OrderP0 security → P1 correctness → P2 maintainabilityleverage ladder (below), adjusted per repo
Autonomyfix, then show the diffpropose → confirm → apply; nothing is edited before approval
Safety netexisting tests stay greencharacterization tests written first when the target is untested
Metricfewer findings, tool re-run cleanduplication %, cyclomatic complexity, function length, fan-in/out, "now unit-testable"
Pick it whenlint/type/security debt, CI red, "make the scanners happy"code that resists change; a remediation sprint's structural tier

The loop

SCAN → SELECT → SAFETY NET → [PROPOSE → CONFIRM] → FIX → VERIFY → REPORT → REPEAT
                             └─ mandatory in principle mode, skipped in tool mode ─┘

Workflow routing

TriggerWorkflowProduces
"install quality tools", "set up code quality"Workflows/Install.mdmanifest tools installed and verified
"scan", "baseline", "analyze code quality", "smell report", "what should we fix first", "refactoring roadmap"Workflows/Scan.mdsummary.md (A), smell-inventory.md (B), roadmap.md (C)
"improve code quality", "fix lint", "quality loop", "fix [finding]"Workflows/Loop.md in tool modefixes, session-log.md, report
"refactor", "apply SOLID", "clean this up", "start the loop"Workflows/Loop.md in principle modefixes, session-log.md, report
"clean up this repo" with no qualifierScan A + B + C, then Loop in principle modeall of the above
"remediation sprint", "remediation cycle"IssueFlow Remediation owns the branch, PR and merge; Scan scopes the cycle, Loop executes itone PR per cycle

Loop picks its mode by itself when none is given: tool when no roadmap.md exists for the repo, principle when one does. The user can force either.

The manifest

Tools/tools.tsv is the only list of tools in this skill. Tab-separated, one row per tool and language: language category priority tool install run notes, with language in js | python | yaml, category in lint | format | types | security | deadcode | duplication | complexity | deps | coverage, priority in P0 | P1 | P2. Both scripts read it; the workflows never list tools inline. To add or drop a tool, edit one row.

ScriptReads from the manifestDoes
Tools/install-quality-tools.sh [--dry-run] [lang ...]install cells of the chosen languagesdetects languages (package.json → js; pyproject.toml, requirements.txt or *.py → python; *.yaml/*.yml → yaml); installs js tools as devDependencies with the repo's package manager (lockfile → npm/pnpm/bun), python and yaml tools with uv pip install or pip; npm:/pip: prefixes override the channel, - installs nothing
Tools/run-quality-baseline.sh [--dry-run] [lang ...]run cellsruns every tool into reports/codequality/<YYYY-MM-DD>-<HHMMSS>/, substituting $OUT (report dir), $SRC (QUALITY_SRC_DIRS, default src if it exists else .), $PM and $NPX; a tool that is not installed is MISSING, one that crashes is FAILED, neither stops the run; writes summary.md with per-tool status, parsed issue counts and P0/P1/P2 totals; prints the report path

Rows whose run is - (coverage tools) are installed but not run by the baseline: coverage is measured in the Loop, scoped to the target. Every tool is free and runs locally; npm audit, pip-audit and checkov reach the network only for their vulnerability databases.

Leverage ladder (principle lens default order)

  1. Names — code you cannot read, you cannot safely change. Cheap, unblocks everything.
  2. DRY / duplication — removes the most code at the lowest risk; exposes hidden abstractions.
  3. Small functions — Long Method → Extract; one level of abstraction per function.
  4. SRP — split classes and modules that change for more than one reason.
  5. OCP / DIP — invert dependencies, add seams; high impact, higher risk, safety net first.
  6. ISP / LSP — fat interfaces and broken substitutability; need the seams from step 5.

Scan part C adjusts this order to the actual inventory (leverage = impact ÷ risk; see Principles.md Part 3).

Non-negotiables

  • One item per iteration. One finding, or one principle on one bounded target. Small, reviewable diffs.
  • Behavior preserving. Structure changes, behavior does not. If behavior must change, stop and flag it: that is a feature, not a fix.
  • Green to green. Tests pass before and after. Red after a change means revert, never fix forward.
  • Characterization tests first when the lines to be touched are untested. No net, no refactor.
  • Propose before applying any design move (principle mode). Tool mode may fix directly, then shows the diff.
  • P0 → P1 → P2 for tool findings, across languages, never by language.
  • Never weaken a test or a lint rule to get green. Stale tests move to the new correct behavior; rules are satisfied in code.
  • Boy Scout, bounded. Leave touched files cleaner, but do not scope-creep past the current item.
  • Evidence, not opinion. Name the rule or principle, and a metric where one exists.

Output artifacts

All under reports/codequality/ (git-ignored):

FileWritten by
<YYYY-MM-DD>-<HHMMSS>/summary.md + raw tool outputrun-quality-baseline.sh (Scan A)
<YYYY-MM-DD>/smell-inventory.mdScan B
<YYYY-MM-DD>/roadmap.mdScan C
<YYYY-MM-DD>/session-log.mdLoop, one entry per iteration
<YYYY-MM-DD>/quality-report.mdLoop, at the end of the session (below)

Quality Improvement Report (mandatory)

Every Loop session ends with this report, in either mode. It is the deliverable alongside the code change, and the body of the PR or tracker comment when the work ships through IssueFlow.

SectionContent
Summary tablelines added / removed / net; issues before → after per priority; dead-code hotspots removed; tests before → after (count, all green)
Code removedfile, what, lines, risk
Code added or modifiedfile, what, lines, purpose
Bugs fixedseverity, description, root cause (only if any surfaced)
Complexity deltamax and mean cyclomatic complexity before → after, with an ASCII bar per hotspot
Deferreditems seen but out of scope, and why

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

BattlePlan

Daily execution plan from a task tracker (local CSV, Excel workbook, or Google Sheet). Groups open tasks by context and sub-context, estimates time, finds parallel threads, and writes ready-to-paste starting prompts per thread. Starts from yesterday instead of from zero — recaps the previous day's agent sessions and git commits, pre-fills the audit, and offers resume commands. Includes an end-of-day handoff (--close), an unattended morning draft (--draft), and task management (add, done, cancel, restore, sweep, batch import). USE WHEN plan my day, daily plan, battle plan, what should I work on, close the day, end of day handoff, morning draft, task overview, standup prep, prioritize tasks, add a task, mark task done, set up battleplan, configure task tracker.

MeetingAnalysis

Turn meetings into structured summaries and tracked action items. Transcribes recordings locally (faster-whisper on CUDA, Apple Silicon or CPU), imports Google Meet / Gemini notes through connectors, or takes pasted notetaker transcripts; writes a summary with decisions and an action table; pushes only your own items to the BattlePlan tracker. Includes an unattended inbox ingest (drop a recording, get a summary) and a hard rule that recordings never land in a git repo. USE WHEN analyze meeting, meeting summary, transcribe meeting, transcribe recording, summarize this call, what happened in the meeting, import meeting notes, Gemini notes, Google Meet notes, import meetings to tracker, auto ingest meetings, meeting inbox, process recordings folder, set up meeting analysis.

Related Skills