@kudusov.takhir/ba-toolkit 1.5.0 → 3.0.0

package/CHANGELOG.md

@@ -11,6 +11,120 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [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
+
+**Every previous version of this package was broken.** The CLI installed skills under a `ba-toolkit/` wrapper folder (e.g. `.claude/skills/ba-toolkit/brief/SKILL.md`), but Claude Code, Codex CLI, Gemini CLI, Cursor and Windsurf all expect skills as **direct children** of their skills/rules root (`.claude/skills/<skill-name>/SKILL.md`). The wrapper made every shipped skill invisible to the agent — `/brief`, `/srs`, etc. silently did nothing because the agent didn't know they existed. The README, examples and all documentation referenced `/brief`, but the install path made it impossible for that command to ever resolve. Confirmed against the [official Claude Code skills documentation](https://code.claude.com/docs/en/skills.md): *"Each skill is a directory with `SKILL.md` as the entrypoint"* under `.claude/skills/<skill-name>/`, with no nested-namespace support.
+
+v2.0 fixes this for real:
+
+- **All 5 agent install paths drop the `ba-toolkit/` wrapper.** New paths:
+  - Claude Code: `.claude/skills/` (project) and `~/.claude/skills/` (global)
+  - OpenAI Codex CLI: `~/.codex/skills/` (global only)
+  - Gemini CLI: `.gemini/skills/` and `~/.gemini/skills/`
+  - Cursor: `.cursor/rules/` (project only, flat .mdc files)
+  - Windsurf: `.windsurf/rules/` (project only, flat .mdc files)
+- **Cursor and Windsurf layouts are now flat.** Previously each skill was nested under `.cursor/rules/ba-toolkit/<skill>/<skill>.mdc` (3 levels). Now each becomes a single `.mdc` file at the rules root: `.cursor/rules/<skill>.mdc`. Cursor's rule loader expects flat `.mdc` files, never recurses.
+- **SKILL.md `name:` field renamed.** The 21 SKILL.md files used `name: ba-brief`, `name: ba-srs`, etc. But Claude Code derives the slash command from the `name` field — so the actual command was `/ba-brief`, not `/brief` as the README promised. All 21 files now use bare names (`name: brief`, `name: srs`, ...), and the slash commands `/brief`, `/srs`, `/ac`, … finally match the documentation.
+- **Manifest replaces sentinel.** `runInstall` now writes `.ba-toolkit-manifest.json` listing every item it owns at the destination root. `cmdUninstall` and `cmdUpgrade` read the manifest and remove **only** those items — the destination directory is now shared with the user's other skills, so we can never `rm -rf` the whole root. Without a manifest, uninstall and upgrade refuse to do anything destructive. Manifest format:
+  ```json
+  {
+    "version": "2.0.0",
+    "installedAt": "2026-04-09T...",
+    "format": "skill",
+    "items": ["brief", "srs", "ac", ..., "references"]
+  }
+  ```
+- **Legacy v1.x detection.** `runInstall`, `cmdUpgrade`, `cmdUninstall`, and `cmdStatus` now detect the old `ba-toolkit/` wrapper folder if it's still on disk and print a yellow warning with the exact `rm -rf` command to clean it up. The legacy folder is never auto-deleted — it might contain user state.
+
+### Migration from v1.x
+
+If you have a v1.x install on disk, the legacy `ba-toolkit/` wrapper will be sitting in the same parent directory as the new layout — it doesn't conflict with v2.0 file-wise, but it never worked, so you should remove it:
+
+```bash
+# Manual cleanup (one-time, per agent that had a v1.x install):
+rm -rf .claude/skills/ba-toolkit          # claude-code project-level
+rm -rf ~/.claude/skills/ba-toolkit         # claude-code global
+rm -rf ~/.codex/skills/ba-toolkit          # codex
+rm -rf .gemini/skills/ba-toolkit           # gemini project-level
+rm -rf ~/.gemini/skills/ba-toolkit         # gemini global
+rm -rf .cursor/rules/ba-toolkit            # cursor
+rm -rf .windsurf/rules/ba-toolkit          # windsurf
+
+# Then reinstall with v2.0:
+ba-toolkit install --for claude-code
+```
+
+`ba-toolkit status` lists any legacy wrappers it finds on the system as a warning row, so you can audit before cleaning up.
+
+### Internal
+
+- **`copySkills(srcRoot, destRoot, { format })` replaces the previous `copyDir` + `skillToMdc`** combo. The new copy logic understands the per-format layout (folder-per-skill for `skill` format, flat `.mdc` files for `mdc` format) and reads the SKILL.md frontmatter to derive the canonical skill name from the `name:` field. References go to `<destRoot>/references/` regardless of format — non-`.mdc` files there are ignored by Cursor's rule loader.
+- **Manifest helpers** (`readManifest`, `writeManifest`, `removeManifestItems`) replace the previous `readSentinel` / `writeSentinel`. The sentinel was a 2-field marker; the manifest is also the source of truth for what to remove on uninstall.
+- **`detectLegacyInstall(agent)`** helper, used by every command that touches the install layout.
+- **Test count 91 → 95.** Sentinel tests replaced with manifest tests; new tests for `detectLegacyInstall` (positive and negative cases) and `skillToMdcContent` (frontmatter + body extraction). All 95 tests pass.
+
+---
+
 ## [1.5.0] — 2026-04-08
 
 ### Added
@@ -294,7 +408,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.5.0...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v3.0.0...HEAD
+[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
 [1.3.2]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.1...v1.3.2

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,7 @@ 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>`.
 
 `ba-toolkit --help` shows the full CLI reference. Zero runtime dependencies — only Node.js ≥ 18.
 
@@ -55,55 +55,60 @@ 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.
+
 ### Claude Code CLI
 
 ```bash
 git clone https://github.com/TakhirKudusov/ba-toolkit.git
-cp -r ba-toolkit/skills/ /path/to/project/.claude/skills/ba-toolkit/
 
-# Or install globally:
-cp -r ba-toolkit/skills/ ~/.claude/skills/ba-toolkit/
+# Project-level: copy the contents of skills/ into .claude/skills/
+mkdir -p /path/to/project/.claude/skills
+cp -R ba-toolkit/skills/. /path/to/project/.claude/skills/
+
+# Or globally:
+mkdir -p ~/.claude/skills
+cp -R ba-toolkit/skills/. ~/.claude/skills/
 ```
 
-Keep the full tree: skill folders (`brief/`, `srs/`, …) must stay together with `references/` in the same parent directory.
+Each skill folder (`brief/`, `srs/`, …) lands as a direct child of `.claude/skills/`, and the `references/` folder sits next to them. If you have other skills installed in the same directory, they're left alone.
 
 ### OpenAI Codex CLI
 
 Skills load from `$CODEX_HOME/skills` (default `~/.codex/skills`):
 
 ```bash
-cp -r ba-toolkit/skills/ ~/.codex/skills/ba-toolkit/
+mkdir -p ~/.codex/skills
+cp -R ba-toolkit/skills/. ~/.codex/skills/
 ```
 
-If you use a custom Codex home, set `CODEX_HOME` and copy under `$CODEX_HOME/skills/ba-toolkit/`.
+If you use a custom Codex home, set `CODEX_HOME` and copy under `$CODEX_HOME/skills/`.
 
 ### Google Gemini CLI
 
 ```bash
 # User-wide (all projects)
-cp -r ba-toolkit/skills/ ~/.gemini/skills/ba-toolkit/
+mkdir -p ~/.gemini/skills
+cp -R ba-toolkit/skills/. ~/.gemini/skills/
 
 # Or project-only
-cp -r ba-toolkit/skills/ /path/to/project/.gemini/skills/ba-toolkit/
+mkdir -p /path/to/project/.gemini/skills
+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)
 
@@ -193,14 +198,14 @@ BA Toolkit uses the open Agent Skills specification (`SKILL.md` format) publishe
 
 | Platform | Support | Installation |
 |----------|:-------:|-------------|
-| **Claude Code** | Native | `cp -r skills/ .claude/skills/ba-toolkit/` |
-| **OpenAI Codex CLI** | Native | `cp -r skills/ ~/.codex/skills/ba-toolkit/` |
-| **Gemini CLI** | Native | Copy `skills/` to `~/.gemini/skills/ba-toolkit/` (user) or `.gemini/skills/ba-toolkit/` (workspace) |
-| **Cursor** | Convert | `SKILL.md` → `.mdc` rules in `.cursor/rules/` |
-| **Windsurf** | Convert | `SKILL.md` → rules in `.windsurf/rules/` |
+| **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** | 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.