@kudusov.takhir/ba-toolkit 4.1.0 → 4.1.2

package/CHANGELOG.md

@@ -11,6 +11,22 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [4.1.2] — 2026-04-14
+
+### Fixed
+
+- **Install commands now quote the scoped package name** in README, USAGE, TROUBLESHOOTING, ROADMAP, website docs, and the `init.sh`/`init.ps1` next-steps output. Unquoted `@kudusov.takhir/ba-toolkit` can trip shells (notably zsh with globbing/expansion rules) where the `@` or `.` tokens are interpreted; wrapping in single quotes (`'@kudusov.takhir/ba-toolkit'`) works across bash, zsh, and PowerShell. Historical `CHANGELOG.md` entries were not retroactively edited.
+
+---
+
+## [4.1.1] — 2026-04-12
+
+### Fixed
+
+- **Systematic mixed-language output in non-English artifacts** — when users wrote in a non-English language, artifacts got English section headings, table headers, field labels ("**Priority:**", "**Description:**", etc.), and closing summaries ("Artifact saved:", "Next step:", etc.) while body text was in the user's language. Root cause: templates and reference files are English-only (correct per convention), but only 9 of 29 skills had an explicit rule to translate structural elements. Created `skills/references/language-rule.md` — a single shared reference defining exactly what to translate (headings, labels, table headers, closing message text, interview acknowledgments) and what stays in English (element IDs, file paths, slash commands, MoSCoW values, INVEST criteria). All 29 SKILL.md files now reference this file from their Style section. Updated `closing-message.md` with explicit translation guidance for all template labels. Updated `interview-protocol.md` rule 5 to specify acknowledgments are in the user's language. Removed per-template HTML language comments from `stories-template.md` and `ac-template.md` (now covered by the shared rule).
+
+---
+
 ## [4.1.0] — 2026-04-12
 
 ### Added
@@ -922,7 +938,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.1.0...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.1.2...HEAD
+[4.1.2]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.1.1...v4.1.2
+[4.1.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.1.0...v4.1.1
 [4.1.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.4...v4.1.0
 [4.0.4]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.3...v4.0.4
 [4.0.3]: https://github.com/TakhirKudusov/ba-toolkit/compare/v4.0.2...v4.0.3

package/README.md

@@ -42,13 +42,13 @@ Artifacts are generated in whatever language you write in — ask in English, ge
 # Full setup in one command — prompts for project name, domain, and
 # AI agent, then creates output/, AGENTS.md, and installs the skills
 # into the chosen agent's directory.
-npx @kudusov.takhir/ba-toolkit init
+npx '@kudusov.takhir/ba-toolkit' init
 
 # Non-interactive (e.g. for CI): pass every choice on the command line.
-npx @kudusov.takhir/ba-toolkit init --name "My App" --domain saas --for claude-code
+npx '@kudusov.takhir/ba-toolkit' init --name "My App" --domain saas --for claude-code
 
 # Or install globally and reuse across projects:
-npm install -g @kudusov.takhir/ba-toolkit
+npm install -g '@kudusov.takhir/ba-toolkit'
 ba-toolkit init
 ```
 
@@ -139,7 +139,7 @@ bash init.sh
 .\init.ps1
 ```
 
-Equivalent to `npx @kudusov.takhir/ba-toolkit init` — asks for a slug, name, and domain, then creates `output/` and an `AGENTS.md` with the pipeline status table.
+Equivalent to `npx '@kudusov.takhir/ba-toolkit' init` — asks for a slug, name, and domain, then creates `output/` and an `AGENTS.md` with the pipeline status table.
 
 ### Updating a manual install
 

package/bin/ba-toolkit.js

@@ -1939,7 +1939,7 @@ ${bold('EXAMPLES')}
   ba-toolkit uninstall --for claude-code --global
   ba-toolkit uninstall --for cursor --dry-run
 
-  # After 'npm update -g @kudusov.takhir/ba-toolkit', refresh the skills.
+  # After "npm update -g '@kudusov.takhir/ba-toolkit'", refresh the skills.
   ba-toolkit upgrade --for claude-code
   ba-toolkit upgrade --for cursor --dry-run
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "description": "AI-powered Business Analyst pipeline — 29 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

@@ -84,4 +84,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request.
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/analyze/SKILL.md

@@ -165,4 +165,4 @@ No pipeline advancement — this is a quality checkpoint, not a pipeline step.
 
 ## Style
 
-Formal, neutral. No emoji, slang. Generate output in the language of the artifacts. Element IDs, file names, and table column headers remain in English.
+Formal, neutral. No emoji, slang. Generate output in the language of the artifacts — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/apicontract/SKILL.md

@@ -129,4 +129,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request. Endpoint names, field names, and error codes remain in English.
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English. Endpoint names, field names, and error codes remain in English.

package/skills/brief/SKILL.md

@@ -132,4 +132,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang, or evaluative language. Terms and abbreviations explained in parentheses on first use. Generate the artifact in the language of the user's request. Section headings, table headers, and labels also in the user's language.
+Formal, neutral. No emoji, slang, or evaluative language. Terms and abbreviations explained in parentheses on first use. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/clarify/SKILL.md

@@ -127,4 +127,4 @@ No pipeline advancement — return to the current artifact's workflow.
 
 ## Style
 
-Formal, neutral. Questions must be specific and reference exact element IDs. Generate output in the language of the artifact.
+Formal, neutral. Questions must be specific and reference exact element IDs. Generate output in the language of the artifact — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/datadict/SKILL.md

@@ -84,4 +84,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request.
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/discovery/SKILL.md

@@ -160,4 +160,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral, hypothesis-driven. No emoji, slang, or evaluative language ("amazing", "game-changing"). Frame every claim as a hypothesis to validate, not a fact. Generate the artifact in the language of the user's request. Section headings, table headers, and labels also in the user's language.
+Formal, neutral, hypothesis-driven. No emoji, slang, or evaluative language ("amazing", "game-changing"). Frame every claim as a hypothesis to validate, not a fact. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/done/SKILL.md

@@ -115,4 +115,4 @@ Pipeline complete. Hand `12_implplan_{slug}.md` to your AI coding agent (Claude
 
 ## Style
 
-Formal, neutral. Generate output in the language of the artifact.
+Formal, neutral. Generate output in the language of the artifact — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/estimate/SKILL.md

@@ -155,4 +155,4 @@ Available commands: `/estimate [US-NNN]` (re-estimate a story) · `/split [US-NN
 
 ## Style
 
-Be explicit about the rationale for each estimate. Use concise bullet drivers, not paragraphs. Generate output in the language of the artifact.
+Be explicit about the rationale for each estimate. Use concise bullet drivers, not paragraphs. Generate output in the language of the artifact — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/expand/SKILL.md

@@ -109,4 +109,4 @@ No pipeline advancement — return to the current artifact's workflow.
 
 ## Style
 
-Formal, neutral. Generate output in the language of the artifact.
+Formal, neutral. Generate output in the language of the artifact — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/export/SKILL.md

@@ -220,4 +220,4 @@ Available commands: `/export [format]` (export in another format) · `/estimate`
 
 ## Style
 
-Generate only valid JSON or CSV. Do not include comments inside JSON files. Use double quotes for all JSON strings. Escape newlines in description fields as `\n`. Generate output in English regardless of the artifact language (issue trackers expect English field values unless explicitly told otherwise).
+Generate only valid JSON or CSV. Do not include comments inside JSON files. Use double quotes for all JSON strings. Escape newlines in description fields as `\n`. Generate output in English regardless of the artifact language (issue trackers expect English field values unless explicitly told otherwise). Chat messages (interview questions, closing summary) follow `references/language-rule.md` — use the user's language.

package/skills/glossary/SKILL.md

@@ -161,4 +161,4 @@ Available commands: `/glossary drift` (drift report only) · `/glossary add [Ter
 
 ## Style
 
-Neutral, precise. Term definitions should be one sentence, domain-specific, and consistent with the artifact language set in `00_principles_{slug}.md`. Do not invent definitions — only use what is stated or clearly implied in the artifacts.
+Neutral, precise. Term definitions should be one sentence, domain-specific, and consistent with the artifact language. Do not invent definitions — only use what is stated or clearly implied in the artifacts. See `references/language-rule.md` for what to translate and what stays in English.

package/skills/handoff/SKILL.md

@@ -190,4 +190,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji in the saved file. Generate in the artifact language. English for IDs, file names, table column headers, and code.
+Formal, neutral. No emoji in the saved file. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/implement-plan/SKILL.md

@@ -280,4 +280,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral, imperative. No emoji in the saved file. Phase goals are user-outcome sentences, not task lists. Task titles are imperative verbs ("Create", "Implement", "Wire", "Migrate", "Document"). Definition-of-Done bullets are checkable, not aspirational. Generate the artifact in the language of the user's request; section headings, table headers, and labels also in the user's language. ID columns and code identifiers (`T-04-007`, `FR-001`, `Entity:User`, file paths) stay ASCII.
+Formal, neutral, imperative. No emoji in the saved file. Phase goals are user-outcome sentences, not task lists. Task titles are imperative verbs ("Create", "Implement", "Wire", "Migrate", "Document"). Definition-of-Done bullets are checkable, not aspirational. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/nfr/SKILL.md

@@ -87,4 +87,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request.
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/principles/SKILL.md

@@ -182,4 +182,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. The principles file itself is generated in the artifact language defined in section 1. Section headings and table column headers remain in that language.
+Formal, neutral. No emoji, slang. The principles file itself is generated in the artifact language defined in section 1. See `references/language-rule.md` for what to translate and what stays in English.

package/skills/publish/SKILL.md

@@ -76,4 +76,4 @@ Do not build a `Next step:` block — `/publish` is cross-cutting and does not a
 
 ## Style
 
-Formal, neutral. No emoji. Generate the chat reply in the language of the user's first message. Keep the report under 10 lines: paths, counts, two next-step lines, optional re-run hint.
+Formal, neutral. No emoji. Generate the chat reply in the language of the user's first message — see `references/language-rule.md` for what to translate and what stays in English. Keep the report under 10 lines: paths, counts, two next-step lines, optional re-run hint.

package/skills/references/closing-message.md

@@ -4,7 +4,7 @@ After saving an artifact, every BA Toolkit skill presents a closing summary bloc
 
 ## Format
 
-Present the block in the same language as the artifact.
+Present the block in the same language as the artifact. The template below is written in English because this file follows the project's English-only convention. At generation time, translate all labels ("Artifact saved:", "Available commands:", "Next step:", "What it produces:", "Quality check before moving on:", table headers) to the artifact's language. Slash commands (`/clarify`, `/revise`, etc.) and file paths stay as-is. See `references/language-rule.md` for the full list of what to translate and what stays in English.
 
 ```
 Artifact saved: `{file_path}`

package/skills/references/interview-protocol.md

@@ -17,7 +17,7 @@ Every BA Toolkit skill that gathers information from the user MUST follow this p
 
 4. **Wait for the answer.** Do not generate the next question or any part of the artifact until the user has replied. A non-answer (e.g. "I don't know", "skip") is a valid answer — record it as "unknown" and move on. The user can respond with the letter ID (`a`, `b`, …), the verbatim variant text, or — for the free-text row — any text of their own.
 
-5. **Acknowledge, then proceed.** After each answer, reflect it back in one line (e.g. "Got it — primary user is the Ops team at mid-size logistics companies.") before asking the next question. This catches misunderstandings early.
+5. **Acknowledge, then proceed.** After each answer, reflect it back in one line **in the user's language** (e.g. "Got it — primary user is the Ops team at mid-size logistics companies.") before asking the next question. This catches misunderstandings early.
 
 6. **Batch only when the user asks.** If the user explicitly says "just give me all the questions at once" or "I'll answer in one go", switch to a single numbered list. Otherwise stay one-at-a-time.
 

package/skills/references/language-rule.md

@@ -0,0 +1,31 @@
+# Language Rule
+
+Template files, reference documents, and closing-message templates in BA Toolkit are written in English per the project's English-only file convention. When generating artifacts, chat summaries (closing messages), and interview questions, translate **all** of the following to the user's language:
+
+## Translate to the user's language
+
+- Section headings (`##` and `###`)
+- Table headers (`| Column | ... |`)
+- Field labels (`**Priority:**`, `**Description:**`, `**Type:**`, `**Source:**`, `**Linked FR:**`, `**Depends on:**`, `**Notes:**`, etc.)
+- User story labels (`**As**` / `**I want to**` / `**so that**`)
+- Acceptance criteria labels (`**Given**` / `**When**` / `**Then**`)
+- Closing message labels ("Artifact saved:", "Available commands:", "Next step:", "What it produces:", "Quality check before moving on:", table headers in the commands table)
+- Interview acknowledgments ("Got it — ...")
+- Interview question text and option variants (per interview-protocol rule 11)
+
+## Keep in English/ASCII regardless of artifact language
+
+- Element IDs: FR-001, US-001, AC-001-01, NFR-001, UC-001, E-01, etc.
+- File paths and filenames: `output/01_brief_my-app.md`
+- Slash commands: `/brief`, `/srs`, `/clarify`, `/revise`, `/validate`, `/done`, etc.
+- The `(recommended)` marker in interview option tables
+- Letter IDs in option tables: `a`, `b`, `c`, `d`, `e`
+- MoSCoW priority values: Must, Should, Could, Won't
+- INVEST criteria names: Independent, Negotiable, Valuable, Estimable, Small, Testable
+- Code identifiers, API endpoint paths, HTTP methods, status codes
+- Technical terms that are industry-standard English (REST, JWT, OAuth, CRUD, etc.)
+- ISO/IEEE standard references (IEEE 830, ISO 25010, ISO 31000, etc.)
+
+## Why this rule exists
+
+Without this rule, the AI copies English labels from templates verbatim and only translates body text, producing mixed-language artifacts — e.g., Russian content under English headings, or an English closing summary after a Russian-language interview. The rule ensures that every user-facing text element matches the artifact's language while technical identifiers stay stable for cross-referencing.

package/skills/research/SKILL.md

@@ -152,4 +152,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Generate in the artifact language. Technical terms (ADR, REST, WebSocket, JWT) remain in English. Architecture option names remain in English.
+Formal, neutral. No emoji, slang. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English. Architecture option names remain in English.

package/skills/revise/SKILL.md

@@ -121,4 +121,4 @@ No pipeline advancement — return to the current artifact's workflow.
 
 ## Style
 
-Formal, neutral. Generate output in the language of the artifact.
+Formal, neutral. Generate output in the language of the artifact — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/risk/SKILL.md

@@ -196,4 +196,4 @@ Available commands: `/risk add [description]` · `/risk update RISK-NN` · `/cla
 
 ## Style
 
-Concise, factual. Risk descriptions state the condition and consequence ("If X happens, then Y will occur"). Do not inflate severity — score based on evidence from artifacts, not speculation. Use the artifact language set in `00_principles_{slug}.md`.
+Concise, factual. Risk descriptions state the condition and consequence ("If X happens, then Y will occur"). Do not inflate severity — score based on evidence from artifacts, not speculation. Generate output in the language of the artifact — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/scenarios/SKILL.md

@@ -80,4 +80,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Generate in the artifact language. Persona names, screen labels, and API paths remain in their original language/format.
+Formal, neutral. No emoji, slang. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English. Persona names, screen labels, and API paths remain in their original language/format.

package/skills/split/SKILL.md

@@ -148,4 +148,4 @@ No pipeline advancement — return to the current artifact's workflow.
 
 ## Style
 
-Formal, neutral. Generate output in the language of the artifact.
+Formal, neutral. Generate output in the language of the artifact — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/sprint/SKILL.md

@@ -120,4 +120,4 @@ Available commands: `/sprint [SP-NN]` (re-plan a sprint) · `/split [US-NNN]` (s
 
 ## Style
 
-Be specific about sprint goals — one user-outcome sentence per sprint. Show capacity percentages to make overloading visible at a glance. Flag risks and deadline conflicts explicitly, do not bury them in footnotes. Generate output in the language of the artifact.
+Be specific about sprint goals — one user-outcome sentence per sprint. Show capacity percentages to make overloading visible at a glance. Flag risks and deadline conflicts explicitly, do not bury them in footnotes. Generate output in the language of the artifact — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/srs/SKILL.md

@@ -146,4 +146,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Terms explained in parentheses on first use. Generate the artifact in the language of the user's request.
+Formal, neutral. No emoji, slang. Terms explained in parentheses on first use. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/stories/SKILL.md

@@ -87,4 +87,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request.
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/trace/SKILL.md

@@ -67,4 +67,4 @@ No further pipeline step — use `/analyze` for a detailed cross-artifact qualit
 
 ## Style
 
-Formal, neutral. No emoji, slang. Generate the artifact in the language of the user's request.
+Formal, neutral. No emoji, slang. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/usecases/SKILL.md

@@ -79,4 +79,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request.
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/validate/SKILL.md

@@ -121,4 +121,4 @@ No pipeline advancement — return to the current artifact's workflow.
 
 ## Style
 
-Formal, neutral. Findings must reference exact element IDs and section numbers. Generate output in the language of the artifact.
+Formal, neutral. Findings must reference exact element IDs and section numbers. Generate output in the language of the artifact — see `references/language-rule.md` for what to translate and what stays in English.

package/skills/wireframes/SKILL.md

@@ -113,4 +113,4 @@ Build the `Next step:` block from the pipeline lookup table in `references/closi
 
 ## Style
 
-Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request.
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request — see `references/language-rule.md` for what to translate and what stays in English.