diff --git a/.augment/code_review_guidelines.yaml b/.augment/code_review_guidelines.yaml index 02e4f2b95..d2b33ef4d 100644 --- a/.augment/code_review_guidelines.yaml +++ b/.augment/code_review_guidelines.yaml @@ -56,17 +56,13 @@ areas: - "src/**/workflows/**" rules: - id: "workflow_entry_point_required" - description: "Every workflow folder must have workflow.yaml, workflow.md, or workflow.xml as entry point" + description: "Every workflow folder must have workflow.md as entry point" severity: "high" - id: "sharded_workflow_steps_folder" description: "Sharded workflows (using workflow.md) must have steps/ folder with numbered files (step-01-*.md, step-02-*.md)" severity: "high" - - id: "standard_workflow_instructions" - description: "Standard workflows using workflow.yaml must include instructions.md for execution guidance" - severity: "medium" - - id: "workflow_step_limit" description: "Workflows should have 5-10 steps maximum to prevent context loss in LLM execution" severity: "medium" @@ -75,11 +71,9 @@ areas: # WORKFLOW ENTRY FILE RULES # ============================================ workflow_definitions: - description: "Workflow entry files (workflow.yaml, workflow.md, workflow.xml)" + description: "Workflow entry files (workflow.md)" globs: - - "src/**/workflows/**/workflow.yaml" - "src/**/workflows/**/workflow.md" - - "src/**/workflows/**/workflow.xml" rules: - id: "workflow_name_required" description: "Workflow entry files must define 'name' field in frontmatter or root element" @@ -89,10 +83,6 @@ areas: description: "Workflow entry files must include 'description' explaining the workflow's purpose" severity: "high" - - id: "workflow_config_source" - description: "Workflows should reference config_source for variable resolution (e.g., {project-root}/_bmad/module/config.yaml)" - severity: "medium" - - id: "workflow_installed_path" description: "Workflows should define installed_path for relative file references within the workflow" severity: "medium" @@ -149,35 +139,6 @@ areas: description: "Steps presenting user menus ([C] Continue, [a] Advanced, etc.) must HALT and wait for response" severity: "high" - # ============================================ - # XML WORKFLOW/TASK RULES - # ============================================ - xml_workflows: - description: "XML-based workflows and tasks" - globs: - - "src/**/workflows/**/*.xml" - - "src/**/tasks/**/*.xml" - rules: - - id: "xml_task_id_required" - description: "XML tasks must have unique 'id' attribute on root task element" - severity: "high" - - - id: "xml_llm_instructions" - description: "XML workflows should include section with critical execution instructions for the agent" - severity: "medium" - - - id: "xml_step_numbering" - description: "XML steps should use n='X' attribute for sequential numbering" - severity: "medium" - - - id: "xml_action_tags" - description: "Use for required actions, for user input (must HALT), for jumps, for conditionals" - severity: "medium" - - - id: "xml_ask_must_halt" - description: " tags require agent to HALT and wait for user response before continuing" - severity: "high" - # ============================================ # WORKFLOW CONTENT QUALITY # ============================================ @@ -185,7 +146,6 @@ areas: description: "Content quality and consistency rules for all workflow files" globs: - "src/**/workflows/**/*.md" - - "src/**/workflows/**/*.yaml" rules: - id: "communication_language_variable" description: "Workflows should use {communication_language} variable for agent output language consistency" diff --git a/.claude/skills/bmad-os-audit-file-refs/SKILL.md b/.claude/skills/bmad-os-audit-file-refs/SKILL.md deleted file mode 100644 index 637bcfd33..000000000 --- a/.claude/skills/bmad-os-audit-file-refs/SKILL.md +++ /dev/null @@ -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. diff --git a/.claude/skills/bmad-os-audit-file-refs/prompts/instructions.md b/.claude/skills/bmad-os-audit-file-refs/prompts/instructions.md deleted file mode 100644 index cf9e3d6e8..000000000 --- a/.claude/skills/bmad-os-audit-file-refs/prompts/instructions.md +++ /dev/null @@ -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." diff --git a/.claude/skills/bmad-os-changelog-social/SKILL.md b/.claude/skills/bmad-os-changelog-social/SKILL.md deleted file mode 100644 index d2e5cda29..000000000 --- a/.claude/skills/bmad-os-changelog-social/SKILL.md +++ /dev/null @@ -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 .. --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. diff --git a/.claude/skills/bmad-os-changelog-social/examples/discord-example.md b/.claude/skills/bmad-os-changelog-social/examples/discord-example.md deleted file mode 100644 index 325e8824e..000000000 --- a/.claude/skills/bmad-os-changelog-social/examples/discord-example.md +++ /dev/null @@ -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! diff --git a/.claude/skills/bmad-os-changelog-social/examples/linkedin-example.md b/.claude/skills/bmad-os-changelog-social/examples/linkedin-example.md deleted file mode 100644 index dc5919e65..000000000 --- a/.claude/skills/bmad-os-changelog-social/examples/linkedin-example.md +++ /dev/null @@ -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 diff --git a/.claude/skills/bmad-os-changelog-social/examples/twitter-example.md b/.claude/skills/bmad-os-changelog-social/examples/twitter-example.md deleted file mode 100644 index d8a0feaed..000000000 --- a/.claude/skills/bmad-os-changelog-social/examples/twitter-example.md +++ /dev/null @@ -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 diff --git a/.claude/skills/bmad-os-diataxis-style-fix/SKILL.md b/.claude/skills/bmad-os-diataxis-style-fix/SKILL.md deleted file mode 100644 index 8a4f69ae6..000000000 --- a/.claude/skills/bmad-os-diataxis-style-fix/SKILL.md +++ /dev/null @@ -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. diff --git a/.claude/skills/bmad-os-diataxis-style-fix/prompts/instructions.md b/.claude/skills/bmad-os-diataxis-style-fix/prompts/instructions.md deleted file mode 100644 index 827e39115..000000000 --- a/.claude/skills/bmad-os-diataxis-style-fix/prompts/instructions.md +++ /dev/null @@ -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. -::: -``` diff --git a/.claude/skills/bmad-os-draft-changelog/SKILL.md b/.claude/skills/bmad-os-draft-changelog/SKILL.md deleted file mode 100644 index aab75dd98..000000000 --- a/.claude/skills/bmad-os-draft-changelog/SKILL.md +++ /dev/null @@ -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. diff --git a/.claude/skills/bmad-os-draft-changelog/prompts/instructions.md b/.claude/skills/bmad-os-draft-changelog/prompts/instructions.md deleted file mode 100644 index ef3feccef..000000000 --- a/.claude/skills/bmad-os-draft-changelog/prompts/instructions.md +++ /dev/null @@ -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 diff --git a/.claude/skills/bmad-os-gh-triage/SKILL.md b/.claude/skills/bmad-os-gh-triage/SKILL.md deleted file mode 100644 index 020fdd4e2..000000000 --- a/.claude/skills/bmad-os-gh-triage/SKILL.md +++ /dev/null @@ -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. diff --git a/.claude/skills/bmad-os-gh-triage/prompts/agent-prompt.md b/.claude/skills/bmad-os-gh-triage/prompts/agent-prompt.md deleted file mode 100644 index 5c0d7d8d8..000000000 --- a/.claude/skills/bmad-os-gh-triage/prompts/agent-prompt.md +++ /dev/null @@ -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. diff --git a/.claude/skills/bmad-os-gh-triage/prompts/instructions.md b/.claude/skills/bmad-os-gh-triage/prompts/instructions.md deleted file mode 100644 index 782d23268..000000000 --- a/.claude/skills/bmad-os-gh-triage/prompts/instructions.md +++ /dev/null @@ -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. diff --git a/.claude/skills/bmad-os-release-module/SKILL.md b/.claude/skills/bmad-os-release-module/SKILL.md deleted file mode 100644 index 557381ee0..000000000 --- a/.claude/skills/bmad-os-release-module/SKILL.md +++ /dev/null @@ -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. diff --git a/.claude/skills/bmad-os-release-module/prompts/instructions.md b/.claude/skills/bmad-os-release-module/prompts/instructions.md deleted file mode 100644 index 157ce0b33..000000000 --- a/.claude/skills/bmad-os-release-module/prompts/instructions.md +++ /dev/null @@ -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 diff --git a/.claude/skills/bmad-os-review-pr/SKILL.md b/.claude/skills/bmad-os-review-pr/SKILL.md deleted file mode 100644 index 67bb05bd5..000000000 --- a/.claude/skills/bmad-os-review-pr/SKILL.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -name: bmad-os-review-pr -description: Adversarial PR review tool (Raven's Verdict). Cynical deep review transformed into professional engineering findings. Use when user asks to 'review a PR' and provides a PR url or id. ---- - -Read `prompts/instructions.md` and execute. diff --git a/.claude/skills/bmad-os-review-pr/prompts/instructions.md b/.claude/skills/bmad-os-review-pr/prompts/instructions.md deleted file mode 100644 index 12d150049..000000000 --- a/.claude/skills/bmad-os-review-pr/prompts/instructions.md +++ /dev/null @@ -1,231 +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. - -## Adversarial Review - -### 1.1 Run Cynical Review - -**INTERNAL PERSONA - Never post this directly:** - -Task: You are a cynical, jaded code reviewer with zero patience for sloppy work. This PR was submitted by a clueless weasel and you expect to find problems. Find at least five issues to fix or improve in it. Number them. Be skeptical of everything. Ultrathink. - -Output format: - -```markdown -### [NUMBER]. [FINDING TITLE] [likely] - -**Severity:** [EMOJI] [LEVEL] - -[DESCRIPTION - be specific, include file:line references] -``` - -Severity scale: - -| Level | Emoji | Meaning | -| -------- | ----- | ------------------------------------------------------- | -| Critical | 🔴 | Security issue, data loss risk, or broken functionality | -| Moderate | 🟡 | Bug, performance issue, or significant code smell | -| Minor | 🟢 | Style, naming, minor improvement opportunity | - -Likely tag: - -- Add `[likely]` to findings with high confidence, e.g. with direct evidence -- Sort findings by severity (Critical → Moderate → Minor), not by confidence - -## Tone Transformation - -**Transform the cynical output into cold engineering professionalism.** - -**Transformation rules:** - -1. Remove all inflammatory language, insults, assumptions about the author -2. Keep all technical substance, file references, severity ratings and likely tag -3. Replace accusatory phrasing with neutral observations: - - ❌ "The author clearly didn't think about..." - - ✅ "This implementation may not account for..." -4. Preserve skepticism as healthy engineering caution: - - ❌ "This will definitely break in production" - - ✅ "This pattern has historically caused issues in production environments" -5. Add the suggested fixes. -6. Keep suggestions actionable and specific - -Output format after transformation: - -```markdown -## PR Review: #{PR_NUMBER} - -**Title:** {PR_TITLE} -**Author:** @{AUTHOR} -**Branch:** {HEAD} → {BASE} - ---- - -### Findings - -[TRANSFORMED FINDINGS HERE] - ---- - -### Summary - -**Critical:** {COUNT} | **Moderate:** {COUNT} | **Minor:** {COUNT} - -[BINARY_FILES_NOTE if any] - ---- - -_Review generated by Raven's Verdict. LLM-produced analysis - findings may be incorrect or lack context. Verify before acting._ -``` - -## 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 diff --git a/.github/ISSUE_TEMPLATE/config.yaml b/.github/ISSUE_TEMPLATE/config.yaml index b4c92ee6c..7e980f119 100644 --- a/.github/ISSUE_TEMPLATE/config.yaml +++ b/.github/ISSUE_TEMPLATE/config.yaml @@ -1,7 +1,7 @@ blank_issues_enabled: false contact_links: - name: 📚 Documentation - url: http://docs.bmad-method.org + url: https://docs.bmad-method.org about: Check the docs first — tutorials, guides, and reference - name: 💬 Discord Community url: https://discord.gg/gk8jAdXWmj diff --git a/.github/ISSUE_TEMPLATE/documentation.yaml b/.github/ISSUE_TEMPLATE/documentation.yaml index 00729a363..6b132c48e 100644 --- a/.github/ISSUE_TEMPLATE/documentation.yaml +++ b/.github/ISSUE_TEMPLATE/documentation.yaml @@ -28,7 +28,7 @@ body: attributes: label: Documentation location description: Where is the documentation that needs improvement? - placeholder: e.g., http://docs.bmad-method.org/tutorials/getting-started/ or "In the README" + placeholder: e.g., https://docs.bmad-method.org/tutorials/getting-started/ or "In the README" validations: required: true diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml new file mode 100644 index 000000000..759ea2621 --- /dev/null +++ b/.github/workflows/publish.yaml @@ -0,0 +1,141 @@ +name: Publish + +on: + push: + branches: [main] + paths: + - "src/**" + - "tools/cli/**" + - "package.json" + workflow_dispatch: + inputs: + channel: + description: "Publish channel" + required: true + default: "latest" + type: choice + options: + - latest + - next + bump: + description: "Version bump type (latest channel only)" + required: false + default: "patch" + type: choice + options: + - patch + - minor + - major + +concurrency: + group: publish + cancel-in-progress: ${{ github.event_name == 'push' }} + +permissions: + id-token: write + contents: write + +jobs: + publish: + if: github.repository == 'bmad-code-org/BMAD-METHOD' && (github.event_name != 'workflow_dispatch' || github.ref == 'refs/heads/main') + runs-on: ubuntu-latest + steps: + - name: Generate GitHub App token + id: app-token + if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest' + uses: actions/create-github-app-token@v2 + with: + app-id: ${{ secrets.RELEASE_APP_ID }} + private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }} + + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }} + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version-file: ".nvmrc" + cache: "npm" + + - name: Ensure trusted publishing toolchain + run: | + # npm trusted publishing requires Node >= 22.14.0 and npm >= 11.5.1. + npm install --global npm@11.6.2 + + - name: Configure git user + if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest' + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + - name: Install dependencies + run: npm ci + + - name: Run tests + run: npm test + + - name: Derive next prerelease version + if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.channel == 'next') + run: | + NEXT_VER=$(npm view bmad-method@next version 2>/dev/null || echo "") + LATEST_VER=$(npm view bmad-method@latest version 2>/dev/null || echo "") + + # Determine the best base version for the next prerelease. + BASE=$(node -e " + const semver = require('semver'); + const next = process.argv[1] || null; + const latest = process.argv[2] || null; + if (!next && !latest) process.exit(0); + if (!next) { console.log(latest); process.exit(0); } + if (!latest) { console.log(next); process.exit(0); } + const nextBase = next.replace(/-next\.\d+$/, ''); + console.log(semver.gt(latest, nextBase) ? latest : next); + " "$NEXT_VER" "$LATEST_VER") + + if [ -n "$BASE" ]; then + npm version "$BASE" --no-git-tag-version --allow-same-version + fi + npm version prerelease --preid=next --no-git-tag-version + + - name: Bump stable version + if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest' + run: 'npm version ${{ inputs.bump }} -m "chore(release): v%s [skip ci]"' + + - name: Publish prerelease to npm + if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.channel == 'next') + run: npm publish --tag next --provenance + + - name: Publish stable release to npm + if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest' + run: npm publish --tag latest --provenance + + - name: Push version commit and tag + if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest' + run: git push origin main --follow-tags + + - name: Create GitHub Release + if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest' + run: | + TAG="v$(node -p 'require("./package.json").version')" + gh release create "$TAG" --generate-notes + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Notify Discord + if: github.event_name == 'workflow_dispatch' && inputs.channel == 'latest' + continue-on-error: true + run: | + set -o pipefail + source .github/scripts/discord-helpers.sh + [ -z "$WEBHOOK" ] && exit 0 + + VERSION=$(node -p 'require("./package.json").version') + RELEASE_URL="${{ github.server_url }}/${{ github.repository }}/releases/tag/v${VERSION}" + MSG=$(printf '📦 **[bmad-method v%s released](<%s>)**' "$VERSION" "$RELEASE_URL" | esc) + + jq -n --arg content "$MSG" '{content: $content}' | curl -sf --retry 2 -X POST "$WEBHOOK" -H "Content-Type: application/json" -d @- + env: + WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }} diff --git a/.gitignore b/.gitignore index a1229c93d..1c84b15de 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,10 @@ build/*.txt # Environment variables .env +# Python +__pycache__/ +.pytest_cache/ + # System files .DS_Store Thumbs.db @@ -40,6 +44,7 @@ CLAUDE.local.md .agents/ z*/ +!docs/zh-cn/ _bmad _bmad-output @@ -55,7 +60,7 @@ _bmad-output .qwen .rovodev .kilocodemodes -.claude/commands +.claude .codex .github/chatmodes .github/agents diff --git a/.npmignore b/.npmignore new file mode 100644 index 000000000..452bb4ba4 --- /dev/null +++ b/.npmignore @@ -0,0 +1,40 @@ +# Development & Testing +test/ +.husky/ +.github/ +.vscode/ +.augment/ +coverage/ +test-output/ + +# Documentation site (users access docs online) +docs/ +website/ + +# Configuration files (development only) +.coderabbit.yaml +.markdownlint-cli2.yaml +.prettierignore +.nvmrc +eslint.config.mjs +prettier.config.mjs + +# Build tools (not needed at runtime) +tools/build-docs.mjs +tools/fix-doc-links.js +tools/validate-doc-links.js +tools/validate-file-refs.js +tools/validate-agent-schema.js + +# Images (branding/marketing only) +banner-bmad-method.png +Wordmark.png + +# Repository metadata +CONTRIBUTING.md +CONTRIBUTORS.md +SECURITY.md +TRADEMARK.md +CHANGELOG.md +CNAME +CODE_OF_CONDUCT.md diff --git a/CHANGELOG.md b/CHANGELOG.md index aa9d101d1..98fb9ac68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,119 @@ # Changelog +## [6.1.0] - 2026-03-12 + +### Highlights + +* Whiteport Design Studio (WDS) module enabled in the installer +* Support @next installation channel (`npx bmad-method@next install`) — get the latest tip of main instead of waiting for the next stable published version +* Everything now installs as a skill — all workflows, agents, and tasks converted to markdown with SKILL.md entrypoints (not yet optimized skills, but unified format) +* An experimental preview of the new Quick Dev is available, which will become the main Phase 4 development tool +* Edge Case Hunter added as a parallel code review layer in Phase 4, improving code quality by exhaustively tracing branching paths and boundary conditions (#1791) +* Documentation now available in Chinese (zh-CN) with complete translation (#1822, #1795) + +### 💥 Breaking Changes + +* Convert entire BMAD method to skills-based architecture with unified skill manifests (#1834) +* Convert all core workflows from YAML+instructions to single workflow.md format +* Migrate all remaining platforms to native Agent Skills format (#1841) +* Remove legacy YAML/XML workflow engine plumbing (#1864) + +### 🎁 Features + +* Add Pi coding agent as supported platform (#1854) +* Add unified skill scanner decoupled from legacy collectors (#1859) +* Add continuous delivery workflows for npm publishing with trusted OIDC publishing (#1872) + +### ♻️ Refactoring + +* Update terminology from "commands" to "skills" across all documentation (#1850) + +### 🐛 Bug Fixes + +* Fix code review removing mandatory minimum issue count that caused infinite review loops (#1913) +* Fix silent loss of brainstorming ideas in PRD by adding reconciliation step (#1914) +* Reduce npm tarball from 533 to 348 files (91% size reduction, 6.2 MB → 555 KB) via .npmignore (#1900) +* Fix party-mode skill conversion review findings (#1919) + +--- + +## [6.0.4] + +### 🎁 Features + +* Add edge case hunter review task - new reusable review task that exhaustively traces branching paths and boundary conditions in code, reporting only unhandled gaps. Method-driven analysis complementary to adversarial review (#1790) + +### 🐛 Bug Fixes + +* Fix brainstorming to not overwrite previous sessions; now prompts to continue existing brainstorming or start a new one when older brainstorming sessions are found +* Fix installer templates - replace legacy `@` path prefixes with explicit `{project-root}` syntax for consistency (#1769) +* Fix edge case hunter - remove zero-findings halt condition that was pressuring the LLM to hallucinate findings when none legitimately exist (#1797) +* Fix broken docs domain references in README and GitHub issue templates (#1777) + +--- + +## [6.0.3] + +### 🎁 Features + +* Add bmad-os-root-cause-analysis skill for analyzing bug-fix commits and producing structured root cause analysis reports with pyramid communication format (#1741) + +### 🐛 Bug Fixes + +* Fix installer to refuse installation when ancestor directory has BMAD commands, preventing duplicate command autocompletion in nested directories (#1735) +* Fix OpenCode integration by replacing unsupported `name` frontmatter with `mode: all` and update directory names to plural form (#1764) +* Fix CSV manifest pipeline double-escaping of quotes that was corrupting output files; switch Gemini templates to single quotes (#1746) +* Fix workflow descriptions to use proper quotes so they format better in skill conversion and don't break yaml front matter +* Fix workflow help task chaining by removing ambiguous "with-argument" clause that caused LLMs to misinterpret help.md as skill calls (#1740) + +### ♻️ Refactoring + +* Standardize all workflow descriptions to use proper quotes to prevent breaking command or skill front matter during skill conversion + +### 📚 Documentation + +* Fix broken TEA hyperlinks to point to new repository URL (#1772) +* Rebrand BMAD acronym to "Build More Architect Dreams" across documentation (#1765) + +--- + +## [6.0.2] + +### 🎁 Features + +* 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) + +### 🐛 Bug Fixes + +* Fix 24 broken step references in create-architecture workflow after directory rename (#1734) +* Fix step file path references in check-implementation-readiness workflow (#1709, #1716) +* Fix 3 broken file references and enable strict file reference validation in CI (#1717) +* Fix Rovo Dev integration with custom installer that generates prompts.yml manifest (#1701) +* Fix 104 relative step file references to use standardized `{project-root}/_bmad/` paths across 68 files (#1722) +* Fix code fence imbalance in step-03-starter.md that caused rendering issues (#1724) +* Remove Windsurf from recommended/preferred IDEs list (#1727) +* Fix default Codex install location from global to project for better defaults (#1698) +* Add npx cache workaround to Quick Start for stale beta versions (#1685) +* Add language instructions to replace placeholder text in Research overview (#1703) +* Ignore `.junie/` IDE integration folder in git and prettier configs (#1719) + +### ♻️ Refactoring + +* Update open source tool skills structure for future plugin migration +* Standardize all workflow descriptions for skill generation with concise format and explicit trigger phrases +* Remove `disable-model-invocation` flag from all IDE installer templates to enable workflow skill calls + +### 📚 Documentation + +* Elevate `bmad-help` as primary on-ramp across all documentation +* Update workflow names with `bmad-bmm-` prefix and standardize table formatting +* Clarify phase routing and catalog path in help task + +--- + ## [6.0.0] V6 Stable Release! The End of Beta! @@ -288,7 +402,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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9c12655f..459195916 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,7 +73,7 @@ After searching, use the [feature request template](https://github.com/bmad-code ### Target Branch -Submit PRs to the `main` branch. We use [trunk-based development](https://trunkbaseddevelopment.com/branch-for-release/): `main` is the trunk where all work lands, and stable release branches receive only cherry-picked fixes. +Submit PRs to the `main` branch. We use trunk-based development. Every push to `main` auto-publishes to `npm` under the `next` tag. Stable releases are cut ~weekly to the `latest` tag. ### PR Size diff --git a/README.md b/README.md index 950811e85..d76519c97 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org) [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj) -**Breakthrough Method of Agile AI Driven Development** — An AI-driven agile development module for the BMad Method Module Ecosystem, the best and most comprehensive Agile AI Driven Development framework that has true scale-adaptive intelligence that adjusts from bug fixes to enterprise systems. +**Build More Architect Dreams** — An AI-driven agile development module for the BMad Method Module Ecosystem, the best and most comprehensive Agile AI Driven Development framework that has true scale-adaptive intelligence that adjusts from bug fixes to enterprise systems. **100% free and open source.** No paywalls. No gated content. No gated Discord. We believe in empowering everyone, not just those who can pay for a gated community or courses. @@ -13,14 +13,24 @@ 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) - **Party Mode** — Bring multiple agent personas into one session to collaborate and discuss - **Complete Lifecycle** — From brainstorming to deployment -[Learn more at **docs.bmad-method.org**](http://docs.bmad-method.org) +[Learn more at **docs.bmad-method.org**](https://docs.bmad-method.org) + +--- + +## 🚀 What's Next for BMad? + +**V6 is here and we're just getting started!** The BMad Method is evolving rapidly with optimizations including Cross Platform Agent Team and Sub Agent inclusion, Skills Architecture, BMad Builder v1, Dev Loop Automation, and so much more in the works. + +**[📍 Check out the complete Roadmap →](https://docs.bmad-method.org/roadmap/)** + +--- ## Quick Start @@ -30,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. @@ -40,9 +50,9 @@ Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, etc.) npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes ``` -[See all installation options](http://docs.bmad-method.org/how-to/non-interactive-installation/) +[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 @@ -52,17 +62,17 @@ BMad Method extends with official modules for specialized domains. Available dur | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | **[BMad Method (BMM)](https://github.com/bmad-code-org/BMAD-METHOD)** | Core framework with 34+ workflows | | **[BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)** | Create custom BMad agents and workflows | -| **[Test Architect (TEA)](https://github.com/bmad-code-org/tea)** | Risk-based test strategy and automation | +| **[Test Architect (TEA)](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)** | Risk-based test strategy and automation | | **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | Game development workflows (Unity, Unreal, Godot) | | **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | Innovation, brainstorming, design thinking | ## Documentation -[BMad Method Docs Site](http://docs.bmad-method.org) — Tutorials, guides, concepts, and reference +[BMad Method Docs Site](https://docs.bmad-method.org) — Tutorials, guides, concepts, and reference **Quick links:** -- [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/) -- [Upgrading from Previous Versions](http://docs.bmad-method.org/how-to/upgrade-to-v6/) +- [Getting Started Tutorial](https://docs.bmad-method.org/tutorials/getting-started/) +- [Upgrading from Previous Versions](https://docs.bmad-method.org/how-to/upgrade-to-v6/) - [Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 000000000..922644e5e --- /dev/null +++ b/README_CN.md @@ -0,0 +1,121 @@ +![BMad Method](banner-bmad-method.png) + +[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org) +[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj) + +**突破性敏捷 AI 驱动开发方法** — 简称 “BMAD 方法论” ，BMAD方法论是由多个模块生态构成的AI驱动敏捷开发模块系统，这是最佳且最全面的敏捷 AI 驱动开发框架，具备真正的规模自适应人工智能，可适应快速开发，适应企业规模化开发。 + +**100% 免费且开源。** 无付费。无内容门槛。无封闭 Discord。我们赋能每个人，我们将为全球现在在人工智能领域发展的普通人提供公平的学习机会。 + +## 为什么选择 BMad 方法？ + +传统 AI 工具替你思考，产生平庸的结果。BMad 智能体和辅助工作流充当专家协作者，引导你通过结构化流程，与 AI 的合作发挥最佳思维，产出最有效优秀的结果。 + +- **AI 智能帮助** — 随时使用 `bmad-help` 获取下一步指导 +- **规模-领域自适应** — 根据项目复杂度自动调整规划深度 +- **结构化工作流** — 基于分析、规划、架构和实施的敏捷最佳实践 +- **专业智能体** — 12+ 领域专家（PM、架构师、开发者、UX、Scrum Master 等） +- **派对模式** — 将多个智能体角色带入一个会话进行协作和讨论 +- **完整生命周期** — 从想法开始（头脑风暴）到部署发布 + +[在 **docs.bmad-method.org** 了解更多](http://docs.bmad-method.org) + +--- + +## 🚀 BMad 的下一步是什么？ + +**V6 已到来，我们才刚刚开始！** BMad 方法正在快速发展，包括跨平台智能体团队和子智能体集成、技能架构、BMad Builder v1、开发循环自动化等优化，以及更多正在开发中的功能。 + +**[📍 查看完整路线图 →](http://docs.bmad-method.org/roadmap/)** + +--- + +## 快速开始 + +**先决条件**：[Node.js](https://nodejs.org) v20+ + +```bash +npx bmad-method install +``` + +> 如果你获得的是过时的测试版，请使用：`npx bmad-method@6.0.1 install` + +按照安装程序提示操作，然后在项目文件夹中打开你的 AI IDE（Claude Code、Cursor 等）。 + +**非交互式安装**（用于 CI/CD）： + +```bash +npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes +``` + +[查看所有安装选项](http://docs.bmad-method.org/how-to/non-interactive-installation/) + +> **不确定该做什么？** 运行 `bmad-help` — 它会准确告诉你下一步做什么以及什么是可选的。你也可以问诸如 `bmad-help 我刚刚完成了架构设计，接下来该做什么？` 之类的问题。 + +## 模块 + +BMad 方法通过官方模块扩展到专业领域。可在安装期间或之后的任何时间使用。 + +| Module | Purpose | +| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | +| **[BMad Method (BMM)](https://github.com/bmad-code-org/BMAD-METHOD)** | 包含 34+ 工作流的核心框架 | +| **[BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)** | 创建自定义 BMad 智能体和工作流 | +| **[Test Architect (TEA)](https://github.com/bmad-code-org/tea)** | 基于风险的测试策略和自动化 | +| **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | 游戏开发工作流（Unity、Unreal、Godot） | +| **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | 创新、头脑风暴、设计思维 | + +## 文档 + +[BMad 方法文档站点](http://docs.bmad-method.org) — 教程、指南、概念和参考 + +**快速链接：** +- [入门教程](http://docs.bmad-method.org/tutorials/getting-started/) +- [从先前版本升级](http://docs.bmad-method.org/how-to/upgrade-to-v6/) +- [测试架构师文档](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) + + +## 社区 + +- [Discord](https://discord.gg/gk8jAdXWmj) — 获取帮助、分享想法、协作 +- [在 YouTube 上订阅](https://www.youtube.com/@BMadCode) — 教程、大师课和播客（2025 年 2 月推出） +- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) — 错误报告和功能请求 +- [讨论](https://github.com/bmad-code-org/BMAD-METHOD/discussions) — 社区对话 + +## 支持 BMad + +BMad 对每个人都是免费的 — 并且永远如此。如果你想支持开发： + +- ⭐ 请点击此页面右上角附近的项目星标图标 +- ☕ [请我喝咖啡](https://buymeacoffee.com/bmad) — 为开发提供动力 +- 🏢 企业赞助 — 在 Discord 上私信 +- 🎤 演讲与媒体 — 可参加会议、播客、采访（在 Discord 上联系 BM） + +## 贡献 + +我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 + +## 许可证 + +MIT 许可证 — 详见 [LICENSE](LICENSE)。 + +--- + +**BMad** 和 **BMAD-METHOD** 是 BMad Code, LLC 的商标。详见 [TRADEMARK.md](TRADEMARK.md)。 + +[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors) + +请参阅 [CONTRIBUTORS.md](CONTRIBUTORS.md) 了解贡献者信息。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 +- **CI/CD**：持续集成/持续部署。一种自动化软件开发实践，用于频繁集成代码更改并自动部署。 +- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。 +- **PM**：产品经理。负责产品规划、需求管理和团队协调的角色。 +- **UX**：用户体验。指用户在使用产品或服务过程中的整体感受和交互体验。 +- **Scrum Master**：Scrum 主管。敏捷开发 Scrum 框架中的角色，负责促进团队遵循 Scrum 流程。 +- **PRD**：产品需求文档。详细描述产品功能、需求和规格的文档。 diff --git a/docs/_STYLE_GUIDE.md b/docs/_STYLE_GUIDE.md index c6e9eff58..99d686df6 100644 --- a/docs/_STYLE_GUIDE.md +++ b/docs/_STYLE_GUIDE.md @@ -59,13 +59,13 @@ Critical warnings only — data loss, security issues | 2 | Planning | Requirements — PRD or tech-spec *(required)* | ``` -**Commands:** +**Skills:** ```md -| Command | Agent | Purpose | +| Skill | Agent | Purpose | | ------------ | ------- | ------------------------------------ | -| `brainstorm` | Analyst | Brainstorm a new project | -| `prd` | PM | Create Product Requirements Document | +| `bmad-brainstorming` | Analyst | Brainstorm a new project | +| `bmad-create-prd` | PM | Create Product Requirements Document | ``` ## Folder Structure Blocks @@ -99,7 +99,7 @@ your-project/ 9. Step 2: [Second Major Task] 10. Step 3: [Third Major Task] 11. What You've Accomplished (summary + folder structure) -12. Quick Reference (commands table) +12. Quick Reference (skills table) 13. Common Questions (FAQ format) 14. Getting Help (community links) 15. Key Takeaways (tip admonition) @@ -111,7 +111,7 @@ your-project/ - [ ] "What You'll Learn" section present - [ ] Prerequisites in admonition - [ ] Quick Path TL;DR admonition at top -- [ ] Tables for phases, commands, agents +- [ ] Tables for phases, skills, agents - [ ] "What You've Accomplished" section present - [ ] Quick Reference table present - [ ] Common Questions section present @@ -243,7 +243,7 @@ your-project/ 1. Title + Hook 2. Items (## for each item) - Brief description (one sentence) - - **Commands:** or **Key Info:** as flat list + - **Skills:** or **Key Info:** as flat list 3. Universal/Shared (## section) (optional) ``` @@ -252,7 +252,7 @@ your-project/ ```text 1. Title + Hook (one sentence purpose) 2. Quick Facts (optional note admonition) - - Module, Command, Input, Output as list + - Module, Skill, Input, Output as list 3. Purpose/Overview (## section) 4. How to Invoke (code block) 5. Key Sections (## for each aspect) @@ -280,7 +280,7 @@ your-project/ - Diagram or table showing organization 3. Major Sections (## for each phase/category) - Items (### for each item) - - Standardized fields: Command, Agent, Input, Output, Description + - Standardized fields: Skill, Agent, Input, Output, Description 4. Next Steps (optional) ``` @@ -353,7 +353,7 @@ Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation. ### Can I change my plan later? -Yes. The SM agent has a `correct-course` workflow for handling scope changes. +Yes. The SM agent has a `bmad-correct-course` workflow for handling scope changes. **Have a question not answered here?** [Open an issue](...) or ask in [Discord](...). ``` diff --git a/docs/explanation/brainstorming.md b/docs/explanation/brainstorming.md index 51aa80e22..68c35b3b1 100644 --- a/docs/explanation/brainstorming.md +++ b/docs/explanation/brainstorming.md @@ -9,7 +9,7 @@ Unlock your creativity through guided exploration. ## What is Brainstorming? -Run `brainstorming` and you've got a creative facilitator pulling ideas out of you - not generating them for you. The AI acts as coach and guide, using proven techniques to create conditions where your best thinking emerges. +Run `bmad-brainstorming` and you've got a creative facilitator pulling ideas out of you - not generating them for you. The AI acts as coach and guide, using proven techniques to create conditions where your best thinking emerges. **Good for:** diff --git a/docs/explanation/party-mode.md b/docs/explanation/party-mode.md index fe25f197d..68c52a292 100644 --- a/docs/explanation/party-mode.md +++ b/docs/explanation/party-mode.md @@ -9,7 +9,7 @@ Get all your AI agents in one conversation. ## What is Party Mode? -Run `party-mode` and you've got your whole AI team in one room - PM, Architect, Dev, UX Designer, whoever you need. BMad Master orchestrates, picking relevant agents per message. Agents respond in character, agree, disagree, and build on each other's ideas. +Run `bmad-party-mode` and you've got your whole AI team in one room - PM, Architect, Dev, UX Designer, whoever you need. BMad Master orchestrates, picking relevant agents per message. Agents respond in character, agree, disagree, and build on each other's ideas. The conversation continues as long as you want. Ask follow-ups, push back on answers, redirect the discussion - it's a real back-and-forth with your agents until you're done. diff --git a/docs/explanation/preventing-agent-conflicts.md b/docs/explanation/preventing-agent-conflicts.md index e611f1c3a..ffa9414d8 100644 --- a/docs/explanation/preventing-agent-conflicts.md +++ b/docs/explanation/preventing-agent-conflicts.md @@ -108,5 +108,5 @@ Common decisions that prevent conflicts: - Document decisions that cross epic boundaries - Focus on conflict-prone areas - Update architecture as you learn -- Use `correct-course` for significant changes +- Use `bmad-correct-course` for significant changes ::: diff --git a/docs/explanation/project-context.md b/docs/explanation/project-context.md index 6522b92a5..7b4eba4ed 100644 --- a/docs/explanation/project-context.md +++ b/docs/explanation/project-context.md @@ -21,12 +21,12 @@ The `project-context.md` file solves this by documenting what agents need to kno Every implementation workflow automatically loads `project-context.md` if it exists. The architect workflow also loads it to respect your technical preferences when designing the architecture. **Loaded by these workflows:** -- `create-architecture` — respects technical preferences during solutioning -- `create-story` — informs story creation with project patterns -- `dev-story` — guides implementation decisions -- `code-review` — validates against project standards -- `quick-dev` — applies patterns when implementing tech-specs -- `sprint-planning`, `retrospective`, `correct-course` — provides project-wide context +- `bmad-create-architecture` — respects technical preferences during solutioning +- `bmad-create-story` — informs story creation with project patterns +- `bmad-dev-story` — guides implementation decisions +- `bmad-code-review` — validates against project standards +- `bmad-quick-dev` — applies patterns when implementing tech-specs +- `bmad-sprint-planning`, `bmad-retrospective`, `bmad-correct-course` — provides project-wide context ## When to Create It @@ -34,10 +34,10 @@ The `project-context.md` file is useful at any stage of a project: | Scenario | When to Create | Purpose | |----------|----------------|---------| -| **New project, before architecture** | Manually, before `create-architecture` | Document your technical preferences so the architect respects them | -| **New project, after architecture** | Via `generate-project-context` or manually | Capture architecture decisions for implementation agents | -| **Existing project** | Via `generate-project-context` | Discover existing patterns so agents follow established conventions | -| **Quick Flow project** | Before or during `quick-dev` | Ensure quick implementation respects your patterns | +| **New project, before architecture** | Manually, before `bmad-create-architecture` | Document your technical preferences so the architect respects them | +| **New project, after architecture** | Via `bmad-generate-project-context` or manually | Capture architecture decisions for implementation agents | +| **Existing project** | Via `bmad-generate-project-context` | Discover existing patterns so agents follow established conventions | +| **Quick Flow project** | Before or during `bmad-quick-dev` | Ensure quick implementation respects your patterns | :::tip[Recommended] For new projects, create it manually before architecture if you have strong technical preferences. Otherwise, generate it after architecture to capture those decisions. @@ -107,20 +107,20 @@ Edit it with your technology stack and implementation rules. The architect and i ### Generate After Architecture -Run the `generate-project-context` workflow after completing your architecture: +Run the `bmad-generate-project-context` workflow after completing your architecture: ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` This scans your architecture document and project files to generate a context file capturing the decisions made. ### Generate for Existing Projects -For existing projects, run `generate-project-context` to discover existing patterns: +For existing projects, run `bmad-generate-project-context` to discover existing patterns: ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine. @@ -150,7 +150,7 @@ The `project-context.md` file is a living document. Update it when: - Patterns evolve during implementation - You identify gaps from agent behavior -You can edit it manually at any time, or re-run `generate-project-context` to update it after significant changes. +You can edit it manually at any time, or re-run `bmad-generate-project-context` to update it after significant changes. :::note[File Location] The default location is `_bmad-output/project-context.md`. Workflows search for it there, and also check `**/project-context.md` anywhere in your project. diff --git a/docs/explanation/quick-dev-new-preview.md b/docs/explanation/quick-dev-new-preview.md new file mode 100644 index 000000000..416fe46a2 --- /dev/null +++ b/docs/explanation/quick-dev-new-preview.md @@ -0,0 +1,73 @@ +--- +title: "Quick Dev New Preview" +description: Reduce human-in-the-loop friction without giving up the checkpoints that protect output quality +sidebar: + order: 2 +--- + +`bmad-quick-dev-new-preview` is an experimental attempt to radically improve Quick Flow: intent in, code changes out, with lower ceremony and fewer human-in-the-loop turns without sacrificing quality. + +It lets the model run longer between checkpoints, then brings the human back only when the task cannot safely continue without human judgment or when it is time to review the end result. + +![Quick Dev New Preview workflow diagram](/diagrams/quick-dev-diagram.png) + +## Why This Exists + +Human-in-the-loop turns are necessary and expensive. + +Current LLMs still fail in predictable ways: they misread intent, fill gaps with confident guesses, drift into unrelated work, and generate noisy review output. At the same time, constant human intervention limits development velocity. Human attention is the bottleneck. + +This experimental version of Quick Flow is an attempt to rebalance that tradeoff. It trusts the model to run unsupervised for longer stretches, but only after the workflow has created a strong enough boundary to make that safe. + +## The Core Design + +### 1. Compress intent first + +The workflow starts by having the human and the model compress the request into one coherent goal. The input can begin as a rough expression of intent, but before the workflow runs autonomously it has to become small enough, clear enough, and contradiction-free enough to execute. + +Intent can come in many forms: a couple of phrases, a bug tracker link, output from plan mode, text copied from a chat session, or even a story number from BMAD's own `epics.md`. In that last case, the workflow will not understand BMAD story-tracking semantics, but it can still take the story itself and run with it. + +This workflow does not eliminate human control. It relocates it to a small number of high-value moments: + +- **Intent clarification** - turning a messy request into one coherent goal without hidden contradictions +- **Spec approval** - confirming that the frozen understanding is the right thing to build +- **Review of the final product** - the primary checkpoint, where the human decides whether the result is acceptable at the end + +### 2. Route to the smallest safe path + +Once the goal is clear, the workflow decides whether this is a true one-shot change or whether it needs the fuller path. Small, zero-blast-radius changes can go straight to implementation. Everything else goes through planning so the model has a stronger boundary before it runs longer on its own. + +### 3. Run longer with less supervision + +After that routing decision, the model can carry more of the work on its own. On the fuller path, the approved spec becomes the boundary the model executes against with less supervision, which is the whole point of the experiment. + +### 4. Diagnose failure at the right layer + +If the implementation is wrong because the intent was wrong, patching the code is the wrong fix. If the code is wrong because the spec was weak, patching the diff is also the wrong fix. The workflow is designed to diagnose where the failure entered the system, go back to that layer, and regenerate from there. + +Review findings are used to decide whether the problem came from intent, spec generation, or local implementation. Only truly local problems get patched locally. + +### 5. Bring the human back only when needed + +The intent interview is human-in-the-loop, but it is not the same kind of interruption as a recurring checkpoint. The workflow tries to keep those recurring checkpoints to a minimum. After the initial shaping of intent, the human mainly comes back when the workflow cannot safely continue without judgment and at the end, when it is time to review the result. + +- **Intent-gap resolution** - stepping back in when review proves the workflow could not safely infer what was meant + +Everything else is a candidate for longer autonomous execution. That tradeoff is deliberate. Older patterns spend more human attention on continuous supervision. Quick Dev New Preview spends more trust on the model, but saves human attention for the moments where human reasoning has the highest leverage. + +## Why the Review System Matters + +The review phase is not just there to find bugs. It is there to route correction without destroying momentum. + +This workflow works best on a platform that can spawn subagents, or at least invoke another LLM through the command line and wait for a result. If your platform does not support that natively, you can add a skill to do it. Context-free subagents are a cornerstone of the review design. + +Agentic reviews often go wrong in two ways: + +- They generate too many findings, forcing the human to sift through noise. +- They derail the current change by surfacing unrelated issues and turning every run into an ad hoc cleanup project. + +Quick Dev New Preview addresses both by treating review as triage. + +Some findings belong to the current change. Some do not. If a finding is incidental rather than causally tied to the current work, the workflow can defer it instead of forcing the human to handle it immediately. That keeps the run focused and prevents random tangents from consuming the budget of attention. + +That triage will sometimes be imperfect. That is acceptable. It is usually better to misjudge some findings than to flood the human with thousands of low-value review comments. The system is optimizing for signal quality, not exhaustive recall. diff --git a/docs/explanation/quick-flow.md b/docs/explanation/quick-flow.md index 6751feee0..25f63affd 100644 --- a/docs/explanation/quick-flow.md +++ b/docs/explanation/quick-flow.md @@ -5,7 +5,11 @@ sidebar: order: 1 --- -Skip the ceremony. Quick Flow takes you from idea to working code in two commands - no Product Brief, no PRD, no Architecture doc. +Skip the ceremony. Quick Flow takes you from idea to working code in two skills - no Product Brief, no PRD, no Architecture doc. + +:::tip[Want a Unified Variant?] +If you want one workflow to clarify, plan, implement, review, and present in a single run, see [Quick Dev New Preview](./quick-dev-new-preview.md). +::: ## When to Use It @@ -23,16 +27,16 @@ Skip the ceremony. Quick Flow takes you from idea to working code in two command - Anything where requirements are unclear or contested :::caution[Scope Creep] -If you start a Quick Flow and realize the scope is bigger than expected, `quick-dev` will detect this and offer to escalate. You can switch to a full PRD workflow at any point without losing your work. +If you start a Quick Flow and realize the scope is bigger than expected, `bmad-quick-dev` will detect this and offer to escalate. You can switch to a full PRD workflow at any point without losing your work. ::: ## How It Works -Quick Flow has two commands, each backed by a structured workflow. You can run them together or independently. +Quick Flow has two skills, each backed by a structured workflow. You can run them together or independently. ### quick-spec: Plan -Run `quick-spec` and Barry (the Quick Flow agent) walks you through a conversational discovery process: +Run `bmad-quick-spec` and Barry (the Quick Flow agent) walks you through a conversational discovery process: 1. **Understand** - You describe what you want to build. Barry scans the codebase to ask informed questions, then captures a problem statement, solution approach, and scope boundaries. 2. **Investigate** - Barry reads relevant files, maps code patterns, identifies files to modify, and documents the technical context. @@ -43,15 +47,15 @@ The output is a `tech-spec-{slug}.md` file saved to your project's implementatio ### quick-dev: Build -Run `quick-dev` and Barry implements the work. It operates in two modes: +Run `bmad-quick-dev` and Barry implements the work. It operates in two modes: - **Tech-spec mode** - Point it at a spec file (`quick-dev tech-spec-auth.md`) and it executes every task in order, writes tests, and verifies acceptance criteria. - **Direct mode** - Give it instructions directly (`quick-dev "refactor the auth middleware"`) and it gathers context, builds a mental plan, and executes. -After implementation, `quick-dev` runs a self-check audit against all tasks and acceptance criteria, then triggers an adversarial code review of the diff. Findings are presented for you to resolve before wrapping up. +After implementation, `bmad-quick-dev` runs a self-check audit against all tasks and acceptance criteria, then triggers an adversarial code review of the diff. Findings are presented for you to resolve before wrapping up. :::tip[Fresh Context] -For best results, run `quick-dev` in a new conversation after finishing `quick-spec`. This gives the implementation agent clean context focused solely on building. +For best results, run `bmad-quick-dev` in a new conversation after finishing `bmad-quick-spec`. This gives the implementation agent clean context focused solely on building. ::: ## What Quick Flow Skips @@ -65,9 +69,9 @@ The full BMad Method produces a Product Brief, PRD, Architecture doc, and Epic/S ## Escalating to Full BMad Method -Quick Flow includes built-in guardrails for scope detection. When you run `quick-dev` with a direct request, it evaluates signals like multi-component mentions, system-level language, and uncertainty about approach. If it detects the work is bigger than a quick flow: +Quick Flow includes built-in guardrails for scope detection. When you run `bmad-quick-dev` with a direct request, it evaluates signals like multi-component mentions, system-level language, and uncertainty about approach. If it detects the work is bigger than a quick flow: -- **Light escalation** - Recommends running `quick-spec` first to create a plan +- **Light escalation** - Recommends running `bmad-quick-spec` first to create a plan - **Heavy escalation** - Recommends switching to the full BMad Method PRD process You can also escalate manually at any time. Your tech-spec work carries forward - it becomes input for the broader planning process rather than being discarded. diff --git a/docs/how-to/established-projects.md b/docs/how-to/established-projects.md index cc36e0f90..3d789fb61 100644 --- a/docs/how-to/established-projects.md +++ b/docs/how-to/established-projects.md @@ -32,7 +32,7 @@ Generate `project-context.md` to capture your existing codebase patterns and con Run the generate project context workflow: ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` This scans your codebase to identify: @@ -55,22 +55,22 @@ Your `docs/` folder should contain succinct, well-organized documentation that a - Architecture - Any other relevant project information -For complex projects, consider using the `document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state. +For complex projects, consider using the `bmad-document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state. ## Step 3: Get Help ### BMad-Help: Your Starting Point -**Run `/bmad-help` anytime you're unsure what to do next.** This intelligent guide: +**Run `bmad-help` anytime you're unsure what to do next.** This intelligent guide: - Inspects your project to see what's already been done - Shows options based on your installed modules - Understands natural language queries ``` -/bmad-help I have an existing Rails app, where should I start? -/bmad-help What's the difference between quick-flow and full method? -/bmad-help Show me what workflows are available +bmad-help I have an existing Rails app, where should I start? +bmad-help What's the difference between quick-flow and full method? +bmad-help Show me what workflows are available ``` BMad-Help also **automatically runs at the end of every workflow**, providing clear guidance on exactly what to do next. @@ -81,7 +81,7 @@ You have two primary options depending on the scope of changes: | Scope | Recommended Approach | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| **Small updates or additions** | Use `quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase BMad Method is likely overkill. | +| **Small updates or additions** | Use `bmad-quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase BMad Method is likely overkill. | | **Major changes or additions** | Start with the BMad Method, applying as much or as little rigor as needed. | ### During PRD Creation diff --git a/docs/how-to/get-answers-about-bmad.md b/docs/how-to/get-answers-about-bmad.md index edefdeacb..c42e69cc8 100644 --- a/docs/how-to/get-answers-about-bmad.md +++ b/docs/how-to/get-answers-about-bmad.md @@ -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 slash command: +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: @@ -81,7 +85,7 @@ https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt :::note[Example] **Q:** "Tell me the fastest way to build something with BMad" -**A:** Use Quick Flow: Run `quick-spec` to write a technical specification, then `quick-dev` to implement it—skipping the full planning phases. +**A:** Use Quick Flow: Run `bmad-quick-spec` to write a technical specification, then `bmad-quick-dev` to implement it—skipping the full planning phases. ::: ## What You Get diff --git a/docs/how-to/install-bmad.md b/docs/how-to/install-bmad.md index 177c2c884..3789c6fa9 100644 --- a/docs/how-to/install-bmad.md +++ b/docs/how-to/install-bmad.md @@ -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 @@ -51,7 +60,11 @@ Pick which AI tools you use: - Cursor - Others -Each tool has its own way of integrating commands. The installer creates tiny prompt files to activate workflows and agents — it just puts them where your tool expects to find them. +Each tool has its own way of integrating skills. The installer creates tiny prompt files to activate workflows and agents — it just puts them where your tool expects to find them. + +:::note[Enabling Skills] +Some platforms require skills to be explicitly enabled in settings before they appear. If you install BMad and don't see the skills, check your platform's settings or ask your AI assistant how to enable skills. +::: ### 4. Choose Modules @@ -71,13 +84,19 @@ your-project/ │ ├── core/ # Required core module │ └── ... ├── _bmad-output/ # Generated artifacts -├── .claude/ # Claude Code commands (if using Claude Code) -└── .kiro/ # Kiro steering files (if using Kiro) +├── .claude/ # Claude Code skills (if using Claude Code) +│ └── skills/ +│ ├── bmad-help/ +│ ├── bmad-persona/ +│ └── ... +└── .cursor/ # Cursor skills (if using Cursor) + └── skills/ + └── ... ``` ## Verify Installation -Run `/bmad-help` to verify everything works and see what to do next. +Run `bmad-help` to verify everything works and see what to do next. **BMad-Help is your intelligent guide** that will: - Confirm your installation is working @@ -86,8 +105,8 @@ Run `/bmad-help` to verify everything works and see what to do next. You can also ask it questions: ``` -/bmad-help I just installed, what should I do first? -/bmad-help What are my options for a SaaS project? +bmad-help I just installed, what should I do first? +bmad-help What are my options for a SaaS project? ``` ## Troubleshooting diff --git a/docs/how-to/project-context.md b/docs/how-to/project-context.md index 105906098..9196733c8 100644 --- a/docs/how-to/project-context.md +++ b/docs/how-to/project-context.md @@ -77,7 +77,7 @@ sections_completed: ['technology_stack', 'critical_rules'] Run the workflow in a fresh chat: ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` The workflow scans your architecture document and project files to generate a context file capturing the decisions made. @@ -87,7 +87,7 @@ The workflow scans your architecture document and project files to generate a co For existing projects, run: ```bash -/bmad-bmm-generate-project-context +bmad-generate-project-context ``` The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine. diff --git a/docs/how-to/quick-fixes.md b/docs/how-to/quick-fixes.md index 76ee5ebe0..d88d7e9d0 100644 --- a/docs/how-to/quick-fixes.md +++ b/docs/how-to/quick-fixes.md @@ -30,18 +30,18 @@ If you are unsure, start with the DEV agent. You can always escalate to Quick Fl ## Steps -### 1. Load the DEV Agent +### 1. Invoke the DEV Agent -Start a **fresh chat** in your AI IDE and load the DEV agent with its slash command: +Start a **fresh chat** in your AI IDE and invoke the DEV agent skill: ```text -/bmad-agent-bmm-dev +bmad-dev ``` -This loads the agent's persona and capabilities into the session. If you decide you need Quick Flow instead, load the **Quick Flow Solo Dev** agent in a fresh chat: +This loads the agent's persona and capabilities into the session. If you decide you need Quick Flow instead, invoke the **Quick Flow Solo Dev** agent skill in a fresh chat: ```text -/bmad-agent-bmm-quick-flow-solo-dev +bmad-quick-flow-solo-dev ``` Once the Solo Dev agent is loaded, describe your change and ask it to create a **quick-spec**. The agent drafts a lightweight spec capturing what you want to change and how. After you approve the quick-spec, tell the agent to start the **Quick Flow dev cycle** -- it will implement the change, run tests, and perform a self-review, all guided by the spec you just approved. diff --git a/docs/how-to/shard-large-documents.md b/docs/how-to/shard-large-documents.md index b10c64fb8..0edac1483 100644 --- a/docs/how-to/shard-large-documents.md +++ b/docs/how-to/shard-large-documents.md @@ -5,7 +5,7 @@ sidebar: order: 8 --- -Use the `shard-doc` tool if you need to split large markdown files into smaller, organized files for better context management. +Use the `bmad-shard-doc` tool if you need to split large markdown files into smaller, organized files for better context management. :::caution[Deprecated] This is no longer recommended, and soon with updated workflows and most major LLMs and tools supporting subprocesses this will be unnecessary. diff --git a/docs/how-to/upgrade-to-v6.md b/docs/how-to/upgrade-to-v6.md index 882640a69..e01d95f00 100644 --- a/docs/how-to/upgrade-to-v6.md +++ b/docs/how-to/upgrade-to-v6.md @@ -33,12 +33,15 @@ When v4 is detected, you can: If you named your bmad method folder something else - you will need to manually remove the folder yourself. -### 3. Clean Up IDE Commands +### 3. Clean Up IDE Skills -Manually remove legacy v4 IDE commands - for example if you have claude, look for any nested folders that start with bmad and remove them: +Manually remove legacy v4 IDE commands/skills - for example if you have Claude Code, look for any nested folders that start with bmad and remove them: -- `.claude/commands/BMad/agents` -- `.claude/commands/BMad/tasks` +- `.claude/commands/` + +The new v6 skills are installed to: + +- `.claude/skills/` ### 4. Migrate Planning Artifacts @@ -58,7 +61,7 @@ If you have stories created or implemented: 1. Complete the v6 installation 2. Place `epics.md` or `epics/epic*.md` in `_bmad-output/planning-artifacts/` -3. Run the Scrum Master's `sprint-planning` workflow +3. Run the Scrum Master's `bmad-sprint-planning` workflow 4. Tell the SM which epics/stories are already complete ## What You Get diff --git a/docs/index.md b/docs/index.md index 2d3de20cd..acbb7ad96 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,10 +3,14 @@ title: Welcome to the BMad Method description: AI-driven development framework with specialized agents, guided workflows, and intelligent planning --- -The BMad Method (**B**reakthrough **M**ethod of **A**gile AI **D**riven Development) is an AI-driven development framework module within the BMad Method Ecosystem that helps you build software through the whole process from ideation and planning all the way through agentic implementation. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity, whether you're fixing a bug or building an enterprise platform. +The BMad Method (**B**uild **M**ore **A**rchitect **D**reams) is an AI-driven development framework module within the BMad Method Ecosystem that helps you build software through the whole process from ideation and planning all the way through agentic implementation. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity, whether you're fixing a bug or building an enterprise platform. If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started. +:::note[🚀 V6 is Here and We're Just Getting Started!] +Skills Architecture, BMad Builder v1, Dev Loop Automation, and so much more in the works. **[Check out the Roadmap →](/roadmap/)** +::: + ## New Here? Start with a Tutorial The fastest way to understand BMad is to try it. @@ -15,7 +19,7 @@ The fastest way to understand BMad is to try it. - **[Workflow Map](./reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management :::tip[Just Want to Dive In?] -Install BMad and run `/bmad-help` — it will guide you through everything based on your project and installed modules. +Install BMad and use the `bmad-help` skill — it will guide you through everything based on your project and installed modules. ::: ## How to Use These Docs diff --git a/docs/reference/agents.md b/docs/reference/agents.md index 779f0b96e..072bdb84e 100644 --- a/docs/reference/agents.md +++ b/docs/reference/agents.md @@ -1,28 +1,58 @@ --- title: Agents -description: Default BMM agents with their menu triggers and primary workflows +description: Default BMM agents with their skill IDs, menu triggers, and primary workflows sidebar: order: 2 --- ## Default Agents -This page lists the default BMM (Agile suite) agents that install with BMad Method, along with their menu triggers and primary workflows. +This page lists the default BMM (Agile suite) agents that install with BMad Method, along with their skill IDs, menu triggers, and primary workflows. Each agent is invoked as a skill. ## Notes +- Each agent is available as a skill, generated by the installer. The skill ID (e.g., `bmad-dev`) is used to invoke the agent. - Triggers are the short menu codes (e.g., `CP`) and fuzzy matches shown in each agent menu. -- Slash commands are generated separately. See [Commands](./commands.md) for the slash command list and where they are defined. - QA (Quinn) is the lightweight test automation agent in BMM. The full Test Architect (TEA) lives in its own module. -| Agent | Triggers | Primary workflows | -| --------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- | -| Analyst (Mary) | `BP`, `RS`, `CB`, `DP` | Brainstorm Project, Research, Create Brief, Document Project | -| Product Manager (John) | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | Create/Validate/Edit PRD, Create Epics and Stories, Implementation Readiness, Correct Course | -| Architect (Winston) | `CA`, `IR` | Create Architecture, Implementation Readiness | -| Scrum Master (Bob) | `SP`, `CS`, `ER`, `CC` | Sprint Planning, Create Story, Epic Retrospective, Correct Course | -| Developer (Amelia) | `DS`, `CR` | Dev Story, Code Review | -| QA Engineer (Quinn) | `QA` | Automate (generate tests for existing features) | -| Quick Flow Solo Dev (Barry) | `QS`, `QD`, `CR` | Quick Spec, Quick Dev, Code Review | -| UX Designer (Sally) | `CU` | Create UX Design | -| Technical Writer (Paige) | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | Document Project, Write Document, Update Standards, Mermaid Generate, Validate Doc, Explain Concept | +| Agent | Skill ID | Triggers | Primary workflows | +| --------------------------- | -------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- | +| Analyst (Mary) | `bmad-analyst` | `BP`, `RS`, `CB`, `DP` | Brainstorm Project, Research, Create Brief, Document Project | +| Product Manager (John) | `bmad-pm` | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | Create/Validate/Edit PRD, Create Epics and Stories, Implementation Readiness, Correct Course | +| Architect (Winston) | `bmad-architect` | `CA`, `IR` | Create Architecture, Implementation Readiness | +| Scrum Master (Bob) | `bmad-sm` | `SP`, `CS`, `ER`, `CC` | Sprint Planning, Create Story, Epic Retrospective, Correct Course | +| Developer (Amelia) | `bmad-dev` | `DS`, `CR` | Dev Story, Code Review | +| QA Engineer (Quinn) | `bmad-qa` | `QA` | Automate (generate tests for existing features) | +| Quick Flow Solo Dev (Barry) | `bmad-master` | `QS`, `QD`, `CR` | Quick Spec, Quick Dev, Code Review | +| UX Designer (Sally) | `bmad-ux-designer` | `CU` | Create UX Design | +| Technical Writer (Paige) | `bmad-tech-writer` | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | Document Project, Write Document, Update Standards, Mermaid Generate, Validate Doc, Explain Concept | + +## Trigger Types + +Agent menu triggers use two different invocation types. Knowing which type a trigger uses helps you provide the right input. + +### Workflow triggers (no arguments needed) + +Most triggers load a structured workflow file. Type the trigger code and the agent starts the workflow, prompting you for input at each step. + +Examples: `CP` (Create PRD), `DS` (Dev Story), `CA` (Create Architecture), `QS` (Quick Spec) + +### Conversational triggers (arguments required) + +Some triggers start a free-form conversation instead of a structured workflow. These expect you to describe what you need alongside the trigger code. + +| Agent | Trigger | What to provide | +| --- | --- | --- | +| Technical Writer (Paige) | `WD` | Description of the document to write | +| Technical Writer (Paige) | `US` | Preferences or conventions to add to standards | +| Technical Writer (Paige) | `MG` | Diagram description and type (sequence, flowchart, etc.) | +| Technical Writer (Paige) | `VD` | Document to validate and focus areas | +| Technical Writer (Paige) | `EC` | Concept name to explain | + +**Example:** + +```text +WD Write a deployment guide for our Docker setup +MG Create a sequence diagram showing the auth flow +EC Explain how the module system works +``` diff --git a/docs/reference/commands.md b/docs/reference/commands.md index af4f1f496..0de99157c 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -1,111 +1,113 @@ --- -title: Commands -description: Reference for BMad slash commands — what they are, how they work, and where to find them. +title: Skills +description: Reference for BMad skills — what they are, how they work, and where to find them. sidebar: order: 3 --- -Slash commands are pre-built prompts that load agents, run workflows, or execute tasks inside your IDE. The BMad installer generates them from your installed modules at install time. If you later add, remove, or change modules, re-run the installer to keep commands in sync (see [Troubleshooting](#troubleshooting)). +Skills are pre-built prompts that load agents, run workflows, or execute tasks inside your IDE. The BMad installer generates them from your installed modules at install time. If you later add, remove, or change modules, re-run the installer to keep skills in sync (see [Troubleshooting](#troubleshooting)). -## Commands vs. Agent Menu Triggers +## Skills vs. Agent Menu Triggers BMad offers two ways to start work, and they serve different purposes. | Mechanism | How you invoke it | What happens | | --- | --- | --- | -| **Slash command** | Type `/bmad-...` in your IDE | Directly loads an agent, runs a workflow, or executes a task | +| **Skill** | Type the skill name (e.g. `bmad-help`) in your IDE | Directly loads an agent, runs a workflow, or executes a task | | **Agent menu trigger** | Load an agent first, then type a short code (e.g. `DS`) | The agent interprets the code and starts the matching workflow while staying in character | -Agent menu triggers require an active agent session. Use slash commands when you know which workflow you want. Use triggers when you are already working with an agent and want to switch tasks without leaving the conversation. +Agent menu triggers require an active agent session. Use skills when you know which workflow you want. Use triggers when you are already working with an agent and want to switch tasks without leaving the conversation. -## How Commands Are Generated +## How Skills Are Generated -When you run `npx bmad-method install`, the installer reads the manifests for every selected module and writes one command file per agent, workflow, task, and tool. Each file is a short markdown prompt that instructs the AI to load the corresponding source file and follow its instructions. +When you run `npx bmad-method install`, the installer reads the manifests for every selected module and writes one skill per agent, workflow, task, and tool. Each skill is a directory containing a `SKILL.md` file that instructs the AI to load the corresponding source file and follow its instructions. -The installer uses templates for each command type: +The installer uses templates for each skill type: -| Command type | What the generated file does | +| Skill type | What the generated file does | | --- | --- | | **Agent launcher** | Loads the agent persona file, activates its menu, and stays in character | -| **Workflow command** | Loads the workflow engine (`workflow.xml`) and passes the workflow config | -| **Task command** | Loads a standalone task file and follows its instructions | -| **Tool command** | Loads a standalone tool file and follows its instructions | +| **Workflow skill** | Loads the workflow config and follows its steps | +| **Task skill** | Loads a standalone task file and follows its instructions | +| **Tool skill** | Loads a standalone tool file and follows its instructions | :::note[Re-running the installer] -If you add or remove modules, run the installer again. It regenerates all command files to match your current module selection. +If you add or remove modules, run the installer again. It regenerates all skill files to match your current module selection. ::: -## Where Command Files Live +## Where Skill Files Live -The installer writes command files into an IDE-specific directory inside your project. The exact path depends on which IDE you selected during installation. +The installer writes skill files into an IDE-specific directory inside your project. The exact path depends on which IDE you selected during installation. -| IDE / CLI | Command directory | +| IDE / CLI | Skills directory | | --- | --- | -| Claude Code | `.claude/commands/` | -| Cursor | `.cursor/commands/` | -| Windsurf | `.windsurf/workflows/` | +| Claude Code | `.claude/skills/` | +| Cursor | `.cursor/skills/` | +| Windsurf | `.windsurf/skills/` | | Other IDEs | See the installer output for the target path | -All IDEs receive a flat set of command files in their command directory. For example, a Claude Code installation looks like: +Each skill is a directory containing a `SKILL.md` file. For example, a Claude Code installation looks like: ```text -.claude/commands/ -├── bmad-agent-bmm-dev.md -├── bmad-agent-bmm-pm.md -├── bmad-bmm-create-prd.md -├── bmad-editorial-review-prose.md -├── bmad-help.md +.claude/skills/ +├── bmad-help/ +│ └── SKILL.md +├── bmad-create-prd/ +│ └── SKILL.md +├── bmad-dev/ +│ └── SKILL.md └── ... ``` -The filename determines the slash command name in your IDE. For example, the file `bmad-agent-bmm-dev.md` registers the command `/bmad-agent-bmm-dev`. +The directory name determines the skill name in your IDE. For example, the directory `bmad-dev/` registers the skill `bmad-dev`. -## How to Discover Your Commands +## How to Discover Your Skills -Type `/bmad` in your IDE and use autocomplete to browse available commands. +Type the skill name in your IDE to invoke it. Some platforms require you to enable skills in settings before they appear. -Run `/bmad-help` for context-aware guidance on your next step. +Run `bmad-help` for context-aware guidance on your next step. :::tip[Quick discovery] -The generated command folders in your project are the canonical list. Open them in your file explorer to see every command with its description. +The generated skill directories in your project are the canonical list. Open them in your file explorer to see every skill with its description. ::: -## Command Categories +## Skill Categories -### Agent Commands +### Agent Skills -Agent commands load a specialized AI persona with a defined role, communication style, and menu of workflows. Once loaded, the agent stays in character and responds to menu triggers. +Agent skills load a specialized AI persona with a defined role, communication style, and menu of workflows. Once loaded, the agent stays in character and responds to menu triggers. -| Example command | Agent | Role | +| Example skill | Agent | Role | | --- | --- | --- | -| `/bmad-agent-bmm-dev` | Amelia (Developer) | Implements stories with strict adherence to specs | -| `/bmad-agent-bmm-pm` | John (Product Manager) | Creates and validates PRDs | -| `/bmad-agent-bmm-architect` | Winston (Architect) | Designs system architecture | -| `/bmad-agent-bmm-sm` | Bob (Scrum Master) | Manages sprints and stories | +| `bmad-dev` | Amelia (Developer) | Implements stories with strict adherence to specs | +| `bmad-pm` | John (Product Manager) | Creates and validates PRDs | +| `bmad-architect` | Winston (Architect) | Designs system architecture | +| `bmad-sm` | Bob (Scrum Master) | Manages sprints and stories | See [Agents](./agents.md) for the full list of default agents and their triggers. -### Workflow Commands +### Workflow Skills -Workflow commands run a structured, multi-step process without loading an agent persona first. They load the workflow engine and pass a specific workflow configuration. +Workflow skills run a structured, multi-step process without loading an agent persona first. They load a workflow configuration and follow its steps. -| Example command | Purpose | +| Example skill | Purpose | | --- | --- | -| `/bmad-bmm-create-prd` | Create a Product Requirements Document | -| `/bmad-bmm-create-architecture` | Design system architecture | -| `/bmad-bmm-dev-story` | Implement a story | -| `/bmad-bmm-code-review` | Run a code review | -| `/bmad-bmm-quick-spec` | Define an ad-hoc change (Quick Flow) | +| `bmad-create-prd` | Create a Product Requirements Document | +| `bmad-create-architecture` | Design system architecture | +| `bmad-create-epics-and-stories` | Create epics and stories | +| `bmad-dev-story` | Implement a story | +| `bmad-code-review` | Run a code review | +| `bmad-quick-spec` | Define an ad-hoc change (Quick Flow) | See [Workflow Map](./workflow-map.md) for the complete workflow reference organized by phase. -### Task and Tool Commands +### Task and Tool Skills Tasks and tools are standalone operations that do not require an agent or workflow context. #### BMad-Help: Your Intelligent Guide -**`/bmad-help`** is your primary interface for discovering what to do next. It's not just a lookup tool — it's an intelligent assistant that: +**`bmad-help`** is your primary interface for discovering what to do next. It's not just a lookup tool — it's an intelligent assistant that: - **Inspects your project** to see what's already been done - **Understands natural language queries** — ask questions in plain English @@ -116,36 +118,28 @@ Tasks and tools are standalone operations that do not require an agent or workfl **Examples:** ``` -/bmad-help -/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 +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 ``` #### Other Tasks and Tools -| Example command | Purpose | +| Example skill | Purpose | | --- | --- | -| `/bmad-shard-doc` | Split a large markdown file into smaller sections | -| `/bmad-index-docs` | Index project documentation | -| `/bmad-editorial-review-prose` | Review document prose quality | +| `bmad-shard-doc` | Split a large markdown file into smaller sections | +| `bmad-index-docs` | Index project documentation | +| `bmad-editorial-review-prose` | Review document prose quality | ## Naming Convention -Command names follow a predictable pattern. - -| Pattern | Meaning | Example | -| --- | --- | --- | -| `bmad-agent--` | Agent launcher | `bmad-agent-bmm-dev` | -| `bmad--` | Workflow command | `bmad-bmm-create-prd` | -| `bmad-` | Core task or tool | `bmad-help` | - -Module codes: `bmm` (Agile suite), `bmb` (Builder), `tea` (Test Architect), `cis` (Creative Intelligence), `gds` (Game Dev Studio). See [Modules](./modules.md) for descriptions. +All skills use the `bmad-` prefix followed by a descriptive name (e.g., `bmad-dev`, `bmad-create-prd`, `bmad-help`). See [Modules](./modules.md) for available modules. ## Troubleshooting -**Commands not appearing after install.** Restart your IDE or reload the window. Some IDEs cache the command list and require a refresh to pick up new files. +**Skills not appearing after install.** Some platforms require skills to be explicitly enabled in settings. Check your IDE's documentation or ask your AI assistant how to enable skills. You may also need to restart your IDE or reload the window. -**Expected commands are missing.** The installer only generates commands for modules you selected. Run `npx bmad-method install` again and verify your module selection. Check that the command files exist in the expected directory. +**Expected skills are missing.** The installer only generates skills for modules you selected. Run `npx bmad-method install` again and verify your module selection. Check that the skill files exist in the expected directory. -**Commands from a removed module still appear.** The installer does not delete old command files automatically. Remove the stale files from your IDE's command directory, or delete the entire command directory and re-run the installer for a clean set. +**Skills from a removed module still appear.** The installer does not delete old skill files automatically. Remove the stale directories from your IDE's skills directory, or delete the entire skills directory and re-run the installer for a clean set. diff --git a/docs/reference/testing.md b/docs/reference/testing.md index 4063ddfe1..f7832c2e6 100644 --- a/docs/reference/testing.md +++ b/docs/reference/testing.md @@ -26,7 +26,7 @@ Most projects should start with Quinn. If you later need test strategy, quality Quinn is the built-in QA agent in the BMM (Agile suite) module. It generates working tests quickly using your project's existing test framework -- no configuration or additional installation required. -**Trigger:** `QA` or `bmad-bmm-qa-automate` +**Trigger:** `QA` or `bmad-qa-generate-e2e-tests` ### What Quinn Does @@ -95,11 +95,11 @@ TEA also supports P0-P3 risk-based prioritization and optional integrations with ## How Testing Fits into Workflows -Quinn's Automate workflow appears in Phase 4 (Implementation) of the BMad Method workflow map. A typical sequence: +Quinn's Automate workflow appears in Phase 4 (Implementation) of the BMad Method workflow map. It is designed to run **after a full epic is complete** — once all stories in an epic have been implemented and code-reviewed. A typical sequence: -1. Implement a story with the Dev workflow (`DS`) -2. Generate tests with Quinn (`QA`) or TEA's Automate workflow -3. Validate implementation with Code Review (`CR`) +1. For each story in the epic: implement with Dev (`DS`), then validate with Code Review (`CR`) +2. After the epic is complete: generate tests with Quinn (`QA`) or TEA's Automate workflow +3. Run retrospective (`bmad-retrospective`) to capture lessons learned Quinn works directly from source code without loading planning documents (PRD, architecture). TEA workflows can integrate with upstream planning artifacts for traceability. diff --git a/docs/reference/workflow-map.md b/docs/reference/workflow-map.md index 05885a5e1..612757925 100644 --- a/docs/reference/workflow-map.md +++ b/docs/reference/workflow-map.md @@ -9,9 +9,9 @@ The BMad Method (BMM) is a module in the BMad Ecosystem, targeted at following t The rationale and concepts come from agile methodologies that have been used across the industry with great success as a mental framework. -If at any time you are unsure what to do, the `/bmad-help` command will help you stay on track or know what to do next. You can always refer to this for reference also - but /bmad-help is fully interactive and much quicker if you have already installed the BMad Method. Additionally, if you are using different modules that have extended the BMad Method or added other complementary non-extension modules - the /bmad-help evolves to know all that is available to give you the best in-the-moment advice. +If at any time you are unsure what to do, the `bmad-help` skill will help you stay on track or know what to do next. You can always refer to this for reference also - but `bmad-help` is fully interactive and much quicker if you have already installed the BMad Method. Additionally, if you are using different modules that have extended the BMad Method or added other complementary non-extension modules - `bmad-help` evolves to know all that is available to give you the best in-the-moment advice. -Final important note: Every workflow below can be run directly with your tool of choice via slash command or by loading an agent first and using the entry from the agents menu. +Final important note: Every workflow below can be run directly with your tool of choice via skill or by loading an agent first and using the entry from the agents menu. @@ -26,8 +26,8 @@ Explore the problem space and validate ideas before committing to planning. | Workflow | Purpose | Produces | | ------------------------------- | -------------------------------------------------------------------------- | ------------------------- | | `bmad-brainstorming` | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` | -| `bmad-bmm-research` | Validate market, technical, or domain assumptions | Research findings | -| `bmad-bmm-create-product-brief` | Capture strategic vision | `product-brief.md` | +| `bmad-domain-research`, `bmad-market-research`, `bmad-technical-research` | Validate market, technical, or domain assumptions | Research findings | +| `bmad-create-product-brief` | Capture strategic vision | `product-brief.md` | ## Phase 2: Planning @@ -35,8 +35,8 @@ Define what to build and for whom. | Workflow | Purpose | Produces | | --------------------------- | ---------------------------------------- | ------------ | -| `bmad-bmm-create-prd` | Define requirements (FRs/NFRs) | `PRD.md` | -| `bmad-bmm-create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` | +| `bmad-create-prd` | Define requirements (FRs/NFRs) | `PRD.md` | +| `bmad-create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` | ## Phase 3: Solutioning @@ -44,9 +44,9 @@ Decide how to build it and break work into stories. | Workflow | Purpose | Produces | | ----------------------------------------- | ------------------------------------------ | --------------------------- | -| `bmad-bmm-create-architecture` | Make technical decisions explicit | `architecture.md` with ADRs | -| `bmad-bmm-create-epics-and-stories` | Break requirements into implementable work | Epic files with stories | -| `bmad-bmm-check-implementation-readiness` | Gate check before implementation | PASS/CONCERNS/FAIL decision | +| `bmad-create-architecture` | Make technical decisions explicit | `architecture.md` with ADRs | +| `bmad-create-epics-and-stories` | Break requirements into implementable work | Epic files with stories | +| `bmad-check-implementation-readiness` | Gate check before implementation | PASS/CONCERNS/FAIL decision | ## Phase 4: Implementation @@ -54,13 +54,13 @@ Build it, one story at a time. Coming soon, full phase 4 automation! | Workflow | Purpose | Produces | | -------------------------- | ------------------------------------------------------------------------ | -------------------------------- | -| `bmad-bmm-sprint-planning` | Initialize tracking (once per project to sequence the dev cycle) | `sprint-status.yaml` | -| `bmad-bmm-create-story` | Prepare next story for implementation | `story-[slug].md` | -| `bmad-bmm-dev-story` | Implement the story | Working code + tests | -| `bmad-bmm-code-review` | Validate implementation quality | Approved or changes requested | -| `bmad-bmm-correct-course` | Handle significant mid-sprint changes | Updated plan or re-routing | -| `bmad-bmm-automate` | Generate tests for existing features - Use after a full epic is complete | End to End UI Focused Test suite | -| `bmad-bmm-retrospective` | Review after epic completion | Lessons learned | +| `bmad-sprint-planning` | Initialize tracking (once per project to sequence the dev cycle) | `sprint-status.yaml` | +| `bmad-create-story` | Prepare next story for implementation | `story-[slug].md` | +| `bmad-dev-story` | Implement the story | Working code + tests | +| `bmad-code-review` | Validate implementation quality | Approved or changes requested | +| `bmad-correct-course` | Handle significant mid-sprint changes | Updated plan or re-routing | +| `bmad-sprint-status` | Track sprint progress and story status | Sprint status update | +| `bmad-retrospective` | Review after epic completion | Lessons learned | ## Quick Flow (Parallel Track) @@ -68,8 +68,8 @@ Skip phases 1-3 for small, well-understood work. | Workflow | Purpose | Produces | | --------------------- | ------------------------------------------ | --------------------------------------------- | -| `bmad-bmm-quick-spec` | Define an ad-hoc change | `tech-spec.md` (story file for small changes) | -| `bmad-bmm-quick-dev` | Implement from spec or direct instructions | Working code + tests | +| `bmad-quick-spec` | Define an ad-hoc change | `tech-spec.md` (story file for small changes) | +| `bmad-quick-dev` | Implement from spec or direct instructions | Working code + tests | ## Context Management @@ -84,6 +84,6 @@ Create `project-context.md` to ensure AI agents follow your project's rules and **How to create it:** - **Manually** — Create `_bmad-output/project-context.md` with your technology stack and implementation rules -- **Generate it** — Run `/bmad-bmm-generate-project-context` to auto-generate from your architecture or codebase +- **Generate it** — Run `bmad-generate-project-context` to auto-generate from your architecture or codebase [**Learn more about project-context.md**](../explanation/project-context.md) diff --git a/docs/roadmap.mdx b/docs/roadmap.mdx new file mode 100644 index 000000000..8c7f7f1c8 --- /dev/null +++ b/docs/roadmap.mdx @@ -0,0 +1,136 @@ +--- +title: Roadmap +description: What's next for BMad - Features, improvements, and community contributions +--- + +# The BMad Method: Public Roadmap + +The BMad Method, BMad Method Module (BMM), and BMad Builder (BMB) are evolving. Here's what we're working on and what's coming next. + +
+ +

In Progress

+ +
+
+ 🧩 +

Universal Skills Architecture

+

One skill, any platform. Write once, run everywhere.

+
+
+ 🏗️ +

BMad Builder v1

+

Craft production-ready AI agents and workflows with evals, teams, and graceful degradation built in.

+
+
+ 🧠 +

Project Context System

+

Your AI actually understands your project. Framework-aware context that evolves with your codebase.

+
+
+ 📦 +

Centralized Skills

+

Install once, use everywhere. Share skills across projects without the file clutter.

+
+
+ 🔄 +

Adaptive Skills

+

Skills that know your tool. Optimized variants for Claude, Codex, Kimi, and OpenCode, plus many more.

+
+
+ 📝 +

BMad Team Pros Blog

+

Guides, articles and insights from the team. Launching soon.

+
+
+ +

Getting Started

+ +
+
+ 🏪 +

Skill Marketplace

+

Discover, install, and update community-built skills. One curl command away from superpowers.

+
+
+ 🎨 +

Workflow Customization

+

Make it yours. Integrate Jira, Linear, custom outputs your workflow, your rules.

+
+
+ 🚀 +

Phase 1-3 Optimization

+

Lightning-fast planning with sub-agent context gathering. YOLO mode meets guided excellence.

+
+
+ 🌐 +

Enterprise Ready

+

SSO, audit logs, team workspaces. All the boring stuff that makes companies say yes.

+
+
+ 💎 +

Community Modules Explosion

+

Entertainment, security, therapy, roleplay and much more. Expand the BMad Method platform.

+
+
+ ⚡ +

Dev Loop Automation

+

Optional autopilot for development. Let AI handle the flow while keeping quality sky-high.

+
+
+ +

Community and Team

+ +
+
+ 🎙️ +

The BMad Method Podcast

+

Conversations about AI-native development. Launching March 1, 2026!

+
+
+ 🎓 +

The BMad Method Master Class

+

Go from user to expert. Deep dives into every phase, every workflow, every secret.

+
+
+ 🏗️ +

The BMad Builder Master Class

+

Build your own agents. Advanced techniques for when you are ready to create, not just use.

+
+
+ ⚡ +

BMad Prototype First

+

Idea to working prototype in one session. Craft your dream app like a work of art.

+
+
+ 🌴 +

BMad BALM!

+

Life management for the AI-native. Tasks, habits, goals your AI copilot for everything.

+
+
+ 🖥️ +

Official UI

+

A beautiful interface for the entire BMad ecosystem. CLI power, GUI polish.

+
+
+ 🔒 +

BMad in a Box

+

Self-hosted, air-gapped, enterprise-grade. Your AI assistant, your infrastructure, your control.

+
+
+ +
+

Want to Contribute?

+

+ This is only a partial list of what's planned. The BMad Open Source team welcomes contributors!{" "}
+ Join us on GitHub to help shape the future of AI-driven development. +

+

+ Love what we're building? We appreciate both one-time and monthly{" "}support. +

+

+ For corporate sponsorship, partnership inquiries, speaking engagements, training, or media enquiries:{" "} + contact@bmadcode.com +

+
+
diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index b7aa02dfd..43b5ba2e9 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -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 ::: @@ -37,16 +37,16 @@ Build software faster using AI-powered workflows with specialized agents that gu ### How to Use BMad-Help -Run it in your AI IDE with just the slash command: +Run it in your AI IDE by invoking the skill: ``` -/bmad-help +bmad-help ``` Or combine it with a question for context-aware guidance: ``` -/bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started? +bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started? ``` BMad-Help will respond with: @@ -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 **slash command** you run in your IDE (e.g., `/bmad-bmm-create-prd`). Running a workflow command automatically loads the appropriate agent — you don't need to load agents separately. You can also load an agent directly for general conversation (e.g., `/bmad-agent-bmm-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-bmm-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-bmm-research`) — Market and technical research -- **create-product-brief** (`/bmad-bmm-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. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat -2. Run the `prd` workflow (`/bmad-bmm-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 `quick-spec` workflow (`/bmad-bmm-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, load the **UX-Designer agent** (`/bmad-agent-bmm-ux-designer`) and run the UX design workflow (`/bmad-bmm-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. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat -2. Run `create-architecture` (`/bmad-bmm-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, load the **UX-Designer agent** (`/bmad-age 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. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat -2. Run `create-epics-and-stories` (`/bmad-bmm-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. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat -2. Run `check-implementation-readiness` (`/bmad-bmm-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 -Load the **SM agent** (`/bmad-agent-bmm-sm`) and run `sprint-planning` (`/bmad-bmm-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 | `create-story` | `/bmad-bmm-create-story` | Create story file from epic | -| 2 | DEV | `dev-story` | `/bmad-bmm-dev-story` | Implement the story | -| 3 | DEV | `code-review` | `/bmad-bmm-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, load the **SM agent** (`/bmad-agent-bmm-sm`) and run `retrospective` (`/bmad-bmm-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 | | ------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------- | -| **`help`** ⭐ | `/bmad-help` | Any | **Your intelligent guide — ask anything!** | -| `prd` | `/bmad-bmm-create-prd` | PM | Create Product Requirements Document | -| `create-architecture` | `/bmad-bmm-create-architecture` | Architect | Create architecture document | -| `generate-project-context` | `/bmad-bmm-generate-project-context` | Analyst | Create project context file | -| `create-epics-and-stories` | `/bmad-bmm-create-epics-and-stories` | PM | Break down PRD into epics | -| `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | Validate planning cohesion | -| `sprint-planning` | `/bmad-bmm-sprint-planning` | SM | Initialize sprint tracking | -| `create-story` | `/bmad-bmm-create-story` | SM | Create a story file | -| `dev-story` | `/bmad-bmm-dev-story` | DEV | Implement a story | -| `code-review` | `/bmad-bmm-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 `correct-course` workflow (`/bmad-bmm-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?** -Load the Analyst agent (`/bmad-agent-bmm-analyst`) and run `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. diff --git a/docs/zh-cn/404.md b/docs/zh-cn/404.md new file mode 100644 index 000000000..bb835ceea --- /dev/null +++ b/docs/zh-cn/404.md @@ -0,0 +1,9 @@ +--- +title: 页面未找到 +template: splash +--- + + +您查找的页面不存在或已被移动。 + +[返回首页](./index.md) diff --git a/docs/zh-cn/_STYLE_GUIDE.md b/docs/zh-cn/_STYLE_GUIDE.md new file mode 100644 index 000000000..c6e9eff58 --- /dev/null +++ b/docs/zh-cn/_STYLE_GUIDE.md @@ -0,0 +1,370 @@ +--- +title: "Documentation Style Guide" +description: Project-specific documentation conventions based on Google style and Diataxis structure +--- + +This project adheres to the [Google Developer Documentation Style Guide](https://developers.google.com/style) and uses [Diataxis](https://diataxis.fr/) to structure content. Only project-specific conventions follow. + +## Project-Specific Rules + +| Rule | Specification | +| -------------------------------- | ---------------------------------------- | +| No horizontal rules (`---`) | Fragments reading flow | +| No `####` headers | Use bold text or admonitions instead | +| No "Related" or "Next:" sections | Sidebar handles navigation | +| No deeply nested lists | Break into sections instead | +| No code blocks for non-code | Use admonitions for dialogue examples | +| No bold paragraphs for callouts | Use admonitions instead | +| 1-2 admonitions per section max | Tutorials allow 3-4 per major section | +| Table cells / list items | 1-2 sentences max | +| Header budget | 8-12 `##` per doc; 2-3 `###` per section | + +## Admonitions (Starlight Syntax) + +```md +:::tip[Title] +Shortcuts, best practices +::: + +:::note[Title] +Context, definitions, examples, prerequisites +::: + +:::caution[Title] +Caveats, potential issues +::: + +:::danger[Title] +Critical warnings only — data loss, security issues +::: +``` + +### Standard Uses + +| Admonition | Use For | +| ------------------------ | ----------------------------- | +| `:::note[Prerequisites]` | Dependencies before starting | +| `:::tip[Quick Path]` | TL;DR summary at document top | +| `:::caution[Important]` | Critical caveats | +| `:::note[Example]` | Command/response examples | + +## Standard Table Formats + +**Phases:** + +```md +| Phase | Name | What Happens | +| ----- | -------- | -------------------------------------------- | +| 1 | Analysis | Brainstorm, research *(optional)* | +| 2 | Planning | Requirements — PRD or tech-spec *(required)* | +``` + +**Commands:** + +```md +| Command | Agent | Purpose | +| ------------ | ------- | ------------------------------------ | +| `brainstorm` | Analyst | Brainstorm a new project | +| `prd` | PM | Create Product Requirements Document | +``` + +## Folder Structure Blocks + +Show in "What You've Accomplished" sections: + +````md +``` +your-project/ +├── _bmad/ # BMad configuration +├── _bmad-output/ +│ ├── planning-artifacts/ +│ │ └── PRD.md # Your requirements document +│ ├── implementation-artifacts/ +│ └── project-context.md # Implementation rules (optional) +└── ... +``` +```` + +## Tutorial Structure + +```text +1. Title + Hook (1-2 sentences describing outcome) +2. Version/Module Notice (info or warning admonition) (optional) +3. What You'll Learn (bullet list of outcomes) +4. Prerequisites (info admonition) +5. Quick Path (tip admonition - TL;DR summary) +6. Understanding [Topic] (context before steps - tables for phases/agents) +7. Installation (optional) +8. Step 1: [First Major Task] +9. Step 2: [Second Major Task] +10. Step 3: [Third Major Task] +11. What You've Accomplished (summary + folder structure) +12. Quick Reference (commands table) +13. Common Questions (FAQ format) +14. Getting Help (community links) +15. Key Takeaways (tip admonition) +``` + +### Tutorial Checklist + +- [ ] Hook describes outcome in 1-2 sentences +- [ ] "What You'll Learn" section present +- [ ] Prerequisites in admonition +- [ ] Quick Path TL;DR admonition at top +- [ ] Tables for phases, commands, agents +- [ ] "What You've Accomplished" section present +- [ ] Quick Reference table present +- [ ] Common Questions section present +- [ ] Getting Help section present +- [ ] Key Takeaways admonition at end + +## How-To Structure + +```text +1. Title + Hook (one sentence: "Use the `X` workflow to...") +2. When to Use This (bullet list of scenarios) +3. When to Skip This (optional) +4. Prerequisites (note admonition) +5. Steps (numbered ### subsections) +6. What You Get (output/artifacts produced) +7. Example (optional) +8. Tips (optional) +9. Next Steps (optional) +``` + +### How-To Checklist + +- [ ] Hook starts with "Use the `X` workflow to..." +- [ ] "When to Use This" has 3-5 bullet points +- [ ] Prerequisites listed +- [ ] Steps are numbered `###` subsections with action verbs +- [ ] "What You Get" describes output artifacts + +## Explanation Structure + +### Types + +| Type | Example | +| ----------------- | ----------------------------- | +| **Index/Landing** | `core-concepts/index.md` | +| **Concept** | `what-are-agents.md` | +| **Feature** | `quick-flow.md` | +| **Philosophy** | `why-solutioning-matters.md` | +| **FAQ** | `established-projects-faq.md` | + +### General Template + +```text +1. Title + Hook (1-2 sentences) +2. Overview/Definition (what it is, why it matters) +3. Key Concepts (### subsections) +4. Comparison Table (optional) +5. When to Use / When Not to Use (optional) +6. Diagram (optional - mermaid, 1 per doc max) +7. Next Steps (optional) +``` + +### Index/Landing Pages + +```text +1. Title + Hook (one sentence) +2. Content Table (links with descriptions) +3. Getting Started (numbered list) +4. Choose Your Path (optional - decision tree) +``` + +### Concept Explainers + +```text +1. Title + Hook (what it is) +2. Types/Categories (### subsections) (optional) +3. Key Differences Table +4. Components/Parts +5. Which Should You Use? +6. Creating/Customizing (pointer to how-to guides) +``` + +### Feature Explainers + +```text +1. Title + Hook (what it does) +2. Quick Facts (optional - "Perfect for:", "Time to:") +3. When to Use / When Not to Use +4. How It Works (mermaid diagram optional) +5. Key Benefits +6. Comparison Table (optional) +7. When to Graduate/Upgrade (optional) +``` + +### Philosophy/Rationale Documents + +```text +1. Title + Hook (the principle) +2. The Problem +3. The Solution +4. Key Principles (### subsections) +5. Benefits +6. When This Applies +``` + +### Explanation Checklist + +- [ ] Hook states what document explains +- [ ] Content in scannable `##` sections +- [ ] Comparison tables for 3+ options +- [ ] Diagrams have clear labels +- [ ] Links to how-to guides for procedural questions +- [ ] 2-3 admonitions max per document + +## Reference Structure + +### Types + +| Type | Example | +| ----------------- | --------------------- | +| **Index/Landing** | `workflows/index.md` | +| **Catalog** | `agents/index.md` | +| **Deep-Dive** | `document-project.md` | +| **Configuration** | `core-tasks.md` | +| **Glossary** | `glossary/index.md` | +| **Comprehensive** | `bmgd-workflows.md` | + +### Reference Index Pages + +```text +1. Title + Hook (one sentence) +2. Content Sections (## for each category) + - Bullet list with links and descriptions +``` + +### Catalog Reference + +```text +1. Title + Hook +2. Items (## for each item) + - Brief description (one sentence) + - **Commands:** or **Key Info:** as flat list +3. Universal/Shared (## section) (optional) +``` + +### Item Deep-Dive Reference + +```text +1. Title + Hook (one sentence purpose) +2. Quick Facts (optional note admonition) + - Module, Command, Input, Output as list +3. Purpose/Overview (## section) +4. How to Invoke (code block) +5. Key Sections (## for each aspect) + - Use ### for sub-options +6. Notes/Caveats (tip or caution admonition) +``` + +### Configuration Reference + +```text +1. Title + Hook +2. Table of Contents (jump links if 4+ items) +3. Items (## for each config/task) + - **Bold summary** — one sentence + - **Use it when:** bullet list + - **How it works:** numbered steps (3-5 max) + - **Output:** expected result (optional) +``` + +### Comprehensive Reference Guide + +```text +1. Title + Hook +2. Overview (## section) + - Diagram or table showing organization +3. Major Sections (## for each phase/category) + - Items (### for each item) + - Standardized fields: Command, Agent, Input, Output, Description +4. Next Steps (optional) +``` + +### Reference Checklist + +- [ ] Hook states what document references +- [ ] Structure matches reference type +- [ ] Items use consistent structure throughout +- [ ] Tables for structured/comparative data +- [ ] Links to explanation docs for conceptual depth +- [ ] 1-2 admonitions max + +## Glossary Structure + +Starlight generates right-side "On this page" navigation from headers: + +- Categories as `##` headers — appear in right nav +- Terms in tables — compact rows, not individual headers +- No inline TOC — right sidebar handles navigation + +### Table Format + +```md +## Category Name + +| Term | Definition | +| ------------ | ---------------------------------------------------------------------------------------- | +| **Agent** | Specialized AI persona with specific expertise that guides users through workflows. | +| **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. | +``` + +### Definition Rules + +| Do | Don't | +| ----------------------------- | ------------------------------------------- | +| Start with what it IS or DOES | Start with "This is..." or "A [term] is..." | +| Keep to 1-2 sentences | Write multi-paragraph explanations | +| Bold term name in cell | Use plain text for terms | + +### Context Markers + +Add italic context at definition start for limited-scope terms: + +- `*Quick Flow only.*` +- `*BMad Method/Enterprise.*` +- `*Phase N.*` +- `*BMGD.*` +- `*Established projects.*` + +### Glossary Checklist + +- [ ] Terms in tables, not individual headers +- [ ] Terms alphabetized within categories +- [ ] Definitions 1-2 sentences +- [ ] Context markers italicized +- [ ] Term names bolded in cells +- [ ] No "A [term] is..." definitions + +## FAQ Sections + +```md +## Questions + +- [Do I always need architecture?](#do-i-always-need-architecture) +- [Can I change my plan later?](#can-i-change-my-plan-later) + +### Do I always need architecture? + +Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation. + +### Can I change my plan later? + +Yes. The SM agent has a `correct-course` workflow for handling scope changes. + +**Have a question not answered here?** [Open an issue](...) or ask in [Discord](...). +``` + +## Validation Commands + +Before submitting documentation changes: + +```bash +npm run docs:fix-links # Preview link format fixes +npm run docs:fix-links -- --write # Apply fixes +npm run docs:validate-links # Check links exist +npm run docs:build # Verify no build errors +``` diff --git a/docs/zh-cn/explanation/advanced-elicitation.md b/docs/zh-cn/explanation/advanced-elicitation.md new file mode 100644 index 000000000..7ecbdf0e5 --- /dev/null +++ b/docs/zh-cn/explanation/advanced-elicitation.md @@ -0,0 +1,62 @@ +--- +title: "高级启发" +description: 使用结构化推理方法推动 LLM 重新思考其工作 +sidebar: + order: 6 +--- + +让 LLM 重新审视它刚刚生成的内容。你选择一种推理方法，它将该方法应用于自己的输出，然后你决定是否保留改进。 + +## 什么是高级启发？ + +结构化的第二轮处理。与其要求 AI "再试一次" 或 "做得更好"，不如选择一种特定的推理方法，让 AI 通过该视角重新审视自己的输出。 + +这种区别很重要。模糊的请求会产生模糊的修订。命名的方法会强制采用特定的攻击角度，揭示出通用重试会遗漏的见解。 + +## 何时使用 + +- 在工作流生成内容后，你想要替代方案 +- 当输出看起来还可以，但你怀疑还有更深层次的内容 +- 对假设进行压力测试或发现弱点 +- 对于重新思考有帮助的高风险内容 + +工作流在决策点提供高级启发——在 LLM 生成某些内容后，系统会询问你是否要运行它。 + +## 工作原理 + +1. LLM 为你的内容建议 5 种相关方法 +2. 你选择一种（或重新洗牌以获取不同选项） +3. 应用方法，显示改进 +4. 接受或丢弃，重复或继续 + +## 内置方法 + +有数十种推理方法可用。几个示例： + +- **事前复盘** - 假设项目已经失败，反向推导找出原因 +- **第一性原理思维** - 剥离假设，从基本事实重建 +- **逆向思维** - 询问如何保证失败，然后避免这些事情 +- **红队对蓝队** - 攻击你自己的工作，然后为它辩护 +- **苏格拉底式提问** - 用"为什么？"和"你怎么知道？"挑战每个主张 +- **约束移除** - 放下所有约束，看看有什么变化，然后有选择地加回 +- **利益相关者映射** - 从每个利益相关者的角度重新评估 +- **类比推理** - 在其他领域找到平行案例并应用其教训 + +还有更多。AI 会为你的内容选择最相关的选项——你选择运行哪一个。 + +:::tip[从这里开始] +对于任何规范或计划，事前复盘都是一个很好的首选。它始终能找到标准审查会遗漏的空白。 +::: + +--- +## 术语说明 + +- **LLM**：大语言模型。一种基于深度学习的自然语言处理模型，能够理解和生成人类语言。 +- **elicitation**：启发。在人工智能与提示工程中，指通过特定方法引导模型生成更高质量或更符合预期的输出。 +- **pre-mortem analysis**：事前复盘。一种风险管理技术，假设项目已经失败，然后反向推导可能的原因，以提前识别和预防潜在问题。 +- **first principles thinking**：第一性原理思维。一种将复杂问题分解为最基本事实或假设，然后从这些基本要素重新构建解决方案的思维方式。 +- **inversion**：逆向思维。通过思考如何导致失败来避免失败，从而找到成功路径的思维方式。 +- **red team vs blue team**：红队对蓝队。一种模拟对抗的方法，红队负责攻击和发现问题，蓝队负责防御和解决问题。 +- **socratic questioning**：苏格拉底式提问。一种通过连续提问来揭示假设、澄清概念和深入思考的对话方法。 +- **stakeholder mapping**：利益相关者映射。识别并分析项目中所有利益相关者及其利益、影响和关系的系统性方法。 +- **analogical reasoning**：类比推理。通过将当前问题与已知相似领域的问题进行比较，从而借鉴解决方案或见解的推理方式。 diff --git a/docs/zh-cn/explanation/adversarial-review.md b/docs/zh-cn/explanation/adversarial-review.md new file mode 100644 index 000000000..c969c1e53 --- /dev/null +++ b/docs/zh-cn/explanation/adversarial-review.md @@ -0,0 +1,71 @@ +--- +title: "对抗性评审" +description: 防止懒惰"看起来不错"评审的强制推理技术 +sidebar: + order: 5 +--- + +通过要求发现问题来强制进行更深入的分析。 + +## 什么是对抗性评审？ + +一种评审技术，评审者*必须*发现问题。不允许"看起来不错"。评审者采取怀疑态度——假设问题存在并找到它们。 + +这不是为了消极。而是为了强制进行真正的分析，而不是对提交的内容进行草率浏览并盖章批准。 + +**核心规则：**你必须发现问题。零发现会触发停止——重新分析或解释原因。 + +## 为什么有效 + +普通评审容易受到确认偏差的影响。你浏览工作，没有发现突出的问题，就批准了它。"发现问题"的指令打破了这种模式： + +- **强制彻底性**——在你足够努力地查看以发现问题之前，不能批准 +- **捕捉遗漏**——"这里缺少什么？"成为一个自然的问题 +- **提高信号质量**——发现是具体且可操作的，而不是模糊的担忧 +- **信息不对称**——在新的上下文中运行评审（无法访问原始推理），以便你评估的是工件，而不是意图 + +## 在哪里使用 + +对抗性评审出现在 BMad 工作流程的各个地方——代码评审、实施就绪检查、规范验证等。有时它是必需步骤，有时是可选的（如高级启发或派对模式）。该模式适应任何需要审查的工件。 + +## 需要人工过滤 + +因为 AI 被*指示*要发现问题，它就会发现问题——即使问题不存在。预期会有误报：伪装成问题的吹毛求疵、对意图的误解，或完全幻觉化的担忧。 + +**你决定什么是真实的。**审查每个发现，忽略噪音，修复重要的内容。 + +## 示例 + +而不是： + +> "身份验证实现看起来合理。已批准。" + +对抗性评审产生： + +> 1. **高** - `login.ts:47` - 失败尝试没有速率限制 +> 2. **高** - 会话令牌存储在 localStorage 中（易受 XSS 攻击） +> 3. **中** - 密码验证仅在客户端进行 +> 4. **中** - 失败登录尝试没有审计日志 +> 5. **低** - 魔法数字 `3600` 应该是 `SESSION_TIMEOUT_SECONDS` + +第一个评审可能会遗漏安全漏洞。第二个发现了四个。 + +## 迭代和收益递减 + +在处理发现后，考虑再次运行。第二轮通常会捕获更多。第三轮也不总是无用的。但每一轮都需要时间，最终你会遇到收益递减——只是吹毛求疵和虚假发现。 + +:::tip[更好的评审] +假设问题存在。寻找缺失的内容，而不仅仅是错误的内容。 +::: + +--- +## 术语说明 + +- **adversarial review**：对抗性评审。一种强制评审者必须发现问题的评审技术，旨在防止草率批准。 +- **confirmation bias**：确认偏差。倾向于寻找、解释和记忆符合自己已有信念的信息的心理倾向。 +- **information asymmetry**：信息不对称。交易或评审中一方拥有比另一方更多或更好信息的情况。 +- **false positives**：误报。错误地将不存在的问题识别为存在的问题。 +- **diminishing returns**：收益递减。在投入持续增加的情况下，产出增长逐渐减少的现象。 +- **XSS**：跨站脚本攻击（Cross-Site Scripting）。一种安全漏洞，攻击者可在网页中注入恶意脚本。 +- **localStorage**：本地存储。浏览器提供的 Web Storage API，用于在客户端存储键值对数据。 +- **magic number**：魔法数字。代码中直接出现的未命名数值常量，缺乏语义含义。 diff --git a/docs/zh-cn/explanation/brainstorming.md b/docs/zh-cn/explanation/brainstorming.md new file mode 100644 index 000000000..a7479e88f --- /dev/null +++ b/docs/zh-cn/explanation/brainstorming.md @@ -0,0 +1,43 @@ +--- +title: "头脑风暴" +description: 使用 60+ 种经过验证的构思技术进行互动创意会议 +sidebar: + order: 2 +--- + +通过引导式探索释放你的创造力。 + +## 什么是头脑风暴？ + +运行 `brainstorming`，你就拥有了一位创意引导者，帮助你从自身挖掘想法——而不是替你生成想法。AI 充当教练和向导，使用经过验证的技术，创造让你最佳思维涌现的条件。 + +**适用于：** + +- 突破创意瓶颈 +- 生成产品或功能想法 +- 从新角度探索问题 +- 将原始概念发展为行动计划 + +## 工作原理 + +1. **设置** - 定义主题、目标、约束 +2. **选择方法** - 自己选择技术、获取 AI 推荐、随机选择或遵循渐进式流程 +3. **引导** - 通过探索性问题和协作式教练引导完成技术 +4. **组织** - 将想法按主题分组并确定优先级 +5. **行动** - 为顶级想法制定下一步和成功指标 + +所有内容都会被记录在会议文档中，你可以稍后参考或与利益相关者分享。 + +:::note[你的想法] +每个想法都来自你。工作流程创造洞察的条件——你是源头。 +::: + +--- +## 术语说明 + +- **brainstorming**：头脑风暴。一种集体或个人的创意生成方法，通过自由联想和发散思维产生大量想法。 +- **ideation**：构思。产生想法、概念或解决方案的过程。 +- **facilitator**：引导者。在会议或工作坊中引导讨论、促进参与并帮助达成目标的人。 +- **creative blocks**：创意瓶颈。在创意过程中遇到的思维停滞或灵感枯竭状态。 +- **probing questions**：探索性问题。旨在深入挖掘信息、激发思考或揭示潜在见解的问题。 +- **stakeholders**：利益相关者。对项目或决策有利益关系或受其影响的个人或群体。 diff --git a/docs/zh-cn/explanation/established-projects-faq.md b/docs/zh-cn/explanation/established-projects-faq.md new file mode 100644 index 000000000..8756faa20 --- /dev/null +++ b/docs/zh-cn/explanation/established-projects-faq.md @@ -0,0 +1,60 @@ +--- +title: "既有项目常见问题" +description: 关于在既有项目上使用 BMad 方法的常见问题 +sidebar: + order: 8 +--- +关于使用 BMad 方法（BMM）在既有项目上工作的常见问题的快速解答。 + +## 问题 + +- [我必须先运行 document-project 吗？](#do-i-have-to-run-document-project-first) +- [如果我忘记运行 document-project 怎么办？](#what-if-i-forget-to-run-document-project) +- [我可以在既有项目上使用快速流程吗？](#can-i-use-quick-flow-for-established-projects) +- [如果我的现有代码不遵循最佳实践怎么办？](#what-if-my-existing-code-doesnt-follow-best-practices) + +### 我必须先运行 document-project 吗？ + +强烈推荐，特别是如果： + +- 没有现有文档 +- 文档已过时 +- AI 智能体需要关于现有代码的上下文 + +如果你拥有全面且最新的文档，包括 `docs/index.md`，或者将使用其他工具或技术来帮助智能体发现现有系统，则可以跳过此步骤。 + +### 如果我忘记运行 document-project 怎么办？ + +不用担心——你可以随时执行。你甚至可以在项目期间或项目之后执行，以帮助保持文档最新。 + +### 我可以在既有项目上使用快速流程吗？ + +可以！快速流程在既有项目上效果很好。它将： + +- 自动检测你的现有技术栈 +- 分析现有代码模式 +- 检测约定并请求确认 +- 生成尊重现有代码的上下文丰富的技术规范 + +非常适合现有代码库中的错误修复和小功能。 + +### 如果我的现有代码不遵循最佳实践怎么办？ + +快速流程会检测你的约定并询问："我应该遵循这些现有约定吗？"你决定： + +- **是** → 与当前代码库保持一致 +- **否** → 建立新标准（在技术规范中记录原因） + +BMM 尊重你的选择——它不会强制现代化，但会提供现代化选项。 + +**有未在此处回答的问题吗？** 请[提出问题](https://github.com/bmad-code-org/BMAD-METHOD/issues)或在 [Discord](https://discord.gg/gk8jAdXWmj) 中提问，以便我们添加它！ + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **Quick Flow**：快速流程。BMad 方法中的一种工作流程，用于快速处理既有项目。 +- **tech-spec**：技术规范。描述技术实现细节和标准的文档。 +- **stack**：技术栈。项目所使用的技术组合，包括框架、库、工具等。 +- **conventions**：约定。代码库中遵循的编码风格、命名规则等规范。 +- **modernization**：现代化。将旧代码或系统更新为更现代的技术和最佳实践的过程。 diff --git a/docs/zh-cn/explanation/party-mode.md b/docs/zh-cn/explanation/party-mode.md new file mode 100644 index 000000000..85061f393 --- /dev/null +++ b/docs/zh-cn/explanation/party-mode.md @@ -0,0 +1,79 @@ +--- +title: "派对模式" +description: 多智能体协作——将所有 AI 智能体汇聚到一次对话中 +sidebar: + order: 7 +--- + +将所有 AI 智能体汇聚到一次对话中。 + +## 什么是 Party Mode？ + +运行 `party-mode`，你的整个 AI 团队就齐聚一堂——PM、架构师、开发者、UX 设计师，任何你需要的人。BMad Master 负责编排，根据每条消息选择相关的智能体。智能体以角色身份回应，彼此同意、反对，并在彼此的想法基础上继续构建。 + +对话可以持续到你想要的时间。提出追问、对答案提出质疑、引导讨论方向——这是与智能体之间真正的来回交流，直到你完成目标。 + +**适用于：** + +- 需要权衡的重大决策 +- 头脑风暴会议 +- 出现问题时的复盘 +- 冲刺回顾与规划 + +## 示例 + +### 指出糟糕的架构 + +**You:** "好了团队，我们上个冲刺是一场灾难。认证服务宕机了三次。谁搞砸了这件事？" + +**Architect:** "设计本身是合理的——分布式认证，有适当的回退机制。如果实现偏离了规范……" + +**Dev:** "我完全按照架构文档执行的。规范没有考虑到并发会话失效的竞态条件。" + +**PM:** "你们两个都忽略了更大的问题——我们没有在 PRD 中验证会话管理需求。这是我的错，没有发现这一点。" + +**TEA:** "我也应该在集成测试中发现这一点。测试场景没有覆盖并发失效。" + +### 创意头脑风暴 + +**You:** "我们如何让入职体验变得神奇，而不是无聊？" + +**UX Designer:** "从渐进式披露开始——在用户需要时揭示功能，而不是在教程中一次性展示所有内容。" + +**Storyteller:** "如果入职是一个故事会怎样？每一步都揭示一个角色的旅程——用户就是英雄。" + +**Game Designer:** "在此基础上——如果第一个'任务'实际上是解决一个真实的用户问题会怎样？他们通过做有价值的事情来学习。" + +### 技术决策 + +**You:** "MVP 用单体还是微服务？" + +**Architect:** "从单体开始。微服务会增加你在 1000 用户时不需要的复杂性。" + +**PM:** "同意。上市时间比理论上的可扩展性更重要。" + +**Dev:** "单体，但要有清晰的模块边界。如果需要，我们以后可以提取服务。" + +:::tip[Better Decisions] +通过多元视角做出更好的决策。欢迎来到 party mode。 +::: + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **PM**：产品经理（Product Manager）。 +- **Architect**：架构师。 +- **Dev**：开发者（Developer）。 +- **UX Designer**：用户体验设计师。 +- **TEA**：测试工程师（Test Engineer/Automation）。 +- **PRD**：产品需求文档（Product Requirements Document）。 +- **MVP**：最小可行产品（Minimum Viable Product）。 +- **monolith**：单体架构。一种将应用程序构建为单一、统一单元的架构风格。 +- **microservices**：微服务。一种将应用程序构建为一组小型、独立服务的架构风格。 +- **progressive disclosure**：渐进式披露。一种交互设计模式，仅在用户需要时显示信息或功能。 +- **post-mortem**：复盘。对事件或项目进行事后分析，以了解发生了什么以及如何改进。 +- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周。 +- **race condition**：竞态条件。当多个进程或线程同时访问和操作共享数据时，系统行为取决于执行顺序的一种情况。 +- **fallback**：回退机制。当主要方法失败时使用的备用方案。 +- **time to market**：上市时间。产品从概念到推向市场所需的时间。 diff --git a/docs/zh-cn/explanation/preventing-agent-conflicts.md b/docs/zh-cn/explanation/preventing-agent-conflicts.md new file mode 100644 index 000000000..c3f24faf6 --- /dev/null +++ b/docs/zh-cn/explanation/preventing-agent-conflicts.md @@ -0,0 +1,137 @@ +--- +title: "防止智能体冲突" +description: 架构如何在多个智能体实现系统时防止冲突 +sidebar: + order: 4 +--- + +当多个 AI 智能体实现系统的不同部分时，它们可能会做出相互冲突的技术决策。架构文档通过建立共享标准来防止这种情况。 + +## 常见冲突类型 + +### API 风格冲突 + +没有架构时： +- 智能体 A 使用 REST，路径为 `/users/{id}` +- 智能体 B 使用 GraphQL mutations +- 结果：API 模式不一致，消费者困惑 + +有架构时： +- ADR 指定："所有客户端-服务器通信使用 GraphQL" +- 所有智能体遵循相同的模式 + +### 数据库设计冲突 + +没有架构时： +- 智能体 A 使用 snake_case 列名 +- 智能体 B 使用 camelCase 列名 +- 结果：模式不一致，查询混乱 + +有架构时： +- 标准文档指定命名约定 +- 所有智能体遵循相同的模式 + +### 状态管理冲突 + +没有架构时： +- 智能体 A 使用 Redux 管理全局状态 +- 智能体 B 使用 React Context +- 结果：多种状态管理方法，复杂度增加 + +有架构时： +- ADR 指定状态管理方法 +- 所有智能体一致实现 + +## 架构如何防止冲突 + +### 1. 通过 ADR 明确决策 + +每个重要的技术选择都记录以下内容： +- 上下文（为什么这个决策很重要） +- 考虑的选项（有哪些替代方案） +- 决策（我们选择了什么） +- 理由（为什么选择它） +- 后果（接受的权衡） + +### 2. FR/NFR 特定指导 + +架构将每个功能需求映射到技术方法： +- FR-001：用户管理 → GraphQL mutations +- FR-002：移动应用 → 优化查询 + +### 3. 标准和约定 + +明确记录以下内容： +- 目录结构 +- 命名约定 +- 代码组织 +- 测试模式 + +## 架构作为共享上下文 + +将架构视为所有智能体在实现之前阅读的共享上下文： + +```text +PRD："构建什么" + ↓ +架构："如何构建" + ↓ +智能体 A 阅读架构 → 实现 Epic 1 +智能体 B 阅读架构 → 实现 Epic 2 +智能体 C 阅读架构 → 实现 Epic 3 + ↓ +结果：一致的实现 +``` + +## Key ADR Topics + +防止冲突的常见决策： + +| Topic | Example Decision | +| ---------------- | -------------------------------------------- | +| API Style | GraphQL vs REST vs gRPC | +| Database | PostgreSQL vs MongoDB | +| Auth | JWT vs Sessions | +| State Management | Redux vs Context vs Zustand | +| Styling | CSS Modules vs Tailwind vs Styled Components | +| Testing | Jest + Playwright vs Vitest + Cypress | + +## 避免的反模式 + +:::caution[常见错误] +- **隐式决策** — "我们边做边确定 API 风格"会导致不一致 +- **过度文档化** — 记录每个次要选择会导致分析瘫痪 +- **过时架构** — 文档写一次后从不更新，导致智能体遵循过时的模式 +::: + +:::tip[正确方法] +- 记录跨越 epic 边界的决策 +- 专注于容易产生冲突的领域 +- 随着学习更新架构 +- 对重大变更使用 `correct-course` +::: + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **ADR**：架构决策记录（Architecture Decision Record）。用于记录重要架构决策及其背景、选项和后果的文档。 +- **FR**：功能需求（Functional Requirement）。系统必须具备的功能或行为。 +- **NFR**：非功能需求（Non-Functional Requirement）。系统性能、安全性、可扩展性等质量属性。 +- **Epic**：史诗。大型功能或用户故事的集合，通常需要多个迭代完成。 +- **snake_case**：蛇形命名法。单词之间用下划线连接，所有字母小写的命名风格。 +- **camelCase**：驼峰命名法。除第一个单词外，每个单词首字母大写的命名风格。 +- **GraphQL mutations**：GraphQL 变更操作。用于修改服务器数据的 GraphQL 操作类型。 +- **Redux**：JavaScript 状态管理库。用于管理应用全局状态的可预测状态容器。 +- **React Context**：React 上下文 API。用于在组件树中传递数据而无需逐层传递 props。 +- **Zustand**：轻量级状态管理库。用于 React 应用的简单状态管理解决方案。 +- **CSS Modules**：CSS 模块。将 CSS 作用域限制在组件内的技术。 +- **Tailwind**：Tailwind CSS。实用优先的 CSS 框架。 +- **Styled Components**：样式化组件。使用 JavaScript 编写样式的 React 库。 +- **Jest**：JavaScript 测试框架。用于编写和运行测试的工具。 +- **Playwright**：端到端测试框架。用于自动化浏览器测试的工具。 +- **Vitest**：Vite 原生测试框架。快速且轻量的单元测试工具。 +- **Cypress**：端到端测试框架。用于 Web 应用测试的工具。 +- **gRPC**：远程过程调用框架。Google 开发的高性能 RPC 框架。 +- **JWT**：JSON Web Token。用于身份验证的开放标准令牌。 +- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。 diff --git a/docs/zh-cn/explanation/project-context.md b/docs/zh-cn/explanation/project-context.md new file mode 100644 index 000000000..c33b3adfc --- /dev/null +++ b/docs/zh-cn/explanation/project-context.md @@ -0,0 +1,176 @@ +--- +title: "项目上下文" +description: project-context.md 如何使用项目的规则和偏好指导 AI 智能体 +sidebar: + order: 7 +--- + +[`project-context.md`](project-context.md) 文件是您的项目面向 AI 智能体的实施指南。类似于其他开发系统中的"宪法"，它记录了确保所有工作流中代码生成一致的规则、模式和偏好。 + +## 它的作用 + +AI 智能体不断做出实施决策——遵循哪些模式、如何组织代码、使用哪些约定。如果没有明确指导，它们可能会： +- 遵循与您的代码库不匹配的通用最佳实践 +- 在不同的用户故事中做出不一致的决策 +- 错过项目特定的需求或约束 + +[`project-context.md`](project-context.md) 文件通过以简洁、针对 LLM 优化的格式记录智能体需要了解的内容来解决这个问题。 + +## 它的工作原理 + +每个实施工作流都会自动加载 [`project-context.md`](project-context.md)（如果存在）。架构师工作流也会加载它，以便在设计架构时尊重您的技术偏好。 + +**由以下工作流加载：** +- `create-architecture` — 在解决方案设计期间尊重技术偏好 +- `create-story` — 使用项目模式指导用户故事创建 +- `dev-story` — 指导实施决策 +- `code-review` — 根据项目标准进行验证 +- `quick-dev` — 在实施技术规范时应用模式 +- `sprint-planning`、`retrospective`、`correct-course` — 提供项目范围的上下文 + +## 何时创建 + +[`project-context.md`](project-context.md) 文件在项目的任何阶段都很有用： + +| 场景 | 何时创建 | 目的 | +|----------|----------------|---------| +| **新项目，架构之前** | 手动，在 `create-architecture` 之前 | 记录您的技术偏好，以便架构师尊重它们 | +| **新项目，架构之后** | 通过 `generate-project-context` 或手动 | 捕获架构决策，供实施智能体使用 | +| **现有项目** | 通过 `generate-project-context` | 发现现有模式，以便智能体遵循既定约定 | +| **快速流程项目** | 在 `quick-dev` 之前或期间 | 确保快速实施尊重您的模式 | + +:::tip[推荐] +对于新项目，如果您有强烈的技术偏好，请在架构之前手动创建。否则，在架构之后生成它以捕获这些决策。 +::: + +## 文件内容 + +该文件有两个主要部分： + +### 技术栈与版本 + +记录项目使用的框架、语言和工具及其具体版本： + +```markdown +## Technology Stack & Versions + +- Node.js 20.x, TypeScript 5.3, React 18.2 +- State: Zustand (not Redux) +- Testing: Vitest, Playwright, MSW +- Styling: Tailwind CSS with custom design tokens +``` + +### 关键实施规则 + +记录智能体可能忽略的模式和约定： + +```markdown +## Critical Implementation Rules + +**TypeScript Configuration:** +- Strict mode enabled — no `any` types without explicit approval +- Use `interface` for public APIs, `type` for unions/intersections + +**Code Organization:** +- Components in `/src/components/` with co-located `.test.tsx` +- Utilities in `/src/lib/` for reusable pure functions +- API calls use the `apiClient` singleton — never fetch directly + +**Testing Patterns:** +- Unit tests focus on business logic, not implementation details +- Integration tests use MSW to mock API responses +- E2E tests cover critical user journeys only + +**Framework-Specific:** +- All async operations use the `handleError` wrapper for consistent error handling +- Feature flags accessed via `featureFlag()` from `@/lib/flags` +- New routes follow the file-based routing pattern in `/src/app/` +``` + +专注于那些**不明显**的内容——智能体可能无法从阅读代码片段中推断出来的内容。不要记录普遍适用的标准实践。 + +## 创建文件 + +您有三个选择： + +### 手动创建 + +在 `_bmad-output/project-context.md` 创建文件并添加您的规则： + +```bash +# In your project root +mkdir -p _bmad-output +touch _bmad-output/project-context.md +``` + +使用您的技术栈和实施规则编辑它。架构师和实施工作流将自动查找并加载它。 + +### 架构后生成 + +在完成架构后运行 `generate-project-context` 工作流： + +```bash +/bmad-bmm-generate-project-context +``` + +这将扫描您的架构文档和项目文件，生成一个捕获所做决策的上下文文件。 + +### 为现有项目生成 + +对于现有项目，运行 `generate-project-context` 以发现现有模式： + +```bash +/bmad-bmm-generate-project-context +``` + +该工作流分析您的代码库以识别约定，然后生成一个您可以审查和优化的上下文文件。 + +## 为什么重要 + +没有 [`project-context.md`](project-context.md)，智能体会做出可能与您的项目不匹配的假设： + +| 没有上下文 | 有上下文 | +|----------------|--------------| +| 使用通用模式 | 遵循您的既定约定 | +| 用户故事之间风格不一致 | 实施一致 | +| 可能错过项目特定的约束 | 尊重所有技术需求 | +| 每个智能体独立决策 | 所有智能体遵循相同规则 | + +这对于以下情况尤其重要： +- **快速流程** — 跳过 PRD 和架构，因此上下文文件填补了空白 +- **团队项目** — 确保所有智能体遵循相同的标准 +- **现有项目** — 防止破坏既定模式 + +## 编辑和更新 + +[`project-context.md`](project-context.md) 文件是一个动态文档。在以下情况下更新它： + +- 架构决策发生变化 +- 建立了新的约定 +- 模式在实施过程中演变 +- 您从智能体行为中发现差距 + +您可以随时手动编辑它，或者在重大更改后重新运行 `generate-project-context` 来更新它。 + +:::note[文件位置] +默认位置是 `_bmad-output/project-context.md`。工作流在那里搜索它，并且还会检查项目中任何位置的 `**/project-context.md`。 +::: + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列自动化或半自动化的任务流程。 +- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。 +- **LLM**：大语言模型（Large Language Model）。指基于深度学习的自然语言处理模型。 +- **singleton**：单例。一种设计模式，确保一个类只有一个实例。 +- **E2E**：端到端（End-to-End）。指从用户角度出发的完整测试流程。 +- **MSW**：Mock Service Worker。用于模拟 API 响应的库。 +- **Vitest**：基于 Vite 的单元测试框架。 +- **Playwright**：端到端测试框架。 +- **Zustand**：轻量级状态管理库。 +- **Redux**：JavaScript 应用状态管理库。 +- **Tailwind CSS**：实用优先的 CSS 框架。 +- **TypeScript**：JavaScript 的超集，添加了静态类型。 +- **React**：用于构建用户界面的 JavaScript 库。 +- **Node.js**：基于 Chrome V8 引擎的 JavaScript 运行时。 diff --git a/docs/zh-cn/explanation/quick-flow.md b/docs/zh-cn/explanation/quick-flow.md new file mode 100644 index 000000000..ac1af0446 --- /dev/null +++ b/docs/zh-cn/explanation/quick-flow.md @@ -0,0 +1,93 @@ +--- +title: "快速流程" +description: 小型变更的快速通道 - 跳过完整方法论 +sidebar: + order: 1 +--- + +跳过繁琐流程。快速流程通过两条命令将你从想法带到可运行的代码 - 无需产品简报、无需 PRD、无需架构文档。 + +## 何时使用 + +- Bug 修复和补丁 +- 重构现有代码 +- 小型、易于理解的功能 +- 原型设计和探索性开发 +- 单智能体工作，一名开发者可以掌控完整范围 + +## 何时不使用 + +- 需要利益相关者对齐的新产品或平台 +- 跨越多个组件或团队的主要功能 +- 需要架构决策的工作（数据库架构、API 契约、服务边界） +- 需求不明确或有争议的任何工作 + +:::caution[Scope Creep] +如果你启动快速流程后发现范围超出预期，`quick-dev` 会检测到并提供升级选项。你可以在任何时间切换到完整的 PRD 工作流程，而不会丢失你的工作。 +::: + +## 工作原理 + +快速流程有两条命令，每条都由结构化的工作流程支持。你可以一起运行它们，也可以独立运行。 + +### quick-spec：规划 + +运行 `quick-spec`，Barry（Quick Flow 智能体）会引导你完成对话式发现过程： + +1. **理解** - 你描述想要构建的内容。Barry 扫描代码库以提出有针对性的问题，然后捕获问题陈述、解决方案方法和范围边界。 +2. **调查** - Barry 读取相关文件，映射代码模式，识别需要修改的文件，并记录技术上下文。 +3. **生成** - 生成完整的技术规范，包含有序的实现任务（具体文件路径和操作）、Given/When/Then 格式的验收标准、测试策略和依赖项。 +4. **审查** - 展示完整规范供你确认。你可以在最终定稿前进行编辑、提问、运行对抗性审查或使用高级启发式方法进行优化。 + +输出是一个 `tech-spec-{slug}.md` 文件，保存到项目的实现工件文件夹中。它包含新智能体实现功能所需的一切 - 无需对话历史。 + +### quick-dev：构建 + +运行 `quick-dev`，Barry 实现工作。它以两种模式运行： + +- **技术规范模式** - 指向规范文件（`quick-dev tech-spec-auth.md`），它按顺序执行每个任务，编写测试，并验证验收标准。 +- **直接模式** - 直接给出指令（`quick-dev "refactor the auth middleware"`），它收集上下文，构建心智计划，并执行。 + +实现后，`quick-dev` 针对所有任务和验收标准运行自检审计，然后触发差异的对抗性代码审查。发现的问题会呈现给你，以便在收尾前解决。 + +:::tip[Fresh Context] +为获得最佳效果，在完成 `quick-spec` 后，在新对话中运行 `quick-dev`。这为实现智能体提供了专注于构建的干净上下文。 +::: + +## 快速流程跳过的内容 + +完整的 BMad 方法在编写任何代码之前会生成产品简报、PRD、架构文档和 Epic/Story 分解。Quick Flow 用单个技术规范替代所有这些。这之所以有效，是因为 Quick Flow 针对以下变更： + +- 产品方向已确立 +- 架构决策已做出 +- 单个开发者可以推理完整范围 +- 需求可以在一次对话中涵盖 + +## 升级到完整 BMad 方法 + +快速流程包含内置的范围检测护栏。当你使用直接请求运行 `quick-dev` 时，它会评估多组件提及、系统级语言和方法不确定性等信号。如果检测到工作超出快速流程范围： + +- **轻度升级** - 建议先运行 `quick-spec` 创建计划 +- **重度升级** - 建议切换到完整的 BMad 方法 PRD 流程 + +你也可以随时手动升级。你的技术规范工作会继续推进 - 它将成为更广泛规划过程的输入，而不是被丢弃。 + +--- +## 术语说明 + +- **Quick Flow**：快速流程。BMad 方法中用于小型变更的简化工作流程，跳过完整的产品规划和架构文档阶段。 +- **PRD**：Product Requirements Document，产品需求文档。详细描述产品功能、需求和验收标准的文档。 +- **Product Brief**：产品简报。概述产品愿景、目标和范围的高层文档。 +- **Architecture doc**：架构文档。描述系统架构、组件设计和技术决策的文档。 +- **Epic/Story**：史诗/故事。敏捷开发中的工作单元，Epic 是大型功能集合，Story 是具体用户故事。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **Scope Creep**：范围蔓延。项目范围在开发过程中逐渐扩大，超出原始计划的现象。 +- **tech-spec**：技术规范。详细描述技术实现方案、任务分解和验收标准的文档。 +- **slug**：短标识符。用于生成 URL 或文件名的简短、唯一的字符串标识。 +- **Given/When/Then**：一种行为驱动开发（BDD）的测试场景描述格式，用于定义验收标准。 +- **adversarial review**：对抗性审查。一种代码审查方法，模拟攻击者视角以发现潜在问题和漏洞。 +- **elicitation**：启发式方法。通过提问和对话引导来获取信息、澄清需求的技术。 +- **stakeholder**：利益相关者。对项目有利益或影响的个人或组织。 +- **API contracts**：API 契约。定义 API 接口规范、请求/响应格式和行为约定的文档。 +- **service boundaries**：服务边界。定义服务职责范围和边界的架构概念。 +- **spikes**：探索性开发。用于探索技术可行性或解决方案的短期研究活动。 diff --git a/docs/zh-cn/explanation/why-solutioning-matters.md b/docs/zh-cn/explanation/why-solutioning-matters.md new file mode 100644 index 000000000..27e8f96ca --- /dev/null +++ b/docs/zh-cn/explanation/why-solutioning-matters.md @@ -0,0 +1,90 @@ +--- +title: "为什么解决方案阶段很重要" +description: 理解为什么解决方案阶段对于多史诗项目至关重要 +sidebar: + order: 3 +--- + + +阶段 3（解决方案）将构建**什么**（来自规划）转化为**如何**构建（技术设计）。该阶段通过在实施开始前记录架构决策，防止多史诗项目中的智能体冲突。 + +## 没有解决方案阶段的问题 + +```text +智能体 1 使用 REST API 实现史诗 1 +智能体 2 使用 GraphQL 实现史诗 2 +结果：API 设计不一致，集成噩梦 +``` + +当多个智能体在没有共享架构指导的情况下实现系统的不同部分时，它们会做出可能冲突的独立技术决策。 + +## 有解决方案阶段的解决方案 + +```text +架构工作流决定："所有 API 使用 GraphQL" +所有智能体遵循架构决策 +结果：实现一致，无冲突 +``` + +通过明确记录技术决策，所有智能体都能一致地实现，集成变得简单直接。 + +## 解决方案阶段 vs 规划阶段 + +| 方面 | 规划（阶段 2） | 解决方案（阶段 3） | +| -------- | ----------------------- | --------------------------------- | +| 问题 | 做什么和为什么？ | 如何做？然后是什么工作单元？ | +| 输出 | FRs/NFRs（需求） | 架构 + 史诗/用户故事 | +| 智能体 | PM | 架构师 → PM | +| 受众 | 利益相关者 | 开发人员 | +| 文档 | PRD（FRs/NFRs） | 架构 + 史诗文件 | +| 层级 | 业务逻辑 | 技术设计 + 工作分解 | + +## 核心原则 + +**使技术决策明确且有文档记录**，以便所有智能体一致地实现。 + +这可以防止： +- API 风格冲突（REST vs GraphQL） +- 数据库设计不一致 +- 状态管理分歧 +- 命名约定不匹配 +- 安全方法差异 + +## 何时需要解决方案阶段 + +| 流程 | 需要解决方案阶段？ | +|-------|----------------------| +| Quick Flow | 否 - 完全跳过 | +| BMad Method Simple | 可选 | +| BMad Method Complex | 是 | +| Enterprise | 是 | + +:::tip[经验法则] +如果你有多个可能由不同智能体实现的史诗，你需要解决方案阶段。 +::: + +## 跳过的代价 + +在复杂项目中跳过解决方案阶段会导致： + +- **集成问题**在冲刺中期发现 +- **返工**由于实现冲突 +- **开发时间更长**整体 +- **技术债务**来自不一致模式 + +:::caution[成本倍增] +在解决方案阶段发现对齐问题比在实施期间发现要快 10 倍。 +::: + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **epic**：史诗。在敏捷开发中，指一个大型的工作项，可分解为多个用户故事。 +- **REST API**：表述性状态传递应用程序接口。一种基于 HTTP 协议的 Web API 设计风格。 +- **GraphQL**：一种用于 API 的查询语言和运行时环境。 +- **FRs/NFRs**：功能需求/非功能需求。Functional Requirements/Non-Functional Requirements 的缩写。 +- **PRD**：产品需求文档。Product Requirements Document 的缩写。 +- **PM**：产品经理。Product Manager 的缩写。 +- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周。 +- **technical debt**：技术债务。指为了短期目标而选择的不完美技术方案，未来需要付出额外成本来修复。 diff --git a/docs/zh-cn/how-to/customize-bmad.md b/docs/zh-cn/how-to/customize-bmad.md new file mode 100644 index 000000000..55396ac6e --- /dev/null +++ b/docs/zh-cn/how-to/customize-bmad.md @@ -0,0 +1,182 @@ +--- +title: "如何自定义 BMad" +description: 自定义智能体、工作流和模块，同时保持更新兼容性 +sidebar: + order: 7 +--- + +使用 `.customize.yaml` 文件来调整智能体行为、角色和菜单，同时在更新过程中保留您的更改。 + +## 何时使用此功能 + +- 您想要更改智能体的名称、个性或沟通风格 +- 您需要智能体记住项目特定的上下文 +- 您想要添加自定义菜单项来触发您自己的工作流或提示 +- 您希望智能体在每次启动时执行特定操作 + +:::note[前置条件] +- 在项目中安装了 BMad（参见[如何安装 BMad](./install-bmad.md)） +- 用于编辑 YAML 文件的文本编辑器 +::: + +:::caution[保护您的自定义配置] +始终使用此处描述的 `.customize.yaml` 文件，而不是直接编辑智能体文件。安装程序在更新期间会覆盖智能体文件，但会保留您的 `.customize.yaml` 更改。 +::: + +## 步骤 + +### 1. 定位自定义文件 + +安装后，在以下位置为每个智能体找到一个 `.customize.yaml` 文件： + +```text +_bmad/_config/agents/ +├── core-bmad-master.customize.yaml +├── bmm-dev.customize.yaml +├── bmm-pm.customize.yaml +└── ...（每个已安装的智能体一个文件） +``` + +### 2. 编辑自定义文件 + +打开您想要修改的智能体的 `.customize.yaml` 文件。每个部分都是可选的——只自定义您需要的内容。 + +| 部分 | 行为 | 用途 | +| ------------------ | -------- | ---------------------------------------------- | +| `agent.metadata` | 替换 | 覆盖智能体的显示名称 | +| `persona` | 替换 | 设置角色、身份、风格和原则 | +| `memories` | 追加 | 添加智能体始终会记住的持久上下文 | +| `menu` | 追加 | 为工作流或提示添加自定义菜单项 | +| `critical_actions` | 追加 | 定义智能体的启动指令 | +| `prompts` | 追加 | 创建可重复使用的提示供菜单操作使用 | + +标记为 **替换** 的部分会完全覆盖智能体的默认设置。标记为 **追加** 的部分会添加到现有配置中。 + +**智能体名称** + +更改智能体的自我介绍方式： + +```yaml +agent: + metadata: + name: 'Spongebob' # 默认值："Amelia" +``` + +**角色** + +替换智能体的个性、角色和沟通风格： + +```yaml +persona: + role: 'Senior Full-Stack Engineer' + identity: 'Lives in a pineapple (under the sea)' + communication_style: 'Spongebob annoying' + principles: + - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep' + - 'Favor composition over inheritance' +``` + +`persona` 部分会替换整个默认角色，因此如果您设置它，请包含所有四个字段。 + +**记忆** + +添加智能体将始终记住的持久上下文： + +```yaml +memories: + - 'Works at Krusty Krab' + - 'Favorite Celebrity: David Hasslehoff' + - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed' +``` + +**菜单项** + +向智能体的显示菜单添加自定义条目。每个条目需要一个 `trigger`、一个目标（`workflow` 路径或 `action` 引用）和一个 `description`： + +```yaml +menu: + - trigger: my-workflow + workflow: 'my-custom/workflows/my-workflow.yaml' + description: My custom workflow + - trigger: deploy + action: '#deploy-prompt' + description: Deploy to production +``` + +**关键操作** + +定义智能体启动时运行的指令： + +```yaml +critical_actions: + - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention' +``` + +**自定义提示** + +创建可重复使用的提示，菜单项可以通过 `action="#id"` 引用： + +```yaml +prompts: + - id: deploy-prompt + content: | + Deploy the current branch to production: + 1. Run all tests + 2. Build the project + 3. Execute deployment script +``` + +### 3. 应用您的更改 + +编辑后，重新编译智能体以应用更改： + +```bash +npx bmad-method install +``` + +安装程序会检测现有安装并提供以下选项： + +| Option | What It Does | +| ---------------------------- | ------------------------------------------------------------------- | +| **Quick Update** | 将所有模块更新到最新版本并重新编译所有智能体 | +| **Recompile Agents** | 仅应用自定义配置，不更新模块文件 | +| **Modify BMad Installation** | 用于添加或删除模块的完整安装流程 | + +对于仅自定义配置的更改，**Recompile Agents** 是最快的选项。 + +## 故障排除 + +**更改未生效？** + +- 运行 `npx bmad-method install` 并选择 **Recompile Agents** 以应用更改 +- 检查您的 YAML 语法是否有效（缩进很重要） +- 验证您编辑的是该智能体正确的 `.customize.yaml` 文件 + +**智能体无法加载？** + +- 使用在线 YAML 验证器检查 YAML 语法错误 +- 确保在取消注释后没有留下空字段 +- 尝试恢复到原始模板并重新构建 + +**需要重置智能体？** + +- 清空或删除智能体的 `.customize.yaml` 文件 +- 运行 `npx bmad-method install` 并选择 **Recompile Agents** 以恢复默认设置 + +## 工作流自定义 + +对现有 BMad Method 工作流和技能的自定义即将推出。 + +## 模块自定义 + +关于构建扩展模块和自定义现有模块的指南即将推出。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 +- **persona**：角色。指智能体的身份、个性、沟通风格和行为原则的集合。 +- **memory**：记忆。指智能体持久存储的上下文信息，用于在对话中保持连贯性。 +- **critical action**：关键操作。指智能体启动时必须执行的指令或任务。 +- **prompt**：提示。指发送给智能体的输入文本，用于引导其生成特定响应或执行特定操作。 diff --git a/docs/zh-cn/how-to/established-projects.md b/docs/zh-cn/how-to/established-projects.md new file mode 100644 index 000000000..5b853e3c2 --- /dev/null +++ b/docs/zh-cn/how-to/established-projects.md @@ -0,0 +1,134 @@ +--- +title: "既有项目" +description: 如何在现有代码库中使用 BMad Method +sidebar: + order: 6 +--- + +在现有项目和遗留代码库上工作时，有效使用 BMad Method。 + +本指南涵盖了使用 BMad Method 接入现有项目的核心工作流程。 + +:::note[前置条件] +- 已安装 BMad Method（`npx bmad-method install`） +- 一个你想要处理的现有代码库 +- 访问 AI 驱动的 IDE（Claude Code 或 Cursor） +::: + +## 步骤 1：清理已完成的规划产物 + +如果你通过 BMad 流程完成了所有 PRD 史诗和用户故事，请清理这些文件。归档它们、删除它们，或者在需要时依赖版本历史。不要将这些文件保留在： + +- `docs/` +- `_bmad-output/planning-artifacts/` +- `_bmad-output/implementation-artifacts/` + +## 步骤 2：创建项目上下文 + +:::tip[推荐用于既有项目] +生成 `project-context.md` 以捕获你现有代码库的模式和约定。这确保 AI 智能体在实施变更时遵循你既定的实践。 +::: + +运行生成项目上下文工作流程： + +```bash +/bmad-bmm-generate-project-context +``` + +这将扫描你的代码库以识别： +- 技术栈和版本 +- 代码组织模式 +- 命名约定 +- 测试方法 +- 框架特定模式 + +你可以查看和完善生成的文件，或者如果你更喜欢，可以在 `_bmad-output/project-context.md` 手动创建它。 + +[了解更多关于项目上下文](../explanation/project-context.md) + +## 步骤 3：维护高质量项目文档 + +你的 `docs/` 文件夹应包含简洁、组织良好的文档，准确代表你的项目： + +- 意图和业务理由 +- 业务规则 +- 架构 +- 任何其他相关的项目信息 + +对于复杂项目，考虑使用 `document-project` 工作流程。它提供运行时变体，将扫描你的整个项目并记录其实际当前状态。 + +## 步骤 3：获取帮助 + +### BMad-Help：你的起点 + +**随时运行 `bmad-help`，当你不确定下一步该做什么时。** 这个智能指南： + +- 检查你的项目以查看已经完成了什么 +- 根据你安装的模块显示选项 +- 理解自然语言查询 + +``` +bmad-help 我有一个现有的 Rails 应用，我应该从哪里开始？ +bmad-help quick-flow 和完整方法有什么区别？ +bmad-help 显示我有哪些可用的工作流程 +``` + +BMad-Help 还会在**每个工作流程结束时自动运行**，提供关于下一步该做什么的清晰指导。 + +### 选择你的方法 + +根据变更范围，你有两个主要选项： + +| 范围 | 推荐方法 | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | +| **小型更新或添加** | 使用 `quick-flow-solo-dev` 创建技术规范并实施变更。完整的四阶段 BMad Method 可能有些过度。 | +| **重大变更或添加** | 从 BMad Method 开始，根据需要应用或多或少的严谨性。 | + +### 在创建 PRD 期间 + +在创建简报或直接进入 PRD 时，确保智能体： + +- 查找并分析你现有的项目文档 +- 阅读关于你当前系统的适当上下文 + +你可以明确地指导智能体，但目标是确保新功能与你的现有系统良好集成。 + +### UX 考量 + +UX 工作是可选的。决定不取决于你的项目是否有 UX，而取决于： + +- 你是否将处理 UX 变更 +- 是否需要重要的新 UX 设计或模式 + +如果你的变更只是对你满意的现有屏幕进行简单更新，则不需要完整的 UX 流程。 + +### 架构考量 + +在进行架构工作时，确保架构师： + +- 使用适当的已记录文件 +- 扫描现有代码库 + +在此处要密切注意，以防止重新发明轮子或做出与你现有架构不一致的决定。 + +## 更多信息 + +- **[快速修复](./quick-fixes.md)** - 错误修复和临时变更 +- **[既有项目 FAQ](../explanation/established-projects-faq.md)** - 关于在既有项目上工作的常见问题 + +--- +## 术语说明 + +- **BMad Method**：BMad 方法。一种结构化的软件开发方法论，用于指导从分析到实施的完整流程。 +- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。 +- **epic**：史诗。大型功能或用户故事的集合，通常需要较长时间完成。 +- **story**：用户故事。描述用户需求的简短陈述，通常遵循"作为...我想要...以便于..."的格式。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试、构建等功能的软件工具。 +- **UX**：用户体验（User Experience）。用户在使用产品或服务过程中的整体感受和交互体验。 +- **tech-spec**：技术规范（Technical Specification）。描述技术实现细节、架构设计和开发标准的文档。 +- **quick-flow**：快速流程。BMad Method 中的一种简化工作流程，适用于小型变更或快速迭代。 +- **legacy codebase**：遗留代码库。指历史遗留的、可能缺乏文档或使用过时技术的代码集合。 +- **project context**：项目上下文。描述项目技术栈、约定、模式等背景信息的文档。 +- **artifact**：产物。在开发过程中生成的文档、代码或其他输出物。 +- **runtime variant**：运行时变体。在程序运行时可选择或切换的不同实现方式或配置。 diff --git a/docs/zh-cn/how-to/get-answers-about-bmad.md b/docs/zh-cn/how-to/get-answers-about-bmad.md new file mode 100644 index 000000000..aa96acf60 --- /dev/null +++ b/docs/zh-cn/how-to/get-answers-about-bmad.md @@ -0,0 +1,144 @@ +--- +title: "如何获取关于 BMad 的答案" +description: 使用 LLM 快速回答您自己的 BMad 问题 +sidebar: + order: 4 +--- + +## 从这里开始：BMad-Help + +**获取关于 BMad 答案的最快方式是 `bmad-help`。** 这个智能指南可以回答超过 80% 的问题，并且直接在您的 IDE 中可用，方便您工作时使用。 + +BMad-Help 不仅仅是一个查询工具——它： +- **检查您的项目**以查看已完成的内容 +- **理解自然语言**——用简单的英语提问 +- **根据您安装的模块变化**——显示相关选项 +- **在工作流后自动运行**——告诉您接下来该做什么 +- **推荐第一个必需任务**——无需猜测从哪里开始 + +### 如何使用 BMad-Help + +只需使用斜杠命令运行它： + +``` +bmad-help +``` + +或者结合自然语言查询： + +``` +bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？ +bmad-help 我在 UX 设计方面有哪些选择？ +bmad-help 我在 PRD 工作流上卡住了 +bmad-help 向我展示到目前为止已完成的内容 +``` + +BMad-Help 会回应： +- 针对您情况的建议 +- 第一个必需任务是什么 +- 流程的其余部分是什么样的 + +--- + +## 何时使用本指南 + +在以下情况下使用本节： +- 您想了解 BMad 的架构或内部机制 +- 您需要 BMad-Help 提供范围之外的答案 +- 您在安装前研究 BMad +- 您想直接探索源代码 + +## 步骤 + +### 1. 选择您的来源 + +| 来源 | 最适合用于 | 示例 | +| -------------------- | ----------------------------------------- | ---------------------------- | +| **`_bmad` 文件夹** | BMad 如何工作——智能体、工作流、提示词 | "PM 智能体做什么？" | +| **完整的 GitHub 仓库** | 历史、安装程序、架构 | "v6 中有什么变化？" | +| **`llms-full.txt`** | 来自文档的快速概述 | "解释 BMad 的四个阶段" | + +`_bmad` 文件夹在您安装 BMad 时创建。如果您还没有它，请改为克隆仓库。 + +### 2. 将您的 AI 指向来源 + +**如果您的 AI 可以读取文件（Claude Code、Cursor 等）：** + +- **已安装 BMad：** 指向 `_bmad` 文件夹并直接提问 +- **想要更深入的上下文：** 克隆[完整仓库](https://github.com/bmad-code-org/BMAD-METHOD) + +**如果您使用 ChatGPT 或 Claude.ai：** + +将 `llms-full.txt` 获取到您的会话中： + +```text +https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt +``` + + +### 3. 提出您的问题 + +:::note[示例] +**问：** "告诉我用 BMad 构建某物的最快方式" + +**答：** 使用快速流程：运行 `quick-spec` 编写技术规范，然后运行 `quick-dev` 实现它——跳过完整的规划阶段。 +::: + +## 您将获得什么 + +关于 BMad 的直接答案——智能体如何工作、工作流做什么、为什么事物以这种方式构建——无需等待其他人回应。 + +## 提示 + +- **验证令人惊讶的答案**——LLM 偶尔会出错。检查源文件或在 Discord 上询问。 +- **具体化**——"PRD 工作流的第 3 步做什么？"比"PRD 如何工作？"更好 + +## 仍然卡住了？ + +尝试了 LLM 方法但仍需要帮助？您现在有一个更好的问题可以问。 + +| 频道 | 用于 | +| ------------------------- | ------------------------------------------- | +| `#bmad-method-help` | 快速问题（实时聊天） | +| `help-requests` 论坛 | 详细问题（可搜索、持久） | +| `#suggestions-feedback` | 想法和功能请求 | +| `#report-bugs-and-issues` | 错误报告 | + +**Discord：** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) + +**GitHub Issues：** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)（用于明确的错误） + +*你！* + *卡住* + *在队列中——* + *等待* + *等待谁？* + +*来源* + *就在那里，* + *显而易见！* + +*指向* + *你的机器。* + *释放它。* + +*它读取。* + *它说话。* + *尽管问——* + +*为什么要等* + *明天* + *当你拥有* + *今天？* + +*—Claude* + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **LLM**：大语言模型。基于深度学习的自然语言处理模型，能够理解和生成人类语言。 +- **SaaS**：软件即服务。一种通过互联网提供软件应用的交付模式。 +- **UX**：用户体验。用户在使用产品或服务过程中建立的主观感受和评价。 +- **PRD**：产品需求文档。详细描述产品功能、特性和需求的正式文档。 +- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。 diff --git a/docs/zh-cn/how-to/install-bmad.md b/docs/zh-cn/how-to/install-bmad.md new file mode 100644 index 000000000..e0309d2b9 --- /dev/null +++ b/docs/zh-cn/how-to/install-bmad.md @@ -0,0 +1,105 @@ +--- +title: "如何安装 BMad" +description: 在项目中安装 BMad 的分步指南 +sidebar: + order: 1 +--- + +使用 `npx bmad-method install` 命令在项目中设置 BMad，并选择你需要的模块和 AI 工具。 + +如果你想使用非交互式安装程序并在命令行中提供所有安装选项，请参阅[本指南](./non-interactive-installation.md)。 + +## 何时使用 + +- 使用 BMad 启动新项目 +- 将 BMad 添加到现有代码库 +- 更新现有的 BMad 安装 + +:::note[前置条件] +- **Node.js** 20+（安装程序必需） +- **Git**（推荐） +- **AI 工具**（Claude Code、Cursor 或类似工具） +::: + +## 步骤 + +### 1. 运行安装程序 + +```bash +npx bmad-method install +``` + +:::tip[最新版本] +要从主分支安装最新版本（可能不稳定）： +```bash +npx github:bmad-code-org/BMAD-METHOD install +``` +::: + +### 2. 选择安装位置 + +安装程序会询问在哪里安装 BMad 文件： + +- 当前目录（如果你自己创建了目录并从该目录运行，推荐用于新项目） +- 自定义路径 + +### 3. 选择你的 AI 工具 + +选择你使用的 AI 工具： + +- Claude Code +- Cursor +- 其他 + +每个工具都有自己的命令集成方式。安装程序会创建微小的提示文件来激活工作流和智能体——它只是将它们放在工具期望找到的位置。 + +### 4. 选择模块 + +安装程序会显示可用的模块。选择你需要的模块——大多数用户只需要 **BMad Method**（软件开发模块）。 + +### 5. 按照提示操作 + +安装程序会引导你完成剩余步骤——自定义内容、设置等。 + +## 你将获得 + +```text +your-project/ +├── _bmad/ +│ ├── bmm/ # 你选择的模块 +│ │ └── config.yaml # 模块设置（如果你需要更改它们） +│ ├── core/ # 必需的核心模块 +│ └── ... +├── _bmad-output/ # 生成的工件 +├── .claude/ # Claude Code 命令（如果使用 Claude Code） +└── .kiro/ # Kiro 引导文件（如果使用 Kiro） +``` + +## 验证安装 + +运行 `bmad-help` 来验证一切正常并查看下一步操作。 + +**BMad-Help 是你的智能向导**，它会： +- 确认你的安装正常工作 +- 根据你安装的模块显示可用内容 +- 推荐你的第一步 + +你也可以向它提问： +``` +bmad-help 我刚安装完成，应该先做什么？ +bmad-help 对于 SaaS 项目我有哪些选项？ +``` + +## 故障排除 + +**安装程序抛出错误**——将输出复制粘贴到你的 AI 助手中，让它来解决问题。 + +**安装程序工作正常但后续出现问题**——你的 AI 需要 BMad 上下文才能提供帮助。请参阅[如何获取关于 BMad 的答案](./get-answers-about-bmad.md)了解如何将你的 AI 指向正确的来源。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 +- **module**：模块。指软件系统中可独立开发、测试和维护的功能单元。 +- **artifact**：工件。指在软件开发过程中生成的任何输出，如文档、代码、配置文件等。 diff --git a/docs/zh-cn/how-to/non-interactive-installation.md b/docs/zh-cn/how-to/non-interactive-installation.md new file mode 100644 index 000000000..11d57a712 --- /dev/null +++ b/docs/zh-cn/how-to/non-interactive-installation.md @@ -0,0 +1,181 @@ +--- +title: "非交互式安装" +description: 使用命令行标志安装 BMad，适用于 CI/CD 流水线和自动化部署 +sidebar: + order: 2 +--- + +使用命令行标志以非交互方式安装 BMad。这适用于： + +## 使用场景 + +- 自动化部署和 CI/CD 流水线 +- 脚本化安装 +- 跨多个项目的批量安装 +- 使用已知配置的快速安装 + +:::note[前置条件] +需要 [Node.js](https://nodejs.org) v20+ 和 `npx`（随 npm 附带）。 +::: + +## 可用标志 + +### 安装选项 + +| 标志 | 描述 | 示例 | +|------|-------------|---------| +| `--directory ` | 安装目录 | `--directory ~/projects/myapp` | +| `--modules ` | 逗号分隔的模块 ID | `--modules bmm,bmb` | +| `--tools ` | 逗号分隔的工具/IDE ID（使用 `none` 跳过） | `--tools claude-code,cursor` 或 `--tools none` | +| `--custom-content ` | 逗号分隔的自定义模块路径 | `--custom-content ~/my-module,~/another-module` | +| `--action ` | 对现有安装的操作：`install`（默认）、`update`、`quick-update` 或 `compile-agents` | `--action quick-update` | + +### 核心配置 + +| 标志 | 描述 | 默认值 | +|------|-------------|---------| +| `--user-name ` | 智能体使用的名称 | 系统用户名 | +| `--communication-language ` | 智能体通信语言 | 英语 | +| `--document-output-language ` | 文档输出语言 | 英语 | +| `--output-folder ` | 输出文件夹路径 | _bmad-output | + +### 其他选项 + +| 标志 | 描述 | +|------|-------------| +| `-y, --yes` | 接受所有默认值并跳过提示 | +| `-d, --debug` | 启用清单生成的调试输出 | + +## 模块 ID + +`--modules` 标志可用的模块 ID： + +- `bmm` — BMad Method Master +- `bmb` — BMad Builder + +查看 [BMad 注册表](https://github.com/bmad-code-org) 获取可用的外部模块。 + +## 工具/IDE ID + +`--tools` 标志可用的工具 ID： + +**推荐：** `claude-code`、`cursor` + +运行一次 `npx bmad-method install` 交互式安装以查看完整的当前支持工具列表，或查看 [平台代码配置](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/tools/cli/installers/lib/ide/platform-codes.yaml)。 + +## 安装模式 + +| 模式 | 描述 | 示例 | +|------|-------------|---------| +| 完全非交互式 | 提供所有标志以跳过所有提示 | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` | +| 半交互式 | 提供部分标志；BMad 提示其余部分 | `npx bmad-method install --directory . --modules bmm` | +| 仅使用默认值 | 使用 `-y` 接受所有默认值 | `npx bmad-method install --yes` | +| 不包含工具 | 跳过工具/IDE 配置 | `npx bmad-method install --modules bmm --tools none` | + +## 示例 + +### CI/CD 流水线安装 + +```bash +#!/bin/bash +# install-bmad.sh + +npx bmad-method install \ + --directory "${GITHUB_WORKSPACE}" \ + --modules bmm \ + --tools claude-code \ + --user-name "CI Bot" \ + --communication-language English \ + --document-output-language English \ + --output-folder _bmad-output \ + --yes +``` + +### 更新现有安装 + +```bash +npx bmad-method install \ + --directory ~/projects/myapp \ + --action update \ + --modules bmm,bmb,custom-module +``` + +### 快速更新（保留设置） + +```bash +npx bmad-method install \ + --directory ~/projects/myapp \ + --action quick-update +``` + +### 使用自定义内容安装 + +```bash +npx bmad-method install \ + --directory ~/projects/myapp \ + --modules bmm \ + --custom-content ~/my-custom-module,~/another-module \ + --tools claude-code +``` + +## 安装结果 + +- 项目中完全配置的 `_bmad/` 目录 +- 为所选模块和工具编译的智能体和工作流 +- 用于生成产物的 `_bmad-output/` 文件夹 + +## 验证和错误处理 + +BMad 会验证所有提供的标志： + +- **目录** — 必须是具有写入权限的有效路径 +- **模块** — 对无效的模块 ID 发出警告（但不会失败） +- **工具** — 对无效的工具 ID 发出警告（但不会失败） +- **自定义内容** — 每个路径必须包含有效的 `module.yaml` 文件 +- **操作** — 必须是以下之一：`install`、`update`、`quick-update`、`compile-agents` + +无效值将： +1. 显示错误并退出（对于目录等关键选项） +2. 显示警告并跳过（对于自定义内容等可选项目） +3. 回退到交互式提示（对于缺失的必需值） + +:::tip[最佳实践] +- 为 `--directory` 使用绝对路径以避免歧义 +- 在 CI/CD 流水线中使用前先在本地测试标志 +- 结合 `-y` 实现真正的无人值守安装 +- 如果在安装过程中遇到问题，使用 `--debug` +::: + +## 故障排除 + +### 安装失败，提示"Invalid directory" + +- 目录路径必须存在（或其父目录必须存在） +- 您需要写入权限 +- 路径必须是绝对路径或相对于当前目录的正确相对路径 + +### 未找到模块 + +- 验证模块 ID 是否正确 +- 外部模块必须在注册表中可用 + +### 自定义内容路径无效 + +确保每个自定义内容路径： +- 指向一个目录 +- 在根目录中包含 `module.yaml` 文件 +- 在 `module.yaml` 中有 `code` 字段 + +:::note[仍然卡住了？] +使用 `--debug` 运行以获取详细输出，尝试交互模式以隔离问题，或在 报告。 +::: + +--- +## 术语说明 + +- **CI/CD**：持续集成/持续部署。一种自动化软件开发流程的实践，用于频繁集成代码更改并自动部署到生产环境。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **module**：模块。软件系统中可独立开发、测试和维护的功能单元。 +- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。 +- **npx**：Node Package eXecute。npm 包执行器，用于直接执行 npm 包而无需全局安装。 +- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。 diff --git a/docs/zh-cn/how-to/project-context.md b/docs/zh-cn/how-to/project-context.md new file mode 100644 index 000000000..89ce6af15 --- /dev/null +++ b/docs/zh-cn/how-to/project-context.md @@ -0,0 +1,152 @@ +--- +title: "管理项目上下文" +description: 创建并维护 project-context.md 以指导 AI 智能体 +sidebar: + order: 7 +--- + +使用 `project-context.md` 文件确保 AI 智能体在所有工作流程中遵循项目的技术偏好和实现规则。 + +:::note[前置条件] +- 已安装 BMad Method +- 了解项目的技术栈和约定 +::: + +## 何时使用 + +- 在开始架构设计之前有明确的技术偏好 +- 已完成架构设计并希望为实施捕获决策 +- 正在处理具有既定模式的现有代码库 +- 注意到智能体在不同用户故事中做出不一致的决策 + +## 步骤 1：选择方法 + +**手动创建** — 当您确切知道要记录哪些规则时最佳 + +**架构后生成** — 最适合捕获解决方案制定过程中所做的决策 + +**为现有项目生成** — 最适合在现有代码库中发现模式 + +## 步骤 2：创建文件 + +### 选项 A：手动创建 + +在 `_bmad-output/project-context.md` 创建文件： + +```bash +mkdir -p _bmad-output +touch _bmad-output/project-context.md +``` + +添加技术栈和实现规则： + +```markdown +--- +project_name: 'MyProject' +user_name: 'YourName' +date: '2026-02-15' +sections_completed: ['technology_stack', 'critical_rules'] +--- + +# AI 智能体的项目上下文 + +## 技术栈与版本 + +- Node.js 20.x, TypeScript 5.3, React 18.2 +- 状态管理：Zustand +- 测试：Vitest, Playwright +- 样式：Tailwind CSS + +## 关键实现规则 + +**TypeScript：** +- 启用严格模式，不使用 `any` 类型 +- 公共 API 使用 `interface`，联合类型使用 `type` + +**代码组织：** +- 组件位于 `/src/components/` 并附带同位置测试 +- API 调用使用 `apiClient` 单例 — 绝不直接使用 fetch + +**测试：** +- 单元测试专注于业务逻辑 +- 集成测试使用 MSW 进行 API 模拟 +``` + +### 选项 B：架构后生成 + +在新的聊天中运行工作流程： + +```bash +/bmad-bmm-generate-project-context +``` + +工作流程扫描架构文档和项目文件，生成捕获所做决策的上下文文件。 + +### 选项 C：为现有项目生成 + +对于现有项目，运行： + +```bash +/bmad-bmm-generate-project-context +``` + +工作流程分析代码库以识别约定，然后生成上下文文件供您审查和完善。 + +## 步骤 3：验证内容 + +审查生成的文件并确保它捕获了： + +- 正确的技术版本 +- 实际约定（而非通用最佳实践） +- 防止常见错误的规则 +- 框架特定的模式 + +手动编辑以添加任何缺失内容或删除不准确之处。 + +## 您将获得 + +一个 `project-context.md` 文件，它： + +- 确保所有智能体遵循相同的约定 +- 防止在不同用户故事中做出不一致的决策 +- 为实施捕获架构决策 +- 作为项目模式和规则的参考 + +## 提示 + +:::tip[关注非显而易见的内容] +记录智能体可能遗漏的模式，例如"在每个公共类、函数和变量上使用 JSDoc 风格注释"，而不是像"使用有意义的变量名"这样的通用实践，因为 LLM 目前已经知道这些。 +::: + +:::tip[保持精简] +此文件由每个实施工作流程加载。长文件会浪费上下文。不要包含仅适用于狭窄范围或特定用户故事或功能的内容。 +::: + +:::tip[根据需要更新] +当模式发生变化时手动编辑，或在重大架构更改后重新生成。 +::: + +:::tip[适用于所有项目类型] +对于快速流程和完整的 BMad Method 项目同样有用。 +::: + +## 后续步骤 + +- [**项目上下文说明**](../explanation/project-context.md) — 了解其工作原理 +- [**工作流程图**](../reference/workflow-map.md) — 查看哪些工作流程加载项目上下文 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流程。指完成特定任务的一系列步骤或过程。 +- **codebase**：代码库。指项目的所有源代码和资源的集合。 +- **implementation**：实施。指将设计或架构转化为实际代码的过程。 +- **architecture**：架构。指系统的整体结构和设计。 +- **stack**：技术栈。指项目使用的技术组合，如编程语言、框架、工具等。 +- **convention**：约定。指团队或项目中遵循的编码规范和最佳实践。 +- **singleton**：单例。一种设计模式，确保类只有一个实例。 +- **co-located**：同位置。指相关文件（如测试文件）与主文件放在同一目录中。 +- **mocking**：模拟。在测试中用模拟对象替代真实对象的行为。 +- **context**：上下文。指程序运行时的环境信息或背景信息。 +- **LLM**：大语言模型。Large Language Model 的缩写，指大型语言模型。 diff --git a/docs/zh-cn/how-to/quick-fixes.md b/docs/zh-cn/how-to/quick-fixes.md new file mode 100644 index 000000000..166a10a50 --- /dev/null +++ b/docs/zh-cn/how-to/quick-fixes.md @@ -0,0 +1,140 @@ +--- +title: "快速修复" +description: 如何进行快速修复和临时更改 +sidebar: + order: 5 +--- + +直接使用 **DEV 智能体**进行 bug 修复、重构或小型针对性更改，这些操作不需要完整的 BMad Method 或 Quick Flow。 + +## 何时使用此方法 + +- 原因明确且已知的 bug 修复 +- 包含在少数文件中的小型重构（重命名、提取、重组） +- 次要功能调整或配置更改 +- 探索性工作，以了解不熟悉的代码库 + +:::note[前置条件] +- 已安装 BMad Method（`npx bmad-method install`） +- AI 驱动的 IDE（Claude Code、Cursor 或类似工具） +::: + +## 选择你的方法 + +| 情况 | 智能体 | 原因 | +| --- | --- | --- | +| 修复特定 bug 或进行小型、范围明确的更改 | **DEV agent** | 直接进入实现，无需规划开销 | +| 更改涉及多个文件，或希望先有书面计划 | **Quick Flow Solo Dev** | 在实现前创建 quick-spec，使智能体与你的标准保持一致 | + +如果不确定，请从 DEV 智能体开始。如果更改范围扩大，你始终可以升级到 Quick Flow。 + +## 步骤 + +### 1. 加载 DEV 智能体 + +在 AI IDE 中启动一个**新的聊天**，并使用斜杠命令加载 DEV 智能体： + +```text +/bmad-agent-bmm-dev +``` + +这会将智能体的角色和能力加载到会话中。如果你决定需要 Quick Flow，请在新的聊天中加载 **Quick Flow Solo Dev** 智能体： + +```text +/bmad-agent-bmm-quick-flow-solo-dev +``` + +加载 Solo Dev 智能体后，描述你的更改并要求它创建一个 **quick-spec**。智能体会起草一个轻量级规范，捕获你想要更改的内容和方式。批准 quick-spec 后，告诉智能体开始 **Quick Flow 开发周期**——它将实现更改、运行测试并执行自我审查，所有这些都由你刚刚批准的规范指导。 + +:::tip[新聊天] +加载智能体时始终启动新的聊天会话。重用之前工作流的会话可能导致上下文冲突。 +::: + +### 2. 描述更改 + +用通俗语言告诉智能体你需要什么。具体说明问题，如果你知道相关代码的位置，也请说明。 + +:::note[示例提示词] +**Bug 修复** -- "修复允许空密码的登录验证 bug。验证逻辑位于 `src/auth/validate.ts`。" + +**重构** -- "重构 UserService 以使用 async/await 而不是回调。" + +**配置更改** -- "更新 CI 流水线以在运行之间缓存 node_modules。" + +**依赖更新** -- "将 express 依赖升级到最新的 v5 版本并修复任何破坏性更改。" +::: + +你不需要提供每个细节。智能体会读取相关的源文件，并在需要时提出澄清问题。 + +### 3. 让智能体工作 + +智能体将： + +- 读取并分析相关的源文件 +- 提出解决方案并解释其推理 +- 在受影响的文件中实现更改 +- 如果存在测试套件，则运行项目的测试套件 + +如果你的项目有测试，智能体会在进行更改后自动运行它们，并迭代直到测试通过。对于没有测试套件的项目，请手动验证更改（运行应用、访问端点、检查输出）。 + +### 4. 审查和验证 + +在提交之前，审查更改内容： + +- 通读 diff 以确认更改符合你的意图 +- 自己运行应用程序或测试以再次检查 +- 如果看起来有问题，告诉智能体需要修复什么——它可以在同一会话中迭代 + +满意后，使用描述修复的清晰消息提交更改。 + +:::caution[如果出现问题] +如果提交的更改导致意外问题，请使用 `git revert HEAD` 干净地撤销最后一次提交。然后启动与 DEV 智能体的新聊天以尝试不同的方法。 +::: + +## 学习你的代码库 + +DEV 智能体也适用于探索不熟悉的代码。在新的聊天中加载它并提出问题： + +:::note[示例提示词] +"解释此代码库中的身份验证系统是如何工作的。" + +"向我展示 API 层中的错误处理发生在哪里。" + +"`ProcessOrder` 函数的作用是什么，什么调用了它？" +::: + +使用智能体了解你的项目，理解组件如何连接，并在进行更改之前探索不熟悉的区域。 + +## 你将获得 + +- 已应用修复或重构的修改后的源文件 +- 通过的测试（如果你的项目有测试套件） +- 描述更改的干净提交 + +不会生成规划产物——这就是这种方法的意义所在。 + +## 何时升级到正式规划 + +在以下情况下考虑使用 [Quick Flow](../explanation/quick-flow.md) 或完整的 BMad Method： + +- 更改影响多个系统或需要在许多文件中进行协调更新 +- 你不确定范围，需要规范来理清思路 +- 修复在工作过程中变得越来越复杂 +- 你需要为团队记录文档或架构决策 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **quick-spec**：快速规范。一种轻量级的规范文档，用于快速捕获和描述更改的内容和方式。 +- **Quick Flow**：快速流程。BMad Method 中的一种工作流程，用于快速实现小型更改。 +- **refactoring**：重构。在不改变代码外部行为的情况下改进其内部结构的过程。 +- **breaking changes**：破坏性更改。可能导致现有代码或功能不再正常工作的更改。 +- **test suite**：测试套件。一组用于验证软件功能的测试用例集合。 +- **CI pipeline**：CI 流水线。持续集成流水线，用于自动化构建、测试和部署代码。 +- **async/await**：异步编程语法。JavaScript/TypeScript 中用于处理异步操作的语法糖。 +- **callbacks**：回调函数。作为参数传递给其他函数并在适当时候被调用的函数。 +- **endpoint**：端点。API 中可访问的特定 URL 路径。 +- **diff**：差异。文件或代码更改前后的对比。 +- **commit**：提交。将更改保存到版本控制系统的操作。 +- **git revert HEAD**：Git 命令，用于撤销最后一次提交。 diff --git a/docs/zh-cn/how-to/shard-large-documents.md b/docs/zh-cn/how-to/shard-large-documents.md new file mode 100644 index 000000000..3f3385623 --- /dev/null +++ b/docs/zh-cn/how-to/shard-large-documents.md @@ -0,0 +1,86 @@ +--- +title: "文档分片指南" +description: 将大型 Markdown 文件拆分为更小的组织化文件，以更好地管理上下文 +sidebar: + order: 8 +--- + +如果需要将大型 Markdown 文件拆分为更小、组织良好的文件以更好地管理上下文，请使用 `shard-doc` 工具。 + +:::caution[已弃用] +不再推荐使用此方法，随着工作流程的更新以及大多数主要 LLM 和工具支持子进程，这很快将变得不再必要。 +::: + +## 何时使用 + +仅当你发现所选工具/模型组合无法在需要时加载和读取所有文档作为输入时，才使用此方法。 + +## 什么是文档分片？ + +文档分片根据二级标题（`## Heading`）将大型 Markdown 文件拆分为更小、组织良好的文件。 + +### 架构 + +```text +分片前： +_bmad-output/planning-artifacts/ +└── PRD.md（大型 50k token 文件） + +分片后： +_bmad-output/planning-artifacts/ +└── prd/ + ├── index.md # 带有描述的目录 + ├── overview.md # 第 1 节 + ├── user-requirements.md # 第 2 节 + ├── technical-requirements.md # 第 3 节 + └── ... # 其他章节 +``` + +## 步骤 + +### 1. 运行 Shard-Doc 工具 + +```bash +/bmad-shard-doc +``` + +### 2. 遵循交互式流程 + +```text +智能体：您想要分片哪个文档？ +用户：docs/PRD.md + +智能体：默认目标位置：docs/prd/ + 接受默认值？[y/n] +用户：y + +智能体：正在分片 PRD.md... + ✓ 已创建 12 个章节文件 + ✓ 已生成 index.md + ✓ 完成！ +``` + +## 工作流程发现机制 + +BMad 工作流程使用**双重发现系统**： + +1. **首先尝试完整文档** - 查找 `document-name.md` +2. **检查分片版本** - 查找 `document-name/index.md` +3. **优先级规则** - 如果两者都存在，完整文档优先 - 如果希望使用分片版本，请删除完整文档 + +## 工作流程支持 + +所有 BMM 工作流程都支持这两种格式： + +- 完整文档 +- 分片文档 +- 自动检测 +- 对用户透明 + +--- +## 术语说明 + +- **sharding**：分片。将大型文档或数据集拆分为更小、更易管理的部分的过程。 +- **token**：令牌。在自然语言处理和大型语言模型中，文本的基本单位，通常对应单词或字符的一部分。 +- **subprocesses**：子进程。由主进程创建的独立执行单元，可以并行运行以执行特定任务。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 diff --git a/docs/zh-cn/how-to/upgrade-to-v6.md b/docs/zh-cn/how-to/upgrade-to-v6.md new file mode 100644 index 000000000..b833d360c --- /dev/null +++ b/docs/zh-cn/how-to/upgrade-to-v6.md @@ -0,0 +1,120 @@ +--- +title: "如何升级到 v6" +description: 从 BMad v4 迁移到 v6 +sidebar: + order: 3 +--- + +使用 BMad 安装程序从 v4 升级到 v6，其中包括自动检测旧版安装和迁移辅助。 + +## 何时使用本指南 + +- 您已安装 BMad v4（`.bmad-method` 文件夹） +- 您希望迁移到新的 v6 架构 +- 您有需要保留的现有规划产物 + +:::note[前置条件] +- Node.js 20+ +- 现有的 BMad v4 安装 +::: + +## 步骤 + +### 1. 运行安装程序 + +按照[安装程序说明](./install-bmad.md)操作。 + +### 2. 处理旧版安装 + +当检测到 v4 时，您可以： + +- 允许安装程序备份并删除 `.bmad-method` +- 退出并手动处理清理 + +如果您将 bmad method 文件夹命名为其他名称 - 您需要手动删除该文件夹。 + +### 3. 清理 IDE 命令 + +手动删除旧版 v4 IDE 命令 - 例如如果您使用 claude，查找任何以 bmad 开头的嵌套文件夹并删除它们： + +- `.claude/commands/BMad/agents` +- `.claude/commands/BMad/tasks` + +### 4. 迁移规划产物 + +**如果您有规划文档（Brief/PRD/UX/Architecture）：** + +将它们移动到 `_bmad-output/planning-artifacts/` 并使用描述性名称： + +- 在文件名中包含 `PRD` 用于 PRD 文档 +- 相应地包含 `brief`、`architecture` 或 `ux-design` +- 分片文档可以放在命名的子文件夹中 + +**如果您正在进行规划：** 考虑使用 v6 工作流重新开始。将现有文档作为输入——新的渐进式发现工作流配合网络搜索和 IDE 计划模式会产生更好的结果。 + +### 5. 迁移进行中的开发 + +如果您已创建或实现了故事： + +1. 完成 v6 安装 +2. 将 `epics.md` 或 `epics/epic*.md` 放入 `_bmad-output/planning-artifacts/` +3. 运行 Scrum Master 的 `sprint-planning` 工作流 +4. 告诉 SM 哪些史诗/故事已经完成 + +## 您将获得 + +**v6 统一结构：** + +```text +your-project/ +├── _bmad/ # 单一安装文件夹 +│ ├── _config/ # 您的自定义配置 +│ │ └── agents/ # 智能体自定义文件 +│ ├── core/ # 通用核心框架 +│ ├── bmm/ # BMad Method 模块 +│ ├── bmb/ # BMad Builder +│ └── cis/ # Creative Intelligence Suite +└── _bmad-output/ # 输出文件夹（v4 中为 doc 文件夹） +``` + +## 模块迁移 + +| v4 模块 | v6 状态 | +| ----------------------------- | ----------------------------------------- | +| `.bmad-2d-phaser-game-dev` | 已集成到 BMGD 模块 | +| `.bmad-2d-unity-game-dev` | 已集成到 BMGD 模块 | +| `.bmad-godot-game-dev` | 已集成到 BMGD 模块 | +| `.bmad-infrastructure-devops` | 已弃用 — 新的 DevOps 智能体即将推出 | +| `.bmad-creative-writing` | 未适配 — 新的 v6 模块即将推出 | + +## 主要变更 + +| 概念 | v4 | v6 | +| ------------ | --------------------------------------- | ------------------------------------ | +| **核心** | `_bmad-core` 实际上是 BMad Method | `_bmad/core/` 是通用框架 | +| **方法** | `_bmad-method` | `_bmad/bmm/` | +| **配置** | 直接修改文件 | 每个模块使用 `config.yaml` | +| **文档** | 需要设置分片或非分片 | 完全灵活，自动扫描 | + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **epic**：史诗。在敏捷开发中，指大型的工作项，可分解为多个用户故事。 +- **story**：故事。在敏捷开发中，指用户故事，描述用户需求的功能单元。 +- **Scrum Master**：Scrum 主管。敏捷开发 Scrum 框架中的角色，负责促进团队流程和移除障碍。 +- **sprint-planning**：冲刺规划。Scrum 框架中的会议，用于确定下一个冲刺期间要完成的工作。 +- **sharded**：分片。将大型文档拆分为多个较小的文件以便于管理和处理。 +- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和特性的文档。 +- **Brief**：简报。概述项目目标、范围和关键信息的文档。 +- **UX**：用户体验（User Experience）。用户在使用产品或服务过程中的整体感受和交互体验。 +- **Architecture**：架构。系统的结构设计，包括组件、模块及其相互关系。 +- **BMGD**：BMad Game Development。BMad 游戏开发模块。 +- **DevOps**：开发运维（Development Operations）。结合开发和运维的实践，旨在缩短系统开发生命周期。 +- **BMad Method**：BMad 方法。BMad 框架的核心方法论模块。 +- **BMad Builder**：BMad 构建器。BMad 框架的构建工具。 +- **Creative Intelligence Suite**：创意智能套件。BMad 框架中的创意工具集合。 +- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试等功能的软件开发工具。 +- **progressive discovery**：渐进式发现。逐步深入探索和理解需求的过程。 +- **web search**：网络搜索。通过互联网检索信息的能力。 +- **plan mode**：计划模式。IDE 中的一种工作模式，用于规划和设计任务。 diff --git a/docs/zh-cn/index.md b/docs/zh-cn/index.md new file mode 100644 index 000000000..11c43eeb5 --- /dev/null +++ b/docs/zh-cn/index.md @@ -0,0 +1,69 @@ +--- +title: 欢迎使用 BMad 方法 +description: 具备专业智能体、引导式工作流和智能规划的 AI 驱动开发框架 +--- + +BMad 方法（**B**reakthrough **M**ethod of **A**gile AI **D**riven Development，敏捷 AI 驱动开发的突破性方法）是 BMad 方法生态系统中的一个 AI 驱动开发框架模块，帮助您完成从构思和规划到智能体实现的整个软件开发过程。它提供专业的 AI 智能体、引导式工作流和智能规划，能够根据您项目的复杂度进行调整，无论是修复错误还是构建企业平台。 + +如果您熟悉使用 Claude、Cursor 或 GitHub Copilot 等 AI 编码助手，就可以开始使用了。 + +:::note[🚀 V6 已发布，我们才刚刚起步！] +技能架构、BMad Builder v1、开发循环自动化以及更多功能正在开发中。**[查看路线图 →](/roadmap/)** +::: + +## 新手入门？从教程开始 + +理解 BMad 的最快方式是亲自尝试。 + +- **[BMad 入门指南](./tutorials/getting-started.md)** — 安装并了解 BMad 的工作原理 +- **[工作流地图](./reference/workflow-map.md)** — BMM 阶段、工作流和上下文管理的可视化概览 + +:::tip[只想直接上手？] +安装 BMad 并运行 `bmad-help` — 它会根据您的项目和已安装的模块引导您完成所有操作。 +::: + +## 如何使用本文档 + +本文档根据您的目标分为四个部分： + +| 部分 | 用途 | +| ----------------- | ---------------------------------------------------------------------------------------------------------- | +| **教程** | 以学习为导向。通过分步指南引导您构建内容。如果您是新手，请从这里开始。 | +| **操作指南** | 以任务为导向。解决特定问题的实用指南。"如何自定义智能体？"等内容位于此处。 | +| **说明** | 以理解为导向。深入探讨概念和架构。当您想知道*为什么*时阅读。 | +| **参考** | 以信息为导向。智能体、工作流和配置的技术规范。 | + +## 扩展和自定义 + +想要使用自己的智能体、工作流或模块来扩展 BMad 吗？**[BMad Builder](https://bmad-builder-docs.bmad-method.org/)** 提供了创建自定义扩展的框架和工具，无论是为 BMad 添加新功能还是从头开始构建全新的模块。 + +## 您需要什么 + +BMad 可与任何支持自定义系统提示词或项目上下文的 AI 编码助手配合使用。热门选项包括： + +- **[Claude Code](https://code.claude.com)** — Anthropic 的 CLI 工具（推荐） +- **[Cursor](https://cursor.sh)** — AI 优先的代码编辑器 +- **[Codex CLI](https://github.com/openai/codex)** — OpenAI 的终端编码智能体 + +您应该熟悉版本控制、项目结构和敏捷工作流等基本软件开发概念。无需具备 BMad 风格智能体系统的先验经验——这正是本文档的作用。 + +## 加入社区 + +获取帮助、分享您的构建内容，或为 BMad 做出贡献： + +- **[Discord](https://discord.gg/gk8jAdXWmj)** — 与其他 BMad 用户聊天、提问、分享想法 +- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — 源代码、问题和贡献 +- **[YouTube](https://www.youtube.com/@BMadCode)** — 视频教程和演练 + +## 下一步 + +准备开始了吗？**[BMad 入门指南](./tutorials/getting-started.md)** 并构建您的第一个项目。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **AI-driven**：AI 驱动。指由人工智能技术主导或驱动的系统或方法。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。 +- **prompt**：提示词。指输入给 AI 模型的指令或问题，用于引导其生成特定输出。 +- **context**：上下文。指在特定场景下理解信息所需的背景信息或环境。 diff --git a/docs/zh-cn/reference/agents.md b/docs/zh-cn/reference/agents.md new file mode 100644 index 000000000..393053b9e --- /dev/null +++ b/docs/zh-cn/reference/agents.md @@ -0,0 +1,41 @@ +--- +title: "智能体" +description: 默认 BMM 智能体及其菜单触发器和主要工作流 +sidebar: + order: 2 +--- + +## 默认智能体 + +本页列出了随 BMad Method 安装的默认 BMM（Agile 套件）智能体，以及它们的菜单触发器和主要工作流。 + +## 注意事项 + +- 触发器是显示在每个智能体菜单中的简短菜单代码（例如 `CP`）和模糊匹配。 +- 斜杠命令是单独生成的。斜杠命令列表及其定义位置请参阅[命令](./commands.md)。 +- QA（Quinn）是 BMM 中的轻量级测试自动化智能体。完整的测试架构师（TEA）位于其独立模块中。 + +| 智能体 | 触发 | 主要工作流 | +| --------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------- | +| Analyst (Mary) | `BP`, `RS`, `CB`, `DP` | 头脑风暴项目、研究、创建简报、文档化项目 | +| Product Manager (John) | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | 创建/验证/编辑 PRD、创建史诗和用户故事、实施就绪、纠正方向 | +| Architect (Winston) | `CA`, `IR` | 创建架构、实施就绪 | +| Scrum Master (Bob) | `SP`, `CS`, `ER`, `CC` | 冲刺规划、创建用户故事、史诗回顾、纠正方向 | +| Developer (Amelia) | `DS`, `CR` | 开发用户故事、代码评审 | +| QA Engineer (Quinn) | `QA` | 自动化（为现有功能生成测试） | +| Quick Flow Solo Dev (Barry) | `QS`, `QD`, `CR` | 快速规格、快速开发、代码评审 | +| UX Designer (Sally) | `CU` | 创建 UX 设计 | +| Technical Writer (Paige) | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | 文档化项目、撰写文档、更新标准、Mermaid 生成、验证文档、解释概念 | + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **BMM**：BMad Method 中的默认智能体套件，涵盖敏捷开发流程中的各类角色。 +- **PRD**：产品需求文档（Product Requirements Document）。 +- **Epic**：史诗。大型功能或需求集合，可拆分为多个用户故事。 +- **Story**：用户故事。描述用户需求的简短陈述。 +- **Sprint**：冲刺。敏捷开发中的固定时间周期迭代。 +- **QA**：质量保证（Quality Assurance）。 +- **TEA**：测试架构师（Test Architect）。 +- **Mermaid**：一种用于生成图表和流程图的文本语法。 diff --git a/docs/zh-cn/reference/commands.md b/docs/zh-cn/reference/commands.md new file mode 100644 index 000000000..773998cfd --- /dev/null +++ b/docs/zh-cn/reference/commands.md @@ -0,0 +1,166 @@ +--- +title: "命令" +description: BMad 斜杠命令参考——它们是什么、如何工作以及在哪里找到它们。 +sidebar: + order: 3 +--- + +斜杠命令是预构建的提示词，用于在 IDE 中加载智能体、运行工作流或执行任务。BMad 安装程序在安装时根据已安装的模块生成这些命令。如果您后续添加、删除或更改模块，请重新运行安装程序以保持命令同步（参见[故障排除](#troubleshooting)）。 + +## 命令与智能体菜单触发器 + +BMad 提供两种开始工作的方式，它们服务于不同的目的。 + +| 机制 | 调用方式 | 发生什么 | +| --- | --- | --- | +| **斜杠命令** | 在 IDE 中输入 `bmad-...` | 直接加载智能体、运行工作流或执行任务 | +| **智能体菜单触发器** | 先加载智能体，然后输入简短代码（例如 `DS`） | 智能体解释代码并启动匹配的工作流，同时保持角色设定 | + +智能体菜单触发器需要活动的智能体会话。当您知道要使用哪个工作流时，使用斜杠命令。当您已经与智能体一起工作并希望在不离开对话的情况下切换任务时，使用触发器。 + +## 命令如何生成 + +当您运行 `npx bmad-method install` 时，安装程序会读取每个选定模块的清单，并为每个智能体、工作流、任务和工具编写一个命令文件。每个文件都是一个简短的 Markdown 提示词，指示 AI 加载相应的源文件并遵循其指令。 + +安装程序为每种命令类型使用模板： + +| 命令类型 | 生成的文件的作用 | +| --- | --- | +| **智能体启动器** | 加载智能体角色文件，激活其菜单，并保持角色设定 | +| **工作流命令** | 加载工作流引擎（`workflow.xml`）并传递工作流配置 | +| **任务命令** | 加载独立任务文件并遵循其指令 | +| **工具命令** | 加载独立工具文件并遵循其指令 | + +:::note[重新运行安装程序] +如果您添加或删除模块，请再次运行安装程序。它会重新生成所有命令文件以匹配您当前的模块选择。 +::: + +## 命令文件的位置 + +安装程序将命令文件写入项目内 IDE 特定的目录中。确切路径取决于您在安装期间选择的 IDE。 + +| IDE / CLI | 命令目录 | +| --- | --- | +| Claude Code | `.claude/commands/` | +| Cursor | `.cursor/commands/` | +| Windsurf | `.windsurf/workflows/` | +| 其他 IDE | 请参阅安装程序输出中的目标路径 | + +所有 IDE 都在其命令目录中接收一组扁平的命令文件。例如，Claude Code 安装看起来像： + +```text +.claude/commands/ +├── bmad-agent-bmm-dev.md +├── bmad-agent-bmm-pm.md +├── bmad-bmm-create-prd.md +├── bmad-editorial-review-prose.md +├── bmad-help.md +└── ... +``` + +文件名决定了 IDE 中的技能名称。例如，文件 `bmad-agent-bmm-dev.md` 注册技能 `bmad-agent-bmm-dev`。 + +## 如何发现您的命令 + +在 IDE 中输入 `/bmad` 并使用自动完成功能浏览可用命令。 + +运行 `bmad-help` 获取关于下一步的上下文感知指导。 + +:::tip[快速发现] +项目中生成的命令文件夹是权威列表。在文件资源管理器中打开它们以查看每个命令及其描述。 +::: + +## 命令类别 + +### 智能体命令 + +智能体命令加载具有定义角色、沟通风格和工作流菜单的专业化 AI 角色。加载后，智能体保持角色设定并响应菜单触发器。 + +| 示例命令 | 智能体 | 角色 | +| --- | --- | --- | +| `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)获取默认智能体及其触发器的完整列表。 + +### 工作流命令 + +工作流命令运行结构化的多步骤过程，而无需先加载智能体角色。它们加载工作流引擎并传递特定的工作流配置。 + +| 示例命令 | 目的 | +| --- | --- | +| `bmad-bmm-create-prd` | 创建产品需求文档 | +| `bmad-bmm-create-architecture` | 设计系统架构 | +| `bmad-bmm-dev-story` | 实现故事 | +| `bmad-bmm-code-review` | 运行代码审查 | +| `bmad-bmm-quick-spec` | 定义临时更改（快速流程） | + +参见[工作流地图](./workflow-map.md)获取按阶段组织的完整工作流参考。 + +### 任务和工具命令 + +任务和工具是独立的操作，不需要智能体或工作流上下文。 + +#### BMad-Help：您的智能向导 + +**`bmad-help`** 是您发现下一步操作的主要界面。它不仅仅是一个查找工具——它是一个智能助手，可以： + +- **检查您的项目**以查看已经完成的工作 +- **理解自然语言查询**——用简单的英语提问 +- **根据已安装的模块而变化**——根据您拥有的内容显示选项 +- **在工作流后自动调用**——每个工作流都以清晰的下一步结束 +- **推荐第一个必需任务**——无需猜测从哪里开始 + +**示例：** + +``` +bmad-help +bmad-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？ +bmad-help 我在 UX 设计方面有哪些选择？ +bmad-help 我在 PRD 工作流上卡住了 +``` + +#### 其他任务和工具 + +| 示例命令 | 目的 | +| --- | --- | +| `bmad-shard-doc` | 将大型 Markdown 文件拆分为较小的部分 | +| `bmad-index-docs` | 索引项目文档 | +| `bmad-editorial-review-prose` | 审查文档散文质量 | + +## 命名约定 + +命令名称遵循可预测的模式。 + +| 模式 | 含义 | 示例 | +| --- | --- | --- | +| `bmad-agent--` | 智能体启动器 | `bmad-agent-bmm-dev` | +| `bmad--` | 工作流命令 | `bmad-bmm-create-prd` | +| `bmad-` | 核心任务或工具 | `bmad-help` | + +模块代码：`bmm`（敏捷套件）、`bmb`（构建器）、`tea`（测试架构师）、`cis`（创意智能）、`gds`（游戏开发工作室）。参见[模块](./modules.md)获取描述。 + +## 故障排除 + +**安装后命令未出现。** 重启您的 IDE 或重新加载窗口。某些 IDE 会缓存命令列表，需要刷新才能获取新文件。 + +**预期的命令缺失。** 安装程序仅为您选择的模块生成命令。再次运行 `npx bmad-method install` 并验证您的模块选择。检查命令文件是否存在于预期目录中。 + +**已删除模块的命令仍然出现。** 安装程序不会自动删除旧的命令文件。从 IDE 的命令目录中删除过时的文件，或删除整个命令目录并重新运行安装程序以获取一组干净的命令。 + +--- +## 术语说明 + +- **slash command**：斜杠命令。以 `/` 开头的命令，用于在 IDE 中快速执行特定操作。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。一系列结构化的步骤，用于完成特定任务或流程。 +- **IDE**：集成开发环境。用于软件开发的综合应用程序，提供代码编辑、调试、构建等功能。 +- **persona**：角色设定。为智能体定义的特定角色、性格和行为方式。 +- **trigger**：触发器。用于启动特定操作或流程的机制。 +- **manifest**：清单。描述模块或组件的元数据文件。 +- **installer**：安装程序。用于安装和配置软件的工具。 +- **PRD**：产品需求文档。描述产品功能、需求和规范的文档。 +- **SaaS**：软件即服务。通过互联网提供软件服务的模式。 +- **UX**：用户体验。用户在使用产品或服务过程中的整体感受和交互体验。 diff --git a/docs/zh-cn/reference/modules.md b/docs/zh-cn/reference/modules.md new file mode 100644 index 000000000..d8fbdf8d2 --- /dev/null +++ b/docs/zh-cn/reference/modules.md @@ -0,0 +1,94 @@ +--- +title: "官方模块" +description: 用于构建自定义智能体、创意智能、游戏开发和测试的附加模块 +sidebar: + order: 4 +--- + +BMad 通过您在安装期间选择的官方模块进行扩展。这些附加模块为内置核心和 BMM（敏捷套件）之外的特定领域提供专门的智能体、工作流和任务。 + +:::tip[安装模块] +运行 `npx bmad-method install` 并选择您需要的模块。安装程序会自动处理下载、配置和 IDE 集成。 +::: + +## BMad Builder + +在引导式协助下创建自定义智能体、工作流和特定领域的模块。BMad Builder 是用于扩展框架本身的元模块。 + +- **代码：** `bmb` +- **npm：** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) +- **GitHub：** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) + +**提供：** + +- 智能体构建器 —— 创建具有自定义专业知识和工具访问权限的专用 AI 智能体 +- 工作流构建器 —— 设计包含步骤和决策点的结构化流程 +- 模块构建器 —— 将智能体和工作流打包为可共享、可发布的模块 +- 交互式设置，支持 YAML 配置和 npm 发布 + +## 创意智能套件 + +用于早期开发阶段的结构化创意、构思和创新的 AI 驱动工具。该套件提供多个智能体，利用经过验证的框架促进头脑风暴、设计思维和问题解决。 + +- **代码：** `cis` +- **npm：** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) +- **GitHub：** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) + +**提供：** + +- 创新策略师、设计思维教练和头脑风暴教练智能体 +- 问题解决者和创意问题解决者，用于系统性和横向思维 +- 故事讲述者和演示大师，用于叙事和推介 +- 构思框架，包括 SCAMPER、逆向头脑风暴和问题重构 + +## 游戏开发工作室 + +适用于 Unity、Unreal、Godot 和自定义引擎的结构化游戏开发工作流。通过 Quick Flow 支持快速原型制作，并通过史诗驱动的冲刺支持全面规模的生产。 + +- **代码：** `gds` +- **npm：** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) +- **GitHub：** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) + +**提供：** + +- 游戏设计文档（GDD）生成工作流 +- 用于快速原型制作的 Quick Dev 模式 +- 针对角色、对话和世界构建的叙事设计支持 +- 覆盖 21+ 种游戏类型，并提供特定引擎的架构指导 + +## 测试架构师（TEA） + +通过专家智能体和九个结构化工作流提供企业级测试策略、自动化指导和发布门控决策。TEA 远超内置 QA 智能体，提供基于风险的优先级排序和需求可追溯性。 + +- **代码：** `tea` +- **npm：** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) +- **GitHub：** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) + +**提供：** + +- Murat 智能体（主测试架构师和质量顾问） +- 用于测试设计、ATDD、自动化、测试审查和可追溯性的工作流 +- NFR 评估、CI 设置和框架脚手架 +- P0-P3 优先级排序，可选 Playwright Utils 和 MCP 集成 + +## 社区模块 + +社区模块和模块市场即将推出。请查看 [BMad GitHub 组织](https://github.com/bmad-code-org) 获取最新更新。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。 +- **module**：模块。指可独立开发、测试和部署的软件单元，用于扩展系统功能。 +- **meta-module**：元模块。指用于创建或扩展其他模块的模块，是模块的模块。 +- **ATDD**：验收测试驱动开发（Acceptance Test-Driven Development）。一种敏捷开发实践，在编写代码之前先编写验收测试。 +- **NFR**：非功能性需求（Non-Functional Requirement）。指系统在性能、安全性、可维护性等方面的质量属性要求。 +- **CI**：持续集成（Continuous Integration）。一种软件开发实践，频繁地将代码集成到主干分支，并进行自动化测试。 +- **MCP**：模型上下文协议（Model Context Protocol）。一种用于在 AI 模型与外部工具或服务之间进行通信的协议。 +- **SCAMPER**：一种创意思维技巧，包含替代、组合、调整、修改、其他用途、消除和重组七个维度。 +- **GDD**：游戏设计文档（Game Design Document）。用于描述游戏设计理念、玩法、机制等内容的详细文档。 +- **P0-P3**：优先级分级。P0 为最高优先级（关键），P3 为最低优先级（可选）。 +- **sprint**：冲刺。敏捷开发中的固定时间周期，通常为 1-4 周，用于完成预定的工作。 +- **epic**：史诗。敏捷开发中的大型工作项，可分解为多个用户故事或任务。 +- **Quick Flow**：快速流程。一种用于快速原型开发的工作流模式。 diff --git a/docs/zh-cn/reference/testing.md b/docs/zh-cn/reference/testing.md new file mode 100644 index 000000000..85fcde0db --- /dev/null +++ b/docs/zh-cn/reference/testing.md @@ -0,0 +1,122 @@ +--- +title: "测试选项" +description: 比较内置 QA 智能体（Quinn）与测试架构师（TEA）模块的测试自动化。 +sidebar: + order: 5 +--- + +BMad 提供两条测试路径：用于快速生成测试的内置 QA 智能体，以及用于企业级测试策略的可安装测试架构师模块。 + +## 应该使用哪一个？ + +| 因素 | Quinn（内置 QA） | TEA 模块 | +| --- | --- | --- | +| **最适合** | 中小型项目、快速覆盖 | 大型项目、受监管或复杂领域 | +| **设置** | 无需安装——包含在 BMM 中 | 通过 `npx bmad-method install` 单独安装 | +| **方法** | 快速生成测试，稍后迭代 | 先规划，再生成并保持可追溯性 | +| **测试类型** | API 和 E2E 测试 | API、E2E、ATDD、NFR 等 | +| **策略** | 快乐路径 + 关键边界情况 | 基于风险的优先级排序（P0-P3） | +| **工作流数量** | 1（Automate） | 9（设计、ATDD、自动化、审查、可追溯性等） | + +:::tip[从 Quinn 开始] +大多数项目应从 Quinn 开始。如果后续需要测试策略、质量门控或需求可追溯性，可并行安装 TEA。 +::: + +## 内置 QA 智能体（Quinn） + +Quinn 是 BMM（敏捷套件）模块中的内置 QA 智能体。它使用项目现有的测试框架快速生成可运行的测试——无需配置或额外安装。 + +**触发方式：** `QA` 或 `bmad-bmm-qa-automate` + +### Quinn 的功能 + +Quinn 运行单个工作流（Automate），包含五个步骤： + +1. **检测测试框架**——扫描 `package.json` 和现有测试文件以识别框架（Jest、Vitest、Playwright、Cypress 或任何标准运行器）。如果不存在，则分析项目技术栈并推荐一个。 +2. **识别功能**——询问要测试的内容或自动发现代码库中的功能。 +3. **生成 API 测试**——覆盖状态码、响应结构、快乐路径和 1-2 个错误情况。 +4. **生成 E2E 测试**——使用语义定位器和可见结果断言覆盖用户工作流。 +5. **运行并验证**——执行生成的测试并立即修复失败。 + +Quinn 会生成测试摘要，保存到项目的实现产物文件夹中。 + +### 测试模式 + +生成的测试遵循"简单且可维护"的理念： + +- **仅使用标准框架 API**——不使用外部工具或自定义抽象 +- UI 测试使用**语义定位器**（角色、标签、文本而非 CSS 选择器） +- **独立测试**，无顺序依赖 +- **无硬编码等待或休眠** +- **清晰的描述**，可作为功能文档阅读 + +:::note[范围] +Quinn 仅生成测试。如需代码审查和故事验证，请改用代码审查工作流（`CR`）。 +::: + +### 何时使用 Quinn + +- 为新功能或现有功能快速实现测试覆盖 +- 无需高级设置的初学者友好型测试自动化 +- 任何开发者都能阅读和维护的标准测试模式 +- 不需要全面测试策略的中小型项目 + +## 测试架构师（TEA）模块 + +TEA 是一个独立模块，提供专家智能体（Murat）和九个结构化工作流，用于企业级测试。它超越了测试生成，涵盖测试策略、基于风险的规划、质量门控和需求可追溯性。 + +- **文档：** [TEA 模块文档](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) +- **安装：** `npx bmad-method install` 并选择 TEA 模块 +- **npm：** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) + +### TEA 提供的功能 + +| Workflow | Purpose | +| --- | --- | +| Test Design | 创建与需求关联的全面测试策略 | +| ATDD | 基于干系人标准的验收测试驱动开发 | +| Automate | 使用高级模式和工具生成测试 | +| Test Review | 根据策略验证测试质量和覆盖范围 | +| Traceability | 将测试映射回需求，用于审计和合规 | +| NFR Assessment | 评估非功能性需求（性能、安全性） | +| CI Setup | 在持续集成管道中配置测试执行 | +| Framework Scaffolding | 设置测试基础设施和项目结构 | +| Release Gate | 基于数据做出发布/不发布决策 | + +TEA 还支持 P0-P3 基于风险的优先级排序，以及与 Playwright Utils 和 MCP 工具的可选集成。 + +### 何时使用 TEA + +- 需要需求可追溯性或合规文档的项目 +- 需要在多个功能间进行基于风险的测试优先级排序的团队 +- 发布前具有正式质量门控的企业环境 +- 在编写测试前必须规划测试策略的复杂领域 +- 已超出 Quinn 单一工作流方法的项目 + +## 测试如何融入工作流 + +Quinn 的 Automate 工作流出现在 BMad 方法工作流图的第 4 阶段（实现）。典型序列： + +1. 使用开发工作流（`DS`）实现一个故事 +2. 使用 Quinn（`QA`）或 TEA 的 Automate 工作流生成测试 +3. 使用代码审查（`CR`）验证实现 + +Quinn 直接从源代码工作，无需加载规划文档（PRD、架构）。TEA 工作流可以与上游规划产物集成以实现可追溯性。 + +有关测试在整体流程中的位置，请参阅[工作流图](./workflow-map.md)。 + +--- +## 术语说明 + +- **QA (Quality Assurance)**：质量保证。确保产品或服务满足质量要求的过程。 +- **E2E (End-to-End)**：端到端。测试整个系统从开始到结束的完整流程。 +- **ATDD (Acceptance Test-Driven Development)**：验收测试驱动开发。在编码前先编写验收测试的开发方法。 +- **NFR (Non-Functional Requirement)**：非功能性需求。描述系统如何运行而非做什么的需求，如性能、安全性等。 +- **P0-P3**：优先级级别。P0 为最高优先级，P3 为最低优先级，用于基于风险的测试排序。 +- **Happy path**：快乐路径。测试系统在理想条件下的正常工作流程。 +- **Semantic locators**：语义定位器。使用有意义的元素属性（如角色、标签、文本）而非 CSS 选择器来定位 UI 元素。 +- **Quality gates**：质量门控。在开发流程中设置的检查点，用于确保质量标准。 +- **Requirements traceability**：需求可追溯性。能够追踪需求从设计到测试再到实现的完整链路。 +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **CI (Continuous Integration)**：持续集成。频繁地将代码集成到主干，并自动运行测试的实践。 +- **MCP (Model Context Protocol)**：模型上下文协议。用于在 AI 模型与外部工具之间通信的协议。 diff --git a/docs/zh-cn/reference/workflow-map.md b/docs/zh-cn/reference/workflow-map.md new file mode 100644 index 000000000..51a8e2219 --- /dev/null +++ b/docs/zh-cn/reference/workflow-map.md @@ -0,0 +1,104 @@ +--- +title: "工作流程图" +description: BMad Method 工作流程阶段与输出的可视化参考 +sidebar: + order: 1 +--- + +BMad Method（BMM）是 BMad 生态系统中的一个模块，旨在遵循上下文工程与规划的最佳实践。AI 智能体在清晰、结构化的上下文中表现最佳。BMM 系统在 4 个不同阶段中逐步构建该上下文——每个阶段以及每个阶段内的多个可选工作流程都会生成文档，这些文档为下一阶段提供信息，因此智能体始终知道要构建什么以及为什么。 + +其基本原理和概念来自敏捷方法论，这些方法论在整个行业中被广泛用作思维框架，并取得了巨大成功。 + +如果您在任何时候不确定该做什么，`bmad-help` 命令将帮助您保持正轨或了解下一步该做什么。您也可以随时参考此文档以获取参考信息——但如果您已经安装了 BMad Method，`bmad-help` 是完全交互式的，速度要快得多。此外，如果您正在使用扩展了 BMad Method 或添加了其他互补非扩展模块的不同模块——`bmad-help` 会不断演进以了解所有可用内容，从而为您提供最佳即时建议。 + +最后的重要说明：以下每个工作流程都可以通过斜杠命令直接使用您选择的工具运行，或者先加载智能体，然后使用智能体菜单中的条目来运行。 + + + +

+ 在新标签页中打开图表 ↗ +

+ +## 阶段 1：分析（可选） + +在投入规划之前探索问题空间并验证想法。 + +| 工作流程 | 目的 | 产出 | +| ------------------------------- | -------------------------------------------------------------------------- | ------------------------- | +| `bmad-brainstorming` | 在头脑风暴教练的引导协助下进行项目想法头脑风暴 | `brainstorming-report.md` | +| `bmad-bmm-research` | 验证市场、技术或领域假设 | 研究发现 | +| `bmad-bmm-create-product-brief` | 捕捉战略愿景 | `product-brief.md` | + +## 阶段 2：规划 + +定义要构建什么以及为谁构建。 + +| 工作流程 | 目的 | 产出 | +| --------------------------- | ---------------------------------------- | ------------ | +| `bmad-bmm-create-prd` | 定义需求（FRs/NFRs） | `PRD.md` | +| `bmad-bmm-create-ux-design` | 设计用户体验（当 UX 重要时） | `ux-spec.md` | + +## 阶段 3：解决方案设计 + +决定如何构建它并将工作分解为故事。 + +| 工作流程 | 目的 | 产出 | +| ----------------------------------------- | ------------------------------------------ | --------------------------- | +| `bmad-bmm-create-architecture` | 明确技术决策 | 包含 ADR 的 `architecture.md` | +| `bmad-bmm-create-epics-and-stories` | 将需求分解为可实施的工作 | 包含故事的 Epic 文件 | +| `bmad-bmm-check-implementation-readiness` | 实施前的关卡检查 | PASS/CONCERNS/FAIL 决策 | + +## 阶段 4：实施 + +逐个故事地构建它。即将推出完整的阶段 4 自动化！ + +| 工作流程 | 目的 | 产出 | +| -------------------------- | ------------------------------------------------------------------------ | -------------------------------- | +| `bmad-bmm-sprint-planning` | 初始化跟踪（每个项目一次，以排序开发周期） | `sprint-status.yaml` | +| `bmad-bmm-create-story` | 准备下一个故事以供实施 | `story-[slug].md` | +| `bmad-bmm-dev-story` | 实施该故事 | 工作代码 + 测试 | +| `bmad-bmm-code-review` | 验证实施质量 | 批准或请求更改 | +| `bmad-bmm-correct-course` | 处理冲刺中的重大变更 | 更新的计划或重新路由 | +| `bmad-bmm-automate` | 为现有功能生成测试 - 在完整的 epic 完成后使用 | 端到端 UI 专注测试套件 | +| `bmad-bmm-retrospective` | 在 epic 完成后回顾 | 经验教训 | + +## 快速流程（并行轨道） + +对于小型、易于理解的工作，跳过阶段 1-3。 + +| 工作流程 | 目的 | 产出 | +| --------------------- | ------------------------------------------ | --------------------------------------------- | +| `bmad-bmm-quick-spec` | 定义临时变更 | `tech-spec.md`（小型变更的故事文件） | +| `bmad-bmm-quick-dev` | 根据规范或直接指令实施 | 工作代码 + 测试 | + +## 上下文管理 + +每个文档都成为下一阶段的上下文。PRD 告诉架构师哪些约束很重要。架构告诉开发智能体要遵循哪些模式。故事文件为实施提供专注、完整的上下文。没有这种结构，智能体会做出不一致的决策。 + +### 项目上下文 + +:::tip[推荐] +创建 `project-context.md` 以确保 AI 智能体遵循您项目的规则和偏好。该文件就像您项目的宪法——它指导所有工作流程中的实施决策。这个可选文件可以在架构创建结束时生成，或者在现有项目中也可以生成它，以捕捉与当前约定保持一致的重要内容。 +::: + +**如何创建它：** + +- **手动** — 使用您的技术栈和实施规则创建 `_bmad-output/project-context.md` +- **生成它** — 运行 `bmad-bmm-generate-project-context` 以从您的架构或代码库自动生成 + +[**了解更多关于 project-context.md**](../explanation/project-context.md) + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **BMad Method (BMM)**：BMad 方法。BMad 生态系统中的一个模块，用于上下文工程与规划。 +- **FRs/NFRs**：功能需求/非功能需求。Functional Requirements/Non-Functional Requirements 的缩写。 +- **PRD**：产品需求文档。Product Requirements Document 的缩写。 +- **UX**：用户体验。User Experience 的缩写。 +- **ADR**：架构决策记录。Architecture Decision Record 的缩写。 +- **Epic**：史诗。大型功能或用户故事的集合，通常需要多个冲刺才能完成。 +- **Story**：用户故事。描述用户需求的简短陈述。 +- **Sprint**：冲刺。敏捷开发中的固定时间周期，用于完成预定的工作。 +- **Slug**：短标识符。URL 友好的标识符，通常用于文件命名。 +- **Context**：上下文。为 AI 智能体提供的环境信息和背景资料。 diff --git a/docs/zh-cn/roadmap.mdx b/docs/zh-cn/roadmap.mdx new file mode 100644 index 000000000..2bc89b7e2 --- /dev/null +++ b/docs/zh-cn/roadmap.mdx @@ -0,0 +1,152 @@ +--- +title: 路线图 +description: BMad 的下一步计划——功能、改进与社区贡献 +--- + +# BMad 方法：公开路线图 + +BMad 方法、BMad 方法模块（BMM）和 BMad 构建器（BMB）正在持续演进。以下是我们正在开展的工作以及即将推出的内容。 + +
+ +

进行中

+ +
+
+ 🧩 +

通用技能架构

+

一个技能，任意平台。一次编写，随处运行。

+
+
+ 🏗️ +

BMad 构建器 v1

+

打造生产级 AI 智能体与工作流，内置评估、团队协作与优雅降级。

+
+
+ 🧠 +

项目上下文系统

+

AI 真正理解你的项目。框架感知的上下文，随代码库共同演进。

+
+
+ 📦 +

集中式技能

+

一次安装，随处使用。跨项目共享技能，告别文件杂乱。

+
+
+ 🔄 +

自适应技能

+

技能懂你的工具。为 Claude、Codex、Kimi、OpenCode 等提供优化变体，以及更多。

+
+
+ 📝 +

BMad 团队专业博客

+

来自团队的指南、文章与见解。即将上线。

+
+
+ +

入门阶段

+ +
+
+ 🏪 +

技能市场

+

发现、安装与更新社区构建的技能。一条 curl 命令即可获得超能力。

+
+
+ 🎨 +

工作流定制

+

打造属于你的工作流。集成 Jira、Linear、自定义输出——你的工作流，你的规则。

+
+
+ 🚀 +

阶段 1-3 优化

+

通过子智能体上下文收集实现闪电般快速的规划。YOLO 模式遇上引导式卓越。

+
+
+ 🌐 +

企业级就绪

+

SSO、审计日志、团队工作空间。那些让企业点头同意的无聊但必要的东西。

+
+
+ 💎 +

社区模块爆发

+

娱乐、安全、治疗、角色扮演以及更多内容。扩展 BMad 方法平台。

+
+
+ ⚡ +

开发循环自动化

+

可选的开发自动驾驶。让 AI 处理流程，同时保持质量高企。

+
+
+ +

社区与团队

+ +
+
+ 🎙️ +

BMad 方法播客

+

关于 AI 原生开发的对话。2026 年 3 月 1 日上线！

+
+
+ 🎓 +

BMad 方法大师课

+

从用户到专家。深入每个阶段、每个工作流、每个秘密。

+
+
+ 🏗️ +

BMad 构建器大师课

+

构建你自己的智能体。当你准备好创造而不仅仅是使用时的高级技巧。

+
+
+ ⚡ +

BMad 原型优先

+

一次会话从想法到可用原型。像创作艺术品一样打造你的梦想应用。

+
+
+ 🌴 +

BMad BALM！

+

AI 原生的生活管理。任务、习惯、目标——你的 AI 副驾驶，无处不在。

+
+
+ 🖥️ +

官方 UI

+

整个 BMad 生态系统的精美界面。CLI 的强大，GUI 的精致。

+
+
+ 🔒 +

BMad 一体机

+

自托管、气隙隔离、企业级。你的 AI 助手、你的基础设施、你的控制。

+
+
+ +
+

想要贡献？

+

+ 这只是计划内容的一部分。BMad 开源团队欢迎贡献者！{" "}
+ 在 GitHub 上加入我们，共同塑造 AI 驱动开发的未来。 +

+

+ 喜欢我们正在构建的东西？我们感谢一次性与月度{" "}支持。 +

+

+ 如需企业赞助、合作咨询、演讲邀请、培训或媒体咨询：{" "} + contact@bmadcode.com +

+
+
+ +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **SSO**：单点登录。一种用户认证机制，允许用户使用一组凭据访问多个应用程序。 +- **air-gapped**：气隙隔离。指系统与外部网络完全物理隔离的安全措施。 +- **YOLO**：You Only Live Once 的缩写，此处指快速、大胆的执行模式。 +- **evals**：评估。对 AI 模型或智能体性能的测试与评价。 +- **graceful degradation**：优雅降级。系统在部分功能失效时仍能保持基本功能的特性。 +- **sub-agent**：子智能体。在主智能体协调下执行特定任务的辅助智能体。 +- **context**：上下文。AI 理解任务所需的相关信息与环境背景。 +- **workflow**：工作流。一系列有序的任务或操作流程。 +- **skills**：技能。AI 智能体可执行的具体能力或功能模块。 +- **CLI**：命令行界面。通过文本命令与计算机交互的方式。 +- **GUI**：图形用户界面。通过图形元素与计算机交互的方式。 diff --git a/docs/zh-cn/tutorials/getting-started.md b/docs/zh-cn/tutorials/getting-started.md new file mode 100644 index 000000000..3bffb4407 --- /dev/null +++ b/docs/zh-cn/tutorials/getting-started.md @@ -0,0 +1,300 @@ +--- +title: "快速入门" +description: 安装 BMad 并构建你的第一个项目 +--- + +使用 AI 驱动的工作流更快地构建软件，通过专门的智能体引导你完成规划、架构设计和实现。 + +## 你将学到 + +- 为新项目安装并初始化 BMad Method +- 使用 **BMad-Help** —— 你的智能向导，它知道下一步该做什么 +- 根据项目规模选择合适的规划路径 +- 从需求到可用代码，逐步推进各个阶段 +- 有效使用智能体和工作流 + +:::note[前置条件] +- **Node.js 20+** — 安装程序必需 +- **Git** — 推荐用于版本控制 +- **AI 驱动的 IDE** — Claude Code、Cursor 或类似工具 +- **一个项目想法** — 即使是简单的想法也可以用于学习 +::: + +:::tip[最简单的路径] +**安装** → `npx bmad-method install` +**询问** → `bmad-help 我应该先做什么？` +**构建** → 让 BMad-Help 逐个工作流地引导你 +::: + +## 认识 BMad-Help：你的智能向导 + +**BMad-Help 是开始使用 BMad 的最快方式。** 你不需要记住工作流或阶段 —— 只需询问，BMad-Help 就会： + +- **检查你的项目**，看看已经完成了什么 +- **根据你安装的模块显示你的选项** +- **推荐下一步** —— 包括第一个必需任务 +- **回答问题**，比如"我有一个 SaaS 想法，应该从哪里开始？" + +### 如何使用 BMad-Help + +只需在 AI IDE 中使用斜杠命令运行它： + +``` +bmad-help +``` + +或者结合问题以获得上下文感知的指导： + +``` +bmad-help 我有一个 SaaS 产品的想法，我已经知道我想要的所有功能。我应该从哪里开始？ +``` + +BMad-Help 将回应： +- 针对你的情况推荐什么 +- 第一个必需任务是什么 +- 其余流程是什么样的 + +### 它也驱动工作流 + +BMad-Help 不仅回答问题 —— **它会在每个工作流结束时自动运行**，告诉你确切地下一步该做什么。无需猜测，无需搜索文档 —— 只需对下一个必需工作流的清晰指导。 + +:::tip[从这里开始] +安装 BMad 后，立即运行 `bmad-help`。它将检测你安装了哪些模块，并引导你找到项目的正确起点。 +::: + +## 了解 BMad + +BMad 通过带有专门 AI 智能体的引导工作流帮助你构建软件。该过程遵循四个阶段： + +| 阶段 | 名称 | 发生什么 | +| ---- | -------------- | -------------------------------------------------- | +| 1 | 分析 | 头脑风暴、研究、产品简报 *（可选）* | +| 2 | 规划 | 创建需求（PRD 或技术规范） | +| 3 | 解决方案设计 | 设计架构 *（仅限 BMad Method/Enterprise only）* | +| 4 | 实现 | 逐个史诗、逐个故事地构建 | + +**[打开工作流地图](../reference/workflow-map.md)** 以探索阶段、工作流和上下文管理。 + +根据项目的复杂性，BMad 提供三种规划路径： + +| 路径 | 最适合 | 创建的文档 | +| --------------- | ---------------------------------------------------- | --------------------------------------- | +| **Quick Flow** | 错误修复、简单功能、范围清晰（1-15 个故事） | 仅技术规范 | +| **BMad Method** | 产品、平台、复杂功能（10-50+ 个故事） | PRD + 架构 + UX | +| **Enterprise** | 合规、多租户系统（30+ 个故事） | PRD + 架构 + 安全 + DevOps | + +:::note +故事数量是指导，而非定义。根据规划需求选择你的路径，而不是故事数学。 +::: + +## 安装 + +在项目目录中打开终端并运行： + +```bash +npx bmad-method install +``` + +当提示选择模块时，选择 **BMad Method**。 + +安装程序会创建两个文件夹： +- `_bmad/` — 智能体、工作流、任务和配置 +- `_bmad-output/` — 目前为空，但这是你的工件将被保存的地方 + +:::tip[你的下一步] +在项目文件夹中打开你的 AI IDE 并运行： + +``` +bmad-help +``` + +BMad-Help 将检测你已完成的内容，并准确推荐下一步该做什么。你也可以问它诸如"我的选项是什么？"或"我有一个 SaaS 想法，我应该从哪里开始？"之类的问题。 +::: + +:::note[如何加载智能体和运行工作流] +每个工作流都有一个你在 IDE 中运行的**斜杠命令**（例如 `bmad-bmm-create-prd`）。运行工作流命令会自动加载相应的智能体 —— 你不需要单独加载智能体。你也可以直接加载智能体进行一般对话（例如，加载 PM 智能体使用 `bmad-agent-bmm-pm`）。 +::: + +:::caution[新对话] +始终为每个工作流开始一个新的对话。这可以防止上下文限制导致问题。 +::: + +## 步骤 1：创建你的计划 + +完成阶段 1-3。**为每个工作流使用新对话。** + +:::tip[项目上下文（可选）] +在开始之前，考虑创建 `project-context.md` 来记录你的技术偏好和实现规则。这确保所有 AI 智能体在整个项目中遵循你的约定。 + +在 `_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`） — 推荐的基础文档 + +### 阶段 2：规划（必需） + +**对于 BMad Method 和 Enterprise 路径：** +1. 在新对话中加载 **PM 智能体**（`bmad-agent-bmm-pm`） +2. 运行 `prd` 工作流（`bmad-bmm-create-prd`） +3. 输出：`PRD.md` + +**对于 Quick Flow 路径：** +- 使用 `quick-spec` 工作流（`bmad-bmm-quick-spec`）代替 PRD，然后跳转到实现 + +:::note[UX 设计（可选）] +如果你的项目有用户界面，在创建 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`） +3. 输出：包含技术决策的架构文档 + +**创建史诗和故事** + +:::tip[V6 改进] +史诗和故事现在在架构*之后*创建。这会产生更高质量的故事，因为架构决策（数据库、API 模式、技术栈）直接影响工作应该如何分解。 +::: + +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`） +3. 验证所有规划文档之间的一致性 + +## 步骤 2：构建你的项目 + +规划完成后，进入实现阶段。**每个工作流应该在新对话中运行。** + +### 初始化冲刺规划 + +加载 **SM 智能体**（`bmad-agent-bmm-sm`）并运行 `sprint-planning`（`bmad-bmm-sprint-planning`）。这将创建 `sprint-status.yaml` 来跟踪所有史诗和故事。 + +### 构建周期 + +对于每个故事，使用新对话重复此周期： + +| 步骤 | 智能体 | 工作流 | 命令 | 目的 | +| ---- | ------ | ------------ | ----------------------- | ------------------------------- | +| 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`）。 + +## 你已完成的工作 + +你已经学习了使用 BMad 构建的基础： + +- 安装了 BMad 并为你的 IDE 进行了配置 +- 使用你选择的规划路径初始化了项目 +- 创建了规划文档（PRD、架构、史诗和故事） +- 了解了实现的构建周期 + +你的项目现在拥有： + +```text +your-project/ +├── _bmad/ # BMad 配置 +├── _bmad-output/ +│ ├── planning-artifacts/ +│ │ ├── PRD.md # 你的需求文档 +│ │ ├── architecture.md # 技术决策 +│ │ └── epics/ # 史诗和故事文件 +│ ├── implementation-artifacts/ +│ │ └── sprint-status.yaml # 冲刺跟踪 +│ └── project-context.md # 实现规则（可选） +└── ... +``` + +## 快速参考 + +| 工作流 | 命令 | 智能体 | 目的 | +| ----------------------------------- | --------------------------------------- | -------- | -------------------------------------------- | +| **`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 | 审查已实现的代码 | + +## 常见问题 + +**我总是需要架构吗？** +仅对于 BMad Method 和 Enterprise 路径。Quick Flow 从技术规范跳转到实现。 + +**我可以稍后更改我的计划吗？** +可以。SM 智能体有一个 `correct-course` 工作流（`bmad-bmm-correct-course`）用于处理范围变更。 + +**如果我想先进行头脑风暴怎么办？** +在开始 PRD 之前，加载 Analyst 智能体（`bmad-agent-bmm-analyst`）并运行 `brainstorming`（`bmad-brainstorming`）。 + +**我需要遵循严格的顺序吗？** +不一定。一旦你了解了流程，你可以使用上面的快速参考直接运行工作流。 + +## 获取帮助 + +:::tip[第一站：BMad-Help] +**随时运行 `bmad-help`** —— 这是摆脱困境的最快方式。问它任何问题： +- "安装后我应该做什么？" +- "我在工作流 X 上卡住了" +- "我在 Y 方面有什么选项？" +- "向我展示到目前为止已完成的工作" + +BMad-Help 检查你的项目，检测你已完成的内容，并确切地告诉你下一步该做什么。 +::: + +- **在工作流期间** — 智能体通过问题和解释引导你 +- **社区** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) + +## 关键要点 + +:::tip[记住这些] +- **从 `bmad-help` 开始** — 你的智能向导，了解你的项目和选项 +- **始终使用新对话** — 为每个工作流开始新对话 +- **路径很重要** — Quick Flow 使用 quick-spec；Method/Enterprise 需要 PRD 和架构 +- **BMad-Help 自动运行** — 每个工作流结束时都会提供下一步的指导 +::: + +准备好开始了吗？安装 BMad，运行 `bmad-help`，让你的智能向导为你引路。 + +--- +## 术语说明 + +- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。 +- **epic**：史诗。软件开发中用于组织和管理大型功能或用户需求的高级工作项。 +- **story**：故事。敏捷开发中的用户故事，描述用户需求的小型工作项。 +- **PRD**：产品需求文档（Product Requirements Document）。详细描述产品功能、需求和目标的文档。 +- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定目标。 +- **sprint**：冲刺。敏捷开发中的固定时间周期，用于完成预定的工作。 +- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试等功能的软件工具。 +- **artifact**：工件。软件开发过程中产生的文档、代码或其他可交付成果。 +- **retrospective**：回顾。敏捷开发中的会议，用于反思和改进团队工作流程。 +- **tech-spec**：技术规范（Technical Specification）。描述系统技术实现细节的文档。 +- **UX**：用户体验（User Experience）。用户在使用产品过程中的整体感受和交互体验。 +- **PM**：产品经理（Product Manager）。负责产品规划、需求管理和团队协调的角色。 +- **SM**：Scrum Master。敏捷开发中的角色，负责促进 Scrum 流程和团队协作。 +- **DEV**：开发者（Developer）。负责编写代码和实现功能的角色。 +- **Architect**：架构师。负责系统架构设计和技术决策的角色。 +- **Analyst**：分析师。负责需求分析、市场研究等工作的角色。 +- **npx**：Node Package eXecute。Node.js 包执行器，用于运行 npm 包而无需安装。 +- **Node.js**：基于 Chrome V8 引擎的 JavaScript 运行时环境。 +- **Git**：分布式版本控制系统。 +- **SaaS**：软件即服务（Software as a Service）。通过互联网提供软件服务的模式。 +- **DevOps**：开发运维（Development and Operations）。强调开发和运维协作的实践和方法。 +- **multi-tenant**：多租户。一种软件架构，允许单个实例为多个客户（租户）提供服务。 +- **compliance**：合规性。遵守法律、法规和行业标准的要求。 diff --git a/package-lock.json b/package-lock.json index 5f538a62f..a87584a21 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "bmad-method", - "version": "6.0.1", + "version": "6.1.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "bmad-method", - "version": "6.0.1", + "version": "6.1.0", "license": "MIT", "dependencies": { "@clack/core": "^1.0.0", diff --git a/package.json b/package.json index 3881e2733..5012dea5a 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/package.json", "name": "bmad-method", - "version": "6.0.1", + "version": "6.1.0", "description": "Breakthrough Method of Agile AI-driven Development", "keywords": [ "agile", diff --git a/src/bmm/agents/analyst.agent.yaml b/src/bmm/agents/analyst.agent.yaml index 28120d098..f17597c2a 100644 --- a/src/bmm/agents/analyst.agent.yaml +++ b/src/bmm/agents/analyst.agent.yaml @@ -18,7 +18,7 @@ agent: menu: - trigger: BP or fuzzy match on brainstorm-project - exec: "{project-root}/_bmad/core/workflows/brainstorming/workflow.md" + exec: "skill:bmad-brainstorming" data: "{project-root}/_bmad/bmm/data/project-context-template.md" description: "[BP] Brainstorm Project: Expert Guided Facilitation through a single or multiple techniques with a final report" @@ -27,7 +27,7 @@ agent: description: "[MR] Market Research: Market analysis, competitive landscape, customer needs and trends" - trigger: DR or fuzzy match on domain-research - exec: "{project-root}/_bmad/bmm/workflows/1-analysis/research/workflow-domain-research.md" + exec: "skill:bmad-domain-research" description: "[DR] Domain Research: Industry domain deep dive, subject matter expertise and terminology" - trigger: TR or fuzzy match on technical-research @@ -35,9 +35,9 @@ agent: description: "[TR] Technical Research: Technical feasibility, architecture options and implementation approaches" - trigger: CB or fuzzy match on product-brief - exec: "{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md" + exec: "skill:bmad-create-product-brief" description: "[CB] Create Brief: A guided experience to nail down your product idea into an executive brief" - trigger: DP or fuzzy match on document-project - workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md" description: "[DP] Document Project: Analyze an existing project to produce useful documentation for both human and LLM" diff --git a/src/bmm/agents/bmad-skill-manifest.yaml b/src/bmm/agents/bmad-skill-manifest.yaml new file mode 100644 index 000000000..2f3930de8 --- /dev/null +++ b/src/bmm/agents/bmad-skill-manifest.yaml @@ -0,0 +1,39 @@ +analyst.agent.yaml: + canonicalId: bmad-analyst + type: agent + description: "Business Analyst for market research, competitive analysis, and requirements elicitation" + +architect.agent.yaml: + canonicalId: bmad-architect + type: agent + description: "Architect for distributed systems, cloud infrastructure, and API design" + +dev.agent.yaml: + canonicalId: bmad-dev + type: agent + description: "Developer Agent for story execution, test-driven development, and code implementation" + +pm.agent.yaml: + canonicalId: bmad-pm + type: agent + description: "Product Manager for PRD creation, requirements discovery, and stakeholder alignment" + +qa.agent.yaml: + canonicalId: bmad-qa + type: agent + description: "QA Engineer for test automation, API testing, and E2E testing" + +quick-flow-solo-dev.agent.yaml: + canonicalId: bmad-quick-flow-solo-dev + type: agent + description: "Quick Flow Solo Dev for rapid spec creation and lean implementation" + +sm.agent.yaml: + canonicalId: bmad-sm + type: agent + description: "Scrum Master for sprint planning, story preparation, and agile ceremonies" + +ux-designer.agent.yaml: + canonicalId: bmad-ux-designer + type: agent + description: "UX Designer for user research, interaction design, and UI patterns" diff --git a/src/bmm/agents/dev.agent.yaml b/src/bmm/agents/dev.agent.yaml index c707124d0..d9da7446b 100644 --- a/src/bmm/agents/dev.agent.yaml +++ b/src/bmm/agents/dev.agent.yaml @@ -30,9 +30,9 @@ agent: menu: - trigger: DS or fuzzy match on dev-story - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml" + exec: "skill:bmad-dev-story" description: "[DS] Dev Story: Write the next or specified stories tests and code." - trigger: CR or fuzzy match on code-review - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.md" description: "[CR] Code Review: Initiate a comprehensive code review across multiple quality facets. For best results, use a fresh context and a different quality LLM if available" diff --git a/src/bmm/agents/pm.agent.yaml b/src/bmm/agents/pm.agent.yaml index 30377a682..bf104246a 100644 --- a/src/bmm/agents/pm.agent.yaml +++ b/src/bmm/agents/pm.agent.yaml @@ -40,5 +40,5 @@ agent: description: "[IR] Implementation Readiness: Ensure the PRD, UX, and Architecture and Epics and Stories List are all aligned" - trigger: CC or fuzzy match on correct-course - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md" description: "[CC] Course Correction: Use this so we can determine how to proceed if major need for change is discovered mid implementation" diff --git a/src/bmm/agents/qa.agent.yaml b/src/bmm/agents/qa.agent.yaml index 9265f5a7b..65b0711b2 100644 --- a/src/bmm/agents/qa.agent.yaml +++ b/src/bmm/agents/qa.agent.yaml @@ -29,7 +29,7 @@ agent: menu: - trigger: QA or fuzzy match on qa-automate - workflow: "{project-root}/_bmad/bmm/workflows/qa/automate/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/qa-generate-e2e-tests/workflow.md" description: "[QA] Automate - Generate tests for existing features (simplified)" prompts: diff --git a/src/bmm/agents/quick-flow-solo-dev.agent.yaml b/src/bmm/agents/quick-flow-solo-dev.agent.yaml index fff3052d4..e019804e2 100644 --- a/src/bmm/agents/quick-flow-solo-dev.agent.yaml +++ b/src/bmm/agents/quick-flow-solo-dev.agent.yaml @@ -24,9 +24,13 @@ agent: description: "[QS] Quick Spec: Architect a quick but complete technical spec with implementation-ready stories/specs" - trigger: QD or fuzzy match on quick-dev - workflow: "{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md" + exec: "skill:bmad-quick-dev" description: "[QD] Quick-flow Develop: Implement a story tech spec end-to-end (Core of Quick Flow)" + - trigger: QQ or fuzzy match on bmad-quick-dev-new-preview + exec: "{project-root}/_bmad/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md" + description: "[QQ] Quick Dev New (Preview): Unified quick flow — clarify intent, plan, implement, review, present (experimental)" + - trigger: CR or fuzzy match on code-review - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.md" description: "[CR] Code Review: Initiate a comprehensive code review across multiple quality facets. For best results, use a fresh context and a different quality LLM if available" diff --git a/src/bmm/agents/sm.agent.yaml b/src/bmm/agents/sm.agent.yaml index d79f644e5..ef71f7681 100644 --- a/src/bmm/agents/sm.agent.yaml +++ b/src/bmm/agents/sm.agent.yaml @@ -20,18 +20,18 @@ agent: menu: - trigger: SP or fuzzy match on sprint-planning - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.md" description: "[SP] Sprint Planning: Generate or update the record that will sequence the tasks to complete the full project that the dev agent will follow" - trigger: CS or fuzzy match on create-story - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml" + exec: "skill:bmad-create-story" description: "[CS] Context Story: Prepare a story with all required context for implementation for the developer agent" - trigger: ER or fuzzy match on epic-retrospective - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.md" data: "{project-root}/_bmad/_config/agent-manifest.csv" description: "[ER] Epic Retrospective: Party Mode review of all work completed across an epic." - trigger: CC or fuzzy match on correct-course - workflow: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md" description: "[CC] Course Correction: Use this so we can determine how to proceed if major need for change is discovered mid implementation" diff --git a/src/bmm/agents/tech-writer/bmad-skill-manifest.yaml b/src/bmm/agents/tech-writer/bmad-skill-manifest.yaml new file mode 100644 index 000000000..78aaa63eb --- /dev/null +++ b/src/bmm/agents/tech-writer/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-tech-writer +type: agent +description: "Technical Writer for documentation, Mermaid diagrams, and standards compliance" diff --git a/src/bmm/agents/tech-writer/tech-writer.agent.yaml b/src/bmm/agents/tech-writer/tech-writer.agent.yaml index 555bd7981..25f0aca06 100644 --- a/src/bmm/agents/tech-writer/tech-writer.agent.yaml +++ b/src/bmm/agents/tech-writer/tech-writer.agent.yaml @@ -22,7 +22,7 @@ agent: menu: - trigger: DP or fuzzy match on document-project - workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/document-project/workflow.md" description: "[DP] Document Project: Generate comprehensive project documentation (brownfield analysis, architecture scanning)" - trigger: WD or fuzzy match on write-document diff --git a/src/bmm/module-help.csv b/src/bmm/module-help.csv index 635bb8a81..0afef236c 100644 --- a/src/bmm/module-help.csv +++ b/src/bmm/module-help.csv @@ -1,19 +1,20 @@ module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs, -bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.yaml,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*, +bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.md,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze an existing project to produce useful documentation",project-knowledge,*, bmm,anytime,Generate Project Context,GPC,,_bmad/bmm/workflows/generate-project-context/workflow.md,bmad-bmm-generate-project-context,false,analyst,Create Mode,"Scan existing codebase to generate a lean LLM-optimized project-context.md containing critical implementation rules patterns and conventions for AI agents. Essential for brownfield projects and quick-flow.",output_folder,"project context", bmm,anytime,Quick Spec,QS,,_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md,bmad-bmm-quick-spec,false,quick-flow-solo-dev,Create Mode,"Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method. Quick one-off tasks small changes simple apps brownfield additions to well established patterns utilities without extensive planning",planning_artifacts,"tech spec", -bmm,anytime,Quick Dev,QD,,_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning - Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method, unless the user is already working through the implementation phase and just requests a 1 off things not already in the plan",,, -bmm,anytime,Correct Course,CC,,_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal", +bmm,anytime,Quick Dev,QD,,skill:bmad-quick-dev,bmad-bmm-quick-dev,false,quick-flow-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning - Do not suggest for potentially very complex things unless requested or if the user complains that they do not want to follow the extensive planning of the bmad method, unless the user is already working through the implementation phase and just requests a 1 off things not already in the plan",,, +bmm,anytime,Quick Dev New Preview,QQ,,skill:bmad-quick-dev-new-preview,bmad-bmm-quick-dev-new-preview,false,quick-flow-solo-dev,Create Mode,"Unified quick flow (experimental): clarify intent plan implement review and present in a single workflow",implementation_artifacts,"tech spec implementation", +bmm,anytime,Correct Course,CC,,_bmad/bmm/workflows/4-implementation/correct-course/workflow.md,bmad-bmm-correct-course,false,sm,Create Mode,"Anytime: Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories",planning_artifacts,"change proposal", bmm,anytime,Write Document,WD,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Describe in detail what you want, and the agent will follow the documentation best practices defined in agent memory. Multi-turn conversation with subprocess for research/review.",project-knowledge,"document", bmm,anytime,Update Standards,US,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Update agent memory documentation-standards.md with your specific preferences if you discover missing document conventions.",_bmad/_memory/tech-writer-sidecar,"standards", bmm,anytime,Mermaid Generate,MG,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Create a Mermaid diagram based on user description. Will suggest diagram types if not specified.",planning_artifacts,"mermaid diagram", bmm,anytime,Validate Document,VD,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Review the specified document against documentation standards and best practices. Returns specific actionable improvement suggestions organized by priority.",planning_artifacts,"validation report", bmm,anytime,Explain Concept,EC,,_bmad/bmm/agents/tech-writer/tech-writer.agent.yaml,,false,tech-writer,,"Create clear technical explanations with examples and diagrams for complex concepts. Breaks down into digestible sections using task-oriented approach.",project_knowledge,"explanation", -bmm,1-analysis,Brainstorm Project,BP,10,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,data=_bmad/bmm/data/project-context-template.md,"Expert Guided Facilitation through a single or multiple techniques",planning_artifacts,"brainstorming session", +bmm,1-analysis,Brainstorm Project,BP,10,skill:bmad-brainstorming,bmad-brainstorming,false,analyst,data=_bmad/bmm/data/project-context-template.md,"Expert Guided Facilitation through a single or multiple techniques",planning_artifacts,"brainstorming session", bmm,1-analysis,Market Research,MR,20,_bmad/bmm/workflows/1-analysis/research/workflow-market-research.md,bmad-bmm-market-research,false,analyst,Create Mode,"Market analysis competitive landscape customer needs and trends","planning_artifacts|project-knowledge","research documents", -bmm,1-analysis,Domain Research,DR,21,_bmad/bmm/workflows/1-analysis/research/workflow-domain-research.md,bmad-bmm-domain-research,false,analyst,Create Mode,"Industry domain deep dive subject matter expertise and terminology","planning_artifacts|project_knowledge","research documents", +bmm,1-analysis,Domain Research,DR,21,skill:bmad-domain-research,bmad-bmm-domain-research,false,analyst,Create Mode,"Industry domain deep dive subject matter expertise and terminology","planning_artifacts|project_knowledge","research documents", bmm,1-analysis,Technical Research,TR,22,_bmad/bmm/workflows/1-analysis/research/workflow-technical-research.md,bmad-bmm-technical-research,false,analyst,Create Mode,"Technical feasibility architecture options and implementation approaches","planning_artifacts|project_knowledge","research documents", -bmm,1-analysis,Create Brief,CB,30,_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md,bmad-bmm-create-product-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief", +bmm,1-analysis,Create Brief,CB,30,skill:bmad-create-product-brief,bmad-bmm-create-product-brief,false,analyst,Create Mode,"A guided experience to nail down your product idea",planning_artifacts,"product brief", bmm,2-planning,Create PRD,CP,10,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md,bmad-bmm-create-prd,true,pm,Create Mode,"Expert led facilitation to produce your Product Requirements Document",planning_artifacts,prd, bmm,2-planning,Validate PRD,VP,20,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md,bmad-bmm-validate-prd,false,pm,Validate Mode,"Validate PRD is comprehensive lean well organized and cohesive",planning_artifacts,"prd validation report", bmm,2-planning,Edit PRD,EP,25,_bmad/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md,bmad-bmm-edit-prd,false,pm,Edit Mode,"Improve and enhance an existing PRD",planning_artifacts,"updated prd", @@ -21,11 +22,11 @@ bmm,2-planning,Create UX,CU,30,_bmad/bmm/workflows/2-plan-workflows/create-ux-de bmm,3-solutioning,Create Architecture,CA,10,_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md,bmad-bmm-create-architecture,true,architect,Create Mode,"Guided Workflow to document technical decisions",planning_artifacts,architecture, bmm,3-solutioning,Create Epics and Stories,CE,30,_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md,bmad-bmm-create-epics-and-stories,true,pm,Create Mode,"Create the Epics and Stories Listing",planning_artifacts,"epics and stories", bmm,3-solutioning,Check Implementation Readiness,IR,70,_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md,bmad-bmm-check-implementation-readiness,true,architect,Validate Mode,"Ensure PRD UX Architecture and Epics Stories are aligned",planning_artifacts,"readiness report", -bmm,4-implementation,Sprint Planning,SP,10,_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml,bmad-bmm-sprint-planning,true,sm,Create Mode,"Generate sprint plan for development tasks - this kicks off the implementation phase by producing a plan the implementation agents will follow in sequence for every story in the plan.",implementation_artifacts,"sprint status", -bmm,4-implementation,Sprint Status,SS,20,_bmad/bmm/workflows/4-implementation/sprint-status/workflow.yaml,bmad-bmm-sprint-status,false,sm,Create Mode,"Anytime: Summarize sprint status and route to next workflow",,, -bmm,4-implementation,Validate Story,VS,35,_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml,bmad-bmm-create-story,false,sm,Validate Mode,"Validates story readiness and completeness before development work begins",implementation_artifacts,"story validation report", -bmm,4-implementation,Create Story,CS,30,_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml,bmad-bmm-create-story,true,sm,Create Mode,"Story cycle start: Prepare first found story in the sprint plan that is next, or if the command is run with a specific epic and story designation with context. Once complete, then VS then DS then CR then back to DS if needed or next CS or ER",implementation_artifacts,story, -bmm,4-implementation,Dev Story,DS,40,_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml,bmad-bmm-dev-story,true,dev,Create Mode,"Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed",,, -bmm,4-implementation,Code Review,CR,50,_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml,bmad-bmm-code-review,false,dev,Create Mode,"Story cycle: If issues back to DS if approved then next CS or ER if epic complete",,, -bmm,4-implementation,QA Automation Test,QA,45,_bmad/bmm/workflows/qa/automate/workflow.yaml,bmad-bmm-qa-automate,false,qa,Create Mode,"Generate automated API and E2E tests for implemented code using the project's existing test framework (detects existing well known in use test frameworks). Use after implementation to add test coverage. NOT for code review or story validation - use CR for that.",implementation_artifacts,"test suite", -bmm,4-implementation,Retrospective,ER,60,_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml,bmad-bmm-retrospective,false,sm,Create Mode,"Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC",implementation_artifacts,retrospective, +bmm,4-implementation,Sprint Planning,SP,10,_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.md,bmad-bmm-sprint-planning,true,sm,Create Mode,"Generate sprint plan for development tasks - this kicks off the implementation phase by producing a plan the implementation agents will follow in sequence for every story in the plan.",implementation_artifacts,"sprint status", +bmm,4-implementation,Sprint Status,SS,20,_bmad/bmm/workflows/4-implementation/sprint-status/workflow.md,bmad-bmm-sprint-status,false,sm,Create Mode,"Anytime: Summarize sprint status and route to next workflow",,, +bmm,4-implementation,Validate Story,VS,35,skill:bmad-create-story,bmad-bmm-create-story,false,sm,Validate Mode,"Validates story readiness and completeness before development work begins",implementation_artifacts,"story validation report", +bmm,4-implementation,Create Story,CS,30,skill:bmad-create-story,bmad-bmm-create-story,true,sm,Create Mode,"Story cycle start: Prepare first found story in the sprint plan that is next, or if the command is run with a specific epic and story designation with context. Once complete, then VS then DS then CR then back to DS if needed or next CS or ER",implementation_artifacts,story, +bmm,4-implementation,Dev Story,DS,40,skill:bmad-dev-story,bmad-bmm-dev-story,true,dev,Create Mode,"Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed",,, +bmm,4-implementation,Code Review,CR,50,_bmad/bmm/workflows/4-implementation/code-review/workflow.md,bmad-bmm-code-review,false,dev,Create Mode,"Story cycle: If issues back to DS if approved then next CS or ER if epic complete",,, +bmm,4-implementation,QA Automation Test,QA,45,_bmad/bmm/workflows/qa-generate-e2e-tests/workflow.md,bmad-bmm-qa-automate,false,qa,Create Mode,"Generate automated API and E2E tests for implemented code using the project's existing test framework (detects existing well known in use test frameworks). Use after implementation to add test coverage. NOT for code review or story validation - use CR for that.",implementation_artifacts,"test suite", +bmm,4-implementation,Retrospective,ER,60,_bmad/bmm/workflows/4-implementation/retrospective/workflow.md,bmad-bmm-retrospective,false,sm,Create Mode,"Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC",implementation_artifacts,retrospective, diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/SKILL.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/SKILL.md new file mode 100644 index 000000000..4ef96c650 --- /dev/null +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-create-product-brief +description: 'Create product brief through collaborative discovery. Use when the user says "lets create a product brief" or "help me create a project brief"' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/bmm/workflows/1-analysis/bmad-create-product-brief/bmad-skill-manifest.yaml b/src/bmm/workflows/1-analysis/bmad-create-product-brief/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/bmm/workflows/1-analysis/create-product-brief/product-brief.template.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md similarity index 100% rename from src/bmm/workflows/1-analysis/create-product-brief/product-brief.template.md rename to src/bmm/workflows/1-analysis/bmad-create-product-brief/product-brief.template.md diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-01-init.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01-init.md similarity index 96% rename from src/bmm/workflows/1-analysis/create-product-brief/steps/step-01-init.md rename to src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01-init.md index 0046af0cc..496180933 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-01-init.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01-init.md @@ -3,7 +3,7 @@ name: 'step-01-init' description: 'Initialize the product brief workflow by detecting continuation state and setting up the document' # File References -nextStepFile: '{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md' +nextStepFile: './step-02-vision.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Template References @@ -73,7 +73,7 @@ If the document exists and has frontmatter with `stepsCompleted`: **Continuation Protocol:** -- **STOP immediately** and load `{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-01b-continue.md` +- **STOP immediately** and load `./step-01b-continue.md` - Do not proceed with any initialization tasks - Let step-01b handle all continuation logic - This is an auto-proceed situation - no user choice needed diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-01b-continue.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01b-continue.md similarity index 93% rename from src/bmm/workflows/1-analysis/create-product-brief/steps/step-01b-continue.md rename to src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01b-continue.md index bedcfc913..99b2495fe 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-01b-continue.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-01b-continue.md @@ -95,9 +95,9 @@ Does this look right, or do you want to make any adjustments before we proceed?" **Next Step Logic:** Based on `lastStep` value, determine which step to load next: -- If `lastStep = 1` → Load `{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md` -- If `lastStep = 2` → Load `{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md` -- If `lastStep = 3` → Load `{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md` +- If `lastStep = 1` → Load `./step-02-vision.md` +- If `lastStep = 2` → Load `./step-03-users.md` +- If `lastStep = 3` → Load `./step-04-metrics.md` - Continue this pattern for all steps - If `lastStep = 6` → Workflow already complete diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md similarity index 96% rename from src/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md rename to src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md index fbbdffd01..c9e60df19 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md @@ -3,12 +3,12 @@ name: 'step-02-vision' description: 'Discover and define the core product vision, problem statement, and unique value proposition' # File References -nextStepFile: '{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md' +nextStepFile: './step-03-users.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 2: Product Vision Discovery diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md similarity index 96% rename from src/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md rename to src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md index eb8fd1168..2a035eeb9 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md @@ -3,12 +3,12 @@ name: 'step-03-users' description: 'Define target users with rich personas and map their key interactions with the product' # File References -nextStepFile: '{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md' +nextStepFile: './step-04-metrics.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 3: Target Users Discovery diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md similarity index 96% rename from src/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md rename to src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md index 04c67edc4..359bc0954 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md @@ -3,12 +3,12 @@ name: 'step-04-metrics' description: 'Define comprehensive success metrics that include user success, business objectives, and key performance indicators' # File References -nextStepFile: '{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md' +nextStepFile: './step-05-scope.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 4: Success Metrics Definition diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md similarity index 96% rename from src/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md rename to src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md index 04339f41f..0d5b99613 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.md @@ -3,12 +3,12 @@ name: 'step-05-scope' description: 'Define MVP scope with clear boundaries and outline future vision while managing scope creep' # File References -nextStepFile: '{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md' +nextStepFile: './step-06-complete.md' outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 5: MVP Scope Definition diff --git a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-06-complete.md similarity index 98% rename from src/bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md rename to src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-06-complete.md index 82573286f..7363f7c95 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-06-complete.md @@ -128,7 +128,7 @@ Recap that the brief captures everything needed to guide subsequent product deve ### 5. Suggest next steps -Product Brief complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Validate PRD`. +Product Brief complete. Invoke the `bmad-help` skill. --- diff --git a/src/bmm/workflows/1-analysis/create-product-brief/workflow.md b/src/bmm/workflows/1-analysis/bmad-create-product-brief/workflow.md similarity index 88% rename from src/bmm/workflows/1-analysis/create-product-brief/workflow.md rename to src/bmm/workflows/1-analysis/bmad-create-product-brief/workflow.md index 9d5e83f19..267f8cce8 100644 --- a/src/bmm/workflows/1-analysis/create-product-brief/workflow.md +++ b/src/bmm/workflows/1-analysis/bmad-create-product-brief/workflow.md @@ -1,8 +1,3 @@ ---- -name: create-product-brief -description: Create comprehensive product briefs through collaborative step-by-step discovery as creative Business Analyst working with the user as peers. ---- - # Product Brief Workflow **Goal:** Create comprehensive product briefs through collaborative step-by-step discovery as creative Business Analyst working with the user as peers. @@ -54,4 +49,4 @@ Load and read full config from {project-root}/_bmad/bmm/config.yaml and resolve: ### 2. First Step EXECUTION -Read fully and follow: `{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/steps/step-01-init.md` to begin the workflow. +Read fully and follow: `./steps/step-01-init.md` to begin the workflow. diff --git a/src/bmm/workflows/1-analysis/research/bmad-domain-research/SKILL.md b/src/bmm/workflows/1-analysis/research/bmad-domain-research/SKILL.md new file mode 100644 index 000000000..f978519dc --- /dev/null +++ b/src/bmm/workflows/1-analysis/research/bmad-domain-research/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-domain-research +description: 'Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]"' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/bmm/workflows/1-analysis/research/bmad-domain-research/bmad-skill-manifest.yaml b/src/bmm/workflows/1-analysis/research/bmad-domain-research/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/bmm/workflows/1-analysis/research/bmad-domain-research/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/bmm/workflows/1-analysis/research/domain-steps/step-01-init.md b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-01-init.md similarity index 95% rename from src/bmm/workflows/1-analysis/research/domain-steps/step-01-init.md rename to src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-01-init.md index 50093186e..27d056b1d 100644 --- a/src/bmm/workflows/1-analysis/research/domain-steps/step-01-init.md +++ b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-01-init.md @@ -78,7 +78,7 @@ For **{{research_topic}}**, I will research: - Document scope confirmation in research file - Update frontmatter: `stepsCompleted: [1]` -- Load: `{project-root}/_bmad/bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md` +- Load: `./step-02-domain-analysis.md` ## APPEND TO DOCUMENT: @@ -132,6 +132,6 @@ When user selects 'C', append scope confirmation: ## NEXT STEP: -After user selects 'C', load `{project-root}/_bmad/bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md` to begin industry analysis. +After user selects 'C', load `./step-02-domain-analysis.md` to begin industry analysis. Remember: This is SCOPE CONFIRMATION ONLY - no actual domain research yet, just confirming the research approach and scope! diff --git a/src/bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-02-domain-analysis.md similarity index 96% rename from src/bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md rename to src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-02-domain-analysis.md index ed5c78f5e..bb4cbb63f 100644 --- a/src/bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md +++ b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-02-domain-analysis.md @@ -171,7 +171,7 @@ _Source: [URL]_ - **CONTENT ALREADY WRITTEN TO DOCUMENT** - Update frontmatter: `stepsCompleted: [1, 2]` -- Load: `{project-root}/_bmad/bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md` +- Load: `./step-03-competitive-landscape.md` ## APPEND TO DOCUMENT: @@ -224,6 +224,6 @@ Content is already written to document when generated in step 4. No additional a ## NEXT STEP: -After user selects 'C', load `{project-root}/_bmad/bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md` to analyze competitive landscape, key players, and ecosystem analysis for {{research_topic}}. +After user selects 'C', load `./step-03-competitive-landscape.md` to analyze competitive landscape, key players, and ecosystem analysis for {{research_topic}}. Remember: Always write research content to document immediately and search the web to verify facts! diff --git a/src/bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-03-competitive-landscape.md similarity index 96% rename from src/bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md rename to src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-03-competitive-landscape.md index 6970ad87b..0dc2de6ea 100644 --- a/src/bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md +++ b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-03-competitive-landscape.md @@ -180,7 +180,7 @@ _Source: [URL]_ - **CONTENT ALREADY WRITTEN TO DOCUMENT** - Update frontmatter: `stepsCompleted: [1, 2, 3]` -- Load: `{project-root}/_bmad/bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md` +- Load: `./step-04-regulatory-focus.md` ## APPEND TO DOCUMENT: @@ -233,6 +233,6 @@ Content is already written to document when generated in step 4. No additional a ## NEXT STEP: -After user selects 'C', load `{project-root}/_bmad/bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md` to analyze regulatory requirements, compliance frameworks, and legal considerations for {{research_topic}}. +After user selects 'C', load `./step-04-regulatory-focus.md` to analyze regulatory requirements, compliance frameworks, and legal considerations for {{research_topic}}. Remember: Always write research content to document immediately and search the web to verify facts! diff --git a/src/bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-04-regulatory-focus.md similarity index 95% rename from src/bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md rename to src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-04-regulatory-focus.md index 3fd24b00b..e98010c7f 100644 --- a/src/bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md +++ b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-04-regulatory-focus.md @@ -155,7 +155,7 @@ Show the generated regulatory analysis and present continue option: - **CONTENT ALREADY WRITTEN TO DOCUMENT** - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]` -- Load: `{project-root}/_bmad/bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md` +- Load: `./step-05-technical-trends.md` ## APPEND TO DOCUMENT: @@ -201,6 +201,6 @@ Content is already written to document when generated in step 5. No additional a ## NEXT STEP: -After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md` to analyze technical trends and innovations in the domain. +After user selects 'C' and content is saved to document, load `./step-05-technical-trends.md` to analyze technical trends and innovations in the domain. Remember: Search the web to verify regulatory facts and provide practical implementation considerations! diff --git a/src/bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-05-technical-trends.md similarity index 98% rename from src/bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md rename to src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-05-technical-trends.md index caf69e142..55e834cd1 100644 --- a/src/bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md +++ b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-05-technical-trends.md @@ -174,7 +174,7 @@ Show the generated technical analysis and present complete option: - **CONTENT ALREADY WRITTEN TO DOCUMENT** - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]` -- Load: `{project-root}/_bmad/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md` +- Load: `./step-06-research-synthesis.md` ## APPEND TO DOCUMENT: diff --git a/src/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md b/src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-06-research-synthesis.md similarity index 100% rename from src/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md rename to src/bmm/workflows/1-analysis/research/bmad-domain-research/domain-steps/step-06-research-synthesis.md diff --git a/src/bmm/workflows/1-analysis/research/bmad-domain-research/research.template.md b/src/bmm/workflows/1-analysis/research/bmad-domain-research/research.template.md new file mode 100644 index 000000000..1d9952470 --- /dev/null +++ b/src/bmm/workflows/1-analysis/research/bmad-domain-research/research.template.md @@ -0,0 +1,29 @@ +--- +stepsCompleted: [] +inputDocuments: [] +workflowType: 'research' +lastStep: 1 +research_type: '{{research_type}}' +research_topic: '{{research_topic}}' +research_goals: '{{research_goals}}' +user_name: '{{user_name}}' +date: '{{date}}' +web_research_enabled: true +source_verification: true +--- + +# Research Report: {{research_type}} + +**Date:** {{date}} +**Author:** {{user_name}} +**Research Type:** {{research_type}} + +--- + +## Research Overview + +[Research overview and methodology will be appended here] + +--- + + diff --git a/src/bmm/workflows/1-analysis/research/workflow-domain-research.md b/src/bmm/workflows/1-analysis/research/bmad-domain-research/workflow.md similarity index 92% rename from src/bmm/workflows/1-analysis/research/workflow-domain-research.md rename to src/bmm/workflows/1-analysis/research/bmad-domain-research/workflow.md index 91fcbaa9a..09976cb9a 100644 --- a/src/bmm/workflows/1-analysis/research/workflow-domain-research.md +++ b/src/bmm/workflows/1-analysis/research/bmad-domain-research/workflow.md @@ -1,8 +1,3 @@ ---- -name: domain-research -description: Conduct domain research covering industry analysis, regulations, technology trends, and ecosystem dynamics using current web data and verified sources. ---- - # Domain Research Workflow **Goal:** Conduct comprehensive domain/industry research using current web data and verified sources to produce complete research documents with compelling narratives and proper citations. diff --git a/src/bmm/workflows/1-analysis/research/bmad-skill-manifest.yaml b/src/bmm/workflows/1-analysis/research/bmad-skill-manifest.yaml new file mode 100644 index 000000000..f9ca17f4b --- /dev/null +++ b/src/bmm/workflows/1-analysis/research/bmad-skill-manifest.yaml @@ -0,0 +1,9 @@ +workflow-market-research.md: + canonicalId: bmad-market-research + type: workflow + description: "Conduct market research on competition and customers. Use when the user says 'create a market research report about [business idea]'" + +workflow-technical-research.md: + canonicalId: bmad-technical-research + type: workflow + description: "Conduct technical research on technologies and architecture. Use when the user says 'create a technical research report on [topic]'" diff --git a/src/bmm/workflows/1-analysis/research/workflow-market-research.md b/src/bmm/workflows/1-analysis/research/workflow-market-research.md index 5669e6f24..8a77a67cd 100644 --- a/src/bmm/workflows/1-analysis/research/workflow-market-research.md +++ b/src/bmm/workflows/1-analysis/research/workflow-market-research.md @@ -1,6 +1,6 @@ --- name: market-research -description: Conduct market research covering market size, growth, competition, and customer insights using current web data and verified sources. +description: 'Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".' --- # Market Research Workflow diff --git a/src/bmm/workflows/1-analysis/research/workflow-technical-research.md b/src/bmm/workflows/1-analysis/research/workflow-technical-research.md index 2ac5420ce..ecc9a2f27 100644 --- a/src/bmm/workflows/1-analysis/research/workflow-technical-research.md +++ b/src/bmm/workflows/1-analysis/research/workflow-technical-research.md @@ -1,6 +1,6 @@ --- name: technical-research -description: Conduct technical research covering technology evaluation, architecture decisions, and implementation approaches using current web data and verified sources. +description: 'Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".' --- # Technical Research Workflow diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/bmad-skill-manifest.yaml b/src/bmm/workflows/2-plan-workflows/create-prd/bmad-skill-manifest.yaml new file mode 100644 index 000000000..aea9910a2 --- /dev/null +++ b/src/bmm/workflows/2-plan-workflows/create-prd/bmad-skill-manifest.yaml @@ -0,0 +1,14 @@ +workflow-create-prd.md: + canonicalId: bmad-create-prd + type: workflow + description: "Create a PRD from scratch. Use when the user says 'lets create a product requirements document' or 'I want to create a new PRD'" + +workflow-edit-prd.md: + canonicalId: bmad-edit-prd + type: workflow + description: "Edit an existing PRD. Use when the user says 'edit this PRD'" + +workflow-validate-prd.md: + canonicalId: bmad-validate-prd + type: workflow + description: "Validate a PRD against standards. Use when the user says 'validate this PRD' or 'run PRD validation'" diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md index 7d337b47d..ebbfc9dea 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md @@ -11,8 +11,8 @@ projectTypesCSV: '../data/project-types.csv' domainComplexityCSV: '../data/domain-complexity.csv' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 2: Project Discovery diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02b-vision.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02b-vision.md index 9b7b2a975..ca5c5cc91 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02b-vision.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02b-vision.md @@ -7,8 +7,8 @@ nextStepFile: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/st outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 2b: Product Vision Discovery diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02c-executive-summary.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02c-executive-summary.md index 3f024decd..60a91f314 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02c-executive-summary.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02c-executive-summary.md @@ -7,8 +7,8 @@ nextStepFile: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/st outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 2c: Executive Summary Generation diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md index 79722289a..b77e2db28 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md @@ -7,8 +7,8 @@ nextStepFile: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/st outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 3: Success Criteria Definition diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md index fc919ff07..0f9ddacdd 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md @@ -7,8 +7,8 @@ nextStepFile: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/st outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 4: User Journey Mapping diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md index bb95ea16f..7a9b52380 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md @@ -8,8 +8,8 @@ outputFile: '{planning_artifacts}/prd.md' domainComplexityCSV: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/domain-complexity.csv' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 5: Domain-Specific Requirements (Optional) diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md index 708eac7b1..471140455 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md @@ -10,8 +10,8 @@ outputFile: '{planning_artifacts}/prd.md' projectTypesCSV: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/project-types.csv' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 6: Innovation Discovery diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md index 63c9070b6..259cb136e 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md @@ -10,8 +10,8 @@ outputFile: '{planning_artifacts}/prd.md' projectTypesCSV: '../data/project-types.csv' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 7: Project-Type Deep Dive diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md index e9df0caba..5954c4312 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md @@ -7,8 +7,8 @@ nextStepFile: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/st outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 8: Scoping Exercise - MVP & Future Features diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md index a39150c0c..8bcdddad9 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md @@ -7,8 +7,8 @@ nextStepFile: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/st outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 9: Functional Requirements Synthesis diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md index d42323046..207dea459 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md @@ -7,8 +7,8 @@ nextStepFile: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/st outputFile: '{planning_artifacts}/prd.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 10: Non-Functional Requirements diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md index 257afbc27..19ed725bb 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md @@ -8,8 +8,8 @@ outputFile: '{planning_artifacts}/prd.md' purposeFile: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step 11: Document Polish @@ -99,6 +99,22 @@ Review the entire document with PRD purpose principles in mind: - Are technical terms used appropriately? - Would stakeholders find this easy to understand? +### 2b. Brainstorming Reconciliation (if brainstorming input exists) + +**Check the PRD frontmatter `inputDocuments` for any brainstorming document** (e.g., `brainstorming-session*.md`, `brainstorming-report.md`). If a brainstorming document was used as input: + +1. **Load the brainstorming document** and extract all distinct ideas, themes, and recommendations +2. **Cross-reference against the PRD** — for each brainstorming idea, check if it landed in any PRD section (requirements, success criteria, user journeys, scope, etc.) +3. **Identify dropped ideas** — ideas from brainstorming that do not appear anywhere in the PRD. Pay special attention to: + - Tone, personality, and interaction design ideas (these are most commonly lost) + - Design philosophy and coaching approach ideas + - "What should this feel like" ideas (UX feel, not just UX function) + - Qualitative/soft ideas that don't map cleanly to functional requirements +4. **Present findings to user**: "These brainstorming ideas did not make it into the PRD: [list]. Should any be incorporated?" +5. **If user wants to incorporate dropped ideas**: Add them to the most appropriate PRD section (success criteria, non-functional requirements, or a new section if needed) + +**Why this matters**: Brainstorming documents are often long, and the PRD's structured template has an implicit bias toward concrete/structural ideas. Soft ideas (tone, philosophy, interaction feel) frequently get silently dropped because they don't map cleanly to FR/NFR format. + ### 3. Optimization Actions Make targeted improvements: @@ -193,6 +209,7 @@ When user selects 'C', replace the entire document content with the polished ver ✅ User's voice and intent preserved ✅ Document is more readable and professional ✅ A/P/C menu presented and handled correctly +✅ Brainstorming reconciliation completed (if brainstorming input exists) ✅ Polished document saved when C selected ## FAILURE MODES: diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md index 266bf06e4..04204e8a9 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md @@ -87,7 +87,7 @@ Offer validation workflows to ensure PRD is ready for implementation: ### 4. Suggest Next Workflows -PRD complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Create PRD`. +PRD complete. Invoke the `bmad-help` skill. ### 5. Final Completion Confirmation diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md index 8f47cd551..b20743c16 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md @@ -5,8 +5,8 @@ description: 'Discovery & Understanding - Understand what user wants to edit and # File references (ONLY variables used in this step) altStepFile: './step-e-01b-legacy-conversion.md' prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Step E-1: Discovery & Understanding diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md index f34de79ff..bf4c91b4d 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-02-review.md @@ -7,7 +7,7 @@ nextStepFile: './step-e-03-edit.md' prdFile: '{prd_file_path}' validationReport: '{validation_report_path}' # If provided prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' --- # Step E-2: Deep Review & Analysis diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md index 6c591c2dd..e10611c8e 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md @@ -4,8 +4,8 @@ description: 'Document Discovery & Confirmation - Handle fresh context validatio # File references (ONLY variables used in this step) nextStepFile: './step-v-02-format-detection.md' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' prdPurpose: '../data/prd-purpose.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-10-smart-validation.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-10-smart-validation.md index e937c7526..5f5fc2d19 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-10-smart-validation.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-10-smart-validation.md @@ -6,7 +6,6 @@ description: 'SMART Requirements Validation - Validate Functional Requirements m nextStepFile: './step-v-11-holistic-quality-validation.md' prdFile: '{prd_file_path}' validationReportPath: '{validation_report_path}' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' --- # Step 10: SMART Requirements Validation diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md index 698b6f654..347215135 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-11-holistic-quality-validation.md @@ -6,7 +6,7 @@ description: 'Holistic Quality Assessment - Assess PRD as cohesive, compelling d nextStepFile: './step-v-12-completeness-validation.md' prdFile: '{prd_file_path}' validationReportPath: '{validation_report_path}' -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' --- # Step 11: Holistic Quality Assessment diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md index 24e0c7de7..dd331bf48 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md @@ -197,7 +197,7 @@ Display: - **IF X (Exit):** - Display: "**Validation Report Saved:** {validationReportPath}" - Display: "**Summary:** {overall status} - {recommendation}" - - PRD Validation complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Validate PRD`. + - PRD Validation complete. Invoke the `bmad-help` skill. - **IF Any other:** Help user, then redisplay menu diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md b/src/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md index 7d10ec3ed..c7c565a72 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md @@ -1,6 +1,6 @@ --- name: create-prd -description: Create a comprehensive PRD (Product Requirements Document) through structured workflow facilitation +description: 'Create a PRD from scratch. Use when the user says "lets create a product requirements document" or "I want to create a new PRD"' main_config: '{project-root}/_bmad/bmm/config.yaml' nextStep: './steps-c/step-01-init.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md b/src/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md index 5cb05af53..e416e11f5 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md @@ -1,6 +1,6 @@ --- name: edit-prd -description: Edit and improve an existing PRD - enhance clarity, completeness, and quality +description: 'Edit an existing PRD. Use when the user says "edit this PRD".' main_config: '{project-root}/_bmad/bmm/config.yaml' editWorkflow: './steps-e/step-e-01-discovery.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md b/src/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md index e21745139..7f0703440 100644 --- a/src/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md +++ b/src/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md @@ -1,6 +1,6 @@ --- name: validate-prd -description: Validate an existing PRD against BMAD standards - comprehensive review for completeness, clarity, and quality +description: 'Validate a PRD against standards. Use when the user says "validate this PRD" or "run PRD validation"' main_config: '{project-root}/_bmad/bmm/config.yaml' validateWorkflow: './steps-v/step-v-01-discovery.md' --- diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/bmad-skill-manifest.yaml b/src/bmm/workflows/2-plan-workflows/create-ux-design/bmad-skill-manifest.yaml new file mode 100644 index 000000000..f0b8a250f --- /dev/null +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-create-ux-design +type: workflow +description: "Plan UX patterns and design specifications" diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md index 41821e326..ac32ed77f 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md index 9dc98e70f..215cc36f3 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -161,7 +161,7 @@ Show the generated core experience content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current core experience content +- Read fully and follow: skill:bmad-advanced-elicitation with the current core experience content - Process the enhanced experience insights that come back - Ask user: "Accept these improvements to the core experience definition? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -169,7 +169,7 @@ Show the generated core experience content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current core experience definition +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current core experience definition - Process the collaborative experience improvements that come back - Ask user: "Accept these changes to the core experience definition? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md index f25bf0528..0c7d96fc7 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -164,7 +164,7 @@ Show the generated emotional response content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current emotional response content +- Read fully and follow: skill:bmad-advanced-elicitation with the current emotional response content - Process the enhanced emotional insights that come back - Ask user: "Accept these improvements to the emotional response definition? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -172,7 +172,7 @@ Show the generated emotional response content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current emotional response definition +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current emotional response definition - Process the collaborative emotional insights that come back - Ask user: "Accept these changes to the emotional response definition? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md index 890048b74..5d94d3924 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -179,7 +179,7 @@ Show the generated inspiration analysis content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current inspiration analysis content +- Read fully and follow: skill:bmad-advanced-elicitation with the current inspiration analysis content - Process the enhanced pattern insights that come back - Ask user: "Accept these improvements to the inspiration analysis? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -187,7 +187,7 @@ Show the generated inspiration analysis content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current inspiration analysis +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current inspiration analysis - Process the collaborative pattern insights that come back - Ask user: "Accept these changes to the inspiration analysis? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md index 26caf73db..ad24b7d46 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -197,7 +197,7 @@ Show the generated design system content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current design system content +- Read fully and follow: skill:bmad-advanced-elicitation with the current design system content - Process the enhanced design system insights that come back - Ask user: "Accept these improvements to the design system decision? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -205,7 +205,7 @@ Show the generated design system content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current design system choice +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design system choice - Process the collaborative design system insights that come back - Ask user: "Accept these changes to the design system decision? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md index 8cd5ff3b8..be3dc0782 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -199,7 +199,7 @@ Show the generated defining experience content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current defining experience content +- Read fully and follow: skill:bmad-advanced-elicitation with the current defining experience content - Process the enhanced experience insights that come back - Ask user: "Accept these improvements to the defining experience? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -207,7 +207,7 @@ Show the generated defining experience content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current defining experience +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current defining experience - Process the collaborative experience insights that come back - Ask user: "Accept these changes to the defining experience? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md index 430aab043..501460f01 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -169,7 +169,7 @@ Show the generated visual foundation content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current visual foundation content +- Read fully and follow: skill:bmad-advanced-elicitation with the current visual foundation content - Process the enhanced visual insights that come back - Ask user: "Accept these improvements to the visual foundation? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -177,7 +177,7 @@ Show the generated visual foundation content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current visual foundation +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current visual foundation - Process the collaborative visual insights that come back - Ask user: "Accept these changes to the visual foundation? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md index 09864e0b4..10b2b7d36 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -169,7 +169,7 @@ Show the generated design direction content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current design direction content +- Read fully and follow: skill:bmad-advanced-elicitation with the current design direction content - Process the enhanced design insights that come back - Ask user: "Accept these improvements to the design direction? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -177,7 +177,7 @@ Show the generated design direction content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current design direction +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design direction - Process the collaborative design insights that come back - Ask user: "Accept these changes to the design direction? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md index 9f05201fe..bc1ad1213 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -187,7 +187,7 @@ Show the generated user journey content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current user journey content +- Read fully and follow: skill:bmad-advanced-elicitation with the current user journey content - Process the enhanced journey insights that come back - Ask user: "Accept these improvements to the user journeys? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -195,7 +195,7 @@ Show the generated user journey content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current user journeys +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current user journeys - Process the collaborative journey insights that come back - Ask user: "Accept these changes to the user journeys? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md index 95f2f294a..2a661edf0 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -193,7 +193,7 @@ Show the generated component strategy content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current component strategy content +- Read fully and follow: skill:bmad-advanced-elicitation with the current component strategy content - Process the enhanced component insights that come back - Ask user: "Accept these improvements to the component strategy? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -201,7 +201,7 @@ Show the generated component strategy content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current component strategy +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current component strategy - Process the collaborative component insights that come back - Ask user: "Accept these changes to the component strategy? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md index 08f272a62..cde4a15c3 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -182,7 +182,7 @@ Show the generated UX patterns content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current UX patterns content +- Read fully and follow: skill:bmad-advanced-elicitation with the current UX patterns content - Process the enhanced pattern insights that come back - Ask user: "Accept these improvements to the UX patterns? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -190,7 +190,7 @@ Show the generated UX patterns content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current UX patterns +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current UX patterns - Process the collaborative pattern insights that come back - Ask user: "Accept these changes to the UX patterns? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md index d13ffa5c4..57becfded 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md @@ -30,8 +30,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -209,7 +209,7 @@ Show the generated responsive and accessibility content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current responsive/accessibility content +- Read fully and follow: skill:bmad-advanced-elicitation with the current responsive/accessibility content - Process the enhanced insights that come back - Ask user: "Accept these improvements to the responsive/accessibility strategy? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -217,7 +217,7 @@ Show the generated responsive and accessibility content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current responsive/accessibility strategy +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current responsive/accessibility strategy - Process the collaborative insights that come back - Ask user: "Accept these changes to the responsive/accessibility strategy? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md index ff2268248..73b07217d 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md @@ -82,7 +82,7 @@ Update the main workflow status file: ### 3. Suggest Next Steps -UX Design complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Create UX`. +UX Design complete. Invoke the `bmad-help` skill. ### 5. Final Completion Confirmation diff --git a/src/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md b/src/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md index baa0fe488..4dfdba9f1 100644 --- a/src/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md +++ b/src/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md @@ -1,6 +1,6 @@ --- name: create-ux-design -description: Work with a peer UX Design expert to plan your applications UX patterns, look and feel. +description: 'Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"' --- # Create UX Design Workflow diff --git a/src/bmm/workflows/3-solutioning/check-implementation-readiness/bmad-skill-manifest.yaml b/src/bmm/workflows/3-solutioning/check-implementation-readiness/bmad-skill-manifest.yaml new file mode 100644 index 000000000..3040413b8 --- /dev/null +++ b/src/bmm/workflows/3-solutioning/check-implementation-readiness/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-check-implementation-readiness +type: workflow +description: "Validate PRD, UX, Architecture and Epics specs are complete" diff --git a/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md b/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md index 199b48a21..548aa8f6d 100644 --- a/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md +++ b/src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md @@ -109,7 +109,7 @@ The assessment found [number] issues requiring attention. Review the detailed re The implementation readiness workflow is now complete. The report contains all findings and recommendations for the user to consider. -Implementation Readiness complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `implementation readiness`. +Implementation Readiness complete. Invoke the `bmad-help` skill. --- diff --git a/src/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md b/src/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md index 0c20e032a..f1ab122ec 100644 --- a/src/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md +++ b/src/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md @@ -1,6 +1,6 @@ --- name: check-implementation-readiness -description: 'Critical validation workflow that assesses PRD, Architecture, and Epics & Stories for completeness and alignment before implementation. Uses adversarial review approach to find gaps and issues.' +description: 'Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says "check implementation readiness".' --- # Implementation Readiness diff --git a/src/bmm/workflows/3-solutioning/create-architecture/bmad-skill-manifest.yaml b/src/bmm/workflows/3-solutioning/create-architecture/bmad-skill-manifest.yaml new file mode 100644 index 000000000..6b35ce8e7 --- /dev/null +++ b/src/bmm/workflows/3-solutioning/create-architecture/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-create-architecture +type: workflow +description: "Create architecture solution design decisions for AI agent consistency" diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md index d4c908711..cd62d7988 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md @@ -31,8 +31,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -170,7 +170,7 @@ Show the generated content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with the current context analysis +- Invoke the `bmad-advanced-elicitation` skill with the current context analysis - Process the enhanced architectural insights that come back - Ask user: "Accept these enhancements to the project context analysis? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu @@ -178,7 +178,7 @@ Show the generated content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current project context +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current project context - Process the collaborative improvements to architectural understanding - Ask user: "Accept these changes to the project context analysis? (y/n)" - If yes: Update content with improvements, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md index 45dc74c55..cf6ef39a7 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md @@ -31,8 +31,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -276,7 +276,7 @@ Show the generated content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with current starter analysis +- Read fully and follow: skill:bmad-advanced-elicitation with current starter analysis - Process enhanced insights about starter options or custom approaches - Ask user: "Accept these changes to the starter template evaluation? (y/n)" - If yes: Update content, then return to A/P/C menu @@ -284,7 +284,7 @@ Show the generated content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with starter evaluation context +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with starter evaluation context - Process collaborative insights about starter trade-offs - Ask user: "Accept these changes to the starter template evaluation? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md index 2fe2d3469..fd596e91b 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md @@ -32,8 +32,8 @@ This step will generate content and present choices for each decision category: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -264,7 +264,7 @@ Show the generated decisions content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with specific decision categories +- Read fully and follow: skill:bmad-advanced-elicitation with specific decision categories - Process enhanced insights about particular decisions - Ask user: "Accept these enhancements to the architectural decisions? (y/n)" - If yes: Update content, then return to A/P/C menu @@ -272,7 +272,7 @@ Show the generated decisions content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with architectural decisions context +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with architectural decisions context - Process collaborative insights about decision trade-offs - Ask user: "Accept these changes to the architectural decisions? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md index cb0641afb..7620f1cf7 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md @@ -32,8 +32,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -305,7 +305,7 @@ Show the generated patterns content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with current patterns +- Read fully and follow: skill:bmad-advanced-elicitation with current patterns - Process enhanced consistency rules that come back - Ask user: "Accept these additional pattern refinements? (y/n)" - If yes: Update content, then return to A/P/C menu @@ -313,7 +313,7 @@ Show the generated patterns content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with implementation patterns context +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with implementation patterns context - Process collaborative insights about potential conflicts - Ask user: "Accept these changes to the implementation patterns? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md index 7a2019a9f..75a4c1462 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md @@ -32,8 +32,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -325,7 +325,7 @@ Show the generated project structure content and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with current project structure +- Read fully and follow: skill:bmad-advanced-elicitation with current project structure - Process enhanced organizational insights that come back - Ask user: "Accept these changes to the project structure? (y/n)" - If yes: Update content, then return to A/P/C menu @@ -333,7 +333,7 @@ Show the generated project structure content and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with project structure context +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with project structure context - Process collaborative insights about organization trade-offs - Ask user: "Accept these changes to the project structure? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md index 580a957fe..5ce15b6a5 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md @@ -32,8 +32,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md +- When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation +- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -305,7 +305,7 @@ Show the validation results and present choices: #### If 'A' (Advanced Elicitation): -- Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml with validation issues +- Read fully and follow: skill:bmad-advanced-elicitation with validation issues - Process enhanced solutions for complex concerns - Ask user: "Accept these architectural improvements? (y/n)" - If yes: Update content, then return to A/P/C menu @@ -313,7 +313,7 @@ Show the validation results and present choices: #### If 'P' (Party Mode): -- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with validation context +- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with validation context - Process collaborative insights on implementation readiness - Ask user: "Accept these changes to the validation results? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md index 791c17778..e378fc97e 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md @@ -41,7 +41,7 @@ completedAt: '{{current_date}}' ### 3. Next Steps Guidance -Architecture complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Create Architecture`. +Architecture complete. Invoke the `bmad-help` skill. Upon Completion of task output: offer to answer any questions about the Architecture Document. diff --git a/src/bmm/workflows/3-solutioning/create-architecture/workflow.md b/src/bmm/workflows/3-solutioning/create-architecture/workflow.md index 508a57046..1fac8d1ac 100644 --- a/src/bmm/workflows/3-solutioning/create-architecture/workflow.md +++ b/src/bmm/workflows/3-solutioning/create-architecture/workflow.md @@ -1,6 +1,6 @@ --- name: create-architecture -description: Collaborative architectural decision facilitation for AI-agent consistency. Replaces template-driven architecture with intelligent, adaptive conversation that produces a decision-focused architecture document optimized for preventing agent conflicts. +description: 'Create architecture solution design decisions for AI agent consistency. Use when the user says "lets create architecture" or "create technical architecture" or "create a solution design"' --- # Architecture Workflow diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/bmad-skill-manifest.yaml b/src/bmm/workflows/3-solutioning/create-epics-and-stories/bmad-skill-manifest.yaml new file mode 100644 index 000000000..92b343dd9 --- /dev/null +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-create-epics-and-stories +type: workflow +description: "Break requirements into epics and user stories" diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md index c8d6b1330..60e9f21f4 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md @@ -13,8 +13,8 @@ outputFile: '{planning_artifacts}/epics.md' epicsTemplate: '{workflow_path}/templates/epics-template.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' # Template References epicsTemplate: '{workflow_path}/templates/epics-template.md' @@ -154,20 +154,31 @@ Review the Architecture document for technical requirements that impact epic and ... ``` -### 6. Extract Additional Requirements from UX (if exists) +### 6. Extract UX Design Requirements (if UX document exists) -Review the UX document for requirements that affect epic and story creation: +**IMPORTANT**: The UX Design Specification is a first-class input document, not supplementary material. Requirements from the UX spec must be extracted with the same rigor as PRD functional requirements. + +Read the FULL UX Design document and extract ALL actionable work items: **Look for:** -- Responsive design requirements -- Accessibility requirements -- Browser/device compatibility -- User interaction patterns that need implementation -- Animation or transition requirements -- Error handling UX requirements +- **Design token work**: Color systems, spacing scales, typography tokens that need implementation or consolidation +- **Component proposals**: Reusable UI components identified in the UX spec (e.g., ConfirmActions, StatusMessage, EmptyState, FocusIndicator) +- **Visual standardization**: Semantic CSS classes, consistent color palette usage, design pattern consolidation +- **Accessibility requirements**: Contrast audit fixes, ARIA patterns, keyboard navigation, screen reader support +- **Responsive design requirements**: Breakpoints, layout adaptations, mobile-specific interactions +- **Interaction patterns**: Animations, transitions, loading states, error handling UX +- **Browser/device compatibility**: Target platforms, progressive enhancement requirements -**Add these to Additional Requirements list.** +**Format UX Design Requirements as a SEPARATE section (not merged into Additional Requirements):** + +``` +UX-DR1: [Actionable UX design requirement with clear implementation scope] +UX-DR2: [Actionable UX design requirement with clear implementation scope] +... +``` + +**🚨 CRITICAL**: Do NOT reduce UX requirements to vague summaries. Each UX-DR must be specific enough to generate a story with testable acceptance criteria. If the UX spec identifies 6 reusable components, list all 6 — not "create reusable components." ### 7. Load and Initialize Template @@ -178,7 +189,8 @@ Load {epicsTemplate} and initialize {outputFile}: 3. Replace placeholder sections with extracted requirements: - {{fr_list}} → extracted FRs - {{nfr_list}} → extracted NFRs - - {{additional_requirements}} → extracted additional requirements + - {{additional_requirements}} → extracted additional requirements (from Architecture) + - {{ux_design_requirements}} → extracted UX Design Requirements (if UX document exists) 4. Leave {{requirements_coverage_map}} and {{epics_list}} as placeholders for now ### 8. Present Extracted Requirements @@ -197,12 +209,17 @@ Display to user: - Display key NFRs - Ask if any constraints were missed -**Additional Requirements:** +**Additional Requirements (Architecture):** - Summarize technical requirements from Architecture -- Summarize UX requirements (if applicable) - Verify completeness +**UX Design Requirements (if applicable):** + +- Show count of UX-DRs found +- Display key UX Design requirements (design tokens, components, accessibility) +- Verify each UX-DR is specific enough for story creation + ### 9. Get User Confirmation Ask: "Do these extracted requirements accurately represent what needs to be built? Any additions or corrections?" @@ -216,6 +233,7 @@ After extraction and confirmation, update {outputFile} with: - Complete FR list in {{fr_list}} section - Complete NFR list in {{nfr_list}} section - All additional requirements in {{additional_requirements}} section +- UX Design requirements in {{ux_design_requirements}} section (if UX document exists) ### 10. Present MENU OPTIONS diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md index 1b497c2ad..6453c62ee 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md @@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md' outputFile: '{planning_artifacts}/epics.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' # Template References epicsTemplate: '{workflow_path}/templates/epics-template.md' diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md index 2e13f9b2c..1bdbb0631 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md @@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md' outputFile: '{planning_artifacts}/epics.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' # Template References epicsTemplate: '{workflow_path}/templates/epics-template.md' @@ -66,9 +66,11 @@ Load {outputFile} and review: - Approved epics_list from Step 2 - FR coverage map -- All requirements (FRs, NFRs, additional) +- All requirements (FRs, NFRs, additional, **UX Design requirements if present**) - Template structure at the end of the document +**UX Design Integration**: If UX Design Requirements (UX-DRs) were extracted in Step 1, ensure they are visible during story creation. UX-DRs must be covered by stories — either within existing epics (e.g., accessibility fixes for a feature epic) or in a dedicated "Design System / UX Polish" epic. + ### 2. Explain Story Creation Approach **STORY CREATION GUIDELINES:** @@ -146,6 +148,7 @@ Display: - Epic goal statement - FRs covered by this epic - Any NFRs or additional requirements relevant +- Any UX Design Requirements (UX-DRs) relevant to this epic #### B. Story Breakdown @@ -207,6 +210,7 @@ After all epics and stories are generated: - Verify the document follows template structure exactly - Ensure all placeholders are replaced - Confirm all FRs are covered +- **Confirm all UX Design Requirements (UX-DRs) are covered by at least one story** (if UX document was an input) - Check formatting consistency ## TEMPLATE STRUCTURE COMPLIANCE: diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md index dc504182d..92bb71277 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md @@ -11,8 +11,8 @@ workflowFile: '{workflow_path}/workflow.md' outputFile: '{planning_artifacts}/epics.md' # Task References -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' +partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' # Template References epicsTemplate: '{workflow_path}/templates/epics-template.md' @@ -144,6 +144,6 @@ If all validations pass: When C is selected, the workflow is complete and the epics.md is ready for development. -Epics and Stories complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Create Epics and Stories`. +Epics and Stories complete. Invoke the `bmad-help` skill. Upon Completion of task output: offer to answer any questions about the Epics and Stories. diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md index 05afe1f5f..bf80c7fba 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md @@ -23,6 +23,10 @@ This document provides the complete epic and story breakdown for {{project_name} {{additional_requirements}} +### UX Design Requirements + +{{ux_design_requirements}} + ### FR Coverage Map {{requirements_coverage_map}} diff --git a/src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md b/src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md index a0e232ab8..41a6ee106 100644 --- a/src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md +++ b/src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md @@ -1,6 +1,6 @@ --- name: create-epics-and-stories -description: 'Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value. This workflow requires completed PRD + Architecture documents (UX recommended if UI exists) and breaks down requirements into implementation-ready epics and user stories that incorporate all available technical and design context. Creates detailed, actionable stories with complete acceptance criteria for development teams.' +description: 'Break requirements into epics and user stories. Use when the user says "create the epics and stories list"' --- # Create Epics and Stories diff --git a/src/bmm/workflows/4-implementation/bmad-create-story/SKILL.md b/src/bmm/workflows/4-implementation/bmad-create-story/SKILL.md new file mode 100644 index 000000000..5acb64e97 --- /dev/null +++ b/src/bmm/workflows/4-implementation/bmad-create-story/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-create-story +description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/bmm/workflows/4-implementation/bmad-create-story/bmad-skill-manifest.yaml b/src/bmm/workflows/4-implementation/bmad-create-story/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/bmm/workflows/4-implementation/bmad-create-story/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/bmm/workflows/4-implementation/create-story/checklist.md b/src/bmm/workflows/4-implementation/bmad-create-story/checklist.md similarity index 95% rename from src/bmm/workflows/4-implementation/create-story/checklist.md rename to src/bmm/workflows/4-implementation/bmad-create-story/checklist.md index d9ed06375..06ad346ba 100644 --- a/src/bmm/workflows/4-implementation/create-story/checklist.md +++ b/src/bmm/workflows/4-implementation/bmad-create-story/checklist.md @@ -33,25 +33,25 @@ This is a COMPETITION to create the **ULTIMATE story context** that makes LLM de ### **When Running from Create-Story Workflow:** -- The `{project-root}/_bmad/core/tasks/workflow.xml` framework will automatically: +- The workflow framework will automatically: - Load this checklist file - Load the newly created story file (`{story_file_path}`) - - Load workflow variables from `{installed_path}/workflow.yaml` + - Load workflow variables from `{installed_path}/workflow.md` - Execute the validation process ### **When Running in Fresh Context:** - User should provide the story file path being reviewed - Load the story file directly -- Load the corresponding workflow.yaml for variable context +- Load the corresponding workflow.md for variable context - Proceed with systematic analysis ### **Required Inputs:** - **Story file**: The story file to review and improve -- **Workflow variables**: From workflow.yaml (implementation_artifacts, epics_file, etc.) +- **Workflow variables**: From workflow.md (implementation_artifacts, epics_file, etc.) - **Source documents**: Epics, architecture, etc. (discovered or provided) -- **Validation framework**: `validate-workflow.xml` (handles checklist execution) +- **Validation framework**: The workflow's checklist execution system --- @@ -61,12 +61,11 @@ You will systematically re-do the entire story creation process, but with a crit ### **Step 1: Load and Understand the Target** -1. **Load the workflow configuration**: `{installed_path}/workflow.yaml` for variable inclusion +1. **Load the workflow configuration**: `{installed_path}/workflow.md` for variable inclusion 2. **Load the story file**: `{story_file_path}` (provided by user or discovered) -3. **Load validation framework**: `{project-root}/_bmad/core/tasks/workflow.xml` -4. **Extract metadata**: epic_num, story_num, story_key, story_title from story file -5. **Resolve all workflow variables**: implementation_artifacts, epics_file, architecture_file, etc. -6. **Understand current status**: What story implementation guidance is currently provided? +3. **Extract metadata**: epic_num, story_num, story_key, story_title from story file +4. **Resolve all workflow variables**: implementation_artifacts, epics_file, architecture_file, etc. +5. **Understand current status**: What story implementation guidance is currently provided? **Note:** If running in fresh context, user should provide the story file path being reviewed. If running from create-story workflow, the validation framework will automatically discover the checklist and story file. diff --git a/src/bmm/workflows/4-implementation/bmad-create-story/discover-inputs.md b/src/bmm/workflows/4-implementation/bmad-create-story/discover-inputs.md new file mode 100644 index 000000000..2c313db3d --- /dev/null +++ b/src/bmm/workflows/4-implementation/bmad-create-story/discover-inputs.md @@ -0,0 +1,88 @@ +# Discover Inputs Protocol + +**Objective:** Intelligently load project files (whole or sharded) based on the workflow's Input Files configuration. + +**Prerequisite:** Only execute this protocol if the workflow defines an Input Files section. If no input file patterns are configured, skip this entirely. + +--- + +## Step 1: Parse Input File Patterns + +- Read the Input Files table from the workflow configuration. +- For each input group (prd, architecture, epics, ux, etc.), note the **load strategy** if specified. + +## Step 2: Load Files Using Smart Strategies + +For each pattern in the Input Files table, work through the following substeps in order: + +### 2a: Try Sharded Documents First + +If a sharded pattern exists for this input, determine the load strategy (defaults to **FULL_LOAD** if not specified), then apply the matching strategy: + +#### FULL_LOAD Strategy + +Load ALL files in the sharded directory. Use this for PRD, Architecture, UX, brownfield docs, or whenever the full picture is needed. + +1. Use the glob pattern to find ALL `.md` files (e.g., `{planning_artifacts}/*architecture*/*.md`). +2. Load EVERY matching file completely. +3. Concatenate content in logical order: `index.md` first if it exists, then alphabetical. +4. Store the combined result in a variable named `{pattern_name_content}` (e.g., `{architecture_content}`). + +#### SELECTIVE_LOAD Strategy + +Load a specific shard using a template variable. Example: used for epics with `{{epic_num}}`. + +1. Check for template variables in the sharded pattern (e.g., `{{epic_num}}`). +2. If the variable is undefined, ask the user for the value OR infer it from context. +3. Resolve the template to a specific file path. +4. Load that specific file. +5. Store in variable: `{pattern_name_content}`. + +#### INDEX_GUIDED Strategy + +Load index.md, analyze the structure and description of each doc in the index, then intelligently load relevant docs. + +**DO NOT BE LAZY** -- use best judgment to load documents that might have relevant information, even if there is only a 5% chance of relevance. + +1. Load `index.md` from the sharded directory. +2. Parse the table of contents, links, and section headers. +3. Analyze the workflow's purpose and objective. +4. Identify which linked/referenced documents are likely relevant. + - *Example:* If the workflow is about authentication and the index shows "Auth Overview", "Payment Setup", "Deployment" -- load the auth docs, consider deployment docs, skip payment. +5. Load all identified relevant documents. +6. Store combined content in variable: `{pattern_name_content}`. + +**When in doubt, LOAD IT** -- context is valuable, and being thorough is better than missing critical info. + +--- + +After applying the matching strategy, mark the pattern as **RESOLVED** and move to the next pattern. + +### 2b: Try Whole Document if No Sharded Found + +If no sharded matches were found OR no sharded pattern exists for this input: + +1. Attempt a glob match on the "whole" pattern (e.g., `{planning_artifacts}/*prd*.md`). +2. If matches are found, load ALL matching files completely (no offset/limit). +3. Store content in variable: `{pattern_name_content}` (e.g., `{prd_content}`). +4. Mark pattern as **RESOLVED** and move to the next pattern. + +### 2c: Handle Not Found + +If no matches were found for either sharded or whole patterns: + +1. Set `{pattern_name_content}` to empty string. +2. Note in session: "No {pattern_name} files found" -- this is not an error, just unavailable. Offer the user a chance to provide the file. + +## Step 3: Report Discovery Results + +List all loaded content variables with file counts. Example: + +``` +OK Loaded {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ... +OK Loaded {architecture_content} from 1 file: Architecture.md +OK Loaded {epics_content} from selective load: epics/epic-3.md +-- No ux_design files found +``` + +This gives the workflow transparency into what context is available. diff --git a/src/bmm/workflows/4-implementation/create-story/template.md b/src/bmm/workflows/4-implementation/bmad-create-story/template.md similarity index 100% rename from src/bmm/workflows/4-implementation/create-story/template.md rename to src/bmm/workflows/4-implementation/bmad-create-story/template.md diff --git a/src/bmm/workflows/4-implementation/bmad-create-story/workflow.md b/src/bmm/workflows/4-implementation/bmad-create-story/workflow.md new file mode 100644 index 000000000..47b0f8d23 --- /dev/null +++ b/src/bmm/workflows/4-implementation/bmad-create-story/workflow.md @@ -0,0 +1,388 @@ +--- +name: bmad-create-story +description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"' +--- + +# Create Story Workflow + +**Goal:** Create a comprehensive story file that gives the dev agent everything needed for flawless implementation. + +**Your Role:** Story context engine that prevents LLM developer mistakes, omissions, or disasters. +- Communicate all responses in {communication_language} and generate all documents in {document_output_language} +- Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent EVERYTHING needed for flawless implementation +- COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX, vague implementations, lying about completion, not learning from past work +- EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim! This is the most important function in the entire development process! +- UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different artifacts simultaneously and thoroughly +- SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is written +- ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `user_name` +- `communication_language`, `document_output_language` +- `user_skill_level` +- `planning_artifacts`, `implementation_artifacts` +- `date` as system-generated current datetime + +### Paths + +- `installed_path` = `.` +- `template` = `./template.md` +- `validation` = `./checklist.md` +- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` +- `epics_file` = `{planning_artifacts}/epics.md` +- `prd_file` = `{planning_artifacts}/prd.md` +- `architecture_file` = `{planning_artifacts}/architecture.md` +- `ux_file` = `{planning_artifacts}/*ux*.md` +- `story_title` = "" (will be elicited if not derivable) +- `project_context` = `**/project-context.md` (load if exists) +- `default_output_file` = `{implementation_artifacts}/{{story_key}}.md` + +### Input Files + +| Input | Description | Path Pattern(s) | Load Strategy | +|-------|-------------|------------------|---------------| +| prd | PRD (fallback - epics file should have most content) | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | SELECTIVE_LOAD | +| architecture | Architecture (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | SELECTIVE_LOAD | +| ux | UX design (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | SELECTIVE_LOAD | +| epics | Enhanced epics+stories file with BDD and source hints | whole: `{planning_artifacts}/*epic*.md`, sharded: `{planning_artifacts}/*epic*/*.md` | SELECTIVE_LOAD | + +--- + +## EXECUTION + + + + + + Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth" + Set {{epic_num}}, {{story_num}}, {{story_key}} from user input + GOTO step 2a + + + Check if {{sprint_status}} file exists for auto discover + + 🚫 No sprint status file found and no story specified + + **Required Options:** + 1. Run `sprint-planning` to initialize sprint tracking (recommended) + 2. Provide specific epic-story number to create (e.g., "1-2-user-auth") + 3. Provide path to story documents if sprint status doesn't exist yet + + Choose option [1], provide epic-story number, path to story docs, or [q] to quit: + + + HALT - No work needed + + + + Run sprint-planning workflow first to create sprint-status.yaml + HALT - User needs to run sprint-planning + + + + Parse user input: extract epic_num, story_num, story_title + Set {{epic_num}}, {{story_num}}, {{story_key}} from user input + GOTO step 2a + + + + Use user-provided path for story documents + GOTO step 2a + + + + + + MUST read COMPLETE {sprint_status} file from start to end to preserve order + Load the FULL file: {{sprint_status}} + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely + + Find the FIRST story (by reading in order from top to bottom) where: + - Key matches pattern: number-number-name (e.g., "1-2-user-auth") + - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) + - Status value equals "backlog" + + + + 📋 No backlog stories found in sprint-status.yaml + + All stories are either already created, in progress, or done. + + **Options:** + 1. Run sprint-planning to refresh story tracking + 2. Load PM agent and run correct-course to add more stories + 3. Check if current sprint is complete and run retrospective + + HALT + + + Extract from found story key (e.g., "1-2-user-authentication"): + - epic_num: first number before dash (e.g., "1") + - story_num: second number after first dash (e.g., "2") + - story_title: remainder after second dash (e.g., "user-authentication") + + Set {{story_id}} = "{{epic_num}}.{{story_num}}" + Store story_key for later use (e.g., "1-2-user-authentication") + + + Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern + + Load {{sprint_status}} and check epic-{{epic_num}} status + If epic status is "backlog" → update to "in-progress" + If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility) + If epic status is "in-progress" → no change needed + + 🚫 ERROR: Cannot create story in completed epic + Epic {{epic_num}} is marked as 'done'. All stories are complete. + If you need to add more work, either: + 1. Manually change epic status back to 'in-progress' in sprint-status.yaml + 2. Create a new epic for additional work + HALT - Cannot proceed + + + 🚫 ERROR: Invalid epic status '{{epic_status}}' + Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done + Please fix sprint-status.yaml manually or run sprint-planning to regenerate + HALT - Cannot proceed + + 📊 Epic {{epic_num}} status updated to in-progress + + + GOTO step 2a + + Load the FULL file: {{sprint_status}} + Read ALL lines from beginning to end - do not skip any content + Parse the development_status section completely + + Find the FIRST story (by reading in order from top to bottom) where: + - Key matches pattern: number-number-name (e.g., "1-2-user-auth") + - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) + - Status value equals "backlog" + + + + No backlog stories found in sprint-status.yaml + + All stories are either already created, in progress, or done. + + **Options:** + 1. Run sprint-planning to refresh story tracking + 2. Load PM agent and run correct-course to add more stories + 3. Check if current sprint is complete and run retrospective + + HALT + + + Extract from found story key (e.g., "1-2-user-authentication"): + - epic_num: first number before dash (e.g., "1") + - story_num: second number after first dash (e.g., "2") + - story_title: remainder after second dash (e.g., "user-authentication") + + Set {{story_id}} = "{{epic_num}}.{{story_num}}" + Store story_key for later use (e.g., "1-2-user-authentication") + + + Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern + + Load {{sprint_status}} and check epic-{{epic_num}} status + If epic status is "backlog" → update to "in-progress" + If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility) + If epic status is "in-progress" → no change needed + + ERROR: Cannot create story in completed epic + Epic {{epic_num}} is marked as 'done'. All stories are complete. + If you need to add more work, either: + 1. Manually change epic status back to 'in-progress' in sprint-status.yaml + 2. Create a new epic for additional work + HALT - Cannot proceed + + + ERROR: Invalid epic status '{{epic_status}}' + Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done + Please fix sprint-status.yaml manually or run sprint-planning to regenerate + HALT - Cannot proceed + + Epic {{epic_num}} status updated to in-progress + + + GOTO step 2a + + + + 🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer fuckups! + + + Read fully and follow `{installed_path}/discover-inputs.md` to load all input files + Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, + {project_context} + + + From {epics_content}, extract Epic {{epic_num}} complete context: **EPIC ANALYSIS:** - Epic + objectives and business value - ALL stories in this epic for cross-story context - Our specific story's requirements, user story + statement, acceptance criteria - Technical requirements and constraints - Dependencies on other stories/epics - Source hints pointing to + original documents + Extract our story ({{epic_num}}-{{story_num}}) details: **STORY FOUNDATION:** - User story statement + (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story - + Business context and value - Success criteria + + Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}} + Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md **PREVIOUS STORY INTELLIGENCE:** - + Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their + patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established Extract + all learnings that could impact current story implementation + + + + + Get last 5 commit titles to understand recent work patterns + Analyze 1-5 most recent commits for relevance to current story: + - Files created/modified + - Code patterns and conventions used + - Library dependencies added/changed + - Architecture decisions implemented + - Testing approaches used + + Extract actionable insights for current story implementation + + + + + 🏗️ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow! **ARCHITECTURE DOCUMENT ANALYSIS:** Systematically + analyze architecture content for story-relevant requirements: + + + + Load complete {architecture_content} + + + Load architecture index and scan all architecture files + **CRITICAL ARCHITECTURE EXTRACTION:** For + each architecture section, determine if relevant to this story: - **Technical Stack:** Languages, frameworks, libraries with + versions - **Code Structure:** Folder organization, naming conventions, file patterns - **API Patterns:** Service structure, endpoint + patterns, data contracts - **Database Schemas:** Tables, relationships, constraints relevant to story - **Security Requirements:** + Authentication patterns, authorization rules - **Performance Requirements:** Caching strategies, optimization patterns - **Testing + Standards:** Testing frameworks, coverage expectations, test patterns - **Deployment Patterns:** Environment configurations, build + processes - **Integration Patterns:** External service integrations, data flows Extract any story-specific requirements that the + developer MUST follow + Identify any architectural decisions that override previous patterns + + + + 🌐 ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations! **WEB INTELLIGENCE:** Identify specific + technical areas that require latest version knowledge: + + + From architecture analysis, identify specific libraries, APIs, or + frameworks + For each critical technology, research latest stable version and key changes: + - Latest API documentation and breaking changes + - Security vulnerabilities or updates + - Performance improvements or deprecations + - Best practices for current version + + **EXTERNAL CONTEXT INCLUSION:** Include in story any critical latest information the developer needs: + - Specific library versions and why chosen + - API endpoints with parameters and authentication + - Recent security patches or considerations + - Performance optimization techniques + - Migration considerations if upgrading + + + + + 📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide! + + Initialize from template.md: + {default_output_file} + story_header + + + story_requirements + + + + developer_context_section **DEV AGENT GUARDRAILS:** + technical_requirements + architecture_compliance + library_framework_requirements + + file_structure_requirements + testing_requirements + + + + previous_story_intelligence + + + + + git_intelligence_summary + + + + + latest_tech_information + + + + project_context_reference + + + + story_completion_status + + + Set story Status to: "ready-for-dev" + Add completion note: "Ultimate + context engine analysis completed - comprehensive developer guide created" + + + + Validate the newly created story file {story_file} against {installed_path}/checklist.md and apply any required fixes before finalizing + Save story document unconditionally + + + + Update {{sprint_status}} + Load the FULL file and read all development_status entries + Find development_status key matching {{story_key}} + Verify current status is "backlog" (expected previous state) + Update development_status[{{story_key}}] = "ready-for-dev" + Update last_updated field to current date + Save file, preserving ALL comments and structure including STATUS DEFINITIONS + + + Report completion + **🎯 ULTIMATE BMad Method STORY CONTEXT CREATED, {user_name}!** + + **Story Details:** + - Story ID: {{story_id}} + - Story Key: {{story_key}} + - File: {{story_file}} + - Status: ready-for-dev + + **Next Steps:** + 1. Review the comprehensive story in {{story_file}} + 2. Run dev agents `dev-story` for optimized implementation + 3. Run `code-review` when complete (auto-marks done) + 4. Optional: If Test Architect module installed, run `/bmad:tea:automate` after `dev-story` to generate guardrail tests + + **The developer now has everything needed for flawless implementation!** + + + + diff --git a/src/bmm/workflows/4-implementation/bmad-dev-story/SKILL.md b/src/bmm/workflows/4-implementation/bmad-dev-story/SKILL.md new file mode 100644 index 000000000..c7217863d --- /dev/null +++ b/src/bmm/workflows/4-implementation/bmad-dev-story/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-dev-story +description: 'Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan"' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/bmm/workflows/4-implementation/bmad-dev-story/bmad-skill-manifest.yaml b/src/bmm/workflows/4-implementation/bmad-dev-story/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/bmm/workflows/4-implementation/bmad-dev-story/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/bmm/workflows/4-implementation/dev-story/checklist.md b/src/bmm/workflows/4-implementation/bmad-dev-story/checklist.md similarity index 100% rename from src/bmm/workflows/4-implementation/dev-story/checklist.md rename to src/bmm/workflows/4-implementation/bmad-dev-story/checklist.md diff --git a/src/bmm/workflows/4-implementation/dev-story/instructions.xml b/src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md similarity index 92% rename from src/bmm/workflows/4-implementation/dev-story/instructions.xml rename to src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md index 3c4989f39..1981276e2 100644 --- a/src/bmm/workflows/4-implementation/dev-story/instructions.xml +++ b/src/bmm/workflows/4-implementation/bmad-dev-story/workflow.md @@ -1,6 +1,45 @@ +# Dev Story Workflow + +**Goal:** Execute story implementation following a context filled story spec file. + +**Your Role:** Developer implementing the story. +- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} +- Generate all documents in {document_output_language} +- Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status +- Execute ALL steps in exact order; do NOT skip steps +- Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction. +- Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion. +- User skill level ({user_skill_level}) affects conversation style ONLY, not code updates. + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `user_name` +- `communication_language`, `document_output_language` +- `user_skill_level` +- `implementation_artifacts` +- `date` as system-generated current datetime + +### Paths + +- `validation` = `./checklist.md` +- `story_file` = `` (explicit story path; auto-discovered if empty) +- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` + +### Context + +- `project_context` = `**/project-context.md` (load if exists) + +--- + +## EXECUTION + - The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml - You MUST have already loaded and processed: {installed_path}/workflow.yaml Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, @@ -195,6 +234,7 @@ Update the story in the sprint status report to = "in-progress" + Update last_updated field to current date 🚀 Starting work on story {{story_key}} Status updated: ready-for-dev → in-progress @@ -348,6 +388,7 @@ Find development_status key matching {{story_key}} Verify current status is "in-progress" (expected previous state) Update development_status[{{story_key}}] = "review" + Update last_updated field to current date Save file, preserving ALL comments and structure including STATUS DEFINITIONS ✅ Story status updated to "review" in sprint-status.yaml diff --git a/src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml b/src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml new file mode 100644 index 000000000..6b1589a4a --- /dev/null +++ b/src/bmm/workflows/4-implementation/code-review/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-code-review +type: workflow +description: "Perform adversarial code review finding specific issues" diff --git a/src/bmm/workflows/4-implementation/code-review/discover-inputs.md b/src/bmm/workflows/4-implementation/code-review/discover-inputs.md new file mode 100644 index 000000000..2c313db3d --- /dev/null +++ b/src/bmm/workflows/4-implementation/code-review/discover-inputs.md @@ -0,0 +1,88 @@ +# Discover Inputs Protocol + +**Objective:** Intelligently load project files (whole or sharded) based on the workflow's Input Files configuration. + +**Prerequisite:** Only execute this protocol if the workflow defines an Input Files section. If no input file patterns are configured, skip this entirely. + +--- + +## Step 1: Parse Input File Patterns + +- Read the Input Files table from the workflow configuration. +- For each input group (prd, architecture, epics, ux, etc.), note the **load strategy** if specified. + +## Step 2: Load Files Using Smart Strategies + +For each pattern in the Input Files table, work through the following substeps in order: + +### 2a: Try Sharded Documents First + +If a sharded pattern exists for this input, determine the load strategy (defaults to **FULL_LOAD** if not specified), then apply the matching strategy: + +#### FULL_LOAD Strategy + +Load ALL files in the sharded directory. Use this for PRD, Architecture, UX, brownfield docs, or whenever the full picture is needed. + +1. Use the glob pattern to find ALL `.md` files (e.g., `{planning_artifacts}/*architecture*/*.md`). +2. Load EVERY matching file completely. +3. Concatenate content in logical order: `index.md` first if it exists, then alphabetical. +4. Store the combined result in a variable named `{pattern_name_content}` (e.g., `{architecture_content}`). + +#### SELECTIVE_LOAD Strategy + +Load a specific shard using a template variable. Example: used for epics with `{{epic_num}}`. + +1. Check for template variables in the sharded pattern (e.g., `{{epic_num}}`). +2. If the variable is undefined, ask the user for the value OR infer it from context. +3. Resolve the template to a specific file path. +4. Load that specific file. +5. Store in variable: `{pattern_name_content}`. + +#### INDEX_GUIDED Strategy + +Load index.md, analyze the structure and description of each doc in the index, then intelligently load relevant docs. + +**DO NOT BE LAZY** -- use best judgment to load documents that might have relevant information, even if there is only a 5% chance of relevance. + +1. Load `index.md` from the sharded directory. +2. Parse the table of contents, links, and section headers. +3. Analyze the workflow's purpose and objective. +4. Identify which linked/referenced documents are likely relevant. + - *Example:* If the workflow is about authentication and the index shows "Auth Overview", "Payment Setup", "Deployment" -- load the auth docs, consider deployment docs, skip payment. +5. Load all identified relevant documents. +6. Store combined content in variable: `{pattern_name_content}`. + +**When in doubt, LOAD IT** -- context is valuable, and being thorough is better than missing critical info. + +--- + +After applying the matching strategy, mark the pattern as **RESOLVED** and move to the next pattern. + +### 2b: Try Whole Document if No Sharded Found + +If no sharded matches were found OR no sharded pattern exists for this input: + +1. Attempt a glob match on the "whole" pattern (e.g., `{planning_artifacts}/*prd*.md`). +2. If matches are found, load ALL matching files completely (no offset/limit). +3. Store content in variable: `{pattern_name_content}` (e.g., `{prd_content}`). +4. Mark pattern as **RESOLVED** and move to the next pattern. + +### 2c: Handle Not Found + +If no matches were found for either sharded or whole patterns: + +1. Set `{pattern_name_content}` to empty string. +2. Note in session: "No {pattern_name} files found" -- this is not an error, just unavailable. Offer the user a chance to provide the file. + +## Step 3: Report Discovery Results + +List all loaded content variables with file counts. Example: + +``` +OK Loaded {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ... +OK Loaded {architecture_content} from 1 file: Architecture.md +OK Loaded {epics_content} from selective load: epics/epic-3.md +-- No ux_design files found +``` + +This gives the workflow transparency into what context is available. diff --git a/src/bmm/workflows/4-implementation/code-review/instructions.xml b/src/bmm/workflows/4-implementation/code-review/instructions.xml deleted file mode 100644 index e5649559d..000000000 --- a/src/bmm/workflows/4-implementation/code-review/instructions.xml +++ /dev/null @@ -1,227 +0,0 @@ - - The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml - You MUST have already loaded and processed: {installed_path}/workflow.yaml - Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} - Generate all documents in {document_output_language} - - 🔥 YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing! 🔥 - Your purpose: Validate story file claims against actual implementation - Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented? - Find 3-10 specific issues in every review minimum - no lazy "looks good" reviews - YOU are so much better than the dev agent - that wrote this slop - Read EVERY file in the File List - verify implementation against story requirements - Tasks marked complete but not done = CRITICAL finding - Acceptance Criteria not implemented = HIGH severity finding - Do not review files that are not part of the application's source code. Always exclude the _bmad/ and _bmad-output/ folders from the review. Always exclude IDE and CLI configuration folders like .cursor/ and .windsurf/ and .claude/ - - - - Use provided {{story_path}} or ask user which story file to review - Read COMPLETE story file - Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story - metadata - Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log - - - Check if git repository detected in current directory - - Run `git status --porcelain` to find uncommitted changes - Run `git diff --name-only` to see modified files - Run `git diff --cached --name-only` to see staged files - Compile list of actually changed files from git output - - - - Compare story's Dev Agent Record → File List with actual git changes - Note discrepancies: - - Files in git but not in story File List - - Files in story File List but no git changes - - Missing documentation of what was actually changed - - - - Load {project_context} for coding standards (if exists) - - - - Extract ALL Acceptance Criteria from story - Extract ALL Tasks/Subtasks with completion status ([x] vs [ ]) - From Dev Agent Record → File List, compile list of claimed changes - - Create review plan: - 1. **AC Validation**: Verify each AC is actually implemented - 2. **Task Audit**: Verify each [x] task is really done - 3. **Code Quality**: Security, performance, maintainability - 4. **Test Quality**: Real tests vs placeholder bullshit - - - - - VALIDATE EVERY CLAIM - Check git reality vs story claims - - - Review git vs story File List discrepancies: - 1. **Files changed but not in story File List** → MEDIUM finding (incomplete documentation) - 2. **Story lists files but no git changes** → HIGH finding (false claims) - 3. **Uncommitted changes not documented** → MEDIUM finding (transparency issue) - - - - Create comprehensive review file list from story File List and git changes - - - For EACH Acceptance Criterion: - 1. Read the AC requirement - 2. Search implementation files for evidence - 3. Determine: IMPLEMENTED, PARTIAL, or MISSING - 4. If MISSING/PARTIAL → HIGH SEVERITY finding - - - - For EACH task marked [x]: - 1. Read the task description - 2. Search files for evidence it was actually done - 3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding - 4. Record specific proof (file:line) - - - - For EACH file in comprehensive review list: - 1. **Security**: Look for injection risks, missing validation, auth issues - 2. **Performance**: N+1 queries, inefficient loops, missing caching - 3. **Error Handling**: Missing try/catch, poor error messages - 4. **Code Quality**: Complex functions, magic numbers, poor naming - 5. **Test Quality**: Are tests real assertions or placeholders? - - - - NOT LOOKING HARD ENOUGH - Find more problems! - Re-examine code for: - - Edge cases and null handling - - Architecture violations - - Documentation gaps - - Integration issues - - Dependency problems - - Git commit message quality (if applicable) - - Find at least 3 more specific, actionable issues - - - - - Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix) - Set {{fixed_count}} = 0 - Set {{action_count}} = 0 - - **🔥 CODE REVIEW FINDINGS, {user_name}!** - - **Story:** {{story_file}} - **Git vs Story Discrepancies:** {{git_discrepancy_count}} found - **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low - - ## 🔴 CRITICAL ISSUES - - Tasks marked [x] but not actually implemented - - Acceptance Criteria not implemented - - Story claims files changed but no git evidence - - Security vulnerabilities - - ## 🟡 MEDIUM ISSUES - - Files changed but not documented in story File List - - Uncommitted changes not tracked - - Performance problems - - Poor test coverage/quality - - Code maintainability issues - - ## 🟢 LOW ISSUES - - Code style improvements - - Documentation gaps - - Git commit message quality - - - What should I do with these issues? - - 1. **Fix them automatically** - I'll update the code and tests - 2. **Create action items** - Add to story Tasks/Subtasks for later - 3. **Show me details** - Deep dive into specific issues - - Choose [1], [2], or specify which issue to examine: - - - Fix all HIGH and MEDIUM issues in the code - Add/update tests as needed - Update File List in story if files changed - Update story Dev Agent Record with fixes applied - Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed - Set {{action_count}} = 0 - - - - Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks - For each issue: `- [ ] [AI-Review][Severity] Description [file:line]` - Set {{action_count}} = number of action items created - Set {{fixed_count}} = 0 - - - - Show detailed explanation with code examples - Return to fix decision - - - - - - - Set {{new_status}} = "done" - Update story Status field to "done" - - - Set {{new_status}} = "in-progress" - Update story Status field to "in-progress" - - Save story file - - - - Set {{current_sprint_status}} = "enabled" - - - Set {{current_sprint_status}} = "no-sprint-tracking" - - - - - Load the FULL file: {sprint_status} - Find development_status key matching {{story_key}} - - - Update development_status[{{story_key}}] = "done" - Save file, preserving ALL comments and structure - ✅ Sprint status synced: {{story_key}} → done - - - - Update development_status[{{story_key}}] = "in-progress" - Save file, preserving ALL comments and structure - 🔄 Sprint status synced: {{story_key}} → in-progress - - - - ⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml - - - - - ℹ️ Story status updated (no sprint tracking configured) - - - **✅ Review Complete!** - - **Story Status:** {{new_status}} - **Issues Fixed:** {{fixed_count}} - **Action Items Created:** {{action_count}} - - {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}} - - - - \ No newline at end of file diff --git a/src/bmm/workflows/4-implementation/code-review/workflow.md b/src/bmm/workflows/4-implementation/code-review/workflow.md new file mode 100644 index 000000000..1abb4d174 --- /dev/null +++ b/src/bmm/workflows/4-implementation/code-review/workflow.md @@ -0,0 +1,268 @@ +--- +name: code-review +description: 'Perform adversarial code review finding specific issues. Use when the user says "run code review" or "review this code"' +--- + +# Code Review Workflow + +**Goal:** Perform adversarial code review finding specific issues. + +**Your Role:** Adversarial Code Reviewer. +- YOU ARE AN ADVERSARIAL CODE REVIEWER - Find what's wrong or missing! +- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} +- Generate all documents in {document_output_language} +- Your purpose: Validate story file claims against actual implementation +- Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented? +- Be thorough and specific — find real issues, not manufactured ones. If the code is genuinely good after fixes, say so +- Read EVERY file in the File List - verify implementation against story requirements +- Tasks marked complete but not done = CRITICAL finding +- Acceptance Criteria not implemented = HIGH severity finding +- Do not review files that are not part of the application's source code. Always exclude the `_bmad/` and `_bmad-output/` folders from the review. Always exclude IDE and CLI configuration folders like `.cursor/` and `.windsurf/` and `.claude/` + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `user_name` +- `communication_language`, `document_output_language` +- `user_skill_level` +- `planning_artifacts`, `implementation_artifacts` +- `date` as system-generated current datetime + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/code-review` +- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml` +- `validation` = `{installed_path}/checklist.md` + +### Input Files + +| Input | Description | Path Pattern(s) | Load Strategy | +|-------|-------------|------------------|---------------| +| architecture | System architecture for review context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD | +| ux_design | UX design specification (if UI review) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | FULL_LOAD | +| epics | Epic containing story being reviewed | whole: `{planning_artifacts}/*epic*.md`, sharded_index: `{planning_artifacts}/*epic*/index.md`, sharded_single: `{planning_artifacts}/*epic*/epic-{{epic_num}}.md` | SELECTIVE_LOAD | + +### Context + +- `project_context` = `**/project-context.md` (load if exists) + +--- + +## EXECUTION + + + + + Use provided {{story_path}} or ask user which story file to review + Read COMPLETE story file + Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" → "1-2-user-authentication") or story + metadata + Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record → File List, Change Log + + + Check if git repository detected in current directory + + Run `git status --porcelain` to find uncommitted changes + Run `git diff --name-only` to see modified files + Run `git diff --cached --name-only` to see staged files + Compile list of actually changed files from git output + + + + Compare story's Dev Agent Record → File List with actual git changes + Note discrepancies: + - Files in git but not in story File List + - Files in story File List but no git changes + - Missing documentation of what was actually changed + + + Read fully and follow `{installed_path}/discover-inputs.md` to load all input files + Load {project_context} for coding standards (if exists) + + + + Extract ALL Acceptance Criteria from story + Extract ALL Tasks/Subtasks with completion status ([x] vs [ ]) + From Dev Agent Record → File List, compile list of claimed changes + + Create review plan: + 1. **AC Validation**: Verify each AC is actually implemented + 2. **Task Audit**: Verify each [x] task is really done + 3. **Code Quality**: Security, performance, maintainability + 4. **Test Quality**: Real tests vs placeholder bullshit + + + + + VALIDATE EVERY CLAIM - Check git reality vs story claims + + + Review git vs story File List discrepancies: + 1. **Files changed but not in story File List** → MEDIUM finding (incomplete documentation) + 2. **Story lists files but no git changes** → HIGH finding (false claims) + 3. **Uncommitted changes not documented** → MEDIUM finding (transparency issue) + + + + Create comprehensive review file list from story File List and git changes + + + For EACH Acceptance Criterion: + 1. Read the AC requirement + 2. Search implementation files for evidence + 3. Determine: IMPLEMENTED, PARTIAL, or MISSING + 4. If MISSING/PARTIAL → HIGH SEVERITY finding + + + + For EACH task marked [x]: + 1. Read the task description + 2. Search files for evidence it was actually done + 3. **CRITICAL**: If marked [x] but NOT DONE → CRITICAL finding + 4. Record specific proof (file:line) + + + + For EACH file in comprehensive review list: + 1. **Security**: Look for injection risks, missing validation, auth issues + 2. **Performance**: N+1 queries, inefficient loops, missing caching + 3. **Error Handling**: Missing try/catch, poor error messages + 4. **Code Quality**: Complex functions, magic numbers, poor naming + 5. **Test Quality**: Are tests real assertions or placeholders? + + + + Double-check by re-examining code for: + - Edge cases and null handling + - Architecture violations + - Integration issues + - Dependency problems + + If still no issues found after thorough re-examination, that is a valid outcome — report a clean review + + + + + Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix) + Set {{fixed_count}} = 0 + Set {{action_count}} = 0 + + **🔥 CODE REVIEW FINDINGS, {user_name}!** + + **Story:** {{story_file}} + **Git vs Story Discrepancies:** {{git_discrepancy_count}} found + **Issues Found:** {{high_count}} High, {{medium_count}} Medium, {{low_count}} Low + + ## 🔴 CRITICAL ISSUES + - Tasks marked [x] but not actually implemented + - Acceptance Criteria not implemented + - Story claims files changed but no git evidence + - Security vulnerabilities + + ## 🟡 MEDIUM ISSUES + - Files changed but not documented in story File List + - Uncommitted changes not tracked + - Performance problems + - Poor test coverage/quality + - Code maintainability issues + + ## 🟢 LOW ISSUES + - Code style improvements + - Documentation gaps + - Git commit message quality + + + What should I do with these issues? + + 1. **Fix them automatically** - I'll update the code and tests + 2. **Create action items** - Add to story Tasks/Subtasks for later + 3. **Show me details** - Deep dive into specific issues + + Choose [1], [2], or specify which issue to examine: + + + Fix all HIGH and MEDIUM issues in the code + Add/update tests as needed + Update File List in story if files changed + Update story Dev Agent Record with fixes applied + Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed + Set {{action_count}} = 0 + + + + Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks + For each issue: `- [ ] [AI-Review][Severity] Description [file:line]` + Set {{action_count}} = number of action items created + Set {{fixed_count}} = 0 + + + + Show detailed explanation with code examples + Return to fix decision + + + + + + + Set {{new_status}} = "done" + Update story Status field to "done" + + + Set {{new_status}} = "in-progress" + Update story Status field to "in-progress" + + Save story file + + + + Set {{current_sprint_status}} = "enabled" + + + Set {{current_sprint_status}} = "no-sprint-tracking" + + + + + Load the FULL file: {sprint_status} + Find development_status key matching {{story_key}} + + + Update development_status[{{story_key}}] = "done" + Update last_updated field to current date + Save file, preserving ALL comments and structure + ✅ Sprint status synced: {{story_key}} → done + + + + Update development_status[{{story_key}}] = "in-progress" + Update last_updated field to current date + Save file, preserving ALL comments and structure + 🔄 Sprint status synced: {{story_key}} → in-progress + + + + ⚠️ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml + + + + + ℹ️ Story status updated (no sprint tracking configured) + + + **✅ Review Complete!** + + **Story Status:** {{new_status}} + **Issues Fixed:** {{fixed_count}} + **Action Items Created:** {{action_count}} + + {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}} + + + + diff --git a/src/bmm/workflows/4-implementation/code-review/workflow.yaml b/src/bmm/workflows/4-implementation/code-review/workflow.yaml deleted file mode 100644 index c6edf8464..000000000 --- a/src/bmm/workflows/4-implementation/code-review/workflow.yaml +++ /dev/null @@ -1,44 +0,0 @@ -# Review Story Workflow -name: code-review -description: "Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts `looks good` - must find minimum issues and can auto-fix with user approval." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -user_skill_level: "{config_source}:user_skill_level" -document_output_language: "{config_source}:document_output_language" -date: system-generated -planning_artifacts: "{config_source}:planning_artifacts" -implementation_artifacts: "{config_source}:implementation_artifacts" -sprint_status: "{implementation_artifacts}/sprint-status.yaml" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review" -instructions: "{installed_path}/instructions.xml" -validation: "{installed_path}/checklist.md" -template: false - -project_context: "**/project-context.md" - -# Smart input file references - handles both whole docs and sharded docs -# Priority: Whole document first, then sharded version -# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review -input_file_patterns: - architecture: - description: "System architecture for review context" - whole: "{planning_artifacts}/*architecture*.md" - sharded: "{planning_artifacts}/*architecture*/*.md" - load_strategy: "FULL_LOAD" - ux_design: - description: "UX design specification (if UI review)" - whole: "{planning_artifacts}/*ux*.md" - sharded: "{planning_artifacts}/*ux*/*.md" - load_strategy: "FULL_LOAD" - epics: - description: "Epic containing story being reviewed" - whole: "{planning_artifacts}/*epic*.md" - sharded_index: "{planning_artifacts}/*epic*/index.md" - sharded_single: "{planning_artifacts}/*epic*/epic-{{epic_num}}.md" - load_strategy: "SELECTIVE_LOAD" diff --git a/src/bmm/workflows/4-implementation/correct-course/bmad-skill-manifest.yaml b/src/bmm/workflows/4-implementation/correct-course/bmad-skill-manifest.yaml new file mode 100644 index 000000000..6a95bd4a7 --- /dev/null +++ b/src/bmm/workflows/4-implementation/correct-course/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-correct-course +type: workflow +description: "Manage significant changes during sprint execution" diff --git a/src/bmm/workflows/4-implementation/correct-course/checklist.md b/src/bmm/workflows/4-implementation/correct-course/checklist.md index f13ab9be0..1e630ccbb 100644 --- a/src/bmm/workflows/4-implementation/correct-course/checklist.md +++ b/src/bmm/workflows/4-implementation/correct-course/checklist.md @@ -1,6 +1,6 @@ # Change Navigation Checklist -This checklist is executed as part of: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml +This checklist is executed as part of: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.md Work through each section systematically with the user, recording findings and impacts diff --git a/src/bmm/workflows/4-implementation/correct-course/instructions.md b/src/bmm/workflows/4-implementation/correct-course/workflow.md similarity index 64% rename from src/bmm/workflows/4-implementation/correct-course/instructions.md rename to src/bmm/workflows/4-implementation/correct-course/workflow.md index bbe2c21e0..e95ec8432 100644 --- a/src/bmm/workflows/4-implementation/correct-course/instructions.md +++ b/src/bmm/workflows/4-implementation/correct-course/workflow.md @@ -1,11 +1,83 @@ -# Correct Course - Sprint Change Management Instructions +--- +name: correct-course +description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"' +--- -The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml -Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} -Generate all documents in {document_output_language} +# Correct Course - Sprint Change Management Workflow -DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level ({user_skill_level}) affects conversation style ONLY, not document updates. +**Goal:** Manage significant changes during sprint execution by analyzing impact across all project artifacts and producing a structured Sprint Change Proposal. + +**Your Role:** You are a Scrum Master navigating change management. Analyze the triggering issue, assess impact across PRD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff. + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `user_name` +- `communication_language`, `document_output_language` +- `user_skill_level` +- `implementation_artifacts` +- `planning_artifacts` +- `project_knowledge` +- `date` as system-generated current datetime +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Language MUST be tailored to `{user_skill_level}` +- Generate all documents in `{document_output_language}` +- DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level (`{user_skill_level}`) affects conversation style ONLY, not document updates. + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/correct-course` +- `checklist` = `{installed_path}/checklist.md` +- `default_output_file` = `{planning_artifacts}/sprint-change-proposal-{date}.md` + +### Input Files + +| Input | Path | Load Strategy | +|-------|------|---------------| +| PRD | `{planning_artifacts}/*prd*.md` (whole) or `{planning_artifacts}/*prd*/*.md` (sharded) | FULL_LOAD | +| Epics | `{planning_artifacts}/*epic*.md` (whole) or `{planning_artifacts}/*epic*/*.md` (sharded) | FULL_LOAD | +| Architecture | `{planning_artifacts}/*architecture*.md` (whole) or `{planning_artifacts}/*architecture*/*.md` (sharded) | FULL_LOAD | +| UX Design | `{planning_artifacts}/*ux*.md` (whole) or `{planning_artifacts}/*ux*/*.md` (sharded) | FULL_LOAD | +| Tech Spec | `{planning_artifacts}/*tech-spec*.md` (whole) | FULL_LOAD | +| Document Project | `{project_knowledge}/index.md` (sharded) | INDEX_GUIDED | + +### Context + +- `project_context` = `**/project-context.md` (load if exists) + +--- + +## EXECUTION + +### Document Discovery - Loading Project Artifacts + +**Strategy**: Course correction needs broad project context to assess change impact accurately. Load all available planning artifacts. + +**Discovery Process for FULL_LOAD documents (PRD, Epics, Architecture, UX Design, Tech Spec):** + +1. **Search for whole document first** - Look for files matching the whole-document pattern (e.g., `*prd*.md`, `*epic*.md`, `*architecture*.md`, `*ux*.md`, `*tech-spec*.md`) +2. **Check for sharded version** - If whole document not found, look for a directory with `index.md` (e.g., `prd/index.md`, `epics/index.md`) +3. **If sharded version found**: + - Read `index.md` to understand the document structure + - Read ALL section files listed in the index + - Process the combined content as a single document +4. **Priority**: If both whole and sharded versions exist, use the whole document + +**Discovery Process for INDEX_GUIDED documents (Document Project):** + +1. **Search for index file** - Look for `{project_knowledge}/index.md` +2. **If found**: Read the index to understand available documentation sections +3. **Selectively load sections** based on relevance to the change being analyzed — do NOT load everything, only sections that relate to the impacted areas +4. **This document is optional** — skip if `{project_knowledge}` does not exist (greenfield projects) + +**Fuzzy matching**: Be flexible with document names — users may use variations like `prd.md`, `bmm-prd.md`, `product-requirements.md`, etc. + +**Missing documents**: Not all documents may exist. PRD and Epics are essential; Architecture, UX Design, Tech Spec, and Document Project are loaded if available. HALT if PRD or Epics cannot be found. @@ -28,11 +100,6 @@ HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible." - - - After discovery, these content variables are available: {prd_content}, {epics_content}, {architecture_content}, {ux_design_content}, {tech_spec_content}, {document_project_content} - - Read fully and follow the systematic analysis from: {checklist} Work through each checklist section interactively with the user @@ -200,7 +267,7 @@ - Specific edit proposals with before/after - Implementation handoff plan -Report workflow completion to user with personalized message: "✅ Correct Course workflow complete, {user_name}!" +Report workflow completion to user with personalized message: "Correct Course workflow complete, {user_name}!" Remind user of success criteria and next steps for implementation team diff --git a/src/bmm/workflows/4-implementation/correct-course/workflow.yaml b/src/bmm/workflows/4-implementation/correct-course/workflow.yaml deleted file mode 100644 index 6eb4b7f03..000000000 --- a/src/bmm/workflows/4-implementation/correct-course/workflow.yaml +++ /dev/null @@ -1,54 +0,0 @@ -# Correct Course - Sprint Change Management Workflow -name: "correct-course" -description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation" -author: "BMad Method" - -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -user_skill_level: "{config_source}:user_skill_level" -document_output_language: "{config_source}:document_output_language" -date: system-generated -implementation_artifacts: "{config_source}:implementation_artifacts" -planning_artifacts: "{config_source}:planning_artifacts" -project_knowledge: "{config_source}:project_knowledge" -project_context: "**/project-context.md" - -# Smart input file references - handles both whole docs and sharded docs -# Priority: Whole document first, then sharded version -# Strategy: Load project context for impact analysis -input_file_patterns: - prd: - description: "Product requirements for impact analysis" - whole: "{planning_artifacts}/*prd*.md" - sharded: "{planning_artifacts}/*prd*/*.md" - load_strategy: "FULL_LOAD" - epics: - description: "All epics to analyze change impact" - whole: "{planning_artifacts}/*epic*.md" - sharded: "{planning_artifacts}/*epic*/*.md" - load_strategy: "FULL_LOAD" - architecture: - description: "System architecture and decisions" - whole: "{planning_artifacts}/*architecture*.md" - sharded: "{planning_artifacts}/*architecture*/*.md" - load_strategy: "FULL_LOAD" - ux_design: - description: "UX design specification (if UI impacts)" - whole: "{planning_artifacts}/*ux*.md" - sharded: "{planning_artifacts}/*ux*/*.md" - load_strategy: "FULL_LOAD" - tech_spec: - description: "Technical specification" - whole: "{planning_artifacts}/*tech-spec*.md" - load_strategy: "FULL_LOAD" - document_project: - description: "Brownfield project documentation (optional)" - sharded: "{project_knowledge}/index.md" - load_strategy: "INDEX_GUIDED" - -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/correct-course" -template: false -instructions: "{installed_path}/instructions.md" -checklist: "{installed_path}/checklist.md" -default_output_file: "{planning_artifacts}/sprint-change-proposal-{date}.md" diff --git a/src/bmm/workflows/4-implementation/create-story/instructions.xml b/src/bmm/workflows/4-implementation/create-story/instructions.xml deleted file mode 100644 index f9433371f..000000000 --- a/src/bmm/workflows/4-implementation/create-story/instructions.xml +++ /dev/null @@ -1,346 +0,0 @@ - - The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml - You MUST have already loaded and processed: {installed_path}/workflow.yaml - Communicate all responses in {communication_language} and generate all documents in {document_output_language} - - 🔥 CRITICAL MISSION: You are creating the ULTIMATE story context engine that prevents LLM developer mistakes, omissions or - disasters! 🔥 - Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent - EVERYTHING needed for flawless implementation - COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX, - vague implementations, lying about completion, not learning from past work - 🚨 EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim! - This is the most important function in the entire development process! - 🔬 UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly - analyze different artifacts simultaneously and thoroughly - ❓ SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is - written - 🎯 ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents - - - - Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth" - Set {{epic_num}}, {{story_num}}, {{story_key}} from user input - GOTO step 2a - - - Check if {{sprint_status}} file exists for auto discover - - 🚫 No sprint status file found and no story specified - - **Required Options:** - 1. Run `sprint-planning` to initialize sprint tracking (recommended) - 2. Provide specific epic-story number to create (e.g., "1-2-user-auth") - 3. Provide path to story documents if sprint status doesn't exist yet - - Choose option [1], provide epic-story number, path to story docs, or [q] to quit: - - - HALT - No work needed - - - - Run sprint-planning workflow first to create sprint-status.yaml - HALT - User needs to run sprint-planning - - - - Parse user input: extract epic_num, story_num, story_title - Set {{epic_num}}, {{story_num}}, {{story_key}} from user input - GOTO step 2a - - - - Use user-provided path for story documents - GOTO step 2a - - - - - - MUST read COMPLETE {sprint_status} file from start to end to preserve order - Load the FULL file: {{sprint_status}} - Read ALL lines from beginning to end - do not skip any content - Parse the development_status section completely - - Find the FIRST story (by reading in order from top to bottom) where: - - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - - Status value equals "backlog" - - - - 📋 No backlog stories found in sprint-status.yaml - - All stories are either already created, in progress, or done. - - **Options:** - 1. Run sprint-planning to refresh story tracking - 2. Load PM agent and run correct-course to add more stories - 3. Check if current sprint is complete and run retrospective - - HALT - - - Extract from found story key (e.g., "1-2-user-authentication"): - - epic_num: first number before dash (e.g., "1") - - story_num: second number after first dash (e.g., "2") - - story_title: remainder after second dash (e.g., "user-authentication") - - Set {{story_id}} = "{{epic_num}}.{{story_num}}" - Store story_key for later use (e.g., "1-2-user-authentication") - - - Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern - - Load {{sprint_status}} and check epic-{{epic_num}} status - If epic status is "backlog" → update to "in-progress" - If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility) - If epic status is "in-progress" → no change needed - - 🚫 ERROR: Cannot create story in completed epic - Epic {{epic_num}} is marked as 'done'. All stories are complete. - If you need to add more work, either: - 1. Manually change epic status back to 'in-progress' in sprint-status.yaml - 2. Create a new epic for additional work - HALT - Cannot proceed - - - 🚫 ERROR: Invalid epic status '{{epic_status}}' - Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done - Please fix sprint-status.yaml manually or run sprint-planning to regenerate - HALT - Cannot proceed - - 📊 Epic {{epic_num}} status updated to in-progress - - - GOTO step 2a - - Load the FULL file: {{sprint_status}} - Read ALL lines from beginning to end - do not skip any content - Parse the development_status section completely - - Find the FIRST story (by reading in order from top to bottom) where: - - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - - Status value equals "backlog" - - - - 📋 No backlog stories found in sprint-status.yaml - - All stories are either already created, in progress, or done. - - **Options:** - 1. Run sprint-planning to refresh story tracking - 2. Load PM agent and run correct-course to add more stories - 3. Check if current sprint is complete and run retrospective - - HALT - - - Extract from found story key (e.g., "1-2-user-authentication"): - - epic_num: first number before dash (e.g., "1") - - story_num: second number after first dash (e.g., "2") - - story_title: remainder after second dash (e.g., "user-authentication") - - Set {{story_id}} = "{{epic_num}}.{{story_num}}" - Store story_key for later use (e.g., "1-2-user-authentication") - - - Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern - - Load {{sprint_status}} and check epic-{{epic_num}} status - If epic status is "backlog" → update to "in-progress" - If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility) - If epic status is "in-progress" → no change needed - - 🚫 ERROR: Cannot create story in completed epic - Epic {{epic_num}} is marked as 'done'. All stories are complete. - If you need to add more work, either: - 1. Manually change epic status back to 'in-progress' in sprint-status.yaml - 2. Create a new epic for additional work - HALT - Cannot proceed - - - 🚫 ERROR: Invalid epic status '{{epic_status}}' - Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done - Please fix sprint-status.yaml manually or run sprint-planning to regenerate - HALT - Cannot proceed - - 📊 Epic {{epic_num}} status updated to in-progress - - - GOTO step 2a - - - - 🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer fuckups! - - - - Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, - {project_context} - - - From {epics_content}, extract Epic {{epic_num}} complete context: **EPIC ANALYSIS:** - Epic - objectives and business value - ALL stories in this epic for cross-story context - Our specific story's requirements, user story - statement, acceptance criteria - Technical requirements and constraints - Dependencies on other stories/epics - Source hints pointing to - original documents - Extract our story ({{epic_num}}-{{story_num}}) details: **STORY FOUNDATION:** - User story statement - (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story - - Business context and value - Success criteria - - Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}} - Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md **PREVIOUS STORY INTELLIGENCE:** - - Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their - patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established Extract - all learnings that could impact current story implementation - - - - - Get last 5 commit titles to understand recent work patterns - Analyze 1-5 most recent commits for relevance to current story: - - Files created/modified - - Code patterns and conventions used - - Library dependencies added/changed - - Architecture decisions implemented - - Testing approaches used - - Extract actionable insights for current story implementation - - - - - 🏗️ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow! **ARCHITECTURE DOCUMENT ANALYSIS:** Systematically - analyze architecture content for story-relevant requirements: - - - - Load complete {architecture_content} - - - Load architecture index and scan all architecture files - **CRITICAL ARCHITECTURE EXTRACTION:** For - each architecture section, determine if relevant to this story: - **Technical Stack:** Languages, frameworks, libraries with - versions - **Code Structure:** Folder organization, naming conventions, file patterns - **API Patterns:** Service structure, endpoint - patterns, data contracts - **Database Schemas:** Tables, relationships, constraints relevant to story - **Security Requirements:** - Authentication patterns, authorization rules - **Performance Requirements:** Caching strategies, optimization patterns - **Testing - Standards:** Testing frameworks, coverage expectations, test patterns - **Deployment Patterns:** Environment configurations, build - processes - **Integration Patterns:** External service integrations, data flows Extract any story-specific requirements that the - developer MUST follow - Identify any architectural decisions that override previous patterns - - - - 🌐 ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations! **WEB INTELLIGENCE:** Identify specific - technical areas that require latest version knowledge: - - - From architecture analysis, identify specific libraries, APIs, or - frameworks - For each critical technology, research latest stable version and key changes: - - Latest API documentation and breaking changes - - Security vulnerabilities or updates - - Performance improvements or deprecations - - Best practices for current version - - **EXTERNAL CONTEXT INCLUSION:** Include in story any critical latest information the developer needs: - - Specific library versions and why chosen - - API endpoints with parameters and authentication - - Recent security patches or considerations - - Performance optimization techniques - - Migration considerations if upgrading - - - - - 📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide! - - Initialize from template.md: - {default_output_file} - story_header - - - story_requirements - - - - developer_context_section **DEV AGENT GUARDRAILS:** - technical_requirements - architecture_compliance - library_framework_requirements - - file_structure_requirements - testing_requirements - - - - previous_story_intelligence - - - - - git_intelligence_summary - - - - - latest_tech_information - - - - project_context_reference - - - - story_completion_status - - - Set story Status to: "ready-for-dev" - Add completion note: "Ultimate - context engine analysis completed - comprehensive developer guide created" - - - - Validate against checklist at {installed_path}/checklist.md using _bmad/core/tasks/validate-workflow.xml - Save story document unconditionally - - - - Update {{sprint_status}} - Load the FULL file and read all development_status entries - Find development_status key matching {{story_key}} - Verify current status is "backlog" (expected previous state) - Update development_status[{{story_key}}] = "ready-for-dev" - Save file, preserving ALL comments and structure including STATUS DEFINITIONS - - - Report completion - **🎯 ULTIMATE BMad Method STORY CONTEXT CREATED, {user_name}!** - - **Story Details:** - - Story ID: {{story_id}} - - Story Key: {{story_key}} - - File: {{story_file}} - - Status: ready-for-dev - - **Next Steps:** - 1. Review the comprehensive story in {{story_file}} - 2. Run dev agents `dev-story` for optimized implementation - 3. Run `code-review` when complete (auto-marks done) - 4. Optional: If Test Architect module installed, run `/bmad:tea:automate` after `dev-story` to generate guardrail tests - - **The developer now has everything needed for flawless implementation!** - - - - diff --git a/src/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/bmm/workflows/4-implementation/create-story/workflow.yaml deleted file mode 100644 index 991f78c2e..000000000 --- a/src/bmm/workflows/4-implementation/create-story/workflow.yaml +++ /dev/null @@ -1,53 +0,0 @@ -name: create-story -description: "Create the next user story from epics+stories with enhanced context analysis and direct ready-for-dev marking" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -document_output_language: "{config_source}:document_output_language" -user_skill_level: "{config_source}:user_skill_level" -date: system-generated -planning_artifacts: "{config_source}:planning_artifacts" -implementation_artifacts: "{config_source}:implementation_artifacts" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story" -template: "{installed_path}/template.md" -instructions: "{installed_path}/instructions.xml" -validation: "{installed_path}/checklist.md" - -# Variables and inputs -sprint_status: "{implementation_artifacts}/sprint-status.yaml" # Primary source for story tracking -epics_file: "{planning_artifacts}/epics.md" # Enhanced epics+stories with BDD and source hints -prd_file: "{planning_artifacts}/prd.md" # Fallback for requirements (if not in epics file) -architecture_file: "{planning_artifacts}/architecture.md" # Fallback for constraints (if not in epics file) -ux_file: "{planning_artifacts}/*ux*.md" # Fallback for UX requirements (if not in epics file) -story_title: "" # Will be elicited if not derivable -project_context: "**/project-context.md" -default_output_file: "{implementation_artifacts}/{{story_key}}.md" - -# Smart input file references - Simplified for enhanced approach -# The epics+stories file should contain everything needed with source hints -input_file_patterns: - prd: - description: "PRD (fallback - epics file should have most content)" - whole: "{planning_artifacts}/*prd*.md" - sharded: "{planning_artifacts}/*prd*/*.md" - load_strategy: "SELECTIVE_LOAD" # Only load if needed - architecture: - description: "Architecture (fallback - epics file should have relevant sections)" - whole: "{planning_artifacts}/*architecture*.md" - sharded: "{planning_artifacts}/*architecture*/*.md" - load_strategy: "SELECTIVE_LOAD" # Only load if needed - ux: - description: "UX design (fallback - epics file should have relevant sections)" - whole: "{planning_artifacts}/*ux*.md" - sharded: "{planning_artifacts}/*ux*/*.md" - load_strategy: "SELECTIVE_LOAD" # Only load if needed - epics: - description: "Enhanced epics+stories file with BDD and source hints" - whole: "{planning_artifacts}/*epic*.md" - sharded: "{planning_artifacts}/*epic*/*.md" - load_strategy: "SELECTIVE_LOAD" # Only load needed epic diff --git a/src/bmm/workflows/4-implementation/dev-story/workflow.yaml b/src/bmm/workflows/4-implementation/dev-story/workflow.yaml deleted file mode 100644 index c8a85a079..000000000 --- a/src/bmm/workflows/4-implementation/dev-story/workflow.yaml +++ /dev/null @@ -1,21 +0,0 @@ -name: dev-story -description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -user_skill_level: "{config_source}:user_skill_level" -document_output_language: "{config_source}:document_output_language" -date: system-generated - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/dev-story" -instructions: "{installed_path}/instructions.xml" -validation: "{installed_path}/checklist.md" - -story_file: "" # Explicit story path; auto-discovered if empty -implementation_artifacts: "{config_source}:implementation_artifacts" -sprint_status: "{implementation_artifacts}/sprint-status.yaml" -project_context: "**/project-context.md" diff --git a/src/bmm/workflows/4-implementation/retrospective/bmad-skill-manifest.yaml b/src/bmm/workflows/4-implementation/retrospective/bmad-skill-manifest.yaml new file mode 100644 index 000000000..51a5648ef --- /dev/null +++ b/src/bmm/workflows/4-implementation/retrospective/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-retrospective +type: workflow +description: "Post-epic review to extract lessons and assess success" diff --git a/src/bmm/workflows/4-implementation/retrospective/instructions.md b/src/bmm/workflows/4-implementation/retrospective/workflow.md similarity index 94% rename from src/bmm/workflows/4-implementation/retrospective/instructions.md rename to src/bmm/workflows/4-implementation/retrospective/workflow.md index 018ef6ee3..cbc502d8b 100644 --- a/src/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/bmm/workflows/4-implementation/retrospective/workflow.md @@ -1,31 +1,71 @@ -# Retrospective - Epic Completion Review Instructions +--- +name: retrospective +description: 'Post-epic review to extract lessons and assess success. Use when the user says "run a retrospective" or "lets retro the epic [epic]"' +--- -The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml -Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} -Generate all documents in {document_output_language} -⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever. +# Retrospective Workflow - - DOCUMENT OUTPUT: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content. +**Goal:** Post-epic review to extract lessons and assess success. -FACILITATION NOTES: +**Your Role:** Scrum Master facilitating retrospective. +- No time estimates — NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed. +- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} +- Generate all documents in {document_output_language} +- Document output: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content. +- Facilitation notes: + - Psychological safety is paramount - NO BLAME + - Focus on systems, processes, and learning + - Everyone contributes with specific examples preferred + - Action items must be achievable with clear ownership + - Two-part format: (1) Epic Review + (2) Next Epic Preparation +- Party mode protocol: + - ALL agent dialogue MUST use format: "Name (Role): dialogue" + - Example: Bob (Scrum Master): "Let's begin..." + - Example: {user_name} (Project Lead): [User responds] + - Create natural back-and-forth with user actively participating + - Show disagreements, diverse perspectives, authentic team dynamics -- Scrum Master facilitates this retrospective -- Psychological safety is paramount - NO BLAME -- Focus on systems, processes, and learning -- Everyone contributes with specific examples preferred -- Action items must be achievable with clear ownership -- Two-part format: (1) Epic Review + (2) Next Epic Preparation +--- -PARTY MODE PROTOCOL: +## INITIALIZATION -- ALL agent dialogue MUST use format: "Name (Role): dialogue" -- Example: Bob (Scrum Master): "Let's begin..." -- Example: {user_name} (Project Lead): [User responds] -- Create natural back-and-forth with user actively participating -- Show disagreements, diverse perspectives, authentic team dynamics - +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `user_name` +- `communication_language`, `document_output_language` +- `user_skill_level` +- `planning_artifacts`, `implementation_artifacts` +- `date` as system-generated current datetime +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/retrospective` +- `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml` + +### Input Files + +| Input | Description | Path Pattern(s) | Load Strategy | +|-------|-------------|------------------|---------------| +| epics | The completed epic for retrospective | whole: `{planning_artifacts}/*epic*.md`, sharded_index: `{planning_artifacts}/*epic*/index.md`, sharded_single: `{planning_artifacts}/*epic*/epic-{{epic_num}}.md` | SELECTIVE_LOAD | +| previous_retrospective | Previous epic's retrospective (optional) | `{implementation_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md` | SELECTIVE_LOAD | +| architecture | System architecture for context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD | +| prd | Product requirements for context | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | FULL_LOAD | +| document_project | Brownfield project documentation (optional) | sharded: `{planning_artifacts}/*.md` | INDEX_GUIDED | + +### Required Inputs + +- `agent_manifest` = `{project-root}/_bmad/_config/agent-manifest.csv` + +### Context + +- `project_context` = `**/project-context.md` (load if exists) + +--- + +## EXECUTION @@ -159,7 +199,7 @@ Bob (Scrum Master): "Perfect. Epic {{epic_number}} is complete and ready for ret - + Load input files according to the Input Files table in INITIALIZATION. For SELECTIVE_LOAD inputs, load only the epic matching {{epic_number}}. For FULL_LOAD inputs, load the complete document. For INDEX_GUIDED inputs, check the index first and load relevant sections. After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content} After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content} @@ -1336,6 +1376,7 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!" Find development_status key "epic-{{epic_number}}-retrospective" Verify current status (typically "optional" or "pending") Update development_status["epic-{{epic_number}}-retrospective"] = "done" +Update last_updated field to current date Save file, preserving ALL comments and structure including STATUS DEFINITIONS diff --git a/src/bmm/workflows/4-implementation/retrospective/workflow.yaml b/src/bmm/workflows/4-implementation/retrospective/workflow.yaml deleted file mode 100644 index 773c7f2d6..000000000 --- a/src/bmm/workflows/4-implementation/retrospective/workflow.yaml +++ /dev/null @@ -1,53 +0,0 @@ -# Retrospective - Epic Completion Review Workflow -name: "retrospective" -description: "Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic" -author: "BMad" - -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -user_skill_level: "{config_source}:user_skill_level" -document_output_language: "{config_source}:document_output_language" -date: system-generated -planning_artifacts: "{config_source}:planning_artifacts" -implementation_artifacts: "{config_source}:implementation_artifacts" -project_context: "**/project-context.md" - -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective" -template: false -instructions: "{installed_path}/instructions.md" - -required_inputs: - - agent_manifest: "{project-root}/_bmad/_config/agent-manifest.csv" - -# Smart input file references - handles both whole docs and sharded docs -# Priority: Whole document first, then sharded version -# Strategy: SELECTIVE LOAD - only load the completed epic and relevant retrospectives -input_file_patterns: - epics: - description: "The completed epic for retrospective" - whole: "{planning_artifacts}/*epic*.md" - sharded_index: "{planning_artifacts}/*epic*/index.md" - sharded_single: "{planning_artifacts}/*epic*/epic-{{epic_num}}.md" - load_strategy: "SELECTIVE_LOAD" - previous_retrospective: - description: "Previous epic's retrospective (optional)" - pattern: "{implementation_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md" - load_strategy: "SELECTIVE_LOAD" - architecture: - description: "System architecture for context" - whole: "{planning_artifacts}/*architecture*.md" - sharded: "{planning_artifacts}/*architecture*/*.md" - load_strategy: "FULL_LOAD" - prd: - description: "Product requirements for context" - whole: "{planning_artifacts}/*prd*.md" - sharded: "{planning_artifacts}/*prd*/*.md" - load_strategy: "FULL_LOAD" - document_project: - description: "Brownfield project documentation (optional)" - sharded: "{planning_artifacts}/*.md" - load_strategy: "INDEX_GUIDED" - -# Required files -sprint_status_file: "{implementation_artifacts}/sprint-status.yaml" diff --git a/src/bmm/workflows/4-implementation/sprint-planning/bmad-skill-manifest.yaml b/src/bmm/workflows/4-implementation/sprint-planning/bmad-skill-manifest.yaml new file mode 100644 index 000000000..2c02512ee --- /dev/null +++ b/src/bmm/workflows/4-implementation/sprint-planning/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-sprint-planning +type: workflow +description: "Generate sprint status tracking from epics" diff --git a/src/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml b/src/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml index 80d404310..6725b206c 100644 --- a/src/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml +++ b/src/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml @@ -35,6 +35,7 @@ # EXAMPLE STRUCTURE (your actual epics/stories will replace these): generated: 05-06-2-2025 21:30 +last_updated: 05-06-2-2025 21:30 project: My Awesome Project project_key: NOKEY tracking_system: file-system diff --git a/src/bmm/workflows/4-implementation/sprint-planning/instructions.md b/src/bmm/workflows/4-implementation/sprint-planning/workflow.md similarity index 79% rename from src/bmm/workflows/4-implementation/sprint-planning/instructions.md rename to src/bmm/workflows/4-implementation/sprint-planning/workflow.md index 316d2fec3..aba449c01 100644 --- a/src/bmm/workflows/4-implementation/sprint-planning/instructions.md +++ b/src/bmm/workflows/4-implementation/sprint-planning/workflow.md @@ -1,9 +1,57 @@ -# Sprint Planning - Sprint Status Generator +--- +name: sprint-planning +description: 'Generate sprint status tracking from epics. Use when the user says "run sprint planning" or "generate sprint plan"' +--- -The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml +# Sprint Planning Workflow -## 📚 Document Discovery - Full Epic Loading +**Goal:** Generate sprint status tracking from epics, detecting current story statuses and building a complete sprint-status.yaml file. + +**Your Role:** You are a Scrum Master generating and maintaining sprint tracking. Parse epic files, detect story statuses, and produce a structured sprint-status.yaml. + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `user_name` +- `communication_language`, `document_output_language` +- `implementation_artifacts` +- `planning_artifacts` +- `date` as system-generated current datetime +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning` +- `template` = `{installed_path}/sprint-status-template.yaml` +- `checklist` = `{installed_path}/checklist.md` +- `tracking_system` = `file-system` +- `project_key` = `NOKEY` +- `story_location` = `{implementation_artifacts}` +- `story_location_absolute` = `{implementation_artifacts}` +- `epics_location` = `{planning_artifacts}` +- `epics_pattern` = `*epic*.md` +- `status_file` = `{implementation_artifacts}/sprint-status.yaml` + +### Input Files + +| Input | Path | Load Strategy | +|-------|------|---------------| +| Epics | `{planning_artifacts}/*epic*.md` (whole) or `{planning_artifacts}/*epic*/*.md` (sharded) | FULL_LOAD | + +### Context + +- `project_context` = `**/project-context.md` (load if exists) + +--- + +## EXECUTION + +### Document Discovery - Full Epic Loading **Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking. @@ -44,11 +92,6 @@ Build complete inventory of all epics and stories from all epic files - - - After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy) - - For each epic found, create entries in this order: @@ -95,6 +138,7 @@ development_status: ```yaml # generated: {date} +# last_updated: {date} # project: {project_name} # project_key: {project_key} # tracking_system: {tracking_system} @@ -130,6 +174,7 @@ development_status: # - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended) generated: { date } +last_updated: { date } project: { project_name } project_key: { project_key } tracking_system: { tracking_system } @@ -168,7 +213,7 @@ development_status: - **File Location:** {status_file} - **Total Epics:** {{epic_count}} - **Total Stories:** {{story_count}} -- **Epics In Progress:** {{epics_in_progress_count}} +- **Epics In Progress:** {{in_progress_count}} - **Stories Completed:** {{done_count}} **Next Steps:** diff --git a/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml b/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml deleted file mode 100644 index 6c5d22d64..000000000 --- a/src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml +++ /dev/null @@ -1,47 +0,0 @@ -name: sprint-planning -description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -date: system-generated -implementation_artifacts: "{config_source}:implementation_artifacts" -planning_artifacts: "{config_source}:planning_artifacts" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning" -instructions: "{installed_path}/instructions.md" -template: "{installed_path}/sprint-status-template.yaml" -validation: "{installed_path}/checklist.md" - -# Variables and inputs -project_context: "**/project-context.md" -project_name: "{config_source}:project_name" - -# Tracking system configuration -tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello -project_key: "NOKEY" # Placeholder for tracker integrations; file-system uses a no-op key -story_location: "{implementation_artifacts}" # Relative path for file-system, Future will support URL for Jira/Linear/Trello -story_location_absolute: "{implementation_artifacts}" # Absolute path for file operations - -# Source files (file-system only) -epics_location: "{planning_artifacts}" # Directory containing epic*.md files -epics_pattern: "epic*.md" # Pattern to find epic files - -# Output configuration -status_file: "{implementation_artifacts}/sprint-status.yaml" - -# Smart input file references - handles both whole docs and sharded docs -# Priority: Whole document first, then sharded version -# Strategy: FULL LOAD - sprint planning needs ALL epics to build complete status -input_file_patterns: - epics: - description: "All epics with user stories" - whole: "{planning_artifacts}/*epic*.md" - sharded: "{planning_artifacts}/*epic*/*.md" - load_strategy: "FULL_LOAD" - -# Output configuration -default_output_file: "{status_file}" diff --git a/src/bmm/workflows/4-implementation/sprint-status/bmad-skill-manifest.yaml b/src/bmm/workflows/4-implementation/sprint-status/bmad-skill-manifest.yaml new file mode 100644 index 000000000..437b880e9 --- /dev/null +++ b/src/bmm/workflows/4-implementation/sprint-status/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-sprint-status +type: workflow +description: "Summarize sprint status and surface risks" diff --git a/src/bmm/workflows/4-implementation/sprint-status/instructions.md b/src/bmm/workflows/4-implementation/sprint-status/workflow.md similarity index 84% rename from src/bmm/workflows/4-implementation/sprint-status/instructions.md rename to src/bmm/workflows/4-implementation/sprint-status/workflow.md index 4182e1f25..aeed0ab23 100644 --- a/src/bmm/workflows/4-implementation/sprint-status/instructions.md +++ b/src/bmm/workflows/4-implementation/sprint-status/workflow.md @@ -1,9 +1,46 @@ -# Sprint Status - Multi-Mode Service +--- +name: sprint-status +description: 'Summarize sprint status and surface risks. Use when the user says "check sprint status" or "show sprint status"' +--- -The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/sprint-status/workflow.yaml -Modes: interactive (default), validate, data -⚠️ ABSOLUTELY NO TIME ESTIMATES. Do NOT mention hours, days, weeks, or timelines. +# Sprint Status Workflow + +**Goal:** Summarize sprint status, surface risks, and recommend the next workflow action. + +**Your Role:** You are a Scrum Master providing clear, actionable sprint visibility. No time estimates — focus on status, risks, and next steps. + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `user_name` +- `communication_language`, `document_output_language` +- `implementation_artifacts` +- `date` as system-generated current datetime +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/4-implementation/sprint-status` +- `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml` + +### Input Files + +| Input | Path | Load Strategy | +|-------|------|---------------| +| Sprint status | `{sprint_status_file}` | FULL_LOAD | + +### Context + +- `project_context` = `**/project-context.md` (load if exists) + +--- + +## EXECUTION @@ -36,7 +73,7 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat Read the FULL file: {sprint_status_file} - Parse fields: generated, project, project_key, tracking_system, story_location + Parse fields: generated, last_updated, project, project_key, tracking_system, story_location Parse development_status map. Classify keys: - Epics: keys starting with "epic-" (and not ending with "-retrospective") - Retrospectives: keys ending with "-retrospective" @@ -84,7 +121,7 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho - IF any story has status "review": suggest `/bmad:bmm:workflows:code-review` - IF any story has status "in-progress" AND no stories have status "ready-for-dev": recommend staying focused on active story - IF all epics have status "backlog" AND no stories have status "ready-for-dev": prompt `/bmad:bmm:workflows:create-story` -- IF `generated` timestamp is more than 7 days old: warn "sprint-status.yaml may be stale" +- IF `last_updated` timestamp is more than 7 days old (or `last_updated` is missing, fall back to `generated`): warn "sprint-status.yaml may be stale" - IF any story key doesn't match an epic pattern (e.g., story "5-1-..." but no "epic-5"): warn "orphaned story detected" - IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories" @@ -195,7 +232,7 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted. Read and parse {sprint_status_file} -Validate required metadata fields exist: generated, project, project_key, tracking_system, story_location +Validate required metadata fields exist: generated, project, project_key, tracking_system, story_location (last_updated is optional for backward compatibility) is_valid = false error = "Missing required field(s): {{missing_fields}}" diff --git a/src/bmm/workflows/4-implementation/sprint-status/workflow.yaml b/src/bmm/workflows/4-implementation/sprint-status/workflow.yaml deleted file mode 100644 index f27d57024..000000000 --- a/src/bmm/workflows/4-implementation/sprint-status/workflow.yaml +++ /dev/null @@ -1,25 +0,0 @@ -# Sprint Status - Implementation Tracker -name: sprint-status -description: "Summarize sprint-status.yaml, surface risks, and route to the right implementation workflow." -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -document_output_language: "{config_source}:document_output_language" -implementation_artifacts: "{config_source}:implementation_artifacts" - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/sprint-status" -instructions: "{installed_path}/instructions.md" - -# Inputs -sprint_status_file: "{implementation_artifacts}/sprint-status.yaml" - -# Smart input file references -input_file_patterns: - sprint_status: - description: "Sprint status file generated by sprint-planning" - whole: "{implementation_artifacts}/sprint-status.yaml" - load_strategy: "FULL_LOAD" diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/SKILL.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/SKILL.md new file mode 100644 index 000000000..cb03301ac --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-quick-dev-new-preview +description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/bmad-skill-manifest.yaml b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-01-clarify-and-route.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-01-clarify-and-route.md new file mode 100644 index 000000000..b8812e4f6 --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-01-clarify-and-route.md @@ -0,0 +1,54 @@ +--- +name: 'step-01-clarify-and-route' +description: 'Capture intent, route to execution path' + +wipFile: '{implementation_artifacts}/tech-spec-wip.md' +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +spec_file: '' # set at runtime before leaving this step +--- + +# Step 1: Clarify and Route + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- The prompt that triggered this workflow IS the intent — not a hint. +- Do NOT assume you start from zero. +- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly. +- The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them. + +## ARTIFACT SCAN + +- `{wipFile}` exists? → Offer resume or archive. +- Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new). + - If `ready-for-dev` or `in-progress` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 3. + - If `in-review` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 4. +- Unformatted spec or intent file lacking `status` frontmatter in `{implementation_artifacts}`? → Suggest to the user to treat its contents as the starting intent for this workflow. DO NOT attempt to infer a state and resume it. + +## INSTRUCTIONS + +1. Load context. + - List files in `{planning_artifacts}` and `{implementation_artifacts}`. + - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent. +2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement. +3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check. +4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria: + - Present detected distinct goals as a bullet list. + - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first. + - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks` + - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing. + - On **K**: Proceed as-is. +5. Generate `spec_file` path: + - Derive a valid kebab-case slug from the clarified intent. + - If `{implementation_artifacts}/tech-spec-{slug}.md` already exists, append `-2`, `-3`, etc. + - Set `spec_file` = `{implementation_artifacts}/tech-spec-{slug}.md`. +6. Route: + - **One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. `execution_mode = "one-shot"`. → Step 3. + - **Plan-code-review** — everything else. `execution_mode = "plan-code-review"`. → Step 2. + - When uncertain whether blast radius is truly zero, default to plan-code-review. + + +## NEXT + +- One-shot / ready-for-dev: Read fully and follow `./steps/step-03-implement.md` +- Plan-code-review: Read fully and follow `./steps/step-02-plan.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md new file mode 100644 index 000000000..22df65b60 --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-02-plan.md @@ -0,0 +1,39 @@ +--- +name: 'step-02-plan' +description: 'Investigate, generate spec, present for approval' + +templateFile: '../tech-spec-template.md' +wipFile: '{implementation_artifacts}/tech-spec-wip.md' +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +--- + +# Step 2: Plan + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- No intermediate approvals. + +## INSTRUCTIONS + +1. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._ +2. Read `{templateFile}` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`. +3. Self-review against READY FOR DEVELOPMENT standard. +4. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human. +5. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens: + - Show user the token count. + - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks` + - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint. + - On **K**: Continue to checkpoint with full spec. + +### CHECKPOINT 1 + +Present summary. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem. HALT and ask human: `[A] Approve` | `[E] Edit` + +- **A**: Rename `{wipFile}` to `{spec_file}`, set status `ready-for-dev`. Everything inside `` is now locked — only the human can change it. → Step 3. +- **E**: Apply changes, then return to CHECKPOINT 1. + + +## NEXT + +Read fully and follow `./steps/step-03-implement.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-03-implement.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-03-implement.md new file mode 100644 index 000000000..97d189272 --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-03-implement.md @@ -0,0 +1,35 @@ +--- +name: 'step-03-implement' +description: 'Execute implementation directly or via sub-agent. Local only.' +--- + +# Step 3: Implement + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- No push. No remote ops. +- Sequential execution only. +- Content inside `` in `{spec_file}` is read-only. Do not modify. + +## PRECONDITION + +Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding. + +## INSTRUCTIONS + +### Baseline (plan-code-review only) + +Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes. + +### Implement + +Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation. + +`execution_mode = "one-shot"` or no sub-agents/tasks available: implement the intent. + +Otherwise (`execution_mode = "plan-code-review"`): hand `{spec_file}` to a sub-agent/task and let it implement. + +## NEXT + +Read fully and follow `./steps/step-04-review.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md new file mode 100644 index 000000000..79e4510f8 --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md @@ -0,0 +1,53 @@ +--- +name: 'step-04-review' +description: 'Adversarial review, classify findings, optional spec loop' + +deferred_work_file: '{implementation_artifacts}/deferred-work.md' +specLoopIteration: 1 +--- + +# Step 4: Review + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- Review subagents get NO conversation context. + +## INSTRUCTIONS + +Change `{spec_file}` status to `in-review` in the frontmatter before continuing. + +### Construct Diff (plan-code-review only) + +Read `{baseline_commit}` from `{spec_file}` frontmatter. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_commit}`. + +Do NOT `git add` anything — this is read-only inspection. + +### Review + +**One-shot:** Skip diff construction. Still invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files — inline review invites anchoring bias. + +**Plan-code-review:** Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings. + +- **Blind hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill. +- **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill. +- **Acceptance auditor** — receives `{diff_output}`, `{spec_file}`, and read access to the project. Must also read the docs listed in `{spec_file}` frontmatter `context`. Checks for violations of acceptance criteria, rules, and principles from the spec and context docs. + +### Classify + +1. Deduplicate all review findings. +2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**. + - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading. + - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code. + - **patch** — caused by the change; trivially fixable without human input. Just part of the diff. + - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention. + - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real. +3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human. On any loopback, re-evaluate routing — if scope has grown beyond one-shot, escalate `execution_mode` to plan-code-review. + - **intent_gap** — Root cause is inside ``. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./steps/step-02-plan.md` to re-run steps 2–4. + - **bad_spec** — Root cause is outside ``. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./steps/step-03-implement.md` to re-derive the code, then this step will run again. + - **patch** — Auto-fix. These are the only findings that survive loopbacks. + - **defer** — Append to `{deferred_work_file}`. + - **reject** — Drop silently. +## NEXT + +Read fully and follow `./steps/step-05-present.md` diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md new file mode 100644 index 000000000..c9bc13d50 --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md @@ -0,0 +1,19 @@ +--- +name: 'step-05-present' +description: 'Present findings, get approval, create PR' +--- + +# Step 5: Present + +## RULES + +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` +- NEVER auto-push. + +## INSTRUCTIONS + +1. Change `{spec_file}` status to `done` in the frontmatter. +2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title. +3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request. + +Workflow complete. diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/tech-spec-template.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/tech-spec-template.md new file mode 100644 index 000000000..c9fef536b --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/tech-spec-template.md @@ -0,0 +1,90 @@ +--- +title: '{title}' +type: 'feature' # feature | bugfix | refactor | chore +created: '{date}' +status: 'draft' # draft | ready-for-dev | in-progress | in-review | done +context: [] # optional: max 3 project-wide standards/docs. NO source code files. +--- + + + +# {title} + + + +## Intent + + + +**Problem:** ONE_TO_TWO_SENTENCES + +**Approach:** ONE_TO_TWO_SENTENCES + +## Boundaries & Constraints + + + +**Always:** INVARIANT_RULES + +**Ask First:** DECISIONS_REQUIRING_HUMAN_APPROVAL + + +**Never:** NON_GOALS_AND_FORBIDDEN_APPROACHES + +## I/O & Edge-Case Matrix + + + +| Scenario | Input / State | Expected Output / Behavior | Error Handling | +|----------|--------------|---------------------------|----------------| +| HAPPY_PATH | INPUT | OUTCOME | N/A | +| ERROR_CASE | INPUT | OUTCOME | ERROR_HANDLING | + + + +## Code Map + + + +- `FILE` -- ROLE_OR_RELEVANCE +- `FILE` -- ROLE_OR_RELEVANCE + +## Tasks & Acceptance + + + + + +**Execution:** +- [ ] `FILE` -- ACTION -- RATIONALE + +**Acceptance Criteria:** +- Given PRECONDITION, when ACTION, then EXPECTED_RESULT + +## Spec Change Log + + + +## Design Notes + + + + +DESIGN_RATIONALE_AND_EXAMPLES + +## Verification + + + + +**Commands:** +- `COMMAND` -- expected: SUCCESS_CRITERIA + +**Manual checks (if no CLI):** +- WHAT_TO_INSPECT_AND_EXPECTED_STATE diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md new file mode 100644 index 000000000..71d231ac1 --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md @@ -0,0 +1,80 @@ +--- +main_config: '{project-root}/_bmad/bmm/config.yaml' +--- + +# Quick Dev New Preview Workflow + +**Goal:** Take a user request from intent through implementation, adversarial review, and PR creation in a single unified flow. + +**Your Role:** You are an elite developer. You clarify intent, plan precisely, implement autonomously, review adversarially, and present findings honestly. Minimum ceremony, maximum signal. + + +## READY FOR DEVELOPMENT STANDARD + +A specification is "Ready for Development" when: + +- **Actionable**: Every task has a file path and specific action. +- **Logical**: Tasks ordered by dependency. +- **Testable**: All ACs use Given/When/Then. +- **Complete**: No placeholders or TBDs. + + +## SCOPE STANDARD + +A specification should target a **single user-facing goal** within **900–1600 tokens**: + +- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal. + - Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard" + - Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry" +- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents. +- **Neither limit is a gate.** Both are proposals with user override. + + +## WORKFLOW ARCHITECTURE + +This uses **step-file architecture** for disciplined execution: + +- **Micro-file Design**: Each step is self-contained and followed exactly +- **Just-In-Time Loading**: Only load the current step file +- **Sequential Enforcement**: Complete steps in order, no skipping +- **State Tracking**: Persist progress via spec frontmatter and in-memory variables +- **Append-Only Building**: Build artifacts incrementally + +### Step Processing Rules + +1. **READ COMPLETELY**: Read the entire step file before acting +2. **FOLLOW SEQUENCE**: Execute sections in order +3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human +4. **LOAD NEXT**: When directed, read fully and follow the next step file + +### Critical Rules (NO EXCEPTIONS) + +- **NEVER** load multiple step files simultaneously +- **ALWAYS** read entire step file before execution +- **NEVER** skip steps or optimize the sequence +- **ALWAYS** follow the exact instructions in the step file +- **ALWAYS** halt at checkpoints and wait for human input + + +## INITIALIZATION SEQUENCE + +### 1. Configuration Loading + +Load and read full config from `{main_config}` and resolve: + +- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name` +- `communication_language`, `document_output_language`, `user_skill_level` +- `date` as system-generated current datetime +- `project_context` = `**/project-context.md` (load if exists) +- CLAUDE.md / memory files (load if exist) + +YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`. + +### 2. Paths + +- `templateFile` = `./tech-spec-template.md` +- `wipFile` = `{implementation_artifacts}/tech-spec-wip.md` + +### 3. First Step Execution + +Read fully and follow: `./steps/step-01-clarify-and-route.md` to begin the workflow. diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/SKILL.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/SKILL.md new file mode 100644 index 000000000..cc2b628b1 --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-quick-dev +description: 'Implement a Quick Tech Spec for small changes or features. Use when the user provides a quick tech spec and says "implement this quick spec" or "proceed with implementation of [quick tech spec]"' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/bmad-skill-manifest.yaml b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-01-mode-detection.md similarity index 87% rename from src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md rename to src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-01-mode-detection.md index 2391f9722..8de9be3fd 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-01-mode-detection.md @@ -50,7 +50,7 @@ Analyze the user's input to determine mode: - Load the spec, extract tasks/context/AC - Set `{execution_mode}` = "tech-spec" - Set `{tech_spec_path}` = provided path -- **NEXT:** Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md` +- **NEXT:** Read fully and follow: `{nextStepFile_modeA}` **Mode B: Direct Instructions** @@ -91,7 +91,7 @@ Display: "**Select:** [P] Plan first (tech-spec) [E] Execute directly" #### Menu Handling Logic: - IF P: Direct user to `{quick_spec_workflow}`. **EXIT Quick Dev.** -- IF E: Ask for any additional guidance, then **NEXT:** Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md` +- IF E: Ask for any additional guidance, then **NEXT:** Read fully and follow: `{nextStepFile_modeB}` #### EXECUTION RULES: @@ -114,7 +114,7 @@ Display: - IF P: Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.** - IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.** -- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md` +- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `{nextStepFile_modeB}` #### EXECUTION RULES: @@ -137,7 +137,7 @@ Display: - IF P: Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.** - IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.** -- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md` +- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `{nextStepFile_modeB}` #### EXECUTION RULES: @@ -150,8 +150,8 @@ Display: **CRITICAL:** When this step completes, explicitly state which step to load: -- Mode A (tech-spec): "**NEXT:** read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md`" -- Mode B (direct, [E] selected): "**NEXT:** Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md`" +- Mode A (tech-spec): "**NEXT:** read fully and follow: `{nextStepFile_modeA}`" +- Mode B (direct, [E] selected): "**NEXT:** Read fully and follow: `{nextStepFile_modeB}`" - Escalation ([P] or [W]): "**EXITING Quick Dev.** Follow the directed workflow." --- diff --git a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-02-context-gathering.md similarity index 94% rename from src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md rename to src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-02-context-gathering.md index da178a088..3652bb924 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-02-context-gathering.md @@ -97,7 +97,7 @@ Ready to execute? (y/n/adjust) **CRITICAL:** When user confirms ready, explicitly state: -- **y:** "**NEXT:** Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md`" +- **y:** "**NEXT:** Read fully and follow: `{nextStepFile}`" - **n/adjust:** Continue gathering context, then re-present plan --- diff --git a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-03-execute.md similarity index 95% rename from src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md rename to src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-03-execute.md index 81be97fba..06801af7a 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-03-execute.md @@ -89,7 +89,7 @@ For each task: ## NEXT STEP -When ALL tasks are complete (or halted on blocker), read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md`. +When ALL tasks are complete (or halted on blocker), read fully and follow: `{nextStepFile}`. --- diff --git a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-04-self-check.md similarity index 94% rename from src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md rename to src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-04-self-check.md index f12b2a3fd..e70de8515 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-04-self-check.md @@ -89,7 +89,7 @@ Proceeding to adversarial code review... ## NEXT STEP -Proceed immediately to `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md`. +Proceed immediately to `{nextStepFile}`. --- diff --git a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-05-adversarial-review.md similarity index 68% rename from src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md rename to src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-05-adversarial-review.md index 8bbd6761e..29a0cef19 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-05-adversarial-review.md @@ -1,13 +1,13 @@ --- name: 'step-05-adversarial-review' -description: 'Construct diff and invoke adversarial review task' +description: 'Construct diff and invoke adversarial review skill' nextStepFile: './step-06-resolve-findings.md' --- # Step 5: Adversarial Code Review -**Goal:** Construct diff of all changes, invoke adversarial review task, present findings. +**Goal:** Construct diff of all changes, invoke adversarial review skill, present findings. --- @@ -57,21 +57,15 @@ Merge all changes into `{diff_output}`. ### 2. Invoke Adversarial Review -With `{diff_output}` constructed, load and follow the review task. If possible, use information asymmetry: load this step, and only it, in a separate subagent or process with read access to the project, but no context except the `{diff_output}`. +With `{diff_output}` constructed, invoke the `bmad-review-adversarial-general` skill. If possible, use information asymmetry: invoke the skill in a separate subagent or process with read access to the project, but no context except the `{diff_output}`. -```xml -Review {diff_output} using {project-root}/_bmad/core/tasks/review-adversarial-general.xml -``` - -**Platform fallback:** If task invocation not available, load the task file and follow its instructions inline, passing `{diff_output}` as the content. - -The task should: review `{diff_output}` and return a list of findings. +Pass `{diff_output}` as the content to review. The skill should return a list of findings. --- ### 3. Process Findings -Capture the findings from the task output. +Capture the findings from the skill output. **If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance. Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided). DO NOT exclude findings based on severity or validity unless explicitly asked to do so. @@ -83,7 +77,7 @@ If TodoWrite or similar tool is available, turn each finding into a TODO, includ ## NEXT STEP -With findings in hand, read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-06-resolve-findings.md` for user to choose resolution approach. +With findings in hand, read fully and follow: `{nextStepFile}` for user to choose resolution approach. --- @@ -91,7 +85,7 @@ With findings in hand, read fully and follow: `{project-root}/_bmad/bmm/workflow - Diff constructed from baseline_commit - New files included in diff -- Task invoked with diff as input +- Skill invoked with diff as input - Findings received - Findings processed into TODOs or table and presented to user @@ -99,6 +93,6 @@ With findings in hand, read fully and follow: `{project-root}/_bmad/bmm/workflow - Missing baseline_commit (can't construct accurate diff) - Not including new untracked files in diff -- Invoking task without providing diff input +- Invoking skill without providing diff input - Accepting zero findings without questioning -- Presenting fewer findings than the review task returned without explicit instruction to do so +- Presenting fewer findings than the review skill returned without explicit instruction to do so diff --git a/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-06-resolve-findings.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-06-resolve-findings.md similarity index 100% rename from src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-06-resolve-findings.md rename to src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/steps/step-06-resolve-findings.md diff --git a/src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/workflow.md similarity index 63% rename from src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md rename to src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/workflow.md index 009ead510..0ad096c52 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md +++ b/src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/workflow.md @@ -1,8 +1,3 @@ ---- -name: quick-dev -description: 'Flexible development - execute tech-specs OR direct instructions with optional planning.' ---- - # Quick Dev Workflow **Goal:** Execute implementation tasks efficiently, either from a tech-spec or direct user instructions. @@ -34,17 +29,16 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: ### Paths -- `installed_path` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev` - `project_context` = `**/project-context.md` (load if exists) ### Related Workflows -- `quick_spec_workflow` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md` -- `party_mode_exec` = `{project-root}/_bmad/core/workflows/party-mode/workflow.md` -- `advanced_elicitation` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` +- `quick_spec_workflow` = `../quick-spec/workflow.md` +- `party_mode_exec` = `{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md` +- `advanced_elicitation` = `skill:bmad-advanced-elicitation` --- ## EXECUTION -Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md` to begin the workflow. +Read fully and follow: `./steps/step-01-mode-detection.md` to begin the workflow. diff --git a/src/bmm/workflows/bmad-quick-flow/quick-spec/bmad-skill-manifest.yaml b/src/bmm/workflows/bmad-quick-flow/quick-spec/bmad-skill-manifest.yaml new file mode 100644 index 000000000..1a383135c --- /dev/null +++ b/src/bmm/workflows/bmad-quick-flow/quick-spec/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-quick-spec +type: workflow +description: "Very quick process to create implementation-ready quick specs for small changes or features" diff --git a/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md b/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md index 24c65d088..a973caecd 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md +++ b/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md @@ -138,7 +138,7 @@ b) **HALT and wait for user selection.** #### Menu Handling Logic: - IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu -- IF B: Read the entire workflow file at `{quick_dev_workflow}` and follow the instructions with the final spec file (warn: fresh context is better) +- IF B: Invoke the `bmad-quick-dev` skill with `{finalFile}` in a fresh context if possible (warn: fresh context is better) - IF D: Exit workflow - display final confirmation and path to spec - IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu - IF R: Execute Adversarial Review (see below) @@ -151,14 +151,12 @@ b) **HALT and wait for user selection.** #### Adversarial Review [R] Process: -1. **Invoke Adversarial Review Task**: - > With `{finalFile}` constructed, load and follow the review task. If possible, use information asymmetry: load this task, and only it, in a separate subagent or process with read access to the project, but no context except the `{finalFile}`. - Review {finalFile} using {project-root}/_bmad/core/tasks/review-adversarial-general.xml - > **Platform fallback:** If task invocation not available, load the task file and follow its instructions inline, passing `{finalFile}` as the content. - > The task should: review `{finalFile}` and return a list of findings. +1. **Invoke Adversarial Review Skill**: + > With `{finalFile}` constructed, invoke the `bmad-review-adversarial-general` skill. If possible, use information asymmetry: invoke the skill in a separate subagent or process with read access to the project, but no context except the `{finalFile}`. + > Pass `{finalFile}` as the content to review. The skill should return a list of findings. 2. **Process Findings**: - > Capture the findings from the task output. + > Capture the findings from the skill output. > **If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance. > Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided). > DO NOT exclude findings based on severity or validity unless explicitly asked to do so. diff --git a/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md b/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md index 7175b2aa9..02e231fe5 100644 --- a/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md +++ b/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md @@ -1,12 +1,11 @@ --- name: quick-spec -description: Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec. +description: 'Very quick process to create implementation-ready quick specs for small changes or features. Use when the user says "create a quick spec" or "generate a quick tech spec"' main_config: '{project-root}/_bmad/bmm/config.yaml' -# Checkpoint handler paths -advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' -party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' -quick_dev_workflow: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md' +# Checkpoint handler references +advanced_elicitation: 'skill:bmad-advanced-elicitation' +party_mode_exec: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md' --- # Quick-Spec Workflow diff --git a/src/bmm/workflows/document-project/bmad-skill-manifest.yaml b/src/bmm/workflows/document-project/bmad-skill-manifest.yaml new file mode 100644 index 000000000..4e8cb2767 --- /dev/null +++ b/src/bmm/workflows/document-project/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-document-project +type: workflow +description: "Document brownfield projects for AI context" diff --git a/src/bmm/workflows/document-project/instructions.md b/src/bmm/workflows/document-project/instructions.md index 0354be610..64f652247 100644 --- a/src/bmm/workflows/document-project/instructions.md +++ b/src/bmm/workflows/document-project/instructions.md @@ -1,7 +1,5 @@ # Document Project Workflow Router -The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml -You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/document-project/workflow.yaml Communicate all responses in {communication_language} @@ -49,11 +47,11 @@ Display: "Resuming {{workflow_mode}} from {{current_step}} with cached project type(s): {{cached_project_types}}" - Read fully and follow: {installed_path}/workflows/deep-dive-instructions.md with resume context + Read fully and follow: {installed_path}/workflows/deep-dive-workflow.md with resume context - Read fully and follow: {installed_path}/workflows/full-scan-instructions.md with resume context + Read fully and follow: {installed_path}/workflows/full-scan-workflow.md with resume context @@ -100,7 +98,7 @@ Your choice [1/2/3]: Set workflow_mode = "full_rescan" Display: "Starting full project rescan..." - Read fully and follow: {installed_path}/workflows/full-scan-instructions.md + Read fully and follow: {installed_path}/workflows/full-scan-workflow.md After sub-workflow completes, continue to Step 4 @@ -108,7 +106,7 @@ Your choice [1/2/3]: Set workflow_mode = "deep_dive" Set scan_level = "exhaustive" Display: "Starting deep-dive documentation mode..." - Read fully and follow: {installed_path}/workflows/deep-dive-instructions.md + Read fully and follow: {installed_path}/workflows/deep-dive-workflow.md After sub-workflow completes, continue to Step 4 @@ -121,7 +119,7 @@ Your choice [1/2/3]: Set workflow_mode = "initial_scan" Display: "No existing documentation found. Starting initial project scan..." - Read fully and follow: {installed_path}/workflows/full-scan-instructions.md + Read fully and follow: {installed_path}/workflows/full-scan-workflow.md After sub-workflow completes, continue to Step 4 diff --git a/src/bmm/workflows/document-project/workflow.md b/src/bmm/workflows/document-project/workflow.md new file mode 100644 index 000000000..cd7d9d33d --- /dev/null +++ b/src/bmm/workflows/document-project/workflow.md @@ -0,0 +1,39 @@ +--- +name: document-project +description: 'Document brownfield projects for AI context. Use when the user says "document this project" or "generate project docs"' +--- + +# Document Project Workflow + +**Goal:** Document brownfield projects for AI context. + +**Your Role:** Project documentation specialist. +- Communicate all responses in {communication_language} + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_knowledge` +- `user_name` +- `communication_language` +- `document_output_language` +- `user_skill_level` +- `date` as system-generated current datetime + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/document-project` +- `instructions` = `{installed_path}/instructions.md` +- `validation` = `{installed_path}/checklist.md` +- `documentation_requirements_csv` = `{installed_path}/documentation-requirements.csv` + +--- + +## EXECUTION + +Read fully and follow: `{installed_path}/instructions.md` diff --git a/src/bmm/workflows/document-project/workflow.yaml b/src/bmm/workflows/document-project/workflow.yaml deleted file mode 100644 index be9600c24..000000000 --- a/src/bmm/workflows/document-project/workflow.yaml +++ /dev/null @@ -1,22 +0,0 @@ -# Document Project Workflow Configuration -name: "document-project" -version: "1.2.0" -description: "Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development" -author: "BMad" - -# Critical variables -config_source: "{project-root}/_bmad/bmm/config.yaml" -project_knowledge: "{config_source}:project_knowledge" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -document_output_language: "{config_source}:document_output_language" -user_skill_level: "{config_source}:user_skill_level" -date: system-generated - -# Module path and component files -installed_path: "{project-root}/_bmad/bmm/workflows/document-project" -instructions: "{installed_path}/instructions.md" -validation: "{installed_path}/checklist.md" - -# Required data files - CRITICAL for project type detection and documentation requirements -documentation_requirements_csv: "{installed_path}/documentation-requirements.csv" diff --git a/src/bmm/workflows/document-project/workflows/deep-dive-instructions.md b/src/bmm/workflows/document-project/workflows/deep-dive-instructions.md index 637621c4c..396a2e43a 100644 --- a/src/bmm/workflows/document-project/workflows/deep-dive-instructions.md +++ b/src/bmm/workflows/document-project/workflows/deep-dive-instructions.md @@ -3,7 +3,6 @@ This workflow performs exhaustive deep-dive documentation of specific areas -Called by: ../document-project/instructions.md router Handles: deep_dive mode only diff --git a/src/bmm/workflows/document-project/workflows/deep-dive-workflow.md b/src/bmm/workflows/document-project/workflows/deep-dive-workflow.md new file mode 100644 index 000000000..fea471e6d --- /dev/null +++ b/src/bmm/workflows/document-project/workflows/deep-dive-workflow.md @@ -0,0 +1,42 @@ +--- +name: document-project-deep-dive +description: 'Exhaustive deep-dive documentation of specific project areas' +--- + +# Deep-Dive Documentation Sub-Workflow + +**Goal:** Exhaustive deep-dive documentation of specific project areas. + +**Your Role:** Deep-dive documentation specialist. +- Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN. + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_knowledge` +- `user_name` +- `date` as system-generated current datetime + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/document-project/workflows` +- `instructions` = `{installed_path}/deep-dive-instructions.md` +- `validation` = `{project-root}/_bmad/bmm/workflows/document-project/checklist.md` +- `deep_dive_template` = `{project-root}/_bmad/bmm/workflows/document-project/templates/deep-dive-template.md` + +### Runtime Inputs + +- `workflow_mode` = `deep_dive` +- `scan_level` = `exhaustive` +- `autonomous` = `false` (requires user input to select target area) + +--- + +## EXECUTION + +Read fully and follow: `{installed_path}/deep-dive-instructions.md` diff --git a/src/bmm/workflows/document-project/workflows/deep-dive.yaml b/src/bmm/workflows/document-project/workflows/deep-dive.yaml deleted file mode 100644 index c7b85c031..000000000 --- a/src/bmm/workflows/document-project/workflows/deep-dive.yaml +++ /dev/null @@ -1,31 +0,0 @@ -# Deep-Dive Documentation Workflow Configuration -name: "document-project-deep-dive" -description: "Exhaustive deep-dive documentation of specific project areas" -author: "BMad" - -# This is a sub-workflow called by document-project/workflow.yaml -parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml" - -# Critical variables inherited from parent -config_source: "{project-root}/_bmad/bmb/config.yaml" -project_knowledge: "{config_source}:project_knowledge" -user_name: "{config_source}:user_name" -date: system-generated - -# Module path and component files -installed_path: "{project-root}/_bmad/bmm/workflows/document-project/workflows" -template: false # Action workflow -instructions: "{installed_path}/deep-dive-instructions.md" -validation: "{project-root}/_bmad/bmm/workflows/document-project/checklist.md" - -# Templates -deep_dive_template: "{project-root}/_bmad/bmm/workflows/document-project/templates/deep-dive-template.md" - -# Runtime inputs (passed from parent workflow) -workflow_mode: "deep_dive" -scan_level: "exhaustive" # Deep-dive always uses exhaustive scan -project_root_path: "" -existing_index_path: "" # Path to existing index.md - -# Configuration -autonomous: false # Requires user input to select target area diff --git a/src/bmm/workflows/document-project/workflows/full-scan-instructions.md b/src/bmm/workflows/document-project/workflows/full-scan-instructions.md index 8a3621d21..d2a8a1e79 100644 --- a/src/bmm/workflows/document-project/workflows/full-scan-instructions.md +++ b/src/bmm/workflows/document-project/workflows/full-scan-instructions.md @@ -3,7 +3,6 @@ This workflow performs complete project documentation (Steps 1-12) -Called by: document-project/instructions.md router Handles: initial_scan and full_rescan modes diff --git a/src/bmm/workflows/document-project/workflows/full-scan-workflow.md b/src/bmm/workflows/document-project/workflows/full-scan-workflow.md new file mode 100644 index 000000000..4c26fa1a7 --- /dev/null +++ b/src/bmm/workflows/document-project/workflows/full-scan-workflow.md @@ -0,0 +1,42 @@ +--- +name: document-project-full-scan +description: 'Complete project documentation workflow (initial scan or full rescan)' +--- + +# Full Project Scan Sub-Workflow + +**Goal:** Complete project documentation (initial scan or full rescan). + +**Your Role:** Full project scan documentation specialist. + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_knowledge` +- `user_name` +- `date` as system-generated current datetime + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/document-project/workflows` +- `instructions` = `{installed_path}/full-scan-instructions.md` +- `validation` = `{project-root}/_bmad/bmm/workflows/document-project/checklist.md` +- `documentation_requirements_csv` = `{project-root}/_bmad/bmm/workflows/document-project/documentation-requirements.csv` + +### Runtime Inputs + +- `workflow_mode` = `""` (set by parent: `initial_scan` or `full_rescan`) +- `scan_level` = `""` (set by parent: `quick`, `deep`, or `exhaustive`) +- `resume_mode` = `false` +- `autonomous` = `false` (requires user input at key decision points) + +--- + +## EXECUTION + +Read fully and follow: `{installed_path}/full-scan-instructions.md` diff --git a/src/bmm/workflows/document-project/workflows/full-scan.yaml b/src/bmm/workflows/document-project/workflows/full-scan.yaml deleted file mode 100644 index 272baedda..000000000 --- a/src/bmm/workflows/document-project/workflows/full-scan.yaml +++ /dev/null @@ -1,31 +0,0 @@ -# Full Project Scan Workflow Configuration -name: "document-project-full-scan" -description: "Complete project documentation workflow (initial scan or full rescan)" -author: "BMad" - -# This is a sub-workflow called by document-project/workflow.yaml -parent_workflow: "{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml" - -# Critical variables inherited from parent -config_source: "{project-root}/_bmad/bmb/config.yaml" -project_knowledge: "{config_source}:project_knowledge" -user_name: "{config_source}:user_name" -date: system-generated - -# Data files -documentation_requirements_csv: "{project-root}/_bmad/bmm/workflows/document-project/documentation-requirements.csv" - -# Module path and component files -installed_path: "{project-root}/_bmad/bmm/workflows/document-project/workflows" -template: false # Action workflow -instructions: "{installed_path}/full-scan-instructions.md" -validation: "{project-root}/_bmad/bmm/workflows/document-project/checklist.md" - -# Runtime inputs (passed from parent workflow) -workflow_mode: "" # "initial_scan" or "full_rescan" -scan_level: "" # "quick", "deep", or "exhaustive" -resume_mode: false -project_root_path: "" - -# Configuration -autonomous: false # Requires user input at key decision points diff --git a/src/bmm/workflows/generate-project-context/bmad-skill-manifest.yaml b/src/bmm/workflows/generate-project-context/bmad-skill-manifest.yaml new file mode 100644 index 000000000..c319972c4 --- /dev/null +++ b/src/bmm/workflows/generate-project-context/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-generate-project-context +type: workflow +description: "Create project-context.md with AI rules" diff --git a/src/bmm/workflows/generate-project-context/steps/step-02-generate.md b/src/bmm/workflows/generate-project-context/steps/step-02-generate.md index dcb2f0097..b44f1bc43 100644 --- a/src/bmm/workflows/generate-project-context/steps/step-02-generate.md +++ b/src/bmm/workflows/generate-project-context/steps/step-02-generate.md @@ -29,8 +29,8 @@ This step will generate content and present choices for each rule category: ## PROTOCOL INTEGRATION: -- When 'A' selected: Execute {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml -- When 'P' selected: Execute {project-root}/_bmad/core/workflows/party-mode +- When 'A' selected: Execute skill:bmad-advanced-elicitation +- When 'P' selected: Execute {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed - User accepts/rejects protocol changes before proceeding @@ -267,7 +267,7 @@ After each category, show the generated rules and present choices: #### If 'A' (Advanced Elicitation): -- Execute advanced-elicitation.xml with current category rules +- Execute skill:bmad-advanced-elicitation with current category rules - Process enhanced rules that come back - Ask user: "Accept these enhanced rules for {{category}}? (y/n)" - If yes: Update content, then return to A/P/C menu diff --git a/src/bmm/workflows/generate-project-context/workflow.md b/src/bmm/workflows/generate-project-context/workflow.md index e19902270..f1537c06e 100644 --- a/src/bmm/workflows/generate-project-context/workflow.md +++ b/src/bmm/workflows/generate-project-context/workflow.md @@ -1,6 +1,6 @@ --- name: generate-project-context -description: Creates a concise project-context.md file with critical rules and patterns that AI agents must follow when implementing code. Optimized for LLM context efficiency. +description: 'Create project-context.md with AI rules. Use when the user says "generate project context" or "create project context"' --- # Generate Project Context Workflow diff --git a/src/bmm/workflows/qa-generate-e2e-tests/bmad-skill-manifest.yaml b/src/bmm/workflows/qa-generate-e2e-tests/bmad-skill-manifest.yaml new file mode 100644 index 000000000..20e08be69 --- /dev/null +++ b/src/bmm/workflows/qa-generate-e2e-tests/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-qa-generate-e2e-tests +type: workflow +description: "Generate end-to-end automated tests for existing features" diff --git a/src/bmm/workflows/qa/automate/checklist.md b/src/bmm/workflows/qa-generate-e2e-tests/checklist.md similarity index 100% rename from src/bmm/workflows/qa/automate/checklist.md rename to src/bmm/workflows/qa-generate-e2e-tests/checklist.md diff --git a/src/bmm/workflows/qa/automate/instructions.md b/src/bmm/workflows/qa-generate-e2e-tests/workflow.md similarity index 61% rename from src/bmm/workflows/qa/automate/instructions.md rename to src/bmm/workflows/qa-generate-e2e-tests/workflow.md index 03653337f..f911090b0 100644 --- a/src/bmm/workflows/qa/automate/instructions.md +++ b/src/bmm/workflows/qa-generate-e2e-tests/workflow.md @@ -1,10 +1,43 @@ -# Quinn QA - Automate +--- +name: qa-generate-e2e-tests +description: 'Generate end to end automated tests for existing features. Use when the user says "create qa automated tests for [feature]"' +--- -**Goal**: Generate automated API and E2E tests for implemented code. +# QA Generate E2E Tests Workflow -**Scope**: This workflow generates tests ONLY. It does **not** perform code review or story validation (use Code Review `CR` for that). +**Goal:** Generate automated API and E2E tests for implemented code. -## Instructions +**Your Role:** You are a QA automation engineer. You generate tests ONLY — no code review or story validation (use Code Review `CR` for that). + +--- + +## INITIALIZATION + +### Configuration Loading + +Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: + +- `project_name`, `user_name` +- `communication_language`, `document_output_language` +- `implementation_artifacts` +- `date` as system-generated current datetime +- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}` + +### Paths + +- `installed_path` = `{project-root}/_bmad/bmm/workflows/qa-generate-e2e-tests` +- `checklist` = `{installed_path}/checklist.md` +- `test_dir` = `{project-root}/tests` +- `source_dir` = `{project-root}` +- `default_output_file` = `{implementation_artifacts}/tests/test-summary.md` + +### Context + +- `project_context` = `**/project-context.md` (load if exists) + +--- + +## EXECUTION ### Step 0: Detect Test Framework @@ -101,10 +134,10 @@ If the project needs: - Comprehensive coverage analysis - Advanced testing patterns and utilities -→ **Install Test Architect (TEA) module**: +> **Install Test Architect (TEA) module**: ## Output -Save summary to: `{implementation_artifacts}/tests/test-summary.md` +Save summary to: `{default_output_file}` -**Done!** Tests generated and verified. +**Done!** Tests generated and verified. Validate against `{checklist}`. diff --git a/src/bmm/workflows/qa/automate/workflow.yaml b/src/bmm/workflows/qa/automate/workflow.yaml deleted file mode 100644 index f1119e980..000000000 --- a/src/bmm/workflows/qa/automate/workflow.yaml +++ /dev/null @@ -1,44 +0,0 @@ -# Quinn QA workflow: Automate -name: qa-automate -description: "Generate tests quickly for existing features using standard test patterns" -author: "BMad" - -# Critical variables from config -config_source: "{project-root}/_bmad/bmm/config.yaml" -implementation_artifacts: "{config_source}:implementation_artifacts" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -document_output_language: "{config_source}:document_output_language" -date: system-generated - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/qa/automate" -instructions: "{installed_path}/instructions.md" -validation: "{installed_path}/checklist.md" -template: false - -# Variables and inputs -test_dir: "{project-root}/tests" # Root test directory -source_dir: "{project-root}" # Source code directory - -# Output configuration -default_output_file: "{implementation_artifacts}/tests/test-summary.md" - -# Required tools -required_tools: - - read_file # Read source code and existing tests - - write_file # Create test files - - create_directory # Create test directories - - list_files # Discover features - - search_repo # Find patterns - - glob # Find files - -tags: - - qa - - automation - - testing - -execution_hints: - interactive: false - autonomous: true - iterative: false diff --git a/src/core/agents/bmad-master.agent.yaml b/src/core/agents/bmad-master.agent.yaml index 1304c1cc9..796a91b38 100644 --- a/src/core/agents/bmad-master.agent.yaml +++ b/src/core/agents/bmad-master.agent.yaml @@ -18,7 +18,7 @@ agent: - Load resources at runtime, never pre-load, and always present numbered lists for choices. critical_actions: - - "Always greet the user and let them know they can use `/bmad-help` at any time to get advice on what to do next, and they can combine that with what they need help with `/bmad-help where should I start with an idea I have that does XYZ`" + - 'Always greet the user and let them know they can invoke the `bmad-help` skill at any time to get advice on what to do next, and they can combine it with what they need help with Invoke the `bmad-help` skill with a question like "where should I start with an idea I have that does XYZ?"' menu: - trigger: "LT or fuzzy match on list-tasks" diff --git a/src/core/agents/bmad-skill-manifest.yaml b/src/core/agents/bmad-skill-manifest.yaml new file mode 100644 index 000000000..21cd90501 --- /dev/null +++ b/src/core/agents/bmad-skill-manifest.yaml @@ -0,0 +1,3 @@ +canonicalId: bmad-master +type: agent +description: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator" diff --git a/src/core/module-help.csv b/src/core/module-help.csv index 1fdf064c4..e987b9353 100644 --- a/src/core/module-help.csv +++ b/src/core/module-help.csv @@ -1,9 +1,10 @@ module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs -core,anytime,Brainstorming,BSP,,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,,"Generate diverse ideas through interactive techniques. Use early in ideation phase or when stuck generating ideas.",{output_folder}/brainstorming/brainstorming-session-{{date}}.md,, -core,anytime,Party Mode,PM,,_bmad/core/workflows/party-mode/workflow.md,bmad-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",, -core,anytime,bmad-help,BH,,_bmad/core/tasks/help.md,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,Adversarial Review (General),AR,,_bmad/core/tasks/review-adversarial-general.xml,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,Brainstorming,BSP,,skill:bmad-brainstorming,bmad-brainstorming,false,analyst,,"Generate diverse ideas through interactive techniques. Use early in ideation phase or when stuck generating ideas.",{output_folder}/brainstorming/brainstorming-session-{{date}}.md,, +core,anytime,Party Mode,PM,,skill:bmad-party-mode,bmad-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",, +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,,skill:bmad-index-docs,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,,skill:bmad-shard-doc,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,,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.",, diff --git a/src/core/module.yaml b/src/core/module.yaml index 10596d862..48e7a58f7 100644 --- a/src/core/module.yaml +++ b/src/core/module.yaml @@ -2,7 +2,7 @@ code: core name: "BMad Core Module" header: "BMad Core Configuration" -subheader: "Configure the core settings for your BMad installation.\nThese settings will be used across all modules and agents." +subheader: "Configure the core settings for your BMad installation.\nThese settings will be used across all installed bmad skills, workflows, and agents." user_name: prompt: "What should agents call you? (Use your name or a team name)" diff --git a/src/core/tasks/bmad-advanced-elicitation/SKILL.md b/src/core/tasks/bmad-advanced-elicitation/SKILL.md new file mode 100644 index 000000000..2c222cd7f --- /dev/null +++ b/src/core/tasks/bmad-advanced-elicitation/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-advanced-elicitation +description: 'Push the LLM to reconsider refine and improve its recent output.' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/core/tasks/bmad-advanced-elicitation/bmad-skill-manifest.yaml b/src/core/tasks/bmad-advanced-elicitation/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/tasks/bmad-advanced-elicitation/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/workflows/advanced-elicitation/methods.csv b/src/core/tasks/bmad-advanced-elicitation/methods.csv similarity index 100% rename from src/core/workflows/advanced-elicitation/methods.csv rename to src/core/tasks/bmad-advanced-elicitation/methods.csv diff --git a/src/core/tasks/bmad-advanced-elicitation/workflow.md b/src/core/tasks/bmad-advanced-elicitation/workflow.md new file mode 100644 index 000000000..4d947d6f4 --- /dev/null +++ b/src/core/tasks/bmad-advanced-elicitation/workflow.md @@ -0,0 +1,136 @@ +--- +methods: './methods.csv' +agent_party: '{project-root}/_bmad/_config/agent-manifest.csv' +--- + +# Advanced Elicitation Workflow + +**Goal:** Push the LLM to reconsider, refine, and improve its recent output. + +--- + +## CRITICAL LLM INSTRUCTIONS + +- **MANDATORY:** Execute ALL steps in the flow 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 +- Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution +- **YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the `communication_language`** + +--- + +## INTEGRATION (When Invoked Indirectly) + +When invoked from another prompt or process: + +1. Receive or review the current section content that was just generated +2. Apply elicitation methods iteratively to enhance that specific content +3. Return the enhanced version back when user selects 'x' to proceed and return back +4. The enhanced content replaces the original section content in the output document + +--- + +## FLOW + +### Step 1: Method Registry Loading + +**Action:** Load and read `{methods}` and `{agent_party}` + +#### CSV Structure + +- **category:** Method grouping (core, structural, risk, etc.) +- **method_name:** Display name for the method +- **description:** Rich explanation of what the method does, when to use it, and why it's valuable +- **output_pattern:** Flexible flow guide using arrows (e.g., "analysis -> insights -> action") + +#### Context Analysis + +- Use conversation history +- Analyze: content type, complexity, stakeholder needs, risk level, and creative potential + +#### Smart Selection + +1. Analyze context: Content type, complexity, stakeholder needs, risk level, creative potential +2. Parse descriptions: Understand each method's purpose from the rich descriptions in CSV +3. Select 5 methods: Choose methods that best match the context based on their descriptions +4. Balance approach: Include mix of foundational and specialized techniques as appropriate + +--- + +### Step 2: Present Options and Handle Responses + +#### Display Format + +``` +**Advanced Elicitation Options** +_If party mode is active, agents will join in._ +Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed: + +1. [Method Name] +2. [Method Name] +3. [Method Name] +4. [Method Name] +5. [Method Name] +r. Reshuffle the list with 5 new options +a. List all methods with descriptions +x. Proceed / No Further Actions +``` + +#### Response Handling + +**Case 1-5 (User selects a numbered method):** + +- Execute the selected method using its description from the CSV +- Adapt the method's complexity and output format based on the current context +- Apply the method creatively to the current section content being enhanced +- Display the enhanced version showing what the method revealed or improved +- **CRITICAL:** Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response. +- **CRITICAL:** ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to follow the instructions given by the user. +- **CRITICAL:** Re-present the same 1-5,r,x prompt to allow additional elicitations + +**Case r (Reshuffle):** + +- Select 5 random methods from methods.csv, present new list with same prompt format +- When selecting, try to think and pick a diverse set of methods covering different categories and approaches, with 1 and 2 being potentially the most useful for the document or section being discovered + +**Case x (Proceed):** + +- Complete elicitation and proceed +- Return the fully enhanced content back to create-doc.md +- The enhanced content becomes the final version for that section +- Signal completion back to create-doc.md to continue with next section + +**Case a (List All):** + +- List all methods with their descriptions from the CSV in a compact table +- Allow user to select any method by name or number from the full list +- After selection, execute the method as described in the Case 1-5 above + +**Case: Direct Feedback:** + +- Apply changes to current section content and re-present choices + +**Case: Multiple Numbers:** + +- Execute methods in sequence on the content, then re-offer choices + +--- + +### Step 3: Execution Guidelines + +- **Method execution:** Use the description from CSV to understand and apply each method +- **Output pattern:** Use the pattern as a flexible guide (e.g., "paths -> evaluation -> selection") +- **Dynamic adaptation:** Adjust complexity based on content needs (simple to sophisticated) +- **Creative application:** Interpret methods flexibly based on context while maintaining pattern consistency +- Focus on actionable insights +- **Stay relevant:** Tie elicitation to specific content being analyzed (the current section from the document being created unless user indicates otherwise) +- **Identify personas:** For single or multi-persona methods, clearly identify viewpoints, and use party members if available in memory already +- **Critical loop behavior:** Always re-offer the 1-5,r,a,x choices after each method execution +- Continue until user selects 'x' to proceed with enhanced content, confirm or ask the user what should be accepted from the session +- Each method application builds upon previous enhancements +- **Content preservation:** Track all enhancements made during elicitation +- **Iterative enhancement:** Each selected method (1-5) should: + 1. Apply to the current enhanced version of the content + 2. Show the improvements made + 3. Return to the prompt for additional elicitations or completion diff --git a/src/core/tasks/bmad-editorial-review-prose/SKILL.md b/src/core/tasks/bmad-editorial-review-prose/SKILL.md new file mode 100644 index 000000000..ccd895e23 --- /dev/null +++ b/src/core/tasks/bmad-editorial-review-prose/SKILL.md @@ -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). diff --git a/src/core/tasks/bmad-editorial-review-prose/bmad-skill-manifest.yaml b/src/core/tasks/bmad-editorial-review-prose/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/tasks/bmad-editorial-review-prose/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/tasks/bmad-editorial-review-prose/workflow.md b/src/core/tasks/bmad-editorial-review-prose/workflow.md new file mode 100644 index 000000000..42db68710 --- /dev/null +++ b/src/core/tasks/bmad-editorial-review-prose/workflow.md @@ -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) diff --git a/src/core/tasks/bmad-editorial-review-structure/SKILL.md b/src/core/tasks/bmad-editorial-review-structure/SKILL.md new file mode 100644 index 000000000..917e04c62 --- /dev/null +++ b/src/core/tasks/bmad-editorial-review-structure/SKILL.md @@ -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). diff --git a/src/core/tasks/bmad-editorial-review-structure/bmad-skill-manifest.yaml b/src/core/tasks/bmad-editorial-review-structure/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/tasks/bmad-editorial-review-structure/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/tasks/bmad-editorial-review-structure/workflow.md b/src/core/tasks/bmad-editorial-review-structure/workflow.md new file mode 100644 index 000000000..bc6c35f73 --- /dev/null +++ b/src/core/tasks/bmad-editorial-review-structure/workflow.md @@ -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) diff --git a/src/core/tasks/bmad-help/SKILL.md b/src/core/tasks/bmad-help/SKILL.md new file mode 100644 index 000000000..fbd6ff60e --- /dev/null +++ b/src/core/tasks/bmad-help/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-help +description: 'Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/core/tasks/bmad-help/bmad-skill-manifest.yaml b/src/core/tasks/bmad-help/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/tasks/bmad-help/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/tasks/help.md b/src/core/tasks/bmad-help/workflow.md similarity index 88% rename from src/core/tasks/help.md rename to src/core/tasks/bmad-help/workflow.md index f07cbc062..7cea8b7ff 100644 --- a/src/core/tasks/help.md +++ b/src/core/tasks/bmad-help/workflow.md @@ -1,7 +1,3 @@ ---- -name: help -description: Get unstuck by showing what workflow steps come next or answering questions about what to do ---- # Task: BMAD Help @@ -19,18 +15,24 @@ description: Get unstuck by showing what workflow steps come next or answering q ### 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 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... ``` diff --git a/src/core/tasks/bmad-index-docs/SKILL.md b/src/core/tasks/bmad-index-docs/SKILL.md new file mode 100644 index 000000000..30e451a62 --- /dev/null +++ b/src/core/tasks/bmad-index-docs/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-index-docs +description: 'Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/core/tasks/bmad-index-docs/bmad-skill-manifest.yaml b/src/core/tasks/bmad-index-docs/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/tasks/bmad-index-docs/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/tasks/bmad-index-docs/workflow.md b/src/core/tasks/bmad-index-docs/workflow.md new file mode 100644 index 000000000..b500cf984 --- /dev/null +++ b/src/core/tasks/bmad-index-docs/workflow.md @@ -0,0 +1,61 @@ +# Index Docs + +**Goal:** Generate or update an index.md to reference all docs in a target folder. + + +## EXECUTION + +### Step 1: Scan Directory + +- List all files and subdirectories in the target location + +### Step 2: Group Content + +- Organize files by type, purpose, or subdirectory + +### Step 3: Generate Descriptions + +- Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the filename + +### Step 4: Create/Update Index + +- Write or update index.md with organized file listings + + +## OUTPUT FORMAT + +```markdown +# Directory Index + +## Files + +- **[filename.ext](./filename.ext)** - Brief description +- **[another-file.ext](./another-file.ext)** - Brief description + +## Subdirectories + +### subfolder/ + +- **[file1.ext](./subfolder/file1.ext)** - Brief description +- **[file2.ext](./subfolder/file2.ext)** - Brief description + +### another-folder/ + +- **[file3.ext](./another-folder/file3.ext)** - Brief description +``` + + +## HALT CONDITIONS + +- HALT if target directory does not exist or is inaccessible +- HALT if user does not have write permissions to create index.md + + +## VALIDATION + +- Use relative paths starting with ./ +- Group similar files together +- Read file contents to generate accurate descriptions - don't guess from filenames +- Keep descriptions concise but informative (3-10 words) +- Sort alphabetically within groups +- Skip hidden files (starting with .) unless specified diff --git a/src/core/tasks/bmad-review-adversarial-general/SKILL.md b/src/core/tasks/bmad-review-adversarial-general/SKILL.md new file mode 100644 index 000000000..88f5b2fa1 --- /dev/null +++ b/src/core/tasks/bmad-review-adversarial-general/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-review-adversarial-general +description: 'Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/core/tasks/bmad-review-adversarial-general/bmad-skill-manifest.yaml b/src/core/tasks/bmad-review-adversarial-general/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/tasks/bmad-review-adversarial-general/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/tasks/bmad-review-adversarial-general/workflow.md b/src/core/tasks/bmad-review-adversarial-general/workflow.md new file mode 100644 index 000000000..8290ff16d --- /dev/null +++ b/src/core/tasks/bmad-review-adversarial-general/workflow.md @@ -0,0 +1,32 @@ +# Adversarial Review (General) + +**Goal:** Cynically review content and produce findings. + +**Your Role:** You are a cynical, jaded reviewer with zero patience for sloppy work. The content was submitted by a clueless weasel and you expect to find problems. Be skeptical of everything. Look for what's missing, not just what's wrong. Use a precise, professional tone — no profanity or personal attacks. + +**Inputs:** +- **content** — Content to review: diff, spec, story, doc, or any artifact +- **also_consider** (optional) — Areas to keep in mind during review alongside normal adversarial analysis + + +## EXECUTION + +### Step 1: Receive Content + +- Load the content to review from provided input or context +- If content to review is empty, ask for clarification and abort +- Identify content type (diff, branch, uncommitted changes, document, etc.) + +### Step 2: Adversarial Analysis + +Review with extreme skepticism — assume problems exist. Find at least ten issues to fix or improve in the provided content. + +### Step 3: Present Findings + +Output findings as a Markdown list (descriptions only). + + +## HALT CONDITIONS + +- HALT if zero findings — this is suspicious, re-analyze or ask for guidance +- HALT if content is empty or unreadable diff --git a/src/core/tasks/bmad-review-edge-case-hunter/SKILL.md b/src/core/tasks/bmad-review-edge-case-hunter/SKILL.md new file mode 100644 index 000000000..872fff46f --- /dev/null +++ b/src/core/tasks/bmad-review-edge-case-hunter/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-review-edge-case-hunter +description: 'Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven.' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/core/tasks/bmad-review-edge-case-hunter/bmad-skill-manifest.yaml b/src/core/tasks/bmad-review-edge-case-hunter/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/tasks/bmad-review-edge-case-hunter/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/tasks/bmad-review-edge-case-hunter/workflow.md b/src/core/tasks/bmad-review-edge-case-hunter/workflow.md new file mode 100644 index 000000000..4d21c3961 --- /dev/null +++ b/src/core/tasks/bmad-review-edge-case-hunter/workflow.md @@ -0,0 +1,62 @@ +# Edge Case Hunter Review + +**Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling. +When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff. +When no diff is provided (full file or function), treat the entire provided content as the scope. +Ignore the rest of the codebase unless the provided content explicitly references external functions. + +**Inputs:** +- **content** — Content to review: diff, full file, or function +- **also_consider** (optional) — Areas to keep in mind during review alongside normal edge-case analysis + +**MANDATORY: Execute steps in the Execution section IN EXACT ORDER. DO NOT skip steps or change the sequence. When a halt condition triggers, follow its specific instruction exactly. Each action within a step is a REQUIRED action to complete that step.** + +**Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition. Report ONLY paths and conditions that lack handling — discard handled ones silently. Do NOT editorialize or add filler — findings only.** + + +## EXECUTION + +### Step 1: Receive Content + +- Load the content to review strictly from provided input +- If content is empty, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop +- Identify content type (diff, full file, or function) to determine scope rules + +### Step 2: Exhaustive Path Analysis + +**Walk every branching path and boundary condition within scope — report only unhandled ones.** + +- If `also_consider` input was provided, incorporate those areas into the analysis +- Walk all branching paths: control flow (conditionals, loops, error handlers, early returns) and domain boundaries (where values, states, or conditions transition). Derive the relevant edge classes from the content itself — don't rely on a fixed checklist. Examples: missing else/default, unguarded inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps +- For each path: determine whether the content handles it +- Collect only the unhandled paths as findings — discard handled ones silently + +### Step 3: Validate Completeness + +- Revisit every edge class from Step 2 — e.g., missing else/default, null/empty inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps +- Add any newly found unhandled paths to findings; discard confirmed-handled ones + +### Step 4: Present Findings + +Output findings as a JSON array following the Output Format specification exactly. + + +## OUTPUT FORMAT + +Return ONLY a valid JSON array of objects. Each object must contain exactly these four fields and nothing else: + +```json +[{ + "location": "file:start-end (or file:line when single line, or file:hunk when exact line unavailable)", + "trigger_condition": "one-line description (max 15 words)", + "guard_snippet": "minimal code sketch that closes the gap (single-line escaped string, no raw newlines or unescaped quotes)", + "potential_consequence": "what could actually go wrong (max 15 words)" +}] +``` + +No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when no unhandled paths are found. + + +## HALT CONDITIONS + +- If content is empty or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop diff --git a/src/core/tasks/bmad-shard-doc/SKILL.md b/src/core/tasks/bmad-shard-doc/SKILL.md new file mode 100644 index 000000000..2bd4404d4 --- /dev/null +++ b/src/core/tasks/bmad-shard-doc/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-shard-doc +description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/core/tasks/bmad-shard-doc/bmad-skill-manifest.yaml b/src/core/tasks/bmad-shard-doc/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/tasks/bmad-shard-doc/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/tasks/bmad-shard-doc/workflow.md b/src/core/tasks/bmad-shard-doc/workflow.md new file mode 100644 index 000000000..3304991db --- /dev/null +++ b/src/core/tasks/bmad-shard-doc/workflow.md @@ -0,0 +1,100 @@ +# Shard Document + +**Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`. + +## CRITICAL RULES + +- MANDATORY: Execute ALL steps in the EXECUTION 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 + +## EXECUTION + +### Step 1: Get Source Document + +- Ask user for the source document path if not provided already +- Verify file exists and is accessible +- Verify file is markdown format (.md extension) +- If file not found or not markdown: HALT with error message + +### Step 2: Get Destination Folder + +- Determine default destination: same location as source file, folder named after source file without .md extension + - Example: `/path/to/architecture.md` --> `/path/to/architecture/` +- Ask user for the destination folder path (`[y]` to confirm use of default: `[suggested-path]`, else enter a new path) +- If user accepts default: use the suggested destination path +- If user provides custom path: use the custom destination path +- Verify destination folder exists or can be created +- Check write permissions for destination +- If permission denied: HALT with error message + +### Step 3: Execute Sharding + +- Inform user that sharding is beginning +- Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]` +- Capture command output and any errors +- If command fails: HALT and display error to user + +### Step 4: Verify Output + +- Check that destination folder contains sharded files +- Verify index.md was created in destination folder +- Count the number of files created +- If no files created: HALT with error message + +### Step 5: Report Completion + +- Display completion report to user including: + - Source document path and name + - Destination folder path + - Number of section files created + - Confirmation that index.md was created + - Any tool output or warnings +- Inform user that sharding completed successfully + +### Step 6: Handle Original Document + +> **Critical:** Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion. + +Present user with options for the original document: + +> What would you like to do with the original document `[source-document-name]`? +> +> Options: +> - `[d]` Delete - Remove the original (recommended - shards can always be recombined) +> - `[m]` Move to archive - Move original to a backup/archive location +> - `[k]` Keep - Leave original in place (NOT recommended - defeats sharding purpose) +> +> Your choice (d/m/k): + +#### If user selects `d` (delete) + +- Delete the original source document file +- Confirm deletion to user: "Original document deleted: [source-document-path]" +- Note: The document can be reconstructed from shards by concatenating all section files in order + +#### If user selects `m` (move) + +- Determine default archive location: same directory as source, in an `archive` subfolder + - Example: `/path/to/architecture.md` --> `/path/to/archive/architecture.md` +- Ask: Archive location (`[y]` to use default: `[default-archive-path]`, or provide custom path) +- If user accepts default: use default archive path +- If user provides custom path: use custom archive path +- Create archive directory if it does not exist +- Move original document to archive location +- Confirm move to user: "Original document moved to: [archive-path]" + +#### If user selects `k` (keep) + +- Display warning to user: + - Keeping both original and sharded versions is NOT recommended + - The discover_inputs protocol may load the wrong version + - Updates to one will not reflect in the other + - Duplicate content taking up space + - Consider deleting or archiving the original document +- Confirm user choice: "Original document kept at: [source-document-path]" + +## HALT CONDITIONS + +- HALT if npx command fails or produces no output files diff --git a/src/core/tasks/editorial-review-prose.xml b/src/core/tasks/editorial-review-prose.xml deleted file mode 100644 index deb53570e..000000000 --- a/src/core/tasks/editorial-review-prose.xml +++ /dev/null @@ -1,102 +0,0 @@ - - - Review text for communication issues that impede comprehension and output suggested fixes in a three-column table - - - - - - - - - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER - DO NOT skip steps or change the sequence - HALT immediately when halt-conditions are met - Each action xml tag within step xml tag is a REQUIRED action to complete that step - - 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 - - CONTENT IS SACROSANCT: Never challenge ideas—only clarify how they're expressed. - - - Minimal intervention: Apply the smallest fix that achieves clarity - Preserve structure: Fix prose within existing structure, never restructure - Skip code/markup: Detect and skip code blocks, frontmatter, structural markup - When uncertain: Flag with a query rather than suggesting a definitive change - Deduplicate: Same issue in multiple places = one entry with locations listed - No conflicts: Merge overlapping fixes into single entries - 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. - - - - - Check if content is empty or contains 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") - 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 - - - - 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 parameter - Prioritize: unambiguous references, consistent terminology, explicit structure, no hedging - Prioritize: clarity, flow, readability, natural progression - - - - 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 - - - - Output a three-column markdown table with all suggested fixes - Output: "No editorial issues identified" - - - | Original Text | Revised Text | Changes | - |---------------|--------------|---------| - | The exact original passage | The suggested revision | Brief explanation of what changed and why | - - - - | 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 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) - - - \ No newline at end of file diff --git a/src/core/tasks/editorial-review-structure.xml b/src/core/tasks/editorial-review-structure.xml deleted file mode 100644 index 426dc3c8c..000000000 --- a/src/core/tasks/editorial-review-structure.xml +++ /dev/null @@ -1,209 +0,0 @@ - - - - Review document structure and propose substantive changes - to improve clarity and flow-run this BEFORE copy editing - - - - - - - - - - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER - DO NOT skip steps or change the sequence - HALT immediately when halt-conditions are met - Each action xml tag within step xml tag is a REQUIRED action to complete that step - 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 - - 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. - - 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. - - 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 - - - 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) - - - - 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 - - - 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) - - - Abstract to Concrete: Definition to Context to Implementation/Example - Scaffolding: Complex ideas built on established foundations - - - 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 - - - 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 - - - - - - Check if content is empty or contains 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") - 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 - - - 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) - - - 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? - 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 - - - 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 - Assess pacing: Is there enough - whitespace and visual variety to maintain attention? - - - 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 - Flag with warning: "This cut may impact - reader comprehension/engagement" - - - Output document summary (purpose, audience, reader_type, current length) - Output the recommendation list in priority order - Output estimated total reduction if all recommendations accepted - Output: "No substantive changes recommended-document structure is sound" - - ## 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 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) - - \ No newline at end of file diff --git a/src/core/tasks/index-docs.xml b/src/core/tasks/index-docs.xml deleted file mode 100644 index 30e060921..000000000 --- a/src/core/tasks/index-docs.xml +++ /dev/null @@ -1,65 +0,0 @@ - - - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER - DO NOT skip steps or change the sequence - HALT immediately when halt-conditions are met - Each action xml tag within step xml tag is a REQUIRED action to complete that step - Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution - - - - - List all files and subdirectories in the target location - - - - Organize files by type, purpose, or subdirectory - - - - Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the - filename - - - - Write or update index.md with organized file listings - - - - - - # Directory Index - - ## Files - - - **[filename.ext](./filename.ext)** - Brief description - - **[another-file.ext](./another-file.ext)** - Brief description - - ## Subdirectories - - ### subfolder/ - - - **[file1.ext](./subfolder/file1.ext)** - Brief description - - **[file2.ext](./subfolder/file2.ext)** - Brief description - - ### another-folder/ - - - **[file3.ext](./another-folder/file3.ext)** - Brief description - - - - - HALT if target directory does not exist or is inaccessible - HALT if user does not have write permissions to create index.md - - - - Use relative paths starting with ./ - Group similar files together - Read file contents to generate accurate descriptions - don't guess from filenames - Keep descriptions concise but informative (3-10 words) - Sort alphabetically within groups - Skip hidden files (starting with .) unless specified - - \ No newline at end of file diff --git a/src/core/tasks/review-adversarial-general.xml b/src/core/tasks/review-adversarial-general.xml deleted file mode 100644 index 421719bb5..000000000 --- a/src/core/tasks/review-adversarial-general.xml +++ /dev/null @@ -1,48 +0,0 @@ - - - - Cynically review content and produce findings - - - - - - - - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER - DO NOT skip steps or change the sequence - HALT immediately when halt-conditions are met - Each action xml tag within step xml tag is a REQUIRED action to complete that step - - You are a cynical, jaded reviewer with zero patience for sloppy work - The content was submitted by a clueless weasel and you expect to find problems - Be skeptical of everything - Look for what's missing, not just what's wrong - Use a precise, professional tone - no profanity or personal attacks - - - - - Load the content to review from provided input or context - If content to review is empty, ask for clarification and abort task - Identify content type (diff, branch, uncommitted changes, document, etc.) - - - - Review with extreme skepticism - assume problems exist - Find at least ten issues to fix or improve in the provided content - - - - Output findings as a Markdown list (descriptions only) - - - - - HALT if zero findings - this is suspicious, re-analyze or ask for guidance - HALT if content is empty or unreadable - - - \ No newline at end of file diff --git a/src/core/tasks/shard-doc.xml b/src/core/tasks/shard-doc.xml deleted file mode 100644 index 1dc8fe80e..000000000 --- a/src/core/tasks/shard-doc.xml +++ /dev/null @@ -1,108 +0,0 @@ - - Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool - - - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER - DO NOT skip steps or change the sequence - HALT immediately when halt-conditions are met - Each action xml tag within step xml tag is a REQUIRED action to complete that step - Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution - - - - Uses `npx @kayvan/markdown-tree-parser` to automatically shard documents by level 2 headings and generate an index - - - - - Ask user for the source document path if not provided already - Verify file exists and is accessible - Verify file is markdown format (.md extension) - HALT with error message - - - - Determine default destination: same location as source file, folder named after source file without .md extension - Example: /path/to/architecture.md → /path/to/architecture/ - Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path) - Use the suggested destination path - Use the custom destination path - Verify destination folder exists or can be created - Check write permissions for destination - HALT with error message - - - - Inform user that sharding is beginning - Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]` - Capture command output and any errors - HALT and display error to user - - - - Check that destination folder contains sharded files - Verify index.md was created in destination folder - Count the number of files created - HALT with error message - - - - Display completion report to user including: - - Source document path and name - - Destination folder path - - Number of section files created - - Confirmation that index.md was created - - Any tool output or warnings - Inform user that sharding completed successfully - - - - Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion - Present user with options for the original document: - - What would you like to do with the original document `[source-document-name]`? - - Options: - [d] Delete - Remove the original (recommended - shards can always be recombined) - [m] Move to archive - Move original to a backup/archive location - [k] Keep - Leave original in place (NOT recommended - defeats sharding purpose) - - Your choice (d/m/k): - - - Delete the original source document file - Confirm deletion to user: "✓ Original document deleted: [source-document-path]" - The document can be reconstructed from shards by concatenating all section files in order - - - - Determine default archive location: same directory as source, in an "archive" subfolder - Example: /path/to/architecture.md → /path/to/archive/architecture.md - Archive location ([y] to use default: [default-archive-path], or provide custom path): - Use default archive path - Use custom archive path - Create archive directory if it doesn't exist - Move original document to archive location - Confirm move to user: "✓ Original document moved to: [archive-path]" - - - - Display warning to user: - ⚠️ WARNING: Keeping both original and sharded versions is NOT recommended. - - This creates confusion because: - - The discover_inputs protocol may load the wrong version - - Updates to one won't reflect in the other - - You'll have duplicate content taking up space - - Consider deleting or archiving the original document. - Confirm user choice: "Original document kept at: [source-document-path]" - - - - - - HALT if npx command fails or produces no output files - - \ No newline at end of file diff --git a/src/core/tasks/workflow.xml b/src/core/tasks/workflow.xml deleted file mode 100644 index 536c9d8e7..000000000 --- a/src/core/tasks/workflow.xml +++ /dev/null @@ -1,235 +0,0 @@ - - Execute given workflow by loading its configuration, following instructions, and producing output - - - Always read COMPLETE files - NEVER use offset/limit when reading any workflow related files - Instructions are MANDATORY - either as file path, steps or embedded list in YAML, XML or markdown - Execute ALL steps in instructions IN EXACT ORDER - Save to template output file after EVERY "template-output" tag - NEVER skip a step - YOU are responsible for every steps execution without fail or excuse - - - - Steps execute in exact numerical order (1, 2, 3...) - Optional steps: Ask user unless #yolo mode active - Template-output tags: Save content, discuss with the user the section completed, and NEVER proceed until the users indicates - to proceed (unless YOLO mode has been activated) - - - - - - Read workflow.yaml from provided path - Load config_source (REQUIRED for all modules) - Load external config from config_source path - Resolve all {config_source}: references with values from config - Resolve system variables (date:system-generated) and paths ({project-root}, {installed_path}) - Ask user for input of any variables that are still unknown - - - - Instructions: Read COMPLETE file from path OR embedded list (REQUIRED) - If template path → Read COMPLETE template file - If validation path → Note path for later loading when needed - If template: false → Mark as action-workflow (else template-workflow) - Data files (csv, json) → Store paths only, load on-demand when instructions reference them - - - - Resolve default_output_file path with all variables and {{date}} - Create output directory if doesn't exist - If template-workflow → Write template to output file with placeholders - If action-workflow → Skip file creation - - - - - For each step in instructions: - - - If optional="true" and NOT #yolo → Ask user to include - If if="condition" → Evaluate condition - If for-each="item" → Repeat step for each item - If repeat="n" → Repeat step n times - - - - Process step instructions (markdown or XML tags) - Replace {{variables}} with values (ask user if unknown) - - action xml tag → Perform the action - check if="condition" xml tag → Conditional block wrapping actions (requires closing </check>) - ask xml tag → Prompt user and WAIT for response - invoke-workflow xml tag → Execute another workflow with given inputs and the workflow.xml runner - invoke-task xml tag → Execute specified task - invoke-protocol name="protocol_name" xml tag → Execute reusable protocol from protocols section - goto step="x" → Jump to specified step - - - - - - Generate content for this section - Save to file (Write first time, Edit subsequent) - Display generated content - [a] Advanced Elicitation, [c] Continue, [p] Party-Mode, [y] YOLO the rest of this document only. WAIT for response. - Start the advanced elicitation workflow {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml - - - Continue to next step - - - Start the party-mode workflow {project-root}/_bmad/core/workflows/party-mode/workflow.md - - - Enter #yolo mode for the rest of the workflow - - - - - - - If no special tags and NOT #yolo: - Continue to next step? (y/n/edit) - - - - - Confirm document saved to output path - Report workflow completion - - - - - Full user interaction and confirmation of EVERY step at EVERY template output - NO EXCEPTIONS except yolo MODE - Skip all confirmations and elicitation, minimize prompts and try to produce all of the workflow automatically by - simulating the remaining discussions with an simulated expert user - - - - - step n="X" goal="..." - Define step with number and goal - optional="true" - Step can be skipped - if="condition" - Conditional execution - for-each="collection" - Iterate over items - repeat="n" - Repeat n times - - - action - Required action to perform - action if="condition" - Single conditional action (inline, no closing tag needed) - check if="condition">...</check> - Conditional block wrapping multiple items (closing tag required) - ask - Get user input (ALWAYS wait for response before continuing) - goto - Jump to another step - invoke-workflow - Call another workflow - invoke-task - Call a task - invoke-protocol - Execute a reusable protocol (e.g., discover_inputs) - - - template-output - Save content checkpoint - critical - Cannot be skipped - example - Show example output - - - - - - Intelligently load project files (whole or sharded) based on workflow's input_file_patterns configuration - - Only execute if workflow.yaml contains input_file_patterns section - - - - Read input_file_patterns from loaded workflow.yaml - For each pattern group (prd, architecture, epics, etc.), note the load_strategy if present - - - - For each pattern in input_file_patterns: - - - - Determine load_strategy from pattern config (defaults to FULL_LOAD if not specified) - - - Load ALL files in sharded directory - used for PRD, Architecture, UX, brownfield docs - Use glob pattern to find ALL .md files (e.g., "{output_folder}/*architecture*/*.md") - Load EVERY matching file completely - Concatenate content in logical order (index.md first if exists, then alphabetical) - Store in variable: {pattern_name_content} - - - - Load specific shard using template variable - example: used for epics with {{epic_num}} - Check for template variables in sharded_single pattern (e.g., {{epic_num}}) - If variable undefined, ask user for value OR infer from context - Resolve template to specific file path - Load that specific file - Store in variable: {pattern_name_content} - - - - Load index.md, analyze structure and description of each doc in the index, then intelligently load relevant docs - DO NOT BE LAZY - use best judgment to load documents that might have relevant information, even if only a 5% chance - Load index.md from sharded directory - Parse table of contents, links, section headers - Analyze workflow's purpose and objective - Identify which linked/referenced documents are likely relevant - If workflow is about authentication and index shows "Auth Overview", "Payment Setup", "Deployment" → Load auth - docs, consider deployment docs, skip payment - Load all identified relevant documents - Store combined content in variable: {pattern_name_content} - When in doubt, LOAD IT - context is valuable, being thorough is better than missing critical info - - Mark pattern as RESOLVED, skip to next pattern - - - - - - Attempt glob match on 'whole' pattern (e.g., "{output_folder}/*prd*.md") - - Load ALL matching files completely (no offset/limit) - Store content in variable: {pattern_name_content} (e.g., {prd_content}) - Mark pattern as RESOLVED, skip to next pattern - - - - - - - Set {pattern_name_content} to empty string - Note in session: "No {pattern_name} files found" (not an error, just unavailable, offer use change to provide) - - - - - - List all loaded content variables with file counts - - ✓ Loaded {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ... - ✓ Loaded {architecture_content} from 1 file: Architecture.md - ✓ Loaded {epics_content} from selective load: epics/epic-3.md - ○ No ux_design files found - - This gives workflow transparency into what context is available - - - - - - - - - • This is the complete workflow execution engine - • You MUST Follow instructions exactly as written - • The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml - • You MUST have already loaded and processed: {installed_path}/workflow.yaml - • This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context - • YOU ARE FACILITATING A CONVERSATION With a user to produce a final document step by step. The whole process is meant to be - collaborative helping the user flesh out their ideas. Do not rush or optimize and skip any section. - - - \ No newline at end of file diff --git a/src/core/workflows/advanced-elicitation/workflow.xml b/src/core/workflows/advanced-elicitation/workflow.xml deleted file mode 100644 index ea7395e41..000000000 --- a/src/core/workflows/advanced-elicitation/workflow.xml +++ /dev/null @@ -1,117 +0,0 @@ - - - MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER - DO NOT skip steps or change the sequence - HALT immediately when halt-conditions are met - Each action xml tag within step xml tag is a REQUIRED action to complete that step - Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution - YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language` - - - - When called during template workflow processing: - 1. Receive or review the current section content that was just generated or - 2. Apply elicitation methods iteratively to enhance that specific content - 3. Return the enhanced version back when user selects 'x' to proceed and return back - 4. The enhanced content replaces the original section content in the output document - - - - - Load and read {{methods}} and {{agent-party}} - - - category: Method grouping (core, structural, risk, etc.) - method_name: Display name for the method - description: Rich explanation of what the method does, when to use it, and why it's valuable - output_pattern: Flexible flow guide using → arrows (e.g., "analysis → insights → action") - - - - Use conversation history - Analyze: content type, complexity, stakeholder needs, risk level, and creative potential - - - - 1. Analyze context: Content type, complexity, stakeholder needs, risk level, creative potential - 2. Parse descriptions: Understand each method's purpose from the rich descriptions in CSV - 3. Select 5 methods: Choose methods that best match the context based on their descriptions - 4. Balance approach: Include mix of foundational and specialized techniques as appropriate - - - - - - - **Advanced Elicitation Options (If you launched Party Mode, they will participate randomly)** - Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed: - - 1. [Method Name] - 2. [Method Name] - 3. [Method Name] - 4. [Method Name] - 5. [Method Name] - r. Reshuffle the list with 5 new options - a. List all methods with descriptions - x. Proceed / No Further Actions - - - - - Execute the selected method using its description from the CSV - Adapt the method's complexity and output format based on the current context - Apply the method creatively to the current section content being enhanced - Display the enhanced version showing what the method revealed or improved - CRITICAL: Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response. - CRITICAL: ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to - follow the instructions given by the user. - CRITICAL: Re-present the same 1-5,r,x prompt to allow additional elicitations - - - Select 5 random methods from advanced-elicitation-methods.csv, present new list with same prompt format - When selecting, try to think and pick a diverse set of methods covering different categories and approaches, with 1 and 2 being - potentially the most useful for the document or section being discovered - - - Complete elicitation and proceed - Return the fully enhanced content back to create-doc.md - The enhanced content becomes the final version for that section - Signal completion back to create-doc.md to continue with next section - - - List all methods with their descriptions from the CSV in a compact table - Allow user to select any method by name or number from the full list - After selection, execute the method as described in the n="1-5" case above - - - Apply changes to current section content and re-present choices - - - Execute methods in sequence on the content, then re-offer choices - - - - - - Method execution: Use the description from CSV to understand and apply each method - Output pattern: Use the pattern as a flexible guide (e.g., "paths → evaluation → selection") - Dynamic adaptation: Adjust complexity based on content needs (simple to sophisticated) - Creative application: Interpret methods flexibly based on context while maintaining pattern consistency - Focus on actionable insights - Stay relevant: Tie elicitation to specific content being analyzed (the current section from the document being created unless user - indicates otherwise) - Identify personas: For single or multi-persona methods, clearly identify viewpoints, and use party members if available in memory - already - Critical loop behavior: Always re-offer the 1-5,r,a,x choices after each method execution - Continue until user selects 'x' to proceed with enhanced content, confirm or ask the user what should be accepted from the session - Each method application builds upon previous enhancements - Content preservation: Track all enhancements made during elicitation - Iterative enhancement: Each selected method (1-5) should: - 1. Apply to the current enhanced version of the content - 2. Show the improvements made - 3. Return to the prompt for additional elicitations or completion - - - \ No newline at end of file diff --git a/src/core/workflows/bmad-brainstorming/SKILL.md b/src/core/workflows/bmad-brainstorming/SKILL.md new file mode 100644 index 000000000..0d0d55663 --- /dev/null +++ b/src/core/workflows/bmad-brainstorming/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-brainstorming +description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/core/workflows/bmad-brainstorming/bmad-skill-manifest.yaml b/src/core/workflows/bmad-brainstorming/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/workflows/bmad-brainstorming/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/workflows/brainstorming/brain-methods.csv b/src/core/workflows/bmad-brainstorming/brain-methods.csv similarity index 100% rename from src/core/workflows/brainstorming/brain-methods.csv rename to src/core/workflows/bmad-brainstorming/brain-methods.csv diff --git a/src/core/workflows/brainstorming/steps/step-01-session-setup.md b/src/core/workflows/bmad-brainstorming/steps/step-01-session-setup.md similarity index 74% rename from src/core/workflows/brainstorming/steps/step-01-session-setup.md rename to src/core/workflows/bmad-brainstorming/steps/step-01-session-setup.md index 7e1cb2cdb..cf970e3f7 100644 --- a/src/core/workflows/brainstorming/steps/step-01-session-setup.md +++ b/src/core/workflows/bmad-brainstorming/steps/step-01-session-setup.md @@ -29,23 +29,30 @@ Initialize the brainstorming workflow by detecting continuation state and settin ## INITIALIZATION SEQUENCE: -### 1. Check for Existing Workflow +### 1. Check for Existing Sessions -First, check if the output document already exists: +First, check the brainstorming sessions folder for existing sessions: -- Look for file at `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` -- If exists, read the complete file including frontmatter -- If not exists, this is a fresh workflow +- List all files in `{output_folder}/brainstorming/` +- **DO NOT read any file contents** - only list filenames +- If files exist, identify the most recent by date/time in the filename +- If no files exist, this is a fresh workflow -### 2. Handle Continuation (If Document Exists) +### 2. Handle Existing Sessions (If Files Found) -If the document exists and has frontmatter with `stepsCompleted`: +If existing session files are found: -- **STOP here** and load `./step-01b-continue.md` immediately -- Do not proceed with any initialization tasks -- Let step-01b handle the continuation logic +- Display the most recent session filename (do NOT read its content) +- Ask the user: "Found existing session: `[filename]`. Would you like to: + **[1]** Continue this session + **[2]** Start a new session + **[3]** See all existing sessions" -### 3. Fresh Workflow Setup (If No Document) +- If user selects **[1]** (continue): Set `{brainstorming_session_output_file}` to that file path and load `./step-01b-continue.md` +- If user selects **[2]** (new): Generate new filename with current date/time and proceed to step 3 +- If user selects **[3]** (see all): List all session filenames and ask which to continue or if new + +### 3. Fresh Workflow Setup (If No Files or User Chooses New) If no document exists or no `stepsCompleted` in frontmatter: @@ -55,10 +62,10 @@ Create the brainstorming session document: ```bash # Create directory if needed -mkdir -p "$(dirname "{output_folder}/brainstorming/brainstorming-session-{{date}}.md")" +mkdir -p "$(dirname "{brainstorming_session_output_file}")" # Initialize from template -cp "{template_path}" "{output_folder}/brainstorming/brainstorming-session-{{date}}.md" +cp "{template_path}" "{brainstorming_session_output_file}" ``` #### B. Context File Check and Loading @@ -134,7 +141,7 @@ _[Content based on conversation about session parameters and facilitator approac ## APPEND TO DOCUMENT: -When user selects approach, append the session overview content directly to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` using the structure from above. +When user selects approach, append the session overview content directly to `{brainstorming_session_output_file}` using the structure from above. ### E. Continue to Technique Selection @@ -152,7 +159,7 @@ Which approach appeals to you most? (Enter 1-4)" #### When user selects approach number: -- **Append initial session overview to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`** +- **Append initial session overview to `{brainstorming_session_output_file}`** - **Update frontmatter:** `stepsCompleted: [1]`, `selected_approach: '[selected approach]'` - **Load the appropriate step-02 file** based on selection @@ -167,7 +174,9 @@ After user selects approach number: ## SUCCESS METRICS: -✅ Existing workflow detected and continuation handled properly +✅ Existing sessions detected without reading file contents +✅ User prompted to continue existing session or start new +✅ Correct session file selected for continuation ✅ Fresh workflow initialized with correct document structure ✅ Session context gathered and understood clearly ✅ User's approach selection captured and routed correctly @@ -176,7 +185,9 @@ After user selects approach number: ## FAILURE MODES: -❌ Not checking for existing document before creating new one +❌ Reading file contents during session detection (wastes context) +❌ Not asking user before continuing existing session +❌ Not properly routing user's continue/new session selection ❌ Missing continuation detection leading to duplicate work ❌ Insufficient session context gathering ❌ Not properly routing user's approach selection @@ -184,7 +195,9 @@ After user selects approach number: ## SESSION SETUP PROTOCOLS: -- Always verify document existence before initialization +- Always list sessions folder WITHOUT reading file contents +- Ask user before continuing any existing session +- Only load continue step after user confirms - Load brain techniques CSV only when needed for technique presentation - Use collaborative facilitation language throughout - Maintain psychological safety for creative exploration diff --git a/src/core/workflows/brainstorming/steps/step-01b-continue.md b/src/core/workflows/bmad-brainstorming/steps/step-01b-continue.md similarity index 97% rename from src/core/workflows/brainstorming/steps/step-01b-continue.md rename to src/core/workflows/bmad-brainstorming/steps/step-01b-continue.md index 23205c0d4..9b7e5968c 100644 --- a/src/core/workflows/brainstorming/steps/step-01b-continue.md +++ b/src/core/workflows/bmad-brainstorming/steps/step-01b-continue.md @@ -35,7 +35,7 @@ Load existing document and analyze current state: **Document Analysis:** -- Read existing `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` +- Read existing `{brainstorming_session_output_file}` - Examine frontmatter for `stepsCompleted`, `session_topic`, `session_goals` - Review content to understand session progress and outcomes - Identify current stage and next logical steps diff --git a/src/core/workflows/brainstorming/steps/step-02a-user-selected.md b/src/core/workflows/bmad-brainstorming/steps/step-02a-user-selected.md similarity index 100% rename from src/core/workflows/brainstorming/steps/step-02a-user-selected.md rename to src/core/workflows/bmad-brainstorming/steps/step-02a-user-selected.md diff --git a/src/core/workflows/brainstorming/steps/step-02b-ai-recommended.md b/src/core/workflows/bmad-brainstorming/steps/step-02b-ai-recommended.md similarity index 100% rename from src/core/workflows/brainstorming/steps/step-02b-ai-recommended.md rename to src/core/workflows/bmad-brainstorming/steps/step-02b-ai-recommended.md diff --git a/src/core/workflows/brainstorming/steps/step-02c-random-selection.md b/src/core/workflows/bmad-brainstorming/steps/step-02c-random-selection.md similarity index 100% rename from src/core/workflows/brainstorming/steps/step-02c-random-selection.md rename to src/core/workflows/bmad-brainstorming/steps/step-02c-random-selection.md diff --git a/src/core/workflows/brainstorming/steps/step-02d-progressive-flow.md b/src/core/workflows/bmad-brainstorming/steps/step-02d-progressive-flow.md similarity index 100% rename from src/core/workflows/brainstorming/steps/step-02d-progressive-flow.md rename to src/core/workflows/bmad-brainstorming/steps/step-02d-progressive-flow.md diff --git a/src/core/workflows/brainstorming/steps/step-03-technique-execution.md b/src/core/workflows/bmad-brainstorming/steps/step-03-technique-execution.md similarity index 97% rename from src/core/workflows/brainstorming/steps/step-03-technique-execution.md rename to src/core/workflows/bmad-brainstorming/steps/step-03-technique-execution.md index 362bead3b..3b19dde45 100644 --- a/src/core/workflows/brainstorming/steps/step-03-technique-execution.md +++ b/src/core/workflows/bmad-brainstorming/steps/step-03-technique-execution.md @@ -1,7 +1,7 @@ # Step 3: Interactive Technique Execution and Facilitation --- -advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml' +advancedElicitationTask: 'skill:bmad-advanced-elicitation' --- ## MANDATORY EXECUTION RULES (READ FIRST): @@ -296,7 +296,7 @@ After final technique element: #### If 'C' (Move to organization): -- **Append the technique execution content to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`** +- **Append the technique execution content to `{brainstorming_session_output_file}`** - **Update frontmatter:** `stepsCompleted: [1, 2, 3]` - **Load:** `./step-04-idea-organization.md` @@ -356,7 +356,7 @@ _[Short narrative describing the user and AI collaboration journey - what made t ## APPEND TO DOCUMENT: -When user selects 'C', append the content directly to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` using the structure from above. +When user selects 'C', append the content directly to `{brainstorming_session_output_file}` using the structure from above. ## SUCCESS METRICS: diff --git a/src/core/workflows/brainstorming/steps/step-04-idea-organization.md b/src/core/workflows/bmad-brainstorming/steps/step-04-idea-organization.md similarity index 97% rename from src/core/workflows/brainstorming/steps/step-04-idea-organization.md rename to src/core/workflows/bmad-brainstorming/steps/step-04-idea-organization.md index afe56ff77..74e7faeb8 100644 --- a/src/core/workflows/brainstorming/steps/step-04-idea-organization.md +++ b/src/core/workflows/bmad-brainstorming/steps/step-04-idea-organization.md @@ -253,14 +253,14 @@ Provide final session wrap-up and forward guidance: #### If [C] Complete: -- **Append the final session content to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`** +- **Append the final session content to `{brainstorming_session_output_file}`** - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]` - Set `session_active: false` and `workflow_completed: true` - Complete workflow with positive closure message ## APPEND TO DOCUMENT: -When user selects 'C', append the content directly to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` using the structure from step 7. +When user selects 'C', append the content directly to `{brainstorming_session_output_file}` using the structure from step 7. ## SUCCESS METRICS: diff --git a/src/core/workflows/brainstorming/template.md b/src/core/workflows/bmad-brainstorming/template.md similarity index 100% rename from src/core/workflows/brainstorming/template.md rename to src/core/workflows/bmad-brainstorming/template.md diff --git a/src/core/workflows/brainstorming/workflow.md b/src/core/workflows/bmad-brainstorming/workflow.md similarity index 82% rename from src/core/workflows/brainstorming/workflow.md rename to src/core/workflows/bmad-brainstorming/workflow.md index 3190c983c..f4a6686df 100644 --- a/src/core/workflows/brainstorming/workflow.md +++ b/src/core/workflows/bmad-brainstorming/workflow.md @@ -1,6 +1,4 @@ --- -name: brainstorming -description: Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods context_file: '' # Optional context file path for project-specific guidance --- @@ -42,12 +40,13 @@ Load config from `{project-root}/_bmad/core/config.yaml` and resolve: ### Paths -- `installed_path` = `{project-root}/_bmad/core/workflows/brainstorming` -- `template_path` = `{installed_path}/template.md` -- `brain_techniques_path` = `{installed_path}/brain-methods.csv` -- `default_output_file` = `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` +- `template_path` = `./template.md` +- `brain_techniques_path` = `./brain-methods.csv` +- `brainstorming_session_output_file` = `{output_folder}/brainstorming/brainstorming-session-{{date}}-{{time}}.md` (evaluated once at workflow start) + +All steps MUST reference `{brainstorming_session_output_file}` instead of the full path pattern. - `context_file` = Optional context file path from workflow invocation for project-specific guidance -- `advancedElicitationTask` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` +- `advancedElicitationTask` = `skill:bmad-advanced-elicitation` --- diff --git a/src/core/workflows/bmad-party-mode/SKILL.md b/src/core/workflows/bmad-party-mode/SKILL.md new file mode 100644 index 000000000..bc8a92f22 --- /dev/null +++ b/src/core/workflows/bmad-party-mode/SKILL.md @@ -0,0 +1,6 @@ +--- +name: bmad-party-mode +description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests party mode.' +--- + +Follow the instructions in [workflow.md](workflow.md). diff --git a/src/core/workflows/bmad-party-mode/bmad-skill-manifest.yaml b/src/core/workflows/bmad-party-mode/bmad-skill-manifest.yaml new file mode 100644 index 000000000..d0f08abdb --- /dev/null +++ b/src/core/workflows/bmad-party-mode/bmad-skill-manifest.yaml @@ -0,0 +1 @@ +type: skill diff --git a/src/core/workflows/party-mode/steps/step-01-agent-loading.md b/src/core/workflows/bmad-party-mode/steps/step-01-agent-loading.md similarity index 100% rename from src/core/workflows/party-mode/steps/step-01-agent-loading.md rename to src/core/workflows/bmad-party-mode/steps/step-01-agent-loading.md diff --git a/src/core/workflows/party-mode/steps/step-02-discussion-orchestration.md b/src/core/workflows/bmad-party-mode/steps/step-02-discussion-orchestration.md similarity index 100% rename from src/core/workflows/party-mode/steps/step-02-discussion-orchestration.md rename to src/core/workflows/bmad-party-mode/steps/step-02-discussion-orchestration.md diff --git a/src/core/workflows/party-mode/steps/step-03-graceful-exit.md b/src/core/workflows/bmad-party-mode/steps/step-03-graceful-exit.md similarity index 99% rename from src/core/workflows/party-mode/steps/step-03-graceful-exit.md rename to src/core/workflows/bmad-party-mode/steps/step-03-graceful-exit.md index 92274a382..d3dbb7192 100644 --- a/src/core/workflows/party-mode/steps/step-03-graceful-exit.md +++ b/src/core/workflows/bmad-party-mode/steps/step-03-graceful-exit.md @@ -93,7 +93,6 @@ Final workflow completion steps: ```yaml --- stepsCompleted: [1, 2, 3] -workflowType: 'party-mode' user_name: '{{user_name}}' date: '{{date}}' agents_loaded: true diff --git a/src/core/workflows/party-mode/workflow.md b/src/core/workflows/bmad-party-mode/workflow.md similarity index 95% rename from src/core/workflows/party-mode/workflow.md rename to src/core/workflows/bmad-party-mode/workflow.md index eaec3c931..e8e13b2a1 100644 --- a/src/core/workflows/party-mode/workflow.md +++ b/src/core/workflows/bmad-party-mode/workflow.md @@ -1,6 +1,4 @@ --- -name: party-mode -description: Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations --- # Party Mode Workflow @@ -36,7 +34,6 @@ Load config from `{project-root}/_bmad/core/config.yaml` and resolve: ### Paths -- `installed_path` = `{project-root}/_bmad/core/workflows/party-mode` - `agent_manifest_path` = `{project-root}/_bmad/_config/agent-manifest.csv` - `standalone_mode` = `true` (party mode is an interactive workflow) @@ -115,7 +112,6 @@ Load step: `./steps/step-02-discussion-orchestration.md` ```yaml --- stepsCompleted: [1] -workflowType: 'party-mode' user_name: '{{user_name}}' date: '{{date}}' agents_loaded: true diff --git a/src/utility/agent-components/activation-steps.txt b/src/utility/agent-components/activation-steps.txt index 9ead0e01c..726be3e06 100644 --- a/src/utility/agent-components/activation-steps.txt +++ b/src/utility/agent-components/activation-steps.txt @@ -8,7 +8,7 @@ Remember: user's name is {user_name} {AGENT_SPECIFIC_STEPS} Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section - Let {user_name} know they can type command `/bmad-help` at any time to get advice on what to do next, and that they can combine that with what they need help with `/bmad-help where should I start with an idea I have that does XYZ` + Let {user_name} know they can invoke the `bmad-help` skill at any time to get advice on what to do next, and that they can combine it with what they need help with Invoke the `bmad-help` skill with a question like "where should I start with an idea I have that does XYZ?" STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match On user input: Number → process menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized" - When processing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions \ No newline at end of file + When processing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (exec, tmpl, data, action, multi) and follow the corresponding handler instructions diff --git a/src/utility/agent-components/handler-multi.txt b/src/utility/agent-components/handler-multi.txt index f33a73fe5..e05be2390 100644 --- a/src/utility/agent-components/handler-multi.txt +++ b/src/utility/agent-components/handler-multi.txt @@ -4,10 +4,9 @@ 2. Parse all nested handlers within the multi item 3. For each nested handler: - Use the 'match' attribute for fuzzy matching user input (or Exact Match of character code in brackets []) - - Process based on handler attributes (exec, workflow, action) + - Process based on handler attributes (exec, action) 4. When user input matches a handler's 'match' pattern: - For exec="path/to/file.md": follow the `handler type="exec"` instructions - - For workflow="path/to/workflow.yaml": follow the `handler type="workflow"` instructions - For action="...": Perform the specified action directly 5. Support both exact matches and fuzzy matching based on the match attribute 6. If no handler matches, prompt user to choose from available options diff --git a/src/utility/agent-components/handler-validate-workflow.txt b/src/utility/agent-components/handler-validate-workflow.txt deleted file mode 100644 index aca040550..000000000 --- a/src/utility/agent-components/handler-validate-workflow.txt +++ /dev/null @@ -1,7 +0,0 @@ - - When command has: validate-workflow="path/to/workflow.yaml" - 1. You MUST LOAD the file at: {project-root}/_bmad/core/tasks/validate-workflow.xml - 2. READ its entire contents and EXECUTE all instructions in that file - 3. Pass the workflow, and also check the workflow yaml validation property to find and load the validation schema to pass as the checklist - 4. The workflow should try to identify the file to validate based on checklist context or else you will ask the user to specify - \ No newline at end of file diff --git a/src/utility/agent-components/handler-workflow.txt b/src/utility/agent-components/handler-workflow.txt deleted file mode 100644 index 1be1dcbe5..000000000 --- a/src/utility/agent-components/handler-workflow.txt +++ /dev/null @@ -1,10 +0,0 @@ - - When menu item has: workflow="path/to/workflow.yaml": - - 1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml - 2. Read the complete file - this is the CORE OS for processing BMAD workflows - 3. Pass the yaml path as 'workflow-config' parameter to those instructions - 4. Follow workflow.xml instructions precisely following all steps - 5. Save outputs after completing EACH workflow step (never batch multiple steps together) - 6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet - \ No newline at end of file diff --git a/test/adversarial-review-tests/README.md b/test/adversarial-review-tests/README.md index 8d2af5079..364359b0a 100644 --- a/test/adversarial-review-tests/README.md +++ b/test/adversarial-review-tests/README.md @@ -1,6 +1,6 @@ # Adversarial Review Test Suite -Tests for the `also_consider` optional input in `review-adversarial-general.xml`. +Tests for the `also_consider` optional input in the `bmad-review-adversarial-general` skill. ## Purpose @@ -19,12 +19,12 @@ All tests use `sample-content.md` - a deliberately imperfect User Authentication ## Running Tests -For each test case in `test-cases.yaml`, invoke the adversarial review task. +For each test case in `test-cases.yaml`, invoke the adversarial review skill. ### Manual Test Invocation ``` -Review this content using the adversarial review task: +Review this content using the adversarial review skill: [paste sample-content.md] diff --git a/test/adversarial-review-tests/test-cases.yaml b/test/adversarial-review-tests/test-cases.yaml index 7f20e84ff..0f5deefa2 100644 --- a/test/adversarial-review-tests/test-cases.yaml +++ b/test/adversarial-review-tests/test-cases.yaml @@ -1,9 +1,9 @@ -# Test Cases for review-adversarial-general.xml with also_consider input +# Test Cases for bmad-review-adversarial-general skill with also_consider input # # Purpose: Evaluate how the optional also_consider input influences review findings # Content: All tests use sample-content.md (User Authentication API docs) # -# To run: Manually invoke the task with each configuration and compare outputs +# To run: Manually invoke the skill with each configuration and compare outputs test_cases: # BASELINE - No also_consider diff --git a/test/fixtures/agent-schema/valid/menu-commands/all-command-types.agent.yaml b/test/fixtures/agent-schema/valid/menu-commands/all-command-types.agent.yaml index 959085cb7..22ae9886d 100644 --- a/test/fixtures/agent-schema/valid/menu-commands/all-command-types.agent.yaml +++ b/test/fixtures/agent-schema/valid/menu-commands/all-command-types.agent.yaml @@ -19,7 +19,7 @@ agent: menu: - trigger: workflow-test description: Test workflow command - workflow: path/to/workflow + exec: path/to/workflow - trigger: validate-test description: Test validate-workflow command validate-workflow: path/to/validation diff --git a/test/fixtures/agent-schema/valid/menu-commands/multiple-commands.agent.yaml b/test/fixtures/agent-schema/valid/menu-commands/multiple-commands.agent.yaml index 945722b5b..9133b02de 100644 --- a/test/fixtures/agent-schema/valid/menu-commands/multiple-commands.agent.yaml +++ b/test/fixtures/agent-schema/valid/menu-commands/multiple-commands.agent.yaml @@ -19,6 +19,5 @@ agent: menu: - trigger: multi-command description: Menu item with multiple command targets - workflow: path/to/workflow - exec: npm test + exec: path/to/workflow action: perform_action diff --git a/test/fixtures/agent-schema/valid/menu/multiple-menu-items.agent.yaml b/test/fixtures/agent-schema/valid/menu/multiple-menu-items.agent.yaml index c8a23a9d5..c95025025 100644 --- a/test/fixtures/agent-schema/valid/menu/multiple-menu-items.agent.yaml +++ b/test/fixtures/agent-schema/valid/menu/multiple-menu-items.agent.yaml @@ -22,7 +22,7 @@ agent: action: display_help - trigger: start-workflow description: Start a workflow - workflow: path/to/workflow + exec: path/to/workflow - trigger: execute description: Execute command exec: npm test diff --git a/test/fixtures/file-refs-csv/valid/bmm-style.csv b/test/fixtures/file-refs-csv/valid/bmm-style.csv index ab870ab01..c803064ba 100644 --- a/test/fixtures/file-refs-csv/valid/bmm-style.csv +++ b/test/fixtures/file-refs-csv/valid/bmm-style.csv @@ -1,3 +1,3 @@ module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs, -bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.yaml,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze project",project-knowledge,*, +bmm,anytime,Document Project,DP,,_bmad/bmm/workflows/document-project/workflow.md,bmad-bmm-document-project,false,analyst,Create Mode,"Analyze project",project-knowledge,*, bmm,1-analysis,Brainstorm Project,BP,10,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,data=template.md,"Brainstorming",planning_artifacts,"session", diff --git a/test/fixtures/file-refs-csv/valid/core-style.csv b/test/fixtures/file-refs-csv/valid/core-style.csv index d55df72d9..c6edcd0dc 100644 --- a/test/fixtures/file-refs-csv/valid/core-style.csv +++ b/test/fixtures/file-refs-csv/valid/core-style.csv @@ -1,3 +1,3 @@ module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs core,anytime,Brainstorming,BSP,,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,,"Generate ideas",{output_folder}/brainstorming.md, -core,anytime,Party Mode,PM,,_bmad/core/workflows/party-mode/workflow.md,bmad-party-mode,false,facilitator,,"Multi-agent discussion",, +core,anytime,Party Mode,PM,,_bmad/core/workflows/bmad-party-mode/workflow.md,bmad-party-mode,false,facilitator,,"Multi-agent discussion",, diff --git a/test/test-file-refs-csv.js b/test/test-file-refs-csv.js index d068bd75d..cc66e5589 100644 --- a/test/test-file-refs-csv.js +++ b/test/test-file-refs-csv.js @@ -58,7 +58,7 @@ test('bmm-style.csv: extracts workflow-file refs with trailing commas', () => { const { fullPath, content } = loadFixture('valid/bmm-style.csv'); const refs = extractCsvRefs(fullPath, content); assert(refs.length === 2, `Expected 2 refs, got ${refs.length}`); - assert(refs[0].raw === '_bmad/bmm/workflows/document-project/workflow.yaml', `Wrong raw[0]: ${refs[0].raw}`); + assert(refs[0].raw === '_bmad/bmm/workflows/document-project/workflow.md', `Wrong raw[0]: ${refs[0].raw}`); assert(refs[1].raw === '_bmad/core/workflows/brainstorming/workflow.md', `Wrong raw[1]: ${refs[1].raw}`); assert(refs[0].type === 'project-root', `Wrong type: ${refs[0].type}`); assert(refs[0].line === 2, `Wrong line for row 0: ${refs[0].line}`); @@ -71,7 +71,7 @@ test('core-style.csv: extracts refs from core module-help format', () => { const refs = extractCsvRefs(fullPath, content); assert(refs.length === 2, `Expected 2 refs, got ${refs.length}`); assert(refs[0].raw === '_bmad/core/workflows/brainstorming/workflow.md', `Wrong raw[0]: ${refs[0].raw}`); - assert(refs[1].raw === '_bmad/core/workflows/party-mode/workflow.md', `Wrong raw[1]: ${refs[1].raw}`); + assert(refs[1].raw === '_bmad/core/workflows/bmad-party-mode/workflow.md', `Wrong raw[1]: ${refs[1].raw}`); }); test('minimal.csv: extracts refs from minimal 3-column CSV', () => { diff --git a/test/test-install-to-bmad.js b/test/test-install-to-bmad.js new file mode 100644 index 000000000..0367dbe93 --- /dev/null +++ b/test/test-install-to-bmad.js @@ -0,0 +1,154 @@ +/** + * install_to_bmad Flag — Design Contract Tests + * + * Unit tests against the functions that implement the install_to_bmad flag. + * These nail down the 4 core design decisions: + * + * 1. true/omitted → skill stays in _bmad/ (default behavior) + * 2. false → skill removed from _bmad/ after IDE install + * 3. No platform → no cleanup runs (cleanup lives in installVerbatimSkills) + * 4. Mixed flags → each skill evaluated independently + * + * Usage: node test/test-install-to-bmad.js + */ + +const path = require('node:path'); +const os = require('node:os'); +const fs = require('fs-extra'); +const { loadSkillManifest, getInstallToBmad } = require('../tools/cli/installers/lib/ide/shared/skill-manifest'); + +// ANSI colors +const colors = { + reset: '\u001B[0m', + green: '\u001B[32m', + red: '\u001B[31m', + yellow: '\u001B[33m', + cyan: '\u001B[36m', + dim: '\u001B[2m', +}; + +let passed = 0; +let failed = 0; + +function assert(condition, testName, errorMessage = '') { + if (condition) { + console.log(`${colors.green}✓${colors.reset} ${testName}`); + passed++; + } else { + console.log(`${colors.red}✗${colors.reset} ${testName}`); + if (errorMessage) { + console.log(` ${colors.dim}${errorMessage}${colors.reset}`); + } + failed++; + } +} + +async function runTests() { + console.log(`${colors.cyan}========================================`); + console.log('install_to_bmad — Design Contract Tests'); + console.log(`========================================${colors.reset}\n`); + + // ============================================================ + // 1. true/omitted → getInstallToBmad returns true (keep in _bmad/) + // ============================================================ + console.log(`${colors.yellow}Design decision 1: true or omitted → skill stays in _bmad/${colors.reset}\n`); + + // Null manifest (no bmad-skill-manifest.yaml) → true + assert(getInstallToBmad(null, 'workflow.md') === true, 'null manifest defaults to true'); + + // Single-entry, flag omitted → true + assert( + getInstallToBmad({ __single: { type: 'skill' } }, 'workflow.md') === true, + 'single-entry manifest with flag omitted defaults to true', + ); + + // Single-entry, explicit true → true + assert( + getInstallToBmad({ __single: { type: 'skill', install_to_bmad: true } }, 'workflow.md') === true, + 'single-entry manifest with explicit true returns true', + ); + + console.log(''); + + // ============================================================ + // 2. false → getInstallToBmad returns false (remove from _bmad/) + // ============================================================ + console.log(`${colors.yellow}Design decision 2: false → skill removed from _bmad/${colors.reset}\n`); + + // Single-entry, explicit false → false + assert( + getInstallToBmad({ __single: { type: 'skill', install_to_bmad: false } }, 'workflow.md') === false, + 'single-entry manifest with explicit false returns false', + ); + + // loadSkillManifest round-trip: YAML with false is preserved through load + { + const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-itb-')); + await fs.writeFile(path.join(tmpDir, 'bmad-skill-manifest.yaml'), 'type: skill\ninstall_to_bmad: false\n'); + const loaded = await loadSkillManifest(tmpDir); + assert(getInstallToBmad(loaded, 'workflow.md') === false, 'loadSkillManifest preserves install_to_bmad: false through round-trip'); + await fs.remove(tmpDir); + } + + console.log(''); + + // ============================================================ + // 3. No platform → cleanup only runs inside installVerbatimSkills + // (This is a design invariant: getInstallToBmad is only consulted + // during IDE install. Without a platform, the flag has no effect.) + // ============================================================ + console.log(`${colors.yellow}Design decision 3: flag is a per-skill property, not a pipeline gate${colors.reset}\n`); + + // The flag value is stored but doesn't trigger any side effects by itself. + // Cleanup is driven by reading the CSV column inside installVerbatimSkills. + // We verify the flag is just data — getInstallToBmad doesn't touch the filesystem. + { + const manifest = { __single: { type: 'skill', install_to_bmad: false } }; + const result = getInstallToBmad(manifest, 'workflow.md'); + assert(typeof result === 'boolean', 'getInstallToBmad returns a boolean (pure data, no side effects)'); + assert(result === false, 'false value is faithfully returned for consumer to act on'); + } + + console.log(''); + + // ============================================================ + // 4. Mixed flags → each skill evaluated independently + // ============================================================ + console.log(`${colors.yellow}Design decision 4: mixed flags — each skill independent${colors.reset}\n`); + + // Multi-entry manifest: different files can have different flags + { + const manifest = { + 'workflow.md': { type: 'skill', install_to_bmad: false }, + 'other.md': { type: 'skill', install_to_bmad: true }, + }; + assert(getInstallToBmad(manifest, 'workflow.md') === false, 'multi-entry: workflow.md with false returns false'); + assert(getInstallToBmad(manifest, 'other.md') === true, 'multi-entry: other.md with true returns true'); + assert(getInstallToBmad(manifest, 'unknown.md') === true, 'multi-entry: unknown file defaults to true'); + } + + console.log(''); + + // ============================================================ + // Summary + // ============================================================ + console.log(`${colors.cyan}========================================`); + console.log('Results:'); + console.log(` Passed: ${colors.green}${passed}${colors.reset}`); + console.log(` Failed: ${colors.red}${failed}${colors.reset}`); + console.log(`========================================${colors.reset}\n`); + + if (failed === 0) { + console.log(`${colors.green}All install_to_bmad contract tests passed!${colors.reset}\n`); + process.exit(0); + } else { + console.log(`${colors.red}Some install_to_bmad contract tests failed${colors.reset}\n`); + process.exit(1); + } +} + +runTests().catch((error) => { + console.error(`${colors.red}Test runner failed:${colors.reset}`, error.message); + console.error(error.stack); + process.exit(1); +}); diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 0970861b9..e86541593 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -12,9 +12,12 @@ */ const path = require('node:path'); +const os = require('node:os'); const fs = require('fs-extra'); const { YamlXmlBuilder } = require('../tools/cli/lib/yaml-xml-builder'); const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest-generator'); +const { IdeManager } = require('../tools/cli/installers/lib/ide/manager'); +const { clearCache, loadPlatformCodes } = require('../tools/cli/installers/lib/ide/platform-codes'); // ANSI colors const colors = { @@ -45,6 +48,93 @@ function assert(condition, testName, errorMessage = '') { } } +async function createTestBmadFixture() { + const fixtureDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-fixture-')); + + // Minimal workflow manifest (generators check for this) + await fs.ensureDir(path.join(fixtureDir, '_config')); + await fs.writeFile(path.join(fixtureDir, '_config', 'workflow-manifest.csv'), ''); + + // Minimal compiled agent for core/agents (contains ', + 'Test persona', + '', + ].join('\n'); + + await fs.ensureDir(path.join(fixtureDir, 'core', 'agents')); + await fs.writeFile(path.join(fixtureDir, 'core', 'agents', 'bmad-master.md'), minimalAgent); + // Skill manifest so the installer uses 'bmad-master' as the canonical skill name + await fs.writeFile(path.join(fixtureDir, 'core', 'agents', 'bmad-skill-manifest.yaml'), 'bmad-master.md:\n canonicalId: bmad-master\n'); + + // Minimal compiled agent for bmm module (tests use selectedModules: ['bmm']) + await fs.ensureDir(path.join(fixtureDir, 'bmm', 'agents')); + await fs.writeFile(path.join(fixtureDir, 'bmm', 'agents', 'test-bmm-agent.md'), minimalAgent); + + return fixtureDir; +} + +async function createSkillCollisionFixture() { + const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-skill-collision-')); + const fixtureDir = path.join(fixtureRoot, '_bmad'); + const configDir = path.join(fixtureDir, '_config'); + await fs.ensureDir(configDir); + + await fs.writeFile( + path.join(configDir, 'agent-manifest.csv'), + [ + 'name,displayName,title,icon,capabilities,role,identity,communicationStyle,principles,module,path,canonicalId', + '"bmad-master","BMAD Master","","","","","","","","core","_bmad/core/agents/bmad-master.md","bmad-master"', + '', + ].join('\n'), + ); + + await fs.writeFile( + path.join(configDir, 'workflow-manifest.csv'), + [ + 'name,description,module,path,canonicalId', + '"help","Workflow help","core","_bmad/core/workflows/help/workflow.md","bmad-help"', + '', + ].join('\n'), + ); + + await fs.writeFile(path.join(configDir, 'task-manifest.csv'), 'name,displayName,description,module,path,standalone,canonicalId\n'); + await fs.writeFile(path.join(configDir, 'tool-manifest.csv'), 'name,displayName,description,module,path,standalone,canonicalId\n'); + await fs.writeFile( + path.join(configDir, 'skill-manifest.csv'), + [ + 'canonicalId,name,description,module,path,install_to_bmad', + '"bmad-help","bmad-help","Native help skill","core","_bmad/core/tasks/bmad-help/SKILL.md","true"', + '', + ].join('\n'), + ); + + const skillDir = path.join(fixtureDir, 'core', 'tasks', 'bmad-help'); + await fs.ensureDir(skillDir); + await fs.writeFile( + path.join(skillDir, 'SKILL.md'), + ['---', 'name: bmad-help', 'description: Native help skill', '---', '', 'Use this skill directly.'].join('\n'), + ); + + const agentDir = path.join(fixtureDir, 'core', 'agents'); + await fs.ensureDir(agentDir); + await fs.writeFile( + path.join(agentDir, 'bmad-master.md'), + ['---', 'name: BMAD Master', 'description: Master agent', '---', '', '', ''].join( + '\n', + ), + ); + + return { root: fixtureRoot, bmadDir: fixtureDir }; +} + /** * Test Suite */ @@ -158,9 +248,613 @@ async function runTests() { console.log(''); // ============================================================ - // Test 5: QA Agent Compilation + // Test 4: Windsurf Native Skills Install // ============================================================ - console.log(`${colors.yellow}Test Suite 5: QA Agent Compilation${colors.reset}\n`); + console.log(`${colors.yellow}Test Suite 4: Windsurf Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes = await loadPlatformCodes(); + const windsurfInstaller = platformCodes.platforms.windsurf?.installer; + + assert(windsurfInstaller?.target_dir === '.windsurf/skills', 'Windsurf target_dir uses native skills path'); + + assert(windsurfInstaller?.skill_format === true, 'Windsurf installer enables native skill output'); + + assert( + Array.isArray(windsurfInstaller?.legacy_targets) && windsurfInstaller.legacy_targets.includes('.windsurf/workflows'), + 'Windsurf installer cleans legacy workflow output', + ); + + const tempProjectDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-windsurf-test-')); + const installedBmadDir = await createTestBmadFixture(); + const legacyDir = path.join(tempProjectDir, '.windsurf', 'workflows', 'bmad-legacy-dir'); + await fs.ensureDir(legacyDir); + await fs.writeFile(path.join(tempProjectDir, '.windsurf', 'workflows', 'bmad-legacy.md'), 'legacy\n'); + await fs.writeFile(path.join(legacyDir, 'SKILL.md'), 'legacy\n'); + + const ideManager = new IdeManager(); + await ideManager.ensureInitialized(); + const result = await ideManager.setup('windsurf', tempProjectDir, installedBmadDir, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result.success === true, 'Windsurf setup succeeds against temp project'); + + const skillFile = path.join(tempProjectDir, '.windsurf', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile), 'Windsurf install writes SKILL.md directory output'); + + assert(!(await fs.pathExists(path.join(tempProjectDir, '.windsurf', 'workflows'))), 'Windsurf setup removes legacy workflows dir'); + + await fs.remove(tempProjectDir); + await fs.remove(installedBmadDir); + } catch (error) { + assert(false, 'Windsurf native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 5: Kiro Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 5: Kiro Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes = await loadPlatformCodes(); + const kiroInstaller = platformCodes.platforms.kiro?.installer; + + assert(kiroInstaller?.target_dir === '.kiro/skills', 'Kiro target_dir uses native skills path'); + + assert(kiroInstaller?.skill_format === true, 'Kiro installer enables native skill output'); + + assert( + Array.isArray(kiroInstaller?.legacy_targets) && kiroInstaller.legacy_targets.includes('.kiro/steering'), + 'Kiro installer cleans legacy steering output', + ); + + const tempProjectDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-kiro-test-')); + const installedBmadDir = await createTestBmadFixture(); + const legacyDir = path.join(tempProjectDir, '.kiro', 'steering', 'bmad-legacy-dir'); + await fs.ensureDir(legacyDir); + await fs.writeFile(path.join(tempProjectDir, '.kiro', 'steering', 'bmad-legacy.md'), 'legacy\n'); + await fs.writeFile(path.join(legacyDir, 'SKILL.md'), 'legacy\n'); + + const ideManager = new IdeManager(); + await ideManager.ensureInitialized(); + const result = await ideManager.setup('kiro', tempProjectDir, installedBmadDir, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result.success === true, 'Kiro setup succeeds against temp project'); + + const skillFile = path.join(tempProjectDir, '.kiro', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile), 'Kiro install writes SKILL.md directory output'); + + assert(!(await fs.pathExists(path.join(tempProjectDir, '.kiro', 'steering'))), 'Kiro setup removes legacy steering dir'); + + await fs.remove(tempProjectDir); + await fs.remove(installedBmadDir); + } catch (error) { + assert(false, 'Kiro native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 6: Antigravity Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 6: Antigravity Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes = await loadPlatformCodes(); + const antigravityInstaller = platformCodes.platforms.antigravity?.installer; + + assert(antigravityInstaller?.target_dir === '.agent/skills', 'Antigravity target_dir uses native skills path'); + + assert(antigravityInstaller?.skill_format === true, 'Antigravity installer enables native skill output'); + + assert( + Array.isArray(antigravityInstaller?.legacy_targets) && antigravityInstaller.legacy_targets.includes('.agent/workflows'), + 'Antigravity installer cleans legacy workflow output', + ); + + const tempProjectDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-antigravity-test-')); + const installedBmadDir = await createTestBmadFixture(); + const legacyDir = path.join(tempProjectDir, '.agent', 'workflows', 'bmad-legacy-dir'); + await fs.ensureDir(legacyDir); + await fs.writeFile(path.join(tempProjectDir, '.agent', 'workflows', 'bmad-legacy.md'), 'legacy\n'); + await fs.writeFile(path.join(legacyDir, 'SKILL.md'), 'legacy\n'); + + const ideManager = new IdeManager(); + await ideManager.ensureInitialized(); + const result = await ideManager.setup('antigravity', tempProjectDir, installedBmadDir, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result.success === true, 'Antigravity setup succeeds against temp project'); + + const skillFile = path.join(tempProjectDir, '.agent', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile), 'Antigravity install writes SKILL.md directory output'); + + assert(!(await fs.pathExists(path.join(tempProjectDir, '.agent', 'workflows'))), 'Antigravity setup removes legacy workflows dir'); + + await fs.remove(tempProjectDir); + await fs.remove(installedBmadDir); + } catch (error) { + assert(false, 'Antigravity native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 7: Auggie Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 7: Auggie Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes = await loadPlatformCodes(); + const auggieInstaller = platformCodes.platforms.auggie?.installer; + + assert(auggieInstaller?.target_dir === '.augment/skills', 'Auggie target_dir uses native skills path'); + + assert(auggieInstaller?.skill_format === true, 'Auggie installer enables native skill output'); + + assert( + Array.isArray(auggieInstaller?.legacy_targets) && auggieInstaller.legacy_targets.includes('.augment/commands'), + 'Auggie installer cleans legacy command output', + ); + + assert( + auggieInstaller?.ancestor_conflict_check !== true, + 'Auggie installer does not enable ancestor conflict checks without verified inheritance', + ); + + const tempProjectDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-auggie-test-')); + const installedBmadDir = await createTestBmadFixture(); + const legacyDir = path.join(tempProjectDir, '.augment', 'commands', 'bmad-legacy-dir'); + await fs.ensureDir(legacyDir); + await fs.writeFile(path.join(tempProjectDir, '.augment', 'commands', 'bmad-legacy.md'), 'legacy\n'); + await fs.writeFile(path.join(legacyDir, 'SKILL.md'), 'legacy\n'); + + const ideManager = new IdeManager(); + await ideManager.ensureInitialized(); + const result = await ideManager.setup('auggie', tempProjectDir, installedBmadDir, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result.success === true, 'Auggie setup succeeds against temp project'); + + const skillFile = path.join(tempProjectDir, '.augment', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile), 'Auggie install writes SKILL.md directory output'); + + assert(!(await fs.pathExists(path.join(tempProjectDir, '.augment', 'commands'))), 'Auggie setup removes legacy commands dir'); + + await fs.remove(tempProjectDir); + await fs.remove(installedBmadDir); + } catch (error) { + assert(false, 'Auggie native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 8: OpenCode Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 8: OpenCode Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes = await loadPlatformCodes(); + const opencodeInstaller = platformCodes.platforms.opencode?.installer; + + assert(opencodeInstaller?.target_dir === '.opencode/skills', 'OpenCode target_dir uses native skills path'); + + assert(opencodeInstaller?.skill_format === true, 'OpenCode installer enables native skill output'); + + assert(opencodeInstaller?.ancestor_conflict_check === true, 'OpenCode installer enables ancestor conflict checks'); + + assert( + Array.isArray(opencodeInstaller?.legacy_targets) && + ['.opencode/agents', '.opencode/commands', '.opencode/agent', '.opencode/command'].every((legacyTarget) => + opencodeInstaller.legacy_targets.includes(legacyTarget), + ), + 'OpenCode installer cleans split legacy agent and command output', + ); + + const tempProjectDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-opencode-test-')); + const installedBmadDir = await createTestBmadFixture(); + const legacyDirs = [ + path.join(tempProjectDir, '.opencode', 'agents', 'bmad-legacy-agent'), + path.join(tempProjectDir, '.opencode', 'commands', 'bmad-legacy-command'), + path.join(tempProjectDir, '.opencode', 'agent', 'bmad-legacy-agent-singular'), + path.join(tempProjectDir, '.opencode', 'command', 'bmad-legacy-command-singular'), + ]; + + for (const legacyDir of legacyDirs) { + await fs.ensureDir(legacyDir); + await fs.writeFile(path.join(legacyDir, 'SKILL.md'), 'legacy\n'); + await fs.writeFile(path.join(path.dirname(legacyDir), `${path.basename(legacyDir)}.md`), 'legacy\n'); + } + + const ideManager = new IdeManager(); + await ideManager.ensureInitialized(); + const result = await ideManager.setup('opencode', tempProjectDir, installedBmadDir, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result.success === true, 'OpenCode setup succeeds against temp project'); + + const skillFile = path.join(tempProjectDir, '.opencode', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile), 'OpenCode install writes SKILL.md directory output'); + + for (const legacyDir of ['agents', 'commands', 'agent', 'command']) { + assert( + !(await fs.pathExists(path.join(tempProjectDir, '.opencode', legacyDir))), + `OpenCode setup removes legacy .opencode/${legacyDir} dir`, + ); + } + + await fs.remove(tempProjectDir); + await fs.remove(installedBmadDir); + } catch (error) { + assert(false, 'OpenCode native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 9: Claude Code Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 9: Claude Code Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes9 = await loadPlatformCodes(); + const claudeInstaller = platformCodes9.platforms['claude-code']?.installer; + + assert(claudeInstaller?.target_dir === '.claude/skills', 'Claude Code target_dir uses native skills path'); + + assert(claudeInstaller?.skill_format === true, 'Claude Code installer enables native skill output'); + + assert(claudeInstaller?.ancestor_conflict_check === true, 'Claude Code installer enables ancestor conflict checks'); + + assert( + Array.isArray(claudeInstaller?.legacy_targets) && claudeInstaller.legacy_targets.includes('.claude/commands'), + 'Claude Code installer cleans legacy command output', + ); + + const tempProjectDir9 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-claude-code-test-')); + const installedBmadDir9 = await createTestBmadFixture(); + const legacyDir9 = path.join(tempProjectDir9, '.claude', 'commands'); + await fs.ensureDir(legacyDir9); + await fs.writeFile(path.join(legacyDir9, 'bmad-legacy.md'), 'legacy\n'); + + const ideManager9 = new IdeManager(); + await ideManager9.ensureInitialized(); + const result9 = await ideManager9.setup('claude-code', tempProjectDir9, installedBmadDir9, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result9.success === true, 'Claude Code setup succeeds against temp project'); + + const skillFile9 = path.join(tempProjectDir9, '.claude', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile9), 'Claude Code install writes SKILL.md directory output'); + + // Verify name frontmatter matches directory name + const skillContent9 = await fs.readFile(skillFile9, 'utf8'); + const nameMatch9 = skillContent9.match(/^name:\s*(.+)$/m); + assert(nameMatch9 && nameMatch9[1].trim() === 'bmad-master', 'Claude Code skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(legacyDir9)), 'Claude Code setup removes legacy commands dir'); + + await fs.remove(tempProjectDir9); + await fs.remove(installedBmadDir9); + } catch (error) { + assert(false, 'Claude Code native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 10: Claude Code Ancestor Conflict + // ============================================================ + console.log(`${colors.yellow}Test Suite 10: Claude Code Ancestor Conflict${colors.reset}\n`); + + try { + const tempRoot10 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-claude-code-ancestor-test-')); + const parentProjectDir10 = path.join(tempRoot10, 'parent'); + const childProjectDir10 = path.join(parentProjectDir10, 'child'); + const installedBmadDir10 = await createTestBmadFixture(); + + await fs.ensureDir(path.join(parentProjectDir10, '.git')); + await fs.ensureDir(path.join(parentProjectDir10, '.claude', 'skills', 'bmad-existing')); + await fs.ensureDir(childProjectDir10); + await fs.writeFile(path.join(parentProjectDir10, '.claude', 'skills', 'bmad-existing', 'SKILL.md'), 'legacy\n'); + + const ideManager10 = new IdeManager(); + await ideManager10.ensureInitialized(); + const result10 = await ideManager10.setup('claude-code', childProjectDir10, installedBmadDir10, { + silent: true, + selectedModules: ['bmm'], + }); + const expectedConflictDir10 = await fs.realpath(path.join(parentProjectDir10, '.claude', 'skills')); + + assert(result10.success === false, 'Claude Code setup refuses install when ancestor skills already exist'); + assert(result10.handlerResult?.reason === 'ancestor-conflict', 'Claude Code ancestor rejection reports ancestor-conflict reason'); + assert( + result10.handlerResult?.conflictDir === expectedConflictDir10, + 'Claude Code ancestor rejection points at ancestor .claude/skills dir', + ); + + await fs.remove(tempRoot10); + await fs.remove(installedBmadDir10); + } catch (error) { + assert(false, 'Claude Code ancestor conflict protection test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 11: Codex Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 11: Codex Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes11 = await loadPlatformCodes(); + const codexInstaller = platformCodes11.platforms.codex?.installer; + + assert(codexInstaller?.target_dir === '.agents/skills', 'Codex target_dir uses native skills path'); + + assert(codexInstaller?.skill_format === true, 'Codex installer enables native skill output'); + + assert(codexInstaller?.ancestor_conflict_check === true, 'Codex installer enables ancestor conflict checks'); + + assert( + Array.isArray(codexInstaller?.legacy_targets) && codexInstaller.legacy_targets.includes('.codex/prompts'), + 'Codex installer cleans legacy prompt output', + ); + + const tempProjectDir11 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-codex-test-')); + const installedBmadDir11 = await createTestBmadFixture(); + const legacyDir11 = path.join(tempProjectDir11, '.codex', 'prompts'); + await fs.ensureDir(legacyDir11); + await fs.writeFile(path.join(legacyDir11, 'bmad-legacy.md'), 'legacy\n'); + + const ideManager11 = new IdeManager(); + await ideManager11.ensureInitialized(); + const result11 = await ideManager11.setup('codex', tempProjectDir11, installedBmadDir11, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result11.success === true, 'Codex setup succeeds against temp project'); + + const skillFile11 = path.join(tempProjectDir11, '.agents', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile11), 'Codex install writes SKILL.md directory output'); + + // Verify name frontmatter matches directory name + const skillContent11 = await fs.readFile(skillFile11, 'utf8'); + const nameMatch11 = skillContent11.match(/^name:\s*(.+)$/m); + assert(nameMatch11 && nameMatch11[1].trim() === 'bmad-master', 'Codex skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(legacyDir11)), 'Codex setup removes legacy prompts dir'); + + await fs.remove(tempProjectDir11); + await fs.remove(installedBmadDir11); + } catch (error) { + assert(false, 'Codex native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 12: Codex Ancestor Conflict + // ============================================================ + console.log(`${colors.yellow}Test Suite 12: Codex Ancestor Conflict${colors.reset}\n`); + + try { + const tempRoot12 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-codex-ancestor-test-')); + const parentProjectDir12 = path.join(tempRoot12, 'parent'); + const childProjectDir12 = path.join(parentProjectDir12, 'child'); + const installedBmadDir12 = await createTestBmadFixture(); + + await fs.ensureDir(path.join(parentProjectDir12, '.git')); + await fs.ensureDir(path.join(parentProjectDir12, '.agents', 'skills', 'bmad-existing')); + await fs.ensureDir(childProjectDir12); + await fs.writeFile(path.join(parentProjectDir12, '.agents', 'skills', 'bmad-existing', 'SKILL.md'), 'legacy\n'); + + const ideManager12 = new IdeManager(); + await ideManager12.ensureInitialized(); + const result12 = await ideManager12.setup('codex', childProjectDir12, installedBmadDir12, { + silent: true, + selectedModules: ['bmm'], + }); + const expectedConflictDir12 = await fs.realpath(path.join(parentProjectDir12, '.agents', 'skills')); + + assert(result12.success === false, 'Codex setup refuses install when ancestor skills already exist'); + assert(result12.handlerResult?.reason === 'ancestor-conflict', 'Codex ancestor rejection reports ancestor-conflict reason'); + assert(result12.handlerResult?.conflictDir === expectedConflictDir12, 'Codex ancestor rejection points at ancestor .agents/skills dir'); + + await fs.remove(tempRoot12); + await fs.remove(installedBmadDir12); + } catch (error) { + assert(false, 'Codex ancestor conflict protection test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 13: Cursor Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 13: Cursor Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes13 = await loadPlatformCodes(); + const cursorInstaller = platformCodes13.platforms.cursor?.installer; + + assert(cursorInstaller?.target_dir === '.cursor/skills', 'Cursor target_dir uses native skills path'); + + assert(cursorInstaller?.skill_format === true, 'Cursor installer enables native skill output'); + + assert( + Array.isArray(cursorInstaller?.legacy_targets) && cursorInstaller.legacy_targets.includes('.cursor/commands'), + 'Cursor installer cleans legacy command output', + ); + + assert(!cursorInstaller?.ancestor_conflict_check, 'Cursor installer does not enable ancestor conflict checks'); + + const tempProjectDir13c = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-cursor-test-')); + const installedBmadDir13c = await createTestBmadFixture(); + const legacyDir13c = path.join(tempProjectDir13c, '.cursor', 'commands'); + await fs.ensureDir(legacyDir13c); + await fs.writeFile(path.join(legacyDir13c, 'bmad-legacy.md'), 'legacy\n'); + + const ideManager13c = new IdeManager(); + await ideManager13c.ensureInitialized(); + const result13c = await ideManager13c.setup('cursor', tempProjectDir13c, installedBmadDir13c, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result13c.success === true, 'Cursor setup succeeds against temp project'); + + const skillFile13c = path.join(tempProjectDir13c, '.cursor', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile13c), 'Cursor install writes SKILL.md directory output'); + + // Verify name frontmatter matches directory name + const skillContent13c = await fs.readFile(skillFile13c, 'utf8'); + const nameMatch13c = skillContent13c.match(/^name:\s*(.+)$/m); + assert(nameMatch13c && nameMatch13c[1].trim() === 'bmad-master', 'Cursor skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(legacyDir13c)), 'Cursor setup removes legacy commands dir'); + + await fs.remove(tempProjectDir13c); + await fs.remove(installedBmadDir13c); + } catch (error) { + assert(false, 'Cursor native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 14: Roo Code Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 14: Roo Code Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes13 = await loadPlatformCodes(); + const rooInstaller = platformCodes13.platforms.roo?.installer; + + assert(rooInstaller?.target_dir === '.roo/skills', 'Roo target_dir uses native skills path'); + + assert(rooInstaller?.skill_format === true, 'Roo installer enables native skill output'); + + assert( + Array.isArray(rooInstaller?.legacy_targets) && rooInstaller.legacy_targets.includes('.roo/commands'), + 'Roo installer cleans legacy command output', + ); + + const tempProjectDir13 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-roo-test-')); + const installedBmadDir13 = await createTestBmadFixture(); + const legacyDir13 = path.join(tempProjectDir13, '.roo', 'commands', 'bmad-legacy-dir'); + await fs.ensureDir(legacyDir13); + await fs.writeFile(path.join(tempProjectDir13, '.roo', 'commands', 'bmad-legacy.md'), 'legacy\n'); + await fs.writeFile(path.join(legacyDir13, 'SKILL.md'), 'legacy\n'); + + const ideManager13 = new IdeManager(); + await ideManager13.ensureInitialized(); + const result13 = await ideManager13.setup('roo', tempProjectDir13, installedBmadDir13, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result13.success === true, 'Roo setup succeeds against temp project'); + + const skillFile13 = path.join(tempProjectDir13, '.roo', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile13), 'Roo install writes SKILL.md directory output'); + + // Verify name frontmatter matches directory name (Roo constraint: lowercase alphanumeric + hyphens) + const skillContent13 = await fs.readFile(skillFile13, 'utf8'); + const nameMatch13 = skillContent13.match(/^name:\s*(.+)$/m); + assert( + nameMatch13 && nameMatch13[1].trim() === 'bmad-master', + 'Roo skill name frontmatter matches directory name exactly (lowercase alphanumeric + hyphens)', + ); + + assert(!(await fs.pathExists(path.join(tempProjectDir13, '.roo', 'commands'))), 'Roo setup removes legacy commands dir'); + + // Reinstall/upgrade: run setup again over existing skills output + const result13b = await ideManager13.setup('roo', tempProjectDir13, installedBmadDir13, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result13b.success === true, 'Roo reinstall/upgrade succeeds over existing skills'); + assert(await fs.pathExists(skillFile13), 'Roo reinstall preserves SKILL.md output'); + + await fs.remove(tempProjectDir13); + await fs.remove(installedBmadDir13); + } catch (error) { + assert(false, 'Roo native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 15: OpenCode Ancestor Conflict + // ============================================================ + console.log(`${colors.yellow}Test Suite 15: OpenCode Ancestor Conflict${colors.reset}\n`); + + try { + const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-opencode-ancestor-test-')); + const parentProjectDir = path.join(tempRoot, 'parent'); + const childProjectDir = path.join(parentProjectDir, 'child'); + const installedBmadDir = await createTestBmadFixture(); + + await fs.ensureDir(path.join(parentProjectDir, '.git')); + await fs.ensureDir(path.join(parentProjectDir, '.opencode', 'skills', 'bmad-existing')); + await fs.ensureDir(childProjectDir); + await fs.writeFile(path.join(parentProjectDir, '.opencode', 'skills', 'bmad-existing', 'SKILL.md'), 'legacy\n'); + + const ideManager = new IdeManager(); + await ideManager.ensureInitialized(); + const result = await ideManager.setup('opencode', childProjectDir, installedBmadDir, { + silent: true, + selectedModules: ['bmm'], + }); + const expectedConflictDir = await fs.realpath(path.join(parentProjectDir, '.opencode', 'skills')); + + assert(result.success === false, 'OpenCode setup refuses install when ancestor skills already exist'); + assert(result.handlerResult?.reason === 'ancestor-conflict', 'OpenCode ancestor rejection reports ancestor-conflict reason'); + assert( + result.handlerResult?.conflictDir === expectedConflictDir, + 'OpenCode ancestor rejection points at ancestor .opencode/skills dir', + ); + + await fs.remove(tempRoot); + await fs.remove(installedBmadDir); + } catch (error) { + assert(false, 'OpenCode ancestor conflict protection test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 16: QA Agent Compilation + // ============================================================ + console.log(`${colors.yellow}Test Suite 16: QA Agent Compilation${colors.reset}\n`); try { const builder = new YamlXmlBuilder(); @@ -173,7 +867,7 @@ async function runTests() { assert(compiled.includes('QA Engineer'), 'QA agent compilation includes agent title'); - assert(compiled.includes('qa/automate'), 'QA agent menu includes automate workflow'); + assert(compiled.includes('qa-generate-e2e-tests'), 'QA agent menu includes automate workflow'); // Cleanup await fs.remove(tempOutput); @@ -186,6 +880,994 @@ async function runTests() { console.log(''); + // ============================================================ + // Test 17: GitHub Copilot Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 17: GitHub Copilot Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes17 = await loadPlatformCodes(); + const copilotInstaller = platformCodes17.platforms['github-copilot']?.installer; + + assert(copilotInstaller?.target_dir === '.github/skills', 'GitHub Copilot target_dir uses native skills path'); + + assert(copilotInstaller?.skill_format === true, 'GitHub Copilot installer enables native skill output'); + + assert( + Array.isArray(copilotInstaller?.legacy_targets) && copilotInstaller.legacy_targets.includes('.github/agents'), + 'GitHub Copilot installer cleans legacy agents output', + ); + + assert( + Array.isArray(copilotInstaller?.legacy_targets) && copilotInstaller.legacy_targets.includes('.github/prompts'), + 'GitHub Copilot installer cleans legacy prompts output', + ); + + const tempProjectDir17 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-copilot-test-')); + const installedBmadDir17 = await createTestBmadFixture(); + + // Create legacy .github/agents/ and .github/prompts/ files + const legacyAgentsDir17 = path.join(tempProjectDir17, '.github', 'agents'); + const legacyPromptsDir17 = path.join(tempProjectDir17, '.github', 'prompts'); + await fs.ensureDir(legacyAgentsDir17); + await fs.ensureDir(legacyPromptsDir17); + await fs.writeFile(path.join(legacyAgentsDir17, 'bmad-legacy.agent.md'), 'legacy agent\n'); + await fs.writeFile(path.join(legacyPromptsDir17, 'bmad-legacy.prompt.md'), 'legacy prompt\n'); + + // Create legacy copilot-instructions.md with BMAD markers + const copilotInstructionsPath17 = path.join(tempProjectDir17, '.github', 'copilot-instructions.md'); + await fs.writeFile( + copilotInstructionsPath17, + 'User content before\n\nBMAD generated content\n\nUser content after\n', + ); + + const ideManager17 = new IdeManager(); + await ideManager17.ensureInitialized(); + const result17 = await ideManager17.setup('github-copilot', tempProjectDir17, installedBmadDir17, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result17.success === true, 'GitHub Copilot setup succeeds against temp project'); + + const skillFile17 = path.join(tempProjectDir17, '.github', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile17), 'GitHub Copilot install writes SKILL.md directory output'); + + // Verify name frontmatter matches directory name + const skillContent17 = await fs.readFile(skillFile17, 'utf8'); + const nameMatch17 = skillContent17.match(/^name:\s*(.+)$/m); + assert(nameMatch17 && nameMatch17[1].trim() === 'bmad-master', 'GitHub Copilot skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(legacyAgentsDir17)), 'GitHub Copilot setup removes legacy agents dir'); + + assert(!(await fs.pathExists(legacyPromptsDir17)), 'GitHub Copilot setup removes legacy prompts dir'); + + // Verify copilot-instructions.md BMAD markers were stripped but user content preserved + const cleanedInstructions17 = await fs.readFile(copilotInstructionsPath17, 'utf8'); + assert( + !cleanedInstructions17.includes('BMAD:START') && !cleanedInstructions17.includes('BMAD generated content'), + 'GitHub Copilot setup strips BMAD markers from copilot-instructions.md', + ); + assert( + cleanedInstructions17.includes('User content before') && cleanedInstructions17.includes('User content after'), + 'GitHub Copilot setup preserves user content in copilot-instructions.md', + ); + + await fs.remove(tempProjectDir17); + await fs.remove(installedBmadDir17); + } catch (error) { + assert(false, 'GitHub Copilot native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 18: Cline Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 18: Cline Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes18 = await loadPlatformCodes(); + const clineInstaller = platformCodes18.platforms.cline?.installer; + + assert(clineInstaller?.target_dir === '.cline/skills', 'Cline target_dir uses native skills path'); + + assert(clineInstaller?.skill_format === true, 'Cline installer enables native skill output'); + + assert( + Array.isArray(clineInstaller?.legacy_targets) && clineInstaller.legacy_targets.includes('.clinerules/workflows'), + 'Cline installer cleans legacy workflow output', + ); + + const tempProjectDir18 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-cline-test-')); + const installedBmadDir18 = await createTestBmadFixture(); + const legacyDir18 = path.join(tempProjectDir18, '.clinerules', 'workflows', 'bmad-legacy-dir'); + await fs.ensureDir(legacyDir18); + await fs.writeFile(path.join(tempProjectDir18, '.clinerules', 'workflows', 'bmad-legacy.md'), 'legacy\n'); + await fs.writeFile(path.join(legacyDir18, 'SKILL.md'), 'legacy\n'); + + const ideManager18 = new IdeManager(); + await ideManager18.ensureInitialized(); + const result18 = await ideManager18.setup('cline', tempProjectDir18, installedBmadDir18, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result18.success === true, 'Cline setup succeeds against temp project'); + + const skillFile18 = path.join(tempProjectDir18, '.cline', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile18), 'Cline install writes SKILL.md directory output'); + + // Verify name frontmatter matches directory name + const skillContent18 = await fs.readFile(skillFile18, 'utf8'); + const nameMatch18 = skillContent18.match(/^name:\s*(.+)$/m); + assert(nameMatch18 && nameMatch18[1].trim() === 'bmad-master', 'Cline skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(path.join(tempProjectDir18, '.clinerules', 'workflows'))), 'Cline setup removes legacy workflows dir'); + + // Reinstall/upgrade: run setup again over existing skills output + const result18b = await ideManager18.setup('cline', tempProjectDir18, installedBmadDir18, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result18b.success === true, 'Cline reinstall/upgrade succeeds over existing skills'); + assert(await fs.pathExists(skillFile18), 'Cline reinstall preserves SKILL.md output'); + + await fs.remove(tempProjectDir18); + await fs.remove(installedBmadDir18); + } catch (error) { + assert(false, 'Cline native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 19: CodeBuddy Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 19: CodeBuddy Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes19 = await loadPlatformCodes(); + const codebuddyInstaller = platformCodes19.platforms.codebuddy?.installer; + + assert(codebuddyInstaller?.target_dir === '.codebuddy/skills', 'CodeBuddy target_dir uses native skills path'); + + assert(codebuddyInstaller?.skill_format === true, 'CodeBuddy installer enables native skill output'); + + assert( + Array.isArray(codebuddyInstaller?.legacy_targets) && codebuddyInstaller.legacy_targets.includes('.codebuddy/commands'), + 'CodeBuddy installer cleans legacy command output', + ); + + const tempProjectDir19 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-codebuddy-test-')); + const installedBmadDir19 = await createTestBmadFixture(); + const legacyDir19 = path.join(tempProjectDir19, '.codebuddy', 'commands', 'bmad-legacy-dir'); + await fs.ensureDir(legacyDir19); + await fs.writeFile(path.join(tempProjectDir19, '.codebuddy', 'commands', 'bmad-legacy.md'), 'legacy\n'); + await fs.writeFile(path.join(legacyDir19, 'SKILL.md'), 'legacy\n'); + + const ideManager19 = new IdeManager(); + await ideManager19.ensureInitialized(); + const result19 = await ideManager19.setup('codebuddy', tempProjectDir19, installedBmadDir19, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result19.success === true, 'CodeBuddy setup succeeds against temp project'); + + const skillFile19 = path.join(tempProjectDir19, '.codebuddy', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile19), 'CodeBuddy install writes SKILL.md directory output'); + + const skillContent19 = await fs.readFile(skillFile19, 'utf8'); + const nameMatch19 = skillContent19.match(/^name:\s*(.+)$/m); + assert(nameMatch19 && nameMatch19[1].trim() === 'bmad-master', 'CodeBuddy skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(path.join(tempProjectDir19, '.codebuddy', 'commands'))), 'CodeBuddy setup removes legacy commands dir'); + + const result19b = await ideManager19.setup('codebuddy', tempProjectDir19, installedBmadDir19, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result19b.success === true, 'CodeBuddy reinstall/upgrade succeeds over existing skills'); + assert(await fs.pathExists(skillFile19), 'CodeBuddy reinstall preserves SKILL.md output'); + + await fs.remove(tempProjectDir19); + await fs.remove(installedBmadDir19); + } catch (error) { + assert(false, 'CodeBuddy native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 20: Crush Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 20: Crush Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes20 = await loadPlatformCodes(); + const crushInstaller = platformCodes20.platforms.crush?.installer; + + assert(crushInstaller?.target_dir === '.crush/skills', 'Crush target_dir uses native skills path'); + + assert(crushInstaller?.skill_format === true, 'Crush installer enables native skill output'); + + assert( + Array.isArray(crushInstaller?.legacy_targets) && crushInstaller.legacy_targets.includes('.crush/commands'), + 'Crush installer cleans legacy command output', + ); + + const tempProjectDir20 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-crush-test-')); + const installedBmadDir20 = await createTestBmadFixture(); + const legacyDir20 = path.join(tempProjectDir20, '.crush', 'commands', 'bmad-legacy-dir'); + await fs.ensureDir(legacyDir20); + await fs.writeFile(path.join(tempProjectDir20, '.crush', 'commands', 'bmad-legacy.md'), 'legacy\n'); + await fs.writeFile(path.join(legacyDir20, 'SKILL.md'), 'legacy\n'); + + const ideManager20 = new IdeManager(); + await ideManager20.ensureInitialized(); + const result20 = await ideManager20.setup('crush', tempProjectDir20, installedBmadDir20, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result20.success === true, 'Crush setup succeeds against temp project'); + + const skillFile20 = path.join(tempProjectDir20, '.crush', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile20), 'Crush install writes SKILL.md directory output'); + + const skillContent20 = await fs.readFile(skillFile20, 'utf8'); + const nameMatch20 = skillContent20.match(/^name:\s*(.+)$/m); + assert(nameMatch20 && nameMatch20[1].trim() === 'bmad-master', 'Crush skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(path.join(tempProjectDir20, '.crush', 'commands'))), 'Crush setup removes legacy commands dir'); + + const result20b = await ideManager20.setup('crush', tempProjectDir20, installedBmadDir20, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result20b.success === true, 'Crush reinstall/upgrade succeeds over existing skills'); + assert(await fs.pathExists(skillFile20), 'Crush reinstall preserves SKILL.md output'); + + await fs.remove(tempProjectDir20); + await fs.remove(installedBmadDir20); + } catch (error) { + assert(false, 'Crush native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Test 21: Trae Native Skills Install + // ============================================================ + console.log(`${colors.yellow}Test Suite 21: Trae Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes21 = await loadPlatformCodes(); + const traeInstaller = platformCodes21.platforms.trae?.installer; + + assert(traeInstaller?.target_dir === '.trae/skills', 'Trae target_dir uses native skills path'); + + assert(traeInstaller?.skill_format === true, 'Trae installer enables native skill output'); + + assert( + Array.isArray(traeInstaller?.legacy_targets) && traeInstaller.legacy_targets.includes('.trae/rules'), + 'Trae installer cleans legacy rules output', + ); + + const tempProjectDir21 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-trae-test-')); + const installedBmadDir21 = await createTestBmadFixture(); + const legacyDir21 = path.join(tempProjectDir21, '.trae', 'rules'); + await fs.ensureDir(legacyDir21); + await fs.writeFile(path.join(legacyDir21, 'bmad-legacy.md'), 'legacy\n'); + + const ideManager21 = new IdeManager(); + await ideManager21.ensureInitialized(); + const result21 = await ideManager21.setup('trae', tempProjectDir21, installedBmadDir21, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result21.success === true, 'Trae setup succeeds against temp project'); + + const skillFile21 = path.join(tempProjectDir21, '.trae', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile21), 'Trae install writes SKILL.md directory output'); + + const skillContent21 = await fs.readFile(skillFile21, 'utf8'); + const nameMatch21 = skillContent21.match(/^name:\s*(.+)$/m); + assert(nameMatch21 && nameMatch21[1].trim() === 'bmad-master', 'Trae skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(path.join(tempProjectDir21, '.trae', 'rules'))), 'Trae setup removes legacy rules dir'); + + const result21b = await ideManager21.setup('trae', tempProjectDir21, installedBmadDir21, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result21b.success === true, 'Trae reinstall/upgrade succeeds over existing skills'); + assert(await fs.pathExists(skillFile21), 'Trae reinstall preserves SKILL.md output'); + + await fs.remove(tempProjectDir21); + await fs.remove(installedBmadDir21); + } catch (error) { + assert(false, 'Trae native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Suite 22: KiloCoder Suspended + // ============================================================ + console.log(`${colors.yellow}Test Suite 22: KiloCoder Suspended${colors.reset}\n`); + + try { + clearCache(); + const platformCodes22 = await loadPlatformCodes(); + const kiloConfig22 = platformCodes22.platforms.kilo; + + assert(typeof kiloConfig22?.suspended === 'string', 'KiloCoder has a suspended message in platform config'); + + assert(kiloConfig22?.installer?.target_dir === '.kilocode/skills', 'KiloCoder retains target_dir config for future use'); + + const ideManager22 = new IdeManager(); + await ideManager22.ensureInitialized(); + + // Should not appear in available IDEs + const availableIdes22 = ideManager22.getAvailableIdes(); + assert(!availableIdes22.some((ide) => ide.value === 'kilo'), 'KiloCoder is hidden from IDE selection'); + + // Setup should be blocked but legacy files should be cleaned up + const tempProjectDir22 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-kilo-test-')); + const installedBmadDir22 = await createTestBmadFixture(); + + // Pre-populate legacy Kilo artifacts that should be cleaned up + const legacyDir22 = path.join(tempProjectDir22, '.kilocode', 'workflows'); + await fs.ensureDir(legacyDir22); + await fs.writeFile(path.join(legacyDir22, 'bmad-legacy.md'), 'legacy\n'); + + const result22 = await ideManager22.setup('kilo', tempProjectDir22, installedBmadDir22, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result22.success === false, 'KiloCoder setup is blocked when suspended'); + assert(result22.error === 'suspended', 'KiloCoder setup returns suspended error'); + + // Should not write new skill files + assert( + !(await fs.pathExists(path.join(tempProjectDir22, '.kilocode', 'skills'))), + 'KiloCoder does not create skills directory when suspended', + ); + + // Legacy files should be cleaned up + assert( + !(await fs.pathExists(path.join(tempProjectDir22, '.kilocode', 'workflows'))), + 'KiloCoder legacy workflows are cleaned up even when suspended', + ); + + await fs.remove(tempProjectDir22); + await fs.remove(installedBmadDir22); + } catch (error) { + assert(false, 'KiloCoder suspended test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Suite 23: Gemini CLI Native Skills + // ============================================================ + console.log(`${colors.yellow}Test Suite 23: Gemini CLI Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes23 = await loadPlatformCodes(); + const geminiInstaller = platformCodes23.platforms.gemini?.installer; + + assert(geminiInstaller?.target_dir === '.gemini/skills', 'Gemini target_dir uses native skills path'); + + assert(geminiInstaller?.skill_format === true, 'Gemini installer enables native skill output'); + + assert( + Array.isArray(geminiInstaller?.legacy_targets) && geminiInstaller.legacy_targets.includes('.gemini/commands'), + 'Gemini installer cleans legacy commands output', + ); + + const tempProjectDir23 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-gemini-test-')); + const installedBmadDir23 = await createTestBmadFixture(); + const legacyDir23 = path.join(tempProjectDir23, '.gemini', 'commands'); + await fs.ensureDir(legacyDir23); + await fs.writeFile(path.join(legacyDir23, 'bmad-legacy.toml'), 'legacy\n'); + + const ideManager23 = new IdeManager(); + await ideManager23.ensureInitialized(); + const result23 = await ideManager23.setup('gemini', tempProjectDir23, installedBmadDir23, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result23.success === true, 'Gemini setup succeeds against temp project'); + + const skillFile23 = path.join(tempProjectDir23, '.gemini', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile23), 'Gemini install writes SKILL.md directory output'); + + const skillContent23 = await fs.readFile(skillFile23, 'utf8'); + const nameMatch23 = skillContent23.match(/^name:\s*(.+)$/m); + assert(nameMatch23 && nameMatch23[1].trim() === 'bmad-master', 'Gemini skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(path.join(tempProjectDir23, '.gemini', 'commands'))), 'Gemini setup removes legacy commands dir'); + + const result23b = await ideManager23.setup('gemini', tempProjectDir23, installedBmadDir23, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result23b.success === true, 'Gemini reinstall/upgrade succeeds over existing skills'); + assert(await fs.pathExists(skillFile23), 'Gemini reinstall preserves SKILL.md output'); + + await fs.remove(tempProjectDir23); + await fs.remove(installedBmadDir23); + } catch (error) { + assert(false, 'Gemini native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Suite 24: iFlow Native Skills + // ============================================================ + console.log(`${colors.yellow}Test Suite 24: iFlow Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes24 = await loadPlatformCodes(); + const iflowInstaller = platformCodes24.platforms.iflow?.installer; + + assert(iflowInstaller?.target_dir === '.iflow/skills', 'iFlow target_dir uses native skills path'); + assert(iflowInstaller?.skill_format === true, 'iFlow installer enables native skill output'); + assert( + Array.isArray(iflowInstaller?.legacy_targets) && iflowInstaller.legacy_targets.includes('.iflow/commands'), + 'iFlow installer cleans legacy commands output', + ); + + const tempProjectDir24 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-iflow-test-')); + const installedBmadDir24 = await createTestBmadFixture(); + const legacyDir24 = path.join(tempProjectDir24, '.iflow', 'commands'); + await fs.ensureDir(legacyDir24); + await fs.writeFile(path.join(legacyDir24, 'bmad-legacy.md'), 'legacy\n'); + + const ideManager24 = new IdeManager(); + await ideManager24.ensureInitialized(); + const result24 = await ideManager24.setup('iflow', tempProjectDir24, installedBmadDir24, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result24.success === true, 'iFlow setup succeeds against temp project'); + + const skillFile24 = path.join(tempProjectDir24, '.iflow', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile24), 'iFlow install writes SKILL.md directory output'); + + // Verify name frontmatter matches directory name + const skillContent24 = await fs.readFile(skillFile24, 'utf8'); + const nameMatch24 = skillContent24.match(/^name:\s*(.+)$/m); + assert(nameMatch24 && nameMatch24[1].trim() === 'bmad-master', 'iFlow skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(path.join(tempProjectDir24, '.iflow', 'commands'))), 'iFlow setup removes legacy commands dir'); + + await fs.remove(tempProjectDir24); + await fs.remove(installedBmadDir24); + } catch (error) { + assert(false, 'iFlow native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Suite 25: QwenCoder Native Skills + // ============================================================ + console.log(`${colors.yellow}Test Suite 25: QwenCoder Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes25 = await loadPlatformCodes(); + const qwenInstaller = platformCodes25.platforms.qwen?.installer; + + assert(qwenInstaller?.target_dir === '.qwen/skills', 'QwenCoder target_dir uses native skills path'); + assert(qwenInstaller?.skill_format === true, 'QwenCoder installer enables native skill output'); + assert( + Array.isArray(qwenInstaller?.legacy_targets) && qwenInstaller.legacy_targets.includes('.qwen/commands'), + 'QwenCoder installer cleans legacy commands output', + ); + + const tempProjectDir25 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-qwen-test-')); + const installedBmadDir25 = await createTestBmadFixture(); + const legacyDir25 = path.join(tempProjectDir25, '.qwen', 'commands'); + await fs.ensureDir(legacyDir25); + await fs.writeFile(path.join(legacyDir25, 'bmad-legacy.md'), 'legacy\n'); + + const ideManager25 = new IdeManager(); + await ideManager25.ensureInitialized(); + const result25 = await ideManager25.setup('qwen', tempProjectDir25, installedBmadDir25, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result25.success === true, 'QwenCoder setup succeeds against temp project'); + + const skillFile25 = path.join(tempProjectDir25, '.qwen', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile25), 'QwenCoder install writes SKILL.md directory output'); + + // Verify name frontmatter matches directory name + const skillContent25 = await fs.readFile(skillFile25, 'utf8'); + const nameMatch25 = skillContent25.match(/^name:\s*(.+)$/m); + assert(nameMatch25 && nameMatch25[1].trim() === 'bmad-master', 'QwenCoder skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(path.join(tempProjectDir25, '.qwen', 'commands'))), 'QwenCoder setup removes legacy commands dir'); + + await fs.remove(tempProjectDir25); + await fs.remove(installedBmadDir25); + } catch (error) { + assert(false, 'QwenCoder native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Suite 26: Rovo Dev Native Skills + // ============================================================ + console.log(`${colors.yellow}Test Suite 26: Rovo Dev Native Skills${colors.reset}\n`); + + try { + clearCache(); + const platformCodes26 = await loadPlatformCodes(); + const rovoInstaller = platformCodes26.platforms['rovo-dev']?.installer; + + assert(rovoInstaller?.target_dir === '.rovodev/skills', 'Rovo Dev target_dir uses native skills path'); + assert(rovoInstaller?.skill_format === true, 'Rovo Dev installer enables native skill output'); + assert( + Array.isArray(rovoInstaller?.legacy_targets) && rovoInstaller.legacy_targets.includes('.rovodev/workflows'), + 'Rovo Dev installer cleans legacy workflows output', + ); + + const tempProjectDir26 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-rovodev-test-')); + const installedBmadDir26 = await createTestBmadFixture(); + const legacyDir26 = path.join(tempProjectDir26, '.rovodev', 'workflows'); + await fs.ensureDir(legacyDir26); + await fs.writeFile(path.join(legacyDir26, 'bmad-legacy.md'), 'legacy\n'); + + // Create a prompts.yml with BMAD entries and a user entry + const yaml26 = require('yaml'); + const promptsPath26 = path.join(tempProjectDir26, '.rovodev', 'prompts.yml'); + const promptsContent26 = yaml26.stringify({ + prompts: [ + { name: 'bmad-bmm-create-prd', description: 'BMAD workflow', content_file: 'workflows/bmad-bmm-create-prd.md' }, + { name: 'my-custom-prompt', description: 'User prompt', content_file: 'custom.md' }, + ], + }); + await fs.writeFile(promptsPath26, promptsContent26); + + const ideManager26 = new IdeManager(); + await ideManager26.ensureInitialized(); + const result26 = await ideManager26.setup('rovo-dev', tempProjectDir26, installedBmadDir26, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result26.success === true, 'Rovo Dev setup succeeds against temp project'); + + const skillFile26 = path.join(tempProjectDir26, '.rovodev', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile26), 'Rovo Dev install writes SKILL.md directory output'); + + // Verify name frontmatter matches directory name + const skillContent26 = await fs.readFile(skillFile26, 'utf8'); + const nameMatch26 = skillContent26.match(/^name:\s*(.+)$/m); + assert(nameMatch26 && nameMatch26[1].trim() === 'bmad-master', 'Rovo Dev skill name frontmatter matches directory name exactly'); + + assert(!(await fs.pathExists(path.join(tempProjectDir26, '.rovodev', 'workflows'))), 'Rovo Dev setup removes legacy workflows dir'); + + // Verify prompts.yml cleanup: BMAD entries removed, user entry preserved + const cleanedPrompts26 = yaml26.parse(await fs.readFile(promptsPath26, 'utf8')); + assert( + Array.isArray(cleanedPrompts26.prompts) && cleanedPrompts26.prompts.length === 1, + 'Rovo Dev cleanup removes BMAD entries from prompts.yml', + ); + assert(cleanedPrompts26.prompts[0].name === 'my-custom-prompt', 'Rovo Dev cleanup preserves non-BMAD entries in prompts.yml'); + + await fs.remove(tempProjectDir26); + await fs.remove(installedBmadDir26); + } catch (error) { + assert(false, 'Rovo Dev native skills migration test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Suite 27: Cleanup preserves bmad-os-* skills + // ============================================================ + console.log(`${colors.yellow}Test Suite 27: Cleanup preserves bmad-os-* skills${colors.reset}\n`); + + try { + const tempProjectDir27 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-os-preserve-test-')); + const installedBmadDir27 = await createTestBmadFixture(); + + // Pre-populate .claude/skills with bmad-os-* skills (version-controlled repo skills) + const osSkillDir27 = path.join(tempProjectDir27, '.claude', 'skills', 'bmad-os-review-pr'); + await fs.ensureDir(osSkillDir27); + await fs.writeFile( + path.join(osSkillDir27, 'SKILL.md'), + '---\nname: bmad-os-review-pr\ndescription: Review PRs\n---\nOS skill content\n', + ); + + const osSkillDir27b = path.join(tempProjectDir27, '.claude', 'skills', 'bmad-os-release-module'); + await fs.ensureDir(osSkillDir27b); + await fs.writeFile( + path.join(osSkillDir27b, 'SKILL.md'), + '---\nname: bmad-os-release-module\ndescription: Release module\n---\nOS skill content\n', + ); + + // Also add a regular bmad skill that SHOULD be cleaned up + const regularSkillDir27 = path.join(tempProjectDir27, '.claude', 'skills', 'bmad-architect'); + await fs.ensureDir(regularSkillDir27); + await fs.writeFile( + path.join(regularSkillDir27, 'SKILL.md'), + '---\nname: bmad-architect\ndescription: Architect\n---\nOld skill content\n', + ); + + // Run Claude Code setup (which triggers cleanup then install) + const ideManager27 = new IdeManager(); + await ideManager27.ensureInitialized(); + const result27 = await ideManager27.setup('claude-code', tempProjectDir27, installedBmadDir27, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result27.success === true, 'Claude Code setup succeeds with bmad-os-* skills present'); + + // bmad-os-* skills must survive + assert(await fs.pathExists(osSkillDir27), 'Cleanup preserves bmad-os-review-pr skill'); + assert(await fs.pathExists(osSkillDir27b), 'Cleanup preserves bmad-os-release-module skill'); + + // bmad-os skill content must be untouched + const osContent27 = await fs.readFile(path.join(osSkillDir27, 'SKILL.md'), 'utf8'); + assert(osContent27.includes('OS skill content'), 'bmad-os-review-pr skill content is unchanged'); + + // Regular bmad skill should have been replaced by fresh install + const newSkillFile27 = path.join(tempProjectDir27, '.claude', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(newSkillFile27), 'Fresh bmad skills are installed alongside preserved bmad-os-* skills'); + + // Stale non-bmad-os skill must have been removed by cleanup + assert(!(await fs.pathExists(regularSkillDir27)), 'Cleanup removes stale non-bmad-os skills'); + + await fs.remove(tempProjectDir27); + await fs.remove(installedBmadDir27); + } catch (error) { + assert(false, 'bmad-os-* skill preservation test succeeds', error.message); + } + + console.log(''); + + // ============================================================ + // Suite 28: Pi Native Skills + // ============================================================ + console.log(`${colors.yellow}Test Suite 28: Pi Native Skills${colors.reset}\n`); + + let tempProjectDir28; + let installedBmadDir28; + try { + clearCache(); + const platformCodes28 = await loadPlatformCodes(); + const piInstaller = platformCodes28.platforms.pi?.installer; + + assert(piInstaller?.target_dir === '.pi/skills', 'Pi target_dir uses native skills path'); + assert(piInstaller?.skill_format === true, 'Pi installer enables native skill output'); + assert(piInstaller?.template_type === 'default', 'Pi installer uses default skill template'); + + tempProjectDir28 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-pi-test-')); + installedBmadDir28 = await createTestBmadFixture(); + + const ideManager28 = new IdeManager(); + await ideManager28.ensureInitialized(); + + // Verify Pi is selectable in available IDEs list + const availableIdes28 = ideManager28.getAvailableIdes(); + assert( + availableIdes28.some((ide) => ide.value === 'pi'), + 'Pi appears in available IDEs list', + ); + + // Verify Pi is NOT detected before install + const detectedBefore28 = await ideManager28.detectInstalledIdes(tempProjectDir28); + assert(!detectedBefore28.includes('pi'), 'Pi is not detected before install'); + + const result28 = await ideManager28.setup('pi', tempProjectDir28, installedBmadDir28, { + silent: true, + selectedModules: ['bmm'], + }); + + assert(result28.success === true, 'Pi setup succeeds against temp project'); + + // Verify Pi IS detected after install + const detectedAfter28 = await ideManager28.detectInstalledIdes(tempProjectDir28); + assert(detectedAfter28.includes('pi'), 'Pi is detected after install'); + + const skillFile28 = path.join(tempProjectDir28, '.pi', 'skills', 'bmad-master', 'SKILL.md'); + assert(await fs.pathExists(skillFile28), 'Pi install writes SKILL.md directory output'); + + // Parse YAML frontmatter between --- markers + const skillContent28 = await fs.readFile(skillFile28, 'utf8'); + const fmMatch28 = skillContent28.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/); + assert(fmMatch28, 'Pi SKILL.md contains valid frontmatter delimiters'); + + const frontmatter28 = fmMatch28[1]; + const body28 = fmMatch28[2]; + + // Verify name in frontmatter matches directory name + const fmName28 = frontmatter28.match(/^name:\s*(.+)$/m); + assert(fmName28 && fmName28[1].trim() === 'bmad-master', 'Pi skill name frontmatter matches directory name exactly'); + + // Verify description exists and is non-empty + const fmDesc28 = frontmatter28.match(/^description:\s*(.+)$/m); + assert(fmDesc28 && fmDesc28[1].trim().length > 0, 'Pi skill description frontmatter is present and non-empty'); + + // Verify frontmatter contains only name and description keys + const fmKeys28 = [...frontmatter28.matchAll(/^([a-zA-Z0-9_-]+):/gm)].map((m) => m[1]); + assert( + fmKeys28.length === 2 && fmKeys28.includes('name') && fmKeys28.includes('description'), + 'Pi skill frontmatter contains only name and description keys', + ); + + // Verify body content is non-empty and contains expected activation instructions + assert(body28.trim().length > 0, 'Pi skill body content is non-empty'); + assert(body28.includes('agent-activation'), 'Pi skill body contains expected agent activation instructions'); + + // Reinstall/upgrade: run setup again over existing output + const result28b = await ideManager28.setup('pi', tempProjectDir28, installedBmadDir28, { + silent: true, + selectedModules: ['bmm'], + }); + assert(result28b.success === true, 'Pi reinstall/upgrade succeeds over existing skills'); + assert(await fs.pathExists(skillFile28), 'Pi reinstall preserves SKILL.md output'); + } catch (error) { + assert(false, 'Pi native skills test succeeds', error.message); + } finally { + if (tempProjectDir28) await fs.remove(tempProjectDir28).catch(() => {}); + if (installedBmadDir28) await fs.remove(installedBmadDir28).catch(() => {}); + } + + console.log(''); + + // ============================================================ + // Suite 29: Unified Skill Scanner — collectSkills + // ============================================================ + console.log(`${colors.yellow}Test Suite 29: Unified Skill Scanner${colors.reset}\n`); + + let tempFixture29; + try { + tempFixture29 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-skill-scanner-')); + + // Create _config dir (required by manifest generator) + await fs.ensureDir(path.join(tempFixture29, '_config')); + + // --- Skill at unusual path: core/custom-area/my-skill/ --- + const skillDir29 = path.join(tempFixture29, 'core', 'custom-area', 'my-skill'); + await fs.ensureDir(skillDir29); + await fs.writeFile(path.join(skillDir29, 'bmad-skill-manifest.yaml'), 'type: skill\n'); + await fs.writeFile( + path.join(skillDir29, 'SKILL.md'), + '---\nname: my-skill\ndescription: A skill at an unusual path\n---\n\nFollow the instructions in [workflow.md](workflow.md).\n', + ); + await fs.writeFile(path.join(skillDir29, 'workflow.md'), '# My Custom Skill\n\nSkill body content\n'); + + // --- Regular workflow dir: core/workflows/regular-wf/ (type: workflow) --- + const wfDir29 = path.join(tempFixture29, 'core', 'workflows', 'regular-wf'); + await fs.ensureDir(wfDir29); + await fs.writeFile(path.join(wfDir29, 'bmad-skill-manifest.yaml'), 'type: workflow\ncanonicalId: regular-wf\n'); + await fs.writeFile( + path.join(wfDir29, 'workflow.md'), + '---\nname: Regular Workflow\ndescription: A regular workflow not a skill\n---\n\nWorkflow body\n', + ); + + // --- Skill inside workflows/ dir: core/workflows/wf-skill/ (exercises findWorkflows skip logic) --- + const wfSkillDir29 = path.join(tempFixture29, 'core', 'workflows', 'wf-skill'); + await fs.ensureDir(wfSkillDir29); + await fs.writeFile(path.join(wfSkillDir29, 'bmad-skill-manifest.yaml'), 'type: skill\n'); + await fs.writeFile( + path.join(wfSkillDir29, 'SKILL.md'), + '---\nname: wf-skill\ndescription: A skill inside workflows dir\n---\n\nFollow the instructions in [workflow.md](workflow.md).\n', + ); + await fs.writeFile(path.join(wfSkillDir29, 'workflow.md'), '# Workflow Skill\n\nSkill in workflows\n'); + + // --- Skill inside tasks/ dir: core/tasks/task-skill/ --- + const taskSkillDir29 = path.join(tempFixture29, 'core', 'tasks', 'task-skill'); + await fs.ensureDir(taskSkillDir29); + await fs.writeFile(path.join(taskSkillDir29, 'bmad-skill-manifest.yaml'), 'type: skill\n'); + await fs.writeFile( + path.join(taskSkillDir29, 'SKILL.md'), + '---\nname: task-skill\ndescription: A skill inside tasks dir\n---\n\nFollow the instructions in [workflow.md](workflow.md).\n', + ); + await fs.writeFile(path.join(taskSkillDir29, 'workflow.md'), '# Task Skill\n\nSkill in tasks\n'); + + // Minimal agent so core module is detected + await fs.ensureDir(path.join(tempFixture29, 'core', 'agents')); + const minimalAgent29 = 'p'; + await fs.writeFile(path.join(tempFixture29, 'core', 'agents', 'test.md'), minimalAgent29); + + const generator29 = new ManifestGenerator(); + await generator29.generateManifests(tempFixture29, ['core'], [], { ides: [] }); + + // Skill at unusual path should be in skills + const skillEntry29 = generator29.skills.find((s) => s.canonicalId === 'my-skill'); + assert(skillEntry29 !== undefined, 'Skill at unusual path appears in skills[]'); + assert(skillEntry29 && skillEntry29.name === 'my-skill', 'Skill has correct name from frontmatter'); + assert( + skillEntry29 && skillEntry29.path.includes('custom-area/my-skill/SKILL.md'), + 'Skill path includes relative path from module root', + ); + + // Skill should NOT be in workflows + const inWorkflows29 = generator29.workflows.find((w) => w.name === 'my-skill'); + assert(inWorkflows29 === undefined, 'Skill at unusual path does NOT appear in workflows[]'); + + // Skill in tasks/ dir should be in skills + const taskSkillEntry29 = generator29.skills.find((s) => s.canonicalId === 'task-skill'); + assert(taskSkillEntry29 !== undefined, 'Skill in tasks/ dir appears in skills[]'); + + // Skill in tasks/ should NOT appear in tasks[] + const inTasks29 = generator29.tasks.find((t) => t.name === 'task-skill'); + assert(inTasks29 === undefined, 'Skill in tasks/ dir does NOT appear in tasks[]'); + + // Regular workflow should be in workflows, NOT in skills + const regularWf29 = generator29.workflows.find((w) => w.name === 'Regular Workflow'); + assert(regularWf29 !== undefined, 'Regular type:workflow appears in workflows[]'); + + const regularInSkills29 = generator29.skills.find((s) => s.canonicalId === 'regular-wf'); + assert(regularInSkills29 === undefined, 'Regular type:workflow does NOT appear in skills[]'); + + // Skill inside workflows/ should be in skills[], NOT in workflows[] (exercises findWorkflows skip at lines 311/322) + const wfSkill29 = generator29.skills.find((s) => s.canonicalId === 'wf-skill'); + assert(wfSkill29 !== undefined, 'Skill in workflows/ dir appears in skills[]'); + const wfSkillInWorkflows29 = generator29.workflows.find((w) => w.name === 'wf-skill'); + assert(wfSkillInWorkflows29 === undefined, 'Skill in workflows/ dir does NOT appear in workflows[]'); + + // Test scanInstalledModules recognizes skill-only modules + const skillOnlyModDir29 = path.join(tempFixture29, 'skill-only-mod'); + await fs.ensureDir(path.join(skillOnlyModDir29, 'deep', 'nested', 'my-skill')); + await fs.writeFile(path.join(skillOnlyModDir29, 'deep', 'nested', 'my-skill', 'bmad-skill-manifest.yaml'), 'type: skill\n'); + await fs.writeFile( + path.join(skillOnlyModDir29, 'deep', 'nested', 'my-skill', 'SKILL.md'), + '---\nname: my-skill\ndescription: desc\n---\n\nFollow the instructions in [workflow.md](workflow.md).\n', + ); + await fs.writeFile(path.join(skillOnlyModDir29, 'deep', 'nested', 'my-skill', 'workflow.md'), '# Nested Skill\n\nbody\n'); + + const scannedModules29 = await generator29.scanInstalledModules(tempFixture29); + assert(scannedModules29.includes('skill-only-mod'), 'scanInstalledModules recognizes skill-only module'); + } catch (error) { + assert(false, 'Unified skill scanner test succeeds', error.message); + } finally { + if (tempFixture29) await fs.remove(tempFixture29).catch(() => {}); + } + + console.log(''); + + // ============================================================ + // Suite 30: parseSkillMd validation (negative cases) + // ============================================================ + console.log(`${colors.yellow}Test Suite 30: parseSkillMd Validation${colors.reset}\n`); + + let tempFixture30; + try { + tempFixture30 = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-test-30-')); + + const generator30 = new ManifestGenerator(); + generator30.bmadFolderName = '_bmad'; + + // Case 1: Missing SKILL.md entirely + const noSkillDir = path.join(tempFixture30, 'no-skill-md'); + await fs.ensureDir(noSkillDir); + const result1 = await generator30.parseSkillMd(path.join(noSkillDir, 'SKILL.md'), noSkillDir, 'no-skill-md'); + assert(result1 === null, 'parseSkillMd returns null when SKILL.md is missing'); + + // Case 2: SKILL.md with no frontmatter + const noFmDir = path.join(tempFixture30, 'no-frontmatter'); + await fs.ensureDir(noFmDir); + await fs.writeFile(path.join(noFmDir, 'SKILL.md'), '# Just a heading\n\nNo frontmatter here.\n'); + const result2 = await generator30.parseSkillMd(path.join(noFmDir, 'SKILL.md'), noFmDir, 'no-frontmatter'); + assert(result2 === null, 'parseSkillMd returns null when SKILL.md has no frontmatter'); + + // Case 3: SKILL.md missing description + const noDescDir = path.join(tempFixture30, 'no-desc'); + await fs.ensureDir(noDescDir); + await fs.writeFile(path.join(noDescDir, 'SKILL.md'), '---\nname: no-desc\n---\n\nBody.\n'); + const result3 = await generator30.parseSkillMd(path.join(noDescDir, 'SKILL.md'), noDescDir, 'no-desc'); + assert(result3 === null, 'parseSkillMd returns null when description is missing'); + + // Case 4: SKILL.md missing name + const noNameDir = path.join(tempFixture30, 'no-name'); + await fs.ensureDir(noNameDir); + await fs.writeFile(path.join(noNameDir, 'SKILL.md'), '---\ndescription: has desc but no name\n---\n\nBody.\n'); + const result4 = await generator30.parseSkillMd(path.join(noNameDir, 'SKILL.md'), noNameDir, 'no-name'); + assert(result4 === null, 'parseSkillMd returns null when name is missing'); + + // Case 5: Name mismatch + const mismatchDir = path.join(tempFixture30, 'actual-dir-name'); + await fs.ensureDir(mismatchDir); + await fs.writeFile(path.join(mismatchDir, 'SKILL.md'), '---\nname: wrong-name\ndescription: A skill\n---\n\nBody.\n'); + const result5 = await generator30.parseSkillMd(path.join(mismatchDir, 'SKILL.md'), mismatchDir, 'actual-dir-name'); + assert(result5 === null, 'parseSkillMd returns null when name does not match directory name'); + + // Case 6: Valid SKILL.md (positive control) + const validDir = path.join(tempFixture30, 'valid-skill'); + await fs.ensureDir(validDir); + await fs.writeFile(path.join(validDir, 'SKILL.md'), '---\nname: valid-skill\ndescription: A valid skill\n---\n\nBody.\n'); + const result6 = await generator30.parseSkillMd(path.join(validDir, 'SKILL.md'), validDir, 'valid-skill'); + assert(result6 !== null && result6.name === 'valid-skill', 'parseSkillMd returns metadata for valid SKILL.md'); + + // Case 7: Malformed YAML (non-object) + const malformedDir = path.join(tempFixture30, 'malformed'); + await fs.ensureDir(malformedDir); + await fs.writeFile(path.join(malformedDir, 'SKILL.md'), '---\njust a string\n---\n\nBody.\n'); + const result7 = await generator30.parseSkillMd(path.join(malformedDir, 'SKILL.md'), malformedDir, 'malformed'); + assert(result7 === null, 'parseSkillMd returns null for non-object YAML frontmatter'); + } catch (error) { + assert(false, 'parseSkillMd validation test succeeds', error.message); + } finally { + if (tempFixture30) await fs.remove(tempFixture30).catch(() => {}); + } + + console.log(''); + + // ============================================================ + // Test 31: Skill-format installs report unique skill directories + // ============================================================ + console.log(`${colors.yellow}Test Suite 31: Skill Count Reporting${colors.reset}\n`); + + let collisionFixtureRoot = null; + let collisionProjectDir = null; + + try { + clearCache(); + const collisionFixture = await createSkillCollisionFixture(); + collisionFixtureRoot = collisionFixture.root; + collisionProjectDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-antigravity-test-')); + + const ideManager = new IdeManager(); + await ideManager.ensureInitialized(); + const result = await ideManager.setup('antigravity', collisionProjectDir, collisionFixture.bmadDir, { + silent: true, + selectedModules: ['core'], + }); + + assert(result.success === true, 'Antigravity setup succeeds with overlapping skill names'); + assert(result.detail === '2 agents', 'Installer detail reports agents separately from skills'); + assert(result.handlerResult.results.skillDirectories === 2, 'Result exposes unique skill directory count'); + assert(result.handlerResult.results.agents === 2, 'Result retains generated agent write count'); + assert(result.handlerResult.results.workflows === 1, 'Result retains generated workflow count'); + assert(result.handlerResult.results.skills === 1, 'Result retains verbatim skill count'); + assert( + await fs.pathExists(path.join(collisionProjectDir, '.agent', 'skills', 'bmad-agent-bmad-master', 'SKILL.md')), + 'Agent skill directory is created', + ); + assert( + await fs.pathExists(path.join(collisionProjectDir, '.agent', 'skills', 'bmad-help', 'SKILL.md')), + 'Overlapping skill directory is created once', + ); + } catch (error) { + assert(false, 'Skill-format unique count test succeeds', error.message); + } finally { + if (collisionProjectDir) await fs.remove(collisionProjectDir).catch(() => {}); + if (collisionFixtureRoot) await fs.remove(collisionFixtureRoot).catch(() => {}); + } + + console.log(''); + // ============================================================ // Summary // ============================================================ diff --git a/test/test-workflow-path-regex.js b/test/test-workflow-path-regex.js new file mode 100644 index 000000000..5f57a0ab9 --- /dev/null +++ b/test/test-workflow-path-regex.js @@ -0,0 +1,88 @@ +/** + * Workflow Path Regex Tests + * + * Tests that the source and install workflow path regexes in ModuleManager + * extract the correct capture groups (module name and workflow sub-path). + * + * Usage: node test/test-workflow-path-regex.js + */ + +// ANSI colors +const colors = { + reset: '\u001B[0m', + green: '\u001B[32m', + red: '\u001B[31m', + cyan: '\u001B[36m', + dim: '\u001B[2m', +}; + +let passed = 0; +let failed = 0; + +function assert(condition, testName, errorMessage = '') { + if (condition) { + console.log(`${colors.green}✓${colors.reset} ${testName}`); + passed++; + } else { + console.log(`${colors.red}✗${colors.reset} ${testName}`); + if (errorMessage) { + console.log(` ${colors.dim}${errorMessage}${colors.reset}`); + } + failed++; + } +} + +// --------------------------------------------------------------------------- +// These regexes are extracted from ModuleManager.vendorWorkflowDependencies() +// in tools/cli/installers/lib/modules/manager.js +// --------------------------------------------------------------------------- + +// Source regex (line ~1081) — uses non-capturing group for _bmad +const SOURCE_REGEX = /\{project-root\}\/(?:_bmad)\/([^/]+)\/workflows\/(.+)/; + +// Install regex (line ~1091) — uses non-capturing group for _bmad, +// consistent with source regex +const INSTALL_REGEX = /\{project-root\}\/(?:_bmad)\/([^/]+)\/workflows\/(.+)/; + +// --------------------------------------------------------------------------- +// Test data +// --------------------------------------------------------------------------- +const sourcePath = '{project-root}/_bmad/bmm/workflows/4-implementation/bmad-create-story/workflow.md'; +const installPath = '{project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.md'; + +console.log(`\n${colors.cyan}Workflow Path Regex Tests${colors.reset}\n`); + +// --- Source regex tests (these should pass — source regex is correct) --- + +const sourceMatch = sourcePath.match(SOURCE_REGEX); + +assert(sourceMatch !== null, 'Source regex matches source path'); +assert( + sourceMatch && sourceMatch[1] === 'bmm', + 'Source regex group [1] is the module name', + `Expected "bmm", got "${sourceMatch && sourceMatch[1]}"`, +); +assert( + sourceMatch && sourceMatch[2] === '4-implementation/bmad-create-story/workflow.md', + 'Source regex group [2] is the workflow sub-path', + `Expected "4-implementation/bmad-create-story/workflow.md", got "${sourceMatch && sourceMatch[2]}"`, +); + +// --- Install regex tests (group [2] returns module name, not sub-path) --- + +const installMatch = installPath.match(INSTALL_REGEX); + +assert(installMatch !== null, 'Install regex matches install path'); + +// This is the critical test: installMatch[2] should be the workflow sub-path, +// because the code uses it as `installWorkflowSubPath`. +// With the bug, installMatch[2] is "bmgd" (module name) instead of the sub-path. +assert( + installMatch && installMatch[2] === '4-production/create-story/workflow.md', + 'Install regex group [2] is the workflow sub-path (used as installWorkflowSubPath)', + `Expected "4-production/create-story/workflow.md", got "${installMatch && installMatch[2]}"`, +); + +// --- Summary --- +console.log(`\n${passed} passed, ${failed} failed\n`); +process.exit(failed > 0 ? 1 : 0); diff --git a/tools/build-docs.mjs b/tools/build-docs.mjs index bf04eb911..5ea825f2d 100644 --- a/tools/build-docs.mjs +++ b/tools/build-docs.mjs @@ -161,6 +161,7 @@ function generateLlmsTxt(outputDir) { '## Core Concepts', '', `- **[Quick Flow](${siteUrl}/explanation/quick-flow/)** - Fast development workflow`, + `- **[Quick Dev New Preview](${siteUrl}/explanation/quick-dev-new-preview/)** - Unified quick workflow with planning, implementation, and review in one run`, `- **[Party Mode](${siteUrl}/explanation/party-mode/)** - Multi-agent collaboration`, `- **[Workflow Map](${siteUrl}/reference/workflow-map/)** - Visual overview of phases and workflows`, '', diff --git a/tools/cli/external-official-modules.yaml b/tools/cli/external-official-modules.yaml index d6ae06ee6..986cd7fe4 100644 --- a/tools/cli/external-official-modules.yaml +++ b/tools/cli/external-official-modules.yaml @@ -2,15 +2,15 @@ # allowing us to keep the source of these projects in separate repos. modules: - bmad-builder: - url: https://github.com/bmad-code-org/bmad-builder - module-definition: src/module.yaml - code: bmb - name: "BMad Builder" - description: "Agent, Workflow and Module Builder" - defaultSelected: false - type: bmad-org - npmPackage: bmad-builder + # bmad-builder: + # url: https://github.com/bmad-code-org/bmad-builder + # module-definition: src/module.yaml + # code: bmb + # name: "BMad Builder" + # description: "Agent, Workflow and Module Builder" + # defaultSelected: false + # type: bmad-org + # npmPackage: bmad-builder bmad-creative-intelligence-suite: url: https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite @@ -42,12 +42,12 @@ modules: type: bmad-org npmPackage: bmad-method-test-architecture-enterprise - # whiteport-design-system: - # url: https://github.com/bmad-code-org/bmad-method-wds-expansion - # module-definition: src/module.yaml - # code: wds - # name: "Whiteport UX Design System" - # description: "UX design framework with Figma integration" - # defaultSelected: false - # type: community - # npmPackage: bmad-method-wds-expansion + whiteport-design-studio: + url: https://github.com/bmad-code-org/bmad-method-wds-expansion + module-definition: src/module.yaml + code: wds + name: "Whiteport Design Studio (For UX Professionals)" + description: "Whiteport Design Studio (For UX Professionals)" + defaultSelected: false + type: community + npmPackage: bmad-method-wds-expansion diff --git a/tools/cli/installers/install-messages.yaml b/tools/cli/installers/install-messages.yaml index b14265165..0fc32cc82 100644 --- a/tools/cli/installers/install-messages.yaml +++ b/tools/cli/installers/install-messages.yaml @@ -12,7 +12,7 @@ startMessage: | - Select and install modules during setup - customize your experience - New BMad Method for Agile AI-Driven Development (the evolution of V4) - Exciting new modules available during installation, with community modules coming soon - - Documentation: docs.bmad-method.com + - Documentation: https://docs.bmad-method.org 🌟 BMad is 100% free and open source. - No gated Discord. No paywalls. No gated content. diff --git a/tools/cli/installers/lib/core/installer.js b/tools/cli/installers/lib/core/installer.js index fe8b88d7c..85864145f 100644 --- a/tools/cli/installers/lib/core/installer.js +++ b/tools/cli/installers/lib/core/installer.js @@ -713,10 +713,30 @@ class Installer { } // Merge tool selection into config (for both quick update and regular flow) - config.ides = toolSelection.ides; + // Normalize IDE keys to lowercase so they match handler map keys consistently + config.ides = (toolSelection.ides || []).map((ide) => ide.toLowerCase()); config.skipIde = toolSelection.skipIde; const ideConfigurations = toolSelection.configurations; + // Early check: fail fast if ALL selected IDEs are suspended + if (config.ides && config.ides.length > 0) { + await this.ideManager.ensureInitialized(); + const suspendedIdes = config.ides.filter((ide) => { + const handler = this.ideManager.handlers.get(ide); + return handler?.platformConfig?.suspended; + }); + + if (suspendedIdes.length > 0 && suspendedIdes.length === config.ides.length) { + for (const ide of suspendedIdes) { + const handler = this.ideManager.handlers.get(ide); + await prompts.log.error(`${handler.displayName || ide}: ${handler.platformConfig.suspended}`); + } + throw new Error( + `All selected tool(s) are suspended: ${suspendedIdes.join(', ')}. Installation aborted to prevent upgrading _bmad/ without a working IDE configuration.`, + ); + } + } + // Detect IDEs that were previously installed but are NOT in the new selection (to be removed) if (config._isUpdate && config._existingInstall) { const previouslyInstalledIdes = new Set(config._existingInstall.ides || []); @@ -1133,12 +1153,6 @@ class Installer { preservedModules: modulesForCsvPreserve, }); - addResult( - 'Manifests', - 'ok', - `${manifestStats.workflows} workflows, ${manifestStats.agents} agents, ${manifestStats.tasks} tasks, ${manifestStats.tools} tools`, - ); - // Merge help catalogs message('Generating help catalog...'); await this.mergeModuleHelpCatalogs(bmadDir); @@ -1335,6 +1349,19 @@ class Installer { } catch { // Ensure the original error is never swallowed by a logging failure } + + // Clean up any temp backup directories that were created before the failure + try { + if (config._tempBackupDir && (await fs.pathExists(config._tempBackupDir))) { + await fs.remove(config._tempBackupDir); + } + if (config._tempModifiedBackupDir && (await fs.pathExists(config._tempModifiedBackupDir))) { + await fs.remove(config._tempModifiedBackupDir); + } + } catch { + // Best-effort cleanup — don't mask the original error + } + throw error; } } @@ -1346,10 +1373,27 @@ class Installer { */ async renderInstallSummary(results, context = {}) { const color = await prompts.getColor(); + const selectedIdes = new Set((context.ides || []).map((ide) => String(ide).toLowerCase())); // Build step lines with status indicators const lines = []; for (const r of results) { + let stepLabel = null; + + if (r.status !== 'ok') { + stepLabel = r.step; + } else if (r.step === 'Core') { + stepLabel = 'BMAD'; + } else if (r.step.startsWith('Module: ')) { + stepLabel = r.step; + } else if (selectedIdes.has(String(r.step).toLowerCase())) { + stepLabel = r.step; + } + + if (!stepLabel) { + continue; + } + let icon; if (r.status === 'ok') { icon = color.green('\u2713'); @@ -1359,7 +1403,11 @@ class Installer { icon = color.red('\u2717'); } const detail = r.detail ? color.dim(` (${r.detail})`) : ''; - lines.push(` ${icon} ${r.step}${detail}`); + lines.push(` ${icon} ${stepLabel}${detail}`); + } + + if ((context.ides || []).length === 0) { + lines.push(` ${color.green('\u2713')} No IDE selected ${color.dim('(installed in _bmad only)')}`); } // Context and warnings @@ -1382,8 +1430,10 @@ 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`, ); + if (context.ides && context.ides.length > 0) { + lines.push(` 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!'); } diff --git a/tools/cli/installers/lib/core/manifest-generator.js b/tools/cli/installers/lib/core/manifest-generator.js index bc4694a6d..5dc4ff078 100644 --- a/tools/cli/installers/lib/core/manifest-generator.js +++ b/tools/cli/installers/lib/core/manifest-generator.js @@ -5,6 +5,12 @@ const crypto = require('node:crypto'); const csv = require('csv-parse/sync'); const { getSourcePath, getModulePath } = require('../../../lib/project-root'); const prompts = require('../../../lib/prompts'); +const { + loadSkillManifest: loadSkillManifestShared, + getCanonicalId: getCanonicalIdShared, + getArtifactType: getArtifactTypeShared, + getInstallToBmad: getInstallToBmadShared, +} = require('../ide/shared/skill-manifest'); // Load package.json for version info const packageJson = require('../../../../../package.json'); @@ -15,6 +21,7 @@ const packageJson = require('../../../../../package.json'); class ManifestGenerator { constructor() { this.workflows = []; + this.skills = []; this.agents = []; this.tasks = []; this.tools = []; @@ -23,17 +30,35 @@ class ManifestGenerator { this.selectedIdes = []; } + /** Delegate to shared skill-manifest module */ + async loadSkillManifest(dirPath) { + return loadSkillManifestShared(dirPath); + } + + /** Delegate to shared skill-manifest module */ + getCanonicalId(manifest, filename) { + return getCanonicalIdShared(manifest, filename); + } + + /** Delegate to shared skill-manifest module */ + getArtifactType(manifest, filename) { + return getArtifactTypeShared(manifest, filename); + } + + /** Delegate to shared skill-manifest module */ + getInstallToBmad(manifest, filename) { + return getInstallToBmadShared(manifest, filename); + } + /** - * Clean text for CSV output by normalizing whitespace and escaping quotes + * Clean text for CSV output by normalizing whitespace. + * Note: Quote escaping is handled by escapeCsv() at write time. * @param {string} text - Text to clean - * @returns {string} Cleaned text safe for CSV + * @returns {string} Cleaned text */ cleanForCSV(text) { if (!text) return ''; - return text - .trim() - .replaceAll(/\s+/g, ' ') // Normalize all whitespace (including newlines) to single space - .replaceAll('"', '""'); // Escape quotes for CSV + return text.trim().replaceAll(/\s+/g, ' '); // Normalize all whitespace (including newlines) to single space } /** @@ -80,6 +105,12 @@ class ManifestGenerator { // Filter out any undefined/null values from IDE list this.selectedIdes = resolvedIdes.filter((ide) => ide && typeof ide === 'string'); + // Reset files list (defensive: prevent stale data if instance is reused) + this.files = []; + + // Collect skills first (populates skillClaimedDirs before legacy collectors run) + await this.collectSkills(); + // Collect workflow data await this.collectWorkflows(selectedModules); @@ -96,6 +127,7 @@ class ManifestGenerator { const manifestFiles = [ await this.writeMainManifest(cfgDir), await this.writeWorkflowManifest(cfgDir), + await this.writeSkillManifest(cfgDir), await this.writeAgentManifest(cfgDir), await this.writeTaskManifest(cfgDir), await this.writeToolManifest(cfgDir), @@ -103,6 +135,7 @@ class ManifestGenerator { ]; return { + skills: this.skills.length, workflows: this.workflows.length, agents: this.agents.length, tasks: this.tasks.length, @@ -112,6 +145,169 @@ class ManifestGenerator { }; } + /** + * Recursively walk a module directory tree, collecting skill directories. + * A skill directory is one that contains both a bmad-skill-manifest.yaml with + * type: skill AND a SKILL.md file with name/description frontmatter. + * Populates this.skills[] and this.skillClaimedDirs (Set of absolute paths). + */ + async collectSkills() { + this.skills = []; + this.skillClaimedDirs = new Set(); + const debug = process.env.BMAD_DEBUG_MANIFEST === 'true'; + + for (const moduleName of this.updatedModules) { + const modulePath = path.join(this.bmadDir, moduleName); + if (!(await fs.pathExists(modulePath))) continue; + + // Recursive walk skipping . and _ prefixed dirs + const walk = async (dir) => { + let entries; + try { + entries = await fs.readdir(dir, { withFileTypes: true }); + } catch { + return; + } + + // Check this directory for skill manifest + const manifest = await this.loadSkillManifest(dir); + + // Determine if this directory is a skill (type: skill in manifest) + const skillFile = 'SKILL.md'; + const artifactType = this.getArtifactType(manifest, skillFile); + + if (artifactType === 'skill') { + const skillMdPath = path.join(dir, 'SKILL.md'); + const dirName = path.basename(dir); + + // Validate and parse SKILL.md + const skillMeta = await this.parseSkillMd(skillMdPath, dir, dirName, debug); + + if (skillMeta) { + // Build path relative from module root (points to SKILL.md — the permanent entrypoint) + const relativePath = path.relative(modulePath, dir).split(path.sep).join('/'); + const installPath = relativePath + ? `${this.bmadFolderName}/${moduleName}/${relativePath}/${skillFile}` + : `${this.bmadFolderName}/${moduleName}/${skillFile}`; + + // Skills derive canonicalId from directory name — never from manifest + if (manifest && manifest.__single && manifest.__single.canonicalId) { + console.warn( + `Warning: Skill manifest at ${dir}/bmad-skill-manifest.yaml contains canonicalId — this field is ignored for skills (directory name is the canonical ID)`, + ); + } + const canonicalId = dirName; + + this.skills.push({ + name: skillMeta.name, + description: this.cleanForCSV(skillMeta.description), + module: moduleName, + path: installPath, + canonicalId, + install_to_bmad: this.getInstallToBmad(manifest, skillFile), + }); + + // Add to files list + this.files.push({ + type: 'skill', + name: skillMeta.name, + module: moduleName, + path: installPath, + }); + + this.skillClaimedDirs.add(dir); + + if (debug) { + console.log(`[DEBUG] collectSkills: claimed skill "${skillMeta.name}" as ${canonicalId} at ${dir}`); + } + } + } + + // Warn if manifest says type:skill but directory was not claimed + if (manifest && !this.skillClaimedDirs.has(dir)) { + let hasSkillType = false; + if (manifest.__single) { + hasSkillType = manifest.__single.type === 'skill'; + } else { + for (const key of Object.keys(manifest)) { + if (manifest[key]?.type === 'skill') { + hasSkillType = true; + break; + } + } + } + if (hasSkillType && debug) { + console.log(`[DEBUG] collectSkills: dir has type:skill manifest but failed validation: ${dir}`); + } + } + + // Recurse into subdirectories + for (const entry of entries) { + if (!entry.isDirectory()) continue; + if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue; + await walk(path.join(dir, entry.name)); + } + }; + + await walk(modulePath); + } + + if (debug) { + console.log(`[DEBUG] collectSkills: total skills found: ${this.skills.length}, claimed dirs: ${this.skillClaimedDirs.size}`); + } + } + + /** + * Parse and validate SKILL.md for a skill directory. + * Returns parsed frontmatter object with name/description, or null if invalid. + * @param {string} skillMdPath - Absolute path to SKILL.md + * @param {string} dir - Skill directory path (for error messages) + * @param {string} dirName - Expected name (must match frontmatter name) + * @param {boolean} debug - Whether to emit debug-level messages + * @returns {Promise} Parsed frontmatter or null + */ + async parseSkillMd(skillMdPath, dir, dirName, debug = false) { + if (!(await fs.pathExists(skillMdPath))) { + if (debug) console.log(`[DEBUG] parseSkillMd: "${dir}" is missing SKILL.md — skipping`); + return null; + } + + try { + const rawContent = await fs.readFile(skillMdPath, 'utf8'); + const content = rawContent.replaceAll('\r\n', '\n').replaceAll('\r', '\n'); + + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + if (frontmatterMatch) { + const skillMeta = yaml.parse(frontmatterMatch[1]); + + if ( + !skillMeta || + typeof skillMeta !== 'object' || + typeof skillMeta.name !== 'string' || + typeof skillMeta.description !== 'string' || + !skillMeta.name || + !skillMeta.description + ) { + if (debug) console.log(`[DEBUG] parseSkillMd: SKILL.md in "${dir}" is missing name or description (or wrong type) — skipping`); + return null; + } + + if (skillMeta.name !== dirName) { + console.error(`Error: SKILL.md name "${skillMeta.name}" does not match directory name "${dirName}" — skipping`); + return null; + } + + return skillMeta; + } + + if (debug) console.log(`[DEBUG] parseSkillMd: SKILL.md in "${dir}" has no frontmatter — skipping`); + return null; + } catch (error) { + if (debug) console.log(`[DEBUG] parseSkillMd: failed to parse SKILL.md in "${dir}": ${error.message} — skipping`); + return null; + } + } + /** * Collect all workflows from core and selected modules * Scans the INSTALLED bmad directory, not the source @@ -126,16 +322,20 @@ class ManifestGenerator { if (await fs.pathExists(modulePath)) { const moduleWorkflows = await this.getWorkflowsFromPath(modulePath, moduleName); this.workflows.push(...moduleWorkflows); + + // Also scan tasks/ for type:skill entries (skills can live anywhere) + const tasksSkills = await this.getWorkflowsFromPath(modulePath, moduleName, 'tasks'); + this.workflows.push(...tasksSkills); } } } /** - * Recursively find and parse workflow.yaml and workflow.md files + * Recursively find and parse workflow.md files */ - async getWorkflowsFromPath(basePath, moduleName) { + async getWorkflowsFromPath(basePath, moduleName, subDir = 'workflows') { const workflows = []; - const workflowsPath = path.join(basePath, 'workflows'); + const workflowsPath = path.join(basePath, subDir); const debug = process.env.BMAD_DEBUG_MANIFEST === 'true'; if (debug) { @@ -149,22 +349,25 @@ class ManifestGenerator { return workflows; } - // Recursively find workflow.yaml files + // Recursively find workflow.md files const findWorkflows = async (dir, relativePath = '') => { + // Skip directories already claimed as skills + if (this.skillClaimedDirs && this.skillClaimedDirs.has(dir)) return; + const entries = await fs.readdir(dir, { withFileTypes: true }); + // Load skill manifest for this directory (if present) + const skillManifest = await this.loadSkillManifest(dir); for (const entry of entries) { const fullPath = path.join(dir, entry.name); if (entry.isDirectory()) { + // Skip directories claimed by collectSkills + if (this.skillClaimedDirs && this.skillClaimedDirs.has(fullPath)) continue; // Recurse into subdirectories const newRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name; await findWorkflows(fullPath, newRelativePath); - } else if ( - entry.name === 'workflow.yaml' || - entry.name === 'workflow.md' || - (entry.name.startsWith('workflow-') && entry.name.endsWith('.md')) - ) { + } else if (entry.name === 'workflow.md' || (entry.name.startsWith('workflow-') && entry.name.endsWith('.md'))) { // Parse workflow file (both YAML and MD formats) if (debug) { console.log(`[DEBUG] Found workflow file: ${fullPath}`); @@ -174,21 +377,15 @@ class ManifestGenerator { const rawContent = await fs.readFile(fullPath, 'utf8'); const content = rawContent.replaceAll('\r\n', '\n').replaceAll('\r', '\n'); - let workflow; - if (entry.name === 'workflow.yaml') { - // Parse YAML workflow - workflow = yaml.parse(content); - } else { - // Parse MD workflow with YAML frontmatter - const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); - if (!frontmatterMatch) { - if (debug) { - console.log(`[DEBUG] Skipped (no frontmatter): ${fullPath}`); - } - continue; // Skip MD files without frontmatter + // Parse MD workflow with YAML frontmatter + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + if (!frontmatterMatch) { + if (debug) { + console.log(`[DEBUG] Skipped (no frontmatter): ${fullPath}`); } - workflow = yaml.parse(frontmatterMatch[1]); + continue; // Skip MD files without frontmatter } + const workflow = yaml.parse(frontmatterMatch[1]); if (debug) { console.log(`[DEBUG] Parsed: name="${workflow.name}", description=${workflow.description ? 'OK' : 'MISSING'}`); @@ -214,8 +411,8 @@ class ManifestGenerator { // Build relative path for installation const installPath = moduleName === 'core' - ? `${this.bmadFolderName}/core/workflows/${relativePath}/${entry.name}` - : `${this.bmadFolderName}/${moduleName}/workflows/${relativePath}/${entry.name}`; + ? `${this.bmadFolderName}/core/${subDir}/${relativePath}/${entry.name}` + : `${this.bmadFolderName}/${moduleName}/${subDir}/${relativePath}/${entry.name}`; // Workflows with standalone: false are filtered out above workflows.push({ @@ -223,6 +420,7 @@ class ManifestGenerator { description: this.cleanForCSV(workflow.description), module: moduleName, path: installPath, + canonicalId: this.getCanonicalId(skillManifest, entry.name), }); // Add to files list @@ -294,13 +492,19 @@ class ManifestGenerator { * Only includes compiled .md files (not .agent.yaml source files) */ async getAgentsFromDir(dirPath, moduleName, relativePath = '') { + // Skip directories claimed by collectSkills + if (this.skillClaimedDirs && this.skillClaimedDirs.has(dirPath)) return []; const agents = []; const entries = await fs.readdir(dirPath, { withFileTypes: true }); + // Load skill manifest for this directory (if present) + const skillManifest = await this.loadSkillManifest(dirPath); for (const entry of entries) { const fullPath = path.join(dirPath, entry.name); if (entry.isDirectory()) { + // Skip directories claimed by collectSkills + if (this.skillClaimedDirs && this.skillClaimedDirs.has(fullPath)) continue; // Recurse into subdirectories const newRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name; const subDirAgents = await this.getAgentsFromDir(fullPath, moduleName, newRelativePath); @@ -351,6 +555,7 @@ class ManifestGenerator { principles: principlesMatch ? this.cleanForCSV(principlesMatch[1]) : '', module: moduleName, path: installPath, + canonicalId: this.getCanonicalId(skillManifest, entry.name), }); // Add to files list @@ -388,8 +593,12 @@ class ManifestGenerator { * Get tasks from a directory */ async getTasksFromDir(dirPath, moduleName) { + // Skip directories claimed by collectSkills + if (this.skillClaimedDirs && this.skillClaimedDirs.has(dirPath)) return []; const tasks = []; const files = await fs.readdir(dirPath); + // Load skill manifest for this directory (if present) + const skillManifest = await this.loadSkillManifest(dirPath); for (const file of files) { // Check for both .xml and .md files @@ -449,6 +658,7 @@ class ManifestGenerator { module: moduleName, path: installPath, standalone: standalone, + canonicalId: this.getCanonicalId(skillManifest, file), }); // Add to files list @@ -486,8 +696,12 @@ class ManifestGenerator { * Get tools from a directory */ async getToolsFromDir(dirPath, moduleName) { + // Skip directories claimed by collectSkills + if (this.skillClaimedDirs && this.skillClaimedDirs.has(dirPath)) return []; const tools = []; const files = await fs.readdir(dirPath); + // Load skill manifest for this directory (if present) + const skillManifest = await this.loadSkillManifest(dirPath); for (const file of files) { // Check for both .xml and .md files @@ -547,6 +761,7 @@ class ManifestGenerator { module: moduleName, path: installPath, standalone: standalone, + canonicalId: this.getCanonicalId(skillManifest, file), }); // Add to files list @@ -737,8 +952,8 @@ class ManifestGenerator { const csvPath = path.join(cfgDir, 'workflow-manifest.csv'); const escapeCsv = (value) => `"${String(value ?? '').replaceAll('"', '""')}"`; - // Create CSV header - standalone column removed, everything is canonicalized to 4 columns - let csv = 'name,description,module,path\n'; + // Create CSV header - standalone column removed, canonicalId added as optional column + let csv = 'name,description,module,path,canonicalId\n'; // Build workflows map from discovered workflows only // Old entries are NOT preserved - the manifest reflects what actually exists on disk @@ -752,12 +967,19 @@ class ManifestGenerator { description: workflow.description, module: workflow.module, path: workflow.path, + canonicalId: workflow.canonicalId || '', }); } // Write all workflows for (const [, value] of allWorkflows) { - const row = [escapeCsv(value.name), escapeCsv(value.description), escapeCsv(value.module), escapeCsv(value.path)].join(','); + const row = [ + escapeCsv(value.name), + escapeCsv(value.description), + escapeCsv(value.module), + escapeCsv(value.path), + escapeCsv(value.canonicalId), + ].join(','); csv += row + '\n'; } @@ -765,6 +987,32 @@ class ManifestGenerator { return csvPath; } + /** + * Write skill manifest CSV + * @returns {string} Path to the manifest file + */ + async writeSkillManifest(cfgDir) { + const csvPath = path.join(cfgDir, 'skill-manifest.csv'); + const escapeCsv = (value) => `"${String(value ?? '').replaceAll('"', '""')}"`; + + let csvContent = 'canonicalId,name,description,module,path,install_to_bmad\n'; + + for (const skill of this.skills) { + const row = [ + escapeCsv(skill.canonicalId), + escapeCsv(skill.name), + escapeCsv(skill.description), + escapeCsv(skill.module), + escapeCsv(skill.path), + escapeCsv(skill.install_to_bmad), + ].join(','); + csvContent += row + '\n'; + } + + await fs.writeFile(csvPath, csvContent); + return csvPath; + } + /** * Write agent manifest CSV * @returns {string} Path to the manifest file @@ -786,8 +1034,8 @@ class ManifestGenerator { } } - // Create CSV header with persona fields - let csvContent = 'name,displayName,title,icon,capabilities,role,identity,communicationStyle,principles,module,path\n'; + // Create CSV header with persona fields and canonicalId + let csvContent = 'name,displayName,title,icon,capabilities,role,identity,communicationStyle,principles,module,path,canonicalId\n'; // Combine existing and new agents, preferring new data for duplicates const allAgents = new Map(); @@ -812,6 +1060,7 @@ class ManifestGenerator { principles: agent.principles, module: agent.module, path: agent.path, + canonicalId: agent.canonicalId || '', }); } @@ -829,6 +1078,7 @@ class ManifestGenerator { escapeCsv(record.principles), escapeCsv(record.module), escapeCsv(record.path), + escapeCsv(record.canonicalId), ].join(','); csvContent += row + '\n'; } @@ -858,8 +1108,8 @@ class ManifestGenerator { } } - // Create CSV header with standalone column - let csvContent = 'name,displayName,description,module,path,standalone\n'; + // Create CSV header with standalone and canonicalId columns + let csvContent = 'name,displayName,description,module,path,standalone,canonicalId\n'; // Combine existing and new tasks const allTasks = new Map(); @@ -879,6 +1129,7 @@ class ManifestGenerator { module: task.module, path: task.path, standalone: task.standalone, + canonicalId: task.canonicalId || '', }); } @@ -891,6 +1142,7 @@ class ManifestGenerator { escapeCsv(record.module), escapeCsv(record.path), escapeCsv(record.standalone), + escapeCsv(record.canonicalId), ].join(','); csvContent += row + '\n'; } @@ -920,8 +1172,8 @@ class ManifestGenerator { } } - // Create CSV header with standalone column - let csvContent = 'name,displayName,description,module,path,standalone\n'; + // Create CSV header with standalone and canonicalId columns + let csvContent = 'name,displayName,description,module,path,standalone,canonicalId\n'; // Combine existing and new tools const allTools = new Map(); @@ -941,6 +1193,7 @@ class ManifestGenerator { module: tool.module, path: tool.path, standalone: tool.standalone, + canonicalId: tool.canonicalId || '', }); } @@ -953,6 +1206,7 @@ class ManifestGenerator { escapeCsv(record.module), escapeCsv(record.path), escapeCsv(record.standalone), + escapeCsv(record.canonicalId), ].join(','); csvContent += row + '\n'; } @@ -1067,8 +1321,14 @@ class ManifestGenerator { const hasTasks = await fs.pathExists(path.join(modulePath, 'tasks')); const hasTools = await fs.pathExists(path.join(modulePath, 'tools')); - // If it has any of these directories, it's likely a module - if (hasAgents || hasWorkflows || hasTasks || hasTools) { + // Check for skill-only modules: recursive scan for bmad-skill-manifest.yaml with type: skill + let hasSkills = false; + if (!hasAgents && !hasWorkflows && !hasTasks && !hasTools) { + hasSkills = await this._hasSkillManifestRecursive(modulePath); + } + + // If it has any of these directories or skill manifests, it's likely a module + if (hasAgents || hasWorkflows || hasTasks || hasTools || hasSkills) { modules.push(entry.name); } } @@ -1078,6 +1338,37 @@ class ManifestGenerator { return modules; } + + /** + * Recursively check if a directory tree contains a bmad-skill-manifest.yaml with type: skill. + * Skips directories starting with . or _. + * @param {string} dir - Directory to search + * @returns {boolean} True if a skill manifest is found + */ + async _hasSkillManifestRecursive(dir) { + let entries; + try { + entries = await fs.readdir(dir, { withFileTypes: true }); + } catch { + return false; + } + + // Check for manifest in this directory + const manifest = await this.loadSkillManifest(dir); + if (manifest) { + const type = this.getArtifactType(manifest, 'workflow.md'); + if (type === 'skill') return true; + } + + // Recurse into subdirectories + for (const entry of entries) { + if (!entry.isDirectory()) continue; + if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue; + if (await this._hasSkillManifestRecursive(path.join(dir, entry.name))) return true; + } + + return false; + } } module.exports = { ManifestGenerator }; diff --git a/tools/cli/installers/lib/ide/_base-ide.js b/tools/cli/installers/lib/ide/_base-ide.js index 9bfbdcf30..ce1b0ceae 100644 --- a/tools/cli/installers/lib/ide/_base-ide.js +++ b/tools/cli/installers/lib/ide/_base-ide.js @@ -289,7 +289,7 @@ class BaseIdeSetup { // Get core workflows const coreWorkflowsPath = path.join(bmadDir, 'core', 'workflows'); if (await fs.pathExists(coreWorkflowsPath)) { - const coreWorkflows = await this.findWorkflowYamlFiles(coreWorkflowsPath); + const coreWorkflows = await this.findWorkflowFiles(coreWorkflowsPath); workflows.push( ...coreWorkflows.map((w) => ({ ...w, @@ -304,7 +304,7 @@ class BaseIdeSetup { if (entry.isDirectory() && entry.name !== 'core' && entry.name !== '_config' && entry.name !== 'agents') { const moduleWorkflowsPath = path.join(bmadDir, entry.name, 'workflows'); if (await fs.pathExists(moduleWorkflowsPath)) { - const moduleWorkflows = await this.findWorkflowYamlFiles(moduleWorkflowsPath); + const moduleWorkflows = await this.findWorkflowFiles(moduleWorkflowsPath); workflows.push( ...moduleWorkflows.map((w) => ({ ...w, @@ -324,11 +324,13 @@ class BaseIdeSetup { } /** - * Recursively find workflow.yaml files + * Recursively find workflow.md files * @param {string} dir - Directory to search + * @param {string} [rootDir] - Original root directory (used internally for recursion) * @returns {Array} List of workflow file info objects */ - async findWorkflowYamlFiles(dir) { + async findWorkflowFiles(dir, rootDir = null) { + rootDir = rootDir || dir; const workflows = []; if (!(await fs.pathExists(dir))) { @@ -342,14 +344,16 @@ class BaseIdeSetup { if (entry.isDirectory()) { // Recursively search subdirectories - const subWorkflows = await this.findWorkflowYamlFiles(fullPath); + const subWorkflows = await this.findWorkflowFiles(fullPath, rootDir); workflows.push(...subWorkflows); - } else if (entry.isFile() && entry.name === 'workflow.yaml') { - // Read workflow.yaml to get name and standalone property + } else if (entry.isFile() && entry.name === 'workflow.md') { + // Read workflow.md frontmatter to get name and standalone property try { - const yaml = require('yaml'); const content = await fs.readFile(fullPath, 'utf8'); - const workflowData = yaml.parse(content); + const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); + if (!frontmatterMatch) continue; + + const workflowData = yaml.parse(frontmatterMatch[1]); if (workflowData && workflowData.name) { // Workflows are standalone by default unless explicitly false @@ -357,7 +361,7 @@ class BaseIdeSetup { workflows.push({ name: workflowData.name, path: fullPath, - relativePath: path.relative(dir, fullPath), + relativePath: path.relative(rootDir, fullPath), filename: entry.name, description: workflowData.description || '', standalone: standalone, @@ -376,9 +380,11 @@ class BaseIdeSetup { * Scan a directory for files with specific extension(s) * @param {string} dir - Directory to scan * @param {string|Array} ext - File extension(s) to match (e.g., '.md' or ['.md', '.xml']) + * @param {string} [rootDir] - Original root directory (used internally for recursion) * @returns {Array} List of file info objects */ - async scanDirectory(dir, ext) { + async scanDirectory(dir, ext, rootDir = null) { + rootDir = rootDir || dir; const files = []; if (!(await fs.pathExists(dir))) { @@ -395,7 +401,7 @@ class BaseIdeSetup { if (entry.isDirectory()) { // Recursively scan subdirectories - const subFiles = await this.scanDirectory(fullPath, ext); + const subFiles = await this.scanDirectory(fullPath, ext, rootDir); files.push(...subFiles); } else if (entry.isFile()) { // Check if file matches any of the extensions @@ -404,7 +410,7 @@ class BaseIdeSetup { files.push({ name: path.basename(entry.name, matchedExt), path: fullPath, - relativePath: path.relative(dir, fullPath), + relativePath: path.relative(rootDir, fullPath), filename: entry.name, }); } @@ -418,9 +424,11 @@ class BaseIdeSetup { * Scan a directory for files with specific extension(s) and check standalone attribute * @param {string} dir - Directory to scan * @param {string|Array} ext - File extension(s) to match (e.g., '.md' or ['.md', '.xml']) + * @param {string} [rootDir] - Original root directory (used internally for recursion) * @returns {Array} List of file info objects with standalone property */ - async scanDirectoryWithStandalone(dir, ext) { + async scanDirectoryWithStandalone(dir, ext, rootDir = null) { + rootDir = rootDir || dir; const files = []; if (!(await fs.pathExists(dir))) { @@ -437,7 +445,7 @@ class BaseIdeSetup { if (entry.isDirectory()) { // Recursively scan subdirectories - const subFiles = await this.scanDirectoryWithStandalone(fullPath, ext); + const subFiles = await this.scanDirectoryWithStandalone(fullPath, ext, rootDir); files.push(...subFiles); } else if (entry.isFile()) { // Check if file matches any of the extensions @@ -481,7 +489,7 @@ class BaseIdeSetup { files.push({ name: path.basename(entry.name, matchedExt), path: fullPath, - relativePath: path.relative(dir, fullPath), + relativePath: path.relative(rootDir, fullPath), filename: entry.name, standalone: standalone, }); diff --git a/tools/cli/installers/lib/ide/_config-driven.js b/tools/cli/installers/lib/ide/_config-driven.js index 9541c75ed..a93fe0c87 100644 --- a/tools/cli/installers/lib/ide/_config-driven.js +++ b/tools/cli/installers/lib/ide/_config-driven.js @@ -1,10 +1,13 @@ +const os = require('node:os'); const path = require('node:path'); const fs = require('fs-extra'); +const yaml = require('yaml'); const { BaseIdeSetup } = require('./_base-ide'); const prompts = require('../../../lib/prompts'); const { AgentCommandGenerator } = require('./shared/agent-command-generator'); const { WorkflowCommandGenerator } = require('./shared/workflow-command-generator'); const { TaskToolCommandGenerator } = require('./shared/task-tool-command-generator'); +const csv = require('csv-parse/sync'); /** * Config-driven IDE setup handler @@ -24,6 +27,34 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { super(platformCode, platformConfig.name, platformConfig.preferred); this.platformConfig = platformConfig; this.installerConfig = platformConfig.installer || null; + + // Set configDir from target_dir so base-class detect() works + if (this.installerConfig?.target_dir) { + this.configDir = this.installerConfig.target_dir; + } + } + + /** + * Detect whether this IDE already has configuration in the project. + * For skill_format platforms, checks for bmad-prefixed entries in target_dir + * (matching old codex.js behavior) instead of just checking directory existence. + * @param {string} projectDir - Project directory + * @returns {Promise} + */ + async detect(projectDir) { + if (this.installerConfig?.skill_format && this.configDir) { + const dir = path.join(projectDir || process.cwd(), this.configDir); + if (await fs.pathExists(dir)) { + try { + const entries = await fs.readdir(dir); + return entries.some((e) => typeof e === 'string' && e.startsWith('bmad')); + } catch { + return false; + } + } + return false; + } + return super.detect(projectDir); } /** @@ -34,6 +65,25 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { * @returns {Promise} Setup result */ async setup(projectDir, bmadDir, options = {}) { + // Check for BMAD files in ancestor directories that would cause duplicates + if (this.installerConfig?.ancestor_conflict_check) { + const conflict = await this.findAncestorConflict(projectDir); + if (conflict) { + await prompts.log.error( + `Found existing BMAD skills in ancestor installation: ${conflict}\n` + + ` ${this.name} inherits skills from parent directories, so this would cause duplicates.\n` + + ` Please remove the BMAD files from that directory first:\n` + + ` rm -rf "${conflict}"/bmad*`, + ); + return { + success: false, + reason: 'ancestor-conflict', + error: `Ancestor conflict: ${conflict}`, + conflictDir: conflict, + }; + } + } + if (!options.silent) await prompts.log.info(`Setting up ${this.name}...`); // Clean up any old BMAD installation first @@ -67,42 +117,54 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { async installToTarget(projectDir, bmadDir, config, options) { const { target_dir, template_type, artifact_types } = config; - // Skip targets with explicitly empty artifact_types array + // Skip targets with explicitly empty artifact_types and no verbatim skills // This prevents creating empty directories when no artifacts will be written - if (Array.isArray(artifact_types) && artifact_types.length === 0) { - return { success: true, results: { agents: 0, workflows: 0, tasks: 0, tools: 0 } }; + const skipStandardArtifacts = Array.isArray(artifact_types) && artifact_types.length === 0; + if (skipStandardArtifacts && !config.skill_format) { + return { success: true, results: { agents: 0, workflows: 0, tasks: 0, tools: 0, skills: 0 } }; } const targetPath = path.join(projectDir, target_dir); await this.ensureDir(targetPath); const selectedModules = options.selectedModules || []; - const results = { agents: 0, workflows: 0, tasks: 0, tools: 0 }; + const results = { agents: 0, workflows: 0, tasks: 0, tools: 0, skills: 0 }; + this.skillWriteTracker = config.skill_format ? new Set() : null; - // Install agents - if (!artifact_types || artifact_types.includes('agents')) { - const agentGen = new AgentCommandGenerator(this.bmadFolderName); - const { artifacts } = await agentGen.collectAgentArtifacts(bmadDir, selectedModules); - results.agents = await this.writeAgentArtifacts(targetPath, artifacts, template_type, config); + // Install standard artifacts (agents, workflows, tasks, tools) + if (!skipStandardArtifacts) { + // Install agents + if (!artifact_types || artifact_types.includes('agents')) { + const agentGen = new AgentCommandGenerator(this.bmadFolderName); + const { artifacts } = await agentGen.collectAgentArtifacts(bmadDir, selectedModules); + results.agents = await this.writeAgentArtifacts(targetPath, artifacts, template_type, config); + } + + // Install workflows + if (!artifact_types || artifact_types.includes('workflows')) { + const workflowGen = new WorkflowCommandGenerator(this.bmadFolderName); + const { artifacts } = await workflowGen.collectWorkflowArtifacts(bmadDir); + results.workflows = await this.writeWorkflowArtifacts(targetPath, artifacts, template_type, config); + } + + // Install tasks and tools using template system (supports TOML for Gemini, MD for others) + if (!artifact_types || artifact_types.includes('tasks') || artifact_types.includes('tools')) { + const taskToolGen = new TaskToolCommandGenerator(this.bmadFolderName); + const { artifacts } = await taskToolGen.collectTaskToolArtifacts(bmadDir); + const taskToolResult = await this.writeTaskToolArtifacts(targetPath, artifacts, template_type, config); + results.tasks = taskToolResult.tasks || 0; + results.tools = taskToolResult.tools || 0; + } } - // Install workflows - if (!artifact_types || artifact_types.includes('workflows')) { - const workflowGen = new WorkflowCommandGenerator(this.bmadFolderName); - const { artifacts } = await workflowGen.collectWorkflowArtifacts(bmadDir); - results.workflows = await this.writeWorkflowArtifacts(targetPath, artifacts, template_type, config); - } - - // Install tasks and tools using template system (supports TOML for Gemini, MD for others) - if (!artifact_types || artifact_types.includes('tasks') || artifact_types.includes('tools')) { - const taskToolGen = new TaskToolCommandGenerator(this.bmadFolderName); - const { artifacts } = await taskToolGen.collectTaskToolArtifacts(bmadDir); - const taskToolResult = await this.writeTaskToolArtifacts(targetPath, artifacts, template_type, config); - results.tasks = taskToolResult.tasks || 0; - results.tools = taskToolResult.tools || 0; + // Install verbatim skills (type: skill) + if (config.skill_format) { + results.skills = await this.installVerbatimSkills(projectDir, bmadDir, targetPath, config); + results.skillDirectories = this.skillWriteTracker ? this.skillWriteTracker.size : 0; } await this.printSummary(results, target_dir, options); + this.skillWriteTracker = null; return { success: true, results }; } @@ -115,7 +177,7 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { * @returns {Promise} Installation result */ async installToMultipleTargets(projectDir, bmadDir, targets, options) { - const allResults = { agents: 0, workflows: 0, tasks: 0, tools: 0 }; + const allResults = { agents: 0, workflows: 0, tasks: 0, tools: 0, skills: 0 }; for (const target of targets) { const result = await this.installToTarget(projectDir, bmadDir, target, options); @@ -124,6 +186,7 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { allResults.workflows += result.results.workflows || 0; allResults.tasks += result.results.tasks || 0; allResults.tools += result.results.tools || 0; + allResults.skills += result.results.skills || 0; } } @@ -146,8 +209,13 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { for (const artifact of artifacts) { const content = this.renderTemplate(template, artifact); const filename = this.generateFilename(artifact, 'agent', extension); - const filePath = path.join(targetPath, filename); - await this.writeFile(filePath, content); + + if (config.skill_format) { + await this.writeSkillFile(targetPath, artifact, content); + } else { + const filePath = path.join(targetPath, filename); + await this.writeFile(filePath, content); + } count++; } @@ -167,20 +235,17 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { for (const artifact of artifacts) { if (artifact.type === 'workflow-command') { - // Use different template based on workflow type (YAML vs MD) - // Default to 'default' template type, but allow override via config - const workflowTemplateType = artifact.isYamlWorkflow - ? config.yaml_workflow_template || `${templateType}-workflow-yaml` - : config.md_workflow_template || `${templateType}-workflow`; - - // Fall back to default templates if specific ones don't exist - const finalTemplateType = artifact.isYamlWorkflow ? 'default-workflow-yaml' : 'default-workflow'; - // workflowTemplateType already contains full name (e.g., 'gemini-workflow-yaml'), so pass empty artifactType - const { content: template, extension } = await this.loadTemplate(workflowTemplateType, '', config, finalTemplateType); + const workflowTemplateType = config.md_workflow_template || `${templateType}-workflow`; + const { content: template, extension } = await this.loadTemplate(workflowTemplateType, '', config, 'default-workflow'); const content = this.renderTemplate(template, artifact); const filename = this.generateFilename(artifact, 'workflow', extension); - const filePath = path.join(targetPath, filename); - await this.writeFile(filePath, content); + + if (config.skill_format) { + await this.writeSkillFile(targetPath, artifact, content); + } else { + const filePath = path.join(targetPath, filename); + await this.writeFile(filePath, content); + } count++; } } @@ -222,8 +287,13 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup { const content = this.renderTemplate(template, artifact); const filename = this.generateFilename(artifact, artifact.type, extension); - const filePath = path.join(targetPath, filename); - await this.writeFile(filePath, content); + + if (config.skill_format) { + await this.writeSkillFile(targetPath, artifact, content); + } else { + const filePath = path.join(targetPath, filename); + await this.writeFile(filePath, content); + } if (artifact.type === 'task') { taskCount++; @@ -353,7 +423,6 @@ You must fully embody this agent's persona and follow all activation instruction return `--- name: '{{name}}' description: '{{description}}' -disable-model-invocation: true --- # {{name}} @@ -391,22 +460,147 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} // No default } - let rendered = template + // Replace _bmad placeholder with actual folder name BEFORE inserting paths, + // so that paths containing '_bmad' are not corrupted by the blanket replacement. + let rendered = template.replaceAll('_bmad', this.bmadFolderName); + + // Replace {{bmadFolderName}} placeholder if present + rendered = rendered.replaceAll('{{bmadFolderName}}', this.bmadFolderName); + + rendered = rendered .replaceAll('{{name}}', artifact.name || '') .replaceAll('{{module}}', artifact.module || 'core') .replaceAll('{{path}}', pathToUse) .replaceAll('{{description}}', artifact.description || `${artifact.name} ${artifact.type || ''}`) .replaceAll('{{workflow_path}}', pathToUse); - // Replace _bmad placeholder with actual folder name - rendered = rendered.replaceAll('_bmad', this.bmadFolderName); - - // Replace {{bmadFolderName}} placeholder if present - rendered = rendered.replaceAll('{{bmadFolderName}}', this.bmadFolderName); - return rendered; } + /** + * Write artifact as a skill directory with SKILL.md inside. + * Writes artifact as a skill directory with SKILL.md inside. + * @param {string} targetPath - Base skills directory + * @param {Object} artifact - Artifact data + * @param {string} content - Rendered template content + */ + async writeSkillFile(targetPath, artifact, content) { + const { resolveSkillName } = require('./shared/path-utils'); + + // Get the skill name (prefers canonicalId, falls back to path-derived) and remove .md + const flatName = resolveSkillName(artifact); + const skillName = path.basename(flatName.replace(/\.md$/, '')); + + if (!skillName) { + throw new Error(`Cannot derive skill name for artifact: ${artifact.relativePath || JSON.stringify(artifact)}`); + } + + // Create skill directory + const skillDir = path.join(targetPath, skillName); + await this.ensureDir(skillDir); + this.skillWriteTracker?.add(skillName); + + // Transform content: rewrite frontmatter for skills format + const skillContent = this.transformToSkillFormat(content, skillName); + + await this.writeFile(path.join(skillDir, 'SKILL.md'), skillContent); + } + + /** + * Transform artifact content to Agent Skills format. + * Rewrites frontmatter to contain only unquoted name and description. + * @param {string} content - Original content with YAML frontmatter + * @param {string} skillName - Skill name (must match directory name) + * @returns {string} Transformed content + */ + transformToSkillFormat(content, skillName) { + // Normalize line endings + content = content.replaceAll('\r\n', '\n').replaceAll('\r', '\n'); + + // Parse frontmatter + const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/); + if (!fmMatch) { + // No frontmatter -- wrap with minimal frontmatter + const fm = yaml.stringify({ name: skillName, description: skillName }).trimEnd(); + return `---\n${fm}\n---\n\n${content}`; + } + + const frontmatter = fmMatch[1]; + const body = fmMatch[2]; + + // Parse frontmatter with yaml library to extract description + let description; + try { + const parsed = yaml.parse(frontmatter); + const rawDesc = parsed?.description; + description = typeof rawDesc === 'string' && rawDesc ? rawDesc : `${skillName} skill`; + } catch { + description = `${skillName} skill`; + } + + // Build new frontmatter with only name and description, unquoted + const newFrontmatter = yaml.stringify({ name: skillName, description: String(description) }, { lineWidth: 0 }).trimEnd(); + return `---\n${newFrontmatter}\n---\n${body}`; + } + + /** + * Install a custom agent launcher. + * For skill_format platforms, produces /SKILL.md. + * For flat platforms, produces a single file in target_dir. + * @param {string} projectDir - Project directory + * @param {string} agentName - Agent name (e.g., "fred-commit-poet") + * @param {string} agentPath - Path to compiled agent (relative to project root) + * @param {Object} metadata - Agent metadata + * @returns {Object|null} Info about created file/skill + */ + async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) { + if (!this.installerConfig?.target_dir) return null; + + const { customAgentDashName } = require('./shared/path-utils'); + const targetPath = path.join(projectDir, this.installerConfig.target_dir); + await this.ensureDir(targetPath); + + // Build artifact to reuse existing template rendering. + // The default-agent template already includes the _bmad/ prefix before {{path}}, + // but agentPath is relative to project root (e.g. "_bmad/custom/agents/fred.md"). + // Strip the bmadFolderName prefix so the template doesn't produce a double path. + const bmadPrefix = this.bmadFolderName + '/'; + const normalizedPath = agentPath.startsWith(bmadPrefix) ? agentPath.slice(bmadPrefix.length) : agentPath; + + const artifact = { + type: 'agent-launcher', + name: agentName, + description: metadata?.description || `${agentName} agent`, + agentPath: normalizedPath, + relativePath: normalizedPath, + module: 'custom', + }; + + const { content: template } = await this.loadTemplate( + this.installerConfig.template_type || 'default', + 'agent', + this.installerConfig, + 'default-agent', + ); + const content = this.renderTemplate(template, artifact); + + if (this.installerConfig.skill_format) { + const skillName = customAgentDashName(agentName).replace(/\.md$/, ''); + const skillDir = path.join(targetPath, skillName); + await this.ensureDir(skillDir); + const skillContent = this.transformToSkillFormat(content, skillName); + const skillPath = path.join(skillDir, 'SKILL.md'); + await this.writeFile(skillPath, skillContent); + return { path: path.relative(projectDir, skillPath), command: `$${skillName}` }; + } + + // Flat file output + const filename = customAgentDashName(agentName); + const filePath = path.join(targetPath, filename); + await this.writeFile(filePath, content); + return { path: path.relative(projectDir, filePath), command: agentName }; + } + /** * Generate filename for artifact * @param {Object} artifact - Artifact data @@ -415,10 +609,11 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} * @returns {string} Generated filename */ generateFilename(artifact, artifactType, extension = '.md') { - const { toDashPath } = require('./shared/path-utils'); + const { resolveSkillName } = require('./shared/path-utils'); // Reuse central logic to ensure consistent naming conventions - const standardName = toDashPath(artifact.relativePath); + // Prefers canonicalId from manifest when available, falls back to path-derived name + const standardName = resolveSkillName(artifact); // Clean up potential double extensions from source files (e.g. .yaml.md, .xml.md -> .md) // This handles any extensions that might slip through toDashPath() @@ -434,6 +629,81 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} return baseName.replace(/\.md$/, extension); } + /** + * Install verbatim skill directories (type: skill entries from skill-manifest.csv). + * Copies the entire source directory as-is into the IDE skill directory. + * The source SKILL.md is used directly — no frontmatter transformation or file generation. + * @param {string} projectDir - Project directory + * @param {string} bmadDir - BMAD installation directory + * @param {string} targetPath - Target skills directory + * @param {Object} config - Installation configuration + * @returns {Promise} Count of skills installed + */ + async installVerbatimSkills(projectDir, bmadDir, targetPath, config) { + const bmadFolderName = path.basename(bmadDir); + const bmadPrefix = bmadFolderName + '/'; + const csvPath = path.join(bmadDir, '_config', 'skill-manifest.csv'); + + if (!(await fs.pathExists(csvPath))) return 0; + + const csvContent = await fs.readFile(csvPath, 'utf8'); + const records = csv.parse(csvContent, { + columns: true, + skip_empty_lines: true, + }); + + let count = 0; + + for (const record of records) { + const canonicalId = record.canonicalId; + if (!canonicalId) continue; + + // Derive source directory from path column + // path is like "_bmad/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/SKILL.md" + // Strip bmadFolderName prefix and join with bmadDir, then get dirname + const relativePath = record.path.startsWith(bmadPrefix) ? record.path.slice(bmadPrefix.length) : record.path; + const sourceFile = path.join(bmadDir, relativePath); + const sourceDir = path.dirname(sourceFile); + + if (!(await fs.pathExists(sourceDir))) continue; + + // Clean target before copy to prevent stale files + const skillDir = path.join(targetPath, canonicalId); + await fs.remove(skillDir); + await fs.ensureDir(skillDir); + this.skillWriteTracker?.add(canonicalId); + + // Copy all skill files, filtering OS/editor artifacts recursively + const skipPatterns = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']); + const skipSuffixes = ['~', '.swp', '.swo', '.bak']; + const filter = (src) => { + const name = path.basename(src); + if (src === sourceDir) return true; + if (skipPatterns.has(name)) return false; + if (name.startsWith('.') && name !== '.gitkeep') return false; + if (skipSuffixes.some((s) => name.endsWith(s))) return false; + return true; + }; + await fs.copy(sourceDir, skillDir, { filter }); + + count++; + } + + // Post-install cleanup: remove _bmad/ directories for skills with install_to_bmad === "false" + for (const record of records) { + if (record.install_to_bmad === 'false') { + const relativePath = record.path.startsWith(bmadPrefix) ? record.path.slice(bmadPrefix.length) : record.path; + const sourceFile = path.join(bmadDir, relativePath); + const sourceDir = path.dirname(sourceFile); + if (await fs.pathExists(sourceDir)) { + await fs.remove(sourceDir); + } + } + } + + return count; + } + /** * Print installation summary * @param {Object} results - Installation results @@ -442,10 +712,11 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} async printSummary(results, targetDir, options = {}) { if (options.silent) return; const parts = []; + const totalDirs = + results.skillDirectories || (results.workflows || 0) + (results.tasks || 0) + (results.tools || 0) + (results.skills || 0); + const skillCount = totalDirs - (results.agents || 0); + if (skillCount > 0) parts.push(`${skillCount} skills`); if (results.agents > 0) parts.push(`${results.agents} agents`); - if (results.workflows > 0) parts.push(`${results.workflows} workflows`); - if (results.tasks > 0) parts.push(`${results.tasks} tasks`); - if (results.tools > 0) parts.push(`${results.tools} tools`); await prompts.log.success(`${this.name} configured: ${parts.join(', ')} → ${targetDir}`); } @@ -454,6 +725,34 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} * @param {string} projectDir - Project directory */ async cleanup(projectDir, options = {}) { + // Migrate legacy target directories (e.g. .opencode/agent → .opencode/agents) + if (this.installerConfig?.legacy_targets) { + if (!options.silent) await prompts.log.message(' Migrating legacy directories...'); + for (const legacyDir of this.installerConfig.legacy_targets) { + if (this.isGlobalPath(legacyDir)) { + await this.warnGlobalLegacy(legacyDir, options); + } else { + await this.cleanupTarget(projectDir, legacyDir, options); + await this.removeEmptyParents(projectDir, legacyDir); + } + } + } + + // Strip BMAD markers from copilot-instructions.md if present + if (this.name === 'github-copilot') { + await this.cleanupCopilotInstructions(projectDir, options); + } + + // Strip BMAD modes from .kilocodemodes if present + if (this.name === 'kilo') { + await this.cleanupKiloModes(projectDir, options); + } + + // Strip BMAD entries from .rovodev/prompts.yml if present + if (this.name === 'rovo-dev') { + await this.cleanupRovoDevPrompts(projectDir, options); + } + // Clean all target directories if (this.installerConfig?.targets) { const parentDirs = new Set(); @@ -474,6 +773,41 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} } } + /** + * Check if a path is global (starts with ~ or is absolute) + * @param {string} p - Path to check + * @returns {boolean} + */ + isGlobalPath(p) { + return p.startsWith('~') || path.isAbsolute(p); + } + + /** + * Warn about stale BMAD files in a global legacy directory (never auto-deletes) + * @param {string} legacyDir - Legacy directory path (may start with ~) + * @param {Object} options - Options (silent, etc.) + */ + async warnGlobalLegacy(legacyDir, options = {}) { + try { + const expanded = legacyDir.startsWith('~/') + ? path.join(os.homedir(), legacyDir.slice(2)) + : legacyDir === '~' + ? os.homedir() + : legacyDir; + + if (!(await fs.pathExists(expanded))) return; + + const entries = await fs.readdir(expanded); + const bmadFiles = entries.filter((e) => typeof e === 'string' && e.startsWith('bmad')); + + if (bmadFiles.length > 0 && !options.silent) { + await prompts.log.warn(`Found ${bmadFiles.length} stale BMAD file(s) in ${expanded}. Remove manually: rm ${expanded}/bmad-*`); + } + } catch { + // Errors reading global paths are silently ignored + } + } + /** * Cleanup a specific target directory * @param {string} projectDir - Project directory @@ -505,7 +839,7 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} if (!entry || typeof entry !== 'string') { continue; } - if (entry.startsWith('bmad')) { + if (entry.startsWith('bmad') && !entry.startsWith('bmad-os-')) { const entryPath = path.join(targetPath, entry); try { await fs.remove(entryPath); @@ -533,24 +867,188 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}} } } /** - * Recursively remove empty directories walking up from dir toward projectDir + * Strip BMAD-owned content from .github/copilot-instructions.md. + * The old custom installer injected content between and markers. + * Deletes the file if nothing remains. Restores .bak backup if one exists. + */ + async cleanupCopilotInstructions(projectDir, options = {}) { + const filePath = path.join(projectDir, '.github', 'copilot-instructions.md'); + + if (!(await fs.pathExists(filePath))) return; + + try { + const content = await fs.readFile(filePath, 'utf8'); + const startIdx = content.indexOf(''); + const endIdx = content.indexOf(''); + + if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) return; + + const cleaned = content.slice(0, startIdx) + content.slice(endIdx + ''.length); + + if (cleaned.trim().length === 0) { + await fs.remove(filePath); + const backupPath = `${filePath}.bak`; + if (await fs.pathExists(backupPath)) { + await fs.rename(backupPath, filePath); + if (!options.silent) await prompts.log.message(' Restored copilot-instructions.md from backup'); + } + } else { + await fs.writeFile(filePath, cleaned, 'utf8'); + const backupPath = `${filePath}.bak`; + if (await fs.pathExists(backupPath)) await fs.remove(backupPath); + } + + if (!options.silent) await prompts.log.message(' Cleaned BMAD markers from copilot-instructions.md'); + } catch { + if (!options.silent) await prompts.log.warn(' Warning: Could not clean BMAD markers from copilot-instructions.md'); + } + } + + /** + * Strip BMAD-owned modes from .kilocodemodes. + * The old custom kilo.js installer added modes with slug starting with 'bmad-'. + * Parses YAML, filters out BMAD modes, rewrites. Leaves file as-is on parse failure. + */ + async cleanupKiloModes(projectDir, options = {}) { + const kiloModesPath = path.join(projectDir, '.kilocodemodes'); + + if (!(await fs.pathExists(kiloModesPath))) return; + + const content = await fs.readFile(kiloModesPath, 'utf8'); + + let config; + try { + config = yaml.parse(content) || {}; + } catch { + if (!options.silent) await prompts.log.warn(' Warning: Could not parse .kilocodemodes for cleanup'); + return; + } + + if (!Array.isArray(config.customModes)) return; + + const originalCount = config.customModes.length; + config.customModes = config.customModes.filter((mode) => mode && (!mode.slug || !mode.slug.startsWith('bmad-'))); + const removedCount = originalCount - config.customModes.length; + + if (removedCount > 0) { + try { + await fs.writeFile(kiloModesPath, yaml.stringify(config, { lineWidth: 0 })); + if (!options.silent) await prompts.log.message(` Removed ${removedCount} BMAD modes from .kilocodemodes`); + } catch { + if (!options.silent) await prompts.log.warn(' Warning: Could not write .kilocodemodes during cleanup'); + } + } + } + + /** + * Strip BMAD-owned entries from .rovodev/prompts.yml. + * The old custom rovodev.js installer registered workflows in prompts.yml. + * Parses YAML, filters out entries with name starting with 'bmad-', rewrites. + * Removes the file if no entries remain. + */ + async cleanupRovoDevPrompts(projectDir, options = {}) { + const promptsPath = path.join(projectDir, '.rovodev', 'prompts.yml'); + + if (!(await fs.pathExists(promptsPath))) return; + + const content = await fs.readFile(promptsPath, 'utf8'); + + let config; + try { + config = yaml.parse(content) || {}; + } catch { + if (!options.silent) await prompts.log.warn(' Warning: Could not parse prompts.yml for cleanup'); + return; + } + + if (!Array.isArray(config.prompts)) return; + + const originalCount = config.prompts.length; + config.prompts = config.prompts.filter((entry) => entry && (!entry.name || !entry.name.startsWith('bmad-'))); + const removedCount = originalCount - config.prompts.length; + + if (removedCount > 0) { + try { + if (config.prompts.length === 0) { + await fs.remove(promptsPath); + } else { + await fs.writeFile(promptsPath, yaml.stringify(config, { lineWidth: 0 })); + } + if (!options.silent) await prompts.log.message(` Removed ${removedCount} BMAD entries from prompts.yml`); + } catch { + if (!options.silent) await prompts.log.warn(' Warning: Could not write prompts.yml during cleanup'); + } + } + } + + /** + * Check ancestor directories for existing BMAD files in the same target_dir. + * IDEs like Claude Code inherit commands from parent directories, so an existing + * installation in an ancestor would cause duplicate commands. + * @param {string} projectDir - Project directory being installed to + * @returns {Promise} Path to conflicting directory, or null if clean + */ + async findAncestorConflict(projectDir) { + const targetDir = this.installerConfig?.target_dir; + if (!targetDir) return null; + + const resolvedProject = await fs.realpath(path.resolve(projectDir)); + let current = path.dirname(resolvedProject); + const root = path.parse(current).root; + + while (current !== root && current.length > root.length) { + const candidatePath = path.join(current, targetDir); + try { + if (await fs.pathExists(candidatePath)) { + const entries = await fs.readdir(candidatePath); + const hasBmad = entries.some( + (e) => typeof e === 'string' && e.toLowerCase().startsWith('bmad') && !e.toLowerCase().startsWith('bmad-os-'), + ); + if (hasBmad) { + return candidatePath; + } + } + } catch { + // Can't read directory — skip + } + current = path.dirname(current); + } + + return null; + } + + /** + * Walk up ancestor directories from relativeDir toward projectDir, removing each if empty * Stops at projectDir boundary — never removes projectDir itself * @param {string} projectDir - Project root (boundary) * @param {string} relativeDir - Relative directory to start from */ async removeEmptyParents(projectDir, relativeDir) { + const resolvedProject = path.resolve(projectDir); let current = relativeDir; let last = null; while (current && current !== '.' && current !== last) { last = current; - const fullPath = path.join(projectDir, current); + const fullPath = path.resolve(projectDir, current); + // Boundary guard: never traverse outside projectDir + if (!fullPath.startsWith(resolvedProject + path.sep) && fullPath !== resolvedProject) break; try { - if (!(await fs.pathExists(fullPath))) break; + if (!(await fs.pathExists(fullPath))) { + // Dir already gone — advance current; last is reset at top of next iteration + current = path.dirname(current); + continue; + } const remaining = await fs.readdir(fullPath); if (remaining.length > 0) break; await fs.rmdir(fullPath); - } catch { - break; + } catch (error) { + // ENOTEMPTY: TOCTOU race (file added between readdir and rmdir) — skip level, continue upward + // ENOENT: dir removed by another process between pathExists and rmdir — skip level, continue upward + if (error.code === 'ENOTEMPTY' || error.code === 'ENOENT') { + current = path.dirname(current); + continue; + } + break; // fatal error (e.g. EACCES) — stop upward walk } current = path.dirname(current); } diff --git a/tools/cli/installers/lib/ide/codex.js b/tools/cli/installers/lib/ide/codex.js deleted file mode 100644 index abee979fd..000000000 --- a/tools/cli/installers/lib/ide/codex.js +++ /dev/null @@ -1,440 +0,0 @@ -const path = require('node:path'); -const os = require('node:os'); -const fs = require('fs-extra'); -const yaml = require('yaml'); -const { BaseIdeSetup } = require('./_base-ide'); -const { WorkflowCommandGenerator } = require('./shared/workflow-command-generator'); -const { AgentCommandGenerator } = require('./shared/agent-command-generator'); -const { TaskToolCommandGenerator } = require('./shared/task-tool-command-generator'); -const { getTasksFromBmad } = require('./shared/bmad-artifacts'); -const { toDashPath, customAgentDashName } = require('./shared/path-utils'); -const prompts = require('../../../lib/prompts'); - -/** - * Codex setup handler (CLI mode) - */ -class CodexSetup extends BaseIdeSetup { - constructor() { - super('codex', 'Codex', false); - } - - /** - * Setup Codex configuration - * @param {string} projectDir - Project directory - * @param {string} bmadDir - BMAD installation directory - * @param {Object} options - Setup options - */ - async setup(projectDir, bmadDir, options = {}) { - if (!options.silent) await prompts.log.info(`Setting up ${this.name}...`); - - // Always use CLI mode - const mode = 'cli'; - - const { artifacts, counts } = await this.collectClaudeArtifacts(projectDir, bmadDir, options); - - // Clean up old .codex/prompts locations (both global and project) - const oldGlobalDir = this.getOldCodexPromptDir(null, 'global'); - await this.clearOldBmadFiles(oldGlobalDir, options); - const oldProjectDir = this.getOldCodexPromptDir(projectDir, 'project'); - await this.clearOldBmadFiles(oldProjectDir, options); - - // Install to .agents/skills - const destDir = this.getCodexSkillsDir(projectDir); - await fs.ensureDir(destDir); - await this.clearOldBmadSkills(destDir, options); - - // Collect and write agent skills - const agentGen = new AgentCommandGenerator(this.bmadFolderName); - const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []); - const agentCount = await this.writeSkillArtifacts(destDir, agentArtifacts, 'agent-launcher'); - - // Collect and write task skills - const tasks = await getTasksFromBmad(bmadDir, options.selectedModules || []); - const taskArtifacts = []; - for (const task of tasks) { - const content = await this.readAndProcessWithProject( - task.path, - { - module: task.module, - name: task.name, - }, - projectDir, - ); - taskArtifacts.push({ - type: 'task', - name: task.name, - displayName: task.name, - module: task.module, - path: task.path, - sourcePath: task.path, - relativePath: path.join(task.module, 'tasks', `${task.name}.md`), - content, - }); - } - - const ttGen = new TaskToolCommandGenerator(this.bmadFolderName); - const taskSkillArtifacts = taskArtifacts.map((artifact) => ({ - ...artifact, - content: ttGen.generateCommandContent(artifact, artifact.type), - })); - const tasksWritten = await this.writeSkillArtifacts(destDir, taskSkillArtifacts, 'task'); - - // Collect and write workflow skills - const workflowGenerator = new WorkflowCommandGenerator(this.bmadFolderName); - const { artifacts: workflowArtifacts } = await workflowGenerator.collectWorkflowArtifacts(bmadDir); - const workflowCount = await this.writeSkillArtifacts(destDir, workflowArtifacts, 'workflow-command'); - - const written = agentCount + workflowCount + tasksWritten; - - if (!options.silent) { - await prompts.log.success( - `${this.name} configured: ${counts.agents} agents, ${counts.workflows} workflows, ${counts.tasks} tasks, ${written} skills → ${destDir}`, - ); - } - - return { - success: true, - mode, - artifacts, - counts, - destination: destDir, - written, - }; - } - - /** - * Detect Codex installation by checking for BMAD skills - */ - async detect(projectDir) { - const dir = this.getCodexSkillsDir(projectDir || process.cwd()); - - if (await fs.pathExists(dir)) { - try { - const entries = await fs.readdir(dir); - if (entries && entries.some((entry) => entry && typeof entry === 'string' && entry.startsWith('bmad'))) { - return true; - } - } catch { - // Ignore errors - } - } - - return false; - } - - /** - * Collect Claude-style artifacts for Codex export. - * Returns the normalized artifact list for further processing. - */ - async collectClaudeArtifacts(projectDir, bmadDir, options = {}) { - const selectedModules = options.selectedModules || []; - const artifacts = []; - - // Generate agent launchers - const agentGen = new AgentCommandGenerator(this.bmadFolderName); - const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, selectedModules); - - for (const artifact of agentArtifacts) { - artifacts.push({ - type: 'agent', - module: artifact.module, - sourcePath: artifact.sourcePath, - relativePath: artifact.relativePath, - content: artifact.content, - }); - } - - const tasks = await getTasksFromBmad(bmadDir, selectedModules); - for (const task of tasks) { - const content = await this.readAndProcessWithProject( - task.path, - { - module: task.module, - name: task.name, - }, - projectDir, - ); - - artifacts.push({ - type: 'task', - name: task.name, - displayName: task.name, - module: task.module, - path: task.path, - sourcePath: task.path, - relativePath: path.join(task.module, 'tasks', `${task.name}.md`), - content, - }); - } - - const workflowGenerator = new WorkflowCommandGenerator(this.bmadFolderName); - const { artifacts: workflowArtifacts, counts: workflowCounts } = await workflowGenerator.collectWorkflowArtifacts(bmadDir); - artifacts.push(...workflowArtifacts); - - return { - artifacts, - counts: { - agents: agentArtifacts.length, - tasks: tasks.length, - workflows: workflowCounts.commands, - workflowLaunchers: workflowCounts.launchers, - }, - }; - } - - getCodexSkillsDir(projectDir) { - if (!projectDir) { - throw new Error('projectDir is required for project-scoped skill installation'); - } - return path.join(projectDir, '.agents', 'skills'); - } - - /** - * Get the old .codex/prompts directory for cleanup purposes - */ - getOldCodexPromptDir(projectDir = null, location = 'global') { - if (location === 'project' && projectDir) { - return path.join(projectDir, '.codex', 'prompts'); - } - return path.join(os.homedir(), '.codex', 'prompts'); - } - - /** - * Write artifacts as Agent Skills (agentskills.io format). - * Each artifact becomes a directory containing SKILL.md. - * @param {string} destDir - Base skills directory - * @param {Array} artifacts - Artifacts to write - * @param {string} artifactType - Type filter (e.g., 'agent-launcher', 'workflow-command', 'task') - * @returns {number} Number of skills written - */ - async writeSkillArtifacts(destDir, artifacts, artifactType) { - let writtenCount = 0; - - for (const artifact of artifacts) { - // Filter by type if the artifact has a type field - if (artifact.type && artifact.type !== artifactType) { - continue; - } - - // Get the dash-format name (e.g., bmad-bmm-create-prd.md) and remove .md - const flatName = toDashPath(artifact.relativePath); - const skillName = flatName.replace(/\.md$/, ''); - - // Create skill directory - const skillDir = path.join(destDir, skillName); - await fs.ensureDir(skillDir); - - // Transform content: rewrite frontmatter for skills format - const skillContent = this.transformToSkillFormat(artifact.content, skillName); - - // Write SKILL.md with platform-native line endings - const platformContent = skillContent.replaceAll('\n', os.EOL); - await fs.writeFile(path.join(skillDir, 'SKILL.md'), platformContent, 'utf8'); - writtenCount++; - } - - return writtenCount; - } - - /** - * Transform artifact content from Codex prompt format to Agent Skills format. - * Removes disable-model-invocation, ensures name matches directory. - * @param {string} content - Original content with YAML frontmatter - * @param {string} skillName - Skill name (must match directory name) - * @returns {string} Transformed content - */ - transformToSkillFormat(content, skillName) { - // Normalize line endings so body matches rebuilt frontmatter (both LF) - content = content.replaceAll('\r\n', '\n').replaceAll('\r', '\n'); - - // Parse frontmatter - const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/); - if (!fmMatch) { - // No frontmatter -- wrap with minimal frontmatter - const fm = yaml.stringify({ name: skillName, description: skillName }).trimEnd(); - return `---\n${fm}\n---\n\n${content}`; - } - - const frontmatter = fmMatch[1]; - const body = fmMatch[2]; - - // Parse frontmatter with yaml library to handle all quoting variants - let description; - try { - const parsed = yaml.parse(frontmatter); - description = parsed?.description || `${skillName} skill`; - } catch { - description = `${skillName} skill`; - } - - // Build new frontmatter with only skills-spec fields, let yaml handle quoting - const newFrontmatter = yaml.stringify({ name: skillName, description }, { lineWidth: 0 }).trimEnd(); - return `---\n${newFrontmatter}\n---\n${body}`; - } - - /** - * Remove existing BMAD skill directories from the skills directory. - */ - async clearOldBmadSkills(destDir, options = {}) { - if (!(await fs.pathExists(destDir))) { - return; - } - - let entries; - try { - entries = await fs.readdir(destDir); - } catch (error) { - if (!options.silent) await prompts.log.warn(`Warning: Could not read directory ${destDir}: ${error.message}`); - return; - } - - if (!entries || !Array.isArray(entries)) { - return; - } - - for (const entry of entries) { - if (!entry || typeof entry !== 'string') { - continue; - } - if (!entry.startsWith('bmad')) { - continue; - } - - const entryPath = path.join(destDir, entry); - try { - await fs.remove(entryPath); - } catch (error) { - if (!options.silent) { - await prompts.log.message(` Skipping ${entry}: ${error.message}`); - } - } - } - } - - /** - * Clean old BMAD files from legacy .codex/prompts directories. - */ - async clearOldBmadFiles(destDir, options = {}) { - if (!(await fs.pathExists(destDir))) { - return; - } - - let entries; - try { - entries = await fs.readdir(destDir); - } catch (error) { - // Directory exists but can't be read - skip cleanup - if (!options.silent) await prompts.log.warn(`Warning: Could not read directory ${destDir}: ${error.message}`); - return; - } - - if (!entries || !Array.isArray(entries)) { - return; - } - - for (const entry of entries) { - // Skip non-strings or undefined entries - if (!entry || typeof entry !== 'string') { - continue; - } - if (!entry.startsWith('bmad')) { - continue; - } - - const entryPath = path.join(destDir, entry); - try { - await fs.remove(entryPath); - } catch (error) { - if (!options.silent) { - await prompts.log.message(` Skipping ${entry}: ${error.message}`); - } - } - } - } - - async readAndProcessWithProject(filePath, metadata, projectDir) { - const rawContent = await fs.readFile(filePath, 'utf8'); - const content = rawContent.replaceAll('\r\n', '\n').replaceAll('\r', '\n'); - return super.processContent(content, metadata, projectDir); - } - - /** - * Get instructions for project-specific installation - * @param {string} projectDir - Optional project directory - * @param {string} destDir - Optional destination directory - * @returns {string} Instructions text - */ - getProjectSpecificInstructions(projectDir = null, destDir = null) { - const lines = [ - 'Project-Specific Codex Configuration', - '', - `Skills installed to: ${destDir || '/.agents/skills'}`, - '', - 'Codex automatically discovers skills in .agents/skills/ at and above the current directory and in your home directory.', - 'No additional configuration is needed.', - ]; - - return lines.join('\n'); - } - - /** - * Cleanup Codex configuration - cleans both new .agents/skills and old .codex/prompts - */ - async cleanup(projectDir = null) { - // Clean old .codex/prompts locations - const oldGlobalDir = this.getOldCodexPromptDir(null, 'global'); - await this.clearOldBmadFiles(oldGlobalDir); - - if (projectDir) { - const oldProjectDir = this.getOldCodexPromptDir(projectDir, 'project'); - await this.clearOldBmadFiles(oldProjectDir); - - // Clean new .agents/skills location - const destDir = this.getCodexSkillsDir(projectDir); - await this.clearOldBmadSkills(destDir); - } - } - - /** - * Install a custom agent launcher for Codex as an Agent Skill - * @param {string} projectDir - Project directory - * @param {string} agentName - Agent name (e.g., "fred-commit-poet") - * @param {string} agentPath - Path to compiled agent (relative to project root) - * @param {Object} metadata - Agent metadata - * @returns {Object|null} Info about created skill - */ - async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) { - const destDir = this.getCodexSkillsDir(projectDir); - - // Skill name from the dash name (without .md) - const skillName = customAgentDashName(agentName).replace(/\.md$/, ''); - const skillDir = path.join(destDir, skillName); - await fs.ensureDir(skillDir); - - const description = metadata?.description || `${agentName} agent`; - const fm = yaml.stringify({ name: skillName, description }).trimEnd(); - const skillContent = - `---\n${fm}\n---\n` + - "\nYou must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.\n" + - '\n\n' + - `1. LOAD the FULL agent file from @${agentPath}\n` + - '2. READ its entire contents - this contains the complete agent persona, menu, and instructions\n' + - '3. FOLLOW every step in the section precisely\n' + - '4. DISPLAY the welcome/greeting as instructed\n' + - '5. PRESENT the numbered menu\n' + - '6. WAIT for user input before proceeding\n' + - '\n'; - - // Write with platform-native line endings - const platformContent = skillContent.replaceAll('\n', os.EOL); - const skillPath = path.join(skillDir, 'SKILL.md'); - await fs.writeFile(skillPath, platformContent, 'utf8'); - - return { - path: path.relative(projectDir, skillPath), - command: `$${skillName}`, - }; - } -} - -module.exports = { CodexSetup }; diff --git a/tools/cli/installers/lib/ide/github-copilot.js b/tools/cli/installers/lib/ide/github-copilot.js deleted file mode 100644 index 033e8d627..000000000 --- a/tools/cli/installers/lib/ide/github-copilot.js +++ /dev/null @@ -1,700 +0,0 @@ -const path = require('node:path'); -const { BaseIdeSetup } = require('./_base-ide'); -const prompts = require('../../../lib/prompts'); -const { AgentCommandGenerator } = require('./shared/agent-command-generator'); -const { BMAD_FOLDER_NAME, toDashPath } = require('./shared/path-utils'); -const fs = require('fs-extra'); -const csv = require('csv-parse/sync'); -const yaml = require('yaml'); - -/** - * GitHub Copilot setup handler - * Creates agents in .github/agents/, prompts in .github/prompts/, - * copilot-instructions.md, and configures VS Code settings - */ -class GitHubCopilotSetup extends BaseIdeSetup { - constructor() { - super('github-copilot', 'GitHub Copilot', false); - // Don't set configDir to '.github' — nearly every GitHub repo has that directory, - // which would cause the base detect() to false-positive. Use detectionPaths instead. - this.configDir = null; - this.githubDir = '.github'; - this.agentsDir = 'agents'; - this.promptsDir = 'prompts'; - this.detectionPaths = ['.github/copilot-instructions.md', '.github/agents']; - } - - /** - * Setup GitHub Copilot configuration - * @param {string} projectDir - Project directory - * @param {string} bmadDir - BMAD installation directory - * @param {Object} options - Setup options - */ - async setup(projectDir, bmadDir, options = {}) { - if (!options.silent) await prompts.log.info(`Setting up ${this.name}...`); - - // Create .github/agents and .github/prompts directories - const githubDir = path.join(projectDir, this.githubDir); - const agentsDir = path.join(githubDir, this.agentsDir); - const promptsDir = path.join(githubDir, this.promptsDir); - await this.ensureDir(agentsDir); - await this.ensureDir(promptsDir); - - // Preserve any customised tool permissions from existing files before cleanup - this.existingToolPermissions = await this.collectExistingToolPermissions(projectDir); - - // Clean up any existing BMAD files before reinstalling - await this.cleanup(projectDir); - - // Load agent manifest for enriched descriptions - const agentManifest = await this.loadAgentManifest(bmadDir); - - // Generate agent launchers - const agentGen = new AgentCommandGenerator(this.bmadFolderName); - const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []); - - // Create agent .agent.md files - let agentCount = 0; - for (const artifact of agentArtifacts) { - const agentMeta = agentManifest.get(artifact.name); - - // Compute fileName first so we can look up any existing tool permissions - const dashName = toDashPath(artifact.relativePath); - const fileName = dashName.replace(/\.md$/, '.agent.md'); - const toolsStr = this.getToolsForFile(fileName); - const agentContent = this.createAgentContent(artifact, agentMeta, toolsStr); - const targetPath = path.join(agentsDir, fileName); - await this.writeFile(targetPath, agentContent); - agentCount++; - } - - // Generate prompt files from bmad-help.csv - const promptCount = await this.generatePromptFiles(projectDir, bmadDir, agentArtifacts, agentManifest); - - // Generate copilot-instructions.md - await this.generateCopilotInstructions(projectDir, bmadDir, agentManifest, options); - - if (!options.silent) await prompts.log.success(`${this.name} configured: ${agentCount} agents, ${promptCount} prompts → .github/`); - - return { - success: true, - results: { - agents: agentCount, - workflows: promptCount, - tasks: 0, - tools: 0, - }, - }; - } - - /** - * Load agent manifest CSV into a Map keyed by agent name - * @param {string} bmadDir - BMAD installation directory - * @returns {Map} Agent metadata keyed by name - */ - async loadAgentManifest(bmadDir) { - const manifestPath = path.join(bmadDir, '_config', 'agent-manifest.csv'); - const agents = new Map(); - - if (!(await fs.pathExists(manifestPath))) { - return agents; - } - - try { - const csvContent = await fs.readFile(manifestPath, 'utf8'); - const records = csv.parse(csvContent, { - columns: true, - skip_empty_lines: true, - }); - - for (const record of records) { - agents.set(record.name, record); - } - } catch { - // Gracefully degrade if manifest is unreadable/malformed - } - - return agents; - } - - /** - * Load bmad-help.csv to drive prompt generation - * @param {string} bmadDir - BMAD installation directory - * @returns {Array|null} Parsed CSV rows - */ - async loadBmadHelp(bmadDir) { - const helpPath = path.join(bmadDir, '_config', 'bmad-help.csv'); - - if (!(await fs.pathExists(helpPath))) { - return null; - } - - try { - const csvContent = await fs.readFile(helpPath, 'utf8'); - return csv.parse(csvContent, { - columns: true, - skip_empty_lines: true, - }); - } catch { - // Gracefully degrade if help CSV is unreadable/malformed - return null; - } - } - - /** - * Create agent .agent.md content with enriched description - * @param {Object} artifact - Agent artifact from AgentCommandGenerator - * @param {Object|undefined} manifestEntry - Agent manifest entry with metadata - * @returns {string} Agent file content - */ - createAgentContent(artifact, manifestEntry, toolsStr) { - // Build enriched description from manifest metadata - let description; - if (manifestEntry) { - const persona = manifestEntry.displayName || artifact.name; - const title = manifestEntry.title || this.formatTitle(artifact.name); - const capabilities = manifestEntry.capabilities || 'agent capabilities'; - description = `${persona} — ${title}: ${capabilities}`; - } else { - description = `Activates the ${this.formatTitle(artifact.name)} agent persona.`; - } - - // Build the agent file path for the activation block - const agentPath = artifact.agentPath || artifact.relativePath; - const agentFilePath = `{project-root}/${this.bmadFolderName}/${agentPath}`; - - return `--- -description: '${description.replaceAll("'", "''")}' -tools: ${toolsStr} -disable-model-invocation: true ---- - -You must fully embody this agent's persona and follow all activation instructions exactly as specified. - - -1. LOAD the FULL agent file from ${agentFilePath} -2. READ its entire contents - this contains the complete agent persona, menu, and instructions -3. FOLLOW every step in the section precisely -4. DISPLAY the welcome/greeting as instructed -5. PRESENT the numbered menu -6. WAIT for user input before proceeding - -`; - } - - /** - * Generate .prompt.md files for workflows, tasks, tech-writer commands, and agent activators - * @param {string} projectDir - Project directory - * @param {string} bmadDir - BMAD installation directory - * @param {Array} agentArtifacts - Agent artifacts for activator generation - * @param {Map} agentManifest - Agent manifest data - * @returns {number} Count of prompts generated - */ - async generatePromptFiles(projectDir, bmadDir, agentArtifacts, agentManifest) { - const promptsDir = path.join(projectDir, this.githubDir, this.promptsDir); - let promptCount = 0; - - // Load bmad-help.csv to drive workflow/task prompt generation - const helpEntries = await this.loadBmadHelp(bmadDir); - - if (helpEntries) { - for (const entry of helpEntries) { - const command = entry.command; - if (!command) continue; // Skip entries without a command (tech-writer commands have no command column) - - const workflowFile = entry['workflow-file']; - if (!workflowFile) continue; // Skip entries with no workflow file path - const promptFileName = `${command}.prompt.md`; - const toolsStr = this.getToolsForFile(promptFileName); - const promptContent = this.createWorkflowPromptContent(entry, workflowFile, toolsStr); - const promptPath = path.join(promptsDir, promptFileName); - await this.writeFile(promptPath, promptContent); - promptCount++; - } - - // Generate tech-writer command prompts (entries with no command column) - for (const entry of helpEntries) { - if (entry.command) continue; // Already handled above - const techWriterPrompt = this.createTechWriterPromptContent(entry); - if (techWriterPrompt) { - const promptFileName = `${techWriterPrompt.fileName}.prompt.md`; - const promptPath = path.join(promptsDir, promptFileName); - await this.writeFile(promptPath, techWriterPrompt.content); - promptCount++; - } - } - } - - // Generate agent activator prompts (Pattern D) - for (const artifact of agentArtifacts) { - const agentMeta = agentManifest.get(artifact.name); - const fileName = `bmad-${artifact.name}.prompt.md`; - const toolsStr = this.getToolsForFile(fileName); - const promptContent = this.createAgentActivatorPromptContent(artifact, agentMeta, toolsStr); - const promptPath = path.join(promptsDir, fileName); - await this.writeFile(promptPath, promptContent); - promptCount++; - } - - return promptCount; - } - - /** - * Create prompt content for a workflow/task entry from bmad-help.csv - * Determines the pattern (A, B, or A for .xml tasks) based on file extension - * @param {Object} entry - bmad-help.csv row - * @param {string} workflowFile - Workflow file path - * @returns {string} Prompt file content - */ - createWorkflowPromptContent(entry, workflowFile, toolsStr) { - const description = this.escapeYamlSingleQuote(this.createPromptDescription(entry.name)); - // bmm/config.yaml is safe to hardcode here: these prompts are only generated when - // bmad-help.csv exists (bmm module data), so bmm is guaranteed to be installed. - const configLine = `1. Load {project-root}/${this.bmadFolderName}/bmm/config.yaml and store ALL fields as session variables`; - - let body; - if (workflowFile.endsWith('.yaml')) { - // Pattern B: YAML-based workflows — use workflow engine - body = `${configLine} -2. Load the workflow engine at {project-root}/${this.bmadFolderName}/core/tasks/workflow.xml -3. Load and execute the workflow configuration at {project-root}/${workflowFile} using the engine from step 2`; - } else if (workflowFile.endsWith('.xml')) { - // Pattern A variant: XML tasks — load and execute directly - body = `${configLine} -2. Load and execute the task at {project-root}/${workflowFile}`; - } else { - // Pattern A: MD workflows — load and follow directly - body = `${configLine} -2. Load and follow the workflow at {project-root}/${workflowFile}`; - } - - return `--- -description: '${description}' -agent: 'agent' -tools: ${toolsStr} ---- - -${body} -`; - } - - /** - * Create a short 2-5 word description for a prompt from the entry name - * @param {string} name - Entry name from bmad-help.csv - * @returns {string} Short description - */ - createPromptDescription(name) { - const descriptionMap = { - 'Brainstorm Project': 'Brainstorm ideas', - 'Market Research': 'Market research', - 'Domain Research': 'Domain research', - 'Technical Research': 'Technical research', - 'Create Brief': 'Create product brief', - 'Create PRD': 'Create PRD', - 'Validate PRD': 'Validate PRD', - 'Edit PRD': 'Edit PRD', - 'Create UX': 'Create UX design', - 'Create Architecture': 'Create architecture', - 'Create Epics and Stories': 'Create epics and stories', - 'Check Implementation Readiness': 'Check implementation readiness', - 'Sprint Planning': 'Sprint planning', - 'Sprint Status': 'Sprint status', - 'Create Story': 'Create story', - 'Validate Story': 'Validate story', - 'Dev Story': 'Dev story', - 'QA Automation Test': 'QA automation', - 'Code Review': 'Code review', - Retrospective: 'Retrospective', - 'Document Project': 'Document project', - 'Generate Project Context': 'Generate project context', - 'Quick Spec': 'Quick spec', - 'Quick Dev': 'Quick dev', - 'Correct Course': 'Correct course', - Brainstorming: 'Brainstorm ideas', - 'Party Mode': 'Party mode', - 'bmad-help': 'BMAD help', - 'Index Docs': 'Index documents', - 'Shard Document': 'Shard document', - 'Editorial Review - Prose': 'Editorial review prose', - 'Editorial Review - Structure': 'Editorial review structure', - 'Adversarial Review (General)': 'Adversarial review', - }; - - return descriptionMap[name] || name; - } - - /** - * Create prompt content for tech-writer agent-only commands (Pattern C) - * @param {Object} entry - bmad-help.csv row - * @returns {Object|null} { fileName, content } or null if not a tech-writer command - */ - createTechWriterPromptContent(entry) { - if (entry['agent-name'] !== 'tech-writer') return null; - - const techWriterCommands = { - 'Write Document': { code: 'WD', file: 'bmad-bmm-write-document', description: 'Write document' }, - 'Update Standards': { code: 'US', file: 'bmad-bmm-update-standards', description: 'Update standards' }, - 'Mermaid Generate': { code: 'MG', file: 'bmad-bmm-mermaid-generate', description: 'Mermaid generate' }, - 'Validate Document': { code: 'VD', file: 'bmad-bmm-validate-document', description: 'Validate document' }, - 'Explain Concept': { code: 'EC', file: 'bmad-bmm-explain-concept', description: 'Explain concept' }, - }; - - const cmd = techWriterCommands[entry.name]; - if (!cmd) return null; - - const safeDescription = this.escapeYamlSingleQuote(cmd.description); - const toolsStr = this.getToolsForFile(`${cmd.file}.prompt.md`); - - const content = `--- -description: '${safeDescription}' -agent: 'agent' -tools: ${toolsStr} ---- - -1. Load {project-root}/${this.bmadFolderName}/bmm/config.yaml and store ALL fields as session variables -2. Load the full agent file from {project-root}/${this.bmadFolderName}/bmm/agents/tech-writer/tech-writer.md and activate the Paige (Technical Writer) persona -3. Execute the ${entry.name} menu command (${cmd.code}) -`; - - return { fileName: cmd.file, content }; - } - - /** - * Create agent activator prompt content (Pattern D) - * @param {Object} artifact - Agent artifact - * @param {Object|undefined} manifestEntry - Agent manifest entry - * @returns {string} Prompt file content - */ - createAgentActivatorPromptContent(artifact, manifestEntry, toolsStr) { - let description; - if (manifestEntry) { - description = manifestEntry.title || this.formatTitle(artifact.name); - } else { - description = this.formatTitle(artifact.name); - } - - const safeDescription = this.escapeYamlSingleQuote(description); - const agentPath = artifact.agentPath || artifact.relativePath; - const agentFilePath = `{project-root}/${this.bmadFolderName}/${agentPath}`; - - // bmm/config.yaml is safe to hardcode: agent activators are only generated from - // bmm agent artifacts, so bmm is guaranteed to be installed. - return `--- -description: '${safeDescription}' -agent: 'agent' -tools: ${toolsStr} ---- - -1. Load {project-root}/${this.bmadFolderName}/bmm/config.yaml and store ALL fields as session variables -2. Load the full agent file from ${agentFilePath} -3. Follow ALL activation instructions in the agent file -4. Display the welcome/greeting as instructed -5. Present the numbered menu -6. Wait for user input before proceeding -`; - } - - /** - * Generate copilot-instructions.md from module config - * @param {string} projectDir - Project directory - * @param {string} bmadDir - BMAD installation directory - * @param {Map} agentManifest - Agent manifest data - */ - async generateCopilotInstructions(projectDir, bmadDir, agentManifest, options = {}) { - const configVars = await this.loadModuleConfig(bmadDir); - - // Build the agents table from the manifest - let agentsTable = '| Agent | Persona | Title | Capabilities |\n|---|---|---|---|\n'; - const agentOrder = [ - 'bmad-master', - 'analyst', - 'architect', - 'dev', - 'pm', - 'qa', - 'quick-flow-solo-dev', - 'sm', - 'tech-writer', - 'ux-designer', - ]; - - for (const agentName of agentOrder) { - const meta = agentManifest.get(agentName); - if (meta) { - const capabilities = meta.capabilities || 'agent capabilities'; - const cleanTitle = (meta.title || '').replaceAll('""', '"'); - agentsTable += `| ${agentName} | ${meta.displayName} | ${cleanTitle} | ${capabilities} |\n`; - } - } - - const bmad = this.bmadFolderName; - const bmadSection = `# BMAD Method — Project Instructions - -## Project Configuration - -- **Project**: ${configVars.project_name || '{{project_name}}'} -- **User**: ${configVars.user_name || '{{user_name}}'} -- **Communication Language**: ${configVars.communication_language || '{{communication_language}}'} -- **Document Output Language**: ${configVars.document_output_language || '{{document_output_language}}'} -- **User Skill Level**: ${configVars.user_skill_level || '{{user_skill_level}}'} -- **Output Folder**: ${configVars.output_folder || '{{output_folder}}'} -- **Planning Artifacts**: ${configVars.planning_artifacts || '{{planning_artifacts}}'} -- **Implementation Artifacts**: ${configVars.implementation_artifacts || '{{implementation_artifacts}}'} -- **Project Knowledge**: ${configVars.project_knowledge || '{{project_knowledge}}'} - -## BMAD Runtime Structure - -- **Agent definitions**: \`${bmad}/bmm/agents/\` (BMM module) and \`${bmad}/core/agents/\` (core) -- **Workflow definitions**: \`${bmad}/bmm/workflows/\` (organized by phase) -- **Core tasks**: \`${bmad}/core/tasks/\` (help, editorial review, indexing, sharding, adversarial review) -- **Core workflows**: \`${bmad}/core/workflows/\` (brainstorming, party-mode, advanced-elicitation) -- **Workflow engine**: \`${bmad}/core/tasks/workflow.xml\` (executes YAML-based workflows) -- **Module configuration**: \`${bmad}/bmm/config.yaml\` -- **Core configuration**: \`${bmad}/core/config.yaml\` -- **Agent manifest**: \`${bmad}/_config/agent-manifest.csv\` -- **Workflow manifest**: \`${bmad}/_config/workflow-manifest.csv\` -- **Help manifest**: \`${bmad}/_config/bmad-help.csv\` -- **Agent memory**: \`${bmad}/_memory/\` - -## Key Conventions - -- Always load \`${bmad}/bmm/config.yaml\` before any agent activation or workflow execution -- Store all config fields as session variables: \`{user_name}\`, \`{communication_language}\`, \`{output_folder}\`, \`{planning_artifacts}\`, \`{implementation_artifacts}\`, \`{project_knowledge}\` -- MD-based workflows execute directly — load and follow the \`.md\` file -- YAML-based workflows require the workflow engine — load \`workflow.xml\` first, then pass the \`.yaml\` config -- Follow step-based workflow execution: load steps JIT, never multiple at once -- Save outputs after EACH step when using the workflow engine -- The \`{project-root}\` variable resolves to the workspace root at runtime - -## Available Agents - -${agentsTable} -## Slash Commands - -Type \`/bmad-\` in Copilot Chat to see all available BMAD workflows and agent activators. Agents are also available in the agents dropdown.`; - - const instructionsPath = path.join(projectDir, this.githubDir, 'copilot-instructions.md'); - const markerStart = ''; - const markerEnd = ''; - const markedContent = `${markerStart}\n${bmadSection}\n${markerEnd}`; - - if (await fs.pathExists(instructionsPath)) { - const existing = await fs.readFile(instructionsPath, 'utf8'); - const startIdx = existing.indexOf(markerStart); - const endIdx = existing.indexOf(markerEnd); - - if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) { - // Replace only the BMAD section between markers - const before = existing.slice(0, startIdx); - const after = existing.slice(endIdx + markerEnd.length); - const merged = `${before}${markedContent}${after}`; - await this.writeFile(instructionsPath, merged); - } else { - // Existing file without markers — back it up before overwriting - const backupPath = `${instructionsPath}.bak`; - await fs.copy(instructionsPath, backupPath); - if (!options.silent) await prompts.log.warn(` Backed up copilot-instructions.md → .bak`); - await this.writeFile(instructionsPath, `${markedContent}\n`); - } - } else { - // No existing file — create fresh with markers - await this.writeFile(instructionsPath, `${markedContent}\n`); - } - } - - /** - * Load module config.yaml for template variables - * @param {string} bmadDir - BMAD installation directory - * @returns {Object} Config variables - */ - async loadModuleConfig(bmadDir) { - const bmmConfigPath = path.join(bmadDir, 'bmm', 'config.yaml'); - const coreConfigPath = path.join(bmadDir, 'core', 'config.yaml'); - - for (const configPath of [bmmConfigPath, coreConfigPath]) { - if (await fs.pathExists(configPath)) { - try { - const content = await fs.readFile(configPath, 'utf8'); - return yaml.parse(content) || {}; - } catch { - // Fall through to next config - } - } - } - - return {}; - } - - /** - * Escape a string for use inside YAML single-quoted values. - * In YAML, the only escape inside single quotes is '' for a literal '. - * @param {string} value - Raw string - * @returns {string} Escaped string safe for YAML single-quoted context - */ - escapeYamlSingleQuote(value) { - return (value || '').replaceAll("'", "''"); - } - - /** - * Scan existing agent and prompt files for customised tool permissions before cleanup. - * Returns a Map so permissions can be preserved across reinstalls. - * @param {string} projectDir - Project directory - * @returns {Map} Existing tool permissions keyed by filename - */ - async collectExistingToolPermissions(projectDir) { - const permissions = new Map(); - const dirs = [ - [path.join(projectDir, this.githubDir, this.agentsDir), /^bmad.*\.agent\.md$/], - [path.join(projectDir, this.githubDir, this.promptsDir), /^bmad-.*\.prompt\.md$/], - ]; - - for (const [dir, pattern] of dirs) { - if (!(await fs.pathExists(dir))) continue; - const files = await fs.readdir(dir); - - for (const file of files) { - if (!pattern.test(file)) continue; - - try { - const content = await fs.readFile(path.join(dir, file), 'utf8'); - const fmMatch = content.match(/^---\n([\s\S]*?)\n---/); - if (!fmMatch) continue; - - const frontmatter = yaml.parse(fmMatch[1]); - if (frontmatter && Array.isArray(frontmatter.tools)) { - permissions.set(file, frontmatter.tools); - } - } catch { - // Skip unreadable files - } - } - } - - return permissions; - } - - /** - * Get the tools array string for a file, preserving any existing customisation. - * Falls back to the default tools if no prior customisation exists. - * @param {string} fileName - Target filename (e.g. 'bmad-agent-bmm-pm.agent.md') - * @returns {string} YAML inline array string - */ - getToolsForFile(fileName) { - const defaultTools = ['read', 'edit', 'search', 'execute']; - const tools = (this.existingToolPermissions && this.existingToolPermissions.get(fileName)) || defaultTools; - return '[' + tools.map((t) => `'${t}'`).join(', ') + ']'; - } - - /** - * Format name as title - */ - formatTitle(name) { - return name - .split('-') - .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) - .join(' '); - } - - /** - * Cleanup GitHub Copilot configuration - surgically remove only BMAD files - */ - async cleanup(projectDir, options = {}) { - // Clean up agents directory - const agentsDir = path.join(projectDir, this.githubDir, this.agentsDir); - if (await fs.pathExists(agentsDir)) { - const files = await fs.readdir(agentsDir); - let removed = 0; - - for (const file of files) { - if (file.startsWith('bmad') && (file.endsWith('.agent.md') || file.endsWith('.md'))) { - await fs.remove(path.join(agentsDir, file)); - removed++; - } - } - - if (removed > 0 && !options.silent) { - await prompts.log.message(` Cleaned up ${removed} existing BMAD agents`); - } - } - - // Clean up prompts directory - const promptsDir = path.join(projectDir, this.githubDir, this.promptsDir); - if (await fs.pathExists(promptsDir)) { - const files = await fs.readdir(promptsDir); - let removed = 0; - - for (const file of files) { - if (file.startsWith('bmad-') && file.endsWith('.prompt.md')) { - await fs.remove(path.join(promptsDir, file)); - removed++; - } - } - - if (removed > 0 && !options.silent) { - await prompts.log.message(` Cleaned up ${removed} existing BMAD prompts`); - } - } - - // During uninstall, also strip BMAD markers from copilot-instructions.md. - // During reinstall (default), this is skipped because generateCopilotInstructions() - // handles marker-based replacement in a single read-modify-write pass, - // which correctly preserves user content outside the markers. - if (options.isUninstall) { - await this.cleanupCopilotInstructions(projectDir, options); - } - } - - /** - * Strip BMAD marker section from copilot-instructions.md - * If file becomes empty after stripping, delete it. - * If a .bak backup exists and the main file was deleted, restore the backup. - * @param {string} projectDir - Project directory - * @param {Object} [options] - Options (e.g. { silent: true }) - */ - async cleanupCopilotInstructions(projectDir, options = {}) { - const instructionsPath = path.join(projectDir, this.githubDir, 'copilot-instructions.md'); - const backupPath = `${instructionsPath}.bak`; - - if (!(await fs.pathExists(instructionsPath))) { - return; - } - - const content = await fs.readFile(instructionsPath, 'utf8'); - const markerStart = ''; - const markerEnd = ''; - const startIdx = content.indexOf(markerStart); - const endIdx = content.indexOf(markerEnd); - - if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) { - return; // No valid markers found - } - - // Strip the marker section (including markers) - const before = content.slice(0, startIdx); - const after = content.slice(endIdx + markerEnd.length); - const cleaned = before + after; - - if (cleaned.trim().length === 0) { - // File is empty after stripping — delete it - await fs.remove(instructionsPath); - - // If backup exists, restore it - if (await fs.pathExists(backupPath)) { - await fs.rename(backupPath, instructionsPath); - if (!options.silent) { - await prompts.log.message(' Restored copilot-instructions.md from backup'); - } - } - } else { - // Write cleaned content back (preserve original whitespace) - await fs.writeFile(instructionsPath, cleaned, 'utf8'); - - // If backup exists, it's stale now — remove it - if (await fs.pathExists(backupPath)) { - await fs.remove(backupPath); - } - } - } -} - -module.exports = { GitHubCopilotSetup }; diff --git a/tools/cli/installers/lib/ide/kilo.js b/tools/cli/installers/lib/ide/kilo.js deleted file mode 100644 index 2e5734391..000000000 --- a/tools/cli/installers/lib/ide/kilo.js +++ /dev/null @@ -1,269 +0,0 @@ -const path = require('node:path'); -const { BaseIdeSetup } = require('./_base-ide'); -const yaml = require('yaml'); -const prompts = require('../../../lib/prompts'); -const { AgentCommandGenerator } = require('./shared/agent-command-generator'); -const { WorkflowCommandGenerator } = require('./shared/workflow-command-generator'); -const { TaskToolCommandGenerator } = require('./shared/task-tool-command-generator'); - -/** - * KiloCode IDE setup handler - * Creates custom modes in .kilocodemodes file (similar to Roo) - */ -class KiloSetup extends BaseIdeSetup { - constructor() { - super('kilo', 'Kilo Code'); - this.configFile = '.kilocodemodes'; - } - - /** - * Setup KiloCode IDE configuration - * @param {string} projectDir - Project directory - * @param {string} bmadDir - BMAD installation directory - * @param {Object} options - Setup options - */ - async setup(projectDir, bmadDir, options = {}) { - if (!options.silent) await prompts.log.info(`Setting up ${this.name}...`); - - // Clean up any old BMAD installation first - await this.cleanup(projectDir, options); - - // Load existing config (may contain non-BMAD modes and other settings) - const kiloModesPath = path.join(projectDir, this.configFile); - let config = {}; - - if (await this.pathExists(kiloModesPath)) { - const existingContent = await this.readFile(kiloModesPath); - try { - config = yaml.parse(existingContent) || {}; - } catch { - // If parsing fails, start fresh but warn user - await prompts.log.warn('Warning: Could not parse existing .kilocodemodes, starting fresh'); - config = {}; - } - } - - // Ensure customModes array exists - if (!Array.isArray(config.customModes)) { - config.customModes = []; - } - - // Generate agent launchers - const agentGen = new AgentCommandGenerator(this.bmadFolderName); - const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []); - - // Create mode objects and add to config - let addedCount = 0; - - for (const artifact of agentArtifacts) { - const modeObject = await this.createModeObject(artifact, projectDir); - config.customModes.push(modeObject); - addedCount++; - } - - // Write .kilocodemodes file with proper YAML structure - const finalContent = yaml.stringify(config, { lineWidth: 0 }); - await this.writeFile(kiloModesPath, finalContent); - - // Generate workflow commands - const workflowGenerator = new WorkflowCommandGenerator(this.bmadFolderName); - const { artifacts: workflowArtifacts } = await workflowGenerator.collectWorkflowArtifacts(bmadDir); - - // Write to .kilocode/workflows/ directory - const workflowsDir = path.join(projectDir, '.kilocode', 'workflows'); - await this.ensureDir(workflowsDir); - - // Clear old BMAD workflows before writing new ones - await this.clearBmadWorkflows(workflowsDir); - - // Write workflow files - const workflowCount = await workflowGenerator.writeDashArtifacts(workflowsDir, workflowArtifacts); - - // Generate task and tool commands - const taskToolGen = new TaskToolCommandGenerator(this.bmadFolderName); - const { artifacts: taskToolArtifacts, counts: taskToolCounts } = await taskToolGen.collectTaskToolArtifacts(bmadDir); - - // Write task/tool files to workflows directory (same location as workflows) - await taskToolGen.writeDashArtifacts(workflowsDir, taskToolArtifacts); - const taskCount = taskToolCounts.tasks || 0; - const toolCount = taskToolCounts.tools || 0; - - if (!options.silent) { - await prompts.log.success( - `${this.name} configured: ${addedCount} modes, ${workflowCount} workflows, ${taskCount} tasks, ${toolCount} tools → ${this.configFile}`, - ); - } - - return { - success: true, - modes: addedCount, - workflows: workflowCount, - tasks: taskCount, - tools: toolCount, - }; - } - - /** - * Create a mode object for an agent - * @param {Object} artifact - Agent artifact - * @param {string} projectDir - Project directory - * @returns {Object} Mode object for YAML serialization - */ - async createModeObject(artifact, projectDir) { - // Extract metadata from launcher content - const titleMatch = artifact.content.match(/title="([^"]+)"/); - const title = titleMatch ? titleMatch[1] : this.formatTitle(artifact.name); - - const iconMatch = artifact.content.match(/icon="([^"]+)"/); - const icon = iconMatch ? iconMatch[1] : '🤖'; - - const whenToUseMatch = artifact.content.match(/whenToUse="([^"]+)"/); - const whenToUse = whenToUseMatch ? whenToUseMatch[1] : `Use for ${title} tasks`; - - // Get the activation header from central template (trim to avoid YAML formatting issues) - const activationHeader = (await this.getAgentCommandHeader()).trim(); - - const roleDefinitionMatch = artifact.content.match(/roleDefinition="([^"]+)"/); - const roleDefinition = roleDefinitionMatch - ? roleDefinitionMatch[1] - : `You are a ${title} specializing in ${title.toLowerCase()} tasks.`; - - // Get relative path - const relativePath = path.relative(projectDir, artifact.sourcePath).replaceAll('\\', '/'); - - // Build mode object (KiloCode uses same schema as Roo) - return { - slug: `bmad-${artifact.module}-${artifact.name}`, - name: `${icon} ${title}`, - roleDefinition: roleDefinition, - whenToUse: whenToUse, - customInstructions: `${activationHeader} Read the full YAML from ${relativePath} start activation to alter your state of being follow startup section instructions stay in this being until told to exit this mode\n`, - groups: ['read', 'edit', 'browser', 'command', 'mcp'], - }; - } - - /** - * Format name as title - */ - formatTitle(name) { - return name - .split('-') - .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) - .join(' '); - } - - /** - * Clear old BMAD workflow files from workflows directory - * @param {string} workflowsDir - Workflows directory path - */ - async clearBmadWorkflows(workflowsDir) { - const fs = require('fs-extra'); - if (!(await fs.pathExists(workflowsDir))) return; - - const entries = await fs.readdir(workflowsDir); - for (const entry of entries) { - if (entry.startsWith('bmad-') && entry.endsWith('.md')) { - await fs.remove(path.join(workflowsDir, entry)); - } - } - } - - /** - * Cleanup KiloCode configuration - */ - async cleanup(projectDir, options = {}) { - const fs = require('fs-extra'); - const kiloModesPath = path.join(projectDir, this.configFile); - - if (await fs.pathExists(kiloModesPath)) { - const content = await fs.readFile(kiloModesPath, 'utf8'); - - try { - const config = yaml.parse(content) || {}; - - if (Array.isArray(config.customModes)) { - const originalCount = config.customModes.length; - // Remove BMAD modes only (keep non-BMAD modes) - config.customModes = config.customModes.filter((mode) => !mode.slug || !mode.slug.startsWith('bmad-')); - const removedCount = originalCount - config.customModes.length; - - if (removedCount > 0) { - await fs.writeFile(kiloModesPath, yaml.stringify(config, { lineWidth: 0 })); - if (!options.silent) await prompts.log.message(`Removed ${removedCount} BMAD modes from .kilocodemodes`); - } - } - } catch { - // If parsing fails, leave file as-is - if (!options.silent) await prompts.log.warn('Warning: Could not parse .kilocodemodes for cleanup'); - } - } - - // Clean up workflow files - const workflowsDir = path.join(projectDir, '.kilocode', 'workflows'); - await this.clearBmadWorkflows(workflowsDir); - } - - /** - * Install a custom agent launcher for Kilo - * @param {string} projectDir - Project directory - * @param {string} agentName - Agent name (e.g., "fred-commit-poet") - * @param {string} agentPath - Path to compiled agent (relative to project root) - * @param {Object} metadata - Agent metadata - * @returns {Object} Installation result - */ - async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) { - const kilocodemodesPath = path.join(projectDir, this.configFile); - let config = {}; - - // Read existing .kilocodemodes file - if (await this.pathExists(kilocodemodesPath)) { - const existingContent = await this.readFile(kilocodemodesPath); - try { - config = yaml.parse(existingContent) || {}; - } catch { - config = {}; - } - } - - // Ensure customModes array exists - if (!Array.isArray(config.customModes)) { - config.customModes = []; - } - - // Create custom agent mode object - const slug = `bmad-custom-${agentName.toLowerCase()}`; - - // Check if mode already exists - if (config.customModes.some((mode) => mode.slug === slug)) { - return { - ide: 'kilo', - path: this.configFile, - command: agentName, - type: 'custom-agent-launcher', - alreadyExists: true, - }; - } - - // Add custom mode object - config.customModes.push({ - slug: slug, - name: `BMAD Custom: ${agentName}`, - description: `Custom BMAD agent: ${agentName}\n\n**⚠️ IMPORTANT**: Run @${agentPath} first to load the complete agent!\n\nThis is a launcher for the custom BMAD agent "${agentName}". The agent will follow the persona and instructions from the main agent file.\n`, - prompt: `@${agentPath}\n`, - always: false, - permissions: 'all', - }); - - // Write .kilocodemodes file with proper YAML structure - await this.writeFile(kilocodemodesPath, yaml.stringify(config, { lineWidth: 0 })); - - return { - ide: 'kilo', - path: this.configFile, - command: slug, - type: 'custom-agent-launcher', - }; - } -} - -module.exports = { KiloSetup }; diff --git a/tools/cli/installers/lib/ide/manager.js b/tools/cli/installers/lib/ide/manager.js index 9b8df1597..d0dee4ae0 100644 --- a/tools/cli/installers/lib/ide/manager.js +++ b/tools/cli/installers/lib/ide/manager.js @@ -1,5 +1,3 @@ -const fs = require('fs-extra'); -const path = require('node:path'); const { BMAD_FOLDER_NAME } = require('./shared/path-utils'); const prompts = require('../../../lib/prompts'); @@ -8,8 +6,7 @@ const prompts = require('../../../lib/prompts'); * Dynamically discovers and loads IDE handlers * * Loading strategy: - * 1. Custom installer files (codex.js, github-copilot.js, kilo.js, rovodev.js) - for platforms with unique installation logic - * 2. Config-driven handlers (from platform-codes.yaml) - for standard IDE installation patterns + * All platforms are config-driven from platform-codes.yaml. */ class IdeManager { constructor() { @@ -43,49 +40,12 @@ class IdeManager { } /** - * Dynamically load all IDE handlers - * 1. Load custom installer files first (codex.js, github-copilot.js, kilo.js, rovodev.js) - * 2. Load config-driven handlers from platform-codes.yaml + * Dynamically load all IDE handlers from platform-codes.yaml */ async loadHandlers() { - // Load custom installer files - await this.loadCustomInstallerFiles(); - - // Load config-driven handlers from platform-codes.yaml await this.loadConfigDrivenHandlers(); } - /** - * Load custom installer files (unique installation logic) - * These files have special installation patterns that don't fit the config-driven model - */ - async loadCustomInstallerFiles() { - const ideDir = __dirname; - const customFiles = ['codex.js', 'github-copilot.js', 'kilo.js', 'rovodev.js']; - - for (const file of customFiles) { - const filePath = path.join(ideDir, file); - if (!fs.existsSync(filePath)) continue; - - try { - const HandlerModule = require(filePath); - const HandlerClass = HandlerModule.default || Object.values(HandlerModule)[0]; - - if (HandlerClass) { - const instance = new HandlerClass(); - if (instance.name && typeof instance.name === 'string') { - if (typeof instance.setBmadFolderName === 'function') { - instance.setBmadFolderName(this.bmadFolderName); - } - this.handlers.set(instance.name, instance); - } - } - } catch (error) { - await prompts.log.warn(`Warning: Could not load ${file}: ${error.message}`); - } - } - } - /** * Load config-driven handlers from platform-codes.yaml * This creates ConfigDrivenIdeSetup instances for platforms with installer config @@ -97,9 +57,6 @@ class IdeManager { const { ConfigDrivenIdeSetup } = require('./_config-driven'); for (const [platformCode, platformInfo] of Object.entries(platformConfig.platforms)) { - // Skip if already loaded by custom installer - if (this.handlers.has(platformCode)) continue; - // Skip if no installer config (platform may not need installation) if (!platformInfo.installer) continue; @@ -127,6 +84,11 @@ class IdeManager { continue; } + // Skip suspended platforms (e.g., IDE doesn't support skills yet) + if (handler.platformConfig?.suspended) { + continue; + } + ides.push({ value: key, name: name, @@ -176,6 +138,22 @@ class IdeManager { return { success: false, ide: ideName, error: 'unsupported IDE' }; } + // Block suspended platforms — clean up legacy files but don't install + if (handler.platformConfig?.suspended) { + if (!options.silent) { + await prompts.log.warn(`${handler.displayName || ideName}: ${handler.platformConfig.suspended}`); + } + // Still clean up legacy artifacts so old broken configs don't linger + if (typeof handler.cleanup === 'function') { + try { + await handler.cleanup(projectDir, { silent: true }); + } catch { + // Best-effort cleanup — don't let stale files block the suspended result + } + } + return { success: false, ide: ideName, error: 'suspended' }; + } + try { const handlerResult = await handler.setup(projectDir, bmadDir, options); // Build detail string from handler-returned data @@ -184,29 +162,15 @@ class IdeManager { // Config-driven handlers return { success, results: { agents, workflows, tasks, tools } } const r = handlerResult.results; const parts = []; + const totalDirs = r.skillDirectories || (r.workflows || 0) + (r.tasks || 0) + (r.tools || 0) + (r.skills || 0); + const skillCount = totalDirs - (r.agents || 0); + if (skillCount > 0) parts.push(`${skillCount} skills`); if (r.agents > 0) parts.push(`${r.agents} agents`); - if (r.workflows > 0) parts.push(`${r.workflows} workflows`); - if (r.tasks > 0) parts.push(`${r.tasks} tasks`); - if (r.tools > 0) parts.push(`${r.tools} tools`); - detail = parts.join(', '); - } else if (handlerResult && handlerResult.counts) { - // Codex handler returns { success, counts: { agents, workflows, tasks }, written } - const c = handlerResult.counts; - const parts = []; - if (c.agents > 0) parts.push(`${c.agents} agents`); - if (c.workflows > 0) parts.push(`${c.workflows} workflows`); - if (c.tasks > 0) parts.push(`${c.tasks} tasks`); - detail = parts.join(', '); - } else if (handlerResult && handlerResult.modes !== undefined) { - // Kilo handler returns { success, modes, workflows, tasks, tools } - const parts = []; - if (handlerResult.modes > 0) parts.push(`${handlerResult.modes} modes`); - if (handlerResult.workflows > 0) parts.push(`${handlerResult.workflows} workflows`); - if (handlerResult.tasks > 0) parts.push(`${handlerResult.tasks} tasks`); - if (handlerResult.tools > 0) parts.push(`${handlerResult.tools} tools`); detail = parts.join(', '); } - return { success: true, ide: ideName, detail, handlerResult }; + // Propagate handler's success status (default true for backward compat) + const success = handlerResult?.success !== false; + return { success, ide: ideName, detail, error: handlerResult?.error, handlerResult }; } catch (error) { await prompts.log.error(`Failed to setup ${ideName}: ${error.message}`); return { success: false, ide: ideName, error: error.message }; diff --git a/tools/cli/installers/lib/ide/platform-codes.yaml b/tools/cli/installers/lib/ide/platform-codes.yaml index 16723f9c5..9d5f171f1 100644 --- a/tools/cli/installers/lib/ide/platform-codes.yaml +++ b/tools/cli/installers/lib/ide/platform-codes.yaml @@ -20,8 +20,11 @@ platforms: category: ide description: "Google's AI development environment" installer: - target_dir: .agent/workflows + legacy_targets: + - .agent/workflows + target_dir: .agent/skills template_type: antigravity + skill_format: true auggie: name: "Auggie" @@ -29,8 +32,11 @@ platforms: category: cli description: "AI development tool" installer: - target_dir: .augment/commands + legacy_targets: + - .augment/commands + target_dir: .augment/skills template_type: default + skill_format: true claude-code: name: "Claude Code" @@ -38,8 +44,12 @@ platforms: category: cli description: "Anthropic's official CLI for Claude" installer: - target_dir: .claude/commands + legacy_targets: + - .claude/commands + target_dir: .claude/skills template_type: default + skill_format: true + ancestor_conflict_check: true cline: name: "Cline" @@ -47,15 +57,26 @@ platforms: category: ide description: "AI coding assistant" installer: - target_dir: .clinerules/workflows - template_type: windsurf + legacy_targets: + - .clinerules/workflows + target_dir: .cline/skills + template_type: default + skill_format: true codex: name: "Codex" preferred: false category: cli description: "OpenAI Codex integration" - # No installer config - uses custom codex.js + installer: + legacy_targets: + - .codex/prompts + - ~/.codex/prompts + target_dir: .agents/skills + template_type: default + skill_format: true + ancestor_conflict_check: true + artifact_types: [agents, workflows, tasks] codebuddy: name: "CodeBuddy" @@ -63,8 +84,11 @@ platforms: category: ide description: "Tencent Cloud Code Assistant - AI-powered coding companion" installer: - target_dir: .codebuddy/commands + legacy_targets: + - .codebuddy/commands + target_dir: .codebuddy/skills template_type: default + skill_format: true crush: name: "Crush" @@ -72,8 +96,11 @@ platforms: category: ide description: "AI development assistant" installer: - target_dir: .crush/commands + legacy_targets: + - .crush/commands + target_dir: .crush/skills template_type: default + skill_format: true cursor: name: "Cursor" @@ -81,8 +108,11 @@ platforms: category: ide description: "AI-first code editor" installer: - target_dir: .cursor/commands + legacy_targets: + - .cursor/commands + target_dir: .cursor/skills template_type: default + skill_format: true gemini: name: "Gemini CLI" @@ -90,15 +120,24 @@ platforms: category: cli description: "Google's CLI for Gemini" installer: - target_dir: .gemini/commands - template_type: gemini + legacy_targets: + - .gemini/commands + target_dir: .gemini/skills + template_type: default + skill_format: true github-copilot: name: "GitHub Copilot" preferred: false category: ide description: "GitHub's AI pair programmer" - # No installer config - uses custom github-copilot.js + installer: + legacy_targets: + - .github/agents + - .github/prompts + target_dir: .github/skills + template_type: default + skill_format: true iflow: name: "iFlow" @@ -106,15 +145,24 @@ platforms: category: ide description: "AI workflow automation" installer: - target_dir: .iflow/commands + legacy_targets: + - .iflow/commands + target_dir: .iflow/skills template_type: default + skill_format: true kilo: name: "KiloCoder" preferred: false category: ide description: "AI coding platform" - # No installer config - uses custom kilo.js (creates .kilocodemodes file) + suspended: "Kilo Code does not yet support the Agent Skills standard. Support is paused until they implement it. See https://github.com/kilocode/kilo-code/issues for updates." + installer: + legacy_targets: + - .kilocode/workflows + target_dir: .kilocode/skills + template_type: default + skill_format: true kiro: name: "Kiro" @@ -122,8 +170,11 @@ platforms: category: ide description: "Amazon's AI-powered IDE" installer: - target_dir: .kiro/steering + legacy_targets: + - .kiro/steering + target_dir: .kiro/skills template_type: kiro + skill_format: true opencode: name: "OpenCode" @@ -131,13 +182,25 @@ platforms: category: ide description: "OpenCode terminal coding assistant" installer: - targets: - - target_dir: .opencode/agent - template_type: opencode - artifact_types: [agents] - - target_dir: .opencode/command - template_type: opencode - artifact_types: [workflows, tasks, tools] + legacy_targets: + - .opencode/agents + - .opencode/commands + - .opencode/agent + - .opencode/command + target_dir: .opencode/skills + template_type: opencode + skill_format: true + ancestor_conflict_check: true + + pi: + name: "Pi" + preferred: false + category: cli + description: "Provider-agnostic terminal-native AI coding agent" + installer: + target_dir: .pi/skills + template_type: default + skill_format: true qwen: name: "QwenCoder" @@ -145,24 +208,35 @@ platforms: category: ide description: "Qwen AI coding assistant" installer: - target_dir: .qwen/commands + legacy_targets: + - .qwen/commands + target_dir: .qwen/skills template_type: default + skill_format: true roo: - name: "Roo Cline" + name: "Roo Code" preferred: false category: ide description: "Enhanced Cline fork" installer: - target_dir: .roo/commands + legacy_targets: + - .roo/commands + target_dir: .roo/skills template_type: default + skill_format: true rovo-dev: name: "Rovo Dev" preferred: false category: ide description: "Atlassian's Rovo development environment" - # No installer config - uses custom rovodev.js (generates prompts.yml manifest) + installer: + legacy_targets: + - .rovodev/workflows + target_dir: .rovodev/skills + template_type: default + skill_format: true trae: name: "Trae" @@ -170,8 +244,11 @@ platforms: category: ide description: "AI coding tool" installer: - target_dir: .trae/rules - template_type: trae + legacy_targets: + - .trae/rules + target_dir: .trae/skills + template_type: default + skill_format: true windsurf: name: "Windsurf" @@ -179,8 +256,11 @@ platforms: category: ide description: "AI-powered IDE with cascade flows" installer: - target_dir: .windsurf/workflows + legacy_targets: + - .windsurf/workflows + target_dir: .windsurf/skills template_type: windsurf + skill_format: true # ============================================================================ # Installer Config Schema @@ -191,12 +271,19 @@ platforms: # template_type: string # Default template type to use # header_template: string (optional) # Override for header/frontmatter template # body_template: string (optional) # Override for body/content template +# legacy_targets: array (optional) # Old target dirs to clean up on reinstall (migration) +# - string # Relative path, e.g. .opencode/agent # targets: array (optional) # For multi-target installations # - target_dir: string # template_type: string # artifact_types: [agents, workflows, tasks, tools] # artifact_types: array (optional) # Filter which artifacts to install (default: all) # skip_existing: boolean (optional) # Skip files that already exist (default: false) +# skill_format: boolean (optional) # Use directory-per-skill output: /SKILL.md +# # with clean frontmatter (name + description, unquoted) +# ancestor_conflict_check: boolean (optional) # Refuse install when ancestor dir has BMAD files +# # in the same target_dir (for IDEs that inherit +# # skills from parent directories) # ============================================================================ # Platform Categories diff --git a/tools/cli/installers/lib/ide/rovodev.js b/tools/cli/installers/lib/ide/rovodev.js deleted file mode 100644 index da3c4809d..000000000 --- a/tools/cli/installers/lib/ide/rovodev.js +++ /dev/null @@ -1,257 +0,0 @@ -const path = require('node:path'); -const fs = require('fs-extra'); -const yaml = require('yaml'); -const { BaseIdeSetup } = require('./_base-ide'); -const prompts = require('../../../lib/prompts'); -const { AgentCommandGenerator } = require('./shared/agent-command-generator'); -const { WorkflowCommandGenerator } = require('./shared/workflow-command-generator'); -const { TaskToolCommandGenerator } = require('./shared/task-tool-command-generator'); -const { toDashPath } = require('./shared/path-utils'); - -/** - * Rovo Dev IDE setup handler - * - * Custom installer that writes .md workflow files to .rovodev/workflows/ - * and generates .rovodev/prompts.yml to register them with Rovo Dev's /prompts feature. - * - * prompts.yml format (per Rovo Dev docs): - * prompts: - * - name: bmad-bmm-create-prd - * description: "PRD workflow..." - * content_file: workflows/bmad-bmm-create-prd.md - */ -class RovoDevSetup extends BaseIdeSetup { - constructor() { - super('rovo-dev', 'Rovo Dev', false); - this.rovoDir = '.rovodev'; - this.workflowsDir = 'workflows'; - this.promptsFile = 'prompts.yml'; - } - - /** - * Setup Rovo Dev configuration - * @param {string} projectDir - Project directory - * @param {string} bmadDir - BMAD installation directory - * @param {Object} options - Setup options - * @returns {Promise} Setup result with { success, results: { agents, workflows, tasks, tools } } - */ - async setup(projectDir, bmadDir, options = {}) { - if (!options.silent) await prompts.log.info(`Setting up ${this.name}...`); - - // Clean up any old BMAD installation first - await this.cleanup(projectDir, options); - - const workflowsPath = path.join(projectDir, this.rovoDir, this.workflowsDir); - await this.ensureDir(workflowsPath); - - const selectedModules = options.selectedModules || []; - const writtenFiles = []; - - // Generate and write agent launchers - const agentGen = new AgentCommandGenerator(this.bmadFolderName); - const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, selectedModules); - const agentCount = await agentGen.writeDashArtifacts(workflowsPath, agentArtifacts); - this._collectPromptEntries(writtenFiles, agentArtifacts, ['agent-launcher'], 'agent'); - - // Generate and write workflow commands - const workflowGen = new WorkflowCommandGenerator(this.bmadFolderName); - const { artifacts: workflowArtifacts } = await workflowGen.collectWorkflowArtifacts(bmadDir); - const workflowCount = await workflowGen.writeDashArtifacts(workflowsPath, workflowArtifacts); - this._collectPromptEntries(writtenFiles, workflowArtifacts, ['workflow-command'], 'workflow'); - - // Generate and write task/tool commands - const taskToolGen = new TaskToolCommandGenerator(this.bmadFolderName); - const { artifacts: taskToolArtifacts, counts: taskToolCounts } = await taskToolGen.collectTaskToolArtifacts(bmadDir); - await taskToolGen.writeDashArtifacts(workflowsPath, taskToolArtifacts); - const taskCount = taskToolCounts.tasks || 0; - const toolCount = taskToolCounts.tools || 0; - this._collectPromptEntries(writtenFiles, taskToolArtifacts, ['task', 'tool']); - - // Generate prompts.yml manifest (only if we have entries to write) - if (writtenFiles.length > 0) { - await this.generatePromptsYml(projectDir, writtenFiles); - } - - if (!options.silent) { - await prompts.log.success( - `${this.name} configured: ${agentCount} agents, ${workflowCount} workflows, ${taskCount} tasks, ${toolCount} tools`, - ); - } - - return { - success: true, - results: { - agents: agentCount, - workflows: workflowCount, - tasks: taskCount, - tools: toolCount, - }, - }; - } - - /** - * Collect prompt entries from artifacts into writtenFiles array - * @param {Array} writtenFiles - Target array to push entries into - * @param {Array} artifacts - Artifacts from a generator's collect method - * @param {string[]} acceptedTypes - Artifact types to include (e.g., ['agent-launcher']) - * @param {string} [fallbackSuffix] - Suffix for fallback description; defaults to artifact.type - */ - _collectPromptEntries(writtenFiles, artifacts, acceptedTypes, fallbackSuffix) { - for (const artifact of artifacts) { - if (!acceptedTypes.includes(artifact.type)) continue; - const flatName = toDashPath(artifact.relativePath); - writtenFiles.push({ - name: path.basename(flatName, '.md'), - description: artifact.description || `${artifact.name} ${fallbackSuffix || artifact.type}`, - contentFile: `${this.workflowsDir}/${flatName}`, - }); - } - } - - /** - * Generate .rovodev/prompts.yml manifest - * Merges with existing user entries -- strips entries with names starting 'bmad-', - * appends new BMAD entries, and writes back. - * - * @param {string} projectDir - Project directory - * @param {Array} writtenFiles - Array of { name, description, contentFile } - */ - async generatePromptsYml(projectDir, writtenFiles) { - const promptsPath = path.join(projectDir, this.rovoDir, this.promptsFile); - let existingPrompts = []; - - // Read existing prompts.yml and preserve non-BMAD entries - if (await this.pathExists(promptsPath)) { - try { - const content = await this.readFile(promptsPath); - const parsed = yaml.parse(content); - if (parsed && Array.isArray(parsed.prompts)) { - // Keep only non-BMAD entries (entries whose name does NOT start with bmad-) - existingPrompts = parsed.prompts.filter((entry) => !entry.name || !entry.name.startsWith('bmad-')); - } - } catch { - // If parsing fails, start fresh but preserve file safety - existingPrompts = []; - } - } - - // Build new BMAD entries (prefix description with name so /prompts list is scannable) - const bmadEntries = writtenFiles.map((file) => ({ - name: file.name, - description: `${file.name} - ${file.description}`, - content_file: file.contentFile, - })); - - // Merge: user entries first, then BMAD entries - const allPrompts = [...existingPrompts, ...bmadEntries]; - - const config = { prompts: allPrompts }; - const yamlContent = yaml.stringify(config, { lineWidth: 0 }); - await this.writeFile(promptsPath, yamlContent); - } - - /** - * Cleanup Rovo Dev configuration - * Removes bmad-* files from .rovodev/workflows/ and strips BMAD entries from prompts.yml - * @param {string} projectDir - Project directory - * @param {Object} options - Cleanup options - */ - async cleanup(projectDir, options = {}) { - const workflowsPath = path.join(projectDir, this.rovoDir, this.workflowsDir); - - // Remove all bmad-* entries from workflows dir (aligned with detect() predicate) - if (await this.pathExists(workflowsPath)) { - const entries = await fs.readdir(workflowsPath); - for (const entry of entries) { - if (entry.startsWith('bmad-')) { - await fs.remove(path.join(workflowsPath, entry)); - } - } - } - - // Clean BMAD entries from prompts.yml (preserve user entries) - const promptsPath = path.join(projectDir, this.rovoDir, this.promptsFile); - if (await this.pathExists(promptsPath)) { - try { - const content = await this.readFile(promptsPath); - const parsed = yaml.parse(content) || {}; - - if (Array.isArray(parsed.prompts)) { - const originalCount = parsed.prompts.length; - parsed.prompts = parsed.prompts.filter((entry) => !entry.name || !entry.name.startsWith('bmad-')); - const removedCount = originalCount - parsed.prompts.length; - - if (removedCount > 0) { - if (parsed.prompts.length === 0) { - // If no entries remain, remove the file entirely - await fs.remove(promptsPath); - } else { - await this.writeFile(promptsPath, yaml.stringify(parsed, { lineWidth: 0 })); - } - if (!options.silent) { - await prompts.log.message(`Removed ${removedCount} BMAD entries from ${this.promptsFile}`); - } - } - } - } catch { - // If parsing fails, leave file as-is - if (!options.silent) { - await prompts.log.warn(`Warning: Could not parse ${this.promptsFile} for cleanup`); - } - } - } - - // Remove empty .rovodev directories - if (await this.pathExists(workflowsPath)) { - const remaining = await fs.readdir(workflowsPath); - if (remaining.length === 0) { - await fs.remove(workflowsPath); - } - } - - const rovoDirPath = path.join(projectDir, this.rovoDir); - if (await this.pathExists(rovoDirPath)) { - const remaining = await fs.readdir(rovoDirPath); - if (remaining.length === 0) { - await fs.remove(rovoDirPath); - } - } - } - - /** - * Detect whether Rovo Dev configuration exists in the project - * Checks for .rovodev/ dir with bmad files or bmad entries in prompts.yml - * @param {string} projectDir - Project directory - * @returns {boolean} - */ - async detect(projectDir) { - const workflowsPath = path.join(projectDir, this.rovoDir, this.workflowsDir); - - // Check for bmad files in workflows dir - if (await fs.pathExists(workflowsPath)) { - const entries = await fs.readdir(workflowsPath); - if (entries.some((entry) => entry.startsWith('bmad-'))) { - return true; - } - } - - // Check for bmad entries in prompts.yml - const promptsPath = path.join(projectDir, this.rovoDir, this.promptsFile); - if (await fs.pathExists(promptsPath)) { - try { - const content = await fs.readFile(promptsPath, 'utf8'); - const parsed = yaml.parse(content); - if (parsed && Array.isArray(parsed.prompts)) { - return parsed.prompts.some((entry) => entry.name && entry.name.startsWith('bmad-')); - } - } catch { - // If parsing fails, check raw content - return false; - } - } - - return false; - } -} - -module.exports = { RovoDevSetup }; diff --git a/tools/cli/installers/lib/ide/shared/agent-command-generator.js b/tools/cli/installers/lib/ide/shared/agent-command-generator.js index 0915c306b..37820992e 100644 --- a/tools/cli/installers/lib/ide/shared/agent-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/agent-command-generator.js @@ -47,6 +47,7 @@ class AgentCommandGenerator { name: agent.name, description: agent.description || `${agent.name} agent`, module: agent.module, + canonicalId: agent.canonicalId || '', relativePath: path.join(agent.module, 'agents', agentPathInModule), // For command filename agentPath: agentRelPath, // Relative path to actual agent file content: launcherContent, diff --git a/tools/cli/installers/lib/ide/shared/bmad-artifacts.js b/tools/cli/installers/lib/ide/shared/bmad-artifacts.js index 7bcfd6a79..d3edf0cd2 100644 --- a/tools/cli/installers/lib/ide/shared/bmad-artifacts.js +++ b/tools/cli/installers/lib/ide/shared/bmad-artifacts.js @@ -1,5 +1,6 @@ const path = require('node:path'); const fs = require('fs-extra'); +const { loadSkillManifest, getCanonicalId } = require('./skill-manifest'); /** * Helpers for gathering BMAD agents/tasks from the installed tree. @@ -34,6 +35,7 @@ async function getAgentsFromBmad(bmadDir, selectedModules = []) { const agentDirPath = path.join(standaloneAgentsDir, agentDir.name); const agentFiles = await fs.readdir(agentDirPath); + const skillManifest = await loadSkillManifest(agentDirPath); for (const file of agentFiles) { if (!file.endsWith('.md')) continue; @@ -48,6 +50,7 @@ async function getAgentsFromBmad(bmadDir, selectedModules = []) { path: filePath, name: file.replace('.md', ''), module: 'standalone', // Mark as standalone agent + canonicalId: getCanonicalId(skillManifest, file), }); } } @@ -84,6 +87,7 @@ async function getAgentsFromDir(dirPath, moduleName, relativePath = '') { } const entries = await fs.readdir(dirPath, { withFileTypes: true }); + const skillManifest = await loadSkillManifest(dirPath); for (const entry of entries) { // Skip if entry.name is undefined or not a string @@ -124,6 +128,7 @@ async function getAgentsFromDir(dirPath, moduleName, relativePath = '') { name: entry.name.replace('.md', ''), module: moduleName, relativePath: newRelativePath, // Keep the .md extension for the full path + canonicalId: getCanonicalId(skillManifest, entry.name), }); } } @@ -139,6 +144,7 @@ async function getTasksFromDir(dirPath, moduleName) { } const files = await fs.readdir(dirPath); + const skillManifest = await loadSkillManifest(dirPath); for (const file of files) { // Include both .md and .xml task files @@ -160,6 +166,7 @@ async function getTasksFromDir(dirPath, moduleName) { path: filePath, name: file.replace(ext, ''), module: moduleName, + canonicalId: getCanonicalId(skillManifest, file), }); } diff --git a/tools/cli/installers/lib/ide/shared/path-utils.js b/tools/cli/installers/lib/ide/shared/path-utils.js index 519669233..35fc263f4 100644 --- a/tools/cli/installers/lib/ide/shared/path-utils.js +++ b/tools/cli/installers/lib/ide/shared/path-utils.js @@ -12,6 +12,7 @@ * - bmm/workflows/plan-project.md → bmad-bmm-plan-project.md * - bmm/tasks/create-story.md → bmad-bmm-create-story.md * - core/agents/brainstorming.md → bmad-agent-brainstorming.md (core agents skip module name) + * - standalone/agents/fred.md → bmad-agent-standalone-fred.md */ // Type segments - agents are included in naming, others are filtered out @@ -26,8 +27,9 @@ const BMAD_FOLDER_NAME = '_bmad'; * Converts: 'bmm', 'agents', 'pm' → 'bmad-agent-bmm-pm.md' * Converts: 'bmm', 'workflows', 'correct-course' → 'bmad-bmm-correct-course.md' * Converts: 'core', 'agents', 'brainstorming' → 'bmad-agent-brainstorming.md' (core agents skip module name) + * Converts: 'standalone', 'agents', 'fred' → 'bmad-agent-standalone-fred.md' * - * @param {string} module - Module name (e.g., 'bmm', 'core') + * @param {string} module - Module name (e.g., 'bmm', 'core', 'standalone') * @param {string} type - Artifact type ('agents', 'workflows', 'tasks', 'tools') * @param {string} name - Artifact name (e.g., 'pm', 'brainstorming') * @returns {string} Flat filename like 'bmad-agent-bmm-pm.md' or 'bmad-bmm-correct-course.md' @@ -39,6 +41,10 @@ function toDashName(module, type, name) { if (module === 'core') { return isAgent ? `bmad-agent-${name}.md` : `bmad-${name}.md`; } + // For standalone module, include 'standalone' in the name + if (module === 'standalone') { + return isAgent ? `bmad-agent-standalone-${name}.md` : `bmad-standalone-${name}.md`; + } // Module artifacts: bmad-module-name.md or bmad-agent-module-name.md // eslint-disable-next-line unicorn/prefer-string-replace-all -- regex replace is intentional here @@ -63,7 +69,7 @@ function toDashPath(relativePath) { } // Strip common file extensions to avoid double extensions in generated filenames - // e.g., 'create-story.xml' → 'create-story', 'workflow.yaml' → 'workflow' + // e.g., 'create-story.xml' → 'create-story', 'workflow.md' → 'workflow' const withoutExt = relativePath.replace(/\.(md|yaml|yml|json|xml|toml)$/i, ''); const parts = withoutExt.split(/[/\\]/); @@ -110,6 +116,8 @@ function isDashFormat(filename) { * Parses: 'bmad-bmm-correct-course.md' → { prefix: 'bmad', module: 'bmm', type: 'workflows', name: 'correct-course' } * Parses: 'bmad-agent-brainstorming.md' → { prefix: 'bmad', module: 'core', type: 'agents', name: 'brainstorming' } (core agents) * Parses: 'bmad-brainstorming.md' → { prefix: 'bmad', module: 'core', type: 'workflows', name: 'brainstorming' } (core workflows) + * Parses: 'bmad-agent-standalone-fred.md' → { prefix: 'bmad', module: 'standalone', type: 'agents', name: 'fred' } + * Parses: 'bmad-standalone-foo.md' → { prefix: 'bmad', module: 'standalone', type: 'workflows', name: 'foo' } * * @param {string} filename - Dash-formatted filename * @returns {Object|null} Parsed parts or null if invalid format @@ -127,7 +135,16 @@ function parseDashName(filename) { if (isAgent) { // This is an agent file - // Format: bmad-agent-name (core) or bmad-agent-module-name + // Format: bmad-agent-name (core) or bmad-agent-standalone-name or bmad-agent-module-name + if (parts.length >= 4 && parts[2] === 'standalone') { + // Standalone agent: bmad-agent-standalone-name + return { + prefix: parts[0], + module: 'standalone', + type: 'agents', + name: parts.slice(3).join('-'), + }; + } if (parts.length === 3) { // Core agent: bmad-agent-name return { @@ -158,6 +175,16 @@ function parseDashName(filename) { }; } + // Check for standalone non-agent: bmad-standalone-name + if (parts[1] === 'standalone') { + return { + prefix: parts[0], + module: 'standalone', + type: 'workflows', // Default to workflows for non-agent standalone items + name: parts.slice(2).join('-'), + }; + } + // Otherwise, it's a module workflow/tool/task (bmad-module-name) return { prefix: parts[0], @@ -180,6 +207,9 @@ function toUnderscoreName(module, type, name) { if (module === 'core') { return isAgent ? `bmad_agent_${name}.md` : `bmad_${name}.md`; } + if (module === 'standalone') { + return isAgent ? `bmad_agent_standalone_${name}.md` : `bmad_standalone_${name}.md`; + } return isAgent ? `bmad_${module}_agent_${name}.md` : `bmad_${module}_${name}.md`; } @@ -231,6 +261,15 @@ function parseUnderscoreName(filename) { if (agentIndex !== -1) { if (agentIndex === 1) { + // bmad_agent_... - check for standalone + if (parts.length >= 4 && parts[2] === 'standalone') { + return { + prefix: parts[0], + module: 'standalone', + type: 'agents', + name: parts.slice(3).join('_'), + }; + } return { prefix: parts[0], module: 'core', @@ -256,6 +295,16 @@ function parseUnderscoreName(filename) { }; } + // Check for standalone non-agent: bmad_standalone_name + if (parts[1] === 'standalone') { + return { + prefix: parts[0], + module: 'standalone', + type: 'workflows', + name: parts.slice(2).join('_'), + }; + } + return { prefix: parts[0], module: parts[1], @@ -264,6 +313,21 @@ function parseUnderscoreName(filename) { }; } +/** + * Resolve the skill name for an artifact. + * Prefers canonicalId from a bmad-skill-manifest.yaml sidecar when available, + * falling back to the path-derived name from toDashPath(). + * + * @param {Object} artifact - Artifact object (must have relativePath; may have canonicalId) + * @returns {string} Filename like 'bmad-create-prd.md' or 'bmad-agent-bmm-pm.md' + */ +function resolveSkillName(artifact) { + if (artifact.canonicalId) { + return `${artifact.canonicalId}.md`; + } + return toDashPath(artifact.relativePath); +} + // Backward compatibility aliases (colon format was same as underscore) const toColonName = toUnderscoreName; const toColonPath = toUnderscorePath; @@ -275,6 +339,7 @@ module.exports = { // New standard (dash-based) toDashName, toDashPath, + resolveSkillName, customAgentDashName, isDashFormat, parseDashName, diff --git a/tools/cli/installers/lib/ide/shared/skill-manifest.js b/tools/cli/installers/lib/ide/shared/skill-manifest.js new file mode 100644 index 000000000..22a7cceef --- /dev/null +++ b/tools/cli/installers/lib/ide/shared/skill-manifest.js @@ -0,0 +1,90 @@ +const path = require('node:path'); +const fs = require('fs-extra'); +const yaml = require('yaml'); + +/** + * Load bmad-skill-manifest.yaml from a directory. + * Single-entry manifests (canonicalId at top level) apply to all files in the directory. + * Multi-entry manifests are keyed by source filename. + * @param {string} dirPath - Directory to check for bmad-skill-manifest.yaml + * @returns {Object|null} Parsed manifest or null + */ +async function loadSkillManifest(dirPath) { + const manifestPath = path.join(dirPath, 'bmad-skill-manifest.yaml'); + try { + if (!(await fs.pathExists(manifestPath))) return null; + const content = await fs.readFile(manifestPath, 'utf8'); + const parsed = yaml.parse(content); + if (!parsed || typeof parsed !== 'object') return null; + if (parsed.canonicalId || parsed.type) return { __single: parsed }; + return parsed; + } catch (error) { + console.warn(`Warning: Failed to parse bmad-skill-manifest.yaml in ${dirPath}: ${error.message}`); + return null; + } +} + +/** + * Get the canonicalId for a specific file from a loaded skill manifest. + * @param {Object|null} manifest - Loaded manifest (from loadSkillManifest) + * @param {string} filename - Source filename to look up (e.g., 'pm.md', 'help.md', 'pm.agent.yaml') + * @returns {string} canonicalId or empty string + */ +function getCanonicalId(manifest, filename) { + if (!manifest) return ''; + // Single-entry manifest applies to all files in the directory + if (manifest.__single) return manifest.__single.canonicalId || ''; + // Multi-entry: look up by filename directly + if (manifest[filename]) return manifest[filename].canonicalId || ''; + // Fallback: try alternate extensions for compiled files + const baseName = filename.replace(/\.(md|xml)$/i, ''); + const agentKey = `${baseName}.agent.yaml`; + if (manifest[agentKey]) return manifest[agentKey].canonicalId || ''; + const xmlKey = `${baseName}.xml`; + if (manifest[xmlKey]) return manifest[xmlKey].canonicalId || ''; + return ''; +} + +/** + * Get the artifact type for a specific file from a loaded skill manifest. + * @param {Object|null} manifest - Loaded manifest (from loadSkillManifest) + * @param {string} filename - Source filename to look up + * @returns {string|null} type or null + */ +function getArtifactType(manifest, filename) { + if (!manifest) return null; + // Single-entry manifest applies to all files in the directory + if (manifest.__single) return manifest.__single.type || null; + // Multi-entry: look up by filename directly + if (manifest[filename]) return manifest[filename].type || null; + // Fallback: try alternate extensions for compiled files + const baseName = filename.replace(/\.(md|xml)$/i, ''); + const agentKey = `${baseName}.agent.yaml`; + if (manifest[agentKey]) return manifest[agentKey].type || null; + const xmlKey = `${baseName}.xml`; + if (manifest[xmlKey]) return manifest[xmlKey].type || null; + return null; +} + +/** + * Get the install_to_bmad flag for a specific file from a loaded skill manifest. + * @param {Object|null} manifest - Loaded manifest (from loadSkillManifest) + * @param {string} filename - Source filename to look up + * @returns {boolean} install_to_bmad value (defaults to true) + */ +function getInstallToBmad(manifest, filename) { + if (!manifest) return true; + // Single-entry manifest applies to all files in the directory + if (manifest.__single) return manifest.__single.install_to_bmad !== false; + // Multi-entry: look up by filename directly + if (manifest[filename]) return manifest[filename].install_to_bmad !== false; + // Fallback: try alternate extensions for compiled files + const baseName = filename.replace(/\.(md|xml)$/i, ''); + const agentKey = `${baseName}.agent.yaml`; + if (manifest[agentKey]) return manifest[agentKey].install_to_bmad !== false; + const xmlKey = `${baseName}.xml`; + if (manifest[xmlKey]) return manifest[xmlKey].install_to_bmad !== false; + return true; +} + +module.exports = { loadSkillManifest, getCanonicalId, getArtifactType, getInstallToBmad }; diff --git a/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js b/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js index ece1c8630..f21a5d174 100644 --- a/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js @@ -50,6 +50,7 @@ class TaskToolCommandGenerator { displayName: task.displayName || task.name, description: task.description || `Execute ${task.displayName || task.name}`, module: task.module, + canonicalId: task.canonicalId || '', // Use forward slashes for cross-platform consistency (not path.join which uses backslashes on Windows) relativePath: `${task.module}/tasks/${task.name}${taskExt}`, path: taskPath, @@ -75,6 +76,7 @@ class TaskToolCommandGenerator { displayName: tool.displayName || tool.name, description: tool.description || `Execute ${tool.displayName || tool.name}`, module: tool.module, + canonicalId: tool.canonicalId || '', // Use forward slashes for cross-platform consistency (not path.join which uses backslashes on Windows) relativePath: `${tool.module}/tools/${tool.name}${toolExt}`, path: toolPath, @@ -176,7 +178,6 @@ class TaskToolCommandGenerator { return `--- description: '${description.replaceAll("'", "''")}' -disable-model-invocation: true --- # ${item.displayName || item.name} diff --git a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js index d94e77db1..ed8c3e508 100644 --- a/tools/cli/installers/lib/ide/shared/workflow-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/workflow-command-generator.js @@ -1,58 +1,16 @@ const path = require('node:path'); const fs = require('fs-extra'); const csv = require('csv-parse/sync'); -const prompts = require('../../../../lib/prompts'); -const { toColonPath, toDashPath, customAgentColonName, customAgentDashName, BMAD_FOLDER_NAME } = require('./path-utils'); +const { BMAD_FOLDER_NAME } = require('./path-utils'); /** * Generates command files for each workflow in the manifest */ class WorkflowCommandGenerator { constructor(bmadFolderName = BMAD_FOLDER_NAME) { - this.templatePath = path.join(__dirname, '../templates/workflow-command-template.md'); this.bmadFolderName = bmadFolderName; } - /** - * Generate workflow commands from the manifest CSV - * @param {string} projectDir - Project directory - * @param {string} bmadDir - BMAD installation directory - */ - async generateWorkflowCommands(projectDir, bmadDir) { - const workflows = await this.loadWorkflowManifest(bmadDir); - - if (!workflows) { - await prompts.log.warn('Workflow manifest not found. Skipping command generation.'); - return { generated: 0 }; - } - - // ALL workflows now generate commands - no standalone filtering - const allWorkflows = workflows; - - // Base commands directory - const baseCommandsDir = path.join(projectDir, '.claude', 'commands', 'bmad'); - - let generatedCount = 0; - - // Generate a command file for each workflow, organized by module - for (const workflow of allWorkflows) { - const moduleWorkflowsDir = path.join(baseCommandsDir, workflow.module, 'workflows'); - await fs.ensureDir(moduleWorkflowsDir); - - const commandContent = await this.generateCommandContent(workflow, bmadDir); - const commandPath = path.join(moduleWorkflowsDir, `${workflow.name}.md`); - - await fs.writeFile(commandPath, commandContent); - generatedCount++; - } - - // Also create a workflow launcher README in each module - const groupedWorkflows = this.groupWorkflowsByModule(allWorkflows); - await this.createModuleWorkflowLaunchers(baseCommandsDir, groupedWorkflows); - - return { generated: generatedCount }; - } - async collectWorkflowArtifacts(bmadDir) { const workflows = await this.loadWorkflowManifest(bmadDir); @@ -66,8 +24,7 @@ class WorkflowCommandGenerator { const artifacts = []; for (const workflow of allWorkflows) { - const commandContent = await this.generateCommandContent(workflow, bmadDir); - // Calculate the relative workflow path (e.g., bmm/workflows/4-implementation/sprint-planning/workflow.yaml) + // Calculate the relative workflow path (e.g., bmm/workflows/4-implementation/sprint-planning/workflow.md) let workflowRelPath = workflow.path || ''; // Normalize path separators for cross-platform compatibility workflowRelPath = workflowRelPath.replaceAll('\\', '/'); @@ -85,17 +42,14 @@ class WorkflowCommandGenerator { workflowRelPath = `${match[1]}/${match[2]}`; } } - // Determine if this is a YAML workflow (use normalized path which is guaranteed to be a string) - const isYamlWorkflow = workflowRelPath.endsWith('.yaml') || workflowRelPath.endsWith('.yml'); artifacts.push({ type: 'workflow-command', - isYamlWorkflow: isYamlWorkflow, // For template selection name: workflow.name, description: workflow.description || `${workflow.name} workflow`, module: workflow.module, + canonicalId: workflow.canonicalId || '', relativePath: path.join(workflow.module, 'workflows', `${workflow.name}.md`), workflowPath: workflowRelPath, // Relative path to actual workflow file - content: commandContent, sourcePath: workflow.path, }); } @@ -120,46 +74,6 @@ class WorkflowCommandGenerator { }; } - /** - * Generate command content for a workflow - */ - async generateCommandContent(workflow, bmadDir) { - // Determine template based on workflow file type - const isMarkdownWorkflow = workflow.path.endsWith('workflow.md'); - const templateName = isMarkdownWorkflow ? 'workflow-commander.md' : 'workflow-command-template.md'; - const templatePath = path.join(path.dirname(this.templatePath), templateName); - - // Load the appropriate template - const template = await fs.readFile(templatePath, 'utf8'); - - // Convert source path to installed path - // From: /Users/.../src/bmm/workflows/.../workflow.yaml - // To: {project-root}/_bmad/bmm/workflows/.../workflow.yaml - let workflowPath = workflow.path; - - // Extract the relative path from source - if (workflowPath.includes('/src/bmm/')) { - // bmm is directly under src/ - const match = workflowPath.match(/\/src\/bmm\/(.+)/); - if (match) { - workflowPath = `${this.bmadFolderName}/bmm/${match[1]}`; - } - } else if (workflowPath.includes('/src/core/')) { - const match = workflowPath.match(/\/src\/core\/(.+)/); - if (match) { - workflowPath = `${this.bmadFolderName}/core/${match[1]}`; - } - } - - // Replace template variables - return template - .replaceAll('{{name}}', workflow.name) - .replaceAll('{{module}}', workflow.module) - .replaceAll('{{description}}', workflow.description) - .replaceAll('{{workflow_path}}', workflowPath) - .replaceAll('_bmad', this.bmadFolderName); - } - /** * Create workflow launcher files for each module */ @@ -217,10 +131,9 @@ class WorkflowCommandGenerator { ## Execution When running any workflow: -1. LOAD {project-root}/${this.bmadFolderName}/core/tasks/workflow.xml -2. Pass the workflow path as 'workflow-config' parameter -3. Follow workflow.xml instructions EXACTLY -4. Save outputs after EACH section +1. LOAD the workflow.md file at the path shown above +2. READ its entire contents and follow its directions exactly +3. Save outputs after EACH section ## Modes - Normal: Full interaction @@ -261,58 +174,6 @@ When running any workflow: skip_empty_lines: true, }); } - - /** - * Write workflow command artifacts using underscore format (Windows-compatible) - * Creates flat files like: bmad_bmm_correct-course.md - * - * @param {string} baseCommandsDir - Base commands directory for the IDE - * @param {Array} artifacts - Workflow artifacts - * @returns {number} Count of commands written - */ - async writeColonArtifacts(baseCommandsDir, artifacts) { - let writtenCount = 0; - - for (const artifact of artifacts) { - if (artifact.type === 'workflow-command') { - // Convert relativePath to underscore format: bmm/workflows/correct-course.md → bmad_bmm_correct-course.md - const flatName = toColonPath(artifact.relativePath); - const commandPath = path.join(baseCommandsDir, flatName); - await fs.ensureDir(path.dirname(commandPath)); - await fs.writeFile(commandPath, artifact.content); - writtenCount++; - } - } - - return writtenCount; - } - - /** - * Write workflow command artifacts using dash format (NEW STANDARD) - * Creates flat files like: bmad-bmm-correct-course.md - * - * Note: Workflows do NOT have bmad-agent- prefix - only agents do. - * - * @param {string} baseCommandsDir - Base commands directory for the IDE - * @param {Array} artifacts - Workflow artifacts - * @returns {number} Count of commands written - */ - async writeDashArtifacts(baseCommandsDir, artifacts) { - let writtenCount = 0; - - for (const artifact of artifacts) { - if (artifact.type === 'workflow-command') { - // Convert relativePath to dash format: bmm/workflows/correct-course.md → bmad-bmm-correct-course.md - const flatName = toDashPath(artifact.relativePath); - const commandPath = path.join(baseCommandsDir, flatName); - await fs.ensureDir(path.dirname(commandPath)); - await fs.writeFile(commandPath, artifact.content); - writtenCount++; - } - } - - return writtenCount; - } } module.exports = { WorkflowCommandGenerator }; diff --git a/tools/cli/installers/lib/ide/templates/agent-command-template.md b/tools/cli/installers/lib/ide/templates/agent-command-template.md index 90e176a03..0f0c2e20d 100644 --- a/tools/cli/installers/lib/ide/templates/agent-command-template.md +++ b/tools/cli/installers/lib/ide/templates/agent-command-template.md @@ -1,13 +1,12 @@ --- name: '{{name}}' description: '{{description}}' -disable-model-invocation: true --- You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command. -1. LOAD the FULL agent file from @_bmad/{{module}}/agents/{{path}} +1. LOAD the FULL agent file from {project-root}/_bmad/{{module}}/agents/{{path}} 2. READ its entire contents - this contains the complete agent persona, menu, and instructions 3. Execute ALL activation steps exactly as written in the agent file 4. Follow the agent's persona and menu system precisely diff --git a/tools/cli/installers/lib/ide/templates/combined/default-agent.md b/tools/cli/installers/lib/ide/templates/combined/default-agent.md index 17a0be4ba..f8ad93801 100644 --- a/tools/cli/installers/lib/ide/templates/combined/default-agent.md +++ b/tools/cli/installers/lib/ide/templates/combined/default-agent.md @@ -1,7 +1,6 @@ --- name: '{{name}}' description: '{{description}}' -disable-model-invocation: true --- You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command. diff --git a/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md b/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md deleted file mode 100644 index 2a5e49b83..000000000 --- a/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -name: '{{name}}' -description: '{{description}}' -disable-model-invocation: true ---- - -IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded: - - -1. Always LOAD the FULL @{project-root}/{{bmadFolderName}}/core/tasks/workflow.xml -2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @{project-root}/{{bmadFolderName}}/{{path}} -3. Pass the yaml path @{project-root}/{{bmadFolderName}}/{{path}} as 'workflow-config' parameter to the workflow.xml instructions -4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions -5. Save outputs after EACH section when generating any documents from templates - diff --git a/tools/cli/installers/lib/ide/templates/combined/default-workflow.md b/tools/cli/installers/lib/ide/templates/combined/default-workflow.md index 8c4fa818f..c8ad40459 100644 --- a/tools/cli/installers/lib/ide/templates/combined/default-workflow.md +++ b/tools/cli/installers/lib/ide/templates/combined/default-workflow.md @@ -1,7 +1,6 @@ --- name: '{{name}}' description: '{{description}}' -disable-model-invocation: true --- -IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{project-root}/{{bmadFolderName}}/{{path}}, READ its entire contents and follow its directions exactly! +IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL {project-root}/{{bmadFolderName}}/{{path}}, READ its entire contents and follow its directions exactly! diff --git a/tools/cli/installers/lib/ide/templates/combined/gemini-workflow-yaml.toml b/tools/cli/installers/lib/ide/templates/combined/gemini-workflow-yaml.toml index 063ca0d0b..bc6c8da39 100644 --- a/tools/cli/installers/lib/ide/templates/combined/gemini-workflow-yaml.toml +++ b/tools/cli/installers/lib/ide/templates/combined/gemini-workflow-yaml.toml @@ -1,4 +1,4 @@ -description = """{{description}}""" +description = '{{description}}' prompt = """ Execute the BMAD '{{name}}' workflow. diff --git a/tools/cli/installers/lib/ide/templates/combined/gemini-workflow.toml b/tools/cli/installers/lib/ide/templates/combined/gemini-workflow.toml index 526241061..3306cce04 100644 --- a/tools/cli/installers/lib/ide/templates/combined/gemini-workflow.toml +++ b/tools/cli/installers/lib/ide/templates/combined/gemini-workflow.toml @@ -1,4 +1,4 @@ -description = """{{description}}""" +description = '{{description}}' prompt = """ Execute the BMAD '{{name}}' workflow. diff --git a/tools/cli/installers/lib/ide/templates/combined/kiro-workflow-yaml.md b/tools/cli/installers/lib/ide/templates/combined/kiro-workflow-yaml.md deleted file mode 100644 index 4ee4e0824..000000000 --- a/tools/cli/installers/lib/ide/templates/combined/kiro-workflow-yaml.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -inclusion: manual ---- - -# {{name}} - -IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded: - - -1. Always LOAD the FULL #[[file:{{bmadFolderName}}/core/tasks/workflow.xml]] -2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config #[[file:{{bmadFolderName}}/{{path}}]] -3. Pass the yaml path {{bmadFolderName}}/{{path}} as 'workflow-config' parameter to the workflow.xml instructions -4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions -5. Save outputs after EACH section when generating any documents from templates - diff --git a/tools/cli/installers/lib/ide/templates/combined/opencode-agent.md b/tools/cli/installers/lib/ide/templates/combined/opencode-agent.md index 65f0a771d..828d673ac 100644 --- a/tools/cli/installers/lib/ide/templates/combined/opencode-agent.md +++ b/tools/cli/installers/lib/ide/templates/combined/opencode-agent.md @@ -1,5 +1,5 @@ --- -name: '{{name}}' +mode: all description: '{{description}}' --- diff --git a/tools/cli/installers/lib/ide/templates/combined/opencode-task.md b/tools/cli/installers/lib/ide/templates/combined/opencode-task.md index 98b3a5d77..772f9c9eb 100644 --- a/tools/cli/installers/lib/ide/templates/combined/opencode-task.md +++ b/tools/cli/installers/lib/ide/templates/combined/opencode-task.md @@ -1,5 +1,4 @@ --- -name: '{{name}}' description: '{{description}}' --- diff --git a/tools/cli/installers/lib/ide/templates/combined/opencode-tool.md b/tools/cli/installers/lib/ide/templates/combined/opencode-tool.md index 1ae9c9ac8..88c317e63 100644 --- a/tools/cli/installers/lib/ide/templates/combined/opencode-tool.md +++ b/tools/cli/installers/lib/ide/templates/combined/opencode-tool.md @@ -1,5 +1,4 @@ --- -name: '{{name}}' description: '{{description}}' --- diff --git a/tools/cli/installers/lib/ide/templates/combined/opencode-workflow-yaml.md b/tools/cli/installers/lib/ide/templates/combined/opencode-workflow-yaml.md index a6f5cb96f..88838cc1c 100644 --- a/tools/cli/installers/lib/ide/templates/combined/opencode-workflow-yaml.md +++ b/tools/cli/installers/lib/ide/templates/combined/opencode-workflow-yaml.md @@ -1,5 +1,4 @@ --- -name: '{{name}}' description: '{{description}}' --- diff --git a/tools/cli/installers/lib/ide/templates/combined/opencode-workflow.md b/tools/cli/installers/lib/ide/templates/combined/opencode-workflow.md index a6f5cb96f..88838cc1c 100644 --- a/tools/cli/installers/lib/ide/templates/combined/opencode-workflow.md +++ b/tools/cli/installers/lib/ide/templates/combined/opencode-workflow.md @@ -1,5 +1,4 @@ --- -name: '{{name}}' description: '{{description}}' --- diff --git a/tools/cli/installers/lib/ide/templates/workflow-command-template.md b/tools/cli/installers/lib/ide/templates/workflow-command-template.md deleted file mode 100644 index 472c1553a..000000000 --- a/tools/cli/installers/lib/ide/templates/workflow-command-template.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: '{{description}}' -disable-model-invocation: true ---- - -IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded: - - -1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml -2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @{{workflow_path}} -3. Pass the yaml path {{workflow_path}} as 'workflow-config' parameter to the workflow.xml instructions -4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions -5. Save outputs after EACH section when generating any documents from templates - diff --git a/tools/cli/installers/lib/ide/templates/workflow-commander.md b/tools/cli/installers/lib/ide/templates/workflow-commander.md deleted file mode 100644 index d49c8319d..000000000 --- a/tools/cli/installers/lib/ide/templates/workflow-commander.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: '{{description}}' -disable-model-invocation: true ---- - -IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{{workflow_path}}, READ its entire contents and follow its directions exactly! diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index f162593b7..9bc027d85 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -762,14 +762,8 @@ class ModuleManager { } } - // Check if this is a workflow.yaml file - if (file.endsWith('workflow.yaml')) { - await fs.ensureDir(path.dirname(targetFile)); - await this.copyWorkflowYamlStripped(sourceFile, targetFile); - } else { - // Copy the file with placeholder replacement - await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile); - } + // Copy the file with placeholder replacement + await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile); // Track the file if callback provided if (fileTrackingCallback) { @@ -778,92 +772,6 @@ class ModuleManager { } } - /** - * Copy workflow.yaml file with web_bundle section stripped - * Preserves comments, formatting, and line breaks - * @param {string} sourceFile - Source workflow.yaml file path - * @param {string} targetFile - Target workflow.yaml file path - */ - async copyWorkflowYamlStripped(sourceFile, targetFile) { - // Read the source YAML file - let yamlContent = await fs.readFile(sourceFile, 'utf8'); - - // IMPORTANT: Replace escape sequence and placeholder BEFORE parsing YAML - // Otherwise parsing will fail on the placeholder - yamlContent = yamlContent.replaceAll('_bmad', this.bmadFolderName); - - try { - // First check if web_bundle exists by parsing - const workflowConfig = yaml.parse(yamlContent); - - if (workflowConfig.web_bundle === undefined) { - // No web_bundle section, just write (placeholders already replaced above) - await fs.writeFile(targetFile, yamlContent, 'utf8'); - return; - } - - // Find the line that starts web_bundle - const lines = yamlContent.split('\n'); - let startIdx = -1; - let endIdx = -1; - let baseIndent = 0; - - // Find the start of web_bundle section - for (const [i, line] of lines.entries()) { - const match = line.match(/^(\s*)web_bundle:/); - if (match) { - startIdx = i; - baseIndent = match[1].length; - break; - } - } - - if (startIdx === -1) { - // web_bundle not found in text (shouldn't happen), copy as-is - await fs.writeFile(targetFile, yamlContent, 'utf8'); - return; - } - - // Find the end of web_bundle section - // It ends when we find a line with same or less indentation that's not empty/comment - endIdx = startIdx; - for (let i = startIdx + 1; i < lines.length; i++) { - const line = lines[i]; - - // Skip empty lines and comments - if (line.trim() === '' || line.trim().startsWith('#')) { - continue; - } - - // Check indentation - const indent = line.match(/^(\s*)/)[1].length; - if (indent <= baseIndent) { - // Found next section at same or lower indentation - endIdx = i - 1; - break; - } - } - - // If we didn't find an end, it goes to end of file - if (endIdx === startIdx) { - endIdx = lines.length - 1; - } - - // Remove the web_bundle section (including the line before if it's just a blank line) - const newLines = [...lines.slice(0, startIdx), ...lines.slice(endIdx + 1)]; - - // Clean up any double blank lines that might result - const strippedYaml = newLines.join('\n').replaceAll(/\n\n\n+/g, '\n\n'); - - // Placeholders already replaced at the beginning of this function - await fs.writeFile(targetFile, strippedYaml, 'utf8'); - } catch { - // If anything fails, just copy the file as-is - await prompts.log.warn(` Could not process ${path.basename(sourceFile)}, copying as-is`); - await fs.copy(sourceFile, targetFile, { overwrite: true }); - } - } - /** * Compile .agent.yaml files to .md format in modules * @param {string} sourcePath - Source module path @@ -1165,13 +1073,11 @@ class ModuleManager { await prompts.log.message(` Processing: ${agentFile}`); for (const item of workflowInstallItems) { - const sourceWorkflowPath = item.workflow; // Where to copy FROM + const sourceWorkflowPath = item.exec; // Where to copy FROM const installWorkflowPath = item['workflow-install']; // Where to copy TO // Parse SOURCE workflow path - // Handle both _bmad placeholder and hardcoded 'bmad' - // Example: {project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml - // Or: {project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml + // Example: {project-root}/_bmad/bmm/workflows/4-implementation/bmad-create-story/workflow.md const sourceMatch = sourceWorkflowPath.match(/\{project-root\}\/(?:_bmad)\/([^/]+)\/workflows\/(.+)/); if (!sourceMatch) { await prompts.log.warn(` Could not parse workflow path: ${sourceWorkflowPath}`); @@ -1181,9 +1087,8 @@ class ModuleManager { const [, sourceModule, sourceWorkflowSubPath] = sourceMatch; // Parse INSTALL workflow path - // Handle_bmad - // Example: {project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.yaml - const installMatch = installWorkflowPath.match(/\{project-root\}\/(_bmad)\/([^/]+)\/workflows\/(.+)/); + // Example: {project-root}/_bmad/bmgd/workflows/4-production/create-story/workflow.md + const installMatch = installWorkflowPath.match(/\{project-root\}\/(?:_bmad)\/([^/]+)\/workflows\/(.+)/); if (!installMatch) { await prompts.log.warn(` Could not parse workflow-install path: ${installWorkflowPath}`); continue; @@ -1192,9 +1097,9 @@ class ModuleManager { const installWorkflowSubPath = installMatch[2]; const sourceModulePath = getModulePath(sourceModule); - const actualSourceWorkflowPath = path.join(sourceModulePath, 'workflows', sourceWorkflowSubPath.replace(/\/workflow\.yaml$/, '')); + const actualSourceWorkflowPath = path.join(sourceModulePath, 'workflows', sourceWorkflowSubPath.replace(/\/workflow\.md$/, '')); - const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(/\/workflow\.yaml$/, '')); + const actualDestWorkflowPath = path.join(targetPath, 'workflows', installWorkflowSubPath.replace(/\/workflow\.md$/, '')); // Check if source workflow exists if (!(await fs.pathExists(actualSourceWorkflowPath))) { @@ -1204,18 +1109,12 @@ class ModuleManager { // Copy the entire workflow folder await prompts.log.message( - ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.yaml$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.yaml$/, '')}`, + ` Vendoring: ${sourceModule}/workflows/${sourceWorkflowSubPath.replace(/\/workflow\.md$/, '')} → ${moduleName}/workflows/${installWorkflowSubPath.replace(/\/workflow\.md$/, '')}`, ); await fs.ensureDir(path.dirname(actualDestWorkflowPath)); // Copy the workflow directory recursively with placeholder replacement await this.copyDirectoryWithPlaceholderReplacement(actualSourceWorkflowPath, actualDestWorkflowPath); - - // Update the workflow.yaml config_source reference - const workflowYamlPath = path.join(actualDestWorkflowPath, 'workflow.yaml'); - if (await fs.pathExists(workflowYamlPath)) { - await this.updateWorkflowConfigSource(workflowYamlPath, moduleName); - } } } @@ -1224,28 +1123,6 @@ class ModuleManager { } } - /** - * Update workflow.yaml config_source to point to new module - * @param {string} workflowYamlPath - Path to workflow.yaml file - * @param {string} newModuleName - New module name to reference - */ - async updateWorkflowConfigSource(workflowYamlPath, newModuleName) { - let yamlContent = await fs.readFile(workflowYamlPath, 'utf8'); - - // Replace config_source: "{project-root}/_bmad/OLD_MODULE/config.yaml" - // with config_source: "{project-root}/_bmad/NEW_MODULE/config.yaml" - // Note: At this point _bmad has already been replaced with actual folder name - const configSourcePattern = /config_source:\s*["']?\{project-root\}\/[^/]+\/[^/]+\/config\.yaml["']?/g; - const newConfigSource = `config_source: "{project-root}/${this.bmadFolderName}/${newModuleName}/config.yaml"`; - - const updatedYaml = yamlContent.replaceAll(configSourcePattern, newConfigSource); - - if (updatedYaml !== yamlContent) { - await fs.writeFile(workflowYamlPath, updatedYaml, 'utf8'); - await prompts.log.message(` Updated config_source to: ${this.bmadFolderName}/${newModuleName}/config.yaml`); - } - } - /** * Create directories declared in module.yaml's `directories` key * This replaces the security-risky module installer pattern with declarative config diff --git a/tools/cli/lib/agent-analyzer.js b/tools/cli/lib/agent-analyzer.js index ae834a098..a62bdd7cf 100644 --- a/tools/cli/lib/agent-analyzer.js +++ b/tools/cli/lib/agent-analyzer.js @@ -39,16 +39,10 @@ class AgentAnalyzer { if (Array.isArray(execArray)) { for (const exec of execArray) { if (exec.route) { - // Check if route is a workflow or exec - if (exec.route.endsWith('.yaml') || exec.route.endsWith('.yml')) { - profile.usedAttributes.add('workflow'); - } else { - profile.usedAttributes.add('exec'); - } + profile.usedAttributes.add('exec'); } - if (exec.workflow) profile.usedAttributes.add('workflow'); if (exec.action) profile.usedAttributes.add('action'); - if (exec.type && ['exec', 'action', 'workflow'].includes(exec.type)) { + if (exec.type && ['exec', 'action'].includes(exec.type)) { profile.usedAttributes.add(exec.type); } } @@ -57,12 +51,6 @@ class AgentAnalyzer { } } else { // Check for each possible attribute in legacy items - if (item.workflow) { - profile.usedAttributes.add('workflow'); - } - if (item['validate-workflow']) { - profile.usedAttributes.add('validate-workflow'); - } if (item.exec) { profile.usedAttributes.add('exec'); } diff --git a/tools/cli/lib/agent/compiler.js b/tools/cli/lib/agent/compiler.js index f9f71baab..a557a69af 100644 --- a/tools/cli/lib/agent/compiler.js +++ b/tools/cli/lib/agent/compiler.js @@ -147,7 +147,6 @@ function buildMenuXml(menuItems) { const attrs = [`cmd="${trigger}"`]; // Add handler attributes - if (item.workflow) attrs.push(`workflow="${item.workflow}"`); if (item.exec) attrs.push(`exec="${item.exec}"`); if (item.tmpl) attrs.push(`tmpl="${item.tmpl}"`); if (item.data) attrs.push(`data="${item.data}"`); @@ -158,7 +157,7 @@ function buildMenuXml(menuItems) { } } - xml += ` [PM] Start Party Mode\n`; + xml += ` [PM] Start Party Mode\n`; xml += ` [DA] Dismiss Agent\n`; xml += ' \n'; @@ -187,8 +186,6 @@ function buildNestedHandlers(triggers) { // Add handler attributes based on exec data if (execData.route) attrs.push(`exec="${execData.route}"`); - if (execData.workflow) attrs.push(`workflow="${execData.workflow}"`); - if (execData['validate-workflow']) attrs.push(`validate-workflow="${execData['validate-workflow']}"`); if (execData.action) attrs.push(`action="${execData.action}"`); if (execData.data) attrs.push(`data="${execData.data}"`); if (execData.tmpl) attrs.push(`tmpl="${execData.tmpl}"`); @@ -212,7 +209,6 @@ function processExecArray(execArray) { const result = { description: '', route: null, - workflow: null, data: null, action: null, type: null, @@ -229,12 +225,7 @@ function processExecArray(execArray) { } if (exec.route) { - // Determine if it's a workflow or exec based on file extension or context - if (exec.route.endsWith('.yaml') || exec.route.endsWith('.yml')) { - result.workflow = exec.route; - } else { - result.route = exec.route; - } + result.route = exec.route; } if (exec.data !== null && exec.data !== undefined) { diff --git a/tools/cli/lib/yaml-xml-builder.js b/tools/cli/lib/yaml-xml-builder.js index ac140814f..f4f8e2f5a 100644 --- a/tools/cli/lib/yaml-xml-builder.js +++ b/tools/cli/lib/yaml-xml-builder.js @@ -367,15 +367,6 @@ class YamlXmlBuilder { const attrs = [`cmd="${trigger}"`]; // Add handler attributes - // If workflow-install exists, use its value for workflow attribute (vendoring) - // workflow-install is build-time metadata - tells installer where to copy workflows - // The final XML should only have workflow pointing to the install location - if (item['workflow-install']) { - attrs.push(`workflow="${item['workflow-install']}"`); - } else if (item.workflow) { - attrs.push(`workflow="${item.workflow}"`); - } - if (item['validate-workflow']) attrs.push(`validate-workflow="${item['validate-workflow']}"`); if (item.exec) attrs.push(`exec="${item.exec}"`); if (item.tmpl) attrs.push(`tmpl="${item.tmpl}"`); @@ -417,8 +408,6 @@ class YamlXmlBuilder { // Add handler attributes based on exec data if (execData.route) attrs.push(`exec="${execData.route}"`); - if (execData.workflow) attrs.push(`workflow="${execData.workflow}"`); - if (execData['validate-workflow']) attrs.push(`validate-workflow="${execData['validate-workflow']}"`); if (execData.action) attrs.push(`action="${execData.action}"`); if (execData.data) attrs.push(`data="${execData.data}"`); if (execData.tmpl) attrs.push(`tmpl="${execData.tmpl}"`); @@ -442,7 +431,6 @@ class YamlXmlBuilder { const result = { description: '', route: null, - workflow: null, data: null, action: null, type: null, @@ -459,12 +447,7 @@ class YamlXmlBuilder { } if (exec.route) { - // Determine if it's a workflow or exec based on file extension or context - if (exec.route.endsWith('.yaml') || exec.route.endsWith('.yml')) { - result.workflow = exec.route; - } else { - result.route = exec.route; - } + result.route = exec.route; } if (exec.data !== null && exec.data !== undefined) { diff --git a/tools/docs/fix-refs.md b/tools/docs/fix-refs.md index df9835b43..fe7ef679f 100644 --- a/tools/docs/fix-refs.md +++ b/tools/docs/fix-refs.md @@ -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. diff --git a/tools/docs/native-skills-migration-checklist.md b/tools/docs/native-skills-migration-checklist.md new file mode 100644 index 000000000..2f0f31344 --- /dev/null +++ b/tools/docs/native-skills-migration-checklist.md @@ -0,0 +1,281 @@ +# Native Skills Migration Checklist + +Branch: `refactor/all-is-skills` + +Scope: migrate the BMAD-supported platforms that fully support the Agent Skills standard from legacy installer outputs to native skills output. + +Current branch status: + +- `Claude Code` has already been moved to `.claude/skills` +- `Codex CLI` has already been moved to `.agents/skills` + +This checklist now includes those completed platforms plus the remaining full-support platforms. + +## Claude Code + +Support assumption: full Agent Skills support. BMAD has already migrated from `.claude/commands` to `.claude/skills`. + +**Install:** `npm install -g @anthropic-ai/claude-code` or `brew install claude-code` + +- [x] Confirm current implementation still matches Claude Code skills expectations +- [x] Confirm legacy cleanup for `.claude/commands` +- [x] Test fresh install +- [x] Test reinstall/upgrade from legacy command output +- [x] Confirm ancestor conflict protection because Claude Code inherits skills from parent directories and `ancestor_conflict_check: true` is set in platform-codes.yaml +- [x] Implement/extend automated tests as needed + +## Codex CLI + +Support assumption: full Agent Skills support. BMAD has already migrated from `.codex/prompts` to `.agents/skills`. + +**Install:** `npm install -g @openai/codex` + +- [x] Confirm current implementation still matches Codex CLI skills expectations +- [x] Confirm legacy cleanup for project and global `.codex/prompts` +- [x] Test fresh install +- [x] Test reinstall/upgrade from legacy prompt output +- [x] Confirm ancestor conflict protection because Codex inherits parent-directory `.agents/skills` +- [x] Implement/extend automated tests as needed + +## Cursor + +Support assumption: full Agent Skills support. BMAD currently installs legacy command files to `.cursor/commands`; target should move to a native skills directory. + +- [x] Confirm current Cursor skills path and that BMAD should target `.cursor/skills` +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.cursor/commands` +- [x] Test fresh install +- [x] Test reinstall/upgrade from legacy command output +- [x] Confirm no ancestor conflict protection is needed because a child workspace surfaced child `.cursor/skills` entries but not a parent-only skill during manual verification +- [x] Implement/extend automated tests +- [x] Commit + +## Windsurf + +Support assumption: full Agent Skills support. Windsurf docs confirm workspace skills at `.windsurf/skills` and global skills at `~/.codeium/windsurf/skills`. BMAD has now migrated from `.windsurf/workflows` to `.windsurf/skills`. Manual verification also confirmed that Windsurf custom skills are triggered via `@skill-name`, not slash commands. + +- [x] Confirm Windsurf native skills directory as `.windsurf/skills` +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.windsurf/workflows` +- [x] Test fresh install +- [x] Test reinstall/upgrade from legacy workflow output +- [x] Confirm no ancestor conflict protection is needed because manual Windsurf verification showed child-local `@` skills loaded while a parent-only skill was not inherited +- [x] Implement/extend automated tests + +## Cline + +Support assumption: full Agent Skills support. Cline docs confirm workspace skills at `.cline/skills//SKILL.md` and global skills at `~/.cline/skills/`. BMAD has now migrated from `.clinerules/workflows` to `.cline/skills`. + +**Install:** VS Code extension `saoudrizwan.claude-dev` — search "Cline" in Extensions or `code --install-extension saoudrizwan.claude-dev` + +- [x] Confirm current Cline skills path is `.cline/skills/{skill-name}/SKILL.md` with YAML frontmatter (name + description) +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.clinerules/workflows` +- [x] Test fresh install — 43 skills installed to `.cline/skills/` +- [x] Test reinstall/upgrade from legacy workflow output +- [x] Confirm no ancestor conflict protection is needed because Cline only scans workspace-local `.cline/skills/` and global `~/.cline/skills/`, with no ancestor directory inheritance +- [x] Implement/extend automated tests — 9 assertions in test suite 18 +- [x] Commit + +## Google Antigravity + +Support assumption: full Agent Skills support. Antigravity docs confirm workspace skills at `.agent/skills//` and global skills at `~/.gemini/antigravity/skills//`. BMAD has now migrated from `.agent/workflows` to `.agent/skills`. + +- [x] Confirm Antigravity native skills path and project/global precedence +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.agent/workflows` +- [x] Test fresh install +- [x] Test reinstall/upgrade from legacy workflow output +- [x] Confirm no ancestor conflict protection is needed because manual Antigravity verification in `/tmp/antigravity-ancestor-repro/parent/child` showed only the child-local `child-only` skill, with no inherited parent `.agent/skills` entry +- [x] Implement/extend automated tests + +## Auggie + +Support assumption: full Agent Skills support. BMAD currently installs commands to `.augment/commands`; target should move to `.augment/skills`. + +- [x] Confirm Auggie native skills path and compatibility loading from `.claude/skills` and `.agents/skills` via Augment docs plus local `auggie --print` repros +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.augment/commands` +- [x] Test fresh install +- [x] Test reinstall/upgrade from legacy command output +- [x] Confirm no ancestor conflict protection is needed because local `auggie --workspace-root` repro showed child-local `.augment/skills` loading `child-only` but not parent `parent-only` +- [x] Implement/extend automated tests +- [x] Commit + +## CodeBuddy + +Support assumption: full Agent Skills support. CodeBuddy docs confirm workspace skills at `.codebuddy/skills//SKILL.md` and global skills at `~/.codebuddy/commands/`. BMAD has now migrated from `.codebuddy/commands` to `.codebuddy/skills`. + +**Install:** Download [Tencent CodeBuddy IDE](https://codebuddyide.net/) or install as VS Code extension `CodebuddyAI.codebuddy-ai` + +- [x] Confirm CodeBuddy native skills path is `.codebuddy/skills/{skill-name}/SKILL.md` with YAML frontmatter (name + description) — per docs, not IDE-verified +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.codebuddy/commands` +- [x] Test fresh install — 43 skills installed to `.codebuddy/skills/` (installer output only) +- [x] Test reinstall/upgrade from legacy command output +- [ ] **NEEDS MANUAL IDE VERIFICATION** — requires Tencent Cloud account; confirm skills appear in UI and test ancestor inheritance +- [x] Implement/extend automated tests — 9 assertions in test suite 19 +- [x] Commit + +## Crush + +Support assumption: full Agent Skills support. Crush scans project-local `.crush/skills/` exclusively ([GitHub issue #2072](https://github.com/charmbracelet/crush/issues/2072) confirms this and requests adding `~/.agents/skills/`). BMAD has now migrated from `.crush/commands` to `.crush/skills`. + +**Install:** `brew install charmbracelet/tap/crush` (macOS/Linux) or `winget install charmbracelet.crush` (Windows) + +- [x] Confirm Crush project-local skills path is `.crush/skills/{skill-name}/SKILL.md` — per GitHub issue #2072 confirming `.crush/skills/` is the only scan path +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.crush/commands` +- [x] Test fresh install — 43 skills installed to `.crush/skills/` +- [x] Test reinstall/upgrade from legacy command output +- [x] Confirm no ancestor conflict protection is needed because Crush only scans project-local `.crush/skills/`, no ancestor inheritance +- [x] Manual CLI verification — `crush run` lists all 10 skills and successfully triggers bmad-help +- [x] Implement/extend automated tests — 9 assertions in test suite 20 +- [x] Commit + +## Kiro + +Support assumption: full Agent Skills support. Kiro docs confirm project skills at `.kiro/skills//SKILL.md` and describe steering as a separate rules mechanism, not a required compatibility layer. BMAD has now migrated from `.kiro/steering` to `.kiro/skills`. Manual app verification also confirmed that Kiro can surface skills in Slash when the relevant UI setting is enabled, and that it does not inherit ancestor `.kiro/skills` directories. + +- [x] Confirm Kiro skills path and verify BMAD should stop writing steering artifacts for this migration +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.kiro/steering` +- [x] Test fresh install +- [x] Test reinstall/upgrade from legacy steering output +- [x] Confirm no ancestor conflict protection is needed because manual Kiro verification showed Slash-visible skills from the current workspace only, with no ancestor `.kiro/skills` inheritance +- [x] Implement/extend automated tests + +## OpenCode + +Support assumption: full Agent Skills support. BMAD currently splits output between `.opencode/agents` and `.opencode/commands`; target should consolidate to `.opencode/skills`. + +- [x] Confirm OpenCode native skills path and compatibility loading from `.claude/skills` and `.agents/skills` in OpenCode docs and with local `opencode run` repros +- [x] Implement installer migration from multi-target legacy output to single native skills target +- [x] Add legacy cleanup for `.opencode/agents`, `.opencode/commands`, `.opencode/agent`, and `.opencode/command` +- [x] Test fresh install +- [x] Test reinstall/upgrade from split legacy output +- [x] Confirm ancestor conflict protection is required because local `opencode run` repros loaded both child-local `child-only` and ancestor `parent-only`, matching the docs that project-local skill discovery walks upward to the git worktree +- [x] Implement/extend automated tests +- [x] Commit + +## Roo Code + +Support assumption: full Agent Skills support. BMAD currently installs commands to `.roo/commands`; target should move to `.roo/skills` or the correct mode-aware skill directories. + +**Install:** VS Code extension `RooVeterinaryInc.roo-cline` — search "Roo Code" in Extensions or `code --install-extension RooVeterinaryInc.roo-cline` + +- [x] Confirm Roo native skills path is `.roo/skills/{skill-name}/SKILL.md` with `name` frontmatter matching directory exactly (lowercase, alphanumeric + hyphens only) +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.roo/commands` +- [x] Test fresh install — 43 skills installed, verified in Roo Code v3.51 +- [x] Test reinstall/upgrade from legacy command output +- [x] Confirm no ancestor conflict protection is needed because manual Roo Code v3.51 verification showed child-local `child-only` skill loaded while parent-only skill was not inherited +- [x] Implement/extend automated tests — 7 assertions in test suite 13 +- [x] Commit + +## Trae + +Support assumption: full Agent Skills support. [Trae docs](https://docs.trae.ai/ide/skills) confirm workspace skills at `.trae/skills//SKILL.md`. BMAD has now migrated from `.trae/rules` to `.trae/skills`. + +**Install:** Download [standalone IDE](https://www.trae.ai/download) (macOS/Windows/Linux) or `winget install -e --id ByteDance.Trae` + +- [x] Confirm Trae native skills path is `.trae/skills/{skill-name}/SKILL.md` — per official docs +- [x] Implement installer migration to native skills output +- [x] Add legacy cleanup for `.trae/rules` +- [x] Test fresh install — 43 skills installed to `.trae/skills/` +- [x] Test reinstall/upgrade from legacy rules output +- [x] Confirm no ancestor conflict protection is needed — Trae docs describe project-local `.trae/skills/` only +- [ ] **NEEDS MANUAL IDE VERIFICATION** — download Trae IDE and confirm skills appear in UI +- [x] Implement/extend automated tests — 9 assertions in test suite 21 +- [x] Commit + +## GitHub Copilot + +Support assumption: full Agent Skills support. BMAD currently uses a custom installer that generates `.github/agents`, `.github/prompts`, and `.github/copilot-instructions.md`; target should move to `.github/skills`. + +**Install:** VS Code extension `GitHub.copilot` — search "GitHub Copilot" in Extensions or `code --install-extension GitHub.copilot` + +- [x] Confirm GitHub Copilot native skills path is `.github/skills/{skill-name}/SKILL.md` — also reads `.claude/skills/` automatically +- [x] Design the migration away from the custom prompt/agent installer model — replaced 699-line custom installer with config-driven `skill_format: true` +- [x] Implement native skills output, ideally with shared config-driven code where practical +- [x] Add legacy cleanup for `.github/agents`, `.github/prompts`, and BMAD markers in `copilot-instructions.md` +- [x] Test fresh install — 43 skills installed to `.github/skills/` +- [x] Test reinstall/upgrade from legacy custom installer output — legacy dirs removed, BMAD markers stripped, user content preserved +- [x] Confirm no ancestor conflict protection is needed because manual Copilot verification showed child-local `child-only` skill loaded while parent-only skill was not inherited +- [x] Implement/extend automated tests — 11 assertions in test suite 17 including marker cleanup +- [x] Commit + +## KiloCoder — SUSPENDED + +**Status: Kilo Code does not support the Agent Skills standard.** The original migration assumed skills support because Kilo forked from Roo Code, but manual IDE verification confirmed Kilo has not merged that feature. BMAD support is paused until Kilo implements skills. + +**Install:** VS Code extension `kilocode.kilo-code` — search "Kilo Code" in Extensions or `code --install-extension kilocode.kilo-code` + +- [x] ~~Confirm KiloCoder native skills path~~ — **FALSE**: assumed from Roo Code fork, not verified. Manual testing showed no skills support in the IDE +- [x] Config and installer code retained in platform-codes.yaml with `suspended` flag — hidden from IDE picker, setup blocked with explanation +- [x] Installer fails early (before writing `_bmad/`) if Kilo is the only selected IDE, protecting existing installations +- [x] Legacy cleanup still runs for `.kilocode/workflows` and `.kilocodemodes` when users switch to a different IDE +- [x] Automated tests — 7 assertions in suite 22 (suspended config, hidden from picker, setup blocked, no files written, legacy cleanup) + +## Gemini CLI + +Support assumption: full Agent Skills support. Gemini CLI docs confirm workspace skills at `.gemini/skills/` and user skills at `~/.gemini/skills/`. Also discovers `.agents/skills/` as an alias. BMAD previously installed TOML files to `.gemini/commands`. + +**Install:** `npm install -g @google/gemini-cli` or see [geminicli.com](https://geminicli.com) + +- [x] Confirm Gemini CLI native skills path is `.gemini/skills/{skill-name}/SKILL.md` (per [geminicli.com/docs/cli/skills](https://geminicli.com/docs/cli/skills/)) +- [x] Implement native skills output — target_dir `.gemini/skills`, skill_format true, template_type default (replaces TOML templates) +- [x] Add legacy cleanup for `.gemini/commands` (via `legacy_targets`) +- [x] Test fresh install — skills written to `.gemini/skills/bmad-master/SKILL.md` with correct frontmatter +- [x] Test reinstall/upgrade from legacy TOML command output — legacy dir removed, skills installed +- [x] Confirm no ancestor conflict protection is needed — Gemini CLI uses workspace > user > extension precedence, no ancestor directory inheritance +- [x] Implement/extend automated tests — 9 assertions in test suite 23 (config, fresh install, legacy cleanup, reinstall) +- [x] Manual CLI verification — `gemini` lists all 10 skills and successfully triggers bmad-help +- [ ] Commit + +## iFlow + +Support assumption: full Agent Skills support. iFlow docs confirm workspace skills at `.iflow/skills/` and global skills at `~/.iflow/skills/`. BMAD previously installed flat files to `.iflow/commands`. + +- [x] Confirm iFlow native skills path is `.iflow/skills/{skill-name}/SKILL.md` +- [x] Implement native skills output — target_dir `.iflow/skills`, skill_format true, template_type default +- [x] Add legacy cleanup for `.iflow/commands` (via `legacy_targets`) +- [x] Test fresh install — skills written to `.iflow/skills/bmad-master/SKILL.md` +- [x] Test legacy cleanup — legacy commands dir removed +- [x] Implement/extend automated tests — 6 assertions in test suite 24 +- [ ] **NEEDS MANUAL IDE VERIFICATION** — install iFlow and confirm skills appear in UI and can be triggered +- [ ] Commit + +## QwenCoder + +Support assumption: full Agent Skills support. Qwen Code supports workspace skills at `.qwen/skills/` and global skills at `~/.qwen/skills/`. BMAD previously installed flat files to `.qwen/commands`. + +- [x] Confirm QwenCoder native skills path is `.qwen/skills/{skill-name}/SKILL.md` +- [x] Implement native skills output — target_dir `.qwen/skills`, skill_format true, template_type default +- [x] Add legacy cleanup for `.qwen/commands` (via `legacy_targets`) +- [x] Test fresh install — skills written to `.qwen/skills/bmad-master/SKILL.md` +- [x] Test legacy cleanup — legacy commands dir removed +- [x] Implement/extend automated tests — 6 assertions in test suite 25 +- [ ] **NEEDS MANUAL IDE VERIFICATION** — install QwenCoder and confirm skills appear in UI and can be triggered +- [ ] Commit + +## Rovo Dev + +Support assumption: full Agent Skills support. Rovo Dev now supports workspace skills at `.rovodev/skills/` and user skills at `~/.rovodev/skills/`. BMAD previously used a custom 257-line installer that wrote `.rovodev/workflows/` and `prompts.yml`. + +- [x] Confirm Rovo Dev native skills path is `.rovodev/skills/{skill-name}/SKILL.md` (per Atlassian blog) +- [x] Replace 257-line custom `rovodev.js` with config-driven entry in `platform-codes.yaml` +- [x] Add legacy cleanup for `.rovodev/workflows` (via `legacy_targets`) and BMAD entries in `prompts.yml` (via `cleanupRovoDevPrompts()` in `_config-driven.js`) +- [x] Test fresh install — skills written to `.rovodev/skills/bmad-master/SKILL.md` +- [x] Test legacy cleanup — legacy workflows dir removed, `prompts.yml` BMAD entries stripped while preserving user entries +- [x] Implement/extend automated tests — 8 assertions in test suite 26 +- [ ] **NEEDS MANUAL IDE VERIFICATION** — install Rovo Dev and confirm skills appear in UI and can be triggered +- [ ] Commit + +## Summary Gates + +- [x] All full-support BMAD platforms install `SKILL.md` directory-based output +- [x] No full-support platform still emits BMAD command/workflow/rule files as its primary install format +- [x] Legacy cleanup paths are defined for every migrated platform +- [x] Automated coverage exists for config-driven and custom-installer migrations +- [ ] Installer docs and migration notes updated after code changes land diff --git a/tools/platform-codes.yaml b/tools/platform-codes.yaml index 97846a9bd..7458143e7 100644 --- a/tools/platform-codes.yaml +++ b/tools/platform-codes.yaml @@ -50,7 +50,7 @@ platforms: description: "AI development tool" roo: - name: "Roo Cline" + name: "Roo Code" preferred: false category: ide description: "Enhanced Cline fork" diff --git a/tools/schema/agent.js b/tools/schema/agent.js index 93ced7c6e..dfec1322f 100644 --- a/tools/schema/agent.js +++ b/tools/schema/agent.js @@ -2,7 +2,7 @@ const assert = require('node:assert'); const { z } = require('zod'); -const COMMAND_TARGET_KEYS = ['workflow', 'validate-workflow', 'exec', 'action', 'tmpl', 'data']; +const COMMAND_TARGET_KEYS = ['validate-workflow', 'exec', 'action', 'tmpl', 'data']; const TRIGGER_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/; const COMPOUND_TRIGGER_PATTERN = /^([A-Z]{1,3}) or fuzzy match on ([a-z0-9]+(?:-[a-z0-9]+)*)$/; @@ -273,8 +273,6 @@ function buildMenuItemSchema() { .object({ trigger: createNonEmptyString('agent.menu[].trigger'), description: createNonEmptyString('agent.menu[].description'), - workflow: createNonEmptyString('agent.menu[].workflow').optional(), - 'workflow-install': createNonEmptyString('agent.menu[].workflow-install').optional(), 'validate-workflow': createNonEmptyString('agent.menu[].validate-workflow').optional(), exec: createNonEmptyString('agent.menu[].exec').optional(), action: createNonEmptyString('agent.menu[].action').optional(), diff --git a/tools/validate-doc-links.js b/tools/validate-doc-links.js index f8ce4c478..167268c90 100644 --- a/tools/validate-doc-links.js +++ b/tools/validate-doc-links.js @@ -51,7 +51,7 @@ function getMarkdownFiles(dir) { if (entry.isDirectory()) { walk(fullPath); - } else if (entry.isFile() && entry.name.endsWith('.md')) { + } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) { files.push(fullPath); } } @@ -120,10 +120,13 @@ function resolveLink(siteRelativePath, sourceFile) { if (!resolved.startsWith(DOCS_ROOT + path.sep) && resolved !== DOCS_ROOT) return null; if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved; if (fs.existsSync(resolved + '.md')) return resolved + '.md'; - // Directory: check for index.md + if (fs.existsSync(resolved + '.mdx')) return resolved + '.mdx'; + // Directory: check for index.md or index.mdx if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) { const indexFile = path.join(resolved, 'index.md'); + const indexMdxFile = path.join(resolved, 'index.mdx'); if (fs.existsSync(indexFile)) return indexFile; + if (fs.existsSync(indexMdxFile)) return indexMdxFile; } return null; } @@ -134,12 +137,17 @@ function resolveLink(siteRelativePath, sourceFile) { } if (checkPath.endsWith('/')) { - // Could be file.md or directory/index.md - const asFile = path.join(DOCS_ROOT, checkPath.slice(0, -1) + '.md'); + // Could be file.md, file.mdx, or directory/index.md/mdx + const baseName = checkPath.slice(0, -1); + const asMd = path.join(DOCS_ROOT, baseName + '.md'); + const asMdx = path.join(DOCS_ROOT, baseName + '.mdx'); const asIndex = path.join(DOCS_ROOT, checkPath, 'index.md'); + const asIndexMdx = path.join(DOCS_ROOT, checkPath, 'index.mdx'); - if (fs.existsSync(asFile)) return asFile; + if (fs.existsSync(asMd)) return asMd; + if (fs.existsSync(asMdx)) return asMdx; if (fs.existsSync(asIndex)) return asIndex; + if (fs.existsSync(asIndexMdx)) return asIndexMdx; return null; } @@ -151,10 +159,16 @@ function resolveLink(siteRelativePath, sourceFile) { const withMd = direct + '.md'; if (fs.existsSync(withMd)) return withMd; - // Directory without trailing slash: check for index.md + // Try with .mdx extension + const withMdx = direct + '.mdx'; + if (fs.existsSync(withMdx)) return withMdx; + + // Directory without trailing slash: check for index.md or index.mdx if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) { const indexFile = path.join(direct, 'index.md'); + const indexMdxFile = path.join(direct, 'index.mdx'); if (fs.existsSync(indexFile)) return indexFile; + if (fs.existsSync(indexMdxFile)) return indexMdxFile; } return null; diff --git a/tools/validate-file-refs.js b/tools/validate-file-refs.js index bf92f31f8..a3b91f2fb 100644 --- a/tools/validate-file-refs.js +++ b/tools/validate-file-refs.js @@ -324,6 +324,8 @@ function extractCsvRefs(filePath, content) { const raw = record['workflow-file']; if (!raw || raw.trim() === '') continue; if (!isResolvable(raw)) continue; + // skill: prefixed references are resolved by the IDE/CLI, not as file paths + if (raw.startsWith('skill:')) continue; // Line = header (1) + data row index (0-based) + 1 const line = i + 2; diff --git a/website/astro.config.mjs b/website/astro.config.mjs index d59de430a..1b987d7f1 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -36,11 +36,28 @@ export default defineConfig({ }, integrations: [ - sitemap(), + // Exclude custom 404 pages (all locales) from the sitemap — they are + // treated as normal content docs by Starlight even with disable404Route. + sitemap({ + filter: (page) => !/\/404(\/|$)/.test(new URL(page).pathname), + }), starlight({ title: 'BMAD Method', tagline: 'AI-driven agile development with specialized agents and workflows that scale from bug fixes to enterprise platforms.', + // i18n: English as root (no URL prefix), Chinese at /zh-cn/ + defaultLocale: 'root', + locales: { + root: { + label: 'English', + lang: 'en', + }, + 'zh-cn': { + label: '简体中文', + lang: 'zh-CN', + }, + }, + logo: { light: './public/img/bmad-light.png', dark: './public/img/bmad-dark.png', @@ -89,24 +106,29 @@ export default defineConfig({ // Sidebar configuration (Diataxis structure) sidebar: [ - { label: 'Welcome', slug: 'index' }, + { label: 'Welcome', translations: { 'zh-CN': '欢迎' }, slug: 'index' }, + { label: 'Roadmap', translations: { 'zh-CN': '路线图' }, slug: 'roadmap' }, { label: 'Tutorials', + translations: { 'zh-CN': '教程' }, collapsed: false, autogenerate: { directory: 'tutorials' }, }, { label: 'How-To Guides', + translations: { 'zh-CN': '操作指南' }, collapsed: true, autogenerate: { directory: 'how-to' }, }, { label: 'Explanation', + translations: { 'zh-CN': '概念说明' }, collapsed: true, autogenerate: { directory: 'explanation' }, }, { label: 'Reference', + translations: { 'zh-CN': '参考' }, collapsed: true, autogenerate: { directory: 'reference' }, }, diff --git a/website/public/diagrams/quick-dev-diagram.png b/website/public/diagrams/quick-dev-diagram.png new file mode 100644 index 000000000..9f813a4bf Binary files /dev/null and b/website/public/diagrams/quick-dev-diagram.png differ diff --git a/website/src/content/config.ts b/website/src/content/config.ts index 31b747625..02ea2ac07 100644 --- a/website/src/content/config.ts +++ b/website/src/content/config.ts @@ -1,6 +1,7 @@ import { defineCollection } from 'astro:content'; -import { docsSchema } from '@astrojs/starlight/schema'; +import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; export const collections = { docs: defineCollection({ schema: docsSchema() }), + i18n: defineCollection({ type: 'data', schema: i18nSchema() }), }; diff --git a/website/src/content/i18n/zh-CN.json b/website/src/content/i18n/zh-CN.json new file mode 100644 index 000000000..35c916a62 --- /dev/null +++ b/website/src/content/i18n/zh-CN.json @@ -0,0 +1,28 @@ +{ + "skipLink.label": "跳转到内容", + "search.label": "搜索", + "search.ctrlKey": "Ctrl", + "search.cancelLabel": "取消", + "themeSelect.accessibleLabel": "选择主题", + "themeSelect.dark": "深色", + "themeSelect.light": "浅色", + "themeSelect.auto": "自动", + "languageSelect.accessibleLabel": "选择语言", + "menuButton.accessibleLabel": "菜单", + "sidebarNav.accessibleLabel": "主导航", + "tableOfContents.onThisPage": "本页内容", + "tableOfContents.overview": "概述", + "i18n.untranslatedContent": "此内容尚未提供中文翻译。", + "page.editLink": "编辑页面", + "page.lastUpdated": "最后更新：", + "page.previousLink": "上一页", + "page.nextLink": "下一页", + "page.draft": "此内容为草稿，不会包含在正式版本中。", + "404.text": "页面未找到。请检查 URL 或尝试使用搜索。", + "aside.note": "注意", + "aside.tip": "提示", + "aside.caution": "警告", + "aside.danger": "危险", + "fileTree.directory": "目录", + "builtWithStarlight.label": "使用 Starlight 构建" +} diff --git a/website/src/rehype-markdown-links.js b/website/src/rehype-markdown-links.js index fbf6fb76e..c0428f261 100644 --- a/website/src/rehype-markdown-links.js +++ b/website/src/rehype-markdown-links.js @@ -101,11 +101,19 @@ export function findFirstDelimiter(str) { /** Walk up from a file path to find the content docs directory. */ export function detectContentDir(filePath) { const segments = filePath.split(path.sep); - // Look for src/content/docs in the path + // Look for src/content/docs in the path (standard Astro) for (let i = segments.length - 1; i >= 2; i--) { if (segments[i - 2] === 'src' && segments[i - 1] === 'content' && segments[i] === 'docs') { return segments.slice(0, i + 1).join(path.sep); } } + // Also check for a standalone 'docs' directory (BMAD project structure) + // Path format: .../bmm/docs/file.mdx or .../bmm/website/... + for (let i = segments.length - 1; i >= 0; i--) { + if (segments[i] === 'docs') { + // Found docs directory - use its parent as the content root + return segments.slice(0, i + 1).join(path.sep); + } + } return null; } diff --git a/website/src/styles/custom.css b/website/src/styles/custom.css index a8f66a2fd..3c1c6d742 100644 --- a/website/src/styles/custom.css +++ b/website/src/styles/custom.css @@ -507,3 +507,299 @@ blockquote { padding-right: 3rem; } } + +/* ============================================ + ROADMAP STYLES + ============================================ */ +.roadmap-container { + --color-planned: #6366f1; + --color-in-progress: #10b981; + --color-exploring: #f59e0b; + --color-bg-card: rgba(255, 255, 255, 0.03); + --color-border: rgba(255, 255, 255, 0.1); +} + +.dark .roadmap-container { + --color-bg-card: rgba(255, 255, 255, 0.03); + --color-border: rgba(255, 255, 255, 0.1); +} + +.light .roadmap-container { + --color-bg-card: rgba(0, 0, 0, 0.02); + --color-border: rgba(0, 0, 0, 0.1); +} + +.roadmap-legend { + display: flex; + gap: 1.5rem; + flex-wrap: wrap; + justify-content: center; + margin: 2rem 0; + padding: 1rem 1.5rem; + background: var(--color-bg-card); + border: 1px solid var(--color-border); + border-radius: 12px; +} + +.legend-item { + display: flex; + align-items: center; + gap: 0.5rem; + font-size: 0.9rem; +} + +.legend-dot { + width: 10px; + height: 10px; + border-radius: 50%; +} + +.legend-dot.planned { background: var(--color-planned); } +.legend-dot.in-progress { background: var(--color-in-progress); } +.legend-dot.exploring { background: var(--color-exploring); } + +.roadmap-timeline { + position: relative; + max-width: 1000px; + margin: 3rem auto; + padding: 0 1rem; +} + +.roadmap-timeline::before { + content: ''; + position: absolute; + left: 50%; + top: 0; + bottom: 0; + width: 3px; + background: linear-gradient(to bottom, var(--color-in-progress), var(--color-planned), var(--color-exploring)); + transform: translateX(-50%); + border-radius: 3px; +} + +.roadmap-item { + position: relative; + margin-bottom: 3rem; + display: grid; + grid-template-columns: 1fr auto 1fr; + gap: 2rem; + align-items: start; +} + +.roadmap-item:nth-child(odd) .roadmap-card { + grid-column: 1; +} + +.roadmap-item:nth-child(even) .roadmap-card { + grid-column: 3; +} + +.roadmap-marker { + grid-column: 2; + width: 20px; + height: 20px; + border-radius: 50%; + border: 4px solid var(--starlight-canvas-bg); + background: var(--color-in-progress); + position: relative; + z-index: 1; + box-shadow: 0 0 0 4px var(--color-border); +} + +.roadmap-item.in-progress .roadmap-marker { background: var(--color-in-progress); } +.roadmap-item.planned .roadmap-marker { background: var(--color-planned); } +.roadmap-item.exploring .roadmap-marker { background: var(--color-exploring); } + +.roadmap-item:nth-child(odd) .roadmap-content { + grid-column: 1; + text-align: right; +} + +.roadmap-item:nth-child(even) .roadmap-content { + grid-column: 3; + text-align: left; +} + +.roadmap-card { + background: var(--color-bg-card); + border: 1px solid var(--color-border); + border-radius: 16px; + padding: 1.5rem; + transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease; +} + +.roadmap-card:hover { + transform: translateY(-4px); + box-shadow: 0 12px 40px rgba(0, 0, 0, 0.15); + border-color: var(--color-in-progress); +} + +.roadmap-card.planned:hover { border-color: var(--color-planned); } +.roadmap-card.exploring:hover { border-color: var(--color-exploring); } + +.roadmap-header { + display: flex; + align-items: center; + gap: 0.75rem; + margin-bottom: 1rem; +} + +.roadmap-item:nth-child(odd) .roadmap-header { + flex-direction: row-reverse; +} + +.roadmap-badge { + padding: 0.25rem 0.75rem; + border-radius: 20px; + font-size: 0.75rem; + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.5px; +} + +.roadmap-badge.in-progress { + background: rgba(16, 185, 129, 0.15); + color: #10b981; +} + +.roadmap-badge.planned { + background: rgba(99, 102, 241, 0.15); + color: #6366f1; +} + +.roadmap-badge.exploring { + background: rgba(245, 158, 11, 0.15); + color: #f59e0b; +} + +.roadmap-title { + font-size: 1.25rem; + font-weight: 700; + margin: 0; +} + +.roadmap-description { + color: var(--slate-color-500); + margin-bottom: 1rem; + line-height: 1.6; +} + +.roadmap-features { + list-style: none; + padding: 0; + margin: 0; +} + +.roadmap-features li { + padding: 0.5rem 0; + padding-left: 1.5rem; + position: relative; + font-size: 0.9rem; + color: var(--slate-color-400); +} + +.roadmap-features li::before { + content: '→'; + position: absolute; + left: 0; + color: var(--color-in-progress); +} + +.roadmap-item.planned .roadmap-features li::before { color: var(--color-planned); } +.roadmap-item.exploring .roadmap-features li::before { color: var(--color-exploring); } + +.roadmap-section-title { + text-align: center; + font-size: 1.5rem; + font-weight: 700; + margin: 3rem 0 2rem; + padding: 1rem; + background: linear-gradient(135deg, var(--color-in-progress), var(--color-planned)); + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; + background-clip: text; +} + +.roadmap-future { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); + align-items: stretch; + gap: 1.5rem; + margin-top: 3rem; + padding: 2rem; + background: var(--color-bg-card); + border: 1px solid var(--color-border); + border-radius: 16px; +} + +.roadmap-future-card { + padding: 1.5rem; + border-radius: 12px; + background: linear-gradient(135deg, rgba(99, 102, 241, 0.1), rgba(245, 158, 11, 0.05)); + border: 1px solid var(--color-border); + transition: transform 0.2s ease; + display: flex; + flex-direction: column; + min-height: 140px; +} + +.roadmap-future-card h4 { + margin: 0 0 0.5rem 0; +} + +.roadmap-future-card p { + margin: 0; +} + +.roadmap-future-card:hover { + transform: scale(1.02); +} + +.roadmap-future-card h4 { + margin: 0 0 0.5rem; + font-size: 1.1rem; + color: var(--color-planned); +} + +.roadmap-future-card p { + margin: 0; + font-size: 0.9rem; + color: var(--slate-color-400); +} + +.roadmap-emoji { + font-size: 1.5rem; + margin-bottom: 0.5rem; + display: block; +} + +@media (max-width: 768px) { + .roadmap-timeline::before { + left: 20px; + } + + .roadmap-item { + grid-template-columns: auto 1fr; + gap: 1rem; + } + + .roadmap-item:nth-child(odd) .roadmap-card, + .roadmap-item:nth-child(even) .roadmap-card { + grid-column: 2; + } + + .roadmap-item:nth-child(odd) .roadmap-content, + .roadmap-item:nth-child(even) .roadmap-content { + grid-column: 2; + text-align: left; + } + + .roadmap-marker { + grid-column: 1; + grid-row: 1; + } + + .roadmap-item:nth-child(odd) .roadmap-header { + flex-direction: row; + } +}