using-quality-gates

name	using-quality-gates
description	Quality Gates workflow for Claude Code. Use when editing code in projects with quality enforcement. Covers the full cycle: TDD guard (write failing test first) → implement → auto-lint/typecheck. Activates on code edits, quality issues, or when user asks about testing/linting workflow.

Using Quality Gates

Quality Gates provides automated code quality enforcement through PostToolUse hooks:

1. TypeScript Quality Gate — Runs after TS/JS edits: TypeScript + ESLint + Prettier
2. Python Quality Gate — Runs after Python edits: Ruff + Mypy

Separate Installation Required for TDD:

• TDD Guard is a separate tool (not included) — See "TDD Guard Setup" below

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│  QUALITY GATES (this skill)                                     │
│  ─────────────────────────────                                  │
│  PostToolUse Hooks (installed by this skill):                   │
│  • .xtrm/hooks/quality-check.cjs  → TS/JS files              │
│  • .xtrm/hooks/quality-check.py   → Python files             │
│  • .claude/settings.json            → Hook registration        │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  TDD GUARD (separate installation)                              │
│  ───────────────────────────────────                            │
│  PreToolUse Hook (requires xtrm install project tdd-guard):    │
│  • Global CLI: npm install -g tdd-guard                        │
│  • Test reporter: tdd-guard-vitest / tdd-guard-pytest / etc.   │
│  • Hook: .claude/hooks/tdd-guard-pretool-bridge.cjs            │
└─────────────────────────────────────────────────────────────────┘

Installation

Step 1: Install This Skill

xtrm install project quality-gates

This installs:

• .claude/hooks/quality-check.cjs — TypeScript/JavaScript checks
• .claude/hooks/quality-check.py — Python checks
• .claude/settings.json — PostToolUse hook registration
• .claude/skills/using-quality-gates/ — This documentation

Step 2: Install Language Dependencies

TypeScript Projects:

npm install --save-dev typescript eslint prettier

Python Projects:

pip install ruff mypy

Step 3: (Optional) Install TDD Guard

For test-first enforcement, install TDD Guard separately:

# 1. Install global CLI
npm install -g tdd-guard

# 2. Install project-skill for hook wiring
xtrm install project tdd-guard

# 3. Install test reporter (choose one)
npm install --save-dev tdd-guard-vitest    # Vitest
npm install --save-dev tdd-guard-jest      # Jest
pip install tdd-guard-pytest               # pytest

Configure test reporter (see https://github.com/nizos/tdd-guard):

Vitest:

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import { VitestReporter } from 'tdd-guard-vitest'

export default defineConfig({
  test: {
    reporters: ['default', new VitestReporter('/path/to/project')],
  },
})

pytest:

# pyproject.toml
[tool.pytest.ini_options]
tdd_guard_project_root = "/path/to/project"

How Quality Gates Work

TypeScript Quality Gate (PostToolUse)

Runs after: Every .ts, .tsx, .js, .jsx file edit

Checks:

1. TypeScript compilation (type errors)
2. ESLint validation (style, best practices)
3. Prettier formatting (consistency)

Configuration (.claude/hooks/hook-config.json):

{
  "typescript": { "enabled": true, "showDependencyErrors": false },
  "eslint": { "enabled": true, "autofix": true },
  "prettier": { "enabled": true, "autofix": true },
  "general": { "autofixSilent": true }
}

Python Quality Gate (PostToolUse)

Runs after: Every .py file edit

Checks:

1. Ruff linting (errors, style, best practices)
2. Ruff formatting (Black-compatible)
3. Mypy type checking (static types)

Configuration (environment variables):

CLAUDE_HOOKS_RUFF_ENABLED=true
CLAUDE_HOOKS_MYPY_ENABLED=true
CLAUDE_HOOKS_AUTOFIX=true

Exit Codes

Code	Meaning	Action
0	All checks passed	Continue
1	Fatal error (missing deps)	Install missing tool
2	Blocking errors	Claude must fix

Handling Quality Gate Errors

When blocked with exit code 2:

1. Read the error output — Specific issues listed
2. Auto-fix applies automatically — ESLint/Prettier/Ruff fix what they can
3. Fix remaining issues manually — Type errors, complex violations
4. Gate re-runs on next edit — No manual trigger needed

Example:

[ERROR] TypeScript compilation failed:
  src/auth.ts:42:5 - error TS2322: Type 'string' is not assignable to type 'number'

[WARN] Auto-fix applied: 2 issues fixed
[BLOCK] 1 issue remains - fix before continuing

TDD Guard Integration

When TDD Guard is installed alongside Quality Gates:

User Request: "Add feature X"
        ↓
┌───────────────────────────────────┐
│ TDD Guard (PreToolUse)            │
│ Checks: Failing test exists?      │
│ • NO → BLOCK: "Write test first"  │
│ • YES → Allow implementation      │
└───────────────────────────────────┘
        ↓
Implementation (Write/Edit)
        ↓
┌───────────────────────────────────┐
│ Quality Gates (PostToolUse)       │
│ Runs: Lint + Typecheck + Format   │
│ • Errors → BLOCK, fix issues      │
│ • Pass → Continue                 │
└───────────────────────────────────┘
        ↓
Tests pass → Commit

Troubleshooting

"ESLint not found" / "Prettier not found"

npm install --save-dev eslint prettier

"Ruff not found" / "Mypy not found"

pip install ruff mypy

"tdd-guard: command not found"

npm install -g tdd-guard

"TDD Guard: No failing test found"

• Write a failing test first
• Ensure test reporter is configured
• Run tests to generate reporter JSON

Hook not running

• Verify .claude/settings.json exists
• Check hook script paths are correct
• Ensure file extension matches (.ts/.py)

When This Skill Activates

Triggers:

• Quality gate reports errors
• User asks about linting, type checking, or quality workflow
• Session starts in a project with quality gates installed

Response Modes:

Full Workflow Mode (user mentions quality/testing, blocked by gate errors):

• Explain complete quality pipeline
• Provide troubleshooting guidance

Minimal Mode (general coding tasks without quality context):

• Complete the task directly
• Brief note: "Consider adding tests. If TDD Guard is installed, write failing test first."

Files Installed

.claude/
├── settings.json              # PostToolUse hook registration
├── hooks/
│   ├── quality-check.cjs      # TypeScript/JavaScript checks
│   ├── quality-check.py       # Python checks
│   └── hook-config.json       # TS hook configuration
├── skills/
│   └── using-quality-gates/   # This skill
└── docs/
    └── quality-gates-readme.md

Related

• TDD Guard: https://github.com/nizos/tdd-guard
• xtrm install project tdd-guard: Install TDD Guard hooks