docs: Add comprehensive GitHub installation guide for TDD methodology
This commit is contained in:
vforvaick
parent
873ba8789c
commit
15298d0bb6
|
|
@ -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
|
||||
Loading…
Reference in New Issue