From 2326f728031a5bb18e3f59e9547648ec3005a7e4 Mon Sep 17 00:00:00 2001 From: Caleb <46907094+rotationalphysics495@users.noreply.github.com> Date: Sat, 17 Jan 2026 06:34:49 -0600 Subject: [PATCH] docs: add party-mode integration and UAT implementation planning docs - Add party-mode integration planning documentation: - README overview with benefits analysis - Context management architecture spec - File modifications specification - Add UAT workflow implementation plan covering P0/P1/P2 gaps Co-Authored-By: Claude Opus 4.5 --- .../02-context-management.md | 598 ++++++++ .../03-file-modifications.md | 1265 +++++++++++++++++ .../party-mode-integration/README.md | 137 ++ docs/improvements/uat-implementation-plan.md | 709 +++++++++ 4 files changed, 2709 insertions(+) create mode 100644 docs/improvements/party-mode-integration/02-context-management.md create mode 100644 docs/improvements/party-mode-integration/03-file-modifications.md create mode 100644 docs/improvements/party-mode-integration/README.md create mode 100644 docs/improvements/uat-implementation-plan.md diff --git a/docs/improvements/party-mode-integration/02-context-management.md b/docs/improvements/party-mode-integration/02-context-management.md new file mode 100644 index 000000000..2888a29d2 --- /dev/null +++ b/docs/improvements/party-mode-integration/02-context-management.md @@ -0,0 +1,598 @@ +# Context Management Deep Dive + +**Document**: 02-context-management.md +**Version**: 1.0.0 +**Date**: 2026-01-03 + +--- + +## Overview + +This document explains how context isolation works in the epic-execute workflow and how Party Mode integration maintains this architecture while enabling multi-agent collaboration. + +--- + +## Current Context Architecture + +### The Shell as Orchestrator + +The epic-execute workflow uses **shell orchestration** to create context isolation between phases. The shell script (`epic-execute.sh`) is the central coordinator that: + +1. Reads story files from disk +2. Builds prompt strings with story contents embedded +3. Invokes Claude in isolated sessions +4. Captures output and parses for completion signals +5. Manages git staging between phases + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ SHELL ORCHESTRATION MODEL │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ epic-execute.sh (Shell - The "Memory") │ +│ │ │ +│ ├── Reads: story files, epic files, config │ +│ ├── Writes: logs, status updates │ +│ ├── Manages: git staging area │ +│ │ │ +│ └── For each phase: │ +│ ├── Build prompt string (inject file contents) │ +│ ├── Invoke: claude --dangerously-skip-permissions -p "$prompt" │ +│ ├── Capture stdout/stderr │ +│ ├── Parse for signals (COMPLETE, BLOCKED, PASSED, FAILED) │ +│ └── Decide next action based on result │ +│ │ +│ Each Claude invocation = FRESH CONTEXT (no conversation history) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Why Context Isolation Matters + +**Problem it solves**: Reviewer bias + +If the reviewer (Context B) could see the developer's (Context A) struggles, dead-ends, and thought process, they would: +- Be biased toward the implementation approach taken +- Miss issues because they "understand" why shortcuts were made +- Not simulate a real code review where reviewers see code "cold" + +**Solution**: Each phase runs in a completely fresh Claude session with no shared conversation history. + +--- + +## Context Transfer Mechanisms + +Since contexts are isolated, information must flow through **persistent storage**: + +| Mechanism | What It Carries | Direction | +|-----------|-----------------|-----------| +| **Git staging** | Actual code changes | Dev → Review | +| **Story file** | Dev Agent Record, Code Review Record, Status | All phases | +| **Prompt injection** | Story contents, context, instructions | Shell → Claude | +| **Output parsing** | Success/failure signals | Claude → Shell | +| **Log file** | Full Claude responses (optional) | Claude → Disk | + +### Transfer Flow Diagram + +``` +┌─────────────┐ +│ Shell │ +│ Orchestrator│ +└──────┬──────┘ + │ + │ 1. Read story file + │ 2. Build prompt with contents + │ 3. Invoke Claude + ▼ +┌─────────────┐ +│ Context A │ +│ (Dev) │ +│ │ +│ - Reads story from prompt +│ - Writes code +│ - Runs: git add -A +│ - Updates story file (Dev Agent Record) +│ - Outputs: IMPLEMENTATION COMPLETE +│ │ +└──────┬──────┘ + │ + │ ┌─────────────────────────────────┐ + │ │ Transfer via: │ + │ │ - Git staging (code) │ + │ │ - Story file (Dev Agent Record) │ + │ └─────────────────────────────────┘ + │ + │ 4. Shell reads story file again + │ 5. Builds new prompt + │ 6. Invokes NEW Claude session + ▼ +┌─────────────┐ +│ Context B │ +│ (Review) │ +│ │ +│ - Reads story from prompt (includes Dev Agent Record) +│ - Runs: git diff --staged (sees code) +│ - Has NO memory of dev phase +│ - Reviews "cold" +│ - Updates story file (Code Review Record) +│ - Outputs: REVIEW PASSED/FAILED +│ │ +└──────┬──────┘ + │ + ▼ +┌─────────────┐ +│ Shell │ +│ (Commit) │ +│ │ +│ git commit -m "..." +└─────────────┘ +``` + +--- + +## How Party Mode Extends This + +Party Mode adds **additional isolated contexts** at specific workflow points without breaking the isolation model. + +### Enhanced Context Flow + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ ENHANCED CONTEXT FLOW │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ epic-execute.sh (Shell - Orchestrator) │ +│ │ +│ Per Story: │ +│ ┌─────────────┐ │ +│ │ CONTEXT 0 │ ← NEW: Party Kickoff (--party-kickoff) │ +│ │ (Kickoff) │ │ +│ │ │ Input: Story file │ +│ │ │ Output: Insights → APPENDED to story file │ +│ │ │ Signal: KICKOFF COMPLETE │ +│ └──────┬──────┘ │ +│ │ │ +│ │ Transfer: Story file now contains Kickoff Insights section │ +│ │ │ +│ ▼ │ +│ ┌─────────────┐ │ +│ │ CONTEXT A │ ← EXISTING: Dev phase │ +│ │ (Dev) │ │ +│ │ │ Input: Story file (NOW includes kickoff insights) │ +│ │ │ Output: Code staged, Dev Agent Record │ +│ │ │ Signal: IMPLEMENTATION COMPLETE/BLOCKED │ +│ └──────┬──────┘ │ +│ │ │ +│ │ Transfer: Git staging + Story file updated │ +│ │ │ +│ ▼ │ +│ ┌─────────────┐ │ +│ │ CONTEXT B │ ← MODIFIED: Standard review OR Party Review │ +│ │ (Review) │ │ +│ │ │ Input: Story file + git diff --staged │ +│ │ │ Output: Code Review Record, fixes staged │ +│ │ │ Signal: REVIEW PASSED/FAILED │ +│ └──────┬──────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────┐ │ +│ │ Shell │ ← EXISTING: Commit │ +│ │ (Commit) │ git commit │ +│ └─────────────┘ │ +│ │ +│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ FAILURE PATH ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ +│ │ +│ If Dev or Review outputs BLOCKED/FAILED: │ +│ ┌─────────────┐ │ +│ │ CONTEXT F │ ← NEW: Failure Analysis (--party-failure) │ +│ │ (Failure) │ │ +│ │ │ Input: Story file + failure message │ +│ │ │ Output: Analysis Record → appended to story │ +│ │ │ Signal: ANALYSIS COMPLETE + recommendation │ +│ └─────────────┘ │ +│ │ +│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ POST-EPIC ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ +│ │ +│ After all stories: │ +│ ┌─────────────┐ │ +│ │ CONTEXT C │ ← EXISTING: UAT Generation │ +│ │ (UAT) │ │ +│ └─────────────┘ │ +│ │ +│ ┌─────────────┐ │ +│ │ CONTEXT R │ ← NEW: Party Retrospective (--party-retro) │ +│ │ (Retro) │ │ +│ │ │ Input: ALL story files + epic file (read-only) │ +│ │ │ Output: Retro doc + handoff doc (new files) │ +│ │ │ Signal: RETRO COMPLETE │ +│ └─────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Detailed Transfer Specifications + +### A. Kickoff → Dev Transfer + +**What gets transferred**: Kickoff Insights (architectural notes, implementation strategy, testing approach, identified risks) + +**Transfer mechanism**: Kickoff context appends a new section to the story file + +```markdown +## Story Kickoff Insights + +**Discussion Date**: 2026-01-03 +**Participants**: Winston (Architect), Amelia (Developer), Murat (Test Architect) + +### Architectural Notes +- Consider using existing auth middleware pattern from lib/auth/ +- Integration point: /api/v1/users endpoint +- Watch for rate limiting constraints on external API + +### Implementation Strategy +- Extend UserService class rather than creating new +- Reuse validation utilities from lib/validators +- Follow repository pattern established in src/repositories/ + +### Testing Approach +- Unit tests for service methods (Jest) +- Integration test for full user flow +- Mock external API calls using existing fixtures + +### Identified Risks +- Rate limiting not yet implemented for external API +- Database migration needed for new user fields +``` + +**Dev context sees**: Story file with the above section included. The prompt says "Read the story file completely before writing any code" - so dev agent has access to kickoff insights. + +**Why this works**: Dev agent can leverage the multi-agent discussion without those agents being in its context window. + +--- + +### B. Dev → Review Transfer (Unchanged) + +**What gets transferred**: +1. Code changes (via git staging) +2. Dev Agent Record (via story file) + +**Transfer mechanism**: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Dev Context writes: │ +│ │ +│ 1. Code files → git add -A (staged, not committed) │ +│ │ +│ 2. Story file updated with: │ +│ ## Dev Agent Record │ +│ │ +│ ### Implementation Summary │ +│ Added user registration endpoint with email verification │ +│ │ +│ ### Files Created │ +│ - src/services/UserService.ts - User registration logic │ +│ - src/routes/users.ts - REST endpoints │ +│ │ +│ ### Files Modified │ +│ - src/app.ts - Added user routes │ +│ │ +│ ### Key Decisions │ +│ - Used bcrypt for password hashing (industry standard) │ +│ - Async email verification (non-blocking) │ +│ │ +│ ### Tests Added │ +│ - test/services/UserService.test.ts │ +│ │ +│ ### Notes for Reviewer │ +│ - Email templates need design review │ +│ - Rate limiting deferred to next story │ +│ │ +│ 3. Outputs: IMPLEMENTATION COMPLETE: story-42-1 │ +└─────────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ Review Context receives (via prompt injection): │ +│ │ +│ 1. Story file contents (includes Dev Agent Record) │ +│ 2. Instructions to run: git diff --staged │ +│ │ +│ Review Context has NO knowledge of: │ +│ - Dead-ends the dev tried │ +│ - Time spent debugging │ +│ - Alternative approaches considered │ +│ - Frustrations or workarounds │ +│ │ +│ This is intentional - reviewer sees code "cold" │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### C. Party Review vs Standard Review + +The difference is in **prompt content**, not transfer mechanism. + +**Standard Review Prompt** (current): +``` +You are a Senior Code Reviewer performing a BMAD code review. + +## Your Task +Review the implementation of story: {story_id} +You are seeing this code for the first time... +``` + +**Party Review Prompt** (new): +``` +You are orchestrating a Party Code Review with multiple BMAD agents. + +## Participating Agents + +### Winston (Architect) +- Focus: Pattern adherence, scalability, API design consistency +- Communication style: Calm, pragmatic, balances "what could be" with "what should be" + +### Murat (Test Architect) +- Focus: Test coverage, security vulnerabilities, edge cases +- Communication style: Data-driven, "strong opinions weakly held", risk calculations + +### Amelia (Developer) +- Focus: Code quality, readability, maintainability, error handling +- Communication style: [from agent definition] + +## Your Task + +1. Run: git diff --staged +2. For each agent, generate their review perspective in character +3. Facilitate cross-discussion where agents reference each other +4. Build consensus on issues and fixes +5. Apply the same severity-based fix policy +6. Generate unified Party Review Record + +## Output Format + +Each agent reviews, then they discuss: + +🏗️ **Winston**: "Looking at the architecture, I see..." + +🧪 **Murat**: "From a testing perspective, Winston raises a good point about..." + +💻 **Amelia**: "I agree with Murat on test coverage. Additionally..." + +### Consensus +[Unified findings after discussion] +``` + +**Same inputs**: Story file + git diff +**Same outputs**: Code Review Record in story file, PASSED/FAILED signal +**Different process**: Multi-perspective analysis within the prompt + +--- + +### D. Failure Analysis Context + +**Trigger**: Dev or Review outputs BLOCKED/FAILED signal + +**What gets transferred**: +1. Story file (current state, may have partial Dev Agent Record) +2. Failure type ("dev" or "review") +3. Failure message extracted from output + +```bash +# In shell script +if echo "$result" | grep -q "IMPLEMENTATION BLOCKED"; then + # Extract failure reason + failure_msg=$(echo "$result" | grep "IMPLEMENTATION BLOCKED" | sed 's/.*BLOCKED: [^ ]* - //') + + if [ "$PARTY_FAILURE" = true ]; then + execute_party_failure_analysis "$story_file" "dev" "$failure_msg" + fi +fi +``` + +**Failure Analysis Context receives**: +``` +## Failed Story + +{story_file_contents} + + +## Failure Information +- **Type**: dev phase +- **Signal**: IMPLEMENTATION BLOCKED +- **Message**: "Cannot resolve circular dependency between UserService and AuthService" + +## Participating Agents +- Winston (Architect): Assess if this is an architectural issue +- Amelia (Developer): Assess if this is an implementation issue +- Bob (Scrum Master): Assess if this is a requirements/process issue +``` + +**Output**: Failure Analysis Record appended to story + recommendation (Retry | Skip | Escalate) + +--- + +### E. Retrospective Context (Post-Epic) + +**Trigger**: All stories completed (or `--party-retro` flag with completed epic) + +**What gets transferred** (read-only, aggregated): + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Retro Context receives: │ +│ │ +│ 1. Epic file │ +│ - Epic description, goals, scope │ +│ │ +│ 2. ALL story files, each containing: │ +│ - Original specification │ +│ - Kickoff Insights (if --party-kickoff was used) │ +│ - Dev Agent Record │ +│ - Code Review Record (standard or party) │ +│ - Failure Analysis Record (if any failures occurred) │ +│ │ +│ 3. Execution summary │ +│ - Stories completed: 8 │ +│ - Stories failed: 1 │ +│ - Total duration: 45 minutes │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Output** (creates new files): + +``` +docs/sprints/epic-42-retro.md # Retrospective insights +docs/handoffs/epic-42-handoff.md # Context for next epic (used by epic-chain) +``` + +--- + +## Context Window Considerations + +### Current Approach: Prompt Injection + +Each context receives its input via prompt injection - the shell script reads files and embeds their contents in the prompt string: + +```bash +local story_contents=$(cat "$story_file") + +local dev_prompt="You are the Dev agent... + +## Story Specification + + +$story_contents + + +## Implementation Requirements +..." +``` + +**Advantage**: Full control over what each context sees +**Limitation**: Large stories or many files can consume significant context window + +### Party Mode Implications + +Party phases add context window usage: + +| Phase | Additional Context Load | +|-------|------------------------| +| Kickoff | Agent personas (~500 tokens) + discussion instructions | +| Party Review | 3x agent personas + cross-talk instructions | +| Failure Analysis | Agent personas + failure context | +| Retrospective | ALL story files aggregated (potentially large) | + +**Mitigation strategies**: + +1. **Selective loading**: Only include relevant agent personas, not full manifests +2. **Summary injection**: For retro, summarize stories rather than full contents +3. **Timeout configuration**: Allow configuration of max tokens per phase + +--- + +## Data Flow Summary + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ DATA FLOW SUMMARY │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ PERSISTENT STORAGE (survives across contexts) │ +│ ├── Story files (.md) │ +│ │ ├── Original spec │ +│ │ ├── Kickoff Insights (written by Context 0) │ +│ │ ├── Dev Agent Record (written by Context A) │ +│ │ ├── Code Review Record (written by Context B) │ +│ │ └── Failure Analysis Record (written by Context F) │ +│ │ │ +│ ├── Git staging area │ +│ │ └── Code changes (written by Context A, read by Context B) │ +│ │ │ +│ ├── Git commits │ +│ │ └── Committed code (written by Shell after Context B passes) │ +│ │ │ +│ └── Output files │ +│ ├── docs/uat/epic-{id}-uat.md (written by Context C) │ +│ ├── docs/sprints/epic-{id}-retro.md (written by Context R) │ +│ └── docs/handoffs/epic-{id}-handoff.md (written by Context R) │ +│ │ +│ EPHEMERAL (exists only during context execution) │ +│ ├── Conversation history (per context, not shared) │ +│ ├── Tool call results (per context) │ +│ └── Working memory (per context) │ +│ │ +│ SHELL VARIABLES (orchestrator state) │ +│ ├── STORIES array │ +│ ├── COMPLETED/FAILED counters │ +│ ├── Flag states (PARTY_KICKOFF, etc.) │ +│ └── Current story pointer │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Key Design Principles + +### 1. File System as the Bridge + +All context transfer happens via the file system. This is intentional: +- Git staging for code +- Markdown files for documentation/records +- No shared memory or conversation history + +### 2. Append-Only Story Files + +Each phase appends to the story file rather than replacing. This creates an audit trail: +``` +Story File +├── Original Spec (created during planning) +├── Kickoff Insights (appended by kickoff party) +├── Dev Agent Record (appended by dev phase) +├── Code Review Record (appended by review phase) +└── Failure Analysis (appended if failure occurred) +``` + +### 3. Signals for Flow Control + +Each context outputs a specific signal that the shell parses: +- `KICKOFF COMPLETE: story-id` +- `IMPLEMENTATION COMPLETE: story-id` +- `IMPLEMENTATION BLOCKED: story-id - reason` +- `REVIEW PASSED: story-id` +- `REVIEW PASSED WITH FIXES: story-id - Fixed N issues` +- `REVIEW FAILED: story-id - reason` +- `ANALYSIS COMPLETE: story-id - Retry|Skip|Escalate` +- `RETRO COMPLETE: Epic epic-id` + +### 4. Non-Blocking Optional Phases + +Party phases are designed to be non-blocking: +- Kickoff failure → Continue to dev (insights are helpful but not required) +- Failure analysis → Informational (doesn't change retry/skip decision) +- Retro failure → Log warning, epic still considered complete + +--- + +## Testing Context Isolation + +To verify context isolation is maintained: + +```bash +# Test 1: Verify dev context doesn't see review instructions +./epic-execute.sh test-epic --dry-run --verbose 2>&1 | grep -A 50 "DEV PHASE" +# Should NOT contain "Code Review" or "severity" language + +# Test 2: Verify review context doesn't see dev struggles +./epic-execute.sh test-epic --dry-run --verbose 2>&1 | grep -A 50 "REVIEW PHASE" +# Should contain "You are seeing this code for the first time" + +# Test 3: Verify party kickoff writes to story file +./epic-execute.sh test-epic --party-kickoff --dry-run +cat docs/stories/test-story.md | grep "Story Kickoff Insights" +# Should find the section +``` diff --git a/docs/improvements/party-mode-integration/03-file-modifications.md b/docs/improvements/party-mode-integration/03-file-modifications.md new file mode 100644 index 000000000..878734638 --- /dev/null +++ b/docs/improvements/party-mode-integration/03-file-modifications.md @@ -0,0 +1,1265 @@ +# File Modifications Specification + +**Document**: 03-file-modifications.md +**Version**: 1.0.0 +**Date**: 2026-01-03 + +--- + +## Overview + +This document provides the detailed specification for all file modifications required to implement Party Mode integration with Epic Execute. + +--- + +## Summary of Changes + +| File | Change Type | Lines Affected | Priority | +|------|-------------|----------------|----------| +| `scripts/epic-execute.sh` | Modify | +150 lines | Phase 1-3 | +| `config/default-config.yaml` | Modify | +50 lines | Phase 1 | +| `steps/step-01b-party-kickoff.md` | Create | ~100 lines | Phase 1 | +| `steps/step-03b-party-review.md` | Create | ~150 lines | Phase 2 | +| `steps/step-02b-party-failure.md` | Create | ~100 lines | Phase 3 | +| `steps/step-05b-party-retro.md` | Create | ~120 lines | Phase 4 | +| `workflow.md` | Modify | +20 lines | Phase 4 | + +**Total**: ~690 lines across 7 files + +--- + +## 1. Shell Script Modifications + +### File: `scripts/epic-execute.sh` + +#### 1.1 New Variables (Insert after line 76) + +**Location**: After existing flag variables, before argument parsing + +```bash +# ============================================================================= +# Party Mode Flags +# ============================================================================= + +PARTY_KICKOFF=false +PARTY_REVIEW=false +PARTY_FAILURE=false +PARTY_RETRO=false +PARTY_AGENTS="" +``` + +--- + +#### 1.2 Argument Parsing (Insert within existing while loop, ~line 79-118) + +**Location**: Add new cases to existing `while [[ $# -gt 0 ]]; do` block + +```bash + --party-kickoff) + PARTY_KICKOFF=true + shift + ;; + --party-review) + PARTY_REVIEW=true + shift + ;; + --party-failure) + PARTY_FAILURE=true + shift + ;; + --party-retro) + PARTY_RETRO=true + shift + ;; + --party-all) + PARTY_KICKOFF=true + PARTY_REVIEW=true + PARTY_FAILURE=true + PARTY_RETRO=true + shift + ;; + --party-agents) + PARTY_AGENTS="$2" + shift 2 + ;; +``` + +--- + +#### 1.3 Usage Text Update (Modify existing usage block, ~line 121-132) + +**Location**: Update the existing usage/help text + +```bash +if [ -z "$EPIC_ID" ]; then + echo "Usage: $0 [options]" + echo "" + echo "Options:" + echo " --dry-run Show what would be executed" + echo " --skip-review Skip code review phase" + echo " --no-commit Don't commit after stories" + echo " --parallel Parallel execution (experimental)" + echo " --verbose Detailed output" + echo " --start-from ID Start from a specific story (e.g., 31-2)" + echo " --skip-done Skip stories with Status: Done" + echo "" + echo "Party Mode Options:" + echo " --party-kickoff Enable Story Kickoff Party before dev phase" + echo " --party-review Enable multi-agent Party Review (replaces standard)" + echo " --party-failure Enable Failure Analysis Party on blocked stories" + echo " --party-retro Enable Post-Epic Retrospective Party" + echo " --party-all Enable all party phases" + echo " --party-agents Override agents (comma-separated, e.g., 'Winston,Murat')" + exit 1 +fi +``` + +--- + +#### 1.4 New Functions (Insert after line 230, before `execute_dev_phase`) + +**Location**: New section for party mode functions + +```bash +# ============================================================================= +# Party Mode Functions +# ============================================================================= + +execute_party_kickoff() { + local story_file="$1" + local story_id=$(basename "$story_file" .md) + + log ">>> PARTY KICKOFF: $story_id" + + local story_contents=$(cat "$story_file") + local agents="${PARTY_AGENTS:-Winston,Amelia,Murat}" + + local kickoff_prompt="You are orchestrating a Story Kickoff Party for BMAD. + +## Participating Agents + +You will roleplay as these agents, each contributing their unique perspective: + +### Winston (Architect) +- Focus: Architectural implications, integration points, scalability concerns +- Style: Calm, pragmatic, balances 'what could be' with 'what should be' + +### Amelia (Developer) +- Focus: Implementation approach, existing patterns to follow, potential gotchas +- Style: Practical, detail-oriented, focuses on what actually ships + +### Murat (Test Architect) +- Focus: Testing strategy, edge cases, quality gates +- Style: Data-driven, risk-focused, 'strong opinions weakly held' + +## Story to Discuss + + +$story_contents + + +## Your Task + +Facilitate a focused discussion between these agents about this story BEFORE implementation begins. Each agent should contribute from their expertise area. + +Generate responses in character for each agent, allowing them to build on each other's points. + +## Output Requirements + +After the discussion, append a 'Story Kickoff Insights' section to the story file at: $story_file + +Use this exact format: + +\`\`\`markdown +## Story Kickoff Insights + +**Discussion Date**: $(date '+%Y-%m-%d') +**Participants**: Winston (Architect), Amelia (Developer), Murat (Test Architect) + +### Architectural Notes +[Winston's key points about architecture, integration, patterns] + +### Implementation Strategy +[Amelia's recommendations for implementation approach] + +### Testing Approach +[Murat's test strategy and edge cases to consider] + +### Identified Risks +- [Risk 1] +- [Risk 2] + +### Key Decisions +- [Any decisions made during discussion] +\`\`\` + +When complete, output exactly: KICKOFF COMPLETE: $story_id" + + if [ "$DRY_RUN" = true ]; then + echo "[DRY RUN] Would execute party kickoff for $story_id" + echo "[DRY RUN] Agents: $agents" + return 0 + fi + + local result + result=$(claude --dangerously-skip-permissions -p "$kickoff_prompt" 2>&1) || true + + echo "$result" >> "$LOG_FILE" + + if echo "$result" | grep -q "KICKOFF COMPLETE"; then + log_success "Party kickoff complete: $story_id" + return 0 + else + log_warn "Party kickoff did not complete cleanly (non-blocking)" + return 0 # Non-blocking - continue to dev phase + fi +} + +execute_party_review() { + local story_file="$1" + local story_id=$(basename "$story_file" .md) + + log ">>> PARTY REVIEW: $story_id (multi-agent)" + + local story_contents=$(cat "$story_file") + local agents="${PARTY_AGENTS:-Winston,Murat,Amelia}" + + local review_prompt="You are orchestrating a Party Code Review for BMAD. + +## Participating Agents + +You will roleplay as these agents conducting a collaborative code review: + +### Winston (Architect) +- Focus: Pattern adherence, scalability, API design consistency, component boundaries +- Style: Calm, pragmatic + +### Murat (Test Architect) +- Focus: Test coverage, security vulnerabilities, edge cases, quality gates +- Style: Data-driven, risk calculations + +### Amelia (Developer) +- Focus: Code quality, readability, maintainability, error handling +- Style: Practical, detail-oriented + +## Story Being Reviewed + + +$story_contents + + +## Review Process + +1. Run: git diff --staged +2. Each agent reviews from their focus area +3. Generate in-character responses for each agent +4. Allow agents to reference each other's points +5. Build consensus on issues found +6. Categorize by severity (HIGH/MEDIUM/LOW) + +## Issue Severity Definitions + +- **HIGH**: Security vulnerabilities, missing error handling, no tests, exposed credentials +- **MEDIUM**: Pattern violations, missing edge cases, hardcoded config +- **LOW**: Naming, style, missing comments + +## Issue Fix Policy + +After collecting all issues: +1. Always fix ALL HIGH severity issues +2. If TOTAL issues > 5, also fix ALL MEDIUM severity issues +3. LOW severity: document only, do NOT fix + +## Output Format + +Generate the review discussion, then update the story file with a Code Review Record: + +\`\`\`markdown +## Code Review Record + +**Review Type**: Party Review +**Date**: $(date '+%Y-%m-%d %H:%M') +**Reviewers**: Winston (Architect), Murat (Test Architect), Amelia (Developer) + +### Agent Findings + +#### Winston (Architecture) +| # | Finding | Severity | Recommendation | +|---|---------|----------|----------------| + +#### Murat (Quality) +| # | Finding | Severity | Recommendation | +|---|---------|----------|----------------| + +#### Amelia (Implementation) +| # | Finding | Severity | Recommendation | +|---|---------|----------|----------------| + +### Cross-Discussion Summary +[Key points where agents agreed/disagreed] + +### Consensus Decision +- **Total Issues**: X HIGH, Y MEDIUM, Z LOW +- **Status**: Approved | Approved with Fixes | Rejected +- **Blocking Issues**: [if any] + +### Fixes Applied +[List of fixes made] + +### Remaining Issues (Low Severity) +[Documented for future cleanup] +\`\`\` + +## Completion + +If PASSED (no unfixed HIGH/MEDIUM issues): +1. Update story Status to: Done +2. Stage changes: git add -A +3. Output: PARTY REVIEW PASSED: $story_id + +If FAILED: +1. Update story Status to: Blocked +2. Output: PARTY REVIEW FAILED: $story_id - [reason]" + + if [ "$DRY_RUN" = true ]; then + echo "[DRY RUN] Would execute party review for $story_id" + echo "[DRY RUN] Agents: $agents" + return 0 + fi + + local result + result=$(claude --dangerously-skip-permissions -p "$review_prompt" 2>&1) || true + + echo "$result" >> "$LOG_FILE" + + if echo "$result" | grep -q "PARTY REVIEW PASSED"; then + log_success "Party review passed: $story_id" + return 0 + elif echo "$result" | grep -q "PARTY REVIEW FAILED"; then + log_error "Party review failed: $story_id" + echo "$result" | grep "PARTY REVIEW FAILED" + return 1 + else + log_warn "Party review did not complete cleanly" + return 1 + fi +} + +execute_party_failure_analysis() { + local story_file="$1" + local failure_type="$2" # "dev" or "review" + local story_id=$(basename "$story_file" .md) + + log ">>> PARTY FAILURE ANALYSIS: $story_id ($failure_type phase)" + + local story_contents=$(cat "$story_file") + local agents="${PARTY_AGENTS:-Winston,Amelia,Bob}" + + local failure_prompt="You are orchestrating a Failure Analysis Party for BMAD. + +## Context + +Story $story_id failed during the $failure_type phase. + +## Participating Agents + +### Winston (Architect) +- Assess: Is this an architectural issue? Design flaw? Integration problem? + +### Amelia (Developer) +- Assess: Is this an implementation issue? Missing dependency? Code problem? + +### Bob (Scrum Master) +- Assess: Is this a requirements issue? Unclear acceptance criteria? Process gap? + +## Failed Story + + +$story_contents + + +## Failure Information + +- **Phase**: $failure_type +- **Signal**: Story did not complete successfully + +## Your Task + +1. Each agent analyzes the failure from their perspective +2. Facilitate discussion to identify root cause +3. Build consensus on the actual problem +4. Recommend action: Retry | Skip | Escalate to Human + +## Output Requirements + +Append a Failure Analysis Record to the story file: + +\`\`\`markdown +## Failure Analysis Record + +**Analysis Date**: $(date '+%Y-%m-%d %H:%M') +**Failed Phase**: $failure_type +**Analysts**: Winston, Amelia, Bob + +### Agent Assessments + +#### Winston (Architecture) +[Assessment] + +#### Amelia (Implementation) +[Assessment] + +#### Bob (Process) +[Assessment] + +### Root Cause (Consensus) +[What the team agreed is the actual problem] + +### Remediation Plan +1. [Step 1] +2. [Step 2] + +### Recommendation +**Action**: Retry | Skip | Escalate +**Rationale**: [Why this action] +\`\`\` + +When complete, output: ANALYSIS COMPLETE: $story_id - [Retry|Skip|Escalate]" + + if [ "$DRY_RUN" = true ]; then + echo "[DRY RUN] Would execute failure analysis for $story_id" + return 0 + fi + + local result + result=$(claude --dangerously-skip-permissions -p "$failure_prompt" 2>&1) || true + + echo "$result" >> "$LOG_FILE" + + if echo "$result" | grep -q "ANALYSIS COMPLETE"; then + log_success "Failure analysis complete: $story_id" + # Extract recommendation for potential future use + local recommendation=$(echo "$result" | grep "ANALYSIS COMPLETE" | sed 's/.*- //') + log "Recommendation: $recommendation" + else + log_warn "Failure analysis did not complete cleanly" + fi + + return 0 # Non-blocking - failure analysis is informational +} + +execute_party_retro() { + log ">>> PARTY RETROSPECTIVE: Epic $EPIC_ID" + + local epic_contents=$(cat "$EPIC_FILE") + local agents="${PARTY_AGENTS:-Mary,Bob,Winston,Amelia}" + + # Aggregate all story contents + local all_stories="" + for story_file in "${STORIES[@]}"; do + local story_id=$(basename "$story_file" .md) + all_stories+=" + +$(cat "$story_file") + +" + done + + local retro_prompt="You are orchestrating a Post-Epic Retrospective Party for BMAD. + +## Participating Agents + +### Mary (Business Analyst) +- Reflect on: Requirements clarity, business value delivered, stakeholder alignment + +### Bob (Scrum Master) +- Reflect on: Sprint flow, story sizing, process effectiveness, blockers encountered + +### Winston (Architect) +- Reflect on: Technical decisions made, patterns established, architectural debt + +### Amelia (Developer) +- Reflect on: Implementation experience, code quality, developer experience + +## Epic Completed + + +$epic_contents + + +## Stories Completed + +$all_stories + +## Execution Summary + +- Total Stories: ${#STORIES[@]} +- Completed: $COMPLETED +- Failed: $FAILED + +## Your Task + +Facilitate a retrospective discussion where each agent reflects from their perspective: + +1. What Went Well (each agent's view) +2. What Could Improve (each agent's view) +3. Patterns Established (for future reference) +4. Key Decisions Made (document for posterity) +5. Lessons Learned (gotchas, workarounds) +6. Context Handoff (for next epic) + +## Output Requirements + +Create TWO files: + +### 1. Retrospective Document +Save to: docs/sprints/epic-${EPIC_ID}-retro.md + +\`\`\`markdown +# Epic $EPIC_ID Retrospective + +**Date**: $(date '+%Y-%m-%d') +**Participants**: Mary, Bob, Winston, Amelia + +## What Went Well + +### Mary (Requirements) +[Points] + +### Bob (Process) +[Points] + +### Winston (Architecture) +[Points] + +### Amelia (Implementation) +[Points] + +## Areas for Improvement + +### Mary (Requirements) +[Points] + +### Bob (Process) +[Points] + +### Winston (Architecture) +[Points] + +### Amelia (Implementation) +[Points] + +## Action Items +- [ ] [Action 1] +- [ ] [Action 2] +\`\`\` + +### 2. Context Handoff Document +Save to: docs/handoffs/epic-${EPIC_ID}-handoff.md + +\`\`\`markdown +# Epic $EPIC_ID Context Handoff + +**Generated**: $(date '+%Y-%m-%d') +**For**: Next epic in chain + +## Patterns Established +| Pattern | Description | Example File | +|---------|-------------|--------------| + +## Key Decisions +| Decision | Rationale | Made By | +|----------|-----------|---------| + +## Gotchas & Lessons Learned +1. [Gotcha]: [What to watch for] + +## Files to Reference +- [Key file 1]: [Why it's important] + +## Test Patterns +[Testing conventions established] +\`\`\` + +When complete, output: RETRO COMPLETE: Epic $EPIC_ID" + + if [ "$DRY_RUN" = true ]; then + echo "[DRY RUN] Would execute party retrospective for Epic $EPIC_ID" + return 0 + fi + + # Ensure output directories exist + mkdir -p "$PROJECT_ROOT/docs/sprints" + mkdir -p "$PROJECT_ROOT/docs/handoffs" + + local result + result=$(claude --dangerously-skip-permissions -p "$retro_prompt" 2>&1) || true + + echo "$result" >> "$LOG_FILE" + + if echo "$result" | grep -q "RETRO COMPLETE"; then + log_success "Party retrospective complete" + + # Commit retro artifacts if auto-commit enabled + if [ "$NO_COMMIT" = false ]; then + git add "docs/sprints/epic-${EPIC_ID}-retro.md" 2>/dev/null || true + git add "docs/handoffs/epic-${EPIC_ID}-handoff.md" 2>/dev/null || true + git commit -m "docs(epic-$EPIC_ID): add retrospective and handoff" 2>/dev/null || true + fi + else + log_warn "Retrospective may not have completed cleanly" + fi + + return 0 # Non-blocking +} +``` + +--- + +#### 1.5 Main Loop Modifications (Modify existing loop, ~line 547-596) + +**Location**: Replace the existing main execution loop + +```bash +# ============================================================================= +# Main Execution Loop +# ============================================================================= + +log "==========================================" +log "Starting execution of ${#STORIES[@]} stories" +if [ "$PARTY_KICKOFF" = true ]; then log " Party Kickoff: ENABLED"; fi +if [ "$PARTY_REVIEW" = true ]; then log " Party Review: ENABLED"; fi +if [ "$PARTY_FAILURE" = true ]; then log " Party Failure Analysis: ENABLED"; fi +if [ "$PARTY_RETRO" = true ]; then log " Party Retrospective: ENABLED"; fi +log "==========================================" + +COMPLETED=0 +FAILED=0 +SKIPPED=0 +START_TIME=$(date +%s) +STARTED=false + +for story_file in "${STORIES[@]}"; do + story_id=$(basename "$story_file" .md) + + # --start-from: Skip stories until we reach the specified one + if [ -n "$START_FROM" ] && [ "$STARTED" = false ]; then + if [[ "$story_id" == *"$START_FROM"* ]]; then + STARTED=true + else + log_warn "Skipping $story_id (waiting for $START_FROM)" + ((SKIPPED++)) + continue + fi + fi + + # --skip-done: Skip stories with Status: Done + if [ "$SKIP_DONE" = true ]; then + if grep -q "^Status:.*Done" "$story_file" 2>/dev/null; then + log_warn "Skipping $story_id (Status: Done)" + ((SKIPPED++)) + continue + fi + fi + + echo "" + log "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + log "Story: $story_id" + log "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + + # PARTY KICKOFF (Optional - Context 0) + if [ "$PARTY_KICKOFF" = true ]; then + execute_party_kickoff "$story_file" + # Non-blocking - continues even if kickoff has issues + fi + + # DEV PHASE (Context A) + if ! execute_dev_phase "$story_file"; then + log_error "Dev phase failed for $story_id" + + # PARTY FAILURE ANALYSIS (Optional) + if [ "$PARTY_FAILURE" = true ]; then + execute_party_failure_analysis "$story_file" "dev" + fi + + ((FAILED++)) + continue + fi + + # REVIEW PHASE (Context B) + if [ "$SKIP_REVIEW" = false ]; then + if [ "$PARTY_REVIEW" = true ]; then + # Multi-agent party review + if ! execute_party_review "$story_file"; then + log_error "Party review failed for $story_id" + + # PARTY FAILURE ANALYSIS (Optional) + if [ "$PARTY_FAILURE" = true ]; then + execute_party_failure_analysis "$story_file" "review" + fi + + ((FAILED++)) + continue + fi + else + # Standard single-agent review (existing behavior) + if ! execute_review_phase "$story_file"; then + log_error "Review phase failed for $story_id" + ((FAILED++)) + continue + fi + fi + fi + + # COMMIT + commit_story "$story_id" + + ((COMPLETED++)) + log_success "Story complete: $story_id ($COMPLETED/${#STORIES[@]})" +done + +# ============================================================================= +# Post-Epic Activities +# ============================================================================= + +echo "" +log "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +log "Post-Epic Activities" +log "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + +# UAT Generation (Standard - Context C) +generate_uat + +# PARTY RETROSPECTIVE (Optional - Context R) +if [ "$PARTY_RETRO" = true ]; then + execute_party_retro +fi +``` + +--- + +## 2. Configuration File Modifications + +### File: `src/modules/bmm/workflows/4-implementation/epic-execute/config/default-config.yaml` + +**Location**: Append to end of existing file (after line 125) + +```yaml +# ============================================================================= +# Party Mode Integration +# ============================================================================= + +party: + # Story Kickoff Party - multi-agent discussion before dev phase + kickoff: + # Enable kickoff party (overridden by --party-kickoff flag) + enabled: false + + # Default agents for kickoff discussions + agents: + - Winston # Architect - architectural implications + - Amelia # Developer - implementation concerns + - Murat # Test Architect - testing strategy + + # Maximum time for kickoff discussion (seconds) + timeout: 300 + + # Where to save kickoff insights: story | separate | none + output: story + + # Party Review - replace single-agent review with multi-agent + review: + # Enable party review (overridden by --party-review flag) + enabled: false + + # Default agents for review + agents: + - Winston # Architecture alignment, patterns + - Murat # Test coverage, security + - Amelia # Code quality, maintainability + + # Maximum time for review discussion (seconds) + timeout: 600 + + # Require all agents to approve (vs majority) + consensus_required: false + + # Failure Analysis Party - triggered on story failure + failure_analysis: + # Enable failure analysis (overridden by --party-failure flag) + enabled: false + + # Default agents for failure analysis + agents: + - Winston # Architectural blockers + - Amelia # Implementation issues + - Bob # Process/requirement issues + + # Automatically trigger on any failure + auto_trigger: true + + # Post-Epic Retrospective Party + retrospective: + # Enable retrospective (overridden by --party-retro flag) + enabled: false + + # Default agents for retrospective + agents: + - Mary # Business Analyst - requirements reflection + - Bob # Scrum Master - process reflection + - Winston # Architect - technical reflection + - Amelia # Developer - implementation reflection + + # Generate context handoff document for epic-chain + generate_handoff: true + + # Output locations (relative to project root) + retro_output: docs/sprints + handoff_output: docs/handoffs + + # Global party settings + settings: + # Maximum agents per party phase (to limit context usage) + max_agents: 4 + + # Enable TTS for party responses (requires bmad-speak hook) + tts_enabled: false + + # Party output format: markdown | yaml | json + output_format: markdown + + # Log full party discussions (verbose) + log_discussions: false +``` + +--- + +## 3. New Step Files + +### File: `steps/step-01b-party-kickoff.md` + +**Location**: `src/modules/bmm/workflows/4-implementation/epic-execute/steps/` + +This file serves as documentation. The actual prompt is embedded in the shell script function. + +```markdown +# Step 1b: Story Kickoff Party (Optional) + +## Context Isolation + +This step executes in a fresh Claude context BEFORE the dev phase. It does not pollute the dev context with discussion history - only the resulting insights are transferred via the story file. + +## Objective + +Bring together 2-3 agents for a focused pre-implementation discussion to surface architectural concerns, implementation strategies, and testing approaches before code is written. + +## Trigger + +Enabled via `--party-kickoff` flag or `party.kickoff.enabled: true` in config. + +## Default Agents + +| Agent | Focus Area | +|-------|------------| +| Winston (Architect) | Architectural implications, integration points, patterns | +| Amelia (Developer) | Implementation approach, existing code to leverage | +| Murat (Test Architect) | Testing strategy, edge cases, quality gates | + +## Input + +- Story file contents (original specification) +- Agent personas from configuration + +## Output + +Appends "Story Kickoff Insights" section to the story file with: +- Architectural Notes +- Implementation Strategy +- Testing Approach +- Identified Risks +- Key Decisions + +## Transfer to Dev Phase + +The dev phase prompt instructs: "Read the story file completely before writing any code" + +This means the dev agent sees the kickoff insights and can leverage them, without the kickoff discussion consuming dev context window. + +## Completion Signal + +``` +KICKOFF COMPLETE: {story_id} +``` + +## Error Handling + +Kickoff is **non-blocking**. If it fails or times out: +- Log warning +- Continue to dev phase +- Dev phase proceeds without kickoff insights + +This design ensures kickoff adds value without becoming a critical path blocker. + +## Example Output + +```markdown +## Story Kickoff Insights + +**Discussion Date**: 2026-01-03 +**Participants**: Winston (Architect), Amelia (Developer), Murat (Test Architect) + +### Architectural Notes +- This story adds a new API endpoint; follow existing REST patterns in src/routes/ +- Consider rate limiting (deferred to Epic 43) +- Integration point with AuthService requires careful error handling + +### Implementation Strategy +- Extend existing UserService rather than creating new class +- Reuse validation utilities from lib/validators +- Follow repository pattern established in src/repositories/ + +### Testing Approach +- Unit tests for service methods using Jest +- Integration test for full request/response cycle +- Mock external API calls using fixtures in test/fixtures/ + +### Identified Risks +- External API rate limit may cause flaky tests +- Database migration required for new fields + +### Key Decisions +- Use bcrypt for password hashing (industry standard, already a dependency) +- Async email verification (non-blocking user registration flow) +``` +``` + +--- + +### File: `steps/step-03b-party-review.md` + +**Location**: `src/modules/bmm/workflows/4-implementation/epic-execute/steps/` + +```markdown +# Step 3b: Party Review (Multi-Agent Code Review) + +## Context Isolation + +This step executes in a fresh Claude context, separate from dev phase. Reviewers have no knowledge of implementation struggles - they see code "cold" via git diff. + +## Objective + +Replace single-agent code review with multi-agent collaborative review where each agent focuses on their domain expertise for more thorough coverage. + +## Trigger + +Enabled via `--party-review` flag or `party.review.enabled: true` in config. + +When enabled, this REPLACES the standard review (step-03-code-review.md). + +## Default Agents + +| Agent | Focus Area | +|-------|------------| +| Winston (Architect) | Pattern adherence, scalability, API design, component boundaries | +| Murat (Test Architect) | Test coverage, security, edge cases, quality gates | +| Amelia (Developer) | Code quality, readability, error handling, maintainability | + +## Input + +- Story file contents (includes Dev Agent Record from dev phase) +- Git staged changes (`git diff --staged`) + +## Review Protocol + +1. **Independent Analysis**: Each agent reviews from their perspective +2. **Cross-Discussion**: Agents discuss findings, reference each other +3. **Consensus Building**: Agree on blocking issues and fix priorities +4. **Issue Categorization**: HIGH / MEDIUM / LOW severity +5. **Fix Policy**: Same as standard review + - Always fix HIGH + - Fix MEDIUM if total > 5 + - Document LOW only + +## Output + +Updates story file with "Code Review Record" section containing: +- Agent-specific findings tables +- Cross-discussion summary +- Consensus decision +- Fixes applied +- Remaining issues + +## Completion Signals + +``` +PARTY REVIEW PASSED: {story_id} +PARTY REVIEW PASSED WITH FIXES: {story_id} - Fixed N issues +PARTY REVIEW FAILED: {story_id} - {reason} +``` + +## Advantages Over Single-Agent Review + +| Aspect | Single-Agent | Party Review | +|--------|--------------|--------------| +| Perspectives | 1 | 3 | +| Blind spots | More | Fewer | +| Architecture focus | General | Dedicated (Winston) | +| Security focus | General | Dedicated (Murat) | +| Code quality focus | General | Dedicated (Amelia) | +| Discussion | None | Cross-talk, debate | +``` + +--- + +### File: `steps/step-02b-party-failure.md` + +**Location**: `src/modules/bmm/workflows/4-implementation/epic-execute/steps/` + +```markdown +# Step 2b: Failure Analysis Party + +## Context + +Triggered when a story fails during dev or review phase. + +## Objective + +Convene agents to diagnose root cause, propose remediation, and recommend next action. + +## Trigger + +- Dev phase outputs: `IMPLEMENTATION BLOCKED` +- Review phase outputs: `REVIEW FAILED` +- Enabled via `--party-failure` flag + +## Default Agents + +| Agent | Assessment Focus | +|-------|------------------| +| Winston (Architect) | Is this an architectural issue? Design flaw? | +| Amelia (Developer) | Is this an implementation issue? Missing dependency? | +| Bob (Scrum Master) | Is this a requirements issue? Process gap? | + +## Input + +- Story file (current state, may have partial records) +- Failure type: "dev" or "review" +- Failure message (if available) + +## Output + +Appends "Failure Analysis Record" to story file with: +- Agent assessments +- Root cause (consensus) +- Remediation plan +- Recommendation (Retry | Skip | Escalate) + +## Completion Signal + +``` +ANALYSIS COMPLETE: {story_id} - Retry +ANALYSIS COMPLETE: {story_id} - Skip +ANALYSIS COMPLETE: {story_id} - Escalate +``` + +## Non-Blocking + +Failure analysis is informational. The current implementation logs the recommendation but does not automatically act on it. Future enhancement could wire Retry/Skip/Escalate into the loop. +``` + +--- + +### File: `steps/step-05b-party-retro.md` + +**Location**: `src/modules/bmm/workflows/4-implementation/epic-execute/steps/` + +```markdown +# Step 5b: Post-Epic Retrospective Party + +## Context + +Executed after all stories complete (regardless of success/failure). + +## Objective + +Conduct multi-agent retrospective to: +- Reflect on what worked and what didn't +- Capture patterns and decisions for future reference +- Generate rich context handoff for epic-chain workflows + +## Trigger + +Enabled via `--party-retro` flag or `party.retrospective.enabled: true` in config. + +## Default Agents + +| Agent | Reflection Focus | +|-------|------------------| +| Mary (Business Analyst) | Requirements clarity, business value delivered | +| Bob (Scrum Master) | Sprint flow, process effectiveness, blockers | +| Winston (Architect) | Technical decisions, patterns, architectural debt | +| Amelia (Developer) | Implementation experience, code quality, DX | + +## Input + +- Epic file +- ALL completed story files (aggregated) +- Execution summary (completed/failed counts) + +## Output + +Creates TWO new files: + +### 1. Retrospective Document +`docs/sprints/epic-{id}-retro.md` + +Contains: +- What Went Well (per agent) +- Areas for Improvement (per agent) +- Action Items + +### 2. Context Handoff Document +`docs/handoffs/epic-{id}-handoff.md` + +Contains: +- Patterns Established +- Key Decisions +- Gotchas & Lessons Learned +- Files to Reference +- Test Patterns + +## Integration with Epic-Chain + +The handoff document is automatically loaded by epic-chain when executing the next epic, providing rich context that the "placeholder" handoff currently lacks. + +## Completion Signal + +``` +RETRO COMPLETE: Epic {epic_id} +``` +``` + +--- + +## 4. Workflow Documentation Update + +### File: `workflow.md` + +**Location**: `src/modules/bmm/workflows/4-implementation/epic-execute/workflow.md` + +**Modification**: Add Party Mode section after existing content (~line 100) + +```markdown +## Party Mode Integration (Optional) + +Epic Execute supports optional Party Mode phases for multi-agent collaboration: + +| Flag | Phase | Purpose | +|------|-------|---------| +| `--party-kickoff` | Pre-Dev | Multi-agent discussion before implementation | +| `--party-review` | Review | Replaces single-agent review with multi-agent | +| `--party-failure` | On Failure | Root cause analysis when stories fail | +| `--party-retro` | Post-Epic | Team retrospective with context handoff | +| `--party-all` | All | Enables all party phases | + +### Enhanced Flow with Party Mode + +``` +┌──────────────┐ +│ Party: │ ← --party-kickoff +│ Kickoff │ +└──────┬───────┘ + ▼ +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Dev Phase │───►│ Review Phase │───►│ Commit │ +│ │ │ (Standard OR │ │ │ +│ │ │ Party) │ │ │ +└──────────────┘ └──────────────┘ └──────────────┘ + │ + ▼ (on failure) +┌──────────────┐ +│ Party: │ ← --party-failure +│ Failure │ +│ Analysis │ +└──────────────┘ + +Post-Epic: +┌──────────────┐ +│ Party: │ ← --party-retro +│ Retrospective│ +└──────────────┘ +``` + +### Documentation + +See `docs/improvements/party-mode-integration/` for detailed implementation documentation. +``` + +--- + +## 5. Directory Structure After Implementation + +``` +src/modules/bmm/workflows/4-implementation/epic-execute/ +├── workflow.md # Updated with party mode references +├── config/ +│ └── default-config.yaml # Updated with party section +├── steps/ +│ ├── step-01-init.md # Existing (unchanged) +│ ├── step-01b-party-kickoff.md # NEW +│ ├── step-02-dev-story.md # Existing (unchanged) +│ ├── step-02b-party-failure.md # NEW +│ ├── step-03-code-review.md # Existing (unchanged, used when party-review disabled) +│ ├── step-03b-party-review.md # NEW +│ ├── step-04-generate-uat.md # Existing (unchanged) +│ ├── step-05-summary.md # Existing (unchanged) +│ └── step-05b-party-retro.md # NEW +└── ... + +scripts/ +└── epic-execute.sh # Updated with party functions + +docs/improvements/party-mode-integration/ +├── README.md # Index document +├── 01-implementation-plan.md # High-level plan +├── 02-context-management.md # Context architecture +└── 03-file-modifications.md # This document +``` + +--- + +## 6. Implementation Checklist + +### Phase 1: Foundation +- [ ] Add party flag variables to `epic-execute.sh` +- [ ] Add argument parsing for party flags +- [ ] Update usage/help text +- [ ] Add party section to `default-config.yaml` +- [ ] Implement `execute_party_kickoff()` function +- [ ] Create `step-01b-party-kickoff.md` +- [ ] Test kickoff with sample story + +### Phase 2: Party Review +- [ ] Implement `execute_party_review()` function +- [ ] Create `step-03b-party-review.md` +- [ ] Add conditional in main loop for party vs standard review +- [ ] Test party review with sample story + +### Phase 3: Failure Analysis +- [ ] Implement `execute_party_failure_analysis()` function +- [ ] Create `step-02b-party-failure.md` +- [ ] Wire into dev/review failure paths +- [ ] Test with intentionally failing story + +### Phase 4: Retrospective +- [ ] Implement `execute_party_retro()` function +- [ ] Create `step-05b-party-retro.md` +- [ ] Add to post-epic section of main loop +- [ ] Test with completed epic +- [ ] Verify handoff document integrates with epic-chain + +### Phase 5: Polish +- [ ] Update `workflow.md` with party mode documentation +- [ ] Add `--party-agents` override support +- [ ] Test all combinations of flags +- [ ] Update main README if needed diff --git a/docs/improvements/party-mode-integration/README.md b/docs/improvements/party-mode-integration/README.md new file mode 100644 index 000000000..d4bb94f14 --- /dev/null +++ b/docs/improvements/party-mode-integration/README.md @@ -0,0 +1,137 @@ +# Party Mode Integration with Epic Execute + +**Status**: Planning +**Version**: 1.0.0 +**Date**: 2026-01-03 + +--- + +## Overview + +This folder contains the complete documentation for integrating Party Mode's multi-agent collaboration capabilities into the Epic Execute and Epic Chain workflows. + +## Documents + +| Document | Description | +|----------|-------------| +| [01-implementation-plan.md](./01-implementation-plan.md) | High-level implementation plan with CLI flags, configuration, and phases | +| [02-context-management.md](./02-context-management.md) | Deep dive into context isolation architecture and data transfer mechanisms | +| [03-file-modifications.md](./03-file-modifications.md) | Detailed specification of all file changes required | +| [04-prompt-engineering.md](./04-prompt-engineering.md) | Prompt templates for each party phase (future) | + +## Quick Links + +- **Why Party Mode?** See [Benefits Analysis](#benefits-of-integration) +- **How does context work?** See [02-context-management.md](./02-context-management.md) +- **What files change?** See [03-file-modifications.md](./03-file-modifications.md) + +--- + +## Benefits of Integration + +### Current Pain Points + +| Pain Point | Impact | +|------------|--------| +| Architectural issues found mid-implementation | Costly rework, context loss | +| Single-perspective code review | Missed issues in blind spots | +| Shallow context handoffs in epic-chain | Next epic starts without learnings | +| Silent failures with only logged errors | No actionable remediation guidance | + +### Party Mode Solutions + +| Party Phase | Addresses | +|-------------|-----------| +| **Story Kickoff Party** | Surfaces architectural/implementation/testing concerns before coding | +| **Party Review** | Multi-perspective code review catches more issue categories | +| **Failure Analysis Party** | Root cause analysis with actionable remediation | +| **Post-Epic Retrospective** | Rich context handoffs, documented patterns and lessons | + +--- + +## Architecture Summary + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ ENHANCED EPIC EXECUTE FLOW │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ Per Story: │ +│ ┌──────────────┐ │ +│ │ PARTY: │ ← --party-kickoff (optional) │ +│ │ Kickoff │ Agents: Winston + Amelia + Murat │ +│ └──────┬───────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Dev Phase │───►│ Review Phase │───►│ Commit │ │ +│ │ (Context A) │ │ Standard OR │ │ (Shell) │ │ +│ │ │ │ PARTY Review │ │ │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ │ +│ ▼ (on failure) │ +│ ┌──────────────┐ │ +│ │ PARTY: │ ← --party-failure (optional) │ +│ │ Failure │ │ +│ │ Analysis │ │ +│ └──────────────┘ │ +│ │ +│ Post-Epic: │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ UAT │ │ PARTY: │ ← --party-retro (optional) │ +│ │ Generation │ │ Retrospective│ │ +│ └──────────────┘ └──────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## CLI Usage + +```bash +# Enable individual party phases +./epic-execute.sh 42 --party-kickoff +./epic-execute.sh 42 --party-review +./epic-execute.sh 42 --party-failure +./epic-execute.sh 42 --party-retro + +# Enable all party phases +./epic-execute.sh 42 --party-all + +# Custom agents for a phase +./epic-execute.sh 42 --party-review --party-agents "Winston,Murat" + +# Combine with existing flags +./epic-execute.sh 42 --party-all --skip-done --verbose +``` + +--- + +## Implementation Phases + +| Phase | Priority | Scope | +|-------|----------|-------| +| **Phase 1** | High | CLI flags + Story Kickoff Party | +| **Phase 2** | High | Party Review (multi-agent code review) | +| **Phase 3** | Medium | Failure Analysis Party | +| **Phase 4** | Medium | Retrospective + epic-chain handoff integration | +| **Phase 5** | Low | Polish (TTS, metrics, comprehensive docs) | + +--- + +## Related Documents + +- [Epic Workflows v1 Improvements](../epic-workflows-v1.md) - General workflow improvements +- [Party Mode Core Docs](../../../src/core/workflows/party-mode/workflow.md) - Party Mode workflow definition +- [Epic Execute Workflow](../../../src/modules/bmm/workflows/4-implementation/epic-execute/workflow.md) - Current workflow + +--- + +## Decision Log + +| Date | Decision | Rationale | +|------|----------|-----------| +| 2026-01-03 | Option B: Configurable flags | Opt-in approach preserves existing behavior, allows gradual adoption | +| 2026-01-03 | File-based context transfer | Maintains context isolation while enabling information flow | +| 2026-01-03 | Non-blocking kickoff | Kickoff insights are helpful but not critical path | diff --git a/docs/improvements/uat-implementation-plan.md b/docs/improvements/uat-implementation-plan.md new file mode 100644 index 000000000..f807814f3 --- /dev/null +++ b/docs/improvements/uat-implementation-plan.md @@ -0,0 +1,709 @@ +# UAT Workflow Implementation Plan + +**Date:** 2026-01-05 +**Source:** `docs/improvements/uat-workflow-implementation-gaps.md` +**Scope:** All gaps (P0, P1, P2) + +--- + +## Overview + +Implement all gaps identified in the UAT workflow implementation gaps analysis to make the UAT validation workflow and epic chain report generator production-ready. + +**Current State:** Workflow definitions, templates, and agent triggers exist +**Missing:** Shell orchestration, metrics collection, step files, and integration points + +--- + +## Files to Create + +| File | Priority | Lines (est) | +|------|----------|-------------| +| `scripts/uat-validate.sh` | P0 | ~350 | +| `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-01-load-uat.md` | P2 | ~60 | +| `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-02-classify-scenarios.md` | P2 | ~50 | +| `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-03-execute-scenarios.md` | P2 | ~70 | +| `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-04-evaluate-gate.md` | P2 | ~60 | +| `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-05-report-results.md` | P2 | ~50 | + +## Files to Modify + +| File | Priority | Changes | +|------|----------|---------| +| `scripts/epic-execute.sh` | P0 | Add metrics collection (~60 lines) | +| `scripts/epic-chain.sh` | P1 | Add UAT gate + report generation (~100 lines) | + +--- + +## Implementation Steps + +### Step 1: Create `scripts/uat-validate.sh` [P0] + +**Purpose:** Shell orchestration for UAT validation with self-healing loop + +**Structure (following epic-execute.sh patterns):** + +``` +Section 1: Configuration (lines 1-50) + - Script/project paths + - Color codes + - Default values: UAT_GATE_MODE=quick, MAX_RETRIES=2 + +Section 2: Helper Functions (lines 51-90) + - log(), log_success(), log_error(), log_warn() + - Log to /tmp/bmad-uat-validate-$$.log + +Section 3: Argument Parsing (lines 91-140) + - Required: + - Flags: --gate-mode=quick|full|skip, --max-retries=N, --skip-manual, --verbose, --dry-run + +Section 4: UAT Document Loading (lines 141-180) + - Find: docs/uat/epic-{id}-uat.md + - Parse scenario blocks + +Section 5: Scenario Classification (lines 181-230) + - Automatable: contains npx, npm run, curl, pytest, etc. + - Semi-auto: requires setup then command + - Manual: no detectable command + +Section 6: Scenario Execution (lines 231-280) + - Execute automatable scenarios with timeout + - Capture exit code + output + - Record pass/fail results + +Section 7: Gate Evaluation (lines 281-320) + - If all passed: output UAT_GATE_RESULT: PASS, exit 0 + - If failed: generate fix context, attempt self-healing + +Section 8: Self-Healing Loop (lines 321-380) + - Generate fix context doc at: docs/sprint-artifacts/uat-fixes/epic-{id}-fix-context-{attempt}.md + - Spawn fresh Claude for quick-dev fixes + - Re-validate in new iteration + - Loop until pass or max_retries + +Section 9: Output Signals (lines 381-400) + - UAT_GATE_RESULT: PASS|FAIL + - UAT_FIX_ATTEMPTS: N + - UAT_SCENARIOS_PASSED: X/Y + - Exit codes: 0=pass, 1=fail-fixable, 2=max-retries-exceeded +``` + +**Key Functions:** + +```bash +load_uat_document() # Parse UAT doc, extract scenarios +classify_scenario() # Return: automatable|semi-auto|manual +execute_scenario() # Run command, capture result +evaluate_gate() # Determine pass/fail +generate_fix_context() # Create fix context doc from template +run_quick_dev_fix() # Spawn fresh Claude session for fixes +``` + +**Interface:** + +```bash +# Usage +./scripts/uat-validate.sh [options] + +# Options +--gate-mode=quick|full|skip # Which scenarios to run +--max-retries=2 # Fix attempts before halt +--skip-manual # Skip manual-only scenarios +--verbose # Detailed output +--dry-run # Show what would run + +# Output signals (for epic-chain.sh to parse) +UAT_GATE_RESULT: PASS|FAIL +UAT_FIX_ATTEMPTS: N +UAT_SCENARIOS_PASSED: X/Y +``` + +--- + +### Step 2: Add Metrics Instrumentation to `scripts/epic-execute.sh` [P0] + +**Location:** Modify existing file + +**Add at epic start (~line 145, after directory setup):** + +```bash +# Initialize metrics file +METRICS_DIR="$SPRINT_ARTIFACTS_DIR/metrics" +METRICS_FILE="$METRICS_DIR/epic-${EPIC_ID}-metrics.yaml" +mkdir -p "$METRICS_DIR" +EPIC_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") +EPIC_START_SECONDS=$(date +%s) + +cat > "$METRICS_FILE" << EOF +epic_id: "$EPIC_ID" +execution: + start_time: "$EPIC_START_TIME" + end_time: "" + duration_seconds: 0 +stories: + total: 0 + completed: 0 + failed: 0 + skipped: 0 +validation: + gate_executed: false + gate_status: "PENDING" + fix_attempts: 0 +issues: [] +EOF +``` + +**Add helper function (~line 65):** + +```bash +update_story_metrics() { + local status="$1" # completed|failed|skipped + case "$status" in + completed) yq -i '.stories.completed += 1' "$METRICS_FILE" ;; + failed) yq -i '.stories.failed += 1' "$METRICS_FILE" ;; + skipped) yq -i '.stories.skipped += 1' "$METRICS_FILE" ;; + esac +} +``` + +**Call after each story completion in main loop:** + +```bash +update_story_metrics "completed" # or failed/skipped based on result +``` + +**Add at epic end (~line 400, before summary):** + +```bash +# Finalize metrics +EPIC_END_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") +DURATION=$(($(date +%s) - EPIC_START_SECONDS)) +yq -i ".execution.end_time = \"$EPIC_END_TIME\"" "$METRICS_FILE" +yq -i ".execution.duration_seconds = $DURATION" "$METRICS_FILE" +yq -i ".stories.total = ${#STORIES[@]}" "$METRICS_FILE" +``` + +--- + +### Step 3: Integrate UAT Gate into `scripts/epic-chain.sh` [P1] + +**Add configuration variables (~line 42):** + +```bash +# UAT Gate Configuration +UAT_GATE_ENABLED="${UAT_GATE_ENABLED:-true}" +UAT_GATE_MODE="${UAT_GATE_MODE:-quick}" +UAT_MAX_RETRIES="${UAT_MAX_RETRIES:-2}" +UAT_BLOCKING="${UAT_BLOCKING:-false}" +``` + +**Add CLI flags (~line 120):** + +```bash +--uat-gate=*) + UAT_GATE_MODE="${1#*=}" + shift + ;; +--uat-blocking) + UAT_BLOCKING=true + shift + ;; +--no-uat) + UAT_GATE_ENABLED=false + shift + ;; +``` + +**Add UAT gate phase after epic completion (~line 320, after epic-execute succeeds):** + +```bash +# Run UAT validation if enabled +if [ "$UAT_GATE_ENABLED" = true ]; then + log_section "UAT Validation Gate: Epic $epic_id" + + uat_result=$("$SCRIPT_DIR/uat-validate.sh" "$epic_id" \ + --gate-mode="$UAT_GATE_MODE" \ + --max-retries="$UAT_MAX_RETRIES" 2>&1) || true + + # Parse result + if echo "$uat_result" | grep -q "UAT_GATE_RESULT: PASS"; then + log_success "UAT validation passed for Epic $epic_id" + # Update metrics + yq -i '.validation.gate_executed = true' "$METRICS_FILE" + yq -i '.validation.gate_status = "PASS"' "$METRICS_FILE" + else + log_error "UAT validation failed for Epic $epic_id" + yq -i '.validation.gate_executed = true' "$METRICS_FILE" + yq -i '.validation.gate_status = "FAIL"' "$METRICS_FILE" + + if [ "$UAT_BLOCKING" = true ]; then + log_error "UAT blocking enabled - halting chain" + exit 1 + else + log_warn "UAT blocking disabled - continuing to next epic" + fi + fi +fi +``` + +--- + +### Step 4: Integrate Report Generation into `scripts/epic-chain.sh` [P1] + +**Add configuration (~line 45):** + +```bash +GENERATE_REPORT="${GENERATE_REPORT:-true}" +CHAIN_REPORT_FILE="$SPRINT_ARTIFACTS_DIR/chain-execution-report.md" +METRICS_DIR="$SPRINT_ARTIFACTS_DIR/metrics" +``` + +**Add CLI flag (~line 130):** + +```bash +--no-report) + GENERATE_REPORT=false + shift + ;; +``` + +**Add report generation after all epics (~line 400, before final summary):** + +```bash +# Generate chain execution report +if [ "$GENERATE_REPORT" = true ] && [ "$DRY_RUN" = false ]; then + log_section "Generating Chain Execution Report" + + INSTALLED_PATH="$BMAD_DIR/bmm/workflows/4-implementation/epic-chain" + + report_prompt="You are Bob, the Scrum Master. + +Execute the chain report generation workflow: +- Step file: $INSTALLED_PATH/steps/step-10-generate-report.md +- Metrics folder: $METRICS_DIR +- Chain plan: $CHAIN_PLAN_FILE +- Output to: $CHAIN_REPORT_FILE + +Generate the complete execution report." + + claude --dangerously-skip-permissions -p "$report_prompt" || true + + if [ -f "$CHAIN_REPORT_FILE" ]; then + log_success "Report generated: $CHAIN_REPORT_FILE" + git add "$CHAIN_REPORT_FILE" 2>/dev/null || true + else + log_warn "Report generation did not produce output" + fi +fi +``` + +--- + +### Step 5: Create UAT Validation Step Files [P2] + +**Directory:** `src/modules/bmm/workflows/5-validation/uat-validate/steps/` + +#### step-01-load-uat.md + +```markdown +# Step 1: Load UAT Document + +## Purpose +Load and validate the UAT document for the specified epic. + +## Inputs +| Input | Source | Required | +|-------|--------|----------| +| epic_id | CLI argument | Yes | +| uat_dir | Configuration | Yes | + +## Process + +### 1.1 Locate UAT Document +Search for UAT document at: `{uat_dir}/epic-{epic_id}-uat.md` + +### 1.2 Validate Structure +Confirm document contains: +- ## Acceptance Criteria or ## Scenarios section +- At least one scenario block + +### 1.3 Parse Scenarios +Extract scenario blocks with: +- Scenario ID/Title +- Given/When/Then steps +- Verification command (if present) +- Expected result + +## Outputs +| Output | Location | Description | +|--------|----------|-------------| +| scenario_list | Memory | Parsed scenario objects | +| scenario_count | Console | Number of scenarios found | + +## Completion Signal +UAT_LOADED: {scenario_count} + +## Error Handling +| Error | Action | +|-------|--------| +| File not found | Exit 1 with clear message | +| Invalid structure | Exit 1 with parsing error | +``` + +#### step-02-classify-scenarios.md + +```markdown +# Step 2: Classify Scenarios + +## Purpose +Categorize scenarios by their executability level. + +## Inputs +| Input | Source | Required | +|-------|--------|----------| +| scenario_list | Step 1 | Yes | + +## Process + +### 2.1 Detect Automatable Scenarios +Keywords that indicate automatability: +- npx, npm run, yarn +- curl, wget, http +- pytest, jest, vitest +- /health, /api/ +- exit code, returns + +### 2.2 Detect Semi-Automated +Scenarios with commands that require setup: +- "Start the server first" +- "Ensure database is running" +- Manual setup + automated verification + +### 2.3 Classify as Manual +No detectable command or automation path. + +## Outputs +| Output | Location | Description | +|--------|----------|-------------| +| automatable | Array | Scenarios to execute | +| semi_auto | Array | Scenarios needing setup | +| manual | Array | Human verification required | + +## Completion Signal +SCENARIOS_CLASSIFIED: {auto}/{semi}/{manual} +``` + +#### step-03-execute-scenarios.md + +```markdown +# Step 3: Execute Scenarios + +## Purpose +Run automatable scenarios via shell commands. + +## Inputs +| Input | Source | Required | +|-------|--------|----------| +| automatable | Step 2 | Yes | +| gate_mode | CLI | Yes (quick/full) | +| timeout | Config | No (default: 30s) | + +## Process + +### 3.1 Filter by Gate Mode +- quick: Execute only critical/blocking scenarios +- full: Execute all automatable scenarios +- skip: Return success without execution + +### 3.2 Execute Each Scenario +For each scenario: +1. Extract command from verification step +2. Execute with timeout: `timeout {seconds} {command}` +3. Capture exit code and output +4. Record result: PASS (exit 0) or FAIL (exit non-zero) + +### 3.3 Handle Execution Errors +- Command not found: Record as FAIL with clear message +- Timeout exceeded: Record as FAIL with timeout note +- Unexpected error: Record as FAIL with stderr + +## Outputs +| Output | Location | Description | +|--------|----------|-------------| +| results | Array | {scenario_id, status, output, exit_code} | +| passed_count | Console | Scenarios that passed | +| failed_count | Console | Scenarios that failed | + +## Completion Signal +SCENARIOS_EXECUTED: {passed}/{total} +``` + +#### step-04-evaluate-gate.md + +```markdown +# Step 4: Evaluate Gate + +## Purpose +Determine pass/fail status and trigger self-healing if needed. + +## Inputs +| Input | Source | Required | +|-------|--------|----------| +| results | Step 3 | Yes | +| max_retries | CLI | Yes | +| current_attempt | State | Yes | + +## Process + +### 4.1 Check All Results +If all automatable scenarios passed: +- Set gate_status = PASS +- Skip to Step 5 + +### 4.2 Handle Failures +If any scenario failed: +- Collect failed scenario details +- Check if current_attempt < max_retries + +### 4.3 Generate Fix Context +If retries available: +1. Load fix context template +2. Populate with failed scenarios +3. Write to: `{sprint_artifacts}/uat-fixes/epic-{id}-fix-context-{attempt}.md` + +### 4.4 Trigger Quick-Dev Fix +Spawn fresh Claude session: +``` +claude --dangerously-skip-permissions -p "Load fix context, implement fixes..." +``` + +### 4.5 Increment and Retry +- Increment attempt counter +- Return to Step 3 for re-validation + +## Outputs +| Output | Location | Description | +|--------|----------|-------------| +| gate_status | State | PASS or FAIL | +| fix_context_file | Path | Generated fix context (if failed) | + +## Completion Signal +GATE_EVALUATED: PASS|FAIL +``` + +#### step-05-report-results.md + +```markdown +# Step 5: Report Results + +## Purpose +Update metrics and output parseable signals. + +## Inputs +| Input | Source | Required | +|-------|--------|----------| +| gate_status | Step 4 | Yes | +| results | Step 3 | Yes | +| fix_attempts | State | Yes | + +## Process + +### 5.1 Update Metrics File +Update `{metrics_dir}/epic-{id}-metrics.yaml`: +```yaml +validation: + gate_executed: true + gate_status: "PASS|FAIL" + fix_attempts: N + scenarios_passed: X + scenarios_failed: Y +``` + +### 5.2 Output Signals +Print to stdout (for parent script parsing): +``` +UAT_GATE_RESULT: PASS|FAIL +UAT_FIX_ATTEMPTS: N +UAT_SCENARIOS_PASSED: X/Y +``` + +### 5.3 Set Exit Code +- 0: PASS +- 1: FAIL (fixable, retries remain) +- 2: FAIL (max retries exceeded) + +## Outputs +| Output | Location | Description | +|--------|----------|-------------| +| Updated metrics | YAML file | Validation results | +| Signals | stdout | Parseable output | + +## Completion Signal +RESULTS_REPORTED: {metrics_path} +``` + +--- + +### Step 6: Integrate Fix Context with Handoff Pattern [P2] + +**Directory structure:** + +``` +docs/sprint-artifacts/ +├── handoffs/ +│ ├── epic-1-to-2-handoff.md +│ └── epic-2-to-3-handoff.md +├── uat-fixes/ # NEW +│ ├── epic-1-fix-context-1.md +│ └── epic-2-fix-context-1.md +└── metrics/ + ├── epic-1-metrics.yaml + └── epic-2-metrics.yaml +``` + +**In uat-validate.sh, implement generate_fix_context():** + +```bash +generate_fix_context() { + local epic_id="$1" + local attempt="$2" + local failed_scenarios="$3" + + local fix_dir="$SPRINT_ARTIFACTS_DIR/uat-fixes" + mkdir -p "$fix_dir" + + local fix_file="$fix_dir/epic-${epic_id}-fix-context-${attempt}.md" + local template="$PROJECT_ROOT/src/modules/bmm/workflows/5-validation/uat-validate/uat-fix-context-template.md" + + # Render template with variables + sed -e "s/{epic_id}/$epic_id/g" \ + -e "s/{attempt}/$attempt/g" \ + -e "s/{timestamp}/$(date -u +"%Y-%m-%dT%H:%M:%SZ")/g" \ + "$template" > "$fix_file" + + # Append failed scenarios + echo "" >> "$fix_file" + echo "## Failed Scenarios" >> "$fix_file" + echo "$failed_scenarios" >> "$fix_file" + + echo "$fix_file" +} +``` + +**In quick-dev fix session, load context:** + +```bash +run_quick_dev_fix() { + local fix_context_file="$1" + local epic_id="$2" + local attempt="$3" + + local fix_prompt="You are Barry, the Quick Flow Solo Dev. + +Load and process this fix context document: +$fix_context_file + +Your task: +1. Read the failed scenarios and error details +2. Analyze root cause for each failure +3. Implement targeted fixes +4. Run the failing commands to verify fixes +5. Stage changes: git add -A +6. Commit with message: fix(epic-${epic_id}): UAT fix #${attempt} + +Constraints: +- Only fix the identified failures +- Do not refactor unrelated code +- Run tests after fixes + +When done, output: +FIX_COMPLETE: {number_fixed}/{total_failures}" + + # Fresh Claude context for fixes + claude --dangerously-skip-permissions -p "$fix_prompt" +} +``` + +--- + +## Execution Order + +1. **`scripts/uat-validate.sh`** - Core orchestration (enables self-healing) +2. **`scripts/epic-execute.sh`** modifications - Metrics collection (enables reporting) +3. **`scripts/epic-chain.sh`** modifications - UAT gate + report integration +4. **Step files** - Documentation and maintainability + +--- + +## Testing Plan + +### Unit Tests + +1. `uat-validate.sh --dry-run` - Verify argument parsing and flow +2. Metrics YAML structure matches template at `src/modules/bmm/workflows/4-implementation/epic-chain/templates/epic-metrics-template.yaml` +3. Signal output format matches spec + +### Integration Tests + +1. Run epic-execute with metrics collection, verify `docs/sprint-artifacts/metrics/epic-{id}-metrics.yaml` created +2. Run uat-validate against known-passing UAT doc, verify `UAT_GATE_RESULT: PASS` +3. Run uat-validate against known-failing UAT doc, verify fix loop triggers +4. Run epic-chain with `--uat-gate=quick`, verify gate runs after each epic + +### Manual Verification + +1. Run `epic-chain 1-3` on test project +2. Verify `docs/sprint-artifacts/metrics/` populated with per-epic metrics +3. Verify `docs/sprint-artifacts/uat-fixes/` created on UAT failure +4. Verify `chain-execution-report.md` generated with accurate aggregated data + +--- + +## Dependencies + +| Dependency | Purpose | Required | +|------------|---------|----------| +| `yq` | YAML manipulation | Recommended (fallback: inline append) | +| `timeout` | Command timeout | Yes (GNU coreutils) | +| `claude` CLI | Isolated context spawning | Yes | +| `sed` | Template rendering | Yes (POSIX) | + +--- + +## Risks & Mitigations + +| Risk | Mitigation | +|------|------------| +| `yq` not installed | Detect and fall back to inline YAML append via echo/cat | +| UAT document malformed | Validate structure before processing, clear error messages | +| Claude session fails | Capture exit code, log output, allow retry | +| Infinite fix loop | Hard limit via `--max-retries`, default 2 | +| Scenario command not found | Record as FAIL with clear "command not found" message | +| Timeout exceeded | Record as FAIL, include timeout duration in output | + +--- + +## Reference Files + +### Existing (to read for patterns) + +- `scripts/epic-execute.sh` - Context isolation, logging, argument parsing +- `scripts/epic-chain.sh` - Orchestration, CLI flags, integration points +- `src/modules/bmm/workflows/5-validation/uat-validate/instructions.md` - Validation logic +- `src/modules/bmm/workflows/5-validation/uat-validate/uat-fix-context-template.md` - Fix context template +- `src/modules/bmm/workflows/4-implementation/epic-chain/templates/epic-metrics-template.yaml` - Metrics schema +- `src/modules/bmm/workflows/4-implementation/epic-chain/steps/step-10-generate-report.md` - Report generation + +### To Create + +- `scripts/uat-validate.sh` +- `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-01-load-uat.md` +- `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-02-classify-scenarios.md` +- `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-03-execute-scenarios.md` +- `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-04-evaluate-gate.md` +- `src/modules/bmm/workflows/5-validation/uat-validate/steps/step-05-report-results.md` + +### To Modify + +- `scripts/epic-execute.sh` - Add metrics collection +- `scripts/epic-chain.sh` - Add UAT gate and report generation