@qa-gentic/stlc-agents 1.0.0

package/src/cmd-init.js

@@ -0,0 +1,92 @@
+/**
+ * cmd-init.js — `qa-stlc init`
+ *
+ * Full bootstrap: install Python agents + skills + MCP config.
+ */
+"use strict";
+
+const { execSync, spawnSync } = require("child_process");
+const path = require("path");
+const fs   = require("fs");
+
+const cmdSkills    = require("./cmd-skills");
+const cmdMcpConfig = require("./cmd-mcp-config");
+
+const C = {
+  reset: "\x1b[0m", bold: "\x1b[1m",
+  green: "\x1b[32m", cyan: "\x1b[36m",
+  yellow: "\x1b[33m", red: "\x1b[31m", dim: "\x1b[2m",
+};
+const ok   = (m) => console.log(`${C.green}✓${C.reset}  ${m}`);
+const info = (m) => console.log(`${C.cyan}→${C.reset}  ${m}`);
+const warn = (m) => console.log(`${C.yellow}⚠${C.reset}  ${m}`);
+const die  = (m) => { console.error(`${C.red}✗${C.reset}  ${m}`); process.exit(1); };
+
+module.exports = async function init(opts) {
+  console.log(`\n${C.bold}QA STLC Agents — init${C.reset}\n`);
+
+  // ── 1. Check Python ──────────────────────────────────────────────────────
+  const python = opts.python || "python3";
+  info(`Checking Python (${python})…`);
+  const pyCheck = spawnSync(python, ["--version"], { encoding: "utf8" });
+  if (pyCheck.status !== 0) {
+    die(`Python not found at '${python}'. Install Python 3.10+ or pass --python <path>.`);
+  }
+  const pyVersion = (pyCheck.stdout || pyCheck.stderr || "").trim();
+  const match = pyVersion.match(/Python (\d+)\.(\d+)/);
+  if (!match || parseInt(match[1]) < 3 || parseInt(match[2]) < 10) {
+    die(`Python 3.10+ required, found: ${pyVersion}`);
+  }
+  ok(`${pyVersion} found.`);
+
+  // ── 2. pip install qa-gentic-stlc-agents ────────────────────────────────────────
+  info("Installing qa-gentic-stlc-agents (pip)…");
+  const pip = spawnSync(python, ["-m", "pip", "install", "qa-gentic-stlc-agents>=1.0.1", "--quiet"], {
+    stdio: "inherit",
+    encoding: "utf8",
+  });
+  if (pip.status !== 0) {
+    die("pip install failed. Run manually: pip install qa-gentic-stlc-agents");
+  }
+  ok("qa-gentic-stlc-agents installed.");
+
+  // ── 3. Install skills ────────────────────────────────────────────────────
+  info("Installing skills…");
+  const skillTarget = opts.vscode ? "both" : "claude";
+  await cmdSkills({ target: skillTarget });
+
+  // ── 4. Write MCP config ──────────────────────────────────────────────────
+  info("Writing MCP config…");
+  await cmdMcpConfig({
+    vscode: opts.vscode || false,
+    print: false,
+    python: python,
+    playwrightPort: "8931",
+  });
+
+  // ── 5. Done ──────────────────────────────────────────────────────────────
+  const mcpLocation   = opts.vscode ? ".vscode/mcp.json" : ".mcp.json";
+  const skillsLocation = opts.vscode
+    ? ".github/copilot-instructions/  (reload VS Code window to activate)"
+    : ".claude/skills/";
+
+  console.log(`
+${C.bold}Setup complete.${C.reset}
+
+  ${C.dim}MCP config :${C.reset} ${mcpLocation}
+  ${C.dim}Skills     :${C.reset} ${skillsLocation}
+
+${C.bold}Start Playwright MCP${C.reset} ${C.dim}(keep running in a separate terminal):${C.reset}
+
+  ${C.cyan}npx @playwright/mcp@latest --port 8931${C.reset}
+
+${C.bold}STLC Workflow${C.reset} ${C.dim}— use agents in this order:${C.reset}
+
+  ${C.dim}1 →${C.reset} ${C.yellow}qa-test-case-manager${C.reset}     ${C.dim}ADO work item ID → create manual test cases in ADO${C.reset}
+  ${C.dim}2 →${C.reset} ${C.yellow}qa-gherkin-generator${C.reset}     ${C.dim}Epic / Feature / PBI → BDD .feature file attached to ADO${C.reset}
+  ${C.dim}3 →${C.reset} ${C.yellow}qa-playwright-generator${C.reset}  ${C.dim}Gherkin + live page snapshot → self-healing Playwright TypeScript${C.reset}
+  ${C.dim}4 →${C.reset} ${C.yellow}qa-helix-writer${C.reset}          ${C.dim}Generated files → merged into Helix-QA project on disk${C.reset}
+
+${C.dim}Skills reference all four steps — ask your agent: "@generate-playwright-code"${C.reset}
+`);
+};

package/src/cmd-mcp-config.js

@@ -0,0 +1,177 @@
+/**
+ * cmd-mcp-config.js — `qa-stlc mcp-config`
+ *
+ * Generates .mcp.json (Claude Code) or .vscode/mcp.json (GitHub Copilot / VS Code).
+ */
+"use strict";
+
+const path     = require("path");
+const fs       = require("fs");
+const { spawnSync } = require("child_process");
+
+const C = {
+  reset: "\x1b[0m", bold: "\x1b[1m",
+  green: "\x1b[32m", cyan: "\x1b[36m",
+  yellow: "\x1b[33m", red: "\x1b[31m", dim: "\x1b[2m",
+};
+const ok   = (m) => console.log(`${C.green}✓${C.reset}  ${m}`);
+const info = (m) => console.log(`${C.cyan}→${C.reset}  ${m}`);
+const warn = (m) => console.log(`${C.yellow}⚠${C.reset}  ${m}`);
+
+const CWD = process.cwd();
+const IS_WIN = process.platform === "win32";
+const EXT = IS_WIN ? ".exe" : "";
+
+const AGENT_NAMES = [
+  "qa-test-case-manager",
+  "qa-gherkin-generator",
+  "qa-playwright-generator",
+  "qa-helix-writer",
+];
+
+/**
+ * Locate the binary for an agent.
+ * Priority: .venv → --python dir → system PATH → python sys.executable dir → macOS framework dirs
+ */
+function findBinary(name, pythonBin) {
+  // 1. .venv in cwd
+  const venvBin = IS_WIN
+    ? path.join(CWD, ".venv", "Scripts", name + EXT)
+    : path.join(CWD, ".venv", "bin", name);
+  if (fs.existsSync(venvBin)) return venvBin;
+
+  // 2. dir of --python flag binary
+  if (pythonBin && pythonBin !== "python3" && pythonBin !== "python") {
+    const candidate = path.join(path.dirname(pythonBin), name + EXT);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  // 3. system PATH via which/where
+  const which = spawnSync(IS_WIN ? "where" : "which", [name], { encoding: "utf8" });
+  if (which.status === 0 && which.stdout.trim()) return which.stdout.trim().split("\n")[0].trim();
+
+  // 4. ask Python where its own bin dir is (catches framework installs not on PATH)
+  for (const py of ["python3", "python"]) {
+    const r = spawnSync(py, ["-c", "import sys, os; print(os.path.dirname(sys.executable))"], { encoding: "utf8" });
+    if (r.status === 0 && r.stdout.trim()) {
+      const candidate = path.join(r.stdout.trim(), name + EXT);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+
+  // 5. macOS Python.org framework fallback
+  if (!IS_WIN) {
+    const frameworkDirs = [
+      "/Library/Frameworks/Python.framework/Versions/3.13/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.12/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.11/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.10/bin",
+    ];
+    for (const dir of frameworkDirs) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+function buildClaudeConfig(pythonBin, playwrightPort) {
+  const servers = {};
+  const missing = [];
+
+  for (const name of AGENT_NAMES) {
+    const bin = findBinary(name, pythonBin);
+    if (bin) {
+      servers[name] = { command: bin };
+    } else {
+      missing.push(name);
+      servers[name] = { command: `/path/to/.venv/bin/${name}`, "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents" };
+    }
+  }
+
+  servers["playwright"] = {
+    type: "url",
+    url: `ws://localhost:${playwrightPort}`,
+  };
+
+  return { config: { mcpServers: servers }, missing };
+}
+
+function buildVscodeConfig(pythonBin, playwrightPort) {
+  const servers = {};
+  const missing = [];
+
+  for (const name of AGENT_NAMES) {
+    const bin = findBinary(name, pythonBin);
+    if (bin) {
+      servers[name] = { command: bin };
+    } else {
+      missing.push(name);
+      servers[name] = { command: `/path/to/.venv/bin/${name}`, "_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents" };
+    }
+  }
+
+  servers["playwright"] = {
+    type: "http",
+    url: `http://localhost:${playwrightPort}/mcp`,
+  };
+
+  return { config: { servers }, missing };
+}
+
+function printNextSteps(mode, playwrightPort) {
+  const isVscode = mode === "vscode";
+  console.log(`
+  ${C.dim}Start Playwright MCP before running generation workflows:${C.reset}
+  npx @playwright/mcp@latest --port ${playwrightPort}
+  ${C.dim}headless (CI): npx @playwright/mcp@latest --headless --port ${playwrightPort}${C.reset}
+
+  ${isVscode
+    ? `Reload VS Code window — all 5 MCP servers will appear in the MCP panel.`
+    : `In Claude Code, run /mcp to verify all 5 servers are loaded.`
+  }
+`);
+}
+
+module.exports = async function mcpConfig(opts) {
+  const useVscode      = opts.vscode || false;
+  const printOnly      = opts.print  || false;
+  const pythonBin      = opts.python || "python3";
+  const playwrightPort = opts.playwrightPort || "8931";
+
+  if (printOnly) {
+    const { config: claudeCfg } = buildClaudeConfig(pythonBin, playwrightPort);
+    const { config: vscodeCfg } = buildVscodeConfig(pythonBin, playwrightPort);
+    console.log("\n=== Claude Code (.mcp.json) ===");
+    console.log(JSON.stringify(claudeCfg, null, 2));
+    console.log("\n=== VS Code (.vscode/mcp.json) ===");
+    console.log(JSON.stringify(vscodeCfg, null, 2));
+    printNextSteps("both", playwrightPort);
+    return;
+  }
+
+  if (useVscode) {
+    const { config, missing } = buildVscodeConfig(pythonBin, playwrightPort);
+    const dir = path.join(CWD, ".vscode");
+    fs.mkdirSync(dir, { recursive: true });
+    const out = path.join(dir, "mcp.json");
+    fs.writeFileSync(out, JSON.stringify(config, null, 2) + "\n", "utf8");
+    ok(`Written → .vscode/mcp.json`);
+    if (missing.length) {
+      warn(`${missing.length} agent(s) not found — run: pip install qa-gentic-stlc-agents`);
+      missing.forEach((m) => warn(`  missing: ${m}`));
+    }
+    printNextSteps("vscode", playwrightPort);
+  } else {
+    const { config, missing } = buildClaudeConfig(pythonBin, playwrightPort);
+    const out = path.join(CWD, ".mcp.json");
+    fs.writeFileSync(out, JSON.stringify(config, null, 2) + "\n", "utf8");
+    ok(`Written → .mcp.json`);
+    if (missing.length) {
+      warn(`${missing.length} agent(s) not found — run: pip install qa-gentic-stlc-agents`);
+      missing.forEach((m) => warn(`  missing: ${m}`));
+    }
+    printNextSteps("claude", playwrightPort);
+  }
+};

package/src/cmd-scaffold.js

@@ -0,0 +1,130 @@
+"use strict";
+
+/**
+ * cmd-scaffold.js — qa-stlc scaffold
+ *
+ * Writes the embedded Healix QA framework boilerplate into a new project directory
+ * and performs post-scaffold customisation (project name replacement, etc.).
+ * All framework files are bundled in boilerplate-bundle.js — no filesystem
+ * dependency on the boilerplate/ directory at runtime.
+ *
+ * Usage:
+ *   qa-stlc scaffold                          # scaffold into ./my-qa-project
+ *   qa-stlc scaffold --name acme-tests        # custom project name
+ *   qa-stlc scaffold --dir /path/to/target    # custom output directory
+ *   qa-stlc scaffold --no-install             # skip npm install
+ */
+
+const fs     = require("fs");
+const path   = require("path");
+const cp     = require("child_process");
+
+const BUNDLE = require("./boilerplate-bundle");
+
+/**
+ * Write all bundle entries to the target directory.
+ * Skips entries whose content is empty (directory markers like .gitkeep).
+ */
+function writeBundleToDir(bundle, dest) {
+  for (const [relPath, content] of Object.entries(bundle)) {
+    const destPath = path.join(dest, relPath);
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    if (relPath.endsWith(".gitkeep")) {
+      // Just ensure the directory exists — don't write .gitkeep files
+      continue;
+    }
+    fs.writeFileSync(destPath, content, "utf-8");
+  }
+}
+
+/**
+ * Replace all occurrences of a string in a file (binary-safe via Buffer → string).
+ */
+function replaceInFile(filePath, search, replacement) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    if (!content.includes(search)) return;
+    fs.writeFileSync(filePath, content.split(search).join(replacement), "utf-8");
+  } catch {
+    // Binary or unreadable files — skip silently
+  }
+}
+
+/**
+ * Walk a directory and apply replaceInFile to every text file.
+ */
+function replaceInDir(dir, search, replacement) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      replaceInDir(fullPath, search, replacement);
+    } else if (entry.isFile()) {
+      replaceInFile(fullPath, search, replacement);
+    }
+  }
+}
+
+module.exports = async function scaffold(options) {
+  const projectName = options.name  || "my-qa-project";
+  const targetDir   = path.resolve(options.dir || projectName);
+  const runInstall  = options.install !== false;
+
+  // Guard: target must not already exist (or be empty)
+  if (fs.existsSync(targetDir)) {
+    const entries = fs.readdirSync(targetDir).filter(f => f !== ".git");
+    if (entries.length > 0) {
+      console.error(`\n  ❌  Target directory is not empty: ${targetDir}`);
+      console.error(`     Use --dir to choose a different location.\n`);
+      process.exit(1);
+    }
+  }
+
+  console.log(`\n  🚀  Scaffolding QA framework boilerplate`);
+  console.log(`      Name   : ${projectName}`);
+  console.log(`      Target : ${targetDir}\n`);
+
+  // 1. Write embedded bundle
+  console.log("  📁  Writing framework files…");
+  writeBundleToDir(BUNDLE, targetDir);
+
+  // 2. Replace {{PROJECT_NAME}} placeholder
+  console.log("  ✏️   Applying project name…");
+  replaceInDir(targetDir, "{{PROJECT_NAME}}", projectName);
+
+  // 3. Copy .env.example → .env (if not already present)
+  const envExample = path.join(targetDir, ".env.example");
+  const envFile    = path.join(targetDir, ".env");
+  if (fs.existsSync(envExample) && !fs.existsSync(envFile)) {
+    fs.copyFileSync(envExample, envFile);
+    console.log("  📋  Created .env from .env.example");
+  }
+
+  // 4. npm install
+  if (runInstall) {
+    console.log("  📦  Installing npm dependencies (this may take a minute)…");
+    try {
+      cp.execSync("npm install", { cwd: targetDir, stdio: "inherit" });
+    } catch {
+      console.warn("\n  ⚠️   npm install exited with an error — check output above.\n");
+    }
+  }
+
+  // 5. Print next steps
+  console.log("");
+  console.log("  ✅  Scaffold complete!\n");
+  console.log("  Next steps:");
+  console.log(`    cd ${path.relative(process.cwd(), targetDir) || "."}`);
+  if (!runInstall) console.log("    npm install");
+  console.log("    npx playwright install chromium");
+  console.log("    # Edit .env — set BASE_URL and (optionally) AI_API_KEY");
+  console.log("    npm test");
+  console.log("");
+  console.log("  To add a new page:");
+  console.log("    cp src/templates/_template.feature        src/test/features/my-page.feature");
+  console.log("    cp src/templates/_template.locators.ts    src/locators/my-page.locators.ts");
+  console.log("    cp src/templates/_template.steps.ts       src/test/steps/my-page.steps.ts");
+  console.log("    cp src/templates/_TemplatePage.ts         src/pages/MyPage.ts");
+  console.log("");
+  console.log("  Docs: https://github.com/your-org/stlc-agents#scaffold");
+  console.log("");
+};

package/src/cmd-skills.js

@@ -0,0 +1,124 @@
+/**
+ * cmd-skills.js — `qa-stlc skills`
+ *
+ * Copies skill markdown files into the correct directory for each coding agent:
+ *
+ *   claude    →  .claude/skills/  +  .claude/AGENT-BEHAVIOR.md
+ *   vscode    →  .github/copilot-instructions/
+ *   cursor    →  .cursor/rules/ (one file per skill)
+ *   windsurf  →  .windsurf/rules/
+ *   both      →  claude + vscode
+ *   print     →  stdout only
+ */
+"use strict";
+
+const path = require("path");
+const fs   = require("fs");
+
+const C = {
+  reset: "\x1b[0m", bold: "\x1b[1m",
+  green: "\x1b[32m", yellow: "\x1b[33m", dim: "\x1b[2m",
+};
+const ok   = (m) => console.log(`${C.green}✓${C.reset}  ${m}`);
+const info = (m) => console.log(`   ${C.dim}${m}${C.reset}`);
+const warn = (m) => console.log(`${C.yellow}⚠${C.reset}  ${m}`);
+
+// Resolve the skills bundled with this npm package
+const PKG_ROOT    = path.resolve(__dirname, "..");
+const SKILLS_DIR  = path.join(PKG_ROOT, "skills", "qa-stlc");
+const BEHAVIOR_MD = path.join(SKILLS_DIR, "AGENT-BEHAVIOR.md");
+
+/** Copy a file, creating parent dirs as needed. */
+function cp(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+/** List all .md files in SKILLS_DIR (flat). */
+function skillFiles() {
+  return fs.readdirSync(SKILLS_DIR)
+    .filter((f) => f.endsWith(".md") && f !== "AGENT-BEHAVIOR.md")
+    .map((f) => path.join(SKILLS_DIR, f));
+}
+
+const CWD = process.cwd();
+
+function installClaude() {
+  const dest = path.join(CWD, ".claude", "skills");
+  for (const src of skillFiles()) {
+    cp(src, path.join(dest, path.basename(src)));
+  }
+  cp(BEHAVIOR_MD, path.join(CWD, ".claude", "AGENT-BEHAVIOR.md"));
+  ok(`Skills installed → .claude/skills/`);
+  info("AGENT-BEHAVIOR.md → .claude/AGENT-BEHAVIOR.md");
+  skillFiles().forEach((f) => info(path.basename(f)));
+  printPlaywrightHint();
+}
+
+function installVscode() {
+  const dest = path.join(CWD, ".github", "copilot-instructions");
+  for (const src of skillFiles()) {
+    cp(src, path.join(dest, path.basename(src)));
+  }
+  cp(BEHAVIOR_MD, path.join(dest, "AGENT-BEHAVIOR.md"));
+  ok(`Skills installed → .github/copilot-instructions/`);
+  info("Add to .github/copilot-instructions.md:");
+  info("  @.github/copilot-instructions/AGENT-BEHAVIOR.md");
+  printPlaywrightHint();
+}
+
+function installCursor() {
+  const dest = path.join(CWD, ".cursor", "rules");
+  for (const src of skillFiles()) {
+    cp(src, path.join(dest, path.basename(src)));
+  }
+  cp(BEHAVIOR_MD, path.join(dest, "AGENT-BEHAVIOR.md"));
+  ok(`Skills installed → .cursor/rules/`);
+  printPlaywrightHint();
+}
+
+function installWindsurf() {
+  const dest = path.join(CWD, ".windsurf", "rules");
+  for (const src of skillFiles()) {
+    cp(src, path.join(dest, path.basename(src)));
+  }
+  cp(BEHAVIOR_MD, path.join(dest, "AGENT-BEHAVIOR.md"));
+  ok(`Skills installed → .windsurf/rules/`);
+  printPlaywrightHint();
+}
+
+function printSkills() {
+  console.log("\nAvailable skills:\n");
+  skillFiles().forEach((f) => console.log(`  ${path.basename(f)}`));
+  console.log(`  AGENT-BEHAVIOR.md`);
+}
+
+function printPlaywrightHint() {
+  console.log(`
+  ${C.dim}Start Playwright MCP before running generation workflows:${C.reset}
+  npx @playwright/mcp@latest --port 8931
+`);
+}
+
+module.exports = async function skills(opts) {
+  const target = (opts.target || "claude").toLowerCase();
+
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error(`Skills directory not found: ${SKILLS_DIR}`);
+    console.error("Try reinstalling: npm install -g @qa-stlc/agents");
+    process.exit(1);
+  }
+
+  switch (target) {
+    case "claude":  installClaude();  break;
+    case "vscode":  installVscode();  break;
+    case "cursor":  installCursor();  break;
+    case "windsurf": installWindsurf(); break;
+    case "both":    installClaude(); installVscode(); break;
+    case "print":   printSkills();   break;
+    default:
+      warn(`Unknown target: ${target}`);
+      warn("Valid targets: claude, vscode, cursor, windsurf, both, print");
+      process.exit(1);
+  }
+};

package/src/cmd-verify.js

@@ -0,0 +1,129 @@
+/**
+ * cmd-verify.js — `qa-stlc verify`
+ *
+ * Quick sanity checks:
+ *   1. Are the four Python MCP agents on PATH (or in .venv)?
+ *   2. Is Playwright MCP reachable on the expected port?
+ *   3. Is MSAL auth cache present?
+ */
+"use strict";
+
+const path   = require("path");
+const fs     = require("fs");
+const http   = require("http");
+const https  = require("https");
+const { spawnSync } = require("child_process");
+const os     = require("os");
+
+const C = {
+  reset: "\x1b[0m", bold: "\x1b[1m",
+  green: "\x1b[32m", yellow: "\x1b[33m", red: "\x1b[31m", dim: "\x1b[2m",
+};
+const ok   = (m) => console.log(`  ${C.green}✓${C.reset}  ${m}`);
+const fail = (m) => console.log(`  ${C.red}✗${C.reset}  ${m}`);
+const warn = (m) => console.log(`  ${C.yellow}⚠${C.reset}  ${m}`);
+const head = (m) => console.log(`\n${C.bold}${m}${C.reset}`);
+
+const CWD    = process.cwd();
+const IS_WIN = process.platform === "win32";
+const EXT    = IS_WIN ? ".exe" : "";
+
+const AGENT_NAMES = [
+  "qa-test-case-manager",
+  "qa-gherkin-generator",
+  "qa-playwright-generator",
+  "qa-helix-writer",
+];
+
+function findBinary(name) {
+  // .venv first
+  const venvBin = IS_WIN
+    ? path.join(CWD, ".venv", "Scripts", name + EXT)
+    : path.join(CWD, ".venv", "bin", name);
+  if (fs.existsSync(venvBin)) return venvBin;
+  // system PATH
+  const w = spawnSync(IS_WIN ? "where" : "which", [name], { encoding: "utf8" });
+  if (w.status === 0 && w.stdout.trim()) return w.stdout.trim().split("\n")[0].trim();
+  return null;
+}
+
+function checkPort(port) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://localhost:${port}/`, (res) => {
+      res.destroy();
+      resolve(true);
+    });
+    req.setTimeout(2000, () => { req.destroy(); resolve(false); });
+    req.on("error", () => resolve(false));
+  });
+}
+
+module.exports = async function verify(opts) {
+  const playwrightPort = opts.playwrightPort || "8931";
+  let allOk = true;
+
+  // ── 1. Python agents ──────────────────────────────────────────────────────
+  head("Python MCP Agents");
+  for (const name of AGENT_NAMES) {
+    const bin = findBinary(name);
+    if (bin) {
+      ok(`${name}  ${C.dim}${bin}${C.reset}`);
+    } else {
+      fail(`${name}  — not found`);
+      allOk = false;
+    }
+  }
+  if (!allOk) {
+    console.log(`\n  ${C.yellow}Fix: pip install qa-gentic-stlc-agents${C.reset}`);
+  }
+
+  // ── 2. Playwright MCP ─────────────────────────────────────────────────────
+  head("Playwright MCP");
+  const pwReachable = await checkPort(playwrightPort);
+  if (pwReachable) {
+    ok(`Reachable on port ${playwrightPort}`);
+  } else {
+    warn(`Not reachable on port ${playwrightPort}  ${C.dim}(start it with: npx @playwright/mcp@latest --port ${playwrightPort})${C.reset}`);
+    // Don't fail — it's optional until generation time
+  }
+
+  // ── 3. MSAL token cache ───────────────────────────────────────────────────
+  head("Azure DevOps Auth (MSAL)");
+  const msalCache = path.join(os.homedir(), ".msal-cache", "msal-cache.json");
+  if (fs.existsSync(msalCache)) {
+    const stat = fs.statSync(msalCache);
+    ok(`Token cache found  ${C.dim}${msalCache}  (${Math.round(stat.size / 1024)} KB)${C.reset}`);
+  } else {
+    warn(`No MSAL cache at ${msalCache}`);
+    warn(`A browser will open the first time an agent calls Azure DevOps.`);
+    warn(`Set AZURE_CLIENT_ID + AZURE_CLIENT_SECRET + AZURE_TENANT_ID for CI/CD.`);
+  }
+
+  // ── 4. MCP config files ───────────────────────────────────────────────────
+  head("MCP Config");
+  const mcpJson   = path.join(CWD, ".mcp.json");
+  const vscodeMcp = path.join(CWD, ".vscode", "mcp.json");
+  if (fs.existsSync(mcpJson))   ok(`.mcp.json present`);
+  else                          warn(`.mcp.json missing  — run: qa-stlc mcp-config`);
+  if (fs.existsSync(vscodeMcp)) ok(`.vscode/mcp.json present`);
+  else                          warn(`.vscode/mcp.json missing  — run: qa-stlc mcp-config --vscode`);
+
+  // ── 5. Skills ─────────────────────────────────────────────────────────────
+  head("Skills");
+  const claudeSkills = path.join(CWD, ".claude", "skills");
+  const copilotSkills = path.join(CWD, ".github", "copilot-instructions");
+  if (fs.existsSync(claudeSkills)) {
+    const files = fs.readdirSync(claudeSkills).filter((f) => f.endsWith(".md"));
+    ok(`Claude Code skills (${files.length} files)  ${C.dim}${claudeSkills}${C.reset}`);
+  } else {
+    warn(`No Claude Code skills  — run: qa-stlc skills`);
+  }
+  if (fs.existsSync(copilotSkills)) {
+    const files = fs.readdirSync(copilotSkills).filter((f) => f.endsWith(".md"));
+    ok(`Copilot instructions (${files.length} files)  ${C.dim}${copilotSkills}${C.reset}`);
+  } else {
+    warn(`No Copilot instructions  — run: qa-stlc skills --target vscode`);
+  }
+
+  console.log();
+};