@kudusov.takhir/ba-toolkit 1.5.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "1.5.0",
+  "version": "3.0.0",
   "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",
@@ -43,6 +43,6 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test test/cli.test.js"
+    "test": "node --test test/cli.test.js test/cli.integration.test.js"
   }
 }

package/skills/ac/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-ac
+name: ac
 description: >
   Generate Acceptance Criteria in Given/When/Then (Gherkin) format for each User Story. Use on /ac command, or when the user asks for "acceptance criteria", "given when then", "gherkin scenarios", "write AC", "definition of done", "how to verify a story", "test scenarios for stories". Fifth step of the BA Toolkit pipeline.
 ---
@@ -21,7 +21,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-3–7 questions per round, 2–4 rounds.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Which business rules should be reflected in AC (limits, formulas, thresholds)?

package/skills/analyze/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-analyze
+name: analyze
 description: >
   Cross-artifact quality analysis across all BA Toolkit pipeline artifacts. Use on /analyze command, or when the user asks for "quality check", "analyze artifacts", "find inconsistencies", "cross-artifact check", "check quality", "find duplicates", "terminology check", "coverage analysis", "what is inconsistent". Available at any pipeline stage after /srs. Generates a structured finding report with severity levels.
 ---

package/skills/apicontract/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-apicontract
+name: apicontract
 description: >
   Generate API contracts: endpoints, methods, parameters, request/response schemas, error codes. Markdown format approximating OpenAPI. Use on /apicontract command, or when the user asks for "API contract", "describe API", "endpoints", "REST API", "WebSocket API", "describe API", "integration contract", "swagger", "describe requests and responses", "webhook contract", "API specification". Eighth step of the BA Toolkit pipeline.
 ---
@@ -21,7 +21,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-3–7 questions per round, 2–4 rounds.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Protocol — REST, WebSocket, GraphQL, combination?

package/skills/brief/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-brief
+name: brief
 description: >
   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.
 ---
@@ -34,7 +34,9 @@ The domain is written into the brief metadata and passed to all subsequent pipel
 
 ### 4. Interview
 
-3–7 questions per round, 2–4 rounds. Do not generate the artifact until sufficient information is collected.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+Cover 3–7 topics per round, 2–4 rounds. Do not generate the artifact until sufficient information is collected.
 
 **Required topics (all domains):**
 1. Product type — what exactly is being built?

package/skills/clarify/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-clarify
+name: clarify
 description: >
   Targeted ambiguity-resolution pass over a BA Toolkit artifact. Use on /clarify command, or when the user asks to "clarify requirements", "find ambiguities", "what is unclear", "check vague terms", "resolve ambiguities", "what needs clarification". Can be focused on a specific area: /clarify security, /clarify FR-012. Cross-cutting command available at any pipeline stage after the first artifact exists.
 ---

package/skills/datadict/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-datadict
+name: datadict
 description: >
   Generate a Data Dictionary: entities, attributes, types, constraints, relationships. Use on /datadict command, or when the user asks for "data dictionary", "data model", "data schema", "describe entities", "ER model", "database structure", "describe tables", "entity attributes", "entity relationships", "domain model". Seventh step of the BA Toolkit pipeline.
 ---
@@ -21,7 +21,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-3–7 questions per round, 2–4 rounds.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. DBMS — MongoDB, PostgreSQL, MySQL, other?

package/skills/estimate/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-estimate
+name: estimate
 description: >
   Effort estimation for BA Toolkit User Stories. Use on /estimate command, or when the user asks to "estimate stories", "add story points", "size the backlog", "estimate effort", "T-shirt sizing", "planning poker". Can target all stories or a specific epic/story. Run after /stories or /ac for best accuracy.
 ---

package/skills/export/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-export
+name: export
 description: >
   Export BA Toolkit artifacts to external formats for import into issue trackers and project management tools. Use on /export command, or when the user asks to "export to Jira", "create GitHub issues", "export stories", "generate Linear tickets", "export to CSV", "import into tracker". Run after /stories and /ac for full export with acceptance criteria.
 ---

package/skills/glossary/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-glossary
+name: glossary
 description: >
   Unified project glossary extraction and maintenance for BA Toolkit projects. Use on /glossary command, or when the user asks to "build a glossary", "extract terms", "create a glossary", "consolidate terminology", "find terminology drift", "what terms are defined". Cross-cutting command — can run at any pipeline stage once at least one artifact exists.
 ---

package/skills/handoff/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-handoff
+name: handoff
 description: >
   Generate a development handoff package summarising the entire BA Toolkit pipeline: artifact inventory, MVP scope, open items, top risks, and recommended next steps. Use on /handoff command, or when the user asks to "prepare handoff", "create handoff document", "summarise the pipeline", "package for developers", "ready for development", "export to Jira", "what is left to do", "pipeline summary". Optional final step — available after /wireframes.
 ---

package/skills/nfr/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-nfr
+name: nfr
 description: >
   Generate Non-functional Requirements (NFR): performance, security, availability, scalability, compliance, localization. Use on /nfr command, or when the user asks for "non-functional requirements", "NFR", "performance requirements", "security requirements", "SLA", "compliance requirements", "load requirements", "uptime requirements", "regulatory requirements", "GDPR". Sixth step of the BA Toolkit pipeline.
 ---
@@ -21,7 +21,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-3–7 questions per round, 2–4 rounds.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Performance — target CCU (Concurrent Users), RPS (Requests Per Second), acceptable response time?

package/skills/principles/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-principles
+name: principles
 description: >
   Define project-level principles that govern the entire BA Toolkit pipeline: artifact language, ID conventions, traceability requirements, Definition of Ready per artifact type, mandatory NFR categories, and quality gates. Use on /principles command, or when the user asks to "set project standards", "define conventions", "establish principles", "set up pipeline rules", "configure traceability requirements", "define definition of ready". Optional step — run before /brief or immediately after it. All subsequent skills load and apply these principles automatically.
 ---
@@ -27,7 +27,9 @@ If `01_brief_*.md` already exists, extract the slug and domain from it. Otherwis
 
 ### 3. Interview
 
-1–2 rounds, 3–5 questions each. Do not ask about topics the user can accept as defaults.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+1–2 rounds, 3–5 topics each. Do not ask about topics the user can accept as defaults.
 
 **Required topics:**
 1. Artifact language — which language should all artifacts be generated in? (default: the language of the user's first message)

package/skills/references/interview-protocol.md

@@ -0,0 +1,53 @@
+# Interview Protocol
+
+Every BA Toolkit skill that gathers information from the user MUST follow this protocol during its Interview phase. The goal is a conversation, not a questionnaire dump — users answer better when each question has focus and concrete options to react to.
+
+## Rules
+
+1. **One question at a time.** Never send a numbered list of 5+ questions in a single message. Ask one question, wait for the answer, acknowledge it in one line, then ask the next.
+
+2. **Offer 3–5 answer options per question.** For every question, present a short numbered list of the most likely answers based on:
+   - The project domain (load `references/domains/{domain}.md` and reuse its vocabulary, typical entities, and business goals verbatim when they fit — do not invent domain-specific options when the reference file already lists them).
+   - What the user has already said earlier in the interview.
+   - Industry conventions for the artifact being built.
+
+   Options should be **concrete**, not abstract — e.g. for "Who is your primary user?" in a SaaS project, offer "Product Manager at a 50–500-person SaaS startup", "Engineering Lead", "Ops/Support team", not "End user", "Customer", "User".
+
+3. **Always include a free-text option.** The last numbered option must always be something like `5. Other — type your own answer`. If the user picks it, accept arbitrary text. Never force the user into one of the predefined options.
+
+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.
+
+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.
+
+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.
+
+7. **Stop when you have enough.** Each skill specifies a required set of topics. Once every required topic has a recorded answer, stop asking and move to the Generation phase. Do not pad the interview with "nice-to-have" questions.
+
+## Example
+
+Bad (old style):
+
+> Please answer the following questions:
+> 1. What is the product?
+> 2. Who is the target user?
+> 3. What problem does it solve?
+> 4. What are the success metrics?
+> 5. What are the key constraints?
+
+Good (protocol style):
+
+> Let's start with the product itself. What are you building?
+>
+> 1. A B2B SaaS tool for internal teams (dashboards, automation, reporting)
+> 2. A customer-facing web application (marketplace, portal, community)
+> 3. A mobile app (consumer or B2B)
+> 4. An API / developer platform
+> 5. Other — type your own answer
+
+*User picks 1 or types custom.*
+
+> Got it — internal B2B SaaS tool. Who is the primary user? [next question with 3–5 options tailored to B2B SaaS internal tooling]
+
+## When this protocol applies
+
+This protocol applies to every skill that has an `### Interview` (or `## Interview`) section in its SKILL.md — currently: `brief`, `srs`, `stories`, `usecases`, `ac`, `nfr`, `datadict`, `apicontract`, `wireframes`, `scenarios`, `research`, `principles`. Each of those skills MUST link to this file from its Interview section and follow the rules above.

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

@@ -1,6 +1,7 @@
 # BA Toolkit — Project Context
 
-> Auto-generated by `ba-toolkit init` on [DATE]. Updated automatically by /brief and /srs.
+<!-- ba-toolkit:begin managed -->
+> Auto-generated by `ba-toolkit init` on [DATE]. The Active Project block below is refreshed on every re-init. Everything outside this managed block is preserved — add your own notes, update the Pipeline Status, and edit the Key Constraints / Open Questions sections freely; `ba-toolkit init` will not touch them.
 
 ## Active Project
 
@@ -9,6 +10,7 @@
 **Domain:** [DOMAIN]
 **Language:** English
 **Output folder:** output/[SLUG]/
+<!-- ba-toolkit:end managed -->
 
 ## Pipeline Status
 

package/skills/research/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-research
+name: research
 description: >
   Generate a technology and constraints research document before committing to API and data design. Covers integration options, API style choices, data storage alternatives, regulatory constraints, and ADR (Architecture Decision Records) with rationale. Use on /research command, or when the user asks for "technology research", "tech decisions", "architecture options", "integration research", "compare options", "what stack to use", "ADR", "architecture decision", "research constraints". Optional step — run after /datadict and before /apicontract.
 ---
@@ -23,7 +23,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-1–2 rounds, 4–6 questions.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+1–2 rounds, 4–6 topics.
 
 **Required topics:**
 1. Existing infrastructure — is there a current backend, database, or API the new system must integrate with or extend?

package/skills/risk/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-risk
+name: risk
 description: >
   Dedicated risk register for BA Toolkit projects. Use on /risk command, or when the user asks to "identify risks", "create a risk register", "assess project risks", "list risks", "risk matrix". Cross-cutting command — can run at any pipeline stage once Brief or SRS exists. Re-run after Research to capture technical risks.
 ---

package/skills/scenarios/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-scenarios
+name: scenarios
 description: >
   Generate end-to-end validation scenarios linking user stories, acceptance criteria, API endpoints, and wireframes into complete user journeys for acceptance testing. Use on /scenarios command, or when the user asks for "validation scenarios", "end-to-end scenarios", "user journeys", "acceptance test scenarios", "E2E scenarios", "test cases", "walkthrough scenarios", "happy path scenarios", "test the product", "QA scenarios". Optional step — run after /wireframes.
 ---
@@ -23,7 +23,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-1 round, 3–5 questions.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+1 round, 3–5 topics.
 
 **Required topics:**
 1. Coverage priority — generate scenarios for Must-priority US only, or include Should as well?

package/skills/sprint/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-sprint
+name: sprint
 description: >
   Sprint planning for BA Toolkit projects. Use on /sprint command, or when the user asks to "create a sprint plan", "plan sprints", "organise backlog into sprints", "sprint breakdown", "velocity planning", "release plan". Run after /estimate (required) and /risk (recommended). Generates 00_sprint_{slug}.md with sprint goals, story assignments, and capacity summary.
 ---

package/skills/srs/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-srs
+name: srs
 description: >
   Generate a Software Requirements Specification (SRS) based on the Project Brief. Adapted IEEE 830 format. Use on /srs command, or when the user asks for "requirements specification", "SRS", "functional requirements", "system requirements", "describe requirements", "write a technical specification". Second step of the BA Toolkit pipeline.
 ---
@@ -23,7 +23,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-3–7 questions per round, 2–4 rounds. Do not re-ask information already known from the brief.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+3–7 topics per round, 2–4 rounds. Do not re-ask information already known from the brief.
 
 **Required topics:**
 1. User roles — which roles interact with the system?

package/skills/stories/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-stories
+name: stories
 description: >
   Generate User Stories based on the SRS. Format: "As a [role], I want [action], so that [value]". Use on /stories command, or when the user asks for "user stories", "create stories", "write user stories", "story decomposition", "epics and stories", "backlog", "break requirements into stories". Third step of the BA Toolkit pipeline.
 ---
@@ -21,7 +21,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-3–7 questions per round, 2–4 rounds.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Which user flows are most critical?

package/skills/trace/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-trace
+name: trace
 description: >
   Build and update the traceability matrix across all BA Toolkit pipeline artifacts: FR ↔ US ↔ UC ↔ AC ↔ NFR ↔ Data Entity ↔ API Endpoint ↔ Wireframe. Use on /trace command, or when the user asks for "traceability matrix", "requirements traceability", "coverage check", "uncovered requirements", "artifact links", "check coverage", "find missing requirements", "what is not covered". Cross-cutting command available at any stage after /stories.
 ---

package/skills/usecases/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-usecases
+name: usecases
 description: >
   Generate Use Cases (Cockburn format) based on User Stories. Use on /usecases command, or when the user asks for "use cases", "scenarios", "describe scenarios", "interaction flows", "main and alternative flows", "describe system behavior", "user interaction scenario". Fourth step of the BA Toolkit pipeline.
 ---
@@ -21,7 +21,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-3–7 questions per round, 2–4 rounds.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Detail level — summary, user-goal, subfunction?

package/skills/wireframes/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ba-wireframes
+name: wireframes
 description: >
   Generate textual wireframe descriptions: screen structure, element placement, navigation, states (loading, empty, error). Use on /wireframes command, or when the user asks for "wireframe descriptions", "wireframes", "screen descriptions", "interface structure", "screen layouts", "UI description", "screen specification", "describe screens", "text prototype", "designer specification", "page descriptions". Ninth and final step of the BA Toolkit pipeline.
 ---
@@ -21,7 +21,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-3–7 questions per round, 2–4 rounds.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, offer 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Platform — web (desktop, mobile responsive), native app, Telegram Mini App?