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 modification reference files in claudedocs/ directory Document all fork-specific modifications that must be preserved during merge Include file paths, line numbers, and critical code snippets Add insertion point details and recovery instructions Save verification commands for post-merge checking Reference files should include:

1. Installer Skip Block (claudedocs/installer-modification-reference.md):

   • File: tools/cli/installers/lib/core/installer.js
   • Lines: 913-916
   • Code: Skip block for workflow instructions.md
   • Verification: grep command to check presence

2. OpenCode Integration (claudedocs/opencode-integration-reference.md):

   • File: tools/cli/installers/lib/ide/opencode.js (entire file)
   • Type: Additive modification (new file)
   • Dependency: comment-json in package.json
   • Verification: File existence + dependency check + runtime check

Execute verification commands to confirm all critical modifications are 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 installer modification is missing from current codebase Provide guidance on restoring the modification before attempting merge Halt until modification is restored

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

Execute OpenCode pre-merge verification checks

Commands:

1. test -f tools/cli/installers/lib/ide/opencode.js
2. grep -q "comment-json" package.json
3. node -e "const {IdeManager}=require('./tools/cli/installers/lib/ide/manager');console.log(new IdeManager().getAvailableIdes().find(i=>i.value==='opencode')?'present':'missing')"

Alert user that OpenCode integration is incomplete or missing Provide recovery steps from claudedocs/opencode-integration-reference.md Suggest restoring from previous backup or commit Halt until OpenCode integration is restored

Confirm OpenCode integration is complete and functional

All fork modifications verified and ready for merge

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 all critical fork modifications survived Command: grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js Alert user that critical installer 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 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

Execute OpenCode verification checks to confirm fork-specific feature survived

Quick Verification Commands:

Check 1 - OpenCode installer file exists Command: test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ OpenCode present" || echo "❌ MISSING"

Alert user that OpenCode integration was lost during merge Identify most recent backup branch: git branch -a | grep backup-before | tail -1 Restore OpenCode: git checkout [backup-branch] -- tools/cli/installers/lib/ide/opencode.js Verify restoration successful

Check 2 - comment-json dependency exists in package.json Command: grep -q "comment-json" package.json && echo "✅ Dependency present" || echo "❌ MISSING"

Alert user that comment-json dependency was lost during merge Restore package.json from backup OR manually add: "comment-json": "^4.2.5" Run: npm install Verify: npm list comment-json

Check 3 - OpenCode is discoverable by IDE manager (runtime check) Command: node -e "const {IdeManager}=require('./tools/cli/installers/lib/ide/manager');const opencode=new IdeManager().getAvailableIdes().find(i=>i.value==='opencode');console.log(opencode?'✅ OpenCode discoverable':'❌ MISSING from IDE list')"

Alert user about runtime discovery failure Verify both opencode.js file AND comment-json dependency are present Check for syntax errors: node -c tools/cli/installers/lib/ide/opencode.js If file is corrupted, restore from backup branch

Confirm all three OpenCode checks passed Reference: Full recovery procedures in claudedocs/opencode-integration-reference.md

Verify git status shows clean merge completion with all modifications intact

Prepare comprehensive memory updates for Serena MCP with merge details Include merge date, commit hash, backup branch name, verification results for all modifications 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 Write updated memory to Serena: CRITICAL-opencode-fork-integration

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.