bmad-elsabro 1.0.0

package/tools/docs/fix-refs.md

@@ -0,0 +1,91 @@
+---
+title: Fix Documentation References
+description: Corrects workflow, agent, and command references in BMad documentation
+---
+
+# Fix Documentation References
+
+## Scope
+
+Fix reference patterns ONLY. Do not modify links, formatting, structure, or other content.
+
+## Purpose
+
+Fix incorrect references to workflows, agents, and commands in BMad documentation files.
+
+## Step 1: Establish Target Audience
+
+Before fixing references, determine who the document is for:
+
+| Audience | Indicators | Style |
+|----------|------------|-------|
+| **Newbies** | tutorials/, getting-started, installation/, "What You'll Learn" | Keep "workflow", include platform hints |
+| **Experienced** | reference/, explanation/ | Drop "workflow", no platform hints |
+| **How-To** | how-to/ | **Ask** — depends on the task |
+
+**How-To guides require judgment**: Don't assume experienced. Ask: "Does this task require prior BMad knowledge?" Early-journey tasks (first PRD, first sprint) are newbie docs. Customization and advanced features are experienced.
+
+**If unclear**: Ask the user "Who is the target audience for this document — new users learning BMad, or experienced users who know the system?"
+
+This determines whether helper words like "workflow" and platform hints are helpful context or just noise.
+
+## Reference Patterns to Fix
+
+### Always Wrong
+
+| Pattern | Example | Problem |
+|---------|---------|---------|
+| `*workflow` | `*prd` | Obsolete menu shortcut notation |
+| `/workflow` | `/workflow-init` | Platform-specific slash command |
+| `bmad_bmm_*` | `bmad_bmm_workflow-init` | Internal slash command name, platform-specific |
+
+### Correct Format
+
+Use backticks with plain workflow name:
+- **Wrong**: Run `/workflow-init`
+- **Wrong**: Run `*prd`
+
+**When to say "workflow"**:
+- **Newbie docs** (getting-started): "Run the `prd` workflow" — helps them learn what it is
+- **Other docs**: "Run `prd`" — they already know, so "workflow" is noise
+
+**Platform hint**: Only in newbie docs, and only on the **first** workflow mention:
+- First mention: Run the `help` workflow (`/bmad-help` on most platforms)
+- Subsequent mentions: Run `prd` — no hint, no "workflow" needed after they've seen the pattern
+
+In experienced docs, the hint is always noise — just use the workflow name.
+
+### Workflow Name Changes
+
+| Old Name | New Name | Notes |
+|----------|----------|-------|
+| `workflow-init` | `bmad-help` | DEPRECATED - help system replaces initialization |
+| `workflow-status` | `bmad-help` | DEPRECATED - help system replaces status checking |
+
+### The Help System
+
+The `bmad-help` workflow is the modern replacement for both `workflow-init` and `workflow-status`:
+- **Universal**: Works regardless of workflow state or module
+- **Contextual**: Infers completion from artifacts and conversation
+- **Adaptive**: Guides users through workflows based on phase ordering
+- **Anytime**: Can be run at any point, no pre-initialization needed
+
+Users can run `bmad-help` to get guidance on what to do next. It detects:
+- What workflows have been completed (by checking for output artifacts)
+- What module is active
+- What the next recommended/required step is
+
+## Lessons Learned
+
+1. **Platform-agnostic**: Docs should never include platform-specific invocation patterns (slashes, prefixes)
+2. **Backtick the name**: Use backticks around workflow names: `workflow-name`
+3. **Simple names**: Just the workflow name, no `bmad_bmm_` prefix, no `/` prefix
+
+## Self-Check
+
+Before finishing, verify you ONLY changed reference patterns:
+
+- [ ] Did I change any hyperlinks? **If yes, revert.**
+- [ ] Did I change any formatting (horizontal rules, whitespace, structure)? **If yes, revert.**
+- [ ] Did I remove or add any sections? **If yes, revert.**
+- [ ] Did I modify anything not matching the patterns in "Reference Patterns to Fix"? **If yes, revert.**

package/tools/docs/index.md

@@ -0,0 +1,2 @@
+# Tool and Repo Maintainability Documentation
+

package/tools/fix-doc-links.js

@@ -0,0 +1,288 @@
+/**
+ * Fix Documentation Links
+ *
+ * Converts relative markdown links to repo-relative paths with .md extension.
+ * This ensures links work both in GitHub and on the Astro/Starlight site
+ * (the rehype plugin transforms /docs/path/file.md → /path/file/ at build time).
+ *
+ * - ./file.md → /docs/current/path/file.md
+ * - ../other/file.md → /docs/resolved/path/file.md
+ * - /path/file/ → /docs/path/file.md (or /docs/path/file/index.md if it's a directory)
+ *
+ * Usage:
+ *   node tools/fix-doc-links.js           # Dry run (shows what would change)
+ *   node tools/fix-doc-links.js --write   # Actually write changes
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DOCS_ROOT = path.resolve(__dirname, '../docs');
+const DRY_RUN = !process.argv.includes('--write');
+
+// Regex to match markdown links:
+// - [text](path.md) or [text](path.md#anchor) - existing .md links
+// - [text](/path/to/page/) or [text](/path/to/page/#anchor) - site-relative links to convert
+const MARKDOWN_LINK_REGEX = /\[([^\]]*)\]\(([^)]+(?:\.md|\/))(?:#[^)]*)?(?:\?[^)]*)?\)/g;
+// Simpler approach: match all markdown links and filter in the handler
+const ALL_MARKDOWN_LINKS_REGEX = /\[([^\]]*)\]\(([^)]+)\)/g;
+
+/**
+ * Get all markdown files in docs directory, excluding _* directories/files
+ */
+function getMarkdownFiles(dir) {
+  const files = [];
+
+  function walk(currentDir) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+
+      // Skip underscore-prefixed entries
+      if (entry.name.startsWith('_')) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+/**
+ * Convert a markdown link href to repo-relative path with .md extension
+ *
+ * @param {string} href - The original href (e.g., "./file.md", "/path/to/page/", "/path/to/page/#anchor")
+ * @param {string} currentFilePath - Absolute path to the file containing this link
+ * @returns {string|null} - Repo-relative path (e.g., "/docs/path/to/file.md"), or null if shouldn't be converted
+ */
+function convertToRepoRelative(href, currentFilePath) {
+  // Skip external links
+  if (href.includes('://') || href.startsWith('mailto:') || href.startsWith('tel:')) {
+    return null;
+  }
+
+  // Skip anchor-only links
+  if (href.startsWith('#')) {
+    return null;
+  }
+
+  // Extract anchor and query string if present
+  let anchor = '';
+  let query = '';
+  let pathPortion = href;
+
+  const hashIndex = href.indexOf('#');
+  const queryIndex = href.indexOf('?');
+
+  if (hashIndex !== -1 || queryIndex !== -1) {
+    const firstDelimiter = Math.min(hashIndex === -1 ? Infinity : hashIndex, queryIndex === -1 ? Infinity : queryIndex);
+    pathPortion = href.slice(0, Math.max(0, firstDelimiter));
+
+    const suffix = href.slice(Math.max(0, firstDelimiter));
+    const anchorInSuffix = suffix.indexOf('#');
+
+    if (suffix.startsWith('?')) {
+      if (anchorInSuffix === -1) {
+        query = suffix;
+      } else {
+        query = suffix.slice(0, Math.max(0, anchorInSuffix));
+        anchor = suffix.slice(Math.max(0, anchorInSuffix));
+      }
+    } else {
+      anchor = suffix;
+    }
+  }
+
+  // Skip non-documentation links (images, external assets, etc.)
+  const ext = path.extname(pathPortion).toLowerCase();
+  if (
+    ext &&
+    ext !== '.md' &&
+    !['.md'].includes(ext) && // Has an extension that's not .md - skip unless it's a trailing slash path
+    !pathPortion.endsWith('/')
+  ) {
+    return null;
+  }
+
+  // Check if original path ends with / (directory reference) BEFORE path.join normalizes it
+  const isDirectoryPath = pathPortion.endsWith('/');
+
+  let absolutePath;
+
+  if (pathPortion.startsWith('/docs/')) {
+    // Already repo-relative with /docs/ prefix
+    absolutePath = path.join(path.dirname(DOCS_ROOT), pathPortion);
+  } else if (pathPortion.startsWith('/')) {
+    // Site-relative (e.g., /tutorials/getting-started/) - resolve from docs root
+    absolutePath = path.join(DOCS_ROOT, pathPortion);
+  } else {
+    // Relative path (./, ../, or bare filename) - resolve from current file's directory
+    const currentDir = path.dirname(currentFilePath);
+    absolutePath = path.resolve(currentDir, pathPortion);
+  }
+
+  // Convert to repo-relative path (with /docs/ prefix)
+  let repoRelative = '/docs/' + path.relative(DOCS_ROOT, absolutePath);
+
+  // Normalize path separators for Windows
+  repoRelative = repoRelative.split(path.sep).join('/');
+
+  // If original path was a directory reference (ended with /), check for index.md or file.md
+  if (isDirectoryPath) {
+    const relativeDir = repoRelative.slice(6); // Remove '/docs/'
+
+    // Handle root path case (relativeDir is empty or just '.')
+    const normalizedDir = relativeDir === '' || relativeDir === '.' ? '' : relativeDir;
+    const indexPath = path.join(DOCS_ROOT, normalizedDir, 'index.md');
+    const filePath = normalizedDir ? path.join(DOCS_ROOT, normalizedDir + '.md') : null;
+
+    if (fs.existsSync(indexPath)) {
+      // Avoid double slash when repoRelative is '/docs/' (root case)
+      repoRelative = repoRelative.endsWith('/') ? repoRelative + 'index.md' : repoRelative + '/index.md';
+    } else if (filePath && fs.existsSync(filePath)) {
+      repoRelative = repoRelative + '.md';
+    } else {
+      // Neither exists - default to index.md and let validation catch it
+      repoRelative = repoRelative.endsWith('/') ? repoRelative + 'index.md' : repoRelative + '/index.md';
+    }
+  } else if (!repoRelative.endsWith('.md')) {
+    // Path doesn't end with .md - add .md
+    repoRelative = repoRelative + '.md';
+  }
+
+  return repoRelative + query + anchor;
+}
+
+/**
+ * Process a single markdown file, skipping links inside fenced code blocks
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {Object} - { changed: boolean, original: string, updated: string, changes: Array }
+ */
+function processFile(filePath) {
+  const original = fs.readFileSync(filePath, 'utf-8');
+  const changes = [];
+
+  // Extract fenced code blocks and replace with placeholders
+  const codeBlocks = [];
+  const CODE_PLACEHOLDER = '\u0000CODE_BLOCK_';
+
+  let contentWithPlaceholders = original.replaceAll(/```[\s\S]*?```/g, (match) => {
+    const index = codeBlocks.length;
+    codeBlocks.push(match);
+    return `${CODE_PLACEHOLDER}${index}\u0000`;
+  });
+
+  // Process links only in non-code-block content
+  contentWithPlaceholders = contentWithPlaceholders.replaceAll(ALL_MARKDOWN_LINKS_REGEX, (match, linkText, href) => {
+    const newHref = convertToRepoRelative(href, filePath);
+
+    // Skip if conversion returned null (external link, anchor, etc.)
+    if (newHref === null) {
+      return match;
+    }
+
+    // Only record as change if actually different
+    if (newHref !== href) {
+      changes.push({ from: href, to: newHref });
+      return `[${linkText}](${newHref})`;
+    }
+
+    return match;
+  });
+
+  // Restore code blocks
+  const updated = contentWithPlaceholders.replaceAll(
+    new RegExp(`${CODE_PLACEHOLDER}(\\d+)\u0000`, 'g'),
+    (match, index) => codeBlocks[parseInt(index, 10)],
+  );
+
+  return {
+    changed: changes.length > 0,
+    original,
+    updated,
+    changes,
+  };
+}
+
+/**
+ * Validate that a repo-relative link points to an existing file
+ */
+function validateLink(repoRelativePath) {
+  // Strip anchor/query
+  const checkPath = repoRelativePath.split('#')[0].split('?')[0];
+
+  // Remove /docs/ prefix to get path relative to DOCS_ROOT
+  const relativePath = checkPath.startsWith('/docs/') ? checkPath.slice(6) : checkPath.slice(1);
+
+  return fs.existsSync(path.join(DOCS_ROOT, relativePath));
+}
+
+// Main execution
+console.log(`\nScanning docs in: ${DOCS_ROOT}`);
+console.log(`Mode: ${DRY_RUN ? 'DRY RUN (use --write to apply changes)' : 'WRITE MODE'}\n`);
+
+const files = getMarkdownFiles(DOCS_ROOT);
+console.log(`Found ${files.length} markdown files (excluding _* paths)\n`);
+
+let totalChanges = 0;
+let filesChanged = 0;
+const brokenLinks = [];
+
+for (const filePath of files) {
+  const relativePath = path.relative(DOCS_ROOT, filePath);
+  const result = processFile(filePath);
+
+  if (result.changed) {
+    filesChanged++;
+    totalChanges += result.changes.length;
+
+    console.log(`\n${relativePath}`);
+    for (const change of result.changes) {
+      const isValid = validateLink(change.to);
+      const status = isValid ? '  ' : '! ';
+
+      console.log(`${status}  ${change.from}`);
+      console.log(`    -> ${change.to}`);
+
+      if (!isValid) {
+        brokenLinks.push({
+          file: relativePath,
+          link: change.to,
+          original: change.from,
+        });
+      }
+    }
+
+    if (!DRY_RUN) {
+      fs.writeFileSync(filePath, result.updated, 'utf-8');
+    }
+  }
+}
+
+console.log(`\n${'─'.repeat(60)}`);
+console.log(`\nSummary:`);
+console.log(`   Files scanned: ${files.length}`);
+console.log(`   Files with changes: ${filesChanged}`);
+console.log(`   Total link updates: ${totalChanges}`);
+
+if (brokenLinks.length > 0) {
+  console.log(`\n!  Potential broken links (${brokenLinks.length}):`);
+  for (const bl of brokenLinks) {
+    console.log(`   ${bl.file}: ${bl.link}`);
+  }
+}
+
+if (DRY_RUN && totalChanges > 0) {
+  console.log(`\nRun with --write to apply these changes`);
+}
+
+console.log('');

package/tools/flattener/aggregate.js

@@ -0,0 +1,76 @@
+const fs = require('fs-extra');
+const path = require('node:path');
+const os = require('node:os');
+const { isBinaryFile } = require('./binary.js');
+
+/**
+ * Aggregate file contents with bounded concurrency.
+ * Returns text files, binary files (with size), and errors.
+ * @param {string[]} files absolute file paths
+ * @param {string} rootDir
+ * @param {{ text?: string, warn?: (msg: string) => void } | null} spinner
+ */
+async function aggregateFileContents(files, rootDir, spinner = null) {
+  const results = {
+    textFiles: [],
+    binaryFiles: [],
+    errors: [],
+    totalFiles: files.length,
+    processedFiles: 0,
+  };
+
+  // Automatic concurrency selection based on CPU count and workload size.
+  // - Base on 2x logical CPUs, clamped to [2, 64]
+  // - For very small workloads, avoid excessive parallelism
+  const cpuCount = os.cpus && Array.isArray(os.cpus()) ? os.cpus().length : os.cpus?.length || 4;
+  let concurrency = Math.min(64, Math.max(2, (Number(cpuCount) || 4) * 2));
+  if (files.length > 0 && files.length < concurrency) {
+    concurrency = Math.max(1, Math.min(concurrency, Math.ceil(files.length / 2)));
+  }
+
+  async function processOne(filePath) {
+    try {
+      const relativePath = path.relative(rootDir, filePath);
+      if (spinner) {
+        spinner.text = `Processing: ${relativePath} (${results.processedFiles + 1}/${results.totalFiles})`;
+      }
+
+      const binary = await isBinaryFile(filePath);
+      if (binary) {
+        const { size } = await fs.stat(filePath);
+        results.binaryFiles.push({ path: relativePath, absolutePath: filePath, size });
+      } else {
+        const content = await fs.readFile(filePath, 'utf8');
+        results.textFiles.push({
+          path: relativePath,
+          absolutePath: filePath,
+          content,
+          size: content.length,
+          lines: content.split('\n').length,
+        });
+      }
+    } catch (error) {
+      const relativePath = path.relative(rootDir, filePath);
+      const errorInfo = { path: relativePath, absolutePath: filePath, error: error.message };
+      results.errors.push(errorInfo);
+      if (spinner) {
+        spinner.warn(`Warning: Could not read file ${relativePath}: ${error.message}`);
+      } else {
+        console.warn(`Warning: Could not read file ${relativePath}: ${error.message}`);
+      }
+    } finally {
+      results.processedFiles++;
+    }
+  }
+
+  for (let index = 0; index < files.length; index += concurrency) {
+    const slice = files.slice(index, index + concurrency);
+    await Promise.all(slice.map(processOne));
+  }
+
+  return results;
+}
+
+module.exports = {
+  aggregateFileContents,
+};

package/tools/flattener/aggregate.ts

@@ -0,0 +1,78 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import os from 'node:os';
+import { isBinaryFile } from './binary.js';
+import type { AggregatedContent, SpinnerInstance } from './types.js';
+
+/**
+ * Aggregate file contents with bounded concurrency.
+ * Returns text files, binary files (with size), and errors.
+ * @param files absolute file paths
+ * @param rootDir
+ * @param spinner Optional spinner instance for progress display
+ */
+export async function aggregateFileContents(
+  files: string[],
+  rootDir: string,
+  spinner: SpinnerInstance = null,
+): Promise<AggregatedContent> {
+  const results: AggregatedContent = {
+    textFiles: [],
+    binaryFiles: [],
+    errors: [],
+    totalFiles: files.length,
+    processedFiles: 0,
+  };
+
+  // Automatic concurrency selection based on CPU count and workload size.
+  // - Base on 2x logical CPUs, clamped to [2, 64]
+  // - For very small workloads, avoid excessive parallelism
+  const cpuCount = os.cpus && Array.isArray(os.cpus()) ? os.cpus().length : os.cpus?.length || 4;
+  let concurrency = Math.min(64, Math.max(2, (Number(cpuCount) || 4) * 2));
+  if (files.length > 0 && files.length < concurrency) {
+    concurrency = Math.max(1, Math.min(concurrency, Math.ceil(files.length / 2)));
+  }
+
+  async function processOne(filePath: string): Promise<void> {
+    try {
+      const relativePath = path.relative(rootDir, filePath);
+      if (spinner) {
+        spinner.text = `Processing: ${relativePath} (${results.processedFiles + 1}/${results.totalFiles})`;
+      }
+
+      const binary = await isBinaryFile(filePath);
+      if (binary) {
+        const { size } = await fs.stat(filePath);
+        results.binaryFiles.push({ path: relativePath, absolutePath: filePath, size });
+      } else {
+        const content = await fs.readFile(filePath, 'utf8');
+        results.textFiles.push({
+          path: relativePath,
+          absolutePath: filePath,
+          content,
+          size: content.length,
+          lines: content.split('\n').length,
+        });
+      }
+    } catch (error) {
+      const relativePath = path.relative(rootDir, filePath);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorInfo = { path: relativePath, absolutePath: filePath, error: errorMessage };
+      results.errors.push(errorInfo);
+      if (spinner) {
+        spinner.warn(`Warning: Could not read file ${relativePath}: ${errorMessage}`);
+      } else {
+        console.warn(`Warning: Could not read file ${relativePath}: ${errorMessage}`);
+      }
+    } finally {
+      results.processedFiles++;
+    }
+  }
+
+  for (let index = 0; index < files.length; index += concurrency) {
+    const slice = files.slice(index, index + concurrency);
+    await Promise.all(slice.map(processOne));
+  }
+
+  return results;
+}

package/tools/flattener/binary.js

@@ -0,0 +1,80 @@
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { Buffer } = require('node:buffer');
+
+/**
+ * Efficiently determine if a file is binary without reading the whole file.
+ * - Fast path by extension for common binaries
+ * - Otherwise read a small prefix and check for NUL bytes
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+async function isBinaryFile(filePath) {
+  try {
+    const stats = await fsp.stat(filePath);
+    if (stats.isDirectory()) {
+      throw new Error('EISDIR: illegal operation on a directory');
+    }
+
+    const binaryExtensions = new Set([
+      '.jpg',
+      '.jpeg',
+      '.png',
+      '.gif',
+      '.bmp',
+      '.ico',
+      '.svg',
+      '.pdf',
+      '.doc',
+      '.docx',
+      '.xls',
+      '.xlsx',
+      '.ppt',
+      '.pptx',
+      '.zip',
+      '.tar',
+      '.gz',
+      '.rar',
+      '.7z',
+      '.exe',
+      '.dll',
+      '.so',
+      '.dylib',
+      '.mp3',
+      '.mp4',
+      '.avi',
+      '.mov',
+      '.wav',
+      '.ttf',
+      '.otf',
+      '.woff',
+      '.woff2',
+      '.bin',
+      '.dat',
+      '.db',
+      '.sqlite',
+    ]);
+
+    const extension = path.extname(filePath).toLowerCase();
+    if (binaryExtensions.has(extension)) return true;
+    if (stats.size === 0) return false;
+
+    const sampleSize = Math.min(4096, stats.size);
+    const fd = await fsp.open(filePath, 'r');
+    try {
+      const buffer = Buffer.allocUnsafe(sampleSize);
+      const { bytesRead } = await fd.read(buffer, 0, sampleSize, 0);
+      const slice = bytesRead === sampleSize ? buffer : buffer.subarray(0, bytesRead);
+      return slice.includes(0);
+    } finally {
+      await fd.close();
+    }
+  } catch (error) {
+    console.warn(`Warning: Could not determine if file is binary: ${filePath} - ${error.message}`);
+    return false;
+  }
+}
+
+module.exports = {
+  isBinaryFile,
+};

package/tools/flattener/discovery.js

@@ -0,0 +1,71 @@
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+const { glob } = require('glob');
+const { loadIgnore } = require('./ignoreRules.js');
+
+const pExecFile = promisify(execFile);
+
+async function isGitRepo(rootDir) {
+  try {
+    const { stdout } = await pExecFile('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: rootDir,
+    });
+    return (
+      String(stdout || '')
+        .toString()
+        .trim() === 'true'
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function gitListFiles(rootDir) {
+  try {
+    const { stdout } = await pExecFile('git', ['ls-files', '-co', '--exclude-standard'], {
+      cwd: rootDir,
+    });
+    return String(stdout || '')
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Discover files under rootDir.
+ * - Prefer git ls-files when available for speed/correctness
+ * - Fallback to glob and apply unified ignore rules
+ * @param {string} rootDir
+ * @param {object} [options]
+ * @param {boolean} [options.preferGit=true]
+ * @returns {Promise<string[]>} absolute file paths
+ */
+async function discoverFiles(rootDir, options = {}) {
+  const { preferGit = true } = options;
+  const { filter } = await loadIgnore(rootDir);
+
+  // Try git first
+  if (preferGit && (await isGitRepo(rootDir))) {
+    const relFiles = await gitListFiles(rootDir);
+    const filteredRel = relFiles.filter((p) => filter(p));
+    return filteredRel.map((p) => path.resolve(rootDir, p));
+  }
+
+  // Glob fallback
+  const globbed = await glob('**/*', {
+    cwd: rootDir,
+    nodir: true,
+    dot: true,
+    follow: false,
+  });
+  const filteredRel = globbed.filter((p) => filter(p));
+  return filteredRel.map((p) => path.resolve(rootDir, p));
+}
+
+module.exports = {
+  discoverFiles,
+};