@hiver/skills 1.0.7 → 1.0.9

package/collections/qa-skills/qa-suite-guide.html

@@ -0,0 +1,760 @@
+<title>QA to release in one conversation — the Hiver qa-suite</title>
+<style>
+  :root {
+    --bg: #f5f7f9;
+    --surface: #ffffff;
+    --surface-2: #eef1f5;
+    --ink: #12151c;
+    --muted: #59616f;
+    --faint: #8b93a1;
+    --line: #e2e6ec;
+    --line-strong: #cbd2dc;
+    --accent: #2f5fe0;
+    --accent-ink: #1e46b6;
+    --accent-wash: #eaf0fe;
+    --pass: #17915a;
+    --fail: #d24141;
+    --warn: #b9791a;
+    --skip: #7f8895;
+    --pass-wash: #e6f4ec;
+    --fail-wash: #fbeaea;
+    --warn-wash: #f8f0e0;
+
+    --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, "Helvetica Neue", Arial, sans-serif;
+    --mono: ui-monospace, "SF Mono", "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
+
+    --maxw: 940px;
+    --radius: 12px;
+    --shadow: 0 1px 2px rgba(16,21,28,.04), 0 6px 20px rgba(16,21,28,.06);
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0c0e13;
+      --surface: #14171e;
+      --surface-2: #1b1f29;
+      --ink: #e9ecf2;
+      --muted: #9aa3b2;
+      --faint: #69727f;
+      --line: #262b35;
+      --line-strong: #333a46;
+      --accent: #6f9bff;
+      --accent-ink: #a6c1ff;
+      --accent-wash: #172236;
+      --pass: #40c185;
+      --fail: #f1685f;
+      --warn: #e2a541;
+      --skip: #7f8896;
+      --pass-wash: #12241b;
+      --fail-wash: #2a1616;
+      --warn-wash: #271f11;
+    }
+  }
+  :root[data-theme="dark"] {
+    --bg: #0c0e13; --surface: #14171e; --surface-2: #1b1f29; --ink: #e9ecf2;
+    --muted: #9aa3b2; --faint: #69727f; --line: #262b35; --line-strong: #333a46;
+    --accent: #6f9bff; --accent-ink: #a6c1ff; --accent-wash: #172236;
+    --pass: #40c185; --fail: #f1685f; --warn: #e2a541; --skip: #7f8896;
+    --pass-wash: #12241b; --fail-wash: #2a1616; --warn-wash: #271f11;
+  }
+  :root[data-theme="light"] {
+    --bg: #f5f7f9; --surface: #ffffff; --surface-2: #eef1f5; --ink: #12151c;
+    --muted: #59616f; --faint: #8b93a1; --line: #e2e6ec; --line-strong: #cbd2dc;
+    --accent: #2f5fe0; --accent-ink: #1e46b6; --accent-wash: #eaf0fe;
+    --pass: #17915a; --fail: #d24141; --warn: #b9791a; --skip: #7f8895;
+    --pass-wash: #e6f4ec; --fail-wash: #fbeaea; --warn-wash: #f8f0e0;
+  }
+
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--ink);
+    font-family: var(--sans); line-height: 1.6;
+    -webkit-font-smoothing: antialiased; font-size: 17px;
+  }
+  .wrap { max-width: var(--maxw); margin: 0 auto; padding: 0 24px; }
+
+  a { color: var(--accent-ink); text-decoration: none; border-bottom: 1px solid color-mix(in srgb, var(--accent) 35%, transparent); }
+  a:hover { border-bottom-color: var(--accent); }
+
+  code, .mono { font-family: var(--mono); font-size: .88em; }
+  :not(pre) > code {
+    background: var(--surface-2); border: 1px solid var(--line);
+    padding: .08em .38em; border-radius: 5px; color: var(--ink);
+    white-space: nowrap;
+  }
+
+  h1, h2, h3 { line-height: 1.15; text-wrap: balance; letter-spacing: -.02em; font-weight: 800; }
+
+  /* ---------- top bar ---------- */
+  .topbar {
+    position: sticky; top: 0; z-index: 20;
+    background: color-mix(in srgb, var(--bg) 86%, transparent);
+    backdrop-filter: blur(10px); -webkit-backdrop-filter: blur(10px);
+    border-bottom: 1px solid var(--line);
+  }
+  .topbar .wrap { display: flex; align-items: center; gap: 14px; height: 56px; }
+  .brand { font-family: var(--mono); font-weight: 600; font-size: 14px; letter-spacing: -.01em; display: flex; align-items: center; gap: 9px; }
+  .brand .dot { width: 9px; height: 9px; border-radius: 50%; background: var(--accent); box-shadow: 0 0 0 4px var(--accent-wash); }
+  .brand b { color: var(--accent-ink); font-weight: 700; }
+  .topbar .cmd { margin-left: auto; font-family: var(--mono); font-size: 13px; color: var(--muted); }
+  .topbar .cmd b { color: var(--ink); }
+
+  /* ---------- hero ---------- */
+  .hero { padding: 68px 0 44px; border-bottom: 1px solid var(--line); }
+  .eyebrow {
+    font-family: var(--mono); font-size: 12.5px; letter-spacing: .14em; text-transform: uppercase;
+    color: var(--accent-ink); font-weight: 600; margin: 0 0 18px;
+  }
+  .hero h1 { font-size: clamp(34px, 6vw, 58px); margin: 0 0 20px; }
+  .hero h1 .fade { color: var(--muted); }
+  .hero .lede { font-size: clamp(18px, 2.4vw, 21px); color: var(--muted); max-width: 62ch; margin: 0 0 30px; }
+  .startline {
+    display: inline-flex; align-items: center; gap: 12px; flex-wrap: wrap;
+    background: var(--surface); border: 1px solid var(--line); border-radius: 999px;
+    padding: 9px 9px 9px 20px; box-shadow: var(--shadow);
+  }
+  .startline .label { font-size: 14px; color: var(--muted); }
+  .startline .chip {
+    font-family: var(--mono); font-weight: 600; font-size: 15px; color: #fff;
+    background: var(--accent); padding: 8px 16px; border-radius: 999px; letter-spacing: -.01em;
+  }
+  .stats { display: grid; grid-template-columns: repeat(4, 1fr); gap: 1px; background: var(--line);
+    border: 1px solid var(--line); border-radius: var(--radius); overflow: hidden; margin-top: 40px; }
+  .stat { background: var(--surface); padding: 20px 18px; }
+  .stat .n { font-family: var(--mono); font-weight: 700; font-size: 27px; color: var(--accent-ink); letter-spacing: -.03em; }
+  .stat .k { font-size: 13.5px; color: var(--muted); margin-top: 4px; }
+
+  /* ---------- generic section ---------- */
+  section { padding: 56px 0; border-bottom: 1px solid var(--line); }
+  .sec-eyebrow { font-family: var(--mono); font-size: 12px; letter-spacing: .16em; text-transform: uppercase; color: var(--faint); font-weight: 600; margin: 0 0 12px; }
+  section h2 { font-size: clamp(25px, 3.6vw, 33px); margin: 0 0 16px; }
+  section > .wrap > p { color: var(--muted); max-width: 68ch; }
+  section > .wrap > p strong, li strong { color: var(--ink); font-weight: 650; }
+
+  /* ---------- callout ---------- */
+  .note {
+    border-left: 3px solid var(--accent); background: var(--accent-wash);
+    padding: 16px 20px; border-radius: 0 10px 10px 0; margin: 26px 0; color: var(--ink);
+  }
+  .note.warnbox { border-left-color: var(--warn); background: var(--warn-wash); }
+  .note .tag { font-family: var(--mono); font-size: 11.5px; letter-spacing: .12em; text-transform: uppercase; font-weight: 700; color: var(--accent-ink); display: block; margin-bottom: 6px; }
+  .note.warnbox .tag { color: var(--warn); }
+  .note p { margin: 0; font-size: 15.5px; color: var(--muted); }
+  .note p + p { margin-top: 8px; }
+
+  /* ---------- spine diagram ---------- */
+  .spine { position: relative; margin: 8px 0 0; padding-left: 4px; }
+  .spine::before {
+    content: ""; position: absolute; left: 21px; top: 12px; bottom: 12px; width: 2px;
+    background: linear-gradient(var(--accent), color-mix(in srgb, var(--accent) 30%, var(--line)));
+  }
+  .station { position: relative; padding: 0 0 22px 62px; }
+  .station:last-child { padding-bottom: 0; }
+  .station .node {
+    position: absolute; left: 10px; top: 2px; width: 24px; height: 24px; border-radius: 50%;
+    background: var(--surface); border: 2px solid var(--accent); display: grid; place-items: center;
+    font-family: var(--mono); font-size: 11px; font-weight: 700; color: var(--accent-ink); z-index: 1;
+  }
+  .station.human .node { border-color: var(--warn); color: var(--warn); }
+  .station.human::after { }
+  .station .card {
+    background: var(--surface); border: 1px solid var(--line); border-radius: 11px; padding: 15px 17px;
+    box-shadow: var(--shadow);
+  }
+  .station .card.branch { border-style: dashed; }
+  .station .row1 { display: flex; align-items: baseline; gap: 10px; flex-wrap: wrap; }
+  .station .skill { font-family: var(--mono); font-weight: 700; font-size: 15px; color: var(--ink); }
+  .station .kind { font-family: var(--mono); font-size: 11px; letter-spacing: .08em; text-transform: uppercase;
+    padding: 2px 8px; border-radius: 999px; border: 1px solid var(--line-strong); color: var(--muted); }
+  .station .kind.auto { color: var(--accent-ink); border-color: color-mix(in srgb, var(--accent) 45%, transparent); background: var(--accent-wash); }
+  .station .kind.man { color: var(--warn); border-color: color-mix(in srgb, var(--warn) 45%, transparent); background: var(--warn-wash); }
+  .station .desc { color: var(--muted); font-size: 15px; margin-top: 6px; }
+  .station .desc b { color: var(--ink); font-weight: 620; }
+
+  .legend-inline { display: flex; gap: 18px; flex-wrap: wrap; margin: 22px 0 4px; font-size: 13.5px; color: var(--muted); }
+  .legend-inline span { display: inline-flex; align-items: center; gap: 7px; }
+  .swatch { width: 13px; height: 13px; border-radius: 4px; border: 2px solid var(--accent); }
+  .swatch.man { border-color: var(--warn); }
+
+  /* ---------- run dir tree ---------- */
+  .tree {
+    background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius);
+    padding: 20px 22px; overflow-x: auto; box-shadow: var(--shadow); margin: 24px 0 0;
+  }
+  .tree pre { margin: 0; font-family: var(--mono); font-size: 13px; line-height: 1.75; color: var(--muted); }
+  .tree pre b { color: var(--ink); font-weight: 600; }
+  .tree pre .c { color: var(--faint); }
+  .tree pre .a { color: var(--accent-ink); }
+
+  /* ---------- station deep-dive grid ---------- */
+  .agent {
+    background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius);
+    padding: 22px 24px; margin: 18px 0; box-shadow: var(--shadow);
+  }
+  .agent > header { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; margin-bottom: 4px; }
+  .agent .id { font-family: var(--mono); font-weight: 700; font-size: 18px; color: var(--ink); letter-spacing: -.01em; }
+  .agent .tagline { color: var(--muted); font-size: 15px; margin: 6px 0 16px; }
+  .io { display: grid; grid-template-columns: 1fr 1fr; gap: 1px; background: var(--line); border: 1px solid var(--line); border-radius: 9px; overflow: hidden; }
+  .io > div { background: var(--surface-2); padding: 12px 15px; }
+  .io .h { font-family: var(--mono); font-size: 11px; letter-spacing: .12em; text-transform: uppercase; color: var(--faint); font-weight: 700; margin-bottom: 6px; }
+  .io .b { font-size: 14px; color: var(--muted); }
+  .io .b code { font-size: .85em; }
+  .agent .meta { margin-top: 14px; font-size: 14px; color: var(--muted); display: flex; flex-direction: column; gap: 7px; }
+  .agent .meta b { color: var(--ink); font-weight: 620; font-family: var(--mono); font-size: 12.5px; letter-spacing: .04em; }
+
+  .grouphdr { display: flex; align-items: center; gap: 14px; margin: 40px 0 4px; }
+  .grouphdr .n { font-family: var(--mono); font-size: 13px; font-weight: 700; color: #fff; background: var(--accent);
+    width: 28px; height: 28px; border-radius: 8px; display: grid; place-items: center; flex: none; }
+  .grouphdr h3 { font-size: 20px; margin: 0; }
+  .grouphdr.man .n { background: var(--warn); }
+
+  /* ---------- signals ---------- */
+  .signals { display: grid; grid-template-columns: repeat(2, 1fr); gap: 12px; margin-top: 8px; }
+  .sig { display: flex; gap: 13px; align-items: flex-start; background: var(--surface); border: 1px solid var(--line);
+    border-radius: 10px; padding: 14px 16px; }
+  .sig .mark { font-size: 20px; line-height: 1; flex: none; margin-top: 1px; }
+  .sig .t { font-weight: 700; font-size: 15px; }
+  .sig .d { font-size: 13.5px; color: var(--muted); margin-top: 2px; }
+  .sig.pass { border-left: 3px solid var(--pass); }
+  .sig.fail { border-left: 3px solid var(--fail); }
+  .sig.warn { border-left: 3px solid var(--warn); }
+  .sig.skip { border-left: 3px solid var(--skip); }
+
+  /* ---------- tables ---------- */
+  .tablewrap { overflow-x: auto; border: 1px solid var(--line); border-radius: var(--radius); box-shadow: var(--shadow); margin-top: 8px; }
+  table { border-collapse: collapse; width: 100%; font-size: 14.5px; min-width: 560px; }
+  th, td { text-align: left; padding: 12px 15px; border-bottom: 1px solid var(--line); vertical-align: top; }
+  thead th { background: var(--surface-2); font-size: 12px; letter-spacing: .06em; text-transform: uppercase; color: var(--muted); font-weight: 700; }
+  tbody tr:last-child td { border-bottom: none; }
+  tbody tr { background: var(--surface); }
+  td .mono, th .mono { color: var(--accent-ink); font-weight: 600; }
+  td.owner { font-family: var(--mono); font-size: 12.5px; color: var(--accent-ink); font-weight: 600; }
+
+  /* ---------- ordered steps (day in the life) ---------- */
+  ol.walk { counter-reset: step; list-style: none; padding: 0; margin: 8px 0 0; }
+  ol.walk li { position: relative; padding: 4px 0 20px 46px; border-left: 2px solid var(--line); margin-left: 13px; }
+  ol.walk li:last-child { border-left-color: transparent; padding-bottom: 0; }
+  ol.walk li::before {
+    counter-increment: step; content: counter(step);
+    position: absolute; left: -14px; top: 0; width: 26px; height: 26px; border-radius: 50%;
+    background: var(--surface); border: 2px solid var(--accent); color: var(--accent-ink);
+    font-family: var(--mono); font-weight: 700; font-size: 12px; display: grid; place-items: center;
+  }
+  ol.walk li b { color: var(--ink); }
+  ol.walk li .who { font-family: var(--mono); font-size: 12px; color: var(--accent-ink); }
+  ol.walk li.human::before { border-color: var(--warn); color: var(--warn); }
+  ol.walk li.human .who { color: var(--warn); }
+
+  /* ---------- install ---------- */
+  .terminal { background: #0c0e13; border: 1px solid var(--line-strong); border-radius: var(--radius); overflow: hidden; margin-top: 8px; box-shadow: var(--shadow); }
+  .terminal .bar { display: flex; gap: 7px; padding: 12px 15px; border-bottom: 1px solid #23272f; }
+  .terminal .bar i { width: 11px; height: 11px; border-radius: 50%; display: block; }
+  .terminal .bar i:nth-child(1){ background:#ff5f57;} .terminal .bar i:nth-child(2){ background:#febc2e;} .terminal .bar i:nth-child(3){ background:#28c840;}
+  .terminal pre { margin: 0; padding: 18px 20px; font-family: var(--mono); font-size: 13.5px; line-height: 1.9; color: #cfd6e0; overflow-x: auto; }
+  .terminal pre .p { color: #6f9bff; }
+  .terminal pre .c { color: #6a7382; }
+  .terminal pre b { color: #fff; font-weight: 600; }
+
+  ul.clean { padding-left: 0; list-style: none; margin: 16px 0 0; display: flex; flex-direction: column; gap: 10px; }
+  ul.clean li { position: relative; padding-left: 26px; color: var(--muted); font-size: 15.5px; }
+  ul.clean li::before { content: ""; position: absolute; left: 4px; top: 11px; width: 7px; height: 7px; border-radius: 2px; background: var(--accent); }
+  ul.clean li b { color: var(--ink); font-weight: 620; }
+
+  footer { padding: 40px 0 60px; color: var(--faint); font-size: 13.5px; }
+  footer .wrap { display: flex; justify-content: space-between; gap: 16px; flex-wrap: wrap; align-items: center; }
+  footer .mono { color: var(--muted); }
+
+  @media (max-width: 720px) {
+    body { font-size: 16px; }
+    .stats { grid-template-columns: repeat(2, 1fr); }
+    .io { grid-template-columns: 1fr; }
+    .signals { grid-template-columns: 1fr; }
+    .topbar .cmd { display: none; }
+  }
+  @media (prefers-reduced-motion: reduce) { * { scroll-behavior: auto; } }
+</style>
+
+<header class="topbar">
+  <div class="wrap">
+    <span class="brand"><span class="dot"></span> qa-suite <b>· Hiver QA</b></span>
+    <span class="cmd">start with <b>/qa-kit</b></span>
+  </div>
+</header>
+
+<div class="hero">
+  <div class="wrap">
+    <p class="eyebrow">Field guide · for QA engineers &amp; SDETs</p>
+    <h1>Take a feature from QA<br><span class="fade">to release in one conversation.</span></h1>
+    <p class="lede">
+      <code>qa-suite</code> is a team of QA agents that hand work to each other inside a single chat.
+      You open with one command; the spec, the test plan, the browser run, the bugs, the release gate,
+      and the automation PR all happen in that same thread. This guide shows what runs when — and where
+      <em>you</em> take the wheel.
+    </p>
+    <span class="startline">
+      <span class="label">Everything begins by typing</span>
+      <span class="chip">/qa-kit</span>
+    </span>
+
+    <div class="stats">
+      <div class="stat"><div class="n">1</div><div class="k">conversation, start to ship</div></div>
+      <div class="stat"><div class="n">9</div><div class="k">specialist agents on the relay</div></div>
+      <div class="stat"><div class="n">2</div><div class="k">test tracks — UI &amp; API</div></div>
+      <div class="stat"><div class="n">4</div><div class="k">verdict signals: ✅ ❌ ⚠️ ⏭️</div></div>
+    </div>
+  </div>
+</div>
+
+<!-- ================= BIG IDEA ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">The big idea</p>
+    <h2>One conversation is one run — and the run remembers everything</h2>
+    <p>
+      The reason a whole team of agents can relay a feature without ever re-asking you the same
+      question twice is a single design decision: <strong>handoffs are files, not chat messages.</strong>
+      The first agent to run mints a <em>run directory</em> and drops a pointer to it in
+      <code>qa-output/.current-run</code>. Every agent after that reads that pointer, picks up the shared
+      <code>handoff.json</code>, does its job, writes its output back into the same folder, and advances
+      the baton. The chat is the conversation; the run directory is the memory.
+    </p>
+
+    <div class="tree">
+<pre><span class="c"># the shared memory for a single feature's QA pass</span>
+qa-output/
+  <b>.current-run</b>                      <span class="c"># → points every agent at the active run</span>
+  hiver-notes/
+    <b>hiver-notes-20260713-1530/</b>
+      <span class="a">handoff.json</span>                  <span class="c"># the baton: who → whom, + all context so far</span>
+      <span class="a">tracker.xlsx</span>                  <span class="c"># the source of truth for cases &amp; pass/fail</span>
+      handoffs/<span class="c"> …-to-….json         # audit trail, one file per boundary crossed</span>
+      steps/<span class="c">   &lt;skill&gt;-&lt;phase&gt;.json   # what each agent produced (for the judge)</span>
+      logs/<span class="c">    &lt;skill&gt;.jsonl         # forensic trace of what each agent did</span>
+      screenshots/<span class="c">                    # evidence from the browser run</span>
+      trace/<span class="c">   report.md             # qa-eval's quality verdict, written at the end</span>
+      spec.md<span class="c">                         # the feature spec (if hiver-explore built one)</span></pre>
+    </div>
+
+    <div class="note">
+      <span class="tag">Why this matters to you</span>
+      <p>You can walk away mid-run and come back. You can hand the chat to a teammate. The tracker has strict
+      <strong>column ownership</strong> — the author agent writes the cases, the run agent writes
+      <em>Testing&nbsp;1</em>, <strong>you</strong> own <em>Testing&nbsp;2</em>, and qa-bugs writes the ticket links.
+      Nobody overwrites anybody. Every stage is independently re-runnable.</p>
+    </div>
+  </div>
+</section>
+
+<!-- ================= THE MAP ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">The map</p>
+    <h2>What runs, in order</h2>
+    <p>
+      <code>/qa-kit</code> is the only thing you have to remember. It gathers your inputs, reads the code
+      diff, interviews you, classifies the change, sizes the effort, and drives the relay.
+      Here is the spine. Blue stations are agents; amber stations are where a human steps in.
+    </p>
+
+    <div class="legend-inline">
+      <span><i class="swatch"></i> agent step (Claude drives)</span>
+      <span><i class="swatch man"></i> human step (you drive)</span>
+    </div>
+
+    <div class="spine">
+      <div class="station">
+        <span class="node">0</span>
+        <div class="card">
+          <div class="row1"><span class="skill">/qa-kit</span><span class="kind auto">orchestrator</span></div>
+          <div class="desc"><b>Front door.</b> Gathers inputs (PR/branch, PRD, Figma), reads the code diff,
+            interviews you, classifies the change <b>UI / API / new-API / mixed</b>, sizes the effort, and routes.</div>
+        </div>
+      </div>
+      <div class="station">
+        <span class="node">↑</span>
+        <div class="card branch">
+          <div class="row1"><span class="skill">hiver-explore</span><span class="kind auto">feeder · only if no spec</span></div>
+          <div class="desc">No PRD? It reads help.hiverhq.com, drives the live feature, and writes a Confluence-style
+            <code>spec.md</code> — then hands back to qa-kit.</div>
+        </div>
+      </div>
+      <div class="station">
+        <span class="node">1</span>
+        <div class="card">
+          <div class="row1"><span class="skill">qa-ui-author</span><span class="kind auto">authoring</span>
+            <span class="mono" style="color:var(--faint);font-size:12px">/ qa-api-author</span></div>
+          <div class="desc">Turns the spec into a <b>Word test plan + the Excel tracker</b>. No browser yet — just cases.</div>
+        </div>
+      </div>
+      <div class="station">
+        <span class="node">2</span>
+        <div class="card">
+          <div class="row1"><span class="skill">qa-ui-run</span><span class="kind auto">round 1</span>
+            <span class="mono" style="color:var(--faint);font-size:12px">/ qa-api-run</span></div>
+          <div class="desc"><b>The browser first pass.</b> Connects to your logged-in Chrome tab and runs every
+            testable case, recording ✅ ❌ ⚠️ ⏭️ + screenshots into the tracker.</div>
+        </div>
+      </div>
+      <div class="station">
+        <span class="node">3</span>
+        <div class="card">
+          <div class="row1"><span class="skill">qa-bugs</span><span class="kind auto">bug sink</span></div>
+          <div class="desc">Every confirmed ❌/⚠️ becomes a <b>ClickUp ticket</b> — repro, expected, actual, evidence attached.</div>
+        </div>
+      </div>
+      <div class="station human">
+        <span class="node">▲</span>
+        <div class="card">
+          <div class="row1"><span class="skill">you — manual QA</span><span class="kind man">human takes over</span></div>
+          <div class="desc">Pick up the <b>⏭️ skipped</b> cases (credentials, multi-account, backend-failure) into the
+            <em>Testing 2</em> column, and do the <b>exploratory testing</b> only a human can — edge cases, odd states, "what if I…".</div>
+        </div>
+      </div>
+      <div class="station human">
+        <span class="node">◆</span>
+        <div class="card">
+          <div class="row1"><span class="skill">release gate</span><span class="kind man">you + LaunchDarkly</span></div>
+          <div class="desc">Signed off? In the <b>same chat</b>, connect the LaunchDarkly MCP (or paste the flag JSON) to update
+            the enrolment list and <b>control the rollout</b> account by account.</div>
+        </div>
+      </div>
+      <div class="station">
+        <span class="node">4</span>
+        <div class="card">
+          <div class="row1"><span class="skill">playwright-gen</span><span class="kind auto">automation</span></div>
+          <div class="desc">Turns the <b>passing</b> cases into real, runnable <code>.spec.ts</code>, runs them, writes results
+            back, and opens the <b>automation PR</b> for an SDET to pull.</div>
+        </div>
+      </div>
+      <div class="station">
+        <span class="node">✓</span>
+        <div class="card">
+          <div class="row1"><span class="skill">qa-eval</span><span class="kind auto">independent judge</span></div>
+          <div class="desc">Runs automatically at the end. Grades every agent's output <b>PASS / DEGRADED / FAIL</b>
+            and writes <code>trace/report.md</code>. Warns; never blocks.</div>
+        </div>
+      </div>
+    </div>
+
+    <div class="note">
+      <span class="tag">Mixed changes get both tracks</span>
+      <p>When a change touches both surfaces, qa-kit runs the UI and API tracks against the
+      <strong>same run directory and the same tracker</strong> (UI vs API column blocks) — so one feature
+      still means one conversation and one source of truth.</p>
+    </div>
+  </div>
+</section>
+
+<!-- ================= DEEP DIVE ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">Station by station</p>
+    <h2>Every agent — what it needs, what it leaves behind, who calls it</h2>
+    <p>You rarely invoke these by name — qa-kit routes to them and they chain to each other. But knowing each
+      one's job tells you exactly where to intervene.</p>
+
+    <!-- FRONT DOOR -->
+    <div class="grouphdr"><span class="n">A</span><h3>The front door &amp; the feeder</h3></div>
+
+    <div class="agent">
+      <header><span class="id">qa-kit</span><span class="kind auto" style="font-family:var(--mono);font-size:11px;letter-spacing:.08em;text-transform:uppercase;padding:2px 8px;border-radius:999px;border:1px solid;">orchestrator</span></header>
+      <div class="tagline">The single command you actually type. Triages and routes — it never writes cases itself.</div>
+      <div class="io">
+        <div><div class="h">Reads</div><div class="b">PR/branch diff (<code>gh pr diff</code>), PRD via Atlassian MCP <em>or</em> pasted text, Figma link, your interview answers</div></div>
+        <div><div class="h">Writes</div><div class="b">Triage Summary + <code>handoff.json</code> with classification, product (HIG/Omni/Both) &amp; effort</div></div>
+      </div>
+      <div class="meta">
+        <span><b>DECIDES</b> UI · API · new-API · mixed → which track(s) run</span>
+        <span><b>SIZES IT</b> smoke · standard · exhaustive</span>
+        <span><b>YOU CONFIRM</b> the classification &amp; effort before it routes</span>
+      </div>
+    </div>
+
+    <div class="agent">
+      <header><span class="id">hiver-explore</span></header>
+      <div class="tagline">The upstream feeder — only runs when there's no spec to work from.</div>
+      <div class="io">
+        <div><div class="h">Reads</div><div class="b">help.hiverhq.com docs + the live feature in your Chrome session</div></div>
+        <div><div class="h">Writes</div><div class="b">A Confluence-style <code>spec.md</code> (user stories, rules, edge cases, live selectors &amp; quirks)</div></div>
+      </div>
+      <div class="meta">
+        <span><b>MINTS THE RUN</b> when it starts the chain, then hands to qa-kit</span>
+        <span><b>TAGS EVERYTHING</b> [D] from docs · [L] from live UI · [D≠L] discrepancy = a risk</span>
+      </div>
+    </div>
+
+    <!-- UI TRACK -->
+    <div class="grouphdr"><span class="n">B</span><h3>The UI track</h3></div>
+
+    <div class="agent">
+      <header><span class="id">qa-ui-author</span></header>
+      <div class="tagline">Turns the spec into paper: a Word test plan and the Excel tracker. No browser.</div>
+      <div class="io">
+        <div><div class="h">Reads</div><div class="b"><code>handoff.json</code> → spec, product, effort, Figma, risks</div></div>
+        <div><div class="h">Writes</div><div class="b"><code>TestPlan_*.docx</code> + <code>tracker.xlsx</code> (it owns the case columns)</div></div>
+      </div>
+      <div class="meta">
+        <span><b>ONE BATCH</b> of clarifying questions for you to take to PM/dev</span>
+        <span><b>EFFORT SIZES IT</b> smoke ≈ 8–12 · standard ≈ 20–40 · exhaustive = full coverage</span>
+      </div>
+    </div>
+
+    <div class="agent">
+      <header><span class="id">qa-ui-run</span></header>
+      <div class="tagline">Round 1 — the browser first pass. This is the one that drives Hiver in front of you.</div>
+      <div class="io">
+        <div><div class="h">Reads</div><div class="b">The tracker's cases + product (picks the HIG-in-Gmail or Omni surface)</div></div>
+        <div><div class="h">Writes</div><div class="b"><em>Initial Behaviour – Testing 1</em> (✅/❌/⚠️/⏭️) + screenshots for every ❌/⚠️</div></div>
+      </div>
+      <div class="meta">
+        <span><b>CONNECTS TO YOU</b> attaches to your already-logged-in Chrome tab — it never logs in for you</span>
+        <span><b>SKIPS &amp; SAYS WHY</b> multi-account, backend-failure sim, credential entry → ⏭️ for a human</span>
+        <span><b>OPTIONAL</b> flow-capture records the API traffic behind passing flows for the API track</span>
+      </div>
+    </div>
+
+    <!-- API TRACK -->
+    <div class="grouphdr"><span class="n">C</span><h3>The API track</h3></div>
+
+    <div class="agent">
+      <header><span class="id">qa-api-author</span></header>
+      <div class="tagline">Documents API cases — endpoint, method, auth, payload, expected status/body. No live calls.</div>
+      <div class="io">
+        <div><div class="h">Reads</div><div class="b">The change's endpoints from the diff/spec (or a captured flow)</div></div>
+        <div><div class="h">Writes</div><div class="b">The API column block of the tracker + a light plan</div></div>
+      </div>
+      <div class="meta"><span><b>SAFE</b> authoring only — it never touches a live environment</span></div>
+    </div>
+
+    <div class="agent">
+      <header><span class="id">qa-api-run</span></header>
+      <div class="tagline">Executes the API cases against staging — opt-in and safety-gated.</div>
+      <div class="io">
+        <div><div class="h">Reads</div><div class="b">The tracker's API cases, <em>or</em> a PASS flow recording from flow-capture</div></div>
+        <div><div class="h">Writes</div><div class="b">Actual status + body back into the tracker; failures to qa-bugs</div></div>
+      </div>
+      <div class="meta">
+        <span><b>STAGING ONLY</b> never production; destructive calls are gated</span>
+        <span><b>RE-AUTHS</b> uses a fresh token — never replays a captured bearer; tokens redacted</span>
+      </div>
+    </div>
+
+    <!-- SHARED BUG SINK -->
+    <div class="grouphdr"><span class="n">D</span><h3>The shared bug sink</h3></div>
+
+    <div class="agent">
+      <header><span class="id">qa-bugs</span></header>
+      <div class="tagline">The one place bug tickets are born, so UI and API bugs look identical.</div>
+      <div class="io">
+        <div><div class="h">Reads</div><div class="b">The failing cases from <code>handoff.json</code> (or TC IDs you name)</div></div>
+        <div><div class="h">Writes</div><div class="b">One ClickUp ticket per confirmed bug + tracker <em>Status→Bug</em>, <em>Notes→link</em></div></div>
+      </div>
+      <div class="meta"><span><b>NEVER FILES BLIND</b> no ticket without attached evidence; one bug = one ticket</span></div>
+    </div>
+
+    <!-- AUTOMATION + JUDGE -->
+    <div class="grouphdr"><span class="n">E</span><h3>Automation &amp; the judge</h3></div>
+
+    <div class="agent">
+      <header><span class="id">playwright-gen</span></header>
+      <div class="tagline">The bridge from confirmed cases to running automated tests + a PR.</div>
+      <div class="io">
+        <div><div class="h">Reads</div><div class="b">The <b>passing</b>, automatable cases + the poc-playwright repo's existing page objects</div></div>
+        <div><div class="h">Writes</div><div class="b"><code>specs/&lt;feature&gt;.spec.ts</code>, runs it, Allure report, results back to tracker, opens the PR</div></div>
+      </div>
+      <div class="meta">
+        <span><b>REUSE, NEVER HALLUCINATE</b> maps steps onto real page-object methods; flags a missing one, never invents a selector</span>
+        <span><b>SDET PICKS IT UP</b> ~80–90% expected to pass on a live build; the rest is a human's last mile</span>
+      </div>
+    </div>
+
+    <div class="agent">
+      <header><span class="id">qa-eval</span></header>
+      <div class="tagline">The independent inspector. Reads every step record and grades output quality.</div>
+      <div class="io">
+        <div><div class="h">Reads</div><div class="b">Every <code>steps/*.json</code> + the artefacts they produced</div></div>
+        <div><div class="h">Writes</div><div class="b"><code>trace/report.md</code> — per-agent PASS/DEGRADED/FAIL + where quality first broke</div></div>
+      </div>
+      <div class="meta">
+        <span><b>WARN, NEVER BLOCK</b> a FAIL is a loud flag, not a halt — you decide what to do</span>
+        <span><b>INDEPENDENT</b> never trusts an agent's own self-check as the verdict</span>
+      </div>
+    </div>
+  </div>
+</section>
+
+<!-- ================= WHERE YOU TAKE OVER ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">The human's job</p>
+    <h2>Round 1 is Claude's. Round 2 is yours.</h2>
+    <p>
+      This system is deliberately <strong>not</strong> trying to replace you. The browser first pass clears the
+      repetitive, mechanical coverage so your hours go where machines can't. Two things are explicitly handed back:
+    </p>
+
+    <ul class="clean">
+      <li><b>The ⏭️ Skipped cases.</b> Anything that needs a real credential typed, two accounts open at once, a
+        simulated backend failure, or an OAuth handshake gets marked <em>Skipped — test manually</em> with the reason.
+        You run these into the <em>Testing 2</em> column, which is yours alone.</li>
+      <li><b>Exploratory testing.</b> While the tracker cases are covered, you go off-script — poke the edges, chase the
+        "that's weird…" moments, and find the behaviours no written case predicted. That's the judgment the pipeline
+        is buying time for.</li>
+    </ul>
+
+    <div class="note">
+      <span class="tag">The division of labour</span>
+      <p>Agents own <em>breadth</em> — every documented case, run consistently, evidence attached.
+      You own <em>depth</em> — the skipped-by-design cases and the intuition-led exploration. The tracker keeps both
+      visible in one sheet.</p>
+    </div>
+  </div>
+</section>
+
+<!-- ================= RELEASE GATE ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">The release gate</p>
+    <h2>Control the rollout without leaving the chat</h2>
+    <p>
+      Once manual QA has signed off, the release itself happens in the same conversation. Hiver ships behind
+      LaunchDarkly flags, so "releasing" means <strong>updating the enrolment / targeting list</strong> —
+      which accounts get the feature, in what order. Two ways to do it:
+    </p>
+    <div class="io" style="margin-top:18px">
+      <div><div class="h">If you connect the LaunchDarkly MCP</div><div class="b">Claude reads the current targeting, you say which accounts to add, and the flag is updated in-thread — a live, auditable rollout control.</div></div>
+      <div><div class="h">If you'd rather not connect it</div><div class="b">Paste the flag's JSON. Claude returns an updated enrolment list you can apply yourself. Same control, zero new access granted.</div></div>
+    </div>
+    <div class="note warnbox">
+      <span class="tag">Status — roadmap</span>
+      <p>The release gate is a <strong>workflow you run in-chat today</strong> (bring-your-own LaunchDarkly MCP or paste JSON),
+      not yet a packaged skill in <code>qa-suite</code>. It's called out here because it belongs in the single-conversation
+      story — and a dedicated release-control skill is the natural next addition.</p>
+    </div>
+  </div>
+</section>
+
+<!-- ================= SIGNALS ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">Reading the tracker</p>
+    <h2>Four signals, one shared vocabulary</h2>
+    <p>Every run agent records exactly one of these per case in <em>Testing 1</em>. When you scan a tracker or a
+      <code>report.md</code>, this is the whole language:</p>
+    <div class="signals">
+      <div class="sig pass"><span class="mark">✅</span><div><div class="t">As Expected</div><div class="d">Behaviour matched the case. Candidate for playwright-gen automation.</div></div></div>
+      <div class="sig fail"><span class="mark">❌</span><div><div class="t">Different</div><div class="d">Observed state differs from Expected — screenshot captured, headed to qa-bugs.</div></div></div>
+      <div class="sig warn"><span class="mark">⚠️</span><div><div class="t">Partial</div><div class="d">Some of the expectation held; the note says which part didn't. Also bug-bound.</div></div></div>
+      <div class="sig skip"><span class="mark">⏭️</span><div><div class="t">Skipped</div><div class="d">Can't be done by the browser pass (credentials, multi-account…). Handed to you.</div></div></div>
+    </div>
+  </div>
+</section>
+
+<!-- ================= CONNECTORS ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">Plumbing</p>
+    <h2>The connectors that make it real</h2>
+    <p>The agents lean on MCP connectors for their outside-world reach. Most are optional — the pipeline always has a
+      paste-it-in fallback so a missing connector never stalls a run.</p>
+    <div class="tablewrap">
+      <table>
+        <thead><tr><th>Connector</th><th>Used by</th><th>For</th><th>If not connected</th></tr></thead>
+        <tbody>
+          <tr><td class="owner">Claude in Chrome</td><td>qa-ui-run · hiver-explore</td><td>Driving the live, logged-in Hiver tab (Gmail / Omni)</td><td>Required for the browser pass — you open &amp; connect the tab</td></tr>
+          <tr><td class="owner">ClickUp</td><td>qa-bugs</td><td>Filing bug tickets with evidence</td><td>Emits copy-paste ticket blocks instead</td></tr>
+          <tr><td class="owner">Atlassian</td><td>qa-kit</td><td>Pulling the Confluence/Jira spec</td><td>You paste the PRD text — first-class path</td></tr>
+          <tr><td class="owner">Figma</td><td>qa-kit · qa-ui-author</td><td>UI states &amp; flows the spec misses (triage + case-writing)</td><td>Share the frames, or note 'none'</td></tr>
+          <tr><td class="owner">LaunchDarkly</td><td>release gate</td><td>Updating flag targeting / enrolment list</td><td>Paste the flag JSON, apply the result yourself</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </div>
+</section>
+
+<!-- ================= DAY IN THE LIFE ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">A worked example</p>
+    <h2>Shipping "Pinned Notes" — one chat, start to finish</h2>
+    <ol class="walk">
+      <li><b>You type <code>/qa-kit</code></b> and answer "QA engineer". You paste the ClickUp ticket, the PRD link,
+        and the Figma frame. <span class="who">qa-kit</span> reads the PR diff, interviews you, and calls it
+        <b>UI · standard effort</b>. You confirm.</li>
+      <li><span class="who">qa-ui-author</span> writes the test plan and a 26-case tracker, and asks its one batch of
+        clarifying questions. You take two of them to the PM, answer, and say go.</li>
+      <li><b>You open the Gmail tab</b> with the extension build and the shared mailbox, and hit Connect.
+        <span class="who">qa-ui-run</span> drives Hiver through all 26 cases: <b>21 ✅, 3 ❌, 2 ⏭️</b> (both need a second account).</li>
+      <li><span class="who">qa-bugs</span> files 3 ClickUp tickets with screenshots and links them in the tracker.</li>
+      <li class="human"><b>You take over.</b> You run the 2 skipped multi-account cases by hand into <em>Testing 2</em>,
+        then spend 40 minutes exploring — and catch a pin-ordering glitch no case predicted. One more ticket.</li>
+      <li class="human"><b>Release gate.</b> Sign-off done, you connect LaunchDarkly and roll "Pinned Notes" out to
+        3 pilot accounts — still in the same chat.</li>
+      <li><span class="who">playwright-gen</span> turns the 21 passing cases into <code>specs/pinnedNotes.spec.ts</code>,
+        runs them green, and opens the automation PR.</li>
+      <li><b>An SDET pulls the branch</b>, runs it locally — 19 pass as-is, 2 need a selector tweak. Merged.
+        <span class="who">qa-eval</span> has already written <code>report.md</code>: all stages PASS.</li>
+    </ol>
+  </div>
+</section>
+
+<!-- ================= GETTING STARTED ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">Getting started</p>
+    <h2>Install once, then just say <code>/qa-kit</code></h2>
+    <p><code>qa-suite</code> ships from the internal <b>grexit</b> marketplace. Add it once; it updates itself when the team ships a new version.</p>
+    <div class="terminal">
+      <div class="bar"><i></i><i></i><i></i></div>
+<pre><span class="c"># 1 — add the internal marketplace (once per machine)</span>
+<span class="p">/plugin</span> marketplace add GrexIt/claude-plugins
+
+<span class="c"># 2 — install the QA suite</span>
+<span class="p">/plugin</span> install <b>qa-suite@grexit</b>
+<span class="p">/reload-plugins</span>
+
+<span class="c"># 3 — start a QA pass, from anywhere</span>
+<span class="p">/qa-kit</span>
+
+<span class="c"># later, to pull the newest version</span>
+<span class="p">/plugin</span> marketplace update grexit</pre>
+    </div>
+    <div class="note">
+      <span class="tag">One prerequisite for the automation step</span>
+      <p><code>playwright-gen</code> writes and runs real specs inside the <code>poc-playwright</code>
+      (a.k.a. <code>playwright-hig-automation</code>) repo, so that repo needs its one-time setup done
+      (<code>npm install</code>, <code>npx playwright install chromium</code>, <code>npm run auth:all</code>).
+      Everything before automation runs without it.</p>
+    </div>
+  </div>
+</section>
+
+<!-- ================= QUICK REF ================= -->
+<section>
+  <div class="wrap">
+    <p class="sec-eyebrow">Quick reference</p>
+    <h2>The whole relay on one card</h2>
+    <div class="tablewrap">
+      <table>
+        <thead><tr><th>Agent</th><th>Role</th><th>Who calls it</th><th>Leaves behind</th></tr></thead>
+        <tbody>
+          <tr><td class="owner">qa-kit</td><td>Orchestrator / front door</td><td>You (<code>/qa-kit</code>)</td><td>Triage + routing</td></tr>
+          <tr><td class="owner">hiver-explore</td><td>Spec builder (no-spec path)</td><td>qa-kit, or you</td><td><code>spec.md</code></td></tr>
+          <tr><td class="owner">qa-ui-author</td><td>UI test plan + tracker</td><td>qa-kit</td><td>Word plan + tracker</td></tr>
+          <tr><td class="owner">qa-ui-run</td><td>Browser first pass (round 1)</td><td>qa-ui-author</td><td>Testing-1 results + screenshots</td></tr>
+          <tr><td class="owner">qa-api-author</td><td>API cases (no calls)</td><td>qa-kit</td><td>API tracker block</td></tr>
+          <tr><td class="owner">qa-api-run</td><td>API execution vs staging</td><td>qa-api-author / flow-capture</td><td>Status+body results</td></tr>
+          <tr><td class="owner">qa-bugs</td><td>Bug → ClickUp ticket</td><td>qa-ui-run / qa-api-run / you</td><td>Tickets + tracker links</td></tr>
+          <tr><td class="owner">playwright-gen</td><td>Cases → running specs + PR</td><td>qa-ui-run, or you</td><td>Spec files + Allure + PR</td></tr>
+          <tr><td class="owner">qa-eval</td><td>Output-quality judge</td><td>Auto, at pipeline end</td><td><code>trace/report.md</code></td></tr>
+        </tbody>
+      </table>
+    </div>
+  </div>
+</section>
+
+<footer>
+  <div class="wrap">
+    <span class="mono">qa-suite · Hiver QA — built at the AI-workflows hackathon</span>
+    <span>One command in. A tested, ticketed, automated, released feature out.</span>
+  </div>
+</footer>