AI_GAME_QA_TestCase — tc-team

Deterministic game-QA test-case pipeline.
Hand it a spec and a sheet — get back a reviewed test-case tab whose structure, gates, and coverage ledger are owned by code, not by a model.

Grounded in the ISTQB test process. Stages S1–S3 follow the ISTQB test development process — test analysis → test design → test implementation — and cases are derived with standard ISTQB test-design techniques (equivalence partitioning, boundary values, state transition), not ad-hoc prompting.

Scope, stated honestly: this is a semi-automatic runbook, not a single unattended command. Your Claude Code session acts as the driver and steps through S0–S7, stopping at any gate that fails. Stages S3·S4 require the Workflow (multi-agent orchestration) tool in that session — without it the pipeline halts at S3 (PREREQUISITES §5). A fully unattended driver is on the roadmap. Verified end-to-end on 3 production features.

📖 Before the setup steps, read why it is shaped this way — the eight stages, why review is adversarial, why the sheet is written exactly once, and the two lessons that cost something:
Read it in English · 한국어로 읽기 — same write-up, 같은 글의 한국어판

⚠️ v4.0.0 — the v2 engine has been retired

This release replaces the tc-팀-v2 multi-agent orchestrator with tc-team, a two-lane pipeline.
If you are running v2, read Migrating from v2 before you pull.

⚡ TL;DR

• Two lanes, strictly separated — the LLM writes sentences and makes judgment calls; deterministic code owns structure, gates, and the coverage ledger. No model ever decides whether a gate passes.
• 8 stages (S0–S7) — each with a machine-checkable exit condition
• 7 deterministic gates — design, content, duplicate, origin, coverage seal, golden diff, traceability ledger
• Confidence scoring with zero LLM calls — a rule-based score (R1–R7) tells you which rows deserve human attention
• One sheet touch — everything is assembled and verified locally, then written once and read back for a 0-diff check
• 4 input formats — Confluence URL / PDF / Word / Excel, auto-detected
• No external API — all model calls go through the Claude Code CLI

🎯 The design decision — why determinism

v2 asked a model to author test cases and judge its own output. That works until it doesn't: duplicate rows reach the sheet, fabricated requirements pass review, and coverage is whatever the model says it is. None of it is reproducible.

tc-team draws a hard line:

This is a tradeoff, stated plainly: tc-team takes roughly 2.2× the wall-clock time of the v2 engine. What you get back is reproducibility, an auditable coverage ledger, and gates that catch a class of defect v2 shipped silently.

📊 Measured — production run, 2026-07-29

A 277-row feature run, all figures measured rather than asserted:

The 7 fabrications are the important number. In the prior run the same failure mode was only found after the sheet was delivered, by hand.

🏗 Pipeline — S0 to S7

Full stage contracts: skills/tc-team/SKILL.md · internals: docs/ARCHITECTURE.md · why it is shaped this way: write-up — English / 한국어

The gates

A gate failure stops the run. No gate consults a model.

Confidence scoring — no LLM calls

tc-team/scripts/confidence/ scores each row deterministically (rules R1–R6: spec-confirmation needed, image-only reference, unresolved cross-reference, cross-reference located only, weak anchor, coverage gap — plus R7, a design-technique badge that is displayed but does not move the score). The output tells a reviewer where to spend attention. Because it is pure code, the same input always yields the same score.

The penalties are tuned, not guessed — tc-team/scripts/confidence/sweep.js runs an offline coefficient sweep against your own completed runs so you can see the resulting score distribution before changing anything, and tc-team/test/confidence.test.js locks the tables so a retune cannot silently invert a rule.

🚀 Quick start

Assumes Claude Code is installed.

git clone https://github.com/nobles92ts-ship-it/AI_GAME_QA_TestCase.git
cd AI_GAME_QA_TestCase

bash ./setup.sh

On Windows use .\setup.ps1 instead.

The setup script auto-detects Node.js and the Claude Code CLI, installs agents and skills into ~/.claude/, substitutes every {PROJECT_ROOT} / {NODE_PATH} / {CLAUDE_HOME} / {CONFLUENCE_SITE} placeholder, creates .env and pipeline_config.json from templates, and runs npm install.

Then, in Claude Code, hand it a sheet link and a spec link together:

/tc-team <google-sheets-url> <spec-source>

<spec-source> can be a Confluence URL, or a path to a .pdf, .docx, or .xlsx file.

Your session then drives S0–S7, reporting at each stage and halting on any gate failure. A spec link without a sheet link is rejected rather than guessed at. One feature per run — there is no batch mode.

Full walkthrough: docs/SETUP.md · Dependencies: docs/PREREQUISITES.md

🔧 Customising the rules — and the two linters

Every pipeline rule lives in skills/tc-team/rules/ as a Markdown file. Edit those and the pipeline picks the change up on the next run; there is no build step and no copy to keep in sync.

But editing a rule can silently desynchronise it from the machinery that enforces it. Two linters exist for exactly that moment:

node scripts/util/doc_reality_lint.js
node scripts/util/ssot_drift_check.js

These are not part of the pipeline and do not run automatically. They are maintenance tools: run them after you edit rules, not on every TC run. If you only use the pipeline as shipped, you will never need them.

🧠 Optional — plug in your own knowledge index

Specs reference values they never define — a drop rate that lives in a table doc, a status effect defined on another team's page. The S1 chain can look those up in a knowledge index of your project's own design docs and resolve them instead of guessing: definition found → folded into the design · data-table location cited on the TC · missing spec area discovered → added to the coverage denominator · no evidence → flagged for spec confirmation rather than invented.

This is a socket, not a shipped component: crossref_brain is off by default and the pipeline is 100% identical without it. Turning it on takes three things — your own design docs, a one-time context-mode indexing pass, and two lines in team/tc_config.json. The docs must be your project's (the whole point is testing TCs against the design world they belong to); resemblance to anyone else's wiki is irrelevant.

The better the index, the more the pipeline resolves on its own instead of flagging for humans — see the preparation ladder in PREREQUISITES.

🔁 Migrating from v2

v2 is not deleted — it is pinned. Everything from the v2 era remains permanently available at the v3.1.0 tag.

To stay on v2, pin that tag and stop pulling main:

git checkout v3.1.0

To move to tc-team, note that v4.0.0 has an unrelated commit history, so git pull will fail with "refusing to merge unrelated histories". Re-clone:

git clone https://github.com/nobles92ts-ship-it/AI_GAME_QA_TestCase.git

What changed for you:

tc-대시보드, tc-이미지매칭, and haiku are unchanged and still ship.

🗺 Repository structure

AI_GAME_QA_TestCase/
├── agents/                       # 3 tc-team agent definitions
│   ├── tc-team-designer.md       # S1 — spec analysis & coverage design
│   ├── tc-team-대조.md            # S1 — cross-reference against the knowledge index
│   └── tc-team-설계검수.md        # S1 — design inspection gate
│
├── skills/
│   ├── tc-team/
│   │   ├── SKILL.md              # S0–S7 stage contracts (entry point)
│   │   └── rules/                # 9 rule files — the SSoT you customise
│   ├── tc-대시보드/               # Dashboard refresh
│   ├── tc-이미지매칭/             # Confluence image → sheet column matching
│   └── haiku/
│
├── tc-team/                      # The deterministic engine
│   ├── lib/                      # 22 modules — gates, slicer, ledger, impact scope, sheet I/O
│   ├── scripts/                  # Chain drivers + confidence scoring
│   ├── test/                     # 16 suites
│   └── docs/                     # Driver reference, EVAL digest, guides
│
├── scripts/
│   ├── handoff_gate.py           # Between-step markdown integrity gate
│   └── util/                     # Shared Node utilities + the 2 linters
│       └── expander/             # Design expansion & schema validation
│
├── team/                         # Pipeline board + config originals (.example / .template)
├── appscript/                    # Google Apps Script (tabs, dashboard, nav sidebar, Slack)
├── docs/                         # Setup, prerequisites, architecture
├── commands/                     # Slash commands
└── credentials/                  # OAuth files (gitignored, .gitkeep only)

🛠 Tech stack

🔮 Roadmap

✅ Shipped

• Two-lane pipeline with 7 deterministic gates
• Coverage ledger with explicit, reason-coded exclusions
• LLM-free confidence scoring
• Single-touch sheet write with read-back verification

🔜 Next

• Duplicate-gate threshold tuning against a larger corpus
• Coverage-denominator handling for superseded spec sections
• Spec-change detection and surgical TC update on the tc-team engine

🤖 Built with Claude Code

Every agent definition, orchestration script, rule file, and page of documentation in this project was designed and built using Claude Code.