@kudusov.takhir/ba-toolkit 4.0.1 → 4.0.3

package/CHANGELOG.md

@@ -11,6 +11,26 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [4.0.3] — 2026-04-12
+
+### Fixed
+
+- **Shell fallback scripts (`init.sh`, `init.ps1`) were missing three domains** added in v3.3.0 — `edtech`, `govtech`, `ai-ml`. Users who set up projects via the shell scripts only saw 10 domains instead of 13.
+- **Shell fallback scripts generated an outdated AGENTS.md** — missing `/discovery` (stage 0), `/implement-plan` (stage 12), and the Utility Skills section. Stage numbering for `/principles` was `0` instead of `0a`. Both scripts now match the canonical template at `skills/references/templates/agents-template.md`.
+- **`docs/TROUBLESHOOTING.md` listed only 9 of 12 domain reference files** — added `edtech`, `govtech`, `ai-ml` and clarified that `custom` has no reference file.
+- **Removed orphaned `skills/{brief,srs,…}/` directory** — an empty folder with a literal brace-expansion string as its name, shipped in the npm package.
+
+---
+
+## [4.0.2] — 2026-04-12
+
+### Fixed
+
+- **Skills invented their own project slug instead of reading the one `ba-toolkit init` wrote to `AGENTS.md`.** Reproduction: `ba-toolkit init --name "New Test App"` produced `**Slug:** new-test-app` in `AGENTS.md`, but a follow-up `/brief` saved `01_brief_knitted-socks.md` — slug picked from conversation context, not from the scaffold. Root cause: pipeline skills carried v3.x-era wording (`/brief`: *"slug — kebab-case, fixed here for the entire pipeline"*; `/principles`: *"extract the slug from the brief, otherwise ask the user"*; `/discovery`: *"derive from the project name"*) and never read the canonical slug from the managed block of `AGENTS.md` that v4.0 `init` writes. Downstream skills inherited the wrong slug from the brief filename and the project silently desynchronised. Fixed by adding `skills/references/slug-source.md` (the single rule + fallbacks + rationale) and an explicit "Slug source" directive in every pipeline and utility skill that emits a `{slug}` filename: `/brief`, `/discovery`, `/principles`, `/srs`, `/stories`, `/usecases`, `/ac`, `/nfr`, `/datadict`, `/research`, `/apicontract`, `/wireframes`, `/scenarios`, `/handoff`, `/implement-plan`, `/analyze`, `/trace`, `/risk`, `/sprint`, `/glossary`, `/estimate`, `/export`. Each now reads `**Slug:**` from `AGENTS.md` verbatim and refuses to invent a new one. `/discovery` is the one exception — it may still derive a slug if `AGENTS.md` does not yet exist (the brain-storm-before-init flow), and otherwise honours the scaffold value instead of renaming the project.
+- **`ba-toolkit init` crashed on second run with "Input stream closed before all prompts could be answered."** When an existing install was detected after the domain/agent arrow-key menus, the "Replace existing BA Toolkit install?" prompt rejected immediately. Root cause: the raw-mode menu closes the shared readline interface, which sets a sticky `inputClosed` flag that was never reset when `ensureReadline()` recreated the interface for the next `prompt()`. Fixed by clearing the flag on interface recreation.
+
+---
+
 ## [4.0.1] — 2026-04-12
 
 ### Fixed
@@ -879,7 +899,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.10.1...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.3...HEAD
+[4.0.3]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.2...v4.0.3
+[4.0.2]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.1...v4.0.2
 [4.0.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.0...v4.0.1
 [4.0.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.13.1...v4.0.0
 [3.13.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.13.0...v3.13.1

package/bin/ba-toolkit.js

@@ -193,6 +193,12 @@ let inputClosed = false;
 
 function ensureReadline() {
   if (sharedRl) return;
+  // Reset the sticky close flag — a previous interface may have been
+  // torn down by closeReadline() (e.g. before an arrow-key menu took
+  // over stdin in raw mode). Without this reset, the next prompt()
+  // after a menu would immediately reject with INPUT_CLOSED even
+  // though stdin is still perfectly usable.
+  inputClosed = false;
   sharedRl = readline.createInterface({ input: process.stdin, output: process.stdout });
   sharedRl.on('line', (line) => {
     if (waiters.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "AI-powered Business Analyst pipeline — 24 skills from concept discovery to a sequenced implementation plan an AI coding agent can execute, with one-command Notion + Confluence publish. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf.",
   "keywords": [
     "business-analyst",

package/skills/ac/SKILL.md

@@ -42,6 +42,8 @@ Supplement with domain-specific questions from the reference.
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `05_ac_{slug}.md`
 
 The full per-AC field set lives at `references/templates/ac-template.md` and is the single source of truth. Each AC carries: ID (`AC-NNN-NN`), Type (positive / negative / boundary / performance / security), Given / When / Then, Linked US, Linked UC, Linked FR, Linked NFR (for performance/security ACs), Source (which business rule from `02_srs_{slug}.md` drove this AC), and Verification method (automated test / manual test / observed in production). The artifact also carries a US → AC coverage matrix at the bottom.

package/skills/analyze/SKILL.md

@@ -86,6 +86,8 @@ The 8 canonical categories cover the IEEE 830 §4.3 SRS quality attributes (corr
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `00_analyze_{slug}.md`
 
 The full report layout lives at `references/templates/analyze-template.md` and is the single source of truth. Each finding carries: ID, Severity, Category (one of the 8 above), Location (artifact + element ID), Description, Recommendation, and **Owner** (which role is accountable for fixing the finding — assigned by `00_principles_*.md` §4 Definition of Ready ownership where applicable, otherwise by domain default).

package/skills/apicontract/SKILL.md

@@ -47,6 +47,8 @@ Supplement with domain-specific questions from the reference.
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `08_apicontract_{slug}.md`
 
 ```markdown

package/skills/brief/SKILL.md

@@ -61,7 +61,9 @@ If a domain reference is loaded, supplement general questions with domain-specif
 
 ### 5. Generation
 
-**File:** `01_brief_{slug}.md` (slug — kebab-case, fixed here for the entire pipeline).
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` at the project root (look in cwd first; if cwd is `output/`, check `../AGENTS.md`). Use that value verbatim — do not invent or re-derive a slug from the project name. `ba-toolkit init` is the single source of truth; see [`../references/slug-source.md`](../references/slug-source.md) for fallback rules and rationale.
+
+**File:** `01_brief_{slug}.md`
 
 ```markdown
 # Project Brief: {Project Name}

package/skills/datadict/SKILL.md

@@ -45,6 +45,8 @@ Supplement with domain-specific questions and mandatory entities from the refere
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `07_datadict_{slug}.md`
 
 The full per-entity field set lives at `references/templates/datadict-template.md` and is the single source of truth. Each entity carries: name, **Source** (which FR/US introduced this entity), **Owner** (which team / role curates it), **Sensitivity** (Public / Internal / Confidential / PII / PCI / PHI), description, attribute table (with logical types, not DBMS-specific), relationships with cascade rules, **state machine** (if applicable), indexes (logical, not physical), retention policy, and notes. The artifact carries an FR → Entity coverage matrix at the bottom.

package/skills/discovery/SKILL.md

@@ -54,7 +54,9 @@ If a topic was already covered by inline context or the lead-in answer, skip it
 
 ### 5. Generation
 
-**File:** `00_discovery_{slug}.md` (slug — kebab-case, derived from the project name; if the user has not yet picked a name, propose 2–3 candidates and let them choose).
+**Slug:** if `AGENTS.md` exists at the project root with a `**Slug:**` line in its managed block, read that value verbatim and use it as `{slug}` — `ba-toolkit init` is the single source of truth. Do **not** propose a new slug, and do **not** rename the project the user already scaffolded. Only when `AGENTS.md` is absent (the user is brain-storming before running `ba-toolkit init`) may you derive a kebab-case slug from the project name; if the user has not yet picked a name, propose 2–3 candidates and let them choose. See [`../references/slug-source.md`](../references/slug-source.md) for the full rule.
+
+**File:** `00_discovery_{slug}.md`
 
 ```markdown
 # Discovery: {Project Name}

package/skills/estimate/SKILL.md

@@ -87,6 +87,8 @@ This skill produces a **single-estimator analytical pass**. A senior BA running
 
 ## Output
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 ### If scope ≤ 20 stories — update `03_stories_{slug}.md` in-place
 
 Add a `**Estimate:**` field to each US block and append the Estimation Summary table at the end of the file.

package/skills/export/SKILL.md

@@ -197,6 +197,8 @@ Compatible with Jira CSV import, Trello, Asana, Monday.com, and Google Sheets. I
 
 ## Output
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 Save the export file to the output directory alongside the artifacts:
 
 ```

package/skills/glossary/SKILL.md

@@ -99,6 +99,8 @@ Identify terms used in requirements but not defined anywhere in the glossary or
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 Save `00_glossary_{slug}.md` to the output directory.
 
 ```markdown

package/skills/handoff/SKILL.md

@@ -24,6 +24,8 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 No interview. All content is derived from the existing artifacts. The full template lives at `references/templates/handoff-template.md` and is the single source of truth — including the full inventory of pipeline-stage and cross-cutting artifacts (`/discovery`, `/principles`, `/implement-plan`, `/sprint`, `/risk`, `/glossary`, `/trace`, `/analyze`, `/estimate`), the Brief Goal → FR / FR → NFR / FR → API forward-traceability tables, the ADR summary, and the formal Sign-off section.
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `11_handoff_{slug}.md`
 
 ```markdown

package/skills/implement-plan/SKILL.md

@@ -115,6 +115,8 @@ Within a phase, order tasks so each task's `dependsOn` list points only at tasks
 
 ### 7. Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `12_implplan_{slug}.md`
 
 ```markdown

package/skills/nfr/SKILL.md

@@ -48,6 +48,8 @@ Supplement with domain-specific questions and mandatory categories from the refe
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `06_nfr_{slug}.md`
 
 The full per-NFR field set lives at `references/templates/nfr-template.md` and is the single source of truth. Each NFR carries: ID (`NFR-NNN`), ISO 25010 characteristic, sub-characteristic, description, measurable metric, **acceptance threshold** (the bar that says "we passed"), verification method, source (which stakeholder, regulation, or FR drove this NFR), rationale, priority, and linked FRs / USs / Brief constraints. The artifact carries an FR → NFR coverage matrix and a per-characteristic priority summary at the bottom.

package/skills/principles/SKILL.md

@@ -23,7 +23,7 @@ If `00_principles_*.md` already exists, load it and offer to:
 - Amend a specific section (`/revise [section]`).
 - Regenerate from scratch.
 
-If `01_brief_*.md` already exists, extract the slug and domain from it. Otherwise, ask the user for the project name (to derive the slug) and domain.
+**Slug source.** Read the `**Slug:**` line from the managed block of `AGENTS.md` at the project root (cwd, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. `ba-toolkit init` is the single source of truth — do not invent or re-derive a slug. If `AGENTS.md` is missing, warn the user to run `ba-toolkit init` first. See [`../references/slug-source.md`](../references/slug-source.md) for the full rule and fallbacks. The domain comes from the same managed block; if `01_brief_*.md` already exists, prefer the brief's domain over the scaffold default.
 
 ### 3. Interview
 

package/skills/references/slug-source.md

@@ -0,0 +1,30 @@
+# Slug source — single rule
+
+`ba-toolkit init` is the **single source of truth** for the project slug. It writes the slug into the managed block of `AGENTS.md` at the project root:
+
+```
+<!-- ba-toolkit:begin managed -->
+...
+**Slug:** new-test-app
+...
+<!-- ba-toolkit:end managed -->
+```
+
+Every skill that emits a file whose name contains `{slug}` (e.g. `01_brief_{slug}.md`, `02_srs_{slug}.md`, `00_analyze_{slug}.md`) **must read the slug from this line and use it verbatim**. Do not invent a slug, do not re-derive it from the project name, do not pick one based on conversation context.
+
+## How to read the slug
+
+1. Locate `AGENTS.md`. Look in `cwd` first; if `cwd` is `output/`, check `../AGENTS.md`.
+2. Find the managed block delimited by `<!-- ba-toolkit:begin managed -->` and `<!-- ba-toolkit:end managed -->`.
+3. Inside the block, parse the line that starts with `**Slug:**`. Strip whitespace. The remainder is the slug.
+4. Use that exact string as `{slug}` in every output filename for this run.
+
+## Fallbacks
+
+- **No `AGENTS.md` at the project root.** The project was not scaffolded with `ba-toolkit init`. Stop and tell the user to run `ba-toolkit init` first. Do not invent a slug to keep going.
+- **`AGENTS.md` exists but has no managed block** (legacy file the user authored manually). Look for `01_brief_*.md` in `output/`; the part between `01_brief_` and `.md` is the slug. If no brief file exists either, ask the user for the slug explicitly — do not invent one.
+- **`AGENTS.md` managed block is present but the `**Slug:**` line is missing or empty.** Treat as a corrupted scaffold. Tell the user to re-run `ba-toolkit init` to repair `AGENTS.md`. Do not invent a slug.
+
+## Why
+
+Before v4.0, `/brief` was the entry point and decided the slug. In v4.0, `ba-toolkit init` runs first and fixes the slug at scaffold time, so that `AGENTS.md` and the file names in `output/` are guaranteed to agree from the very first artifact. Skills that still derive a slug locally (from the project name or from conversation context) silently desynchronise the project: `AGENTS.md` says one thing, the artifact filenames say another, downstream skills pick up the wrong slug, and the user sees `01_brief_knitted-socks.md` next to `**Slug:** new-test-app`.

package/skills/research/SKILL.md

@@ -53,6 +53,8 @@ Supplement with domain-specific typical integrations from the reference.
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `07a_research_{slug}.md`
 
 ```markdown

package/skills/risk/SKILL.md

@@ -115,6 +115,8 @@ Assign each risk one of the four canonical treatment strategies (PMBOK 7 / ISO 3
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 Save `00_risks_{slug}.md` to the output directory.
 
 ```markdown

package/skills/scenarios/SKILL.md

@@ -41,6 +41,8 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `10_scenarios_{slug}.md`
 
 The full per-scenario field set lives at `references/templates/scenarios-template.md` and is the single source of truth. Each scenario carries: ID (`SC-NNN`), Title, Persona (named with context), Type (happy / negative / edge / performance / security), Priority (P1 / P2 / P3), Entry point, Platform, **Source** (Linked US, Linked FR, Linked NFR), Linked AC, Steps table, Expected Outcome, Failure Conditions. The artifact carries a coverage matrix at the bottom showing US, AC scenario, FR, NFR, and WF coverage.

package/skills/sprint/SKILL.md

@@ -92,6 +92,8 @@ For each sprint, derive a one-sentence goal that describes the primary user-faci
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 Save `00_sprint_{slug}.md` to the output directory. The full layout lives at `references/templates/sprint-template.md` and is the single source of truth — including the per-story Persona column (per v3.5.0+ stories template), the net-velocity header, and the sprint-level Definition of Done.
 
 Sprint IDs are sequential (SP-00, SP-01, SP-02, …). SP-00 is reserved for setup/architecture sprint if requested.

package/skills/srs/SKILL.md

@@ -14,7 +14,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.
+2. Extract: domain, business goals, functionality, stakeholders, constraints, glossary. The slug comes from `AGENTS.md`, not from the brief filename — see [`../references/slug-source.md`](../references/slug-source.md).
 3. If a matching `references/domains/{domain}.md` file exists (currently: `saas`, `fintech`, `ecommerce`, `healthcare`, `logistics`, `on-demand`, `social-media`, `real-estate`, `igaming`, `edtech`, `govtech`, `ai-ml`), load it and apply its section `2. /srs`.
 
 ## Environment

package/skills/stories/SKILL.md

@@ -38,6 +38,8 @@ Supplement with domain-specific questions and typical epics from the reference.
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `03_stories_{slug}.md`
 
 The full template lives at `references/templates/stories-template.md` and is the single source of truth for the per-story field set. The fields are:

package/skills/trace/SKILL.md

@@ -33,6 +33,8 @@ If the user invokes `/trace` with no inline hint, ask the following short calibr
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `00_trace_{slug}.md`
 
 The full per-axis matrix layout lives at `references/templates/trace-template.md` and is the single source of truth. The artifact carries: a Forward Traceability matrix (FR → all downstream artifacts), a Reverse Traceability matrix (US, UC, AC, NFR, Entity, API, WF, SC, Task → FR), Coverage Gaps grouped by severity (Critical / High / Medium / Low per the principles thresholds), Coverage Statistics per artifact pair, and Recommended Actions sorted by severity.

package/skills/usecases/SKILL.md

@@ -41,6 +41,8 @@ Supplement with domain-specific questions and typical exceptional flows from the
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `04_usecases_{slug}.md`
 
 The full per-UC field set lives at `references/templates/usecases-template.md` and is the single source of truth. Each UC carries: Goal in Context, Scope, Level, Primary Actor, Supporting Actors, Stakeholders & Interests, Pre-conditions, Trigger, Main Success Scenario (numbered table), Extensions / Alternative Flows, Exception Flows, Post-conditions (success guarantees + minimal guarantees), Source (linked US/FR), Linked WF, Linked AC. The artifact also carries a US → UC coverage matrix at the bottom.

package/skills/wireframes/SKILL.md

@@ -41,6 +41,8 @@ Supplement with domain-specific questions and typical screens from the reference
 
 ## Generation
 
+**Slug:** read the `**Slug:**` line from the managed block of `AGENTS.md` (project root, or `../AGENTS.md` if cwd is `output/`) and use it verbatim. See [`../references/slug-source.md`](../references/slug-source.md).
+
 **File:** `09_wireframes_{slug}.md`
 
 ```markdown