# Implementation Plan: Multilingual Hello-World State Machine

## Context

Create a multilingual hello-world state machine that demonstrates state cycling between two languages (English and Spanish). Each state prints the greeting in its respective language, and the machine automatically cycles through them. This includes comprehensive unit tests to verify correct behavior.

## Architecture

**Pattern**: Simple class-based state machine (avoids complexity overhead of GoF State pattern for this scope)

**Key Components**:
- `Language` enum: Type-safe representation of states (ENGLISH, SPANISH)
- `StateMachine` class: Manages current state, transitions, and output
- Separation of concern: `greet()` returns string, `print_greeting()` outputs to stdout

**Why this approach**:
- Type-safe states via Enum
- Easy to extend with additional languages
- Simple and maintainable for this scope
- Testable without complex mocking

## File Structure

```
project/
├── src/
│   ├── __init__.py                    (empty package marker)
│   └── state_machine.py               (StateMachine class implementation)
├── tests/
│   ├── __init__.py                    (empty package marker)
│   └── test_state_machine.py          (pytest unit tests)
├── requirements.txt                   (pytest dependency)
└── (existing files: .git/, .gitignore, CLAUDE.md, etc.)
```

## Implementation Details

### StateMachine Class API

```python
class StateMachine:
    def __init__(self):
        """Initialize with English as starting state."""

    def greet(self) -> str:
        """Return greeting text in current language (no side effects)."""

    def print_greeting(self) -> None:
        """Print greeting to stdout."""

    def next(self) -> None:
        """Transition to next language (English ↔ Spanish, cycling)."""

    @property
    def current_language(self) -> Language:
        """Get current language state."""
```

### Key Design Decisions

1. **Greetings as class constant dictionary**:
   ```python
   GREETINGS = {
       Language.ENGLISH: "Hello, World!",
       Language.SPANISH: "¡Hola, Mundo!",
   }
   ```
   - Decoupled from logic; easy to modify
   - Supports future config-driven approach

2. **State cycling via Enum iteration**:
   - Convert to list, find current index, increment with modulo wrapping
   - Scales naturally to more than 2 languages

3. **Starting state**: English (sensible default for "hello world")

## Test Coverage

**Test cases to implement**:
- `test_initial_state`: Verify starts in English
- `test_english_greeting`: Verify English output from `greet()`
- `test_spanish_greeting`: Verify Spanish output after `next()`
- `test_cycle_back_to_english`: Verify wrapping (Spanish → English)
- `test_print_greeting_english`: Verify stdout output using `capsys` fixture
- `test_print_greeting_spanish`: Verify Spanish stdout after state change
- `test_multiple_cycles`: Verify pattern holds over many transitions
- `test_current_language_property`: Verify property reflects state changes

**Testing approach**:
- Use `capsys` pytest fixture for stdout capture (built-in, no mocking needed)
- String equality assertions for `greet()` return values
- Idempotent verification: calling `greet()` multiple times returns same value

## Critical Files to Create

1. **`src/state_machine.py`**
   - `Language` enum with ENGLISH, SPANISH
   - `StateMachine` class with `__init__`, `greet()`, `print_greeting()`, `next()`, `current_language` property
   - ~40-50 lines of implementation code

2. **`tests/test_state_machine.py`**
   - Import `StateMachine`, `Language` from `state_machine`
   - 8+ test methods covering state transitions, output, and edge cases
   - ~80-100 lines of test code

3. **`src/__init__.py`**
   - Empty file (package marker)

4. **`tests/__init__.py`**
   - Empty file (package marker)

5. **`requirements.txt`**
   - Single line: `pytest>=7.0.0`

## Reusable Utilities

No utilities to reuse in this greenfield project. However, this design is extensible:
- Add languages: extend `Language` enum and `GREETINGS` dict
- Extract greetings to config file: replace dict with JSON/YAML loader
- Migrate to State pattern: wrap logic in separate state classes if complexity grows

## Verification

**Execution steps**:
1. Install dependencies: `pip install -r requirements.txt`
2. Run tests: `pytest tests/test_state_machine.py -v`
3. Manual verification: Create simple script to instantiate `StateMachine` and call methods
4. Verify all tests pass (expected: 8+ tests, all passing)
5. Verify pytest output shows correct English/Spanish assertions

**Expected test output**:
```
tests/test_state_machine.py::test_initial_state PASSED
tests/test_state_machine.py::test_english_greeting PASSED
tests/test_state_machine.py::test_spanish_greeting PASSED
tests/test_state_machine.py::test_cycle_back_to_english PASSED
tests/test_state_machine.py::test_print_greeting_english PASSED
tests/test_state_machine.py::test_print_greeting_spanish PASSED
tests/test_state_machine.py::test_multiple_cycles PASSED
tests/test_state_machine.py::test_current_language_property PASSED
```

## Dependencies

- **pytest >= 7.0.0**: Standard Python testing framework
- **Python >= 3.8**: For Enum and modern type hints
- No other external dependencies required

## Summary

A clean, testable multilingual state machine implementation:
- ✓ Separates state logic from output mechanism
- ✓ Type-safe via Enum
- ✓ Comprehensive test coverage of state transitions and output
- ✓ Extensible design for future language additions
- ✓ Follows Python best practices (PEP 8, standard package structure)