@qa-gentic/stlc-agents 1.0.4 → 1.0.6

package/README.md

@@ -1,6 +1,6 @@
 # @qa-gentic/stlc-agents
 
-> AI-powered QA STLC automation — from Azure DevOps work item to self-healing Playwright TypeScript in a Helix-QA project.
+> AI-powered QA STLC automation — from Azure DevOps **or Jira Cloud** work item to self-healing Playwright TypeScript in a Helix-QA project.
 
 Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**, and **Windsurf**.
 
@@ -14,16 +14,19 @@ Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**,
 
 ## What It Does
 
-Four Python MCP servers cover the full QA Software Test Life Cycle:
+Five Python MCP servers cover the full QA Software Test Life Cycle:
 
 | Agent | Input | Output |
 |---|---|---|
 | `qa-test-case-manager` | ADO PBI / Bug / Feature ID | Manual test cases created & linked via TestedBy-Forward |
-| `qa-gherkin-generator` | ADO Epic / Feature / PBI / Bug ID | `.feature` file attached to the ADO work item |
-| `qa-playwright-generator` | Gherkin + live browser | `locators.ts` + page objects + step defs attached to ADO |
+| `qa-gherkin-generator` | ADO / Jira Epic / Feature / PBI / Bug ID | `.feature` file attached to ADO work item or saved locally |
+| `qa-playwright-generator` | Gherkin + live browser | `locators.ts` + page objects + step defs attached to ADO or saved locally |
 | `qa-helix-writer` | Generated `.ts` files + `helix_root` | Files written to Helix-QA directory layout on disk |
+| `qa-jira-manager` | **Jira** Story / Bug / Task / Epic | Test cases created in Jira → Gherkin → Playwright TypeScript → Helix-QA files |
 
-A fifth server — **Playwright MCP** (`http://localhost:8931/mcp`) — drives a real browser during code generation, replacing hand-authored locators with accessibility-tree-derived, zero-hallucination selectors.
+A sixth server — **Playwright MCP** (`http://localhost:8931/mcp`) — drives a real browser during code generation, replacing hand-authored locators with accessibility-tree-derived, zero-hallucination selectors.
+
+> **ADO or Jira?** Both pipelines now run the full STLC: fetch → analyse → test cases → Gherkin → Playwright → Helix-QA. ADO uses `qa-test-case-manager` as the entry point; Jira uses `qa-jira-manager`. Agents 2–4 (`qa-gherkin-generator`, `qa-playwright-generator`, `qa-helix-writer`) are shared by both pipelines.
 
 ---
 
@@ -31,12 +34,17 @@ A fifth server — **Playwright MCP** (`http://localhost:8931/mcp`) — drives a
 
 ```bash
 # 1. Install the CLI + npm package globally
+#    You will be prompted to choose your integration: ado / jira / both
+#    The choice is saved to ~/.qa-stlc/integration and reused by all subsequent commands.
 npm install -g @qa-gentic/stlc-agents
 
 # 2. Bootstrap your project (installs Python agents, copies skills, writes MCP config)
-qa-stlc init --vscode          # GitHub Copilot / VS Code
-# or
-qa-stlc init                   # Claude Code
+#    --integration overrides the saved preference; omit to reuse the choice from step 1.
+qa-stlc init --vscode --integration ado    # GitHub Copilot / VS Code — ADO pipeline
+qa-stlc init --vscode --integration jira   # GitHub Copilot / VS Code — Jira pipeline
+qa-stlc init --vscode --integration both   # GitHub Copilot / VS Code — both pipelines
+# or for Claude Code (no --vscode flag):
+qa-stlc init --integration ado
 
 # 3. Scaffold a new Playwright + Cucumber + TypeScript QA project
 qa-stlc scaffold --name my-qa-project
@@ -47,10 +55,15 @@ qa-stlc scaffold --name acme-e2e --dir /path/to/acme-e2e
 npx @playwright/mcp@latest --port 8931
 ```
 
-`qa-stlc init` does three things:
-1. `pip install qa-gentic-stlc-agents` — installs the four Python MCP servers
+`qa-stlc init` does four things:
+1. `pip install qa-gentic-stlc-agents` — installs all five Python MCP servers
 2. Copies skill files to `.github/copilot-instructions/` (and `.claude/` if not `--vscode`)
-3. Writes `.vscode/mcp.json` with all five servers configured
+3. Copies custom agent files to `.github/agents/` (used by GitHub Copilot and Claude's agent picker)
+4. Writes `.vscode/mcp.json` with all six servers configured
+
+> **Integration flag:** `--integration` controls which agents and skill files are installed.
+> If omitted, the value saved during `npm install -g` is used.
+> You can change it at any time by re-running `qa-stlc init --integration <ado|jira|both>`.
 
 ---
 
@@ -58,7 +71,7 @@ npx @playwright/mcp@latest --port 8931
 
 - Node.js ≥ 18
 - Python ≥ 3.10, < 3.14
-- Azure DevOps organisation with a `.env` containing:
+- For **Azure DevOps** (Agents 1–4) — a `.env` containing:
 
 ```env
 ADO_ORGANIZATION_URL=https://dev.azure.com/your-org
@@ -69,13 +82,26 @@ APP_EMAIL=your-test-email@example.com
 APP_PASSWORD=your-test-password
 ```
 
+- For **Jira Cloud** (Agent 5) — additional `.env` vars:
+
+```env
+JIRA_CLIENT_ID=your-atlassian-oauth-client-id
+JIRA_CLIENT_SECRET=your-atlassian-oauth-client-secret
+JIRA_CLOUD_ID=your-atlassian-cloud-id
+# Optional — defaults to http://localhost:8765/callback
+# JIRA_REDIRECT_URI=http://localhost:8765/callback
+```
+
+See [Jira Authentication Setup](#jira-authentication-setup) for how to obtain these values.
+
 ---
 
 ## Commands
 
 ```bash
-qa-stlc init [--vscode] [--python <path>]
-# Full bootstrap: pip install + skills + MCP config
+qa-stlc init [--vscode] [--python <path>] [--integration ado|jira|both]
+# Full bootstrap: pip install + skills + agent files + MCP config
+# Integration defaults to the value saved during npm install -g (prompted at that time)
 
 qa-stlc scaffold [--name <name>] [--dir <path>] [--no-install]
 # Copy full Playwright + Cucumber + TypeScript boilerplate to a new project directory
@@ -87,7 +113,7 @@ qa-stlc mcp-config [--vscode] [--print] [--python <path>] [--playwright-port <n>
 # Write .vscode/mcp.json (--vscode) or .mcp.json (Claude Code)
 
 qa-stlc verify
-# Check that all five MCP servers are reachable
+# Check that all six MCP servers are reachable
 ```
 
 ---
@@ -97,13 +123,19 @@ qa-stlc verify
 Open your AI coding agent and use natural language:
 
 ```
-# Generate test cases
+# Azure DevOps — Generate test cases
 Generate test cases for work item #12345 in MyProject at https://dev.azure.com/myorg
 
-# Generate Gherkin BDD
+# Azure DevOps — Generate Gherkin BDD
 Generate a Gherkin regression suite for Feature #11000 in MyProject at https://dev.azure.com/myorg
 
-# Generate Playwright code (requires Playwright MCP running)
+# Jira — Fetch issue and generate test cases
+Generate test cases for Jira issue PROJ-123
+
+# Jira — Fetch an Epic hierarchy
+Fetch the full Epic hierarchy for PROJ-10 in Jira
+
+# Generate Playwright code (requires Playwright MCP running — works with both ADO and Jira flows)
 Generate Playwright TypeScript for the Gherkin I just created. The login page is at /auth/login
 
 # Write to Helix-QA project
@@ -114,7 +146,7 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
 
 ## Tool Reference
 
-### qa-test-case-manager
+### qa-test-case-manager _(Azure DevOps)_
 
 | Tool | Description |
 |---|---|
@@ -122,7 +154,7 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
 | `get_linked_test_cases` | List all test cases already linked to a work item. Call before generating to power the deduplication diff. |
 | `create_and_link_test_cases` | Create structured manual test cases in ADO and link them via TestedBy-Forward. |
 
-### qa-gherkin-generator
+### qa-gherkin-generator _(Azure DevOps)_
 
 | Tool | Description |
 |---|---|
@@ -133,7 +165,7 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
 | `attach_gherkin_to_work_item` | Validate and attach a `.feature` file to a PBI or Bug work item. |
 | `validate_gherkin_content` | Structural validation — tags, scenario count, navigation steps. Returns `valid: bool` + `errors` + `warnings`. |
 
-### qa-playwright-generator
+### qa-playwright-generator _(ADO + Jira)_
 
 | Tool | Description |
 |---|---|
@@ -142,7 +174,7 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
 | `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. |
 | `attach_code_to_work_item` | Attach delta Playwright TypeScript files to an ADO work item. Pass only net-new delta files. |
 
-### qa-helix-writer
+### qa-helix-writer _(ADO + Jira)_
 
 | Tool | Description |
 |---|---|
@@ -151,7 +183,16 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
 | `read_helix_file` | Read an existing file from the Helix-QA project for overlap detection. |
 | `write_helix_files` | Write generated files to the correct Helix-QA paths. |
 
-### playwright (external)
+### qa-jira-manager _(Jira Cloud)_
+
+| Tool | Description |
+|---|---|
+| `fetch_jira_issue` | Fetch a Story, Bug, or Task with acceptance criteria, coverage hints, and existing linked test case count. Returns `epic_use_hierarchy` for Epics. |
+| `fetch_jira_epic_hierarchy` | Fetch an Epic with all child issues (Stories, Tasks, Bugs, Sub-tasks). |
+| `create_and_link_test_cases` | Create test case issues in Jira (type `Test`, falls back to `Task`) and link them via `is tested by`. Steps stored as an ADF table — no Xray required. Returns `confirmation_required: true` for Epics. |
+| `get_linked_test_cases` | List all issues linked to a Jira issue via `is tested by` / `Test` link type. Call before generating to avoid duplicates. |
+
+### playwright _(external)_
 
 | Tool | Description |
 |---|---|
@@ -174,6 +215,14 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
     "qa-gherkin-generator":    { "command": "/path/to/.venv/bin/qa-gherkin-generator" },
     "qa-playwright-generator": { "command": "/path/to/.venv/bin/qa-playwright-generator" },
     "qa-helix-writer":         { "command": "/path/to/.venv/bin/qa-helix-writer" },
+    "qa-jira-manager": {
+      "command": "/path/to/.venv/bin/qa-jira-manager",
+      "env": {
+        "JIRA_CLIENT_ID": "${env:JIRA_CLIENT_ID}",
+        "JIRA_CLIENT_SECRET": "${env:JIRA_CLIENT_SECRET}",
+        "JIRA_CLOUD_ID": "${env:JIRA_CLOUD_ID}"
+      }
+    },
     "playwright": { "type": "http", "url": "http://localhost:8931/mcp" }
   }
 }
@@ -188,6 +237,14 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
     "qa-gherkin-generator":    { "command": "/path/to/.venv/bin/qa-gherkin-generator" },
     "qa-playwright-generator": { "command": "/path/to/.venv/bin/qa-playwright-generator" },
     "qa-helix-writer":         { "command": "/path/to/.venv/bin/qa-helix-writer" },
+    "qa-jira-manager": {
+      "command": "/path/to/.venv/bin/qa-jira-manager",
+      "env": {
+        "JIRA_CLIENT_ID": "${env:JIRA_CLIENT_ID}",
+        "JIRA_CLIENT_SECRET": "${env:JIRA_CLIENT_SECRET}",
+        "JIRA_CLOUD_ID": "${env:JIRA_CLOUD_ID}"
+      }
+    },
     "playwright": { "type": "url", "url": "ws://localhost:8931" }
   }
 }
@@ -201,14 +258,75 @@ Write the generated files to my Helix-QA project at /workspace/my-qa-project
 
 ## Skills Installed
 
+Skills follow the [Agent Skills specification](https://agentskills.io/specification) and live under `skills/<n>/SKILL.md`.
+
 | Skill | Purpose |
 |---|---|
 | `AGENT-BEHAVIOR.md` | Zero-inference contract. Read first. Always. |
-| `generate-test-cases.md` | PBI / Bug / Feature → ADO manual test cases |
-| `generate-gherkin.md` | Epic / Feature / PBI / Bug → validated `.feature` + ADO attach |
-| `generate-playwright-code.md` | Gherkin + live browser → three-layer self-healing Playwright TypeScript |
-| `write-helix-files.md` | Generated files → Helix-QA disk layout, scaffold or merge |
-| `deduplication-protocol.md` | READ → DIFF → CREATE mandatory pre-flight gate |
+| `generate-test-cases/SKILL.md` | PBI / Bug / Feature → ADO manual test cases |
+| `generate-gherkin/SKILL.md` | Epic / Feature / PBI / Bug → validated `.feature` + ADO attach |
+| `generate-playwright-code/SKILL.md` | Gherkin + live browser → three-layer self-healing Playwright TypeScript |
+| `write-helix-files/SKILL.md` | Generated files → Helix-QA disk layout, scaffold or merge |
+| `deduplication-protocol/SKILL.md` | READ → DIFF → CREATE mandatory pre-flight gate |
+| `qa-jira-manager/SKILL.md` | Jira issue → test case issues + `is tested by` links |
+
+> **Installed copies** (`.claude/skills/`, `.github/copilot-instructions/`) are generated by
+> `qa-stlc init` / `qa-stlc skills` at project bootstrap time and are gitignored.
+> The canonical source for all skills is the `skills/` directory.
+
+---
+
+## Jira Authentication Setup
+
+`qa-jira-manager` uses **Jira OAuth 2.0 (3LO)** with a persistent file-based token cache
+at `~/.jira-cache/jira-token.json` — the same silent-cache / browser-fallback pattern
+used by the ADO MSAL auth module.
+
+### Step 1 — Create an Atlassian OAuth 2.0 (3LO) app
+
+1. Go to <https://developer.atlassian.com/console/myapps/>
+2. Click **Create** → **OAuth 2.0 integration**
+3. Add callback URL: `http://localhost:8765/callback`
+4. Under **Permissions**, enable: `read:jira-user`, `read:jira-work`, `write:jira-work`, `offline_access`
+5. Copy the **Client ID** and **Secret**
+
+### Step 2 — Find your Cloud ID
+
+```bash
+curl -H "Authorization: Bearer <any-token>" \
+  https://api.atlassian.com/oauth/token/accessible-resources
+```
+
+Copy the `id` field for your Jira site.
+
+### Step 3 — Add to `.env`
+
+```env
+JIRA_CLIENT_ID=your-client-id
+JIRA_CLIENT_SECRET=your-client-secret
+JIRA_CLOUD_ID=your-cloud-id
+```
+
+### Step 4 — First run
+
+The browser opens once on startup. Sign in to Jira. The token is cached silently
+and refreshed automatically for ~60 days — no re-prompting.
+
+---
+
+## Workflow Comparison: ADO vs Jira
+
+| Step | Azure DevOps | Jira Cloud |
+|---|---|---|
+| Fetch issue | `fetch_work_item` | `fetch_jira_issue` |
+| Fetch Epic hierarchy | `fetch_epic_hierarchy` | `fetch_jira_epic_hierarchy` |
+| Check for duplicates | `get_linked_test_cases` | `get_linked_test_cases` |
+| Create & link test cases | `create_and_link_test_cases` | `create_and_link_test_cases` |
+| Generate Gherkin | `fetch_work_item_for_gherkin` → `attach_gherkin_to_work_item` | `qa-gherkin-generator` with Jira issue AC (save locally or attach to Jira) |
+| Generate Playwright | `generate_playwright_code` (shared) | `generate_playwright_code` (shared) |
+| Write to disk | `write_helix_files` (shared) | `write_helix_files` (shared) |
+| Authentication | MSAL silent + browser (`~/.msal-cache/`) | OAuth 2.0 (3LO) + browser (`~/.jira-cache/`) |
+| Link relation | `TestedBy-Forward` | `is tested by` / `Test` link type |
 
 ---
 
@@ -295,18 +413,41 @@ HEALIX_CI_AUTO_APPROVE=true npm run healix:apply-ci
 ## Development
 
 ```bash
-make install      # create .venv + pip install -e .
-make test         # run pytest tests/ -v
-make skills       # install skill files to .claude/skills/
-make verify       # check MSAL auth status without making ADO calls
-make clean        # remove .venv, __pycache__, dist
+# Install (all five agents from one pip package)
+make install-ado         # install + ADO next steps
+make install-jira        # install + Jira next steps
+make install-both        # install + Both next steps
+
+# Verify
+make verify-ado          # ADO agents + MSAL auth cache
+make verify-jira         # Jira agents + OAuth token cache
+make verify-both         # all agents + both auth caches
+
+# Skills
+make skills-ado          # ADO skill files → .claude/skills/ + copilot-instructions/
+make skills-jira         # Jira skill files
+make skills-both         # all skill files
+
+# MCP config
+make mcp-config-ado      # write .mcp.json for ADO pipeline
+make mcp-config-jira     # write .mcp.json for Jira pipeline
+make mcp-config-both     # write .mcp.json for both pipelines
+
+# Test + clean
+make test                # run pytest tests/ -v
+make clean               # remove .venv, __pycache__, dist
 ```
 
 ---
 
 ## Documentation
 
-- [Quick Start Guide](docs/quickstart.md)
+- [Quick Start: Azure DevOps](QUICKSTART-ADO.md)
+- [Quick Start: Jira Cloud](QUICKSTART-JIRA.md)
+- [Architecture: ADO](ARCHITECTURE-ADO.md)
+- [Architecture: Jira](ARCHITECTURE-JIRA.md)
+- [Walkthrough: ADO](WALKTHROUGH-ADO.md)
+- [Walkthrough: Jira](WALKTHROUGH-JIRA.md)
 - [Architecture Reference](docs/architecture.md)
 - [End-to-End Walkthrough](docs/walkthrough.md)
 

package/bin/postinstall.js

@@ -1,78 +1,134 @@
 #!/usr/bin/env node
 /**
- * postinstall.js — Auto-install Python MCP servers after npm install -g.
+ * postinstall.js — Auto-install Python MCP servers after  npm install -g
+ *
+ * Asks the user which integration they need (ADO / Jira / Both) and installs
+ * only the relevant Python agents.  In non-interactive (CI) environments the
+ * prompt is skipped and the default (ado) is used.
+ *
+ * The chosen value is persisted to  ~/.qa-stlc/integration  so that
+ * `qa-stlc init`, `qa-stlc mcp-config`, and `qa-stlc verify` all read it
+ * without asking again.
  */
 "use strict";
 
-const { spawnSync } = require("child_process");
-const pkg = require("../package.json");
+const { spawnSync }   = require("child_process");
+const path            = require("path");
+const fs              = require("fs");
+const os              = require("os");
+const pickIntegration = require("../src/cli/prompt-integration");
+const pkg             = require("../package.json");
 
 const C = {
-  reset:  "\x1b[0m",
-  bold:   "\x1b[1m",
-  green:  "\x1b[32m",
-  cyan:   "\x1b[36m",
-  yellow: "\x1b[33m",
-  red:    "\x1b[31m",
-  dim:    "\x1b[2m",
+  reset:  "\x1b[0m", bold:   "\x1b[1m",
+  green:  "\x1b[32m", cyan:   "\x1b[36m",
+  yellow: "\x1b[33m", red:    "\x1b[31m", dim: "\x1b[2m",
 };
 
-const b  = (s) => `${C.bold}${s}${C.reset}`;
-const ok = (s) => console.log(`${C.green}✓${C.reset}  ${s}`);
+const b    = (s) => `${C.bold}${s}${C.reset}`;
+const ok   = (s) => console.log(`${C.green}✓${C.reset}  ${s}`);
 const info = (s) => console.log(`${C.cyan}→${C.reset}  ${s}`);
 const warn = (s) => console.log(`${C.yellow}⚠${C.reset}  ${s}`);
-const y  = (s) => `${C.yellow}${s}${C.reset}`;
-const d  = (s) => `${C.dim}${s}${C.reset}`;
+const y    = (s) => `${C.yellow}${s}${C.reset}`;
+const d    = (s) => `${C.dim}${s}${C.reset}`;
 
-console.log(`\n${b("QA STLC Agents")} — post-install\n`);
+// Persistent preference file — shared with cmd-init / cmd-mcp-config / cmd-verify
+const PREF_DIR  = path.join(os.homedir(), ".qa-stlc");
+const PREF_FILE = path.join(PREF_DIR, "integration");
 
-// ── 1. Find python ────────────────────────────────────────────────────────────
-const pythonCandidates = ["python3", "python"];
-let python = null;
-for (const candidate of pythonCandidates) {
-  const r = spawnSync(candidate, ["--version"], { encoding: "utf8" });
-  if (r.status === 0) { python = candidate; break; }
+function savePreference(value) {
+  try {
+    fs.mkdirSync(PREF_DIR, { recursive: true });
+    fs.writeFileSync(PREF_FILE, value, "utf8");
+  } catch (_) { /* non-fatal */ }
 }
 
-if (!python) {
-  warn("Python not found — skipping pip install.");
-  warn("Run manually after installing Python 3.10+:");
-  warn("  pip install qa-gentic-stlc-agents");
-} else {
-  // ── 2. pip install qa-gentic-stlc-agents ──────────────────────────────────────────
+console.log(`\n${b("QA STLC Agents")} v${pkg.version} — post-install\n`);
+
+// ── Async main ───────────────────────────────────────────────────────────────
+(async () => {
+
+  // ── 1. Find Python ─────────────────────────────────────────────────────────
+  const pythonCandidates = ["python3", "python"];
+  let python = null;
+  for (const candidate of pythonCandidates) {
+    const r = spawnSync(candidate, ["--version"], { encoding: "utf8" });
+    if (r.status === 0) { python = candidate; break; }
+  }
+
+  if (!python) {
+    warn("Python not found — skipping pip install.");
+    warn("Run manually after installing Python 3.10+:");
+    warn("  pip install qa-gentic-stlc-agents");
+    printNextSteps("ado");
+    return;
+  }
+
+  // ── 2. Ask which integration ──────────────────────────────────────────────
+  const integration = await pickIntegration("ado");
+  savePreference(integration);
+
+  // ── 3. pip install ────────────────────────────────────────────────────────
   info("Installing qa-gentic-stlc-agents via pip…");
-  const pip = spawnSync(python, ["-m", "pip", "install", "qa-gentic-stlc-agents", "--upgrade", "--quiet"], {
-    stdio: "inherit",
-    encoding: "utf8",
-  });
+  const pip = spawnSync(
+    python,
+    ["-m", "pip", "install", "qa-gentic-stlc-agents", "--upgrade", "--quiet"],
+    { stdio: "inherit", encoding: "utf8" }
+  );
 
   if (pip.status === 0) {
     ok("qa-gentic-stlc-agents installed.");
   } else {
     warn("pip install failed. Run manually: pip install qa-gentic-stlc-agents");
   }
-}
 
-// ── 3. Next steps ─────────────────────────────────────────────────────────────
-console.log(`
+  // ── 4. Print next steps ───────────────────────────────────────────────────
+  printNextSteps(integration);
+
+})();
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function printNextSteps(integration) {
+  const initFlag = integration !== "ado" ? ` --integration ${integration}` : "";
+
+  const adoWorkflow = `
+  ${d("ADO pipeline:")}
+  ${d("1 →")} ${y("qa-test-case-manager")}     ${d("ADO work item → manual test cases")}
+  ${d("2 →")} ${y("qa-gherkin-generator")}     ${d("Epic / Feature / PBI → .feature file")}
+  ${d("3 →")} ${y("qa-playwright-generator")}  ${d("Gherkin + live browser → self-healing Playwright TypeScript")}
+  ${d("4 →")} ${y("qa-helix-writer")}          ${d("Generated files → Helix-QA project on disk")}`;
+
+  const jiraWorkflow = `
+  ${d("Jira pipeline:")}
+  ${d("1 →")} ${y("qa-jira-manager")}          ${d("Fetch Jira issue + analyse acceptance criteria")}
+  ${d("2 →")} ${y("qa-jira-manager")}          ${d("Generate test cases and create in Jira with 'is tested by' links")}
+  ${d("3 →")} ${y("qa-gherkin-generator")}     ${d("Generate Gherkin .feature file from Jira issue AC")}
+  ${d("4 →")} ${y("qa-playwright-generator")}  ${d("Gherkin + live browser → self-healing Playwright TypeScript")}
+  ${d("5 →")} ${y("qa-helix-writer")}          ${d("Generated files → Helix-QA project on disk")}
+  ${d("   Requires: JIRA_CLIENT_ID + JIRA_CLIENT_SECRET + JIRA_CLOUD_ID in .env")}`;
+
+  const workflow =
+      integration === "ado"  ? adoWorkflow
+    : integration === "jira" ? jiraWorkflow
+    :                          adoWorkflow + "\n" + jiraWorkflow;
+
+  console.log(`
 ${b("Setup")} — run once in your project root:
 
-  ${C.cyan}qa-stlc init --vscode${C.reset}   ${d("# GitHub Copilot / VS Code")}
-  ${C.cyan}qa-stlc init${C.reset}             ${d("# Claude Code")}
+  ${C.cyan}qa-stlc init --vscode${initFlag}${C.reset}   ${d("# GitHub Copilot / VS Code")}
+  ${C.cyan}qa-stlc init${initFlag}${C.reset}             ${d("# Claude Code")}
 
-  ${d("Writes .vscode/mcp.json + installs skill files — then reload VS Code.")}
+  ${d("Writes MCP config + installs skill files — then reload VS Code.")}
 
 ${b("Start Playwright MCP")} ${d("(keep running in a separate terminal)")}:
 
   ${C.cyan}npx @playwright/mcp@latest --port 8931${C.reset}
 
-${b("STLC Workflow")} — use agents in this order:
-
-  ${d("1 →")} ${y("qa-test-case-manager")}     ${d("ADO work item ID → create manual test cases in ADO")}
-  ${d("2 →")} ${y("qa-gherkin-generator")}     ${d("Epic / Feature / PBI → BDD .feature file attached to ADO")}
-  ${d("3 →")} ${y("qa-playwright-generator")}  ${d("Gherkin + live page snapshot → self-healing Playwright TypeScript")}
-  ${d("4 →")} ${y("qa-helix-writer")}          ${d("Generated files → merged into Helix-QA project on disk")}
+${b("STLC Workflow")}:
+${workflow}
 
-${d("Skills reference all four steps — ask your agent: \"@generate-playwright-code\"")}
+${d("Change integration at any time:  qa-stlc init --integration <ado|jira|both>")}
 ${d("Docs: https://github.com/qa-gentic/stlc-agents")}
 `);
+}

package/bin/qa-stlc.js

@@ -17,11 +17,11 @@ const path = require("path");
 const pkg = require("../package.json");
 
 // Sub-commands
-const cmdInit       = require("../src/cmd-init");
-const cmdSkills     = require("../src/cmd-skills");
-const cmdMcpConfig  = require("../src/cmd-mcp-config");
-const cmdVerify     = require("../src/cmd-verify");
-const cmdScaffold   = require("../src/cmd-scaffold");
+const cmdInit       = require("../src/cli/cmd-init");
+const cmdSkills     = require("../src/cli/cmd-skills");
+const cmdMcpConfig  = require("../src/cli/cmd-mcp-config");
+const cmdVerify     = require("../src/cli/cmd-verify");
+const cmdScaffold   = require("../src/cli/cmd-scaffold");
 
 program
   .name("qa-stlc")
@@ -39,6 +39,7 @@ program
   )
   .option("--vscode", "Also write .vscode/mcp.json for GitHub Copilot")
   .option("--python <path>", "Path to Python 3.10+ binary", "python3")
+  .option("--integration <value>", "Integration to set up: ado, jira, or both (prompts if omitted)")
   .action(cmdInit);
 
 // ── skills ────────────────────────────────────────────────────────────────────
@@ -60,6 +61,7 @@ program
   .option("--print", "Print config to stdout without writing any file")
   .option("--python <path>", "Path to Python 3.10+ binary or venv", "python3")
   .option("--playwright-port <port>", "Port Playwright MCP is running on", "8931")
+  .option("--integration <value>", "Override integration filter: ado, jira, or both")
   .action(cmdMcpConfig);
 
 // ── verify ────────────────────────────────────────────────────────────────────
@@ -81,9 +83,27 @@ program
   .option("--no-install",  "Skip npm install after scaffolding")
   .action(cmdScaffold);
 
+// ── Quick-start hint appended to every --help output ─────────────────────────
+program.addHelpText("after", `
+Quick Start (run once in your project root):
+  $ qa-stlc init --vscode                        GitHub Copilot / VS Code
+  $ qa-stlc init                                 Claude Code (prompts for ADO/Jira/Both)
+
+  Override integration without prompting:
+  $ qa-stlc init --integration ado               Azure DevOps only
+  $ qa-stlc init --integration jira              Jira Cloud only
+  $ qa-stlc init --integration both              Both
+
+  Then scaffold a new QA project:
+  $ qa-stlc scaffold --name my-qa-project
+
+  Start Playwright MCP (keep running in a separate terminal):
+  $ npx @playwright/mcp@latest --port 8931
+`);
+
 program.parse(process.argv);
 
 // Show help if no command given
 if (!process.argv.slice(2).length) {
   program.outputHelp();
-}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qa-gentic/stlc-agents",
-  "version": "1.0.4",
-  "description": "QA STLC Agents — four MCP servers + skills for AI-powered test case, Gherkin, Playwright generation, and Helix-QA file writing against Azure DevOps. Includes Playwright + Cucumber + TypeScript scaffold. Works with Claude Code, GitHub Copilot, Cursor, Windsurf.",
+  "version": "1.0.6",
+  "description": "QA STLC Agents — five MCP servers + skills for AI-powered test case, Gherkin, Playwright generation, and Helix-QA file writing against Azure DevOps and Jira Cloud. Full pipeline for both: fetch → test cases → Gherkin → Playwright → Helix-QA. Works with Claude Code, GitHub Copilot, Cursor, Windsurf.",
   "keywords": [
     "playwright",
     "mcp",

package/skills/{qa-stlc/AGENT-BEHAVIOR.md → AGENT-BEHAVIOR.md}

@@ -17,9 +17,10 @@
 | Agent | What it does | What it produces |
 |---|---|---|
 | `qa-test-case-manager` | Fetches ADO work items; creates and links manual test cases | ADO test case work items linked via `TestedBy-Forward` |
-| `qa-gherkin-generator` | Fetches ADO work item hierarchies; validates and attaches `.feature` files | `.feature` files attached to ADO work items |
-| `qa-playwright-generator` | Generates TypeScript Playwright code from Gherkin; attaches files to ADO | `locators.ts`, `*Page.ts`, `*.steps.ts` attached to ADO work items |
-| `qa-helix-writer` | Writes already-generated files to disk at Helix-QA paths | Files on disk — no ADO writes |
+| `qa-gherkin-generator` | Fetches ADO/Jira work item hierarchies; validates and attaches `.feature` files | `.feature` files attached to ADO work items or saved locally |
+| `qa-playwright-generator` | Generates TypeScript Playwright code from Gherkin; attaches files to ADO | `locators.ts`, `*Page.ts`, `*.steps.ts` attached to ADO work items or saved locally |
+| `qa-helix-writer` | Writes already-generated files to disk at Helix-QA paths | Files on disk — no ADO/Jira writes |
+| `qa-jira-manager` | Fetches Jira issues; generates and creates test cases in Jira with 'is tested by' links; then hands off to `qa-gherkin-generator` → `qa-playwright-generator` → `qa-helix-writer` | Jira test case issues + Gherkin + Playwright TypeScript + Helix-QA files |
 
 ### What the agents do NOT do
 
@@ -47,7 +48,7 @@ This applies specifically to:
 | User says "yes" to one step | Carrying that "yes" forward to the next step | Seek fresh confirmation for each distinct action |
 | Navigation path not in work item | Inventing a path | Write placeholder `<!-- TODO: confirm screen name -->` and surface to user |
 | Test data not provided | Inventing emails, IDs, file contents | Stop and ask; never hardcode invented data |
-| Work item appears new | Skipping the deduplication protocol | Always run Phase 1 of deduplication-protocol.md before creating anything |
+| Work item appears new | Skipping the deduplication protocol | Always run Phase 1 of the deduplication-protocol skill before creating anything |
 
 ---
 
@@ -101,7 +102,7 @@ Every artifact type has exactly one delivery rule. Completing one artifact does
 
 | Condition | Action |
 |---|---|
-| User asks to write files to disk | Follow `write-helix-files.md` in full — never skip any step |
+| User asks to write files to disk | Follow the `write-helix-files` skill in full — never skip any step |
 | `write_helix_files` succeeds | Report the deduplication summary to the user |
 | `write_helix_files` fails | **See failure recovery rules below** — do NOT fall back to `create_file` |
 | A locator file already exists on disk (`list_helix_tree` returns it) | Extend that file via `write_helix_files` — **NEVER create a new file** |
@@ -370,7 +371,7 @@ When a rule is changed:
 
 1. Update the rule in this file with a dated entry in the change log below.
 2. Update the corresponding skill file in `skills/` to match.
-3. Run `./scripts/install-skills.sh vscode` to sync `.github/copilot-instructions/`.
+3. Run `make skills-ado`, `make skills-jira`, or `make skills-both` to sync installed skills.
 4. Update `CLAUDE.md` if the rule affects a key rule number.
 
 ### Change log