Merge 59608d360a into e37edf098c

Introduces Ring of Fire Sessions feature for BMad Method, enabling
multi-agent collaborative sessions that run in parallel to user workflow.

Key features:
- User-controlled scope (2 agents/5min to 10 agents/2hrs)
- Approval-gated tool access for safety
- Flexible reporting (brief/detailed/live)
- Parallel workflow support

Origin: tellingCube project (masemIT e.U.)
Real-world validated with successful multi-agent planning sessions.

Command: *rof "<topic>" --agents <list> [--report mode]

docs/ring-of-fire-sessions.md

@@ -0,0 +1,256 @@
+# BMad Method PR #1: Ring of Fire (ROF) Sessions
+
+**Feature Type**: Core workflow enhancement
+**Status**: Draft for community review
+**Origin**: tellingCube project (masemIT e.U.)
+**Author**: Mario Semper (@sempre)
+**Date**: 2025-11-23
+
+---
+
+## Summary
+
+**Ring of Fire (ROF) Sessions** enable multi-agent collaborative sessions that run in parallel to the user's main workflow, allowing users to delegate complex multi-perspective analysis while continuing other work.
+
+---
+
+## Problem Statement
+
+Current BMad Method requires **sequential agent interaction**. When users need multiple agents to collaborate on a complex topic, they must:
+- Manually orchestrate each agent conversation
+- Stay in the loop for every exchange
+- Wait for sequential responses before proceeding
+- Context-switch constantly between tasks
+
+This creates **bottlenecks** and prevents **parallel work streams**.
+
+---
+
+## Proposed Solution: Ring of Fire Sessions
+
+A new command pattern that enables **scoped multi-agent collaboration sessions** that run while the user continues other work.
+
+### Command Syntax
+
+```bash
+*rof "<topic>" --agents <agent-list> [--report brief|detailed|live]
+```
+
+### Example Usage
+
+```bash
+*rof "API Refactoring Strategy" --agents dev,architect,qa --report brief
+```
+
+**What happens**:
+1. Dev, Architect, and QA agents enter a collaborative session
+2. They analyze the topic together (code review, design discussion, testing concerns)
+3. When agents need tool access (read files, run commands), they request user approval
+4. User continues working on other tasks in parallel
+5. Session ends with consolidated report (brief: just recommendations, detailed: full transcript)
+
+---
+
+## Key Features
+
+### 1. User-Controlled Scope
+- **Small**: 2 agents, 5-minute quick discussion
+- **Large**: 10 agents, 2-hour deep analysis
+- User decides granularity based on complexity
+
+### 2. Approval-Gated Tool Access
+- Agents can **discuss** freely within the session
+- When agents need **tools** (read files, execute commands, make changes), they:
+  - Pause the session
+  - Request user approval
+  - Resume after user decision
+
+**Why**: Maintains user control, prevents runaway agent actions
+
+### 3. Flexible Reporting
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `brief` | Final recommendations only | "Just tell me what to do" |
+| `detailed` | Full transcript + recommendations | "Show me the reasoning" |
+| `live` | Real-time updates as agents discuss | "I want to observe" |
+
+**Default**: `brief` with Q&A available
+
+### 4. Parallel Workflows
+- User works on **Task A** while ROF session tackles **Task B**
+- No context-switching overhead
+- Efficient use of time
+
+---
+
+## Use Cases
+
+### 1. Architecture Reviews
+```bash
+*rof "Evaluate microservices vs monolith for new feature" --agents architect,dev,qa
+```
+**Agents collaborate on**: Design trade-offs, implementation complexity, testing implications
+
+### 2. Code Refactoring
+```bash
+*rof "Refactor authentication module" --agents dev,architect --report detailed
+```
+**Agents collaborate on**: Current code analysis, refactoring approach, migration strategy
+
+### 3. Feature Planning
+```bash
+*rof "Plan user notifications feature" --agents pm,ux,dev --report brief
+```
+**Agents collaborate on**: Requirements, UX flow, technical feasibility, timeline
+
+### 4. Quality Gates
+```bash
+*rof "Investigate test failures in CI/CD" --agents qa,dev --report live
+```
+**Agents collaborate on**: Root cause analysis, fix recommendations, regression prevention
+
+### 5. Documentation Sprints
+```bash
+*rof "Document API endpoints" --agents dev,pm,ux
+```
+**Agents collaborate on**: Technical accuracy, user-friendly examples, completeness
+
+---
+
+## User Experience Flow
+
+```mermaid
+sequenceDiagram
+    User->>River: *rof "Topic" --agents dev,architect
+    River->>Dev: Join ROF session
+    River->>Architect: Join ROF session
+    River->>User: Session started, continue your work
+
+    Dev->>Architect: Discuss approach
+    Architect->>Dev: Suggest alternatives
+
+    Dev->>User: Need to read auth.ts - approve?
+    User->>Dev: Approved
+    Dev->>Architect: After reading file...
+
+    Architect->>Dev: Recommendation
+    Dev->>River: Session complete
+    River->>User: Brief report: [Recommendations]
+```
+
+---
+
+## Implementation Considerations
+
+### Technical Requirements
+- **Session state management**: Track active ROF sessions, participating agents
+- **Agent context sharing**: Agents share knowledge within session scope
+- **User approval workflow**: Clear prompt for tool requests
+- **Report generation**: Brief/detailed/live output formatting
+- **Workflow integration**: Link ROF findings to existing workflow plans/todos
+
+### Open Questions for Community
+
+1. **Integration**: Core BMad feature or plugin/extension?
+2. **Concurrency**: How to handle file conflicts if multiple agents want to edit?
+3. **Cost Model**: Guidance for LLM call budgeting with multiple agents?
+4. **Session Limits**: Recommended max agents/duration?
+5. **Agent Communication**: Free-form discussion or structured turn-taking?
+
+---
+
+## Real-World Validation
+
+**Origin Project**: tellingCube (BI dashboard, masemIT e.U.)
+
+**Validation Scenario**:
+- **Topic**: "Next steps for tellingCube after validation test"
+- **Agents**: River (orchestrator), Mary (analyst), Winston (architect)
+- **Report Mode**: Brief
+- **Outcome**: Successfully analyzed post-validation roadmap with 3 scenarios (GO/CHANGE/NO-GO), delivered consolidated recommendations in 5 minutes
+
+**User Feedback (Mario Semper)**:
+> "This is exactly what I needed - I wanted multiple perspectives without having to orchestrate every conversation. The brief report gave me actionable next steps immediately."
+
+**Documentation**: `docs/_masemIT/readme.md` in tellingCube repository
+
+---
+
+## Proposed Documentation Structure
+
+```
+.bmad-core/
+  features/
+    ring-of-fire.md              # Feature specification
+
+docs/
+  guides/
+    using-rof-sessions.md        # User guide with examples
+
+  architecture/
+    agent-collaboration.md       # Technical design
+    rof-session-management.md    # State handling approach
+```
+
+---
+
+## Benefits
+
+✅ **Unlocks parallel workflows** - User productivity gains
+✅ **Reduces context-switching** - Cognitive load reduction
+✅ **Enables complex analysis** - Multi-perspective insights
+✅ **Maintains user control** - Approval gates for tools
+✅ **Scales flexibly** - From quick checks to deep dives
+
+---
+
+## Comparison to Existing Patterns
+
+| Feature | Standard Agent Use | ROF Session |
+|---------|-------------------|-------------|
+| Agent collaboration | Sequential (one at a time) | Parallel (multiple simultaneously) |
+| User involvement | Required for every exchange | Only for approvals |
+| Parallel work | No (user waits) | Yes (user continues tasks) |
+| Output | Chat transcript | Consolidated report |
+| Use case | Single-perspective tasks | Multi-perspective analysis |
+
+---
+
+## Next Steps
+
+1. **Community feedback** on approach and open questions
+2. **Technical design** refinement (state management, agent communication)
+3. **Prototype implementation** in BMad core or as extension
+4. **Beta testing** with real projects (beyond tellingCube)
+5. **Documentation** completion with examples
+
+---
+
+## Alternatives Considered
+
+### Alt 1: "Breakout Session"
+- **Pros**: Clear meeting metaphor
+- **Cons**: Less evocative, doesn't convey "continuous collaborative space"
+
+### Alt 2: "Agent Huddle"
+- **Pros**: Short, casual
+- **Cons**: Implies quick/informal only
+
+### Alt 3: "Lagerfeuer" (original German name)
+- **Pros**: Warm, campfire metaphor
+- **Cons**: Poor i18n, hard to pronounce/remember for non-German speakers
+
+**Chosen**: **Ring of Fire** - evokes continuous collaboration circle, internationally understood, memorable, shortcut "ROF" works well
+
+---
+
+## References
+
+- **Source Project**: tellingCube (https://github.com/masemIT/telling-cube) [if public]
+- **Documentation**: `docs/_masemIT/readme.md`
+- **Discussion**: [Link to BMad community discussion if applicable]
+
+---
+
+**Contribution ready for review.** Feedback welcome! 🔥

tools/cli/lib/ui.js

@@ -241,7 +241,35 @@ class UI {
         }
 
         // After module selection, ask about custom modules
-        const customModuleResult = await this.handleCustomModulesInModifyFlow(confirmedDirectory, selectedModules);
+        console.log('');
+        const { changeCustomModules } = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'changeCustomModules',
+            message: 'Modify custom module selection (add, update, or remove custom modules/agents/workflows)?',
+            default: false,
+          },
+        ]);
+
+        let customModuleResult = { selectedCustomModules: [], customContentConfig: { hasCustomContent: false } };
+        if (changeCustomModules) {
+          customModuleResult = await this.handleCustomModulesInModifyFlow(confirmedDirectory, selectedModules);
+        } else {
+          // Preserve existing custom modules if user doesn't want to modify them
+          const { Installer } = require('../installers/lib/core/installer');
+          const installer = new Installer();
+          const { bmadDir } = await installer.findBmadDir(confirmedDirectory);
+
+          const cacheDir = path.join(bmadDir, '_config', 'custom');
+          if (await fs.pathExists(cacheDir)) {
+            const entries = await fs.readdir(cacheDir, { withFileTypes: true });
+            for (const entry of entries) {
+              if (entry.isDirectory()) {
+                customModuleResult.selectedCustomModules.push(entry.name);
+              }
+            }
+          }
+        }
 
         // Merge any selected custom modules
         if (customModuleResult.selectedCustomModules.length > 0) {
@@ -1322,26 +1350,35 @@ class UI {
       customContentConfig: { hasCustomContent: false },
     };
 
-    if (cachedCustomModules.length === 0) {
-      return result;
-    }
-
     // Ask user about custom modules
     console.log(chalk.cyan('\n⚙️  Custom Modules'));
+    if (cachedCustomModules.length > 0) {
       console.log(chalk.dim('Found custom modules in your installation:'));
+    } else {
+      console.log(chalk.dim('No custom modules currently installed.'));
+    }
+
+    // Build choices dynamically based on whether we have existing modules
+    const choices = [];
+    if (cachedCustomModules.length > 0) {
+      choices.push(
+        { name: 'Keep all existing custom modules', value: 'keep' },
+        { name: 'Select which custom modules to keep', value: 'select' },
+        { name: 'Add new custom modules', value: 'add' },
+        { name: 'Remove all custom modules', value: 'remove' },
+      );
+    } else {
+      choices.push({ name: 'Add new custom modules', value: 'add' }, { name: 'Cancel (no custom modules)', value: 'cancel' });
+    }
 
     const { customAction } = await inquirer.prompt([
       {
         type: 'list',
         name: 'customAction',
-        message: 'What would you like to do with custom modules?',
+        message:
-        choices: [
+          cachedCustomModules.length > 0 ? 'What would you like to do with custom modules?' : 'Would you like to add custom modules?',
-          { name: 'Keep all existing custom modules', value: 'keep' },
+        choices: choices,
-          { name: 'Select which custom modules to keep', value: 'select' },
+        default: cachedCustomModules.length > 0 ? 'keep' : 'add',
-          { name: 'Add new custom modules', value: 'add' },
-          { name: 'Remove all custom modules', value: 'remove' },
-        ],
-        default: 'keep',
       },
     ]);
 
@@ -1374,19 +1411,9 @@ class UI {
       }
 
       case 'add': {
-        // First ask to keep existing ones
+        // By default, keep existing modules when adding new ones
-        const { keepExisting } = await inquirer.prompt([
+        // User chose "Add new" not "Replace", so we assume they want to keep existing
-          {
-            type: 'confirm',
-            name: 'keepExisting',
-            message: 'Keep existing custom modules?',
-            default: true,
-          },
-        ]);
-
-        if (keepExisting) {
         result.selectedCustomModules = cachedCustomModules.map((m) => m.id);
-        }
 
         // Then prompt for new ones (reuse existing method)
         const newCustomContent = await this.promptCustomContentSource();
@@ -1402,6 +1429,12 @@ class UI {
         console.log(chalk.yellow('All custom modules will be removed from the installation'));
         break;
       }
+
+      case 'cancel': {
+        // User cancelled - no custom modules
+        console.log(chalk.dim('No custom modules will be added'));
+        break;
+      }
     }
 
     return result;