QA Pass With Handoff — Autonomous Agents Agentic Workflow

schema_version: 1
id: agent_qa_pass
title: "QA Pass With Handoff"
description: "Multi-session QA pass over a quality epic's task — checkpointed handoff, tracker bug filing, closing verdict"
overview: |
  The quality lane's multi-session pass. A QA task on a quality epic rarely fits one turn: an area has more
  scenarios than a single session can walk, and a task that seeds fixtures can only be judged once the runs it
  started have finished. This job therefore treats the ticket's own comments as its checkpoint — a handoff block
  from an earlier session names what is already covered and what remains, so the next agent resumes the walk
  instead of repeating it, and a session that finds a verdict already posted re-checks the acceptance criteria
  once and closes the task.

  Defects leave as tracker bugs rather than as prose buried in a comment. Each one is filed as its own issue,
  after a duplicate search against the bugs the lane has already raised, linked back to the QA task and given a
  priority from its severity, so the fix lane can pick it up independently. The report itself stays neutral:
  result cells read ok, defect or n/a, and the verdict token appears exactly once, on the last line, because the
  playbook gate scans the whole comment in routing order and a stray verdict word inside a table outranks the
  real one at the end.

category:
  level: pipeline
  domain: engineering

metadata:
  agent: true
  role: qa
  # Gate-verdict vocabulary for portal playbook steps (PLAYBOOKS.md §5) — matched from the
  # step's ticket comment; declaring it here is what makes this workflow content-routable.
  # HANDOFF is the session-continuation token: fresh, so it is matched token-only, and carried in
  # the loopback set of the step running this job — gate.retry is v1-allowlisted to agent_se_work —
  # so a closing step loops back to re-dispatch this same pass to the next session. The prompt below
  # therefore allows it ONLY as the final line of a handoff comment, and never inside a report.
  verdicts: [PASS, FAIL, HANDOFF, BLOCKED]

params:
  agentic_app:
    type: string
    default: "cc"
    description: "Agent-app slug selecting the per-run env file ~/.agent-env.d/<slug> (AAP-C); 'cc'/subscription clears provider vars"
  ticket_url:
    type: string
    description: "Jira ticket URL — the QA task this pass covers"
  depth:
    type: string
    default: "L3"
    description: "Max test depth: L0 (smoke), L1 (structure), L2 (interaction), L3 (data), L4 (edge)"
  hint:
    type: string
    default: ""
    description: "Optional extra instructions for the agent; also carries the CONTINUATION note on a re-dispatch"
  entry_path:
    type: string
    default: "~/workspace"
    description: "Working directory for the agent"

steps:
  - type: terminal.open
    title: "Agent: QA Pass"
    cwd: "{{entry_path}}"
  - type: terminal.run
    cmd: |
      source ~/.agent-env
      # AAP-C (SCRUM-1506) + AAP-17 (SCRUM-1653): clear EVERY provider var an agent-app can deliver so
      # none hijacks/poisons a subscription run. A stray global ANTHROPIC_MODEL / ANTHROPIC_SMALL_FAST_MODEL
      # needs no CLAUDE_CODE_USE_* flag, so the old ${!CLAUDE_CODE_USE_@} glob never caught it — it survived
      # into the run and 404-ed aux/small-fast calls against api.anthropic.com. This explicit list mirrors
      # AGENT_APP_ENV_KEYS 1:1 (the-assistant website/src/lib/cloud/agent-app-env.ts — the single source of
      # truth; a parity test in each repo guards the two from drifting). Explicit over a glob: the union has
      # non-ANTHROPIC_ members (AWS_REGION, AWS_PROFILE, CLOUD_ML_REGION, CLAUDE_CODE_MAX_OUTPUT_TOKENS) and
      # a ${!AWS_@} glob would over-clear unrelated creds. Then source the per-run app env by slug when it
      # exists; no file => subscription/default. base/19-secrets stages ~/.agent-env.d/<slug>.
      unset \
        ANTHROPIC_API_KEY ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN CCR_CONFIG_B64 \
        CLAUDE_CODE_USE_BEDROCK AWS_REGION AWS_PROFILE ANTHROPIC_MODEL \
        ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION ANTHROPIC_SMALL_FAST_MODEL CLAUDE_CODE_MAX_OUTPUT_TOKENS \
        CLAUDE_CODE_USE_VERTEX CLOUD_ML_REGION ANTHROPIC_VERTEX_PROJECT_ID ANTHROPIC_VERTEX_BASE_URL \
        CLAUDE_CODE_USE_FOUNDRY ANTHROPIC_FOUNDRY_RESOURCE ANTHROPIC_FOUNDRY_BASE_URL \
        ANTHROPIC_DEFAULT_OPUS_MODEL ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL
      if [ -f "$HOME/.agent-env.d/{{agentic_app}}" ]; then
        source "$HOME/.agent-env.d/{{agentic_app}}"
      fi
      claude --dangerously-skip-permissions "$(cat <<'SB_PROMPT'
      read ticket with attachments and all comments - {{ticket_url}}. if it fails, stop and report the error.
      then load the knowledge packs TOP-DOWN before you test anything: the domain root _skill.md, then that domain's qa role file, then the module _skill.md for every module the ticket names AND for every further module you discover is in scope while walking it, then each of those modules' qa.md. walk the module qa.md phases in their given order, up to depth {{depth}} (L0 smoke, L1 structure, L2 interaction, L3 data, L4 edge). a module with no qa.md is tested from its _skill.md Common Tasks instead. a pack that is stale or missing for a module in scope is itself a finding - say so, and test that module against the ticket directly.
      the ticket's scope and acceptance criteria define this pass. they are the baseline you judge against, not your own idea of what the area ought to do: every criterion gets a result, and anything you notice outside them is a note, not a result.
      EXECUTION RULES (read first — they override any habit):
      - Do ALL of the work in THIS session, in the FOREGROUND, and finish before your turn ends. You MAY spawn subagents (the Agent / Task tool) or run parallel searches to investigate faster — but you MUST wait for every subagent and any background task to return and fold their results in YOURSELF before ending the turn. Never move the work (or the comment) into the background — no run_in_background, no background workflows, no trailing & — and then end the turn expecting to be resumed. Ending your turn is FINAL here: nothing wakes you to "resume", so a turn that ends while a spawned subagent or any background work is still pending is reported as a FAILED step, not a pause.
      - Post the ticket comment YOURSELF, in the foreground, as the LAST thing you do — after every subagent and background task has returned. Never delegate that comment to a subagent, and never end the turn "holding", "pausing", or planning to "resume/continue later". If the pass genuinely does not fit this session, that is the handoff shape below: post it and stop. It is never a reason to leave work running past your turn.
      CONTINUATION: if a CONTINUATION note appears in the hint below, or the ticket carries a handoff comment from a previous session, this task is already mid-pass — read that checkpoint FIRST and continue from it. Do NOT restart the pass and do NOT re-run a scenario it already recorded a result for; walk what its checklist lists as remaining, plus anything its evidence shows it could not reach. If the checkpoint is unusable, say why in your comment before you start over.
      CLOSING SESSION: if the ticket already carries a comment from an earlier session of this same task whose last line is a verdict line (Verdict: PASS or Verdict: FAIL), this is the closing session. Do not re-walk the area: re-check the acceptance criteria and the scenarios that recorded a defect ONCE, against the fixes, runs and bugs that landed since that comment, then post the final verdict for the task. if the ticket carries BOTH a handoff comment and a verdict line, the LATER of the two decides which rule you are under: a verdict posted after the last handoff makes this the closing session, and a handoff posted after the last verdict means the closing re-check is itself mid-pass — continue that re-check from its checkpoint.
      ENVIRONMENT: set up your own data on your own account — create the workspaces, fixtures and runs this pass needs rather than reusing whatever happens to be lying around, so every failure is one you can reproduce from scratch. if the epic carries a sibling task labelled qa-fixture, load its map artifact FIRST and address only the ids that map names; it is the inventory this pass is meant to read. never navigate to, mutate, or report on another tenant's workspace, run, job, artifact or ticket — someone else's data is a leak, not evidence.
      BUGS: file one tracker Bug per defect, through the tracker tools, while this session is still open — a defect described only inside your comment is not filed. BEFORE creating one, search the OPEN Bugs labelled qa-found for the same symptom; on a match, add your evidence as a comment on that issue instead of opening a duplicate. each Bug carries: a title naming the symptom, the label qa-found, a "relates to" link to this ticket, a priority mapped from severity (P0 → Highest, P1 → High, P2 → Medium, P3 → Low), numbered repro steps, expected vs actual, the exact URL at the time of failure, and the published evidence link. your comment lists the resulting keys — created and commented-on — against the scenario that found them.
      REPORTING DISCIPLINE — the playbook gate string-matches your WHOLE comment, not just its last line, and it tests the verdicts in routing order (retry → loopback → pass → stop → pause), so one stray token anywhere in the body outranks the genuine one at the end. Report every scenario result NEUTRALLY, as one of three cell values: ok (behaved as the acceptance criteria say), defect (cite the Bug key you filed or commented on) or n/a (not applicable, or not reachable — say which). Never the bare words pass/fail/passed/failed, in any case, in a cell, a heading or a sentence, and never the word blocked. Describe a finding, do not label it: "the priority select keeps its old value after save", not "priority: failed". Keep the verdict token itself out of the body entirely — it appears exactly once, on the last line.
      {{hint}}
      FINISH — your LAST action is exactly ONE ticket comment, in exactly ONE of these three shapes:
      1. REPORT — this session reached a verdict for the task: the coverage matrix (module or area × depth level, cells ok/defect/n/a), the per-scenario results (scenario, result, notes), the Bugs filed or commented on with their keys, the evidence links, and as the LAST line either "Verdict: PASS" when every acceptance criterion holds and no defect stands against one, or "Verdict: FAIL" when one or more do not. The tokens HANDOFF and BLOCKED appear nowhere in this shape.
      2. HANDOFF — the pass does not fit this session, or its outcome cannot be judged until runs already started have finished: FIRST publish the evidence and the results artifact for everything you did cover, THEN post a block carrying what is done (the scenarios walked, with their results), what remains (a concrete checklist of the scenarios still to walk), the single next step the next session starts from, the evidence links, and the run and job ids anything in flight is waiting on. End the comment with the token HANDOFF alone on its own last line. The platform dispatches another session to continue from that block. Write no verdict line in this shape.
      3. BLOCKED — a missing decision, credential, access or environment stops the pass entirely: state what blocks it and what would unblock it. End the comment with the token BLOCKED alone on its own last line. Write no verdict line in this shape.
      Never mix the shapes: HANDOFF and BLOCKED are routing tokens — each may appear ONLY as the final line of its own shape, and a report contains neither.
      EVIDENCE: publish as you go, not at the end. Run publish_artifact per test step for the screenshot or extract that step produced, and once per session for the results artifact <area>-qa-results-<n>.md (n is this session's number on the task — 1 for the first, 2 for the next), then cite the returned download links in the comment above. If publish_artifact is unavailable, save every file under ~/workspace/artifacts/ for post-run collection, as in the other QA jobs. Keep evidence filenames free of verdict words.
      SB_PROMPT
      )"