bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.4

package/bmad/bmm/workflows/document-project/workflows/full-scan.yaml

@@ -0,0 +1,31 @@
+# Full Project Scan Workflow Configuration
+name: "document-project-full-scan"
+description: "Complete project documentation workflow (initial scan or full rescan)"
+author: "BMad"
+
+# This is a sub-workflow called by document-project/workflow.yaml
+parent_workflow: "{project-root}/bmad/bmm/workflows/document-project/workflow.yaml"
+
+# Critical variables inherited from parent
+config_source: "{project-root}/bmad/bmb/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+date: system-generated
+
+# Data files
+documentation_requirements_csv: "{project-root}/bmad/bmm/workflows/document-project/documentation-requirements.csv"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmm/workflows/document-project/workflows"
+template: false # Action workflow
+instructions: "{installed_path}/full-scan-instructions.md"
+validation: "{project-root}/bmad/bmm/workflows/document-project/checklist.md"
+
+# Runtime inputs (passed from parent workflow)
+workflow_mode: "" # "initial_scan" or "full_rescan"
+scan_level: "" # "quick", "deep", or "exhaustive"
+resume_mode: false
+project_root_path: ""
+
+# Configuration
+autonomous: false # Requires user input at key decision points

package/bmad/bmm/workflows/techdoc/documentation-standards.md

@@ -0,0 +1,238 @@
+# Technical Documentation Standards for BMAD
+
+**For Agent: Paige (Documentation Guide)**
+**Purpose: Concise reference for documentation creation and review**
+
+---
+
+## CRITICAL RULE: CommonMark Strict Compliance
+
+ALL documentation MUST follow CommonMark specification exactly. No exceptions.
+
+### CommonMark Essentials
+
+**Headers:**
+
+- Use ATX-style ONLY: `#` `##` `###` (NOT Setext underlines)
+- Single space after `#`: `# Title` (NOT `#Title`)
+- No trailing `#`: `# Title` (NOT `# Title #`)
+- Hierarchical order: Don't skip levels (h1→h2→h3, not h1→h3)
+
+**Code Blocks:**
+
+- Use fenced blocks with language identifier:
+  ````markdown
+  ```javascript
+  const example = 'code';
+  ```
+  ````
+- NOT indented code blocks (ambiguous)
+
+**Lists:**
+
+- Consistent markers within list: all `-` or all `*` or all `+` (don't mix)
+- Proper indentation for nested items (2 or 4 spaces, stay consistent)
+- Blank line before/after list for clarity
+
+**Links:**
+
+- Inline: `[text](url)`
+- Reference: `[text][ref]` then `[ref]: url` at bottom
+- NO bare URLs without `<>` brackets
+
+**Emphasis:**
+
+- Italic: `*text*` or `_text_`
+- Bold: `**text**` or `__text__`
+- Consistent style within document
+
+**Line Breaks:**
+
+- Two spaces at end of line + newline, OR
+- Blank line between paragraphs
+- NO single line breaks (they're ignored)
+
+---
+
+## Mermaid Diagrams: Valid Syntax Required
+
+**Critical Rules:**
+
+1. Always specify diagram type first line
+2. Use valid Mermaid v10+ syntax
+3. Test syntax before outputting (mental validation)
+4. Keep focused: 5-10 nodes ideal, max 15
+
+**Diagram Type Selection:**
+
+- **flowchart** - Process flows, decision trees, workflows
+- **sequenceDiagram** - API interactions, message flows, time-based processes
+- **classDiagram** - Object models, class relationships, system structure
+- **erDiagram** - Database schemas, entity relationships
+- **stateDiagram-v2** - State machines, lifecycle stages
+- **gitGraph** - Branch strategies, version control flows
+
+**Formatting:**
+
+````markdown
+```mermaid
+flowchart TD
+    Start[Clear Label] --> Decision{Question?}
+    Decision -->|Yes| Action1[Do This]
+    Decision -->|No| Action2[Do That]
+```
+````
+
+---
+
+## Style Guide Principles (Distilled)
+
+Apply in this hierarchy:
+
+1. **Project-specific guide** (if exists) - always ask first
+2. **BMAD conventions** (this document)
+3. **Google Developer Docs style** (defaults below)
+4. **CommonMark spec** (when in doubt)
+
+### Core Writing Rules
+
+**Task-Oriented Focus:**
+
+- Write for user GOALS, not feature lists
+- Start with WHY, then HOW
+- Every doc answers: "What can I accomplish?"
+
+**Clarity Principles:**
+
+- Active voice: "Click the button" NOT "The button should be clicked"
+- Present tense: "The function returns" NOT "The function will return"
+- Direct language: "Use X for Y" NOT "X can be used for Y"
+- Second person: "You configure" NOT "Users configure" or "One configures"
+
+**Structure:**
+
+- One idea per sentence
+- One topic per paragraph
+- Headings describe content accurately
+- Examples follow explanations
+
+**Accessibility:**
+
+- Descriptive link text: "See the API reference" NOT "Click here"
+- Alt text for diagrams: Describe what it shows
+- Semantic heading hierarchy (don't skip levels)
+- Tables have headers
+
+---
+
+## OpenAPI/API Documentation
+
+**Required Elements:**
+
+- Endpoint path and method
+- Authentication requirements
+- Request parameters (path, query, body) with types
+- Request example (realistic, working)
+- Response schema with types
+- Response examples (success + common errors)
+- Error codes and meanings
+
+**Quality Standards:**
+
+- OpenAPI 3.0+ specification compliance
+- Complete schemas (no missing fields)
+- Examples that actually work
+- Clear error messages
+- Security schemes documented
+
+---
+
+## Documentation Types: Quick Reference
+
+**README:**
+
+- What (overview), Why (purpose), How (quick start)
+- Installation, Usage, Contributing, License
+- Under 500 lines (link to detailed docs)
+
+**API Reference:**
+
+- Complete endpoint coverage
+- Request/response examples
+- Authentication details
+- Error handling
+- Rate limits if applicable
+
+**User Guide:**
+
+- Task-based sections (How to...)
+- Step-by-step instructions
+- Screenshots/diagrams where helpful
+- Troubleshooting section
+
+**Architecture Docs:**
+
+- System overview diagram (Mermaid)
+- Component descriptions
+- Data flow
+- Technology decisions (ADRs)
+- Deployment architecture
+
+**Developer Guide:**
+
+- Setup/environment requirements
+- Code organization
+- Development workflow
+- Testing approach
+- Contribution guidelines
+
+---
+
+## Quality Checklist
+
+Before finalizing ANY documentation:
+
+- [ ] CommonMark compliant (no violations)
+- [ ] Headers in proper hierarchy
+- [ ] All code blocks have language tags
+- [ ] Links work and have descriptive text
+- [ ] Mermaid diagrams render correctly
+- [ ] Active voice, present tense
+- [ ] Task-oriented (answers "how do I...")
+- [ ] Examples are concrete and working
+- [ ] Accessibility standards met
+- [ ] Spelling/grammar checked
+- [ ] Reads clearly at target skill level
+
+---
+
+## BMAD-Specific Conventions
+
+**File Organization:**
+
+- `README.md` at root of each major component
+- `docs/` folder for extensive documentation
+- Workflow-specific docs in workflow folder
+- Cross-references use relative paths
+
+**Frontmatter:**
+Use YAML frontmatter when appropriate:
+
+```yaml
+---
+title: Document Title
+description: Brief description
+author: Author name
+date: YYYY-MM-DD
+---
+```
+
+**Metadata:**
+
+- Always include last-updated date
+- Version info for versioned docs
+- Author attribution for accountability
+
+---
+
+**Remember: This is your foundation. Follow these rules consistently, and all documentation will be clear, accessible, and maintainable.**

package/bmad/bmm/workflows/testarch/atdd/atdd-checklist-template.md

@@ -0,0 +1,363 @@
+# ATDD Checklist - Epic {epic_num}, Story {story_num}: {story_title}
+
+**Date:** {date}
+**Author:** {user_name}
+**Primary Test Level:** {primary_level}
+
+---
+
+## Story Summary
+
+{Brief 2-3 sentence summary of the user story}
+
+**As a** {user_role}
+**I want** {feature_description}
+**So that** {business_value}
+
+---
+
+## Acceptance Criteria
+
+{List all testable acceptance criteria from the story}
+
+1. {Acceptance criterion 1}
+2. {Acceptance criterion 2}
+3. {Acceptance criterion 3}
+
+---
+
+## Failing Tests Created (RED Phase)
+
+### E2E Tests ({e2e_test_count} tests)
+
+**File:** `{e2e_test_file_path}` ({line_count} lines)
+
+{List each E2E test with its current status and expected failure reason}
+
+- ✅ **Test:** {test_name}
+  - **Status:** RED - {failure_reason}
+  - **Verifies:** {what_this_test_validates}
+
+### API Tests ({api_test_count} tests)
+
+**File:** `{api_test_file_path}` ({line_count} lines)
+
+{List each API test with its current status and expected failure reason}
+
+- ✅ **Test:** {test_name}
+  - **Status:** RED - {failure_reason}
+  - **Verifies:** {what_this_test_validates}
+
+### Component Tests ({component_test_count} tests)
+
+**File:** `{component_test_file_path}` ({line_count} lines)
+
+{List each component test with its current status and expected failure reason}
+
+- ✅ **Test:** {test_name}
+  - **Status:** RED - {failure_reason}
+  - **Verifies:** {what_this_test_validates}
+
+---
+
+## Data Factories Created
+
+{List all data factory files created with their exports}
+
+### {Entity} Factory
+
+**File:** `tests/support/factories/{entity}.factory.ts`
+
+**Exports:**
+
+- `create{Entity}(overrides?)` - Create single entity with optional overrides
+- `create{Entity}s(count)` - Create array of entities
+
+**Example Usage:**
+
+```typescript
+const user = createUser({ email: 'specific@example.com' });
+const users = createUsers(5); // Generate 5 random users
+```
+
+---
+
+## Fixtures Created
+
+{List all test fixture files created with their fixture names and descriptions}
+
+### {Feature} Fixtures
+
+**File:** `tests/support/fixtures/{feature}.fixture.ts`
+
+**Fixtures:**
+
+- `{fixtureName}` - {description_of_what_fixture_provides}
+  - **Setup:** {what_setup_does}
+  - **Provides:** {what_test_receives}
+  - **Cleanup:** {what_cleanup_does}
+
+**Example Usage:**
+
+```typescript
+import { test } from './fixtures/{feature}.fixture';
+
+test('should do something', async ({ {fixtureName} }) => {
+  // {fixtureName} is ready to use with auto-cleanup
+});
+```
+
+---
+
+## Mock Requirements
+
+{Document external services that need mocking and their requirements}
+
+### {Service Name} Mock
+
+**Endpoint:** `{HTTP_METHOD} {endpoint_url}`
+
+**Success Response:**
+
+```json
+{
+  {success_response_example}
+}
+```
+
+**Failure Response:**
+
+```json
+{
+  {failure_response_example}
+}
+```
+
+**Notes:** {any_special_mock_requirements}
+
+---
+
+## Required data-testid Attributes
+
+{List all data-testid attributes required in UI implementation for test stability}
+
+### {Page or Component Name}
+
+- `{data-testid-name}` - {description_of_element}
+- `{data-testid-name}` - {description_of_element}
+
+**Implementation Example:**
+
+```tsx
+<button data-testid="login-button">Log In</button>
+<input data-testid="email-input" type="email" />
+<div data-testid="error-message">{errorText}</div>
+```
+
+---
+
+## Implementation Checklist
+
+{Map each failing test to concrete implementation tasks that will make it pass}
+
+### Test: {test_name_1}
+
+**File:** `{test_file_path}`
+
+**Tasks to make this test pass:**
+
+- [ ] {Implementation task 1}
+- [ ] {Implementation task 2}
+- [ ] {Implementation task 3}
+- [ ] Add required data-testid attributes: {list_of_testids}
+- [ ] Run test: `{test_execution_command}`
+- [ ] ✅ Test passes (green phase)
+
+**Estimated Effort:** {effort_estimate} hours
+
+---
+
+### Test: {test_name_2}
+
+**File:** `{test_file_path}`
+
+**Tasks to make this test pass:**
+
+- [ ] {Implementation task 1}
+- [ ] {Implementation task 2}
+- [ ] {Implementation task 3}
+- [ ] Add required data-testid attributes: {list_of_testids}
+- [ ] Run test: `{test_execution_command}`
+- [ ] ✅ Test passes (green phase)
+
+**Estimated Effort:** {effort_estimate} hours
+
+---
+
+## Running Tests
+
+```bash
+# Run all failing tests for this story
+{test_command_all}
+
+# Run specific test file
+{test_command_specific_file}
+
+# Run tests in headed mode (see browser)
+{test_command_headed}
+
+# Debug specific test
+{test_command_debug}
+
+# Run tests with coverage
+{test_command_coverage}
+```
+
+---
+
+## Red-Green-Refactor Workflow
+
+### RED Phase (Complete) ✅
+
+**TEA Agent Responsibilities:**
+
+- ✅ All tests written and failing
+- ✅ Fixtures and factories created with auto-cleanup
+- ✅ Mock requirements documented
+- ✅ data-testid requirements listed
+- ✅ Implementation checklist created
+
+**Verification:**
+
+- All tests run and fail as expected
+- Failure messages are clear and actionable
+- Tests fail due to missing implementation, not test bugs
+
+---
+
+### GREEN Phase (DEV Team - Next Steps)
+
+**DEV Agent Responsibilities:**
+
+1. **Pick one failing test** from implementation checklist (start with highest priority)
+2. **Read the test** to understand expected behavior
+3. **Implement minimal code** to make that specific test pass
+4. **Run the test** to verify it now passes (green)
+5. **Check off the task** in implementation checklist
+6. **Move to next test** and repeat
+
+**Key Principles:**
+
+- One test at a time (don't try to fix all at once)
+- Minimal implementation (don't over-engineer)
+- Run tests frequently (immediate feedback)
+- Use implementation checklist as roadmap
+
+**Progress Tracking:**
+
+- Check off tasks as you complete them
+- Share progress in daily standup
+- Mark story as IN PROGRESS in `bmm-workflow-status.md`
+
+---
+
+### REFACTOR Phase (DEV Team - After All Tests Pass)
+
+**DEV Agent Responsibilities:**
+
+1. **Verify all tests pass** (green phase complete)
+2. **Review code for quality** (readability, maintainability, performance)
+3. **Extract duplications** (DRY principle)
+4. **Optimize performance** (if needed)
+5. **Ensure tests still pass** after each refactor
+6. **Update documentation** (if API contracts change)
+
+**Key Principles:**
+
+- Tests provide safety net (refactor with confidence)
+- Make small refactors (easier to debug if tests fail)
+- Run tests after each change
+- Don't change test behavior (only implementation)
+
+**Completion:**
+
+- All tests pass
+- Code quality meets team standards
+- No duplications or code smells
+- Ready for code review and story approval
+
+---
+
+## Next Steps
+
+1. **Review this checklist** with team in standup or planning
+2. **Run failing tests** to confirm RED phase: `{test_command_all}`
+3. **Begin implementation** using implementation checklist as guide
+4. **Work one test at a time** (red → green for each)
+5. **Share progress** in daily standup
+6. **When all tests pass**, refactor code for quality
+7. **When refactoring complete**, run `bmad sm story-done` to move story to DONE
+
+---
+
+## Knowledge Base References Applied
+
+This ATDD workflow consulted the following knowledge fragments:
+
+- **fixture-architecture.md** - Test fixture patterns with setup/teardown and auto-cleanup using Playwright's `test.extend()`
+- **data-factories.md** - Factory patterns using `@faker-js/faker` for random test data generation with overrides support
+- **component-tdd.md** - Component test strategies using Playwright Component Testing
+- **network-first.md** - Route interception patterns (intercept BEFORE navigation to prevent race conditions)
+- **test-quality.md** - Test design principles (Given-When-Then, one assertion per test, determinism, isolation)
+- **test-levels-framework.md** - Test level selection framework (E2E vs API vs Component vs Unit)
+
+See `tea-index.csv` for complete knowledge fragment mapping.
+
+---
+
+## Test Execution Evidence
+
+### Initial Test Run (RED Phase Verification)
+
+**Command:** `{test_command_all}`
+
+**Results:**
+
+```
+{paste_test_run_output_showing_all_tests_failing}
+```
+
+**Summary:**
+
+- Total tests: {total_test_count}
+- Passing: 0 (expected)
+- Failing: {total_test_count} (expected)
+- Status: ✅ RED phase verified
+
+**Expected Failure Messages:**
+{list_expected_failure_messages_for_each_test}
+
+---
+
+## Notes
+
+{Any additional notes, context, or special considerations for this story}
+
+- {Note 1}
+- {Note 2}
+- {Note 3}
+
+---
+
+## Contact
+
+**Questions or Issues?**
+
+- Ask in team standup
+- Tag @{tea_agent_username} in Slack/Discord
+- Refer to `testarch/README.md` for workflow documentation
+- Consult `testarch/knowledge/` for testing best practices
+
+---
+
+**Generated by BMad TEA Agent** - {date}