@kudusov.takhir/ba-toolkit 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -11,6 +11,33 @@ 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
@@ -267,7 +294,8 @@ CI scripts that relied on the old behaviour (`init` creates files only, `install
 
 ---
 
-[Unreleased]: https://github.com/TakhirKudusov/ba-toolkit/compare/v1.4.0...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

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.
+// 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');
 
-| 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)
-`;
+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}]: `);
@@ -596,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);
@@ -726,8 +849,8 @@ function cmdStatus() {
 }
 
 async function cmdUpgrade(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);
@@ -813,8 +936,8 @@ async function cmdUpgrade(args) {
 }
 
 async function cmdUninstall(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);
@@ -908,38 +1031,24 @@ ${bold('COMMANDS')}
                                  report which versions are installed where.
                                  Read-only; no flags.
 
-${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
-
-${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('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
@@ -980,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);
@@ -1019,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.4.0",
+  "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)