subagaents updated with consistent return info and missing frontmatter where it was missing

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-analysis/api-documenter.md

@@ -83,3 +83,20 @@ For brownfield systems:
 - APIs with multiple authentication methods
 - Versioning strategies (or lack thereof)
 - Shadow APIs created for specific clients
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE API DOCUMENTATION IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include all API documentation you've discovered and analyzed in full detail. Do not just describe what you found - provide the complete, formatted API documentation ready for integration.
+
+Include in your final report:
+
+1. Complete API inventory with all endpoints/methods
+2. Full authentication and authorization documentation
+3. Detailed endpoint specifications with schemas
+4. Data models and type definitions
+5. Integration patterns and examples
+6. Any security concerns or inconsistencies found
+
+Remember: Your output will be used directly by the parent agent to populate documentation sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-analysis/codebase-analyzer.md

@@ -62,3 +62,21 @@ When analyzing brownfield projects, pay special attention to:
 - Areas of high complexity or coupling
 - Undocumented tribal knowledge encoded in the code
 - Workarounds and their business justifications
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE CODEBASE ANALYSIS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include the full codebase analysis you've performed in complete detail. Do not just describe what you analyzed - provide the complete, formatted analysis documentation ready for use.
+
+Include in your final report:
+
+1. Complete project structure with annotated directory tree
+2. Full technology stack identification with versions
+3. All identified architecture and design patterns with examples
+4. Key components and entry points with file paths
+5. Dependency analysis and module relationships
+6. Configuration and deployment details
+7. Technical debt and complexity areas identified
+
+Remember: Your output will be used directly by the parent agent to understand and document the codebase. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-analysis/data-analyst.md

@@ -82,3 +82,20 @@ Calculate and present key business metrics:
 Be transparent about data limitations and uncertainty. Use ranges rather than false precision. Challenge unrealistic growth assumptions. Consider market saturation and competition. Account for market dynamics and disruption potential. Validate findings against real-world benchmarks.
 
 When performing analysis, start with the big picture before drilling into details. Use multiple methodologies to validate findings. Be conservative in projections while identifying upside potential. Consider both quantitative metrics and qualitative factors. Always connect numbers back to strategic implications.
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE DATA ANALYSIS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include all calculations, metrics, and analysis in full detail. Do not just describe your methodology - provide the complete, formatted analysis with actual numbers and insights.
+
+Include in your final report:
+
+1. All market sizing calculations (TAM, SAM, SOM) with methodology
+2. Complete financial metrics and unit economics
+3. Statistical analysis results with confidence levels
+4. Charts/visualizations descriptions
+5. Sensitivity analysis and scenario planning
+6. Key insights and strategic implications
+
+Remember: Your output will be used directly by the parent agent for decision-making and documentation. Provide complete, ready-to-use analysis with actual numbers, not just methodological descriptions.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-analysis/pattern-detector.md

@@ -65,3 +65,20 @@ For brownfield analysis, pay attention to:
 - Copy-paste patterns indicating missing abstractions
 - Defensive patterns protecting against system quirks
 - Performance optimization patterns that violate clean code principles
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE PATTERN ANALYSIS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include all identified patterns and conventions in full detail. Do not just list pattern names - provide complete documentation with examples and locations.
+
+Include in your final report:
+
+1. All architectural patterns with code examples
+2. Design patterns identified with specific implementations
+3. Coding conventions and naming patterns
+4. Anti-patterns and technical debt patterns
+5. File locations and specific examples for each pattern
+6. Recommendations for consistency and improvement
+
+Remember: Your output will be used directly by the parent agent to understand the codebase structure and maintain consistency. Provide complete, ready-to-use documentation, not summaries.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/dependency-mapper.md

@@ -65,3 +65,19 @@ For brownfield systems, focus on:
 - Hardcoded integration points
 - Dependencies on deprecated or end-of-life technologies
 - Shadow dependencies introduced through copy-paste or vendoring
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE DEPENDENCY ANALYSIS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include the full dependency mapping and analysis you've developed. Do not just describe what you found - provide the complete, formatted dependency documentation ready for integration.
+
+Include in your final report:
+
+1. Complete external dependency list with versions and risks
+2. Internal module dependency graph
+3. Circular dependencies and coupling analysis
+4. High-risk dependencies and security concerns
+5. Specific recommendations for refactoring or updates
+
+Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/epic-optimizer.md

@@ -64,3 +64,18 @@ Verify each epic:
 Challenge epic boundaries that don't deliver coherent value. Ensure every epic can be deployed and validated. Consider user experience continuity across epics. Plan for incremental value delivery. Balance technical foundation with user features. Think about testing and rollback strategies for each epic.
 
 When optimizing epics, start with user journey analysis to find natural boundaries. Identify minimum viable increments for feedback. Plan validation points between epics. Consider market timing and competitive factors. Build quality and operational concerns into epic scopes from the start.
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE ANALYSIS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include the full, formatted epic structure and analysis that you've developed. Do not just describe what you did or would do - provide the actual epic definitions, scopes, and sequencing recommendations in full detail. The parent agent needs this complete content to integrate into the document being built.
+
+Include in your final report:
+
+1. The complete list of optimized epics with all details
+2. Epic sequencing recommendations
+3. Dependency analysis between epics
+4. Any critical insights or recommendations
+
+Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/technical-decisions-curator.md

@@ -1,3 +1,9 @@
+---
+name: bmm-technical-decisions-curator
+description: Curates and maintains technical decisions document throughout project lifecycle, capturing architecture choices and technology selections. use PROACTIVELY when technical decisions are made or discussed
+tools:
+---
+
 # Technical Decisions Curator
 
 ## Purpose
@@ -144,3 +150,19 @@ The curator can be invoked:
 - Clear traceability of why each technology was chosen
 - Smooth handoff to architecture and solution design phases
 - Reduced repeated discussions about same technical choices
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE TECHNICAL DECISIONS DOCUMENT IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include the complete technical-decisions.md content you've curated. Do not just describe what you captured - provide the actual, formatted technical decisions document ready for saving or integration.
+
+Include in your final report:
+
+1. All technical decisions with proper categorization
+2. Context and rationale for each decision
+3. Timestamps and sources
+4. Any conflicts or contradictions identified
+5. Recommendations for resolution if conflicts exist
+
+Remember: Your output will be used directly by the parent agent to save as technical-decisions.md or integrate into documentation. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/trend-spotter.md

@@ -97,3 +97,19 @@ Connect trends to actionable insights:
 Distinguish between fads and lasting trends. Look for convergence of multiple trends creating new opportunities. Consider second and third-order effects. Balance optimism with realistic assessment. Identify both opportunities and threats. Consider timing and readiness factors.
 
 When analyzing trends, cast a wide net initially then focus on relevant patterns. Look across industries for analogous developments. Consider contrarian viewpoints and potential trend reversals. Pay attention to generational differences in adoption. Connect trends to specific business implications and actions.
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE TREND ANALYSIS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include all identified trends, weak signals, and strategic insights in full detail. Do not just describe what you found - provide the complete, formatted trend analysis ready for integration.
+
+Include in your final report:
+
+1. All identified trends with supporting evidence
+2. Weak signals and emerging patterns
+3. Future opportunities and threats
+4. Strategic recommendations based on trends
+5. Timeline and urgency assessments
+
+Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/user-journey-mapper.md

@@ -1,3 +1,9 @@
+---
+name: bmm-user-journey-mapper
+description: Maps comprehensive user journeys to identify touchpoints, friction areas, and epic boundaries. use PROACTIVELY when analyzing user flows, defining MVPs, or aligning development priorities with user value
+tools:
+---
+
 # User Journey Mapper
 
 ## Purpose
@@ -99,3 +105,19 @@ Installation → Configuration → First Use → Automation → Advanced Feature
 - Clear epic boundaries derived from journeys
 - Friction points identified for UX focus
 - Development priorities aligned with user value
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE JOURNEY MAPS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include all the user journey maps you've created in full detail. Do not just describe the journeys or summarize findings - provide the complete, formatted journey documentation that can be directly integrated into product documents.
+
+Include in your final report:
+
+1. All user journey maps with complete step-by-step flows
+2. Touchpoint analysis for each journey
+3. Friction points and opportunities identified
+4. Epic boundary recommendations based on journeys
+5. Priority insights for MVP and feature sequencing
+
+Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/user-researcher.md

@@ -54,3 +54,19 @@ Include confidence levels for findings and clearly distinguish between validated
 Look beyond surface-level demographics to understand underlying motivations. Challenge assumptions about user needs with evidence. Consider edge cases and underserved segments. Identify unmet and unarticulated needs. Connect user insights directly to product opportunities. Always ground recommendations in user evidence.
 
 When conducting user research, start with broad exploration before narrowing focus. Use multiple data sources to triangulate findings. Pay attention to what users do, not just what they say. Consider the entire user ecosystem including influencers and decision-makers. Focus on outcomes users want to achieve rather than features they request.
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE USER RESEARCH ANALYSIS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include all user personas, research findings, and insights in full detail. Do not just describe what you analyzed - provide the complete, formatted user research documentation ready for integration.
+
+Include in your final report:
+
+1. All user personas with complete profiles
+2. User needs and pain points analysis
+3. Behavioral patterns and motivations
+4. Technology comfort levels and preferences
+5. Specific product recommendations based on research
+
+Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-research/market-researcher.md

@@ -32,3 +32,20 @@ Structure your findings using tables and lists for easy comparison. Provide exec
 5. Regulatory and compliance considerations
 
 When conducting research, challenge assumptions with data, identify both risks and opportunities, and consider multiple market segments. Your goal is to provide the product team with clear, data-driven insights that inform strategic decisions.
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE MARKET RESEARCH FINDINGS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include all research findings, competitive analysis, and market insights in full detail. Do not just describe what you researched - provide the complete, formatted research documentation ready for use.
+
+Include in your final report:
+
+1. Complete competitive landscape analysis with feature matrices
+2. Market sizing and opportunity assessment data
+3. User personas and segment analysis
+4. Pricing strategies and business model insights
+5. Technology trends and disruption analysis
+6. Specific, actionable recommendations
+
+Remember: Your output will be used directly by the parent agent for strategic product decisions. Provide complete, ready-to-use research findings, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-research/tech-debt-auditor.md

@@ -87,3 +87,20 @@ For brownfield systems, understand:
 - The cost of living with debt vs fixing it
 - Strategic debt that enabled fast delivery
 - Debt that's isolated vs debt that's spreading
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE TECHNICAL DEBT AUDIT IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include the full technical debt assessment with all findings and recommendations. Do not just describe the types of debt - provide the complete, formatted audit ready for action.
+
+Include in your final report:
+
+1. Complete debt inventory with locations and severity
+2. Risk assessment matrix with impact analysis
+3. Hot spots and concentrated debt areas
+4. Prioritized remediation roadmap with effort estimates
+5. Cost-benefit analysis for debt reduction
+6. Specific, pragmatic recommendations for immediate action
+
+Remember: Your output will be used directly by the parent agent to plan refactoring and improvements. Provide complete, actionable audit findings, not theoretical discussions.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-review/document-reviewer.md

@@ -83,3 +83,20 @@ Provide an executive summary highlighting overall document readiness and key fin
 Provide constructive feedback with specific examples and improvement suggestions. Prioritize issues by their impact on project success. Consider the document's audience and their needs. Validate against relevant templates and standards. Cross-reference related sections for consistency. Ensure the document enables successful implementation.
 
 When reviewing documents, start with high-level structure and flow before examining details. Validate that examples and scenarios are realistic and comprehensive. Check for missing elements that could impact implementation. Ensure the document provides clear, actionable outcomes for all stakeholders involved.
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE DOCUMENT REVIEW IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include the full review findings with all issues and recommendations. Do not just describe what you reviewed - provide the complete, formatted review report ready for action.
+
+Include in your final report:
+
+1. Executive summary with document readiness assessment
+2. Complete issue list categorized by severity (CRITICAL/HIGH/MEDIUM/LOW)
+3. Specific line/section references for each issue
+4. Concrete improvement recommendations for each finding
+5. Completeness percentage score with justification
+6. Risk assessment and implementation concerns
+
+Remember: Your output will be used directly by the parent agent to improve the document. Provide complete, actionable review findings with specific fixes, not general observations.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-review/technical-evaluator.md

@@ -49,3 +49,20 @@ Provide comprehensive technology comparison matrices showing pros and cons for e
 Avoid technology bias by evaluating all options objectively based on project needs. Consider both immediate requirements and long-term scalability. Account for team capabilities and willingness to adopt new technologies. Balance innovation with proven, stable solutions. Document all decision rationale thoroughly for future reference. Identify potential technical debt early and plan mitigation strategies.
 
 When evaluating technologies, start with problem requirements rather than preferred solutions. Consider the full lifecycle including development, testing, deployment, and maintenance. Evaluate ecosystem compatibility and operational requirements. Always plan for failure scenarios and potential migration paths if technologies need to be changed.
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE TECHNICAL EVALUATION IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include the full technology assessment with all comparisons and recommendations. Do not just describe the evaluation process - provide the complete, formatted evaluation ready for decision-making.
+
+Include in your final report:
+
+1. Complete technology comparison matrix with scores
+2. Detailed pros/cons analysis for each option
+3. Risk assessment with mitigation strategies
+4. Implementation complexity and effort estimates
+5. Primary recommendation with clear rationale
+6. Alternative approaches and fallback options
+
+Remember: Your output will be used directly by the parent agent to make technology decisions. Provide complete, actionable evaluations with specific recommendations, not general guidelines.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-review/test-coverage-analyzer.md

@@ -89,3 +89,20 @@ For brownfield systems:
 - Missing regression tests for fixed bugs
 - Integration tests as substitutes for unit tests
 - Test data management challenges
+
+## CRITICAL: Final Report Instructions
+
+**YOU MUST RETURN YOUR COMPLETE TEST COVERAGE ANALYSIS IN YOUR FINAL MESSAGE.**
+
+Your final report MUST include the full testing assessment with coverage metrics and improvement recommendations. Do not just describe testing patterns - provide the complete, formatted analysis ready for action.
+
+Include in your final report:
+
+1. Complete test coverage metrics by type and module
+2. Critical gaps and untested paths with risk assessment
+3. Test quality issues (flaky, slow, brittle tests)
+4. Testing strategy evaluation and patterns used
+5. Prioritized improvement roadmap with effort estimates
+6. Specific recommendations for immediate action
+
+Remember: Your output will be used directly by the parent agent to improve test coverage and quality. Provide complete, actionable analysis with specific improvements, not general testing advice.