bmad-method 6.0.0-alpha.8 → 6.0.1

package/tools/fix-doc-links.js

@@ -0,0 +1,285 @@
+/**
+ * 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');
+
+// Match all markdown links; filtering (external, anchors, assets) happens in convertToRepoRelative.
+// This intentionally matches broadly so the handler can make context-aware decisions.
+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 (including protocol-relative URLs like //cdn.example.com)
+  if (href.includes('://') || href.startsWith('//') || 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/lib/xml-utils.js

@@ -0,0 +1,13 @@
+/**
+ * Escape XML special characters in a string
+ * @param {string} text - The text to escape
+ * @returns {string} The escaped text
+ */
+function escapeXml(text) {
+  if (!text) return '';
+  return text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+
+module.exports = {
+  escapeXml,
+};

package/tools/maintainer/review-pr-README.md

@@ -0,0 +1,55 @@
+# Raven's Verdict - Deep PR Review Tool
+
+Adversarial code review for GitHub PRs. Works with any LLM agent.
+
+> **Status: Experimental.** We're still figuring out how to use this effectively. Expect the workflow to evolve.
+
+## How It Works
+
+Point your agent at `review-pr.md` and ask it to review a specific PR:
+
+> "Read tools/maintainer/review-pr.md and apply it to PR #123"
+
+The tool will:
+
+1. Check out the PR branch locally
+2. Run an adversarial review (find at least 5 issues)
+3. Transform findings into professional tone
+4. Preview the review and ask before posting
+
+See `review-pr.md` for full prompt structure, severity ratings, and sandboxing rules.
+
+## When to Use
+
+**Good candidates:**
+
+- PRs with meaningful logic changes
+- Refactors touching multiple files
+- New features or architectural changes
+
+**Skip it for:**
+
+- Trivial PRs (typo fixes, version bumps, single-line changes)
+- PRs you've already reviewed manually
+- PRs where you haven't agreed on the approach yet — fix the direction before the implementation
+
+## Workflow Tips
+
+**Always review before posting.** The preview step exists for a reason:
+
+- **[y] Yes** — Post as-is (only if you're confident)
+- **[e] Edit** — Modify findings before posting
+- **[s] Save only** — Write to file, don't post
+
+The save option is useful when you want to:
+
+- Hand-edit the review before posting
+- Use the findings as input for a second opinion ("Hey Claude, here's what Raven found — what do you think?")
+- Cherry-pick specific findings
+
+**Trust but verify.** LLM reviews can miss context or flag non-issues. Skim the findings before they hit the PR.
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated (`gh auth status`)
+- Any LLM agent capable of running bash commands

package/tools/maintainer/review-pr.md

@@ -0,0 +1,242 @@
+# Raven's Verdict - Deep PR Review Tool
+
+A cynical adversarial review, transformed into cold engineering professionalism.
+
+<orientation>
+CRITICAL: Sandboxed Execution Rules
+
+Before proceeding, you MUST verify:
+
+- [ ] PR number or URL was EXPLICITLY provided in the user's message
+- [ ] You are NOT inferring the PR from conversation history
+- [ ] You are NOT looking at git branches, recent commits, or local state
+- [ ] You are NOT guessing or assuming any PR numbers
+
+**If no explicit PR number/URL was provided, STOP immediately and ask:**
+"What PR number or URL should I review?"
+</orientation>
+
+<preflight-checks>
+
+## Preflight Checks
+
+### 0.1 Parse PR Input
+
+Extract PR number from user input. Examples of valid formats:
+
+- `123` (just the number)
+- `#123` (with hash)
+- `https://github.com/owner/repo/pull/123` (full URL)
+
+If a URL specifies a different repository than the current one:
+
+```bash
+# Check current repo
+gh repo view --json nameWithOwner -q '.nameWithOwner'
+```
+
+If mismatch detected, ask user:
+
+> "This PR is from `{detected_repo}` but we're in `{current_repo}`. Proceed with reviewing `{detected_repo}#123`? (y/n)"
+
+If user confirms, store `{REPO}` for use in all subsequent `gh` commands.
+
+### 0.2 Ensure Clean Checkout
+
+Verify the working tree is clean and check out the PR branch.
+
+```bash
+# Check for uncommitted changes
+git status --porcelain
+```
+
+If output is non-empty, STOP and tell user:
+
+> "You have uncommitted changes. Please commit or stash them before running a PR review."
+
+If clean, fetch and checkout the PR branch:
+
+```bash
+# Fetch and checkout PR branch
+# For cross-repo PRs, include --repo {REPO}
+gh pr checkout {PR_NUMBER} [--repo {REPO}]
+```
+
+If checkout fails, STOP and report the error.
+
+Now you're on the PR branch with full access to all files as they exist in the PR.
+
+### 0.3 Check PR Size
+
+```bash
+# For cross-repo PRs, include --repo {REPO}
+gh pr view {PR_NUMBER} [--repo {REPO}] --json additions,deletions,changedFiles -q '{"additions": .additions, "deletions": .deletions, "files": .changedFiles}'
+```
+
+**Size thresholds:**
+
+| Metric        | Warning Threshold |
+| ------------- | ----------------- |
+| Files changed | > 50              |
+| Lines changed | > 5000            |
+
+If thresholds exceeded, ask user:
+
+> "This PR has {X} files and {Y} line changes. That's large.
+>
+> **[f] Focus** - Pick specific files or directories to review
+> **[p] Proceed** - Review everything (may be slow/expensive)
+> **[a] Abort** - Stop here"
+
+### 0.4 Note Binary Files
+
+```bash
+# For cross-repo PRs, include --repo {REPO}
+gh pr diff {PR_NUMBER} [--repo {REPO}] --name-only | grep -E '\.(png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|pdf|zip|tar|gz|bin|exe|dll|so|dylib)$' || echo "No binary files detected"
+```
+
+Store list of binary files to skip. Note them in final output.
+
+</preflight-checks>
+
+<adversarial-review>
+
+### 1.1 Run Cynical Review
+
+**INTERNAL PERSONA - Never post this directly:**
+
+Task: You are a cynical, jaded code reviewer with zero patience for sloppy work. This PR was submitted by a clueless weasel and you expect to find problems. Find at least five issues to fix or improve in it. Number them. Be skeptical of everything. Ultrathink.
+
+Output format:
+
+```markdown
+### [NUMBER]. [FINDING TITLE] [likely]
+
+**Severity:** [EMOJI] [LEVEL]
+
+[DESCRIPTION - be specific, include file:line references]
+```
+
+Severity scale:
+
+| Level    | Emoji | Meaning                                                 |
+| -------- | ----- | ------------------------------------------------------- |
+| Critical | 🔴    | Security issue, data loss risk, or broken functionality |
+| Moderate | 🟡    | Bug, performance issue, or significant code smell       |
+| Minor    | 🟢    | Style, naming, minor improvement opportunity            |
+
+Likely tag:
+
+- Add `[likely]` to findings with high confidence, e.g. with direct evidence
+- Sort findings by severity (Critical → Moderate → Minor), not by confidence
+
+</adversarial-review>
+
+<tone-transformation>
+
+**Transform the cynical output into cold engineering professionalism.**
+
+**Transformation rules:**
+
+1. Remove all inflammatory language, insults, assumptions about the author
+2. Keep all technical substance, file references, severity ratings and likely tag
+3. Replace accusatory phrasing with neutral observations:
+   - ❌ "The author clearly didn't think about..."
+   - ✅ "This implementation may not account for..."
+4. Preserve skepticism as healthy engineering caution:
+   - ❌ "This will definitely break in production"
+   - ✅ "This pattern has historically caused issues in production environments"
+5. Add the suggested fixes.
+6. Keep suggestions actionable and specific
+
+Output format after transformation:
+
+```markdown
+## PR Review: #{PR_NUMBER}
+
+**Title:** {PR_TITLE}
+**Author:** @{AUTHOR}
+**Branch:** {HEAD} → {BASE}
+
+---
+
+### Findings
+
+[TRANSFORMED FINDINGS HERE]
+
+---
+
+### Summary
+
+**Critical:** {COUNT} | **Moderate:** {COUNT} | **Minor:** {COUNT}
+
+[BINARY_FILES_NOTE if any]
+
+---
+
+_Review generated by Raven's Verdict. LLM-produced analysis - findings may be incorrect or lack context. Verify before acting._
+```
+
+</tone-transformation>
+
+<post-review>
+### 3.1 Preview
+
+Display the complete transformed review to the user.
+
+```
+══════════════════════════════════════════════════════
+PREVIEW - This will be posted to PR #{PR_NUMBER}
+══════════════════════════════════════════════════════
+
+[FULL REVIEW CONTENT]
+
+══════════════════════════════════════════════════════
+```
+
+### 3.2 Confirm
+
+Ask user for explicit confirmation:
+
+> **Ready to post this review to PR #{PR_NUMBER}?**
+>
+> **[y] Yes** - Post as comment
+> **[n] No** - Abort, do not post
+> **[e] Edit** - Let me modify before posting
+> **[s] Save only** - Save locally, don't post
+
+### 3.3 Post or Save
+
+**Write review to a temp file, then post:**
+
+1. Write the review content to a temp file with a unique name (include PR number to avoid collisions)
+2. Post using `gh pr comment {PR_NUMBER} [--repo {REPO}] --body-file {path}`
+3. Delete the temp file after successful post
+
+Do NOT use heredocs or `echo` - Markdown code blocks will break shell parsing. Use your file writing tool instead.
+
+**If auth fails or post fails:**
+
+1. Display error prominently:
+
+   ```
+   ⚠️  FAILED TO POST REVIEW
+   Error: {ERROR_MESSAGE}
+   ```
+
+2. Keep the temp file and tell the user where it is, so they can post manually with:
+   `gh pr comment {PR_NUMBER} [--repo {REPO}] --body-file {path}`
+
+**If save only (s):**
+
+Keep the temp file and inform user of location.
+
+</post-review>
+
+<notes>
+- The "cynical asshole" phase is internal only - never posted
+- Tone transform MUST happen before any external output
+- When in doubt, ask the user - never assume
+- If you're unsure about severity, err toward higher severity
+- If you're unsure about confidence, be honest and use Medium or Low
+</notes>