Mastering `cm-quality-gate`: The Complete Guide

In the fast-moving world of Vibe Coding, speed is the ultimate currency. We describe a feature, the AI agent builds it, we preview the result, and—if the “vibe” is right—we ship. It feels like magic until the moment the illusion shatters. You push to production, and suddenly the site is down, a critical environment variable is missing, or the UI looks like a Picasso painting on mobile devices.

The anxiety of shipping AI-generated code is a real psychological barrier. We often find ourselves caught in a “Verification Loop,” manually checking every file, running dev servers, and praying that the agent didn’t accidentally delete a closing div or introduce a breaking type error in an unrelated module.

This is where cm-quality-gate changes the game. It is not just a tool; it is a disciplined architectural philosophy. It is the uncompromising “Gatekeeper” that ensures no code—no matter how good the vibe—ever reaches your main branch without empirical evidence of its correctness. In this guide, we will master the mechanics of the quality gate and learn how to transform your development workflow from “hope-based” to “evidence-based.”

Core Concepts: The Anatomy of a Quality Gate

At its heart, cm-quality-gate solves the “Confidence Gap.” When an AI agent says, “I have fixed the bug,” a human’s natural instinct is to trust but verify. The quality gate automates the “verify” part with extreme prejudice.

It operates on a single, foundational principle: Evidence before Assertions.

In traditional development, we make assertions: “This function works.” In Vibe Coding with cm-quality-gate, we require evidence: “Here is the test output showing the function passing with edge cases A, B, and C.”

The 8 Levels of Verification

A truly robust quality gate isn’t just a linter. It is a multi-layered mesh that catches different types of failures at different stages. The cm-quality-gate skill typically orchestrates these eight distinct gates:

Syntactic Integrity: Does the code actually run? This gate uses linters (ESLint, Ruff, Biome) to catch syntax errors, unused variables, and stylistic violations before they even touch a compiler.
Type Safety: In TypeScript or typed Python environments, this is the “Truth Gate.” It ensures that the data structures the agent imagined actually match the definitions in the codebase.
The Secret Shield: AI agents are notorious for accidentally hardcoding API keys or “mocking” credentials that accidentally make it into a commit. This gate runs tools like Gitleaks or custom regex scanners to block any sensitive data from leaving your machine.
Functional Logic: The Unit and Integration test suite. This gate runs Vitest, Jest, or Pytest to ensure that the logic of the change matches the requirements defined in the planning phase.
Build Artifact Validation: “It works in dev” is the most dangerous phrase in engineering. This gate triggers a production build (e.g., npm run build) to ensure that bundling, tree-shaking, and asset optimization don’t break the application.
Frontend DOM Audit: Using headless browsers like Playwright, this gate verifies that the HTML structure is sound and that critical UI elements are actually rendered and interactive.
I18n & Content Parity: For global applications, this gate ensures that if you added a string in English, it exists (or is correctly keyed) in Spanish, French, and Japanese. It prevents “Missing Translation” keys from appearing in the UI.
SEO & Metadata Compliance: The final check. Does the new page have a Title tag? A Meta Description? Are the OpenGraph tags correct? It ensures the “business vibe” is as good as the “code vibe.”

Practical Example: Shipping a “Contact Us” Feature

Let’s walk through a real-world scenario. You’ve asked your agent to implement a new “Contact Us” form in an Astro-based project. The agent has finished the code. Now, the Quality Gate takes over.

Step 1: The Activation

Instead of just saying “Commit this,” you invoke the gate: Gemini: activate_skill cm-quality-gate

The gate looks at your current changes and identifies the “Risk Surface.” It sees a new .astro file, a new API route in src/pages/api/contact.ts, and a new translation entry in public/i18n/en.json.

Step 2: The Security Scan (Gate 3)

Before running a single test, the gate checks the new API route. It notices the agent left a const SENDGRID_KEY = 'SG.xxx...' in the file for “testing.” The Gate Result: 🛑 FAILURE. Reason: Secret detected in src/pages/api/contact.ts. Execution halted.

The agent is forced to move that key to .env and use process.env.SENDGRID_KEY. This one check just saved you from a compromised production environment.

Step 3: The Type Check (Gate 2)

The agent fixes the secret. The gate runs tsc --noEmit. It finds that the ContactForm component is passing a string to a function that expects a Date object for the “Preferred Callback Time.” The Gate Result: 🛑 FAILURE. Reason: Type mismatch in src/components/ContactForm.tsx:42.

The agent refactors the date handling. The vibe is getting stronger, but the gate is still not satisfied.

Step 4: The Build Smoke Test (Gate 5)

Now the gate runs npm run build. In an Astro project, this is critical. It catches things like “Dynamic route params missing” or “Client-side only library imported without client:only directive.” The build passes. The site is technically “shippable,” but is it correct?

Step 5: Functional Verification (Gate 4)

The gate runs the tests you (or the agent) wrote during the cm-tdd phase.

Test: Should show error if email is invalid. (✅ Pass)
Test: Should show success message after submission. (❌ Fail)

The agent realizes it forgot to clear the form state after a successful fetch call, so the “Success” message was hidden behind the form validation logic.

Step 6: The Final Clearance

The agent fixes the state logic. All tests pass. The build is green. The secrets are gone. The types are strict. The Gate Result: ✅ SUCCESS. Evidence Log: 14 checks passed. 0 warnings. Build artifact verified.

Only now does the gate allow the git commit to proceed. You are no longer “vibe coding”; you are engineering.

Best Practices & Tips for Quality Gate Mastery

To get the most out of cm-quality-gate, you need to treat it as a partner, not a hurdle. Here are the professional standards for managing your gates.

1. The “Zero Warning” Policy

In a Vibe Coding environment, warnings are just “delayed errors.” If your linter has 50 warnings about “missing alt tags,” the AI agent will start ignoring them, and eventually, a critical error will be buried in the noise. Pro Tip: Configure your gate to treat all warnings as errors. Use eslint --max-warnings 0. If it’s not perfect, the gate doesn’t open.

2. Atomic Verification

Don’t wait until a massive feature is done to run the gate. Use the gate after every sub-task. If you are using the cm-execution workflow, the gate should be the final step of every “Act” phase. This prevents “Debugging Debt,” where you have to fix 20 errors at once. It is much easier to fix one type error in one file than to untangle a web of type mismatches across an entire module.

3. Custom Gates: The “Project DNA”

Every project has unique requirements. Maybe your project must have a specific license header in every file. Maybe you have a performance budget where no page can exceed 100kb of JavaScript. Actionable Step: Create a scripts/quality-check.js file and wire it into your cm-quality-gate configuration.

// Example: Custom SEO Check
const fs = require('fs');
const files = fs.readdirSync('./src/pages');
files.forEach(file => {
  const content = fs.readFileSync(`./src/pages/${file}`, 'utf8');
  if (!content.includes('<title>')) {
    console.error(`🛑 Missing Title Tag in ${file}`);
    process.exit(1);
  }
});

4. Evidence Logging

Always ask the agent to provide the “Verification Log” in the final turn. Don’t just accept “It’s done.” Ask for:

“Show me the npm test output.”
“Show me the tsc results.”
“Confirm that .env.example matches the new keys used.”

5. The “Surgical” Fix

When a gate fails, the natural tendency for an AI agent is to “guess” a fix. Best Practice: Instruct the agent to re-read the failing file and the error message carefully before attempting a fix. A failed gate is a signal that the agent’s internal model of the code is slightly out of sync with reality. Re-reading is the synchronization mechanism.

The Psychology of the Gatekeeper: Why it Matters

Why do we put so much effort into these barriers? Because freedom comes from constraints.

When you know that your cm-quality-gate is active, you are free to experiment. You can tell the AI to “Refactor this entire navigation system to use a bento-grid layout” with zero fear. If the refactor breaks a link, the gate catches it. If it messes up the mobile view, the gate catches it.

The quality gate is the safety net that allows you to perform high-wire acts of creativity. Without it, you are just throwing code at a wall and hoping it doesn’t fall down. With it, you are building a fortress.

In the Vibe Coding era, the developers who win aren’t the ones who type the fastest—they are the ones who verify the most rigorously. They are the ones who understand that the “vibe” is the spark, but the “gate” is the engine.

Conclusion: Shipping with Absolute Certainty

cm-quality-gate is the difference between a side project and a production-grade application. It transforms the AI from a slightly erratic collaborator into a precision-guided tool.

By mastering the 8 gates, enforcing a zero-warning policy, and prioritizing empirical evidence over verbal assertions, you eliminate the “Fear of the Push.” You can close your laptop at the end of the day knowing that every line of code on your remote repository has been linted, typed, scanned, tested, and built.

The vibe is the destination. The quality gate is the road. Now, go build something incredible—and make sure the gate stays closed until it’s perfect.