# Plan: Multilingual Hello-World State Machine

## Context
The project is a blank Python repo (no source files yet). The user wants a `StateMachine` class that cycles through English and Spanish "hello world" states, with pytest tests verifying each language's output.

---

## Files to Create

| File | Purpose |
|------|---------|
| `project/hello_world_sm.py` | State machine implementation |
| `project/test_hello_world_sm.py` | pytest unit tests |

No existing utilities to reuse (project is empty).

---

## Implementation Design

### `project/hello_world_sm.py`

**`State` dataclass / simple class:**
```python
@dataclass
class State:
    name: str        # e.g. "english", "spanish"
    greeting: str    # e.g. "Hello, World!", "¡Hola, Mundo!"
```

**`StateMachine` class:**
- `__init__`: builds ordered list of `State` objects (English → Spanish) and sets `current_index = 0`
- `current_state` property: returns the active `State`
- `greet()`: prints `self.current_state.greeting` (captured by tests via `capsys`)
- `transition()`: advances `current_index` to `(current_index + 1) % len(states)` — wraps around for cycling

### States (in order)

| Index | Name | Greeting |
|-------|------|----------|
| 0 | `"english"` | `"Hello, World!"` |
| 1 | `"spanish"` | `"¡Hola, Mundo!"` |

---

## Test Plan — `project/test_hello_world_sm.py`

Using `pytest` with `capsys` fixture to capture stdout:

1. **`test_initial_state_is_english`** — verify `sm.current_state.name == "english"` on fresh machine
2. **`test_english_greeting`** — call `sm.greet()`, assert stdout contains `"Hello, World!"`
3. **`test_transition_to_spanish`** — call `sm.transition()`, assert `sm.current_state.name == "spanish"`
4. **`test_spanish_greeting`** — transition once, call `sm.greet()`, assert stdout contains `"¡Hola, Mundo!"`
5. **`test_cycles_back_to_english`** — transition twice, assert back to `"english"`
6. **`test_full_cycle_greetings`** — run a full two-step cycle and verify both greetings in order

No `conftest.py` or `pytest.ini` needed — pytest discovery works out of the box with the `test_` prefix.

---

## Audit Requirement (CLAUDE.md)

Before starting implementation, log `plan_stated` via:
```bash
bash audit/agent-report.sh "SESSION_ID" "plan_stated" "multilingual hello-world state machine with English and Spanish states and pytest tests"
```

---

## Verification

```bash
cd /tmp/pytest-sandbox/test_full_workflow0/project
python -m pytest test_hello_world_sm.py -v
```

Expected: **6 tests pass**, output shows both greetings exercised.