@kudusov.takhir/ba-toolkit 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -11,6 +11,39 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.4.0] — 2026-04-08
+
+### Added
+
+- **`ba-toolkit uninstall --for <agent>`** — remove BA Toolkit skills from an agent's directory. Symmetric to `install`: same `--for`, `--global`, `--project`, `--dry-run` flag set, same project-vs-global default. Counts files in the destination, asks `Remove {dest}? (y/N)` (defaults to N), and prints `Removed N files` after the rm completes. The pre-removal safety guard refuses to proceed unless `path.basename(destDir) === 'ba-toolkit'` — this is the only place in the CLI that calls `fs.rmSync({recursive: true})`, so it gets the strictest validation against future bugs that could turn it into `rm -rf $HOME`.
+- **`ba-toolkit upgrade --for <agent>`** (aliased as `update`) — refresh skills after a toolkit version bump. Reads the new version sentinel (see below), compares to `PKG.version`, and either prints `Already up to date` or wipes the destination wholesale and re-runs install with `force: true` (skipping the overwrite prompt). The wipe-and-reinstall approach guarantees that files removed from the toolkit between versions don't linger as ghost files in the destination — fixes the same class of bug that motivated `cmdUninstall`'s safety check. Pre-1.4 installs with no sentinel are treated as out-of-date and get a clean reinstall on first upgrade.
+- **`ba-toolkit status`** — pure read-only inspection: scans every (agent × scope) combination — 5 agents × project/global where supported, 8 real locations in total — and reports which versions of BA Toolkit are installed where. Output is grouped per installation, multi-line for readability, with colored version labels (`green: current` / `yellow: outdated` / `gray: pre-1.4 install with no sentinel`) and a summary footer pointing at `upgrade` for stale installs. Drives the natural follow-up to the version sentinel: now there's something to read it back with.
+- **Version sentinel `.ba-toolkit-version`** — `runInstall` now writes a hidden JSON marker file (`{"version": "1.4.0", "installedAt": "..."}`) into the install destination after a successful copy. The file has no `.md`/`.mdc` extension, so all five supported agents' skill loaders ignore it. Lets `upgrade` and `status` tell which package version is currently installed without diffing every file.
+- **`runInstall({..., force: true})` option** — skips the existing-destination overwrite prompt. Used by `cmdUpgrade` because it has already wiped the destination (or is in dry-run) and the prompt would just be noise. Not exposed as a CLI flag — `force` is an internal API surface only.
+
+### Fixed
+
+- **Five Tier 1 CLI fixes were already shipped in 1.3.2**, but they're worth restating in context here because 1.4.0 builds directly on the same `bin/ba-toolkit.js` improvements: `cmdInit` now honours `runInstall`'s return value (no false success message after a declined overwrite), `parseArgs` accepts `--key=value` form, the readline lifecycle and SIGINT handling are unified through a single shared interface with `INPUT_CLOSED` rejection, the slug-derivation path prints a clear error when the input has no ASCII letters, and `AGENTS.md` now lists all 21 skills (the previous template was missing the 8 cross-cutting utilities added in v1.1 and v1.2). See the 1.3.2 entry below for the per-fix detail.
+
+### Internal
+
+- **`resolveAgentDestination(...)` helper** — extracted scope-resolution logic from `runInstall`'s inline checks. `cmdUninstall` and `cmdUpgrade` reuse it. `runInstall` itself could be refactored to call the helper too in a follow-up — kept inline for now to keep this release's diff focused on the user-facing features.
+- **Documentation:** `CLAUDE.md` added at the repo root, with project conventions, the release flow (including the `.claude/settings.local.json` stash dance), the npm publish CI gotchas (curl tarball bypass for the broken bundled npm, `_authToken` strip for OIDC), and the do-not-touch list. Future Claude Code sessions get the institutional context without reading the full git log.
+
+---
+
+## [1.3.2] — 2026-04-08
+
+### Fixed
+
+- **`bin/ba-toolkit.js` `cmdInit` ignored `runInstall` return value.** When the user declined the "Overwrite? (y/N)" prompt for an existing skill destination, `runInstall` returned `false`, but `cmdInit` ignored it and printed the success path ("Project is ready. Next steps: Restart Claude Code to load the new skills") even though no skills were installed. The next-steps block now branches on the install result and tells the user how to retry: `ba-toolkit install --for {agentId}`.
+- **`parseArgs` did not accept `--key=value` form.** The hand-rolled parser only understood `--key value` (space-separated). Users typing the GNU long-option style accepted by git/npm/gh (`--name=MyApp`, `--domain=saas`) silently lost the value — the flag was stored as `name=MyApp` set to `true` and the script then prompted for the project name interactively. Both forms now work and can be mixed in a single invocation. Splits on the first `=` only, so values containing further `=` characters are preserved (e.g. `--name="Foo=Bar"`).
+- **No SIGINT handler / readline lifecycle issues.** Each `prompt()` call previously created a fresh `readline.Interface` and closed it after the answer. Hitting Ctrl+C mid-prompt killed Node abruptly and left some terminals in raw mode. Piped stdin that closed mid-flow caused the next prompt's promise to hang forever and the process to exit silently with no error message. Fixed by switching to a single shared `readline.Interface` per CLI invocation, adding a `process.on('SIGINT')` handler that prints a clean `Cancelled.` message and exits with code 130, and rejecting in-flight prompt promises with `err.code = 'INPUT_CLOSED'` when the input stream closes prematurely. The outer `main().catch(...)` filters this code to print a friendly two-line message instead of a Node stack trace.
+- **Silent failure when slug could not be derived from a non-ASCII name.** `sanitiseSlug` strips everything outside `[a-z0-9-]`, so `--name "Проект Космос"` or `--name "🚀"` produced an empty derived slug. In the non-interactive path the script then exited with a generic `Invalid or empty slug` error with no clue about why. Now in the non-interactive path it prints `Cannot derive a slug from "{name}" — it contains no ASCII letters or digits` plus a one-line workaround (`Pass an explicit slug with --slug, e.g. --slug my-project`). In the interactive path it prints a gray hint above the manual slug prompt explaining we couldn't auto-derive.
+- **`AGENTS.md` template was missing 8 of the 21 skills.** `renderAgentsMd` emitted a "Pipeline Status" table with 13 rows — the 12 numbered stages + the `7a` sub-step. The 8 cross-cutting utilities added in v1.1 and v1.2 (`/trace`, `/clarify`, `/analyze`, `/estimate`, `/glossary`, `/export`, `/risk`, `/sprint`) were missing entirely. Since `AGENTS.md` is the project context every AI agent reads on entry to a new session, those 8 skills were effectively invisible — agents didn't know they existed without re-reading README. Added a second "Cross-cutting Tools" section below the pipeline table listing all 8, with descriptions copied from the canonical README pipeline table. A `MAINTENANCE` comment above the function reminds future-me to update both tables when adding a new skill.
+
+---
+
 ## [1.3.1] — 2026-04-08
 
 ### Fixed
@@ -234,7 +267,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.1...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.4.0...HEAD
+[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
 [1.3.1]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.2.5...v1.3.0
 [1.2.5]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.2.4...v1.2.5

package/bin/ba-toolkit.js

@@ -94,6 +94,15 @@ function parseArgs(argv) {
       break;
     }
     if (a.startsWith('--')) {
+      // Support --key=value form (in addition to --key value). The `=` must
+      // come after at least one character of key, so `--=value` and `--`
+      // alone fall through. Splits on the FIRST `=` only — values may
+      // contain further `=` characters.
+      const eqIdx = a.indexOf('=');
+      if (eqIdx > 2) {
+        args.flags[a.slice(2, eqIdx)] = a.slice(eqIdx + 1);
+        continue;
+      }
       const key = a.slice(2);
       const next = argv[i + 1];
       if (next !== undefined && !next.startsWith('-')) {
@@ -114,16 +123,42 @@ function parseArgs(argv) {
 
 // --- Prompt helper -----------------------------------------------------
 
+// Shared across all prompts in a single CLI invocation. Creating a new
+// readline.Interface for every question (the previous approach) made Ctrl+C
+// handling unreliable, leaked listeners on stdin, and broke when stdin was
+// piped (EOF on the second create). One interface per process, closed by
+// closeReadline() once main() finishes (or by the SIGINT handler).
+let sharedRl = null;
+
 function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
+  if (!sharedRl) {
+    sharedRl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  }
+  return new Promise((resolve, reject) => {
+    let answered = false;
+    const onClose = () => {
+      if (!answered) {
+        const err = new Error('input stream closed before answer');
+        err.code = 'INPUT_CLOSED';
+        reject(err);
+      }
+    };
+    sharedRl.once('close', onClose);
+    sharedRl.question(question, (answer) => {
+      answered = true;
+      sharedRl.removeListener('close', onClose);
       resolve(answer.trim());
     });
   });
 }
 
+function closeReadline() {
+  if (sharedRl) {
+    sharedRl.close();
+    sharedRl = null;
+  }
+}
+
 // --- Utilities ---------------------------------------------------------
 
 function sanitiseSlug(input) {
@@ -222,6 +257,12 @@ function skillToMdc(srcPath, destPath) {
   return { destPath: newDestPath, content: mdcFrontmatter + body };
 }
 
+// MAINTENANCE: when adding a new skill, update BOTH tables below.
+// - Sequential pipeline stages (numbered 0-11 + 7a sub-step) go in
+//   "Pipeline Status" — they have a per-project status that progresses.
+// - Cross-cutting utilities (no fixed stage) go in "Cross-cutting Tools".
+// The README.md pipeline table is the canonical source of truth for the
+// 21-skill list and ordering; keep this template in sync with it.
 function renderAgentsMd({ name, slug, domain }) {
   return `# BA Toolkit — Project Context
 
@@ -253,6 +294,21 @@ function renderAgentsMd({ name, slug, domain }) {
 | 10 | /scenarios | ⬜ Not started | — |
 | 11 | /handoff | ⬜ Not started | — |
 
+## Cross-cutting Tools
+
+Utilities available throughout the pipeline. No fixed stage — invoke whenever they help. See README.md for the prerequisites of each.
+
+| Tool | Purpose |
+|------|---------|
+| /trace | Traceability Matrix + coverage gaps |
+| /clarify [focus] | Targeted ambiguity resolution for any artifact |
+| /analyze | Cross-artifact quality report with severity-rated findings |
+| /estimate | Effort estimation — Fibonacci SP, T-shirt sizes, or person-days |
+| /glossary | Unified project glossary with terminology drift detection |
+| /export [format] | Export User Stories to Jira / GitHub Issues / Linear / CSV |
+| /risk | Risk register — probability × impact matrix, mitigation per risk |
+| /sprint | Sprint plan — stories grouped by velocity and capacity with sprint goals |
+
 ## Key Constraints
 
 - Domain: ${domain}
@@ -293,12 +349,22 @@ async function cmdInit(args) {
   if (!slug) {
     const derived = sanitiseSlug(name);
     if (nameFromFlag) {
-      // Non-interactive path: silently accept the derived slug.
+      // Non-interactive path. Either accept the derived slug, or fail
+      // loudly with a hint when the name has no ASCII letters/digits to
+      // derive from (e.g. `--name "Проект"` or `--name "🚀"`). Without
+      // this branch the user got an opaque "Invalid or empty slug" with
+      // no clue why.
+      if (!derived) {
+        logError(`Cannot derive a slug from "${name}" — it contains no ASCII letters or digits.`);
+        log('Pass an explicit slug with --slug, e.g. --slug my-project');
+        process.exit(1);
+      }
       slug = derived;
     } else if (derived) {
       const custom = await prompt(`  Project slug [${cyan(derived)}]: `);
       slug = custom || derived;
     } else {
+      log('  ' + gray(`(could not derive a slug from "${name}" — please type one manually)`));
       slug = await prompt('  Project slug (lowercase, hyphens only): ');
     }
   }
@@ -389,9 +455,13 @@ async function cmdInit(args) {
   }
 
   // --- 6. Install skills for the selected agent ---
+  // installed: null = no install attempted (--no-install or no agentId),
+  //            true = install succeeded,
+  //            false = install was cancelled (e.g. user declined overwrite).
+  let installed = null;
   if (!skipInstall && agentId) {
     log('');
-    await runInstall({
+    installed = await runInstall({
       agentId,
       isGlobal: !!args.flags.global,
       isProject: !!args.flags.project,
@@ -405,10 +475,16 @@ async function cmdInit(args) {
   log('  ' + cyan(`Project '${name}' (${slug}) is ready.`));
   log('');
   log('  ' + yellow('Next steps:'));
-  if (!skipInstall && agentId) {
+  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');
+  } 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('    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'));
@@ -421,10 +497,39 @@ async function cmdInit(args) {
   log('');
 }
 
-// Core install logic. Shared between `cmdInstall` (standalone) and `cmdInit`
-// (full setup). Returns true on success, false if the user declined to
-// overwrite an existing destination.
-async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = true }) {
+// Marker file written into the install destination after a successful copy.
+// Lets `upgrade` and `status` (future command) tell which package version
+// is currently installed without diffing every file. Hidden file with no
+// `.md` / `.mdc` extension so the agent's skill loader ignores it.
+const SENTINEL_FILENAME = '.ba-toolkit-version';
+
+function readSentinel(destDir) {
+  const p = path.join(destDir, SENTINEL_FILENAME);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeSentinel(destDir) {
+  const payload = {
+    version: PKG.version,
+    installedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(
+    path.join(destDir, SENTINEL_FILENAME),
+    JSON.stringify(payload, null, 2) + '\n',
+  );
+}
+
+// Core install logic. Shared between `cmdInstall` (standalone), `cmdInit`
+// (full setup), and `cmdUpgrade`. Returns true on success, false if the
+// user declined to overwrite an existing destination. Pass `force: true`
+// to skip the overwrite prompt — `cmdUpgrade` uses this because it has
+// already wiped the destination and explicitly knows the overwrite is ok.
+async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = true, force = false }) {
   const agent = AGENTS[agentId];
   if (!agent) {
     logError(`Unknown agent: ${agentId}`);
@@ -462,7 +567,7 @@ async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = t
   log(`    format:       ${agent.format === 'mdc' ? '.mdc (converted from SKILL.md)' : 'SKILL.md (native)'}`);
   if (dryRun) log('    ' + yellow('mode:         dry-run (no files will be written)'));
 
-  if (fs.existsSync(destDir) && !dryRun) {
+  if (fs.existsSync(destDir) && !dryRun && !force) {
     const answer = await prompt(`    ${destDir} already exists. Overwrite? (y/N): `);
     if (answer.toLowerCase() !== 'y') {
       log('    cancelled.');
@@ -479,6 +584,10 @@ async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = t
     process.exit(1);
   }
 
+  if (!dryRun) {
+    writeSentinel(destDir);
+  }
+
   log('    ' + green(`${dryRun ? 'would copy' : 'copied'} ${copied.length} files.`));
   if (!dryRun && agent.format === 'mdc') {
     log('    ' + gray('SKILL.md files converted to .mdc rule format.'));
@@ -508,6 +617,271 @@ async function cmdInstall(args) {
   log('');
 }
 
+// Resolve agent + scope (project vs global) into the target directory
+// path. Shared validation for cmdUninstall — `runInstall` does its own
+// version of this inline; both could be unified later.
+function resolveAgentDestination({ agentId, isGlobal, isProject }) {
+  const agent = AGENTS[agentId];
+  if (!agent) {
+    logError(`Unknown agent: ${agentId}`);
+    log('Supported: ' + Object.keys(AGENTS).join(', '));
+    process.exit(1);
+  }
+  let effectiveGlobal = !!isGlobal;
+  if (!isGlobal && !isProject) {
+    effectiveGlobal = !agent.projectPath;
+  }
+  if (effectiveGlobal && !agent.globalPath) {
+    logError(`${agent.name} does not support --global install.`);
+    process.exit(1);
+  }
+  if (!effectiveGlobal && !agent.projectPath) {
+    logError(`${agent.name} does not support project-level install. Use --global.`);
+    process.exit(1);
+  }
+  const destDir = effectiveGlobal ? agent.globalPath : path.resolve(process.cwd(), agent.projectPath);
+  return { agent, destDir, effectiveGlobal };
+}
+
+function cmdStatus() {
+  log('');
+  log('  ' + cyan('BA Toolkit — Installation Status'));
+  log('  ' + cyan('================================'));
+  log('');
+  log(`  package version:  ${PKG.version}`);
+  log(`  scanning from:    ${process.cwd()}`);
+  log('');
+
+  // Walk every (agent × scope) combination and collect the ones whose
+  // destination directory actually exists. Project-scope paths resolve
+  // against the current working directory; global paths are absolute.
+  const rows = [];
+  for (const [agentId, agent] of Object.entries(AGENTS)) {
+    if (agent.projectPath) {
+      const projectDir = path.resolve(process.cwd(), agent.projectPath);
+      if (fs.existsSync(projectDir)) {
+        const sentinel = readSentinel(projectDir);
+        rows.push({
+          agentName: agent.name,
+          agentId,
+          scope: 'project',
+          path: projectDir,
+          version: sentinel ? sentinel.version : null,
+          installedAt: sentinel ? sentinel.installedAt : null,
+        });
+      }
+    }
+    if (agent.globalPath) {
+      if (fs.existsSync(agent.globalPath)) {
+        const sentinel = readSentinel(agent.globalPath);
+        rows.push({
+          agentName: agent.name,
+          agentId,
+          scope: 'global',
+          path: agent.globalPath,
+          version: sentinel ? sentinel.version : null,
+          installedAt: sentinel ? sentinel.installedAt : null,
+        });
+      }
+    }
+  }
+
+  if (rows.length === 0) {
+    log('  ' + gray('No BA Toolkit installations found in any known location.'));
+    log('  ' + gray("Run 'ba-toolkit install --for <agent>' to install one."));
+    log('');
+    return;
+  }
+
+  log(`  Found ${bold(rows.length)} installation${rows.length === 1 ? '' : 's'}:`);
+  log('');
+
+  for (const row of rows) {
+    let versionLabel;
+    if (!row.version) {
+      versionLabel = gray('(unknown — pre-1.4 install with no sentinel)');
+    } else if (row.version === PKG.version) {
+      versionLabel = green(row.version + ' (current)');
+    } else {
+      versionLabel = yellow(row.version + ' (outdated)');
+    }
+    log(`  ${bold(row.agentName)} ${gray('(' + row.agentId + ', ' + row.scope + ')')}`);
+    log(`    path:      ${row.path}`);
+    log(`    version:   ${versionLabel}`);
+    if (row.installedAt) {
+      log(`    installed: ${gray(row.installedAt)}`);
+    }
+    log('');
+  }
+
+  const stale = rows.filter((r) => !r.version || r.version !== PKG.version);
+  if (stale.length > 0) {
+    log('  ' + yellow(`${stale.length} installation${stale.length === 1 ? '' : 's'} not at version ${PKG.version}.`));
+    log('  ' + gray("Run 'ba-toolkit upgrade --for <agent>' to refresh."));
+    log('');
+  } else {
+    log('  ' + green('All installations are up to date.'));
+    log('');
+  }
+}
+
+async function cmdUpgrade(args) {
+  const agentId = args.flags.for;
+  if (!agentId || agentId === true) {
+    logError('--for <agent> is required.');
+    log('Supported agents: ' + Object.keys(AGENTS).join(', '));
+    process.exit(1);
+  }
+  const { agent, destDir, effectiveGlobal } = resolveAgentDestination({
+    agentId,
+    isGlobal: !!args.flags.global,
+    isProject: !!args.flags.project,
+  });
+  const dryRun = !!args.flags['dry-run'];
+
+  log('');
+  log('  ' + cyan(`BA Toolkit — Upgrade for ${agent.name}`));
+  log('  ' + cyan('================================'));
+  log('');
+  log(`  destination:  ${destDir}`);
+  log(`  scope:        ${effectiveGlobal ? 'global (user-wide)' : 'project-level'}`);
+
+  if (!fs.existsSync(destDir)) {
+    log('');
+    log('  ' + gray(`No installation found at ${destDir}.`));
+    log('  ' + gray(`Run \`ba-toolkit install --for ${agentId}\` first.`));
+    log('');
+    return;
+  }
+
+  const sentinel = readSentinel(destDir);
+  const currentVersion = PKG.version;
+  const installedVersion = sentinel ? sentinel.version : null;
+
+  if (installedVersion === currentVersion) {
+    log(`  installed:    ${installedVersion} (current)`);
+    log(`  package:      ${currentVersion}`);
+    log('');
+    log('  ' + green('Already up to date.'));
+    log('  ' + gray(`To force a clean reinstall, run \`ba-toolkit install --for ${agentId}\`.`));
+    log('');
+    return;
+  }
+
+  log(`  installed:    ${installedVersion || gray('(unknown — pre-1.4 install with no sentinel)')}`);
+  log(`  package:      ${currentVersion}`);
+  if (dryRun) log('  ' + yellow('mode:         dry-run (no files will be written)'));
+  log('');
+
+  // Safety: same guard as cmdUninstall — never rmSync anything that
+  // doesn't look like a ba-toolkit folder.
+  if (path.basename(destDir) !== 'ba-toolkit') {
+    logError(`Refusing to upgrade suspicious destination (not a ba-toolkit folder): ${destDir}`);
+    process.exit(1);
+  }
+
+  // Count files in the existing install for the dry-run preview.
+  if (dryRun) {
+    let existingCount = 0;
+    (function walk(d) {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const p = path.join(d, entry.name);
+        if (entry.isDirectory()) walk(p);
+        else existingCount++;
+      }
+    })(destDir);
+    log('  ' + yellow(`would remove ${existingCount} existing files`));
+  } else {
+    log('  ' + green('Removing previous install...'));
+    fs.rmSync(destDir, { recursive: true, force: true });
+  }
+
+  const ok = await runInstall({
+    agentId,
+    isGlobal: effectiveGlobal,
+    isProject: !effectiveGlobal,
+    dryRun,
+    showHeader: false,
+    force: true,
+  });
+  log('');
+  if (ok && !dryRun) {
+    log('  ' + cyan(`Upgraded to ${currentVersion}.`));
+    log('  ' + yellow(agent.restartHint));
+  }
+  log('');
+}
+
+async function cmdUninstall(args) {
+  const agentId = args.flags.for;
+  if (!agentId || agentId === true) {
+    logError('--for <agent> is required.');
+    log('Supported agents: ' + Object.keys(AGENTS).join(', '));
+    process.exit(1);
+  }
+  const { agent, destDir, effectiveGlobal } = resolveAgentDestination({
+    agentId,
+    isGlobal: !!args.flags.global,
+    isProject: !!args.flags.project,
+  });
+  const dryRun = !!args.flags['dry-run'];
+
+  log('');
+  log('  ' + cyan(`BA Toolkit — Uninstall from ${agent.name}`));
+  log('  ' + cyan('================================'));
+  log('');
+  log(`  destination:  ${destDir}`);
+  log(`  scope:        ${effectiveGlobal ? 'global (user-wide)' : 'project-level'}`);
+  if (dryRun) log('  ' + yellow('mode:         dry-run (no files will be removed)'));
+  log('');
+
+  // Safety: this is the only place in the CLI that calls fs.rmSync with
+  // recursive: true. Refuse to proceed unless the destination is clearly
+  // a ba-toolkit folder (the install paths in AGENTS all end in
+  // `ba-toolkit/`). Without this check, a corrupted AGENTS entry or a
+  // future bug could turn this into `rm -rf $HOME`.
+  if (path.basename(destDir) !== 'ba-toolkit') {
+    logError(`Refusing to remove suspicious destination (not a ba-toolkit folder): ${destDir}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(destDir)) {
+    log('  ' + gray(`Nothing to uninstall — ${destDir} does not exist.`));
+    log('');
+    return;
+  }
+
+  // Count files for the preview message and final confirmation.
+  let fileCount = 0;
+  (function walk(d) {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, entry.name);
+      if (entry.isDirectory()) walk(p);
+      else fileCount++;
+    }
+  })(destDir);
+
+  log(`  Found ${bold(fileCount)} files in the destination.`);
+
+  if (dryRun) {
+    log('  ' + yellow(`would remove ${fileCount} files from ${destDir}.`));
+    log('');
+    return;
+  }
+
+  log('');
+  const answer = await prompt(`  Remove ${destDir}? (y/N): `);
+  if (answer.toLowerCase() !== 'y') {
+    log('  Cancelled.');
+    log('');
+    return;
+  }
+  fs.rmSync(destDir, { recursive: true, force: true });
+  log('  ' + green(`Removed ${fileCount} files from ${destDir}.`));
+  log('  ' + yellow(agent.restartHint));
+  log('');
+}
+
 function cmdHelp() {
   log(`${bold('ba-toolkit')} v${PKG.version} — AI-powered Business Analyst pipeline
 
@@ -521,6 +895,18 @@ ${bold('COMMANDS')}
                                  skills into the chosen agent's directory.
   install --for <agent>          Install (or re-install) skills into an
                                  agent's directory without creating a project.
+  uninstall --for <agent>        Remove BA Toolkit skills from an agent's
+                                 directory. Asks for confirmation before
+                                 deleting; supports --dry-run.
+  upgrade --for <agent>          Refresh skills after a toolkit version bump.
+                                 Compares the installed version sentinel
+                                 against the package version, wipes the old
+                                 install on mismatch, and re-runs install.
+                                 Aliased as 'update'.
+  status                         Scan all known install locations for every
+                                 supported agent (project + global) and
+                                 report which versions are installed where.
+                                 Read-only; no flags.
 
 ${bold('INIT OPTIONS')}
   --name <name>                  Skip the project name prompt
@@ -541,6 +927,20 @@ ${bold('INSTALL OPTIONS')}
   --project                      Project-level install (default when supported)
   --dry-run                      Preview without writing files
 
+${bold('UNINSTALL OPTIONS')}
+  --for <agent>                  One of: ${Object.keys(AGENTS).join(', ')}
+  --global                       Remove the user-wide install
+  --project                      Remove the project-level install
+                                 (default when the agent supports it)
+  --dry-run                      Preview without removing files
+
+${bold('UPGRADE OPTIONS')}
+  --for <agent>                  One of: ${Object.keys(AGENTS).join(', ')}
+  --global                       Upgrade the user-wide install
+  --project                      Upgrade the project-level install
+                                 (default when the agent supports it)
+  --dry-run                      Preview without writing or removing files
+
 ${bold('GENERAL OPTIONS')}
   --version, -v                  Print version and exit
   --help, -h                     Print this help and exit
@@ -559,6 +959,18 @@ ${bold('EXAMPLES')}
   ba-toolkit install --for claude-code
   ba-toolkit install --for cursor --dry-run
 
+  # Remove skills from an agent (asks for confirmation).
+  ba-toolkit uninstall --for claude-code
+  ba-toolkit uninstall --for claude-code --global
+  ba-toolkit uninstall --for cursor --dry-run
+
+  # After 'npm update -g @kudusov.takhir/ba-toolkit', refresh the skills.
+  ba-toolkit upgrade --for claude-code
+  ba-toolkit upgrade --for cursor --dry-run
+
+  # See where (and which version) BA Toolkit is installed.
+  ba-toolkit status
+
 ${bold('LEARN MORE')}
   https://github.com/TakhirKudusov/ba-toolkit
 `);
@@ -587,6 +999,16 @@ async function main() {
     case 'install':
       await cmdInstall(args);
       break;
+    case 'uninstall':
+      await cmdUninstall(args);
+      break;
+    case 'upgrade':
+    case 'update':
+      await cmdUpgrade(args);
+      break;
+    case 'status':
+      cmdStatus();
+      break;
     case 'help':
       cmdHelp();
       break;
@@ -597,7 +1019,26 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  logError(err && (err.stack || err.message) || String(err));
-  process.exit(1);
+// Clean exit on Ctrl+C: print on a fresh line so we don't append to a
+// half-typed prompt, close the readline interface so the terminal is
+// returned to a sane state, then exit with the conventional 130 code.
+process.on('SIGINT', () => {
+  console.log('\n  ' + yellow('Cancelled.'));
+  closeReadline();
+  process.exit(130);
 });
+
+main()
+  .then(() => {
+    closeReadline();
+  })
+  .catch((err) => {
+    closeReadline();
+    if (err && err.code === 'INPUT_CLOSED') {
+      logError('Input stream closed before all prompts could be answered.');
+      log('Pass remaining values as flags (e.g. --name, --domain, --for) or run interactively.');
+      process.exit(1);
+    }
+    logError(err && (err.stack || err.message) || String(err));
+    process.exit(1);
+  });

package/package.json

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