refactor: convert document-project workflow.yaml to workflow.md (step 9)#1863
Conversation
🤖 Augment PR SummarySummary: Converts the “Document Project” workflow family from legacy Changes:
Technical Notes: The router continues to orchestrate 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
src/bmm/workflows/document-project/workflows/deep-dive-workflow.md
Outdated
Show resolved
Hide resolved
src/bmm/workflows/document-project/workflows/full-scan-workflow.md
Outdated
Show resolved
Hide resolved
📝 WalkthroughWalkthroughMigrates the document-project workflow system from YAML-based configuration to Markdown-based format. Updates agent configurations to reference new Markdown workflow files, removes legacy YAML workflow definitions, and creates corresponding Markdown workflow documentation for the main workflow and sub-workflows. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 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)
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 (2)
src/bmm/workflows/document-project/instructions.md (2)
101-123:⚠️ Potential issue | 🟠 MajorThe router returns to a step that does not exist.
Lines 102, 110, and 123 say execution continues to Step 4, but this file ends at Step 3. That leaves the post-scan path unreachable.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/document-project/instructions.md` around lines 101 - 123, The post-sub-workflow actions reference "After sub-workflow completes, continue to Step 4" which doesn't exist; update the three occurrences inside the <check if="user selects 1">, <check if="user selects 2"> and the <check if="index.md does not exist"> blocks so the action reads "After sub-workflow completes, continue to Step 3" (or alternatively create a valid Step 4 and its content); modify the action text exactly where it appears to ensure the router points to an existing step (look for the literal string "After sub-workflow completes, continue to Step 4" in instructions.md).
13-23:⚠️ Potential issue | 🟠 MajorPropagate
scan_levelbefore any full-scan delegation.This file reads
scan_levelfrom the state file, andfull-scan-workflow.mddeclares it as parent-supplied, but neither the resume branch nor the freshinitial_scan/full_rescanbranches ever assign it before delegation. The full-scan sub-workflow therefore starts with an emptyscan_levelon every path.Also applies to: 36-54, 98-123
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/document-project/instructions.md` around lines 13 - 23, The state file's scan_level is read but never passed into the delegated full-scan sub-workflow, causing full-scan-workflow.md to receive an empty scan_level; before delegating (in the resume branch and the initial_scan / full_rescan branches) explicitly set the sub-workflow input's scan_level to the extracted scan_level from the state, and ensure any delegation call or StartSubWorkflow/dispatch includes that field so full-scan-workflow.md always gets scan_level populated.
🧹 Nitpick comments (3)
src/bmm/agents/analyst.agent.yaml (1)
41-43: This workflow path is duplicated across agents again.
src/bmm/agents/analyst.agent.yamlLine 42 andsrc/bmm/agents/tech-writer/tech-writer.agent.yamlLine 25 now hardcode the same installed launcher string. That duplication is exactly how entry-point migrations like.yaml→.mdget missed later. Consider sourcing the document-project launcher from one shared manifest or generator.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/agents/analyst.agent.yaml` around lines 41 - 43, The two agent YAMLs duplicate the same hardcoded workflow launcher string ("{project-root}/_bmad/bmm/workflows/document-project/workflow.md") causing drift; update both src/bmm/agents/analyst.agent.yaml and src/bmm/agents/tech-writer/tech-writer.agent.yaml to reference a single shared manifest or generator (e.g., a central constant or manifest entry such as DOCUMENT_PROJECT_WORKFLOW or a shared manifest file that exposes the workflow path) instead of duplicating the literal workflow path; change the workflow fields in the analyst and tech-writer agents to pull the value from that shared source (or use a templated include) so future path changes only need to be made in one place.src/bmm/agents/tech-writer/tech-writer.agent.yaml (1)
24-26: Add a smoke test for this new Markdown launcher path.This is a user-facing entry point. Static reference validation only proves the file exists; it does not prove the tech-writer menu still dispatches
.mdworkflows correctly. This change wants an agent-menu regression test.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/agents/tech-writer/tech-writer.agent.yaml` around lines 24 - 26, Add a smoke/regression test that exercises the tech-writer agent menu entry (the YAML keys trigger, workflow, description) to ensure the Markdown launcher path "{project-root}/_bmad/bmm/workflows/document-project/workflow.md" is actually dispatched at runtime: write a test that programmatically invokes the agent menu (simulate selecting the "DP" trigger or a fuzzy match on "document-project"), asserts the menu routes to the .md workflow launcher, and verifies the invoked workflow path equals the YAML workflow value and returns a successful response; place the test alongside other agent-menu integration tests and mock or stub the workflow runner to observe dispatch without executing full workflow.src/bmm/workflows/document-project/workflows/deep-dive-workflow.md (1)
32-36: Make the chosen deep-dive area an explicit runtime input.The workflow says user input is required to select a target area, and the downstream template is area-specific, but the contract never names the variable that carries that selection. Keeping it implicit makes this flow harder to resume and reason about.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/bmm/workflows/document-project/workflows/deep-dive-workflow.md` around lines 32 - 36, The runtime contract omits the explicit variable for the chosen deep-dive area—add a named runtime input (e.g., deep_dive_area or target_area) so the selection is explicit and resumable; update the Runtime Inputs section alongside workflow_mode, scan_level, and autonomous to include deep_dive_area (with allowed values or schema), and ensure the downstream area-specific template consumes that variable (update references in the template to read deep_dive_area instead of relying on implicit user state).
🤖 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/document-project/workflows/deep-dive-workflow.md`:
- Line 19: The workflow doc references the wrong module path; change the config
path string "_bmad/bmb/config.yaml" in deep-dive-workflow.md to the correct
installed location "_bmad/bmm/config.yaml" so the router delegates to the proper
module (update the literal path used in the "Load config from ..." line).
In `@src/bmm/workflows/document-project/workflows/full-scan-workflow.md`:
- Around line 35-36: Summary: The documented `autonomous` flag is dead surface
and should be removed or implemented; update the doc to avoid advertising
non-existent behavior. Fix: remove the `autonomous = false` line from the
full-scan-workflow.md and any examples or schema references that mention
`autonomous`, or alternatively implement runtime handling in the workflow code
to accept and act on `autonomous`; locate occurrences by searching for the
symbol `autonomous` (and related examples) and ensure only the supported
`resume_mode` flag remains referenced and documented.
- Line 18: The workflow references the wrong config path string
`_bmad/bmb/config.yaml` causing config load failures; update that literal to
`_bmad/bmm/config.yaml` wherever it appears in the full-scan-workflow markdown
(the config load/resolution step) so it matches the rest of the workflow family
and the router's delegated path.
- Around line 33-35: The sub-workflow default is clobbering resume state by
resetting resume_mode to false; remove that reset (do not assign resume_mode =
false) so the router-set resume_mode (true on restart) flows into the
sub-workflow and lets full-scan-instructions.md branch correctly; leave
workflow_mode and scan_level defaults as-is and only omit any assignment or
default for resume_mode in the sub-workflow definitions.
---
Outside diff comments:
In `@src/bmm/workflows/document-project/instructions.md`:
- Around line 101-123: The post-sub-workflow actions reference "After
sub-workflow completes, continue to Step 4" which doesn't exist; update the
three occurrences inside the <check if="user selects 1">, <check if="user
selects 2"> and the <check if="index.md does not exist"> blocks so the action
reads "After sub-workflow completes, continue to Step 3" (or alternatively
create a valid Step 4 and its content); modify the action text exactly where it
appears to ensure the router points to an existing step (look for the literal
string "After sub-workflow completes, continue to Step 4" in instructions.md).
- Around line 13-23: The state file's scan_level is read but never passed into
the delegated full-scan sub-workflow, causing full-scan-workflow.md to receive
an empty scan_level; before delegating (in the resume branch and the
initial_scan / full_rescan branches) explicitly set the sub-workflow input's
scan_level to the extracted scan_level from the state, and ensure any delegation
call or StartSubWorkflow/dispatch includes that field so full-scan-workflow.md
always gets scan_level populated.
---
Nitpick comments:
In `@src/bmm/agents/analyst.agent.yaml`:
- Around line 41-43: The two agent YAMLs duplicate the same hardcoded workflow
launcher string
("{project-root}/_bmad/bmm/workflows/document-project/workflow.md") causing
drift; update both src/bmm/agents/analyst.agent.yaml and
src/bmm/agents/tech-writer/tech-writer.agent.yaml to reference a single shared
manifest or generator (e.g., a central constant or manifest entry such as
DOCUMENT_PROJECT_WORKFLOW or a shared manifest file that exposes the workflow
path) instead of duplicating the literal workflow path; change the workflow
fields in the analyst and tech-writer agents to pull the value from that shared
source (or use a templated include) so future path changes only need to be made
in one place.
In `@src/bmm/agents/tech-writer/tech-writer.agent.yaml`:
- Around line 24-26: Add a smoke/regression test that exercises the tech-writer
agent menu entry (the YAML keys trigger, workflow, description) to ensure the
Markdown launcher path
"{project-root}/_bmad/bmm/workflows/document-project/workflow.md" is actually
dispatched at runtime: write a test that programmatically invokes the agent menu
(simulate selecting the "DP" trigger or a fuzzy match on "document-project"),
asserts the menu routes to the .md workflow launcher, and verifies the invoked
workflow path equals the YAML workflow value and returns a successful response;
place the test alongside other agent-menu integration tests and mock or stub the
workflow runner to observe dispatch without executing full workflow.
In `@src/bmm/workflows/document-project/workflows/deep-dive-workflow.md`:
- Around line 32-36: The runtime contract omits the explicit variable for the
chosen deep-dive area—add a named runtime input (e.g., deep_dive_area or
target_area) so the selection is explicit and resumable; update the Runtime
Inputs section alongside workflow_mode, scan_level, and autonomous to include
deep_dive_area (with allowed values or schema), and ensure the downstream
area-specific template consumes that variable (update references in the template
to read deep_dive_area instead of relying on implicit user state).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 8a616189-e4de-45ef-8469-9b13fb6d454a
⛔ Files ignored due to path filters (1)
src/bmm/module-help.csvis excluded by!**/*.csv
📒 Files selected for processing (11)
src/bmm/agents/analyst.agent.yamlsrc/bmm/agents/tech-writer/tech-writer.agent.yamlsrc/bmm/workflows/document-project/instructions.mdsrc/bmm/workflows/document-project/workflow.mdsrc/bmm/workflows/document-project/workflow.yamlsrc/bmm/workflows/document-project/workflows/deep-dive-instructions.mdsrc/bmm/workflows/document-project/workflows/deep-dive-workflow.mdsrc/bmm/workflows/document-project/workflows/deep-dive.yamlsrc/bmm/workflows/document-project/workflows/full-scan-instructions.mdsrc/bmm/workflows/document-project/workflows/full-scan-workflow.mdsrc/bmm/workflows/document-project/workflows/full-scan.yaml
💤 Files with no reviewable changes (5)
- src/bmm/workflows/document-project/workflows/deep-dive-instructions.md
- src/bmm/workflows/document-project/workflows/deep-dive.yaml
- src/bmm/workflows/document-project/workflow.yaml
- src/bmm/workflows/document-project/workflows/full-scan-instructions.md
- src/bmm/workflows/document-project/workflows/full-scan.yaml
src/bmm/workflows/document-project/workflows/deep-dive-workflow.md
Outdated
Show resolved
Hide resolved
src/bmm/workflows/document-project/workflows/full-scan-workflow.md
Outdated
Show resolved
Hide resolved
Triage of remaining review findings (outside diff / nitpick)F5 [Major] Router references non-existent Step 4 ( F6 [Major] scan_level never propagated to sub-workflow ( F7 [Nitpick] Duplicated workflow path across agents ( F8 [Nitpick] Add smoke test for .md launcher path ( F9 [Nitpick] Deep-dive area should be explicit runtime input ( |
Convert main workflow and both sub-workflows (deep-dive, full-scan) from legacy .yaml entry point format to unified .md format. Update agent files and module-help.csv references. Clean engine-scaffolding <critical> blocks from instruction files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Both deep-dive-workflow.md and full-scan-workflow.md referenced _bmad/bmb/config.yaml instead of _bmad/bmm/config.yaml, which would break config resolution at runtime. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
alexeyv
force-pushed
the
convert-document-project-yaml-to-md
branch
from
4b1170c to
15f4891
Compare
1 participant
Summary
workflow.yamlentry point format to unifiedworkflow.mdformat<critical>blocks from instruction files while preserving behavioral constraintsanalyst.agent.yaml,tech-writer.agent.yaml) andmodule-help.csvreferences from.yamlto.mdThis is step 9 (final) of the yaml-to-md conversion plan.
Test plan
workflow.mdloads correctly and resolves all config variablesinstructions.mddelegates todeep-dive-workflow.mdandfull-scan-workflow.mdcorrectly.mdpathnpm run lint)🤖 Generated with Claude Code