bmad-method 6.0.0-alpha.14 → 6.0.0-alpha.15

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', '.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, '_cfg', '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 };

package/docs/custom-agent-installation.md

@@ -1,137 +0,0 @@
-# Custom Agent Installation
-
-BMAD agents and workflows are now installed through the main CLI installer using a `custom.yaml` configuration file or by having an installer file.
-
-## Quick Start
-
-Create a `custom.yaml` file in the root of your agent/workflow folder:
-
-```yaml
-code: my-custom-agent
-name: 'My Custom Agent'
-default_selected: true
-```
-
-Then run the BMAD installer from your project directory:
-
-```bash
-npx bmad-method install
-```
-
-Or if you have bmad-cli installed globally:
-
-```bash
-bmad install
-```
-
-## Installation Methods
-
-### Method 1: Stand-alone Folder with custom.yaml
-
-Place your agent or workflow in a folder with a `custom.yaml` file at the root:
-
-```
-my-agent/
-├── custom.yaml      # Required configuration file
-├── my-agent.agent.yaml
-└── sidecar/         # Optional
-    └── instructions.md
-```
-
-### Method 2: Installer File
-
-For more complex installations, include an `installer.js` or `installer.yaml` file in your agent/workflow folder:
-
-```
-my-workflow/
-├── workflow.md
-└── installer.yaml   # Custom installation logic
-```
-
-## What It Does
-
-1. **Discovers** available agents and workflows from folders with `custom.yaml`
-2. **Installs** to your project's `.bmad/custom/` directory
-3. **Creates** IDE commands for all your configured IDEs (Claude Code, Codex, Cursor, etc.)
-4. **Registers** the agent/workflow in the BMAD system
-
-## Example custom.yaml
-
-```yaml
-code: my-custom-agent
-name: 'My Custom Agent'
-default_selected: true
-```
-
-## Installing Reference Agents
-
-The BMAD source includes example agents you can install. **You must copy them to your project first.**
-
-### Step 1: Copy the Agent Template
-
-**For simple agents** (single file):
-
-```bash
-# From your project root
-mkdir -p .bmad/custom/agents/my-agent
-cp node_modules/bmad-method/src/modules/bmb/reference/agents/stand-alone/commit-poet.agent.yaml \
-   .bmad/custom/agents/my-agent/
-```
-
-**For expert agents** (folder with sidecar files):
-
-```bash
-# Copy the entire folder
-cp -r node_modules/bmad-method/src/modules/bmb/reference/agents/agent-with-memory/journal-keeper \
-   .bmad/custom/agents/
-```
-
-### Step 2: Create custom.yaml
-
-```bash
-# In the agent folder, create custom.yaml
-cat > .bmad/custom/agents/my-agent/custom.yaml << EOF
-code: my-agent
-name: "My Custom Agent"
-default_selected: true
-EOF
-```
-
-### Step 3: Install
-
-```bash
-npx bmad-method install
-# or: bmad install (if BMAD installed locally)
-```
-
-The installer will:
-
-1. Find the agent with its `custom.yaml`
-2. Install it to the appropriate location
-3. Create IDE commands for immediate use
-
-### Available Reference Agents
-
-**Simple (standalone file):**
-
-- `commit-poet.agent.yaml` - Commit message artisan with style preferences
-
-**Expert (folder with sidecar):**
-
-- `journal-keeper/` - Personal journal companion with memory and pattern recognition
-
-Find these in the BMAD source:
-
-```
-src/modules/bmb/reference/agents/
-├── stand-alone/
-│   └── commit-poet.agent.yaml
-└── agent-with-memory/
-    └── journal-keeper/
-        ├── journal-keeper.agent.yaml
-        └── journal-keeper-sidecar/
-```
-
-## Creating Your Own
-
-Use the BMB agent builder to craft your agents. Once ready to use, place your `.agent.yaml` files or folders with `custom.yaml` in `.bmad/custom/agents/` or `.bmad/custom/workflows/`.