@kudusov.takhir/ba-toolkit 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -11,6 +11,49 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [3.1.1] — 2026-04-09
+
+### Changed
+
+- **Interview options table is now capped at 5 rows total** (`skills/references/interview-protocol.md` rule 3). Previously rule 3 allowed "3–5 variants per question" with the free-text "Other" row on top, so a single question could surface up to 6 options and overwhelm the user. The new cap is **up to 4 predefined variants + exactly 1 free-text "Other" row = 5 rows max**, no exceptions. Fewer than 4 predefined rows is still fine when the topic only has 2–3 sensible options. The one-line protocol summary in all 12 interview-phase skills (`brief`, `srs`, `stories`, `usecases`, `ac`, `nfr`, `datadict`, `apicontract`, `wireframes`, `scenarios`, `research`, `principles`) was updated to match. New regression test in `test/cli.test.js` walks every shipped SKILL.md with an Interview heading and fails if any of them carry the legacy `3–5 domain-appropriate options` wording or omit the new `5 rows max` reminder.
+- **Exactly one variant per question is now marked `**Recommended**`** (`skills/references/interview-protocol.md` new rule 10). The AI picks the row using, in priority order, (a) the loaded `references/domains/{domain}.md` for the current skill, (b) the user's prior interview answers, (c) the inline context from rule 9, (d) widely-accepted industry default. The free-text "Other" row is never recommended. If none of (a)–(d) gives a defensible choice the AI omits the marker entirely rather than guessing — a missing recommendation is better than a misleading one. Rendered as `**Recommended**` appended to the end of the `Variant` cell so it stays visible even when the table wraps. Translated together with the variant text per rule 11 (e.g. `**Рекомендуется**`, `**Recomendado**`). All 12 interview-phase SKILL.md summaries point at rule 10. New regression test in `test/cli.test.js` enforces that every Interview-section SKILL.md mentions the marker.
+- **Variant text and the `Variant` column header are now rendered in the user's language** (`skills/references/interview-protocol.md` new rule 11), matching the rule the generated artifacts already follow (`skills/brief/SKILL.md:107`). The `ID` column header and the letter IDs (`a`, `b`, …) stay ASCII. Domain reference files in `skills/references/domains/` remain English-only by design (per the project's English-only convention) — the AI translates the variants on the fly when rendering the table for a non-English-speaking user, instead of pasting the English source verbatim or asking the user which language to use. Updated example block in the protocol now shows both an English question with `**Recommended**` and a Russian rendering of the same question to make the rule concrete.
+- **Replaced `example/dragon-fortune/` with `example/lumen-goods/`**, a sustainable home-goods D2C e-commerce walkthrough. The new example is more universally relatable than the iGaming-themed predecessor: 15 cross-referenced artifacts (Brief, Principles, SRS, Stories, Use Cases, AC, NFRs, Data Dictionary, Tech Research, API Contract, Wireframes, Scenarios, Risk Register, Sprint Plan, Handoff) for a fictional D2C online store selling lighting, kitchenware, and textiles to eco-conscious EU/UK buyers. Stack covers Next.js storefront, Stripe (cards / Apple Pay / Klarna / SEPA), Stripe Tax for destination-based VAT, hybrid stock sync between an NL warehouse and a UK 3PL, GDPR/DSAR/cookie consent flows, and a paid Lumen Circle loyalty tier. CLAUDE.md "Do NOT touch" entry, the placeholder warning, the repo-layout block, and the README example table all updated to reference `lumen-goods`. The old `example/dragon-fortune/` folder has been removed.
+
+---
+
+## [3.1.0] — 2026-04-09
+
+### Highlights
+
+- **Multi-project in one repo.** `ba-toolkit init` now writes `AGENTS.md` inside `output/<slug>/`, scoped to that project. Two agent windows in the same repo can `cd output/alpha && claude` and `cd output/beta && claude` independently — no AGENTS.md collision, no shared state.
+- **Interview options as a 2-column markdown table with letter IDs** (`a`, `b`, `c`, …) instead of a numbered list. Same change cascades through every interview-phase skill via the protocol link.
+- **Inline context after slash commands**: `/brief I want to build an online store for construction materials...` is parsed as a lead-in answer; the skill skips redundant questions and jumps straight to what's missing. Works for all 12 interview-phase skills.
+- **Open-ended lead-in question** for `/brief` and `/principles` when there's no inline context — `Tell me about the project in your own words` — instead of dumping a structured table on the first turn.
+- **Detailed next-step closing block** driven by a 13-row pipeline lookup table in `closing-message.md`, replacing per-skill hardcoded `Next step: /xxx` lines. Locked in by two regression tests.
+
+### Changed
+
+- **Closing message of every skill is now driven by a single source of truth** — `skills/references/closing-message.md` got a full rewrite that includes (a) a richer closing-block format with an `Available commands` table explaining when to use each subcommand, (b) a 4-line `Next step:` block detailing what the next skill produces, the output filename, the time estimate, and what comes after that, and (c) a 13-row pipeline next-step lookup table that every skill reads from instead of hardcoding `Next step: /xxx` in its own SKILL.md. 10 pipeline-phase SKILL.md files (`brief`, `srs`, `stories`, `usecases`, `ac`, `nfr`, `datadict`, `research`, `apicontract`, `principles`) had their hardcoded `Next step:` lines removed and replaced with an instruction to copy the row from the lookup table. Cross-cutting skills (`/clarify`, `/analyze`, `/trace`, `/estimate`, `/glossary`, `/export`, `/risk`, `/sprint`) keep their per-skill `Available commands` lines but skip the next-step block entirely (as documented in the template). New "If you're stuck" nudge in the closing format suggests `/clarify` and `/validate` for users who don't know what to do next.
+- **Two new regression tests in `test/cli.test.js`**: `closing message: every SKILL.md references the closing-message.md template` (mirror of the existing interview-protocol test, walks every shipped SKILL.md and asserts it points at the template) and `closing message: no SKILL.md hardcodes a next-step line` (greps every shipped SKILL.md for a `Next step: /xxx` pattern and fails if any skill ships its own roll-your-own next-step block, which would silently bypass the lookup table). Locks in the rule for future contributors and future skills.
+
+### Added
+
+- **Multi-project support: each `ba-toolkit init` writes `AGENTS.md` inside `output/<slug>/`**, scoped to that project, instead of a single repo-root `AGENTS.md` shared by all projects in the repo. The user opens their AI agent inside the project folder (`cd output/alpha-shop && claude`) — cwd becomes the project root, every skill that looks for `AGENTS.md` or 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 and no shared "active project" pointer to get out of sync. The merge-on-reinit behaviour from v3.0 (managed-block anchors) still applies, just at per-project scope. Closing message of `ba-toolkit init` now points the user at the new `cd output/<slug>` step. Pre-existing repo-root `AGENTS.md` files are never touched by v3.1+ init — covered by an integration regression test. The `skills/references/environment.md` reference file documents both the v3.1+ per-project layout (default) and the legacy v3.0 single-project fallback for backward compat.
+- **`bin/ba-toolkit.js` `cmdInit`** now writes `AGENTS.md` to `output/<slug>/AGENTS.md` and updates the closing "Next steps" message to instruct the user to `cd` into the project folder before opening their AI agent. The `mergeAgentsMd` helper is unchanged — the path move alone gives per-project isolation.
+- **`skills/brief/SKILL.md` and `skills/srs/SKILL.md`** updated their AGENTS.md handling instructions: skills now find AGENTS.md by checking cwd first, falling back to walking up the tree for legacy v3.0 single-project layouts, and only update the `## Pipeline Status` row for their stage — never recreate the file or add legacy `## Artifacts` / `## Key context` sections that aren't part of the v3.1+ template.
+- **Two new integration tests** in `test/cli.integration.test.js`: a `multi-project` test that runs two consecutive `ba-toolkit init` runs with different slugs in the same cwd and asserts that both `output/<slug>/AGENTS.md` files exist independently with the correct project metadata, plus an `init does not touch a pre-existing repo-root AGENTS.md` test that asserts legacy v3.0 root files are preserved byte-for-byte.
+- **Interview skills now accept inline context after the slash command** (interview-protocol rule 9). `/brief I want to build an online store for construction materials targeting B2B buyers in LATAM` is parsed as the lead-in answer; the skill acknowledges it once, skips the open-ended lead-in question, and jumps straight to the first structured-table question that the inline text didn't already cover. Works for every interview-phase skill, not just `/brief` — `/srs focus on the payments module first`, `/stories plan the onboarding epic`, `/nfr emphasise security and compliance`, etc. Each scope hint narrows what the skill asks about. All 12 interview SKILL.md files updated with a one-line pointer to rule 9 in their Interview section; the regression test that walks every shipped SKILL.md still passes (it just checks the protocol link, which all 12 already had).
+- **Open-ended lead-in question for entry-point skills** (interview-protocol rule 8). When `/brief` (or `/principles` for principles-first projects) is invoked with no inline context and no prior brief artifact exists, the very first interview question is now an open-ended free-text prompt: `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 agent extracts whatever it can from the user's reply (product type, target audience, business goal, domain hints) and uses it to pre-fill subsequent structured questions. Subsequent questions follow the regular options-table protocol from rule 2. Non-entry-point skills (`/srs`, `/stories`, …) skip the lead-in entirely because prior artifacts already supply the project context.
+- **Two new walkthrough examples in `docs/USAGE.md` §1** — one showing the plain `/brief` flow with the open-ended lead-in, one showing the `/brief <text>` inline-context flow. Both examples use the new option-table format with letter IDs.
+
+### Changed
+
+- **Interview options are now presented as a 2-column markdown table with letter IDs** instead of a numbered list. Every interview-phase skill (12 SKILL.md files) inherits this automatically through the protocol — the change lives in `skills/references/interview-protocol.md` rule 2, no SKILL.md was touched. Each question now carries `| ID | Variant |` columns where ID is `a`, `b`, `c`, … (lowercase letters); the last row is always the free-text "Other" option. Tables render cleanly in Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf, scan faster than a numbered list, and let users reply with the letter ID, the verbatim variant text, or — for the free-text row — any text of their own.
+- **CLI domain/agent menus now use letter IDs** to match the interview-protocol convention. Arrow-key navigation, vim-bindings (`j/k`), Enter, and Esc/Ctrl+C are unchanged; the jump key is now `a-z` instead of `1-9`. The non-TTY numbered fallback (CI, piped input) accepts a letter ID as the primary input, with digit and verbatim id-string kept as backward-compat fallbacks so existing scripts and muscle memory still work. New regression test asserts both letter and digit input paths through the fallback. `menuStep`, `renderMenu`, and `runMenuTty` were updated; the keypress handler accepts `[a-z]` as primary and `[0-9]` as fallback.
+
+---
+
 ## [3.0.0] — 2026-04-09
 
 ### ⚠️ BREAKING — Cursor and Windsurf install paths moved to native Agent Skills
@@ -408,7 +451,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.0.0...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.1.1...HEAD
+[3.1.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.1.0...v3.1.1
+[3.1.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.0.0...v3.1.0
 [3.0.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v2.0.0...v3.0.0
 [2.0.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.5.0...v2.0.0
 [1.5.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.4.0...v1.5.0

package/COMMANDS.md

@@ -11,7 +11,7 @@ Run these in order. Each skill reads the output of all previous steps.
 | # | Command | Output file | What it generates |
 |:---:|---------|-------------|-------------------|
 | 0 | `/principles` | `00_principles_{slug}.md` | Project constitution: language, ID conventions, DoR, traceability rules, NFR baseline |
-| 1 | `/brief` | `01_brief_{slug}.md` | Project Brief: goals, audience, stakeholders, constraints, risks. Creates `AGENTS.md` |
+| 1 | `/brief` | `01_brief_{slug}.md` | Project Brief: goals, audience, stakeholders, constraints, risks. Updates the `AGENTS.md` Pipeline Status table (which `ba-toolkit init` already created) |
 | 2 | `/srs` | `02_srs_{slug}.md` | Requirements Specification (IEEE 830): scope, FRs, constraints, assumptions |
 | 3 | `/stories` | `03_stories_{slug}.md` | User Stories grouped by Epics, with priority and FR references |
 | 4 | `/usecases` | `04_usecases_{slug}.md` | Use Cases with main, alternative, and exception flows |

package/README.md

@@ -48,6 +48,20 @@ ba-toolkit init
 
 Supported agents: `claude-code`, `codex`, `gemini`, `cursor`, `windsurf`. All five use the native Agent Skills format (folder-per-skill with `SKILL.md`) — Claude Code at `.claude/skills/`, Codex at `~/.codex/skills/`, Gemini at `.gemini/skills/`, Cursor at `.cursor/skills/`, Windsurf at `.windsurf/skills/`. Pass `--dry-run` to preview the install step without writing files, or `--no-install` to create only the project structure and install skills later with `ba-toolkit install --for <agent>`.
 
+**New in v3.1** — multi-project + interview UX:
+
+- **Multi-project: each `ba-toolkit init` creates `output/<slug>/AGENTS.md`**, scoped to that project. Two agent windows in the same repo can `cd output/alpha && claude` and `cd output/beta && claude` independently — no AGENTS.md collision, no shared state.
+- **Interview options as a 2-column table with letter IDs** (`a`, `b`, `c`, …) instead of a numbered list. Renders cleanly across all 5 supported agents, easier to scan, last row is always free-text "Other".
+- **Inline context after slash commands**: `/brief I want to build an online store for construction materials...` is parsed as a lead-in answer; the skill skips redundant questions and jumps straight to what's missing. Works for all 12 interview-phase skills.
+- **Open-ended lead-in question** for `/brief` and `/principles` when there's no inline context — `Tell me about the project in your own words` — instead of dumping a structured table on the first turn.
+
+**New in v3.0** — `ba-toolkit init` UX improvements:
+
+- **Arrow-key menu navigation** for the domain and agent prompts in real terminals (`↑/↓` or `j/k` to move, `a-z` to jump, `Enter` to select, `Esc`/`Ctrl+C` to cancel). CI / piped input automatically falls back to a numbered prompt.
+- **Re-prompt on invalid input** instead of crashing on the first typo. Three attempts before aborting, so a piped input can't infinite-loop.
+- **`AGENTS.md` is merged on re-init**, not overwritten. Pipeline Status edits, Key Constraints, Open Questions, and any user notes outside the managed block are preserved byte-for-byte. See [docs/USAGE.md §8](docs/USAGE.md#8-agentsmd--persistent-project-context).
+- **Native Cursor and Windsurf skills** at `.cursor/skills/` and `.windsurf/skills/` — finally registered as actual Agent Skills instead of `.mdc` rules. v2.x users: see the v3.0 migration recipe in [CHANGELOG.md](CHANGELOG.md).
+
 `ba-toolkit --help` shows the full CLI reference. Zero runtime dependencies — only Node.js ≥ 18.
 
 <details>
@@ -55,7 +69,7 @@ Supported agents: `claude-code`, `codex`, `gemini`, `cursor`, `windsurf`. All fi
 
 Use these if you can't use npm or want to track a specific git commit.
 
-**Important — v2.0 layout:** the skills go directly under the agent's skills root, not nested under a `ba-toolkit/` wrapper folder. Versions before v2.0 used a wrapper, which made every skill invisible to the agent. If you're upgrading from v1.x, remove the legacy wrapper folder first.
+**Current install layout (v3.0+):** all five supported agents use the native Agent Skills format — the BA Toolkit skills go directly under each agent's skills root (`.claude/skills/`, `~/.codex/skills/`, `.gemini/skills/`, `.cursor/skills/`, `.windsurf/skills/`), one folder per skill, each containing its own `SKILL.md`. No `.mdc` conversion, no `ba-toolkit/` wrapper. Versions before v2.0 nested everything under a `ba-toolkit/` wrapper folder which made the skills invisible to the agent — remove that wrapper if you're upgrading from v1.x. Versions v2.0–v2.x installed Cursor and Windsurf as `.mdc` rules under `.cursor/rules/` and `.windsurf/rules/`, which were the wrong feature entirely (Cursor and Windsurf loaded them as Rules, never as Skills) — see the v3.0 entry in [CHANGELOG.md](CHANGELOG.md) for the migration steps if you're upgrading from v2.x.
 
 ### Claude Code CLI
 
@@ -138,25 +152,25 @@ Your generated artifacts (`01_brief_*.md`, `02_srs_*.md`, …) are untouched by
 
 ## Example output
 
-A complete example project — **Dragon Fortune** (iGaming Telegram Mini App) — lives in [`example/dragon-fortune/`](example/dragon-fortune/). All 15 artifacts are realistic, cross-referenced, and generated by running the full BA Toolkit pipeline.
+A complete example project — **Lumen Goods** (sustainable home-goods D2C online store) — lives in [`example/lumen-goods/`](example/lumen-goods/). All 15 artifacts are realistic, cross-referenced, and generated by running the full BA Toolkit pipeline.
 
 | Artifact | File |
 |---------|------|
-| Project Principles | [`00_principles_dragon-fortune.md`](example/dragon-fortune/00_principles_dragon-fortune.md) |
-| Project Brief | [`01_brief_dragon-fortune.md`](example/dragon-fortune/01_brief_dragon-fortune.md) |
-| Requirements (SRS) | [`02_srs_dragon-fortune.md`](example/dragon-fortune/02_srs_dragon-fortune.md) |
-| User Stories | [`03_stories_dragon-fortune.md`](example/dragon-fortune/03_stories_dragon-fortune.md) |
-| Use Cases | [`04_usecases_dragon-fortune.md`](example/dragon-fortune/04_usecases_dragon-fortune.md) |
-| Acceptance Criteria | [`05_ac_dragon-fortune.md`](example/dragon-fortune/05_ac_dragon-fortune.md) |
-| Non-functional Requirements | [`06_nfr_dragon-fortune.md`](example/dragon-fortune/06_nfr_dragon-fortune.md) |
-| Data Dictionary | [`07_datadict_dragon-fortune.md`](example/dragon-fortune/07_datadict_dragon-fortune.md) |
-| Technology Research | [`07a_research_dragon-fortune.md`](example/dragon-fortune/07a_research_dragon-fortune.md) |
-| API Contract | [`08_apicontract_dragon-fortune.md`](example/dragon-fortune/08_apicontract_dragon-fortune.md) |
-| Wireframes | [`09_wireframes_dragon-fortune.md`](example/dragon-fortune/09_wireframes_dragon-fortune.md) |
-| Validation Scenarios | [`10_scenarios_dragon-fortune.md`](example/dragon-fortune/10_scenarios_dragon-fortune.md) |
-| Development Handoff | [`11_handoff_dragon-fortune.md`](example/dragon-fortune/11_handoff_dragon-fortune.md) |
-| Risk Register | [`00_risks_dragon-fortune.md`](example/dragon-fortune/00_risks_dragon-fortune.md) |
-| Sprint Plan | [`00_sprint_dragon-fortune.md`](example/dragon-fortune/00_sprint_dragon-fortune.md) |
+| Project Principles | [`00_principles_lumen-goods.md`](example/lumen-goods/00_principles_lumen-goods.md) |
+| Project Brief | [`01_brief_lumen-goods.md`](example/lumen-goods/01_brief_lumen-goods.md) |
+| Requirements (SRS) | [`02_srs_lumen-goods.md`](example/lumen-goods/02_srs_lumen-goods.md) |
+| User Stories | [`03_stories_lumen-goods.md`](example/lumen-goods/03_stories_lumen-goods.md) |
+| Use Cases | [`04_usecases_lumen-goods.md`](example/lumen-goods/04_usecases_lumen-goods.md) |
+| Acceptance Criteria | [`05_ac_lumen-goods.md`](example/lumen-goods/05_ac_lumen-goods.md) |
+| Non-functional Requirements | [`06_nfr_lumen-goods.md`](example/lumen-goods/06_nfr_lumen-goods.md) |
+| Data Dictionary | [`07_datadict_lumen-goods.md`](example/lumen-goods/07_datadict_lumen-goods.md) |
+| Technology Research | [`07a_research_lumen-goods.md`](example/lumen-goods/07a_research_lumen-goods.md) |
+| API Contract | [`08_apicontract_lumen-goods.md`](example/lumen-goods/08_apicontract_lumen-goods.md) |
+| Wireframes | [`09_wireframes_lumen-goods.md`](example/lumen-goods/09_wireframes_lumen-goods.md) |
+| Validation Scenarios | [`10_scenarios_lumen-goods.md`](example/lumen-goods/10_scenarios_lumen-goods.md) |
+| Development Handoff | [`11_handoff_lumen-goods.md`](example/lumen-goods/11_handoff_lumen-goods.md) |
+| Risk Register | [`00_risks_lumen-goods.md`](example/lumen-goods/00_risks_lumen-goods.md) |
+| Sprint Plan | [`00_sprint_lumen-goods.md`](example/lumen-goods/00_sprint_lumen-goods.md) |
 
 Full traceability: FR → US → UC → AC → NFR → Entity → ADR → API → WF → Scenario, plus risk register and sprint plan.
 
@@ -188,7 +202,7 @@ Full traceability: FR → US → UC → AC → NFR → Entity → ADR → API
 | — | `/risk` | Risk register — probability × impact matrix, mitigation per risk | `00_risks_{slug}.md` |
 | — | `/sprint` | Sprint plan — stories grouped by velocity and capacity with sprint goals | `00_sprint_{slug}.md` |
 
-The project **slug** (e.g., `nova-analytics`) is set at `/brief` and reused across all files automatically.
+The project **slug** (e.g., `nova-analytics`) is set at `ba-toolkit init` (derived from the project name) and reused across all files automatically — every skill reads it from `AGENTS.md`.
 
 ---
 
@@ -213,7 +227,7 @@ Skills do not hardcode platform paths — they reference `skills/references/envi
 
 ## Domain support
 
-The pipeline is domain-agnostic by default. At `/brief`, you pick a domain, and every subsequent skill loads domain-specific interview questions, mandatory entities, NFR categories, and glossary terms.
+The pipeline is domain-agnostic by default. At `ba-toolkit init` you pick a domain, and every subsequent skill loads domain-specific interview questions, mandatory entities, NFR categories, and glossary terms from `skills/references/domains/{domain}.md`.
 
 | Domain | Industries covered |
 |--------|-------------------|

package/bin/ba-toolkit.js

@@ -277,7 +277,17 @@ function menuStep(state, key) {
       return { ...state, done: true, choice: state.items[state.index] };
     case 'cancel':
       return { ...state, done: true, choice: null };
-    default:
+    default: {
+      // Letter jump: 'a' → 0, 'b' → 1, …, 'i' → 8.
+      if (/^[a-z]$/.test(key)) {
+        const idx = key.charCodeAt(0) - 'a'.charCodeAt(0);
+        if (idx < len) {
+          return { ...state, index: idx };
+        }
+        return state;
+      }
+      // Digit jump kept as a backward-compat fallback so existing
+      // CI scripts and muscle-memory keep working: '1' → 0, '9' → 8.
       if (/^[0-9]$/.test(key)) {
         const n = parseInt(key, 10);
         if (n >= 1 && n <= len) {
@@ -285,6 +295,7 @@ function menuStep(state, key) {
         }
       }
       return state;
+    }
   }
 }
 
@@ -298,13 +309,16 @@ function renderMenu(state, { title } = {}) {
   state.items.forEach((item, i) => {
     const selected = i === state.index;
     const marker = selected ? cyan('>') : ' ';
-    const idx = String(i + 1).padStart(2);
+    // Letter ID — `a`, `b`, `c`, … — matches the interview-protocol
+    // table format and works for menus up to 26 items (we currently
+    // ship 10 domains and 5 agents, so this is plenty).
+    const id = String.fromCharCode('a'.charCodeAt(0) + i);
     const label = selected ? bold(item.label.padEnd(labelWidth)) : item.label.padEnd(labelWidth);
     const desc = item.desc ? '  ' + gray('— ' + item.desc) : '';
-    lines.push(`  ${marker} ${idx}) ${label}${desc}`);
+    lines.push(`  ${marker} ${id}) ${label}${desc}`);
   });
   lines.push('');
-  lines.push('  ' + gray('↑/↓ navigate · Enter select · 1-9 jump · Esc cancel'));
+  lines.push('  ' + gray('↑/↓ navigate · Enter select · a-z jump · Esc cancel'));
   return lines.join('\n') + '\n';
 }
 
@@ -362,6 +376,12 @@ function runMenuTty(items, { title } = {}) {
       else if (key.name === 'up' || key.name === 'k') action = 'up';
       else if (key.name === 'down' || key.name === 'j') action = 'down';
       else if (key.name === 'return') action = 'enter';
+      // Letter jump (a-z) is the new primary; digit (0-9) stays as a
+      // backward-compat fallback for users who muscle-memory cipher
+      // navigation. menuStep parses both — see its switch statement.
+      // Note: 'j' and 'k' are intercepted above as down/up (vim-bindings),
+      // so they never reach the letter-jump path.
+      else if (key.sequence && /^[a-z]$/.test(key.sequence)) action = key.sequence;
       else if (key.sequence && /^[0-9]$/.test(key.sequence)) action = key.sequence;
       if (!action) return;
       state = menuStep(state, action);
@@ -389,15 +409,15 @@ async function selectMenu(items, { title, fallbackPrompt }) {
   if (isInteractiveTerminal()) {
     return await runMenuTty(items, { title });
   }
-  // Non-TTY fallback: print the numbered list once, then prompt with
+  // Non-TTY fallback: print the lettered list once, then prompt with
   // promptUntilValid so a single typo doesn't kill the wizard.
   log('');
   if (title) log('  ' + yellow(title));
   const labelWidth = Math.max(...items.map((it) => it.label.length));
   items.forEach((item, i) => {
-    const idx = String(i + 1).padStart(2);
+    const id = String.fromCharCode('a'.charCodeAt(0) + i);
     const desc = item.desc ? '  ' + gray('— ' + item.desc) : '';
-    log(`    ${idx}) ${bold(item.label.padEnd(labelWidth))}${desc}`);
+    log(`    ${id}) ${bold(item.label.padEnd(labelWidth))}${desc}`);
   });
   log('');
   return await promptUntilValid(
@@ -405,13 +425,21 @@ async function selectMenu(items, { title, fallbackPrompt }) {
     (raw) => {
       const trimmed = String(raw || '').toLowerCase().trim();
       if (!trimmed) return null;
+      // Letter ID is the primary input (a → 0, b → 1, …).
+      if (/^[a-z]$/.test(trimmed)) {
+        const idx = trimmed.charCodeAt(0) - 'a'.charCodeAt(0);
+        return idx < items.length ? items[idx] : null;
+      }
+      // Digit ID stays as a fallback so legacy CI scripts and pasted
+      // numbers still work (1 → 0, 2 → 1, …).
       if (/^\d+$/.test(trimmed)) {
         const n = parseInt(trimmed, 10);
         return n >= 1 && n <= items.length ? items[n - 1] : null;
       }
+      // Verbatim id-string fallback (e.g., 'saas', 'claude-code').
       return items.find((it) => it.id === trimmed) || null;
     },
-    { invalidMessage: `Invalid selection — pick a number between 1 and ${items.length} or an id.` },
+    { invalidMessage: `Invalid selection — pick a letter (a–${String.fromCharCode('a'.charCodeAt(0) + items.length - 1)}), a number, or an id.` },
   );
 }
 
@@ -881,7 +909,7 @@ async function cmdInit(args) {
       DOMAINS.map((d) => ({ id: d.id, label: d.name, desc: d.desc })),
       {
         title: 'Pick a domain:',
-        fallbackPrompt: `  Select [1-${DOMAINS.length}]: `,
+        fallbackPrompt: `  Select [a-${String.fromCharCode('a'.charCodeAt(0) + DOMAINS.length - 1)}]: `,
       },
     );
     if (chosen == null) {
@@ -909,7 +937,7 @@ async function cmdInit(args) {
         agentEntries.map(([id, a]) => ({ id, label: a.name, desc: '(' + id + ')' })),
         {
           title: 'Pick your AI agent:',
-          fallbackPrompt: `  Select [1-${agentEntries.length}]: `,
+          fallbackPrompt: `  Select [a-${String.fromCharCode('a'.charCodeAt(0) + agentEntries.length - 1)}]: `,
         },
       );
       if (chosen == null) {
@@ -932,11 +960,14 @@ async function cmdInit(args) {
     log(`    exists   ${outputDir}`);
   }
 
-  // AGENTS.md: merge-on-reinit instead of overwrite. Everything outside
-  // the managed block (Pipeline Status, Key Constraints, user notes) is
-  // preserved. See mergeAgentsMd for the three branches (created,
-  // merged, preserved).
-  const agentsPath = 'AGENTS.md';
+  // AGENTS.md: per-project, lives inside output/<slug>/. Two agent
+  // windows can now work on two different projects in the same repo
+  // without colliding — each cd-s into its own output/<slug>/ folder
+  // and finds its own AGENTS.md there. The merge-on-reinit behaviour
+  // (managed-block anchors) still applies, just at per-project scope.
+  // See mergeAgentsMd for the three branches (created, merged,
+  // preserved).
+  const agentsPath = path.join(outputDir, 'AGENTS.md');
   const existingAgents = fs.existsSync(agentsPath)
     ? fs.readFileSync(agentsPath, 'utf8')
     : null;
@@ -945,10 +976,10 @@ async function cmdInit(args) {
     { name, slug, domain },
   );
   if (agentsAction === 'preserved') {
-    log('    ' + gray('preserved AGENTS.md (no ba-toolkit managed block — left untouched)'));
+    log('    ' + gray(`preserved ${agentsPath} (no ba-toolkit managed block — left untouched)`));
   } else {
     fs.writeFileSync(agentsPath, agentsContent);
-    log(`    ${agentsAction === 'merged' ? 'updated ' : 'created '} AGENTS.md`);
+    log(`    ${agentsAction === 'merged' ? 'updated ' : 'created '} ${agentsPath}`);
   }
 
   // --- 6. Install skills for the selected agent ---
@@ -969,28 +1000,31 @@ async function cmdInit(args) {
 
   // --- 7. Final message ---
   log('');
-  log('  ' + cyan(`Project '${name}' (${slug}) is ready.`));
+  log('  ' + cyan(`Project '${name}' (${slug}) is ready in ${outputDir}/.`));
   log('');
   log('  ' + yellow('Next steps:'));
   if (installed === true) {
     log('    1. ' + AGENTS[agentId].restartHint);
-    log('    2. Optional: run /principles to define project-wide conventions');
-    log('    3. Run /brief to start the BA pipeline');
+    log('    2. ' + bold(`cd ${outputDir}`) + ' — open your AI agent in this folder.');
+    log('       Each project has its own AGENTS.md, so two agent windows');
+    log('       can work on two different projects in the same repo.');
+    log('    3. Optional: run /principles to define project-wide conventions');
+    log('    4. Run /brief to start the BA pipeline');
   } else if (installed === false) {
     log('    1. Skill install was cancelled. To install later, run:');
     log('         ' + gray(`ba-toolkit install --for ${agentId}`));
-    log('    2. Open your AI assistant (Claude, Cursor, etc.)');
+    log('    2. ' + bold(`cd ${outputDir}`) + ' and open your AI agent there.');
     log('    3. Optional: run /principles to define project-wide conventions');
     log('    4. Run /brief to start the BA pipeline');
   } else {
     log('    1. Install skills for your agent:');
     log('         ' + gray('ba-toolkit install --for claude-code'));
-    log('    2. Open your AI assistant (Claude, Cursor, etc.)');
+    log('    2. ' + bold(`cd ${outputDir}`) + ' and open your AI agent there.');
     log('    3. Optional: run /principles to define project-wide conventions');
     log('    4. Run /brief to start the BA pipeline');
   }
   log('');
-  log('  ' + gray(`Artifacts will be saved to: ${outputDir}/`));
+  log('  ' + gray(`Artifacts and AGENTS.md live in: ${outputDir}/`));
   log('');
 }
 

package/package.json

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

package/skills/ac/SKILL.md

@@ -21,7 +21,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -81,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,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -106,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,11 @@ The domain is written into the brief metadata and passed to all subsequent pipel
 
 ### 4. Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options (load `references/domains/{domain}.md` for the ones that fit) plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -71,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.
+`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).
 
-```markdown
-# BA Toolkit — Project Context
-
-**Project:** {Project Name}
-**Slug:** {slug}
-**Domain:** {domain}
-**Language:** {artifact language}
-**Pipeline stage:** Brief complete
-
-## 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
 
@@ -113,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,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -91,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,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -78,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,11 @@ If `01_brief_*.md` already exists, extract the slug and domain from it. Otherwis
 
 ### 3. Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -175,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

@@ -6,16 +6,16 @@ Every BA Toolkit skill that gathers information from the user MUST follow this p
 
 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:
+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.
 
-   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".
+   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. **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.
+3. **At most 5 rows per question, last row is always free-text.** Hard cap: **5 rows total = up to 4 predefined variants + exactly 1 free-text "Other" row**. Never render a 6th row. 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. Fewer than 4 predefined rows is fine when the topic genuinely has only 2–3 sensible options — pad with "Other" rather than inventing filler.
 
-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.
+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.
 
@@ -23,9 +23,17 @@ Every BA Toolkit skill that gathers information from the user MUST follow this p
 
 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.
+
+10. **Mark exactly one row as Recommended.** In every options table, append `**Recommended**` to the end of the `Variant` cell of the single row that best fits the project context. Pick the row using, in order: (a) the loaded `references/domains/{domain}.md` for the current skill — what the reference treats as the typical default; (b) what the user has already said earlier in this interview; (c) the inline context from rule 9; (d) widely-accepted industry default. Never recommend the free-text "Other" row. Never recommend more than one row. If none of (a)–(d) gives you a defensible choice, omit the marker entirely for that question rather than guessing — a missing recommendation is better than a misleading one. Translate the marker together with the variant text per rule 11 (e.g. `**Рекомендуется**`, `**Recomendado**`).
+
+11. **Variant text in the user's language.** The `Variant` column header and every variant string must be written in the same language as the user's first message in this conversation — the same rule the generated artifact already follows. The `ID` column header and the letter IDs (`a`, `b`, …) stay ASCII, unchanged. The `**Recommended**` marker is also translated. Domain reference files in `references/domains/` are English-only by design; when the interview language is not English, translate the variants on the fly as you render the table — do not paste the English source verbatim and do not ask the user which language to use.
+
 ## Example
 
-Bad (old style):
+Bad (old style — questionnaire dump):
 
 > Please answer the following questions:
 > 1. What is the product?
@@ -34,20 +42,45 @@ Bad (old style):
 > 4. What are the success metrics?
 > 5. What are the key constraints?
 
-Good (protocol style):
+Good (protocol style — one question, table of variants, 5 rows max, one Recommended):
 
 > 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
+> | ID | Variant                                                                       |
+> |----|-------------------------------------------------------------------------------|
+> | a  | A B2B SaaS tool for internal teams (dashboards, automation) **Recommended**   |
+> | 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. The `**Recommended**` marker on row `a` reflects the loaded SaaS domain reference + the inline context the user gave with `/brief`.*
+
+> Got it — internal B2B SaaS tool. Who is the primary user?
+>
+> | ID | Variant                                                                  |
+> |----|--------------------------------------------------------------------------|
+> | a  | Product Manager at a 50–500-person SaaS startup **Recommended**          |
+> | 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. Tables stay at 5 rows or fewer; exactly one predefined row is marked Recommended, never the "Other" row.*
 
-*User picks 1 or types custom.*
+### Variant translation example (rule 11)
 
-> Got it — internal B2B SaaS tool. Who is the primary user? [next question with 3–5 options tailored to B2B SaaS internal tooling]
+If the user's first message was in Russian, the same question is rendered with Russian variants and a translated `Variant` header / `Recommended` marker — `ID` column and letter IDs stay ASCII:
+
+> Давайте начнём с самого продукта. Что вы создаёте?
+>
+> | ID | Вариант                                                                          |
+> |----|----------------------------------------------------------------------------------|
+> | a  | B2B SaaS-инструмент для внутренних команд (дашборды, автоматизация) **Рекомендуется** |
+> | b  | Клиентское веб-приложение (маркетплейс, портал)                                  |
+> | c  | Мобильное приложение (для потребителей или B2B)                                  |
+> | d  | API / платформа для разработчиков                                                |
+> | e  | Другое — введите свой вариант                                                    |
 
 ## 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.
+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 + rules 9–11. 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/research/SKILL.md

@@ -23,7 +23,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -129,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,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 

package/skills/srs/SKILL.md

@@ -23,7 +23,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -80,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:
+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.
 
-```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.
-```
-
-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
 
@@ -117,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,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -78,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,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.
 
@@ -84,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,9 @@ Read `references/environment.md` from the `ba-toolkit` directory to determine th
 
 ## Interview
 
-> **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.
+> **Follow the [Interview Protocol](../references/interview-protocol.md):** ask one question at a time, present a 2-column `| ID | Variant |` markdown table of up to 4 domain-appropriate options plus a free-text "Other" row last (5 rows max), mark exactly one row **Recommended** based on the loaded domain reference and prior answers, render variants in the user's language (rule 11), 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.