From 15298d0bb6a81663ab3de4139f792a9f26d0f3d2 Mon Sep 17 00:00:00 2001 From: vforvaick Date: Tue, 2 Sep 2025 15:31:16 +0700 Subject: [PATCH] docs: Add comprehensive GitHub installation guide for TDD methodology --- INSTALL_WITH_TDD_FROM_GITHUB.md | 305 ++++++++++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 INSTALL_WITH_TDD_FROM_GITHUB.md diff --git a/INSTALL_WITH_TDD_FROM_GITHUB.md b/INSTALL_WITH_TDD_FROM_GITHUB.md new file mode 100644 index 00000000..24c4f415 --- /dev/null +++ b/INSTALL_WITH_TDD_FROM_GITHUB.md @@ -0,0 +1,305 @@ +# Install BMAD with TDD Methodology from GitHub + +This guide provides complete installation steps for BMAD-METHOD with the TDD methodology expansion pack directly from the GitHub fork. + +## Prerequisites + +- **Node.js:** v20+ required +- **Git:** For cloning repositories +- **NPM:** For package management +- **IDE:** Cursor, Windsurf, or compatible IDE (optional) + +## Installation Methods + +### Method 1: Direct Installation from GitHub Fork (Recommended) + +This method installs your complete BMAD fork that includes the TDD methodology expansion pack. + +```bash +# 1. Create new project directory +mkdir my-tdd-project && cd my-tdd-project + +# 2. Clone the BMAD fork with TDD expansion +git clone https://github.com/vforvaick/BMAD-METHOD.git +cd BMAD-METHOD + +# 3. Switch to the TDD methodology branch +git checkout expansion/tdd-methodology + +# 4. Install dependencies +npm install + +# 5. Build the framework (includes TDD expansion pack) +npm run build + +# 6. Go back to project root and install BMAD from local clone +cd .. +node BMAD-METHOD/tools/installer/bin/bmad.js install --full + +# 7. Install TDD expansion pack +cp -r BMAD-METHOD/expansion-packs/bmad-tdd-methodology .bmad-tdd-methodology + +# 8. Set up development environment +npm init -y +npm install --save-dev jest + +# 9. Create project structure +mkdir -p src tests stories + +# 10. Update package.json test script +sed -i '' 's/"test": "echo \\"Error: no test specified\\" && exit 1"/"test": "jest"/g' package.json +``` + +### Method 2: NPX Installation with GitHub TDD Expansion + +This method uses official BMAD core with TDD expansion from GitHub. + +```bash +# 1. Create project directory +mkdir my-tdd-project && cd my-tdd-project + +# 2. Install BMAD core (official) +npx bmad-method install --full + +# 3. Clone TDD expansion from GitHub +git clone https://github.com/vforvaick/BMAD-METHOD.git temp-bmad +cd temp-bmad && git checkout expansion/tdd-methodology && cd .. + +# 4. Copy TDD expansion pack +cp -r temp-bmad/expansion-packs/bmad-tdd-methodology .bmad-tdd-methodology + +# 5. Clean up temporary clone +rm -rf temp-bmad + +# 6. Set up development environment +npm init -y +npm install --save-dev jest +mkdir -p src tests stories + +# 7. Update package.json for Jest +sed -i '' 's/"test": "echo \\"Error: no test specified\\" && exit 1"/"test": "jest"/g' package.json +``` + +### Method 3: Local Development Installation + +For contributors working on the BMAD-METHOD itself. + +```bash +# 1. Clone your fork +git clone https://github.com/vforvaick/BMAD-METHOD.git +cd BMAD-METHOD +git checkout expansion/tdd-methodology + +# 2. Install development dependencies +npm install + +# 3. Build the framework +npm run build + +# 4. Create test project +cd .. +mkdir test-project && cd test-project + +# 5. Install from local repository +node ../BMAD-METHOD/tools/installer/bin/bmad.js install --full +cp -r ../BMAD-METHOD/expansion-packs/bmad-tdd-methodology .bmad-tdd-methodology + +# 6. Set up test environment +npm init -y +npm install --save-dev jest +mkdir -p src tests stories +``` + +## Post-Installation Setup + +### 1. IDE Configuration (Optional) + +If you installed with IDE support, your IDE should now have BMAD agent rules: + +**Cursor:** + +- Rules available in `.cursor/rules/bmad/` +- Use `@bmad Apply QA Agent (Quinn) persona` to activate TDD-enhanced QA agent + +**Windsurf:** + +- Workflows available in `.windsurf/workflows/` +- Access BMAD agents through workflow menu + +### 2. Verify Installation + +```bash +# Check BMAD core installation +ls -la .bmad-core + +# Check TDD expansion installation +ls -la .bmad-tdd-methodology + +# Verify TDD agents are available +cat .bmad-tdd-methodology/agents/qa.md | grep "tdd-start\|write-failing-tests" + +# Test your setup +npm test +``` + +### 3. Create Your First TDD Story + +```bash +# Copy TDD story template +cp .bmad-tdd-methodology/templates/story-tdd-template.md stories/1.1-my-first-story.md + +# Edit the story file with your requirements +# Use your IDE or text editor to customize the template +``` + +## Available TDD Commands + +Once installed, your enhanced QA agent supports these TDD-specific commands: + +- `*tdd-start {story}` - Initialize TDD process for a story +- `*write-failing-tests {story}` - Create failing tests (Red phase) +- `*tdd-refactor {story}` - Participate in refactor phase +- `*help` - Show all available commands + +## Project Structure After Installation + +``` +your-project/ +├── .bmad-core/ # Standard BMAD framework +├── .bmad-tdd-methodology/ # TDD expansion pack +│ ├── agents/ # Enhanced QA & Dev agents +│ │ ├── qa.md # TDD-enhanced QA agent +│ │ └── dev.md # TDD-enhanced Dev agent +│ ├── tasks/ # TDD-specific tasks +│ │ ├── write-failing-tests.md +│ │ └── tdd-refactor.md +│ ├── templates/ # TDD templates +│ │ └── story-tdd-template.md +│ └── config.yaml # Expansion configuration +├── .cursor/ # IDE rules (if configured) +├── .windsurf/ # IDE workflows (if configured) +├── src/ # Your source code +├── tests/ # Your test files +├── stories/ # User stories +└── package.json # Project configuration +``` + +## Quick Start Example + +Here's a complete example to get started quickly: + +````bash +# 1. Create and setup project +mkdir calculator-tdd && cd calculator-tdd + +# 2. Install BMAD + TDD from GitHub +git clone https://github.com/vforvaick/BMAD-METHOD.git temp-bmad +cd temp-bmad && git checkout expansion/tdd-methodology && cd .. + +# 3. Install BMAD core +npx bmad-method install --full + +# 4. Add TDD expansion +cp -r temp-bmad/expansion-packs/bmad-tdd-methodology .bmad-tdd-methodology +rm -rf temp-bmad + +# 5. Setup development environment +npm init -y +npm install --save-dev jest +mkdir -p src tests stories +sed -i '' 's/"test": "echo \\"Error: no test specified\\" && exit 1"/"test": "jest"/g' package.json + +# 6. Create sample TDD story +cat > stories/1.1-calculator-add.md << 'EOF' +# Story 1.1: Calculator Addition + +## Story Metadata +```yaml +story: + epic: '1' + number: '1.1' + title: 'Calculator Addition' + status: 'draft' + priority: 'high' +tdd: + status: 'red' + cycle: 1 + coverage_target: 95.0 + tests: [] +```` + +## Story Description + +**As a** calculator user +**I want** to add two numbers +**So that** I can perform arithmetic calculations + +## Acceptance Criteria + +```gherkin +Scenario: Add two positive numbers + Given I have numbers 5 and 3 + When I add them + Then I should get 8 +``` + +EOF + +# 7. Verify installation + +echo "✅ Installation complete! Your TDD-enabled BMAD project is ready." +echo "🚀 Next steps:" +echo " 1. Open your IDE in this directory" +echo " 2. Activate QA agent: @bmad Apply QA Agent (Quinn) persona" +echo " 3. Run: \*write-failing-tests 1.1" +echo " 4. Implement code to make tests pass" +echo " 5. Run: npm test" + +```` + +## Troubleshooting + +### Issue: TDD commands not available +**Solution:** Verify TDD expansion pack installation: +```bash +ls -la .bmad-tdd-methodology/agents/ +cat .bmad-tdd-methodology/agents/qa.md | grep "tdd-start" +```` + +### Issue: Tests not running + +**Solution:** Ensure Jest is configured: + +```bash +npm install --save-dev jest +# Check package.json has "test": "jest" +``` + +### Issue: IDE not showing BMAD agents + +**Solution:** Reinstall with IDE configuration: + +```bash +npx bmad-method install --full -i cursor windsurf +``` + +## Contributing + +If you want to contribute to the TDD methodology expansion: + +1. Fork the repository: https://github.com/vforvaick/BMAD-METHOD +2. Create a feature branch from `expansion/tdd-methodology` +3. Make your changes +4. Test with the installation methods above +5. Submit a pull request + +## Support + +- **GitHub Issues:** https://github.com/vforvaick/BMAD-METHOD/issues +- **Original BMAD:** https://github.com/bmad-code-org/BMAD-METHOD +- **Documentation:** Check `.bmad-core/user-guide.md` after installation + +--- + +**Installation Status:** Ready for use with complete TDD methodology support! +**Last Updated:** 2025-09-02