Skip to content

fix(workflows): correct broken step refs in create-architecture #1734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bmadcode merged 1 commit into from
Feb 22, 2026
Merged

fix(workflows): correct broken step refs in create-architecture #1734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ First, check if the output document already exists:

If the document exists and has frontmatter with `stepsCompleted`:

- **STOP here** and load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-01b-continue.md` immediately
- **STOP here** and load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md` immediately
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# Check if step-01b-continue.md exists and search for architecture/steps/ references
find . -name "step-01b-continue.md" -type f 2>/dev/null

Repository: bmad-code-org/BMAD-METHOD

Length of output: 448

🏁 Script executed:

# Also check the structure of the workflow directory
find . -path "*3-solutioning/create-architecture/steps*" -type f 2>/dev/null | head -20

Repository: bmad-code-org/BMAD-METHOD

Length of output: 787

🏁 Script executed:

# Check the step-01-init.md file for the mentioned issues
cat -n "src/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md" 2>/dev/null | head -160

Repository: bmad-code-org/BMAD-METHOD

Length of output: 7795

Inconsistent path reference patterns: use variable placeholders instead of hardcoded paths

Lines 47 and 151 hardcode {project-root}/_bmad/bmm/workflows/... paths while line 98 correctly uses {installed_path}/ for the template reference. Unify these to use variable placeholders for maintainability. If {installed_path} is not appropriate for workflow steps, define a workflow steps variable and use it consistently.

Missing closing quote on user output message block

The output block starting at line 111 with "Welcome {{user_name}}! opens with a quote but has no closing quote before ## SUCCESS METRICS: at line 127. Either close the quote at line 125 or clarify the intended formatting.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md` at
line 47, Replace hardcoded
"{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/..."
references with a consistent variable placeholder (e.g., use the existing
{installed_path}/_bmad/bmm/workflows/... or define and use a new
{workflow_steps} placeholder) so all template/step path references in
step-01-init.md match the pattern used at the template reference (the one using
{installed_path}); also fix the unclosed user-output string that begins with
"Welcome {{user_name}}! by adding the missing closing quote before the "##
SUCCESS METRICS:" header so the quoted block is properly terminated.

- Do not proceed with any initialization tasks
- Let step-01b handle the continuation logic

Expand Down Expand Up @@ -148,6 +148,6 @@ Ready to begin architectural decision making. Do you have any other documents yo

## NEXT STEP:

After user selects [C] to continue, only after ensuring all the template output has been created, then load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-02-context.md` to analyze the project context and begin architectural decision making.
After user selects [C] to continue, only after ensuring all the template output has been created, then load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md` to analyze the project context and begin architectural decision making.
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Grammar: "architectural decision making" should be hyphenated

"architectural decision-making" is the correct form when used as a compound noun phrase.

✏️ Proposed fix 
-After user selects [C] to continue, only after ensuring all the template output has been created, then load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md` to analyze the project context and begin architectural decision making.
+After user selects [C] to continue, only after ensuring all the template output has been created, then load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md` to analyze the project context and begin architectural decision-making.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
After user selects [C] to continue, only after ensuring all the template output has been created, then load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md` to analyze the project context and begin architectural decision making.
After user selects [C] to continue, only after ensuring all the template output has been created, then load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md` to analyze the project context and begin architectural decision-making.
🧰 Tools
🪛 LanguageTool

[grammar] ~151-~151: Use a hyphen to join words.
Context: ...context and begin architectural decision making. Remember: Do NOT proceed to ste...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md` at
line 151, The phrase "architectural decision making" in the sentence that
instructs loading step-02-context.md should be corrected to the hyphenated
compound noun "architectural decision-making"; locate the sentence containing
"After user selects [C] to continue..." and replace "architectural decision
making" with "architectural decision-making" (the line referencing
step-02-context.md).


Remember: Do NOT proceed to step-02 until user explicitly selects [C] from the menu and setup is confirmed!
18 changes: 9 additions & 9 deletions src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ Show the user their current progress:

- Identify the next step based on `stepsCompleted`
- Load the appropriate step file to continue
- Example: If `stepsCompleted: [1, 2, 3]`, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md`
- Example: If `stepsCompleted: [1, 2, 3]`, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md`
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

{project-root} used in 9 places with no resolution guidance — claiming to close #1625 is premature

The linked issue #1625 specifically identifies that workflow variable resolution (including {project-root}) fails when the agent runs in a cold-start / fresh context. This PR performs a mechanical architecture/ → create-architecture/ path substitution, but all 9 occurrences of {project-root} on Lines 88, 106, and 165–171 remain unresolved stubs. The file contains no instruction for how the agent should resolve {project-root} before constructing these paths — which is precisely the gap that #1625 identifies.

The PR description says "Closes #1625", but the variable resolution problem is untouched. Either:

  1. The PR description should be corrected (this PR only fixes broken literal paths, not #1625), or
  2. Explicit instructions must be added here for resolving {project-root} in the absence of the workflow engine (e.g., reference config.yaml, derive from {installed_path}, etc.)

Also applies to: 106-106, 165-171

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md`
at line 88, The documentation still leaves the workflow variable
`{project-root}` unresolved in step-01b-continue.md (occurrences around the
Example line and lines 106, 165–171) so do not claim this PR "Closes `#1625`";
either remove that close statement from the PR description or add explicit
resolution guidance here: describe how the agent should compute `{project-root}`
in a cold-start (e.g., read `config.yaml` for a project_root field, fall back to
`{installed_path}` if present, or derive from the current working directory),
and update the Example and all nine occurrences to reference that resolution
approach (mention `{project-root}`, `config.yaml`, and `{installed_path}` so
reviewers can find and verify the changes).


#### If 'C' (Continue to next logical step):

Expand All @@ -103,7 +103,7 @@ Show the user their current progress:
#### If 'X' (Start over):

- Confirm: "This will delete all existing architectural decisions. Are you sure? (y/n)"
- If confirmed: Delete existing document and read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-01-init.md`
- If confirmed: Delete existing document and read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md`
- If not confirmed: Return to continuation menu
Comment on lines 103 to 107
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

"Delete existing document" specifies no file path or deletion mechanism

The handler for option [X] tells the agent to "Delete existing document" but provides no:

  • Concrete file path (the architecture output document's location is project-dependent and depends on resolving workflow variables)
  • Tool or command to perform the deletion
  • Error handling if the delete fails or the file is not found

An agent receiving this instruction has no deterministic way to act on it.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In
`@src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md`
around lines 103 - 107, The "Delete existing document" action in
step-01b-continue.md (option [X]) is underspecified; update the step to (1)
resolve the actual architecture output path using the workflow variables (e.g.,
the variable that points to the architecture output file in the workflow context
or {project-root}/_bmad/... if that variable is absent), (2) specify the exact
deletion mechanism (e.g., call the file-delete tool/command used by the agent
runtime or invoke fs.unlinkSync/fs.promises.unlink in the handler for option X),
(3) add explicit error handling and messaging for file-not-found and
delete-failure cases (log/return distinct errors and do not proceed to
step-01-init.md if deletion fails), and (4) keep the confirmation prompt and
only perform the delete when the user confirms; reference the option identifier
"option [X]" and the continuation file "step-01-init.md" so the handler
implementing the flow can locate and update the deletion logic.


### 4. Navigate to Selected Step
Expand Down Expand Up @@ -162,12 +162,12 @@ After user makes choice:
After user selects their continuation option, load the appropriate step file based on their choice. The step file will handle the detailed work from that point forward.

Valid step files to load:
- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-02-context.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-05-patterns.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-06-structure.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-07-validation.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-08-complete.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md`
- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md`

Remember: The goal is smooth, transparent resumption that respects the work already done while giving the user control over how to proceed.
4 changes: 2 additions & 2 deletions src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ Show the generated content and present choices:

- Append the final content to `{planning_artifacts}/architecture.md`
- Update frontmatter: `stepsCompleted: [1, 2]`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md`

## APPEND TO DOCUMENT:

Expand Down Expand Up @@ -219,6 +219,6 @@ When user selects 'C', append the content directly to the document using the str

## NEXT STEP:

After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md` to evaluate starter template options.
After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md` to evaluate starter template options.

Remember: Do NOT proceed to step-03 until user explicitly selects 'C' from the A/P/C menu and content is saved!
4 changes: 2 additions & 2 deletions src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,7 +294,7 @@ Show the generated content and present choices:

- Append the final content to `{planning_artifacts}/architecture.md`
- Update frontmatter: `stepsCompleted: [1, 2, 3]`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md`

## APPEND TO DOCUMENT:

Expand Down Expand Up @@ -324,6 +324,6 @@ When user selects 'C', append the content directly to the document using the str

## NEXT STEP:

After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md` to begin making specific architectural decisions.
After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md` to begin making specific architectural decisions.

Remember: Do NOT proceed to step-04 until user explicitly selects 'C' from the A/P/C menu and content is saved!
4 changes: 2 additions & 2 deletions src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@ Show the generated decisions content and present choices:

- Append the final content to `{planning_artifacts}/architecture.md`
- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-05-patterns.md`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md`

## APPEND TO DOCUMENT:

Expand Down Expand Up @@ -313,6 +313,6 @@ When user selects 'C', append the content directly to the document using the str

## NEXT STEP:

After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-05-patterns.md` to define implementation patterns that ensure consistency across AI agents.
After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md` to define implementation patterns that ensure consistency across AI agents.

Remember: Do NOT proceed to step-05 until user explicitly selects 'C' from the A/P/C menu and content is saved!
4 changes: 2 additions & 2 deletions src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,7 @@ Show the generated patterns content and present choices:

- Append the final content to `{planning_artifacts}/architecture.md`
- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-06-structure.md`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md`

## APPEND TO DOCUMENT:

Expand Down Expand Up @@ -354,6 +354,6 @@ When user selects 'C', append the content directly to the document using the str

## NEXT STEP:

After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-06-structure.md` to define the complete project structure.
After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md` to define the complete project structure.

Remember: Do NOT proceed to step-06 until user explicitly selects 'C' from the A/P/C menu and content is saved!
4 changes: 2 additions & 2 deletions src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -343,7 +343,7 @@ Show the generated project structure content and present choices:

- Append the final content to `{planning_artifacts}/architecture.md`
- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-07-validation.md`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md`

## APPEND TO DOCUMENT:

Expand Down Expand Up @@ -374,6 +374,6 @@ When user selects 'C', append the content directly to the document using the str

## NEXT STEP:

After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-07-validation.md` to validate architectural coherence and completeness.
After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md` to validate architectural coherence and completeness.

Remember: Do NOT proceed to step-07 until user explicitly selects 'C' from the A/P/C menu and content is saved!
4 changes: 2 additions & 2 deletions src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,7 @@ Show the validation results and present choices:

- Append the final content to `{planning_artifacts}/architecture.md`
- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6, 7]`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-08-complete.md`
- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md`

## APPEND TO DOCUMENT:

Expand Down Expand Up @@ -354,6 +354,6 @@ When user selects 'C', append the content directly to the document using the str

## NEXT STEP:

After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-08-complete.md` to complete the workflow and provide implementation guidance.
After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md` to complete the workflow and provide implementation guidance.

Remember: Do NOT proceed to step-08 until user explicitly selects 'C' from the A/P/C menu and content is saved!
2 changes: 1 addition & 1 deletion src/bmm/workflows/3-solutioning/create-architecture/workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,6 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:

## EXECUTION

Read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-01-init.md` to begin the workflow.
Read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md` to begin the workflow.

**Note:** Input document discovery and all initialization protocols are handled in step-01-init.md.