bmad-plus 0.7.5 → 0.8.0

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

@@ -1,379 +1,379 @@
-# Step 6: Project Structure & Boundaries
-
-## 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 defining complete project structure and clear boundaries
-- 🗺️ MAP requirements/epics to architectural components
-- ⚠️ 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
-- 🗺️ Create complete project tree, not generic placeholders
-- ⚠️ Present A/P/C menu after generating project structure
-- 💾 ONLY save when user chooses C (Continue)
-- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` 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 explore innovative project organization approaches
-- **P (Party Mode)**: Bring multiple perspectives to evaluate project structure trade-offs
-- **C (Continue)**: Save the project structure and proceed to validation
-
-## 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:
-
-- All previous architectural decisions are complete
-- Implementation patterns and consistency rules are defined
-- Focus on physical project structure and component boundaries
-- Map requirements to specific files and directories
-
-## YOUR TASK:
-
-Define the complete project structure and architectural boundaries based on all decisions made, creating a concrete implementation guide for AI agents.
-
-## PROJECT STRUCTURE SEQUENCE:
-
-### 1. Analyze Requirements Mapping
-
-Map project requirements to architectural components:
-
-**From Epics (if available):**
-"Epic: {{epic_name}} → Lives in {{module/directory/service}}"
-
-- User stories within the epic
-- Cross-epic dependencies
-- Shared components needed
-
-**From FR Categories (if no epics):**
-"FR Category: {{fr_category_name}} → Lives in {{module/directory/service}}"
-
-- Related functional requirements
-- Shared functionality across categories
-- Integration points between categories
-
-### 2. Define Project Directory Structure
-
-Based on technology stack and patterns, create the complete project structure:
-
-**Root Configuration Files:**
-
-- Package management files (package.json, requirements.txt, etc.)
-- Build and development configuration
-- Environment configuration files
-- CI/CD pipeline files
-- Documentation files
-
-**Source Code Organization:**
-
-- Application entry points
-- Core application structure
-- Feature/module organization
-- Shared utilities and libraries
-- Configuration and environment files
-
-**Test Organization:**
-
-- Unit test locations and structure
-- Integration test organization
-- End-to-end test structure
-- Test utilities and fixtures
-
-**Build and Distribution:**
-
-- Build output directories
-- Distribution files
-- Static assets
-- Documentation build
-
-### 3. Define Integration Boundaries
-
-Map how components communicate and where boundaries exist:
-
-**API Boundaries:**
-
-- External API endpoints
-- Internal service boundaries
-- Authentication and authorization boundaries
-- Data access layer boundaries
-
-**Component Boundaries:**
-
-- Frontend component communication patterns
-- State management boundaries
-- Service communication patterns
-- Event-driven integration points
-
-**Data Boundaries:**
-
-- Database schema boundaries
-- Data access patterns
-- Caching boundaries
-- External data integration points
-
-### 4. Create Complete Project Tree
-
-Generate a comprehensive directory structure showing all files and directories:
-
-**Technology-Specific Structure Examples:**
-
-**Next.js Full-Stack:**
-
-```
-project-name/
-├── README.md
-├── package.json
-├── next.config.js
-├── tailwind.config.js
-├── tsconfig.json
-├── .env.local
-├── .env.example
-├── .gitignore
-├── .github/
-│   └── workflows/
-│       └── ci.yml
-├── src/
-│   ├── app/
-│   │   ├── globals.css
-│   │   ├── layout.tsx
-│   │   └── page.tsx
-│   ├── components/
-│   │   ├── ui/
-│   │   ├── forms/
-│   │   └── features/
-│   ├── lib/
-│   │   ├── db.ts
-│   │   ├── auth.ts
-│   │   └── utils.ts
-│   ├── types/
-│   └── middleware.ts
-├── prisma/
-│   ├── schema.prisma
-│   └── migrations/
-├── tests/
-│   ├── __mocks__/
-│   ├── components/
-│   └── e2e/
-└── public/
-    └── assets/
-```
-
-**API Backend (NestJS):**
-
-```
-project-name/
-├── package.json
-├── nest-cli.json
-├── tsconfig.json
-├── .env
-├── .env.example
-├── .gitignore
-├── README.md
-├── src/
-│   ├── main.ts
-│   ├── app.module.ts
-│   ├── config/
-│   ├── modules/
-│   │   ├── auth/
-│   │   ├── users/
-│   │   └── common/
-│   ├── services/
-│   ├── repositories/
-│   ├── decorators/
-│   ├── pipes/
-│   ├── guards/
-│   └── interceptors/
-├── test/
-│   ├── unit/
-│   ├── integration/
-│   └── e2e/
-├── prisma/
-│   ├── schema.prisma
-│   └── migrations/
-└── docker-compose.yml
-```
-
-### 5. Map Requirements to Structure
-
-Create explicit mapping from project requirements to specific files/directories:
-
-**Epic/Feature Mapping:**
-"Epic: User Management
-
-- Components: src/components/features/users/
-- Services: src/services/users/
-- API Routes: src/app/api/users/
-- Database: prisma/migrations/_*users*_
-- Tests: tests/features/users/"
-
-**Cross-Cutting Concerns:**
-"Authentication System
-
-- Components: src/components/auth/
-- Services: src/services/auth/
-- Middleware: src/middleware/auth.ts
-- Guards: src/guards/auth.guard.ts
-- Tests: tests/auth/"
-
-### 6. Generate Structure Content
-
-Prepare the content to append to the document:
-
-#### Content Structure:
-
-```markdown
-## Project Structure & Boundaries
-
-### Complete Project Directory Structure
-```
-
-{{complete_project_tree_with_all_files_and_directories}}
-
-```
-
-### Architectural Boundaries
-
-**API Boundaries:**
-{{api_boundary_definitions_and_endpoints}}
-
-**Component Boundaries:**
-{{component_communication_patterns_and_boundaries}}
-
-**Service Boundaries:**
-{{service_integration_patterns_and_boundaries}}
-
-**Data Boundaries:**
-{{data_access_patterns_and_boundaries}}
-
-### Requirements to Structure Mapping
-
-**Feature/Epic Mapping:**
-{{mapping_of_epics_or_features_to_specific_directories}}
-
-**Cross-Cutting Concerns:**
-{{mapping_of_shared_functionality_to_locations}}
-
-### Integration Points
-
-**Internal Communication:**
-{{how_components_within_the_project_communicate}}
-
-**External Integrations:**
-{{third_party_service_integration_points}}
-
-**Data Flow:**
-{{how_data_flows_through_the_architecture}}
-
-### File Organization Patterns
-
-**Configuration Files:**
-{{where_and_how_config_files_are_organized}}
-
-**Source Organization:**
-{{how_source_code_is_structured_and_organized}}
-
-**Test Organization:**
-{{how_tests_are_structured_and_organized}}
-
-**Asset Organization:**
-{{how_static_and_dynamic_assets_are_organized}}
-
-### Development Workflow Integration
-
-**Development Server Structure:**
-{{how_the_project_is organized_for_development}}
-
-**Build Process Structure:**
-{{how_the_build_process_uses_the_project_structure}}
-
-**Deployment Structure:**
-{{how_the_project_structure_supports_deployment}}
-```
-
-### 7. Present Content and Menu
-
-Show the generated project structure content and present choices:
-
-"I've created a complete project structure based on all our architectural decisions.
-
-**Here's what I'll add to the document:**
-
-[Show the complete markdown content from step 6]
-
-**What would you like to do?**
-[A] Advanced Elicitation - Explore innovative project organization approaches
-[P] Party Mode - Review structure from different development perspectives
-[C] Continue - Save this structure and move to architecture validation"
-
-### 8. Handle Menu Selection
-
-#### If 'A' (Advanced Elicitation):
-
-- Invoke the `bmad-advanced-elicitation` skill with current project structure
-- Process enhanced organizational insights that come back
-- Ask user: "Accept these changes to the project structure? (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 project structure context
-- Process collaborative insights about organization trade-offs
-- Ask user: "Accept these changes to the project structure? (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, 6]`
-- Load `./step-07-validation.md`
-
-## APPEND TO DOCUMENT:
-
-When user selects 'C', append the content directly to the document using the structure from step 6.
-
-## SUCCESS METRICS:
-
-✅ Complete project tree defined with all files and directories
-✅ All architectural boundaries clearly documented
-✅ Requirements/epics mapped to specific locations
-✅ Integration points and communication patterns defined
-✅ Project structure aligned with chosen technology stack
-✅ A/P/C menu presented and handled correctly
-✅ Content properly appended to document when C selected
-
-## FAILURE MODES:
-
-❌ Creating generic placeholder structure instead of specific, complete tree
-❌ Not mapping requirements to specific files and directories
-❌ Missing important integration boundaries
-❌ Not considering the chosen technology stack in structure design
-❌ Not defining how components communicate across boundaries
-❌ 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-07-validation.md` to validate architectural coherence and completeness.
-
-Remember: Do NOT proceed to step-07 until user explicitly selects 'C' from the A/P/C menu and content is saved!
+# Step 6: Project Structure & Boundaries
+
+## 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 defining complete project structure and clear boundaries
+- 🗺️ MAP requirements/epics to architectural components
+- ⚠️ 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
+- 🗺️ Create complete project tree, not generic placeholders
+- ⚠️ Present A/P/C menu after generating project structure
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` 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 explore innovative project organization approaches
+- **P (Party Mode)**: Bring multiple perspectives to evaluate project structure trade-offs
+- **C (Continue)**: Save the project structure and proceed to validation
+
+## 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:
+
+- All previous architectural decisions are complete
+- Implementation patterns and consistency rules are defined
+- Focus on physical project structure and component boundaries
+- Map requirements to specific files and directories
+
+## YOUR TASK:
+
+Define the complete project structure and architectural boundaries based on all decisions made, creating a concrete implementation guide for AI agents.
+
+## PROJECT STRUCTURE SEQUENCE:
+
+### 1. Analyze Requirements Mapping
+
+Map project requirements to architectural components:
+
+**From Epics (if available):**
+"Epic: {{epic_name}} → Lives in {{module/directory/service}}"
+
+- User stories within the epic
+- Cross-epic dependencies
+- Shared components needed
+
+**From FR Categories (if no epics):**
+"FR Category: {{fr_category_name}} → Lives in {{module/directory/service}}"
+
+- Related functional requirements
+- Shared functionality across categories
+- Integration points between categories
+
+### 2. Define Project Directory Structure
+
+Based on technology stack and patterns, create the complete project structure:
+
+**Root Configuration Files:**
+
+- Package management files (package.json, requirements.txt, etc.)
+- Build and development configuration
+- Environment configuration files
+- CI/CD pipeline files
+- Documentation files
+
+**Source Code Organization:**
+
+- Application entry points
+- Core application structure
+- Feature/module organization
+- Shared utilities and libraries
+- Configuration and environment files
+
+**Test Organization:**
+
+- Unit test locations and structure
+- Integration test organization
+- End-to-end test structure
+- Test utilities and fixtures
+
+**Build and Distribution:**
+
+- Build output directories
+- Distribution files
+- Static assets
+- Documentation build
+
+### 3. Define Integration Boundaries
+
+Map how components communicate and where boundaries exist:
+
+**API Boundaries:**
+
+- External API endpoints
+- Internal service boundaries
+- Authentication and authorization boundaries
+- Data access layer boundaries
+
+**Component Boundaries:**
+
+- Frontend component communication patterns
+- State management boundaries
+- Service communication patterns
+- Event-driven integration points
+
+**Data Boundaries:**
+
+- Database schema boundaries
+- Data access patterns
+- Caching boundaries
+- External data integration points
+
+### 4. Create Complete Project Tree
+
+Generate a comprehensive directory structure showing all files and directories:
+
+**Technology-Specific Structure Examples:**
+
+**Next.js Full-Stack:**
+
+```
+project-name/
+├── README.md
+├── package.json
+├── next.config.js
+├── tailwind.config.js
+├── tsconfig.json
+├── .env.local
+├── .env.example
+├── .gitignore
+├── .github/
+│   └── workflows/
+│       └── ci.yml
+├── src/
+│   ├── app/
+│   │   ├── globals.css
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   ├── components/
+│   │   ├── ui/
+│   │   ├── forms/
+│   │   └── features/
+│   ├── lib/
+│   │   ├── db.ts
+│   │   ├── auth.ts
+│   │   └── utils.ts
+│   ├── types/
+│   └── middleware.ts
+├── prisma/
+│   ├── schema.prisma
+│   └── migrations/
+├── tests/
+│   ├── __mocks__/
+│   ├── components/
+│   └── e2e/
+└── public/
+    └── assets/
+```
+
+**API Backend (NestJS):**
+
+```
+project-name/
+├── package.json
+├── nest-cli.json
+├── tsconfig.json
+├── .env
+├── .env.example
+├── .gitignore
+├── README.md
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── config/
+│   ├── modules/
+│   │   ├── auth/
+│   │   ├── users/
+│   │   └── common/
+│   ├── services/
+│   ├── repositories/
+│   ├── decorators/
+│   ├── pipes/
+│   ├── guards/
+│   └── interceptors/
+├── test/
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+├── prisma/
+│   ├── schema.prisma
+│   └── migrations/
+└── docker-compose.yml
+```
+
+### 5. Map Requirements to Structure
+
+Create explicit mapping from project requirements to specific files/directories:
+
+**Epic/Feature Mapping:**
+"Epic: User Management
+
+- Components: src/components/features/users/
+- Services: src/services/users/
+- API Routes: src/app/api/users/
+- Database: prisma/migrations/_*users*_
+- Tests: tests/features/users/"
+
+**Cross-Cutting Concerns:**
+"Authentication System
+
+- Components: src/components/auth/
+- Services: src/services/auth/
+- Middleware: src/middleware/auth.ts
+- Guards: src/guards/auth.guard.ts
+- Tests: tests/auth/"
+
+### 6. Generate Structure Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+```markdown
+## Project Structure & Boundaries
+
+### Complete Project Directory Structure
+```
+
+{{complete_project_tree_with_all_files_and_directories}}
+
+```
+
+### Architectural Boundaries
+
+**API Boundaries:**
+{{api_boundary_definitions_and_endpoints}}
+
+**Component Boundaries:**
+{{component_communication_patterns_and_boundaries}}
+
+**Service Boundaries:**
+{{service_integration_patterns_and_boundaries}}
+
+**Data Boundaries:**
+{{data_access_patterns_and_boundaries}}
+
+### Requirements to Structure Mapping
+
+**Feature/Epic Mapping:**
+{{mapping_of_epics_or_features_to_specific_directories}}
+
+**Cross-Cutting Concerns:**
+{{mapping_of_shared_functionality_to_locations}}
+
+### Integration Points
+
+**Internal Communication:**
+{{how_components_within_the_project_communicate}}
+
+**External Integrations:**
+{{third_party_service_integration_points}}
+
+**Data Flow:**
+{{how_data_flows_through_the_architecture}}
+
+### File Organization Patterns
+
+**Configuration Files:**
+{{where_and_how_config_files_are_organized}}
+
+**Source Organization:**
+{{how_source_code_is_structured_and_organized}}
+
+**Test Organization:**
+{{how_tests_are_structured_and_organized}}
+
+**Asset Organization:**
+{{how_static_and_dynamic_assets_are_organized}}
+
+### Development Workflow Integration
+
+**Development Server Structure:**
+{{how_the_project_is organized_for_development}}
+
+**Build Process Structure:**
+{{how_the_build_process_uses_the_project_structure}}
+
+**Deployment Structure:**
+{{how_the_project_structure_supports_deployment}}
+```
+
+### 7. Present Content and Menu
+
+Show the generated project structure content and present choices:
+
+"I've created a complete project structure based on all our architectural decisions.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Explore innovative project organization approaches
+[P] Party Mode - Review structure from different development perspectives
+[C] Continue - Save this structure and move to architecture validation"
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with current project structure
+- Process enhanced organizational insights that come back
+- Ask user: "Accept these changes to the project structure? (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 project structure context
+- Process collaborative insights about organization trade-offs
+- Ask user: "Accept these changes to the project structure? (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, 6]`
+- Load `./step-07-validation.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Complete project tree defined with all files and directories
+✅ All architectural boundaries clearly documented
+✅ Requirements/epics mapped to specific locations
+✅ Integration points and communication patterns defined
+✅ Project structure aligned with chosen technology stack
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Creating generic placeholder structure instead of specific, complete tree
+❌ Not mapping requirements to specific files and directories
+❌ Missing important integration boundaries
+❌ Not considering the chosen technology stack in structure design
+❌ Not defining how components communicate across boundaries
+❌ 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-07-validation.md` to validate architectural coherence and completeness.
+
+Remember: Do NOT proceed to step-07 until user explicitly selects 'C' from the A/P/C menu and content is saved!