@kudusov.takhir/ba-toolkit 2.0.0 → 3.1.0

package/CHANGELOG.md

@@ -11,6 +11,96 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [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
+
+Cursor and Windsurf both have **two separate features**: Rules (`.cursor/rules/*.mdc`, `.windsurf/rules/*.mdc`) and Agent Skills (`.cursor/skills/<skill>/SKILL.md`, `.windsurf/skills/<skill>/SKILL.md`). BA Toolkit is a pipeline of skills, not rules, but every previous version installed it as `.mdc` rules under `.cursor/rules/` and `.windsurf/rules/`. Both editors loaded those files as **rules**, never as skills, so `/brief`, `/srs`, … slash commands were never registered with the agent. Users reported that the skills did not show up. v3.0 fixes this by switching to the native Agent Skills paths and the native folder-per-skill `SKILL.md` layout (the same one Claude Code, Codex CLI, and Gemini CLI use). Confirmed against the official Cursor and Windsurf documentation via ctx7 MCP:
+
+| Agent | v2.0 path (broken) | v3.0 path (correct) | Format |
+|---|---|---|---|
+| Cursor | `.cursor/rules/<skill>.mdc` (flat) | `.cursor/skills/<skill>/SKILL.md` (folder-per-skill) | Native |
+| Windsurf | `.windsurf/rules/<skill>.mdc` (flat) | `.windsurf/skills/<skill>/SKILL.md` (folder-per-skill) | Native |
+
+**Migration for v2.0 Cursor/Windsurf users:**
+
+```bash
+# 1. Upgrade the package
+npm install -g @kudusov.takhir/ba-toolkit@latest
+
+# 2. Reinstall — the old install was at the wrong path; upgrade can't find
+#    its manifest there, so just run install fresh against the correct path.
+ba-toolkit install --for cursor      # writes to .cursor/skills/
+ba-toolkit install --for windsurf    # writes to .windsurf/skills/
+
+# 3. Manually clean up the orphaned old install (it never actually worked
+#    as skills anyway — Cursor/Windsurf were loading it as rules):
+rm -rf .cursor/rules/*.mdc           # if those .mdc files came from BA Toolkit
+rm -rf .windsurf/rules/*.mdc
+```
+
+After this you'll see the BA Toolkit skills register as actual Agent Skills in Cursor and Windsurf for the first time — `/brief`, `/srs`, `/ac`, `/nfr`, … become real slash commands. Reload the editor window after install. Claude Code, Codex CLI, and Gemini CLI users are unaffected — their paths and behavior are unchanged.
+
+### Added
+
+- **Integration test suite for every CLI subcommand** (`test/cli.integration.test.js`, 33 tests). Spawns the real CLI as a child process against temporary directories and asserts exit codes, stdout/stderr content, and filesystem state. Covers `--version`/`--help`/no-args, typo detection for unknown flags, `init` with flag combinations and validation failures, `install`/`upgrade`/`uninstall` dry-runs for every supported agent, end-to-end install → manifest → status → upgrade → uninstall round-trips for both Claude Code and Cursor (native skill format), and a regression guard proving that `uninstall` leaves the user's own unrelated skills in the shared destination untouched (manifest-driven removal guarantee).
+- **Test gate in `.github/workflows/release.yml`**. A new `Run tests` step runs `npm test` between the smoke test and the npm publish step — if any unit or integration test fails, the `publish-npm` job exits before the classic-auth strip + publish steps, and no broken release reaches npm. The GitHub Release created by the preceding job still happens; npm and GitHub are intentionally independent.
+- **Test job in `.github/workflows/validate.yml`**. A new `run-tests` job mirrors the release gate at PR time, so regressions are caught on the PR instead of at tag push. Triggered for changes under `bin/**`, `test/**`, `skills/**`, `output/**`, or `package.json`.
+- **ASCII banner at the top of `ba-toolkit init`**. Decorative `ba-toolkit` wordmark printed before the "New Project Setup" heading. Suppressed on non-TTY stdout (CI logs, piped output, captured test stdout) via an `isTTY` guard in `printBanner()`, so the banner never pollutes automation. Covered by a regression test that asserts the banner glyphs don't appear in non-TTY runs.
+- **Arrow-key menu navigation in `ba-toolkit init`** for the domain and agent selection prompts. Real terminals now get an interactive menu — `↑/↓` (also `j/k`) to move, `1-9` to jump by index, `Enter` to confirm, `Esc` or `Ctrl+C` to cancel cleanly with exit code 130. The previous numbered prompt is the automatic fallback when stdin/stdout is not a TTY (CI, piped input, `TERM=dumb`, IDE shells), so all CI/integration tests and the `printf | ba-toolkit init` use case keep working unchanged. Cross-platform via Node's `readline.emitKeypressEvents` + `setRawMode` — works the same on bash, zsh, fish, Windows Terminal (PowerShell, cmd, WSL), Git Bash, and VSCode integrated terminal. Three-layer design for testability: `menuStep(state, key)` — pure state machine, 11 unit tests; `renderMenu(state, opts)` — pure renderer, 7 unit tests; `runMenuTty` — the I/O glue, manually smoke-tested.
+- **Interview Protocol for every interview-phase skill** (`skills/references/interview-protocol.md`). Codifies the rule that AI skills must ask ONE question at a time, offer 3–5 domain-appropriate options per question sourced from `references/domains/{domain}.md`, always include a free-text "Other" option as the last choice, and wait for an answer before asking the next question. Replaces the previous "dump a numbered questionnaire of 5+ questions at once" style that made users abandon long interviews. Every shipped SKILL.md with an `Interview` heading — 12 files: `brief`, `srs`, `stories`, `usecases`, `ac`, `nfr`, `datadict`, `apicontract`, `wireframes`, `scenarios`, `research`, `principles` — now opens its Interview section with a blockquote pointing to this protocol. A Node-level regression test in `test/cli.test.js` walks every shipped SKILL.md and fails if any interview skill ever ships without the protocol link; a mirror validation step in `.github/workflows/validate.yml` catches the same at PR time.
+
+### Changed
+
+- **`ba-toolkit init` now merges `AGENTS.md` instead of overwriting it.** The `agents-template.md` wraps the Active Project block (name/slug/domain/date) in `<!-- ba-toolkit:begin managed -->` / `<!-- ba-toolkit:end managed -->` anchors. On re-init, only the managed block is refreshed — Pipeline Status edits, Key Constraints, Open Questions, user notes, and anything else outside the anchors is preserved byte-for-byte. If an existing `AGENTS.md` has no anchors (legacy file or fully user-authored), it's left untouched and a `preserved` note is printed instead of overwriting. The old interactive "AGENTS.md already exists. Overwrite? (y/N)" prompt is removed — the merge is always safe. New pure helper `mergeAgentsMd(existing, ctx)` exported from `bin/ba-toolkit.js` with unit tests covering all three branches (`created`, `merged`, `preserved`) plus malformed-anchor edge cases; integration tests verify the double-init scenario and the unmanaged-file preservation.
+- `npm test` now runs both the pre-existing unit suite (`test/cli.test.js`) and the new integration suite — 154 tests total, ~2 seconds, still zero dependencies (only Node built-ins: `node:test`, `node:assert`, `node:child_process`).
+- `.gitignore` now excludes `.claude/settings.local.json` and `.claude/skills/` — local Claude Code state, never part of the package. `settings.local.json` was previously tracked and required a stash dance around `npm version`; that workaround is no longer needed.
+
+### Fixed
+
+- **Cursor install now targets `.cursor/skills/` with native SKILL.md format, not `.cursor/rules/` with `.mdc` conversion.** See the BREAKING section above for the full story and migration steps.
+- **Windsurf install now targets `.windsurf/skills/` with native SKILL.md format, not `.windsurf/rules/` with `.mdc` conversion.** Mirror of the Cursor fix. Confirmed against the [Windsurf Agent Skills documentation](https://docs.windsurf.com/windsurf/cascade/skills) via ctx7 MCP: Windsurf loads skills from `.windsurf/skills/<skill-name>/SKILL.md` as folder-per-skill with the same YAML frontmatter (`name`, `description`) as Claude Code and Cursor.
+- **`ba-toolkit init` no longer crashes on a single typo during interactive input.** The domain menu, agent menu, and manual slug entry now re-prompt on invalid input via a new `promptUntilValid(question, resolver, { maxAttempts, invalidMessage })` helper. After three consecutive invalid answers the command aborts with a clear "Too many invalid attempts — aborting." message so piped input can't infinite-loop. The flag-path (`--domain=banana`, `--for=vim`) still hard-fails immediately — that's the correct behavior for CI and scripting, and its tests are untouched.
+- **`prompt()` race condition that silently dropped piped input lines.** The previous implementation used `rl.question()` on a shared `readline.Interface`; when stdin was piped with multiple answers at once (e.g. `printf "banana\nsaas\n" | ba-toolkit init`, or any test feeding a full input buffer via `spawnSync`), readline emitted `'line'` events before the next `question()` handler had been attached, and those answers were silently lost. The second prompt then saw EOF and aborted with `INPUT_CLOSED` despite the answer being in the buffer. The new `prompt()` owns the `'line'` event directly, buffers arriving lines into an internal `lineQueue`, and parks `waiters` when the queue is empty — no more lost input. Uncovered while wiring up the `promptUntilValid` retry path.
+
+### Removed
+
+- **`.mdc` rule format conversion path is gone** — every shipped agent now uses native Agent Skills, so the conversion was dead code. Deleted: `skillToMdcContent()` (and its 2 unit tests), the `mdc` branch of `copySkills()`, the `format` field on every entry in `AGENTS`, the `format` parameter passed to `copySkills` and `writeManifest`, the runtime "format: .mdc (converted from SKILL.md)" log line. The `format` field is also gone from new manifests, but `readManifest` still parses legacy manifests that have it (covered by a forward-compat unit test). Net removal: ~80 lines of code + 2 unit tests; CLI surface unchanged.
+
+---
+
 ## [2.0.0] — 2026-04-09
 
 ### ⚠️ BREAKING — install layout dropped the `ba-toolkit/` wrapper
@@ -350,7 +440,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.1.0...HEAD
+[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
 [1.4.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.2...v1.4.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

@@ -13,8 +13,8 @@ Structured BA pipeline for AI coding agents — brief to handoff, 21 skills, 9 d
 <img src="https://img.shields.io/badge/Claude_Code-✓-6C5CE7" alt="Claude Code">
 <img src="https://img.shields.io/badge/Codex_CLI-✓-00D26A" alt="Codex CLI">
 <img src="https://img.shields.io/badge/Gemini_CLI-✓-4285F4" alt="Gemini CLI">
-<img src="https://img.shields.io/badge/Cursor-convert-F5A623" alt="Cursor">
-<img src="https://img.shields.io/badge/Windsurf-convert-1ABCFE" alt="Windsurf">
+<img src="https://img.shields.io/badge/Cursor-✓-F5A623" alt="Cursor">
+<img src="https://img.shields.io/badge/Windsurf-✓-1ABCFE" alt="Windsurf">
 
 </div>
 
@@ -46,7 +46,21 @@ npm install -g @kudusov.takhir/ba-toolkit
 ba-toolkit init
 ```
 
-Supported agents: `claude-code`, `codex`, `gemini`, `cursor`, `windsurf`. Cursor and Windsurf installs auto-convert `SKILL.md` into the `.mdc` rule format. 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>`.
+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.
 
@@ -55,7 +69,7 @@ Supported agents: `claude-code`, `codex`, `gemini`, `cursor`, `windsurf`. Cursor
 
 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
 
@@ -98,21 +112,17 @@ cp -R ba-toolkit/skills/. /path/to/project/.gemini/skills/
 
 Reload the CLI after copying.
 
-### Cursor, Windsurf, Aider
+### Cursor
 
-These use their own rules format instead of `SKILL.md`. Convert first, then copy:
+Cursor has two separate features — Rules (`.cursor/rules/*.mdc`) and [Agent Skills](https://cursor.com/docs/skills) (`.cursor/skills/<skill>/SKILL.md`). BA Toolkit is a set of skills, not rules, so `ba-toolkit install --for cursor` drops the 21 skills directly into `.cursor/skills/` using the native folder-per-skill `SKILL.md` format — no conversion needed. Reload the Cursor window to pick them up.
 
-```bash
-# Option 1: community converter
-# https://github.com/alirezarezvani/claude-skills/blob/main/scripts/convert.sh
-./convert.sh --tool cursor --target /path/to/project
-./convert.sh --tool windsurf --target /path/to/project
+### Windsurf
 
-# Option 2: ask your AI agent
-# "Convert all SKILL.md files in skills/ to Cursor .mdc rule format"
-```
+Windsurf's [Agent Skills](https://docs.windsurf.com/windsurf/cascade/skills) feature loads skills from `.windsurf/skills/<skill>/SKILL.md`, the same folder-per-skill layout as Claude Code and Cursor. `ba-toolkit install --for windsurf` writes the 21 skills there natively. Reload the Windsurf window to pick them up.
+
+### Aider
 
-Cursor rules live in [`.cursor/rules/`](https://cursor.com/docs/rules) as `.mdc` files with YAML frontmatter (`description`, optional `globs`, `alwaysApply`). A plain rename of `SKILL.md` to `.mdc` is not enough — the metadata block is required. [Cursor CLI](https://cursor.com/docs/cli/using) reads the same `.cursor/rules` setup and may also pick up `AGENTS.md` / `CLAUDE.md` at repo root.
+Aider has no native skills feature. Convert manually with the community script at <https://github.com/alirezarezvani/claude-skills/blob/main/scripts/convert.sh> or ask your AI agent to convert `SKILL.md` files to the target format.
 
 ### Starting a new project (shell scripts)
 
@@ -192,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`.
 
 ---
 
@@ -205,11 +215,11 @@ BA Toolkit uses the open Agent Skills specification (`SKILL.md` format) publishe
 | **Claude Code** | Native | `cp -R skills/. .claude/skills/` |
 | **OpenAI Codex CLI** | Native | `cp -R skills/. ~/.codex/skills/` |
 | **Gemini CLI** | Native | Copy `skills/.` contents to `~/.gemini/skills/` (user) or `.gemini/skills/` (workspace) |
-| **Cursor** | Convert | `SKILL.md` → `.mdc` rules in `.cursor/rules/` |
-| **Windsurf** | Convert | `SKILL.md` → rules in `.windsurf/rules/` |
+| **Cursor** | Native | Copy `skills/.` contents to `.cursor/skills/` |
+| **Windsurf** | Native | Copy `skills/.` contents to `.windsurf/skills/` |
 | **Aider** | Convert | `SKILL.md` → conventions file |
 
-Native platforms read `SKILL.md` as-is. Convert platforms need a one-time format conversion — the content is the same, only the file format differs. `ba-toolkit install --for cursor|windsurf` does this automatically.
+All five officially supported platforms read `SKILL.md` as-is — no conversion. `ba-toolkit install --for <agent>` lands skills directly in the agent's native skills root.
 
 Skills do not hardcode platform paths — they reference `skills/references/environment.md`, which contains the output directory logic for each platform. Edit that file to customize; all skills pick up the change automatically.
 
@@ -217,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 |
 |--------|-------------------|