bmad-fh 6.0.0-alpha.23

package/docs/how-to/workflows/create-story.md

@@ -0,0 +1,102 @@
+---
+title: "How to Create a Story"
+description: How to create implementation-ready stories from epic backlog
+---
+
+Use the `create-story` workflow to prepare the next story from the epic backlog for implementation.
+
+## When to Use This
+
+- Before implementing each story
+- When moving to the next story in an epic
+- After sprint-planning has been run
+
+:::note[Prerequisites]
+- BMad Method installed
+- SM (Scrum Master) agent available
+- Sprint-status.yaml created by sprint-planning
+- Architecture and PRD available for context
+:::
+
+## Steps
+
+### 1. Load the SM Agent
+
+Start a fresh chat and load the SM (Scrum Master) agent.
+
+### 2. Run the Workflow
+
+```
+*create-story
+```
+
+### 3. Specify the Story
+
+The agent will:
+- Read the sprint-status.yaml
+- Identify the next story to work on
+- Or let you specify a particular story
+
+### 4. Review the Story File
+
+The agent creates a comprehensive story file ready for development.
+
+## What You Get
+
+A `story-[slug].md` file containing:
+
+- Story objective and scope
+- Acceptance criteria (specific, testable)
+- Technical implementation notes
+- References to architecture decisions
+- Dependencies on other stories
+- Definition of Done
+
+## Story Content Sources
+
+The create-story workflow pulls from:
+
+- **PRD** — Requirements and acceptance criteria
+- **Architecture** — Technical approach and ADRs
+- **Epic file** — Story context and dependencies
+- **Existing code** — Patterns to follow (brownfield)
+
+## Example Output
+
+```markdown
+## Objective
+Implement email verification flow for new user registrations.
+
+## Acceptance Criteria
+- [ ] User receives verification email within 30 seconds
+- [ ] Email contains unique verification link
+- [ ] Link expires after 24 hours
+- [ ] User can request new verification email
+
+## Technical Notes
+- Use SendGrid API per ADR-003
+- Store verification tokens in Redis per architecture
+- Follow existing email template patterns in /templates
+
+## Dependencies
+- Story 1.1 (User Registration) - DONE
+
+## Definition of Done
+- All acceptance criteria pass
+- Tests written and passing
+- Code review approved
+```
+
+## Tips
+
+- **Complete one story before creating the next** — Focus on finishing
+- **Ensure dependencies are DONE** — Don't start blocked stories
+- **Review technical notes** — Align with architecture
+- **Use the story file as context** — Pass to dev-story workflow
+
+## Next Steps
+
+After creating a story:
+
+1. **Implement Story** — Run dev-story with the DEV agent
+2. **Code Review** — Run code-review after implementation

package/docs/how-to/workflows/create-ux-design.md

@@ -0,0 +1,100 @@
+---
+title: "How to Create a UX Design"
+description: How to create UX specifications using the BMad Method
+---
+
+Use the `create-ux-design` workflow to create UX specifications for projects where user experience is a primary differentiator.
+
+## When to Use This
+
+- UX is primary competitive advantage
+- Complex user workflows needing design thinking
+- Innovative interaction patterns
+- Design system creation
+- Accessibility-critical experiences
+
+## When to Skip This
+
+- Simple CRUD interfaces
+- Internal tools with standard patterns
+- Changes to existing screens you're happy with
+- Quick Flow projects
+
+:::note[Prerequisites]
+- BMad Method installed
+- UX Designer agent available
+- PRD completed
+:::
+
+## Steps
+
+### 1. Load the UX Designer Agent
+
+Start a fresh chat and load the UX Designer agent.
+
+### 2. Run the UX Design Workflow
+
+```
+*create-ux-design
+```
+
+### 3. Provide Context
+
+Point the agent to your PRD and describe:
+- Key user journeys
+- UX priorities
+- Any existing design patterns
+
+### 4. Collaborate on Design
+
+The workflow uses a collaborative approach:
+
+1. **Visual exploration** — Generate multiple options
+2. **Informed decisions** — Evaluate with user needs
+3. **Collaborative design** — Refine iteratively
+4. **Living documentation** — Evolves with project
+
+### 5. Review the UX Spec
+
+The agent produces comprehensive UX documentation.
+
+## What You Get
+
+The `ux-spec.md` document includes:
+
+- User journeys
+- Wireframes and mockups
+- Interaction specifications
+- Design system (components, patterns, tokens)
+- Epic breakdown (UX stories)
+
+## Example
+
+Dashboard redesign produces:
+- Card-based layout with split-pane toggle
+- 5 card components
+- 12 color tokens
+- Responsive grid
+- 3 epics (Layout, Visualization, Accessibility)
+
+## Integration
+
+The UX spec feeds into:
+- PRD updates
+- Epic and story creation
+- Architecture decisions (Phase 3)
+
+## Tips
+
+- **Focus on user problems first** — Solutions come second
+- **Generate multiple options** — Don't settle on the first idea
+- **Consider accessibility from the start** — Not an afterthought
+- **Document component reusability** — Build a system, not just screens
+
+## Next Steps
+
+After UX design:
+
+1. **Update PRD** — Incorporate UX findings
+2. **Create Architecture** — Technical design informed by UX
+3. **Create Epics and Stories** — Include UX-specific stories

package/docs/how-to/workflows/implement-story.md

@@ -0,0 +1,97 @@
+---
+title: "How to Implement a Story"
+description: How to implement a story using the dev-story workflow
+---
+
+Use the `dev-story` workflow to implement a story with tests following the architecture and conventions.
+
+## When to Use This
+
+- After create-story has prepared the story file
+- When ready to write code for a story
+- Story dependencies are marked DONE
+
+:::note[Prerequisites]
+- BMad Method installed
+- DEV agent available
+- Story file created by create-story
+- Architecture and tech-spec available for context
+:::
+
+## Steps
+
+### 1. Load the DEV Agent
+
+Start a fresh chat and load the DEV agent.
+
+### 2. Run the Workflow
+
+```
+*dev-story
+```
+
+### 3. Provide Story Context
+
+Point the agent to the story file created by create-story.
+
+### 4. Implement with Guidance
+
+The DEV agent:
+- Reads the story file and acceptance criteria
+- References architecture decisions
+- Follows existing code patterns
+- Implements with tests
+
+### 5. Complete Implementation
+
+Work with the agent until all acceptance criteria are met.
+
+## What Happens
+
+The dev-story workflow:
+
+1. **Reads context** — Story file, architecture, existing patterns
+2. **Plans implementation** — Identifies files to create/modify
+3. **Writes code** — Following conventions and patterns
+4. **Writes tests** — Unit, integration, or E2E as appropriate
+5. **Validates** — Runs tests and checks acceptance criteria
+
+## Key Principles
+
+**One Story at a Time** — Complete each story's full lifecycle before starting the next. This prevents context switching and ensures quality.
+
+**Follow Architecture** — The DEV agent references ADRs for technology decisions, standards for naming and structure, and existing patterns in the codebase.
+
+**Write Tests** — Every story includes appropriate tests: unit tests for business logic, integration tests for API endpoints, E2E tests for critical flows.
+
+## After Implementation
+
+1. **Update sprint-status.yaml** — Mark story as READY FOR REVIEW
+2. **Run code-review** — Quality assurance
+3. **Address feedback** — If code review finds issues
+4. **Mark DONE** — After code review passes
+
+## Tips
+
+- **Keep the story file open** — Reference it during implementation
+- **Ask the agent to explain decisions** — Understand the approach
+- **Run tests frequently** — Catch issues early
+- **Don't skip tests** — Even for "simple" changes
+
+## Troubleshooting
+
+**Story needs significant changes mid-implementation?**
+Run `correct-course` to analyze impact and route appropriately.
+
+**Can I work on multiple stories in parallel?**
+Not recommended. Complete one story's full lifecycle first.
+
+**What if implementation reveals the story is too large?**
+Split the story and document the change.
+
+## Next Steps
+
+After implementing a story:
+
+1. **Code Review** — Run code-review with the DEV agent
+2. **Create Next Story** — Run create-story with the SM agent

package/docs/how-to/workflows/quick-spec.md

@@ -0,0 +1,122 @@
+---
+title: "How to Use Quick Spec"
+description: How to create a technical specification using Quick Spec workflow
+---
+
+Use the `quick-spec` workflow for Quick Flow projects to go directly from idea to implementation-ready specification.
+
+## When to Use This
+
+- Bug fixes and small enhancements
+- Small features with clear scope (1-15 stories)
+- Rapid prototyping
+- Adding to existing brownfield codebase
+- Quick Flow track projects
+
+:::note[Prerequisites]
+- BMad Method installed
+- PM agent or Quick Flow Solo Dev agent available
+- Project directory (can be empty for greenfield)
+:::
+
+## Steps
+
+### 1. Load the PM Agent
+
+Start a fresh chat and load the PM agent (or Quick Flow Solo Dev agent).
+
+### 2. Run the Tech Spec Workflow
+
+```
+*quick-spec
+```
+
+Or simply describe what you want to build:
+
+```
+I want to fix the login validation bug
+```
+
+### 3. Answer Discovery Questions
+
+The workflow will ask:
+- What problem are you solving?
+- What's the scope of the change?
+- Any specific constraints?
+
+### 4. Review Detected Context
+
+For brownfield projects, the agent will:
+- Detect your project stack
+- Analyze existing code patterns
+- Detect test frameworks
+- Ask: "Should I follow these existing conventions?"
+
+### 5. Get Your Tech Spec
+
+The agent generates a comprehensive tech-spec with ready-to-implement stories.
+
+## What You Get
+
+**tech-spec.md:**
+- 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
+
+**Story Files:**
+- Single changes: `story-[slug].md`
+- Small features: `epics.md` + `story-[epic-slug]-1.md`, etc.
+
+## Example: Bug Fix
+
+**You:** "I want to fix the login validation bug that allows empty passwords"
+
+**Agent:**
+1. Asks clarifying questions about the issue
+2. Detects your Node.js stack (Express 4.18.2, Jest for testing)
+3. Analyzes existing UserService code patterns
+4. Asks: "Should I follow your existing conventions?" → Yes
+5. Generates tech-spec.md with specific file paths
+6. Creates story-login-fix.md
+
+## Example: Small Feature
+
+**You:** "I want to add OAuth social login (Google, GitHub)"
+
+**Agent:**
+1. Asks about feature scope
+2. Detects your stack (Next.js 13.4, NextAuth.js already installed!)
+3. Analyzes existing auth patterns
+4. Confirms conventions
+5. 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)
+
+## Implementing After Tech Spec
+
+```bash
+# Single change:
+# Load DEV agent and run dev-story
+
+# Multi-story feature:
+# Optional: Load SM agent and run sprint-planning
+# Then: Load DEV agent and run dev-story for each story
+```
+
+## Tips
+
+- **Be specific in discovery** — "Fix email validation in UserService to allow plus-addressing" beats "Fix validation bug"
+- **Trust convention detection** — If it detects your patterns correctly, say yes! It's faster than establishing new conventions
+- **Keep single changes atomic** — If your "single change" needs 3+ files, it might be a multi-story feature. Let the workflow guide you
+
+## Next Steps
+
+After tech spec:
+
+1. **Implement Story** — Run dev-story with the DEV agent
+2. **Sprint Planning** — Optional for multi-story features