qa
Skill1 starsChanged 16 days agoApache-2.0View on GitHub
Write an item or stage QA brief, request QA as the lead, or run the brief as QA and record its verdict.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- codebase-designSkill
- code-reviewSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- grillingSkill
- handoverSkill
- implementSkill
- mergeSkill
- onboardingSkill
- plan-epicSkill
- prototypeSkill
- releaseSkill
- researchSkill
- retroSkill
- tddSkill
- to-specSkill
- to-ticketsSkill
- triageSkill
- wayfinderSkill
- writing-for-agentsSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Before running or recording QA, check node --version against cland's shipped node-engines.json beside this skill's recorder.
- Distinctive: line 38
Keep conditional-check scope identical in the request and committed brief, stating whether missing authorization means out of scope or …
- Very specific: line 69
Run each headless case with the recorder from the local checkout.
- Very specific: line 122
Use hub-api for checks of the hub through the cland CLI.
- Very specific: line 185
If Reviewer or QA is unavailable, run its brief with /codex:rescue --wait --fresh --model gpt-6.1-sol (read-only review) or /codex:rescue …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
A QA run has one file at its centre: the brief, qa/briefs/T-<n>.md, committed with the work and self-contained, because a rescue run cannot ask. Headless-grid cases are Lua files, qa/cases/<ID>.lua, run with cland --headless --qa; other surfaces use the brief’s commands or computer-use steps and qa-record.sh note. Every case ends as one line of .cland/qa/runs.jsonl; the run ends as one verdict on the item.
Before running or recording QA, check node --version against cland's shipped node-engines.json beside this skill's recorder. This file
travels with cland init/update and release packaging; the host project's
package.json does not define cland's runtime contract. With nvm, source "${NVM_DIR:-$HOME/.nvm}/nvm.sh",
run nvm use 24, and confirm the full range including its minimum patch.
Alternatively prepend an installed supported Node's bin directory to PATH
for the command and its children. qa-record.sh run and note refuse an
unsupported or unavailable Node with exit 2, naming the running version and
required range, before running or appending anything. Rerun the check on the
supported runtime before recording evidence; recover preserves historical
receipts without applying today's runtime check.
BRIEF.md in this folder is the template. qa-record.sh in this folder runs a case or records a manual check and writes the runs.jsonl line; run it from the item's worktree, always as sh .agents/skills/qa/qa-record.sh … (cland init copies the file without its executable bit).
If you are the Coordinator
- Write the brief. Copy
BRIEF.mdtoqa/briefs/T-<n>.mdin the item's worktree (or on the branch the item will land from), fill in every section and commit it with the work. A brief has: the item; the build (branch and commit); the cases, each a catalogue id with its surface (headless-gridby default, ortmux,web-terminal,hub-api,real-browser); manual checks, each a command with its expected outcome; what is out of scope; the grants it needs (none by default). Do not leave a section out: write "none". A headless-grid case that does not exist yet is written first, inqa/cases/<ID>.luawith its catalogue header (see "Cases" below). End this step only whencland qa lint qa/briefs/T-<n>.mdpasses at the build under test; fix every finding before requesting QA. Lint runs offline in production installs with development dependencies pruned. Source references use committed HEAD (or--commit <sha>), ignoring uncommitted source. Follow reference syntax and limits for titles/selectors; derive test totals from generated cases and membership fromcland task plan show <item>. Assign command roles with arolecolumn orRole: Implementerabove the checks; for Aide verification rows, follow the named report recipients and preview limits. - Give the brief to the item lead. The live claimant from
task.viewrequests QA itself and handles not-clear findings and re-runs. Launch a QA holder when none is available. For an unclaimed item, act as its lead and request QA yourself. - Handle an unclaimed item or unavailable QA.
- For an unclaimed item, through the hub (preferred).
sendto theqarole (launch one withsession.launchif none is live) with first lineqa request T-<n>and the brief's path (the brief carries its own build rule: the branch tip when the run starts). The QA session runs the brief, records the runs and writes a QA verdict through the hub; the merge gate counts it (decision D5). - Rescue (fallback, or a second opinion).
/codex:rescue --background --fresh --model gpt-6-astra "Run the QA brief in qa/briefs/T-<n>.md exactly", then/codex:statusand/codex:result. A rescue run reaches no hub socket: it returns theruns.jsonllines and the verdict in its output. Recover the run's evidence and lines as "Recovering a rescue run" below says, and record the verdict withtask.comment(verdictqa,result,runthe rescue job id,commit), saying in the text that it came through/codex:rescue. That verdict shows as yours and the merge gate does not count it (decision D5): it informs, it does not clear.
- For an unclaimed item, through the hub (preferred).
- Read findings escalated by the lead. The verdict is
clearonly when every case in scope passed. A finding outside the item under test is a bug found aside: the Coordinator files it into the category Bugs (find its id withcland task list --kind category):cland task create "<finding>" --parent C-<n> --label qa-found --label needs-triage --body-file -, with the case id, the commit, the command and what it showed. Findings in the tested scope stay in its review/QA loop.
Epic QA request topic
Send every epic QA request (after-stage or Definition of done) in a topic bound to the epic, never in Agents. Use its existing topic, or have the Coordinator create one before sending: QA can publish artifacts only where its request arrived.
After-stage QA
Keep conditional-check scope identical in the request and committed brief, stating whether missing authorization means out of scope or BLOCKED. Read stage member counts and other plan facts from task plan show at the run rather than hard-coding totals (A-9063 R3; E-416 stage 1, E-413 stage 1/T-1093).
The Coordinator or epic's Lead writes qa/briefs/T-<epic>-stage-<index>.md from STAGE-BRIEF.md after reading task.plan show and the stage's merged items. Fill every section: exact stage name, ordered item ids, effective stage scope (affected or full, including after-stage item overrides), commands/cases and expected results, evidence, out of scope and grants. affected covers the stage's combined changes; full covers the product's complete QA scope. Commit the brief on dev before requesting the run. A stage uses no stage QA verdict when neither its default nor any item override requires after-stage QA.
Once all stage tasks have dev landing receipts or qualify as evidence-only (closed done, no branch, no landing receipt and no Item: trailer on dev), its Lead or the Coordinator sends to QA in the epic's topic: first line qa request T-<epic> stage <exact stage name>, then the committed stage brief and full dev SHA. Keep the next stage's launches held until task.plan show reports this stage closed. A not-clear verdict keeps it open: file the findings, add their items to this stage through task.plan set, merge their fixes, then request a new run on dev.
QA takes a hold on the epic and reads its plan, stage progress and brief. Use a clean detached worktree at the requested dev SHA (the tracker in the root can have live edits). Before running, check that HEAD equals the request and refs/heads/dev, and that every listed task has a dev landing receipt or meets the evidence-only definition above; otherwise report BLOCKED to the requester. Run and record the cases/manual checks with the existing script using the epic id and one unique run id. Record evidence before the verdict. Recheck dev after the cases: if it moved, keep the evidence and report BLOCKED; request a new run at the new build.
Write one task.comment on the epic with verdict: qa, stage: "<exact stage name>", commit: "<full tested dev SHA>", run and result. The CLI form adds --stage "<exact stage name>" to the normal verdict command. Clear only when every check in the stage brief passed. Stage verdicts carry no verified or failed epic criterion marks; the epic's Definition of done remains a separate run. Report qa clear T-<epic> stage <name> or qa not clear T-<epic> stage <name> in the request topic to its Lead. The hub refuses a stale dev build or unfinished stage; retry only the verdict when the evidence/build still qualify, otherwise request a fresh run.
Web briefs: real browser through computer use
Web workbench briefs include real-browser cases run locally by QA with Codex gpt-6-astra and computer-use tools. The Coordinator tells the human before launching this GUI run. Implementers and Reviewers never launch a real browser or any GUI on the human’s Mac; their browser checks use isolated Chrome Headless Shell or Chrome for Testing in headless mode and close it afterwards.
- The brief names the local project/page, dedicated cland browser profile, steps and expected results. Fixture server, hub, Git and harness commands stay in a disposable project with sealed HOME/XDG/Git and credential filtering. Only the real-browser computer-use session uses the human’s normal HOME and login keychain, with the dedicated cland profile. Never launch that browser from a sealed fixture environment or fall back to the human’s default profile. If the tools cannot use that environment/profile, record
BLOCKEDwith the exact limitation. - Obtain the
cland weblink for the brief’s project and open it in the human’s default browser through computer use with that profile. Untilcland webis available, the brief may name a local static page. Touch only the cland page and its browser permission prompts, under the brief’s grants. A harness refusal, missing Screen Recording/Accessibility permission or unavailable profile is a blocker: report the exact message tolead T-<n>in the item topic (Coordinator for a closed or unknown item). - Keep keychain, profile and system settings unchanged. Never press Reset or Reset To Defaults. Dismiss unexpected system dialogs only with Cancel; if a dialog cannot be cancelled, stop and report it as a blocker to the item lead so the Coordinator can take it to the human.
- Take screenshot evidence through computer use and save it under
.cland/qa/<item>/<run>/. Close the tab opened for the case when finished, including after a failure when the tools permit it; leave other tabs alone. Record withnote, surfacereal-browser, a method describing computer-use steps and observations, result and screenshot paths. Record blocked attempts too, with any available capture and the exact blocker. The recorder never opens a browser.
sh .agents/skills/qa/qa-record.sh note T-1011 qa-2026-10-20-1 WEB-001 real-browser "computer use: opened local page, observed shell, took screenshot, closed tab" PASS .cland/qa/T-1011/qa-2026-10-20-1/WEB-001.pngEpic demos on a named dev commit
Bind every human-visible Definition-of-done sentence to a concrete check and criterion, retaining explicit approval evidence when plan show says “not required”. Before naming the build, normalize DoD criterion ids, commit tracker changes and pin the final SHA for both demo and occasion suite. If a QA hold creates a tracker-only commit, name it next to the tested source SHA in the request and receipt so clean-root admission cannot silently change the claimed build (A-8634 R12; E-412 stage 2, E-415 stage 3/DoD, E-1006; A-9063 R3; E-1006 DoD).
For an epic's Definition of done (separate from after-stage QA), take its QA hold and resolve the requested full dev SHA. Start the demo with cland demo start <epic> --commit <sha> --json. Keep the returned lease id, commit and deadline. The hub delivers that committed tree with the suite's dependencies and Neovim, under the shared remote budget and daily cap. Only QA holding the epic, the Coordinator and the human may use demo controls; sessions leave provider operations to the hub.
Wait for start to complete before running cases. Concurrent demo status reports provisioning through creation and delivery; exec refuses with the lease id and commit while it is provisioning. Status becomes active after delivery persists readiness, when exec can accept commands until the deadline. See hub/README.md, "Epic demo leases".
Run each headless case with the recorder from the local checkout. Use the requested epic's canonical id for both arguments (E-423 in this example):
QA_DEMO_EPIC=E-423 CLAND="$PWD/hub/bin/cland.ts" sh .agents/skills/qa/qa-record.sh run E-423 <run> <CASE-ID>The recorder invokes cland demo exec <epic> -- …, runs the case in the delivered tree as the ordinary user, copies its captures into the local evidence directory and records executor, commit, elapsed lifetime and estimated cost. Run each CLI/manual case through cland demo exec <epic> -- <command…>, save its output locally, then record it with QA_DEMO_EPIC=<epic> … qa-record.sh note …. Commands are argument vectors; use sh -c '<script>' when a case needs a shell. The remote PATH includes the delivered hub/bin for cland --headless --qa.
For a demo case reporting structured facts, the brief supplies a local JSON array of required top-level keys and sets QA_EXPECTED_FACTS to that file for qa-record.sh run. The case writes <case>.facts.json under CLAND_QA_OUT, containing {facts: {key: value}, steps: [...]}; the recorder merges its fact/error fields into the result and retains the sidecar as evidence. Duplicate fields are refused. Every required key must be its own non-null fact; false and 0 are recorded facts. Unreadable/malformed declarations or missing facts produce BLOCKED, exit 2. A claimed PASS with a nonempty error, errors or stepErrors anywhere in its result, or a nonzero native exit, also becomes BLOCKED. Legacy Lua results without a declaration keep their existing shape; the recorder does not infer expectations from prose.
The demo recorder scans result metadata, stderr and every decoded capture before any local copy or cleanup acknowledgement. Recognized sign-in query tokens, bearer credentials, provider key formats, named token/API-key assignments and private-key headers refuse publication with a value-free diagnostic. Unsafe captures stay remote; the blocked receipt has no evidence. The scan covers text bytes (UTF-8/UTF-16 and URL/JSON escapes), without OCR or archive unpacking. This automatic gate applies to remote run; manual note, local runs and rescue recovery still require QA to redact and scan their outputs before recording or sharing. See demo recording. Never pass secrets or scanning patterns in argv.
Cases requiring macOS run locally in a clean detached worktree at that same full SHA, with QA_DEMO_EPIC unset. The case table names droplet or local macOS for every case. If start refuses for lack of a remote slot or spend budget, run locally at the requested SHA and report the reason; the lane's merge hold remains in force until the demo verdict. Other start failures are blockers to report to the lead.
After the cases, run cland demo status <epic> --commit <tested-sha> --json and read freshness. An unrelated dev move is allowed: current: true means the tested commit is on dev and every later commit avoids the files changed by the epic's task merges (Item: trailers). current: false names the conflicting commits/files, or a build no longer on dev: retain evidence and request a fresh run. This same check works without a remote lease after a local fallback. The hub rechecks this rule when recording the verdict and closing the epic.
Collect all captures, then cland demo stop <epic> --json before recording the verdict, so the evidence can name the confirmed lifetime and cost. Include executor, full commit, lease/deadline, lifetime and cost in the verdict text; local cases have no droplet cost. A verdict or the earlier of run timeout and machine lifetime also destroys the droplet automatically. If destruction is pending, report it to the lead and use the status once confirmed. Write the epic verdict with the tested commit and verified criterion ids, and close through the normal epic gate. A verdict refusal after evidence was recorded retries only the verdict when the build still qualifies.
If you are the item lead
After committing and pushing the work to origin, send kind report to qa in the item topic, with first line qa request T-<n>, the Coordinator’s committed qa/briefs/T-<n>.md and the branch/head. Request QA when a brief was supplied; without one request review only, unless task.view’s qaPolicy has a non-none scope and when: per-item, or qaCriteria names criteria still needing QA marks; in either case report the missing brief to the Coordinator. Items with after-stage QA merge on review and receive their stage QA pass on dev. Fix not-clear findings and request a new source review before any new cland verify run at the new head. Keep the claim until merge. The hub’s ready event supplies the supervising Lead’s or Coordinator’s handover; a clear QA verdict needs no relay.
The Implementer requests source review first and runs cland verify only after a clear source verdict at the exact reviewed head. An unchanged head may reuse an earlier green run through the tree-hash cache; use its same-head result for full-suite evidence. QA case execution remains governed by the brief.
Default item subscriptions deliver status/verdict and verifier death or long idle to the lead at its next turn. Use subscribe for additional subjects and subscriptions to inspect them; routine updates use kind progress, requests and verdicts use report, blockers use question or report. lead T-<n> falls back to the nearest container Lead, then the Coordinator, for an unclaimed item; for a closed or unknown item address coordinator directly.
Inspect the request's send outcomes. resolvedTo names the selected QA session. A queued outcome waiting for the next free verifier means the hub will assign the request automatically and notify you; wait instead of resending it. If none is live, report the staffing blocker so a QA session can be launched. A later refusal notice names the retry rule.
If you are the QA role
Accept qa request T-<n> from the item’s lead (the live claimant in task.view), a supervising Lead within its subtree, or the Coordinator; the Coordinator-authored brief it names is the whole job. Questions about the build or findings go to lead T-<n>; a missing brief blocks the run. Do not fix what you find.
Submit cland verify --report <request-topic> --to <requester-name> --to <your-name> with no mode for task runs (D29) and wait for its head-bound result before settling the verdict. When both the candidate and hosting hub enable the merge queue, task runs cover T0–T2, changed T3/T4 files and tiers.json mapped T4 read-path guards once (shared duration procedure: docs/agents/tests.md), plus the separate Web phase (included after T1 in web/-touching merge batches; always in periodic/integrated/occasion runs; cadence: docs/agents/tests.md#web-phase): all T1 and selected T2, falling back to all T2 in both packages. The hub runs all T1 and T3 in merge batches of up to three items by default. Ordinary integrated dev runs and explicit all cover T1–T3 after T0. At stage and epic close and before release, the Coordinator requests occasions that add T4; QA may request the epic occasion for its demo. The hub's nightly soak also includes T4. When the brief needs a full suite on a non-dev head, use cland verify all with authorization. Explicit all is reserved to the Coordinator, the human shell and authorized occasions; a flaky-gate second receipt uses the ordinary diff selection. cland suite is the transition alias; see docs/agents/tests.md for admission and compatibility.
For an epic demo on clean integrated dev, QA may submit cland verify all --occasion epic --report <request-topic> --to <requester-name> --to <your-name>. The Coordinator owns stage and release occasions. Task heads and ordinary batches use one slot. Remote occasions use the free remote slots up to [verification] shards (default 2), reserving the whole group against the daily cap ($3 here); fewer than two slots or insufficient cap yields one whole run on one slot with a warn notice naming the cause. Record the merged result and each shard's machine, duration and cost, total cost, and wall time. Two ten-minute c-8 lifetimes estimate $0.0833 total at $0.25/hour; include provisioning/cleanup lifetime in measured costs. See docs/agents/tests.md for details.
The brief's full suite may run on the project's droplet executor. A green same-head Linux result satisfies the gate's suite evidence; its macOS-only cases are listed as skips and run in the release's final local run ("Release v0.1.2 from the item"). Name the executor, platform and droplet lifetime/cost in the verdict's evidence (cost is not applicable for local runs). For a check that needs macOS, request --executor local on a macOS host and retain any brief cases still needing that platform. The hub owns droplets; sessions never create, list or delete them themselves. cland executor controls belong to the human and Coordinator.
- Read.
task.viewthe item, then the brief. Work from the item's worktree (.cland/worktrees/T-<n>, or the path the request names) and apply the brief's build rule:git status --shortmust be empty andgit rev-parse HEADis the build, which you run and then name in the verdict. A request that names a commit is honoured when it equals HEAD; when it differs the run isBLOCKEDand the verdict names both commits. A brief that names no cases, or a worktree that is dirty or off the branch, isBLOCKED: say so in the verdict instead of guessing. - Choose a run id of your own, unique for the item:
qa-<date>-<n>, for exampleqa-2026-10-09-1. Run each case in scope, headless-grid ones with the script, from the worktree:
CLAND="$PWD/hub/bin/cland.ts" sh .agents/skills/qa/qa-record.sh run T-<n> <run> <CASE-ID>CLANDis the path of the cland executable (in this repositoryhub/bin/cland.ts, which is executable); in a project that hasclandon its PATH leave it out. Ids are checked: the item has one uppercase kind prefix and digits (T-12,E-423, or a configured planning kind such asI-42), run and case ids are one path component of letters, digits,.,_,-starting with a letter or digit. The script runsqa/cases/<CASE-ID>.lua, keeps the grid and state dumps in.cland/qa/<item>/<run>/, prints theruns.jsonlline and appends it to.cland/qa/runs.jsonlof the project (not the worktree's copy). Exit 0 is PASS, 1 FAIL, 2 INCONCLUSIVE or BLOCKED.Run each manual check and each case on another surface the way the brief says, and record it with what you ran and saw:
sh .agents/skills/qa/qa-record.sh note T-<n> <run> <check-id> <surface> "<the command you ran>" <PASS|FAIL|INCONCLUSIVE|BLOCKED> [evidence-file…]Use
hub-apifor checks of the hub through theclandCLI. Put captures under.cland/qa/T-<n>/<run>/first. A grant the brief does not list is a grant you do not have: record the caseBLOCKED.Verify criteria and write the verdict. Match the cases and checks to the stable ids in
task.viewcriteria. A clear verdict includesverified: "C1,C3"for the criteria established by this run, orverified: "all"when every criterion was checked. A not-clear verdict includesfailed: [{ criterion: "C2", note: "what failed" }]for each failed criterion; notes are nonempty and single-line. For separate marks usetask.criterionverify withcriterionandrun, or fail withcriterionandnote. Leave unchecked criteria unverified. The hub lists the marks in the verdict report. Write onetask.comment,verdictqa,runyour run id,committhe commit you ran (full SHA),result:clearonly when every case and check in scope is PASS;not clearwhen any is FAIL, BLOCKED or INCONCLUSIVE, and the text names each such case by id.
The text opens with the case table, then findings ranked high, medium, low, each with the case id, the command and what it showed:
| case | surface | result | evidence | | --- | --- | --- | --- | | SHELL-001 | headless-grid | PASS | .cland/qa/T-12/qa-2026-10-09-1/SHELL-001.screen.txt | | ITEMS-001 | headless-grid | FAIL | …/ITEMS-001.screen.txt | not clear: ITEMS-001 FAILED (T-2 missing from the items panel).- Report to the item lead with
sendkindreport(to: ["lead T-<n>"], in the request's topic): first lineqa clear T-<n>orqa not clear T-<n>, then the failed cases. Report any find outside the item under test to that lead with its category (Bugs for a bug found aside) and evidence, so the Coordinator files it.
If you are a rescue run
You have no hub and cannot ask. Do steps 1 to 3 and 4 with the same script, with QA_SESSION=rescue-<job id> set (it prints the line when it cannot append it, and keeps evidence in the temp dir when .cland/qa is not writable), then answer with, in this order: every runs.jsonl line as printed; the captures' directory ($TMPDIR/cland-qa-evidence/T-<n>/<run>/) when any line names it; every block the script printed on stderr after no evidence directory could be made, verbatim, when both destinations failed (the Coordinator cannot get those captures any other way); the case table; and the verdict as verdict: qa, result: clear | not clear, commit: <sha>, run: <the job id>. Do not claim a verdict was recorded on the item.
Recovering a rescue run
A rescue run usually cannot write .cland/qa/, so its lines name disposable captures. The Coordinator makes them durable with the script, never by hand: paste the returned lines into a file (lines.jsonl, one line each), find the captures' directory (the lines name it: $TMPDIR/cland-qa-evidence/T-<n>/<run>/ of the rescue run), and run, from the project:
sh .agents/skills/qa/qa-record.sh recover T-<n> <run> <captures-dir> lines.jsonlFor each line it copies the captures into .cland/qa/T-<n>/<run>/, verifies each copy, rewrites the evidence paths to the durable tree and appends the line to .cland/qa/runs.jsonl, in that order, and only for a line whose captures were all copied. It never deletes a source. Exit 0: every line appended. Exit 71: .cland/qa/T-<n>/<run>/ cannot be made, nothing was appended or copied. Exit 73: some lines were not appended (a missing, unreadable or conflicting capture, a line of another item or run, a failed append); stderr names each loss and the sources stay in <captures-dir>. Fix the cause and run it again on the lines that were lost only (a line already appended would be appended twice). If a capture is gone for good, append that line by hand without the lost path and say so in the verdict's text.
Two things can go wrong with the evidence directory in the rescue run itself, and the run says which:
.cland/qa/T-<n>/<run>/cannot be written: the script keeps the captures in$TMPDIR/cland-qa-evidence/T-<n>/<run>/and the line names those paths (absolute). Recover with the command above.- Neither directory can be written: the case still runs, the line has
"evidence":[], and the case's inline captures (grid and state) are printed on stderr, afterno evidence directory could be made. The rescue answer forwards them (see "If you are a rescue run"); the Coordinator saves them as.cland/qa/T-<n>/<run>/<CASE>.inline.jsonand adds that path to the line'sevidenceby hand.
When a step fails
The run is three writes, in this order: the evidence files, the runs.jsonl line, the verdict. Nothing is rolled back; each leaves a state you can finish from.
- The evidence cannot be written: the case still runs; the captures go to the temp dir, or inline on stderr when even that fails ("Recovering a rescue run").
- The line cannot be serialized (exit 70): nothing is appended; the outcome and the captures' directory are on stderr. Rerun nothing: write the line by hand from that outcome, or record the case with
qa-record.sh note … <result>. - The line cannot be appended (
NOT recorded): the case ran and the line is on stdout. Append that line to.cland/qa/runs.jsonlby hand, or report it to the Coordinator; do not rerun the case under the same run id. - The verdict is refused or fails after the lines are in: the lines stay, they are the record. Fix the cause (for example a wrong
commit), write only the verdict again with the samerun, and report. A later verdict of the same kind replaces the earlier one. Never rerun the cases to "retry" a verdict. - The run is interrupted: lines already appended stay. A new run id covers the rest; the verdict names the cases that have no line
BLOCKED.
Cases
Each qa/cases/<ID>.lua opens with its catalogue header, a comment block of exactly these fields, so the catalogue is the files:
-- id: SHELL-001
-- title: General shows and a message goes queued
-- preconditions: a fixture project with no items; the stdio hub
-- expected: the empty General thread, then the typed message shown as queued
-- since: T-57
-- regression: noregression is yes when the case was added to guard a bug that was fixed. The case then returns the table cland --headless --qa runs (nvim/README.md, "QA cases"). A case needs no grant and runs in a sandbox; the tmux and web-terminal surfaces need the grants spec 4.10 names, and a brief that uses them says which.
Coordinator fallback procedure
- If Reviewer or QA is unavailable, run its brief with
/codex:rescue --wait --fresh --model gpt-6.1-sol(read-only review) or/codex:rescue --background --fresh --model gpt-6-astra(QA). Record verdict/result/run id withtask.comment; yours cannot pass the gate. Append QAruns.jsonlto.cland/qa/runs.jsonl; file finds withqa-found,needs-triageandqa.
QA execution procedure
- Work: take a verifier hold with
task.holdon the item (beside the Implementer's claim; it setsqa), then read the item withtask.viewand the brief, then run each case of the brief from the item's worktree (cland --headless --qa, through the skill's script,sh .agents/skills/qa/qa-record.sh run T-<n> <run> <CASE-ID>, which appends one line per case to.cland/qa/runs.jsonl, with evidence in.cland/qa/T-<n>/<run>/) and each manual check. Beyond the brief, the checks you can run yourself: shell-level checks (build, tests, the commands a user would run); thecland taskCLI (cland task list,cland task view); and where UI is involved, a headless Neovim: onenvim --headlessprocess running a Lua script that feeds keys withnvim_inputand reads the grid withscreenstring(), or the project's own test harness if it does that (nvim --headless --listenwith--remote-sendand--remote-expr). Keep what you ran and what you saw. Do not fix what you find.
QA verdict procedure
For rule 17 evidence, retain both tested-source and served-page stamps; differing stamps support load smoke only. Timing-sensitive checks retain local queue state and a short CPU-idle sample, separating deterministic assertions from timing diagnostics. A corrected probe keeps its unaltered capture and labels the correction separately from product failures (A-8634 R13; T-794, T-965, T-970, E-1006 stage 2, E-795, E-415/E-412 stage stamps, E-412 DoD; A-9063 R2; E-413 stage 1/T-1093).
- Verdict: one
task.commenton the item withverdictqa,resultclear or not clear, andrunan id of your own for this pass. Givecommit, the full SHA you ran. The hub writes the header from them:verdict: qa,result: clear | not clear,by: <name> [<role>],run: <id>.clearonly when every case in scope passed; a FAIL, BLOCKED or INCONCLUSIVE case makes itnot clearand the text names the case. The text is the case table, then the findings ranked by severity (high, medium, low), each with the case id or file:line, the command and what it showed.
QA criterion procedure
- Criteria: read
task.viewcriteria and verify each tested id. On a clear verdict passverified: "C1,C3"(or"all"only when every criterion was checked); the hub marks them with yourrun. On a not-clear verdict passfailed: [{ criterion: "C2", note: "what failed" }]; a failure clears done and verification and returns the task to in progress. For separate marks usetask.criterionverify withcriterionandrun, or fail withcriterionand a single-linenote. The verdict report lists its marks.
Epic demo procedure
- Epic demos (D16): when the Coordinator requests an epic, run its Definition of done at named
devSHA via demo lease (cland demo start|exec|status|stop;qaskill, "Epic demos"). No slot/budget: local at same SHA. Fresh: on dev, no later epic-file edits. Readtask.viewcriterion ids (containers also recognize## Definition of done), and record a clear QA verdict on the epic with the full tested SHA and every tested id verified in that run. All criteria must pass for closure; deferred or blocked checks remain unverified. The Coordinator closes the epic after its children are closed; only the release waits for human acceptance.
Coordinator request procedure
- The item’s lead requests review and QA and handles not-clear verdicts and retries. Before launching an item needing QA, commit
qa/briefs/T-<n>.mdviaqaand give its lead the path. Use theqaskill’s brief-lint completion rule. Launch missing verifiers withsession.launch. Lead an unclaimed item outside a claimed Lead subtree yourself;@lead T-<n>routes verdicts up. - The item’s lead requests review and QA and handles not-clear verdicts and retries. Before launching an item needing QA, commit
qa/briefs/T-<n>.mdviaqaand give its lead the path. Launch missing verifiers withsession.launch. Lead an unclaimed item outside a claimed Lead subtree yourself;@lead T-<n>routes verdicts up.
Declining an accepted verifier request (T-1494)
Reviewer and QA use verification.decline with request set to the delivered
msg_id and reason set to one nonempty line. The hub checks the caller's durable
session and exact accepted receipt, clears that pending reservation immediately,
and durably returns the reason and request id to the original requester's session
in the request topic. Missing agent identity or incomplete captured-ID delivery
admission refuses and retains pending; retry after identity recovery. Human
requests receive the notice in their topic. It records
no verdict and does not requeue the declined request; the requester decides the
next assignment. Other queued requests can use the released capacity immediately.
A stale id cannot release newer work, even on the same item or head. Existing
tracker holds remain separate: release an acquired hold with task.hold too.
Requests without a captured message receipt cannot be declined by guessing prose.
Verifier sessions must be relaunched after this tool lands: tools are fixed at
launch. Inherited roles with explicit tool lists must grant verification.decline
to Reviewer/QA; generated defaults include it. Older hubs refuse the new tool
without changing pending state; do not substitute a verdict to clear it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

