Skip to main content
skill CX Codex

quality-gates — Claude Code skill: what it does, how to install

quality-gates scores task complexity on a 1–5 scale and halts work when requirements are vague or solutions loop. Triggers before complex tasks and after repeated failures.

MIT 259 installs ★ 305 updated 2026-11-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill quality-gates -a claude-code
Open on GitHub

What quality-gates does

This skill equips coding agents with a structured pre-execution assessment. Complexity is graded from Level 1 (under 50 lines, single file) up to Level 5 (1500+ lines, multiple unknowns). The grade uses the maximum metric across file counts, line numbers, dependencies, and unknowns rather than an average.

Execution stops when safety rules trip. If planned lines of code exceed the architecture tier budget by more than 2.0x, the YAGNI gate halts the run until simpler alternatives are proposed, though security patterns remain exempt. The skill also enforces a hard stop after three failed attempts or more than three unanswered questions, generating a standardized escalation summary instead of burning tokens.

Setup requires Claude Code 2.1.277 or newer. During file operations, a PreToolUse hook on Read loads the quality-baseline-loader script to verify standards before edits begin.

What it helps with

  • prevent agent token loops after multiple failed fix attempts
  • score task complexity using strict multi-axis criteria
  • block over-engineered solutions before code generation starts
  • escalate unresolved architecture dependencies and missing specs

Example prompts for the agent

  • Assess complexity for the upcoming billing module migration before writing code
  • Run a quality gate check on this task and surface any unanswered questions
  • Generate an escalation report for the failed database migration attempts

How to install quality-gates

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill quality-gates -a claude-code

2Manually: put the files in place

~/.claude/skills/quality-gates/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/quality-gates/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about quality-gates

How to install quality-gates in Claude Code?

Run npx skills add yonatangross/orchestkit --skill quality-gates -a claude-code in your terminal. The configuration installs to ~/.claude/skills/quality-gates/SKILL.md.

What does quality-gates do?

It applies quality gates to agent planning: calculates 1–5 task complexity, blocks over-engineering via YAGNI checks, and escalates to the user after three failed attempts.

What version of Claude Code is required?

The skill requires Claude Code 2.1.277 or higher, with access to Read, Glob, Grep, WebFetch, and WebSearch tools.

Source text

SKILL.md · MIT
---
name: quality-gates
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Task complexity scoring (1-5), escalation when stuck, and best-practice checks. Use before complex tasks or after repeated failed attempts."
skills: [scope-appropriate-architecture]
user-invocable: false
disable-model-invocation: false
effort: high
hooks:
  PreToolUse:
    - matcher: "Read"
      hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs skill/quality-baseline-loader"
          once: true
metadata:
  owner-agent: "code-quality-reviewer"
  category: document-asset-creation
  version: "1.3.0"
  author: "OrchestKit"
  complexity: "max"
  tags: "quality, complexity, planning, escalation, blocking, best-practices, patterns, yagni, over-engineering"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
---

# Quality Gates

This skill teaches agents how to assess task complexity, enforce quality gates, and prevent wasted work on incomplete or poorly-defined tasks.

**Key Principle:** Stop and clarify before proceeding with incomplete information. Better to ask questions than to waste cycles on the wrong solution.

---

## Overview

### Auto-Activate Triggers
- Receiving a new task assignment
- Starting a complex feature implementation
- Before allocating work in Squad mode
- When requirements seem unclear or incomplete
- After 3 failed attempts at the same task
- When blocked by dependencies

### Manual Activation
- User asks for complexity assessment
- Planning a multi-step project
- Before committing to a timeline

---

## Core Concepts

### Complexity Scoring (1-5 Scale)

| Level | Files | Lines | Time | Characteristics |
|-------|-------|-------|------|-----------------|
| 1 - Trivial | 1 | < 50 | < 30 min | No deps, no unknowns |
| 2 - Simple | 1-3 | 50-200 | 30 min - 2 hr | 0-1 deps, minimal unknowns |
| 3 - Moderate | 3-10 | 200-500 | 2-8 hr | 2-3 deps, some unknowns |
| 4 - Complex | 10-25 | 500-1500 | 8-24 hr | 4-6 deps, significant unknowns |
| 5 - Very Complex | 25+ | 1500+ | 24+ hr | 7+ deps, many unknowns |

The table above is the canonical rubric. Score with `max(file_count, LOC, dependency_count, unknowns)`, not an average: one Level 5 axis makes the task Level 5. Run `scripts/assess-complexity.md` or `scripts/analyze-codebase.sh <target>` to measure the inputs.

### Blocking Thresholds

| Condition | Threshold | Action |
|-----------|-----------|--------|
| **YAGNI Gate** | **Justified ratio > 2.0** | **BLOCK with simpler alternatives** |
| YAGNI Warning | Justified ratio 1.5-2.0 | WARN with simpler alternatives |
| Critical Questions | > 3 unanswered | BLOCK |
| Missing Dependencies | Any blocking | BLOCK |
| Failed Attempts | >= 3 | BLOCK & ESCALATE |
| Evidence Failure | 2 fix attempts | BLOCK |
| Complexity Overflow | Level 4-5 no plan | BLOCK |

**WARNING Conditions** (proceed with caution):
- Level 3 complexity
- 1-2 unanswered questions
- 1-2 failed attempts

The escalation protocol and gate decision logic are both in "Quick Reference" below. The YAGNI ratio, tier LOC budgets, and simpler-alternative surfacing live in `rules/yagni-gate.md`.

---

## References

Load on demand with `Read("references/<file>")`:
| File | Content |
|------|---------|
| `ork-delta.md` | OrchestKit-specific scars and house decisions: line-counting correctness, fail-open policy, gate self-monitoring, non-bypassable categories |
| `unified-scoring-framework.md` | Canonical 0-10 dimensions, weights, grade thresholds, improvement prioritization. Also loaded by `ork:assess` and `ork:verify` |

---

## Upstream coverage (do not restate)

This skill wraps generic quality-gate practice and keeps only the OrchestKit delta. When one of these topics comes up, go to the source instead of re-teaching it here.

| Topic | Source |
|-------|--------|
| Complexity 1-5 rubric, per-level examples, assessment formula | "Complexity Scoring" table above, canonical |
| BLOCKING vs WARNING conditions, escalation protocol, attempt tracking | "Blocking Thresholds" and "Quick Reference" above, canonical |
| YAGNI ratio, project tier LOC budgets, simpler alternatives | `rules/yagni-gate.md` + `ork:scope-appropriate-architecture` |
| Score dimensions, weights, grade thresholds | `references/unified-scoring-framework.md` |
| LLM-as-judge, G-Eval, aspect scoring, metric APIs | `ork:testing-llm` |
| Requirements completeness, acceptance criteria templates | `ork:write-prd` |
| Test standards enforced as part of a gate | `ork:architecture-patterns` |
| Repo metrics for a gate input (files, LOC, tests, churn) | `scripts/analyze-codebase.sh` in this skill |
| LangGraph conditional routing for a gate node | https://langchain-ai.github.io/langgraph/ |
| FastAPI error responses for a failed gate | https://fastapi.tiangolo.com/tutorial/handling-errors/ |
| Pydantic validators for gate output schemas | https://docs.pydantic.dev/latest/concepts/validators/ |
| Retry with exponential backoff, SLO-based alerting on gates | https://sre.google/workbook/alerting-on-slos/ |

---

## Quick Reference

### Gate Decision Flow

```
0. YAGNI check (runs FIRST — before any implementation planning)
   → Read project tier from scope-appropriate-architecture
   → Calculate justified_complexity = planned_LOC / tier_appropriate_LOC
   → If ratio > 2.0: BLOCK (must simplify)
   → If ratio 1.5-2.0: WARN (present simpler alternative)
   → Security patterns exempt from YAGNI gate

1. Assess complexity (1-5)
2. Count critical questions unanswered
3. Check dependencies blocked
4. Check attempt count

if (yagni_ratio > 2.0) -> BLOCK with simpler alternatives
else if (questions > 3 || deps blocked || attempts >= 3) -> BLOCK
else if (complexity >= 4 && no plan) -> BLOCK
else if (yagni_ratio > 1.5 || complexity == 3 || questions 1-2) -> WARNING
else -> PASS
```

### Gate Check Template

```markdown
## Quality Gate: [Task Name]

**Complexity:** Level [1-5]
**Unanswered Critical Questions:** [Count]
**Blocked Dependencies:** [List or None]
**Failed Attempts:** [Count]

**Status:** PASS / WARNING / BLOCKED
**Can Proceed:** Yes / No
```

### Escalation Template

```markdown
## Escalation: Task Blocked

**Task:** [Description]
**Block Type:** [Critical Questions / Dependencies / Stuck / Evidence]
**Attempts:** [Count]

### What Was Tried
1. [Approach 1] - Failed: [Reason]
2. [Approach 2] - Failed: [Reason]

### Need Guidance On
- [Specific question]

**Recommendation:** [Suggested action]
```

---

## Integration with Context System

```javascript
// Add gate check to context
context.quality_gates = context.quality_gates || [];
context.quality_gates.push({
  task_id: taskId,
  timestamp: new Date().toISOString(),
  complexity_score: 3,
  gate_status: 'pass', // pass, warning, blocked
  critical_questions_count: 1,
  unanswered_questions: 1,
  dependencies_blocked: 0,
  attempt_count: 0,
  can_proceed: true
});
```

## Integration with Evidence System

```javascript
// Before marking task complete
const evidence = context.quality_evidence;
const hasPassingEvidence = (
  evidence?.tests?.exit_code === 0 ||
  evidence?.build?.exit_code === 0
);

if (!hasPassingEvidence) {
  return { gate_status: 'blocked', reason: 'no_passing_evidence' };
}
```

---

## Best Practices Pattern Library

Track success/failure patterns across projects to prevent repeating mistakes and proactively warn during code reviews.

| Rule | File | Key Pattern |
|------|------|-------------|
| YAGNI Gate | `rules/yagni-gate.md` | Pre-implementation scope check, justified complexity ratio, simpler alternatives |
| Pattern Library | `rules/practices-code-standards.md` | Success/failure tracking, confidence scoring, memory integration |
| Review Checklist | `rules/practices-review-checklist.md` | Category-based review, proactive anti-pattern detection |

### Pattern Confidence Levels

| Level | Meaning | Action |
|-------|---------|--------|
| Strong success | 3+ projects, 100% success | Always recommend |
| Mixed results | Both successes and failures | Context-dependent |
| Strong anti-pattern | 3+ projects, all failed | Block with explanation |

---

## Common Pitfalls

| Pitfall | Problem | Solution |
|---------|---------|----------|
| Skip gates for "simple" tasks | Get stuck later | Always run gate check |
| Ignore WARNING status | Undocumented assumptions cause issues | Document every assumption |
| Not tracking attempts | Waste cycles on same approach | Track every attempt, escalate at 3 |
| Proceed when BLOCKED | Build wrong solution | NEVER bypass BLOCKED gates |

---

---

## Related Skills

- `ork:scope-appropriate-architecture` - Project tier detection that feeds YAGNI gate
- `ork:architecture-patterns` - Enforce testing standards as part of quality gates
- `ork:testing-llm` - LLM-as-judge patterns for quality validation (DeepEval, RAGAS)
- `ork-extras:golden-dataset` - Validate datasets meet quality thresholds

## Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Complexity Scale | 1-5 levels | Granular enough for estimation, simple enough for quick assessment |
| Block Threshold | 3 critical questions | Prevents proceeding with too many unknowns |
| Escalation Trigger | 3 failed attempts | Balances persistence with avoiding wasted cycles |
| Level 4-5 Requirement | Plan required | Complex tasks need upfront decomposition |

## Capability Details

### complexity-scoring
**Keywords:** complexity, score, difficulty, estimate, sizing, 1-5 scale
**Solves:** How complex is this task? Score task complexity on 1-5 scale, assess implementation difficulty

### blocking-thresholds
**Keywords:** blocking, threshold, gate, stop, escalate, cannot proceed
**Solves:** When should I block progress? >3 critical questions = BLOCK, Missing dependencies = BLOCK

### critical-questions
**Keywords:** critical questions, unanswered, unknowns, clarify
**Solves:** What are critical questions? Count unanswered, block if >3

### stuck-detection
**Keywords:** stuck, failed attempts, retry, 3 attempts, escalate
**Solves:** How do I detect when stuck? After 3 failed attempts, escalate

### gate-validation
**Keywords:** validate, gate check, pass, fail, gate status
**Solves:** How do I validate quality gates? Run pre-task gate validation

### pre-task-gate-check
**Keywords:** pre-task, before starting, can proceed
**Solves:** How do I check gates before starting? Assess complexity, identify blockers

### complexity-breakdown
**Keywords:** breakdown, decompose, subtasks, split task
**Solves:** How do I break down complex tasks? Split Level 4-5 into Level 1-3 subtasks

### requirements-completeness
**Keywords:** requirements, incomplete, acceptance criteria
**Solves:** Gate check only: is the requirement set complete enough to start? Authoring the requirements themselves belongs to `ork:write-prd` (see Upstream coverage)

### escalation-protocol
**Keywords:** escalate, ask user, need help, human guidance
**Solves:** When and how to escalate? Escalate after 3 failed attempts

### llm-as-judge
**Keywords:** llm as judge, g-eval, aspect scoring, quality validation
**Solves:** Gate thresholds only: what score must a judge return to pass? Building and running the judge belongs to `ork:testing-llm` (see Upstream coverage)

### yagni-gate
**Keywords:** yagni, over-engineering, justified complexity, scope check, too complex, simplify
**Solves:** Is this complexity justified? Calculate justified_complexity ratio against project tier, BLOCK if > 2.0, surface simpler alternatives

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set86

The whole set →
write-prd write-prd generates 8-section product requirements documents with INVEST user stories, acceptance criteria, and go/no-go gates. Writes the final specification to PRD-[product-name].md. CX Codex +1 336installs distributed-systems distributed-systems is a Claude Code skill with architectural guidelines for distributed locks, circuit breakers, idempotency keys, and rate limiting. CX Codex +1 297installs monitoring-observability monitoring-observability — a skill for Claude Code that configures Prometheus metrics, Grafana dashboards, and Langfuse v4 tracing. Activates when adding logging, distributed tracing, or LLM cost tracking. CX Codex +1 270installs vite-advanced vite-advanced is a Claude Code and Codex skill for Vite 8 builds with Rolldown, chunk splitting, and Environment API. It activates when editing vite.config.* or files under **/vite/**. CX Codex +1 265installs code-review-playbook code-review-playbook supplies structured review workflows, conventional comment formats, and security checklists. Triggers during pull request evaluations or author self-reviews. CX Codex +1 254installs python-backend python-backend — a skill for Claude Code and Codex providing async Python patterns when editing *.py or package files. Enforces conventions for FastAPI, SQLAlchemy 2.0, and asyncio. CX Codex +1 250installs accessibility accessibility — a Claude Code skill for building accessible web interfaces. It activates for work on screen reader support, keyboard navigation, focus handling, and ARIA components. CX Codex +1 246installs memory-fabric memory-fabric is a Claude Code skill that orchestrates knowledge graph retrieval, parses queries, deduplicates facts, and ranks results. It runs when designing or debugging agent memory mechanics. CX Codex +1 244installs

Project sponsors

Companies that keep this analytics open