Compare commits
13 Commits
8b48154fa0
...
4129ec30a3
| Author | SHA1 | Date |
|---|---|---|
Ajay Kumar
|
4129ec30a3 | |
Alex Verkhovsky
|
3339f24890 | |
|
Alex Verkhovsky
|
c0877e795f | |
|
Alex Verkhovsky
|
ffd7d53be5 | |
|
Alex Verkhovsky
|
031a9093a1 | |
|
Alex Verkhovsky
|
2a12c6b2f0 | |
|
Alex Verkhovsky
|
bb046f5062 | |
Brian Madison
|
2b809e56a4 | |
|
Brian Madison
|
5988fe0506 | |
|
Alex Verkhovsky
|
ace23f6902 | |
ak95asb
|
d756b79322 | |
PinkyD
|
622e1fd813 | |
NOI03_Ajay Singh
|
2632f6c538 |
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
name: bmad-os-audit-file-refs
|
||||
description: Audit BMAD source files for file-reference convention violations using parallel Haiku subagents. Use when users requests an "audit file references" for a skill, workflow or task.
|
||||
---
|
||||
|
||||
Read `prompts/instructions.md` and execute.
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
# audit-file-refs
|
||||
|
||||
Audit new-format BMAD source files for file-reference convention violations using parallel Haiku subagents.
|
||||
|
||||
## Convention
|
||||
|
||||
In new-format BMAD workflow and task files (`src/bmm/`, `src/core/`, `src/utility/`), every file path reference must use one of these **valid** forms:
|
||||
|
||||
- `{project-root}/_bmad/path/to/file.ext` — canonical form, always correct
|
||||
- `{installed_path}/relative/path` — valid in new-format step files (always defined by workflow.md before any step is reached)
|
||||
- Template/runtime variables: `{nextStepFile}`, `{workflowFile}`, `{{mustache}}`, `{output_folder}`, `{communication_language}`, etc. — skip these, they are substituted at runtime
|
||||
|
||||
**Flag any reference that uses:**
|
||||
|
||||
- `./step-NN.md` or `../something.md` — relative paths
|
||||
- `step-NN.md` — bare filename with no path prefix
|
||||
- `steps/step-NN.md` — bare steps-relative path (missing `{project-root}/_bmad/...` prefix)
|
||||
- `` `_bmad/core/tasks/help.md` `` — bare `_bmad/` path (missing `{project-root}/`)
|
||||
- `/Users/...`, `/home/...`, `C:\...` — absolute system paths
|
||||
|
||||
References inside fenced code blocks (``` ``` ```) are examples — skip them.
|
||||
|
||||
Old-format files in `src/bmm/workflows/4-implementation/` use `{installed_path}` by design within the XML calling chain — exclude that directory entirely.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Run this command to get the file list:
|
||||
```
|
||||
find src/bmm src/core src/utility -type f \( -name "*.md" -o -name "*.yaml" \) | grep -v "4-implementation" | sort
|
||||
```
|
||||
|
||||
2. Divide the resulting file paths into batches of roughly 20 files each.
|
||||
|
||||
3. For each batch, spawn a subagent (`subagent_type: "Explore"`, `model: "haiku"`) with this prompt (fill in the actual file paths):
|
||||
|
||||
> Read each of these files (use the Read tool on each):
|
||||
> [list the file paths from this batch]
|
||||
>
|
||||
> For each file, identify every line that contains a file path reference that violates the convention described below. Skip references inside fenced code blocks. Skip template variables (anything containing `{` that isn't `{project-root}` or `{installed_path}`).
|
||||
>
|
||||
> **Valid references:** `{project-root}/_bmad/...`, `{installed_path}/...`, template variables.
|
||||
> **Flag:** bare filenames (`step-NN.md`), `./` or `../` relative paths, bare `steps/` paths, bare `_bmad/` paths (without `{project-root}/`), absolute system paths.
|
||||
>
|
||||
> Return findings as a list:
|
||||
> `path/to/file.md:LINE_NUMBER | VIOLATION_TYPE | offending text`
|
||||
>
|
||||
> If a file has no violations, include it as: `path/to/file.md | clean`
|
||||
>
|
||||
> End your response with a single line: `FILES CHECKED: N` where N is the exact number of files you read.
|
||||
|
||||
4. Collect all findings from all subagents.
|
||||
|
||||
5. **Self-check before reporting:** Count the total number of files returned by the `find` command. Sum the `FILES CHECKED: N` values across all subagent responses. If the totals do not match, identify which files are missing and re-run subagents for those files before proceeding. Do not produce the final report until all files are accounted for.
|
||||
|
||||
6. Output a final report:
|
||||
- Group findings by violation type
|
||||
- List each finding as `file:line — offending text`
|
||||
- Show total count of violations and number of affected files
|
||||
- If nothing found, say "All files conform to the convention."
|
||||
|
|
@ -1,177 +0,0 @@
|
|||
---
|
||||
name: bmad-os-changelog-social
|
||||
description: Generate social media announcements for Discord, Twitter, and LinkedIn from the latest changelog entry. Use when user asks to 'create release announcement' or 'create social posts' or share changelog updates.
|
||||
---
|
||||
|
||||
# Changelog Social
|
||||
|
||||
Generate engaging social media announcements from changelog entries.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Extract Changelog Entry
|
||||
|
||||
Read `./CHANGELOG.md` and extract the latest version entry. The changelog follows this format:
|
||||
|
||||
```markdown
|
||||
## [VERSION]
|
||||
|
||||
### 🎁 Features
|
||||
* **Title** — Description
|
||||
|
||||
### 🐛 Bug Fixes
|
||||
* **Title** — Description
|
||||
|
||||
### 📚 Documentation
|
||||
* **Title** — Description
|
||||
|
||||
### 🔧 Maintenance
|
||||
* **Title** — Description
|
||||
```
|
||||
|
||||
Parse:
|
||||
- **Version number** (e.g., `6.0.0-Beta.5`)
|
||||
- **Features** - New functionality, enhancements
|
||||
- **Bug Fixes** - Fixes users will care about
|
||||
- **Documentation** - New or improved docs
|
||||
- **Maintenance** - Dependency updates, tooling improvements
|
||||
|
||||
### Step 2: Get Git Contributors
|
||||
|
||||
Use git log to find contributors since the previous version. Get commits between the current version tag and the previous one:
|
||||
|
||||
```bash
|
||||
# Find the previous version tag first
|
||||
git tag --sort=-version:refname | head -5
|
||||
|
||||
# Get commits between versions with PR numbers and authors
|
||||
git log <previous-tag>..<current-tag> --pretty=format:"%h|%s|%an" --grep="#"
|
||||
```
|
||||
|
||||
Extract PR numbers from commit messages that contain `#` followed by digits. Compile unique contributors.
|
||||
|
||||
### Step 3: Generate Discord Announcement
|
||||
|
||||
**Limit: 2,000 characters per message.** Split into multiple messages if needed.
|
||||
|
||||
Use this template style:
|
||||
|
||||
```markdown
|
||||
🚀 **BMad vVERSION RELEASED!**
|
||||
|
||||
🎉 [Brief hype sentence]
|
||||
|
||||
🪥 **KEY HIGHLIGHT** - [One-line summary]
|
||||
|
||||
🎯 **CATEGORY NAME**
|
||||
• Feature one - brief description
|
||||
• Feature two - brief description
|
||||
• Coming soon: Future teaser
|
||||
|
||||
🔧 **ANOTHER CATEGORY**
|
||||
• Fix or feature
|
||||
• Another item
|
||||
|
||||
📚 **DOCS OR OTHER**
|
||||
• Item
|
||||
• Item with link
|
||||
|
||||
🌟 **COMMUNITY PHILOSOPHY** (optional - include for major releases)
|
||||
• Everything is FREE - No paywalls
|
||||
• Knowledge shared, not sold
|
||||
|
||||
📊 **STATS**
|
||||
X commits | Y PRs merged | Z files changed
|
||||
|
||||
🙏 **CONTRIBUTORS**
|
||||
@username1 (X PRs!), @username2 (Y PRs!)
|
||||
@username3, @username4, username5 + dependabot 🛡️
|
||||
Community-driven FTW! 🌟
|
||||
|
||||
📦 **INSTALL:**
|
||||
`npx bmad-method@VERSION install`
|
||||
|
||||
⭐ **SUPPORT US:**
|
||||
🌟 GitHub: github.com/bmad-code-org/BMAD-METHOD/
|
||||
📺 YouTube: youtube.com/@BMadCode
|
||||
☕ Donate: buymeacoffee.com/bmad
|
||||
|
||||
🔥 **Next version tease!**
|
||||
```
|
||||
|
||||
**Content Strategy:**
|
||||
- Focus on **user impact** - what's better for them?
|
||||
- Highlight **annoying bugs fixed** that frustrated users
|
||||
- Show **new capabilities** that enable workflows
|
||||
- Keep it **punchy** - use emojis and short bullets
|
||||
- Add **personality** - excitement, humor, gratitude
|
||||
|
||||
### Step 4: Generate Twitter Post
|
||||
|
||||
**Limit: 25,000 characters per tweet (Premium).** With Premium, use a single comprehensive post matching the Discord style (minus Discord-specific formatting). Aim for 1,500-3,000 characters for better engagement.
|
||||
|
||||
**Threads are optional** — only use for truly massive releases where you want multiple engagement points.
|
||||
|
||||
See `examples/twitter-example.md` for the single-post Premium format.
|
||||
|
||||
## Content Selection Guidelines
|
||||
|
||||
**Include:**
|
||||
- New features that change workflows
|
||||
- Bug fixes for annoying/blocking issues
|
||||
- Documentation that helps users
|
||||
- Performance improvements
|
||||
- New agents or workflows
|
||||
- Breaking changes (call out clearly)
|
||||
|
||||
**Skip/Minimize:**
|
||||
- Internal refactoring
|
||||
- Dependency updates (unless user-facing)
|
||||
- Test improvements
|
||||
- Minor style fixes
|
||||
|
||||
**Emphasize:**
|
||||
- "Finally fixed" issues
|
||||
- "Faster" operations
|
||||
- "Easier" workflows
|
||||
- "Now supports" capabilities
|
||||
|
||||
## Examples
|
||||
|
||||
Reference example posts in `examples/` for tone and formatting guidance:
|
||||
|
||||
- **discord-example.md** — Full Discord announcement with emojis, sections, contributor shout-outs
|
||||
- **twitter-example.md** — Twitter thread format (5 tweets max for major releases)
|
||||
- **linkedin-example.md** — Professional post for major/minor releases with significant features
|
||||
|
||||
**When to use LinkedIn:**
|
||||
- Major version releases (e.g., v6.0.0 Beta, v7.0.0)
|
||||
- Minor releases with exceptional new features
|
||||
- Community milestone announcements
|
||||
|
||||
Read the appropriate example file before generating to match the established style and voice.
|
||||
|
||||
## Output Format
|
||||
|
||||
**CRITICAL: ALWAYS write to files** - Create files in `_bmad-output/social/` directory:
|
||||
|
||||
1. `{repo-name}-discord-{version}.md` - Discord announcement
|
||||
2. `{repo-name}-twitter-{version}.md` - Twitter post
|
||||
3. `{repo-name}-linkedin-{version}.md` - LinkedIn post (if applicable)
|
||||
|
||||
Also present a preview in the chat:
|
||||
|
||||
```markdown
|
||||
## Discord Announcement
|
||||
|
||||
[paste Discord content here]
|
||||
|
||||
## Twitter Post
|
||||
|
||||
[paste Twitter content here]
|
||||
```
|
||||
|
||||
Files created:
|
||||
- `_bmad-output/social/{filename}`
|
||||
|
||||
Offer to make adjustments if the user wants different emphasis, tone, or content.
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
🚀 **BMad v6.0.0-alpha.23 RELEASED!**
|
||||
|
||||
🎉 Huge update - almost beta!
|
||||
|
||||
🪟 **WINDOWS INSTALLER FIXED** - Menu arrows issue should be fixed! CRLF & ESM problems resolved.
|
||||
|
||||
🎯 **PRD WORKFLOWS IMPROVED**
|
||||
• Validation & Edit workflows added!
|
||||
• PRD Cohesion check ensures document flows beautifully
|
||||
• Coming soon: Use of subprocess optimization (context saved!)
|
||||
• Coming soon: Final format polish step in all workflows - Human consumption OR hyper-optimized LLM condensed initially!
|
||||
|
||||
🔧 **WORKFLOW CREATOR & VALIDATOR**
|
||||
• Subprocess support for advanced optimization
|
||||
• Path violation checks ensure integrity
|
||||
• Beyond error checking - offers optimization & flow suggestions!
|
||||
|
||||
📚 **NEW DOCS SITE** - docs.bmad-method.org
|
||||
• Diataxis framework: Tutorials, How-To, Explanations, References
|
||||
• Current docs still being revised
|
||||
• Tutorials, blogs & explainers coming soon!
|
||||
|
||||
💡 **BRAINSTORMING REVOLUTION**
|
||||
• 100+ idea goal (quantity-first!)
|
||||
• Anti-bias protocol (pivot every 10 ideas)
|
||||
• Chain-of-thought + simulated temperature prompts
|
||||
• Coming soon: SubProcessing (on-the-fly sub agents)
|
||||
|
||||
🌟 **COMMUNITY PHILOSOPHY**
|
||||
• Everything is FREE - No paywalls, no gated content
|
||||
• Knowledge shared, not sold
|
||||
• No premium tiers - full access to our ideas
|
||||
|
||||
📊 **27 commits | 217 links converted | 42+ docs created**
|
||||
|
||||
🙏 **17 Community PR Authors in this release!**
|
||||
@lum (6 PRs!), @q00 (3 PRs!), @phil (2 PRs!)
|
||||
@mike, @alex, @ramiz, @sjennings + dependabot 🛡️
|
||||
Community-driven FTW! 🌟
|
||||
|
||||
📦 **INSTALL ALPHA:**
|
||||
`npx bmad-method install`
|
||||
|
||||
⭐ **SUPPORT US:**
|
||||
🌟 GitHub: github.com/bmad-code-org/BMAD-METHOD/
|
||||
📺 YouTube: youtube.com/@BMadCode
|
||||
|
||||
🎤 **SPEAKING & MEDIA**
|
||||
Available for conferences, podcasts, media appearances!
|
||||
Topics: AI-Native Organizations (Any Industry), BMad Method
|
||||
DM on Discord for inquiries!
|
||||
|
||||
🔥 **V6 Beta is DAYS away!** January 22nd ETA - new features such as xyz and abc bug fixes!
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
🚀 **Announcing BMad Method v6.0.0 Beta - AI-Native Agile Development Framework**
|
||||
|
||||
I'm excited to share that BMad Method, the open-source AI-driven agile development framework, is entering Beta! After 27 alpha releases and countless community contributions, we're approaching a major milestone.
|
||||
|
||||
**What's New in v6.0.0-alpha.23**
|
||||
|
||||
🪟 **Windows Compatibility Fixed**
|
||||
We've resolved the installer issues that affected Windows users. The menu arrows problem, CRLF handling, and ESM compatibility are all resolved.
|
||||
|
||||
🎯 **Enhanced PRD Workflows**
|
||||
Our Product Requirements Document workflows now include validation and editing capabilities, with a new cohesion check that ensures your documents flow beautifully. Subprocess optimization is coming soon to save even more context.
|
||||
|
||||
🔧 **Workflow Creator & Validator**
|
||||
New tools for creating and validating workflows with subprocess support, path violation checks, and optimization suggestions that go beyond simple error checking.
|
||||
|
||||
📚 **New Documentation Platform**
|
||||
We've launched docs.bmad-method.org using the Diataxis framework - providing clear separation between tutorials, how-to guides, explanations, and references. Our documentation is being continuously revised and expanded.
|
||||
|
||||
💡 **Brainstorming Revolution**
|
||||
Our brainstorming workflows now use research-backed techniques: 100+ idea goals, anti-bias protocols, chain-of-thought reasoning, and simulated temperature prompts for higher divergence.
|
||||
|
||||
**Our Philosophy**
|
||||
|
||||
Everything in BMad Method is FREE. No paywalls, no gated content, no premium tiers. We believe knowledge should be shared, not sold. This is community-driven development at its finest.
|
||||
|
||||
**The Stats**
|
||||
- 27 commits in this release
|
||||
- 217 documentation links converted
|
||||
- 42+ new documents created
|
||||
- 17 community PR authors contributed
|
||||
|
||||
**Get Started**
|
||||
|
||||
```
|
||||
npx bmad-method@alpha install
|
||||
```
|
||||
|
||||
**Learn More**
|
||||
- GitHub: github.com/bmad-code-org/BMAD-METHOD
|
||||
- YouTube: youtube.com/@BMadCode
|
||||
- Docs: docs.bmad-method.org
|
||||
|
||||
**What's Next?**
|
||||
|
||||
Beta is just days away with an ETA of January 22nd. We're also available for conferences, podcasts, and media appearances to discuss AI-Native Organizations and the BMad Method.
|
||||
|
||||
Have you tried BMad Method yet? I'd love to hear about your experience in the comments!
|
||||
|
||||
#AI #SoftwareDevelopment #Agile #OpenSource #DevTools #LLM #AgentEngineering
|
||||
|
|
@ -1,55 +0,0 @@
|
|||
🚀 **BMad v6.0.0-alpha.23 RELEASED!**
|
||||
|
||||
Huge update - we're almost at Beta! 🎉
|
||||
|
||||
🪟 **WINDOWS INSTALLER FIXED** - Menu arrows issue should be fixed! CRLF & ESM problems resolved.
|
||||
|
||||
🎯 **PRD WORKFLOWS IMPROVED**
|
||||
• Validation & Edit workflows added!
|
||||
• PRD Cohesion check ensures document flows beautifully
|
||||
• Coming soon: Subprocess optimization (context saved!)
|
||||
• Coming soon: Final format polish step in all workflows
|
||||
|
||||
🔧 **WORKFLOW CREATOR & VALIDATOR**
|
||||
• Subprocess support for advanced optimization
|
||||
• Path violation checks ensure integrity
|
||||
• Beyond error checking - offers optimization & flow suggestions!
|
||||
|
||||
📚 **NEW DOCS SITE** - docs.bmad-method.org
|
||||
• Diataxis framework: Tutorials, How-To, Explanations, References
|
||||
• Current docs still being revised
|
||||
• Tutorials, blogs & explainers coming soon!
|
||||
|
||||
💡 **BRAINSTORMING REVOLUTION**
|
||||
• 100+ idea goal (quantity-first!)
|
||||
• Anti-bias protocol (pivot every 10 ideas)
|
||||
• Chain-of-thought + simulated temperature prompts
|
||||
• Coming soon: SubProcessing (on-the-fly sub agents)
|
||||
|
||||
🌟 **COMMUNITY PHILOSOPHY**
|
||||
• Everything is FREE - No paywalls, no gated content
|
||||
• Knowledge shared, not sold
|
||||
• No premium tiers - full access to our ideas
|
||||
|
||||
📊 **27 commits | 217 links converted | 42+ docs created**
|
||||
|
||||
🙏 **17 Community PR Authors in this release!**
|
||||
@lum (6 PRs!), @q00 (3 PRs!), @phil (2 PRs!)
|
||||
@mike, @alex, @ramiz, @sjennings + dependabot 🛡️
|
||||
Community-driven FTW! 🌟
|
||||
|
||||
📦 **INSTALL ALPHA:**
|
||||
`npx bmad-method install`
|
||||
|
||||
⭐ **SUPPORT US:**
|
||||
🌟 GitHub: github.com/bmad-code-org/BMAD-METHOD/
|
||||
📺 YouTube: youtube.com/@BMadCode
|
||||
|
||||
🎤 **SPEAKING & MEDIA**
|
||||
Available for conferences, podcasts, media appearances!
|
||||
Topics: AI-Native Organizations (Any Industry), BMad Method
|
||||
DM on Discord for inquiries!
|
||||
|
||||
🔥 **V6 Beta is DAYS away!** January 22nd ETA!
|
||||
|
||||
#AI #DevTools #Agile #OpenSource #LLM #AgentEngineering
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
name: bmad-os-diataxis-style-fix
|
||||
description: Fixes documentation to comply with Diataxis framework and BMad Method style guide rules. Use when user asks to check or fix style of files under the docs folder.
|
||||
---
|
||||
|
||||
Read `prompts/instructions.md` and execute.
|
||||
|
|
@ -1,229 +0,0 @@
|
|||
# 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.
|
||||
:::
|
||||
```
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -1,82 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
name: bmad-os-findings-triage
|
||||
description: Orchestrate HITL triage of review findings using parallel agents. Use when the user says 'triage these findings' or 'run findings triage' or has a batch of review findings to process.
|
||||
---
|
||||
|
||||
Read `prompts/instructions.md` and execute.
|
||||
|
|
@ -1,104 +0,0 @@
|
|||
# Finding Agent: {{TASK_ID}} — {{TASK_SUBJECT}}
|
||||
|
||||
You are a finding agent in the `{{TEAM_NAME}}` triage team. You own exactly one finding and will shepherd it through research, planning, human conversation, and a final decision.
|
||||
|
||||
## Your Assignment
|
||||
|
||||
- **Task:** `{{TASK_ID}}`
|
||||
- **Finding:** `{{FINDING_ID}}` — {{FINDING_TITLE}}
|
||||
- **Severity:** {{SEVERITY}}
|
||||
- **Team:** `{{TEAM_NAME}}`
|
||||
- **Team Lead:** `{{TEAM_LEAD_NAME}}`
|
||||
|
||||
## Phase 1 — Research (autonomous)
|
||||
|
||||
1. Read your task details with `TaskGet("{{TASK_ID}}")`.
|
||||
2. Read the relevant source files to understand the finding in context:
|
||||
{{FILE_LIST}}
|
||||
If no specific files are listed above, use codebase search to locate code relevant to the finding.
|
||||
|
||||
If a context document was provided:
|
||||
- Also read this context document for background: {{CONTEXT_DOC}}
|
||||
|
||||
If an initial triage was provided:
|
||||
- **Note:** The team lead triaged this as **{{INITIAL_TRIAGE}}** — {{TRIAGE_RATIONALE}}. Evaluate whether this triage is correct and incorporate your assessment into your plan.
|
||||
|
||||
**Rules for research:**
|
||||
- Work autonomously. Do not ask the team lead or the human for help during research.
|
||||
- Use `Read`, `Grep`, `Glob`, and codebase search tools to understand the codebase.
|
||||
- Trace call chains, check tests, read related code — be thorough.
|
||||
- Form your own opinion on whether this finding is real, a false positive, or somewhere in between.
|
||||
|
||||
## Phase 2 — Plan (display only)
|
||||
|
||||
Prepare a plan for dealing with this finding. The plan MUST cover:
|
||||
|
||||
1. **Assessment** — Is this finding real? What is the actual risk or impact?
|
||||
2. **Recommendation** — One of: fix it, accept the risk (wontfix), dismiss as not a real issue, or reject as a false positive.
|
||||
3. **If recommending a fix:** Describe the specific changes — which files, what modifications, why this approach.
|
||||
4. **If recommending against fixing:** Explain the reasoning — existing mitigations, acceptable risk, false positive rationale.
|
||||
|
||||
**Display the plan in your output.** Write it clearly so the human can read it directly. Follow the plan with a 2-5 line summary of the finding itself.
|
||||
|
||||
**CRITICAL: Do NOT send your plan or analysis to the team lead.** The team lead does not need your plan — the human reads it from your output stream. Sending full plans to the team lead wastes its context window.
|
||||
|
||||
## Phase 3 — Signal Ready
|
||||
|
||||
After displaying your plan, send exactly this to the team lead:
|
||||
|
||||
```
|
||||
SendMessage({
|
||||
type: "message",
|
||||
recipient: "{{TEAM_LEAD_NAME}}",
|
||||
content: "{{FINDING_ID}} ready for HITL",
|
||||
summary: "{{FINDING_ID}} ready for review"
|
||||
})
|
||||
```
|
||||
|
||||
Then **stop and wait**. Do not proceed until the human engages with you.
|
||||
|
||||
## Phase 4 — HITL Conversation
|
||||
|
||||
The human will review your plan and talk to you directly. This is a real conversation, not a rubber stamp:
|
||||
|
||||
- The human may agree immediately, push back, ask questions, or propose alternatives.
|
||||
- Answer questions thoroughly. Refer back to specific code you read.
|
||||
- If the human wants a fix, **apply it** — edit the source files, verify the change makes sense.
|
||||
- If the human disagrees with your assessment, update your recommendation.
|
||||
- Stay focused on THIS finding only. Do not discuss other findings.
|
||||
- **Do not send a decision until the human explicitly states a verdict.** Acknowledging your plan is NOT a decision. Wait for clear direction like "fix it", "dismiss", "reject", "skip", etc.
|
||||
|
||||
## Phase 5 — Report Decision
|
||||
|
||||
When the human reaches a decision, send exactly ONE message to the team lead:
|
||||
|
||||
```
|
||||
SendMessage({
|
||||
type: "message",
|
||||
recipient: "{{TEAM_LEAD_NAME}}",
|
||||
content: "DECISION {{FINDING_ID}} {{TASK_ID}} [CATEGORY] | [one-sentence summary]",
|
||||
summary: "{{FINDING_ID}} [CATEGORY]"
|
||||
})
|
||||
```
|
||||
|
||||
Where `[CATEGORY]` is one of:
|
||||
|
||||
| Category | Meaning |
|
||||
|----------|---------|
|
||||
| **SKIP** | Human chose to skip without full review. |
|
||||
| **DEFER** | Human chose to defer to a later session. |
|
||||
| **FIX** | Change applied. List the file paths changed and what each change was (use a parseable format: `files: path1, path2`). |
|
||||
| **WONTFIX** | Real finding, not worth fixing now. State why. |
|
||||
| **DISMISS** | Not a real finding or mitigated by existing design. State the mitigation. |
|
||||
| **REJECT** | False positive from the reviewer. State why it is wrong. |
|
||||
|
||||
After sending the decision, **go idle and wait for shutdown**. Do not take any further action. The team lead will send you a shutdown request — approve it.
|
||||
|
||||
## Rules
|
||||
|
||||
- You own ONE finding. Do not touch files unrelated to your finding unless required for the fix.
|
||||
- Your plan is for the human's eyes — display it in your output, never send it to the team lead.
|
||||
- Your only messages to the team lead are: (1) ready for HITL, (2) final decision. Nothing else.
|
||||
- If you cannot form a confident plan (ambiguous finding, missing context), still signal ready for HITL and explain what you are unsure about. The HITL conversation will resolve it.
|
||||
- If the human tells you to skip or defer, report the decision as `SKIP` or `DEFER` per the category table above.
|
||||
- When you receive a shutdown request, approve it immediately.
|
||||
|
|
@ -1,286 +0,0 @@
|
|||
# Findings Triage — Team Lead Orchestration
|
||||
|
||||
You are the team lead for a findings triage session. Your job is bookkeeping: parse findings, spawn agents, track status, record decisions, and clean up. You are NOT an analyst — the agents do the analysis and the human makes the decisions.
|
||||
|
||||
**Be minimal.** Short confirmations. No editorializing. No repeating what agents already said.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Setup
|
||||
|
||||
### 1.1 Determine Input Source
|
||||
|
||||
The human will provide findings in one of three ways:
|
||||
|
||||
1. **A findings report file** — a markdown file with structured findings. Read the file.
|
||||
2. **A pre-populated task list** — tasks already exist. Call `TaskList` to discover them.
|
||||
- If tasks are pre-populated: skip section 1.2 (parsing) and section 1.4 (task creation). Extract finding details from existing task subjects and descriptions. Number findings based on task order. Proceed from section 1.3 (pre-spawn checks).
|
||||
3. **Inline findings** — pasted directly in conversation. Parse them.
|
||||
|
||||
Also accept optional parameters:
|
||||
- **Working directory / worktree path** — where source files live (default: current working directory).
|
||||
- **Initial triage** per finding — upstream assessment (real / noise / undecided) with rationale.
|
||||
- **Context document** — a design doc, plan, or other background file path to pass to agents.
|
||||
|
||||
### 1.2 Parse Findings
|
||||
|
||||
Extract from each finding:
|
||||
- **Title / description**
|
||||
- **Severity** (Critical / High / Medium / Low)
|
||||
- **Relevant file paths**
|
||||
- **Initial triage** (if provided)
|
||||
|
||||
Number findings sequentially: F1, F2, ... Fn. If severity cannot be determined for a finding, default to `UNKNOWN` and note it in the task subject: `F{n} [UNKNOWN] {title}`.
|
||||
|
||||
**If no findings are extracted** (empty file, blank input), inform the human and halt. Do not proceed to task creation or team setup.
|
||||
|
||||
**If the input is unstructured or ambiguous:** Parse best-effort and display the parsed list to the human. Ask for confirmation before proceeding. Do NOT spawn agents until confirmed.
|
||||
|
||||
### 1.3 Pre-Spawn Checks
|
||||
|
||||
**Large batch (>25 findings):**
|
||||
HALT. Tell the human:
|
||||
> "There are {N} findings. Spawning {N} agents at once may overwhelm the system. I recommend processing in waves of ~20. Proceed with all at once, or batch into waves?"
|
||||
|
||||
Wait for the human to decide. If batching, record wave assignments (Wave 1: F1-F20, Wave 2: F21-Fn).
|
||||
|
||||
**Same-file conflicts:**
|
||||
Scan all findings for overlapping file paths. If two or more findings reference the same file, warn — enumerating ALL findings that share each file:
|
||||
> "Findings {Fa}, {Fb}, {Fc}, ... all reference `{file}`. Concurrent edits may conflict. Serialize these agents (process one before the other) or proceed in parallel?"
|
||||
|
||||
Wait for the human to decide. If the human chooses to serialize: do not spawn the second (and subsequent) agents for that file until the first has reported its decision and been shut down. Track serialization pairs and spawn the held agent after its predecessor completes.
|
||||
|
||||
### 1.4 Create Tasks
|
||||
|
||||
For each finding, create a task:
|
||||
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "F{n} [{SEVERITY}] {title}",
|
||||
description: "{full finding details}\n\nFiles: {file paths}\n\nInitial triage: {triage or 'none'}",
|
||||
activeForm: "Analyzing F{n}"
|
||||
})
|
||||
```
|
||||
|
||||
Record the mapping: finding number -> task ID.
|
||||
|
||||
### 1.5 Create Team
|
||||
|
||||
```
|
||||
TeamCreate({
|
||||
team_name: "{review-type}-triage",
|
||||
description: "HITL triage of {N} findings from {source}"
|
||||
})
|
||||
```
|
||||
|
||||
Use a contextual name based on the review type (e.g., `pr-review-triage`, `prompt-audit-triage`, `code-review-triage`). If unsure, use `findings-triage`.
|
||||
|
||||
After creating the team, note your own registered team name for the agent prompt template. Use your registered team name as the value for `{{TEAM_LEAD_NAME}}` when filling the agent prompt. If unsure of your name, read the team config at `~/.claude/teams/{team-name}/config.json` to find your own entry in the members list.
|
||||
|
||||
### 1.6 Spawn Agents
|
||||
|
||||
Read the agent prompt template from `prompts/agent-prompt.md`.
|
||||
|
||||
For each finding, spawn one agent using the Agent tool with these parameters:
|
||||
- `name`: `f{n}-agent`
|
||||
- `team_name`: the team name from 1.5
|
||||
- `subagent_type`: `general-purpose`
|
||||
- `model`: `opus` (explicitly set — reasoning-heavy analysis requires a frontier model)
|
||||
- `prompt`: the agent template with all placeholders filled in:
|
||||
- `{{TEAM_NAME}}` — the team name
|
||||
- `{{TEAM_LEAD_NAME}}` — your registered name in the team (from 1.5)
|
||||
- `{{TASK_ID}}` — the task ID from 1.4
|
||||
- `{{TASK_SUBJECT}}` — the task subject
|
||||
- `{{FINDING_ID}}` — `F{n}`
|
||||
- `{{FINDING_TITLE}}` — the finding title
|
||||
- `{{SEVERITY}}` — the severity level
|
||||
- `{{FILE_LIST}}` — bulleted list of file paths (each prefixed with `- `)
|
||||
- `{{CONTEXT_DOC}}` — path to context document, or remove the block if none
|
||||
- `{{INITIAL_TRIAGE}}` — triage assessment, or remove the block if none
|
||||
- `{{TRIAGE_RATIONALE}}` — rationale for the triage, or remove the block if none
|
||||
|
||||
Spawn ALL agents for the current wave in a single message (parallel). If batching, spawn only the current wave.
|
||||
|
||||
After spawning, print:
|
||||
|
||||
```
|
||||
All {N} agents spawned. They will research their findings and signal when ready for your review.
|
||||
```
|
||||
|
||||
Initialize the scorecard (internal state):
|
||||
|
||||
```
|
||||
Scorecard:
|
||||
- Total: {N}
|
||||
- Pending: {N}
|
||||
- Ready for review: 0
|
||||
- Completed: 0
|
||||
- Decisions: FIX=0 WONTFIX=0 DISMISS=0 REJECT=0 SKIP=0 DEFER=0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — HITL Review Loop
|
||||
|
||||
### 2.1 Track Agent Readiness
|
||||
|
||||
Agents will send messages matching: `F{n} ready for HITL`
|
||||
|
||||
When received:
|
||||
- Note which finding is ready.
|
||||
- Update the internal status tracker.
|
||||
- Print a short status line: `F{n} ready. ({ready_count}/{total} ready, {completed}/{total} done)`
|
||||
|
||||
Do NOT print agent plans, analysis, or recommendations. The human reads those directly from the agent output.
|
||||
|
||||
### 2.2 Status Dashboard
|
||||
|
||||
When the human asks for status (or periodically when useful), print:
|
||||
|
||||
```
|
||||
=== Triage Status ===
|
||||
Ready for review: F3, F7, F11
|
||||
Still analyzing: F1, F5, F9
|
||||
Completed: F2 (FIX), F4 (DISMISS), F6 (REJECT)
|
||||
{completed}/{total} done
|
||||
===
|
||||
```
|
||||
|
||||
Keep it compact. No decoration beyond what is needed.
|
||||
|
||||
### 2.3 Process Decisions
|
||||
|
||||
Agents will send messages matching: `DECISION F{n} {task_id} [CATEGORY] | [summary]`
|
||||
|
||||
When received:
|
||||
1. **Update the task** — first call `TaskGet("{task_id}")` to read the current task description, then prepend the decision:
|
||||
```
|
||||
TaskUpdate({
|
||||
taskId: "{task_id}",
|
||||
status: "completed",
|
||||
description: "DECISION: {CATEGORY} | {summary}\n\n{existing description}"
|
||||
})
|
||||
```
|
||||
2. **Update the scorecard** — increment the decision category counter. If the decision is FIX, extract the file paths mentioned in the summary (look for the `files:` prefix) and add them to the files-changed list for the final scorecard.
|
||||
3. **Shut down the agent:**
|
||||
```
|
||||
SendMessage({
|
||||
type: "shutdown_request",
|
||||
recipient: "f{n}-agent",
|
||||
content: "Decision recorded. Shutting down."
|
||||
})
|
||||
```
|
||||
4. **Print confirmation:** `F{n} closed: {CATEGORY}. {remaining} remaining.`
|
||||
|
||||
### 2.4 Human-Initiated Skip/Defer
|
||||
|
||||
If the human wants to skip or defer a finding without full engagement:
|
||||
|
||||
1. Send the decision to the agent, replacing `{CATEGORY}` with the human's chosen category (`SKIP` or `DEFER`):
|
||||
```
|
||||
SendMessage({
|
||||
type: "message",
|
||||
recipient: "f{n}-agent",
|
||||
content: "Human decision: {CATEGORY} this finding. Report {CATEGORY} as your decision and go idle.",
|
||||
summary: "F{n} {CATEGORY} directive"
|
||||
})
|
||||
```
|
||||
2. Wait for the agent to report the decision back (it will send `DECISION F{n} ... {CATEGORY}`).
|
||||
3. Process as a normal decision (2.3).
|
||||
|
||||
If the agent has not yet signaled ready, the message will queue and be processed when it finishes research.
|
||||
|
||||
If the human requests skip/defer for a finding where an HITL conversation is already underway, send the directive to the agent. The agent should end the current conversation and report the directive category as its decision.
|
||||
|
||||
### 2.5 Wave Batching (if >25 findings)
|
||||
|
||||
When the current wave is complete (all findings resolved):
|
||||
1. Print wave summary.
|
||||
2. Ask: `"Wave {W} complete. Spawn wave {W+1} ({count} findings)? (y/n)"`
|
||||
3. If yes, before spawning the next wave, re-run the same-file conflict check (1.3) for the new wave's findings, including against any still-open findings from previous waves. Then repeat Phase 1.4 (task creation) and 1.6 (agent spawning) only. Do NOT call TeamCreate again — the team already exists.
|
||||
4. If the human declines, treat unspawned findings as not processed. Proceed to Phase 3 wrap-up. Note the count of unprocessed findings in the final scorecard.
|
||||
5. Carry the scorecard forward across waves.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Wrap-up
|
||||
|
||||
When all findings across all waves are resolved:
|
||||
|
||||
### 3.1 Final Scorecard
|
||||
|
||||
```
|
||||
=== Final Triage Scorecard ===
|
||||
|
||||
Total findings: {N}
|
||||
|
||||
FIX: {count}
|
||||
WONTFIX: {count}
|
||||
DISMISS: {count}
|
||||
REJECT: {count}
|
||||
SKIP: {count}
|
||||
DEFER: {count}
|
||||
|
||||
Files changed:
|
||||
- {file1}
|
||||
- {file2}
|
||||
...
|
||||
|
||||
Findings:
|
||||
F1 [{SEVERITY}] {title} — {DECISION}
|
||||
F2 [{SEVERITY}] {title} — {DECISION}
|
||||
...
|
||||
|
||||
=== End Triage ===
|
||||
```
|
||||
|
||||
### 3.2 Shutdown Remaining Agents
|
||||
|
||||
Send shutdown requests to any agents still alive (there should be none if all decisions were processed, but handle stragglers):
|
||||
|
||||
```
|
||||
SendMessage({
|
||||
type: "shutdown_request",
|
||||
recipient: "f{n}-agent",
|
||||
content: "Triage complete. Shutting down."
|
||||
})
|
||||
```
|
||||
|
||||
### 3.3 Offer to Save
|
||||
|
||||
Ask the human:
|
||||
> "Save the scorecard to a file? (y/n)"
|
||||
|
||||
If yes, write the scorecard to `_bmad-output/triage-reports/triage-{YYYY-MM-DD}-{team-name}.md`.
|
||||
|
||||
### 3.4 Delete Team
|
||||
|
||||
```
|
||||
TeamDelete()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases Reference
|
||||
|
||||
| Situation | Response |
|
||||
|-----------|----------|
|
||||
| >25 findings | HALT, suggest wave batching, wait for human decision |
|
||||
| Same-file conflict | Warn, suggest serializing, wait for human decision |
|
||||
| Unstructured input | Parse best-effort, display list, confirm before spawning |
|
||||
| Agent signals uncertainty | Normal — the HITL conversation resolves it |
|
||||
| Human skips/defers | Send directive to agent, process decision when reported |
|
||||
| Agent goes idle unexpectedly | Send a message to check status; agents stay alive until explicit shutdown |
|
||||
| Human asks to re-open a completed finding | Not supported in this session; suggest re-running triage on that finding |
|
||||
| All agents spawned but none ready yet | Tell the human agents are still analyzing; no action needed |
|
||||
|
||||
---
|
||||
|
||||
## Behavioral Rules
|
||||
|
||||
1. **Be minimal.** Short confirmations, compact dashboards. Do not repeat agent analysis.
|
||||
2. **Never auto-close.** Every finding requires a human decision. No exceptions.
|
||||
3. **One agent per finding.** Never batch multiple findings into one agent.
|
||||
4. **Protect your context window.** Agents display plans in their output, not in messages to you. If an agent sends you a long message, acknowledge it briefly and move on.
|
||||
5. **Track everything.** Finding number, task ID, agent name, decision, files changed. You are the single source of truth for the session.
|
||||
6. **Respect the human's pace.** They review in whatever order they want. Do not rush them. Do not suggest which finding to review next unless asked.
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -1,60 +0,0 @@
|
|||
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.
|
||||
|
|
@ -1,74 +0,0 @@
|
|||
# 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.
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
# 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
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
---
|
||||
name: bmad-os-review-pr
|
||||
description: Dual-layer PR review tool (Raven's Verdict). Runs adversarial cynical review and edge case hunter in parallel, merges and deduplicates findings into professional engineering output. Use when user asks to 'review a PR' and provides a PR url or id.
|
||||
---
|
||||
|
||||
Read `prompts/instructions.md` and execute.
|
||||
|
|
@ -1,288 +0,0 @@
|
|||
# Raven's Verdict - Deep PR Review Tool
|
||||
|
||||
A cynical adversarial review, transformed into cold engineering professionalism.
|
||||
|
||||
## 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?"
|
||||
|
||||
## 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.
|
||||
|
||||
## Review Layers
|
||||
|
||||
**Launch steps 1.1 and 1.2 as parallel subagents.** Both receive the same PR diff and run concurrently. Wait for both to complete before proceeding to step 1.3.
|
||||
|
||||
### 1.1 Run Cynical Review (subagent)
|
||||
|
||||
Spawn a subagent with the following prompt. Pass the full PR diff as context.
|
||||
|
||||
**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.
|
||||
|
||||
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
|
||||
|
||||
### 1.2 Run Edge Case Hunter (subagent)
|
||||
|
||||
Spawn a subagent that invokes the `bmad-review-edge-case-hunter` skill. Pass the full PR diff as the `content` input. Omit `also_consider` unless the user specified extra focus areas.
|
||||
|
||||
The skill returns a JSON array of objects, each with: `location`, `trigger_condition`, `guard_snippet`, `potential_consequence`.
|
||||
|
||||
**Map each JSON finding to the standard finding format:**
|
||||
|
||||
````markdown
|
||||
### [NUMBER]. [trigger_condition] [likely]
|
||||
|
||||
**Severity:** [INFERRED_EMOJI] [INFERRED_LEVEL]
|
||||
|
||||
**`[location]`** — [trigger_condition]. [potential_consequence].
|
||||
|
||||
**Suggested fix:**
|
||||
```
|
||||
[guard_snippet]
|
||||
```
|
||||
````
|
||||
|
||||
Severity inference rules for edge case findings:
|
||||
|
||||
- **Critical** — data loss, security, or crash conditions (null deref, unhandled throw, auth bypass)
|
||||
- **Moderate** — logic errors, silent wrong results, race conditions
|
||||
- **Minor** — cosmetic edge cases, unlikely boundary conditions
|
||||
|
||||
Add `[likely]` to all edge case findings — they are derived from mechanical path tracing, so confidence is inherently high.
|
||||
|
||||
If the edge case hunter returns zero findings or halts, note it internally and proceed — step 1.1 findings still stand.
|
||||
|
||||
### 1.3 Merge and Deduplicate
|
||||
|
||||
Combine the findings from step 1.1 (adversarial) and step 1.2 (edge case hunter) into a single list.
|
||||
|
||||
**Deduplication rules:**
|
||||
|
||||
1. Compare each edge case finding against each adversarial finding
|
||||
2. Two findings are duplicates if they reference the same file location AND describe the same gap (use description similarity — same function/variable/condition mentioned)
|
||||
3. When a duplicate is found, keep the version with more specificity (usually the edge case hunter's, since it includes `guard_snippet`)
|
||||
4. Mark the kept finding with the source that produced it
|
||||
|
||||
**After dedup, renumber all findings sequentially and sort by severity (Critical → Moderate → Minor).**
|
||||
|
||||
Tag each finding with its source:
|
||||
|
||||
- `[Adversarial]` — from step 1.1 only
|
||||
- `[Edge Case]` — from step 1.2 only
|
||||
- `[Both]` — flagged by both layers (deduped)
|
||||
|
||||
## Tone Transformation
|
||||
|
||||
**Transform the merged findings 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, likely tag, and **source tags**
|
||||
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
|
||||
7. Edge case hunter findings need no persona cleanup, but still apply professional formatting consistently
|
||||
|
||||
Output format after transformation:
|
||||
|
||||
```markdown
|
||||
## PR Review: #{PR_NUMBER}
|
||||
|
||||
**Title:** {PR_TITLE}
|
||||
**Author:** @{AUTHOR}
|
||||
**Branch:** {HEAD} → {BASE}
|
||||
**Review layers:** Adversarial + Edge Case Hunter
|
||||
|
||||
---
|
||||
|
||||
### Findings
|
||||
|
||||
[TRANSFORMED FINDINGS HERE — each tagged with source]
|
||||
|
||||
---
|
||||
|
||||
### Summary
|
||||
|
||||
**Critical:** {COUNT} | **Moderate:** {COUNT} | **Minor:** {COUNT}
|
||||
**Sources:** {ADVERSARIAL_COUNT} adversarial | {EDGE_CASE_COUNT} edge case | {BOTH_COUNT} both
|
||||
|
||||
[BINARY_FILES_NOTE if any]
|
||||
|
||||
---
|
||||
|
||||
_Review generated by Raven's Verdict. LLM-produced analysis - findings may be incorrect or lack context. Verify before acting._
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## 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
|
||||
|
|
@ -1,177 +0,0 @@
|
|||
---
|
||||
name: bmad-os-review-prompt
|
||||
description: Review LLM workflow step prompts for known failure modes (silent ignoring, negation fragility, scope creep, etc). Use when user asks to "review a prompt" or "audit a workflow step".
|
||||
---
|
||||
|
||||
# Prompt Review Skill: PromptSentinel v1.2
|
||||
|
||||
**Version:** v1.2
|
||||
**Date:** March 2026
|
||||
**Target Models:** Frontier LLMs (Claude 4.6, GPT-5.3, Gemini 3.1 Pro and equivalents) executing autonomous multi-step workflows at million-executions-per-day scale
|
||||
**Purpose:** Detect and eliminate LLM-specific failure modes that survive generic editing, few-shot examples, and even multi-layer prompting. Output is always actionable, quoted, risk-quantified, and mitigation-ready.
|
||||
|
||||
---
|
||||
|
||||
### System Role (copy verbatim into reviewer agent)
|
||||
|
||||
You are **PromptSentinel v1.2**, a Prompt Auditor for production-grade LLM agent systems.
|
||||
|
||||
Your sole objective is to prevent silent, non-deterministic, or cascading failures in prompts that will be executed millions of times daily across heterogeneous models, tool stacks, and sub-agent contexts.
|
||||
|
||||
**Core Principles (required for every finding)**
|
||||
- Every finding must populate all columns of the output table defined in the Strict Output Format section.
|
||||
- Every finding must include: exact quote/location, failure mode ID or "ADV" (adversarial) / "PATH" (path-trace), production-calibrated risk, and a concrete mitigation with positive, deterministic rewritten example.
|
||||
- Assume independent sub-agent contexts, variable context-window pressure, and model variance.
|
||||
|
||||
---
|
||||
|
||||
### Mandatory Review Procedure
|
||||
|
||||
Execute steps in order. Steps 0-1 run sequentially. Steps 2A/2B/2C run in parallel. Steps 3-4 run sequentially after all parallel tracks complete.
|
||||
|
||||
---
|
||||
|
||||
**Step 0: Input Validation**
|
||||
If the input is not a clear LLM instruction prompt (raw code, data table, empty, or fewer than 50 tokens), output exactly:
|
||||
`INPUT_NOT_A_PROMPT: [one-sentence reason]. Review aborted.`
|
||||
and stop.
|
||||
|
||||
**Step 1: Context & Dependency Inventory**
|
||||
Parse the entire prompt. Derive the **Prompt Title** as follows:
|
||||
- First # or ## heading if present, OR
|
||||
- Filename if provided, OR
|
||||
- First complete sentence (truncated to 80 characters).
|
||||
|
||||
Build an explicit inventory table listing:
|
||||
- All numbered/bulleted steps
|
||||
- All variables, placeholders, file references, prior-step outputs
|
||||
- All conditionals, loops, halts, tool calls
|
||||
- All assumptions about persistent memory or ordering
|
||||
|
||||
Flag any unresolved dependencies.
|
||||
Step 1 is complete when the full inventory table is populated.
|
||||
|
||||
This inventory is shared context for all three parallel tracks below.
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Three Parallel Review Tracks
|
||||
|
||||
Launch all three tracks concurrently. Each track produces findings in the same table format. Tracks are independent — no track reads another track's output.
|
||||
|
||||
---
|
||||
|
||||
**Track A: Adversarial Review (sub-agent)**
|
||||
|
||||
Spawn a sub-agent with the following brief and the full prompt text. Give it the Step 1 inventory for reference. Give it NO catalog, NO checklist, and NO further instructions beyond this brief:
|
||||
|
||||
> You are reviewing an LLM prompt that will execute millions of times daily across different models. Find every way this prompt could fail, produce wrong results, or behave inconsistently. For each issue found, provide: exact quote or location, what goes wrong at scale, and a concrete fix. Use only training knowledge — rely on your own judgment, not any external checklist.
|
||||
|
||||
Track A is complete when the sub-agent returns its findings.
|
||||
|
||||
---
|
||||
|
||||
**Track B: Catalog Scan + Execution Simulation (main agent)**
|
||||
|
||||
**B.1 — Failure Mode Audit**
|
||||
Scan the prompt against all 17 failure modes in the catalog below. Quote every relevant instance. For modes with zero findings, list them in a single summary line (e.g., "Modes 3, 7, 10, 12: no instances found").
|
||||
B.1 is complete when every mode has been explicitly checked.
|
||||
|
||||
**B.2 — Execution Simulation**
|
||||
Simulate the prompt under 3 scenarios:
|
||||
- Scenario A: Small-context model (32k window) under load
|
||||
- Scenario B: Large-context model (200k window), fresh session
|
||||
- Scenario C: Different model vendor with weaker instruction-following
|
||||
|
||||
For each scenario, produce one row in this table:
|
||||
|
||||
| Scenario | Likely Failure Location | Failure Mode | Expected Symptom |
|
||||
|----------|-------------------------|--------------|------------------|
|
||||
|
||||
B.2 is complete when the table contains 3 fully populated rows.
|
||||
|
||||
Track B is complete when both B.1 and B.2 are finished.
|
||||
|
||||
---
|
||||
|
||||
**Track C: Prompt Path Tracer (sub-agent)**
|
||||
|
||||
Spawn a sub-agent with the following brief, the full prompt text, and the Step 1 inventory:
|
||||
|
||||
> You are a mechanical path tracer for LLM prompts. Walk every execution path through this prompt — every conditional, branch, loop, halt, optional step, tool call, and error path. For each path, determine: is the entry condition unambiguous? Is there a defined done-state? Are all required inputs guaranteed to be available? Report only paths with gaps — discard clean paths silently.
|
||||
>
|
||||
> For each finding, provide:
|
||||
> - **Location**: step/section reference
|
||||
> - **Path**: the specific conditional or branch
|
||||
> - **Gap**: what is missing (unclear entry, no done-state, unresolved input)
|
||||
> - **Fix**: concrete rewrite that closes the gap
|
||||
|
||||
Track C is complete when the sub-agent returns its findings.
|
||||
|
||||
---
|
||||
|
||||
**Step 3: Merge & Deduplicate**
|
||||
|
||||
Collect all findings from Tracks A, B, and C. Tag each finding with its source (ADV, catalog mode number, or PATH). Deduplicate by exact quote — when multiple tracks flag the same issue, keep the finding with the most specific mitigation and note all sources.
|
||||
|
||||
Assign severity to each finding: Critical / High / Medium / Low.
|
||||
|
||||
Step 3 is complete when the merged, deduplicated, severity-scored findings table is populated.
|
||||
|
||||
**Step 4: Final Synthesis**
|
||||
|
||||
Format the entire review using the Strict Output Format below. Emit the complete review only after Step 3 is finished.
|
||||
|
||||
---
|
||||
|
||||
### Complete Failure Mode Catalog (Track B — scan all 17)
|
||||
|
||||
1. **Silent Ignoring** — Instructions buried mid-paragraph, nested >2-deep conditionals, parentheticals, or "also remember to..." after long text.
|
||||
2. **Ambiguous Completion** — Steps with no observable done-state or verification criterion ("think about it", "finalize").
|
||||
3. **Context Window Assumptions** — References to "previous step output", "the file we created earlier", or variables not re-passed.
|
||||
4. **Over-specification vs Under-specification** — Wall-of-text detail causing selective attention OR vague verbs inviting hallucination.
|
||||
5. **Non-deterministic Phrasing** — "Consider", "you may", "if appropriate", "best way", "optionally", "try to".
|
||||
6. **Negation Fragility** — "Do NOT", "avoid", "never" (especially multiple or under load).
|
||||
7. **Implicit Ordering** — Step B assumes Step A completed without explicit sequencing or guardrails.
|
||||
8. **Variable Resolution Gaps** — `{{VAR}}` or "the result from tool X" never initialized upstream.
|
||||
9. **Scope Creep Invitation** — "Explore", "improve", "make it better", open-ended goals without hard boundaries.
|
||||
10. **Halt / Checkpoint Gaps** — Human-in-loop required but no explicit `STOP_AND_WAIT_FOR_HUMAN` or output format that forces pause.
|
||||
11. **Teaching Known Knowledge** — Re-explaining basic facts, tool usage, or reasoning patterns frontier models already know (2026 cutoff).
|
||||
12. **Obsolete Prompting Techniques** — Outdated patterns (vanilla "think step by step" without modern scaffolding, deprecated few-shot styles).
|
||||
13. **Missing Strict Output Schema** — No enforced JSON mode or structured output format.
|
||||
14. **Missing Error Handling** — No recovery instructions for tool failures, timeouts, or malformed inputs.
|
||||
15. **Missing Success Criteria** — No quality gates or measurable completion standards.
|
||||
16. **Monolithic Prompt Anti-pattern** — Single large prompt that should be split into specialized sub-agents.
|
||||
17. **Missing Grounding Instructions** — Factual claims required without explicit requirement to base them on retrieved evidence.
|
||||
|
||||
---
|
||||
|
||||
### Strict Output Format (use this template exactly as shown)
|
||||
|
||||
```markdown
|
||||
# PromptSentinel Review: [Derived Prompt Title]
|
||||
|
||||
**Overall Risk Level:** Critical / High / Medium / Low
|
||||
**Critical Issues:** X | **High:** Y | **Medium:** Z | **Low:** W
|
||||
**Estimated Production Failure Rate if Unfixed:** ~XX% of runs
|
||||
|
||||
## Critical & High Findings
|
||||
| # | Source | Failure Mode | Exact Quote / Location | Risk (High-Volume) | Mitigation & Rewritten Example |
|
||||
|---|--------|--------------|------------------------|--------------------|-------------------------------|
|
||||
| | | | | | |
|
||||
|
||||
## Medium & Low Findings
|
||||
(same table format)
|
||||
|
||||
## Positive Observations
|
||||
(only practices that actively mitigate known failure modes)
|
||||
|
||||
## Recommended Refactor Summary
|
||||
- Highest-leverage changes (bullets)
|
||||
|
||||
## Revised Prompt Sections (Critical/High items only)
|
||||
Provide full rewritten paragraphs/sections with changes clearly marked.
|
||||
|
||||
**Reviewer Confidence:** XX/100
|
||||
**Review Complete** – ready for re-submission or automated patching.
|
||||
```
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
---
|
||||
name: bmad-os-root-cause-analysis
|
||||
description: Analyzes a bug-fix commit or PR and produces a structured Root Cause Analysis report covering what went wrong, why, and what guardrails failed.
|
||||
license: MIT
|
||||
disable-model-invocation: true
|
||||
metadata:
|
||||
author: bmad-code-org
|
||||
version: "1.0.0"
|
||||
compatibility: Requires gh CLI and git repository
|
||||
---
|
||||
|
||||
Read `prompts/instructions.md` and execute.
|
||||
|
|
@ -1,74 +0,0 @@
|
|||
# Bug-Fix Root Cause Analysis
|
||||
|
||||
Analyze a bug-fix commit or PR and produce a structured Root Cause Analysis report.
|
||||
|
||||
## Principles
|
||||
|
||||
- **Direct attribution.** This report names the individual who introduced the defect. Industry convention advocates blameless postmortems. This skill deliberately deviates: naming the individual and trusting them to own it is more respectful than diffusing accountability into systemic abstraction. Direct, factual, not accusatory. If authorship can't be determined confidently, say so.
|
||||
- **Pyramid communication.** The executive summary must convey the full picture. A reader who stops after the first paragraph gets the gist. Everything else is supporting evidence.
|
||||
|
||||
## Preflight
|
||||
|
||||
Verify `gh auth status` and that you're in a git repository. Stop with a clear message if either fails.
|
||||
|
||||
## Execution
|
||||
|
||||
1. **Identify the fix.** Accept whatever the user provides — commit SHA, PR, issue, description. Resolve to the specific fix commit/PR using `gh` and `git`. If ambiguous, ask. Confirm the change is actually a bug fix before proceeding.
|
||||
2. **Gather evidence.** Read the fix diff, PR/issue discussion, and use blame/log to identify the commit that introduced the bug. Collect timeline data.
|
||||
3. **Analyze.** Apply 5 Whys. Classify the root cause. Identify contributing factors.
|
||||
4. **Evaluate guardrails.** Inspect the actual repo configuration (CI workflows, linter configs, test setup) — don't assume. For each applicable guardrail, explain specifically why it missed this bug.
|
||||
5. **Write the report** to `_bmad-output/rca-reports/rca-{YYYY-MM-DD}-{slug}.md`. Present the executive summary in chat.
|
||||
|
||||
## Report Structure
|
||||
|
||||
```markdown
|
||||
# Root Cause Analysis: {Bug Title}
|
||||
|
||||
**Date:** {today}
|
||||
**Fix:** {PR link or commit SHA}
|
||||
**Severity:** {Critical | High | Medium | Low}
|
||||
**Root Cause Category:** {Requirements | Design | Code Logic | Test Gap | Process | Environment/Config}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{One paragraph. What the bug was, root cause, who introduced it and when, detection
|
||||
latency (introduced → detected), severity, and the key preventive recommendation.}
|
||||
|
||||
## What Was the Problem?
|
||||
|
||||
## When Did It Happen?
|
||||
|
||||
| Event | Date | Reference |
|
||||
|-------|------|-----------|
|
||||
| Introduced | | |
|
||||
| Detected | | |
|
||||
| Fixed | | |
|
||||
| **Detection Latency** | **{introduced → detected}** | |
|
||||
|
||||
## Who Caused It?
|
||||
|
||||
{Author, commit/PR that introduced the defect, and the context — what were they
|
||||
trying to do?}
|
||||
|
||||
## How Did It Happen?
|
||||
|
||||
## Why Did It Happen?
|
||||
|
||||
{5 Whys analysis. Root cause category. Contributing factors.}
|
||||
|
||||
## Failed Guardrails Analysis
|
||||
|
||||
| Guardrail | In Place? | Why It Failed |
|
||||
|-----------|-----------|---------------|
|
||||
| | | |
|
||||
|
||||
**Most Critical Failure:** {Which one mattered most and why.}
|
||||
|
||||
## Resolution
|
||||
|
||||
## Corrective & Preventive Actions
|
||||
|
||||
| # | Action | Type | Priority |
|
||||
|---|--------|------|----------|
|
||||
| | | {Prevent/Detect/Mitigate} | |
|
||||
```
|
||||
|
|
@ -56,7 +56,7 @@ _bmad-output
|
|||
.qwen
|
||||
.rovodev
|
||||
.kilocodemodes
|
||||
.claude/commands
|
||||
.claude
|
||||
.codex
|
||||
.github/chatmodes
|
||||
.github/agents
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@
|
|||
* Add CodeBuddy platform support with installer configuration (#1483)
|
||||
* Add LLM audit prompt for file reference conventions - new audit tool using parallel subagents (#1720)
|
||||
* Migrate Codex installer from `.codex/prompts` to `.agents/skills` format to align with Codex CLI changes (#1729)
|
||||
* Convert review-pr and audit-file-refs tools to proper bmad-os skills with slash commands `/bmad-os-review-pr` and `/bmad-os-audit-file-refs` (#1732)
|
||||
* Convert review-pr and audit-file-refs tools to proper bmad-os skills with slash commands `bmad-os-review-pr` and `bmad-os-audit-file-refs` (#1732)
|
||||
|
||||
### 🐛 Bug Fixes
|
||||
|
||||
|
|
@ -365,7 +365,7 @@ V6 Stable Release! The End of Beta!
|
|||
- TEA documentation restructured using Diátaxis framework (25 docs)
|
||||
- Style guide optimized for LLM readers (367 lines, down from 767)
|
||||
- Glossary rewritten using table format (123 lines, down from 373)
|
||||
- README overhaul with numbered command flows and prominent `/bmad-help` callout
|
||||
- README overhaul with numbered command flows and prominent `bmad-help` callout
|
||||
- New workflow map diagram with interactive HTML
|
||||
- New editorial review tasks for document quality
|
||||
- E2E testing methodology for Game Dev Studio
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
|
||||
Traditional AI tools do the thinking for you, producing average results. BMad agents and facilitated workflows act as expert collaborators who guide you through a structured process to bring out your best thinking in partnership with the AI.
|
||||
|
||||
- **AI Intelligent Help** — Ask `/bmad-help` anytime for guidance on what's next
|
||||
- **AI Intelligent Help** — Invoke the `bmad-help` skill anytime for guidance on what's next
|
||||
- **Scale-Domain-Adaptive** — Automatically adjusts planning depth based on project complexity
|
||||
- **Structured Workflows** — Grounded in agile best practices across analysis, planning, architecture, and implementation
|
||||
- **Specialized Agents** — 12+ domain experts (PM, Architect, Developer, UX, Scrum Master, and more)
|
||||
|
|
@ -40,7 +40,7 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
|
|||
npx bmad-method install
|
||||
```
|
||||
|
||||
> If you are getting a stale beta version, use: `npx bmad-method@6.0.1 install`
|
||||
> Want the newest prerelease build? Use `npx bmad-method@next install`. Expect higher churn than the default install.
|
||||
|
||||
Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, etc.) in your project folder.
|
||||
|
||||
|
|
@ -52,7 +52,7 @@ npx bmad-method install --directory /path/to/project --modules bmm --tools claud
|
|||
|
||||
[See all installation options](https://docs.bmad-method.org/how-to/non-interactive-installation/)
|
||||
|
||||
> **Not sure what to do?** Run `/bmad-help` — it tells you exactly what's next and what's optional. You can also ask questions like `/bmad-help I just finished the architecture, what do I do next?`
|
||||
> **Not sure what to do?** Ask `bmad-help` — it tells you exactly what's next and what's optional. You can also ask questions like `bmad-help I just finished the architecture, what do I do next?`
|
||||
|
||||
## Modules
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
|
||||
传统 AI 工具替你思考，产生平庸的结果。BMad 智能体和辅助工作流充当专家协作者，引导你通过结构化流程，与 AI 的合作发挥最佳思维，产出最有效优秀的结果。
|
||||
|
||||
- **AI 智能帮助** — 随时使用 `/bmad-help` 获取下一步指导
|
||||
- **AI 智能帮助** — 随时使用 `bmad-help` 获取下一步指导
|
||||
- **规模-领域自适应** — 根据项目复杂度自动调整规划深度
|
||||
- **结构化工作流** — 基于分析、规划、架构和实施的敏捷最佳实践
|
||||
- **专业智能体** — 12+ 领域专家（PM、架构师、开发者、UX、Scrum Master 等）
|
||||
|
|
@ -52,7 +52,7 @@ npx bmad-method install --directory /path/to/project --modules bmm --tools claud
|
|||
|
||||
[查看所有安装选项](http://docs.bmad-method.org/how-to/non-interactive-installation/)
|
||||
|
||||
> **不确定该做什么？** 运行 `/bmad-help` — 它会准确告诉你下一步做什么以及什么是可选的。你也可以问诸如 `/bmad-help 我刚刚完成了架构设计，接下来该做什么？` 之类的问题。
|
||||
> **不确定该做什么？** 运行 `bmad-help` — 它会准确告诉你下一步做什么以及什么是可选的。你也可以问诸如 `bmad-help 我刚刚完成了架构设计，接下来该做什么？` 之类的问题。
|
||||
|
||||
## 模块
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ sidebar:
|
|||
|
||||
## Start Here: BMad-Help
|
||||
|
||||
**The fastest way to get answers about BMad is `/bmad-help`.** This intelligent guide will answer upwards of 80% of all questions and is available to you directly in your IDE as you work.
|
||||
**The fastest way to get answers about BMad is the `bmad-help` skill.** This intelligent guide will answer upwards of 80% of all questions and is available to you directly in your IDE as you work.
|
||||
|
||||
BMad-Help is more than a lookup tool — it:
|
||||
- **Inspects your project** to see what's already been completed
|
||||
|
|
@ -18,19 +18,23 @@ BMad-Help is more than a lookup tool — it:
|
|||
|
||||
### How to Use BMad-Help
|
||||
|
||||
Run it with just the skill name:
|
||||
Call it by name in your AI session:
|
||||
|
||||
```
|
||||
/bmad-help
|
||||
bmad-help
|
||||
```
|
||||
|
||||
Or combine it with a natural language query:
|
||||
:::tip
|
||||
You can also use `/bmad-help` or `$bmad-help` depending on your platform, but just `bmad-help` should work everywhere.
|
||||
:::
|
||||
|
||||
Combine it with a natural language query:
|
||||
|
||||
```
|
||||
/bmad-help I have a SaaS idea and know all the features. Where do I start?
|
||||
/bmad-help What are my options for UX design?
|
||||
/bmad-help I'm stuck on the PRD workflow
|
||||
/bmad-help Show me what's been done so far
|
||||
bmad-help I have a SaaS idea and know all the features. Where do I start?
|
||||
bmad-help What are my options for UX design?
|
||||
bmad-help I'm stuck on the PRD workflow
|
||||
bmad-help Show me what's been done so far
|
||||
```
|
||||
|
||||
BMad-Help responds with:
|
||||
|
|
|
|||
|
|
@ -29,6 +29,15 @@ If you want to use a non interactive installer and provide all install options o
|
|||
npx bmad-method install
|
||||
```
|
||||
|
||||
:::tip[Want the newest prerelease build?]
|
||||
Use the `next` dist-tag:
|
||||
```bash
|
||||
npx bmad-method@next install
|
||||
```
|
||||
|
||||
This gets you newer changes earlier, with a higher chance of churn than the default install.
|
||||
:::
|
||||
|
||||
:::tip[Bleeding edge]
|
||||
To install the latest from the main branch (may be unstable):
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ Build software faster using AI-powered workflows with specialized agents that gu
|
|||
|
||||
:::tip[The Easiest Path]
|
||||
**Install** → `npx bmad-method install`
|
||||
**Ask** → `/bmad-help what should I do first?`
|
||||
**Ask** → `bmad-help what should I do first?`
|
||||
**Build** → Let BMad-Help guide you workflow by workflow
|
||||
:::
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ BMad-Help will respond with:
|
|||
BMad-Help doesn't just answer questions — **it automatically runs at the end of every workflow** to tell you exactly what to do next. No guessing, no searching docs — just clear guidance on the next required workflow.
|
||||
|
||||
:::tip[Start Here]
|
||||
After installing BMad, run `/bmad-help` immediately. It will detect what modules you have installed and guide you to the right starting point for your project.
|
||||
After installing BMad, invoke the `bmad-help` skill immediately. It will detect what modules you have installed and guide you to the right starting point for your project.
|
||||
:::
|
||||
|
||||
## Understanding BMad
|
||||
|
|
@ -95,6 +95,8 @@ Open a terminal in your project directory and run:
|
|||
npx bmad-method install
|
||||
```
|
||||
|
||||
If you want the newest prerelease build instead of the default release channel, use `npx bmad-method@next install`.
|
||||
|
||||
When prompted to select modules, choose **BMad Method**.
|
||||
|
||||
The installer creates two folders:
|
||||
|
|
@ -105,14 +107,14 @@ The installer creates two folders:
|
|||
Open your AI IDE in the project folder and run:
|
||||
|
||||
```
|
||||
/bmad-help
|
||||
bmad-help
|
||||
```
|
||||
|
||||
BMad-Help will detect what you've completed and recommend exactly what to do next. You can also ask it questions like "What are my options?" or "I have a SaaS idea, where should I start?"
|
||||
:::
|
||||
|
||||
:::note[How to Load Agents and Run Workflows]
|
||||
Each workflow has a **skill** you invoke in your IDE (e.g., `/bmad-create-prd`). Running a workflow skill automatically loads the appropriate agent — you don't need to load agents separately. You can also invoke an agent directly for general conversation (e.g., `/bmad-pm` for the PM agent).
|
||||
Each workflow has a **skill** you invoke by name in your IDE (e.g., `bmad-create-prd`). Your AI tool will recognize the `bmad-*` name and run it — you don't need to load agents separately. You can also invoke an agent skill directly for general conversation (e.g., `bmad-pm` for the PM agent).
|
||||
:::
|
||||
|
||||
:::caution[Fresh Chats]
|
||||
|
|
@ -126,35 +128,35 @@ Work through phases 1-3. **Use fresh chats for each workflow.**
|
|||
:::tip[Project Context (Optional)]
|
||||
Before starting, consider creating `project-context.md` to document your technical preferences and implementation rules. This ensures all AI agents follow your conventions throughout the project.
|
||||
|
||||
Create it manually at `_bmad-output/project-context.md` or generate it after architecture using `/bmad-generate-project-context`. [Learn more](../explanation/project-context.md).
|
||||
Create it manually at `_bmad-output/project-context.md` or generate it after architecture using `bmad-generate-project-context`. [Learn more](../explanation/project-context.md).
|
||||
:::
|
||||
|
||||
### Phase 1: Analysis (Optional)
|
||||
|
||||
All workflows in this phase are optional:
|
||||
- **brainstorming** (`/bmad-brainstorming`) — Guided ideation
|
||||
- **research** (`/bmad-research`) — Market and technical research
|
||||
- **create-product-brief** (`/bmad-create-product-brief`) — Recommended foundation document
|
||||
- **brainstorming** (`bmad-brainstorming`) — Guided ideation
|
||||
- **research** (`bmad-research`) — Market and technical research
|
||||
- **create-product-brief** (`bmad-create-product-brief`) — Recommended foundation document
|
||||
|
||||
### Phase 2: Planning (Required)
|
||||
|
||||
**For BMad Method and Enterprise tracks:**
|
||||
1. Invoke the **PM agent** (`/bmad-pm`) in a new chat
|
||||
2. Run the `bmad-create-prd` workflow (`/bmad-create-prd`)
|
||||
1. Invoke the **PM agent** (`bmad-pm`) in a new chat
|
||||
2. Run the `bmad-create-prd` workflow (`bmad-create-prd`)
|
||||
3. Output: `PRD.md`
|
||||
|
||||
**For Quick Flow track:**
|
||||
- Use the `bmad-quick-spec` workflow (`/bmad-quick-spec`) instead of PRD, then skip to implementation
|
||||
- Use the `bmad-quick-spec` workflow (`bmad-quick-spec`) instead of PRD, then skip to implementation
|
||||
|
||||
:::note[UX Design (Optional)]
|
||||
If your project has a user interface, invoke the **UX-Designer agent** (`/bmad-ux-designer`) and run the UX design workflow (`/bmad-create-ux-design`) after creating your PRD.
|
||||
If your project has a user interface, invoke the **UX-Designer agent** (`bmad-ux-designer`) and run the UX design workflow (`bmad-create-ux-design`) after creating your PRD.
|
||||
:::
|
||||
|
||||
### Phase 3: Solutioning (BMad Method/Enterprise)
|
||||
|
||||
**Create Architecture**
|
||||
1. Invoke the **Architect agent** (`/bmad-architect`) in a new chat
|
||||
2. Run `bmad-create-architecture` (`/bmad-create-architecture`)
|
||||
1. Invoke the **Architect agent** (`bmad-architect`) in a new chat
|
||||
2. Run `bmad-create-architecture` (`bmad-create-architecture`)
|
||||
3. Output: Architecture document with technical decisions
|
||||
|
||||
**Create Epics and Stories**
|
||||
|
|
@ -163,13 +165,13 @@ If your project has a user interface, invoke the **UX-Designer agent** (`/bmad-u
|
|||
Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
|
||||
:::
|
||||
|
||||
1. Invoke the **PM agent** (`/bmad-pm`) in a new chat
|
||||
2. Run `bmad-create-epics-and-stories` (`/bmad-create-epics-and-stories`)
|
||||
1. Invoke the **PM agent** (`bmad-pm`) in a new chat
|
||||
2. Run `bmad-create-epics-and-stories` (`bmad-create-epics-and-stories`)
|
||||
3. The workflow uses both PRD and Architecture to create technically-informed stories
|
||||
|
||||
**Implementation Readiness Check** *(Highly Recommended)*
|
||||
1. Invoke the **Architect agent** (`/bmad-architect`) in a new chat
|
||||
2. Run `bmad-check-implementation-readiness` (`/bmad-check-implementation-readiness`)
|
||||
1. Invoke the **Architect agent** (`bmad-architect`) in a new chat
|
||||
2. Run `bmad-check-implementation-readiness` (`bmad-check-implementation-readiness`)
|
||||
3. Validates cohesion across all planning documents
|
||||
|
||||
## Step 2: Build Your Project
|
||||
|
|
@ -178,7 +180,7 @@ Once planning is complete, move to implementation. **Each workflow should run in
|
|||
|
||||
### Initialize Sprint Planning
|
||||
|
||||
Invoke the **SM agent** (`/bmad-sm`) and run `bmad-sprint-planning` (`/bmad-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.
|
||||
Invoke the **SM agent** (`bmad-sm`) and run `bmad-sprint-planning` (`bmad-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories.
|
||||
|
||||
### The Build Cycle
|
||||
|
||||
|
|
@ -186,11 +188,11 @@ For each story, repeat this cycle with fresh chats:
|
|||
|
||||
| Step | Agent | Workflow | Command | Purpose |
|
||||
| ---- | ----- | -------------- | -------------------------- | ---------------------------------- |
|
||||
| 1 | SM | `bmad-create-story` | `/bmad-create-story` | Create story file from epic |
|
||||
| 2 | DEV | `bmad-dev-story` | `/bmad-dev-story` | Implement the story |
|
||||
| 3 | DEV | `bmad-code-review` | `/bmad-code-review` | Quality validation *(recommended)* |
|
||||
| 1 | SM | `bmad-create-story` | `bmad-create-story` | Create story file from epic |
|
||||
| 2 | DEV | `bmad-dev-story` | `bmad-dev-story` | Implement the story |
|
||||
| 3 | DEV | `bmad-code-review` | `bmad-code-review` | Quality validation *(recommended)* |
|
||||
|
||||
After completing all stories in an epic, invoke the **SM agent** (`/bmad-sm`) and run `bmad-retrospective` (`/bmad-retrospective`).
|
||||
After completing all stories in an epic, invoke the **SM agent** (`bmad-sm`) and run `bmad-retrospective` (`bmad-retrospective`).
|
||||
|
||||
## What You've Accomplished
|
||||
|
||||
|
|
@ -221,16 +223,16 @@ your-project/
|
|||
|
||||
| Workflow | Command | Agent | Purpose |
|
||||
| ------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------- |
|
||||
| **`bmad-help`** ⭐ | `/bmad-help` | Any | **Your intelligent guide — ask anything!** |
|
||||
| `bmad-create-prd` | `/bmad-create-prd` | PM | Create Product Requirements Document |
|
||||
| `bmad-create-architecture` | `/bmad-create-architecture` | Architect | Create architecture document |
|
||||
| `bmad-generate-project-context` | `/bmad-generate-project-context` | Analyst | Create project context file |
|
||||
| `bmad-create-epics-and-stories` | `/bmad-create-epics-and-stories` | PM | Break down PRD into epics |
|
||||
| `bmad-check-implementation-readiness` | `/bmad-check-implementation-readiness` | Architect | Validate planning cohesion |
|
||||
| `bmad-sprint-planning` | `/bmad-sprint-planning` | SM | Initialize sprint tracking |
|
||||
| `bmad-create-story` | `/bmad-create-story` | SM | Create a story file |
|
||||
| `bmad-dev-story` | `/bmad-dev-story` | DEV | Implement a story |
|
||||
| `bmad-code-review` | `/bmad-code-review` | DEV | Review implemented code |
|
||||
| **`bmad-help`** ⭐ | `bmad-help` | Any | **Your intelligent guide — ask anything!** |
|
||||
| `bmad-create-prd` | `bmad-create-prd` | PM | Create Product Requirements Document |
|
||||
| `bmad-create-architecture` | `bmad-create-architecture` | Architect | Create architecture document |
|
||||
| `bmad-generate-project-context` | `bmad-generate-project-context` | Analyst | Create project context file |
|
||||
| `bmad-create-epics-and-stories` | `bmad-create-epics-and-stories` | PM | Break down PRD into epics |
|
||||
| `bmad-check-implementation-readiness` | `bmad-check-implementation-readiness` | Architect | Validate planning cohesion |
|
||||
| `bmad-sprint-planning` | `bmad-sprint-planning` | SM | Initialize sprint tracking |
|
||||
| `bmad-create-story` | `bmad-create-story` | SM | Create a story file |
|
||||
| `bmad-dev-story` | `bmad-dev-story` | DEV | Implement a story |
|
||||
| `bmad-code-review` | `bmad-code-review` | DEV | Review implemented code |
|
||||
|
||||
## Common Questions
|
||||
|
||||
|
|
@ -238,10 +240,10 @@ your-project/
|
|||
Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation.
|
||||
|
||||
**Can I change my plan later?**
|
||||
Yes. The SM agent has a `bmad-correct-course` workflow (`/bmad-correct-course`) for handling scope changes.
|
||||
Yes. The SM agent has a `bmad-correct-course` workflow (`bmad-correct-course`) for handling scope changes.
|
||||
|
||||
**What if I want to brainstorm first?**
|
||||
Invoke the Analyst agent (`/bmad-analyst`) and run `bmad-brainstorming` (`/bmad-brainstorming`) before starting your PRD.
|
||||
Invoke the Analyst agent (`bmad-analyst`) and run `bmad-brainstorming` (`bmad-brainstorming`) before starting your PRD.
|
||||
|
||||
**Do I need to follow a strict order?**
|
||||
Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above.
|
||||
|
|
@ -249,7 +251,7 @@ Not strictly. Once you learn the flow, you can run workflows directly using the
|
|||
## Getting Help
|
||||
|
||||
:::tip[First Stop: BMad-Help]
|
||||
**Run `/bmad-help` anytime** — it's the fastest way to get unstuck. Ask it anything:
|
||||
**Invoke `bmad-help` anytime** — it's the fastest way to get unstuck. Ask it anything:
|
||||
- "What should I do after installing?"
|
||||
- "I'm stuck on workflow X"
|
||||
- "What are my options for Y?"
|
||||
|
|
@ -264,10 +266,10 @@ BMad-Help inspects your project, detects what you've completed, and tells you ex
|
|||
## Key Takeaways
|
||||
|
||||
:::tip[Remember These]
|
||||
- **Start with `/bmad-help`** — Your intelligent guide that knows your project and options
|
||||
- **Start with `bmad-help`** — Your intelligent guide that knows your project and options
|
||||
- **Always use fresh chats** — Start a new chat for each workflow
|
||||
- **Track matters** — Quick Flow uses quick-spec; Method/Enterprise need PRD and architecture
|
||||
- **BMad-Help runs automatically** — Every workflow ends with guidance on what's next
|
||||
:::
|
||||
|
||||
Ready to start? Install BMad, run `/bmad-help`, and let your intelligent guide lead the way.
|
||||
Ready to start? Install BMad, invoke `bmad-help`, and let your intelligent guide lead the way.
|
||||
|
|
|
|||
|
|
@ -61,16 +61,16 @@ sidebar:
|
|||
|
||||
### BMad-Help：你的起点
|
||||
|
||||
**随时运行 `/bmad-help`，当你不确定下一步该做什么时。** 这个智能指南：
|
||||
**随时运行 `bmad-help`，当你不确定下一步该做什么时。** 这个智能指南：
|
||||
|
||||
- 检查你的项目以查看已经完成了什么
|
||||
- 根据你安装的模块显示选项
|
||||
- 理解自然语言查询
|
||||
|
||||
```
|
||||
/bmad-help 我有一个现有的 Rails 应用，我应该从哪里开始？
|
||||
/bmad-help quick-flow 和完整方法有什么区别？
|
||||
/bmad-help 显示我有哪些可用的工作流程
|
||||
bmad-help 我有一个现有的 Rails 应用，我应该从哪里开始？
|
||||
bmad-help quick-flow 和完整方法有什么区别？
|
||||
bmad-help 显示我有哪些可用的工作流程
|
||||
```
|
||||
|
||||
BMad-Help 还会在**每个工作流程结束时自动运行**，提供关于下一步该做什么的清晰指导。
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ sidebar:
|
|||
|
||||
## 从这里开始：BMad-Help
|
||||
|
||||
**获取关于 BMad 答案的最快方式是 `/bmad-help`。** 这个智能指南可以回答超过 80% 的问题，并且直接在您的 IDE 中可用，方便您工作时使用。
|
||||
**获取关于 BMad 答案的最快方式是 `bmad-help`。** 这个智能指南可以回答超过 80% 的问题，并且直接在您的 IDE 中可用，方便您工作时使用。
|
||||
|
||||
BMad-Help 不仅仅是一个查询工具——它：
|
||||
- **检查您的项目**以查看已完成的内容
|
||||
|
|
@ -21,16 +21,16 @@ BMad-Help 不仅仅是一个查询工具——它：
|
|||
只需使用斜杠命令运行它：
|
||||
|
||||
```
|
||||
/bmad-help
|
||||
bmad-help
|
||||
```
|
||||
|
||||
或者结合自然语言查询：
|
||||
|
||||
```
|
||||
/bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？
|
||||
/bmad-help 我在 UX 设计方面有哪些选择？
|
||||
/bmad-help 我在 PRD 工作流上卡住了
|
||||
/bmad-help 向我展示到目前为止已完成的内容
|
||||
bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？
|
||||
bmad-help 我在 UX 设计方面有哪些选择？
|
||||
bmad-help 我在 PRD 工作流上卡住了
|
||||
bmad-help 向我展示到目前为止已完成的内容
|
||||
```
|
||||
|
||||
BMad-Help 会回应：
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ your-project/
|
|||
|
||||
## 验证安装
|
||||
|
||||
运行 `/bmad-help` 来验证一切正常并查看下一步操作。
|
||||
运行 `bmad-help` 来验证一切正常并查看下一步操作。
|
||||
|
||||
**BMad-Help 是你的智能向导**，它会：
|
||||
- 确认你的安装正常工作
|
||||
|
|
@ -86,8 +86,8 @@ your-project/
|
|||
|
||||
你也可以向它提问：
|
||||
```
|
||||
/bmad-help 我刚安装完成，应该先做什么？
|
||||
/bmad-help 对于 SaaS 项目我有哪些选项？
|
||||
bmad-help 我刚安装完成，应该先做什么？
|
||||
bmad-help 对于 SaaS 项目我有哪些选项？
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ BMad 方法（**B**reakthrough **M**ethod of **A**gile AI **D**riven Development
|
|||
- **[工作流地图](./reference/workflow-map.md)** — BMM 阶段、工作流和上下文管理的可视化概览
|
||||
|
||||
:::tip[只想直接上手？]
|
||||
安装 BMad 并运行 `/bmad-help` — 它会根据您的项目和已安装的模块引导您完成所有操作。
|
||||
安装 BMad 并运行 `bmad-help` — 它会根据您的项目和已安装的模块引导您完成所有操作。
|
||||
:::
|
||||
|
||||
## 如何使用本文档
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ BMad 提供两种开始工作的方式，它们服务于不同的目的。
|
|||
|
||||
| 机制 | 调用方式 | 发生什么 |
|
||||
| --- | --- | --- |
|
||||
| **斜杠命令** | 在 IDE 中输入 `/bmad-...` | 直接加载智能体、运行工作流或执行任务 |
|
||||
| **斜杠命令** | 在 IDE 中输入 `bmad-...` | 直接加载智能体、运行工作流或执行任务 |
|
||||
| **智能体菜单触发器** | 先加载智能体，然后输入简短代码（例如 `DS`） | 智能体解释代码并启动匹配的工作流，同时保持角色设定 |
|
||||
|
||||
智能体菜单触发器需要活动的智能体会话。当您知道要使用哪个工作流时，使用斜杠命令。当您已经与智能体一起工作并希望在不离开对话的情况下切换任务时，使用触发器。
|
||||
|
|
@ -58,13 +58,13 @@ BMad 提供两种开始工作的方式，它们服务于不同的目的。
|
|||
└── ...
|
||||
```
|
||||
|
||||
文件名决定了 IDE 中的斜杠命令名称。例如，文件 `bmad-agent-bmm-dev.md` 注册命令 `/bmad-agent-bmm-dev`。
|
||||
文件名决定了 IDE 中的技能名称。例如，文件 `bmad-agent-bmm-dev.md` 注册技能 `bmad-agent-bmm-dev`。
|
||||
|
||||
## 如何发现您的命令
|
||||
|
||||
在 IDE 中输入 `/bmad` 并使用自动完成功能浏览可用命令。
|
||||
|
||||
运行 `/bmad-help` 获取关于下一步的上下文感知指导。
|
||||
运行 `bmad-help` 获取关于下一步的上下文感知指导。
|
||||
|
||||
:::tip[快速发现]
|
||||
项目中生成的命令文件夹是权威列表。在文件资源管理器中打开它们以查看每个命令及其描述。
|
||||
|
|
@ -78,10 +78,10 @@ BMad 提供两种开始工作的方式，它们服务于不同的目的。
|
|||
|
||||
| 示例命令 | 智能体 | 角色 |
|
||||
| --- | --- | --- |
|
||||
| `/bmad-agent-bmm-dev` | Amelia（开发者） | 严格按照规范实现故事 |
|
||||
| `/bmad-agent-bmm-pm` | John（产品经理） | 创建和验证 PRD |
|
||||
| `/bmad-agent-bmm-architect` | Winston（架构师） | 设计系统架构 |
|
||||
| `/bmad-agent-bmm-sm` | Bob（Scrum Master） | 管理冲刺和故事 |
|
||||
| `bmad-agent-bmm-dev` | Amelia（开发者） | 严格按照规范实现故事 |
|
||||
| `bmad-agent-bmm-pm` | John（产品经理） | 创建和验证 PRD |
|
||||
| `bmad-agent-bmm-architect` | Winston（架构师） | 设计系统架构 |
|
||||
| `bmad-agent-bmm-sm` | Bob（Scrum Master） | 管理冲刺和故事 |
|
||||
|
||||
参见[智能体](./agents.md)获取默认智能体及其触发器的完整列表。
|
||||
|
||||
|
|
@ -91,11 +91,11 @@ BMad 提供两种开始工作的方式，它们服务于不同的目的。
|
|||
|
||||
| 示例命令 | 目的 |
|
||||
| --- | --- |
|
||||
| `/bmad-bmm-create-prd` | 创建产品需求文档 |
|
||||
| `/bmad-bmm-create-architecture` | 设计系统架构 |
|
||||
| `/bmad-bmm-dev-story` | 实现故事 |
|
||||
| `/bmad-bmm-code-review` | 运行代码审查 |
|
||||
| `/bmad-bmm-quick-spec` | 定义临时更改（快速流程） |
|
||||
| `bmad-bmm-create-prd` | 创建产品需求文档 |
|
||||
| `bmad-bmm-create-architecture` | 设计系统架构 |
|
||||
| `bmad-bmm-dev-story` | 实现故事 |
|
||||
| `bmad-bmm-code-review` | 运行代码审查 |
|
||||
| `bmad-bmm-quick-spec` | 定义临时更改（快速流程） |
|
||||
|
||||
参见[工作流地图](./workflow-map.md)获取按阶段组织的完整工作流参考。
|
||||
|
||||
|
|
@ -105,7 +105,7 @@ BMad 提供两种开始工作的方式，它们服务于不同的目的。
|
|||
|
||||
#### BMad-Help：您的智能向导
|
||||
|
||||
**`/bmad-help`** 是您发现下一步操作的主要界面。它不仅仅是一个查找工具——它是一个智能助手，可以：
|
||||
**`bmad-help`** 是您发现下一步操作的主要界面。它不仅仅是一个查找工具——它是一个智能助手，可以：
|
||||
|
||||
- **检查您的项目**以查看已经完成的工作
|
||||
- **理解自然语言查询**——用简单的英语提问
|
||||
|
|
@ -116,19 +116,19 @@ BMad 提供两种开始工作的方式，它们服务于不同的目的。
|
|||
**示例：**
|
||||
|
||||
```
|
||||
/bmad-help
|
||||
/bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？
|
||||
/bmad-help 我在 UX 设计方面有哪些选择？
|
||||
/bmad-help 我在 PRD 工作流上卡住了
|
||||
bmad-help
|
||||
bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？
|
||||
bmad-help 我在 UX 设计方面有哪些选择？
|
||||
bmad-help 我在 PRD 工作流上卡住了
|
||||
```
|
||||
|
||||
#### 其他任务和工具
|
||||
|
||||
| 示例命令 | 目的 |
|
||||
| --- | --- |
|
||||
| `/bmad-shard-doc` | 将大型 Markdown 文件拆分为较小的部分 |
|
||||
| `/bmad-index-docs` | 索引项目文档 |
|
||||
| `/bmad-editorial-review-prose` | 审查文档散文质量 |
|
||||
| `bmad-shard-doc` | 将大型 Markdown 文件拆分为较小的部分 |
|
||||
| `bmad-index-docs` | 索引项目文档 |
|
||||
| `bmad-editorial-review-prose` | 审查文档散文质量 |
|
||||
|
||||
## 命名约定
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ BMad Method（BMM）是 BMad 生态系统中的一个模块，旨在遵循上下
|
|||
|
||||
其基本原理和概念来自敏捷方法论，这些方法论在整个行业中被广泛用作思维框架，并取得了巨大成功。
|
||||
|
||||
如果您在任何时候不确定该做什么，`/bmad-help` 命令将帮助您保持正轨或了解下一步该做什么。您也可以随时参考此文档以获取参考信息——但如果您已经安装了 BMad Method，`/bmad-help` 是完全交互式的，速度要快得多。此外，如果您正在使用扩展了 BMad Method 或添加了其他互补非扩展模块的不同模块——`/bmad-help` 会不断演进以了解所有可用内容，从而为您提供最佳即时建议。
|
||||
如果您在任何时候不确定该做什么，`bmad-help` 命令将帮助您保持正轨或了解下一步该做什么。您也可以随时参考此文档以获取参考信息——但如果您已经安装了 BMad Method，`bmad-help` 是完全交互式的，速度要快得多。此外，如果您正在使用扩展了 BMad Method 或添加了其他互补非扩展模块的不同模块——`bmad-help` 会不断演进以了解所有可用内容，从而为您提供最佳即时建议。
|
||||
|
||||
最后的重要说明：以下每个工作流程都可以通过斜杠命令直接使用您选择的工具运行，或者先加载智能体，然后使用智能体菜单中的条目来运行。
|
||||
|
||||
|
|
@ -84,7 +84,7 @@ BMad Method（BMM）是 BMad 生态系统中的一个模块，旨在遵循上下
|
|||
**如何创建它：**
|
||||
|
||||
- **手动** — 使用您的技术栈和实施规则创建 `_bmad-output/project-context.md`
|
||||
- **生成它** — 运行 `/bmad-bmm-generate-project-context` 以从您的架构或代码库自动生成
|
||||
- **生成它** — 运行 `bmad-bmm-generate-project-context` 以从您的架构或代码库自动生成
|
||||
|
||||
[**了解更多关于 project-context.md**](../explanation/project-context.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ description: 安装 BMad 并构建你的第一个项目
|
|||
|
||||
:::tip[最简单的路径]
|
||||
**安装** → `npx bmad-method install`
|
||||
**询问** → `/bmad-help 我应该先做什么？`
|
||||
**询问** → `bmad-help 我应该先做什么？`
|
||||
**构建** → 让 BMad-Help 逐个工作流地引导你
|
||||
:::
|
||||
|
||||
|
|
@ -40,13 +40,13 @@ description: 安装 BMad 并构建你的第一个项目
|
|||
只需在 AI IDE 中使用斜杠命令运行它：
|
||||
|
||||
```
|
||||
/bmad-help
|
||||
bmad-help
|
||||
```
|
||||
|
||||
或者结合问题以获得上下文感知的指导：
|
||||
|
||||
```
|
||||
/bmad-help 我有一个 SaaS 产品的想法，我已经知道我想要的所有功能。我应该从哪里开始？
|
||||
bmad-help 我有一个 SaaS 产品的想法，我已经知道我想要的所有功能。我应该从哪里开始？
|
||||
```
|
||||
|
||||
BMad-Help 将回应：
|
||||
|
|
@ -59,7 +59,7 @@ BMad-Help 将回应：
|
|||
BMad-Help 不仅回答问题 —— **它会在每个工作流结束时自动运行**，告诉你确切地下一步该做什么。无需猜测，无需搜索文档 —— 只需对下一个必需工作流的清晰指导。
|
||||
|
||||
:::tip[从这里开始]
|
||||
安装 BMad 后，立即运行 `/bmad-help`。它将检测你安装了哪些模块，并引导你找到项目的正确起点。
|
||||
安装 BMad 后，立即运行 `bmad-help`。它将检测你安装了哪些模块，并引导你找到项目的正确起点。
|
||||
:::
|
||||
|
||||
## 了解 BMad
|
||||
|
|
@ -105,14 +105,14 @@ npx bmad-method install
|
|||
在项目文件夹中打开你的 AI IDE 并运行：
|
||||
|
||||
```
|
||||
/bmad-help
|
||||
bmad-help
|
||||
```
|
||||
|
||||
BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么。你也可以问它诸如"我的选项是什么？"或"我有一个 SaaS 想法，我应该从哪里开始？"之类的问题。
|
||||
:::
|
||||
|
||||
:::note[如何加载智能体和运行工作流]
|
||||
每个工作流都有一个你在 IDE 中运行的**斜杠命令**（例如 `/bmad-bmm-create-prd`）。运行工作流命令会自动加载相应的智能体 —— 你不需要单独加载智能体。你也可以直接加载智能体进行一般对话（例如，加载 PM 智能体使用 `/bmad-agent-bmm-pm`）。
|
||||
每个工作流都有一个你在 IDE 中运行的**斜杠命令**（例如 `bmad-bmm-create-prd`）。运行工作流命令会自动加载相应的智能体 —— 你不需要单独加载智能体。你也可以直接加载智能体进行一般对话（例如，加载 PM 智能体使用 `bmad-agent-bmm-pm`）。
|
||||
:::
|
||||
|
||||
:::caution[新对话]
|
||||
|
|
@ -126,35 +126,35 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么
|
|||
:::tip[项目上下文（可选）]
|
||||
在开始之前，考虑创建 `project-context.md` 来记录你的技术偏好和实现规则。这确保所有 AI 智能体在整个项目中遵循你的约定。
|
||||
|
||||
在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `/bmad-bmm-generate-project-context` 生成它。[了解更多](../explanation/project-context.md)。
|
||||
在 `_bmad-output/project-context.md` 手动创建它，或在架构之后使用 `bmad-bmm-generate-project-context` 生成它。[了解更多](../explanation/project-context.md)。
|
||||
:::
|
||||
|
||||
### 阶段 1：分析（可选）
|
||||
|
||||
此阶段中的所有工作流都是可选的：
|
||||
- **头脑风暴**（`/bmad-brainstorming`） — 引导式构思
|
||||
- **研究**（`/bmad-bmm-research`） — 市场和技术研究
|
||||
- **创建产品简报**（`/bmad-bmm-create-product-brief`） — 推荐的基础文档
|
||||
- **头脑风暴**（`bmad-brainstorming`） — 引导式构思
|
||||
- **研究**（`bmad-bmm-research`） — 市场和技术研究
|
||||
- **创建产品简报**（`bmad-bmm-create-product-brief`） — 推荐的基础文档
|
||||
|
||||
### 阶段 2：规划（必需）
|
||||
|
||||
**对于 BMad Method 和 Enterprise 路径：**
|
||||
1. 在新对话中加载 **PM 智能体**（`/bmad-agent-bmm-pm`）
|
||||
2. 运行 `prd` 工作流（`/bmad-bmm-create-prd`）
|
||||
1. 在新对话中加载 **PM 智能体**（`bmad-agent-bmm-pm`）
|
||||
2. 运行 `prd` 工作流（`bmad-bmm-create-prd`）
|
||||
3. 输出：`PRD.md`
|
||||
|
||||
**对于 Quick Flow 路径：**
|
||||
- 使用 `quick-spec` 工作流（`/bmad-bmm-quick-spec`）代替 PRD，然后跳转到实现
|
||||
- 使用 `quick-spec` 工作流（`bmad-bmm-quick-spec`）代替 PRD，然后跳转到实现
|
||||
|
||||
:::note[UX 设计（可选）]
|
||||
如果你的项目有用户界面，在创建 PRD 后加载 **UX-Designer 智能体**（`/bmad-agent-bmm-ux-designer`）并运行 UX 设计工作流（`/bmad-bmm-create-ux-design`）。
|
||||
如果你的项目有用户界面，在创建 PRD 后加载 **UX-Designer 智能体**（`bmad-agent-bmm-ux-designer`）并运行 UX 设计工作流（`bmad-bmm-create-ux-design`）。
|
||||
:::
|
||||
|
||||
### 阶段 3：解决方案设计（BMad Method/Enterprise）
|
||||
|
||||
**创建架构**
|
||||
1. 在新对话中加载 **Architect 智能体**（`/bmad-agent-bmm-architect`）
|
||||
2. 运行 `create-architecture`（`/bmad-bmm-create-architecture`）
|
||||
1. 在新对话中加载 **Architect 智能体**（`bmad-agent-bmm-architect`）
|
||||
2. 运行 `create-architecture`（`bmad-bmm-create-architecture`）
|
||||
3. 输出：包含技术决策的架构文档
|
||||
|
||||
**创建史诗和故事**
|
||||
|
|
@ -163,13 +163,13 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么
|
|||
史诗和故事现在在架构*之后*创建。这会产生更高质量的故事，因为架构决策（数据库、API 模式、技术栈）直接影响工作应该如何分解。
|
||||
:::
|
||||
|
||||
1. 在新对话中加载 **PM 智能体**（`/bmad-agent-bmm-pm`）
|
||||
2. 运行 `create-epics-and-stories`（`/bmad-bmm-create-epics-and-stories`）
|
||||
1. 在新对话中加载 **PM 智能体**（`bmad-agent-bmm-pm`）
|
||||
2. 运行 `create-epics-and-stories`（`bmad-bmm-create-epics-and-stories`）
|
||||
3. 工作流使用 PRD 和架构来创建技术信息丰富的故事
|
||||
|
||||
**实现就绪检查** *（强烈推荐）*
|
||||
1. 在新对话中加载 **Architect 智能体**（`/bmad-agent-bmm-architect`）
|
||||
2. 运行 `check-implementation-readiness`（`/bmad-bmm-check-implementation-readiness`）
|
||||
1. 在新对话中加载 **Architect 智能体**（`bmad-agent-bmm-architect`）
|
||||
2. 运行 `check-implementation-readiness`（`bmad-bmm-check-implementation-readiness`）
|
||||
3. 验证所有规划文档之间的一致性
|
||||
|
||||
## 步骤 2：构建你的项目
|
||||
|
|
@ -178,7 +178,7 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么
|
|||
|
||||
### 初始化冲刺规划
|
||||
|
||||
加载 **SM 智能体**（`/bmad-agent-bmm-sm`）并运行 `sprint-planning`（`/bmad-bmm-sprint-planning`）。这将创建 `sprint-status.yaml` 来跟踪所有史诗和故事。
|
||||
加载 **SM 智能体**（`bmad-agent-bmm-sm`）并运行 `sprint-planning`（`bmad-bmm-sprint-planning`）。这将创建 `sprint-status.yaml` 来跟踪所有史诗和故事。
|
||||
|
||||
### 构建周期
|
||||
|
||||
|
|
@ -186,11 +186,11 @@ BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么
|
|||
|
||||
| 步骤 | 智能体 | 工作流 | 命令 | 目的 |
|
||||
| ---- | ------ | ------------ | ----------------------- | ------------------------------- |
|
||||
| 1 | SM | `create-story` | `/bmad-bmm-create-story` | 从史诗创建故事文件 |
|
||||
| 2 | DEV | `dev-story` | `/bmad-bmm-dev-story` | 实现故事 |
|
||||
| 3 | DEV | `code-review` | `/bmad-bmm-code-review` | 质量验证 *（推荐）* |
|
||||
| 1 | SM | `create-story` | `bmad-bmm-create-story` | 从史诗创建故事文件 |
|
||||
| 2 | DEV | `dev-story` | `bmad-bmm-dev-story` | 实现故事 |
|
||||
| 3 | DEV | `code-review` | `bmad-bmm-code-review` | 质量验证 *（推荐）* |
|
||||
|
||||
完成史诗中的所有故事后，加载 **SM 智能体**（`/bmad-agent-bmm-sm`）并运行 `retrospective`（`/bmad-bmm-retrospective`）。
|
||||
完成史诗中的所有故事后，加载 **SM 智能体**（`bmad-agent-bmm-sm`）并运行 `retrospective`（`bmad-bmm-retrospective`）。
|
||||
|
||||
## 你已完成的工作
|
||||
|
||||
|
|
@ -221,16 +221,16 @@ your-project/
|
|||
|
||||
| 工作流 | 命令 | 智能体 | 目的 |
|
||||
| ----------------------------------- | --------------------------------------- | -------- | -------------------------------------------- |
|
||||
| **`help`** ⭐ | `/bmad-help` | 任意 | **你的智能向导 —— 随时询问任何问题！** |
|
||||
| `prd` | `/bmad-bmm-create-prd` | PM | 创建产品需求文档 |
|
||||
| `create-architecture` | `/bmad-bmm-create-architecture` | Architect | 创建架构文档 |
|
||||
| `generate-project-context` | `/bmad-bmm-generate-project-context` | Analyst | 创建项目上下文文件 |
|
||||
| `create-epics-and-stories` | `/bmad-bmm-create-epics-and-stories` | PM | 将 PRD 分解为史诗 |
|
||||
| `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | 验证规划一致性 |
|
||||
| `sprint-planning` | `/bmad-bmm-sprint-planning` | SM | 初始化冲刺跟踪 |
|
||||
| `create-story` | `/bmad-bmm-create-story` | SM | 创建故事文件 |
|
||||
| `dev-story` | `/bmad-bmm-dev-story` | DEV | 实现故事 |
|
||||
| `code-review` | `/bmad-bmm-code-review` | DEV | 审查已实现的代码 |
|
||||
| **`help`** ⭐ | `bmad-help` | 任意 | **你的智能向导 —— 随时询问任何问题！** |
|
||||
| `prd` | `bmad-bmm-create-prd` | PM | 创建产品需求文档 |
|
||||
| `create-architecture` | `bmad-bmm-create-architecture` | Architect | 创建架构文档 |
|
||||
| `generate-project-context` | `bmad-bmm-generate-project-context` | Analyst | 创建项目上下文文件 |
|
||||
| `create-epics-and-stories` | `bmad-bmm-create-epics-and-stories` | PM | 将 PRD 分解为史诗 |
|
||||
| `check-implementation-readiness` | `bmad-bmm-check-implementation-readiness` | Architect | 验证规划一致性 |
|
||||
| `sprint-planning` | `bmad-bmm-sprint-planning` | SM | 初始化冲刺跟踪 |
|
||||
| `create-story` | `bmad-bmm-create-story` | SM | 创建故事文件 |
|
||||
| `dev-story` | `bmad-bmm-dev-story` | DEV | 实现故事 |
|
||||
| `code-review` | `bmad-bmm-code-review` | DEV | 审查已实现的代码 |
|
||||
|
||||
## 常见问题
|
||||
|
||||
|
|
@ -238,10 +238,10 @@ your-project/
|
|||
仅对于 BMad Method 和 Enterprise 路径。Quick Flow 从技术规范跳转到实现。
|
||||
|
||||
**我可以稍后更改我的计划吗？**
|
||||
可以。SM 智能体有一个 `correct-course` 工作流（`/bmad-bmm-correct-course`）用于处理范围变更。
|
||||
可以。SM 智能体有一个 `correct-course` 工作流（`bmad-bmm-correct-course`）用于处理范围变更。
|
||||
|
||||
**如果我想先进行头脑风暴怎么办？**
|
||||
在开始 PRD 之前，加载 Analyst 智能体（`/bmad-agent-bmm-analyst`）并运行 `brainstorming`（`/bmad-brainstorming`）。
|
||||
在开始 PRD 之前，加载 Analyst 智能体（`bmad-agent-bmm-analyst`）并运行 `brainstorming`（`bmad-brainstorming`）。
|
||||
|
||||
**我需要遵循严格的顺序吗？**
|
||||
不一定。一旦你了解了流程，你可以使用上面的快速参考直接运行工作流。
|
||||
|
|
@ -249,7 +249,7 @@ your-project/
|
|||
## 获取帮助
|
||||
|
||||
:::tip[第一站：BMad-Help]
|
||||
**随时运行 `/bmad-help`** —— 这是摆脱困境的最快方式。问它任何问题：
|
||||
**随时运行 `bmad-help`** —— 这是摆脱困境的最快方式。问它任何问题：
|
||||
- "安装后我应该做什么？"
|
||||
- "我在工作流 X 上卡住了"
|
||||
- "我在 Y 方面有什么选项？"
|
||||
|
|
@ -264,13 +264,13 @@ BMad-Help 检查你的项目，检测你已完成的内容，并确切地告诉
|
|||
## 关键要点
|
||||
|
||||
:::tip[记住这些]
|
||||
- **从 `/bmad-help` 开始** — 你的智能向导，了解你的项目和选项
|
||||
- **从 `bmad-help` 开始** — 你的智能向导，了解你的项目和选项
|
||||
- **始终使用新对话** — 为每个工作流开始新对话
|
||||
- **路径很重要** — Quick Flow 使用 quick-spec；Method/Enterprise 需要 PRD 和架构
|
||||
- **BMad-Help 自动运行** — 每个工作流结束时都会提供下一步的指导
|
||||
:::
|
||||
|
||||
准备好开始了吗？安装 BMad，运行 `/bmad-help`，让你的智能向导为你引路。
|
||||
准备好开始了吗？安装 BMad，运行 `bmad-help`，让你的智能向导为你引路。
|
||||
|
||||
---
|
||||
## 术语说明
|
||||
|
|
|
|||
|
|
@ -124,13 +124,21 @@ Saved to: {finalFile}
|
|||
|
||||
Once you are fully satisfied with the spec (ideally after **Adversarial Review** and maybe a few rounds of **Advanced Elicitation**), it is recommended to run implementation in a FRESH CONTEXT for best results.
|
||||
|
||||
Copy this prompt to start dev:
|
||||
Load and follow **Adversarial Review** in a fresh context (recommended for information asymmetry):
|
||||
|
||||
\`\`\`
|
||||
quick-dev {finalFile}
|
||||
/bmad-review-adversarial-general "{finalFile}"
|
||||
\`\`\`
|
||||
|
||||
This ensures the dev agent has clean context focused solely on implementation.
|
||||
Load and follow **development** in a fresh context:
|
||||
|
||||
\`\`\`
|
||||
/quick-dev "{finalFile}"
|
||||
\`\`\`
|
||||
|
||||
_(Both are slash commands — prefix `/` invokes a BMAD skill or workflow.)_
|
||||
|
||||
This ensures the agent has clean context focused solely on its task.
|
||||
```
|
||||
|
||||
b) **HALT and wait for user selection.**
|
||||
|
|
@ -177,7 +185,7 @@ b) **HALT and wait for user selection.**
|
|||
When you're ready to implement, run:
|
||||
|
||||
```
|
||||
quick-dev {finalFile}
|
||||
/quick-dev {finalFile}
|
||||
```
|
||||
|
||||
Ship it!"
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ core,anytime,Party Mode,PM,,_bmad/core/workflows/party-mode/workflow.md,bmad-par
|
|||
core,anytime,bmad-help,BH,,skill:bmad-help,bmad-help,false,,,"Get unstuck by showing what workflow steps come next or answering BMad Method questions.",,
|
||||
core,anytime,Index Docs,ID,,_bmad/core/tasks/index-docs.xml,bmad-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
|
||||
core,anytime,Shard Document,SD,,_bmad/core/tasks/shard-doc.xml,bmad-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
|
||||
core,anytime,Editorial Review - Prose,EP,,_bmad/core/tasks/editorial-review-prose.xml,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
|
||||
core,anytime,Editorial Review - Structure,ES,,_bmad/core/tasks/editorial-review-structure.xml,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
|
||||
core,anytime,Editorial Review - Prose,EP,,skill:bmad-editorial-review-prose,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
|
||||
core,anytime,Editorial Review - Structure,ES,,skill:bmad-editorial-review-structure,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
|
||||
core,anytime,Adversarial Review (General),AR,,skill:bmad-review-adversarial-general,bmad-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
|
||||
core,anytime,Edge Case Hunter Review,ECH,,skill:bmad-review-edge-case-hunter,bmad-review-edge-case-hunter,false,,,"Walk every branching path and boundary condition in code, report only unhandled edge cases. Use alongside adversarial review for orthogonal coverage - method-driven not attitude-driven.",,
|
||||
|
|
|
|||
|
Can't render this file because it has a wrong number of fields in line 2.
|
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: bmad-editorial-review-prose
|
||||
description: 'Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose'
|
||||
---
|
||||
|
||||
Follow the instructions in [workflow.md](workflow.md).
|
||||
|
|
@ -0,0 +1 @@
|
|||
type: skill
|
||||
|
|
@ -0,0 +1,81 @@
|
|||
# Editorial Review - Prose
|
||||
|
||||
**Goal:** Review text for communication issues that impede comprehension and output suggested fixes in a three-column table.
|
||||
|
||||
**Your Role:** You are a clinical copy-editor: precise, professional, neither warm nor cynical. Apply Microsoft Writing Style Guide principles as your baseline. Focus on communication issues that impede comprehension — not style preferences. NEVER rewrite for preference — only fix genuine issues. Follow ALL steps in the STEPS section IN EXACT ORDER. DO NOT skip steps or change the sequence. HALT immediately when halt-conditions are met. Each action within a step is a REQUIRED action to complete that step.
|
||||
|
||||
**CONTENT IS SACROSANCT:** Never challenge ideas — only clarify how they're expressed.
|
||||
|
||||
**Inputs:**
|
||||
- **content** (required) — Cohesive unit of text to review (markdown, plain text, or text-heavy XML)
|
||||
- **style_guide** (optional) — Project-specific style guide. When provided, overrides all generic principles in this task (except CONTENT IS SACROSANCT). The style guide is the final authority on tone, structure, and language choices.
|
||||
- **reader_type** (optional, default: `humans`) — `humans` for standard editorial, `llm` for precision focus
|
||||
|
||||
|
||||
## PRINCIPLES
|
||||
|
||||
1. **Minimal intervention:** Apply the smallest fix that achieves clarity
|
||||
2. **Preserve structure:** Fix prose within existing structure, never restructure
|
||||
3. **Skip code/markup:** Detect and skip code blocks, frontmatter, structural markup
|
||||
4. **When uncertain:** Flag with a query rather than suggesting a definitive change
|
||||
5. **Deduplicate:** Same issue in multiple places = one entry with locations listed
|
||||
6. **No conflicts:** Merge overlapping fixes into single entries
|
||||
7. **Respect author voice:** Preserve intentional stylistic choices
|
||||
|
||||
> **STYLE GUIDE OVERRIDE:** If a style_guide input is provided, it overrides ALL generic principles in this task (including the Microsoft Writing Style Guide baseline and reader_type-specific priorities). The ONLY exception is CONTENT IS SACROSANCT — never change what ideas say, only how they're expressed. When style guide conflicts with this task, style guide wins.
|
||||
|
||||
|
||||
## STEPS
|
||||
|
||||
### Step 1: Validate Input
|
||||
|
||||
- Check if content is empty or contains fewer than 3 words
|
||||
- If empty or fewer than 3 words: **HALT** with error: "Content too short for editorial review (minimum 3 words required)"
|
||||
- Validate reader_type is `humans` or `llm` (or not provided, defaulting to `humans`)
|
||||
- If reader_type is invalid: **HALT** with error: "Invalid reader_type. Must be 'humans' or 'llm'"
|
||||
- Identify content type (markdown, plain text, XML with text)
|
||||
- Note any code blocks, frontmatter, or structural markup to skip
|
||||
|
||||
### Step 2: Analyze Style
|
||||
|
||||
- Analyze the style, tone, and voice of the input text
|
||||
- Note any intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns)
|
||||
- Calibrate review approach based on reader_type:
|
||||
- If `llm`: Prioritize unambiguous references, consistent terminology, explicit structure, no hedging
|
||||
- If `humans`: Prioritize clarity, flow, readability, natural progression
|
||||
|
||||
### Step 3: Editorial Review (CRITICAL)
|
||||
|
||||
- If style_guide provided: Consult style_guide now and note its key requirements — these override default principles for this review
|
||||
- Review all prose sections (skip code blocks, frontmatter, structural markup)
|
||||
- Identify communication issues that impede comprehension
|
||||
- For each issue, determine the minimal fix that achieves clarity
|
||||
- Deduplicate: If same issue appears multiple times, create one entry listing all locations
|
||||
- Merge overlapping issues into single entries (no conflicting suggestions)
|
||||
- For uncertain fixes, phrase as query: "Consider: [suggestion]?" rather than definitive change
|
||||
- Preserve author voice — do not "improve" intentional stylistic choices
|
||||
|
||||
### Step 4: Output Results
|
||||
|
||||
- If issues found: Output a three-column markdown table with all suggested fixes
|
||||
- If no issues found: Output "No editorial issues identified"
|
||||
|
||||
**Output format:**
|
||||
|
||||
| Original Text | Revised Text | Changes |
|
||||
|---------------|--------------|---------|
|
||||
| The exact original passage | The suggested revision | Brief explanation of what changed and why |
|
||||
|
||||
**Example:**
|
||||
|
||||
| Original Text | Revised Text | Changes |
|
||||
|---------------|--------------|---------|
|
||||
| The system will processes data and it handles errors. | The system processes data and handles errors. | Fixed subject-verb agreement ("will processes" to "processes"); removed redundant "it" |
|
||||
| Users can chose from options (lines 12, 45, 78) | Users can choose from options | Fixed spelling: "chose" to "choose" (appears in 3 locations) |
|
||||
|
||||
|
||||
## HALT CONDITIONS
|
||||
|
||||
- HALT with error if content is empty or fewer than 3 words
|
||||
- HALT with error if reader_type is not `humans` or `llm`
|
||||
- If no issues found after thorough review, output "No editorial issues identified" (this is valid completion, not an error)
|
||||
|
|
@ -0,0 +1,6 @@
|
|||
---
|
||||
name: bmad-editorial-review-structure
|
||||
description: 'Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure'
|
||||
---
|
||||
|
||||
Follow the instructions in [workflow.md](workflow.md).
|
||||
|
|
@ -0,0 +1 @@
|
|||
type: skill
|
||||
|
|
@ -0,0 +1,174 @@
|
|||
# Editorial Review - Structure
|
||||
|
||||
**Goal:** Review document structure and propose substantive changes to improve clarity and flow -- run this BEFORE copy editing.
|
||||
|
||||
**Your Role:** You are a structural editor focused on HIGH-VALUE DENSITY. Brevity IS clarity: concise writing respects limited attention spans and enables effective scanning. Every section must justify its existence -- cut anything that delays understanding. True redundancy is failure. Follow ALL steps in the STEPS section IN EXACT ORDER. DO NOT skip steps or change the sequence. HALT immediately when halt-conditions are met. Each action within a step is a REQUIRED action to complete that step.
|
||||
|
||||
> **STYLE GUIDE OVERRIDE:** If a style_guide input is provided, it overrides ALL generic principles in this task (including human-reader-principles, llm-reader-principles, reader_type-specific priorities, structure-models selection, and the Microsoft Writing Style Guide baseline). The ONLY exception is CONTENT IS SACROSANCT -- never change what ideas say, only how they're expressed. When style guide conflicts with this task, style guide wins.
|
||||
|
||||
**Inputs:**
|
||||
- **content** (required) -- Document to review (markdown, plain text, or structured content)
|
||||
- **style_guide** (optional) -- Project-specific style guide. When provided, overrides all generic principles in this task (except CONTENT IS SACROSANCT). The style guide is the final authority on tone, structure, and language choices.
|
||||
- **purpose** (optional) -- Document's intended purpose (e.g., 'quickstart tutorial', 'API reference', 'conceptual overview')
|
||||
- **target_audience** (optional) -- Who reads this? (e.g., 'new users', 'experienced developers', 'decision makers')
|
||||
- **reader_type** (optional, default: "humans") -- 'humans' (default) preserves comprehension aids; 'llm' optimizes for precision and density
|
||||
- **length_target** (optional) -- Target reduction (e.g., '30% shorter', 'half the length', 'no limit')
|
||||
|
||||
## Principles
|
||||
|
||||
- Comprehension through calibration: Optimize for the minimum words needed to maintain understanding
|
||||
- Front-load value: Critical information comes first; nice-to-know comes last (or goes)
|
||||
- One source of truth: If information appears identically twice, consolidate
|
||||
- Scope discipline: Content that belongs in a different document should be cut or linked
|
||||
- Propose, don't execute: Output recommendations -- user decides what to accept
|
||||
- **CONTENT IS SACROSANCT: Never challenge ideas -- only optimize how they're organized.**
|
||||
|
||||
## Human-Reader Principles
|
||||
|
||||
These elements serve human comprehension and engagement -- preserve unless clearly wasteful:
|
||||
|
||||
- Visual aids: Diagrams, images, and flowcharts anchor understanding
|
||||
- Expectation-setting: "What You'll Learn" helps readers confirm they're in the right place
|
||||
- Reader's Journey: Organize content biologically (linear progression), not logically (database)
|
||||
- Mental models: Overview before details prevents cognitive overload
|
||||
- Warmth: Encouraging tone reduces anxiety for new users
|
||||
- Whitespace: Admonitions and callouts provide visual breathing room
|
||||
- Summaries: Recaps help retention; they're reinforcement, not redundancy
|
||||
- Examples: Concrete illustrations make abstract concepts accessible
|
||||
- Engagement: "Flow" techniques (transitions, variety) are functional, not "fluff" -- they maintain attention
|
||||
|
||||
## LLM-Reader Principles
|
||||
|
||||
When reader_type='llm', optimize for PRECISION and UNAMBIGUITY:
|
||||
|
||||
- Dependency-first: Define concepts before usage to minimize hallucination risk
|
||||
- Cut emotional language, encouragement, and orientation sections
|
||||
- IF concept is well-known from training (e.g., "conventional commits", "REST APIs"): Reference the standard -- don't re-teach it. ELSE: Be explicit -- don't assume the LLM will infer correctly.
|
||||
- Use consistent terminology -- same word for same concept throughout
|
||||
- Eliminate hedging ("might", "could", "generally") -- use direct statements
|
||||
- Prefer structured formats (tables, lists, YAML) over prose
|
||||
- Reference known standards ("conventional commits", "Google style guide") to leverage training
|
||||
- STILL PROVIDE EXAMPLES even for known standards -- grounds the LLM in your specific expectation
|
||||
- Unambiguous references -- no unclear antecedents ("it", "this", "the above")
|
||||
- Note: LLM documents may be LONGER than human docs in some areas (more explicit) while shorter in others (no warmth)
|
||||
|
||||
## Structure Models
|
||||
|
||||
### Tutorial/Guide (Linear)
|
||||
**Applicability:** Tutorials, detailed guides, how-to articles, walkthroughs
|
||||
- Prerequisites: Setup/Context MUST precede action
|
||||
- Sequence: Steps must follow strict chronological or logical dependency order
|
||||
- Goal-oriented: clear 'Definition of Done' at the end
|
||||
|
||||
### Reference/Database
|
||||
**Applicability:** API docs, glossaries, configuration references, cheat sheets
|
||||
- Random Access: No narrative flow required; user jumps to specific item
|
||||
- MECE: Topics are Mutually Exclusive and Collectively Exhaustive
|
||||
- Consistent Schema: Every item follows identical structure (e.g., Signature to Params to Returns)
|
||||
|
||||
### Explanation (Conceptual)
|
||||
**Applicability:** Deep dives, architecture overviews, conceptual guides, whitepapers, project context
|
||||
- Abstract to Concrete: Definition to Context to Implementation/Example
|
||||
- Scaffolding: Complex ideas built on established foundations
|
||||
|
||||
### Prompt/Task Definition (Functional)
|
||||
**Applicability:** BMAD tasks, prompts, system instructions, XML definitions
|
||||
- Meta-first: Inputs, usage constraints, and context defined before instructions
|
||||
- Separation of Concerns: Instructions (logic) separate from Data (content)
|
||||
- Step-by-step: Execution flow must be explicit and ordered
|
||||
|
||||
### Strategic/Context (Pyramid)
|
||||
**Applicability:** PRDs, research reports, proposals, decision records
|
||||
- Top-down: Conclusion/Status/Recommendation starts the document
|
||||
- Grouping: Supporting context grouped logically below the headline
|
||||
- Ordering: Most critical information first
|
||||
- MECE: Arguments/Groups are Mutually Exclusive and Collectively Exhaustive
|
||||
- Evidence: Data supports arguments, never leads
|
||||
|
||||
## STEPS
|
||||
|
||||
### Step 1: Validate Input
|
||||
|
||||
- Check if content is empty or contains fewer than 3 words
|
||||
- If empty or fewer than 3 words, HALT with error: "Content too short for substantive review (minimum 3 words required)"
|
||||
- Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")
|
||||
- If reader_type is invalid, HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"
|
||||
- Identify document type and structure (headings, sections, lists, etc.)
|
||||
- Note the current word count and section count
|
||||
|
||||
### Step 2: Understand Purpose
|
||||
|
||||
- If purpose was provided, use it; otherwise infer from content
|
||||
- If target_audience was provided, use it; otherwise infer from content
|
||||
- Identify the core question the document answers
|
||||
- State in one sentence: "This document exists to help [audience] accomplish [goal]"
|
||||
- Select the most appropriate structural model from Structure Models based on purpose/audience
|
||||
- Note reader_type and which principles apply (Human-Reader Principles or LLM-Reader Principles)
|
||||
|
||||
### Step 3: Structural Analysis (CRITICAL)
|
||||
|
||||
- If style_guide provided, consult style_guide now and note its key requirements -- these override default principles for this analysis
|
||||
- Map the document structure: list each major section with its word count
|
||||
- Evaluate structure against the selected model's primary rules (e.g., 'Does recommendation come first?' for Pyramid)
|
||||
- For each section, answer: Does this directly serve the stated purpose?
|
||||
- If reader_type='humans', for each comprehension aid (visual, summary, example, callout), answer: Does this help readers understand or stay engaged?
|
||||
- Identify sections that could be: cut entirely, merged with another, moved to a different location, or split
|
||||
- Identify true redundancies: identical information repeated without purpose (not summaries or reinforcement)
|
||||
- Identify scope violations: content that belongs in a different document
|
||||
- Identify burying: critical information hidden deep in the document
|
||||
|
||||
### Step 4: Flow Analysis
|
||||
|
||||
- Assess the reader's journey: Does the sequence match how readers will use this?
|
||||
- Identify premature detail: explanation given before the reader needs it
|
||||
- Identify missing scaffolding: complex ideas without adequate setup
|
||||
- Identify anti-patterns: FAQs that should be inline, appendices that should be cut, overviews that repeat the body verbatim
|
||||
- If reader_type='humans', assess pacing: Is there enough whitespace and visual variety to maintain attention?
|
||||
|
||||
### Step 5: Generate Recommendations
|
||||
|
||||
- Compile all findings into prioritized recommendations
|
||||
- Categorize each recommendation: CUT (remove entirely), MERGE (combine sections), MOVE (reorder), CONDENSE (shorten significantly), QUESTION (needs author decision), PRESERVE (explicitly keep -- for elements that might seem cuttable but serve comprehension)
|
||||
- For each recommendation, state the rationale in one sentence
|
||||
- Estimate impact: how many words would this save (or cost, for PRESERVE)?
|
||||
- If length_target was provided, assess whether recommendations meet it
|
||||
- If reader_type='humans' and recommendations would cut comprehension aids, flag with warning: "This cut may impact reader comprehension/engagement"
|
||||
|
||||
### Step 6: Output Results
|
||||
|
||||
- Output document summary (purpose, audience, reader_type, current length)
|
||||
- Output the recommendation list in priority order
|
||||
- Output estimated total reduction if all recommendations accepted
|
||||
- If no recommendations, output: "No substantive changes recommended -- document structure is sound"
|
||||
|
||||
Use the following output format:
|
||||
|
||||
```markdown
|
||||
## Document Summary
|
||||
- **Purpose:** [inferred or provided purpose]
|
||||
- **Audience:** [inferred or provided audience]
|
||||
- **Reader type:** [selected reader type]
|
||||
- **Structure model:** [selected structure model]
|
||||
- **Current length:** [X] words across [Y] sections
|
||||
|
||||
## Recommendations
|
||||
|
||||
### 1. [CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE] - [Section or element name]
|
||||
**Rationale:** [One sentence explanation]
|
||||
**Impact:** ~[X] words
|
||||
**Comprehension note:** [If applicable, note impact on reader understanding]
|
||||
|
||||
### 2. ...
|
||||
|
||||
## Summary
|
||||
- **Total recommendations:** [N]
|
||||
- **Estimated reduction:** [X] words ([Y]% of original)
|
||||
- **Meets length target:** [Yes/No/No target specified]
|
||||
- **Comprehension trade-offs:** [Note any cuts that sacrifice reader engagement for brevity]
|
||||
```
|
||||
|
||||
## HALT CONDITIONS
|
||||
|
||||
- HALT with error if content is empty or fewer than 3 words
|
||||
- HALT with error if reader_type is not "humans" or "llm"
|
||||
- If no structural issues found, output "No substantive changes recommended" (this is valid completion, not an error)
|
||||
|
|
@ -15,24 +15,24 @@
|
|||
|
||||
### Command-Based Workflows
|
||||
When `command` field has a value:
|
||||
- Show the command prefixed with `/` (e.g., `/bmad-bmm-create-prd`)
|
||||
- Show the command as a skill name in backticks (e.g., `bmad-bmm-create-prd`)
|
||||
|
||||
### Skill-Referenced Workflows
|
||||
When `workflow-file` starts with `skill:`:
|
||||
- The value is a skill reference (e.g., `skill:bmad-quick-dev-new-preview`), NOT a file path
|
||||
- Do NOT attempt to resolve or load it as a file path
|
||||
- Display using the `command` column value prefixed with `/` (same as command-based workflows)
|
||||
- Display using the `command` column value as a skill name in backticks (same as command-based workflows)
|
||||
|
||||
### Agent-Based Workflows
|
||||
When `command` field is empty:
|
||||
- User loads agent first via `/agent-command`
|
||||
- User loads agent first by invoking the agent skill (e.g., `bmad-pm`)
|
||||
- Then invokes by referencing the `code` field or describing the `name` field
|
||||
- Do NOT show a slash command — show the code value and agent load instruction instead
|
||||
|
||||
Example presentation for empty command:
|
||||
```
|
||||
Explain Concept (EC)
|
||||
Load: /tech-writer, then ask to "EC about [topic]"
|
||||
Load: tech-writer agent skill, then ask to "EC about [topic]"
|
||||
Agent: Tech Writer
|
||||
Description: Create clear technical explanations with examples...
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,13 +1,3 @@
|
|||
editorial-review-prose.xml:
|
||||
canonicalId: bmad-editorial-review-prose
|
||||
type: task
|
||||
description: "Clinical copy-editor that reviews text for communication issues"
|
||||
|
||||
editorial-review-structure.xml:
|
||||
canonicalId: bmad-editorial-review-structure
|
||||
type: task
|
||||
description: "Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension"
|
||||
|
||||
index-docs.xml:
|
||||
canonicalId: bmad-index-docs
|
||||
type: task
|
||||
|
|
|
|||
|
|
@ -1,102 +0,0 @@
|
|||
<task id="_bmad/core/tasks/editorial-review-prose.xml"
|
||||
name="Editorial Review - Prose"
|
||||
description="Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose">
|
||||
|
||||
<objective>Review text for communication issues that impede comprehension and output suggested fixes in a three-column table</objective>
|
||||
|
||||
<inputs>
|
||||
<input name="content" required="true" desc="Cohesive unit of text to review (markdown, plain text, or text-heavy XML)" />
|
||||
<input name="style_guide" required="false"
|
||||
desc="Project-specific style guide. When provided, overrides all generic
|
||||
principles in this task (except CONTENT IS SACROSANCT). The style guide
|
||||
is the final authority on tone, structure, and language choices." />
|
||||
<input name="reader_type" required="false" default="humans" desc="'humans' (default) for standard editorial, 'llm' for precision focus" />
|
||||
</inputs>
|
||||
|
||||
<llm critical="true">
|
||||
<i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
|
||||
<i>DO NOT skip steps or change the sequence</i>
|
||||
<i>HALT immediately when halt-conditions are met</i>
|
||||
<i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
|
||||
|
||||
<i>You are a clinical copy-editor: precise, professional, neither warm nor cynical</i>
|
||||
<i>Apply Microsoft Writing Style Guide principles as your baseline</i>
|
||||
<i>Focus on communication issues that impede comprehension - not style preferences</i>
|
||||
<i>NEVER rewrite for preference - only fix genuine issues</i>
|
||||
|
||||
<i critical="true">CONTENT IS SACROSANCT: Never challenge ideas—only clarify how they're expressed.</i>
|
||||
|
||||
<principles>
|
||||
<i>Minimal intervention: Apply the smallest fix that achieves clarity</i>
|
||||
<i>Preserve structure: Fix prose within existing structure, never restructure</i>
|
||||
<i>Skip code/markup: Detect and skip code blocks, frontmatter, structural markup</i>
|
||||
<i>When uncertain: Flag with a query rather than suggesting a definitive change</i>
|
||||
<i>Deduplicate: Same issue in multiple places = one entry with locations listed</i>
|
||||
<i>No conflicts: Merge overlapping fixes into single entries</i>
|
||||
<i>Respect author voice: Preserve intentional stylistic choices</i>
|
||||
</principles>
|
||||
<i critical="true">STYLE GUIDE OVERRIDE: If a style_guide input is provided,
|
||||
it overrides ALL generic principles in this task (including the Microsoft
|
||||
Writing Style Guide baseline and reader_type-specific priorities). The ONLY
|
||||
exception is CONTENT IS SACROSANCT—never change what ideas say, only how
|
||||
they're expressed. When style guide conflicts with this task, style guide wins.</i>
|
||||
</llm>
|
||||
|
||||
<flow>
|
||||
<step n="1" title="Validate Input">
|
||||
<action>Check if content is empty or contains fewer than 3 words</action>
|
||||
<action if="empty or fewer than 3 words">HALT with error: "Content too short for editorial review (minimum 3 words required)"</action>
|
||||
<action>Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")</action>
|
||||
<action if="reader_type is invalid">HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"</action>
|
||||
<action>Identify content type (markdown, plain text, XML with text)</action>
|
||||
<action>Note any code blocks, frontmatter, or structural markup to skip</action>
|
||||
</step>
|
||||
|
||||
<step n="2" title="Analyze Style">
|
||||
<action>Analyze the style, tone, and voice of the input text</action>
|
||||
<action>Note any intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns)</action>
|
||||
<action>Calibrate review approach based on reader_type parameter</action>
|
||||
<action if="reader_type='llm'">Prioritize: unambiguous references, consistent terminology, explicit structure, no hedging</action>
|
||||
<action if="reader_type='humans'">Prioritize: clarity, flow, readability, natural progression</action>
|
||||
</step>
|
||||
|
||||
<step n="3" title="Editorial Review" critical="true">
|
||||
<action if="style_guide provided">Consult style_guide now and note its key requirements—these override default principles for this
|
||||
review</action>
|
||||
<action>Review all prose sections (skip code blocks, frontmatter, structural markup)</action>
|
||||
<action>Identify communication issues that impede comprehension</action>
|
||||
<action>For each issue, determine the minimal fix that achieves clarity</action>
|
||||
<action>Deduplicate: If same issue appears multiple times, create one entry listing all locations</action>
|
||||
<action>Merge overlapping issues into single entries (no conflicting suggestions)</action>
|
||||
<action>For uncertain fixes, phrase as query: "Consider: [suggestion]?" rather than definitive change</action>
|
||||
<action>Preserve author voice - do not "improve" intentional stylistic choices</action>
|
||||
</step>
|
||||
|
||||
<step n="4" title="Output Results">
|
||||
<action if="issues found">Output a three-column markdown table with all suggested fixes</action>
|
||||
<action if="no issues found">Output: "No editorial issues identified"</action>
|
||||
|
||||
<output-format>
|
||||
| Original Text | Revised Text | Changes |
|
||||
|---------------|--------------|---------|
|
||||
| The exact original passage | The suggested revision | Brief explanation of what changed and why |
|
||||
</output-format>
|
||||
|
||||
<example title="Correct output format">
|
||||
| Original Text | Revised Text | Changes |
|
||||
|---------------|--------------|---------|
|
||||
| The system will processes data and it handles errors. | The system processes data and handles errors. | Fixed subject-verb
|
||||
agreement ("will processes" to "processes"); removed redundant "it" |
|
||||
| Users can chose from options (lines 12, 45, 78) | Users can choose from options | Fixed spelling: "chose" to "choose" (appears in
|
||||
3 locations) |
|
||||
</example>
|
||||
</step>
|
||||
</flow>
|
||||
|
||||
<halt-conditions>
|
||||
<condition>HALT with error if content is empty or fewer than 3 words</condition>
|
||||
<condition>HALT with error if reader_type is not "humans" or "llm"</condition>
|
||||
<condition>If no issues found after thorough review, output "No editorial issues identified" (this is valid completion, not an error)</condition>
|
||||
</halt-conditions>
|
||||
|
||||
</task>
|
||||
|
|
@ -1,208 +0,0 @@
|
|||
<?xml version="1.0"?>
|
||||
<!-- if possible, run this in a separate subagent or process with read access to the project,
|
||||
but no context except the content to review -->
|
||||
<task id="_bmad/core/tasks/editorial-review-structure.xml"
|
||||
name="Editorial Review - Structure"
|
||||
description="Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure">
|
||||
<objective>Review document structure and propose substantive changes
|
||||
to improve clarity and flow-run this BEFORE copy editing</objective>
|
||||
<inputs>
|
||||
<input name="content" required="true"
|
||||
desc="Document to review (markdown, plain text, or structured content)" />
|
||||
<input name="style_guide" required="false"
|
||||
desc="Project-specific style guide. When provided, overrides all generic
|
||||
principles in this task (except CONTENT IS SACROSANCT). The style guide
|
||||
is the final authority on tone, structure, and language choices." />
|
||||
<input name="purpose" required="false"
|
||||
desc="Document's intended purpose (e.g., 'quickstart tutorial',
|
||||
'API reference', 'conceptual overview')" />
|
||||
<input name="target_audience" required="false"
|
||||
desc="Who reads this? (e.g., 'new users', 'experienced developers',
|
||||
'decision makers')" />
|
||||
<input name="reader_type" required="false" default="humans"
|
||||
desc="'humans' (default) preserves comprehension aids;
|
||||
'llm' optimizes for precision and density" />
|
||||
<input name="length_target" required="false"
|
||||
desc="Target reduction (e.g., '30% shorter', 'half the length',
|
||||
'no limit')" />
|
||||
</inputs>
|
||||
<llm critical="true">
|
||||
<i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
|
||||
<i>DO NOT skip steps or change the sequence</i>
|
||||
<i>HALT immediately when halt-conditions are met</i>
|
||||
<i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
|
||||
<i>You are a structural editor focused on HIGH-VALUE DENSITY</i>
|
||||
<i>Brevity IS clarity: Concise writing respects limited attention spans and enables effective scanning</i>
|
||||
<i>Every section must justify its existence-cut anything that delays understanding</i>
|
||||
<i>True redundancy is failure</i>
|
||||
<principles>
|
||||
<i>Comprehension through calibration: Optimize for the minimum words needed to maintain understanding</i>
|
||||
<i>Front-load value: Critical information comes first; nice-to-know comes last (or goes)</i>
|
||||
<i>One source of truth: If information appears identically twice, consolidate</i>
|
||||
<i>Scope discipline: Content that belongs in a different document should be cut or linked</i>
|
||||
<i>Propose, don't execute: Output recommendations-user decides what to accept</i>
|
||||
<i critical="true">CONTENT IS SACROSANCT: Never challenge ideas—only optimize how they're organized.</i>
|
||||
</principles>
|
||||
<i critical="true">STYLE GUIDE OVERRIDE: If a style_guide input is provided,
|
||||
it overrides ALL generic principles in this task (including human-reader-principles,
|
||||
llm-reader-principles, reader_type-specific priorities, structure-models selection,
|
||||
and the Microsoft Writing Style Guide baseline). The ONLY exception is CONTENT IS
|
||||
SACROSANCT—never change what ideas say, only how they're expressed. When style
|
||||
guide conflicts with this task, style guide wins.</i>
|
||||
<human-reader-principles>
|
||||
<i>These elements serve human comprehension and engagement-preserve unless clearly wasteful:</i>
|
||||
<i>Visual aids: Diagrams, images, and flowcharts anchor understanding</i>
|
||||
<i>Expectation-setting: "What You'll Learn" helps readers confirm they're in the right place</i>
|
||||
<i>Reader's Journey: Organize content biologically (linear progression), not logically (database)</i>
|
||||
<i>Mental models: Overview before details prevents cognitive overload</i>
|
||||
<i>Warmth: Encouraging tone reduces anxiety for new users</i>
|
||||
<i>Whitespace: Admonitions and callouts provide visual breathing room</i>
|
||||
<i>Summaries: Recaps help retention; they're reinforcement, not redundancy</i>
|
||||
<i>Examples: Concrete illustrations make abstract concepts accessible</i>
|
||||
<i>Engagement: "Flow" techniques (transitions, variety) are functional, not "fluff"-they maintain attention</i>
|
||||
</human-reader-principles>
|
||||
<llm-reader-principles>
|
||||
<i>When reader_type='llm', optimize for PRECISION and UNAMBIGUITY:</i>
|
||||
<i>Dependency-first: Define concepts before usage to minimize hallucination risk</i>
|
||||
<i>Cut emotional language, encouragement, and orientation sections</i>
|
||||
<i>
|
||||
IF concept is well-known from training (e.g., "conventional
|
||||
commits", "REST APIs"): Reference the standard-don't re-teach it
|
||||
ELSE: Be explicit-don't assume the LLM will infer correctly
|
||||
</i>
|
||||
<i>Use consistent terminology-same word for same concept throughout</i>
|
||||
<i>Eliminate hedging ("might", "could", "generally")-use direct statements</i>
|
||||
<i>Prefer structured formats (tables, lists, YAML) over prose</i>
|
||||
<i>Reference known standards ("conventional commits", "Google style guide") to leverage training</i>
|
||||
<i>STILL PROVIDE EXAMPLES even for known standards-grounds the LLM in your specific expectation</i>
|
||||
<i>Unambiguous references-no unclear antecedents ("it", "this", "the above")</i>
|
||||
<i>Note: LLM documents may be LONGER than human docs in some areas
|
||||
(more explicit) while shorter in others (no warmth)</i>
|
||||
</llm-reader-principles>
|
||||
<structure-models>
|
||||
<model name="Tutorial/Guide (Linear)" applicability="Tutorials, detailed guides, how-to articles, walkthroughs">
|
||||
<i>Prerequisites: Setup/Context MUST precede action</i>
|
||||
<i>Sequence: Steps must follow strict chronological or logical dependency order</i>
|
||||
<i>Goal-oriented: clear 'Definition of Done' at the end</i>
|
||||
</model>
|
||||
<model name="Reference/Database" applicability="API docs, glossaries, configuration references, cheat sheets">
|
||||
<i>Random Access: No narrative flow required; user jumps to specific item</i>
|
||||
<i>MECE: Topics are Mutually Exclusive and Collectively Exhaustive</i>
|
||||
<i>Consistent Schema: Every item follows identical structure (e.g., Signature to Params to Returns)</i>
|
||||
</model>
|
||||
<model name="Explanation (Conceptual)"
|
||||
applicability="Deep dives, architecture overviews, conceptual guides,
|
||||
whitepapers, project context">
|
||||
<i>Abstract to Concrete: Definition to Context to Implementation/Example</i>
|
||||
<i>Scaffolding: Complex ideas built on established foundations</i>
|
||||
</model>
|
||||
<model name="Prompt/Task Definition (Functional)"
|
||||
applicability="BMAD tasks, prompts, system instructions, XML definitions">
|
||||
<i>Meta-first: Inputs, usage constraints, and context defined before instructions</i>
|
||||
<i>Separation of Concerns: Instructions (logic) separate from Data (content)</i>
|
||||
<i>Step-by-step: Execution flow must be explicit and ordered</i>
|
||||
</model>
|
||||
<model name="Strategic/Context (Pyramid)" applicability="PRDs, research reports, proposals, decision records">
|
||||
<i>Top-down: Conclusion/Status/Recommendation starts the document</i>
|
||||
<i>Grouping: Supporting context grouped logically below the headline</i>
|
||||
<i>Ordering: Most critical information first</i>
|
||||
<i>MECE: Arguments/Groups are Mutually Exclusive and Collectively Exhaustive</i>
|
||||
<i>Evidence: Data supports arguments, never leads</i>
|
||||
</model>
|
||||
</structure-models>
|
||||
</llm>
|
||||
<flow>
|
||||
<step n="1" title="Validate Input">
|
||||
<action>Check if content is empty or contains fewer than 3 words</action>
|
||||
<action if="empty or fewer than 3 words">HALT with error: "Content
|
||||
too short for substantive review (minimum 3 words required)"</action>
|
||||
<action>Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")</action>
|
||||
<action if="reader_type is invalid">HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"</action>
|
||||
<action>Identify document type and structure (headings, sections, lists, etc.)</action>
|
||||
<action>Note the current word count and section count</action>
|
||||
</step>
|
||||
<step n="2" title="Understand Purpose">
|
||||
<action>If purpose was provided, use it; otherwise infer from content</action>
|
||||
<action>If target_audience was provided, use it; otherwise infer from content</action>
|
||||
<action>Identify the core question the document answers</action>
|
||||
<action>State in one sentence: "This document exists to help [audience] accomplish [goal]"</action>
|
||||
<action>Select the most appropriate structural model from structure-models based on purpose/audience</action>
|
||||
<action>Note reader_type and which principles apply (human-reader-principles or llm-reader-principles)</action>
|
||||
</step>
|
||||
<step n="3" title="Structural Analysis" critical="true">
|
||||
<action if="style_guide provided">Consult style_guide now and note its key requirements—these override default principles for this
|
||||
analysis</action>
|
||||
<action>Map the document structure: list each major section with its word count</action>
|
||||
<action>Evaluate structure against the selected model's primary rules
|
||||
(e.g., 'Does recommendation come first?' for Pyramid)</action>
|
||||
<action>For each section, answer: Does this directly serve the stated purpose?</action>
|
||||
<action if="reader_type='humans'">For each comprehension aid (visual,
|
||||
summary, example, callout), answer: Does this help readers
|
||||
understand or stay engaged?</action>
|
||||
<action>Identify sections that could be: cut entirely, merged with
|
||||
another, moved to a different location, or split</action>
|
||||
<action>Identify true redundancies: identical information repeated
|
||||
without purpose (not summaries or reinforcement)</action>
|
||||
<action>Identify scope violations: content that belongs in a different document</action>
|
||||
<action>Identify burying: critical information hidden deep in the document</action>
|
||||
</step>
|
||||
<step n="4" title="Flow Analysis">
|
||||
<action>Assess the reader's journey: Does the sequence match how readers will use this?</action>
|
||||
<action>Identify premature detail: explanation given before the reader needs it</action>
|
||||
<action>Identify missing scaffolding: complex ideas without adequate setup</action>
|
||||
<action>Identify anti-patterns: FAQs that should be inline, appendices
|
||||
that should be cut, overviews that repeat the body verbatim</action>
|
||||
<action if="reader_type='humans'">Assess pacing: Is there enough
|
||||
whitespace and visual variety to maintain attention?</action>
|
||||
</step>
|
||||
<step n="5" title="Generate Recommendations">
|
||||
<action>Compile all findings into prioritized recommendations</action>
|
||||
<action>Categorize each recommendation: CUT (remove entirely),
|
||||
MERGE (combine sections), MOVE (reorder), CONDENSE (shorten
|
||||
significantly), QUESTION (needs author decision), PRESERVE
|
||||
(explicitly keep-for elements that might seem cuttable but
|
||||
serve comprehension)</action>
|
||||
<action>For each recommendation, state the rationale in one sentence</action>
|
||||
<action>Estimate impact: how many words would this save (or cost, for PRESERVE)?</action>
|
||||
<action>If length_target was provided, assess whether recommendations meet it</action>
|
||||
<action if="reader_type='humans' and recommendations would cut
|
||||
comprehension aids">Flag with warning: "This cut may impact
|
||||
reader comprehension/engagement"</action>
|
||||
</step>
|
||||
<step n="6" title="Output Results">
|
||||
<action>Output document summary (purpose, audience, reader_type, current length)</action>
|
||||
<action>Output the recommendation list in priority order</action>
|
||||
<action>Output estimated total reduction if all recommendations accepted</action>
|
||||
<action if="no recommendations">Output: "No substantive changes recommended-document structure is sound"</action>
|
||||
<output-format>
|
||||
## Document Summary
|
||||
- **Purpose:** [inferred or provided purpose]
|
||||
- **Audience:** [inferred or provided audience]
|
||||
- **Reader type:** [selected reader type]
|
||||
- **Structure model:** [selected structure model]
|
||||
- **Current length:** [X] words across [Y] sections
|
||||
|
||||
## Recommendations
|
||||
|
||||
### 1. [CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE] - [Section or element name]
|
||||
**Rationale:** [One sentence explanation]
|
||||
**Impact:** ~[X] words
|
||||
**Comprehension note:** [If applicable, note impact on reader understanding]
|
||||
|
||||
### 2. ...
|
||||
|
||||
## Summary
|
||||
- **Total recommendations:** [N]
|
||||
- **Estimated reduction:** [X] words ([Y]% of original)
|
||||
- **Meets length target:** [Yes/No/No target specified]
|
||||
- **Comprehension trade-offs:** [Note any cuts that sacrifice reader engagement for brevity]
|
||||
</output-format>
|
||||
</step>
|
||||
</flow>
|
||||
<halt-conditions>
|
||||
<condition>HALT with error if content is empty or fewer than 3 words</condition>
|
||||
<condition>HALT with error if reader_type is not "humans" or "llm"</condition>
|
||||
<condition>If no structural issues found, output "No substantive changes
|
||||
recommended" (this is valid completion, not an error)</condition>
|
||||
</halt-conditions>
|
||||
</task>
|
||||
|
|
@ -1415,7 +1415,7 @@ class Installer {
|
|||
` Join our Discord: ${color.dim('https://discord.gg/gk8jAdXWmj')}`,
|
||||
` Star us on GitHub: ${color.dim('https://github.com/bmad-code-org/BMAD-METHOD/')}`,
|
||||
` Subscribe on YouTube: ${color.dim('https://www.youtube.com/@BMadCode')}`,
|
||||
` Run ${color.cyan('/bmad-help')} with your IDE Agent and ask it how to get started`,
|
||||
` Invoke the ${color.cyan('bmad-help')} skill in your IDE Agent to get started`,
|
||||
);
|
||||
|
||||
await prompts.note(lines.join('\n'), 'BMAD is ready to use!');
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ Use backticks with plain workflow name:
|
|||
- **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)
|
||||
- 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.
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 1.3 MiB After Width: | Height: | Size: 5.4 MiB |
Loading…
Reference in New Issue