@kudusov.takhir/ba-toolkit 2.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kudusov.takhir/ba-toolkit",
-  "version": "2.0.0",
+  "version": "3.1.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

@@ -21,7 +21,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/ac` (e.g., `/ac focus on US-007 and US-011`), use it as a story-id filter for which acceptance criteria to draft first.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Which business rules should be reflected in AC (limits, formulas, thresholds)?
@@ -79,9 +83,9 @@ After saving the artifact, present the following summary to the user (see `refer
 - Count of user stories covered.
 - Confirmation that back-references in `03_stories_{slug}.md` were updated.
 
-Available commands: `/clarify [focus]` · `/revise [AC-NNN-NN]` · `/expand [US-NNN]` · `/split [AC-NNN-NN]` · `/validate` · `/done`
+Available commands for this artifact: `/clarify [focus]` · `/revise [AC-NNN-NN]` · `/expand [US-NNN]` · `/split [AC-NNN-NN]` · `/validate` · `/done`
 
-Next step: `/nfr`
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (row `Current = /ac`). Do not hardcode `/nfr` here.
 
 ## Style
 

package/skills/apicontract/SKILL.md

@@ -21,7 +21,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/apicontract` (e.g., `/apicontract REST with JWT auth, OpenAPI 3.1`), use it as a style and protocol hint for the API design.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Protocol — REST, WebSocket, GraphQL, combination?
@@ -104,9 +108,9 @@ After saving the artifact, present the following summary to the user (see `refer
 - Protocol and authentication method confirmed.
 - WebSocket events and Webhook contracts included (if applicable).
 
-Available commands: `/clarify [focus]` · `/revise [endpoint]` · `/expand [endpoint]` · `/validate` · `/done`
+Available commands for this artifact: `/clarify [focus]` · `/revise [endpoint]` · `/expand [endpoint]` · `/validate` · `/done`
 
-Next step: `/wireframes`
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (row `Current = /apicontract`). Do not hardcode `/wireframes` here.
 
 ## Style
 

package/skills/brief/SKILL.md

@@ -34,7 +34,13 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit), always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/brief` (e.g., `/brief I want to build an online store for construction materials`), parse that as the lead-in answer, acknowledge it in one line, and skip directly to the first structured question that the inline text doesn't already cover.
+>
+> **Open-ended lead-in (protocol rule 8):** if there is NO inline text after `/brief`, your very first interview question is open-ended and free-text, not a table — `Tell me about the project in your own words: one or two sentences are enough. What are you building, who is it for, and what problem does it solve?`. After the user answers, switch to the structured table protocol for all subsequent questions and use the lead-in answer to pre-fill what you can.
+
+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?
@@ -69,30 +75,11 @@ If a domain reference is loaded, supplement general questions with domain-specif
 
 ### 6. AGENTS.md update
 
-After saving `01_brief_{slug}.md`, create or update `AGENTS.md` in the current working directory (project root). This file helps AI agents in future sessions quickly understand the project context without re-reading all artifacts.
-
-```markdown
-# BA Toolkit — Project Context
-
-**Project:** {Project Name}
-**Slug:** {slug}
-**Domain:** {domain}
-**Language:** {artifact language}
-**Pipeline stage:** Brief complete
+`ba-toolkit init` already created `AGENTS.md` next to where the artifact lives — typically in the current working directory (the user is expected to `cd output/<slug>` after running init). After saving `01_brief_{slug}.md`, find the project's `AGENTS.md` (look in cwd first; fall back to walking up the directory tree if cwd has none, for legacy v3.0 single-project layouts).
 
-## Artifacts
-- `{output_dir}/01_brief_{slug}.md` — Project Brief
-
-## Key context
-- **Business goal:** {one-line summary}
-- **Target audience:** {one-line summary}
-- **Key constraints:** {comma-separated list}
-
-## Next step
-Run `/srs` to generate the Requirements Specification.
-```
+**Update only the `## Pipeline Status` row for `/brief`** — toggle its status from `⬜ Not started` to `✅ Done` and fill in the artifact filename in the `File` column. **Do not touch the managed block** (`<!-- ba-toolkit:begin managed -->` … `<!-- ba-toolkit:end managed -->`) — that's owned by `ba-toolkit init`. **Do not recreate the file at the repo root.** **Do not add `## Artifacts` / `## Key context` sections** — those are not part of the v3.1+ template and would be ignored by future runs.
 
-If `AGENTS.md` already exists and was created by BA Toolkit, update only the "Pipeline stage" and "Artifacts" sections — do not overwrite custom content added by the user.
+If you find no `AGENTS.md` at all (neither in cwd nor up the tree), warn the user that the project was likely set up before v3.1 and tell them to run `ba-toolkit init --name "..." --slug {slug}` to scaffold the per-project `AGENTS.md`. Do not create one yourself with arbitrary structure.
 
 ### 8. Iterative refinement
 
@@ -111,9 +98,9 @@ After saving the artifact, present the following summary to the user (see `refer
 - Count of business goals documented and key constraints captured.
 - List of identified risks.
 
-Available commands: `/clarify [focus]` · `/revise [section]` · `/expand [section]` · `/validate` · `/done`
+Available commands for this artifact: `/clarify [focus]` · `/revise [section]` · `/expand [section]` · `/validate` · `/done`
 
-Next step: `/srs`
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (look up the row where `Current` is `/brief`). Do not hardcode `/srs` here — that table is the single source of truth and includes the four `→` lines (what the next skill produces, output file, time estimate, what comes after).
 
 ## Style
 

package/skills/datadict/SKILL.md

@@ -21,7 +21,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/datadict` (e.g., `/datadict the user and order entities are critical`), use it as a hint for which entities to model first.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. DBMS — MongoDB, PostgreSQL, MySQL, other?
@@ -89,9 +93,9 @@ After saving the artifact, present the following summary to the user (see `refer
 - DBMS chosen and naming convention confirmed.
 - Entities flagged for audit trail or versioning.
 
-Available commands: `/clarify [focus]` · `/revise [entity]` · `/expand [entity]` · `/split [entity]` · `/validate` · `/done`
+Available commands for this artifact: `/clarify [focus]` · `/revise [entity]` · `/expand [entity]` · `/split [entity]` · `/validate` · `/done`
 
-Next step: `/apicontract`
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (row `Current = /datadict`). Do not hardcode `/research` (or `/apicontract` if research is skipped) here — the lookup table is the canonical source.
 
 ## Style
 

package/skills/nfr/SKILL.md

@@ -21,7 +21,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/nfr` (e.g., `/nfr emphasise security and compliance`), use it as a category hint for which NFR areas to prioritise.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Performance — target CCU (Concurrent Users), RPS (Requests Per Second), acceptable response time?
@@ -76,9 +80,9 @@ After saving the artifact, present the following summary to the user (see `refer
 - Confirmation that section 5 of `02_srs_{slug}.md` was updated with NFR links.
 - Any categories flagged as missing or lacking measurable metrics.
 
-Available commands: `/clarify [focus]` · `/revise [NFR-NNN]` · `/expand [category]` · `/validate` · `/done`
+Available commands for this artifact: `/clarify [focus]` · `/revise [NFR-NNN]` · `/expand [category]` · `/validate` · `/done`
 
-Next step: `/datadict`
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (row `Current = /nfr`). Do not hardcode `/datadict` here.
 
 ## Style
 

package/skills/principles/SKILL.md

@@ -27,7 +27,13 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/principles`, parse it as the lead-in answer and skip directly to the first structured question it doesn't already cover.
+>
+> **Open-ended lead-in (protocol rule 8):** if there is NO inline text and no prior `01_brief_*.md` exists, your very first interview question is open-ended free-text — `What kind of project is this and what conventions matter most to you?`. Otherwise jump straight to the structured questions.
+
+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)
@@ -173,9 +179,9 @@ After saving the artifact, present the following summary to the user (see `refer
 - Quality gate threshold confirmed (which severity blocks `/done`).
 - NFR baseline categories listed.
 
-Available commands: `/revise [section]` · `/expand [section]`
+Available commands for this artifact: `/revise [section]` · `/expand [section]`
 
-Next step: `/brief` (if not yet started) or continue from where the pipeline left off — all skills now load `00_principles_{slug}.md` automatically.
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (row `Current = /principles`). The lookup table points at `/brief` as the typical next step. If the user has already started `/brief` for this project, instead suggest continuing from wherever the pipeline left off — all skills now load `00_principles_{slug}.md` automatically.
 
 ## Style
 

package/skills/references/closing-message.md

@@ -1,6 +1,6 @@
 # Closing Message Template
 
-After saving an artifact, every BA Toolkit skill presents a short summary block to the user in the chat (not inside the saved file). This ensures a consistent pipeline experience across all steps.
+After saving an artifact, every BA Toolkit skill presents a closing summary block to the user in the chat (not inside the saved file). The block ends the current step on a clear note: what was generated, what's available next, and why the next pipeline step matters.
 
 ## Format
 
@@ -14,20 +14,69 @@ Artifact saved: `{file_path}`
  main decisions captured during the interview,
  any back-references updated in prior artifacts.}
 
-Available commands:
-  /clarify [focus]    — targeted ambiguity pass: vague terms, missing metrics, conflicting rules
-  /revise [section]   — rewrite a section with your feedback
-  /expand [section]   — add more detail to a section
-  /validate           — check completeness and cross-artifact consistency
-  /done               — finalize this artifact
+Available commands for the current artifact:
+
+| Command            | When to use it                                              |
+|--------------------|-------------------------------------------------------------|
+| /clarify [focus]   | Pick up vague terms, missing metrics, conflicting rules     |
+| /revise [section]  | Rewrite a specific section with new feedback                |
+| /expand [section]  | Add more depth to an under-developed section                |
+| /validate          | Check completeness and consistency across this artifact     |
+| /done              | Lock this artifact and move on (skill marks it ✅ in AGENTS.md) |
 
 Next step: /{next_command}
+
+  → What it produces: {one-line description, e.g. "IEEE 830 SRS — scope, FRs, constraints"}
+  → Output file:      {NN}_{name}_{slug}.md
+  → Time estimate:    {min}–{max} minutes
+  → After that:       /{step_after_next} ({one-line of what it does})
+
+If you're stuck on the next step:
+  - Run `/clarify` here first to surface ambiguities while context is fresh.
+  - Run `/validate` to confirm this artifact is internally consistent.
+  - The next skill reads this artifact automatically, so you don't need to paste anything.
 ```
 
+## Pipeline next-step lookup table
+
+Skills use this table as the single source of truth for the `Next step:` block. When a skill closes, look up its row by the `Current` column and copy the four `→` lines verbatim (substituting the slug). **Do not hardcode next-step text in individual SKILL.md files** — always reference this table so future pipeline reorganisations stay consistent.
+
+| Current      | Next            | What it produces                                                | Time         | After that                                          |
+|--------------|-----------------|-----------------------------------------------------------------|--------------|-----------------------------------------------------|
+| /principles  | /brief          | Project Brief — goals, audience, stakeholders, constraints      | 20–35 min    | /srs — Requirements Specification (IEEE 830)        |
+| /brief       | /srs            | Requirements Specification (IEEE 830) — scope, FRs, MoSCoW      | 25–40 min    | /stories — User Stories grouped by Epics            |
+| /srs         | /stories        | User Stories grouped by Epics, with priority and FR refs        | 20–30 min    | /usecases — Use Cases with main/alt/exception flows |
+| /stories     | /usecases       | Use Cases with main, alternative, and exception flows           | 20–35 min    | /ac — Acceptance Criteria (Given / When / Then)     |
+| /usecases    | /ac             | Acceptance Criteria (Given / When / Then) linked to stories     | 20–35 min    | /nfr — Non-functional Requirements with metrics     |
+| /ac          | /nfr            | Non-functional Requirements with measurable metrics             | 15–25 min    | /datadict — Data Dictionary (entities, fields)      |
+| /nfr         | /datadict       | Data Dictionary — entities, fields, types, relationships        | 15–30 min    | /research — Technology Research (ADRs, integrations)|
+| /datadict    | /research       | Technology Research — ADRs, integration map, storage decisions  | 15–25 min    | /apicontract — API Contract (endpoints, schemas)    |
+| /research    | /apicontract    | API Contract — endpoints, request/response schemas, errors      | 20–35 min    | /wireframes — Textual Wireframe Descriptions        |
+| /apicontract | /wireframes     | Textual Wireframe Descriptions — screens, components, nav       | 25–40 min    | /scenarios — End-to-end Validation Scenarios        |
+| /wireframes  | /scenarios      | End-to-end Validation Scenarios linking US, AC, WF, API         | 15–25 min    | /trace + /analyze — coverage + cross-artifact QA    |
+| /scenarios   | /handoff        | Development Handoff Package — inventory, MVP scope, open items  | 5–10 min     | (pipeline complete)                                 |
+| /handoff     | (none)          | Pipeline complete                                               | —            | Run /trace and /analyze for final coverage check    |
+
+## Cross-cutting commands (no Next step line)
+
+These skills do not advance the pipeline — they update or report on existing artifacts. Their closing block omits the `Next step:` block entirely (omit it cleanly — don't write "Next step: none"):
+
+- `/trace` — coverage report (FR → US → UC → AC → NFR → API)
+- `/clarify` — targeted ambiguity resolution; updates the artifact in place
+- `/analyze` — cross-artifact quality report
+- `/estimate` — effort estimation
+- `/glossary` — glossary maintenance
+- `/export` — export to Jira / GitHub Issues / Linear / CSV
+- `/risk` — risk register
+- `/sprint` — sprint plan
+
+Their closing block ends after the "Available commands" table. Optionally, they can add a one-line "Re-run after fixes" hint (e.g., `/analyze` says "Re-run /analyze after each fix to track progress").
+
 ## Rules
 
-- `{file_path}` is the full path where the artifact was saved.
-- The summary is generated dynamically — do not repeat boilerplate; mention actual numbers and decisions.
-- The "Next step" line is omitted for cross-cutting commands (/trace, /clarify, /analyze) that do not advance the pipeline.
-- For `/wireframes` (last pipeline step), replace "Next step" with: `Pipeline complete. Run /trace to check full coverage.`
+- `{file_path}` is the full path where the artifact was saved (typically `output/<slug>/{NN}_{name}_{slug}.md`).
+- The summary line is generated dynamically — do not repeat boilerplate; mention actual numbers and decisions ("18 FRs across 3 roles, 4 risks captured", not "the artifact was generated").
+- The "Available commands" table is fixed (5 rows for pipeline skills). Cross-cutting skills omit `/done` from the table since they don't have a "finalize" state.
+- The "Next step" block is built from the lookup table above. Do not hardcode it in individual SKILL.md files.
+- The "If you're stuck" section is a 2–3-line nudge for users who don't know what to do next. Keep it short.
 - The block is a chat message, not part of the saved Markdown file.

package/skills/references/environment.md

@@ -31,27 +31,46 @@ This file defines how skills determine the output directory. Each platform has i
 
 Skills should not hardcode paths. They reference this file and apply the detection logic above.
 
-## Output folder structure (optional)
+## Output folder structure
 
-By default, all artifacts are saved flat in the output directory:
+**v3.1+ default — per-project subfolder.** `ba-toolkit init` creates `output/<slug>/` and writes the project's `AGENTS.md` inside it. All artifacts for that project also live there:
 
 ```
-output_dir/
-  00_principles_my-app.md
-  01_brief_my-app.md
-  02_srs_my-app.md
-  ...
+repo/
+  output/
+    my-app/                        ← project A
+      AGENTS.md
+      00_principles_my-app.md
+      01_brief_my-app.md
+      02_srs_my-app.md
+      ...
+    other-project/                 ← project B
+      AGENTS.md
+      01_brief_other-project.md
+      ...
 ```
 
-If the user prefers a project-scoped subfolder (useful when managing multiple projects in the same directory), set `output_mode: subfolder` in `00_principles_{slug}.md` section 7. In this mode, all artifacts are saved under `output_dir/{slug}/`:
+The user opens their AI agent inside one of those subfolders (`cd output/my-app && claude` or equivalent for the agent of choice). With cwd set to the project subfolder, every skill — including those that look for prior artifacts via `01_brief_*.md` glob — sees only that project's files. Two agent windows in the same repo, each `cd`-ed into a different `output/<slug>/`, work on two completely independent projects with zero cross-talk.
+
+**Legacy v3.0 single-project layout — still supported.** Projects scaffolded before v3.1 have a single `AGENTS.md` at the repo root and artifacts saved flat under `output/`:
 
 ```
-output_dir/
-  my-app/
-    00_principles_my-app.md
+repo/
+  AGENTS.md                        ← legacy single-project
+  output/
     01_brief_my-app.md
     02_srs_my-app.md
     ...
 ```
 
-Skills check `00_principles_{slug}.md` for this setting. If principles do not exist or the setting is absent, the default (flat) layout is used.
+When a skill is run with cwd set to the repo root and finds no `AGENTS.md` next to the artifacts, it walks up the directory tree to find the legacy root `AGENTS.md`. New projects scaffolded with v3.1+ should always use the per-project subfolder layout.
+
+## Detection rule for skills
+
+When a skill needs to find the project's `AGENTS.md` (for example, to update its `## Pipeline Status` table after generating an artifact):
+
+1. Check `cwd/AGENTS.md` first. If present, that's the project's file.
+2. Otherwise walk up the directory tree until you find an `AGENTS.md` (legacy v3.0 fallback).
+3. If neither exists, warn the user that the project was likely not scaffolded with `ba-toolkit init` and tell them to run it.
+
+Never create `AGENTS.md` at the repo root from inside a skill — that file is owned by `ba-toolkit init`.

package/skills/references/interview-protocol.md

@@ -0,0 +1,68 @@
+# 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. **Present options as a 2-column markdown table.** Every question carries a short table with columns `| ID | Variant |`. The IDs are lowercase letters starting at `a` (`a`, `b`, `c`, `d`, `e`, …). Tables render cleanly in every supported AI agent (Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf) and scan faster than a numbered list. Pull the variants from:
+   - 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.
+
+   Variants 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. **3–5 variants per question, last row is always free-text.** Keep the table to 3–5 rows total. The last row is always something like `e | Other — type your own answer` (or whatever letter follows the last predefined variant). If the user picks the free-text row, accept arbitrary text. Never force the user into one of the predefined variants.
+
+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.
+
+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.
+
+8. **Lead-in question for entry-point skills.** For the first skill in a fresh project (typically `/brief`), the very first interview question is **open-ended free-text**, not a structured options table — `Tell me about the project in your own words: one or two sentences are enough. What are you building, who is it for, and what problem does it solve?`. The user replies in free form. From that reply, extract whatever you can (product type, target audience, business goal, domain hints) and use it to pre-fill the structured questions that follow rule 2. Only ask the structured questions for topics the lead-in answer didn't cover. Non-entry-point skills (`/srs`, `/stories`, …) skip the lead-in and go straight to structured questions, because the prior artifacts already supply the project context.
+
+9. **Inline command context.** If the user invokes the skill with text after the slash command — for example `/brief I want to build an online store for construction materials targeting B2B buyers in LATAM` or `/srs the SRS should focus on the payments module first` — parse that text as if it were the answer to the lead-in question (rule 8). Skip the open-ended lead-in and use the inline text to pre-fill any structured questions you can. Only ask the user for what's still missing. Acknowledge the inline context once at the start (`Got it — online store for construction materials, B2B buyers, LATAM market.`) so the user knows their context was understood, then jump straight into the first structured question that the inline text didn't already answer. This rule applies to **every** skill that has an Interview phase, not just entry-point skills.
+
+## Example
+
+Bad (old style — questionnaire dump):
+
+> 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 — one question, table of variants):
+
+> Let's start with the product itself. What are you building?
+>
+> | ID | Variant                                                       |
+> |----|---------------------------------------------------------------|
+> | a  | A B2B SaaS tool for internal teams (dashboards, automation)   |
+> | b  | A customer-facing web application (marketplace, portal)       |
+> | c  | A mobile app (consumer or B2B)                                |
+> | d  | An API / developer platform                                   |
+> | e  | Other — type your own answer                                  |
+
+*User replies with `a`, types the verbatim variant text, or picks `e` and types their own description.*
+
+> Got it — internal B2B SaaS tool. Who is the primary user?
+>
+> | ID | Variant                                                       |
+> |----|---------------------------------------------------------------|
+> | a  | Product Manager at a 50–500-person SaaS startup               |
+> | b  | Engineering Lead at a B2B company                             |
+> | c  | Operations / Support team at a mid-size SaaS                  |
+> | d  | Other — type your own answer                                  |
+
+*…and so on, one question at a time, until every required topic for the current skill has an answer.*
+
+## 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 rules 1–7 + rule 9. Rule 8 (open-ended lead-in question) applies only to entry-point skills — currently `/brief` and `/principles` when no `01_brief_*.md` or `00_principles_*.md` is present in the output directory yet.

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

@@ -23,7 +23,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/research` (e.g., `/research compare PostgreSQL vs DynamoDB for our event store`), use it as the focus question to research instead of asking for one.
+
+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?
@@ -127,9 +131,9 @@ After saving the artifact, present the following summary (see `references/closin
 - Number of confirmed external integrations.
 - Any open questions that must be resolved before `/apicontract`.
 
-Available commands: `/clarify [focus]` · `/revise [ADR-NNN]` · `/expand [ADR-NNN]` · `/validate` · `/done`
+Available commands for this artifact: `/clarify [focus]` · `/revise [ADR-NNN]` · `/expand [ADR-NNN]` · `/validate` · `/done`
 
-Next step: `/apicontract`
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (row `Current = /research`). Do not hardcode `/apicontract` here.
 
 ## Style
 

package/skills/scenarios/SKILL.md

@@ -23,7 +23,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/scenarios` (e.g., `/scenarios focus on the new-user onboarding journey`), use it to scope which end-to-end scenarios to draft.
+
+1 round, 3–5 topics.
 
 **Required topics:**
 1. Coverage priority — generate scenarios for Must-priority US only, or include Should as well?

package/skills/srs/SKILL.md

@@ -23,7 +23,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/srs` (e.g., `/srs focus on the payments module first`), parse it as a scope hint and use it to prioritise which functional areas you ask about.
+
+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?
@@ -78,24 +82,9 @@ FR numbering: sequential, three-digit (FR-001, FR-002, ...).
 
 ## AGENTS.md update
 
-After `/done`, update `AGENTS.md` in the project root with SRS-level context:
-
-```markdown
-## Artifacts
-...
-- `{output_dir}/02_srs_{slug}.md` — SRS ({n} FR, MoSCoW breakdown)
-
-## Key context
-...
-- **User roles:** {comma-separated list}
-- **External integrations:** {comma-separated list}
-- **Must-priority FR count:** {n}
-
-## Next step
-Run `/stories` to generate User Stories.
-```
+After `/done`, find the project's `AGENTS.md` (look in cwd first; fall back to walking up the directory tree for legacy v3.0 single-project layouts). **Update only the `## Pipeline Status` row for `/srs`** — toggle its status from `⬜ Not started` to `✅ Done` and fill in the artifact filename (`02_srs_{slug}.md`) in the `File` column. **Do not touch the managed block** (`<!-- ba-toolkit:begin managed -->` … `<!-- ba-toolkit:end managed -->`) — that's owned by `ba-toolkit init`. **Do not add `## Artifacts` / `## Key context` sections** — those are not part of the v3.1+ template.
 
-Only update the "Pipeline stage", "Artifacts", and "Key context" sections. Preserve any custom content.
+If you find no `AGENTS.md` at all, warn the user that the project was likely set up before v3.1 and tell them to run `ba-toolkit init --name "..." --slug {slug}` to scaffold the per-project file. Do not create one yourself with arbitrary structure.
 
 ## Iterative refinement
 
@@ -115,9 +104,9 @@ After saving the artifact, present the following summary to the user (see `refer
 - User roles identified.
 - External integrations and regulatory requirements captured.
 
-Available commands: `/clarify [focus]` · `/revise [section]` · `/expand [section]` · `/split [FR-NNN]` · `/validate` · `/done`
+Available commands for this artifact: `/clarify [focus]` · `/revise [section]` · `/expand [section]` · `/split [FR-NNN]` · `/validate` · `/done`
 
-Next step: `/stories`
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (look up the row where `Current` is `/srs`). Do not hardcode `/stories` here — copy the four `→` lines verbatim from the lookup table row.
 
 ## Style
 

package/skills/stories/SKILL.md

@@ -21,7 +21,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/stories` (e.g., `/stories focus on the onboarding epic`), parse it as a scope hint and use it to narrow which areas you draft user stories for.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Which user flows are most critical?
@@ -76,9 +80,9 @@ After saving the artifact, present the following summary to the user (see `refer
 - Count of Must-priority FR covered.
 - Any stories flagged for `/split` due to complexity.
 
-Available commands: `/clarify [focus]` · `/revise [US-NNN]` · `/expand [US-NNN]` · `/split [US-NNN]` · `/validate` · `/done`
+Available commands for this artifact: `/clarify [focus]` · `/revise [US-NNN]` · `/expand [US-NNN]` · `/split [US-NNN]` · `/validate` · `/done`
 
-Next step: `/usecases`
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (row `Current = /stories`). Do not hardcode `/usecases` here.
 
 ## Style
 

package/skills/usecases/SKILL.md

@@ -21,7 +21,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/usecases` (e.g., `/usecases focus on admin flows`), use it as a scope hint for which use cases to draft.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Detail level — summary, user-goal, subfunction?
@@ -82,9 +86,9 @@ After saving the artifact, present the following summary to the user (see `refer
 - Count of alternative and exceptional flows documented.
 - External system actors identified.
 
-Available commands: `/clarify [focus]` · `/revise [UC-NNN]` · `/expand [UC-NNN]` · `/split [UC-NNN]` · `/validate` · `/done`
+Available commands for this artifact: `/clarify [focus]` · `/revise [UC-NNN]` · `/expand [UC-NNN]` · `/split [UC-NNN]` · `/validate` · `/done`
 
-Next step: `/ac`
+Build the `Next step:` block from the pipeline lookup table in `references/closing-message.md` (row `Current = /usecases`). Do not hardcode `/ac` here.
 
 ## Style
 

package/skills/wireframes/SKILL.md

@@ -21,7 +21,11 @@ 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, present a 2-column `| ID | Variant |` markdown table of 3–5 domain-appropriate options, always include a free-text "Other" row as the last option, and wait for an answer before asking the next question.
+>
+> **Inline context (protocol rule 9):** if the user wrote text after `/wireframes` (e.g., `/wireframes mobile-first, focus on the checkout flow`), use it as a layout and scope hint for which screens to draft first.
+
+3–7 topics per round, 2–4 rounds.
 
 **Required topics:**
 1. Platform — web (desktop, mobile responsive), native app, Telegram Mini App?