appiq-solution 1.0.9 → 1.1.0

package/bmad-core/working-in-the-brownfield.md

@@ -0,0 +1,364 @@
+# Working in the Brownfield: A Complete Guide
+
+> **HIGHLY RECOMMENDED: Use Gemini Web or Gemini CLI for Brownfield Documentation Generation!**
+>
+> Gemini Web's 1M+ token context window or Gemini CLI (when it's working) can analyze your ENTIRE codebase, or critical sections of it, all at once (obviously within reason):
+>
+> - Upload via GitHub URL or use gemini cli in the project folder
+> - If working in the web: use `npx bmad-method flatten` to flatten your project into a single file, then upload that file to your web agent.
+
+## What is Brownfield Development?
+
+Brownfield development refers to adding features, fixing bugs, or modernizing existing software projects. Unlike greenfield (new) projects, brownfield work requires understanding existing code, respecting constraints, and ensuring new changes integrate seamlessly without breaking existing functionality.
+
+## When to Use BMad for Brownfield
+
+- Add significant new features to existing applications
+- Modernize legacy codebases
+- Integrate new technologies or services
+- Refactor complex systems
+- Fix bugs that require architectural understanding
+- Document undocumented systems
+
+## When NOT to use a Brownfield Flow
+
+If you have just completed an MVP with BMad, and you want to continue with post-MVP, its easier to just talk to the PM and ask it to work with you to create a new epic to add into the PRD, shard out the epic, update any architecture documents with the architect, and just go from there.
+
+## The Complete Brownfield Workflow
+
+1. **Follow the [<ins>User Guide - Installation</ins>](user-guide.md#installation) steps to setup your agent in the web.**
+2. **Generate a 'flattened' single file of your entire codebase** run: ```npx bmad-method flatten```
+
+### Choose Your Approach
+
+#### Approach A: PRD-First (Recommended if adding very large and complex new features, single or multiple epics or massive changes)
+
+**Best for**: Large codebases, monorepos, or when you know exactly what you want to build
+
+1. **Create PRD First** to define requirements
+2. **Document only relevant areas** based on PRD needs
+3. **More efficient** - avoids documenting unused code
+
+#### Approach B: Document-First (Good for Smaller Projects)
+
+**Best for**: Smaller codebases, unknown systems, or exploratory changes
+
+1. **Document entire system** first
+2. **Create PRD** with full context
+3. **More thorough** - captures everything
+
+### Approach A: PRD-First Workflow (Recommended)
+
+#### Phase 1: Define Requirements First
+
+**In Gemini Web (with your flattened-codebase.xml uploaded):**
+
+```bash
+@pm
+*create-brownfield-prd
+```
+
+The PM will:
+
+- **Ask about your enhancement** requirements
+- **Explore the codebase** to understand current state
+- **Identify affected areas** that need documentation
+- **Create focused PRD** with clear scope
+
+**Key Advantage**: The PRD identifies which parts of your monorepo/large codebase actually need documentation!
+
+#### Phase 2: Focused Documentation
+
+**Still in Gemini Web, now with PRD context:**
+
+```bash
+@architect
+*document-project
+```
+
+The analyst will:
+
+- **Ask about your focus** if no PRD was provided
+- **Offer options**: Create PRD, provide requirements, or describe the enhancement
+- **Reference the PRD/description** to understand scope
+- **Focus on relevant modules** identified in PRD or your description
+- **Skip unrelated areas** to keep docs lean
+- **Generate ONE architecture document** for all environments
+
+The analyst creates:
+
+- **One comprehensive architecture document** following fullstack-architecture template
+- **Covers all system aspects** in a single file
+- **Easy to copy and save** as `docs/project-architecture.md`
+- **Can be sharded later** in IDE if desired
+
+For example, if you say "Add payment processing to user service":
+
+- Documents only: user service, API endpoints, database schemas, payment integrations
+- Creates focused source tree showing only payment-related code paths
+- Skips: admin panels, reporting modules, unrelated microservices
+
+### Approach B: Document-First Workflow
+
+#### Phase 1: Document the Existing System
+
+**Best Approach - Gemini Web with 1M+ Context**:
+
+1. **Go to Gemini Web** (gemini.google.com)
+2. **Upload your project**:
+   - **Option A**: Paste your GitHub repository URL directly
+   - **Option B**: Upload your flattened-codebase.xml file
+3. **Load the analyst agent**: Upload `dist/agents/architect.txt`
+4. **Run documentation**: Type `*document-project`
+
+The analyst will generate comprehensive documentation of everything.
+
+#### Phase 2: Plan Your Enhancement
+
+##### Option A: Full Brownfield Workflow (Recommended for Major Changes)
+
+**1. Create Brownfield PRD**:
+
+```bash
+@pm
+*create-brownfield-prd
+```
+
+The PM agent will:
+
+- **Analyze existing documentation** from Phase 1
+- **Request specific enhancement details** from you
+- **Assess complexity** and recommend approach
+- **Create epic/story structure** for the enhancement
+- **Identify risks and integration points**
+
+**How PM Agent Gets Project Context**:
+
+- In Gemini Web: Already has full project context from Phase 1 documentation
+- In IDE: Will ask "Please provide the path to your existing project documentation"
+
+**Key Prompts You'll Encounter**:
+
+- "What specific enhancement or feature do you want to add?"
+- "Are there any existing systems or APIs this needs to integrate with?"
+- "What are the critical constraints we must respect?"
+- "What is your timeline and team size?"
+
+**2. Create Brownfield Architecture**:
+
+```bash
+@architect
+*create-brownfield-architecture
+```
+
+The architect will:
+
+- **Review the brownfield PRD**
+- **Design integration strategy**
+- **Plan migration approach** if needed
+- **Identify technical risks**
+- **Define compatibility requirements**
+
+##### Option B: Quick Enhancement (For Focused Changes)
+
+**For Single Epic Without Full PRD**:
+
+```bash
+@pm
+*create-brownfield-epic
+```
+
+Use when:
+
+- Enhancement is well-defined and isolated
+- Existing documentation is comprehensive
+- Changes don't impact multiple systems
+- You need quick turnaround
+
+**For Single Story**:
+
+```bash
+@pm
+*create-brownfield-story
+```
+
+Use when:
+
+- Bug fix or tiny feature
+- Very isolated change
+- No architectural impact
+- Clear implementation path
+
+### Phase 3: Validate Planning Artifacts
+
+```bash
+@po
+*execute-checklist-po
+```
+
+The PO ensures:
+
+- Compatibility with existing system
+- No breaking changes planned
+- Risk mitigation strategies in place
+- Clear integration approach
+
+### Phase 4: Save and Shard Documents
+
+1. Save your PRD and Architecture as:
+   docs/brownfield-prd.md
+   docs/brownfield-architecture.md
+2. Shard your docs:
+   In your IDE
+
+   ```bash
+   @po
+   shard docs/brownfield-prd.md
+   ```
+
+   ```bash
+   @po
+   shard docs/brownfield-architecture.md
+   ```
+
+### Phase 5: Transition to Development
+
+**Follow the [<ins>Enhanced IDE Development Workflow</ins>](enhanced-ide-development-workflow.md)**
+
+## Brownfield Best Practices
+
+### 1. Always Document First
+
+Even if you think you know the codebase:
+
+- Run `document-project` to capture current state
+- AI agents need this context
+- Discovers undocumented patterns
+
+### 2. Respect Existing Patterns
+
+The brownfield templates specifically look for:
+
+- Current coding conventions
+- Existing architectural patterns
+- Technology constraints
+- Team preferences
+
+### 3. Plan for Gradual Rollout
+
+Brownfield changes should:
+
+- Support feature flags
+- Plan rollback strategies
+- Include migration scripts
+- Maintain backwards compatibility
+
+### 4. Test Integration Thoroughly
+
+Focus testing on:
+
+- Integration points
+- Existing functionality (regression)
+- Performance impact
+- Data migrations
+
+### 5. Communicate Changes
+
+Document:
+
+- What changed and why
+- Migration instructions
+- New patterns introduced
+- Deprecation notices
+
+## Common Brownfield Scenarios
+
+### Scenario 1: Adding a New Feature
+
+1. Document existing system
+2. Create brownfield PRD focusing on integration
+3. Architecture emphasizes compatibility
+4. Stories include integration tasks
+
+### Scenario 2: Modernizing Legacy Code
+
+1. Extensive documentation phase
+2. PRD includes migration strategy
+3. Architecture plans gradual transition
+4. Stories follow strangler fig pattern
+
+### Scenario 3: Bug Fix in Complex System
+
+1. Document relevant subsystems
+2. Use `create-brownfield-story` for focused fix
+3. Include regression test requirements
+4. QA validates no side effects
+
+### Scenario 4: API Integration
+
+1. Document existing API patterns
+2. PRD defines integration requirements
+3. Architecture ensures consistent patterns
+4. Stories include API documentation updates
+
+## Troubleshooting
+
+### "The AI doesn't understand my codebase"
+
+**Solution**: Re-run `document-project` with more specific paths to critical files
+
+### "Generated plans don't fit our patterns"
+
+**Solution**: Update generated documentation with your specific conventions before planning phase
+
+### "Too much boilerplate for small changes"
+
+**Solution**: Use `create-brownfield-story` instead of full workflow
+
+### "Integration points unclear"
+
+**Solution**: Provide more context during PRD creation, specifically highlighting integration systems
+
+## Quick Reference
+
+### Brownfield-Specific Commands
+
+```bash
+# Document existing project
+@architect → *document-project
+
+# Create enhancement PRD
+@pm → *create-brownfield-prd
+
+# Create architecture with integration focus
+@architect → *create-brownfield-architecture
+
+# Quick epic creation
+@pm → *create-brownfield-epic
+
+# Single story creation
+@pm → *create-brownfield-story
+```
+
+### Decision Tree
+
+```text
+Do you have a large codebase or monorepo?
+├─ Yes → PRD-First Approach
+│   └─ Create PRD → Document only affected areas
+└─ No → Is the codebase well-known to you?
+    ├─ Yes → PRD-First Approach
+    └─ No → Document-First Approach
+
+Is this a major enhancement affecting multiple systems?
+├─ Yes → Full Brownfield Workflow
+└─ No → Is this more than a simple bug fix?
+    ├─ Yes → brownfield-create-epic
+    └─ No → brownfield-create-story
+```
+
+## Conclusion
+
+Brownfield development with BMad-Method provides structure and safety when modifying existing systems. The key is providing comprehensive context through documentation, using specialized templates that consider integration requirements, and following workflows that respect existing constraints while enabling progress.
+
+Remember: **Document First, Plan Carefully, Integrate Safely**

package/commands/README.md

@@ -0,0 +1,28 @@
+# APPIQ Commands Reference
+
+## Available Commands
+
+### `/appiq`
+Start intelligent project creation with automatic tech stack detection
+
+### `/story`
+Create a new development story with context-aware template selection
+
+### `/analyze`
+Analyze current project structure and recommend optimal workflow
+
+### `/help`
+Show all available commands with examples
+
+
+## Usage
+Simply type any command (e.g., `/appiq`) in your IDE to start the intelligent workflow.
+
+## Support
+- 📚 [User Guide](bmad-core/user-guide.md)
+- 🎯 [Agent Reference](bmad-core/agents/)
+- 💬 [Discord](https://discord.gg/gk8jAdXWmj)
+- 🐙 [GitHub](https://github.com/Viktor-Hermann/APPIQ-METHOD)
+
+---
+*Generated by APPIQ Smart Installer v4.0.0*

package/commands/analyze.md

@@ -0,0 +1,27 @@
+# /analyze
+
+## Description
+Analyze current project structure and recommend optimal workflow
+
+## Usage
+Type `/analyze` in your IDE to activate the APPIQ Smart Launcher.
+
+## What happens:
+1. **Context Analysis** - Analyzes your current project setup
+2. **Agent Activation** - Loads the bmad-smart-launcher agent
+3. **Intelligent Guidance** - Provides step-by-step workflow guidance
+4. **Task Execution** - Coordinates appropriate agents to complete tasks
+
+## Prerequisites
+- APPIQ-METHOD installed in project
+- Supported IDE (Cursor, Claude, VS Code)
+- Node.js v20+
+
+## Related Commands
+- `/appiq` - Main project creation workflow
+- `/story` - Development story creation
+- `/analyze` - Project analysis
+- `/help` - Command reference
+
+---
+*Generated by APPIQ Smart Installer v4.0.0*

package/commands/appiq.md

@@ -0,0 +1,27 @@
+# /appiq
+
+## Description
+Start intelligent project creation with automatic tech stack detection
+
+## Usage
+Type `/appiq` in your IDE to activate the APPIQ Smart Launcher.
+
+## What happens:
+1. **Context Analysis** - Analyzes your current project setup
+2. **Agent Activation** - Loads the bmad-smart-launcher agent
+3. **Intelligent Guidance** - Provides step-by-step workflow guidance
+4. **Task Execution** - Coordinates appropriate agents to complete tasks
+
+## Prerequisites
+- APPIQ-METHOD installed in project
+- Supported IDE (Cursor, Claude, VS Code)
+- Node.js v20+
+
+## Related Commands
+- `/appiq` - Main project creation workflow
+- `/story` - Development story creation
+- `/analyze` - Project analysis
+- `/help` - Command reference
+
+---
+*Generated by APPIQ Smart Installer v4.0.0*

package/commands/help.md

@@ -0,0 +1,27 @@
+# /help
+
+## Description
+Show all available commands with examples
+
+## Usage
+Type `/help` in your IDE to activate the APPIQ Smart Launcher.
+
+## What happens:
+1. **Context Analysis** - Analyzes your current project setup
+2. **Agent Activation** - Loads the bmad-smart-launcher agent
+3. **Intelligent Guidance** - Provides step-by-step workflow guidance
+4. **Task Execution** - Coordinates appropriate agents to complete tasks
+
+## Prerequisites
+- APPIQ-METHOD installed in project
+- Supported IDE (Cursor, Claude, VS Code)
+- Node.js v20+
+
+## Related Commands
+- `/appiq` - Main project creation workflow
+- `/story` - Development story creation
+- `/analyze` - Project analysis
+- `/help` - Command reference
+
+---
+*Generated by APPIQ Smart Installer v4.0.0*

package/commands/story.md

@@ -0,0 +1,27 @@
+# /story
+
+## Description
+Create a new development story with context-aware template selection
+
+## Usage
+Type `/story` in your IDE to activate the APPIQ Smart Launcher.
+
+## What happens:
+1. **Context Analysis** - Analyzes your current project setup
+2. **Agent Activation** - Loads the bmad-smart-launcher agent
+3. **Intelligent Guidance** - Provides step-by-step workflow guidance
+4. **Task Execution** - Coordinates appropriate agents to complete tasks
+
+## Prerequisites
+- APPIQ-METHOD installed in project
+- Supported IDE (Cursor, Claude, VS Code)
+- Node.js v20+
+
+## Related Commands
+- `/appiq` - Main project creation workflow
+- `/story` - Development story creation
+- `/analyze` - Project analysis
+- `/help` - Command reference
+
+---
+*Generated by APPIQ Smart Installer v4.0.0*

package/common/tasks/create-doc.md

@@ -0,0 +1,101 @@
+# Create Document from Template (YAML Driven)
+
+## ⚠️ CRITICAL EXECUTION NOTICE ⚠️
+
+**THIS IS AN EXECUTABLE WORKFLOW - NOT REFERENCE MATERIAL**
+
+When this task is invoked:
+
+1. **DISABLE ALL EFFICIENCY OPTIMIZATIONS** - This workflow requires full user interaction
+2. **MANDATORY STEP-BY-STEP EXECUTION** - Each section must be processed sequentially with user feedback
+3. **ELICITATION IS REQUIRED** - When `elicit: true`, you MUST use the 1-9 format and wait for user response
+4. **NO SHORTCUTS ALLOWED** - Complete documents cannot be created without following this workflow
+
+**VIOLATION INDICATOR:** If you create a complete document without user interaction, you have violated this workflow.
+
+## Critical: Template Discovery
+
+If a YAML Template has not been provided, list all templates from .bmad-core/templates or ask the user to provide another.
+
+## CRITICAL: Mandatory Elicitation Format
+
+**When `elicit: true`, this is a HARD STOP requiring user interaction:**
+
+**YOU MUST:**
+
+1. Present section content
+2. Provide detailed rationale (explain trade-offs, assumptions, decisions made)
+3. **STOP and present numbered options 1-9:**
+   - **Option 1:** Always "Proceed to next section"
+   - **Options 2-9:** Select 8 methods from data/elicitation-methods
+   - End with: "Select 1-9 or just type your question/feedback:"
+4. **WAIT FOR USER RESPONSE** - Do not proceed until user selects option or provides feedback
+
+**WORKFLOW VIOLATION:** Creating content for elicit=true sections without user interaction violates this task.
+
+**NEVER ask yes/no questions or use any other format.**
+
+## Processing Flow
+
+1. **Parse YAML template** - Load template metadata and sections
+2. **Set preferences** - Show current mode (Interactive), confirm output file
+3. **Process each section:**
+   - Skip if condition unmet
+   - Check agent permissions (owner/editors) - note if section is restricted to specific agents
+   - Draft content using section instruction
+   - Present content + detailed rationale
+   - **IF elicit: true** → MANDATORY 1-9 options format
+   - Save to file if possible
+4. **Continue until complete**
+
+## Detailed Rationale Requirements
+
+When presenting section content, ALWAYS include rationale that explains:
+
+- Trade-offs and choices made (what was chosen over alternatives and why)
+- Key assumptions made during drafting
+- Interesting or questionable decisions that need user attention
+- Areas that might need validation
+
+## Elicitation Results Flow
+
+After user selects elicitation method (2-9):
+
+1. Execute method from data/elicitation-methods
+2. Present results with insights
+3. Offer options:
+   - **1. Apply changes and update section**
+   - **2. Return to elicitation menu**
+   - **3. Ask any questions or engage further with this elicitation**
+
+## Agent Permissions
+
+When processing sections with agent permission fields:
+
+- **owner**: Note which agent role initially creates/populates the section
+- **editors**: List agent roles allowed to modify the section
+- **readonly**: Mark sections that cannot be modified after creation
+
+**For sections with restricted access:**
+
+- Include a note in the generated document indicating the responsible agent
+- Example: "_(This section is owned by dev-agent and can only be modified by dev-agent)_"
+
+## YOLO Mode
+
+User can type `#yolo` to toggle to YOLO mode (process all sections at once).
+
+## CRITICAL REMINDERS
+
+**❌ NEVER:**
+
+- Ask yes/no questions for elicitation
+- Use any format other than 1-9 numbered options
+- Create new elicitation methods
+
+**✅ ALWAYS:**
+
+- Use exact 1-9 format when elicit: true
+- Select options 2-9 from data/elicitation-methods only
+- Provide detailed rationale explaining decisions
+- End with "Select 1-9 or just type your question/feedback:"

package/common/tasks/execute-checklist.md

@@ -0,0 +1,93 @@
+# Checklist Validation Task
+
+This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
+
+## Available Checklists
+
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
+
+## Instructions
+
+1. **Initial Assessment**
+
+   - If user or the task being run provides a checklist name:
+     - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
+     - If multiple matches found, ask user to clarify
+     - Load the appropriate checklist from {root}/checklists/
+   - If no checklist specified:
+     - Ask the user which checklist they want to use
+     - Present the available options from the files in the checklists folder
+   - Confirm if they want to work through the checklist:
+     - Section by section (interactive mode - very time consuming)
+     - All at once (YOLO mode - recommended for checklists, there will be a summary of sections at the end to discuss)
+
+2. **Document and Artifact Gathering**
+
+   - Each checklist will specify its required documents/artifacts at the beginning
+   - Follow the checklist's specific instructions for what to gather, generally a file can be resolved in the docs folder, if not or unsure, halt and ask or confirm with the user.
+
+3. **Checklist Processing**
+
+   If in interactive mode:
+
+   - Work through each section of the checklist one at a time
+   - For each section:
+     - Review all items in the section following instructions for that section embedded in the checklist
+     - Check each item against the relevant documentation or artifacts as appropriate
+     - Present summary of findings for that section, highlighting warnings, errors and non applicable items (rationale for non-applicability).
+     - Get user confirmation before proceeding to next section or if any thing major do we need to halt and take corrective action
+
+   If in YOLO mode:
+
+   - Process all sections at once
+   - Create a comprehensive report of all findings
+   - Present the complete analysis to the user
+
+4. **Validation Approach**
+
+   For each checklist item:
+
+   - Read and understand the requirement
+   - Look for evidence in the documentation that satisfies the requirement
+   - Consider both explicit mentions and implicit coverage
+   - Aside from this, follow all checklist llm instructions
+   - Mark items as:
+     - ✅ PASS: Requirement clearly met
+     - ❌ FAIL: Requirement not met or insufficient coverage
+     - ⚠️ PARTIAL: Some aspects covered but needs improvement
+     - N/A: Not applicable to this case
+
+5. **Section Analysis**
+
+   For each section:
+
+   - think step by step to calculate pass rate
+   - Identify common themes in failed items
+   - Provide specific recommendations for improvement
+   - In interactive mode, discuss findings with user
+   - Document any user decisions or explanations
+
+6. **Final Report**
+
+   Prepare a summary that includes:
+
+   - Overall checklist completion status
+   - Pass rates by section
+   - List of failed items with context
+   - Specific recommendations for improvement
+   - Any sections or items marked as N/A with justification
+
+## Checklist Execution Methodology
+
+Each checklist now contains embedded LLM prompts and instructions that will:
+
+1. **Guide thorough thinking** - Prompts ensure deep analysis of each section
+2. **Request specific artifacts** - Clear instructions on what documents/access is needed
+3. **Provide contextual guidance** - Section-specific prompts for better validation
+4. **Generate comprehensive reports** - Final summary with detailed findings
+
+The LLM will:
+
+- Execute the complete checklist validation
+- Present a final report with pass/fail rates and key findings
+- Offer to provide detailed analysis of any section, especially those with warnings or failures