# Development Plan
## Phase 1: Vertical Slice (MVP)

| Document ID | DEV-001 |
|-------------|---------|
| Version | 1.0.0 |
| Status | Active |
| Author | Kai Chappell |
| Created | 2025-12-01 |

---

## Approach

This plan follows an **iterative, stub-first development** strategy optimised for incremental progress:

1. **Interfaces First** - Define protocols/interfaces before implementations
2. **Stubs Before Logic** - Create skeleton classes that pass type checks before adding behaviour
3. **Bottom-Up Construction** - Build foundational layers before dependent layers
4. **Frequent Commits** - Small, atomic commits after each meaningful change
5. **Minimal Context** - Each iteration should be completable with minimal codebase knowledge

---

## Sprint Structure

Each sprint represents ~2-4 hours of focused work. Sprints are designed to be self-contained with clear deliverables.

---

## Sprint 1: Project Scaffolding

**Goal:** Create project structure and build configuration.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 1.1 | Create `pyproject.toml` with project metadata and dependencies | `chore: add pyproject.toml with dependencies` |
| 1.2 | Create `src/thermaulate/__init__.py` with version | `chore: create package structure` |
| 1.3 | Create empty subpackage `__init__.py` files for all modules | `chore: add subpackage stubs` |
| 1.4 | Create `py.typed` marker file | `chore: add py.typed marker for PEP 561` |
| 1.5 | Create `config/default.yaml` with basic structure | `chore: add default configuration file` |

### Deliverables
- `pip install -e .` works
- All imports resolve (empty packages)
- Type checker can be run

---

## Sprint 2: Configuration System

**Goal:** Load and validate configuration.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 2.1 | Create `config/models.py` with Pydantic config classes | `feat(config): add Pydantic configuration models` |
| 2.2 | Create `config/loader.py` to load YAML and return AppConfig | `feat(config): add configuration loader` |
| 2.3 | Add unit tests for config loading | `test(config): add configuration tests` |

### Deliverables
- Can load `config/default.yaml` into typed Python objects
- Invalid configs raise clear errors

---

## Sprint 3: Transport Layer (Stubs)

**Goal:** Define transport abstractions.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 3.1 | Create `transport/base.py` with `Transport` Protocol | `feat(transport): add Transport protocol` |
| 3.2 | Create `transport/tcp.py` with `TCPTransport` stub class | `feat(transport): add TCPTransport stub` |

### Deliverables
- Transport interface defined
- TCPTransport class exists with NotImplementedError methods

---

## Sprint 4: Transport Layer (Implementation)

**Goal:** Implement TCP transport.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 4.1 | Implement `TCPTransport.connect()` and `disconnect()` | `feat(transport): implement TCP connect/disconnect` |
| 4.2 | Implement `TCPTransport.write()` and `read()` | `feat(transport): implement TCP read/write` |
| 4.3 | Implement `TCPTransport.query()` | `feat(transport): implement TCP query` |
| 4.4 | Add unit tests with mock socket | `test(transport): add TCP transport tests` |

### Deliverables
- Can connect to TCP server and exchange messages
- Handles connection errors gracefully

---

## Sprint 5: SCPI Parser

**Goal:** Parse SCPI command strings.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 5.1 | Create `instruments/scpi_parser.py` with `SCPICommand` dataclass | `feat(scpi): add SCPICommand dataclass` |
| 5.2 | Implement `SCPIParser.parse()` method | `feat(scpi): implement SCPI parser` |
| 5.3 | Add comprehensive parser tests | `test(scpi): add parser tests` |

### Deliverables
- Can parse `*IDN?`, `VOLT 3.3`, `TEMP:SETPOINT?`, etc.
- Returns structured command objects

---

## Sprint 6: Physics Engine (Stubs)

**Goal:** Define physics simulation interfaces.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 6.1 | Create `physics/engine.py` with state dataclasses | `feat(physics): add ThermalState and ElectricalState` |
| 6.2 | Create `PhysicsEngine` class with stub methods | `feat(physics): add PhysicsEngine stub` |
| 6.3 | Create `physics/dut/base.py` with `DUTModel` Protocol | `feat(physics): add DUT model protocol` |

### Deliverables
- Physics interfaces defined
- State objects can be instantiated

---

## Sprint 7: Physics Engine (Thermal)

**Goal:** Implement thermal simulation.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 7.1 | Implement `PhysicsEngine.step()` thermal calculations | `feat(physics): implement thermal step` |
| 7.2 | Implement `PhysicsEngine.set_chamber_setpoint()` | `feat(physics): implement chamber setpoint` |
| 7.3 | Implement `PhysicsEngine.get_thermal_state()` | `feat(physics): implement thermal state getter` |
| 7.4 | Add thermal simulation tests | `test(physics): add thermal simulation tests` |

### Deliverables
- Chamber temperature ramps toward setpoint
- Case temperature follows with time constant

---

## Sprint 8: LDO DUT Model

**Goal:** Implement LDO electrical model.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 8.1 | Create `physics/dut/ldo.py` with `LDOModel` class | `feat(physics): add LDO model stub` |
| 8.2 | Implement temperature-dependent output voltage | `feat(physics): implement LDO Vout vs temperature` |
| 8.3 | Implement power dissipation calculation | `feat(physics): implement LDO power dissipation` |
| 8.4 | Implement quiescent current model | `feat(physics): implement LDO quiescent current` |
| 8.5 | Add LDO model tests | `test(physics): add LDO model tests` |

### Deliverables
- LDO output voltage varies with temperature (TempCo)
- Power dissipation calculated correctly

---

## Sprint 9: Physics Engine (Electrical Coupling)

**Goal:** Connect electrical and thermal domains.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 9.1 | Integrate LDO model into PhysicsEngine | `feat(physics): integrate DUT model` |
| 9.2 | Implement self-heating feedback loop | `feat(physics): implement self-heating` |
| 9.3 | Implement `get_electrical_state()` | `feat(physics): implement electrical state getter` |
| 9.4 | Add coupled physics tests | `test(physics): add thermal-electrical coupling tests` |

### Deliverables
- Higher load current causes self-heating
- Junction temperature affects output voltage

---

## Sprint 10: Virtual Instruments (Stubs)

**Goal:** Define virtual instrument classes.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 10.1 | Create `instruments/base.py` with `VirtualInstrument` base class | `feat(instruments): add VirtualInstrument base` |
| 10.2 | Create `instruments/thermal_chamber.py` stub | `feat(instruments): add ThermalChamberSim stub` |
| 10.3 | Create `instruments/power_supply.py` stub | `feat(instruments): add PowerSupplySim stub` |
| 10.4 | Create `instruments/multimeter.py` stub | `feat(instruments): add MultimeterSim stub` |

### Deliverables
- All instrument classes exist
- Common SCPI commands stubbed (IDN, RST)

---

## Sprint 11: Thermal Chamber Simulator

**Goal:** Implement thermal chamber SCPI commands.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 11.1 | Implement `TEMP:SETPOINT` command | `feat(instruments): implement chamber TEMP:SETPOINT` |
| 11.2 | Implement `TEMP:ACTUAL?` query | `feat(instruments): implement chamber TEMP:ACTUAL?` |
| 11.3 | Implement `TEMP:STAB?` query | `feat(instruments): implement chamber stability query` |
| 11.4 | Add thermal chamber tests | `test(instruments): add thermal chamber tests` |

### Deliverables
- Chamber responds to SCPI commands
- Reads from physics engine state

---

## Sprint 12: Power Supply Simulator

**Goal:** Implement power supply SCPI commands.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 12.1 | Implement `VOLT`, `CURR`, `OUTP` commands | `feat(instruments): implement PSU control commands` |
| 12.2 | Implement `MEAS:VOLT?`, `MEAS:CURR?` queries | `feat(instruments): implement PSU measurements` |
| 12.3 | Add power supply tests | `test(instruments): add power supply tests` |

### Deliverables
- PSU responds to voltage/current/output commands
- Measurements reflect physics state

---

## Sprint 13: Multimeter Simulator

**Goal:** Implement DMM SCPI commands.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 13.1 | Implement `MEAS:VOLT:DC?` query | `feat(instruments): implement DMM voltage measurement` |
| 13.2 | Implement `SENS:VOLT:DC:NPLC` command | `feat(instruments): implement DMM NPLC setting` |
| 13.3 | Add multimeter tests | `test(instruments): add multimeter tests` |

### Deliverables
- DMM returns DUT output voltage from physics
- Integration time configurable

---

## Sprint 14: TCP Server

**Goal:** Create async TCP server for instruments.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 14.1 | Create `server/tcp_server.py` with async server class | `feat(server): add async TCP server` |
| 14.2 | Implement connection handling and command dispatch | `feat(server): implement command dispatch` |
| 14.3 | Create `server/main.py` entry point | `feat(server): add server entry point` |
| 14.4 | Add server integration tests | `test(server): add TCP server tests` |

### Deliverables
- Server listens on configured ports
- Routes commands to correct instrument
- Runs physics engine in background

---

## Sprint 15: HAL Interfaces

**Goal:** Define hardware abstraction protocols.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 15.1 | Create `hal/interfaces.py` with all Protocol classes | `feat(hal): add HAL protocol definitions` |
| 15.2 | Create `hal/factory.py` with `InstrumentSet` and stub factory | `feat(hal): add instrument factory stub` |

### Deliverables
- IThermalChamber, IPowerSupply, IMultimeter defined
- Factory interface established

---

## Sprint 16: SCPI Drivers

**Goal:** Create client-side SCPI drivers.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 16.1 | Create `drivers/base.py` with common driver functionality | `feat(drivers): add driver base class` |
| 16.2 | Create `drivers/thermal_chamber.py` | `feat(drivers): add thermal chamber driver` |
| 16.3 | Create `drivers/power_supply.py` | `feat(drivers): add power supply driver` |
| 16.4 | Create `drivers/multimeter.py` | `feat(drivers): add multimeter driver` |

### Deliverables
- Drivers send SCPI commands via transport
- Parse responses into Python types

---

## Sprint 17: HAL Implementations

**Goal:** Implement HAL using drivers.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 17.1 | Create `hal/impl/thermal_chamber.py` | `feat(hal): implement ThermalChamberHAL` |
| 17.2 | Create `hal/impl/power_supply.py` | `feat(hal): implement PowerSupplyHAL` |
| 17.3 | Create `hal/impl/multimeter.py` | `feat(hal): implement MultimeterHAL` |
| 17.4 | Implement `InstrumentFactory.create()` | `feat(hal): implement instrument factory` |
| 17.5 | Add HAL integration tests | `test(hal): add HAL integration tests` |

### Deliverables
- HAL classes wrap drivers
- Factory creates connected instrument set

---

## Sprint 18: Test Executive (Core)

**Goal:** Create test execution framework.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 18.1 | Create `executive/models.py` with domain models | `feat(executive): add test domain models` |
| 18.2 | Create `executive/context.py` with TestContext | `feat(executive): add test context` |
| 18.3 | Create `executive/logger.py` with test logger | `feat(executive): add test logger` |
| 18.4 | Create `executive/limits.py` with limit checker | `feat(executive): add limit checker` |

### Deliverables
- Can create test contexts
- Can log measurements
- Can evaluate limits

---

## Sprint 19: Test Executive (Sequencer)

**Goal:** Implement test sequencer.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 19.1 | Create `executive/sequencer.py` with TestSequencer class | `feat(executive): add test sequencer` |
| 19.2 | Create `tests/base.py` with ITest protocol | `feat(tests): add test base class` |
| 19.3 | Add sequencer tests | `test(executive): add sequencer tests` |

### Deliverables
- Sequencer runs test instances
- Manages context lifecycle

---

## Sprint 20: TempCo Test Implementation

**Goal:** Implement temperature coefficient characterisation test.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 20.1 | Create `tests/tempco.py` with TempCoTest class | `feat(tests): add TempCo test stub` |
| 20.2 | Implement temperature sweep logic | `feat(tests): implement TempCo temperature sweep` |
| 20.3 | Implement TempCo calculation | `feat(tests): implement TempCo calculation` |
| 20.4 | Add TempCo test tests | `test(tests): add TempCo test coverage` |

### Deliverables
- Complete TempCo characterisation test
- Calculates ppm/°C result

---

## Sprint 21: Data Persistence (Schema)

**Goal:** Set up data storage.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 21.1 | Create `data/models.py` with data models | `feat(data): add data models` |
| 21.2 | Create `data/migrations/001_initial.sql` | `feat(data): add initial schema migration` |
| 21.3 | Create `data/repository.py` with repository interface | `feat(data): add repository interface` |

### Deliverables
- SQLite schema defined
- Repository interface established

---

## Sprint 22: Data Persistence (Implementation)

**Goal:** Implement data repository.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 22.1 | Implement SQLite repository for test runs | `feat(data): implement test run persistence` |
| 22.2 | Implement Parquet writer for measurements | `feat(data): implement measurement persistence` |
| 22.3 | Add repository tests | `test(data): add repository tests` |

### Deliverables
- Test runs persisted to SQLite
- Measurements saved as Parquet files

---

## Sprint 23: CLI (Basic)

**Goal:** Create command-line interface.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 23.1 | Create `cli/main.py` with Typer app | `feat(cli): add CLI application` |
| 23.2 | Add `server start` command | `feat(cli): add server start command` |
| 23.3 | Add `test run` command | `feat(cli): add test run command` |
| 23.4 | Add `test list` command | `feat(cli): add test list command` |

### Deliverables
- `thermaulate server start` launches simulation
- `thermaulate test run tempco` executes test

---

## Sprint 24: Streamlit Dashboard (Basic)

**Goal:** Create real-time monitoring dashboard.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 24.1 | Create `dashboard/app.py` with main Streamlit app | `feat(dashboard): add Streamlit app` |
| 24.2 | Create instruments status page | `feat(dashboard): add instruments page` |
| 24.3 | Add real-time temperature chart | `feat(dashboard): add temperature chart` |

### Deliverables
- Dashboard shows instrument status
- Temperature updates in real-time

---

## Sprint 25: Integration & Polish

**Goal:** End-to-end testing and refinement.

### Tasks

| # | Task | Commit Message |
|---|------|----------------|
| 25.1 | Run full TempCo test end-to-end | `test: add end-to-end TempCo test` |
| 25.2 | Fix any integration issues discovered | `fix: resolve integration issues` |
| 25.3 | Add demo script | `docs: add demo script` |
| 25.4 | Update README with usage instructions | `docs: update README with usage` |
| 25.5 | Verify 80% test coverage on core modules | `test: ensure coverage targets met` |

### Deliverables
- Complete working vertical slice
- Demo-able system
- Documentation updated

---

## Sprint Summary

| Sprint | Focus | Estimated Tasks |
|--------|-------|-----------------|
| 1 | Project scaffolding | 5 |
| 2 | Configuration | 3 |
| 3-4 | Transport layer | 7 |
| 5 | SCPI parser | 3 |
| 6-9 | Physics engine | 16 |
| 10-13 | Virtual instruments | 14 |
| 14 | TCP server | 4 |
| 15-17 | HAL layer | 10 |
| 18-19 | Test executive | 7 |
| 20 | TempCo test | 4 |
| 21-22 | Data persistence | 6 |
| 23 | CLI | 4 |
| 24 | Dashboard | 3 |
| 25 | Integration | 5 |

**Total: 25 sprints, ~91 tasks, ~91 commits**

---

## LLM Optimisation Notes

Each sprint is designed for LLM execution with:

1. **Minimal Context Required** - Each sprint focuses on 1-2 files
2. **Clear Boundaries** - Interfaces defined before implementations
3. **Testable Increments** - Each sprint has verification criteria
4. **Atomic Commits** - Small, focused changes that are easy to review
5. **Stub-First Approach** - Type-safe placeholders before full logic

When starting a sprint:
1. Read only the relevant module's existing code
2. Reference interfaces/protocols, not implementations
3. Complete all tasks before moving to next sprint
4. Commit after each task

---

**End of Development Plan**