# HyperQE Agent Instructions

This repository uses HyperQE (HQE), an AI-Native Agentic Quality Engineering Platform.
Bootstrap policy is defined in `.hyperqe/BOOTSTRAP_RULE.md` and must be enforced.

## Primary control surface: chat (Cursor, Claude Code & GitHub Copilot)

Users normally issue **slash commands in the IDE chat** (`/hqe-design`, `/explore-ui`, `/approve`, …), not the system shell. This applies equally to GitHub Copilot: per GitHub's supported repository-instruction formats, Copilot auto-reads this root `AGENTS.md` (alongside `.github/copilot-instructions.md`) on every chat/agent request — the chat-native orchestration model below is not Cursor/Claude-Code-specific.

## Language

Unless the user explicitly requests another language, **respond in English** (Cursor, Claude Code, and GitHub Copilot). Quoted or pasted material may stay in its source language.

When the user types a HyperQE slash command in chat, you are the **runtime**:

1. Resolve intent via `.hyperqe/commands/command-registry.json` and `.hyperqe/core/orchestration/workflow-registry.json` → **`workflowDefinitions`**: every workflow id maps to a **string path** under `.hyperqe/core/workflows/<id>.workflow.json`. Open that file for `steps`, optional `playbook`, `assignedAgent`, `phases`, gates, and artifacts.
2. Load mapped **skills** (`.hyperqe/skills/*/SKILL.md`), the workflow's **`assignedAgent`** file (`.hyperqe/agents/*.md` — inputs/outputs/blocking/stop conditions for that phase) when present, and stage **playbooks** (`.hyperqe/playbooks/*.md`).
3. Read **`.hyperqe/hqe.config.json` → `gates.reviewEnabled`** (default `true` if omitted). If **`true`**: enforce **gate** checklists and do not bypass gates without explicit user risk acceptance. If **`false`**: still complete gate checklists as quality evidence, but **do not block** handoff on `/approve`; document in the phase artifact or `design-summary.md` (etc.) that gate human review was **skipped by config** (include date).
4. If `gates.reviewEnabled` is **`true`**: continue only after explicit user approval actions (`/approve`, `/rework`, …) when the workflow gate requires it. If **`false`**, proceed when artifacts and checklists are satisfied, and log the bypass as above.
5. Produce delivery entities under **`.hqe/memory/`** (`memoryRoot` in `.hyperqe/hqe.config.json`) and phase handoff JSON under **`.hqe/artifacts/`**, matching `.hyperqe/core/schemas/` when applicable. Add **optional human-review Markdown** companions listed in `.hyperqe/core/lifecycle/human-review-artifacts.json` (under `.hqe/artifacts/`; not a substitute for JSON gates).
6. For **MCP-backed** work (`/explore-ui`, `/explore-mobile`, locator discovery), **invoke the configured MCP tools** in the IDE — do not substitute narration for live inspection.
7. For **`/hqe-design`**: write `.hqe/artifacts/design-summary.md` — five-section layout in `.hyperqe/templates/human-review/design-summary.template.md` (Feasibility Review → Design Gate 24-item → Warnings → Per-TC deep-dive → Final verdict) when `.hyperqe/hqe.config.json` → `evidenceVerbosity` is `full` (default); a short highlights block + JSON link when `lite`. With UI/hybrid scope, run **E2E MCP probe** when the case mutates data or asserts post-action UI state; produce **`minimalPath`**, **`design-quality-assessment.json`**, and **`screenshotRefs`** per `.hyperqe/skills/hqe-testcase-design/SKILL.md` and `.hyperqe/core/workflows/hqe-design.workflow.json`.

## Session-scoped loading (token efficiency)

Load a phase's skill file, playbook, and any .hyperqe/pattern-bank/KB search results **once** at the start
of that phase's work within a delivery session, and hold them in context for every step of that
phase — do not re-read `.hyperqe/skills/*/SKILL.md`, `.hyperqe/playbooks/*.md`, or re-run an identical
`searchPatterns()` query multiple times within the same phase invocation. Re-read only when moving
to a new phase (different skill/playbook) or when a step's outcome genuinely requires fresh
pattern-bank data (e.g. a new `appArea` not covered by the first search).

**Anti-duplication (added 2026-07-19, found by real timing analysis of a `/hqe-generate` run):** never
re-read a file (artifact, spec, config) already read earlier in this same session unless you
yourself changed it since that read — hold its content in context instead. Never re-run an
identical diagnostic/state check (`git status`, `ls`, a validation script) back-to-back when
nothing has changed since the last run of it. Both were observed as real, measurable waste: the
same spec file read 3 times and the same report read twice within one develop phase, and two
near-identical `git status --porcelain` checks seconds apart in one design phase, with no state
change between them. `/hqe-generate` now runs all 4 phases in one continuous session by default
(see `hqe-generate.workflow.json#rules`) specifically so this "already loaded, don't re-fetch"
discipline carries across phase boundaries too, not just within a single phase.

## Parallel tool calls (mandatory, added 2026-07-19)

**Trigger:** before issuing any `Read`, `Glob`, or `Grep` tool call, check whether you already know
of 2+ other files/queries you will need for this same step (not dependent on this call's result).
If yes, you **MUST** issue them together as multiple tool calls in the same message, not as
separate sequential turns. This is not a style preference — it is a hard rule because of measured
real cost: an audit of one `/hqe-generate` run (2026-07-19) found 397 total tool-call turns across
the 4 phases, of which **68 (17%)** were part of a run of 2+ back-to-back single-Read/Glob/Grep
turns with no dependency between them — sequences that should have been one batched turn each.
Every avoidable turn costs real wall-clock time (the model "thinking" between turns is 70-95% of a
phase's total time, dwarfing actual tool execution) and real token cost (each turn re-transmits the
full accumulated session as cache-read). Concretely: when reading a delivery's design artifact +
its TestCase files + relevant pattern-bank entries + an adapter/schema reference at the start of a
phase, issue all of those `Read`/`Glob` calls in one message — do not read one, wait for the
result, then decide to read the next unless the next file's *path* actually depends on the first
file's *content* (e.g. you must read a manifest before you know which file it points to — that
case is a genuine dependency and stays sequential).

## Token/cost debugging (Claude Code only, added 2026-07-19)

At the end of any command/phase, run `node .hyperqe/scripts/token-cost-summary.mjs --pretty` (add
`--since <ISO8601 timestamp captured at the command's start>` when the work happened directly in
the main/orchestrator session rather than a delegated subagent, so the summary reflects just this
command, not the whole multi-hour session) and report the resulting token/cost/model breakdown to
the user as part of your final response — this is a real, measured number read directly from the
session's own local transcript (`~/.claude/projects/*/`, located via the `CLAUDE_CODE_SESSION_ID`
env var Claude Code sets), not an estimate. Pricing comes from the editable
`.hyperqe/execution/model-pricing.json` — an unrecognized model reports token counts with cost
`null` rather than a silently wrong number; update that file when Anthropic pricing changes.
Cursor/Codex/Copilot have no equivalent local transcript this script can read — this capability is
Claude-Code-specific until an equivalent exists for those harnesses. When `orchestrationLog.enabled`
is `true`, also pass the summary's `totalTokens`/`totalCostUSD`/model breakdown into
`log-orchestration-event.mjs`'s `--tokens`/`--cost-usd`/`--model` flags so it's visible in
`.hqe/orchestration-log/events.jsonl` and the orchestration dashboard, not just the chat reply.

## Evidence verbosity (`.hyperqe/hqe.config.json` → `evidenceVerbosity`)

`full` (default) or `lite`. This only affects the optional human-review Markdown summaries
(`design-summary.md`, `develop-summary.md`, `validate-summary.md`, `delivery-summary.md`) — it
never reduces the canonical JSON artifacts, schema validation, or hard rules. In `lite` mode,
write a short highlights block (verdict/recommendation, key scores, blocker/risk count) plus a
direct link to the paired JSON instead of the full mirror. Use this to cut generation tokens on
large deliveries; see `.hyperqe/BOOTSTRAP_RULE.md` for the full rule.

## Runtime model (mandatory)

- Use **chat-native orchestration** (agent resolves command -> workflow -> skill -> playbook from context).
- Do **not** rely on a repository-local mini orchestrator class as the primary execution path for slash commands.
- Keep CLI responsibilities limited to utility operations: `doctor`, `artifact:validate`, `bootstrap`, optional CI/MCP health checks.
- Gate progression and approval behavior: read **`.hyperqe/hqe.config.json` → `gates.reviewEnabled`**. When `true`, enforce by chat flow with explicit approvals. When `false`, do not require approval to close a gate for handoff; still produce evidence and document the config bypass in artifacts.

The **`hqe` CLI** (terminal) is **supplementary**: health checks (`hqe doctor`), artifact validation (`hqe artifact:validate`), bootstrapping a target repo (`hqe bootstrap`), or optional CI/MCP readiness checks. Treat CLI as optional unless the user explicitly wants terminal parity or CI hooks.

For HyperQE delivery lifecycle, follow:

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

unless the user explicitly accepts risk.

**Fast path:** for quick "just write me a test" / vibe-coding requests that don't need
regression-grade evidence or merge governance, use **`/gen-test`** (`.hyperqe/skills/hqe-quick-script/SKILL.md`,
`.hyperqe/core/workflows/gen-test.workflow.json`) instead — no gate, no `.hqe/artifacts/*` JSON, only the
non-negotiable code rules apply. Its output can still be picked up later by `/hqe-develop` /
`/hqe-validate`.

## `/hqe-develop` — project layout (mandatory)

Before creating or moving Playwright/WDIO files, run **`node .hyperqe/scripts/detect-test-layout.mjs`** (optional **`--target <project-root>`**). If the JSON says **`run-init`**, run the matching **`/init-*`** / `node .hyperqe/scripts/init-framework.mjs …` first. If it says **`use-existing`**, extend **`testDirResolved`** and existing **`pageObjectRoots`** only—do not invent a parallel test root (for example a new top-level `e2e/` when `playwright.config.ts` already pins another layout).