fix: anchor workflow commands for create-architecture

[dickymoore]

• What: Anchor generated workflow commands to {project-root} so IDEs don’t resolve core/workflow paths relative to module folders; add regression test for the create-architecture workflow command.
• Why: *workflow-init/*create-architecture commands could fail with “workflow.xml does not exist” because generated command paths were relative (e.g., .bmad/bmm/core/tasks/workflow.xml). Anchoring ensures commands point to .bmad/core/tasks/workflow.xml and the correct workflow file.
• How:
  • Update workflow command generator to prefix core/workflow paths with {project-root} and anchor display paths for installed workflows.
  • Add installation component test validating anchored paths for the create-architecture command.
• Testing: npm test

I double-checked upstream main (55cb468) and the anchoring fix isn’t present:

• tools/cli/installers/lib/ide/shared/workflow-command-generator.js still emits relative paths (no {project-root} anchoring / no withProjectRoot helper), so commands can resolve core/tasks/workflow.xml inside module folders.
• test/test-installation-components.js has no workflow command path coverage.

This looks like a bug, not intentional behavior:

• core/tasks/workflow.xml is under .bmad/core/tasks, but the generator injects {{core_workflow_path}} as /core/tasks/workflow.xml without {project-root}. When the workflow path is already an installed path (e.g., .bmad/bmm/workflows/...), IDEs resolve @... relative to that directory, yielding .bmad/bmm/core/tasks/workflow.xml - the failure seen in BMAD V6 asks to run /bmad:bmm:workflows:create-architecture which doesn't exist #872.
• There’s no test guarding the path shape, so the regression slipped through.
• The command templates state “Always LOAD {project-root}/…/core/tasks/workflow.xml”, which implies anchoring to project root; no docs suggest the current relative resolution is deliberate.

Given the symptom and template intent, anchoring to {project-root} matches the design, while the current relative output is erroneous.

Summary by CodeRabbit

Release Notes

• Tests

  • Added validation test for workflow command paths with project-root anchoring.

• Bug Fixes

  • Improved workflow path resolution by anchoring paths to project root for consistent behavior across environments.

• Updates

  • Enhanced workflow command template with new output handling step and updated path references.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

These changes modify the workflow command generation system to ensure all workflow paths are anchored to the project root. A new helper function standardizes path formatting, the template is updated to use a new placeholder, and a test validates the path anchoring behavior.

Changes

Cohort / File(s)	Summary
Workflow Path Anchoring Logic tools/cli/installers/lib/ide/shared/workflow-command-generator.js	Introduces withProjectRoot helper function to anchor workflow paths to {project-root}/. Applies path anchoring transformation to workflowPath and adds coreWorkflowPath computation. Injects {{core_workflow_path}} placeholder into template replacement. Adds final anchor step to convert paths not starting with {project-root}/ to anchored format.
Template Updates tools/cli/installers/lib/ide/templates/workflow-command-template.md	Replaces load path reference from @{bmad_folder}/core/tasks/workflow.xml to @{{core_workflow_path}}. Adds new step 5 for saving outputs after each section when generating documents from templates.
Test Coverage test/test-installation-components.js	Adds Test 4 to validate workflow command paths. Instantiates WorkflowCommandGenerator with a workflow object containing a relative path, generates command content, and asserts that output uses project-root anchored paths while excluding IDE-resolving relative paths.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• workflow-command-generator.js: Verify the withProjectRoot helper logic correctly anchors all path formats and that the transformation flow applies anchoring consistently across both installed and pre-installed path scenarios
• workflow-command-template.md: Confirm the placeholder replacement is correctly wired and the new step addition doesn't conflict with existing template logic
• test-installation-components.js: Ensure the test case adequately covers edge cases for path anchoring (empty paths, already-anchored paths, various relative path formats)

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically identifies the main change: anchoring workflow commands to use {project-root} paths for the create-architecture workflow to fix IDE path resolution issues.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dickymoore]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

tools/cli/installers/lib/ide/templates/workflow-command-template.md (1)

12-12: Note: Additional step unrelated to path anchoring.

This new step is a useful best practice but appears unrelated to the PR's stated objective of fixing path anchoring. Consider whether this should be in a separate PR or documenting it in the PR description.

tools/cli/installers/lib/ide/shared/workflow-command-generator.js (1)

115-118: Consider handling leading slashes in path normalization.

The withProjectRoot helper could produce double slashes if a path starts with /:

• Input: /foo/bar → Output: {project-root}//foo/bar

While current usage doesn't trigger this (paths are relative like .bmad/... or bmad/...), it would be more robust to normalize:

 const withProjectRoot = (p) => {
   if (!p) return p;
+  const cleanPath = p.startsWith('/') ? p.substring(1) : p;
-  return p.startsWith('{project-root}/') ? p : `{project-root}/${p}`;
+  return cleanPath.startsWith('{project-root}/') ? cleanPath : `{project-root}/${cleanPath}`;
 };

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cf50f49 and 061d9c5.

📒 Files selected for processing (3)

• test/test-installation-components.js (1 hunks)
• tools/cli/installers/lib/ide/shared/workflow-command-generator.js (3 hunks)
• tools/cli/installers/lib/ide/templates/workflow-command-template.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*

⚙️ CodeRabbit configuration file

**/*: Focus on inconsistencies, contradictions, edge cases and serious issues.
Avoid commenting on minor issues such as linting, formatting and style issues.
When providing code suggestions, use GitHub's suggestion format:

<code changes>

Files:

• tools/cli/installers/lib/ide/templates/workflow-command-template.md
• tools/cli/installers/lib/ide/shared/workflow-command-generator.js
• test/test-installation-components.js

**/*.js

⚙️ CodeRabbit configuration file

**/*.js: CLI tooling code. Check for: missing error handling on fs operations,
path.join vs string concatenation, proper cleanup in error paths.
Flag any process.exit() without error message.

Files:

• tools/cli/installers/lib/ide/shared/workflow-command-generator.js
• test/test-installation-components.js

🧬 Code graph analysis (1)

tools/cli/installers/lib/ide/shared/workflow-command-generator.js (1)

test/test-installation-components.js (1)

• workflow (169-174)

🔇 Additional comments (5)

tools/cli/installers/lib/ide/templates/workflow-command-template.md (1)

8-8: LGTM! Template change aligns with path anchoring objective.

The replacement of @{bmad_folder}/core/tasks/workflow.xml with @{{core_workflow_path}} ensures the core workflow path is anchored to the project root, which is properly populated by the generator at line 137-145 in workflow-command-generator.js.

test/test-installation-components.js (1)

160-187: LGTM! Test correctly validates path anchoring.

The test properly verifies that:

1. Workflow paths are anchored to {project-root}/
2. Old relative @.bmad patterns that caused IDE resolution issues are eliminated

The test path flows correctly through the generator's withProjectRoot helper (line 134 in generator) to produce the expected anchored format.

tools/cli/installers/lib/ide/shared/workflow-command-generator.js (3)

120-138: LGTM! Path extraction and anchoring logic is sound.

The flow correctly handles both source paths (from /src/modules/ or /src/core/) and installed paths (like .bmad/...), then consistently anchors them to {project-root}/. The coreWorkflowPath construction ensures the core workflow is always properly anchored.

---

145-145: LGTM! Template replacement for core workflow path.

The {{core_workflow_path}} replacement correctly injects the anchored core workflow path computed on line 137, aligning with the template changes.

---

233-235: LGTM! Handles already-installed paths correctly.

The new else-if branch ensures that installed workflow paths (e.g., .bmad/bmm/...) that don't match the source path patterns (/src/modules/ or /src/core/) are properly anchored to {project-root}/. This complements the anchoring logic in generateCommandContent for display paths in launcher files.

[bmadcode]

@dickymoore good idea here, but going to close as will be removing all need for workflow.xml once the final workflows are converted.