bmad-method 5.1.3 → 6.0.0-Beta.0

package/tools/format-workflow-md.js

@@ -0,0 +1,263 @@
+/**
+ * BMAD Workflow Markdown Formatter
+ *
+ * Formats mixed markdown + XML workflow instruction files with:
+ * - 2-space XML indentation
+ * - Preserved markdown content
+ * - Proper tag nesting
+ * - Consistent formatting
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class WorkflowFormatter {
+  constructor(options = {}) {
+    this.indentSize = options.indentSize || 2;
+    this.preserveMarkdown = options.preserveMarkdown !== false;
+    this.verbose = options.verbose || false;
+  }
+
+  /**
+   * Format a workflow markdown file
+   */
+  format(filePath) {
+    if (this.verbose) {
+      console.log(`Formatting: ${filePath}`);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const formatted = this.formatContent(content);
+
+    // Only write if content changed
+    if (content === formatted) {
+      if (this.verbose) {
+        console.log(`- No changes: ${filePath}`);
+      }
+      return false;
+    } else {
+      fs.writeFileSync(filePath, formatted, 'utf8');
+      if (this.verbose) {
+        console.log(`✓ Formatted: ${filePath}`);
+      }
+      return true;
+    }
+  }
+
+  /**
+   * Format content string with stateful indentation tracking
+   */
+  formatContent(content) {
+    const lines = content.split('\n');
+    const formatted = [];
+    let indentLevel = 0;
+    let inCodeBlock = false;
+    let checkBlockDepth = 0; // Track nested check blocks
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      // Track code blocks (don't format inside them)
+      if (trimmed.startsWith('```')) {
+        if (inCodeBlock) {
+          inCodeBlock = false;
+        } else {
+          inCodeBlock = true;
+        }
+        formatted.push(line);
+        continue;
+      }
+
+      // Don't format inside code blocks
+      if (inCodeBlock) {
+        formatted.push(line);
+        continue;
+      }
+
+      // Handle XML tags
+      if (this.isXMLLine(trimmed)) {
+        const result = this.formatXMLLine(trimmed, indentLevel, checkBlockDepth, i, lines);
+        formatted.push(result.line);
+        indentLevel = result.nextIndent;
+        checkBlockDepth = result.nextCheckDepth;
+      } else if (trimmed === '') {
+        // Preserve blank lines
+        formatted.push('');
+      } else {
+        // Markdown content - preserve as-is but maintain current indent if inside XML
+        formatted.push(line);
+      }
+    }
+
+    return formatted.join('\n');
+  }
+
+  /**
+   * Check if line contains XML tag
+   */
+  isXMLLine(line) {
+    return /^<[a-zA-Z-]+(\s|>|\/)/.test(line) || /^<\/[a-zA-Z-]+>/.test(line);
+  }
+
+  /**
+   * Format a single XML line with context awareness
+   */
+  formatXMLLine(line, currentIndent, checkDepth, lineIndex, allLines) {
+    const trimmed = line.trim();
+    let indent = currentIndent;
+    let nextIndent = currentIndent;
+    let nextCheckDepth = checkDepth;
+
+    // Get the tag name
+    const tagMatch = trimmed.match(/^<\/?([a-zA-Z-]+)/);
+    const tagName = tagMatch ? tagMatch[1] : '';
+
+    // Closing tag - decrease indent before this line
+    if (trimmed.startsWith('</')) {
+      indent = Math.max(0, currentIndent - 1);
+      nextIndent = indent;
+
+      // If closing a step, reset check depth
+      if (tagName === 'step' || tagName === 'workflow') {
+        nextCheckDepth = 0;
+      }
+    }
+    // Self-closing tags (opens and closes on same line)
+    // EXCEPT <check> tags which create logical blocks
+    else if (this.isSelfClosingTag(trimmed) && tagName !== 'check') {
+      // These don't change indent level
+      indent = currentIndent;
+      nextIndent = currentIndent;
+    }
+    // Opening tags
+    else if (trimmed.startsWith('<')) {
+      // Check if this is a <check> tag - these create logical blocks
+      if (tagName === 'check') {
+        indent = currentIndent;
+        // Check tags increase indent for following content
+        nextIndent = currentIndent + 1;
+        nextCheckDepth = checkDepth + 1;
+      }
+      // <action> tags inside check blocks stay at current indent
+      else if (tagName === 'action' && checkDepth > 0) {
+        indent = currentIndent;
+        nextIndent = currentIndent; // Don't increase further
+      }
+      // Other tags close check blocks and return to structural level
+      else if (checkDepth > 0) {
+        // Close all check blocks - return to base structural level
+        indent = Math.max(0, currentIndent - checkDepth);
+        nextIndent = indent + 1;
+        nextCheckDepth = 0;
+      }
+      // Regular opening tags (no check blocks active)
+      else {
+        indent = currentIndent;
+        nextIndent = currentIndent + 1;
+      }
+    }
+
+    const indentStr = ' '.repeat(indent * this.indentSize);
+    return {
+      line: indentStr + trimmed,
+      nextIndent: nextIndent,
+      nextCheckDepth: nextCheckDepth,
+    };
+  }
+
+  /**
+   * Check if tag opens and closes on same line
+   */
+  isSelfClosingTag(line) {
+    // Self-closing with />
+    if (line.endsWith('/>')) {
+      return true;
+    }
+    // Opens and closes on same line: <tag>content</tag>
+    const match = line.match(/^<([a-zA-Z-]+)(\s[^>]*)?>.*<\/\1>$/);
+    return match !== null;
+  }
+
+  /**
+   * Check if tag is a block-level structural tag
+   */
+  isBlockLevelTag(tagName) {
+    return ['step', 'workflow', 'check'].includes(tagName);
+  }
+}
+
+/**
+ * CLI Entry Point
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(`
+BMAD Workflow Markdown Formatter
+
+Usage:
+  node format-workflow-md.js <file-pattern> [options]
+
+Options:
+  --verbose, -v     Verbose output
+  --check, -c       Check formatting without writing (exit 1 if changes needed)
+  --help, -h        Show this help
+
+Examples:
+  node format-workflow-md.js src/**/instructions.md
+  node format-workflow-md.js "src/modules/bmb/**/*.md" --verbose
+  node format-workflow-md.js file.md --check
+`);
+    process.exit(0);
+  }
+
+  const verbose = args.includes('--verbose') || args.includes('-v');
+  const check = args.includes('--check') || args.includes('-c');
+
+  // Remove flags from args
+  const files = args.filter((arg) => !arg.startsWith('-'));
+
+  const formatter = new WorkflowFormatter({ verbose });
+  let hasChanges = false;
+  let formattedCount = 0;
+
+  // Process files
+  for (const pattern of files) {
+    // For now, treat as direct file path
+    // TODO: Add glob support for patterns
+    if (fs.existsSync(pattern)) {
+      const stat = fs.statSync(pattern);
+      if (stat.isFile()) {
+        const changed = formatter.format(pattern);
+        if (changed) {
+          hasChanges = true;
+          formattedCount++;
+        }
+      } else if (stat.isDirectory()) {
+        console.error(`Error: ${pattern} is a directory. Please specify file paths.`);
+      }
+    } else {
+      console.error(`Error: File not found: ${pattern}`);
+    }
+  }
+
+  if (verbose || formattedCount > 0) {
+    console.log(`\nFormatted ${formattedCount} file(s)`);
+  }
+
+  if (check && hasChanges) {
+    console.error('\n❌ Some files need formatting. Run without --check to format.');
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { WorkflowFormatter };

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>

package/tools/migrate-custom-module-paths.js

@@ -0,0 +1,124 @@
+/**
+ * Migration script to convert relative paths to absolute paths in custom module manifests
+ * This should be run once to update existing installations
+ */
+
+const fs = require('fs-extra');
+const path = require('node:path');
+const yaml = require('yaml');
+const chalk = require('chalk');
+
+/**
+ * Find BMAD directory in project
+ */
+function findBmadDir(projectDir = process.cwd()) {
+  const possibleNames = ['_bmad'];
+
+  for (const name of possibleNames) {
+    const bmadDir = path.join(projectDir, name);
+    if (fs.existsSync(bmadDir)) {
+      return bmadDir;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Update manifest to use absolute paths
+ */
+async function updateManifest(manifestPath, projectRoot) {
+  console.log(chalk.cyan(`\nUpdating manifest: ${manifestPath}`));
+
+  const content = await fs.readFile(manifestPath, 'utf8');
+  const manifest = yaml.parse(content);
+
+  if (!manifest.customModules || manifest.customModules.length === 0) {
+    console.log(chalk.dim('  No custom modules found'));
+    return false;
+  }
+
+  let updated = false;
+
+  for (const customModule of manifest.customModules) {
+    if (customModule.relativePath && !customModule.sourcePath) {
+      // Convert relative path to absolute
+      const absolutePath = path.resolve(projectRoot, customModule.relativePath);
+      customModule.sourcePath = absolutePath;
+
+      // Remove the old relativePath
+      delete customModule.relativePath;
+
+      console.log(chalk.green(`  ✓ Updated ${customModule.id}: ${customModule.relativePath} → ${absolutePath}`));
+      updated = true;
+    } else if (customModule.sourcePath && !path.isAbsolute(customModule.sourcePath)) {
+      // Source path exists but is not absolute
+      const absolutePath = path.resolve(customModule.sourcePath);
+      customModule.sourcePath = absolutePath;
+
+      console.log(chalk.green(`  ✓ Updated ${customModule.id}: ${customModule.sourcePath} → ${absolutePath}`));
+      updated = true;
+    }
+  }
+
+  if (updated) {
+    // Write back the updated manifest
+    const yamlStr = yaml.dump(manifest, {
+      indent: 2,
+      lineWidth: -1,
+      noRefs: true,
+      sortKeys: false,
+    });
+
+    await fs.writeFile(manifestPath, yamlStr);
+    console.log(chalk.green('  Manifest updated successfully'));
+  } else {
+    console.log(chalk.dim('  All paths already absolute'));
+  }
+
+  return updated;
+}
+
+/**
+ * Main migration function
+ */
+async function migrate(directory) {
+  const projectRoot = path.resolve(directory || process.cwd());
+  const bmadDir = findBmadDir(projectRoot);
+
+  if (!bmadDir) {
+    console.error(chalk.red('✗ No BMAD installation found in directory'));
+    process.exit(1);
+  }
+
+  console.log(chalk.blue.bold('🔄 BMAD Custom Module Path Migration'));
+  console.log(chalk.dim(`Project: ${projectRoot}`));
+  console.log(chalk.dim(`BMAD Directory: ${bmadDir}`));
+
+  const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
+
+  if (!fs.existsSync(manifestPath)) {
+    console.error(chalk.red('✗ No manifest.yaml found'));
+    process.exit(1);
+  }
+
+  const updated = await updateManifest(manifestPath, projectRoot);
+
+  if (updated) {
+    console.log(chalk.green.bold('\n✨ Migration completed successfully!'));
+    console.log(chalk.dim('Custom modules now use absolute source paths.'));
+  } else {
+    console.log(chalk.yellow('\n⚠ No migration needed - paths already absolute'));
+  }
+}
+
+// Run migration if called directly
+if (require.main === module) {
+  const directory = process.argv[2];
+  migrate(directory).catch((error) => {
+    console.error(chalk.red('\n✗ Migration failed:'), error.message);
+    process.exit(1);
+  });
+}
+
+module.exports = { migrate };