Code Polishy

One policy for all your repos. Deterministic constraints agents can't ignore.

Code Polishy gives every coding agent the same definition of done and enforces it before code merges.

What it does

Code Polishy keeps today's agent code from becoming tomorrow's cleanup.

• Stops agents from tangling parts of your codebase together.
• Flags giant files and hard-to-follow functions before they become expensive to change.
• Makes "done" include the tests, builds, and project checks your repo requires.
• Protects your software supply chain from surprise dependency changes and known vulnerabilities.
• Shows where repository space goes and what caused its growth.

Agents catch problems while the change is still fresh, and one final gate stops unresolved issues before merge.

For sensitive changes, an optional experimental behavior review can compare the result with the user's request.

How it works

Set it up

Setup starts with one prompt to a coding agent:

Set up Code Polishy in this repository. Follow
https://github.com/riteofstring/code-polishy.

Each repo keeps its current Code Polishy version until you choose to upgrade. A new setup uses the latest stable version tag. Ask for a tag such as v1.2.3 when you need a specific version.

Git is required. Allow about 1 GB of disk space. Windows x64 works without WSL or Git Bash.

See the agent setup guide or the manual setup guide for the full process.

How agents use it

A coding agent reads the workflow bundled with the repo's locked release, starts a scoped task, checks the change, and runs the final gate at a merge checkpoint:

# Read the version-matched workflow
code-polishy docs read agent-workflows

# Start a scoped task
code-polishy task-start --module MODULE

# Check the code you changed
code-polishy test --changed

# Review dependency risk before accepting an update
code-polishy dependency-review --base origin/main

# Enforce the policy at a merge checkpoint
code-polishy merge-gate --base origin/main

The locked agent workflow covers long-lived branch checkpoints, behavior review, failed-gate recovery, and CI evidence transfer.

Languages

Code Polishy keeps its built-in tools fixed until you upgrade, so local and CI checks stay consistent. Built-in support covers Go, JavaScript, TypeScript, Python, and shell scripts.

• Go, JavaScript, and TypeScript: Formats code and catches likely bugs, type errors, unused code, and overly complex functions. Locked dependencies are checked for known vulnerabilities.
• Python: Formats and lints each contained project, then checks complexity, dead code, types, module direction, and locked dependencies.
• Shell scripts: Catches syntax errors and common safety problems.

Code Polishy also rejects empty Go tests and obvious test commands that can pass without running tests. Optional mutation testing can provide deeper proof.

Other languages can use reviewed language packs or repo-owned checks. Code Polishy runs and enforces them but does not supply their tools.

What stays in your repo

Four checked-in files keep every agent aligned:

• .code-polishy.lock.json keeps the policy and tools stable until you choose to upgrade.
• .code-polishy.json describes your code boundaries, tests, commands, and exceptions once.
• AGENTS.md gives every coding agent the same operating instructions.
• CLAUDE.md imports those instructions for Claude Code.

Your prompts can stay focused on what you want built.

More

• All docs
• Agent workflows
• Repository size
• Architecture rules
• Test rules
• Dependency rules

Apache-2.0 licensed. See LICENSE.