npm - agentvibes - Versions diffs - 2.12.4 → 2.12.6 - Mend

agentvibes 2.12.4 → 2.12.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (429) hide show

package/.bmad/bmm/docs/quick-spec-flow.md DELETED Viewed

@@ -1,652 +0,0 @@
-# BMad Quick Spec Flow
-**Perfect for:** Bug fixes, small features, rapid prototyping, and quick enhancements
-**Time to implementation:** Minutes, not hours
----
-## What is Quick Spec Flow?
-Quick Spec Flow is a **streamlined alternative** to the full BMad Method for Quick Flow track projects. Instead of going through Product Brief → PRD → Architecture, you go **straight to a context-aware technical specification** and start coding.
-### When to Use Quick Spec Flow
-✅ **Use Quick Flow track when:**
-- Single bug fix or small enhancement
-- Small feature with clear scope (typically 1-15 stories)
-- Rapid prototyping or experimentation
-- Adding to existing brownfield codebase
-- You know exactly what you want to build
-❌ **Use BMad Method or Enterprise tracks when:**
-- Building new products or major features
-- Need stakeholder alignment
-- Complex multi-team coordination
-- Requires extensive planning and architecture
-💡 **Not sure?** Run `workflow-init` to get a recommendation based on your project's needs!
----
-## Quick Spec Flow Overview
-```mermaid
-flowchart TD
-    START[Step 1: Run Tech-Spec Workflow]
-    DETECT[Detects project stack<br/>package.json, requirements.txt, etc.]
-    ANALYZE[Analyzes brownfield codebase<br/>if exists]
-    TEST[Detects test frameworks<br/>and conventions]
-    CONFIRM[Confirms conventions<br/>with you]
-    GENERATE[Generates context-rich<br/>tech-spec]
-    STORIES[Creates ready-to-implement<br/>stories]
-    OPTIONAL[Step 2: Optional<br/>Generate Story Context<br/>SM Agent<br/>For complex scenarios only]
-    IMPL[Step 3: Implement<br/>DEV Agent<br/>Code, test, commit]
-    DONE[DONE! 🚀]
-    START --> DETECT
-    DETECT --> ANALYZE
-    ANALYZE --> TEST
-    TEST --> CONFIRM
-    CONFIRM --> GENERATE
-    GENERATE --> STORIES
-    STORIES --> OPTIONAL
-    OPTIONAL -.->|Optional| IMPL
-    STORIES --> IMPL
-    IMPL --> DONE
-    style START fill:#bfb,stroke:#333,stroke-width:2px,color:#000
-    style OPTIONAL fill:#ffb,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5,color:#000
-    style IMPL fill:#bbf,stroke:#333,stroke-width:2px,color:#000
-    style DONE fill:#f9f,stroke:#333,stroke-width:3px,color:#000
-```
----
-## Single Atomic Change
-**Best for:** Bug fixes, single file changes, isolated improvements
-### What You Get
-1. **tech-spec.md** - Comprehensive technical specification with:
-   - Problem statement and solution
-   - Detected framework versions and dependencies
-   - Brownfield code patterns (if applicable)
-   - Existing test patterns to follow
-   - Specific file paths to modify
-   - Complete implementation guidance
-2. **story-[slug].md** - Single user story ready for development
-### Quick Spec Flow Commands
-```bash
-# Start Quick Spec Flow (no workflow-init needed!)
-# Load PM agent and run tech-spec
-# When complete, implement directly:
-# Load DEV agent and run dev-story
-```
-### What Makes It Quick
-- ✅ No Product Brief needed
-- ✅ No PRD needed
-- ✅ No Architecture doc needed
-- ✅ Auto-detects your stack
-- ✅ Auto-analyzes brownfield code
-- ✅ Auto-validates quality
-- ✅ Story context optional (tech-spec is comprehensive!)
-### Example Single Change Scenarios
-- "Fix the login validation bug"
-- "Add email field to user registration form"
-- "Update API endpoint to return additional field"
-- "Improve error handling in payment processing"
----
-## Coherent Small Feature
-**Best for:** Small features with 2-3 related user stories
-### What You Get
-1. **tech-spec.md** - Same comprehensive spec as single change projects
-2. **epics.md** - Epic organization with story breakdown
-3. **story-[epic-slug]-1.md** - First story
-4. **story-[epic-slug]-2.md** - Second story
-5. **story-[epic-slug]-3.md** - Third story (if needed)
-### Quick Spec Flow Commands
-```bash
-# Start Quick Spec Flow
-# Load PM agent and run tech-spec
-# Optional: Organize stories as a sprint
-# Load SM agent and run sprint-planning
-# Implement story-by-story:
-# Load DEV agent and run dev-story for each story
-```
-### Story Sequencing
-Stories are **automatically validated** to ensure proper sequence:
-- ✅ No forward dependencies (Story 2 can't depend on Story 3)
-- ✅ Clear dependency documentation
-- ✅ Infrastructure → Features → Polish order
-- ✅ Backend → Frontend flow
-### Example Small Feature Scenarios
-- "Add OAuth social login (Google, GitHub, Twitter)"
-- "Build user profile page with avatar upload"
-- "Implement basic search with filters"
-- "Add dark mode toggle to application"
----
-## Smart Context Discovery
-Quick Spec Flow automatically discovers and uses:
-### 1. Existing Documentation
-- Product briefs (if they exist)
-- Research documents
-- `document-project` output (brownfield codebase map)
-### 2. Project Stack
-- **Node.js:** package.json → frameworks, dependencies, scripts, test framework
-- **Python:** requirements.txt, pyproject.toml → packages, tools
-- **Ruby:** Gemfile → gems and versions
-- **Java:** pom.xml, build.gradle → Maven/Gradle dependencies
-- **Go:** go.mod → modules
-- **Rust:** Cargo.toml → crates
-- **PHP:** composer.json → packages
-### 3. Brownfield Code Patterns
-- Directory structure and organization
-- Existing code patterns (class-based, functional, MVC)
-- Naming conventions (camelCase, snake_case, PascalCase)
-- Test frameworks and patterns
-- Code style (semicolons, quotes, indentation)
-- Linter/formatter configs
-- Error handling patterns
-- Logging conventions
-- Documentation style
-### 4. Convention Confirmation
-**IMPORTANT:** Quick Spec Flow detects your conventions and **asks for confirmation**:
-```
-I've detected these conventions in your codebase:
-Code Style:
-- ESLint with Airbnb config
-- Prettier with single quotes, 2-space indent
-- No semicolons
-Test Patterns:
-- Jest test framework
-- .test.js file naming
-- expect() assertion style
-Should I follow these existing conventions? (yes/no)
-```
-**You decide:** Conform to existing patterns or establish new standards!
----
-## Modern Best Practices via WebSearch
-Quick Spec Flow stays current by using WebSearch when appropriate:
-### For Greenfield Projects
-- Searches for latest framework versions
-- Recommends official starter templates
-- Suggests modern best practices
-### For Outdated Dependencies
-- Detects if your dependencies are >2 years old
-- Searches for migration guides
-- Notes upgrade complexity
-### Starter Template Recommendations
-For greenfield projects, Quick Spec Flow recommends:
-**React:**
-- Vite (modern, fast)
-- Next.js (full-stack)
-**Python:**
-- cookiecutter templates
-- FastAPI starter
-**Node.js:**
-- NestJS CLI
-- express-generator
-**Benefits:**
-- ✅ Modern best practices baked in
-- ✅ Proper project structure
-- ✅ Build tooling configured
-- ✅ Testing framework set up
-- ✅ Faster time to first feature
----
-## UX/UI Considerations
-For user-facing changes, Quick Spec Flow captures:
-- UI components affected (create vs modify)
-- UX flow changes (current vs new)
-- Responsive design needs (mobile, tablet, desktop)
-- Accessibility requirements:
-  - Keyboard navigation
-  - Screen reader compatibility
-  - ARIA labels
-  - Color contrast standards
-- User feedback patterns:
-  - Loading states
-  - Error messages
-  - Success confirmations
-  - Progress indicators
----
-## Auto-Validation and Quality Assurance
-Quick Spec Flow **automatically validates** everything:
-### Tech-Spec Validation (Always Runs)
-Checks:
-- ✅ Context gathering completeness
-- ✅ Definitiveness (no "use X or Y" statements)
-- ✅ Brownfield integration quality
-- ✅ Stack alignment
-- ✅ Implementation readiness
-Generates scores:
-```
-✅ Validation Passed!
-- Context Gathering: Comprehensive
-- Definitiveness: All definitive
-- Brownfield Integration: Excellent
-- Stack Alignment: Perfect
-- Implementation Readiness: ✅ Ready
-```
-### Story Validation (Multi-Story Features)
-Checks:
-- ✅ Story sequence (no forward dependencies!)
-- ✅ Acceptance criteria quality (specific, testable)
-- ✅ Completeness (all tech spec tasks covered)
-- ✅ Clear dependency documentation
-**Auto-fixes issues if found!**
----
-## Complete User Journey
-### Scenario 1: Bug Fix (Single Change)
-**Goal:** Fix login validation bug
-**Steps:**
-1. **Start:** Load PM agent, say "I want to fix the login validation bug"
-2. **PM runs tech-spec workflow:**
-   - Asks: "What problem are you solving?"
-   - You explain the validation issue
-   - Detects your Node.js stack (Express 4.18.2, Jest for testing)
-   - Analyzes existing UserService code patterns
-   - Asks: "Should I follow your existing conventions?" → You say yes
-   - Generates tech-spec.md with specific file paths and patterns
-   - Creates story-login-fix.md
-3. **Implement:** Load DEV agent, run `dev-story`
-   - DEV reads tech-spec (has all context!)
-   - Implements fix following existing patterns
-   - Runs tests (following existing Jest patterns)
-   - Done!
-**Total time:** 15-30 minutes (mostly implementation)
----
-### Scenario 2: Small Feature (Multi-Story)
-**Goal:** Add OAuth social login (Google, GitHub)
-**Steps:**
-1. **Start:** Load PM agent, say "I want to add OAuth social login"
-2. **PM runs tech-spec workflow:**
-   - Asks about the feature scope
-   - You specify: Google and GitHub OAuth
-   - Detects your stack (Next.js 13.4, NextAuth.js already installed!)
-   - Analyzes existing auth patterns
-   - Confirms conventions with you
-   - Generates:
-     - tech-spec.md (comprehensive implementation guide)
-     - epics.md (OAuth Integration epic)
-     - story-oauth-1.md (Backend OAuth setup)
-     - story-oauth-2.md (Frontend login buttons)
-3. **Optional Sprint Planning:** Load SM agent, run `sprint-planning`
-4. **Implement Story 1:**
-   - Load DEV agent, run `dev-story` for story 1
-   - DEV implements backend OAuth
-5. **Implement Story 2:**
-   - DEV agent, run `dev-story` for story 2
-   - DEV implements frontend
-   - Done!
-**Total time:** 1-3 hours (mostly implementation)
----
-## Integration with Phase 4 Workflows
-Quick Spec Flow works seamlessly with all Phase 4 implementation workflows:
-### story-context (SM Agent)
-- ✅ Recognizes tech-spec.md as authoritative source
-- ✅ Extracts context from tech-spec (replaces PRD)
-- ✅ Generates XML context for complex scenarios
-### create-story (SM Agent)
-- ✅ Can work with tech-spec.md instead of PRD
-- ✅ Uses epics.md from tech-spec workflow
-- ✅ Creates additional stories if needed
-### sprint-planning (SM Agent)
-- ✅ Works with epics.md from tech-spec
-- ✅ Organizes multi-story features for coordinated implementation
-- ✅ Tracks progress through sprint-status.yaml
-### dev-story (DEV Agent)
-- ✅ Reads stories generated by tech-spec
-- ✅ Uses tech-spec.md as comprehensive context
-- ✅ Implements following detected conventions
----
-## Comparison: Quick Spec vs Full BMM
-| Aspect                | Quick Flow Track             | BMad Method/Enterprise Tracks      |
-| --------------------- | ---------------------------- | ---------------------------------- |
-| **Setup**             | None (standalone)            | workflow-init recommended          |
-| **Planning Docs**     | tech-spec.md only            | Product Brief → PRD → Architecture |
-| **Time to Code**      | Minutes                      | Hours to days                      |
-| **Best For**          | Bug fixes, small features    | New products, major features       |
-| **Context Discovery** | Automatic                    | Manual + guided                    |
-| **Story Context**     | Optional (tech-spec is rich) | Required (generated from PRD)      |
-| **Validation**        | Auto-validates everything    | Manual validation steps            |
-| **Brownfield**        | Auto-analyzes and conforms   | Manual documentation required      |
-| **Conventions**       | Auto-detects and confirms    | Document in PRD/Architecture       |
----
-## When to Graduate from Quick Flow to BMad Method
-Start with Quick Flow, but switch to BMad Method when:
-- ❌ Project grows beyond initial scope
-- ❌ Multiple teams need coordination
-- ❌ Stakeholders need formal documentation
-- ❌ Product vision is unclear
-- ❌ Architectural decisions need deep analysis
-- ❌ Compliance/regulatory requirements exist
-💡 **Tip:** You can always run `workflow-init` later to transition from Quick Flow to BMad Method!
----
-## Quick Spec Flow - Key Benefits
-### 🚀 **Speed**
-- No Product Brief
-- No PRD
-- No Architecture doc
-- Straight to implementation
-### 🧠 **Intelligence**
-- Auto-detects stack
-- Auto-analyzes brownfield
-- Auto-validates quality
-- WebSearch for current info
-### 📐 **Respect for Existing Code**
-- Detects conventions
-- Asks for confirmation
-- Follows patterns
-- Adapts vs. changes
-### ✅ **Quality**
-- Auto-validation
-- Definitive decisions (no "or" statements)
-- Comprehensive context
-- Clear acceptance criteria
-### 🎯 **Focus**
-- Single atomic changes
-- Coherent small features
-- No scope creep
-- Fast iteration
----
-## Getting Started
-### Prerequisites
-- BMad Method installed (`npx bmad-method install`)
-- Project directory with code (or empty for greenfield)
-### Quick Start Commands
-```bash
-# For a quick bug fix or small change:
-# 1. Load PM agent
-# 2. Say: "I want to [describe your change]"
-# 3. PM will ask if you want to run tech-spec
-# 4. Answer questions about your change
-# 5. Get tech-spec + story
-# 6. Load DEV agent and implement!
-# For a small feature with multiple stories:
-# Same as above, but get epic + 2-3 stories
-# Optionally use SM sprint-planning to organize
-```
-### No workflow-init Required!
-Quick Spec Flow is **fully standalone**:
-- Detects if it's a single change or multi-story feature
-- Asks for greenfield vs brownfield
-- Works without status file tracking
-- Perfect for rapid prototyping
----
-## FAQ
-### Q: Can I use Quick Spec Flow on an existing project?
-**A:** Yes! It's perfect for brownfield projects. It will analyze your existing code, detect patterns, and ask if you want to follow them.
-### Q: What if I don't have a package.json or requirements.txt?
-**A:** Quick Spec Flow will work in greenfield mode, recommend starter templates, and use WebSearch for modern best practices.
-### Q: Do I need to run workflow-init first?
-**A:** No! Quick Spec Flow is standalone. But if you want guidance on which flow to use, workflow-init can help.
-### Q: Can I use this for frontend changes?
-**A:** Absolutely! Quick Spec Flow captures UX/UI considerations, component changes, and accessibility requirements.
-### Q: What if my Quick Flow project grows?
-**A:** No problem! You can always transition to BMad Method by running workflow-init and create-prd. Your tech-spec becomes input for the PRD.
-### Q: Do I need story-context for every story?
-**A:** Usually no! Tech-spec is comprehensive enough for most Quick Flow projects. Only use story-context for complex edge cases.
-### Q: Can I skip validation?
-**A:** No, validation always runs automatically. But it's fast and catches issues early!
-### Q: Will it work with my team's code style?
-**A:** Yes! It detects your conventions and asks for confirmation. You control whether to follow existing patterns or establish new ones.
----
-## Tips and Best Practices
-### 1. **Be Specific in Discovery**
-When describing your change, provide specifics:
-- ✅ "Fix email validation in UserService to allow plus-addressing"
-- ❌ "Fix validation bug"
-### 2. **Trust the Convention Detection**
-If it detects your patterns correctly, say yes! It's faster than establishing new conventions.
-### 3. **Use WebSearch Recommendations for Greenfield**
-Starter templates save hours of setup time. Let Quick Spec Flow find the best ones.
-### 4. **Review the Auto-Validation**
-When validation runs, read the scores. They tell you if your spec is production-ready.
-### 5. **Story Context is Optional**
-For single changes, try going directly to dev-story first. Only add story-context if you hit complexity.
-### 6. **Keep Single Changes Truly Atomic**
-If your "single change" needs 3+ files, it might be a multi-story feature. Let the workflow guide you.
-### 7. **Validate Story Sequence for Multi-Story Features**
-When you get multiple stories, check the dependency validation output. Proper sequence matters!
----
-## Real-World Examples
-### Example 1: Adding Logging (Single Change)
-**Input:** "Add structured logging to payment processing"
-**Tech-Spec Output:**
-- Detected: winston 3.8.2 already in package.json
-- Analyzed: Existing services use winston with JSON format
-- Confirmed: Follow existing logging patterns
-- Generated: Specific file paths, log levels, format example
-- Story: Ready to implement in 1-2 hours
-**Result:** Consistent logging added, following team patterns, no research needed.
----
-### Example 2: Search Feature (Multi-Story)
-**Input:** "Add search to product catalog with filters"
-**Tech-Spec Output:**
-- Detected: React 18.2.0, MUI component library, Express backend
-- Analyzed: Existing ProductList component patterns
-- Confirmed: Follow existing API and component structure
-- Generated:
-  - Epic: Product Search Functionality
-  - Story 1: Backend search API with filters
-  - Story 2: Frontend search UI component
-- Auto-validated: Story 1 → Story 2 sequence correct
-**Result:** Search feature implemented in 4-6 hours with proper architecture.
----
-## Summary
-Quick Spec Flow is your **fast path from idea to implementation** for:
-- 🐛 Bug fixes
-- ✨ Small features
-- 🚀 Rapid prototyping
-- 🔧 Quick enhancements
-**Key Features:**
-- Auto-detects your stack
-- Auto-analyzes brownfield code
-- Auto-validates quality
-- Respects existing conventions
-- Uses WebSearch for modern practices
-- Generates comprehensive tech-specs
-- Creates implementation-ready stories
-**Time to code:** Minutes, not hours.
-**Ready to try it?** Load the PM agent and say what you want to build! 🚀
----
-## Next Steps
-- **Try it now:** Load PM agent and describe a small change
-- **Learn more:** See the [BMM Workflow Guides](./README.md#-workflow-guides) for comprehensive workflow documentation
-- **Need help deciding?** Run `workflow-init` to get a recommendation
-- **Have questions?** Join us on Discord: https://discord.gg/gk8jAdXWmj
----
-_Quick Spec Flow - Because not every change needs a Product Brief._