From 4cfa0f8c6f052be56b21adb17e729ee9f49b4548 Mon Sep 17 00:00:00 2001 From: Sallvainian Date: Sun, 19 Oct 2025 02:15:13 -0400 Subject: [PATCH] Add merge-upstream workflow and documentation - Created merge-upstream workflow configuration - Added workflow instructions and validation checklist - Added installer modification reference documentation - Updated workflow manifest --- .../bmad/core/workflows/merge-upstream.md | 11 ++ bmad/_cfg/workflow-manifest.csv | 1 + bmad/workflows/merge-upstream/README.md | 182 ++++++++++++++++++ bmad/workflows/merge-upstream/checklist.md | 101 ++++++++++ bmad/workflows/merge-upstream/instructions.md | 169 ++++++++++++++++ bmad/workflows/merge-upstream/workflow.yaml | 32 +++ .../installer-modification-reference.md | 50 +++++ 7 files changed, 546 insertions(+) create mode 100644 .claude/commands/bmad/core/workflows/merge-upstream.md create mode 100644 bmad/workflows/merge-upstream/README.md create mode 100644 bmad/workflows/merge-upstream/checklist.md create mode 100644 bmad/workflows/merge-upstream/instructions.md create mode 100644 bmad/workflows/merge-upstream/workflow.yaml create mode 100644 claudedocs/installer-modification-reference.md diff --git a/.claude/commands/bmad/core/workflows/merge-upstream.md b/.claude/commands/bmad/core/workflows/merge-upstream.md new file mode 100644 index 00000000..9120e8b2 --- /dev/null +++ b/.claude/commands/bmad/core/workflows/merge-upstream.md @@ -0,0 +1,11 @@ +# merge-upstream + +IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded: + + +1. Always LOAD the FULL {project-root}/bmad/core/tasks/workflow.xml +2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config bmad/workflows/merge-upstream/workflow.yaml +3. Pass the yaml path bmad/workflows/merge-upstream/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions +4. Follow workflow.xml instructions EXACTLY as written +5. Save outputs after EACH section when generating any documents from templates + diff --git a/bmad/_cfg/workflow-manifest.csv b/bmad/_cfg/workflow-manifest.csv index 53ca4bbf..6e794608 100644 --- a/bmad/_cfg/workflow-manifest.csv +++ b/bmad/_cfg/workflow-manifest.csv @@ -1,4 +1,5 @@ name,description,module,path +"merge-upstream","Safely merge upstream repository changes while preserving critical fork modifications with automated verification and memory updates","core","bmad/workflows/merge-upstream/workflow.yaml" "brainstorming","Facilitate interactive brainstorming sessions using diverse creative techniques. This workflow facilitates interactive brainstorming sessions using diverse creative techniques. The session is highly interactive, with the AI acting as a facilitator to guide the user through various ideation methods to generate and refine creative solutions.","core","bmad/core/workflows/brainstorming/workflow.yaml" "party-mode","Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations","core","bmad/core/workflows/party-mode/workflow.yaml" "audit-workflow","Comprehensive workflow quality audit - validates structure, config standards, variable usage, bloat detection, and web_bundle completeness. Performs deep analysis of workflow.yaml, instructions.md, template.md, and web_bundle configuration against BMAD v6 standards.","bmb","bmad/bmb/workflows/audit-workflow/workflow.yaml" diff --git a/bmad/workflows/merge-upstream/README.md b/bmad/workflows/merge-upstream/README.md new file mode 100644 index 00000000..c3656db6 --- /dev/null +++ b/bmad/workflows/merge-upstream/README.md @@ -0,0 +1,182 @@ +# 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 diff --git a/bmad/workflows/merge-upstream/checklist.md b/bmad/workflows/merge-upstream/checklist.md new file mode 100644 index 00000000..b8c03e22 --- /dev/null +++ b/bmad/workflows/merge-upstream/checklist.md @@ -0,0 +1,101 @@ +# Merge Upstream Workflow Validation Checklist + +## Pre-Merge Setup + +- [ ] Git status confirmed clean working tree (no uncommitted changes) +- [ ] Current branch verified and matches target branch +- [ ] Upstream remote exists and is accessible +- [ ] Modification reference file loaded and reviewed +- [ ] Critical modification verified present before merge started + +## Safety Measures + +- [ ] Backup branch created with format: backup-before-pull-YYYYMMDD-HHMMSS +- [ ] Backup branch creation confirmed via `git branch` output +- [ ] Modification reference saved to claudedocs/installer-modification-reference.md +- [ ] Reference file includes: file path, line numbers, code snippet, verification command +- [ ] Reference file includes: insertion point details and recovery instructions + +## Merge Execution + +- [ ] Upstream changes fetched successfully from specified remote +- [ ] Merge commit statistics displayed (files changed, insertions, deletions) +- [ ] Merge strategy used: merge (not rebase) to preserve published history +- [ ] If conflicts occurred: All conflicts resolved manually +- [ ] If conflicts occurred: Critical modification preserved during resolution +- [ ] Merge commit created with proper commit hash recorded +- [ ] Git status shows clean state after merge (no unmerged paths) + +## Critical Modification Preservation + +- [ ] Post-merge verification executed: `grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js` +- [ ] Verification output confirms modification exists at lines 913-916 (or nearby) +- [ ] Modification code intact: 4-line skip block for workflow instructions.md files +- [ ] If lost: Manual restoration completed following reference documentation +- [ ] If lost: Manual restoration verified with grep command +- [ ] Module detection verified: `find src/modules -name "install-menu-config.yaml"` returns all expected modules + +## Memory Updates + +- [ ] Serena MCP memory updated: CRITICAL-installer-fork-modification +- [ ] Serena memory includes: merge date, commit hash, backup branch name +- [ ] Serena memory includes: verification status and any conflicts encountered +- [ ] Serena memory includes: updated merge workflow history +- [ ] Graphiti MCP episode created with group_id: BMAD-METHOD +- [ ] Graphiti episode includes: merge context and upstream commits pulled +- [ ] Graphiti episode includes: modification preservation status +- [ ] Both memory systems confirmed successful storage + +## Completeness + +- [ ] Merge commit hash documented in completion summary +- [ ] Backup branch name documented for potential rollback +- [ ] Files changed statistics recorded (files, insertions, deletions) +- [ ] Modification preservation status documented (preserved/manually restored) +- [ ] Reference documentation location confirmed: claudedocs/installer-modification-reference.md +- [ ] Next steps provided: optional push to origin, consider PR to upstream +- [ ] Future workflow invocation command documented: `workflow merge-upstream` + +## Specific Module Validation + +- [ ] teachflow module install config present: src/modules/teachflow/\_module-installer/install-menu-config.yaml +- [ ] bmm module install config present: src/modules/bmm/\_module-installer/install-menu-config.yaml +- [ ] cis module install config present: src/modules/cis/\_module-installer/install-menu-config.yaml +- [ ] bmb module install config present: src/modules/bmb/\_module-installer/install-menu-config.yaml +- [ ] All workflow instructions.md files protected (28+ files in bmm module) + +## Final Validation + +### Pre-Merge Setup Issues + +- [ ] Issue List: + +### Safety Measures Issues + +- [ ] Issue List: + +### Merge Execution Issues + +- [ ] Issue List: + +### Critical Modification Preservation Issues + +- [ ] Issue List: + +### Memory Updates Issues + +- [ ] Issue List: + +### Completeness Issues + +- [ ] Issue List: + +### Module Validation Issues + +- [ ] Issue List: + +--- + +**Workflow Status**: [ ] Complete and Validated + +**Signed off by**: **\*\*\*\***\_**\*\*\*\*** **Date**: **\*\*\*\***\_**\*\*\*\*** diff --git a/bmad/workflows/merge-upstream/instructions.md b/bmad/workflows/merge-upstream/instructions.md new file mode 100644 index 00000000..d6e31bc7 --- /dev/null +++ b/bmad/workflows/merge-upstream/instructions.md @@ -0,0 +1,169 @@ +# 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 + + + +Generate comprehensive merge completion summary for {user_name} + +Include in summary: + +- Merge status (success/conflicts resolved) +- Backup branch name and location +- 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. + + + diff --git a/bmad/workflows/merge-upstream/workflow.yaml b/bmad/workflows/merge-upstream/workflow.yaml new file mode 100644 index 00000000..5f04374b --- /dev/null +++ b/bmad/workflows/merge-upstream/workflow.yaml @@ -0,0 +1,32 @@ +# Merge Upstream Workflow Configuration +name: "merge-upstream" +description: "Safely merge upstream repository changes while preserving critical fork modifications with automated verification and memory updates" +author: "BMad" + +# Critical variables from config +config_source: "{project-root}/bmad/core/config.yaml" +output_folder: "{config_source}:output_folder" +user_name: "{config_source}:user_name" +communication_language: "{config_source}:communication_language" +date: system-generated + +# Module path and component files +installed_path: "{project-root}/bmad/workflows/merge-upstream" +template: false # This is an action workflow - no template needed +instructions: "{installed_path}/instructions.md" +validation: "{installed_path}/checklist.md" + +# Reference documentation +modification_reference: "{project-root}/claudedocs/installer-modification-reference.md" + +# Tool Requirements +required_tools: + - "Git": + description: "Version control system for merge operations" + link: "https://git-scm.com/" + - "Serena MCP": + description: "Project memory management for cross-session persistence" + link: "MCP server for project context" + - "Graphiti MCP": + description: "Knowledge graph memory for relationship tracking" + link: "MCP server for graph-based memory" diff --git a/claudedocs/installer-modification-reference.md b/claudedocs/installer-modification-reference.md new file mode 100644 index 00000000..18520403 --- /dev/null +++ b/claudedocs/installer-modification-reference.md @@ -0,0 +1,50 @@ +# Critical Installer Modification Reference + +**Date**: 2025-10-18 +**File**: `tools/cli/installers/lib/core/installer.js` +**Lines**: 913-916 +**Backup Branch**: backup-before-pull-20251018-133852 + +## Modification Code + +```javascript +// Skip workflow instructions.md files to preserve user customizations +if (file.includes('workflows/') && file.endsWith('instructions.md')) { + continue; +} +``` + +## Insertion Point + +This code MUST be inserted in the `copyDirectoryWithFiltering()` method, immediately after the config.yaml skip block: + +```javascript +// Skip config.yaml templates - we'll generate clean ones with actual values +if (file === 'config.yaml' || file.endsWith('/config.yaml')) { + continue; +} + +// ← INSERT THE 4-LINE MODIFICATION HERE + +const sourceFile = path.join(sourcePath, file); +``` + +## Purpose + +- Prevents workflow instructions.md files from being overwritten during updates +- Essential for teachflow module to be detected by ModuleManager.listAvailable() +- Without this, user customizations in workflow instructions are lost + +## Verification Command + +```bash +grep -A 2 "Skip workflow instructions" tools/cli/installers/lib/core/installer.js +``` + +Expected output: + +``` +// Skip workflow instructions.md files to preserve user customizations +if (file.includes('workflows/') && file.endsWith('instructions.md')) { + continue; +```