# Multilingual Hello-World State Machine - Implementation Plan

## Context

**Objective**: Create a Python state machine that cycles through 2 languages (English and Spanish) and outputs "hello world" in each language.

**Requirements**:
- StateMachine class with states for English and Spanish
- Each state outputs "hello world" in that language
- Machine cycles through languages in order
- Comprehensive pytest unit tests verifying each language output

**Why**: This is a greenfield project demonstrating state machine patterns with internationalization support and proper testing practices.

---

## Architecture & Design Decisions

### Approach: Simple Enum + Class-Based State Machine

**Why this design**:
- Type-safe language representation using Python Enum
- Explicit state transitions with clear intent
- Return values pattern for easy testing (no stdout capture needed)
- Scalable foundation for adding more languages
- Pythonic and maintainable

### Key Components

1. **Language Enum** (`Language.ENGLISH`, `Language.SPANISH`)
   - Type-safe state representation
   - Discoverability of available languages

2. **StateMachine Class**
   - `LANGUAGES` list: ordered languages `[ENGLISH, SPANISH]`
   - `TRANSLATIONS` dict: language → "hello world" mapping
   - `greet()`: returns greeting in current language
   - `transition()`: cycles to next language using modulo arithmetic
   - `get_current_language()`: returns current state

3. **Output Mechanism**
   - Methods return strings (not print to stdout)
   - Enables easy testing without mocking
   - Caller can print if needed

---

## File Structure

```
project/
├── src/
│   ├── __init__.py
│   └── state_machine.py           # Language enum + StateMachine class
├── tests/
│   ├── __init__.py
│   └── test_state_machine.py      # Pytest unit tests
├── requirements.txt               # pytest dependency
├── setup.py                       # Package configuration
├── README.md                      # Documentation (optional)
└── CLAUDE.md                      # (existing - dev record guidelines)
```

---

## Implementation Steps

### Phase 1: Project Setup
1. Create `src/` and `tests/` directories with `__init__.py`
2. Create `requirements.txt` with `pytest>=7.0.0`
3. Create `setup.py` with package metadata

### Phase 2: Core Implementation (`src/state_machine.py`)
4. Define `Language` Enum with ENGLISH and SPANISH
5. Define `StateMachine` class with:
   - `LANGUAGES = [Language.ENGLISH, Language.SPANISH]`
   - `TRANSLATIONS` dictionary mapping languages to strings
   - `__init__()`: initialize with English state
   - `greet() -> str`: return current language greeting
   - `transition() -> None`: cycle to next language
   - `get_current_language() -> Language`: return current state

### Phase 3: Unit Tests (`tests/test_state_machine.py`)
6. Test initialization: state is English, greet returns "hello world"
7. Test transitions: English→Spanish, Spanish→English (wrap-around)
8. Test outputs: verify correct strings for each language
9. Test multi-cycle: verify repeated transitions work correctly

### Phase 4: Verification
10. Run `pytest tests/` and verify all tests pass
11. Verify cycling works: ENGLISH → SPANISH → ENGLISH
12. Verify output correctness in each state

---

## Key Code Patterns

### Language State Definition
```
Language.ENGLISH = "hello world"
Language.SPANISH = "hola mundo"
```

### State Cycling Logic
```
current_index = LANGUAGES.index(self.current_language)
next_index = (current_index + 1) % len(LANGUAGES)
self.current_language = LANGUAGES[next_index]
```

### Testing Pattern
```
- Create StateMachine instance
- Assert initial state and output
- Call transition()
- Assert new state and output
- Repeat for cycling verification
```

---

## Critical Files to Create

| File | Purpose |
|------|---------|
| `src/state_machine.py` | Core StateMachine and Language Enum implementation |
| `tests/test_state_machine.py` | Pytest unit tests verifying outputs and transitions |
| `setup.py` | Package metadata and dependency configuration |
| `requirements.txt` | Development dependencies (pytest) |

---

## Verification Plan

**How to test the implementation**:

1. **Run all tests**:
   ```bash
   pytest tests/
   ```

2. **Expected test results**: All tests pass with coverage of:
   - Initial state is English
   - English greet returns "hello world"
   - Spanish greet returns "hola mundo"
   - Transition from English to Spanish works
   - Transition from Spanish back to English works (wrap-around)
   - Multiple transitions cycle correctly

3. **Manual verification** (optional):
   - Create a small script that instantiates StateMachine
   - Call `greet()` and `transition()` in a loop
   - Verify English/Spanish output alternates correctly

---

## Notes

- No external dependencies required (pytest is dev-only)
- Python 3.7+ (for type hints)
- This design is intentionally simple and focused on the requirements
- Enum-based approach prevents invalid language states
- Modulo arithmetic ensures seamless cycling