BMAD-METHOD/bmad/workflows/merge-upstream/instructions.md

Merge Upstream Workflow Instructions

The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/workflows/merge-upstream/workflow.yaml Communicate in {communication_language} throughout the workflow process

Verify git repository status to ensure a clean working tree before beginning merge Check current branch and confirm it matches the expected target branch Identify the upstream remote and target branch to merge from

What is the upstream remote name? (default: upstream) What branch should we merge from upstream? (default: v6-alpha)

Verify the upstream remote exists and is accessible

Alert user about uncommitted changes that must be resolved first Provide guidance: commit changes, stash them, or clean the working directory Wait for user to resolve before continuing

Load the modification reference documentation from: {modification_reference} Review critical file locations and modification details that must be preserved

Generate a timestamped backup branch name using format: backup-before-pull-YYYYMMDD-HHMMSS Create the backup branch from current HEAD as a safety checkpoint Verify backup branch was created successfully Inform user of backup branch name for potential rollback

This backup branch is essential for recovery if the merge encounters unexpected issues

Create or update the modification reference file in claudedocs/ directory Document the exact code that must be preserved during merge Include file path, line numbers, and the critical code snippet Add insertion point details and recovery instructions Save verification commands for post-merge checking Reference file should include: - File: tools/cli/installers/lib/core/installer.js - Lines: 913-916 - Code: Skip block for workflow instructions.md - Verification: grep command to check presence Execute verification command to confirm critical modification is present Use grep to search for the modification signature in the target file

Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js

Alert user that critical modification is missing from current codebase Provide guidance on restoring the modification before attempting merge Halt until modification is restored

Confirm modification present at expected location Record current line numbers for post-merge comparison

Fetch latest changes from upstream remote without merging Display summary of incoming changes: commits, files, insertions/deletions Review commit messages from upstream to understand what's being integrated

Command: git fetch {{upstream_remote}} {{target_branch}}

Alert user about network issues or remote access problems

Explain merge strategy: using merge (not rebase) to preserve published history Display number of divergent commits between local and upstream

Ready to proceed with merge? Review upstream changes above. [yes/no]

Inform user they can review changes and restart workflow when ready Remind user of backup branch location for safety Exit workflow

Execute merge command: git merge {{upstream_remote}}/{{target_branch}}

Display conflict files and conflict markers Guide user through conflict resolution, emphasizing preservation of critical modification Provide specific guidance for installer.js conflicts if present Have you resolved all conflicts? [yes/no] Verify modification preserved during resolution Wait for user to complete resolution

Record merge commit hash for documentation Display merge statistics: files changed, insertions, deletions

Execute post-merge verification to confirm critical modification survived

Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js

Alert user that critical modification was lost during merge Load recovery instructions from reference documentation Guide user to manually re-insert the 4-line modification after config.yaml skip block Verify manual restoration before continuing

Confirm modification exists at same or nearby line numbers Verify git status shows clean merge completion Check that all expected modules still have install-menu-config.yaml files

Verification: find src/modules -name "install-menu-config.yaml" should show all modules intact

Prepare comprehensive memory update for Serena MCP with merge details Include merge date, commit hash, backup branch name, verification results Document any conflicts encountered and how they were resolved Update merge workflow history and success metrics

Write updated memory to Serena: CRITICAL-installer-fork-modification

Prepare episode for Graphiti MCP knowledge graph Include merge context, upstream commits pulled, modification preservation status Link to related entities: installer.js, modules, git workflow

Add merge episode to Graphiti with group_id: BMAD-METHOD

Verify both memory systems confirm successful storage

List all backup branches created during merge process Identify backup branches matching pattern: backup-before-pull-*

Command: git branch | grep backup-before-pull

Display found backup branches to user Delete all backup branches matching the pattern Confirm deletion with git branch output Report number of branches cleaned up Inform user that no backup branches need cleanup

Verify backup branches have been removed from git branch list

Generate comprehensive merge completion summary for {user_name}

Include in summary:

• Merge status (success/conflicts resolved)
• Backup branches cleaned up (count)
• Merge commit hash
• Files changed statistics
• Modification preservation status (preserved/manually restored)
• Memory update confirmations (Serena + Graphiti)
• Reference documentation location

Provide next steps guidance:

• Optional: Push to origin fork (git push origin {{target_branch}})
• Consider: Submit PR to upstream to eliminate future maintenance
• Future: Use this workflow for subsequent upstream syncs

Remind user of verification commands for future reference

Workflow complete! All critical modifications preserved and documented.