# HTML Chess Game - Implementation Swarm Prompt

## 🎯 Mission

Implementiere ein vollständiges HTML-Schachspiel basierend auf der umfassenden Planungsdokumentation im `/docs` Verzeichnis.

## 📋 Kontext

Ein Planungs-Swarm hat bereits eine komplette, produktionsreife Spezifikation erstellt mit:
- ✅ Vollständiger Architektur (MVC + Event-System)
- ✅ 120+ Test Cases spezifiziert
- ✅ Code-Templates und Beispielen
- ✅ Schritt-für-Schritt-Implementierungsguide
- ✅ 100+ Code-Snippets und Patterns
- ✅ Kompletter API-Dokumentation

## 🚀 Deine Aufgabe

Implementiere das Schachspiel in **4-5 Wochen** (100-125 Stunden) mit folgenden Phasen:

### Phase 1: MVP Core (Wochen 1-2)
- Board-Rendering (DOM-basiert mit CSS Grid)
- Alle 6 Figuren-Typen mit korrekter Bewegungslogik
- Drag-and-Drop + Tap-to-Move (mobile-first)
- Zugvalidierung mit allen Schachregeln
- Check/Checkmate/Stalemate-Erkennung

### Phase 2: Enhanced UX (Wochen 3-4)
- CSS-Animationen für Züge
- Sound-Effekte
- Zughistorie mit Undo/Redo
- Save/Load via localStorage
- PGN/FEN Import/Export

### Phase 3: AI Opponent (Optional - Wochen 5-6)
- Minimax-Algorithmus mit Alpha-Beta-Pruning
- 5 Schwierigkeitsstufen
- Web Worker für Performance
- Optional: Stockfish.js Integration

## 📚 Dokumentation (SEHR WICHTIG - LIES DIESE ZUERST!)

### Start hier:
1. **`/docs/HANDOFF_CHECKLIST.md`** ⭐ - Komplette Roadmap und Quick Start
2. **`/docs/IMPLEMENTATION_GUIDE.md`** 📖 - Schritt-für-Schritt-Anleitung
3. **`/docs/API_REFERENCE.md`** 📚 - Alle Class/Method-Signaturen

### Während der Implementierung:
- **`/docs/CHESS_RULES.md`** ♟️ - Vollständige Schachregeln (Castling, En Passant, etc.)
- **`/docs/DEVELOPER_GUIDE.md`** 🛠️ - Testing, Debugging, Best Practices
- **`/docs/architecture/`** 🏗️ - System-Design, Komponenten, Datenmodelle
- **`/docs/implementation/code-templates/`** 💻 - Copy-paste fertige Templates
- **`/docs/implementation/examples/`** 📝 - Vollständige Implementierungsbeispiele
- **`/docs/testing/`** 🧪 - Test-Strategie und alle Test Cases
- **`/docs/diagrams/ARCHITECTURE.md`** 🎨 - 16 visuelle Diagramme

## 🎯 Erfolgs-Kriterien

Das Projekt ist erfolgreich, wenn:

✅ **Funktional:**
- Alle FIDE-Schachregeln korrekt implementiert
- Alle Spezialfälle funktionieren (Castling, En Passant, Promotion, Rochade)
- Check, Checkmate, Stalemate korrekt erkannt
- Zwei-Spieler-Modus funktioniert vollständig

✅ **Qualität:**
- 90%+ Test Coverage (Jest + Playwright)
- Alle 120+ Test Cases aus `/docs/testing/test-specifications.md` bestehen
- Keine Eslint/TypeScript-Fehler
- WCAG 2.1 Level AA Accessibility

✅ **Performance:**
- Ladezeit <2 Sekunden (Desktop)
- 60 FPS Rendering
- Bundle-Größe <150KB (gzipped)
- Mobile responsive (320px - 2560px)

✅ **Code-Qualität:**
- Folgt `/docs/implementation/coding-standards.md`
- JSDoc für alle öffentlichen Methoden
- Clean Code (SRP, DRY, KISS)
- Kommentare für komplexe Schachlogik

## 🏗️ Empfohlene Dateistruktur

```
chess-game/
├── index.html
├── css/
│   ├── board.css
│   ├── pieces.css
│   └── game-controls.css
├── js/
│   ├── models/
│   │   ├── Board.js
│   │   ├── Piece.js
│   │   ├── pieces/
│   │   │   ├── Pawn.js
│   │   │   ├── Knight.js
│   │   │   ├── Bishop.js
│   │   │   ├── Rook.js
│   │   │   ├── Queen.js
│   │   │   └── King.js
│   │   └── GameState.js
│   ├── controllers/
│   │   ├── GameController.js
│   │   └── MoveController.js
│   ├── views/
│   │   ├── BoardView.js
│   │   └── UIManager.js
│   ├── engine/
│   │   ├── MoveValidator.js
│   │   ├── RuleEngine.js
│   │   ├── CheckDetector.js
│   │   └── SpecialMoves.js
│   ├── ai/
│   │   ├── AIPlayer.js
│   │   ├── Minimax.js
│   │   └── Evaluator.js
│   └── utils/
│       ├── Constants.js
│       ├── Helpers.js
│       ├── EventBus.js
│       ├── FENParser.js
│       └── PGNParser.js
├── assets/
│   ├── pieces/ (SVG icons)
│   └── sounds/
└── tests/
    ├── unit/
    ├── integration/
    └── e2e/
```

## 🔧 Technologie-Stack (aus Planung empfohlen)

**Core:**
- Vanilla JavaScript ES6+ (KEIN Framework nötig)
- HTML5 + CSS3 (CSS Grid für Board)
- DOM-basiertes Rendering (NICHT Canvas)

**Optional Libraries:**
- chess.js (für Game Logic Validation)
- chessboard.js (für Board Rendering)
- Stockfish.js (für weltklasse AI)

**Build Tools:**
- Babel (ES6+ Transpilation)
- Webpack/Vite (Bundling)
- Jest (Unit/Integration Tests)
- Playwright (E2E Tests)

**Development:**
- ESLint + Prettier
- Husky (Pre-commit Hooks)
- Lighthouse CI (Performance)

## 📋 Implementierungsreihenfolge (wichtig!)

Folge exakt dieser Reihenfolge aus `/docs/IMPLEMENTATION_GUIDE.md`:

**Tag 1-2: Setup & Board**
1. Projekt-Setup (package.json, build tools)
2. Board-Klasse (8x8 Gitter, Koordinaten)
3. BoardView-Klasse (CSS Grid Rendering)

**Tag 3-5: Pieces**
4. Base Piece-Klasse
5. Alle 6 Piece-Typen (Pawn, Knight, Bishop, Rook, Queen, King)
6. Movement-Logik für jede Figur

**Tag 6-8: Move Validation**
7. MoveValidator (Legal moves)
8. RuleEngine (Schachregeln)
9. CheckDetector (King in check)

**Tag 9-12: Game Logic**
10. GameController (Spielfluss)
11. SpecialMoves (Castling, En Passant, Promotion)
12. Checkmate/Stalemate Detection

**Tag 13-15: UI**
13. Drag-and-Drop
14. Tap-to-Move (Mobile)
15. Visual Feedback (highlights, animations)

**Tag 16-20: Polish**
16. Game History + Undo/Redo
17. Save/Load + PGN/FEN
18. Sound Effects + Animations
19. Comprehensive Testing
20. Performance Optimization

**Tag 21-25 (Optional): AI**
21. Minimax Algorithm
22. Alpha-Beta Pruning
23. Position Evaluation
24. Difficulty Levels
25. Web Worker Integration

## ⚠️ Kritische Implementierungs-Hinweise

### Häufige Fallstricke (aus `/docs/IMPLEMENTATION_GUIDE.md`):

1. **En Passant:** Muss im selben Zug nach Pawn-Doppelschritt möglich sein
2. **Castling:** 5 Bedingungen müssen erfüllt sein (King/Rook unmoved, kein Check, freie Felder, etc.)
3. **Checkmate vs. Stalemate:** King in check + keine legalen Züge = Checkmate; King NICHT in check + keine legalen Züge = Stalemate
4. **Pawn Promotion:** Automatisch beim Erreichen der gegnerischen Grundreihe
5. **Zugvalidierung:** IMMER prüfen ob eigener King in Check nach Zug (illegal!)
6. **FEN Parsing:** Validierung und Error Handling essentiell

### Performance-Optimierungen:

- Bitboards für schnelle Position-Checks (optional)
- Move caching für AI
- RequestAnimationFrame für Animationen
- Lazy loading für Assets
- Virtual scrolling für lange Zughistorie

## 🧪 Testing-Anforderungen

Implementiere Tests für:

### Unit Tests (70% der Tests)
- Jede Piece-Bewegung einzeln
- MoveValidator Edge Cases
- FEN/PGN Parser
- Check Detection
- Special Moves

### Integration Tests (20%)
- Game Flow (Start → Züge → Checkmate)
- UI Interaktionen
- Save/Load Functionality

### E2E Tests (10%)
- Komplette Spiele
- Famous Games Replay (Immortal Game, Opera Game)
- Browser Compatibility

**Test Coverage Minimum:** 90% (siehe `/docs/testing/quality-criteria.md`)

## 🎨 UI/UX Requirements

- **Desktop:** Drag-and-Drop primär
- **Mobile:** Tap-to-Move primär (Tap Piece → Tap Destination)
- **Responsive:** 320px - 2560px
- **Accessibility:** Keyboard Navigation, Screen Reader Support, ARIA Labels
- **Visual Feedback:**
  - Highlight legal moves when piece selected
  - Animation for piece movement
  - Check indicator for King
  - Last move highlight

## 📊 Monitoring & Deployment

- Bundle size report
- Lighthouse performance score >90
- Deploy to GitHub Pages / Netlify / Vercel
- Cross-browser testing (Chrome, Firefox, Safari, Edge)

## 🚨 WICHTIG: Bevor du startest!

1. ✅ Lies ZUERST `/docs/HANDOFF_CHECKLIST.md` (30 Minuten)
2. ✅ Studiere `/docs/IMPLEMENTATION_GUIDE.md` Phase 1 (1 Stunde)
3. ✅ Reviewe Code-Templates in `/docs/implementation/code-templates/`
4. ✅ Verstehe Schachregeln aus `/docs/CHESS_RULES.md`
5. ✅ Setup Entwicklungsumgebung via `/docs/DEVELOPER_GUIDE.md`

**Total prep time:** ~2-3 Stunden
**Dann:** START CODING! 🚀

## 📞 Support & Fragen

**BEVOR du fragst, checke:**
1. Implementation steps? → `/docs/IMPLEMENTATION_GUIDE.md`
2. Method signatures? → `/docs/API_REFERENCE.md`
3. Chess rules? → `/docs/CHESS_RULES.md`
4. Debugging? → `/docs/DEVELOPER_GUIDE.md`
5. Timeline? → `/docs/HANDOFF_CHECKLIST.md`
6. Architecture? → `/docs/diagrams/ARCHITECTURE.md`

## 🏆 Definition of Done

Ein Feature ist "Done" wenn:
- ✅ Code geschrieben
- ✅ Tests geschrieben (90%+ coverage)
- ✅ Tests bestehen (grün)
- ✅ Code reviewed
- ✅ Dokumentiert (JSDoc)
- ✅ Performance OK (<100ms für moves)
- ✅ Accessibility geprüft
- ✅ Cross-browser getestet

## 🎯 Final Deliverables

Am Ende der Implementierung:

1. ✅ Funktionierendes Schachspiel (alle Features)
2. ✅ Comprehensive Test Suite (90%+ coverage)
3. ✅ Production Build (<150KB gzipped)
4. ✅ Deployment (Live URL)
5. ✅ README mit Setup/Usage
6. ✅ Performance Report (Lighthouse >90)
7. ✅ Browser Compatibility Matrix
8. ✅ Source Code (GitHub)

## 📈 Timeline & Milestones

- **Week 1:** MVP Core (playable 2-player chess)
- **Week 2:** MVP Complete + Tests
- **Week 3:** UX Enhancement (animations, history, save/load)
- **Week 4:** Polish + Deployment
- **Week 5 (Optional):** AI Opponent

**Total:** 4-5 weeks

---

## 🚀 Ready? Start hier:

1. Clone/Setup Project
2. Read `/docs/HANDOFF_CHECKLIST.md`
3. Follow `/docs/IMPLEMENTATION_GUIDE.md` step-by-step
4. Reference `/docs/API_REFERENCE.md` for specs
5. Build, test, deploy!

**Die Planung ist komplett. Alle Antworten sind in `/docs`. Viel Erfolg!** ♟️

---

**Version:** 1.0
**Created:** 2025-01-22
**Planning Swarm:** Hive Mind Collective Intelligence (8 agents)
**Implementation Swarm:** TBD (You!)
