# Merge Upstream Workflow

**Version**: 1.0.0
**Author**: BMad
**Type**: Action Workflow (no document output)

## Purpose

Safely merge upstream repository changes while preserving critical fork modifications with automated verification and memory updates. This workflow provides a systematic, repeatable process for syncing with upstream repositories without losing custom code modifications.

## Use Cases

- Syncing your BMAD-METHOD fork with upstream bmad-code-org/BMAD-METHOD
- Preserving critical modifications during upstream pulls
- Maintaining cross-session memory of merge operations
- Ensuring custom modules remain functional after upstream integration

## How to Invoke

```bash
workflow merge-upstream
```

Or tell your BMAD agent:

```
Run the merge-upstream workflow
```

## Expected Inputs

**User Prompts During Execution:**

- Upstream remote name (default: `upstream`)
- Target branch name (default: `v6-alpha`)
- Confirmation before executing merge
- Conflict resolution if merge conflicts occur

**Files Referenced:**

- `claudedocs/installer-modification-reference.md` - Critical modification documentation
- `tools/cli/installers/lib/core/installer.js` - File containing critical modification

**Git State Required:**

- Clean working tree (no uncommitted changes)
- Upstream remote configured and accessible
- Current branch matches intended target branch

## Generated Outputs

**Git Artifacts:**

- Backup branch: `backup-before-pull-YYYYMMDD-HHMMSS`
- Merge commit with proper history preservation
- Updated reference documentation in `claudedocs/`

**Memory Updates:**

- **Serena MCP**: Updated `CRITICAL-installer-fork-modification` memory with merge details
- **Graphiti MCP**: New episode in `BMAD-METHOD` group with merge context

**Verification Reports:**

- Modification preservation status (preserved/manually restored)
- Module detection confirmation (all install-menu-config.yaml present)
- Merge statistics (files changed, commits integrated)

## Workflow Steps

1. **Pre-merge verification** - Verify clean git state and load reference docs
2. **Create backup branch** - Safety checkpoint with timestamp
3. **Document modification** - Update reference file in claudedocs/
4. **Verify before merge** - Confirm critical code exists pre-merge
5. **Fetch upstream** - Pull latest changes without merging
6. **Execute merge** - Merge with conflict handling guidance
7. **Verify preservation** - Confirm modification survived merge
8. **Update memories** - Save to Serena + Graphiti MCP
9. **Report completion** - Summary with next steps

## Special Requirements

**Required Tools:**

- **Git** - Version control for merge operations
- **Serena MCP** - Project memory management (must be active)
- **Graphiti MCP** - Knowledge graph memory (must be active)

**Critical File Protection:**
The workflow specifically protects:

- File: `tools/cli/installers/lib/core/installer.js`
- Lines: 913-916
- Code: Skip block for workflow instructions.md preservation

## Safety Features

- **Backup Branch**: Automatic timestamped backup before merge
- **Pre-merge Verification**: Confirms critical modifications exist before starting
- **Post-merge Verification**: Validates modifications survived merge
- **Recovery Guidance**: Step-by-step restoration if modifications lost
- **Memory Persistence**: Cross-session documentation for future reference

## Recovery Procedure

If merge fails or modifications are lost:

1. **Rollback**: `git reset --hard backup-before-pull-YYYYMMDD-HHMMSS`
2. **Restore**: Follow recovery instructions in `claudedocs/installer-modification-reference.md`
3. **Verify**: Run grep verification: `grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js`
4. **Retry**: Execute workflow again after restoration

## Validation Checklist

After workflow completion, verify using `checklist.md`:

- 43 specific validation criteria across 7 categories
- Pre-merge setup, safety measures, merge execution
- Modification preservation, memory updates, completeness
- Module-specific validation for all 4 BMAD modules

## Next Steps After Workflow

**Optional:**

- Push to your fork: `git push origin v6-alpha`
- Submit PR to upstream to eliminate future maintenance burden

**For Future Syncs:**

- Run this workflow again when upstream has new changes
- Reference updated memories for historical context
- Use backup branches for safe rollback if needed

## Troubleshooting

**"Working tree not clean" error**

- Commit or stash uncommitted changes before running workflow
- Ensure no untracked files that should be tracked

**"Upstream remote not found"**

- Add upstream: `git remote add upstream https://github.com/bmad-code-org/BMAD-METHOD`
- Verify: `git remote -v`

**"Modification not found after merge"**

- Workflow will guide through manual restoration
- Reference file has exact code and insertion point
- Verification command confirms successful restoration

**"MCP servers not responding"**

- Ensure Serena and Graphiti MCP servers are active
- Check MCP configuration in .mcp.json
- Memory updates are critical for cross-session persistence

## Files in This Workflow

```
bmad/workflows/merge-upstream/
├── README.md           # This file
├── workflow.yaml       # Configuration and metadata
├── instructions.md     # Step-by-step execution guide
└── checklist.md        # Post-execution validation
```

## Version History

**v1.0.0** (2025-10-18)

- Initial workflow creation
- Based on successful manual merge execution
- Includes Serena + Graphiti memory integration
- Comprehensive validation checklist (43 criteria)

---

**Maintained by**: BMad
**Last Updated**: 2025-10-18
**Status**: Production Ready