fix(workflows): correct broken step refs in create-architecture#1734
fix(workflows): correct broken step refs in create-architecture#1734
Conversation
Update 9 files that referenced the old path bmm/workflows/3-solutioning/architecture/steps/ to the correct bmm/workflows/3-solutioning/create-architecture/steps/ after the directory was renamed. Fixes #1625 Co-authored-by: Junie <junie@jetbrains.com>
🤖 Augment PR SummarySummary: Fixes internal step-file references in the “Create Architecture” workflow after the folder rename from Changes:
Technical Notes: Aligns references with strict file-ref validation ( 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
📝 WalkthroughWalkthroughThis PR corrects hardcoded file path references across the create-architecture workflow steps, updating all internal navigation paths from Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (11)
src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md (1)
300-300:⚠️ Potential issue | 🟡 MinorMalformed template placeholder: space inside underscore-delimited variable name
{{how_the_project_is organized_for_development}}contains a literal space betweenisandorganized. All other placeholders in this file use consistent_separators. An agent performing a naive variable substitution would fail to match this placeholder.✏️ Proposed fix
-{{how_the_project_is organized_for_development}} +{{how_the_project_is_organized_for_development}}🤖 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-06-structure.md` at line 300, The template contains a malformed placeholder "{{how_the_project_is organized_for_development}}" (note the space between "is" and "organized"); replace it with the consistent underscore-delimited form "{{how_the_project_is_organized_for_development}}" so variable substitution will match—update the placeholder in step-06-structure.md (search for the exact string "{{how_the_project_is organized_for_development}}") and ensure it matches other placeholders' naming convention.src/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md (2)
111-126:⚠️ Potential issue | 🟡 MinorUnclosed user-output quote block: agent may treat SUCCESS METRICS as user-facing message
The quoted agent response opened on what resolves to line 111 (
"Welcome {{user_name}}!...) has no closing"before## SUCCESS METRICS:starts at line 128. An AI agent reading this file linearly could interpret the success metrics checklist as part of the message it is supposed to surface to the user.🐛 Proposed fix — close the quoted block before SUCCESS METRICS
[C] Continue to project context analysis +" ## SUCCESS METRICS:🤖 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` around lines 111 - 126, The quoted agent output starting with "Welcome {{user_name}}!..." in step-01-init.md is not closed, so add a closing double quote (") immediately before the "## SUCCESS METRICS:" heading to terminate the user-facing message; locate the open quote at the start of the welcome block and insert the closing quote right before the "## SUCCESS METRICS:" line to prevent the checklist from being parsed as part of the quoted response.
98-99:⚠️ Potential issue | 🟡 Minor
{installed_path}used correctly here but bypassed in the updated navigation linesLine 98 uses
{installed_path}as intended:Copy the template from `{installed_path}/architecture-decision-template.md`Yet lines 47 and 151 — the two lines changed in this PR — hardcode
{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/instead. The variable is in scope and demonstrably works in this same file; there is no reason not to use it for step navigation too.🤖 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` around lines 98 - 99, The navigation links in step-01-init.md were hardcoded to "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/" in the recent changes; update those navigation lines to use the existing {installed_path} variable instead (i.e., replace the hardcoded path with {installed_path}/... ), keeping the template copy line that already uses {installed_path} unchanged so all step navigation and template references consistently use {installed_path}.src/bmm/workflows/3-solutioning/create-architecture/workflow.md (2)
39-47: 🛠️ Refactor suggestion | 🟠 MajorRoot cause unresolved:
{installed_path}is defined but never used for step navigation
installed_pathis defined on line 39 precisely to abstract the workflow directory path. Yet line 47 (and everystep-XX.mdnavigation reference this PR touches) expands it back to the raw hardcoded string. This is why 24 references broke on the last rename — and will break again on the next one. The fix replaces the occurrences but doesn't eliminate the pattern.Line 40 demonstrates the intended usage works correctly (
template_path = {installed_path}/architecture-decision-template.md). The same convention should apply to step navigation.♻️ Proposed fix for workflow.md line 47
-Read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md` to begin the workflow. +Read fully and follow: `{installed_path}/steps/step-01-init.md` to begin the workflow.The same substitution should be applied to the two navigation lines in each of the seven
step-XX.mdfiles (14 additional lines), replacing{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/with{installed_path}/steps/.🤖 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/workflow.md` around lines 39 - 47, The workflow defines installed_path but step navigation still uses the hardcoded "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/" string; update workflow.md (the EXECUTION reference to step-01-init) to use "{installed_path}/steps/step-01-init.md" (mirroring template_path usage) and then in each step-XX.md file replace the two navigation lines that reference the full hardcoded "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/" with "{installed_path}/steps/" so all step links consistently derive from installed_path.
1-47:⚠️ Potential issue | 🟠 MajorPR incorrectly claims to close issue
#1625The stated defects in issue
#1625are:
- Missing file:
_bmad/core/tasks/validate-workflow.xml- No mechanism to resolve
{config_source}:keyvariable indirections in cold-start context- Checker cannot locate required source documents without the workflow engine loaded
This PR exclusively performs a find-and-replace of path prefixes. None of the
#1625defects are addressed. Merging this as "Closes#1625" silently discards those open defects.🤖 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/workflow.md` around lines 1 - 47, The PR wrongly claims to close issue `#1625` but only performs path prefix replacements; either remove the "Closes `#1625`" text from the PR/commit message or actually implement the three required fixes: add the missing task file `_bmad/core/tasks/validate-workflow.xml`, implement a cold-start config indirection resolver that can resolve `{config_source}:key` variable indirections when no engine is loaded (e.g., a resolveConfigIndirection function used by startup), and update the checker that locates required source documents to load or mock the workflow engine during discovery (ensure the checker calls the workflow engine loader/init routine or uses a fallback that loads `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture` paths) so the PR legitimately addresses all three defects before marking the issue closed.src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md (6)
62-64:⚠️ Potential issue | 🟡 Minor
{{stepsCompleted list}}is an ambiguous token — the frontmatter key isstepsCompleted, notstepsCompleted listA space inside a template variable token is not a standard convention. An agent resolving
{{stepsCompleted list}}as a variable name will fail to match thestepsCompletedfrontmatter key. If "list" is intended as a format directive (render the array as a bulleted list), it should be expressed outside the variable token or using whatever pipe/filter syntax the agent template engine supports.✏️ Suggested fix
-- Steps completed: {{stepsCompleted list}} +- Steps completed: {{stepsCompleted}} _(listed above)_Or, if a pipe-filter is supported by the engine:
-- Steps completed: {{stepsCompleted list}} +- Steps completed: {{stepsCompleted | join(", ")}}🤖 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 62 - 64, The template uses an invalid token "{{stepsCompleted list}}" which won't match the frontmatter key stepsCompleted; replace the token with the correct variable "{{stepsCompleted}}" and render the array-as-list outside the token (or use the template engine's pipe/filter syntax if available, e.g. stepsCompleted | list) so the "list" modifier is not part of the variable name; update the line that currently contains "{{stepsCompleted list}}" to use the corrected variable and formatting approach.
109-123:⚠️ Potential issue | 🟡 MinorSection 4 "Navigate to Selected Step" silently omits
stepsCompletedupdate semanticsLine 115 instructs the agent to update
lastStep, butstepsCompleted— the primary tracking array used by [R] to resume — has no update guidance here. Crucially:
- If the user navigates to an earlier step (say step-03 when steps 1–5 are completed), should
stepsCompletedbe trimmed? Left as-is?- If navigation succeeds, should step-01b itself add an entry to
stepsCompleted?Without explicit instruction, agents will make inconsistent choices across sessions, corrupting the resume state that this entire step is designed to protect.
🤖 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 109 - 123, Clarify and implement explicit stepsCompleted semantics in the "Navigate to Selected Step" section: when updating frontmatter `lastStep` also mutate the `stepsCompleted` array deterministically — if the user navigates backward trim `stepsCompleted` to include only steps up to and including the selected step; if navigating forward append any missing step identifiers up to the selected step; and ensure this step file (step-01b) itself adds its own identifier to `stepsCompleted` when executed; preserve other document content and update workflow status accordingly so resume logic always sees a consistent `stepsCompleted` and `lastStep`.
79-79:⚠️ Potential issue | 🟠 Major"Overwrite existing work" (menu, Line 79) contradicts "Delete existing document" (handler, Line 105)
These are not synonyms. Overwriting replaces the content in-place; deleting removes the file. If the correct behavior is deletion, the menu label should say so. If the intent is to reset the file to a fresh state (overwrite with the init template), then Line 105 should say "overwrite" and must specify what content to write, not "delete". As-is, an agent can reasonably interpret this either way, making the start-over flow non-deterministic.
🔧 Suggested clarification (choose one intent)
If the intent is to reset (not delete the file):
- - 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 confirmed: Clear all content from the existing architecture document, reset its frontmatter to initial values, then read and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md`If the intent is to delete:
-[X] Start over (will overwrite existing work) +[X] Start over (will DELETE the existing document — this is irreversible)Also applies to: 103-107
🤖 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 79, The menu label "Start over (will overwrite existing work)" and the handler text "Delete existing document" are contradictory; choose one intent and make both strings and behavior match: either change the menu label to "Delete existing document (will remove file)" and keep the handler that deletes the file, or change the handler to perform an overwrite (write the init template) and update its message to "Overwrite existing document" and explicitly state the template content being written; update both the UI label and the handler function (the "Start over..." menu string and the handler that currently calls "Delete existing document") so wording and actual behavior are consistent.
84-88:⚠️ Potential issue | 🟡 Minor
stepsCompletedinteger mapping has no slot for step-01b, creating ambiguous "next step" resolutionThe example on Line 88 assumes
stepsCompletedcontains plain integers mapping directly to step numbers (1→step-01, 2→step-02, etc.).step-01b-continue.mdis a lettered sub-step that breaks this mapping:
- If
stepsCompleted: [1], does that mean step-01 only, or step-01 + step-01b?- If step-01b is not tracked in
stepsCompleted, the [R] "resume from where we left off" logic cannot reliably determine whether the user resumed mid-step-01 versus completed it.The continuation handler should document explicitly whether it appends a value to
stepsCompletedwhen loading and, if so, what that value is (e.g.,"1b",1.5, or a dedicated key).🤖 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 84 - 88, Update the resume logic and docs to remove ambiguity around lettered sub-steps: explicitly state how the continuation handler updates stepsCompleted when loading step-01b-continue.md (e.g., append the string "1b" or a dedicated key like "1.1"), and modify the resume resolution description to check for these lettered keys (stepsCompleted may contain integers and/or string keys) so the "next step" computation reliably distinguishes step-01 vs step-01b; reference and update any code paths that read/write stepsCompleted and the continuation handler that loads step-01b-continue.md to ensure consistent encoding/decoding of the new slot.
97-101:⚠️ Potential issue | 🟠 MajorOption [O] instructs the agent to describe all remaining steps, but provides no descriptions and the agent hasn't loaded those step files
The progressive-disclosure architecture means the agent executing step-01b has not read step-02 through step-07. Telling it to "provide brief description of all remaining steps" with no content means those descriptions will be fabricated. This directly undermines the quality guarantee that is the entire purpose of the workflow system.
Either:
- Inline brief descriptions of each remaining step directly in this handler (as static text the agent can relay), or
- Remove the [O] option if it cannot be implemented safely within the progressive-disclosure model.
🤖 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 97 - 101, Option "O" in step-01b-continue.md asks the agent to "Provide brief description of all remaining steps" but the handler (step-01b) hasn't loaded step-02 through step-07, so it will fabricate content; fix by either (A) inlining concise static descriptions for step-02, step-03, step-04, step-05, step-06, and step-07 directly in this step-01b-continue.md so the agent can safely relay them, or (B) remove the "O" choice and any references to "Overview of all remaining steps" from the step-01b handler so the agent is not prompted to summarize unloaded steps — update only the text for the "O" option in step-01b-continue.md and any related UI labels to reflect the chosen approach.
58-80:⚠️ Potential issue | 🟠 MajorTemplate variable syntax is inconsistent and ambiguous inside the user-facing output block
The output block (lines 58–80) mixes three distinct notations without a clear convention:
{{user_name}}/{{project_name}}— double-brace Handlebars-style substitution{list all H2/H3 sections found in the document}(Line 67) — single-brace wrapping a full natural-language instruction, not a variable name; an agent interpreting this as a variable lookup will fail silently{{stepsCompleted list}}(Line 63) — the embedded word "list" is ambiguous; it is unclear whether this is the variable name or a formatting hintAdditionally,
{communication_language}(Line 14) and{project-root}(throughout) use single braces for what appear to be workflow-engine variables, while user-facing output tokens use double braces. The distinction is never defined anywhere in this file.An agent has no reliable basis for knowing which notation requires engine-level resolution versus template rendering versus inline instruction. At minimum,
{list all H2/H3 sections found in the document}should be written as a plain prose instruction outside the quoted block, and{{stepsCompleted list}}should be clarified (e.g.,{{stepsCompleted}}).🤖 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 58 - 80, The quoted user-facing template mixes three notations (e.g., {{user_name}}, {{project_name}}, {{stepsCompleted list}} and single-brace items like {list all H2/H3 sections found in the document}, {communication_language}, {project-root}) causing ambiguity; standardize to a single template syntax (use double-brace for data fields: change {{stepsCompleted list}} to {{stepsCompleted}}, {{stepsCompletedCount}} or similar explicit name) remove or relocate natural-language instructions (move "{list all H2/H3 sections found in the document}" out of the quoted user output into prose or a processing step), and replace single-brace workflow tokens like {communication_language} and {project-root} with the same double-brace convention or clearly documented engine-level markers so agent/template renderer can reliably resolve {{user_name}}, {{project_name}}, {{stepsCompleted}}, and any other tokens referenced in the quoted block.
🧹 Nitpick comments (1)
src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md (1)
164-171:step-01-init.mdis used in the [X] start-over flow (Line 106) but is absent from the "Valid step files" list without explanationThe list on Lines 164–171 begins at step-02 and jumps straight to step-08-complete.md. The init step used in the "start over" branch is silently excluded. Anyone maintaining this file — or an agent reasoning about which files are loadable — has no basis for understanding why step-01-init.md is valid in one branch but excluded from the authoritative list.
Add a brief comment or a separate entry (e.g.,
# Note: step-01-init.md is only valid for the [X] start-over path) to make the intent explicit.✏️ Suggested clarification
Valid step files to load: +<!-- step-01-init.md is intentionally excluded here; it is only valid for the [X] start-over path (see Section 3) --> - `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md`🤖 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 164 - 171, The list of valid step files omits step-01-init.md even though the file is referenced/used by the "[X] start-over" flow; update the section that enumerates valid step files to explicitly reference step-01-init.md (either add it to the list alongside step-02-context.md…step-08-complete.md or add a short clarifying note such as "Note: step-01-init.md is only valid for the [X] start-over path") so readers and agents understand why it exists and when it is loadable.
🤖 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/3-solutioning/create-architecture/steps/step-01-init.md`:
- 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).
- 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.
In
`@src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md`:
- Around line 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.
- 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).
---
Outside diff comments:
In `@src/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md`:
- Around line 111-126: The quoted agent output starting with "Welcome
{{user_name}}!..." in step-01-init.md is not closed, so add a closing double
quote (") immediately before the "## SUCCESS METRICS:" heading to terminate the
user-facing message; locate the open quote at the start of the welcome block and
insert the closing quote right before the "## SUCCESS METRICS:" line to prevent
the checklist from being parsed as part of the quoted response.
- Around line 98-99: The navigation links in step-01-init.md were hardcoded to
"{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/" in
the recent changes; update those navigation lines to use the existing
{installed_path} variable instead (i.e., replace the hardcoded path with
{installed_path}/... ), keeping the template copy line that already uses
{installed_path} unchanged so all step navigation and template references
consistently use {installed_path}.
In
`@src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md`:
- Around line 62-64: The template uses an invalid token "{{stepsCompleted
list}}" which won't match the frontmatter key stepsCompleted; replace the token
with the correct variable "{{stepsCompleted}}" and render the array-as-list
outside the token (or use the template engine's pipe/filter syntax if available,
e.g. stepsCompleted | list) so the "list" modifier is not part of the variable
name; update the line that currently contains "{{stepsCompleted list}}" to use
the corrected variable and formatting approach.
- Around line 109-123: Clarify and implement explicit stepsCompleted semantics
in the "Navigate to Selected Step" section: when updating frontmatter `lastStep`
also mutate the `stepsCompleted` array deterministically — if the user navigates
backward trim `stepsCompleted` to include only steps up to and including the
selected step; if navigating forward append any missing step identifiers up to
the selected step; and ensure this step file (step-01b) itself adds its own
identifier to `stepsCompleted` when executed; preserve other document content
and update workflow status accordingly so resume logic always sees a consistent
`stepsCompleted` and `lastStep`.
- Line 79: The menu label "Start over (will overwrite existing work)" and the
handler text "Delete existing document" are contradictory; choose one intent and
make both strings and behavior match: either change the menu label to "Delete
existing document (will remove file)" and keep the handler that deletes the
file, or change the handler to perform an overwrite (write the init template)
and update its message to "Overwrite existing document" and explicitly state the
template content being written; update both the UI label and the handler
function (the "Start over..." menu string and the handler that currently calls
"Delete existing document") so wording and actual behavior are consistent.
- Around line 84-88: Update the resume logic and docs to remove ambiguity around
lettered sub-steps: explicitly state how the continuation handler updates
stepsCompleted when loading step-01b-continue.md (e.g., append the string "1b"
or a dedicated key like "1.1"), and modify the resume resolution description to
check for these lettered keys (stepsCompleted may contain integers and/or string
keys) so the "next step" computation reliably distinguishes step-01 vs step-01b;
reference and update any code paths that read/write stepsCompleted and the
continuation handler that loads step-01b-continue.md to ensure consistent
encoding/decoding of the new slot.
- Around line 97-101: Option "O" in step-01b-continue.md asks the agent to
"Provide brief description of all remaining steps" but the handler (step-01b)
hasn't loaded step-02 through step-07, so it will fabricate content; fix by
either (A) inlining concise static descriptions for step-02, step-03, step-04,
step-05, step-06, and step-07 directly in this step-01b-continue.md so the agent
can safely relay them, or (B) remove the "O" choice and any references to
"Overview of all remaining steps" from the step-01b handler so the agent is not
prompted to summarize unloaded steps — update only the text for the "O" option
in step-01b-continue.md and any related UI labels to reflect the chosen
approach.
- Around line 58-80: The quoted user-facing template mixes three notations
(e.g., {{user_name}}, {{project_name}}, {{stepsCompleted list}} and single-brace
items like {list all H2/H3 sections found in the document},
{communication_language}, {project-root}) causing ambiguity; standardize to a
single template syntax (use double-brace for data fields: change
{{stepsCompleted list}} to {{stepsCompleted}}, {{stepsCompletedCount}} or
similar explicit name) remove or relocate natural-language instructions (move
"{list all H2/H3 sections found in the document}" out of the quoted user output
into prose or a processing step), and replace single-brace workflow tokens like
{communication_language} and {project-root} with the same double-brace
convention or clearly documented engine-level markers so agent/template renderer
can reliably resolve {{user_name}}, {{project_name}}, {{stepsCompleted}}, and
any other tokens referenced in the quoted block.
In
`@src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md`:
- Line 300: The template contains a malformed placeholder "{{how_the_project_is
organized_for_development}}" (note the space between "is" and "organized");
replace it with the consistent underscore-delimited form
"{{how_the_project_is_organized_for_development}}" so variable substitution will
match—update the placeholder in step-06-structure.md (search for the exact
string "{{how_the_project_is organized_for_development}}") and ensure it matches
other placeholders' naming convention.
In `@src/bmm/workflows/3-solutioning/create-architecture/workflow.md`:
- Around line 39-47: The workflow defines installed_path but step navigation
still uses the hardcoded
"{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/"
string; update workflow.md (the EXECUTION reference to step-01-init) to use
"{installed_path}/steps/step-01-init.md" (mirroring template_path usage) and
then in each step-XX.md file replace the two navigation lines that reference the
full hardcoded
"{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/"
with "{installed_path}/steps/" so all step links consistently derive from
installed_path.
- Around line 1-47: The PR wrongly claims to close issue `#1625` but only performs
path prefix replacements; either remove the "Closes `#1625`" text from the
PR/commit message or actually implement the three required fixes: add the
missing task file `_bmad/core/tasks/validate-workflow.xml`, implement a
cold-start config indirection resolver that can resolve `{config_source}:key`
variable indirections when no engine is loaded (e.g., a resolveConfigIndirection
function used by startup), and update the checker that locates required source
documents to load or mock the workflow engine during discovery (ensure the
checker calls the workflow engine loader/init routine or uses a fallback that
loads `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture`
paths) so the PR legitimately addresses all three defects before marking the
issue closed.
---
Nitpick comments:
In
`@src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md`:
- Around line 164-171: The list of valid step files omits step-01-init.md even
though the file is referenced/used by the "[X] start-over" flow; update the
section that enumerates valid step files to explicitly reference step-01-init.md
(either add it to the list alongside step-02-context.md…step-08-complete.md or
add a short clarifying note such as "Note: step-01-init.md is only valid for the
[X] start-over path") so readers and agents understand why it exists and when it
is loadable.
| 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 |
There was a problem hiding this comment.
🧩 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/nullRepository: 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 -20Repository: 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 -160Repository: 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.
| ## 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. |
There was a problem hiding this comment.
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.
| 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).
| - 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` |
There was a problem hiding this comment.
{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:
- The PR description should be corrected (this PR only fixes broken literal paths, not
#1625), or - Explicit instructions must be added here for resolving
{project-root}in the absence of the workflow engine (e.g., referenceconfig.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 '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 |
There was a problem hiding this comment.
"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.
3 participants
Summary
Fixes broken file references in
src/bmm/workflows/3-solutioning/create-architecture/step files.After the directory was renamed from
architecture/tocreate-architecture/, the internalnextStepFile/thisStepFilereferences inside 9 step files were not updated, causing 24 broken references detected byvalidate-file-refs.js --strict.Changes
Bulk find-and-replace across 9 files:
bmm/workflows/3-solutioning/architecture/steps/→bmm/workflows/3-solutioning/create-architecture/steps/Files updated:
workflow.mdsteps/step-01-init.mdsteps/step-01b-continue.mdsteps/step-02-context.mdsteps/step-03-starter.mdsteps/step-04-decisions.mdsteps/step-05-patterns.mdsteps/step-06-structure.mdsteps/step-07-validation.mdValidation
node tools/validate-file-refs.js --strictnow reports 0 broken references.Closes #1625