bmad-plus 0.7.4 → 0.8.0

package/src/bmad-plus/packs/pack-dev-studio/categories/architecture/steps/step-05-patterns.md

@@ -1,359 +1,359 @@
-# Step 5: Implementation Patterns & Consistency Rules
-
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-- 🛑 NEVER generate content without user input
-
-- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
-- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
-- ✅ ALWAYS treat this as collaborative discovery between architectural peers
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- 💬 FOCUS on patterns that prevent AI agent implementation conflicts
-- 🎯 EMPHASIZE what agents could decide DIFFERENTLY if not specified
-- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Show your analysis before taking any action
-- 🎯 Focus on consistency, not implementation details
-- ⚠️ Present A/P/C menu after generating patterns content
-- 💾 ONLY save when user chooses C (Continue)
-- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before loading next step
-- 🚫 FORBIDDEN to load next step until C is selected
-
-## COLLABORATION MENUS (A/P/C):
-
-This step will generate content and present choices:
-
-- **A (Advanced Elicitation)**: Use discovery protocols to develop comprehensive consistency patterns
-- **P (Party Mode)**: Bring multiple perspectives to identify potential conflict points
-- **C (Continue)**: Save the patterns and proceed to project structure
-
-## PROTOCOL INTEGRATION:
-
-- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
-- When 'P' selected: Invoke the `bmad-party-mode` skill
-- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
-- User accepts/rejects protocol changes before proceeding
-
-## CONTEXT BOUNDARIES:
-
-- Core architectural decisions from step 4 are complete
-- Technology stack is decided and versions are verified
-- Focus on HOW agents should implement, not WHAT they should implement
-- Consider what could vary between different AI agents
-
-## YOUR TASK:
-
-Define implementation patterns and consistency rules that ensure multiple AI agents write compatible, consistent code that works together seamlessly.
-
-## PATTERNS DEFINITION SEQUENCE:
-
-### 1. Identify Potential Conflict Points
-
-Based on the chosen technology stack and decisions, identify where AI agents could make different choices:
-
-**Naming Conflicts:**
-
-- Database table/column naming conventions
-- API endpoint naming patterns
-- File and directory naming
-- Component/function/variable naming
-- Route parameter formats
-
-**Structural Conflicts:**
-
-- Where tests are located
-- How components are organized
-- Where utilities and helpers go
-- Configuration file organization
-- Static asset organization
-
-**Format Conflicts:**
-
-- API response wrapper formats
-- Error response structures
-- Date/time formats in APIs and UI
-- JSON field naming conventions
-- API status code usage
-
-**Communication Conflicts:**
-
-- Event naming conventions
-- Event payload structures
-- State update patterns
-- Action naming conventions
-- Logging formats and levels
-
-**Process Conflicts:**
-
-- Loading state handling
-- Error recovery patterns
-- Retry implementation approaches
-- Authentication flow patterns
-- Validation timing and methods
-
-### 2. Facilitate Pattern Decisions
-
-For each conflict category, facilitate collaborative pattern definition:
-
-**Present the Conflict Point:**
-"Given that we're using {{tech_stack}}, different AI agents might handle {{conflict_area}} differently.
-
-For example, one agent might name database tables 'users' while another uses 'Users' - this would cause conflicts.
-
-We need to establish consistent patterns that all agents follow."
-
-**Show Options and Trade-offs:**
-"Common approaches for {{pattern_category}}:
-
-1. {{option_1}} - {{pros_and_cons}}
-2. {{option_2}} - {{pros_and_cons}}
-3. {{option_3}} - {{pros_and_cons}}
-
-Which approach makes the most sense for our project?"
-
-**Get User Decision:**
-"What's your preference for this pattern? (or discuss the trade-offs more)"
-
-### 3. Define Pattern Categories
-
-#### Naming Patterns
-
-**Database Naming:**
-
-- Table naming: users, Users, or user?
-- Column naming: user_id or userId?
-- Foreign key format: user_id or fk_user?
-- Index naming: idx_users_email or users_email_index?
-
-**API Naming:**
-
-- REST endpoint naming: /users or /user? Plural or singular?
-- Route parameter format: :id or {id}?
-- Query parameter naming: user_id or userId?
-- Header naming conventions: X-Custom-Header or Custom-Header?
-
-**Code Naming:**
-
-- Component naming: UserCard or user-card?
-- File naming: UserCard.tsx or user-card.tsx?
-- Function naming: getUserData or get_user_data?
-- Variable naming: userId or user_id?
-
-#### Structure Patterns
-
-**Project Organization:**
-
-- Where do tests live? **tests**/ or \*.test.ts co-located?
-- How are components organized? By feature or by type?
-- Where do shared utilities go?
-- How are services and repositories organized?
-
-**File Structure:**
-
-- Config file locations and naming
-- Static asset organization
-- Documentation placement
-- Environment file organization
-
-#### Format Patterns
-
-**API Formats:**
-
-- API response wrapper? {data: ..., error: ...} or direct response?
-- Error format? {message, code} or {error: {type, detail}}?
-- Date format in JSON? ISO strings or timestamps?
-- Success response structure?
-
-**Data Formats:**
-
-- JSON field naming: snake_case or camelCase?
-- Boolean representations: true/false or 1/0?
-- Null handling patterns
-- Array vs object for single items
-
-#### Communication Patterns
-
-**Event Systems:**
-
-- Event naming convention: user.created or UserCreated?
-- Event payload structure standards
-- Event versioning approach
-- Async event handling patterns
-
-**State Management:**
-
-- State update patterns: immutable updates or direct mutation?
-- Action naming conventions
-- Selector patterns
-- State organization principles
-
-#### Process Patterns
-
-**Error Handling:**
-
-- Global error handling approach
-- Error boundary patterns
-- User-facing error message format
-- Logging vs user error distinction
-
-**Loading States:**
-
-- Loading state naming conventions
-- Global vs local loading states
-- Loading state persistence
-- Loading UI patterns
-
-### 4. Generate Patterns Content
-
-Prepare the content to append to the document:
-
-#### Content Structure:
-
-```markdown
-## Implementation Patterns & Consistency Rules
-
-### Pattern Categories Defined
-
-**Critical Conflict Points Identified:**
-{{number_of_potential_conflicts}} areas where AI agents could make different choices
-
-### Naming Patterns
-
-**Database Naming Conventions:**
-{{database_naming_rules_with_examples}}
-
-**API Naming Conventions:**
-{{api_naming_rules_with_examples}}
-
-**Code Naming Conventions:**
-{{code_naming_rules_with_examples}}
-
-### Structure Patterns
-
-**Project Organization:**
-{{project_structure_rules_with_examples}}
-
-**File Structure Patterns:**
-{{file_organization_rules_with_examples}}
-
-### Format Patterns
-
-**API Response Formats:**
-{{api_response_structure_rules}}
-
-**Data Exchange Formats:**
-{{data_format_rules_with_examples}}
-
-### Communication Patterns
-
-**Event System Patterns:**
-{{event_naming_and_structure_rules}}
-
-**State Management Patterns:**
-{{state_update_and_organization_rules}}
-
-### Process Patterns
-
-**Error Handling Patterns:**
-{{consistent_error_handling_approaches}}
-
-**Loading State Patterns:**
-{{loading_state_management_rules}}
-
-### Enforcement Guidelines
-
-**All AI Agents MUST:**
-
-- {{mandatory_pattern_1}}
-- {{mandatory_pattern_2}}
-- {{mandatory_pattern_3}}
-
-**Pattern Enforcement:**
-
-- How to verify patterns are followed
-- Where to document pattern violations
-- Process for updating patterns
-
-### Pattern Examples
-
-**Good Examples:**
-{{concrete_examples_of_correct_pattern_usage}}
-
-**Anti-Patterns:**
-{{examples_of_what_to_avoid}}
-```
-
-### 5. Present Content and Menu
-
-Show the generated patterns content and present choices:
-
-"I've documented implementation patterns that will prevent conflicts between AI agents working on this project.
-
-**Here's what I'll add to the document:**
-
-[Show the complete markdown content from step 4]
-
-**What would you like to do?**
-[A] Advanced Elicitation - Explore additional consistency patterns
-[P] Party Mode - Review patterns from different implementation perspectives
-[C] Continue - Save these patterns and move to project structure"
-
-### 6. Handle Menu Selection
-
-#### If 'A' (Advanced Elicitation):
-
-- Invoke the `bmad-advanced-elicitation` skill with current patterns
-- Process enhanced consistency rules that come back
-- Ask user: "Accept these additional pattern refinements? (y/n)"
-- If yes: Update content, then return to A/P/C menu
-- If no: Keep original content, then return to A/P/C menu
-
-#### If 'P' (Party Mode):
-
-- Invoke the `bmad-party-mode` skill with implementation patterns context
-- Process collaborative insights about potential conflicts
-- Ask user: "Accept these changes to the implementation patterns? (y/n)"
-- If yes: Update content, then return to A/P/C menu
-- If no: Keep original content, then return to A/P/C menu
-
-#### If 'C' (Continue):
-
-- Append the final content to `{planning_artifacts}/architecture.md`
-- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
-- Load `./step-06-structure.md`
-
-## APPEND TO DOCUMENT:
-
-When user selects 'C', append the content directly to the document using the structure from step 4.
-
-## SUCCESS METRICS:
-
-✅ All potential AI agent conflict points identified and addressed
-✅ Comprehensive patterns defined for naming, structure, and communication
-✅ Concrete examples provided for each pattern
-✅ Enforcement guidelines clearly documented
-✅ User collaborated on pattern decisions rather than receiving recommendations
-✅ A/P/C menu presented and handled correctly
-✅ Content properly appended to document when C selected
-
-## FAILURE MODES:
-
-❌ Missing potential conflict points that could cause agent conflicts
-❌ Being too prescriptive about implementation details instead of focusing on consistency
-❌ Not providing concrete examples for each pattern
-❌ Failing to address cross-cutting concerns like error handling
-❌ Not considering the chosen technology stack when defining patterns
-❌ Not presenting A/P/C menu after content generation
-
-❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
-❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
-❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
-
-## NEXT STEP:
-
-After user selects 'C' and content is saved to document, load `./step-06-structure.md` to define the complete project structure.
-
-Remember: Do NOT proceed to step-06 until user explicitly selects 'C' from the A/P/C menu and content is saved!
+# Step 5: Implementation Patterns & Consistency Rules
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on patterns that prevent AI agent implementation conflicts
+- 🎯 EMPHASIZE what agents could decide DIFFERENTLY if not specified
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 🎯 Focus on consistency, not implementation details
+- ⚠️ Present A/P/C menu after generating patterns content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop comprehensive consistency patterns
+- **P (Party Mode)**: Bring multiple perspectives to identify potential conflict points
+- **C (Continue)**: Save the patterns and proceed to project structure
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Core architectural decisions from step 4 are complete
+- Technology stack is decided and versions are verified
+- Focus on HOW agents should implement, not WHAT they should implement
+- Consider what could vary between different AI agents
+
+## YOUR TASK:
+
+Define implementation patterns and consistency rules that ensure multiple AI agents write compatible, consistent code that works together seamlessly.
+
+## PATTERNS DEFINITION SEQUENCE:
+
+### 1. Identify Potential Conflict Points
+
+Based on the chosen technology stack and decisions, identify where AI agents could make different choices:
+
+**Naming Conflicts:**
+
+- Database table/column naming conventions
+- API endpoint naming patterns
+- File and directory naming
+- Component/function/variable naming
+- Route parameter formats
+
+**Structural Conflicts:**
+
+- Where tests are located
+- How components are organized
+- Where utilities and helpers go
+- Configuration file organization
+- Static asset organization
+
+**Format Conflicts:**
+
+- API response wrapper formats
+- Error response structures
+- Date/time formats in APIs and UI
+- JSON field naming conventions
+- API status code usage
+
+**Communication Conflicts:**
+
+- Event naming conventions
+- Event payload structures
+- State update patterns
+- Action naming conventions
+- Logging formats and levels
+
+**Process Conflicts:**
+
+- Loading state handling
+- Error recovery patterns
+- Retry implementation approaches
+- Authentication flow patterns
+- Validation timing and methods
+
+### 2. Facilitate Pattern Decisions
+
+For each conflict category, facilitate collaborative pattern definition:
+
+**Present the Conflict Point:**
+"Given that we're using {{tech_stack}}, different AI agents might handle {{conflict_area}} differently.
+
+For example, one agent might name database tables 'users' while another uses 'Users' - this would cause conflicts.
+
+We need to establish consistent patterns that all agents follow."
+
+**Show Options and Trade-offs:**
+"Common approaches for {{pattern_category}}:
+
+1. {{option_1}} - {{pros_and_cons}}
+2. {{option_2}} - {{pros_and_cons}}
+3. {{option_3}} - {{pros_and_cons}}
+
+Which approach makes the most sense for our project?"
+
+**Get User Decision:**
+"What's your preference for this pattern? (or discuss the trade-offs more)"
+
+### 3. Define Pattern Categories
+
+#### Naming Patterns
+
+**Database Naming:**
+
+- Table naming: users, Users, or user?
+- Column naming: user_id or userId?
+- Foreign key format: user_id or fk_user?
+- Index naming: idx_users_email or users_email_index?
+
+**API Naming:**
+
+- REST endpoint naming: /users or /user? Plural or singular?
+- Route parameter format: :id or {id}?
+- Query parameter naming: user_id or userId?
+- Header naming conventions: X-Custom-Header or Custom-Header?
+
+**Code Naming:**
+
+- Component naming: UserCard or user-card?
+- File naming: UserCard.tsx or user-card.tsx?
+- Function naming: getUserData or get_user_data?
+- Variable naming: userId or user_id?
+
+#### Structure Patterns
+
+**Project Organization:**
+
+- Where do tests live? **tests**/ or \*.test.ts co-located?
+- How are components organized? By feature or by type?
+- Where do shared utilities go?
+- How are services and repositories organized?
+
+**File Structure:**
+
+- Config file locations and naming
+- Static asset organization
+- Documentation placement
+- Environment file organization
+
+#### Format Patterns
+
+**API Formats:**
+
+- API response wrapper? {data: ..., error: ...} or direct response?
+- Error format? {message, code} or {error: {type, detail}}?
+- Date format in JSON? ISO strings or timestamps?
+- Success response structure?
+
+**Data Formats:**
+
+- JSON field naming: snake_case or camelCase?
+- Boolean representations: true/false or 1/0?
+- Null handling patterns
+- Array vs object for single items
+
+#### Communication Patterns
+
+**Event Systems:**
+
+- Event naming convention: user.created or UserCreated?
+- Event payload structure standards
+- Event versioning approach
+- Async event handling patterns
+
+**State Management:**
+
+- State update patterns: immutable updates or direct mutation?
+- Action naming conventions
+- Selector patterns
+- State organization principles
+
+#### Process Patterns
+
+**Error Handling:**
+
+- Global error handling approach
+- Error boundary patterns
+- User-facing error message format
+- Logging vs user error distinction
+
+**Loading States:**
+
+- Loading state naming conventions
+- Global vs local loading states
+- Loading state persistence
+- Loading UI patterns
+
+### 4. Generate Patterns Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+```markdown
+## Implementation Patterns & Consistency Rules
+
+### Pattern Categories Defined
+
+**Critical Conflict Points Identified:**
+{{number_of_potential_conflicts}} areas where AI agents could make different choices
+
+### Naming Patterns
+
+**Database Naming Conventions:**
+{{database_naming_rules_with_examples}}
+
+**API Naming Conventions:**
+{{api_naming_rules_with_examples}}
+
+**Code Naming Conventions:**
+{{code_naming_rules_with_examples}}
+
+### Structure Patterns
+
+**Project Organization:**
+{{project_structure_rules_with_examples}}
+
+**File Structure Patterns:**
+{{file_organization_rules_with_examples}}
+
+### Format Patterns
+
+**API Response Formats:**
+{{api_response_structure_rules}}
+
+**Data Exchange Formats:**
+{{data_format_rules_with_examples}}
+
+### Communication Patterns
+
+**Event System Patterns:**
+{{event_naming_and_structure_rules}}
+
+**State Management Patterns:**
+{{state_update_and_organization_rules}}
+
+### Process Patterns
+
+**Error Handling Patterns:**
+{{consistent_error_handling_approaches}}
+
+**Loading State Patterns:**
+{{loading_state_management_rules}}
+
+### Enforcement Guidelines
+
+**All AI Agents MUST:**
+
+- {{mandatory_pattern_1}}
+- {{mandatory_pattern_2}}
+- {{mandatory_pattern_3}}
+
+**Pattern Enforcement:**
+
+- How to verify patterns are followed
+- Where to document pattern violations
+- Process for updating patterns
+
+### Pattern Examples
+
+**Good Examples:**
+{{concrete_examples_of_correct_pattern_usage}}
+
+**Anti-Patterns:**
+{{examples_of_what_to_avoid}}
+```
+
+### 5. Present Content and Menu
+
+Show the generated patterns content and present choices:
+
+"I've documented implementation patterns that will prevent conflicts between AI agents working on this project.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 4]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Explore additional consistency patterns
+[P] Party Mode - Review patterns from different implementation perspectives
+[C] Continue - Save these patterns and move to project structure"
+
+### 6. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with current patterns
+- Process enhanced consistency rules that come back
+- Ask user: "Accept these additional pattern refinements? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with implementation patterns context
+- Process collaborative insights about potential conflicts
+- Ask user: "Accept these changes to the implementation patterns? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
+- Load `./step-06-structure.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 4.
+
+## SUCCESS METRICS:
+
+✅ All potential AI agent conflict points identified and addressed
+✅ Comprehensive patterns defined for naming, structure, and communication
+✅ Concrete examples provided for each pattern
+✅ Enforcement guidelines clearly documented
+✅ User collaborated on pattern decisions rather than receiving recommendations
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Missing potential conflict points that could cause agent conflicts
+❌ Being too prescriptive about implementation details instead of focusing on consistency
+❌ Not providing concrete examples for each pattern
+❌ Failing to address cross-cutting concerns like error handling
+❌ Not considering the chosen technology stack when defining patterns
+❌ Not presenting A/P/C menu after content generation
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-06-structure.md` to define the complete project structure.
+
+Remember: Do NOT proceed to step-06 until user explicitly selects 'C' from the A/P/C menu and content is saved!