appiq-solution 1.0.9 → 1.1.0

package/bmad-core/tasks/create-brownfield-story.md

@@ -0,0 +1,304 @@
+# Create Brownfield Story Task
+
+## Purpose
+
+Create detailed, implementation-ready stories for brownfield projects where traditional sharded PRD/architecture documents may not exist. This task bridges the gap between various documentation formats (document-project output, brownfield PRDs, epics, or user documentation) and executable stories for the Dev agent.
+
+## When to Use This Task
+
+**Use this task when:**
+
+- Working on brownfield projects with non-standard documentation
+- Stories need to be created from document-project output
+- Working from brownfield epics without full PRD/architecture
+- Existing project documentation doesn't follow BMad v4+ structure
+- Need to gather additional context from user during story creation
+
+**Use create-next-story when:**
+
+- Working with properly sharded PRD and v4 architecture documents
+- Following standard greenfield or well-documented brownfield workflow
+- All technical context is available in structured format
+
+## Task Execution Instructions
+
+### 0. Documentation Context
+
+Check for available documentation in this order:
+
+1. **Sharded PRD/Architecture** (docs/prd/, docs/architecture/)
+   - If found, recommend using create-next-story task instead
+
+2. **Brownfield Architecture Document** (docs/brownfield-architecture.md or similar)
+   - Created by document-project task
+   - Contains actual system state, technical debt, workarounds
+
+3. **Brownfield PRD** (docs/prd.md)
+   - May contain embedded technical details
+
+4. **Epic Files** (docs/epics/ or similar)
+   - Created by brownfield-create-epic task
+
+5. **User-Provided Documentation**
+   - Ask user to specify location and format
+
+### 1. Story Identification and Context Gathering
+
+#### 1.1 Identify Story Source
+
+Based on available documentation:
+
+- **From Brownfield PRD**: Extract stories from epic sections
+- **From Epic Files**: Read epic definition and story list
+- **From User Direction**: Ask user which specific enhancement to implement
+- **No Clear Source**: Work with user to define the story scope
+
+#### 1.2 Gather Essential Context
+
+CRITICAL: For brownfield stories, you MUST gather enough context for safe implementation. Be prepared to ask the user for missing information.
+
+**Required Information Checklist:**
+
+- [ ] What existing functionality might be affected?
+- [ ] What are the integration points with current code?
+- [ ] What patterns should be followed (with examples)?
+- [ ] What technical constraints exist?
+- [ ] Are there any "gotchas" or workarounds to know about?
+
+If any required information is missing, list the missing information and ask the user to provide it.
+
+### 2. Extract Technical Context from Available Sources
+
+#### 2.1 From Document-Project Output
+
+If using brownfield-architecture.md from document-project:
+
+- **Technical Debt Section**: Note any workarounds affecting this story
+- **Key Files Section**: Identify files that will need modification
+- **Integration Points**: Find existing integration patterns
+- **Known Issues**: Check if story touches problematic areas
+- **Actual Tech Stack**: Verify versions and constraints
+
+#### 2.2 From Brownfield PRD
+
+If using brownfield PRD:
+
+- **Technical Constraints Section**: Extract all relevant constraints
+- **Integration Requirements**: Note compatibility requirements
+- **Code Organization**: Follow specified patterns
+- **Risk Assessment**: Understand potential impacts
+
+#### 2.3 From User Documentation
+
+Ask the user to help identify:
+
+- Relevant technical specifications
+- Existing code examples to follow
+- Integration requirements
+- Testing approaches used in the project
+
+### 3. Story Creation with Progressive Detail Gathering
+
+#### 3.1 Create Initial Story Structure
+
+Start with the story template, filling in what's known:
+
+```markdown
+# Story {{Enhancement Title}}
+
+## Status: Draft
+
+## Story
+
+As a {{user_type}},
+I want {{enhancement_capability}},
+so that {{value_delivered}}.
+
+## Context Source
+
+- Source Document: {{document name/type}}
+- Enhancement Type: {{single feature/bug fix/integration/etc}}
+- Existing System Impact: {{brief assessment}}
+```
+
+#### 3.2 Develop Acceptance Criteria
+
+Critical: For brownfield, ALWAYS include criteria about maintaining existing functionality
+
+Standard structure:
+
+1. New functionality works as specified
+2. Existing {{affected feature}} continues to work unchanged  
+3. Integration with {{existing system}} maintains current behavior
+4. No regression in {{related area}}
+5. Performance remains within acceptable bounds
+
+#### 3.3 Gather Technical Guidance
+
+Critical: This is where you'll need to be interactive with the user if information is missing
+
+Create Dev Technical Guidance section with available information:
+
+```markdown
+## Dev Technical Guidance
+
+### Existing System Context
+[Extract from available documentation]
+
+### Integration Approach
+[Based on patterns found or ask user]
+
+### Technical Constraints
+[From documentation or user input]
+
+### Missing Information
+
+Critical: List anything you couldn't find that dev will need and ask for the missing information
+
+### 4. Task Generation with Safety Checks
+
+#### 4.1 Generate Implementation Tasks
+
+Based on gathered context, create tasks that:
+
+- Include exploration tasks if system understanding is incomplete
+- Add verification tasks for existing functionality
+- Include rollback considerations
+- Reference specific files/patterns when known
+
+Example task structure for brownfield:
+
+```markdown
+## Tasks / Subtasks
+
+- [ ] Task 1: Analyze existing {{component/feature}} implementation
+  - [ ] Review {{specific files}} for current patterns
+  - [ ] Document integration points
+  - [ ] Identify potential impacts
+
+- [ ] Task 2: Implement {{new functionality}}
+  - [ ] Follow pattern from {{example file}}
+  - [ ] Integrate with {{existing component}}
+  - [ ] Maintain compatibility with {{constraint}}
+
+- [ ] Task 3: Verify existing functionality
+  - [ ] Test {{existing feature 1}} still works
+  - [ ] Verify {{integration point}} behavior unchanged
+  - [ ] Check performance impact
+
+- [ ] Task 4: Add tests
+  - [ ] Unit tests following {{project test pattern}}
+  - [ ] Integration test for {{integration point}}
+  - [ ] Update existing tests if needed
+```
+
+### 5. Risk Assessment and Mitigation
+
+CRITICAL: for brownfield - always include risk assessment
+
+Add section for brownfield-specific risks:
+
+```markdown
+## Risk Assessment
+
+### Implementation Risks
+- **Primary Risk**: {{main risk to existing system}}
+- **Mitigation**: {{how to address}}
+- **Verification**: {{how to confirm safety}}
+
+### Rollback Plan
+- {{Simple steps to undo changes if needed}}
+
+### Safety Checks
+- [ ] Existing {{feature}} tested before changes
+- [ ] Changes can be feature-flagged or isolated
+- [ ] Rollback procedure documented
+```
+
+### 6. Final Story Validation
+
+Before finalizing:
+
+1. **Completeness Check**:
+   - [ ] Story has clear scope and acceptance criteria
+   - [ ] Technical context is sufficient for implementation
+   - [ ] Integration approach is defined
+   - [ ] Risks are identified with mitigation
+
+2. **Safety Check**:
+   - [ ] Existing functionality protection included
+   - [ ] Rollback plan is feasible
+   - [ ] Testing covers both new and existing features
+
+3. **Information Gaps**:
+   - [ ] All critical missing information gathered from user
+   - [ ] Remaining unknowns documented for dev agent
+   - [ ] Exploration tasks added where needed
+
+### 7. Story Output Format
+
+Save the story with appropriate naming:
+
+- If from epic: `docs/stories/epic-{n}-story-{m}.md`
+- If standalone: `docs/stories/brownfield-{feature-name}.md`
+- If sequential: Follow existing story numbering
+
+Include header noting documentation context:
+
+```markdown
+# Story: {{Title}}
+
+<!-- Source: {{documentation type used}} -->
+<!-- Context: Brownfield enhancement to {{existing system}} -->
+
+## Status: Draft
+[Rest of story content...]
+```
+
+### 8. Handoff Communication
+
+Provide clear handoff to the user:
+
+```text
+Brownfield story created: {{story title}}
+
+Source Documentation: {{what was used}}
+Story Location: {{file path}}
+
+Key Integration Points Identified:
+- {{integration point 1}}
+- {{integration point 2}}
+
+Risks Noted:
+- {{primary risk}}
+
+{{If missing info}}: 
+Note: Some technical details were unclear. The story includes exploration tasks to gather needed information during implementation.
+
+Next Steps:
+1. Review story for accuracy
+2. Verify integration approach aligns with your system
+3. Approve story or request adjustments
+4. Dev agent can then implement with safety checks
+```
+
+## Success Criteria
+
+The brownfield story creation is successful when:
+
+1. Story can be implemented without requiring dev to search multiple documents
+2. Integration approach is clear and safe for existing system
+3. All available technical context has been extracted and organized
+4. Missing information has been identified and addressed
+5. Risks are documented with mitigation strategies
+6. Story includes verification of existing functionality
+7. Rollback approach is defined
+
+## Important Notes
+
+- This task is specifically for brownfield projects with non-standard documentation
+- Always prioritize existing system stability over new features
+- When in doubt, add exploration and verification tasks
+- It's better to ask the user for clarification than make assumptions
+- Each story should be self-contained for the dev agent
+- Include references to existing code patterns when available

package/bmad-core/tasks/create-deep-research-prompt.md

@@ -0,0 +1,289 @@
+# Create Deep Research Prompt Task
+
+This task helps create comprehensive research prompts for various types of deep analysis. It can process inputs from brainstorming sessions, project briefs, market research, or specific research questions to generate targeted prompts for deeper investigation.
+
+## Purpose
+
+Generate well-structured research prompts that:
+
+- Define clear research objectives and scope
+- Specify appropriate research methodologies
+- Outline expected deliverables and formats
+- Guide systematic investigation of complex topics
+- Ensure actionable insights are captured
+
+## Research Type Selection
+
+CRITICAL: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.
+
+### 1. Research Focus Options
+
+Present these numbered options to the user:
+
+1. **Product Validation Research**
+
+   - Validate product hypotheses and market fit
+   - Test assumptions about user needs and solutions
+   - Assess technical and business feasibility
+   - Identify risks and mitigation strategies
+
+2. **Market Opportunity Research**
+
+   - Analyze market size and growth potential
+   - Identify market segments and dynamics
+   - Assess market entry strategies
+   - Evaluate timing and market readiness
+
+3. **User & Customer Research**
+
+   - Deep dive into user personas and behaviors
+   - Understand jobs-to-be-done and pain points
+   - Map customer journeys and touchpoints
+   - Analyze willingness to pay and value perception
+
+4. **Competitive Intelligence Research**
+
+   - Detailed competitor analysis and positioning
+   - Feature and capability comparisons
+   - Business model and strategy analysis
+   - Identify competitive advantages and gaps
+
+5. **Technology & Innovation Research**
+
+   - Assess technology trends and possibilities
+   - Evaluate technical approaches and architectures
+   - Identify emerging technologies and disruptions
+   - Analyze build vs. buy vs. partner options
+
+6. **Industry & Ecosystem Research**
+
+   - Map industry value chains and dynamics
+   - Identify key players and relationships
+   - Analyze regulatory and compliance factors
+   - Understand partnership opportunities
+
+7. **Strategic Options Research**
+
+   - Evaluate different strategic directions
+   - Assess business model alternatives
+   - Analyze go-to-market strategies
+   - Consider expansion and scaling paths
+
+8. **Risk & Feasibility Research**
+
+   - Identify and assess various risk factors
+   - Evaluate implementation challenges
+   - Analyze resource requirements
+   - Consider regulatory and legal implications
+
+9. **Custom Research Focus**
+
+   - User-defined research objectives
+   - Specialized domain investigation
+   - Cross-functional research needs
+
+### 2. Input Processing
+
+**If Project Brief provided:**
+
+- Extract key product concepts and goals
+- Identify target users and use cases
+- Note technical constraints and preferences
+- Highlight uncertainties and assumptions
+
+**If Brainstorming Results provided:**
+
+- Synthesize main ideas and themes
+- Identify areas needing validation
+- Extract hypotheses to test
+- Note creative directions to explore
+
+**If Market Research provided:**
+
+- Build on identified opportunities
+- Deepen specific market insights
+- Validate initial findings
+- Explore adjacent possibilities
+
+**If Starting Fresh:**
+
+- Gather essential context through questions
+- Define the problem space
+- Clarify research objectives
+- Establish success criteria
+
+## Process
+
+### 3. Research Prompt Structure
+
+CRITICAL: collaboratively develop a comprehensive research prompt with these components.
+
+#### A. Research Objectives
+
+CRITICAL: collaborate with the user to articulate clear, specific objectives for the research.
+
+- Primary research goal and purpose
+- Key decisions the research will inform
+- Success criteria for the research
+- Constraints and boundaries
+
+#### B. Research Questions
+
+CRITICAL: collaborate with the user to develop specific, actionable research questions organized by theme.
+
+**Core Questions:**
+
+- Central questions that must be answered
+- Priority ranking of questions
+- Dependencies between questions
+
+**Supporting Questions:**
+
+- Additional context-building questions
+- Nice-to-have insights
+- Future-looking considerations
+
+#### C. Research Methodology
+
+**Data Collection Methods:**
+
+- Secondary research sources
+- Primary research approaches (if applicable)
+- Data quality requirements
+- Source credibility criteria
+
+**Analysis Frameworks:**
+
+- Specific frameworks to apply
+- Comparison criteria
+- Evaluation methodologies
+- Synthesis approaches
+
+#### D. Output Requirements
+
+**Format Specifications:**
+
+- Executive summary requirements
+- Detailed findings structure
+- Visual/tabular presentations
+- Supporting documentation
+
+**Key Deliverables:**
+
+- Must-have sections and insights
+- Decision-support elements
+- Action-oriented recommendations
+- Risk and uncertainty documentation
+
+### 4. Prompt Generation
+
+**Research Prompt Template:**
+
+```markdown
+## Research Objective
+
+[Clear statement of what this research aims to achieve]
+
+## Background Context
+
+[Relevant information from project brief, brainstorming, or other inputs]
+
+## Research Questions
+
+### Primary Questions (Must Answer)
+
+1. [Specific, actionable question]
+2. [Specific, actionable question]
+   ...
+
+### Secondary Questions (Nice to Have)
+
+1. [Supporting question]
+2. [Supporting question]
+   ...
+
+## Research Methodology
+
+### Information Sources
+
+- [Specific source types and priorities]
+
+### Analysis Frameworks
+
+- [Specific frameworks to apply]
+
+### Data Requirements
+
+- [Quality, recency, credibility needs]
+
+## Expected Deliverables
+
+### Executive Summary
+
+- Key findings and insights
+- Critical implications
+- Recommended actions
+
+### Detailed Analysis
+
+[Specific sections needed based on research type]
+
+### Supporting Materials
+
+- Data tables
+- Comparison matrices
+- Source documentation
+
+## Success Criteria
+
+[How to evaluate if research achieved its objectives]
+
+## Timeline and Priority
+
+[If applicable, any time constraints or phasing]
+```
+
+### 5. Review and Refinement
+
+1. **Present Complete Prompt**
+
+   - Show the full research prompt
+   - Explain key elements and rationale
+   - Highlight any assumptions made
+
+2. **Gather Feedback**
+
+   - Are the objectives clear and correct?
+   - Do the questions address all concerns?
+   - Is the scope appropriate?
+   - Are output requirements sufficient?
+
+3. **Refine as Needed**
+   - Incorporate user feedback
+   - Adjust scope or focus
+   - Add missing elements
+   - Clarify ambiguities
+
+### 6. Next Steps Guidance
+
+**Execution Options:**
+
+1. **Use with AI Research Assistant**: Provide this prompt to an AI model with research capabilities
+2. **Guide Human Research**: Use as a framework for manual research efforts
+3. **Hybrid Approach**: Combine AI and human research using this structure
+
+**Integration Points:**
+
+- How findings will feed into next phases
+- Which team members should review results
+- How to validate findings
+- When to revisit or expand research
+
+## Important Notes
+
+- The quality of the research prompt directly impacts the quality of insights gathered
+- Be specific rather than general in research questions
+- Consider both current state and future implications
+- Balance comprehensiveness with focus
+- Document assumptions and limitations clearly
+- Plan for iterative refinement based on initial findings

package/bmad-core/tasks/create-next-story.md

@@ -0,0 +1,112 @@
+# Create Next Story Task
+
+## Purpose
+
+To identify the next logical story based on project progress and epic definitions, and then to prepare a comprehensive, self-contained, and actionable story file using the `Story Template`. This task ensures the story is enriched with all necessary technical context, requirements, and acceptance criteria, making it ready for efficient implementation by a Developer Agent with minimal need for additional research or finding its own context.
+
+## SEQUENTIAL Task Execution (Do not proceed until current Task is complete)
+
+### 0. Load Core Configuration and Check Workflow
+
+- Load `{root}/core-config.yaml` from the project root
+- If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy it from GITHUB bmad-core/core-config.yaml and configure it for your project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure core-config.yaml before proceeding."
+- Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`, `workflow.*`
+
+### 1. Identify Next Story for Preparation
+
+#### 1.1 Locate Epic Files and Review Existing Stories
+
+- Based on `prdSharded` from config, locate epic files (sharded location/pattern or monolithic PRD sections)
+- If `devStoryLocation` has story files, load the highest `{epicNum}.{storyNum}.story.md` file
+- **If highest story exists:**
+  - Verify status is 'Done'. If not, alert user: "ALERT: Found incomplete story! File: {lastEpicNum}.{lastStoryNum}.story.md Status: [current status] You should fix this story first, but would you like to accept risk & override to create the next story in draft?"
+  - If proceeding, select next sequential story in the current epic
+  - If epic is complete, prompt user: "Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed. Would you like to: 1) Begin Epic {epicNum + 1} with story 1 2) Select a specific story to work on 3) Cancel story creation"
+  - **CRITICAL**: NEVER automatically skip to another epic. User MUST explicitly instruct which story to create.
+- **If no story files exist:** The next story is ALWAYS 1.1 (first story of first epic)
+- Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}"
+
+### 2. Gather Story Requirements and Previous Story Context
+
+- Extract story requirements from the identified epic file
+- If previous story exists, review Dev Agent Record sections for:
+  - Completion Notes and Debug Log References
+  - Implementation deviations and technical decisions
+  - Challenges encountered and lessons learned
+- Extract relevant insights that inform the current story's preparation
+
+### 3. Gather Architecture Context
+
+#### 3.1 Determine Architecture Reading Strategy
+
+- **If `architectureVersion: >= v4` and `architectureSharded: true`**: Read `{architectureShardedLocation}/index.md` then follow structured reading order below
+- **Else**: Use monolithic `architectureFile` for similar sections
+
+#### 3.2 Read Architecture Documents Based on Story Type
+
+**For ALL Stories:** tech-stack.md, unified-project-structure.md, coding-standards.md, testing-strategy.md
+
+**For Backend/API Stories, additionally:** data-models.md, database-schema.md, backend-architecture.md, rest-api-spec.md, external-apis.md
+
+**For Frontend/UI Stories, additionally:** frontend-architecture.md, components.md, core-workflows.md, data-models.md
+
+**For Full-Stack Stories:** Read both Backend and Frontend sections above
+
+#### 3.3 Extract Story-Specific Technical Details
+
+Extract ONLY information directly relevant to implementing the current story. Do NOT invent new libraries, patterns, or standards not in the source documents.
+
+Extract:
+
+- Specific data models, schemas, or structures the story will use
+- API endpoints the story must implement or consume
+- Component specifications for UI elements in the story
+- File paths and naming conventions for new code
+- Testing requirements specific to the story's features
+- Security or performance considerations affecting the story
+
+ALWAYS cite source documents: `[Source: architecture/{filename}.md#{section}]`
+
+### 4. Verify Project Structure Alignment
+
+- Cross-reference story requirements with Project Structure Guide from `docs/architecture/unified-project-structure.md`
+- Ensure file paths, component locations, or module names align with defined structures
+- Document any structural conflicts in "Project Structure Notes" section within the story draft
+
+### 5. Populate Story Template with Full Context
+
+- Create new story file: `{devStoryLocation}/{epicNum}.{storyNum}.story.md` using Story Template
+- Fill in basic story information: Title, Status (Draft), Story statement, Acceptance Criteria from Epic
+- **`Dev Notes` section (CRITICAL):**
+  - CRITICAL: This section MUST contain ONLY information extracted from architecture documents. NEVER invent or assume technical details.
+  - Include ALL relevant technical details from Steps 2-3, organized by category:
+    - **Previous Story Insights**: Key learnings from previous story
+    - **Data Models**: Specific schemas, validation rules, relationships [with source references]
+    - **API Specifications**: Endpoint details, request/response formats, auth requirements [with source references]
+    - **Component Specifications**: UI component details, props, state management [with source references]
+    - **File Locations**: Exact paths where new code should be created based on project structure
+    - **Testing Requirements**: Specific test cases or strategies from testing-strategy.md
+    - **Technical Constraints**: Version requirements, performance considerations, security rules
+  - Every technical detail MUST include its source reference: `[Source: architecture/{filename}.md#{section}]`
+  - If information for a category is not found in the architecture docs, explicitly state: "No specific guidance found in architecture docs"
+- **`Tasks / Subtasks` section:**
+  - Generate detailed, sequential list of technical tasks based ONLY on: Epic Requirements, Story AC, Reviewed Architecture Information
+  - Each task must reference relevant architecture documentation
+  - Include unit testing as explicit subtasks based on the Testing Strategy
+  - Link tasks to ACs where applicable (e.g., `Task 1 (AC: 1, 3)`)
+- Add notes on project structure alignment or discrepancies found in Step 4
+
+### 6. Story Draft Completion and Review
+
+- Review all sections for completeness and accuracy
+- Verify all source references are included for technical details
+- Ensure tasks align with both epic requirements and architecture constraints
+- Update status to "Draft" and save the story file
+- Execute `{root}/tasks/execute-checklist` `{root}/checklists/story-draft-checklist`
+- Provide summary to user including:
+  - Story created: `{devStoryLocation}/{epicNum}.{storyNum}.story.md`
+  - Status: Draft
+  - Key technical components included from architecture docs
+  - Any deviations or conflicts noted between epic and architecture
+  - Checklist Results
+  - Next steps: For Complex stories, suggest the user carefully review the story draft and also optionally have the PO run the task `{root}/tasks/validate-next-story`