fix: replace broken party-mode file path refs with skill syntax#1999
Closed
fix: replace broken party-mode file path refs with skill syntax#1999
Conversation
The party-mode workflow moved from core/workflows/ to core/skills/ in PR #1959, breaking validate:refs. Convert all raw path references to skill:bmad-party-mode to match the established convention. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
🤖 Augment PR SummarySummary: Updates broken Party Mode workflow references after the Party Mode workflow was moved into the skills directory. Changes:
🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
📝 WalkthroughWalkthroughThis pull request converts Party Mode workflow references from file-based paths to skill-based identifiers across 10 workflow files. Each reference is updated from Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (6)
src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.md (1)
199-199:⚠️ Potential issue | 🟡 MinorMissing error handling for skill invocation.
Line 199 executes
{partyModeWorkflow}which now resolves toskill:bmad-party-mode, but there's no error handling if:
- The skill doesn't exist
- The skill resolution fails
- The skill execution encounters an error
- The skill doesn't return control properly
The workflow just says "Read fully and follow" but provides no fallback behavior. If the skill invocation fails, the user will be stuck with no clear recovery path.
This is a runtime robustness gap. The step should detect skill invocation failures and provide a graceful degradation path or clear error message to the user.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.md` at line 199, Wrap the invocation of {partyModeWorkflow} (which currently resolves to skill:bmad-party-mode) in robust error handling: detect and handle "skill not found", resolution failures, execution errors, or lack of return by adding a try/catch (or equivalent error callback) and a timeout/guard; on any failure log the error (with details), show a clear user-facing error message, and redisplay the menu as the fallback path (or route to a safe default workflow) so the user is never left stuck; ensure the handler distinguishes resolution vs runtime errors to give appropriate messages and cleans up any state before redisplaying the menu.src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md (1)
156-158:⚠️ Potential issue | 🟡 MinorNo validation that skill returns to menu.
Lines 156-158 show the menu handling logic where option P executes the party-mode skill and expects it to "return to this menu". However:
- How do you know the skill will return control properly?
- What if the skill halts, crashes, or redirects elsewhere?
- Is there a contract that guarantees skill:bmad-party-mode returns to the calling workflow?
The comment says "After other menu items execution, return to this menu with updated content" but there's no enforcement mechanism. If the skill doesn't honor this contract, the workflow breaks.
This is a control flow assumption with no verification. The skill invocation is a black box that might not behave as expected.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md` around lines 156 - 158, The menu handling assumes option "P" (party-mode) will return control, but there's no enforcement; wrap the party-mode invocation (skill:bmad-party-mode / {partyModeWorkflow}) in a guarded call that enforces a contract: call it inside a try/catch with a timeout and require an explicit success/return marker (e.g., returnToMenu or resolved content) before proceeding, validate the returned content (non-empty updated vision/frontmatter) and on failure log the error, persist current state to {outputFile} (including stepsCompleted) and fall back to re-rendering this menu or advancing to ./step-03-users.md as a safe default; ensure the code path that handles option P checks the skill's response and handles crashes/hangs by restoring the menu instead of assuming control is returned.src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md (1)
1-10:⚠️ Potential issue | 🟠 MajorConsolidate duplicated step files across workflows to reduce maintenance burden.
This step file (
create-prd/steps-v/step-v-01-discovery.md) is byte-for-byte identical tobmad-validate-prd/steps-v/step-v-01-discovery.md. The same duplication exists forstep-v-02-format-detection.md. The party-mode migration at line 8 required modifying both copies separately, confirming the maintenance risk.These two workflows are distinct (create-prd has 13 steps vs. validate-prd's 2 steps), yet they share identical opening steps with no documented shared-component mechanism (no symlinks or includes). Future changes to discovery or format-detection logic must be synchronized across both copies, risking inconsistency.
Recommend either:
- Extract the shared discovery/detection steps into a reusable component both workflows reference
- Use symlinks to a canonical step file location
- Document and enforce that these cross-workflow duplicates must be kept in sync
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md` around lines 1 - 10, The two workflow step files for 'step-v-01-discovery' and 'step-v-02-format-detection' are duplicated between the create-prd and bmad-validate-prd workflows; extract the shared step content into a single canonical component (e.g., a shared steps module) and update both workflows to reference that component (or replace the duplicates with symlinks to the canonical file) so changes (like the party-mode migration) are made once; ensure the workflows now import/include the shared step by name and remove the byte-for-byte duplicates to prevent future divergence.src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md (1)
160-160:⚠️ Potential issue | 🟠 MajorNo error handling when skill resolution fails.
Line 160 states "IF P: Read fully and follow: {partyModeWorkflow}" but completely omits error handling for when the skill reference can't be resolved. What should the agent do if:
- The skill doesn't exist?
- The skill manifest is malformed?
- The skill exists but its workflow.md is missing?
- There's a circular dependency in skill references?
The instruction "Read fully and follow" assumes infallibility. Production workflows need graceful degradation.
Add error handling guidance
#### Menu Handling Logic: - IF A: Read fully and follow: {advancedElicitationTask} with current user content to dive deeper into personas and journeys - ON ERROR: Display "Advanced Elicitation skill unavailable. Proceeding with manual elaboration." and return to menu - IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate user understanding - ON ERROR: Display "Party Mode skill unavailable. Proceeding with single-perspective validation." and return to menu - IF C: Save content to {outputFile}, update frontmatter with stepsCompleted: [1, 2, 3], then read fully and follow: ./step-04-metrics.md🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md` at line 160, The "Read fully and follow: {partyModeWorkflow}" step assumes the referenced skill always resolves; add explicit error handling for skill resolution failures by wrapping the invocation of {partyModeWorkflow} (and other skills like {advancedElicitationTask}) with checks that handle: non-existent skill, malformed manifest, missing workflow.md, and circular references; on failure log a clear user-facing message (e.g., "Party Mode skill unavailable. Proceeding with single-perspective validation."), return to the menu or fallback path, and mark the step as skipped/failed in frontmatter (e.g., stepsCompleted or errors list) so the workflow can continue gracefully instead of breaking.src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md (1)
163-163:⚠️ Potential issue | 🟠 MajorMissing guidance on what happens if Party Mode fails mid-execution.
Line 163 says "Read fully and follow: {partyModeWorkflow}" but doesn't specify:
- What happens if the user aborts Party Mode before completion?
- Should the agent return to this menu, or proceed to the next step?
- Is the user's work saved if Party Mode crashes?
- Can the user resume from where Party Mode left off?
These edge cases will occur in production (user hits Ctrl+C, network timeout, LLM rate limit, etc.) and need handling logic.
Add recovery guidance:
- IF P: Read fully and follow: {partyModeWorkflow} to bring different perspectives to validate comprehensive metrics - ON COMPLETION: Return to this menu with Party Mode insights integrated - ON ABORT: Return to this menu with pre-Party-Mode state preserved - ON ERROR: Display error details and return to this menu🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md` at line 163, Update the {partyModeWorkflow} entry in step-04-metrics (the "IF P: Read fully and follow: {partyModeWorkflow}" line) to add explicit recovery/resume guidance: specify ON COMPLETION should return to this menu with Party Mode insights integrated, ON ABORT should return to this menu with the pre-Party-Mode state preserved and any partial work saved for resumption, and ON ERROR should surface error details to the user and return to this menu with safe rollback; ensure the wording mentions whether users can resume from the last checkpoint and that state-saving is performed before launching {partyModeWorkflow}.src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md (1)
207-224:⚠️ Potential issue | 🟡 MinorMenu options lack Party Mode validation choice despite frontmatter declaration.
The frontmatter declares
partyModeWorkflow(line 9), suggesting this step intended to offer collaborative validation via Party Mode, but the menu at lines 207-224 only offers:
- [C] Convert to BMAD Format
- [E] Edit As-Is
- Exit
No [P] option exists. This is inconsistent with step-03-users.md and step-04-metrics.md from the same PR, which both offer [A]/[P]/[C] menus. Either:
- This step legitimately doesn't need Party Mode (then remove the frontmatter variable)
- The menu is incomplete (then add the [P] option)
The current state is a half-implemented feature.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md` around lines 207 - 224, The menu in step-e-01-discovery.md is missing the Party Mode choice declared by the frontmatter variable partyModeWorkflow; add a [P] Party Mode option to the listed menu options and the Menu Handling Logic (e.g., display "[P] Party Mode — Collaborate/validate in Party Mode", ALWAYS halt and wait for input on P, and implement branch "IF P: route to the Party Mode validation flow" analogous to the implementations in step-03-users.md and step-04-metrics.md (or point to the appropriate altStepFile/party validation step), so the menu and handling logic consistently support partyModeWorkflow instead of leaving it half-implemented.
🧹 Nitpick comments (10)
src/core/tasks/bmad-create-prd/steps-c/step-05-domain.md (1)
143-148: Inconsistent menu option descriptions.The menu text says
[P] Party Modebut the execution logic saysRead fully and follow: skill:bmad-party-mode. This creates ambiguity:
- What does "Party Mode" actually mean to the user? No description provided.
- The skill name "bmad-party-mode" doesn't explain what the skill does or why you'd select it.
- Unlike option
[A] Advanced Elicitationwhich has a clear purpose, option P is cryptic.Without context, users won't know when to choose Party Mode vs Advanced Elicitation vs Continue.
Improve menu clarity
-Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue - Save and Proceed to Innovation (Step 6 of 13)" +Display: "**Select:** [A] Advanced Elicitation [P] Party Mode (Multi-agent Discussion) [C] Continue - Save and Proceed to Innovation (Step 6 of 13)"Or add a brief explanation in the menu handling logic section.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/core/tasks/bmad-create-prd/steps-c/step-05-domain.md` around lines 143 - 148, The menu handling logic is ambiguous for option P; update the menu and handling text to clearly describe what "[P] Party Mode" does and why/when to choose it, and align the label with the referenced skill name `bmad-party-mode`; specifically, add a one-line description for "Party Mode" in the Menu Handling Logic (e.g., purpose and expected behavior), ensure the entry that currently reads "Read fully and follow: skill:bmad-party-mode" references the same user-facing label "[P] Party Mode", and keep the other options (`bmad-advanced-elicitation`, saving to {outputFile} and transitioning to ./step-06-innovation.md) unchanged so users can distinguish when to pick Party Mode versus Advanced Elicitation or Continue.src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/workflow.md (1)
35-38: Missing documentation for Related Workflows.The "Related Workflows" section declares three references (quick_spec_workflow, party_mode_exec, advanced_elicitation) but provides no explanation of:
- When to use each related workflow
- What each workflow does
- How they're invoked from this workflow
- Why they're declared here if not used in the initialization section
These references appear to be used somewhere in the step files, but there's no traceability. If a developer wants to understand the party-mode dependency, where do they look?
Add inline comments or a documentation section explaining the purpose and usage of each related workflow reference. This would improve maintainability.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/workflow.md` around lines 35 - 38, Add a short "Related Workflows" subsection in workflow.md that documents each referenced symbol—quick_spec_workflow, party_mode_exec, and advanced_elicitation—stating (1) a one-line description of what each workflow does, (2) when to use it or the triggering conditions, (3) how it is invoked from this workflow (e.g., which step files call skill:bmad-party-mode or skill:bmad-advanced-elicitation), and (4) why the reference is declared here (e.g., dependency for X step or optional extension), and add inline comments next to each bullet pointing to the exact step file or step name that invokes it for traceability so a developer can find where party-mode is used.src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.md (1)
8-8: Undocumented variable naming convention.This file declares
partyModeWorkflow: 'skill:bmad-party-mode'while other files in this PR useparty_mode_execfor the same skill reference (see bmad-quick-dev/workflow.md line 37 and bmad-quick-spec/workflow.md line 6).This naming inconsistency suggests:
- No systematic naming convention across the codebase
- Copy-paste programming without considering project-wide patterns
- Future maintainability issues when searching for party-mode usage
Establish a consistent naming convention:
- Either use
partyModeWorkfloweverywhere- Or use
party_mode_execeverywhere- Document the choice in a coding standard
The current mix is sloppy and will confuse future developers.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.md` at line 8, This file uses partyModeWorkflow while other files use party_mode_exec; standardize to party_mode_exec: replace the key partyModeWorkflow with party_mode_exec in this file (keeping the value 'skill:bmad-party-mode'), search the repo for any occurrences of partyModeWorkflow and rename them to party_mode_exec, update any docs or workflow references that describe the naming convention (e.g., the coding standard or workflow.md) to state that the canonical symbol is party_mode_exec, and run any tests/CI to ensure no references were missed.src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md (3)
1-8: Frontmatter comment says "Task References" but references both tasks and workflows.Line 5 says
# Task Referencesbut line 7 declares a variable namedpartyModeWorkflow(emphasis on "Workflow"). This terminology mismatch mirrors the issue in step-03-users.md.Are tasks and workflows the same thing? Different things? The comment should match what's actually declared.
Align comment to match declarations
Option 1 - Generic term:
# Skill References advancedElicitationTask: 'skill:bmad-advanced-elicitation' partyModeWorkflow: 'skill:bmad-party-mode'Option 2 - Separate by type if there's a semantic difference:
# Task References (single-purpose skills) advancedElicitationTask: 'skill:bmad-advanced-elicitation' # Workflow References (multi-step skills) partyModeWorkflow: 'skill:bmad-party-mode'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md` around lines 1 - 8, The frontmatter header "Task References" is misleading because it declares both advancedElicitationTask and partyModeWorkflow; update the comment to accurately describe the entries—either change the header to a generic term like "Skill References" or split into two headers ("Task References" and "Workflow References") so advancedElicitationTask and partyModeWorkflow are clearly categorized; ensure the chosen phrasing is applied to the frontmatter block containing those symbols.
160-164: Duplicate code across step files creates maintenance burden.Lines 160-164 duplicate the exact same menu handling logic from step-03-users.md:
- Same menu options ([A] Advanced Elicitation [P] Party Mode [C] Continue)
- Same variable references
- Same "Read fully and follow" pattern
- Same lack of error handling
If the menu handling needs to change (e.g., add error handling, add new option, change wording), you must update multiple step files in lockstep. This violates DRY and increases bug risk.
Consider extracting common menu logic into a reusable component:
# Shared menu template reference commonMenuHandler: 'skill:bmad-common-menu-handler' menuOptions: ['advanced-elicitation', 'party-mode', 'continue']Or document that this duplication is intentional per the "Micro-file Design" pattern mentioned in learnings, but add a comment explaining why each step must be self-contained rather than sharing menu logic.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md` around lines 160 - 164, Extract the duplicated menu handling logic (the IF A/P/C blocks referencing {advancedElicitationTask}, {partyModeWorkflow}, and {outputFile}) into a shared handler and replace the in-file copies in step-04-metrics.md and step-03-users.md with a single call to that handler (e.g., reference a new reusable component like skill:bmad-common-menu-handler or commonMenuHandler), or if duplication is intentional, add a clear comment in each step file explaining the micro-file design decision and why the menu must remain self-contained; ensure the shared handler supports the same menuOptions (advanced-elicitation, party-mode, continue), propagates stepsCompleted updates, and includes basic error handling for invalid choices.
158-164: Menu assumes synchronous execution but provides no timeout or cancellation mechanism.The menu handling logic says "ALWAYS halt and wait for user input" (line 169) but doesn't specify:
- Maximum wait time before timeout
- How to cancel a long-running skill invocation
- Whether the user can switch between menu options mid-execution
- What happens if the LLM session expires while waiting
This creates an unbounded wait state with no escape hatch.
Add timeout and cancellation guidance:
#### EXECUTION RULES: - ALWAYS halt and wait for user input after presenting menu (max wait: session timeout) - User can type 'cancel' or 'back' at any time to abort current operation - ONLY proceed to next step when user selects 'C' - Long-running operations (A, P) should show progress indicators - After other menu items execution, return to this menu with updated content🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md` around lines 158 - 164, The menu handling logic for options A/P/C (the block referencing advancedElicitationTask, partyModeWorkflow and saving to outputFile then ./step-05-scope.md) must be updated to enforce execution rules: implement a maximum wait/timeout for user input (session timeout), accept 'cancel' and 'back' commands to abort or return from long-running tasks, ensure only selecting 'C' advances to saving and invoking step-05-scope.md, require long-running handlers (advancedElicitationTask and partyModeWorkflow) to provide progress indicators and support cancellation, and ensure those handlers return control to this menu with updated content when finished or cancelled.src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md (3)
159-160: Missing validation that menu options A and P are actually executable.The menu presents options A (Advanced Elicitation) and P (Party Mode) but never validates that these skills are available before displaying the menu. If a skill is unavailable (missing manifest, wrong environment, permissions issue), the user sees a menu option that will fail when selected.
Better UX: check skill availability before constructing the menu, and omit unavailable options or mark them as disabled.
**Dynamic Menu Construction:** 1. Check if {advancedElicitationTask} is resolvable → include [A] option 2. Check if {partyModeWorkflow} is resolvable → include [P] option 3. [C] option always available 4. Present only available options to user🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md` around lines 159 - 160, The menu currently lists options A ({advancedElicitationTask}) and P ({partyModeWorkflow}) without verifying those skills exist or are callable; update the menu construction logic to probe each skill’s availability (e.g., via the existing skill resolver/isSkillAvailable or tryResolveSkill call) and only include A and/or P if their respective checks succeed—otherwise omit them or render them disabled with an explanatory label; ensure [C] remains always present and adjust the UI/message generation in the step that builds step-03-users.md accordingly so the displayed options match the actual resolvable skills.
1-8: Frontmatter lacks documentation of skill: syntax semantics.The frontmatter uses
skill:bmad-party-modesyntax but provides no documentation about:
- What the
skill:prefix means- How skill resolution works (global registry? relative path? search path?)
- What happens if the skill can't be resolved
- Whether skill names are case-sensitive
- What the valid skill name format is (kebab-case only?)
This creates a maintenance burden where developers must reverse-engineer the resolution mechanism from other parts of the codebase.
Add a comment block explaining the skill reference syntax:
--- # File References outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md' # Task References # Skill references use 'skill:<name>' syntax and are resolved via the skill manifest registry # Skills must be registered in a bmad-skill-manifest.yaml file to be discoverable advancedElicitationTask: 'skill:bmad-advanced-elicitation' partyModeWorkflow: 'skill:bmad-party-mode' ---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md` around lines 1 - 8, Update the frontmatter in step-03-users.md to include a brief YAML comment block that documents the "skill:<name>" syntax and resolution semantics: state that the `skill:` prefix denotes a skill reference (e.g., values of advancedElicitationTask and partyModeWorkflow), how skills are resolved (looked up via the bmad-skill-manifest registry), what happens if unresolved (fail-fast or fallback behavior), case-sensitivity rules, valid name format (kebab-case convention), and where to register skills (bmad-skill-manifest.yaml); place this comment directly above or inside the existing frontmatter so anyone reading keys like advancedElicitationTask and partyModeWorkflow sees the rules.
160-160: Menu option invocation tightly couples to variable name, creating fragility.The menu says "[P] Party Mode" and the handler says "IF P: Read fully and follow: {partyModeWorkflow}". If the skill is renamed (e.g.,
bmad-party-modebecomesbmad-collaborative-validation), you must update:
- The skill reference value
- Potentially the variable name
- The menu option text
- The menu handler comment
This tight coupling makes refactoring error-prone. Consider whether the menu text should be derived from skill metadata instead of hardcoded.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md` at line 160, The menu option text "[P] Party Mode" and its handler comment "IF P: Read fully and follow: {partyModeWorkflow}" are tightly coupled to the variable/skill name (partyModeWorkflow / bmad-party-mode); change the design so the menu label is generated from the skill's metadata (e.g., skill.displayName or skill.metadata.name) and the handler references the skill by a stable identifier (e.g., skill.id) rather than the variable name; update the step to look up the skill record and render the menu label dynamically and invoke the workflow via its stable id (replace direct uses of partyModeWorkflow and hardcoded "[P] Party Mode" with metadata-driven values) so renaming the skill (bmad-party-mode → bmad-collaborative-validation) no longer requires editing the menu text, variable name, or handler comment.src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md (1)
6-9: Inconsistent reference syntax across different resource types with no explanation.Line 6 uses a relative file path (
'./step-e-01b-legacy-conversion.md'), while lines 8-9 use skill syntax ('skill:bmad-...'). The frontmatter doesn't explain:
- When to use file paths vs skill references
- Why altStepFile uses
./but tasks useskill:- Whether
./paths are resolved relative to this step file or the workflow root- What the scoping rules are for each reference type
This inconsistency forces developers to guess the right syntax for new references.
Add a comment explaining the reference type conventions:
--- name: 'step-e-01-discovery' description: 'Discovery & Understanding - Understand what user wants to edit and detect PRD format' # File references - use relative paths (./) for step files in same workflow altStepFile: './step-e-01b-legacy-conversion.md' prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md' # Skill references - use skill: prefix for reusable skills from the skill registry advancedElicitationTask: 'skill:bmad-advanced-elicitation' partyModeWorkflow: 'skill:bmad-party-mode' ---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md` around lines 6 - 9, Add a frontmatter comment block to step-e-01-discovery explaining reference conventions: state that altStepFile and other step-file entries use relative paths prefixed with ./ (resolved relative to this step file) and that prdPurpose can point to project-root absolute paths using {project-root}; state that reusable behaviors (advancedElicitationTask, partyModeWorkflow) use the skill: prefix to reference entries from the skill registry and clarify scoping rules (./ = current file directory, {project-root} = repo root, skill: = global skill registry) so future authors know when to use file paths vs skill references; place this explanatory comment above the existing keys (altStepFile, prdPurpose, advancedElicitationTask, partyModeWorkflow).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/bmm/workflows/bmad-generate-project-context/steps/step-02-generate.md`:
- Line 34: Update the inconsistent phrasing in the markdown so the party-mode
invocation matches the standardized skill format: replace the text "Execute
party-mode workflow with category rules context" (in the Handle Menu Selection /
PROTOCOL INTEGRATION area) with "Execute skill:bmad-party-mode with category
rules context" so it aligns with other lines that use "Execute
skill:bmad-advanced-elicitation" and the earlier "Execute skill:bmad-party-mode"
reference.
---
Outside diff comments:
In
`@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.md`:
- Around line 156-158: The menu handling assumes option "P" (party-mode) will
return control, but there's no enforcement; wrap the party-mode invocation
(skill:bmad-party-mode / {partyModeWorkflow}) in a guarded call that enforces a
contract: call it inside a try/catch with a timeout and require an explicit
success/return marker (e.g., returnToMenu or resolved content) before
proceeding, validate the returned content (non-empty updated vision/frontmatter)
and on failure log the error, persist current state to {outputFile} (including
stepsCompleted) and fall back to re-rendering this menu or advancing to
./step-03-users.md as a safe default; ensure the code path that handles option P
checks the skill's response and handles crashes/hangs by restoring the menu
instead of assuming control is returned.
In
`@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md`:
- Line 160: The "Read fully and follow: {partyModeWorkflow}" step assumes the
referenced skill always resolves; add explicit error handling for skill
resolution failures by wrapping the invocation of {partyModeWorkflow} (and other
skills like {advancedElicitationTask}) with checks that handle: non-existent
skill, malformed manifest, missing workflow.md, and circular references; on
failure log a clear user-facing message (e.g., "Party Mode skill unavailable.
Proceeding with single-perspective validation."), return to the menu or fallback
path, and mark the step as skipped/failed in frontmatter (e.g., stepsCompleted
or errors list) so the workflow can continue gracefully instead of breaking.
In
`@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md`:
- Line 163: Update the {partyModeWorkflow} entry in step-04-metrics (the "IF P:
Read fully and follow: {partyModeWorkflow}" line) to add explicit
recovery/resume guidance: specify ON COMPLETION should return to this menu with
Party Mode insights integrated, ON ABORT should return to this menu with the
pre-Party-Mode state preserved and any partial work saved for resumption, and ON
ERROR should surface error details to the user and return to this menu with safe
rollback; ensure the wording mentions whether users can resume from the last
checkpoint and that state-saving is performed before launching
{partyModeWorkflow}.
In
`@src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md`:
- Around line 207-224: The menu in step-e-01-discovery.md is missing the Party
Mode choice declared by the frontmatter variable partyModeWorkflow; add a [P]
Party Mode option to the listed menu options and the Menu Handling Logic (e.g.,
display "[P] Party Mode — Collaborate/validate in Party Mode", ALWAYS halt and
wait for input on P, and implement branch "IF P: route to the Party Mode
validation flow" analogous to the implementations in step-03-users.md and
step-04-metrics.md (or point to the appropriate altStepFile/party validation
step), so the menu and handling logic consistently support partyModeWorkflow
instead of leaving it half-implemented.
In
`@src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.md`:
- Line 199: Wrap the invocation of {partyModeWorkflow} (which currently resolves
to skill:bmad-party-mode) in robust error handling: detect and handle "skill not
found", resolution failures, execution errors, or lack of return by adding a
try/catch (or equivalent error callback) and a timeout/guard; on any failure log
the error (with details), show a clear user-facing error message, and redisplay
the menu as the fallback path (or route to a safe default workflow) so the user
is never left stuck; ensure the handler distinguishes resolution vs runtime
errors to give appropriate messages and cleans up any state before redisplaying
the menu.
In
`@src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md`:
- Around line 1-10: The two workflow step files for 'step-v-01-discovery' and
'step-v-02-format-detection' are duplicated between the create-prd and
bmad-validate-prd workflows; extract the shared step content into a single
canonical component (e.g., a shared steps module) and update both workflows to
reference that component (or replace the duplicates with symlinks to the
canonical file) so changes (like the party-mode migration) are made once; ensure
the workflows now import/include the shared step by name and remove the
byte-for-byte duplicates to prevent future divergence.
---
Nitpick comments:
In
`@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.md`:
- Around line 159-160: The menu currently lists options A
({advancedElicitationTask}) and P ({partyModeWorkflow}) without verifying those
skills exist or are callable; update the menu construction logic to probe each
skill’s availability (e.g., via the existing skill resolver/isSkillAvailable or
tryResolveSkill call) and only include A and/or P if their respective checks
succeed—otherwise omit them or render them disabled with an explanatory label;
ensure [C] remains always present and adjust the UI/message generation in the
step that builds step-03-users.md accordingly so the displayed options match the
actual resolvable skills.
- Around line 1-8: Update the frontmatter in step-03-users.md to include a brief
YAML comment block that documents the "skill:<name>" syntax and resolution
semantics: state that the `skill:` prefix denotes a skill reference (e.g.,
values of advancedElicitationTask and partyModeWorkflow), how skills are
resolved (looked up via the bmad-skill-manifest registry), what happens if
unresolved (fail-fast or fallback behavior), case-sensitivity rules, valid name
format (kebab-case convention), and where to register skills
(bmad-skill-manifest.yaml); place this comment directly above or inside the
existing frontmatter so anyone reading keys like advancedElicitationTask and
partyModeWorkflow sees the rules.
- Line 160: The menu option text "[P] Party Mode" and its handler comment "IF P:
Read fully and follow: {partyModeWorkflow}" are tightly coupled to the
variable/skill name (partyModeWorkflow / bmad-party-mode); change the design so
the menu label is generated from the skill's metadata (e.g., skill.displayName
or skill.metadata.name) and the handler references the skill by a stable
identifier (e.g., skill.id) rather than the variable name; update the step to
look up the skill record and render the menu label dynamically and invoke the
workflow via its stable id (replace direct uses of partyModeWorkflow and
hardcoded "[P] Party Mode" with metadata-driven values) so renaming the skill
(bmad-party-mode → bmad-collaborative-validation) no longer requires editing the
menu text, variable name, or handler comment.
In
`@src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.md`:
- Around line 1-8: The frontmatter header "Task References" is misleading
because it declares both advancedElicitationTask and partyModeWorkflow; update
the comment to accurately describe the entries—either change the header to a
generic term like "Skill References" or split into two headers ("Task
References" and "Workflow References") so advancedElicitationTask and
partyModeWorkflow are clearly categorized; ensure the chosen phrasing is applied
to the frontmatter block containing those symbols.
- Around line 160-164: Extract the duplicated menu handling logic (the IF A/P/C
blocks referencing {advancedElicitationTask}, {partyModeWorkflow}, and
{outputFile}) into a shared handler and replace the in-file copies in
step-04-metrics.md and step-03-users.md with a single call to that handler
(e.g., reference a new reusable component like skill:bmad-common-menu-handler or
commonMenuHandler), or if duplication is intentional, add a clear comment in
each step file explaining the micro-file design decision and why the menu must
remain self-contained; ensure the shared handler supports the same menuOptions
(advanced-elicitation, party-mode, continue), propagates stepsCompleted updates,
and includes basic error handling for invalid choices.
- Around line 158-164: The menu handling logic for options A/P/C (the block
referencing advancedElicitationTask, partyModeWorkflow and saving to outputFile
then ./step-05-scope.md) must be updated to enforce execution rules: implement a
maximum wait/timeout for user input (session timeout), accept 'cancel' and
'back' commands to abort or return from long-running tasks, ensure only
selecting 'C' advances to saving and invoking step-05-scope.md, require
long-running handlers (advancedElicitationTask and partyModeWorkflow) to provide
progress indicators and support cancellation, and ensure those handlers return
control to this menu with updated content when finished or cancelled.
In
`@src/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.md`:
- Around line 6-9: Add a frontmatter comment block to step-e-01-discovery
explaining reference conventions: state that altStepFile and other step-file
entries use relative paths prefixed with ./ (resolved relative to this step
file) and that prdPurpose can point to project-root absolute paths using
{project-root}; state that reusable behaviors (advancedElicitationTask,
partyModeWorkflow) use the skill: prefix to reference entries from the skill
registry and clarify scoping rules (./ = current file directory, {project-root}
= repo root, skill: = global skill registry) so future authors know when to use
file paths vs skill references; place this explanatory comment above the
existing keys (altStepFile, prdPurpose, advancedElicitationTask,
partyModeWorkflow).
In
`@src/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.md`:
- Line 8: This file uses partyModeWorkflow while other files use
party_mode_exec; standardize to party_mode_exec: replace the key
partyModeWorkflow with party_mode_exec in this file (keeping the value
'skill:bmad-party-mode'), search the repo for any occurrences of
partyModeWorkflow and rename them to party_mode_exec, update any docs or
workflow references that describe the naming convention (e.g., the coding
standard or workflow.md) to state that the canonical symbol is party_mode_exec,
and run any tests/CI to ensure no references were missed.
In `@src/bmm/workflows/bmad-quick-flow/bmad-quick-dev/workflow.md`:
- Around line 35-38: Add a short "Related Workflows" subsection in workflow.md
that documents each referenced symbol—quick_spec_workflow, party_mode_exec, and
advanced_elicitation—stating (1) a one-line description of what each workflow
does, (2) when to use it or the triggering conditions, (3) how it is invoked
from this workflow (e.g., which step files call skill:bmad-party-mode or
skill:bmad-advanced-elicitation), and (4) why the reference is declared here
(e.g., dependency for X step or optional extension), and add inline comments
next to each bullet pointing to the exact step file or step name that invokes it
for traceability so a developer can find where party-mode is used.
In `@src/core/tasks/bmad-create-prd/steps-c/step-05-domain.md`:
- Around line 143-148: The menu handling logic is ambiguous for option P; update
the menu and handling text to clearly describe what "[P] Party Mode" does and
why/when to choose it, and align the label with the referenced skill name
`bmad-party-mode`; specifically, add a one-line description for "Party Mode" in
the Menu Handling Logic (e.g., purpose and expected behavior), ensure the entry
that currently reads "Read fully and follow: skill:bmad-party-mode" references
the same user-facing label "[P] Party Mode", and keep the other options
(`bmad-advanced-elicitation`, saving to {outputFile} and transitioning to
./step-06-innovation.md) unchanged so users can distinguish when to pick Party
Mode versus Advanced Elicitation or Continue.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: bc463490-853c-4433-9b5e-9ed6861e24dc
📒 Files selected for processing (11)
src/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-02-vision.mdsrc/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-03-users.mdsrc/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-04-metrics.mdsrc/bmm/workflows/1-analysis/bmad-create-product-brief/steps/step-05-scope.mdsrc/bmm/workflows/2-plan-workflows/bmad-edit-prd/steps-e/step-e-01-discovery.mdsrc/bmm/workflows/2-plan-workflows/bmad-validate-prd/steps-v/step-v-01-discovery.mdsrc/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.mdsrc/bmm/workflows/bmad-generate-project-context/steps/step-02-generate.mdsrc/bmm/workflows/bmad-quick-flow/bmad-quick-dev/workflow.mdsrc/bmm/workflows/bmad-quick-flow/bmad-quick-spec/workflow.mdsrc/core/tasks/bmad-create-prd/steps-c/step-05-domain.md
|
|
||
| - When 'A' selected: Execute skill:bmad-advanced-elicitation | ||
| - When 'P' selected: Execute {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md | ||
| - When 'P' selected: Execute skill:bmad-party-mode |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify line 278 terminology
rg -n "party-mode workflow" src/bmm/workflows/bmad-generate-project-context/steps/step-02-generate.mdRepository: bmad-code-org/BMAD-METHOD
Length of output: 130
🏁 Script executed:
#!/bin/bash
# Get context around line 34
echo "=== Lines 30-40 (context around line 34) ==="
sed -n '30,40p' src/bmm/workflows/bmad-generate-project-context/steps/step-02-generate.md | cat -n
echo ""
echo "=== Lines 265-280 (context around line 270 and 279) ==="
sed -n '265,280p' src/bmm/workflows/bmad-generate-project-context/steps/step-02-generate.md | cat -nRepository: bmad-code-org/BMAD-METHOD
Length of output: 1279
Fix inconsistent skill reference terminology in party-mode instructions.
Line 34 uses Execute skill:bmad-party-mode, but line 279 uses the older Execute party-mode workflow terminology. Since line 270 already uses the standardized Execute skill:bmad-advanced-elicitation format, line 279 should be updated to match:
- Line 279: Change
Execute party-mode workflow with category rules contexttoExecute skill:bmad-party-mode with category rules context
This maintains consistent terminology across both the PROTOCOL INTEGRATION and Handle Menu Selection sections.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/bmm/workflows/bmad-generate-project-context/steps/step-02-generate.md` at
line 34, Update the inconsistent phrasing in the markdown so the party-mode
invocation matches the standardized skill format: replace the text "Execute
party-mode workflow with category rules context" (in the Handle Menu Selection /
PROTOCOL INTEGRATION area) with "Execute skill:bmad-party-mode with category
rules context" so it aligns with other lines that use "Execute
skill:bmad-advanced-elicitation" and the earlier "Execute skill:bmad-party-mode"
reference.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
core/workflows/tocore/skills/in PR prototype preview of new version of product brief skill #1959, breakingvalidate:refs{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.mdreferences withskill:bmad-party-modesyntaxskill:bmad-advanced-elicitationin the same filesTest plan
npm run validate:refs— 0 broken references🤖 Generated with Claude Code