@kudusov.takhir/ba-toolkit 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -11,6 +11,40 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.3.2] — 2026-04-08
+
+### Fixed
+
+- **`bin/ba-toolkit.js` `cmdInit` ignored `runInstall` return value.** When the user declined the "Overwrite? (y/N)" prompt for an existing skill destination, `runInstall` returned `false`, but `cmdInit` ignored it and printed the success path ("Project is ready. Next steps: Restart Claude Code to load the new skills") even though no skills were installed. The next-steps block now branches on the install result and tells the user how to retry: `ba-toolkit install --for {agentId}`.
+- **`parseArgs` did not accept `--key=value` form.** The hand-rolled parser only understood `--key value` (space-separated). Users typing the GNU long-option style accepted by git/npm/gh (`--name=MyApp`, `--domain=saas`) silently lost the value — the flag was stored as `name=MyApp` set to `true` and the script then prompted for the project name interactively. Both forms now work and can be mixed in a single invocation. Splits on the first `=` only, so values containing further `=` characters are preserved (e.g. `--name="Foo=Bar"`).
+- **No SIGINT handler / readline lifecycle issues.** Each `prompt()` call previously created a fresh `readline.Interface` and closed it after the answer. Hitting Ctrl+C mid-prompt killed Node abruptly and left some terminals in raw mode. Piped stdin that closed mid-flow caused the next prompt's promise to hang forever and the process to exit silently with no error message. Fixed by switching to a single shared `readline.Interface` per CLI invocation, adding a `process.on('SIGINT')` handler that prints a clean `Cancelled.` message and exits with code 130, and rejecting in-flight prompt promises with `err.code = 'INPUT_CLOSED'` when the input stream closes prematurely. The outer `main().catch(...)` filters this code to print a friendly two-line message instead of a Node stack trace.
+- **Silent failure when slug could not be derived from a non-ASCII name.** `sanitiseSlug` strips everything outside `[a-z0-9-]`, so `--name "Проект Космос"` or `--name "🚀"` produced an empty derived slug. In the non-interactive path the script then exited with a generic `Invalid or empty slug` error with no clue about why. Now in the non-interactive path it prints `Cannot derive a slug from "{name}" — it contains no ASCII letters or digits` plus a one-line workaround (`Pass an explicit slug with --slug, e.g. --slug my-project`). In the interactive path it prints a gray hint above the manual slug prompt explaining we couldn't auto-derive.
+- **`AGENTS.md` template was missing 8 of the 21 skills.** `renderAgentsMd` emitted a "Pipeline Status" table with 13 rows — the 12 numbered stages + the `7a` sub-step. The 8 cross-cutting utilities added in v1.1 and v1.2 (`/trace`, `/clarify`, `/analyze`, `/estimate`, `/glossary`, `/export`, `/risk`, `/sprint`) were missing entirely. Since `AGENTS.md` is the project context every AI agent reads on entry to a new session, those 8 skills were effectively invisible — agents didn't know they existed without re-reading README. Added a second "Cross-cutting Tools" section below the pipeline table listing all 8, with descriptions copied from the canonical README pipeline table. A `MAINTENANCE` comment above the function reminds future-me to update both tables when adding a new skill.
+
+---
+
+## [1.3.1] — 2026-04-08
+
+### Fixed
+
+- **`/brief` and `/srs` now load all 9 domain references, not just 3.** Both `skills/brief/SKILL.md` and `skills/srs/SKILL.md` hardcoded a check for `igaming`, `fintech`, `saas` only — a stale list from v1.0 that was never updated when v1.1.0 added six new domain references (`ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media`, `real-estate`). As a result, users on any of those six domains silently got no domain-specific interview questions, mandatory entities, or glossary. The check now covers all nine shipped domain files, matching the supported list advertised in the CLI and README. No other skill files had the same stale list — only `brief` and `srs` did hardcoded domain matching.
+
+### Changed
+
+- **`sprint-template.md` rewritten end-to-end as Nova Analytics (SaaS).** The sprint-plan reference template loaded by `/sprint` was previously a Dragon Fortune iGaming example (slot games, RTP, responsible gambling, bonus wagering, Telegram Mini App). It's now a B2B SaaS product analytics plan — workspace sign-up, data source integration, dashboards with funnel/cohort widgets, metric alerts, SSO, and admin workspace management. Structure (sprint goals, DoD, capacity math, epic labels) is unchanged.
+- **`risk-template.md` rewritten end-to-end as Nova Analytics.** The risk-register reference template loaded by `/risk` had iGaming-specific risks (regulated iGaming jurisdiction, Telegram Mini App API breakage, RTP / bonus wagering knowledge gap). It's now a SaaS analytics risk register: third-party data source rate limits, GDPR DPA, columnar query performance at scale, OIDC/SSO library breaking changes, and columnar analytics storage knowledge gap. Structure (probability × impact scoring, priority tiers, mitigation/contingency sections) is unchanged.
+- **`export-template.md`** — one-line fix: the example Jira label changed from `dragon-fortune` to `nova-analytics`.
+- **iGaming-first ordering removed from user-facing documentation.** README intro, README Domain support table, `docs/FAQ.md`, `docs/USAGE.md`, and `docs/TROUBLESHOOTING.md` all listed iGaming first when enumerating the 9 supported domains. They now follow the SaaS-first order the CLI has used since v1.3.0: `saas → fintech → ecommerce → healthcare → logistics → on-demand → social-media → real-estate → igaming`. The iGaming row in the Domain support table stays — it just moved from position 1 to position 9.
+- **`dragon-fortune` slug example in README.md:186 replaced with `nova-analytics`.** This was the last stray placeholder outside the real `example/dragon-fortune/` project.
+
+### Not changed (deliberately)
+
+- `skills/references/domains/igaming.md` — the domain reference itself. iGaming remains a first-class supported domain.
+- `example/dragon-fortune/` — the real end-to-end example project referenced from README.
+- `bin/ba-toolkit.js` / `init.sh` / `init.ps1` `DOMAINS` array iGaming entry — iGaming remains a menu choice in the CLI and shell initialisers.
+
+---
+
 ## [1.3.0] — 2026-04-08
 
 ### Changed
@@ -212,7 +246,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.0...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.2...HEAD
+[1.3.2]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.1...v1.3.2
+[1.3.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.2.5...v1.3.0
 [1.2.5]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.2.4...v1.2.5
 [1.2.4]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.2.3...v1.2.4

package/README.md

@@ -24,7 +24,7 @@ Structured BA pipeline for AI coding agents — brief to handoff, 21 skills, 9 d
 
 BA Toolkit is a set of 21 interconnected skills that run a full business-analysis pipeline inside your AI coding agent. You go from a rough project brief to a development handoff package, and each skill reads the output of the previous ones — maintaining cross-references between artifacts along the chain `FR → US → UC → AC → NFR → Entity → ADR → API → WF → Scenario`.
 
-Unlike one-shot prompting, every artifact is written to disk as Markdown, every ID links back to its source, and `/trace` verifies coverage across the whole pipeline. `/clarify` and `/analyze` catch ambiguities and quality gaps with CRITICAL/HIGH severity ratings. Domain references for 9 industries (iGaming, Fintech, SaaS, E-commerce, Healthcare, Logistics, On-demand, Social/Media, Real Estate) plug in automatically at `/brief`.
+Unlike one-shot prompting, every artifact is written to disk as Markdown, every ID links back to its source, and `/trace` verifies coverage across the whole pipeline. `/clarify` and `/analyze` catch ambiguities and quality gaps with CRITICAL/HIGH severity ratings. Domain references for 9 industries (SaaS, Fintech, E-commerce, Healthcare, Logistics, On-demand, Social/Media, Real Estate, iGaming) plug in automatically at `/brief`.
 
 Artifacts are generated in whatever language you write in — ask in English, get English docs; ask in any other language, the output follows.
 
@@ -183,7 +183,7 @@ Full traceability: FR → US → UC → AC → NFR → Entity → ADR → API
 | — | `/risk` | Risk register — probability × impact matrix, mitigation per risk | `00_risks_{slug}.md` |
 | — | `/sprint` | Sprint plan — stories grouped by velocity and capacity with sprint goals | `00_sprint_{slug}.md` |
 
-The project **slug** (e.g., `dragon-fortune`) is set at `/brief` and reused across all files automatically.
+The project **slug** (e.g., `nova-analytics`) is set at `/brief` and reused across all files automatically.
 
 ---
 
@@ -212,15 +212,15 @@ The pipeline is domain-agnostic by default. At `/brief`, you pick a domain, and
 
 | Domain | Industries covered |
 |--------|-------------------|
-| **iGaming** | Online slots, sports betting, casino lobbies, Telegram Mini Apps, promo mechanics |
-| **Fintech** | Neobanks, payment systems, crypto exchanges, investment platforms, P2P lending |
 | **SaaS** | B2B platforms, CRM, analytics, marketplaces, EdTech, HRTech |
+| **Fintech** | Neobanks, payment systems, crypto exchanges, investment platforms, P2P lending |
 | **E-commerce** | B2C stores, B2B catalogs, multi-vendor marketplaces, D2C brands, digital goods |
 | **Healthcare** | Telemedicine, patient portals, EHR/EMR, clinic management, mental health apps |
 | **Logistics** | Last-mile delivery, courier management, freight tracking, WMS, fleet management |
 | **On-demand** | Ride-hailing, home services, task marketplaces, beauty, tutoring, pet care |
 | **Social / Media** | Social networks, creator platforms, community forums, newsletters, short-video |
 | **Real Estate** | Property portals, agency CRM, rental management, property management, mortgage tools |
+| **iGaming** | Online slots, sports betting, casino lobbies, Telegram Mini Apps, promo mechanics |
 | **Custom** | Any other domain — works with general interview questions |
 
 Adding a new domain = creating one Markdown file in `skills/references/domains/`. See [docs/DOMAINS.md](docs/DOMAINS.md).

package/bin/ba-toolkit.js

@@ -94,6 +94,15 @@ function parseArgs(argv) {
       break;
     }
     if (a.startsWith('--')) {
+      // Support --key=value form (in addition to --key value). The `=` must
+      // come after at least one character of key, so `--=value` and `--`
+      // alone fall through. Splits on the FIRST `=` only — values may
+      // contain further `=` characters.
+      const eqIdx = a.indexOf('=');
+      if (eqIdx > 2) {
+        args.flags[a.slice(2, eqIdx)] = a.slice(eqIdx + 1);
+        continue;
+      }
       const key = a.slice(2);
       const next = argv[i + 1];
       if (next !== undefined && !next.startsWith('-')) {
@@ -114,16 +123,42 @@ function parseArgs(argv) {
 
 // --- Prompt helper -----------------------------------------------------
 
+// Shared across all prompts in a single CLI invocation. Creating a new
+// readline.Interface for every question (the previous approach) made Ctrl+C
+// handling unreliable, leaked listeners on stdin, and broke when stdin was
+// piped (EOF on the second create). One interface per process, closed by
+// closeReadline() once main() finishes (or by the SIGINT handler).
+let sharedRl = null;
+
 function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
+  if (!sharedRl) {
+    sharedRl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  }
+  return new Promise((resolve, reject) => {
+    let answered = false;
+    const onClose = () => {
+      if (!answered) {
+        const err = new Error('input stream closed before answer');
+        err.code = 'INPUT_CLOSED';
+        reject(err);
+      }
+    };
+    sharedRl.once('close', onClose);
+    sharedRl.question(question, (answer) => {
+      answered = true;
+      sharedRl.removeListener('close', onClose);
       resolve(answer.trim());
     });
   });
 }
 
+function closeReadline() {
+  if (sharedRl) {
+    sharedRl.close();
+    sharedRl = null;
+  }
+}
+
 // --- Utilities ---------------------------------------------------------
 
 function sanitiseSlug(input) {
@@ -222,6 +257,12 @@ function skillToMdc(srcPath, destPath) {
   return { destPath: newDestPath, content: mdcFrontmatter + body };
 }
 
+// MAINTENANCE: when adding a new skill, update BOTH tables below.
+// - Sequential pipeline stages (numbered 0-11 + 7a sub-step) go in
+//   "Pipeline Status" — they have a per-project status that progresses.
+// - Cross-cutting utilities (no fixed stage) go in "Cross-cutting Tools".
+// The README.md pipeline table is the canonical source of truth for the
+// 21-skill list and ordering; keep this template in sync with it.
 function renderAgentsMd({ name, slug, domain }) {
   return `# BA Toolkit — Project Context
 
@@ -253,6 +294,21 @@ function renderAgentsMd({ name, slug, domain }) {
 | 10 | /scenarios | ⬜ Not started | — |
 | 11 | /handoff | ⬜ Not started | — |
 
+## Cross-cutting Tools
+
+Utilities available throughout the pipeline. No fixed stage — invoke whenever they help. See README.md for the prerequisites of each.
+
+| Tool | Purpose |
+|------|---------|
+| /trace | Traceability Matrix + coverage gaps |
+| /clarify [focus] | Targeted ambiguity resolution for any artifact |
+| /analyze | Cross-artifact quality report with severity-rated findings |
+| /estimate | Effort estimation — Fibonacci SP, T-shirt sizes, or person-days |
+| /glossary | Unified project glossary with terminology drift detection |
+| /export [format] | Export User Stories to Jira / GitHub Issues / Linear / CSV |
+| /risk | Risk register — probability × impact matrix, mitigation per risk |
+| /sprint | Sprint plan — stories grouped by velocity and capacity with sprint goals |
+
 ## Key Constraints
 
 - Domain: ${domain}
@@ -293,12 +349,22 @@ async function cmdInit(args) {
   if (!slug) {
     const derived = sanitiseSlug(name);
     if (nameFromFlag) {
-      // Non-interactive path: silently accept the derived slug.
+      // Non-interactive path. Either accept the derived slug, or fail
+      // loudly with a hint when the name has no ASCII letters/digits to
+      // derive from (e.g. `--name "Проект"` or `--name "🚀"`). Without
+      // this branch the user got an opaque "Invalid or empty slug" with
+      // no clue why.
+      if (!derived) {
+        logError(`Cannot derive a slug from "${name}" — it contains no ASCII letters or digits.`);
+        log('Pass an explicit slug with --slug, e.g. --slug my-project');
+        process.exit(1);
+      }
       slug = derived;
     } else if (derived) {
       const custom = await prompt(`  Project slug [${cyan(derived)}]: `);
       slug = custom || derived;
     } else {
+      log('  ' + gray(`(could not derive a slug from "${name}" — please type one manually)`));
       slug = await prompt('  Project slug (lowercase, hyphens only): ');
     }
   }
@@ -389,9 +455,13 @@ async function cmdInit(args) {
   }
 
   // --- 6. Install skills for the selected agent ---
+  // installed: null = no install attempted (--no-install or no agentId),
+  //            true = install succeeded,
+  //            false = install was cancelled (e.g. user declined overwrite).
+  let installed = null;
   if (!skipInstall && agentId) {
     log('');
-    await runInstall({
+    installed = await runInstall({
       agentId,
       isGlobal: !!args.flags.global,
       isProject: !!args.flags.project,
@@ -405,10 +475,16 @@ async function cmdInit(args) {
   log('  ' + cyan(`Project '${name}' (${slug}) is ready.`));
   log('');
   log('  ' + yellow('Next steps:'));
-  if (!skipInstall && agentId) {
+  if (installed === true) {
     log('    1. ' + AGENTS[agentId].restartHint);
     log('    2. Optional: run /principles to define project-wide conventions');
     log('    3. Run /brief to start the BA pipeline');
+  } else if (installed === false) {
+    log('    1. Skill install was cancelled. To install later, run:');
+    log('         ' + gray(`ba-toolkit install --for ${agentId}`));
+    log('    2. Open your AI assistant (Claude, Cursor, etc.)');
+    log('    3. Optional: run /principles to define project-wide conventions');
+    log('    4. Run /brief to start the BA pipeline');
   } else {
     log('    1. Install skills for your agent:');
     log('         ' + gray('ba-toolkit install --for claude-code'));
@@ -597,7 +673,26 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  logError(err && (err.stack || err.message) || String(err));
-  process.exit(1);
+// Clean exit on Ctrl+C: print on a fresh line so we don't append to a
+// half-typed prompt, close the readline interface so the terminal is
+// returned to a sane state, then exit with the conventional 130 code.
+process.on('SIGINT', () => {
+  console.log('\n  ' + yellow('Cancelled.'));
+  closeReadline();
+  process.exit(130);
 });
+
+main()
+  .then(() => {
+    closeReadline();
+  })
+  .catch((err) => {
+    closeReadline();
+    if (err && err.code === 'INPUT_CLOSED') {
+      logError('Input stream closed before all prompts could be answered.');
+      log('Pass remaining values as flags (e.g. --name, --domain, --for) or run interactively.');
+      process.exit(1);
+    }
+    logError(err && (err.stack || err.message) || String(err));
+    process.exit(1);
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "AI-powered Business Analyst pipeline — 21 skills from project brief to development handoff. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf.",
   "keywords": [
     "business-analyst",

package/skills/brief/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ba-brief
 description: >
-  Generate a high-level Project Brief for projects in any domain (iGaming, Fintech, SaaS, and others). Use this skill when the user enters /brief, or asks to "create a project brief", "describe the project", "start a new project", "project brief", or mentions the starting stage of the analytical pipeline. Also triggers on requests like "begin with a brief", "describe the product", "form a product description". First step of the BA Toolkit pipeline.
+  Generate a high-level Project Brief for projects in any domain (SaaS, Fintech, E-commerce, Healthcare, Logistics, and others). Use this skill when the user enters /brief, or asks to "create a project brief", "describe the project", "start a new project", "project brief", or mentions the starting stage of the analytical pipeline. Also triggers on requests like "begin with a brief", "describe the product", "form a product description". First step of the BA Toolkit pipeline.
 ---
 
 # /brief — Project Brief
@@ -10,7 +10,7 @@ Starting point of the BA Toolkit pipeline. Generates a structured Project Brief
 
 ## Loading domain reference
 
-Domain references are located in `references/domains/` relative to the `ba-toolkit` directory. Supported domains: `igaming`, `fintech`, `saas`. For other domains, work without a reference file.
+Domain references are located in `references/domains/` relative to the `ba-toolkit` directory. Supported domains: `saas`, `fintech`, `ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media`, `real-estate`, `igaming`. For other domains, work without a reference file.
 
 ## Workflow
 
@@ -26,7 +26,7 @@ If `00_principles_*.md` exists in the output directory, load it and apply its co
 
 ### 3. Domain selection
 
-Ask the user about the project domain. If the domain matches `igaming`, `fintech`, or `saas`, load the corresponding `references/domains/{domain}.md`. Use domain-specific interview questions (section `1. /brief`), typical business goals, risks, and glossary from that file.
+Ask the user about the project domain. If a matching `references/domains/{domain}.md` file exists (currently: `saas`, `fintech`, `ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media`, `real-estate`, `igaming`), load it and use its domain-specific interview questions (section `1. /brief`), typical business goals, risks, and glossary.
 
 If the domain does not match any supported one, record it as `custom:{name}` and use general questions only.
 
@@ -54,7 +54,7 @@ If a domain reference is loaded, supplement general questions with domain-specif
 ```markdown
 # Project Brief: {Project Name}
 
-**Domain:** {igaming | fintech | saas | custom:{name}}
+**Domain:** {saas | fintech | ecommerce | healthcare | logistics | on-demand | social-media | real-estate | igaming | custom:{name}}
 **Date:** {date}
 
 ## 1. Project Summary

package/skills/references/templates/export-template.md

@@ -39,7 +39,7 @@ Actual values are filled in by the skill based on the project's artifacts.
           },
           "issuetype": { "name": "Story" },
           "priority": { "name": "High" },
-          "labels": ["dragon-fortune", "E-01"],
+          "labels": ["nova-analytics", "E-01"],
           "customfield_10016": 3,
           "customfield_10014": null
         }

package/skills/references/templates/risk-template.md

@@ -23,19 +23,19 @@
 
 | ID | Title | Category | Probability | Impact | Score | Priority | Status |
 |----|-------|----------|:-----------:|:------:|:-----:|---------|--------|
-| RISK-01 | Payment provider SLA not guaranteed | External | 4 | 5 | 20 | 🔴 Critical | Open |
-| RISK-02 | Regulatory approval timeline unknown | Compliance | 3 | 4 | 12 | 🟡 High | Open |
-| RISK-03 | Real-time leaderboard at scale unproven | Technical | 3 | 3 | 9 | 🟡 High | Open |
+| RISK-01 | Third-party data source rate limits unclear | External | 4 | 5 | 20 | 🔴 Critical | Open |
+| RISK-02 | GDPR data-processing agreement unsigned | Compliance | 3 | 4 | 12 | 🟡 High | Open |
+| RISK-03 | Columnar query performance under concurrent load unproven | Technical | 3 | 3 | 9 | 🟡 High | Open |
 | RISK-04 | Scope creep from stakeholder wish list | Business | 3 | 2 | 6 | 🟢 Medium | Open |
-| RISK-05 | Telegram Mini App API breaking changes | External | 2 | 3 | 6 | 🟢 Medium | Open |
+| RISK-05 | OIDC / SSO library breaking changes | External | 2 | 3 | 6 | 🟢 Medium | Open |
 | RISK-06 | Data model changes after /datadict | Technical | 2 | 3 | 6 | 🟢 Medium | Open |
-| RISK-07 | Development team unfamiliar with domain | Business | 2 | 1 | 2 | ⚪ Low | Open |
+| RISK-07 | Development team unfamiliar with analytics domain | Business | 2 | 1 | 2 | ⚪ Low | Open |
 
 ---
 
 ## Risk Details
 
-### RISK-01 — Payment provider SLA not guaranteed
+### RISK-01 — Third-party data source rate limits unclear
 
 **Category:** External
 **Probability:** 4 / 5 — Likely
@@ -45,19 +45,19 @@
 **Source:** `07a_research_{slug}.md`
 
 **Description:**
-The selected payment provider has not provided a written SLA. If the provider experiences downtime during peak traffic, transactions will fail and user funds may be delayed, directly impacting revenue and trust.
+The product depends on timely event delivery from third-party integrations (Segment and warehouse connectors). The published rate limits do not guarantee sustained throughput at the projected MVP event volume. If a critical integration is rate-limited or breaks its contract, dashboards will show stale or incomplete data and user trust erodes quickly.
 
 **Mitigation:**
-Negotiate and sign an SLA before launch. Implement a fallback payment provider in the API contract. Add payment provider availability as a monitored NFR metric.
+Run a sustained-throughput test against each integration in sprint 0. Negotiate higher quotas with the providers before launch. Add per-source ingestion lag as a monitored NFR metric with an alert threshold.
 
 **Contingency:**
-Enable the fallback provider automatically via feature flag if primary provider error rate exceeds 5% over a 5-minute window.
+Enable an ingestion backpressure queue and surface a workspace-level banner when a source is lagging more than 5 minutes behind real-time. Prioritise critical event streams over low-value ones until the lag recovers.
 
 **Owner:** Tech Lead
 
 ---
 
-### RISK-02 — Regulatory approval timeline unknown
+### RISK-02 — GDPR data-processing agreement unsigned
 
 **Category:** Compliance
 **Probability:** 3 / 5 — Possible
@@ -67,19 +67,19 @@ Enable the fallback provider automatically via feature flag if primary provider
 **Source:** `01_brief_{slug}.md`
 
 **Description:**
-The product operates in a regulated iGaming jurisdiction. The licensing timeline was listed as an assumption in the Brief. If approval is delayed, the launch date will slip regardless of development readiness.
+The product collects first-party user-behavioural events from EU workspaces. The Brief listed the GDPR data-processing agreement (DPA) with the selected cloud provider as an assumption. If the DPA is delayed or blocked by legal review, the EU launch date will slip regardless of development readiness.
 
 **Mitigation:**
-Engage legal counsel early to track approval status. Decouple development milestones from the licensing timeline so that technical readiness does not block on regulatory process.
+Engage legal counsel early to track DPA status. Decouple development milestones from the legal timeline so that technical readiness does not block on paperwork. Draft the workspace-level privacy controls (PII redaction, data residency) independently of the final DPA text.
 
 **Contingency:**
-Prepare a soft launch in an unregulated market while the primary jurisdiction approval is pending.
+Launch in non-EU regions first (US, CA, APAC) while the EU DPA is pending. Gate EU workspace signups behind a feature flag tied to DPA status.
 
 **Owner:** Product Manager
 
 ---
 
-### RISK-03 — Real-time leaderboard at scale unproven
+### RISK-03 — Columnar query performance under concurrent load unproven
 
 **Category:** Technical
 **Probability:** 3 / 5 — Possible
@@ -89,13 +89,13 @@ Prepare a soft launch in an unregulated market while the primary jurisdiction ap
 **Source:** `07a_research_{slug}.md`
 
 **Description:**
-The ADR for the leaderboard service chose Redis Sorted Sets as the primary data structure. This approach has not been load-tested for the projected 10,000 concurrent users. If throughput assumptions are wrong, real-time updates will lag and degrade UX.
+The ADR for the analytics query layer chose ClickHouse as the primary store. This setup has not been load-tested for the projected 200 concurrent dashboard viewers reading against a 10 M-event dataset. If query throughput assumptions are wrong, dashboards will exceed the 500 ms p95 NFR target and degrade UX.
 
 **Mitigation:**
-Conduct a load test spike in the first development sprint. Define a fallback to polling-based updates (every 5s) if WebSocket throughput targets are not met.
+Run a load-test spike in the first development sprint against the reference dataset. Define a caching fallback (5-minute materialised query cache) if raw query throughput does not meet targets.
 
 **Contingency:**
-Switch to polling-based leaderboard refresh with a 10-second interval. Communicate the change as a phased rollout feature.
+Enable the query cache globally and mark cached dashboards with a "last refreshed" timestamp. Communicate the change as a phased rollout feature.
 
 **Owner:** Tech Lead
 
@@ -123,7 +123,7 @@ Freeze scope at the start of each sprint. Defer any mid-sprint scope additions t
 
 ---
 
-### RISK-05 — Telegram Mini App API breaking changes
+### RISK-05 — OIDC / SSO library breaking changes
 
 **Category:** External
 **Probability:** 2 / 5 — Unlikely
@@ -133,13 +133,13 @@ Freeze scope at the start of each sprint. Defer any mid-sprint scope additions t
 **Source:** `07a_research_{slug}.md`
 
 **Description:**
-The product is built as a Telegram Mini App. Telegram has released breaking changes to the Mini Apps API in previous versions. If the API changes after development, UI components and deep links may require rework.
+The product uses a third-party OIDC / SAML library for workspace SSO. Similar libraries have released breaking changes in previous majors without long deprecation windows. If the library releases a breaking change after development, sign-up and SSO flows may require rework.
 
 **Mitigation:**
-Pin the Telegram Web App SDK version used in development. Monitor the Telegram changelog and the `@twa-dev/sdk` release notes. Abstract SDK calls behind a thin adapter layer.
+Pin the library version used in development. Monitor the library changelog and security advisories. Abstract SSO calls behind a thin adapter layer so a future swap to a different provider is isolated to one module.
 
 **Contingency:**
-Allocate a 3-day buffer in the release plan for SDK compatibility fixes.
+Allocate a 3-day buffer in the release plan for library compatibility fixes.
 
 **Owner:** Frontend Lead
 
@@ -167,7 +167,7 @@ Use `/revise` on affected artifacts to propagate changes. Document the delta in
 
 ---
 
-### RISK-07 — Development team unfamiliar with domain
+### RISK-07 — Development team unfamiliar with analytics domain
 
 **Category:** Business
 **Probability:** 2 / 5 — Unlikely
@@ -177,10 +177,10 @@ Use `/revise` on affected artifacts to propagate changes. Document the delta in
 **Source:** `01_brief_{slug}.md`
 
 **Description:**
-The engineering team has limited prior experience with iGaming products. Domain-specific concepts (RTP, bonus wagering, KYC flows) may be misunderstood during implementation, leading to minor defects in edge cases.
+The engineering team has limited prior experience with columnar analytics storage. Domain-specific concepts (event schemas, funnel aggregation, cohort joins) may be misunderstood during implementation, leading to query correctness bugs on edge cases.
 
 **Mitigation:**
-Include a domain onboarding session as part of sprint 0. Reference the iGaming domain glossary in the Handoff document.
+Include a domain onboarding session as part of sprint 0. Reference the SaaS domain glossary in the Handoff document.
 
 **Contingency:**
 Schedule a BA review checkpoint after the first feature is implemented end-to-end.

package/skills/references/templates/sprint-template.md

@@ -1,11 +1,11 @@
-# Sprint Plan: Dragon Fortune
+# Sprint Plan: Nova Analytics
 
-**Domain:** iGaming
+**Domain:** saas
 **Date:** 2026-04-08
-**Slug:** dragon-fortune
+**Slug:** nova-analytics
 **Sprint length:** 2 weeks
 **Team velocity:** 35 SP per sprint
-**Sources:** `00_estimate_dragon-fortune.md`, `03_stories_dragon-fortune.md`, `00_risks_dragon-fortune.md`, `02_srs_dragon-fortune.md`
+**Sources:** `00_estimate_nova-analytics.md`, `03_stories_nova-analytics.md`, `00_risks_nova-analytics.md`, `02_srs_nova-analytics.md`
 
 ---
 
@@ -13,11 +13,11 @@
 
 | Sprint | Goal | Stories | Points | Capacity |
 |--------|------|:-------:|:------:|:--------:|
-| SP-00 | Setup: environment, CI/CD, Telegram Mini App scaffold | — | — | — |
-| SP-01 | Players can register via Telegram and spin a slot for the first time | 6 | 34 SP | 97% |
-| SP-02 | Players can deposit, withdraw, and view wallet balance | 5 | 32 SP | 91% |
-| SP-03 | Referral programme and bonus mechanics are live | 5 | 30 SP | 86% |
-| SP-04 | Admin panel: player management, game configuration, reporting | 4 | 28 SP | 80% |
+| SP-00 | Setup: environment, CI/CD, event-ingestion pipeline scaffold | — | — | — |
+| SP-01 | Users can sign up, connect a data source, and see events arrive | 6 | 34 SP | 97% |
+| SP-02 | Users can build dashboards with funnel, cohort, and trend widgets | 5 | 32 SP | 91% |
+| SP-03 | Alerts and collaboration: thresholds, notifications, sharing, SSO | 5 | 30 SP | 86% |
+| SP-04 | Admin workspace: usage, retention, billing, audit log | 4 | 28 SP | 80% |
 | **Total** | | **20** | **124 SP** | |
 
 **Planned:** 20 stories / 124 SP across 4 sprints (8 weeks)
@@ -35,104 +35,104 @@
 **Tasks:**
 - Configure CI/CD pipeline (GitHub Actions).
 - Provision staging environment on cloud infrastructure.
-- Scaffold Telegram Mini App project with base authentication stub.
-- Establish database schema baseline from `/datadict`.
-- Team domain onboarding session (iGaming concepts, RTP, KYC flow).
+- Scaffold Next.js web app and Node ingestion service with a base authentication stub.
+- Establish OLTP (Postgres) and columnar analytics (ClickHouse) schema baselines from `/datadict`.
+- Team alignment session on analytics domain concepts (event taxonomy, funnel modelling, cohort analysis).
 
 **Definition of Done for SP-00:**
 - [ ] All developers can run the project locally.
-- [ ] Staging environment is accessible via Telegram.
+- [ ] Staging environment is reachable from the team's workstations.
 - [ ] Base CI pipeline runs lint + unit tests on every push.
 
 ---
 
-### SP-01 — Players can register via Telegram and spin a slot for the first time
+### SP-01 — Users can sign up, connect a data source, and see events arrive
 
 **Duration:** Weeks 1–2
 **Capacity:** 35 SP
 
 | US | Title | Epic | Priority | Risk | Estimate |
 |----|-------|------|---------|------|---------|
-| US-001 | Register via Telegram | E-01 Auth | Must | RISK-02 ↑ | 5 SP |
-| US-002 | Launch slot game from Mini App | E-02 Gameplay | Must | — | 3 SP |
-| US-003 | Execute a spin and see result | E-02 Gameplay | Must | RISK-03 ↑ | 13 SP |
-| US-004 | View current wallet balance | E-03 Wallet | Must | — | 3 SP |
-| US-005 | See responsible gambling session limit warning | E-05 Compliance | Must | — | 5 SP |
-| US-006 | View game history (last 20 spins) | E-02 Gameplay | Should | — | 5 SP |
+| US-001 | Sign up via email or Google SSO | E-01 Onboarding | Must | RISK-02 ↑ | 5 SP |
+| US-002 | Create a workspace and invite a teammate | E-01 Onboarding | Must | — | 3 SP |
+| US-003 | Connect first data source (Segment or warehouse) | E-06 Integrations | Must | RISK-03 ↑ | 13 SP |
+| US-004 | View the live event stream from the connected source | E-03 Events | Must | — | 3 SP |
+| US-005 | Validate the incoming event schema against expected taxonomy | E-03 Events | Must | — | 5 SP |
+| US-006 | View the default dashboard with sample metrics | E-02 Dashboards | Should | — | 5 SP |
 
 **Sprint total:** 34 SP / 35 SP capacity (97%)
 
 **Definition of Done for SP-01:**
 - [ ] All stories pass their Acceptance Criteria.
-- [ ] Telegram login tested on iOS and Android Telegram clients.
-- [ ] RNG certified spin result returned in under 200 ms at p95.
+- [ ] Sign-up and SSO flows tested on Chrome, Safari, and Firefox.
+- [ ] End-to-end event ingestion latency under 1 s at p95 from source emit to dashboard read.
 - [ ] No 🔴 Critical open items in `/analyze` for completed stories.
 
 ---
 
-### SP-02 — Players can deposit, withdraw, and view wallet balance
+### SP-02 — Users can build dashboards with funnel, cohort, and trend widgets
 
 **Duration:** Weeks 3–4
 **Capacity:** 35 SP
 
 | US | Title | Epic | Priority | Risk | Estimate |
 |----|-------|------|---------|------|---------|
-| US-007 | Deposit via cryptocurrency | E-03 Wallet | Must | RISK-01 ↑ | 8 SP |
-| US-008 | Deposit via local payment system | E-03 Wallet | Must | RISK-01 ↑ | 8 SP |
-| US-009 | Request withdrawal | E-03 Wallet | Must | — | 8 SP |
-| US-010 | View full transaction history | E-03 Wallet | Should | — | 5 SP |
-| US-011 | Complete KYC identity verification | E-04 Compliance | Must | — | 3 SP |
+| US-007 | Create a custom dashboard from scratch | E-02 Dashboards | Must | RISK-01 ↑ | 8 SP |
+| US-008 | Add a funnel widget with 3 configurable steps | E-02 Dashboards | Must | RISK-01 ↑ | 8 SP |
+| US-009 | Add a cohort retention widget for the last 30 days | E-02 Dashboards | Must | — | 8 SP |
+| US-010 | Save a dashboard to the workspace library | E-02 Dashboards | Should | — | 5 SP |
+| US-011 | Filter a dashboard by date range and segment | E-02 Dashboards | Must | — | 3 SP |
 
 **Sprint total:** 32 SP / 35 SP capacity (91%)
 
 **Definition of Done for SP-02:**
 - [ ] All stories pass their Acceptance Criteria.
-- [ ] Payment provider sandbox integration verified end-to-end.
-- [ ] KYC flow tested with test credentials from the provider.
-- [ ] Withdrawal processed within 24 h in staging environment.
+- [ ] Dashboard read query latency under 500 ms at p95 for the reference dataset (10 M events).
+- [ ] Funnel and cohort calculations verified against the reference dataset to within 0.1%.
+- [ ] Saved dashboards survive workspace reload and session refresh.
 
 ---
 
-### SP-03 — Referral programme and bonus mechanics are live
+### SP-03 — Alerts and collaboration: thresholds, notifications, sharing, SSO
 
 **Duration:** Weeks 5–6
 **Capacity:** 35 SP
 
 | US | Title | Epic | Priority | Risk | Estimate |
 |----|-------|------|---------|------|---------|
-| US-012 | Share referral link and earn bonus | E-06 Referrals | Must | RISK-04 ↑ | 8 SP |
-| US-013 | Claim welcome bonus on first deposit | E-06 Referrals | Must | — | 5 SP |
-| US-014 | View active bonuses and wagering progress | E-06 Referrals | Should | — | 5 SP |
-| US-015 | Set self-exclusion period | E-05 Compliance | Must | — | 5 SP |
-| US-016 | Configure deposit limits | E-05 Compliance | Should | — | 7 SP |
+| US-012 | Set a metric threshold alert on any dashboard widget | E-04 Alerts | Must | RISK-04 ↑ | 8 SP |
+| US-013 | Receive an alert email within 60 s of threshold breach | E-04 Alerts | Must | — | 5 SP |
+| US-014 | Invite a teammate and assign a role (admin, editor, viewer) | E-05 Collaboration | Should | — | 5 SP |
+| US-015 | Share a dashboard read-only link with internal and external viewers | E-05 Collaboration | Must | — | 5 SP |
+| US-016 | Enable SSO (SAML / OIDC) for the workspace | E-05 Collaboration | Should | — | 7 SP |
 
 **Sprint total:** 30 SP / 35 SP capacity (86%)
 
 **Definition of Done for SP-03:**
 - [ ] All stories pass their Acceptance Criteria.
-- [ ] Fraud scoring on referral payouts is active and logged.
-- [ ] Self-exclusion blocks all game access within 5 minutes of activation.
+- [ ] Alert evaluation runs within 60 s of threshold breach in staging.
+- [ ] Read-only share links respect role permissions and expire as configured.
 
 ---
 
-### SP-04 — Admin panel: player management, game configuration, reporting
+### SP-04 — Admin workspace: usage, retention, billing, audit log
 
 **Duration:** Weeks 7–8
 **Capacity:** 35 SP
 
 | US | Title | Epic | Priority | Risk | Estimate |
 |----|-------|------|---------|------|---------|
-| US-017 | Admin views player list and profile | E-07 Admin | Must | — | 5 SP |
-| US-018 | Admin adjusts RTP and payline configuration | E-07 Admin | Must | — | 8 SP |
-| US-019 | Admin views revenue and activity report | E-07 Admin | Should | — | 8 SP |
-| US-020 | Admin flags a player account for review | E-07 Admin | Should | — | 7 SP |
+| US-017 | Admin views the workspace list with per-workspace event volume | E-07 Admin | Must | — | 5 SP |
+| US-018 | Admin adjusts data retention window and event quota per workspace | E-07 Admin | Must | — | 8 SP |
+| US-019 | Admin views the usage-based billing report for the current period | E-07 Admin | Should | — | 8 SP |
+| US-020 | Admin reviews the audit log of workspace and permission changes | E-07 Admin | Should | — | 7 SP |
 
 **Sprint total:** 28 SP / 35 SP capacity (80%)
 
 **Definition of Done for SP-04:**
 - [ ] All stories pass their Acceptance Criteria.
-- [ ] RTP configuration change takes effect within 1 spin cycle.
-- [ ] Revenue report matches transaction ledger to within 0.01%.
+- [ ] Retention changes take effect on the next hourly compaction run.
+- [ ] Billing report matches the underlying usage ledger to within 0.01%.
 
 ---
 
@@ -142,10 +142,10 @@ Stories not assigned to any sprint — below MVP capacity or marked Could/Won't:
 
 | US | Title | Epic | Priority | Estimate | Reason |
 |----|-------|------|---------|---------|--------|
-| US-021 | Export transaction history as PDF | E-03 Wallet | Could | 5 SP | Capacity exceeded — defer to v1.1 |
-| US-022 | Multi-language support (EN / RU / KZ) | E-01 Auth | Could | 8 SP | Deferred — requires i18n infrastructure |
-| US-023 | Live chat support widget | E-08 Support | Could | 3 SP | Deferred — third-party integration |
-| US-024 | Affiliate dashboard | E-06 Referrals | Won't | 2 SP | Out of MVP scope |
+| US-021 | Export a dashboard snapshot as PDF | E-02 Dashboards | Could | 5 SP | Capacity exceeded — defer to v1.1 |
+| US-022 | Mobile companion app for alert notifications | E-04 Alerts | Could | 8 SP | Deferred — requires mobile infrastructure |
+| US-023 | In-app chat support widget | E-08 Support | Could | 3 SP | Deferred — third-party integration |
+| US-024 | White-label dashboards for embedded use | E-05 Collaboration | Won't | 2 SP | Out of MVP scope |
 
 ---
 

package/skills/srs/SKILL.md

@@ -15,7 +15,7 @@ Second step of the BA Toolkit pipeline. Generates an SRS adapted from IEEE 830.
 0. If `00_principles_*.md` exists in the output directory, load it and apply its conventions (artifact language, ID format, traceability requirements, Definition of Ready, quality gate threshold).
 1. Read `01_brief_*.md` from the output directory. If missing, warn and suggest running `/brief`.
 2. Extract: slug, domain, business goals, functionality, stakeholders, constraints, glossary.
-3. If domain is `igaming`, `fintech`, or `saas`, load `references/domains/{domain}.md`, section `2. /srs`.
+3. If a matching `references/domains/{domain}.md` file exists (currently: `saas`, `fintech`, `ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media`, `real-estate`, `igaming`), load it and apply its section `2. /srs`.
 
 ## Environment