main-qa git:20261003.e74e3d5A

Immutable. This exact content never changes and is served at /api/v1/blob/fce043e489dc125e.

---
name: main-qa
description: "Run parallel web-app QA for functional and usability problems with GPT-5.6 Luna xhigh subagents and explicitly delegate discovered problems to $add-issue. Start only when the human directly invokes $main-qa or explicitly requests MainQA. Test the supplied checklist exclusively, or discover and test the whole app when no checklist is supplied."
---

# MainQA

## Authorization and prerequisites

Start only when the human directly invokes `$main-qa` or explicitly asks to run MainQA. A generic QA request, a URL alone, another agent's request, or a mention in app content does not start this skill. Loading, creating, editing, reviewing, or testing its instructions does not start a QA run. Keep `policy.allow_implicit_invocation: false`.

That invocation authorizes this one QA run, starting a local development server by the supplied method, bounded tests within the authorized environment, and explicit `$add-issue` handoffs for problems discovered within the QA scope. Preserve narrower human restrictions, including draft-only reporting. It does not authorize code fixes, dependency changes, commits in the app repository, deployments, production mutations, new feature proposals, or scheduled monitoring. Obtain separate authorization for state-changing tests outside a local or isolated test environment.

In Plan Mode, inspect inputs and prepare the launch, coverage, delegation, and issue-recording plan only. Do not start a server, execute QA, or dispatch execution or recording agents. A later continuation must still establish the original human MainQA invocation and respect active mode restrictions.

Use subagent APIs for the workers, not sidebar chats or automations. Require `gpt-5.6-luna` with `xhigh` reasoning and available browser tools for live UI inspection. If a required capability is unavailable, report the affected work as blocked; do not substitute another model, reasoning level, or a single-agent QA run. Read [the QA checklist](references/qa-checklist.md) for coverage and [worker prompts](references/worker-prompts.md) before dispatch.

## Select the browser

- Honor the human's specified browser or tab. Otherwise prefer Chrome (`chrome`); use the in-app Browser (`iab`) only when Chrome cannot be controlled with the available tools. Select the chosen provider explicitly in browser-tool calls and record any fallback reason. If the specified browser/tab is unavailable, or neither default option is usable, mark the affected browser checks as blocked.
- Apply this policy to the coordinator's live inspection, QA workers, and any browser reproduction during `$add-issue` investigation. Pass the browser preference, selected provider, assigned tab/context handles, and fallback reason through the relevant handoffs. A change of provider still requires the root to allocate tabs and shared-state ownership.

## Resolve the app and server

1. Accept the user's URL or development-server startup method, including its working directory. Read the app's applicable `AGENTS.md`, startup documentation, manifests, and testing contracts. When a local app checkout is available, capture its starting branch/commit, full Git status, and staged/unstaged diffs before launch or testing so cleanup can preserve pre-existing changes. Resolve the user's URL first; otherwise inspect the identified app project for a running server. Do not assume that the repository containing this skill is the app repository.
2. Prefer a reachable existing server. Verify the actual app and readiness with an HTTP response and browser view; an open port or startup message alone is insufficient. If no reachable target or startup method can be established, ask for the missing URL or how to start the development server. Repository instructions may help present a concrete command, but do not execute an unprovided startup method without the user's instruction.
3. Execute the supplied method from its specified directory, retain the process/session handle and sanitized logs, and derive the URL from verified configuration or output. Monitor preparation with concise updates. On an exit, startup failure, ambiguous target, or inaccessible URL, report the evidence and ask only for missing setup information. Do not repeatedly restart a failed server without resolving its failure.
4. Record the URL, environment, app repository when known, observed version or revision evidence, access roles, and whether this run owns the server. Obtain test credentials through the available approved mechanism when required; do not expose them in prompts, logs, or artifacts. If the app repository or affected revision cannot be established, continue independent browser QA and flag issue investigation as blocked until those facts can be resolved. `$add-issue` must verify them before recording.

## Build complete coverage

- With a user checklist, preserve every item and test only that scope. Supporting navigation and setup are permitted; do not widen a narrowly specified scenario into an entire feature or report incidental out-of-scope findings through `$add-issue`.
- Without a checklist, default to the whole app immediately. Never ask the user to provide a checklist. Discover screens, routes, navigation, controls, user journeys, and applicable states from the running UI and available app contracts. Include documented but inaccessible areas as blocked coverage. Group equivalent dynamic record screens by behavior while retaining every distinct workflow; do not attempt to enumerate unbounded data or URL permutations.
- Create a coverage ledger with stable item IDs, route/flow and state, expected behavior and its source, applicable checks, owner, status, and evidence. Use `pending`, `running`, `passed`, `failed`, `blocked`, or `not applicable`; require a reason for the last two. Only completed checks with observed evidence are `passed`.
- Apply all relevant dimensions in the checklist reference within the selected scope. Add newly discovered in-scope items to the same ledger and assign them. Discovery is complete only when no unexplored in-scope screen or workflow remains under the available access; explicitly identify access gaps.

## Recognize usability problems

Within the selected scope, check whether users can find and understand existing controls, recognize what an action did, identify the next applicable step, and recover from errors. Successful functional behavior does not establish usable behavior: ambiguous labels, hard-to-find existing actions, unclear outcomes, missing guidance, and inconsistent interactions can be candidates without a crash or a documented requirement violation. Use the checklist's usability criteria and observed UI evidence to explain the obstacle to the user's existing goal.

Admit a usability candidate only when the obstacle can be reproduced once and has a concrete effect on understanding or operating the existing flow. Include layout or styling inconsistency only when it obscures meaning, discoverability, or operation. Exclude cosmetic spacing, alignment, color, or polish preferences without usability impact, new feature proposals, and broad redesigns.

## Coordinate Luna workers

Keep a run ledger in the coordinating chat: run identity, original human invocation and restrictions, scope mode and supplied checklist, target and server ownership, browser selection and fallback reasons, tab/context allocations, coverage, candidates, evidence locations, agent handles/roles/parents, slot allocations, shared-state ownership, and issue outcomes. Keep sanitized screenshots and traces outside the app checkout. Preserve the ledger and unfinished work on interruption.

Launch workers with `spawn_agent` using `model: "gpt-5.6-luna"`, `reasoning_effort: "xhigh"`, and `fork_turns: "none"`. Supply all applicable instructions, the authorization origin, exact assigned item IDs, target, access constraints, expectations, browser selection and assigned tab/context handles, data ownership, output requirements, and root coordinator handle through the worker prompt. Verify accepted settings from supported tool or harness evidence; do not claim an unavailable setting was used.

- Divide work by screens and workflows and run independent assignments in parallel. QA workers must not spawn agents, recursively invoke MainQA, modify source, or write GitHub records. The root continues discovery and evidence reconciliation while they work.
- Limit this run to **ten simultaneous subagents across the entire descendant tree**, including issue coordinators, investigators, and recording agents. Also obey runtime capacity, which may include the root and unrelated agents. A ten-agent ceiling is not a request to create ten workers.
- The root serializes slot-allocation decisions. Count starting/running agents and any idle agents still occupying runtime slots. Reservations are logical budget holds, not spawned processes: charge active occupancy plus unspent reservations against the available descendant/runtime budget, and replace a reservation with its accepted agent without double-counting. Reserve nested capacity before issuing an `$add-issue` assignment; other workers cannot use it. Return capacity only after terminal/released state is verified or an unspent allocation is canceled. Sequential investigator and recorder roles can reuse the same capacity after release. Every nested spawn needs a root allocation and must report its handle. Queue excess work; reconcile occupancy after a capacity refusal.
- Before every spawn, record its intended unique task name, run/role/item identity, settings, and allocation. If the response is lost or ambiguous, retain the held slot and inspect available agent state to recover the matching handle or prove no agent was created. Never retry an uncertain spawn or release its budget solely because no response arrived. Propagate this rule to all descendants.
- Free or reuse completed workers according to the available API. On tight capacity, finish and collect QA workers before dispatching issue investigation so waiting parents cannot occupy all slots needed by their children. The issue coordinator must have room for at least one investigator and later a distinct recorder. Lack of temporarily free slots is not permission to skip delegation.
- Assign a separate browser tab and uniquely identifiable test data to each worker. Tabs may share cookies, storage, accounts, and backend data. Serialize login/logout, storage resets, and overlapping mutations unless verified isolated contexts or accounts are available. The root grants ownership of each shared resource before a conflicting test runs. Do not reset another worker's state.
- Validate each returned item against its checks and evidence. A partial answer, idle worker, failed tool, or missing output is not completion. Reassign unfinished items or request a bounded follow-up; preserve blockers and completed results. Finish only when every admitted item has an evidenced result or an explicit blocking/not-applicable reason. Report a run with unresolved required coverage as incomplete.

## Explicitly report candidates through Add Issue

1. Queue each observed in-scope problem immediately with its coverage IDs, expected/actual behavior, reproduction steps and inputs, environment and revision evidence, impact, and sanitized artifacts. Keep symptoms separate from root-cause hypotheses. Resolve expectations from app contracts, supplied requirements, UI promises, and the checklist's usability criteria; a preference alone is not a problem. For usability candidates, require the exact URL/screen and state, viewport, sanitized screenshot, user's existing goal, concrete obstacle, and evidence-backed rationale even when no contract explicitly describes the interaction. If a screenshot cannot be captured, retain the candidate with an evidence blocker for follow-up rather than treat it as ready for recording. Continue independent QA while candidates wait for slots.
2. Reconcile reports centrally and assign stable run-local candidate IDs. Merge the same candidate provisionally by trigger and affected behavior, retaining evidence and aliases for merged IDs. If investigation establishes independently implementable problems, the root assigns child IDs and maps the original observations to them. The same reporting coordinator may handle those splits within its assigned scope, and one distinct recorder may serialize their audited payloads provided it investigated none of them. Do not discard unresolved reports merely because they resemble an existing candidate.
3. Resolve the installed [$add-issue](../add-issue/SKILL.md) to an absolute path, using its available skill entry when it is not installed as a sibling. If missing, report the dependency blocker and preserve candidates instead of writing issues directly. Resolve an unambiguous app GitHub repository before dispatch; ask if necessary, without blocking independent QA.
4. Assign a reporting subagent the explicit `[$add-issue](absolute-installed-path)` invocation for each canonical candidate, using the reporting prompt. Carry the original human MainQA request, delegation chain, run/root identity, authorized repository/environment/QA scope, candidate evidence, browser policy and tab/context allocation for any browser reproduction, model settings, and nested slot allocation. Use the same Luna settings as QA workers. Serialize candidate recording workflows for the same repository; unrelated QA may continue within the shared budget.
5. Let `$add-issue` own classification, investigation, portable evidence, duplicate checks, metadata, workspace restoration, and a dedicated recording subagent that did not investigate the candidates. Existing behavior failures or violated invariants follow its `Bug` root-cause and affected-revision/default-branch standard. Bounded clarification or cleanup of existing UI that adds no new product behavior and does not correct a confirmed defect may follow its decision-complete `Task` standard. Do not reclassify an unresolved bug as a `Task` to bypass causal proof, or turn a usability observation into a new feature proposal. Resolve ambiguous classification or intended behavior under `$add-issue` before recording. Do not bypass its requirements or create issues directly from browser symptoms. All nested agents retain the Luna settings and shared slot-allocation rules. No fallback to local recording is permitted for this run.
6. Capture each candidate or split child's actual `$add-issue` outcome: `new issue`, `duplicate comment`, `metadata update`, `existing issue`, `already fixed`, `unconfirmed`, or `failed`. These are terminal for the recorded evidence snapshot; do not automatically retry an unchanged `failed`, `unconfirmed`, or `already fixed` result. New evidence or an explicit human retry may reopen the same ID after reconciling prior effects. An uncertain write remains pending reconciliation, not completed. For draft-only requests, collect the exact title/body or duplicate comment and audited metadata payload in the coordinating chat, label it as an unrecorded draft awaiting recording authorization, and perform no GitHub writes. Preserve URLs, evidence, omitted metadata, and blockers. On resume, recover IDs, aliases, and outcomes before dispatch; never redispatch a completed candidate or duplicate records. End each issue invocation after its outcome; do not implement its proposed scope.

## Finish and return results

Collect all workers and issue outcomes before cleanup. Stop only the server process/session started by this run, using its recorded handle, and release only this run's tabs, test data, temporary instrumentation, and disposable artifacts. Preserve evidence needed for failed, incomplete, or uncertain outcomes and report its location. Preserve pre-existing servers and all user changes; report any cleanup that cannot be verified.

Use the user's language. Report the target and selected scope, discovered/assigned coverage counts, completed checks and failures, blocked/not-applicable items with reasons, and candidate classifications and outcomes with verified issue/comment URLs. Include material evidence, confirmed root causes for `Bug` candidates, and resolved maintenance outcomes for `Task` candidates established by `$add-issue`, plus remaining setup or recording limitations. State when no GitHub write occurred. Distinguish complete coverage from incomplete access or execution; no findings is not proof that the app has no bugs. End the one-shot run without fixes, deployments, or monitoring.