Correctless

Composable Claude Code skills that enforce a correctness-oriented development workflow. Spec before you code. Test before you implement. Never let an agent grade its own work.

The Problem

AI coding assistants are fast but sloppy. They write code that works for the happy path, skip edge cases, and silently introduce bugs that don't surface until production. The same model that wrote the code will review it and say "looks good" — because it's confirming its own decisions.

Correctless fixes this by structuring the workflow so that every phase is executed by a different agent with a different lens:

• The spec agent asks "what does correct mean?" and researches current best practices before any code exists
• The review agent reads the spec cold and checks for security gaps, unstated assumptions, and untestable rules
• The test agent writes tests from the spec without knowing the implementation plan
• The test auditor checks whether those tests would actually catch bugs or just pass against mocks
• The implementation agent makes the tests pass without having written them
• The QA agent hunts for bugs with neither the test author's nor the implementer's blind spots
• The verification agent checks spec-to-code correspondence without insider knowledge

Same model — but the framing determines what the agent finds.

Two Versions

Correctless Lite

For web apps, APIs, CLI tools, and everyday development.

/cspec → /creview → /ctdd [RED → test audit → GREEN → /simplify → QA] → /cverify → /cdocs

~10-15 minutes per feature (after initial setup). You get: specs before code with current best practice research, a skeptical review with automatic OWASP security checklist, enforced TDD with test quality audit, verification, and living documentation. First run includes a 17-point project health check that catches hardcoded secrets, missing CI, and security gaps.

Full spec →

Correctless (Full)

For security-critical infrastructure, financial systems, and anything where a bug is a vulnerability.

/cspec → /cmodel → /creview-spec → /ctdd [RED → test audit → GREEN → /simplify → QA] → /cverify → /cupdate-arch → /cdocs → /caudit

~1-2 hours per feature — but the code that ships is tested, reviewed, and has had its assumptions challenged. Everything in Lite plus: formal Alloy modeling, STRIDE threat analysis, 4-agent adversarial spec review, mutation testing, drift debt tracking, postmortem feedback loops, convergence-based audit system, live red team assessment, and devil's advocate analysis.

Full spec →

Which One?

You can upgrade from Lite to Full incrementally. Existing specs, antipatterns, and architecture docs carry over.

Put another way: Lite is like having someone next to you going through a checklist to make sure your project has some sanity. Full is like taking your Claude Max subscription tokens, setting them on fire, collecting the ash, and using it to create a tiny diamond.

Quick Start

You need Claude Code and a Claude Max subscription ($100-200/mo). Not sure which version? See Which One? above.

Via Plugin Marketplace (recommended)

/plugin marketplace add joshft/correctless
/plugin install correctless-lite          # or: /plugin install correctless
/csetup

Via Git Clone (alternative)

git clone https://github.com/joshft/correctless.git .claude/skills/workflow
.claude/skills/workflow/setup
/csetup

Lite mode by default. To enable Full: add "intensity": "standard" (or "high" / "critical") to .claude/workflow-config.json and re-run setup.

After Install

git checkout -b feature/my-feature
/cspec

Updating

Plugin: Claude Code's plugin update doesn't always pull latest. To update reliably (replace correctless with correctless-lite if you installed Lite):

/plugin uninstall correctless              # or: correctless-lite
/plugin marketplace remove correctless
/plugin marketplace add joshft/correctless
/plugin install correctless                # or: correctless-lite

Then restart Claude Code.

Git clone: cd .claude/skills/workflow && git pull && ./setup

How It Works

1. Project Health Check

On first run, /csetup scans your project for baseline hygiene: hardcoded secrets, missing CI, no linter, no tests, committed build artifacts. Produces a health card with 17 checks across security, code quality, testing, CI/CD, documentation, and git hygiene. For existing projects, it mines your codebase for conventions and architecture patterns before asking you to describe them.

2. Spec Before Code

Every feature starts with a spec (/cspec) that defines what "correct" means — testable rules, not vague goals. The spec agent reads your architecture docs, known bug patterns, and QA findings history. When the feature involves libraries or protocols that may have changed, a research subagent searches the web for current docs, CVEs, and deprecations before rules are written.

3. Skeptical Review with Security Checklist

A fresh agent (/creview) that didn't write the spec reads it cold. This includes an automatic security checklist that fires based on what the spec touches — auth, user input, data storage, payments, APIs, multi-tenant. It checks for the vulnerabilities that vibe-coded apps ship with: missing CSRF, SSRF, broken access control, SQL injection, XSS, missing database RLS. In Full, /creview-spec runs a four-agent adversarial team instead.

4. Enforced TDD with Test Audit

/ctdd enforces agent separation: the test agent writes tests from the spec, a test auditor checks test quality, a separate implementation agent makes them pass, and a QA agent reviews both. Hooks block source code edits until tests exist. Every QA finding requires both an instance fix AND a class fix.

5. Verification and Documentation

/cverify checks that the implementation actually satisfies the spec — not just the test cases. /cdocs updates documentation from the verification report. The state machine enforces both steps before merge.

6. The Compounding Effect

After each feature, Correctless learns:

• Antipatterns capture escaped bugs — every future spec and review checks against them
• QA findings accumulate — specs get tailored to avoid recurrent bugs
• CLAUDE.md learnings compound — postmortems, confirmed conventions, and audit patterns are appended to CLAUDE.md and loaded into every future session automatically
• Workflow effectiveness tracks which phases catch what — weak phases get pushed harder

Six months in, the workflow knows your project's failure modes better than any individual developer.

7. Defense in Depth — Why Enforcement is Bash, Not Prompts

Prompt-level instructions ("don't edit source files during QA") fade as context fills. Research shows LLM instruction adherence drops significantly past ~60% context usage. Enforcement that depends on the model following instructions is not enforcement — it's a suggestion.

Correctless uses three layers, each independent of the model's instruction-following:

Layer 1 — Gate (bash, blocking). A PreToolUse hook that runs before every file edit. Returns block or allow. The model cannot write to a source file during QA because the hook physically prevents the write. This is application-level enforcement — the model's compliance is irrelevant.

Layer 2 — Audit trail (bash, observing). A PostToolUse hook that records every file modification with phase context. If a Bash command slips past the gate's pattern detection (e.g., python3 -c "open('file','w')..."), the audit trail catches it after the fact. /cwtf reads the audit trail and reports deviations.

Layer 3 — Skill instructions (prompt-level, advisory). The skill prompt tells the QA agent not to modify source files. This is the weakest layer — subject to context fade. But it's backed by layers 1 and 2, so it doesn't need to be reliable on its own.

Fresh agents per phase provide additional resilience. Each phase transition spawns a new agent with context: fork — starting at 0% context with fresh instructions. A QA agent at 0% context follows its hostile-lens instructions perfectly. A single agent at 70% context may have forgotten it was supposed to be hostile. Agent separation isn't just about confirmation bias — it's about instruction reliability under context pressure.

Skills

Core Workflow

Code Quality

Open Source

Observability

Full Mode Only

Platform Integration

Correctless hooks into Claude Code's infrastructure for real-time feedback and long-term learning. All features below are automatic after /csetup unless marked opt-in.

Statusline (automatic)

The Correctless statusline shows your workflow state at a glance — no commands needed:

project/  feature/auth  Opus  34%  RED  QA:R0  $0.42  +87/-12

Workflow phase (color-coded), QA round count, session cost, lines delta, context usage with red warning at 70%. Installed during /csetup. Both Lite and Full.

Real-Time Adherence Feedback (automatic)

A PostToolUse hook monitors every file modification and alerts you immediately. Lite shows phase violations; Full adds coverage tracking:

• ⚠ tdd-qa: Source file modified — middleware.ts (this phase should be read-only)
• 📝 GREEN: Test file edited — auth.test.ts (should be logged in test-edit-log)
• 🔍 QA: Read middleware.ts (3 of 7 modified files reviewed) (Full mode)

Session Analytics

/cmetrics reads Claude Code's session-meta and facets data for exact token costs, outcome rates, friction analysis, and a Correctless vs Freeform comparison table — measured evidence that the workflow helps.

Compounding Learning

After postmortems, feature completions, and audits, learnings are appended to CLAUDE.md and loaded into every future session automatically. The spec agent just knows that "auth features in this project need middleware ordering checks" without being told.

Git Integration (opt-in)

• Git trailers in commit messages: Spec:, Rules-covered:, Verified-by: — queryable via git log --format='%(trailers:key=Spec)'
• Git notes attaching verification summaries to commits
• Git bisect in /cdebug for automated regression finding

Output Redaction

External-facing skills (/cpr-review, /ccontribute, /cmaintain) automatically redact paths, credentials, hostnames, and session IDs before posting to GitHub/GitLab.

State Management

Check your workflow status with /cstatus or the statusline. For advanced debugging:

.claude/hooks/workflow-advance.sh diagnose "file" # Why a file is blocked
.claude/hooks/workflow-advance.sh override "why"  # Temporary gate bypass (10 tool calls)
.claude/hooks/workflow-advance.sh spec-update "why"  # Spec was wrong mid-TDD
.claude/hooks/workflow-advance.sh reset           # Nuclear — remove all state

Quick Fixes During an Active Workflow

If you need to fix a typo while a workflow is active and the gate is blocking you:

.claude/hooks/workflow-advance.sh override "quick bugfix: fixing typo in error message"

This bypasses the gate for 10 tool calls. Use for: typos, config tweaks, one-line fixes. When no workflow is active, the gate allows all edits freely.

Comparison

Language Support

Mutation testing and PBT helpers are Full-only. Lite works with any language that has a test runner.

Requirements

• Claude Code CLI
• A Claude Max subscription ($100/mo or $200/mo plan). Correctless spawns multiple agents per feature — the $200/mo Max plan is recommended, especially for Full mode.
• A project with a test runner

Optional (Full only):

• Alloy Analyzer for formal modeling
• Mutation testing tool for your language
• Isolated environment (Docker/VPS) for red team assessments

Glossary

Status

Correctless 2.0.0 — Early release. 23 skills (16 Lite, 23 Full), 57 automated tests, 4 hooks (gate, state machine, statusline, audit trail). Real-world usage ongoing — file issues as you find them.

License

MIT