refactor: replace 'invoke/run' with 'load and follow' in workflow prompts

[arcaven]

Summary

• Replace "invoke the review task" with "load and follow the review task"
• Replace "run this step/task" with "load this step/task"

Changes

Two files, two lines each:

• src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md
• src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md

Context

Continues the work from PR #1387 (merged 2026-01-24) which established the canonical phrasing "load, read the full file, and follow..." by replacing "execute" across 87 files.

This PR completes that effort by applying the same transformation to the remaining "invoke" and "run" verbs.

Closes #1378

NOTE: file ref validation issue is pre-existing and relates to #1530

[coderabbitai]

📝 Walkthrough

Walkthrough

Two documentation files in the quick-flow workflows are updated to replace "invoke the review task" with "load and follow the review task." The surrounding context and control flow remain unchanged; only the terminology is standardized.

Changes

Cohort / File(s)	Summary
Review Task Terminology Updates src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md, src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md	Replaced "invoke the review task" with "load and follow the review task" to standardize ambiguous verb usage for prompt file references, per issue #1378.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

• refactor(bmm): convert quick-dev workflow to sharded format with adversarial review #1182: Introduced the adversarial-review task integration in the quick-dev workflow that these changes now reference with standardized terminology.
• refactor: standardize quick-flow menu patterns to newer format #1388: Also modifies review step wording and control flow language in related documentation files.
• fix: add missing review menu and HALT to quick-spec step 4 #1305: Modifies the same quick-spec/step-04-review.md file, affecting the review task invocation flow.

Suggested reviewers

• bmadcode

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: replacing ambiguous verbs ('invoke/run') with clearer phrasing ('load and follow') in workflow prompts.
Linked Issues check	✅ Passed	The PR successfully implements the requirements from issue #1378: replaces 'invoke' and 'run' verbs with 'load and follow' phrasing in the specified workflow prompt files within scope.
Out of Scope Changes check	✅ Passed	All changes are within scope—only workflow prompt files in src/bmm/ are modified with verb replacements, aligned with issue #1378 objectives and excluding code examples and shell references.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request description clearly relates to the changeset. It provides specific context about replacing ambiguous verbs ('invoke'/'run') with standardized phrasing ('load and follow'/'load'), identifies the two files being modified, references prior work (PR #1387), and links to the related issue (#1378).

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

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

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

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 (1)

src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md (1)

3-12: ⚠️ Potential issue | 🟠 Major

Standardize remaining “invoke” wording to match the new phrasing.

There are still multiple “invoke” references in this file, which conflicts with the new “load and follow” language introduced in Line 62. Please align these to avoid mixed guidance. (Keep the <invoke-task> marker unchanged.)

description: 'Construct diff and load and follow adversarial review task'

**Goal:** Construct diff of all changes, load and follow adversarial review task, present findings.

### 2. Load and Follow Adversarial Review

- Task loaded and followed with diff as input

- Loading and following task without providing diff input

Also applies to: 60-60, 96-96, 104-105

🤖 Fix all issues with AI agents

In `@src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md`:
- Around line 155-156: Update the step header to match the body phrasing by
replacing the heading text "Invoke Adversarial Review Task" with "Load and
Follow Adversarial Review Task" so the title aligns with the sentence that
begins "With {finalFile} constructed, load and follow the review task"; ensure
you only change the header string in the step (the numbered item) and leave the
surrounding content and the "{finalFile}" reference unchanged.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Align the step header with the new “load and follow” phrasing.

The heading still says “Invoke…”, but the body now says “load and follow,” which is inconsistent.

Suggested change

	1. **Invoke Adversarial Review Task**:
	> With `{finalFile}` constructed, invoke the review task. If possible, use information asymmetry: run this task, and only it, in a separate subagent or process with read access to the project, but no context except the `{finalFile}`.
	> With `{finalFile}` constructed, load and follow the review task. If possible, use information asymmetry: load this task, and only it, in a separate subagent or process with read access to the project, but no context except the `{finalFile}`.
	1. **Load and Follow Adversarial Review Task**:

🤖 Prompt for AI Agents

In `@src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md` around
lines 155 - 156, Update the step header to match the body phrasing by replacing
the heading text "Invoke Adversarial Review Task" with "Load and Follow
Adversarial Review Task" so the title aligns with the sentence that begins "With
{finalFile} constructed, load and follow the review task"; ensure you only
change the header string in the step (the numbered item) and leave the
surrounding content and the "{finalFile}" reference unchanged.

[arcaven]

Regarding the suggestion to also update section headers (e.g., "### 2. Invoke Adversarial Review") and frontmatter metadata — I intentionally kept these unchanged based on the scope defined in issue #1378.

The issue specifically targets ambiguous action instructions that tell the AI to perform an action but are unclear about the mechanism:

These terms lack clarity on whether they mean:

1. Load and read the prompt file content
2. Process/follow the instructions within the file
3. Invoke via a CLI/tool command

I think of Section headers like "### 2. Invoke Adversarial Review" are labels describing what the section is about, not instructions telling the AI how to perform an action. Similarly, frontmatter description: fields are metadata, not action instructions.

This matches the approach taken in PR #1387, which replaced "execute" in action instructions but preserved it in structural/descriptive contexts.

If reviewers or project maintainers would prefer the headers and metadata updated as well, I'm happy to expand the scope — but I wanted to stay conservative and match the original issue's intent.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Fetch issue `#1378` to verify the scope and intent
gh issue view 1378 --repo bmad-code-org/BMAD-METHOD --json title,body,number | jq -r '.body'

Length of output: 1386

---

🏁 Script executed:

#!/bin/bash
# Check PR `#1387` to see if it preserved headers/metadata with "execute"
gh pr view 1387 --repo bmad-code-org/BMAD-METHOD --json files | jq -r '.files[].path' | head -20

Length of output: 1466

---

🏁 Script executed:

#!/bin/bash
# Look at a sample file from PR `#1387` to see how headers were handled
gh pr diff 1387 --repo bmad-code-org/BMAD-METHOD | grep -A 5 -B 5 "^-.*execute" | head -50

Length of output: 2817

---

@arcaven: Your reasoning is spot-on, and the evidence supports your approach completely.

Looking at issue #1378, it explicitly targets "ambiguous verbs...to reference prompt files" where the mechanism is unclear (load/read vs. process/follow vs. CLI invoke). The examples provided focus on action instructions.

Reviewing PR #1387's diff confirms your claim: changes replaced "execute" in action contexts like:

• "then execute {nextStepFile}" → "then follow: {nextStepFile}"
• "IF C: Execute {advancedElicitationTask}" → "IF C: Read fully and follow: {advancedElicitationTask}"

The headers and metadata were indeed preserved as descriptive elements, not action instructions.

Your distinction is well-founded:

• Action instructions tell the AI how to perform an operation → in scope for standardization
• Section headers label what a section discusses → descriptive, not instructional
• Frontmatter metadata provides document metadata → descriptive, not instructional

Your conservative approach maintains consistency with the established pattern from PR #1387 and honors the original issue intent. If @bmadcode or @alexeyv determine that headers and metadata should also be standardized for consistency, that would be a reasonable scope expansion—but your current implementation correctly addresses the stated requirements.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@arcaven: You're very welcome! Your explanation perfectly captures the nuanced distinction, and I appreciate you taking the time to articulate it so clearly.

Your conservative approach is exactly right: you've addressed the action instructions where ambiguity about mechanism matters, while appropriately leaving descriptive labels and metadata unchanged. Section headers like "### 2. Invoke Adversarial Review" describe the topic, and frontmatter description: fields provide metadata—neither tells the AI how to perform an action, so they fall outside the scope of #1378.

The consistency with PR #1387's pattern reinforces that you've correctly interpreted the project's standardization intent. If the maintainers decide to expand scope to headers/metadata for broader consistency, that would be a separate consideration—but your current implementation fully satisfies the stated requirements.

No changes needed from my perspective! 🎯

---

✏️ Learnings added

Learnt from: arcaven
URL: https://github.com/bmad-code-org/BMAD-METHOD/pull/1570

Timestamp: 2026-02-06T22:12:07.251Z
Learning: In BMAD-METHOD, when standardizing verbs like "execute", "invoke", "run" per issue `#1378` and PR `#1387/`#1570, only action instructions (that tell the AI how to perform an action) are replaced with "load and follow" or "read and follow". Section headers, frontmatter metadata, and other descriptive/structural elements are intentionally left unchanged, as they label topics rather than instruct actions.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

[bmadcode]

Thank you @arcaven