# Developer Guide – Extending Protocols & Steps

FoodSpec protocols are YAML/JSON recipes interpreted by the `ProtocolRunner`. You can add new steps or extend existing ones without modifying core logic.

## Step registry overview
- Step types are registered in `src/foodspec/protocol_engine.py`.
- Built-ins include: `preprocess`, `harmonize`, `qc_checks`, `hsi_segment`, `hsi_roi_to_1d`, `rq_analysis`, `output`.
- Each step receives a context dict (dataframes/datasets, config, registry handle, cancel flag) and returns updated context.

## Adding a new step type
1. Implement the handler in a new module (e.g., `src/foodspec/steps/your_step.py`). It should accept `(context, params)` and return the updated context; check the cancel flag if long-running.
2. Register it in the step registry in `protocol_engine.py`.
3. Add schema/validation entries so YAML protocols can declare it (type name + expected params).
4. Update docs and tests with a minimal protocol exercising the new step.

## Making it visible in CLI
- Protocols that include your step will work automatically in the CLI.

## Extending protocols
- Protocol YAMLs live under `examples/protocols/`.
- Add new fields for your step under `steps:` with `type: your_step` and any params.
- Include `expected_columns` or `expected_metadata` if your step needs them.

## Plugins
- Steps and protocols can also be shipped as plugins (see `writing_plugins.md`). Plugins register entry points so they are discovered without editing core code.

## Tests and docs
- Add a small synthetic test under `tests/` that executes your step via `ProtocolRunner`.
- Document the new step in `docs/04-user-guide/protocols_and_yaml.md` and, if advanced, in `05-advanced-topics/architecture.md`.
