Merge 2b1bd954ff into 355ccebca2

Introduces /kiss (Keep It Simple & Short) command allowing users to
signal agents for brief, focused responses without verbose explanations.

Key Features:
- User types /kiss anywhere in message
- Agent responds in <5 lines
- Skips explanations, alternatives, exploratory questions
- Executes directly with brief confirmation
- Safety checks still apply (destructive operations)

Use Cases:
- Quick fixes and status checks
- Information retrieval
- Execution mode (skip discussion)
- Maintaining flow state

Real-world origin: tellingCube project where verbose responses
broke user focus during execution-heavy sessions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/kiss-command.md

@@ -0,0 +1,577 @@
+# BMad Method PR #3: /kiss Command (Keep It Simple & Short)
+
+**Feature Type**: User experience enhancement / Workflow optimization
+**Status**: Draft for community review
+**Origin**: tellingCube project (masemIT e.U.)
+**Author**: Mario Semper (@sempre)
+**Date**: 2025-11-23
+
+---
+
+## Summary
+
+**`/kiss` command** provides users a quick way to signal agents to keep responses concise and focused, preventing chat overload with unnecessary information.
+
+**KISS = Keep It Simple & Short**
+
+---
+
+## Problem Statement
+
+### Real-World User Frustration
+
+**Scenario**: User needs quick answer or wants to stay focused on execution, but agents provide verbose explanations, alternatives, and context that clutter the chat.
+
+**Current BMad Behavior:**
+```yaml
+User: "Create the login form component"
+
+Agent:
+  - Explains why login forms are important
+  - Lists 5 different authentication approaches
+  - Discusses security considerations
+  - Asks 3 clarifying questions
+  - Suggests 2 alternative implementations
+  - THEN creates the component
+
+❌ Result: 30 lines of chat before action, user overwhelmed
+```
+
+**What user wanted:**
+```yaml
+User: "Create the login form component /kiss"
+
+Agent:
+  - Creates the component
+  - Brief confirmation message
+
+✅ Result: 3 lines, stays focused, keeps momentum
+```
+
+---
+
+## Proposed Solution: /kiss Command
+
+### Command Syntax
+
+```bash
+/kiss
+```
+
+**Can appear anywhere in user message:**
+- At the end: `"Fix the bug in auth.ts /kiss"`
+- At the start: `"/kiss Show me the error logs"`
+- Standalone: `"/kiss"` (applies to next agent response)
+
+---
+
+## Behavior Specification
+
+### When `/kiss` is Used
+
+**Agent MUST:**
+1. ✅ **Skip explanations** - No "why" or "how it works" unless critical
+2. ✅ **Skip alternatives** - Don't offer other approaches unless asked
+3. ✅ **Skip exploratory questions** - Make reasonable assumptions
+4. ✅ **Execute directly** - Jump to action, not discussion
+5. ✅ **Confirm briefly** - 1-2 sentences max
+
+**Agent SHOULD:**
+- Present results concisely (code, output, answer)
+- Use bullet points over paragraphs
+- Omit context user already knows
+- Save details for follow-up if user asks
+
+**Agent MUST NOT:**
+- Skip critical safety checks (destructive operations still need confirmation)
+- Hide errors or important warnings
+- Omit information that would cause user to make wrong decision
+
+---
+
+## Use Cases
+
+### 1. Quick Fixes
+```
+User: "Add error handling to the login function /kiss"
+
+Agent (WITHOUT /kiss):
+"I'll add error handling to the login function. There are several
+approaches we could take:
+1. Try-catch blocks
+2. Promise rejection handling
+3. Validation middleware
+Which approach would you prefer? Also, should we log errors to
+Sentry or just console? Let me know and I'll implement..."
+
+Agent (WITH /kiss):
+"Added try-catch with Sentry logging:
+[code block]
+Done ✅"
+```
+
+### 2. Information Retrieval
+```
+User: "What's the current Stripe pricing tier configuration /kiss"
+
+Agent (WITHOUT /kiss):
+"Great question! The Stripe pricing configuration is stored in
+components/landing/PricingSection.tsx. Let me explain the structure:
+
+The pricing tiers follow a founding member model with lifetime access.
+This is interesting because... [3 more paragraphs]"
+
+Agent (WITH /kiss):
+"5 tiers: €29, €99, €299, €599, €999 (lifetime, one-time)
+Source: components/landing/PricingSection.tsx"
+```
+
+### 3. Status Checks
+```
+User: "Are all tests passing? /kiss"
+
+Agent (WITHOUT /kiss):
+"Let me run the test suite for you. Our testing strategy includes
+unit tests using Jest, integration tests, and E2E tests with Playwright.
+I'll now execute the test command... [runs tests]...
+The results show..."
+
+Agent (WITH /kiss):
+"✅ All tests passing (23/23)
+Runtime: 4.2s"
+```
+
+### 4. Execution Mode
+```
+User: "We discussed the approach earlier. Just implement it. /kiss"
+
+Agent (WITHOUT /kiss):
+"Before I implement, let me confirm the approach we discussed:
+1. Use event-sourcing architecture
+2. Store events in NeonDB
+3. Generate views via SQL
+Is this correct? Also, should I..."
+
+Agent (WITH /kiss):
+[Implements directly, shows result]
+"Implemented. Ready for review."
+```
+
+---
+
+## Implementation Options
+
+### Option A: Command Flag (Simplest)
+
+**In agent system prompt:**
+```markdown
+If user includes `/kiss` in their message:
+- Keep response under 5 lines
+- No explanations unless critical
+- Execute directly, confirm briefly
+- Skip alternatives and exploratory questions
+```
+
+**Pros:**
+- Simple to implement (prompt addition)
+- Works immediately across all agents
+- No code changes needed
+
+**Cons:**
+- Agents must remember to check for `/kiss`
+- May be forgotten in complex agent definitions
+
+---
+
+### Option B: Global Flag (Most Robust)
+
+**In BMad core:**
+```typescript
+interface UserMessage {
+  content: string
+  flags: {
+    kiss: boolean  // Detected from /kiss in message
+  }
+}
+
+function parseMessage(raw: string): UserMessage {
+  const kiss = raw.includes('/kiss')
+  const content = raw.replace('/kiss', '').trim()
+  return { content, flags: { kiss } }
+}
+```
+
+**Agent access:**
+```markdown
+Context available to all agents:
+- message.flags.kiss: boolean
+
+If true:
+- Response must be concise (< 5 lines preferred)
+- Action-first, explanation-optional
+```
+
+**Pros:**
+- Guaranteed all agents respect flag
+- Easier for agents (don't need to parse)
+- Can extend with other flags (/verbose, /explain, etc.)
+
+**Cons:**
+- Requires BMad core changes
+- Slightly more implementation work
+
+---
+
+### Option C: Mode Switch (Advanced)
+
+**User can toggle mode:**
+```bash
+*mode kiss    # All responses now concise until toggled off
+*mode normal  # Back to default verbosity
+```
+
+**Pros:**
+- Don't need to type `/kiss` every time
+- Good for execution-heavy sessions
+
+**Cons:**
+- More complex to implement
+- User might forget they're in KISS mode
+- Harder to mix verbosity levels
+
+---
+
+## Recommended: Option A (Start Simple)
+
+**Rationale:**
+- Fastest to implement (just prompt update)
+- Test user adoption before building complex infrastructure
+- Can evolve to Option B or C if popular
+
+**Implementation Steps:**
+1. Add `/kiss` detection to all agent prompts
+2. Define behavior rules (5 lines, action-first)
+3. Update BMad user guide with `/kiss` documentation
+4. Gather feedback from community
+5. Iterate based on usage patterns
+
+---
+
+## Behavior Examples (Detailed)
+
+### Example 1: Code Creation
+```
+User: "Create a validation utility for email addresses /kiss"
+
+❌ WITHOUT /kiss (Verbose):
+"I'll create a validation utility for email addresses. Email validation
+is tricky because there are many valid formats according to RFC 5322.
+I recommend using a regex pattern that covers most common cases while
+avoiding false positives. Here's my approach:
+
+1. Use standard email regex
+2. Add domain verification (optional)
+3. Sanitize input first
+4. Return boolean + error message
+
+[Creates utility]
+
+The utility handles:
+- Format validation
+- Common typo detection
+- Disposable email blocking (optional)
+
+Would you like me to add any of these additional features?"
+
+✅ WITH /kiss (Concise):
+"Created email validator:
+[code block]
+Returns {valid: boolean, error?: string}"
+```
+
+---
+
+### Example 2: Error Investigation
+```
+User: "Why is the build failing? /kiss"
+
+❌ WITHOUT /kiss (Verbose):
+"Let me investigate the build failure. I'll check several potential
+causes:
+1. TypeScript errors
+2. Missing dependencies
+3. Configuration issues
+4. Environment variables
+
+[Runs build, analyzes logs]
+
+The build is failing due to a TypeScript error in auth.ts. This is
+happening because the `User` type doesn't match the return type of
+the database query. TypeScript's type system is trying to enforce
+type safety here, which is good because..."
+
+✅ WITH /kiss (Concise):
+"Build error: Type mismatch in auth.ts:42
+Expected: User | null
+Got: User | undefined
+
+Fix: Change `getUser()` return type to `User | null`"
+```
+
+---
+
+### Example 3: Project Status
+```
+User: "What's the current sprint status? /kiss"
+
+❌ WITHOUT /kiss (Verbose):
+"Let me give you a comprehensive sprint status update. Our current
+sprint (Sprint 14) started on Monday and runs through next Friday.
+We're using 2-week sprints as defined in our agile process. Let me
+break down the status by epic:
+
+Epic 1: User Authentication
+- Story 1.1: Login form ✅ (Completed)
+- Story 1.2: Signup flow ✅ (Completed)
+- Story 1.3: Password reset 🟡 (In Progress)
+  - This one is taking longer because we discovered...
+
+Epic 2: Dashboard
+..."
+
+✅ WITH /kiss (Concise):
+"Sprint 14 (Day 8/14):
+✅ 12 stories done
+🟡 3 in progress
+⏳ 2 remaining
+On track for Friday delivery"
+```
+
+---
+
+## When NOT to Use /kiss (Safety Considerations)
+
+### Destructive Operations (Always Confirm)
+```
+User: "Delete the production database /kiss"
+
+Agent (Correct Behavior):
+"⚠️ This is a DESTRUCTIVE operation affecting production.
+
+Are you sure you want to delete the production database?
+Type 'YES DELETE PRODUCTION DATABASE' to confirm.
+
+(Note: /kiss does not skip safety checks for destructive operations)"
+```
+
+**Rationale:** User safety > brevity
+
+---
+
+### Critical Errors (Don't Hide Details)
+```
+User: "Deploy to production /kiss"
+
+Agent (Correct Behavior):
+"❌ Deploy blocked - 3 critical errors:
+1. Tests failing (auth.test.ts:45)
+2. TypeScript errors in 2 files
+3. Missing required env var: STRIPE_SECRET_KEY
+
+/kiss mode active, but showing errors because deployment would fail.
+Fix these first?"
+```
+
+**Rationale:** User needs to know WHY deployment failed
+
+---
+
+### Ambiguous Requests (Ask, Don't Assume)
+```
+User: "Update the pricing /kiss"
+
+Agent (Correct Behavior):
+"Which pricing?
+- Stripe product prices
+- Landing page display
+- Documentation
+
+(Need clarification even in /kiss mode)"
+```
+
+**Rationale:** Guessing wrong wastes more time than asking
+
+---
+
+## Benefits
+
+✅ **Reduces chat clutter** - Keeps conversation focused
+✅ **Maintains momentum** - Less reading, more doing
+✅ **Respects user expertise** - Assumes user knows context
+✅ **Faster execution** - Skip discussion, jump to action
+✅ **Optional, not forced** - User controls verbosity per-message
+
+---
+
+## Tradeoffs & Considerations
+
+### Pro: User Control
+- User decides when to use /kiss
+- Can mix verbose and concise in same session
+- No permanent mode change
+
+### Con: May Skip Helpful Context
+- New users might miss learning opportunities
+- Complex decisions might need more discussion
+- User must know to ask for details if needed
+
+**Mitigation:** Agents can offer "Want details?" at end of concise response
+
+---
+
+### Pro: Reduces Token Usage
+- Shorter agent responses = fewer tokens
+- Saves costs in high-volume sessions
+- Faster response time (less generation)
+
+### Con: May Require Follow-Up
+- User asks "Why?" after concise answer
+- Could use more tokens in total if clarification needed
+
+**Mitigation:** Agents should be smart about what's "brief enough"
+
+---
+
+## Rollout Strategy
+
+### Phase 1: Soft Launch (Week 1-2)
+- Add `/kiss` to core agent prompts
+- Update BMad user guide
+- Announce in community Discord/forum
+- Gather initial feedback
+
+### Phase 2: Refinement (Week 3-4)
+- Analyze usage patterns (how often used?)
+- Identify edge cases (when does /kiss fail?)
+- Refine behavior rules based on feedback
+- A/B test different verbosity thresholds
+
+### Phase 3: Expansion (Month 2+)
+- Consider `/explain` (opposite of /kiss)
+- Consider `/verbose` (maximum detail mode)
+- Consider mode switching (`*mode kiss`)
+- Community voting on preferred approach
+
+---
+
+## Real-World Validation
+
+**Origin Project:** tellingCube (masemIT e.U.)
+
+**User Pain Point (Mario Semper):**
+> "Sometimes I just need the answer, not a lecture. When I'm in flow state, reading 20 lines of explanation breaks my focus. /kiss would let me signal: I know what I'm doing, just execute."
+
+**Example from tellingCube:**
+```
+Mario: "Show me the current pricing tiers /kiss"
+
+River (after implementing /kiss):
+"€29, €99, €299, €599, €999 (lifetime)
+components/landing/PricingSection.tsx"
+
+Mario: "Perfect, thanks."
+```
+
+**Before /kiss:**
+River would explain the Kickstarter model, founding member strategy, tier reasoning, future pricing changes, etc. (12 lines)
+
+**After /kiss:**
+2 lines, instant answer, Mario stays in flow.
+
+---
+
+## Comparison to Similar Patterns
+
+| Pattern | Use Case | When to Use |
+|---------|----------|-------------|
+| **`/kiss`** | Quick execution, minimal chat | User knows what they want, wants brevity |
+| `/explain` | Detailed explanations | User learning, needs context |
+| `/verbose` | Maximum detail | Debugging, auditing, teaching |
+| ROF sessions | Multi-agent collaboration | Complex analysis needing multiple perspectives |
+| Pre-flight | Safety checks | High-risk public outputs |
+
+**KISS is complementary** to other patterns - can use `/kiss` within ROF sessions, etc.
+
+---
+
+## Open Questions for Community
+
+1. **Verbosity Threshold**: What's "brief enough"? 3 lines? 5 lines? 10 lines?
+2. **Default Behavior**: Should agents auto-detect when to be brief, or only via `/kiss`?
+3. **Mode vs. Flag**: Per-message `/kiss` or mode switching (`*mode kiss`)?
+4. **Opposite Command**: Should we also have `/explain` or `/verbose`?
+5. **Safety Override**: What operations ALWAYS require verbose confirmation despite `/kiss`?
+
+---
+
+## Next Steps
+
+1. **Community feedback** on approach and verbosity rules
+2. **Pilot implementation** in BMad core or as agent prompt addition
+3. **User testing** with tellingCube and other projects
+4. **Iteration** based on usage patterns
+5. **Documentation** in BMad user guide
+
+---
+
+## Proposed Documentation
+
+### User Guide Entry
+
+````markdown
+## /kiss - Keep It Simple & Short
+
+**When to use:** You want quick, concise responses without explanations.
+
+**Syntax:**
+```
+/kiss
+```
+
+**Example:**
+```
+User: "Run the tests /kiss"
+Agent: "✅ 23/23 passing (4.2s)"
+```
+
+**What changes:**
+- Responses under 5 lines (typically)
+- No explanations unless critical
+- Direct execution, brief confirmation
+- No alternatives offered
+
+**Safety:** Destructive operations still require confirmation.
+
+**Not working?** Some agents may not support /kiss yet.
+````
+
+---
+
+## References
+
+- **Source Project**: tellingCube (https://github.com/masemIT/telling-cube) [if public]
+- **User Feedback**: Mario Semper (@sempre)
+- **Related PRs**:
+  - PR #964 Ring of Fire (multi-agent collaboration)
+  - PR #965 Pre-Flight Protocol (safety framework)
+
+---
+
+**Contribution ready for review.** Let's make BMad more responsive to user workflow preferences! 🎯
+
+---
+
+**Memes Welcome:**
+- "KISS: Keeping Agents Concise Since 2025"
+- "More doing, less explaining"
+- "TL;DR mode for agents"

src/modules/bmm/_module-installer/assets/bmm-kb.md

@@ -1 +0,0 @@
-# BMad Method Master Knowledge Base Index

src/modules/bmm/_module-installer/assets/technical-decisions.md

@@ -1,30 +0,0 @@
-# Technical Decisions Log
-
-_Auto-updated during discovery and planning sessions - you can also add information here yourself_
-
-## Purpose
-
-This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for architecture.md and solution design documents.
-
-## Confirmed Decisions
-
-<!-- Technical choices explicitly confirmed by the team/user -->
-
-## Preferences
-
-<!-- Non-binding preferences mentioned during discussions -->
-
-## Constraints
-
-<!-- Hard requirements from infrastructure, compliance, or integration needs -->
-
-## To Investigate
-
-<!-- Technical questions that need research or architect input -->
-
-## Notes
-
-- This file is automatically updated when technical information is mentioned
-- Decisions here are inputs, not final architecture
-- Final technical decisions belong in architecture.md
-- Implementation details belong in solutions/\*.md and story context or dev notes.

src/modules/bmm/agents/analyst.agent.yaml

@@ -18,21 +18,25 @@ agent:
       - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`
 
   menu:
+    - trigger: workflow-status
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/workflow-status/workflow.yaml"
+      description: Get workflow status or initialize a workflow if not already done (optional)
+
     - trigger: brainstorm-project
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml"
-      description: Guided Brainstorming scoped to product development ideation and problem discovery
+      description: Guided Brainstorming session with final report (optional)
 
     - trigger: research
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.yaml"
-      description: Guided Research scoped to market and competitive analysis of a product or feature
+      description: Guided Research scoped to market and competitive analysis (optional)
 
     - trigger: product-brief
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/1-analysis/product-brief/workflow.yaml"
-      description: Create a Product Brief, a great input to then drive a PRD
+      description: Create a Product Brief (recommended input for PRD)
 
     - trigger: document-project
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/document-project/workflow.yaml"
-      description: Generate comprehensive documentation of an existing codebase, including architecture, data flows, and API contracts, and other details to aid project understanding.
+      description: Document your existing project (optional, but recommended for existing brownfield project efforts)
 
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"

src/modules/bmm/agents/architect.agent.yaml

@@ -18,25 +18,29 @@ agent:
       - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`
 
   menu:
+    - trigger: workflow-status
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/workflow-status/workflow.yaml"
+      description: Get workflow status or initialize a workflow if not already done (optional)
+
     - trigger: create-architecture
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/architecture/workflow.yaml"
-      description: Produce a Scale Adaptive Architecture
+      description: Create an Architecture Document to Guide Development of a PRD (required for BMad Method projects)
 
     - trigger: validate-architecture
       validate-workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/architecture/workflow.yaml"
-      description: Validate Architecture Document
+      description: Validate Architecture Document (Recommended, use another LLM and fresh context for best results)
 
     - trigger: implementation-readiness
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/implementation-readiness/workflow.yaml"
-      description: Validate implementation readiness - PRD, UX, Architecture, Epics aligned
+      description: Validate PRD, UX, Architecture, Epics and stories aligned (Optional but recommended before development)
 
     - trigger: create-excalidraw-diagram
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/diagrams/create-diagram/workflow.yaml"
-      description: Create system architecture or technical diagram (Excalidraw)
+      description: Create system architecture or technical diagram (Excalidraw) (Use any time you need a diagram)
 
     - trigger: create-excalidraw-dataflow
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/diagrams/create-dataflow/workflow.yaml"
-      description: Create data flow diagram (Excalidraw)
+      description: Create data flow diagram (Excalidraw) (Use any time you need a diagram)
 
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"

src/modules/bmm/agents/dev.agent.yaml

@@ -39,10 +39,6 @@ agent:
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/dev-story/workflow.yaml"
       description: "Execute Dev Story workflow (full BMM path with sprint-status)"
 
-    - trigger: story-done
-      workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-done/workflow.yaml"
-      description: "Mark story done after DoD complete"
-
     - trigger: code-review
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/code-review/workflow.yaml"
-      description: "Perform a thorough clean context QA code review on a story flagged Ready for Review"
+      description: "Perform a thorough clean context code review (Highly Recommended, use fresh context and different LLM)"

src/modules/bmm/agents/pm.agent.yaml

@@ -19,21 +19,25 @@ agent:
       - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`
 
   menu:
+    - trigger: workflow-status
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/workflow-status/workflow.yaml"
+      description: Get workflow status or initialize a workflow if not already done (optional)
+
     - trigger: create-prd
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
-      description: Create Product Requirements Document (PRD)
+      description: Create Product Requirements Document (PRD) (Required for BMad Method flow)
 
     - trigger: validate-prd
       validate-workflow: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
-      description: Validate PRD
+      description: Validate PRD (Highly Recommended, use fresh context and different LLM for best results)
 
     - trigger: create-epics-and-stories
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.yaml"
-      description: Create Epics and User Stories from PRD (Its recommended to not do this until the architecture is complete)
+      description: Create Epics and User Stories from PRD (Required for BMad Method flow AFTER the Architecture is completed)
 
     - trigger: correct-course
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course/workflow.yaml"
-      description: Course Correction Analysis
+      description: Course Correction Analysis (optional during implementation when things go off track)
       ide-only: true
 
     - trigger: party-mode

src/modules/bmm/agents/quick-flow-solo-dev.agent.yaml

@@ -21,15 +21,15 @@ agent:
   menu:
     - trigger: create-tech-spec
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yaml"
-      description: Architect a technical spec with implementation-ready stories
+      description: Architect a technical spec with implementation-ready stories (Required first step)
 
     - trigger: quick-dev
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/bmad-quick-flow/quick-dev/workflow.yaml"
-      description: Ship features from spec or direct instructions - no handoffs
+      description: Implement the tech spec end-to-end solo (Core of Quick Flow)
 
     - trigger: code-review
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/code-review/workflow.yaml"
-      description: Review code for quality, patterns, and acceptance criteria
+      description: Review code and improve it (Highly Recommended, use fresh context and different LLM for best results)
 
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"

src/modules/bmm/agents/sm.agent.yaml

@@ -26,24 +26,24 @@ agent:
   menu:
     - trigger: sprint-planning
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/sprint-planning/workflow.yaml"
-      description: Generate or update sprint-status.yaml from epic files
+      description: Generate or re-generate sprint-status.yaml from epic files (Required after Epics+Stories are created)
 
     - trigger: create-story
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story/workflow.yaml"
-      description: Create a Draft Story
+      description: Create a Draft Story (Required to prepare stories for development)
 
     - trigger: validate-create-story
       validate-workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/create-story/workflow.yaml"
-      description: (Optional) Validate Story Draft with Independent Review
+      description: Validate Story Draft (Highly Recommended, use fresh context and different LLM for best results)
 
     - trigger: epic-retrospective
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/retrospective/workflow.yaml"
       data: "{project-root}/{bmad_folder}/_cfg/agent-manifest.csv"
-      description: (Optional) Facilitate team retrospective after an epic is completed
+      description: Facilitate team retrospective after an epic is completed (Optional)
 
     - trigger: correct-course
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/correct-course/workflow.yaml"
-      description: (Optional) Execute correct-course task
+      description: Execute correct-course task (When implementation is off-track)
 
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"

src/modules/bmm/agents/ux-designer.agent.yaml

@@ -25,7 +25,7 @@ agent:
   menu:
     - trigger: create-ux-design
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml"
-      description: Conduct Design Thinking Workshop to Define the User Specification with PRD as input
+      description: Generate a UX Design and UI Plan from a PRD (Recommended before creating Architecture)
 
     - trigger: validate-design
       validate-workflow: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml"

src/modules/bmm/workflows/workflow-status/init/instructions.md

@@ -3,7 +3,7 @@
 <critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: workflow-init/workflow.yaml</critical>
 <critical>Communicate in {communication_language} with {user_name}</critical>
-<critical>This workflow handles BOTH new projects AND legacy projects being migrated to BMad Method</critical>
+<critical>This workflow handles BOTH new projects AND legacy projects following the BMad Method</critical>
 
 <workflow>
 
@@ -12,7 +12,7 @@
 
 <action>Perform comprehensive scan for existing work:
 
-- BMM artifacts: PRD, tech-spec, epics, architecture, UX, brief, research, brainstorm
+- BMM artifacts: PRD, epics, architecture, UX, brief, research, brainstorm
 - Implementation: stories, sprint-status, workflow-status
 - Codebase: source directories, package files, git repo
 - Check both {output_folder} and {sprint_artifacts} locations
@@ -53,31 +53,31 @@ Happy building! 🚀</output>
 
 <ask>How would you like to proceed?
 
-a) **Continue** - Work with existing artifacts
+1. **Continue** - Work with existing artifacts
-b) **Archive & Start Fresh** - Move old work to archive
+2. **Archive & Start Fresh** - Move old work to archive
-c) **Express Setup** - I know exactly what I need
+3. **Express Setup** - I know exactly what I need
-d) **Guided Setup** - Walk me through options
+4. **Guided Setup** - Walk me through options
 
-Choice [a/b/c/d]:</ask>
+Choice [1-4]</ask>
 
-  <check if="choice == a">
+  <check if="choice == 1">
     <action>Set continuing_existing = true</action>
     <action>Store found artifacts</action>
     <action>Continue to step 7 (detect track from artifacts)</action>
   </check>
 
-  <check if="choice == b">
+  <check if="choice == 2">
     <ask>Archive existing work? (y/n)</ask>
     <action if="y">Move artifacts to {output_folder}/archive/</action>
     <output>Ready for fresh start!</output>
     <action>Continue to step 3</action>
   </check>
 
-  <check if="choice == c">
+  <check if="choice == 3">
     <action>Jump to step 3 (express path)</action>
   </check>
 
-  <check if="choice == d">
+  <check if="choice == 4">
     <action>Continue to step 4 (guided path)</action>
   </check>
 </check>
@@ -85,16 +85,16 @@ Choice [a/b/c/d]:</ask>
 <check if="state == CLEAN">
   <ask>Setup approach:
 
-a) **Express** - I know what I need
+1. **Express** - I know what I need
-b) **Guided** - Show me the options
+2. **Guided** - Show me the options
 
-Choice [a/b]:</ask>
+Choice [1 or 2]:</ask>
 
-  <check if="choice == a">
+  <check if="choice == 1">
     <action>Continue to step 3 (express)</action>
   </check>
 
-  <check if="choice == b">
+  <check if="choice == 2">
     <action>Continue to step 4 (guided)</action>
   </check>
 </check>
@@ -102,20 +102,22 @@ Choice [a/b]:</ask>
 
 <step n="3" goal="Express setup path">
 <ask>Is this for:
-1) **New project** (greenfield)
+1. **New project** (greenfield)
-2) **Existing codebase** (brownfield)
+2. **Existing codebase** (brownfield)
 
 Choice [1/2]:</ask>
 <action>Set field_type based on choice</action>
 
 <ask>Planning approach:
 
-1. **Quick Flow** - Minimal planning, fast to code
+1. **BMad Method** - Full planning for complex projects
-2. **BMad Method** - Full planning for complex projects
+2. **Enterprise Method** - Extended planning with security/DevOps
-3. **Enterprise Method** - Extended planning with security/DevOps
 
-Choice [1/2/3]:</ask>
+Choice [1/2]:</ask>
-<action>Map to selected_track: quick-flow/method/enterprise</action>
+<action>Map to selected_track: method/enterprise</action>
+
+<output>🚀 **For Quick Flow (minimal planning, straight to code):**
+Load the **quick-flow-solo-dev** agent instead - use Quick Flow agent for faster development</output>
 
 <template-output>field_type</template-output>
 <template-output>selected_track</template-output>
@@ -135,8 +137,8 @@ Choice [1/2/3]:</ask>
 
 <check if="field_type unclear AND codebase exists">
   <ask>I see existing code. Are you:
-1) **Modifying** existing codebase (brownfield)
+1. **Modifying** existing codebase (brownfield)
-2) **Starting fresh** - code is just scaffold (greenfield)
+2. **Starting fresh** - code is just scaffold (greenfield)
 
 Choice [1/2]:</ask>
 <action>Set field_type based on answer</action>
@@ -165,44 +167,60 @@ Continue with software workflows? (y/n)</output>
 </step>
 
 <step n="5" goal="Guided setup - select track">
-<output>Based on your project, here are your planning options:
+<output>Based on your project, here are your BMad Method planning options:
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**1. Quick Flow** 🚀
+**1. BMad Method** 🎯 {{#if recommended}}(RECOMMENDED){{/if}}
-
-- Minimal planning, straight to code
-- Best for: Simple features, bug fixes
-- Risk: Potential rework if complexity emerges
-
-**2. BMad Method** 🎯 {{#if recommended}}(RECOMMENDED){{/if}}
 
 - Full planning: PRD + UX + Architecture
 - Best for: Products, platforms, complex features
 - Benefit: AI agents have complete context for better results
 
-**3. Enterprise Method** 🏢
+**2. Enterprise Method** 🏢
 
 - Extended: Method + Security + DevOps + Testing
 - Best for: Enterprise, compliance, mission-critical
 - Benefit: Comprehensive planning for complex systems
 
+**🚀 For Quick Flow (minimal planning, straight to code):**
+Load the **quick-flow-solo-dev** agent instead - use Quick Flow agent for faster development
+
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 {{#if brownfield}}
 💡 Architecture creates focused solution design from your codebase, keeping AI agents on track.
 {{/if}}</output>
 
-<ask>Which approach fits best?
+<ask>Which BMad Method approach fits best?
 
-1. Quick Flow
+1. BMad Method {{#if recommended}}(recommended){{/if}}
-2. BMad Method {{#if recommended}}(recommended){{/if}}
+2. Enterprise Method
-3. Enterprise Method
+3. Help me decide
-4. Help me decide
+4. Switch to Quick Flow (use quick-flow-solo-dev agent)
 
 Choice [1/2/3/4]:</ask>
 
 <check if="choice == 4">
+  <output>🚀 **Switching to Quick Flow!**
+
+Load the **quick-flow-solo-dev** agent instead:
+
+- Start a new chat
+- Load the quick-flow-solo-dev agent
+- Use Quick Flow for minimal planning and faster development
+
+Quick Flow is perfect for:
+
+- Simple features and bug fixes
+- Rapid prototyping
+- When you want to get straight to code
+
+Happy coding! 🚀</output>
+<action>Exit workflow</action>
+</check>
+
+<check if="choice == 3">
   <ask>What concerns you about choosing?</ask>
   <action>Provide tailored guidance based on concerns</action>
   <action>Loop back to choice</action>
@@ -215,7 +233,7 @@ Choice [1/2/3/4]:</ask>
 <step n="6" goal="Discovery workflows selection (unified)">
 <action>Determine available discovery workflows based on:
 - field_type (greenfield gets product-brief option)
-- selected_track (quick-flow skips product-brief)
+- selected_track (method/enterprise options)
 </action>
 
 <check if="field_type == greenfield AND selected_track in [method, enterprise]">
@@ -229,7 +247,7 @@ Choice [1/2/3/4]:</ask>
 Enter numbers (e.g., "1,3" or "all" or "none"): </ask>
 </check>
 
-<check if="field_type == brownfield OR selected_track == quick-flow">
+<check if="field_type == brownfield AND selected_track in [method, enterprise]">
   <output>Optional discovery workflows:</output>
   <ask>Include any of these?
 
@@ -250,7 +268,7 @@ Enter numbers (e.g., "1,2" or "none"): </ask>
 <template-output>research_requested</template-output>
 <template-output>product_brief_requested</template-output>
 
-<check if="brownfield AND selected_track != quick-flow">
+<check if="brownfield">
   <output>💡 **Note:** For brownfield projects, run document-project workflow first to analyze your codebase.</output>
 </check>
 </step>
@@ -258,18 +276,18 @@ Enter numbers (e.g., "1,2" or "none"): </ask>
 <step n="7" goal="Detect track from artifacts" if="continuing_existing OR migrating_legacy">
 <action>Analyze artifacts to detect track:
 - Has PRD → BMad Method
-- Has tech-spec only → Quick Flow
 - Has Security/DevOps → Enterprise Method
+- Has tech-spec only → Suggest switching to quick-flow-solo-dev agent
 </action>
 
 <output>Detected: **{{detected_track}}** based on {{found_artifacts}}</output>
 <ask>Correct? (y/n)</ask>
 
-<ask if="n">Which track instead?
+<ask if="n">Which BMad Method track instead?
 
-1. Quick Flow
+1. BMad Method
-2. BMad Method
+2. Enterprise Method
-3. Enterprise Method
+3. Switch to Quick Flow (use quick-flow-solo-dev agent)
 
 Choice:</ask>
 
@@ -298,11 +316,8 @@ Choice:</ask>
 {{#if brownfield}}Prerequisites: document-project{{/if}}
 {{#if has_discovery}}Discovery: {{list_selected_discovery}}{{/if}}
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
 {{workflow_path_summary}}
-
+</output>
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</output>
 
 <ask>Create workflow tracking file? (y/n)</ask>
 
@@ -326,9 +341,6 @@ To check progress: /bmad:bmm:workflows:workflow-status
 Happy building! 🚀</output>
 </check>
 
-<check if="n">
-  <output>No problem! Run workflow-init again when ready.</output>
-</check>
 </step>
 
 </workflow>

src/modules/bmm/workflows/workflow-status/instructions.md

@@ -37,12 +37,19 @@
 <action>Search {output_folder}/ for file: bmm-workflow-status.yaml</action>
 
 <check if="no status file found">
-  <output>No workflow status found. To get started:
+  <output>No workflow status found.</output>
+  <ask>Would you like to run Workflow Init now? (y/n)</ask>
 
-Load analyst agent and run: `workflow-init`
+  <check if="response == y OR response == yes">
+    <action>Launching workflow-init to set up your project tracking...</action>
+    <invoke-workflow path="{project-root}/{bmad_folder}/bmm/workflows/workflow-status/init/workflow.yaml"></invoke-workflow>
+    <action>Exit workflow and let workflow-init take over</action>
+  </check>
 
-This will guide you through project setup and create your workflow path.</output>
+  <check if="else">
-<action>Exit workflow</action>
+    <output>No workflow status file. Run workflow-init when ready to enable progress tracking.</output>
+    <action>Exit workflow</action>
+  </check>
 </check>
 
 <check if="status file found">

src/modules/bmm/workflows/workflow-status/paths/quick-flow-brownfield.yaml

@@ -1,67 +0,0 @@
-# BMad Quick Flow - Brownfield
-# Fast spec-driven development for existing codebases (1-10 stories typically)
-
-method_name: "BMad Quick Flow"
-track: "quick-flow"
-field_type: "brownfield"
-description: "Spec-driven development for brownfield projects - streamlined path with codebase context"
-
-phases:
-  - prerequisite: true
-    name: "Documentation"
-    conditional: "if_undocumented"
-    note: "NOT a phase - prerequisite for brownfield without docs"
-    workflows:
-      - id: "document-project"
-        required: true
-        agent: "analyst"
-        command: "document-project"
-        output: "Comprehensive project documentation"
-        purpose: "Generate codebase context for spec engineering"
-
-  - phase: 0
-    name: "Discovery (Optional)"
-    optional: true
-    note: "User-selected during workflow-init"
-    workflows:
-      - id: "brainstorm-project"
-        optional: true
-        agent: "analyst"
-        command: "brainstorm-project"
-        included_by: "user_choice"
-
-      - id: "research"
-        optional: true
-        agent: "analyst"
-        command: "research"
-        included_by: "user_choice"
-
-  - phase: 1
-    name: "Spec Engineering"
-    required: true
-    workflows:
-      - id: "create-tech-spec"
-        required: true
-        agent: "quick-flow-solo-dev"
-        command: "create-tech-spec"
-        output: "Technical Specification with implementation-ready stories"
-        note: "Stories include codebase context from document-project"
-
-  - phase: 2
-    name: "Implementation"
-    required: true
-    note: "Barry executes all stories, optional code-review after each"
-    workflows:
-      - id: "dev-spec"
-        required: true
-        repeat: true
-        agent: "quick-flow-solo-dev"
-        command: "dev-spec"
-        note: "Execute stories from spec - Barry is the one-man powerhouse"
-
-      - id: "code-review"
-        optional: true
-        repeat: true
-        agent: "quick-flow-solo-dev"
-        command: "code-review"
-        note: "Review completed story implementation"

src/modules/bmm/workflows/workflow-status/paths/quick-flow-greenfield.yaml

@@ -1,56 +0,0 @@
-# BMad Quick Flow - Greenfield
-# Fast spec-driven development path (1-10 stories typically)
-
-method_name: "BMad Quick Flow"
-track: "quick-flow"
-field_type: "greenfield"
-description: "Spec-driven development for greenfield projects - streamlined path without sprint overhead"
-
-phases:
-  - phase: 0
-    name: "Discovery (Optional)"
-    optional: true
-    note: "User-selected during workflow-init"
-    workflows:
-      - id: "brainstorm-project"
-        optional: true
-        agent: "analyst"
-        command: "brainstorm-project"
-        included_by: "user_choice"
-
-      - id: "research"
-        optional: true
-        agent: "analyst"
-        command: "research"
-        included_by: "user_choice"
-        note: "Can have multiple research workflows"
-
-  - phase: 1
-    name: "Spec Engineering"
-    required: true
-    workflows:
-      - id: "create-tech-spec"
-        required: true
-        agent: "quick-flow-solo-dev"
-        command: "create-tech-spec"
-        output: "Technical Specification with implementation-ready stories"
-        note: "Stories contain all context for execution"
-
-  - phase: 2
-    name: "Implementation"
-    required: true
-    note: "Barry executes all stories, optional code-review after each"
-    workflows:
-      - id: "dev-spec"
-        required: true
-        repeat: true
-        agent: "quick-flow-solo-dev"
-        command: "dev-spec"
-        note: "Execute stories from spec - Barry is the one-man powerhouse"
-
-      - id: "code-review"
-        optional: true
-        repeat: true
-        agent: "quick-flow-solo-dev"
-        command: "code-review"
-        note: "Review completed story implementation"