bmad-method 6.0.0-alpha.9 → 6.0.2

package/.claude/skills/bmad-os-diataxis-style-fix/prompts/instructions.md

@@ -0,0 +1,229 @@
+# Diataxis Style Fixer
+
+Automatically fixes documentation to comply with the Diataxis framework and BMad Method style guide.
+
+## CRITICAL RULES
+
+- **NEVER commit or push changes** — let the user review first
+- **NEVER make destructive edits** — preserve all content, only fix formatting
+- **Use Edit tool** — make targeted fixes, not full file rewrites
+- **Show summary** — after fixing, list all changes made
+
+## Input
+
+Documentation file path or directory to fix. Defaults to `docs/` if not specified.
+
+## Step 1: Understand Diataxis Framework
+
+**Diataxis** is a documentation framework that categorizes content into four types based on two axes:
+
+|                | **Learning** (oriented toward future)                                         | **Doing** (oriented toward present)                                          |
+| -------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| **Practical**  | **Tutorials** — lessons that guide learners through achieving a specific goal | **How-to guides** — step-by-step instructions for solving a specific problem |
+| **Conceptual** | **Explanation** — content that clarifies and describes underlying concepts    | **Reference** — technical descriptions, organized for lookup                 |
+
+**Key principles:**
+- Each document type serves a distinct user need
+- Don't mix types — a tutorial shouldn't explain concepts deeply
+- Focus on the user's goal, not exhaustive coverage
+- Structure follows purpose (tutorials are linear, reference is scannable)
+
+## Step 2: Read the Style Guide
+
+Read the project's style guide at `docs/_STYLE_GUIDE.md` to understand all project-specific conventions.
+
+## Step 3: Detect Document Type
+
+Based on file location, determine the document type:
+
+| Location             | Diataxis Type        |
+| -------------------- | -------------------- |
+| `/docs/tutorials/`   | Tutorial             |
+| `/docs/how-to/`      | How-to guide         |
+| `/docs/explanation/` | Explanation          |
+| `/docs/reference/`   | Reference            |
+| `/docs/glossary/`    | Reference (glossary) |
+
+## Step 4: Find and Fix Issues
+
+For each markdown file, scan for issues and fix them:
+
+### Universal Fixes (All Doc Types)
+
+**Horizontal Rules (`---`)**
+- Remove any `---` outside of YAML frontmatter
+- Replace with `##` section headers or admonitions as appropriate
+
+**`####` Headers**
+- Replace with bold text: `#### Header` → `**Header**`
+- Or convert to admonition if it's a warning/notice
+
+**"Related" or "Next:" Sections**
+- Remove entire section including links
+- The sidebar handles navigation
+
+**Deeply Nested Lists**
+- Break into sections with `##` headers
+- Flatten to max 3 levels
+
+**Code Blocks for Dialogue/Examples**
+- Convert to admonitions:
+  ```
+  :::note[Example]
+  [content]
+  :::
+  ```
+
+**Bold Paragraph Callouts**
+- Convert to admonitions with appropriate type
+
+**Too Many Admonitions**
+- Limit to 1-2 per section (tutorials allow 3-4 per major section)
+- Consolidate related admonitions
+- Remove less critical ones if over limit
+
+**Table Cells / List Items > 2 Sentences**
+- Break into multiple rows/cells
+- Or shorten to 1-2 sentences
+
+**Header Budget Exceeded**
+- Merge related sections
+- Convert some `##` to `###` subsections
+- Goal: 8-12 `##` per doc; 2-3 `###` per section
+
+### Type-Specific Fixes
+
+**Tutorials** (`/docs/tutorials/`)
+- Ensure hook describes outcome in 1-2 sentences
+- Add "What You'll Learn" bullet section if missing
+- Add `:::note[Prerequisites]` if missing
+- Add `:::tip[Quick Path]` TL;DR at top if missing
+- Use tables for phases, commands, agents
+- Add "What You've Accomplished" section if missing
+- Add Quick Reference table if missing
+- Add Common Questions section if missing
+- Add Getting Help section if missing
+- Add `:::tip[Key Takeaways]` at end if missing
+
+**How-To** (`/docs/how-to/`)
+- Ensure hook starts with "Use the `X` workflow to..."
+- Add "When to Use This" with 3-5 bullets if missing
+- Add `:::note[Prerequisites]` if missing
+- Ensure steps are numbered `###` with action verbs
+- Add "What You Get" describing outputs if missing
+
+**Explanation** (`/docs/explanation/`)
+- Ensure hook states what document explains
+- Organize content into scannable `##` sections
+- Add comparison tables for 3+ options
+- Link to how-to guides for procedural questions
+- Limit to 2-3 admonitions per document
+
+**Reference** (`/docs/reference/`)
+- Ensure hook states what document references
+- Ensure structure matches reference type
+- Use consistent item structure throughout
+- Use tables for structured/comparative data
+- Link to explanation docs for conceptual depth
+- Limit to 1-2 admonitions per document
+
+**Glossary** (`/docs/glossary/` or glossary files)
+- Ensure categories as `##` headers
+- Ensure terms in tables (not individual headers)
+- Definitions 1-2 sentences max
+- Bold term names in cells
+
+## Step 5: Apply Fixes
+
+For each file with issues:
+1. Read the file
+2. Use Edit tool for each fix
+3. Track what was changed
+
+## Step 6: Summary
+
+After processing all files, output a summary:
+
+```markdown
+# Style Fixes Applied
+
+**Files processed:** N
+**Files modified:** N
+
+## Changes Made
+
+### `path/to/file.md`
+- Removed horizontal rule at line 45
+- Converted `####` headers to bold text
+- Added `:::tip[Quick Path]` admonition
+- Consolidated 3 admonitions into 2
+
+### `path/to/other.md`
+- Removed "Related:" section
+- Fixed table cell length (broke into 2 rows)
+
+## Review Required
+
+Please review the changes. When satisfied, commit and push as needed.
+```
+
+## Common Patterns
+
+**Converting `####` to bold:**
+```markdown
+#### Important Note
+Some text here.
+```
+→
+```markdown
+**Important Note**
+
+Some text here.
+```
+
+**Removing horizontal rule:**
+```markdown
+Some content above.
+
+---
+
+Some content below.
+```
+→
+```markdown
+Some content above.
+
+## [Descriptive Section Header]
+
+Some content below.
+```
+
+**Converting code block to admonition:**
+```markdown
+```
+User: What should I do?
+
+Agent: Run the workflow.
+```
+```
+→
+```markdown
+:::note[Example]
+
+**User:** What should I do?
+
+**Agent:** Run the workflow.
+
+:::
+```
+
+**Converting bold paragraph to admonition:**
+```markdown
+**IMPORTANT:** This is critical that you read this before proceeding.
+```
+→
+```markdown
+:::caution[Important]
+This is critical that you read this before proceeding.
+:::
+```

package/.claude/skills/bmad-os-draft-changelog/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-os-draft-changelog
+description: "Analyzes changes since last release and updates CHANGELOG.md ONLY. Use when users requests 'update the changelog' or 'prepare changelog release notes'"
+---
+
+Read `prompts/instructions.md` and execute.

package/.claude/skills/bmad-os-draft-changelog/prompts/instructions.md

@@ -0,0 +1,82 @@
+# Draft Changelog Execution
+
+## ⚠️ IMPORTANT - READ FIRST
+
+**This skill ONLY updates CHANGELOG.md. That is its entire purpose.**
+
+- **DO** update CHANGELOG.md with the new version entry
+- **DO** present the draft for user review before editing
+- **DO NOT** trigger any GitHub release workflows
+- **DO NOT** run any other skills or workflows automatically
+- **DO NOT** make any commits
+
+After the changelog is complete, you may suggest the user can run `/release-module` if they want to proceed with the actual release — but NEVER trigger it yourself.
+
+## Input
+Project path (or run from project root)
+
+## Step 1: Identify Current State
+- Get the latest released tag
+- Get current version
+- Verify there are commits since the last release
+
+## Step 2: Launch Explore Agent
+
+Use `thoroughness: "very thorough"` to analyze all changes since the last release tag.
+
+**Key: For each merge commit, look up the merged PR/issue that was closed.**
+- Use `gh pr view` or git commit body to find the PR number
+- Read the PR description and comments to understand full context
+- Don't rely solely on commit merge messages - they lack context
+
+**Analyze:**
+
+1. **All merges/commits** since the last tag
+2. **For each merge, read the original PR/issue** that was closed
+3. **Files changed** with statistics
+4. **Categorize changes:**
+   - 🎁 **Features** - New functionality, new agents, new workflows
+   - 🐛 **Bug Fixes** - Fixed bugs, corrected issues
+   - ♻️ **Refactoring** - Code improvements, reorganization
+   - 📚 **Documentation** - Docs updates, README changes
+   - 🔧 **Maintenance** - Dependency updates, tooling, infrastructure
+   - 💥 **Breaking Changes** - Changes that may affect users
+
+**Provide:**
+- Comprehensive summary of ALL changes with PR context
+- Categorization of each change
+- Identification of breaking changes
+- Significance assessment (major/minor/trivial)
+
+## Step 3: Generate Draft Changelog
+
+Format:
+```markdown
+## v0.X.X - [Date]
+
+* [Change 1 - categorized by type]
+* [Change 2]
+```
+
+Guidelines:
+- Present tense ("Fix bug" not "Fixed bug")
+- Most significant changes first
+- Group related changes
+- Clear, concise language
+- For breaking changes, clearly indicate impact
+
+## Step 4: Present Draft & Update CHANGELOG.md
+
+Show the draft with current version, last tag, commit count, and options to edit/retry.
+
+When user accepts:
+1. Update CHANGELOG.md with the new entry (insert at top, after `# Changelog` header)
+2. STOP. That's it. You're done.
+
+You may optionally suggest: *"When ready, you can run `/release-module` to create the actual release."*
+
+**DO NOT:**
+- Trigger any GitHub workflows
+- Run any other skills
+- Make any commits
+- Do anything beyond updating CHANGELOG.md

package/.claude/skills/bmad-os-gh-triage/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-os-gh-triage
+description: Analyze all github issues. Use when the user says 'triage the github issues' or 'analyze open github issues'.
+---
+
+Read `prompts/instructions.md` and execute.

package/.claude/skills/bmad-os-gh-triage/prompts/agent-prompt.md

@@ -0,0 +1,60 @@
+You are analyzing a batch of GitHub issues for deep understanding and triage.
+
+**YOUR TASK:**
+Read the issues in your batch and provide DEEP analysis:
+
+1. **For EACH issue, analyze:**
+   - What is this ACTUALLY about? (beyond keywords)
+   - What component/system does it affect?
+   - What's the impact and severity?
+   - Is it a bug, feature request, or something else?
+   - What specific theme does it belong to?
+
+2. **PRIORITY ASSESSMENT:**
+   - CRITICAL: Blocks users, security issues, data loss, broken installers
+   - HIGH: Major functionality broken, important features missing
+   - MEDIUM: Workarounds available, minor bugs, nice-to-have features
+   - LOW: Edge cases, cosmetic issues, questions
+
+3. **RELATIONSHIPS:**
+   - Duplicates: Near-identical issues about the same problem
+   - Related: Issues connected by theme or root cause
+   - Dependencies: One issue blocks or requires another
+
+**YOUR BATCH:**
+[Paste the batch of issues here - each with number, title, body, labels]
+
+**OUTPUT FORMAT (JSON only, no markdown):**
+{
+  "issues": [
+    {
+      "number": 123,
+      "title": "issue title",
+      "deep_understanding": "2-3 sentences explaining what this is really about",
+      "affected_components": ["installer", "workflows", "docs"],
+      "issue_type": "bug/feature/question/tech-debt",
+      "priority": "CRITICAL/HIGH/MEDIUM/LOW",
+      "priority_rationale": "Why this priority level",
+      "theme": "installation/workflow/integration/docs/ide-support/etc",
+      "relationships": {
+        "duplicates_of": [456],
+        "related_to": [789, 101],
+        "blocks": [111]
+      }
+    }
+  ],
+  "cross_repo_issues": [
+    {"number": 123, "target_repo": "bmad-builder", "reason": "about agent builder"}
+  ],
+  "cleanup_candidates": [
+    {"number": 456, "reason": "v4-related/outdated/duplicate"}
+  ],
+  "themes_found": {
+    "Installation Blockers": {
+      "count": 5,
+      "root_cause": "Common pattern if identifiable"
+    }
+  }
+}
+
+Return ONLY valid JSON. No explanations outside the JSON structure.

package/.claude/skills/bmad-os-gh-triage/prompts/instructions.md

@@ -0,0 +1,74 @@
+# GitHub Issue Triage with AI Analysis
+
+**CRITICAL RULES:**
+- NEVER include time or effort estimates in output or recommendations
+- Focus on WHAT needs to be done, not HOW LONG it takes
+- Use Bash tool with gh CLI for all GitHub operations
+
+## Execution
+
+### Step 1: Fetch Issues
+Use `gh issue list --json number,title,body,labels` to fetch all open issues.
+
+### Step 2: Batch Creation
+Split issues into batches of ~10 issues each for parallel analysis.
+
+### Step 3: Parallel Agent Analysis
+For EACH batch, use the Task tool with `subagent_type=general-purpose` to launch an agent with prompt from `prompts/agent-prompt.md`
+
+### Step 4: Consolidate & Generate Report
+After all agents complete, create a comprehensive markdown report saved to `_bmad-output/triage-reports/triage-YYYY-MM-DD.md`
+
+## Report Format
+
+### Executive Summary
+- Total issues analyzed
+- Issue count by priority (CRITICAL, HIGH, MEDIUM, LOW)
+- Major themes discovered
+- Top 5 critical issues requiring immediate attention
+
+### Critical Issues (CRITICAL Priority)
+For each CRITICAL issue:
+- **#123 - [Issue Title](url)**
+- **What it's about:** [Deep understanding]
+- **Affected:** [Components]
+- **Why Critical:** [Rationale]
+- **Suggested Action:** [Specific action]
+
+### High Priority Issues (HIGH Priority)
+Same format as Critical, grouped by theme.
+
+### Theme Clusters
+For each major theme:
+- **Theme Name** (N issues)
+- **What connects these:** [Pattern]
+- **Root cause:** [If identifiable]
+- **Consolidated actions:** [Bulk actions if applicable]
+- **Issues:** #123, #456, #789
+
+### Relationships & Dependencies
+- **Duplicates:** List pairs with `gh issue close` commands
+- **Related Issues:** Groups of related issues
+- **Dependencies:** Blocking relationships
+
+### Cross-Repo Issues
+Issues that should be migrated to other repositories.
+
+For each, provide:
+```
+gh issue close XXX --repo CURRENT_REPO --comment "This issue belongs in REPO. Please report at https://github.com/TARGET_REPO/issues/new"
+```
+
+### Cleanup Candidates
+- **v4-related:** Deprecated version issues with close commands
+- **Stale:** No activity >30 days
+- **Low priority + old:** Low priority issues >60 days old
+
+### Actionable Next Steps
+Specific, prioritized actions:
+1. [CRITICAL] Fix broken installer - affects all new users
+2. [HIGH] Resolve Windows path escaping issues
+3. [HIGH] Address workflow integration bugs
+etc.
+
+Include `gh` commands where applicable for bulk actions.

package/.claude/skills/bmad-os-release-module/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-os-release-module
+description: Perform requested version bump, git tag, npm publish, GitHub release. Use when user requests 'perform a release' only.
+---
+
+Read `prompts/instructions.md` and execute.

package/.claude/skills/bmad-os-release-module/prompts/instructions.md

@@ -0,0 +1,53 @@
+# Release BMad Module Execution
+
+## Input
+Project path (or run from project root)
+
+## Execution Steps
+
+### Step 1: Get Current State
+- Verify git working tree is clean
+- Get latest tag and current version
+- Check for unpushed commits
+
+### Step 2: Get Changelog Entry
+
+Ask the user for the changelog entry (from draft-changelog skill or manual).
+
+### Step 3: Confirm Changelog
+
+Show project name, current version, proposed next version, and changelog. Get confirmation.
+
+### Step 4: Confirm Version Bump Type
+
+Ask what type of bump: patch, minor, major, prerelease, or custom.
+
+### Step 5: Update CHANGELOG.md
+
+Insert new entry at top, commit, and push.
+
+### Step 6: Bump Version
+
+Run `npm version` to update package.json, create commit, and create tag.
+
+### Step 7: Push Tag
+
+Push the new version tag to GitHub.
+
+### Step 8: Publish to npm
+
+Publish the package.
+
+### Step 9: Create GitHub Release
+
+Create release with changelog notes using `gh release create`.
+
+## Error Handling
+
+Stop immediately on any step failure. Inform user and suggest fix.
+
+## Important Notes
+
+- Wait for user confirmation before destructive operations
+- Push changelog commit before version bump
+- Use explicit directory paths in commands

package/.claude/skills/bmad-os-review-pr/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-os-review-pr
+description: Adversarial PR review tool (Raven's Verdict). Cynical deep review transformed into professional engineering findings. Use when user asks to 'review a PR' and provides a PR url or id.
+---
+
+Read `prompts/instructions.md` and execute.