hyperqe

HyperQE

The AI-Native Agentic Quality Engineering Platform.

HyperQE turns your AI coding assistant — Claude Code, Cursor, or GitHub Copilot — into a governed test-automation team. Slash commands drive a gated, evidence-backed delivery lifecycle from manual test case to a merge-ready, self-healing automation suite for Playwright and WebDriverIO.

/hqe-design  →  /hqe-develop  →  /hqe-validate  →  /hqe-deliver

v8.1.0 · 4-phase lifecycle · MIT licensed

---

Table of contents

• Overview
• Standout features
• Architecture
• Installation
• Usage guide
• Best practices

---

Overview

HyperQE is a chat-native orchestration layer: your AI assistant reads its slash command, workflow definition, skill, and gate checklist, then acts as the runtime. There is no separate server or execution engine to run — the IDE chat is the control surface.

What it solves

• Turns manual test cases into traceable automation scripts
• Reuses locators, page objects, waits, and auth flows from a shared pattern bank instead of regenerating them
• Collects evidence at every phase — no gate closes on an empty checklist
• Runs a governed gate review before code merges, with a per-testcase (never batch-wide) approval trail

Built for

Frameworks	Playwright, WebDriverIO, Cucumber/BDD
AI tools	Claude Code, Cursor, GitHub Copilot
MCP adapters	Playwright MCP, WebdriverIO MCP, Appium MCP

---

Standout features

Feature	What it means
Gated 4-phase delivery	Design → Develop → Validate → Deliver, each closing on a checklist-backed gate. Run phase-by-phase or end-to-end with /hqe-generate.
Reusable pattern bank	Locators, page objects, waits, assertions, auth flows, and failure-recovery patterns are searched and reused before anything new is written.
Validate → repair → stabilize loop	A 7-step validation chain (execute, analyze, repair, rerun, stabilize, review, verify) with a 16-category failure taxonomy driving automatic repair routing.
Ongoing regression operation	/hqe-regression-run classifies failures as flaky / script-defect / app-defect, auto-repairs script issues, quarantines chronic flake, and escalates app defects.
Live orchestration dashboard	A real-time, live-tail dashboard (SSE, no polling) visualizes the 4-phase pipeline, renders gate evidence in human-readable form, and lets you Approve/Reject per test case from the UI.
Cross-provider command parity	Every slash command is available natively in Claude Code, Cursor, and GitHub Copilot — same workflow, same skill, same gate.
Real MCP-driven exploration	/explore-ui and /explore-mobile call live Playwright / WebDriverIO / Appium MCP tools for real locator evidence — never a fabricated description of the page.
Schema-checked evidence	Every artifact — design, development, validation, delivery reports, pattern-bank entries — validates against a JSON Schema, not just prose self-attestation.
One-command install	The entire engine lives in a single .hyperqe/ folder. Installing the package seeds it plus each tool's integration files automatically via a postinstall hook.
Reuse across deliveries, not just within one	Design cites a prior delivery's own live-probe evidence and page objects when it genuinely still applies, instead of re-exploring the same page from scratch; develop reuses/extends existing automation assets step-by-step (stepReuse[] makes the reuse rate auditable, not anecdotal).
Batch mode across phases	Design, develop, and validate can each process 2+ related deliveries sharing the same app area in one session, amortizing the fixed setup cost (pattern-bank search, layout discovery, framework init) across all of them instead of paying it per delivery.
Optimized end-to-end runs	/hqe-generate runs all 4 phases in one continuous session by default instead of isolating each into its own subagent — measured ~24% cheaper and ~37% faster on a real like-for-like comparison, since it avoids re-discovering the same reference docs from scratch at every phase boundary.
Real token/cost visibility (Claude Code)	.hyperqe/scripts/token-cost-summary.mjs reads the session's own local transcript to report actual token usage, model, and cost after a command — ground truth from the API's own usage data, not an estimate.

---

Architecture

HyperQE has no background service. The AI agent in your chat is the runtime: it resolves a command down to a workflow, skill, playbook, and gate — then acts, using MCP tools for any live UI/mobile evidence it needs.

You type a slash command in chat
            │
            ▼
command-registry.json → workflow-registry.json → *.workflow.json
            │
            ▼
skills/*/SKILL.md + playbooks/*.md + gate-checklists.json
            │
            ▼
.hqe/memory/ + .hqe/artifacts/ + MCP tools (live browser/mobile evidence)

One engine folder, three integration surfaces

All engine content — commands, workflows, skills, playbooks, agents, pattern bank, schemas, scripts — lives under a single .hyperqe/ folder, so bootstrapping a project adds one top-level folder, not fifteen. Each AI tool still auto-discovers its own config from its fixed, non-negotiable root path — those three surfaces cannot move into .hyperqe/, so they stay at the project root as thin pointers into the engine.

Tool	Auto-discovered path	What it holds
Claude Code	.claude/commands/*.md, .claude/agents/*.agent.md, .mcp.json, .claude/settings.json	20 slash commands, 6 subagent personas, MCP servers, a PostToolUse hook that logs artifact writes automatically
Cursor	.cursor/skills/*/SKILL.md, .cursor/rules/*.mdc, .cursor/mcp.json	20 Skills (current, non-deprecated slash-command mechanism), an always-on bootstrap rule, MCP servers
GitHub Copilot	.github/copilot-instructions.md, .github/prompts/*.prompt.md, .vscode/mcp.json, root AGENTS.md	Auto-read repo instructions, 20 prompt files (VS Code Copilot Chat), MCP servers

Pick any one of the three tools and the same workflow, the same gate, and the same pattern bank apply — teammates on different tools stay on one source of truth instead of three forks of the process.

---

Installation

HyperQE is published on the npm registry — one command is enough:

npm install hyperqe

A postinstall hook seeds .hyperqe/ plus the .claude/, .cursor/, .codex/, .github/, .vscode/mcp.json, .mcp.json, and root AGENTS.md integration files into your project automatically. Existing files in your project are never overwritten.

Then:

npx hqe doctor              # verify the seeded layout (10 checks)
/init-playwright             # or /init-wdio — optional, only if no framework exists yet
/hqe-design                  # start your first delivery from a manual test case

CLI reference

Command	What it does
hqe bootstrap [--full] [--target <dir>]	(Re-)seed HyperQE into a project — same logic the postinstall hook runs
hqe doctor [--target <dir>]	Verify a seeded project's layout is intact (engine folder, tool integrations, MCP config)
hqe --version	Print the installed HyperQE version
hqe help	Show CLI usage

The CLI is supplementary, not the primary interface — it only covers what doesn't belong in a chat turn (seeding files, a local health check). The actual QE workflow always runs through slash commands in your AI tool's chat.

---

Usage guide

Core lifecycle (gated, per-delivery)

Command	Phase	Gate
/hqe-design	Testcase analysis, feasibility, reuse search (this delivery, prior deliveries, and the pattern bank), automation design — with mandatory live MCP UI exploration. Batchable across 2+ related test cases.	Design Gate
/hqe-develop	Create/update page objects, locators, helpers (reused/extended before anything new is generated, per-step); generate the script; run an initial smoke pass. Batchable across 2+ deliveries sharing an app area.	Development Gate
/hqe-validate	Execute → analyze → repair → rerun → stabilize → review → verify, in one composite step chain. Real-run count scales to risk (fewer repeats for read-only/already-proven scripts, never fewer for a first-time mutating test). Batchable across 2+ deliveries.	Validation Gate
/hqe-deliver	Aggregate results, confirm manual-TC → script traceability, decide merge readiness via a fixed, literal threshold procedure — never a per-delivery judgment call	Delivery Gate
/hqe-generate	Orchestrates all four phases end-to-end, gate by gate, in one continuous session by default (see Standout features)	Design Gate (start)

Gate decisions — always scoped to one test case

Command	Effect
/approve	Approve — pass the current gate for this delivery
/rework <reason>	Send the current phase back for rework, with a reason on record
/reject <reason>	Hard reject — blocks delivery
/skip-gate <reason>	Skip a non-mandatory gate, with the risk explicitly recorded
/escalate <target>	Escalate to an owner — required for gates that cannot be skipped

Every decision names one specific delivery/test case — there is no shared "batch" approval.

Independent utilities (no phase gate, run any time)

Command	Purpose
/gen-test	Fast path — generate one runnable spec from a manual case with minimal ceremony; feeds back into /hqe-develop//hqe-validate later if promoted to full delivery
/hqe-regression-run	Ongoing regression operation — classify, auto-repair, quarantine, escalate; produces a PROCEED / BLOCK / DEFER recommendation for CI
/create-defect	Record a confirmed app defect found during validate/regression
/fix-selector	Repair a broken selector using live MCP evidence, then re-run affected tests
/explore-ui / /explore-mobile	Live MCP exploration — capture real locator candidates and stability risk
/status / /help	Show current workflow status / list all commands

---

Best practices

• Keep gate review honest. Leave .hyperqe/hqe.config.json → gates.reviewEnabled: true for anything merging to a shared branch. Turning it off still runs the checklist and writes evidence — it just stops blocking on human approval — so it's a real config decision, not a shortcut.
• Search before you generate. Let /hqe-design's reuse search run before writing new locators, page objects, or auth flows. The pattern bank only stays useful if new patterns get contributed back and stale ones get pruned.
• Treat validation failures as signal. A validation failure must trigger the repair → rerun → stabilize loop — never a manual patch outside the workflow. This keeps the 16-category failure taxonomy accurate over time.
• Quarantine flaky tests, don't silence them. /hqe-regression-run quarantines chronically flaky tests instead of deleting or ignoring them — flaky ≠ broken, and quarantine keeps the signal visible for later stabilization work.
• Watch the orchestration dashboard during a delivery. Run npm run orchestration-dashboard alongside a delivery to see the live pipeline, review gate evidence in human-readable form, and approve/reject per test case without leaving the browser.
• Don't fork the process per tool. Commands, workflows, and gates behave identically across Claude Code, Cursor, and Copilot — that parity is the reason to keep using native slash commands instead of ad-hoc prompts when a team mixes tools.
• Batch related deliveries when you have them. If 2+ test cases target the same app area, run /hqe-design, /hqe-develop, or /hqe-validate for them together instead of one at a time — the fixed setup cost (pattern-bank search, layout discovery, framework init) is paid once for the batch instead of once per delivery.
• Watch your token cost (Claude Code). Run node .hyperqe/scripts/token-cost-summary.mjs --pretty after a command to see real token usage, model, and estimated cost from the session's own transcript — useful for spotting a command that's taking unexpectedly long or many turns before it becomes a habit.
• Validate artifacts, not just tests. Run npm run validate:artifacts periodically — it schema-checks every JSON artifact and pattern-bank entry, catching drift a green test run alone won't surface.
• Keep traceability real. Every automation script should trace back to the manual test case it came from. /hqe-deliver checks this before recommending merge.

---

See AGENTS.md and .hyperqe/BOOTSTRAP_RULE.md for the full operating rules, and docs/hyperqe-overview.html for the same content as an interactive page.

License: MIT — see LICENSE.