@kudusov.takhir/ba-toolkit 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -11,6 +11,54 @@ Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.5.0] — 2026-04-08
+
+### Added
+
+- **Typo detection on unknown CLI flags**, with a Levenshtein-based "Did you mean ...?" hint. Previously the parser silently accepted any `--flag` and stored it in `args.flags`, where most code paths then ignored it — users would hit `ba-toolkit init --drry-run`, get no error, and watch the script start an interactive session wondering why their flag did nothing. Now `validateFlags` runs immediately after parsing and rejects anything not in `KNOWN_FLAGS`:
+  ```
+  $ ba-toolkit init --drry-run
+  error: Unknown option: --drry-run
+    Did you mean --dry-run?
+  Run ba-toolkit --help for the full list of options.
+  ```
+  The Levenshtein threshold is calibrated (`max(1, floor(input.length / 3))`) so common typos like `--domian`, `--gloabl`, `--no-installl`, `--foo`/`--for` get matched, but unrelated inputs like `--foobar` (distance 3 from "global") get no suggestion at all — better to say nothing than suggest something wildly off.
+
+### Changed
+
+- **Help output is ~20 lines shorter.** Four nearly-duplicate options sections (`INIT OPTIONS`, `INSTALL OPTIONS`, `UNINSTALL OPTIONS`, `UPGRADE OPTIONS`) collapsed into a single `OPTIONS` section. Each flag is listed exactly once with a per-command scope annotation (`init only — ...`, `install/uninstall/upgrade — ...`). Three sections after v1.4.0 added `uninstall`/`upgrade` repeated the same four flags with only wording differences; the dedup removes the noise without losing any information.
+- **Domain and agent menu column widths are now computed dynamically** from the longest entry instead of being hardcoded to magic constants (`padEnd(13)` and `padEnd(20)`). If a future commit adds a domain or agent with a longer display name, the em-dash column on the right stays aligned automatically. No visible change for the current set.
+
+### Internal
+
+- **`AGENTS.md` template extracted** to `skills/references/templates/agents-template.md`. Previously it lived as a 44-line embedded string in `bin/ba-toolkit.js`, which was the only artifact template not in `skills/references/templates/`. Now follows the same `[NAME]` / `[SLUG]` / `[DOMAIN]` / `[DATE]` placeholder convention as `brief-template.md`, `srs-template.md`, etc. `renderAgentsMd` shrinks from a 60-line string template to a 12-line file read + four `String.replace` calls. Adding a field to the auto-generated AGENTS.md is now a Markdown edit, not a JS edit.
+- **`stringFlag(args, key)` helper extracted** to centralise the `flag && flag !== true` (and inverse `!flag || flag === true`) pattern that was repeated across `cmdInit` (4 sites), `cmdInstall`, `cmdUninstall`, `cmdUpgrade` (3 sites). Returns the string value or `null` for absent / boolean / empty-string flags. The seven call sites collapse to single-line `stringFlag(args, 'name')` reads.
+- **`parseSkillFrontmatter(content)` mini-parser** replaces the three regexes that `skillToMdc` used to extract `name` and `description` from SKILL.md frontmatter. The previous folded-scalar regex (`description:\s*>\s*\r?\n([\s\S]*?)(?:\r?\n\w|$)`) used a fragile `\r?\n\w` lookahead that would have over-captured on multi-paragraph descriptions and silently misparsed the `|` literal block scalar form (no shipped SKILL.md uses it yet, but the trap was there). The new walker handles inline / folded / literal forms uniformly, recognises chomping indicators (`>+`/`>-`/`|+`/`|-`), and correctly collapses multi-paragraph blocks with blank lines. Backward-compat verified by running `ba-toolkit install --for cursor` and confirming all 21 generated `.mdc` files have the same descriptions as before.
+- **Unit-test infrastructure (78 → 91 tests).** Pure helper functions (`sanitiseSlug`, `parseArgs`, `resolveDomain`, `resolveAgent`, `stringFlag`, `parseSkillFrontmatter`, `readSentinel`, `renderAgentsMd`, `levenshtein`, `closestMatch`) are now exported from `bin/ba-toolkit.js` (guarded by `require.main === module` so the CLI still runs directly), and covered by `test/cli.test.js` using Node's built-in `node:test` runner — zero added dependencies. The test file does not ship to npm consumers (`test/` is not in `package.json`'s `files` whitelist). Includes one integration test that loads every shipped `SKILL.md` and asserts the parser produces a non-empty single-line description for each — catches regressions where a future skill is added with a frontmatter form the parser doesn't understand.
+
+---
+
+## [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
@@ -246,7 +294,9 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.3.2...HEAD
+[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.5.0...HEAD
+[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
 [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

package/bin/ba-toolkit.js

@@ -195,6 +195,103 @@ function resolveAgent(raw) {
   return AGENTS[trimmed] ? trimmed : null;
 }
 
+// Returns the string value of a flag, or null if it's absent, was passed
+// as a bare boolean (e.g. `--name` with no following value, which
+// parseArgs stores as `true`), or has an empty value (e.g. `--name=`).
+// Centralises the `flag && flag !== true` / `!flag || flag === true`
+// pattern that was repeated across cmdInit, cmdInstall, cmdUninstall,
+// cmdUpgrade.
+function stringFlag(args, key) {
+  const v = args.flags[key];
+  return (typeof v === 'string' && v.length > 0) ? v : null;
+}
+
+// Every flag the CLI accepts. Typos that don't match anything in this
+// set are rejected by validateFlags() with a "Did you mean ...?" hint.
+// Single-letter aliases (-v, -h) are listed by their letter form.
+const KNOWN_FLAGS = new Set([
+  'name', 'slug', 'domain', 'for', 'no-install',
+  'global', 'project', 'dry-run',
+  'version', 'v', 'help', 'h',
+]);
+
+// Levenshtein distance with the standard two-row optimisation. Used by
+// closestMatch() to suggest a fix for unknown flags. Pure, exported for
+// tests.
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array(n + 1);
+  let curr = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        prev[j] + 1,        // deletion
+        curr[j - 1] + 1,    // insertion
+        prev[j - 1] + cost, // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
+// Find the candidate with the lowest Levenshtein distance to `input`,
+// but only if the distance is small enough to be a plausible typo.
+// Threshold scales with the input length: ~1 edit per 3 input chars,
+// minimum 1. This catches the common cases (transposition like
+// `--domian` for `--domain`, single insertion like `--drry-run` for
+// `--dry-run`) without producing absurd suggestions for things that
+// happen to share a few letters (`--foobar` should NOT suggest
+// `--global` even though they have distance 3).
+function closestMatch(input, candidates) {
+  if (!input) return null;
+  const threshold = Math.max(1, Math.floor(input.length / 3));
+  let best = null;
+  let bestDist = Infinity;
+  for (const c of candidates) {
+    const d = levenshtein(input, c);
+    if (d < bestDist && d <= threshold) {
+      best = c;
+      bestDist = d;
+    }
+  }
+  return best;
+}
+
+// Reject unknown flags with a helpful "Did you mean ...?" suggestion
+// when one is plausible. Called from main() after parseArgs.
+//
+// This catches typos like `--drry-run` or `--for-claude-code` (instead
+// of `--for claude-code`) that the previous version of the CLI would
+// silently store and then ignore. Both cases used to leave the user
+// staring at an interactive prompt wondering why their flag did
+// nothing.
+function validateFlags(args) {
+  const unknown = [];
+  for (const key of Object.keys(args.flags)) {
+    if (!KNOWN_FLAGS.has(key)) unknown.push(key);
+  }
+  if (unknown.length === 0) return;
+  for (const flag of unknown) {
+    const dashes = flag.length === 1 ? '-' : '--';
+    logError(`Unknown option: ${dashes}${flag}`);
+    const suggestion = closestMatch(flag, [...KNOWN_FLAGS]);
+    if (suggestion) {
+      const sugDashes = suggestion.length === 1 ? '-' : '--';
+      log(`  Did you mean ${cyan(sugDashes + suggestion)}?`);
+    }
+  }
+  log('Run ' + cyan('ba-toolkit --help') + ' for the full list of options.');
+  process.exit(1);
+}
+
 function today() {
   return new Date().toISOString().slice(0, 10);
 }
@@ -230,6 +327,79 @@ function copyDir(src, dest, { dryRun = false, transform = null } = {}) {
   return copied;
 }
 
+// Minimal YAML frontmatter parser for SKILL.md files.
+//
+// Replaces the previous regex-based extraction, which used a fragile
+// lookahead (`description:\s*>\s*\r?\n([\s\S]*?)(?:\r?\n\w|$)`) that
+// didn't handle blank lines inside descriptions, didn't recognise the
+// `|` literal block scalar form, and silently produced wrong output
+// if the description happened to contain a line whose first character
+// wasn't a word character.
+//
+// This is NOT a general YAML parser. It only handles the subset that
+// SKILL.md files actually use:
+//   - Top-level keys at column 0: `key: value`
+//   - Inline scalar values: `name: foo`
+//   - Folded block scalars: `description: >` followed by indented text
+//   - Literal block scalars: `description: |` followed by indented text
+//   - Block chomping indicators (>+, >-, |+, |-)
+//   - Multi-paragraph block scalars with blank lines between paragraphs
+//
+// Unsupported (not used by any SKILL.md and YAGNI for the toolkit):
+//   - Nested mappings, sequences, anchors, aliases, tags
+//   - Quoted scalars (single or double quoted) — names would keep quotes
+//
+// Returns { name, description, body }. `description` is always
+// flattened to a single line (whitespace collapsed) because the .mdc
+// rule format expects a one-line description.
+function parseSkillFrontmatter(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!fmMatch) {
+    return { name: null, description: '', body: content };
+  }
+  const frontmatter = fmMatch[1];
+  const body = fmMatch[2];
+  const lines = frontmatter.split(/\r?\n/);
+
+  const fields = {};
+  let currentKey = null;
+  let buffer = [];
+
+  const flush = () => {
+    if (currentKey !== null) {
+      fields[currentKey] = buffer.join(' ').replace(/\s+/g, ' ').trim();
+    }
+    currentKey = null;
+    buffer = [];
+  };
+
+  for (const line of lines) {
+    // A top-level YAML key starts at column 0 with `name:` style.
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (m) {
+      flush();
+      currentKey = m[1];
+      const inlineValue = m[2].trim();
+      // Block scalar markers (>, |, >+, >-, |+, |-) introduce a block
+      // — they aren't part of the value themselves, so don't push them.
+      if (inlineValue && !/^[>|][+-]?$/.test(inlineValue)) {
+        buffer.push(inlineValue);
+      }
+    } else if (currentKey) {
+      // Continuation line for the active block scalar. Indentation and
+      // blank lines are folded into a single space by `flush()`.
+      buffer.push(line.trim());
+    }
+  }
+  flush();
+
+  return {
+    name: fields.name || null,
+    description: fields.description || '',
+    body,
+  };
+}
+
 // Transform SKILL.md → .mdc for Cursor / Windsurf.
 // Other files (references/, templates/) are copied as-is.
 function skillToMdc(srcPath, destPath) {
@@ -238,90 +408,39 @@ function skillToMdc(srcPath, destPath) {
     return { destPath, content: fs.readFileSync(srcPath) };
   }
   const content = fs.readFileSync(srcPath, 'utf8');
-  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
-  let frontmatter = '';
-  let body = content;
-  if (fmMatch) {
-    frontmatter = fmMatch[1];
-    body = fmMatch[2];
-  }
-  const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
-  // description is usually a multi-line block with `description: >`
-  const descMatch = frontmatter.match(/description:\s*>\s*\r?\n([\s\S]*?)(?:\r?\n\w|$)/);
-  const descInlineMatch = frontmatter.match(/^description:\s*(.+)$/m);
-  const ruleName = nameMatch ? nameMatch[1].trim() : path.basename(path.dirname(srcPath));
-  const rawDesc = descMatch ? descMatch[1] : (descInlineMatch ? descInlineMatch[1] : '');
-  const ruleDesc = rawDesc.replace(/\s+/g, ' ').trim();
-  const mdcFrontmatter = `---\ndescription: ${ruleDesc}\nalwaysApply: false\n---\n\n`;
+  const { name, description, body } = parseSkillFrontmatter(content);
+  const ruleName = name || path.basename(path.dirname(srcPath));
+  const mdcFrontmatter = `---\ndescription: ${description}\nalwaysApply: false\n---\n\n`;
   const newDestPath = path.join(path.dirname(destPath), `${ruleName}.mdc`);
   return { destPath: newDestPath, content: mdcFrontmatter + body };
 }
 
-// MAINTENANCE: when adding a new skill, update BOTH tables below.
+// Path to the AGENTS.md template file. Lives next to the rest of the
+// reference templates so the convention stays uniform: anything that
+// looks like generated artifact content lives in
+// skills/references/templates/, not embedded as a string in the CLI.
+//
+// MAINTENANCE: when adding a new skill, update both tables in
+// agents-template.md:
 // - 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
-
-> Auto-generated by \`ba-toolkit init\` on ${today()}. Updated automatically by /brief and /srs.
-
-## Active Project
-
-**Project:** ${name}
-**Slug:** ${slug}
-**Domain:** ${domain}
-**Language:** English
-**Output folder:** output/${slug}/
-
-## Pipeline Status
-
-| Stage | Skill | Status | File |
-|-------|-------|--------|------|
-| 0 | /principles | ⬜ Not started | — |
-| 1 | /brief | ⬜ Not started | — |
-| 2 | /srs | ⬜ Not started | — |
-| 3 | /stories | ⬜ Not started | — |
-| 4 | /usecases | ⬜ Not started | — |
-| 5 | /ac | ⬜ Not started | — |
-| 6 | /nfr | ⬜ Not started | — |
-| 7 | /datadict | ⬜ Not started | — |
-| 7a | /research | ⬜ Not started | — |
-| 8 | /apicontract | ⬜ Not started | — |
-| 9 | /wireframes | ⬜ Not started | — |
-| 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}
-- (Add constraints after /brief completes)
+// 21-skill list and ordering; keep that template in sync with it.
+const AGENTS_TEMPLATE_PATH = path.join(SKILLS_DIR, 'references', 'templates', 'agents-template.md');
 
-## Key Stakeholder Roles
-
-- (Populated after /srs completes)
-
-## Open Questions
-
-- (None yet)
-`;
+function renderAgentsMd({ name, slug, domain }) {
+  let template;
+  try {
+    template = fs.readFileSync(AGENTS_TEMPLATE_PATH, 'utf8');
+  } catch (err) {
+    throw new Error(`Failed to read AGENTS.md template at ${AGENTS_TEMPLATE_PATH}: ${err.message}`);
+  }
+  return template
+    .replace(/\[NAME\]/g, name)
+    .replace(/\[SLUG\]/g, slug)
+    .replace(/\[DOMAIN\]/g, domain)
+    .replace(/\[DATE\]/g, today());
 }
 
 // --- Commands ----------------------------------------------------------
@@ -333,8 +452,8 @@ async function cmdInit(args) {
   log('');
 
   // --- 1. Project name (slug derives from it) ---
-  const nameFromFlag = !!(args.flags.name && args.flags.name !== true);
-  let name = nameFromFlag ? args.flags.name : null;
+  const nameFlag = stringFlag(args, 'name');
+  let name = nameFlag;
   if (!name) name = await prompt('  Project name (e.g. My App): ');
   name = String(name || '').trim();
   if (!name) {
@@ -344,11 +463,11 @@ async function cmdInit(args) {
 
   // --- 2. Slug (auto-derived from name; confirmed interactively unless
   //     both --name and --slug were passed on the command line) ---
-  const slugFromFlag = !!(args.flags.slug && args.flags.slug !== true);
-  let slug = slugFromFlag ? args.flags.slug : null;
+  const slugFlag = stringFlag(args, 'slug');
+  let slug = slugFlag;
   if (!slug) {
     const derived = sanitiseSlug(name);
-    if (nameFromFlag) {
+    if (nameFlag) {
       // 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
@@ -375,20 +494,22 @@ async function cmdInit(args) {
   }
 
   // --- 3. Domain (numbered menu) ---
-  let domain = args.flags.domain;
-  if (domain && domain !== true) {
-    domain = resolveDomain(String(domain));
+  const domainFlag = stringFlag(args, 'domain');
+  let domain;
+  if (domainFlag) {
+    domain = resolveDomain(domainFlag);
     if (!domain) {
-      logError(`Unknown domain: ${args.flags.domain}`);
+      logError(`Unknown domain: ${domainFlag}`);
       log('Valid ids: ' + DOMAINS.map((d) => d.id).join(', '));
       process.exit(1);
     }
   } else {
     log('');
     log('  ' + yellow('Pick a domain:'));
+    const domainNameWidth = Math.max(...DOMAINS.map((d) => d.name.length));
     DOMAINS.forEach((d, i) => {
       const idx = String(i + 1).padStart(2);
-      log(`    ${idx}) ${bold(d.name.padEnd(13))} ${gray('— ' + d.desc)}`);
+      log(`    ${idx}) ${bold(d.name.padEnd(domainNameWidth))} ${gray('— ' + d.desc)}`);
     });
     log('');
     const raw = await prompt(`  Select [1-${DOMAINS.length}]: `);
@@ -401,12 +522,13 @@ async function cmdInit(args) {
 
   // --- 4. Agent (numbered menu), unless --no-install ---
   const skipInstall = !!args.flags['no-install'];
-  let agentId = args.flags.for;
+  const forFlag = stringFlag(args, 'for');
+  let agentId = null;
   if (!skipInstall) {
-    if (agentId && agentId !== true) {
-      agentId = resolveAgent(String(agentId));
+    if (forFlag) {
+      agentId = resolveAgent(forFlag);
       if (!agentId) {
-        logError(`Unknown agent: ${args.flags.for}`);
+        logError(`Unknown agent: ${forFlag}`);
         log('Supported: ' + Object.keys(AGENTS).join(', '));
         process.exit(1);
       }
@@ -414,9 +536,10 @@ async function cmdInit(args) {
       log('');
       log('  ' + yellow('Pick your AI agent:'));
       const agentEntries = Object.entries(AGENTS);
+      const agentNameWidth = Math.max(...agentEntries.map(([, a]) => a.name.length));
       agentEntries.forEach(([id, a], i) => {
         const idx = String(i + 1).padStart(2);
-        log(`    ${idx}) ${bold(a.name.padEnd(20))} ${gray('(' + id + ')')}`);
+        log(`    ${idx}) ${bold(a.name.padEnd(agentNameWidth))} ${gray('(' + id + ')')}`);
       });
       log('');
       const raw = await prompt(`  Select [1-${agentEntries.length}]: `);
@@ -497,10 +620,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}`);
@@ -538,7 +690,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.');
@@ -555,6 +707,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.'));
@@ -563,8 +719,8 @@ async function runInstall({ agentId, isGlobal, isProject, dryRun, showHeader = t
 }
 
 async function cmdInstall(args) {
-  const agentId = args.flags.for;
-  if (!agentId || agentId === true) {
+  const agentId = stringFlag(args, 'for');
+  if (!agentId) {
     logError('--for <agent> is required.');
     log('Supported agents: ' + Object.keys(AGENTS).join(', '));
     process.exit(1);
@@ -584,6 +740,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 = stringFlag(args, 'for');
+  if (!agentId) {
+    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 = stringFlag(args, 'for');
+  if (!agentId) {
+    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
 
@@ -597,25 +1018,37 @@ ${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.
-
-${bold('INIT OPTIONS')}
-  --name <name>                  Skip the project name prompt
-  --slug <slug>                  Skip the slug prompt (auto-derived from name)
-  --domain <id>                  Skip the domain menu (e.g. saas, fintech)
-  --for <agent>                  Skip the agent menu (e.g. claude-code)
-  --no-install                   Create the project structure only; don't
-                                 install skills. Useful for CI or when you
-                                 want to pick the agent later.
-  --global                       Install agent skills user-wide
-  --project                      Install agent skills project-level (default
-                                 when the agent supports it)
-  --dry-run                      Preview the install step without writing
-
-${bold('INSTALL OPTIONS')}
-  --for <agent>                  One of: ${Object.keys(AGENTS).join(', ')}
-  --global                       User-wide install
-  --project                      Project-level install (default when supported)
-  --dry-run                      Preview without writing files
+  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('OPTIONS')}
+  --name <name>                  init only — skip the project name prompt
+  --slug <slug>                  init only — skip the slug prompt (auto-derived
+                                 from name)
+  --domain <id>                  init only — skip the domain menu
+                                 (e.g. saas, fintech)
+  --no-install                   init only — create the project structure
+                                 without installing skills (useful for CI)
+  --for <agent>                  install/uninstall/upgrade — pick the target
+                                 agent. One of: ${Object.keys(AGENTS).join(', ')}.
+                                 init also accepts this to skip the agent menu.
+  --global                       install/uninstall/upgrade — target the
+                                 user-wide install
+  --project                      install/uninstall/upgrade — target the
+                                 project-level install (default when the
+                                 agent supports it)
+  --dry-run                      init/install/uninstall/upgrade — preview
+                                 without writing or removing files
 
 ${bold('GENERAL OPTIONS')}
   --version, -v                  Print version and exit
@@ -635,6 +1068,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
 `);
@@ -644,6 +1089,7 @@ ${bold('LEARN MORE')}
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  validateFlags(args);
 
   if (args.flags.version || args.flags.v) {
     log(PKG.version);
@@ -663,6 +1109,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;
@@ -673,26 +1129,49 @@ async function main() {
   }
 }
 
-// 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) => {
+// Exports for tests. Pure functions only — anything that prompts or
+// touches the filesystem stays internal. The bin file is still
+// runnable as a CLI; the `require.main === module` guard below
+// prevents `main()` from firing when the file is loaded as a module
+// from the test runner.
+module.exports = {
+  sanitiseSlug,
+  parseArgs,
+  resolveDomain,
+  resolveAgent,
+  stringFlag,
+  levenshtein,
+  closestMatch,
+  parseSkillFrontmatter,
+  readSentinel,
+  renderAgentsMd,
+  KNOWN_FLAGS,
+  DOMAINS,
+  AGENTS,
+};
+
+if (require.main === module) {
+  // 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();
-    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);
+    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.2",
+  "version": "1.5.0",
   "description": "AI-powered Business Analyst pipeline — 21 skills from project brief to development handoff. Works with Claude Code, Codex CLI, Gemini CLI, Cursor, and Windsurf.",
   "keywords": [
     "business-analyst",
@@ -43,6 +43,6 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node bin/ba-toolkit.js --help > /dev/null && echo CLI smoke test passed"
+    "test": "node --test test/cli.test.js"
   }
 }

package/skills/references/templates/agents-template.md

@@ -0,0 +1,57 @@
+# BA Toolkit — Project Context
+
+> Auto-generated by `ba-toolkit init` on [DATE]. Updated automatically by /brief and /srs.
+
+## Active Project
+
+**Project:** [NAME]
+**Slug:** [SLUG]
+**Domain:** [DOMAIN]
+**Language:** English
+**Output folder:** output/[SLUG]/
+
+## Pipeline Status
+
+| Stage | Skill | Status | File |
+|-------|-------|--------|------|
+| 0 | /principles | ⬜ Not started | — |
+| 1 | /brief | ⬜ Not started | — |
+| 2 | /srs | ⬜ Not started | — |
+| 3 | /stories | ⬜ Not started | — |
+| 4 | /usecases | ⬜ Not started | — |
+| 5 | /ac | ⬜ Not started | — |
+| 6 | /nfr | ⬜ Not started | — |
+| 7 | /datadict | ⬜ Not started | — |
+| 7a | /research | ⬜ Not started | — |
+| 8 | /apicontract | ⬜ Not started | — |
+| 9 | /wireframes | ⬜ Not started | — |
+| 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]
+- (Add constraints after /brief completes)
+
+## Key Stakeholder Roles
+
+- (Populated after /srs completes)
+
+## Open Questions
+
+- (None yet)