From 76c6c87d4fe8662e71b1aa180747c2d20b4aab0b Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:07:17 +0100
Subject: [PATCH 01/16] Add design spec for AI contributor skills and
 validation pipeline

Defines per-script directory structure, Claude Code skills (contribute-script,
validate-script), AGENTS.md contributor guide, and GitHub Actions CI for
validating pyopenms script contributions in isolated venvs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ...2026-03-24-ai-contributor-skills-design.md | 134 ++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-03-24-ai-contributor-skills-design.md

diff --git a/docs/superpowers/specs/2026-03-24-ai-contributor-skills-design.md b/docs/superpowers/specs/2026-03-24-ai-contributor-skills-design.md
new file mode 100644
index 0000000..a86f90e
--- /dev/null
+++ b/docs/superpowers/specs/2026-03-24-ai-contributor-skills-design.md
@@ -0,0 +1,134 @@
+# AI Contributor Skills & Plans — Design Spec
+
+## Purpose
+
+Define the skills, contributor docs, and CI pipeline that enable AI agents to contribute validated, self-contained pyopenms scripts to the agentomics repo. Every contribution must build against the latest pyopenms, resolve its own dependencies, and pass linting + tests in isolation.
+
+## Per-Script Directory Structure
+
+Every script is a self-contained package under `scripts/<domain>/<tool_name>/`:
+
+```
+scripts/proteomics/peptide_mass_calculator/
+├── peptide_mass_calculator.py
+├── requirements.txt
+├── README.md
+└── tests/
+    └── test_peptide_mass_calculator.py
+```
+
+Rules:
+
+- `requirements.txt` always includes `pyopenms` with no version pin (builds against latest) plus any script-specific dependencies
+- Tests live inside each script's own `tests/` directory (not a top-level `tests/`)
+- Each script is self-contained — no cross-script imports
+- Tests use the `@requires_pyopenms` skip marker pattern (`pytest.mark.skipif`)
+- Existing 7 scripts are migrated to this structure
+
+## Validation Pipeline
+
+For any given script directory, validation runs:
+
+```bash
+python -m venv /tmp/validate_<tool>
+source /tmp/validate_<tool>/bin/activate
+pip install -r <script>/requirements.txt
+pip install pytest ruff
+ruff check <script>/
+python -m pytest <script>/tests/ -v
+deactivate
+rm -rf /tmp/validate_<tool>
+```
+
+Rules:
+
+- Each script is validated in isolation — its own fresh venv, no shared state
+- ruff configuration lives in repo root as `ruff.toml` (line length 120, standard Python rules)
+- The same validation logic is used by: the Claude Code `validate-script` skill, the GitHub Actions CI pipeline, and documented in `AGENTS.md` for other AI agents to replicate
+- Validation must pass before a contribution is considered complete
+
+## Claude Code Skills
+
+Two skills in `.claude/skills/`:
+
+### `contribute-script`
+
+Guides an AI agent through creating a new script end-to-end. Rigid — follow exactly, no skipping steps.
+
+1. **Ask what the tool does** — what pyopenms functionality does it wrap, what gap does it fill
+2. **Determine domain** — proteomics or metabolomics (or prompt if a new domain is needed)
+3. **Scaffold directory** — create `scripts/<domain>/<tool_name>/` with `requirements.txt`, empty `README.md`, empty test file
+4. **Write the script** — following established patterns:
+   - pyopenms try/except import with user-friendly error message
+   - `PROTON = 1.007276` constant where mass-to-charge calculations are needed
+   - Importable functions as primary interface
+   - `main()` function with argparse CLI
+   - `if __name__ == "__main__"` guard
+   - Type hints in function signatures
+   - Numpy-style docstrings
+5. **Write tests** — pytest with `@requires_pyopenms` marker, covering core functionality
+6. **Write README** — CLI usage examples
+7. **Validate** — invoke the `validate-script` logic (fresh venv, ruff, pytest)
+8. **Commit** — on a feature branch
+
+### `validate-script`
+
+Standalone validation — can be invoked on any script directory. Rigid.
+
+1. Detect target script directory (from argument or prompt user)
+2. Create temporary venv
+3. Install from the script's `requirements.txt`
+4. Install `pytest` and `ruff`
+5. Run `ruff check` on the script directory
+6. Run `python -m pytest` on the script's `tests/` directory
+7. Report results — pass/fail with details
+8. Clean up temporary venv
+
+## AGENTS.md
+
+Platform-agnostic contributor guide at repo root for any AI agent (Copilot, Cursor, Gemini, etc.). Contents:
+
+1. **Project purpose** — agentic-only pyopenms tools for proteomics/metabolomics that don't yet exist in OpenMS
+2. **Contribution requirements:**
+   - Self-contained directory under `scripts/<domain>/<tool_name>/`
+   - Must include: script `.py`, `requirements.txt`, `README.md`, `tests/` with pytest tests
+   - Must use latest pyopenms (no version pinning)
+   - Must pass ruff + pytest in an isolated venv
+3. **Code patterns to follow:**
+   - pyopenms import guard (try/except with install message)
+   - Dual interface: importable functions + argparse CLI + `__main__` guard
+   - Numpy-style docstrings, type hints
+   - `@requires_pyopenms` test skip marker
+4. **Validation steps** — exact shell commands to create a venv, install, lint, test
+5. **What not to do:**
+   - No cross-script imports
+   - No adding deps to a shared requirements file
+   - No scripts that duplicate existing pyopenms functionality
+
+## GitHub Actions CI
+
+`.github/workflows/validate.yml`:
+
+- **Trigger:** Pull requests that touch anything under `scripts/`
+- **Detection job:** Diffs against base branch to identify changed script directories, outputs them as a JSON matrix
+- **Validation matrix:** For each changed script directory, a parallel job that:
+  1. Checks out the repo
+  2. Sets up Python (latest stable 3.x)
+  3. Creates a venv
+  4. `pip install -r <script>/requirements.txt`
+  5. `pip install pytest ruff`
+  6. `ruff check <script>/`
+  7. `python -m pytest <script>/tests/ -v`
+- **Designed for branch protection** — can be set as a required status check to block merges on failure
+- Uses the same `ruff.toml` at repo root as local validation
+
+## Deliverables
+
+1. Migrate existing 7 scripts to per-script directory structure
+2. Create `ruff.toml` at repo root
+3. Create `.claude/skills/contribute-script.md`
+4. Create `.claude/skills/validate-script.md`
+5. Create `AGENTS.md` at repo root
+6. Create `.github/workflows/validate.yml`
+7. Update `CLAUDE.md` to reference new structure and skills
+8. Update root `README.md` to reflect new structure

From 39ef3cdae269be2f6e0e00859f3148b97ffe4451 Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:12:55 +0100
Subject: [PATCH 02/16] Address spec review feedback: clarify imports,
 migration, conftest template

- Resolve PYTHONPATH vs sys.path contradiction: PYTHONPATH is primary,
  conftest.py provides fallback for direct pytest invocation
- Add concrete conftest.py template to reduce implementation ambiguity
- Clarify migration: copy files from feature branch, decompose monolithic
  test files and shared requirements.txt into per-script structure
- Use consistent language for branch migration (copy + restructure)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ...2026-03-24-ai-contributor-skills-design.md | 78 ++++++++++++++-----
 1 file changed, 58 insertions(+), 20 deletions(-)

diff --git a/docs/superpowers/specs/2026-03-24-ai-contributor-skills-design.md b/docs/superpowers/specs/2026-03-24-ai-contributor-skills-design.md
index a86f90e..7a3480e 100644
--- a/docs/superpowers/specs/2026-03-24-ai-contributor-skills-design.md
+++ b/docs/superpowers/specs/2026-03-24-ai-contributor-skills-design.md
@@ -14,6 +14,7 @@ scripts/proteomics/peptide_mass_calculator/
 ├── requirements.txt
 ├── README.md
 └── tests/
+    ├── conftest.py
     └── test_peptide_mass_calculator.py
 ```
 
@@ -22,8 +23,27 @@ Rules:
 - `requirements.txt` always includes `pyopenms` with no version pin (builds against latest) plus any script-specific dependencies
 - Tests live inside each script's own `tests/` directory (not a top-level `tests/`)
 - Each script is self-contained — no cross-script imports
-- Tests use the `@requires_pyopenms` skip marker pattern (`pytest.mark.skipif`)
-- Existing 7 scripts are migrated to this structure
+- These directories are NOT Python packages — no `__init__.py` files
+- Each `tests/` directory includes a `conftest.py` that defines the `requires_pyopenms` marker. The `conftest.py` also adds the parent script directory to `sys.path` as a fallback for cases where `PYTHONPATH` is not set (e.g. running `pytest` directly without the validation wrapper):
+  ```python
+  import sys, os, pytest
+  sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+  try:
+      import pyopenms
+      HAS_PYOPENMS = True
+  except ImportError:
+      HAS_PYOPENMS = False
+  requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
+  ```
+- Existing 7 scripts live on the `origin/copilot/add-agentic-scripts-for-proteomics` branch (not yet on `main`). Migration involves copying the files from that branch and restructuring them into per-script directories. The existing monolithic test files (`tests/test_proteomics.py` covering 4 scripts, `tests/test_metabolomics.py` covering 3 scripts) must be decomposed so each script's test class moves into its own `tests/test_<tool_name>.py`. The single root `requirements.txt` is replaced by per-script `requirements.txt` files
+
+### Test Data Strategy
+
+Scripts that process files (mzML, featureXML) need test data. Strategy:
+
+- **Prefer synthetic data** — generate minimal test data in fixtures using pyopenms objects (e.g. `MSExperiment`, `FeatureMap`) directly in test setup
+- If synthetic generation is impractical, include small test fixture files in the script's `tests/` directory
+- File-I/O tests that cannot run without external data use an additional `@pytest.mark.skipif` marker (e.g. `requires_test_data`)
 
 ## Validation Pipeline
 
@@ -31,19 +51,26 @@ For any given script directory, validation runs:
 
 ```bash
 python -m venv /tmp/validate_<tool>
-source /tmp/validate_<tool>/bin/activate
-pip install -r <script>/requirements.txt
-pip install pytest ruff
-ruff check <script>/
-python -m pytest <script>/tests/ -v
-deactivate
+/tmp/validate_<tool>/bin/python -m pip install -r <script>/requirements.txt
+/tmp/validate_<tool>/bin/python -m pip install pytest ruff
+/tmp/validate_<tool>/bin/python -m ruff check <script>/
+PYTHONPATH=<script> /tmp/validate_<tool>/bin/python -m pytest <script>/tests/ -v
 rm -rf /tmp/validate_<tool>
 ```
 
+Note: Commands use direct venv binary paths (`/tmp/.../bin/python`) instead of `source activate` to avoid platform-specific activation scripts. On Windows, substitute `bin/` with `Scripts/`. CI runs on Ubuntu so this is not a concern there.
+
 Rules:
 
 - Each script is validated in isolation — its own fresh venv, no shared state
-- ruff configuration lives in repo root as `ruff.toml` (line length 120, standard Python rules)
+- `PYTHONPATH=<script>` is the primary mechanism for test imports; `conftest.py` provides a `sys.path` fallback for direct `pytest` invocation
+- ruff configuration lives in repo root as `ruff.toml`:
+  ```toml
+  line-length = 120
+  [lint]
+  select = ["E", "F", "W", "I"]
+  ```
+  (pycodestyle errors/warnings, pyflakes, isort)
 - The same validation logic is used by: the Claude Code `validate-script` skill, the GitHub Actions CI pipeline, and documented in `AGENTS.md` for other AI agents to replicate
 - Validation must pass before a contribution is considered complete
 
@@ -69,7 +96,7 @@ Guides an AI agent through creating a new script end-to-end. Rigid — follow ex
 5. **Write tests** — pytest with `@requires_pyopenms` marker, covering core functionality
 6. **Write README** — CLI usage examples
 7. **Validate** — invoke the `validate-script` logic (fresh venv, ruff, pytest)
-8. **Commit** — on a feature branch
+8. **Commit** — on a feature branch named `add/<tool_name>`
 
 ### `validate-script`
 
@@ -110,25 +137,36 @@ Platform-agnostic contributor guide at repo root for any AI agent (Copilot, Curs
 `.github/workflows/validate.yml`:
 
 - **Trigger:** Pull requests that touch anything under `scripts/`
-- **Detection job:** Diffs against base branch to identify changed script directories, outputs them as a JSON matrix
+- **Detection job:** Diffs against base branch to identify changed script directories, outputs them as a JSON matrix. Outputs a `has_changes` flag — the validation matrix is conditional on this flag so PRs that only touch non-script files don't produce an empty matrix error.
 - **Validation matrix:** For each changed script directory, a parallel job that:
   1. Checks out the repo
-  2. Sets up Python (latest stable 3.x)
+  2. Sets up Python 3.11 (pinned for pyopenms wheel availability — update when pyopenms supports newer versions)
   3. Creates a venv
   4. `pip install -r <script>/requirements.txt`
   5. `pip install pytest ruff`
   6. `ruff check <script>/`
-  7. `python -m pytest <script>/tests/ -v`
+  7. `PYTHONPATH=<script> python -m pytest <script>/tests/ -v`
 - **Designed for branch protection** — can be set as a required status check to block merges on failure
 - Uses the same `ruff.toml` at repo root as local validation
 
+## Updated CLAUDE.md
+
+After implementation, `CLAUDE.md` must reflect:
+
+- New per-script directory structure and how to navigate it
+- Per-script test commands: `PYTHONPATH=scripts/<domain>/<tool> python -m pytest scripts/<domain>/<tool>/tests/ -v`
+- Reference to the two Claude Code skills (`contribute-script`, `validate-script`)
+- Reference to `AGENTS.md` for the full contributor guide
+- Ruff lint command: `ruff check scripts/`
+
 ## Deliverables
 
-1. Migrate existing 7 scripts to per-script directory structure
+1. Merge content from `origin/copilot/add-agentic-scripts-for-proteomics` branch, then restructure into per-script directories
 2. Create `ruff.toml` at repo root
-3. Create `.claude/skills/contribute-script.md`
-4. Create `.claude/skills/validate-script.md`
-5. Create `AGENTS.md` at repo root
-6. Create `.github/workflows/validate.yml`
-7. Update `CLAUDE.md` to reference new structure and skills
-8. Update root `README.md` to reflect new structure
+3. Create per-script `conftest.py` with `requires_pyopenms` marker and `PYTHONPATH`/`sys.path` setup
+4. Create `.claude/skills/contribute-script.md`
+5. Create `.claude/skills/validate-script.md`
+6. Create `AGENTS.md` at repo root
+7. Create `.github/workflows/validate.yml`
+8. Update `CLAUDE.md` to reference new structure and skills
+9. Update root `README.md` to reflect new structure

From a81dbaf2ba4e077f8b6a256101e34ebccf46b92f Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:21:44 +0100
Subject: [PATCH 03/16] Add implementation plan for AI contributor skills and
 validation pipeline

14 tasks covering: ruff.toml, migration of 7 scripts to per-script
directories, Claude Code skills, AGENTS.md, GitHub Actions CI, and
documentation updates. Reviewed and approved with minor fixes applied.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-03-24-ai-contributor-skills.md | 1374 +++++++++++++++++
 1 file changed, 1374 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-03-24-ai-contributor-skills.md

diff --git a/docs/superpowers/plans/2026-03-24-ai-contributor-skills.md b/docs/superpowers/plans/2026-03-24-ai-contributor-skills.md
new file mode 100644
index 0000000..d2e73fe
--- /dev/null
+++ b/docs/superpowers/plans/2026-03-24-ai-contributor-skills.md
@@ -0,0 +1,1374 @@
+# AI Contributor Skills & Validation Pipeline — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Create skills, contributor docs, CI, and per-script directory structure so AI agents can contribute validated pyopenms scripts to agentomics.
+
+**Architecture:** Restructure existing flat scripts into self-contained per-script directories with isolated dependency resolution. Add Claude Code skills for guided contribution and validation, a platform-agnostic AGENTS.md, and a GitHub Actions CI pipeline that validates each script in its own venv.
+
+**Tech Stack:** Python, pyopenms, pytest, ruff, GitHub Actions
+
+**Spec:** `docs/superpowers/specs/2026-03-24-ai-contributor-skills-design.md`
+
+---
+
+### Task 1: Create ruff.toml
+
+**Files:**
+- Create: `ruff.toml`
+
+- [ ] **Step 1: Create ruff.toml**
+
+```toml
+line-length = 120
+
+[lint]
+select = ["E", "F", "W", "I"]
+```
+
+- [ ] **Step 2: Verify ruff.toml is valid**
+
+Run: `pip install ruff && ruff check --config ruff.toml . 2>&1 | head -5`
+Expected: No config errors (may show "No files found" which is fine)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add ruff.toml
+git commit -m "Add ruff.toml with E/F/W/I rule set, line-length 120"
+```
+
+---
+
+### Task 2: Migrate peptide_mass_calculator to per-script directory
+
+**Files:**
+- Create: `scripts/proteomics/peptide_mass_calculator/peptide_mass_calculator.py`
+- Create: `scripts/proteomics/peptide_mass_calculator/requirements.txt`
+- Create: `scripts/proteomics/peptide_mass_calculator/README.md`
+- Create: `scripts/proteomics/peptide_mass_calculator/tests/conftest.py`
+- Create: `scripts/proteomics/peptide_mass_calculator/tests/test_peptide_mass_calculator.py`
+
+- [ ] **Step 1: Create directory structure**
+
+```bash
+mkdir -p scripts/proteomics/peptide_mass_calculator/tests
+```
+
+- [ ] **Step 2: Copy script from feature branch**
+
+```bash
+git show origin/copilot/add-agentic-scripts-for-proteomics:scripts/proteomics/peptide_mass_calculator.py > scripts/proteomics/peptide_mass_calculator/peptide_mass_calculator.py
+```
+
+- [ ] **Step 3: Create requirements.txt**
+
+```
+pyopenms
+```
+
+- [ ] **Step 4: Create conftest.py**
+
+```python
+import sys
+import os
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
+```
+
+- [ ] **Step 5: Create test file**
+
+Extract the `TestPeptideMassCalculator` class from the feature branch's `tests/test_proteomics.py`. Adapt imports to use the conftest marker and direct module imports (no sys.path manipulation in the test file itself):
+
+```python
+"""Tests for peptide_mass_calculator."""
+
+import pytest
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestPeptideMassCalculator:
+    def test_basic_mass(self):
+        from peptide_mass_calculator import peptide_masses
+
+        result = peptide_masses("PEPTIDEK")
+        assert result["sequence"] == "PEPTIDEK"
+        assert result["charge"] == 1
+        assert 927.0 < result["monoisotopic_mass"] < 928.0
+        assert result["mz_monoisotopic"] > result["monoisotopic_mass"]
+
+    def test_charge_state(self):
+        from peptide_mass_calculator import peptide_masses
+
+        r1 = peptide_masses("PEPTIDEK", charge=1)
+        r2 = peptide_masses("PEPTIDEK", charge=2)
+        assert r2["mz_monoisotopic"] < r1["mz_monoisotopic"]
+
+    def test_fragment_ions(self):
+        from peptide_mass_calculator import fragment_ions
+
+        ions = fragment_ions("PEPTIDEK")
+        seq_len = len("PEPTIDEK")
+        assert len(ions["b_ions"]) == seq_len - 1
+        assert len(ions["y_ions"]) == seq_len - 1
+
+    def test_modified_sequence(self):
+        from peptide_mass_calculator import peptide_masses
+
+        result = peptide_masses("PEPTM[147]IDEK")
+        assert result["monoisotopic_mass"] > 0
+
+    def test_mz_formula(self):
+        from peptide_mass_calculator import peptide_masses, PROTON
+
+        r = peptide_masses("PEPTIDEK", charge=2)
+        expected = (r["monoisotopic_mass"] + 2 * PROTON) / 2
+        assert abs(r["mz_monoisotopic"] - expected) < 1e-6
+```
+
+- [ ] **Step 6: Create README.md**
+
+```markdown
+# Peptide Mass Calculator
+
+Calculate monoisotopic and average masses for peptide sequences, and compute
+b-ion / y-ion fragment series.
+
+## Usage
+
+```bash
+python peptide_mass_calculator.py --sequence PEPTIDEK
+python peptide_mass_calculator.py --sequence PEPTM[147]IDEK --charge 2
+python peptide_mass_calculator.py --sequence ACDEFGHIK --fragments
+```
+```
+
+- [ ] **Step 7: Run ruff**
+
+Run: `ruff check scripts/proteomics/peptide_mass_calculator/`
+Expected: No errors
+
+- [ ] **Step 8: Run tests**
+
+Run: `PYTHONPATH=scripts/proteomics/peptide_mass_calculator python -m pytest scripts/proteomics/peptide_mass_calculator/tests/ -v`
+Expected: 5 tests pass (or skip if pyopenms not installed)
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add scripts/proteomics/peptide_mass_calculator/
+git commit -m "Migrate peptide_mass_calculator to per-script directory structure"
+```
+
+---
+
+### Task 3: Migrate protein_digest to per-script directory
+
+**Files:**
+- Create: `scripts/proteomics/protein_digest/protein_digest.py`
+- Create: `scripts/proteomics/protein_digest/requirements.txt`
+- Create: `scripts/proteomics/protein_digest/README.md`
+- Create: `scripts/proteomics/protein_digest/tests/conftest.py`
+- Create: `scripts/proteomics/protein_digest/tests/test_protein_digest.py`
+
+- [ ] **Step 1: Create directory and copy script**
+
+```bash
+mkdir -p scripts/proteomics/protein_digest/tests
+git show origin/copilot/add-agentic-scripts-for-proteomics:scripts/proteomics/protein_digest.py > scripts/proteomics/protein_digest/protein_digest.py
+```
+
+- [ ] **Step 2: Create requirements.txt**
+
+```
+pyopenms
+```
+
+- [ ] **Step 3: Create conftest.py** (identical to Task 2 Step 4)
+
+- [ ] **Step 4: Create test file**
+
+Extract the `TestProteinDigest` class from the feature branch's `tests/test_proteomics.py`:
+
+```python
+"""Tests for protein_digest."""
+
+import pytest
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestProteinDigest:
+    PROTEIN = "MKVLWAALLVTFLAGCQAKVEQAVETEPEPELRQQTEWQSGQRWELAL"
+
+    def test_tryptic_digest_returns_peptides(self):
+        from protein_digest import digest_protein
+
+        peptides = digest_protein(self.PROTEIN, enzyme="Trypsin", min_length=1)
+        assert len(peptides) > 0
+
+    def test_peptide_structure(self):
+        from protein_digest import digest_protein
+
+        peptides = digest_protein(self.PROTEIN, enzyme="Trypsin", min_length=1)
+        for pep in peptides:
+            assert "sequence" in pep
+            assert "monoisotopic_mass" in pep
+            assert pep["monoisotopic_mass"] > 0
+
+    def test_missed_cleavages(self):
+        from protein_digest import digest_protein
+
+        peps_0 = digest_protein(self.PROTEIN, enzyme="Trypsin", missed_cleavages=0, min_length=1)
+        peps_2 = digest_protein(self.PROTEIN, enzyme="Trypsin", missed_cleavages=2, min_length=1)
+        assert len(peps_2) >= len(peps_0)
+
+    def test_length_filter(self):
+        from protein_digest import digest_protein
+
+        peptides = digest_protein(
+            self.PROTEIN, enzyme="Trypsin", min_length=5, max_length=20, missed_cleavages=2
+        )
+        for pep in peptides:
+            assert 5 <= pep["length"] <= 20
+
+    def test_list_enzymes(self):
+        from protein_digest import list_enzymes
+
+        enzymes = list_enzymes()
+        assert "Trypsin" in enzymes
+        assert len(enzymes) > 5
+```
+
+- [ ] **Step 5: Create README.md**
+
+```markdown
+# Protein In-Silico Digest
+
+Perform in-silico enzymatic digestion of a protein sequence and report
+the resulting peptides with their masses.
+
+## Usage
+
+```bash
+python protein_digest.py --sequence MKVLWAALLVTFLAGCQAK... --enzyme Trypsin
+python protein_digest.py --sequence MKVLWAALLVTFLAGCQAK... --enzyme Lys-C --missed-cleavages 2
+python protein_digest.py --list-enzymes
+```
+```
+
+- [ ] **Step 6: Run ruff and tests**
+
+Run: `ruff check scripts/proteomics/protein_digest/ && PYTHONPATH=scripts/proteomics/protein_digest python -m pytest scripts/proteomics/protein_digest/tests/ -v`
+Expected: Lint clean, 5 tests pass
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/proteomics/protein_digest/
+git commit -m "Migrate protein_digest to per-script directory structure"
+```
+
+---
+
+### Task 4: Migrate spectrum_file_info to per-script directory
+
+**Files:**
+- Create: `scripts/proteomics/spectrum_file_info/spectrum_file_info.py`
+- Create: `scripts/proteomics/spectrum_file_info/requirements.txt`
+- Create: `scripts/proteomics/spectrum_file_info/README.md`
+- Create: `scripts/proteomics/spectrum_file_info/tests/conftest.py`
+- Create: `scripts/proteomics/spectrum_file_info/tests/test_spectrum_file_info.py`
+
+- [ ] **Step 1: Create directory and copy script**
+
+```bash
+mkdir -p scripts/proteomics/spectrum_file_info/tests
+git show origin/copilot/add-agentic-scripts-for-proteomics:scripts/proteomics/spectrum_file_info.py > scripts/proteomics/spectrum_file_info/spectrum_file_info.py
+```
+
+- [ ] **Step 2: Create requirements.txt**
+
+```
+pyopenms
+```
+
+- [ ] **Step 3: Create conftest.py** (identical to Task 2 Step 4)
+
+- [ ] **Step 4: Create test file with synthetic data**
+
+This script processes mzML files. Tests generate synthetic MSExperiment data using pyopenms:
+
+```python
+"""Tests for spectrum_file_info."""
+
+import pytest
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestSpectrumFileInfo:
+    def _make_experiment(self, n_spectra=5, ms_level=1):
+        """Create a synthetic MSExperiment for testing."""
+        import pyopenms as oms
+        import numpy as np
+
+        exp = oms.MSExperiment()
+        for i in range(n_spectra):
+            spec = oms.MSSpectrum()
+            spec.setMSLevel(ms_level)
+            spec.setRT(60.0 * i)
+            mzs = np.array([100.0 + j for j in range(10)], dtype=np.float64)
+            intensities = np.array([1000.0 * (j + 1) for j in range(10)], dtype=np.float64)
+            spec.set_peaks([mzs, intensities])
+            exp.addSpectrum(spec)
+        return exp
+
+    def test_summarise_nonempty(self):
+        from spectrum_file_info import summarise_experiment
+
+        exp = self._make_experiment(n_spectra=3)
+        summary = summarise_experiment(exp)
+        assert summary["n_spectra"] == 3
+        assert 1 in summary["ms_levels"]
+
+    def test_summarise_empty(self):
+        from spectrum_file_info import summarise_experiment
+        import pyopenms as oms
+
+        exp = oms.MSExperiment()
+        summary = summarise_experiment(exp)
+        assert summary["n_spectra"] == 0
+
+    def test_rt_range(self):
+        from spectrum_file_info import summarise_experiment
+
+        exp = self._make_experiment(n_spectra=5)
+        summary = summarise_experiment(exp)
+        rt_min, rt_max = summary["rt_range_sec"]
+        assert rt_min == 0.0
+        assert rt_max == 240.0
+
+    def test_mz_range(self):
+        from spectrum_file_info import summarise_experiment
+
+        exp = self._make_experiment(n_spectra=2)
+        summary = summarise_experiment(exp)
+        mz_min, mz_max = summary["mz_range"]
+        assert mz_min == pytest.approx(100.0)
+        assert mz_max == pytest.approx(109.0)
+```
+
+- [ ] **Step 5: Create README.md**
+
+```markdown
+# Mass Spectrum File Info
+
+Summarise the contents of an mzML file: spectra counts by MS level,
+retention time range, m/z range, and TIC statistics.
+
+## Usage
+
+```bash
+python spectrum_file_info.py --input sample.mzML
+python spectrum_file_info.py --input sample.mzML --tic
+```
+```
+
+- [ ] **Step 6: Run ruff and tests**
+
+Run: `ruff check scripts/proteomics/spectrum_file_info/ && PYTHONPATH=scripts/proteomics/spectrum_file_info python -m pytest scripts/proteomics/spectrum_file_info/tests/ -v`
+Expected: Lint clean, 4 tests pass
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/proteomics/spectrum_file_info/
+git commit -m "Migrate spectrum_file_info to per-script directory with synthetic test data"
+```
+
+---
+
+### Task 5: Migrate feature_detection_proteomics to per-script directory
+
+**Files:**
+- Create: `scripts/proteomics/feature_detection_proteomics/feature_detection_proteomics.py`
+- Create: `scripts/proteomics/feature_detection_proteomics/requirements.txt`
+- Create: `scripts/proteomics/feature_detection_proteomics/README.md`
+- Create: `scripts/proteomics/feature_detection_proteomics/tests/conftest.py`
+- Create: `scripts/proteomics/feature_detection_proteomics/tests/test_feature_detection_proteomics.py`
+
+- [ ] **Step 1: Create directory and copy script**
+
+```bash
+mkdir -p scripts/proteomics/feature_detection_proteomics/tests
+git show origin/copilot/add-agentic-scripts-for-proteomics:scripts/proteomics/feature_detection_proteomics.py > scripts/proteomics/feature_detection_proteomics/feature_detection_proteomics.py
+```
+
+- [ ] **Step 2: Create requirements.txt**
+
+```
+pyopenms
+```
+
+- [ ] **Step 3: Create conftest.py** (identical to Task 2 Step 4)
+
+- [ ] **Step 4: Create test file with synthetic data**
+
+This script requires mzML file input. Tests generate a synthetic MSExperiment, write it to a temp mzML file, and run feature detection on it:
+
+```python
+"""Tests for feature_detection_proteomics."""
+
+import os
+import tempfile
+
+import pytest
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestFeatureDetectionProteomics:
+    def test_detect_features_returns_feature_map(self):
+        import pyopenms as oms
+        import numpy as np
+        from feature_detection_proteomics import detect_features
+
+        # Create a minimal synthetic experiment with a few peaks
+        exp = oms.MSExperiment()
+        for i in range(10):
+            spec = oms.MSSpectrum()
+            spec.setMSLevel(1)
+            spec.setRT(60.0 + i * 2.0)
+            mzs = np.array([500.0, 500.5, 501.0], dtype=np.float64)
+            intensities = np.array([1e4, 5e3, 1e3], dtype=np.float64)
+            spec.set_peaks([mzs, intensities])
+            exp.addSpectrum(spec)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            input_path = os.path.join(tmpdir, "test.mzML")
+            output_path = os.path.join(tmpdir, "test.featureXML")
+            oms.MzMLFile().store(input_path, exp)
+
+            fm = detect_features(input_path, output_path)
+            assert isinstance(fm, oms.FeatureMap)
+            assert os.path.exists(output_path)
+```
+
+- [ ] **Step 5: Create README.md**
+
+```markdown
+# Feature Detection for Proteomics
+
+Detect peptide isotope features in centroided LC-MS/MS data using the
+`FeatureFinderCentroided` algorithm. Output is written as a featureXML file.
+
+## Usage
+
+```bash
+python feature_detection_proteomics.py --input sample.mzML
+python feature_detection_proteomics.py --input sample.mzML --output features.featureXML
+```
+```
+
+- [ ] **Step 6: Run ruff and tests**
+
+Run: `ruff check scripts/proteomics/feature_detection_proteomics/ && PYTHONPATH=scripts/proteomics/feature_detection_proteomics python -m pytest scripts/proteomics/feature_detection_proteomics/tests/ -v`
+Expected: Lint clean, 1 test passes
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/proteomics/feature_detection_proteomics/
+git commit -m "Migrate feature_detection_proteomics to per-script directory with synthetic test data"
+```
+
+---
+
+### Task 6: Migrate mass_accuracy_calculator to per-script directory
+
+**Files:**
+- Create: `scripts/metabolomics/mass_accuracy_calculator/mass_accuracy_calculator.py`
+- Create: `scripts/metabolomics/mass_accuracy_calculator/requirements.txt`
+- Create: `scripts/metabolomics/mass_accuracy_calculator/README.md`
+- Create: `scripts/metabolomics/mass_accuracy_calculator/tests/conftest.py`
+- Create: `scripts/metabolomics/mass_accuracy_calculator/tests/test_mass_accuracy_calculator.py`
+
+- [ ] **Step 1: Create directory and copy script**
+
+```bash
+mkdir -p scripts/metabolomics/mass_accuracy_calculator/tests
+git show origin/copilot/add-agentic-scripts-for-proteomics:scripts/metabolomics/mass_accuracy_calculator.py > scripts/metabolomics/mass_accuracy_calculator/mass_accuracy_calculator.py
+```
+
+- [ ] **Step 2: Create requirements.txt**
+
+```
+pyopenms
+```
+
+- [ ] **Step 3: Create conftest.py** (identical to Task 2 Step 4)
+
+- [ ] **Step 4: Create test file**
+
+Extract `TestMassAccuracyCalculator` from the feature branch's `tests/test_metabolomics.py`:
+
+```python
+"""Tests for mass_accuracy_calculator."""
+
+import pytest
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestMassAccuracyCalculator:
+    def test_sequence_theoretical(self):
+        from mass_accuracy_calculator import theoretical_mz_from_sequence
+
+        mz = theoretical_mz_from_sequence("PEPTIDEK", 1)
+        assert 928.0 < mz < 929.0
+
+    def test_formula_theoretical(self):
+        from mass_accuracy_calculator import theoretical_mz_from_formula
+
+        mz = theoretical_mz_from_formula("C6H12O6", 1)
+        assert 181.0 < mz < 182.0
+
+    def test_ppm_zero_error(self):
+        from mass_accuracy_calculator import ppm_error
+
+        assert ppm_error(500.0, 500.0) == 0.0
+
+    def test_ppm_positive_error(self):
+        from mass_accuracy_calculator import ppm_error
+
+        assert ppm_error(500.0, 500.001) > 0
+
+    def test_ppm_negative_error(self):
+        from mass_accuracy_calculator import ppm_error
+
+        assert ppm_error(500.0, 499.999) < 0
+
+    def test_ppm_known_value(self):
+        from mass_accuracy_calculator import ppm_error
+
+        ppm = ppm_error(1000.0, 1000.001)
+        assert abs(ppm - 1.0) < 0.001
+```
+
+- [ ] **Step 5: Create README.md**
+
+```markdown
+# Mass Accuracy Calculator
+
+Calculate mass accuracy (ppm error) between a theoretical value derived
+from a peptide sequence or molecular formula and observed m/z values.
+
+## Usage
+
+```bash
+python mass_accuracy_calculator.py --sequence PEPTIDEK --observed 803.4560
+python mass_accuracy_calculator.py --formula C6H12O6 --observed 181.0709
+python mass_accuracy_calculator.py --sequence ACDEFGHIK --charge 2 --observed 554.2478 554.2480
+```
+```
+
+- [ ] **Step 6: Run ruff and tests**
+
+Run: `ruff check scripts/metabolomics/mass_accuracy_calculator/ && PYTHONPATH=scripts/metabolomics/mass_accuracy_calculator python -m pytest scripts/metabolomics/mass_accuracy_calculator/tests/ -v`
+Expected: Lint clean, 6 tests pass
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/metabolomics/mass_accuracy_calculator/
+git commit -m "Migrate mass_accuracy_calculator to per-script directory structure"
+```
+
+---
+
+### Task 7: Migrate isotope_pattern_matcher to per-script directory
+
+**Files:**
+- Create: `scripts/metabolomics/isotope_pattern_matcher/isotope_pattern_matcher.py`
+- Create: `scripts/metabolomics/isotope_pattern_matcher/requirements.txt`
+- Create: `scripts/metabolomics/isotope_pattern_matcher/README.md`
+- Create: `scripts/metabolomics/isotope_pattern_matcher/tests/conftest.py`
+- Create: `scripts/metabolomics/isotope_pattern_matcher/tests/test_isotope_pattern_matcher.py`
+
+- [ ] **Step 1: Create directory and copy script**
+
+```bash
+mkdir -p scripts/metabolomics/isotope_pattern_matcher/tests
+git show origin/copilot/add-agentic-scripts-for-proteomics:scripts/metabolomics/isotope_pattern_matcher.py > scripts/metabolomics/isotope_pattern_matcher/isotope_pattern_matcher.py
+```
+
+- [ ] **Step 2: Create requirements.txt**
+
+```
+pyopenms
+```
+
+- [ ] **Step 3: Create conftest.py** (identical to Task 2 Step 4)
+
+- [ ] **Step 4: Create test file**
+
+Extract `TestIsotopePatternMatcher` from the feature branch's `tests/test_metabolomics.py`:
+
+```python
+"""Tests for isotope_pattern_matcher."""
+
+import pytest
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestIsotopePatternMatcher:
+    def test_glucose_pattern(self):
+        from isotope_pattern_matcher import get_isotope_distribution
+
+        dist = get_isotope_distribution("C6H12O6", max_isotopes=3)
+        assert len(dist) == 3
+        assert dist[0][1] == pytest.approx(100.0)
+        assert dist[1][1] < dist[0][1]
+
+    def test_pattern_mz_ordering(self):
+        from isotope_pattern_matcher import get_isotope_distribution
+
+        dist = get_isotope_distribution("C12H22O11", max_isotopes=4)
+        mzs = [mz for mz, _ in dist]
+        assert mzs == sorted(mzs)
+
+    def test_cosine_similarity_perfect(self):
+        from isotope_pattern_matcher import cosine_similarity
+
+        peaks = [(100.0, 50.0), (101.0, 20.0), (102.0, 5.0)]
+        sim = cosine_similarity(peaks, peaks, mz_tolerance=0.01)
+        assert abs(sim - 1.0) < 1e-9
+
+    def test_cosine_similarity_no_overlap(self):
+        from isotope_pattern_matcher import cosine_similarity
+
+        theoretical = [(100.0, 50.0), (101.0, 20.0)]
+        observed = [(200.0, 50.0), (201.0, 20.0)]
+        sim = cosine_similarity(theoretical, observed, mz_tolerance=0.01)
+        assert sim == 0.0
+
+    def test_parse_peaks(self):
+        from isotope_pattern_matcher import parse_peaks
+
+        result = parse_peaks(["181.0709,100.0", "182.0742,6.7"])
+        assert len(result) == 2
+        assert result[0] == (181.0709, 100.0)
+
+    def test_parse_peaks_invalid(self):
+        from isotope_pattern_matcher import parse_peaks
+
+        with pytest.raises(ValueError):
+            parse_peaks(["181.0709"])
+```
+
+- [ ] **Step 5: Create README.md**
+
+```markdown
+# Isotope Pattern Generator & Matcher
+
+Generate theoretical isotope distributions for any molecular formula and
+optionally compute a cosine similarity score against observed peaks.
+
+## Usage
+
+```bash
+python isotope_pattern_matcher.py --formula C6H12O6
+python isotope_pattern_matcher.py --formula C6H12O6 --peaks 181.0709,100.0 182.0742,6.7 183.0775,0.4
+```
+```
+
+- [ ] **Step 6: Run ruff and tests**
+
+Run: `ruff check scripts/metabolomics/isotope_pattern_matcher/ && PYTHONPATH=scripts/metabolomics/isotope_pattern_matcher python -m pytest scripts/metabolomics/isotope_pattern_matcher/tests/ -v`
+Expected: Lint clean, 6 tests pass
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/metabolomics/isotope_pattern_matcher/
+git commit -m "Migrate isotope_pattern_matcher to per-script directory structure"
+```
+
+---
+
+### Task 8: Migrate metabolite_feature_detection to per-script directory
+
+**Files:**
+- Create: `scripts/metabolomics/metabolite_feature_detection/metabolite_feature_detection.py`
+- Create: `scripts/metabolomics/metabolite_feature_detection/requirements.txt`
+- Create: `scripts/metabolomics/metabolite_feature_detection/README.md`
+- Create: `scripts/metabolomics/metabolite_feature_detection/tests/conftest.py`
+- Create: `scripts/metabolomics/metabolite_feature_detection/tests/test_metabolite_feature_detection.py`
+
+- [ ] **Step 1: Create directory and copy script**
+
+```bash
+mkdir -p scripts/metabolomics/metabolite_feature_detection/tests
+git show origin/copilot/add-agentic-scripts-for-proteomics:scripts/metabolomics/metabolite_feature_detection.py > scripts/metabolomics/metabolite_feature_detection/metabolite_feature_detection.py
+```
+
+- [ ] **Step 2: Create requirements.txt**
+
+```
+pyopenms
+```
+
+- [ ] **Step 3: Create conftest.py** (identical to Task 2 Step 4)
+
+- [ ] **Step 4: Create test file with synthetic data**
+
+Similar to Task 5, generate synthetic MSExperiment data and write to temp mzML:
+
+```python
+"""Tests for metabolite_feature_detection."""
+
+import os
+import tempfile
+
+import pytest
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestMetaboliteFeatureDetection:
+    def test_detect_features_returns_feature_map(self):
+        import pyopenms as oms
+        import numpy as np
+        from metabolite_feature_detection import detect_metabolite_features
+
+        # Create a minimal synthetic experiment
+        exp = oms.MSExperiment()
+        for i in range(20):
+            spec = oms.MSSpectrum()
+            spec.setMSLevel(1)
+            spec.setRT(30.0 + i * 3.0)
+            mzs = np.array([180.063, 181.066, 182.070], dtype=np.float64)
+            intensities = np.array([1e5, 1e4, 1e3], dtype=np.float64)
+            spec.set_peaks([mzs, intensities])
+            exp.addSpectrum(spec)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            input_path = os.path.join(tmpdir, "test.mzML")
+            output_path = os.path.join(tmpdir, "test.featureXML")
+            oms.MzMLFile().store(input_path, exp)
+
+            fm = detect_metabolite_features(input_path, output_path, noise_threshold=1e2)
+            assert isinstance(fm, oms.FeatureMap)
+            assert os.path.exists(output_path)
+```
+
+- [ ] **Step 5: Create README.md**
+
+```markdown
+# Metabolite Feature Detection
+
+Detect small-molecule features in centroided LC-MS data using the
+`FeatureFinderMetabo` pipeline. Output is written as a featureXML file.
+
+## Usage
+
+```bash
+python metabolite_feature_detection.py --input sample.mzML
+python metabolite_feature_detection.py --input sample.mzML --output features.featureXML --noise 1e5
+```
+```
+
+- [ ] **Step 6: Run ruff and tests**
+
+Run: `ruff check scripts/metabolomics/metabolite_feature_detection/ && PYTHONPATH=scripts/metabolomics/metabolite_feature_detection python -m pytest scripts/metabolomics/metabolite_feature_detection/tests/ -v`
+Expected: Lint clean, 1 test passes
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/metabolomics/metabolite_feature_detection/
+git commit -m "Migrate metabolite_feature_detection to per-script directory with synthetic test data"
+```
+
+---
+
+### Task 9: Create validate-script Claude Code skill
+
+**Files:**
+- Create: `.claude/skills/validate-script.md`
+
+- [ ] **Step 1: Create skill directory and file**
+
+```bash
+mkdir -p .claude/skills
+```
+
+Then create `.claude/skills/validate-script.md`:
+
+```markdown
+---
+name: validate-script
+description: Validate a pyopenms script in an isolated venv — runs ruff lint and pytest
+---
+
+# Validate Script
+
+Validate any script in the agentomics repo by running ruff and pytest in a fresh isolated venv.
+
+## Steps (follow exactly — rigid skill)
+
+1. **Identify the script directory.** If the user provided a path, use it. Otherwise, ask which script to validate. The path should be `scripts/<domain>/<tool_name>/`.
+
+2. **Verify the directory structure.** Confirm it contains:
+   - `<tool_name>.py`
+   - `requirements.txt`
+   - `tests/` directory with at least one `test_*.py` file
+
+3. **Create a temporary venv and run validation.** Execute these commands:
+
+   ```bash
+   SCRIPT_DIR=<path-to-script-directory>
+   VENV_DIR=$(mktemp -d)
+   python -m venv "$VENV_DIR"
+   "$VENV_DIR/bin/python" -m pip install -r "$SCRIPT_DIR/requirements.txt"
+   "$VENV_DIR/bin/python" -m pip install pytest ruff
+   "$VENV_DIR/bin/python" -m ruff check "$SCRIPT_DIR/"
+   PYTHONPATH="$SCRIPT_DIR" "$VENV_DIR/bin/python" -m pytest "$SCRIPT_DIR/tests/" -v
+   rm -rf "$VENV_DIR"
+   ```
+
+4. **Report results.** Summarize pass/fail for both ruff and pytest. If either fails, show the relevant error output so the user can fix it.
+
+5. **Clean up.** Ensure the temporary venv is removed even if validation fails.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .claude/skills/validate-script.md
+git commit -m "Add validate-script Claude Code skill for isolated venv validation"
+```
+
+---
+
+### Task 10: Create contribute-script Claude Code skill
+
+**Files:**
+- Create: `.claude/skills/contribute-script.md`
+
+- [ ] **Step 1: Create skill file**
+
+```markdown
+---
+name: contribute-script
+description: Guide creation of a new pyopenms script contribution — scaffolding through validation
+---
+
+# Contribute Script
+
+Guide an AI agent through creating a new pyopenms CLI tool for the agentomics repo. Follow every step — this is a rigid skill.
+
+## Prerequisites
+
+Read `AGENTS.md` in the repo root for the full contributor guide and code patterns.
+
+## Steps
+
+### 1. Understand the tool
+
+Ask the user:
+- What does this tool do? What pyopenms functionality does it use?
+- What gap in OpenMS/pyopenms does it fill?
+
+### 2. Determine the domain
+
+Ask: Is this a **proteomics** or **metabolomics** tool? If neither fits, discuss whether a new domain directory is needed.
+
+### 3. Pick a name
+
+Choose a descriptive snake_case name for the tool (e.g. `peptide_mass_calculator`, `isotope_pattern_matcher`). Confirm with the user.
+
+### 4. Create a feature branch
+
+```bash
+git checkout -b add/<tool_name>
+```
+
+### 5. Scaffold the directory
+
+```bash
+mkdir -p scripts/<domain>/<tool_name>/tests
+```
+
+Create these files:
+
+**`requirements.txt`:**
+```
+pyopenms
+```
+Add any additional dependencies the script needs (one per line, no version pins).
+
+**`tests/conftest.py`:**
+```python
+import sys
+import os
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
+```
+
+### 6. Write the script
+
+Create `scripts/<domain>/<tool_name>/<tool_name>.py` following these patterns:
+
+- Module-level docstring with description, supported features, and CLI usage examples
+- pyopenms import guard:
+  ```python
+  try:
+      import pyopenms as oms
+  except ImportError:
+      sys.exit("pyopenms is required. Install it with:  pip install pyopenms")
+  ```
+- `PROTON = 1.007276` constant where mass-to-charge calculations are needed
+- Importable functions as the primary interface (with type hints and numpy-style docstrings)
+- `main()` function with argparse CLI
+- `if __name__ == "__main__": main()` guard
+
+### 7. Write tests
+
+Create `scripts/<domain>/<tool_name>/tests/test_<tool_name>.py`:
+
+- Import `requires_pyopenms` from conftest
+- Decorate test classes with `@requires_pyopenms`
+- Use `from <tool_name> import <function>` inside test methods
+- For file-I/O scripts: generate synthetic data using pyopenms objects in test fixtures, write to `tempfile.TemporaryDirectory()`
+- Cover: basic functionality, edge cases, key parameters
+
+### 8. Write README
+
+Create `scripts/<domain>/<tool_name>/README.md` with a brief description and CLI usage examples.
+
+### 9. Validate
+
+Invoke the `validate-script` skill on the new script directory. Both ruff and pytest must pass.
+
+### 10. Commit
+
+```bash
+git add scripts/<domain>/<tool_name>/
+git commit -m "Add <tool_name>: <brief description>"
+```
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add .claude/skills/contribute-script.md
+git commit -m "Add contribute-script Claude Code skill for guided new tool creation"
+```
+
+---
+
+### Task 11: Create AGENTS.md
+
+**Files:**
+- Create: `AGENTS.md`
+
+- [ ] **Step 1: Create AGENTS.md**
+
+```markdown
+# AGENTS.md — AI Contributor Guide
+
+This file instructs AI agents (Claude Code, GitHub Copilot, Cursor, Gemini, etc.) how to contribute scripts to the agentomics repository.
+
+## Project Purpose
+
+Agentomics is a collection of standalone CLI tools built with [pyopenms](https://pyopenms.readthedocs.io/) for proteomics and metabolomics workflows. These tools fill gaps not yet covered by OpenMS/pyopenms. All code in this repo is written by AI agents.
+
+## Contribution Requirements
+
+Every script must be a **self-contained directory** under `scripts/<domain>/<tool_name>/`:
+
+```
+scripts/<domain>/<tool_name>/
+├── <tool_name>.py        # The tool itself
+├── requirements.txt      # pyopenms + any script-specific deps (no version pins)
+├── README.md             # Brief description + CLI usage examples
+└── tests/
+    ├── conftest.py       # Shared test config (see below)
+    └── test_<tool_name>.py
+```
+
+### Rules
+
+- `<domain>` is `proteomics` or `metabolomics`
+- `requirements.txt` always includes `pyopenms` with no version pin — builds against latest
+- No cross-script imports — each script is fully independent
+- No `__init__.py` files — these are NOT Python packages
+- No scripts that duplicate functionality already in OpenMS/pyopenms
+
+## Code Patterns
+
+### Script structure
+
+Every script must have:
+
+1. **Module docstring** with description, features, and usage examples
+2. **pyopenms import guard:**
+   ```python
+   import sys
+   try:
+       import pyopenms as oms
+   except ImportError:
+       sys.exit("pyopenms is required. Install it with:  pip install pyopenms")
+   ```
+3. **Importable functions** as the primary interface (with type hints and numpy-style docstrings)
+4. **`main()` function** with argparse CLI
+5. **`if __name__ == "__main__": main()`** guard
+6. **`PROTON = 1.007276`** constant where mass-to-charge calculations are needed
+
+### Test structure
+
+Every `tests/conftest.py` must contain:
+
+```python
+import sys
+import os
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
+```
+
+Test files:
+- Decorate test classes with `@requires_pyopenms` from conftest
+- Import script functions inside test methods: `from <tool_name> import <function>`
+- For file-I/O scripts: generate synthetic data using pyopenms objects, write to `tempfile.TemporaryDirectory()`
+
+## Validation
+
+Every script must pass validation in an **isolated venv** before it can be merged. Run these commands from the repo root:
+
+```bash
+SCRIPT_DIR=scripts/<domain>/<tool_name>
+VENV_DIR=$(mktemp -d)
+python -m venv "$VENV_DIR"
+"$VENV_DIR/bin/python" -m pip install -r "$SCRIPT_DIR/requirements.txt"
+"$VENV_DIR/bin/python" -m pip install pytest ruff
+"$VENV_DIR/bin/python" -m ruff check "$SCRIPT_DIR/"
+PYTHONPATH="$SCRIPT_DIR" "$VENV_DIR/bin/python" -m pytest "$SCRIPT_DIR/tests/" -v
+rm -rf "$VENV_DIR"
+```
+
+Both ruff and pytest must pass with zero errors.
+
+## Linting
+
+Ruff is configured in `ruff.toml` at the repo root:
+- Line length: 120
+- Rules: E (pycodestyle errors), F (pyflakes), W (pycodestyle warnings), I (isort)
+
+## What NOT to Do
+
+- Do not add cross-script imports
+- Do not add dependencies to a shared/root requirements file
+- Do not create scripts that duplicate existing pyopenms CLI tools or OpenMS TOPP tools
+- Do not pin pyopenms to a specific version
+- Do not add `__init__.py` files
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add AGENTS.md
+git commit -m "Add AGENTS.md platform-agnostic AI contributor guide"
+```
+
+---
+
+### Task 12: Create GitHub Actions CI workflow
+
+**Files:**
+- Create: `.github/workflows/validate.yml`
+
+- [ ] **Step 1: Create workflow file**
+
+```yaml
+name: Validate Scripts
+
+on:
+  pull_request:
+    paths:
+      - 'scripts/**'
+
+jobs:
+  detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.detect.outputs.matrix }}
+      has_changes: ${{ steps.detect.outputs.has_changes }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - id: detect
+        name: Detect changed script directories
+        run: |
+          # Note: github.base_ref is only available on pull_request events
+          # Find all script directories that changed in this PR
+          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- 'scripts/' \
+            | grep -oP 'scripts/[^/]+/[^/]+/' \
+            | sort -u \
+            | jq -R -s -c 'split("\n") | map(select(length > 0))')
+
+          if [ "$CHANGED" = "[]" ] || [ -z "$CHANGED" ]; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            echo "matrix=[]" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+            echo "matrix=$CHANGED" >> "$GITHUB_OUTPUT"
+          fi
+
+  validate:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.has_changes == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        script_dir: ${{ fromJson(needs.detect-changes.outputs.matrix) }}
+    name: Validate ${{ matrix.script_dir }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Create venv and install dependencies
+        run: |
+          python -m venv /tmp/validate_venv
+          /tmp/validate_venv/bin/python -m pip install -r ${{ matrix.script_dir }}requirements.txt
+          /tmp/validate_venv/bin/python -m pip install pytest ruff
+
+      - name: Lint with ruff
+        run: |
+          /tmp/validate_venv/bin/python -m ruff check ${{ matrix.script_dir }}
+
+      - name: Run tests
+        run: |
+          PYTHONPATH=${{ matrix.script_dir }} /tmp/validate_venv/bin/python -m pytest ${{ matrix.script_dir }}tests/ -v
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+mkdir -p .github/workflows
+git add .github/workflows/validate.yml
+git commit -m "Add GitHub Actions CI workflow for per-script isolated validation"
+```
+
+---
+
+### Task 13: Update CLAUDE.md and README.md
+
+**Files:**
+- Modify: `CLAUDE.md`
+- Modify: `README.md`
+
+- [ ] **Step 1: Update CLAUDE.md**
+
+Replace the current content with updated version reflecting the new structure:
+
+```markdown
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Purpose
+
+Agentomics is a collection of standalone CLI tools built with [pyopenms](https://pyopenms.readthedocs.io/) for proteomics and metabolomics workflows. These tools fill gaps not yet covered by OpenMS/pyopenms. All code in this repo is agentic-only development — written entirely by AI agents.
+
+## Commands
+
+```bash
+# Install dependencies for a specific script
+pip install -r scripts/proteomics/peptide_mass_calculator/requirements.txt
+
+# Lint a specific script
+ruff check scripts/proteomics/peptide_mass_calculator/
+
+# Run tests for a specific script
+PYTHONPATH=scripts/proteomics/peptide_mass_calculator python -m pytest scripts/proteomics/peptide_mass_calculator/tests/ -v
+
+# Lint all scripts
+ruff check scripts/
+
+# Run all tests (requires pyopenms installed)
+find scripts -name 'tests' -type d -exec sh -c 'PYTHONPATH=$(dirname {}) python -m pytest {} -v' \;
+```
+
+## Architecture
+
+### Per-Script Directory Structure
+
+Each script is a self-contained directory under `scripts/<domain>/<tool_name>/`:
+
+```
+scripts/<domain>/<tool_name>/
+├── <tool_name>.py        # The tool (importable functions + argparse CLI)
+├── requirements.txt      # pyopenms + script-specific deps
+├── README.md             # Usage examples
+└── tests/
+    ├── conftest.py       # requires_pyopenms marker + sys.path setup
+    └── test_<tool_name>.py
+```
+
+Domains: `proteomics/`, `metabolomics/`
+
+### Key Patterns
+
+- pyopenms import wrapped in try/except with user-friendly error message
+- Mass-to-charge: `(mass + charge * PROTON) / charge` with `PROTON = 1.007276`
+- Every script has dual interface: importable functions + argparse CLI + `__main__` guard
+- Tests use `@requires_pyopenms` skip marker from conftest.py
+- File-I/O scripts use synthetic test data generated with pyopenms objects
+
+## Contributing
+
+See `AGENTS.md` for the full AI contributor guide. Two Claude Code skills are available:
+
+- **`contribute-script`** — guided workflow for adding a new script
+- **`validate-script`** — validate any script in an isolated venv (ruff + pytest)
+```
+
+- [ ] **Step 2: Update README.md**
+
+```markdown
+# agentomics
+
+A repository of agentic-created tools using [pyopenms](https://pyopenms.readthedocs.io/) for proteomics and metabolomics.
+
+All code in this repo is written by AI agents. See [AGENTS.md](AGENTS.md) for the contributor guide.
+
+## Requirements
+
+```bash
+pip install pyopenms
+```
+
+## Scripts
+
+### Proteomics
+
+| Script | Description |
+|--------|-------------|
+| [`peptide_mass_calculator`](scripts/proteomics/peptide_mass_calculator/) | Monoisotopic/average masses and b/y fragment ions for peptide sequences |
+| [`protein_digest`](scripts/proteomics/protein_digest/) | In-silico enzymatic protein digestion |
+| [`spectrum_file_info`](scripts/proteomics/spectrum_file_info/) | Summary statistics for mzML files |
+| [`feature_detection_proteomics`](scripts/proteomics/feature_detection_proteomics/) | Peptide feature detection from LC-MS/MS data |
+
+### Metabolomics
+
+| Script | Description |
+|--------|-------------|
+| [`mass_accuracy_calculator`](scripts/metabolomics/mass_accuracy_calculator/) | m/z mass accuracy (ppm error) for sequences or formulas |
+| [`isotope_pattern_matcher`](scripts/metabolomics/isotope_pattern_matcher/) | Theoretical isotope distributions and cosine similarity scoring |
+| [`metabolite_feature_detection`](scripts/metabolomics/metabolite_feature_detection/) | Metabolite feature detection from LC-MS data |
+
+## Validation
+
+Each script is validated in an isolated venv. See [AGENTS.md](AGENTS.md) for validation commands.
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE).
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CLAUDE.md README.md
+git commit -m "Update CLAUDE.md and README.md for per-script directory structure"
+```
+
+---
+
+### Task 14: Final validation — run all scripts through isolated validation
+
+- [ ] **Step 1: Validate all 7 scripts**
+
+Run the validation pipeline on each script directory. For each, execute:
+
+```bash
+SCRIPT_DIR=scripts/<domain>/<tool_name>
+VENV_DIR=$(mktemp -d)
+python -m venv "$VENV_DIR"
+"$VENV_DIR/bin/python" -m pip install -r "$SCRIPT_DIR/requirements.txt"
+"$VENV_DIR/bin/python" -m pip install pytest ruff
+"$VENV_DIR/bin/python" -m ruff check "$SCRIPT_DIR/"
+PYTHONPATH="$SCRIPT_DIR" "$VENV_DIR/bin/python" -m pytest "$SCRIPT_DIR/tests/" -v
+rm -rf "$VENV_DIR"
+```
+
+Run for each:
+1. `scripts/proteomics/peptide_mass_calculator`
+2. `scripts/proteomics/protein_digest`
+3. `scripts/proteomics/spectrum_file_info`
+4. `scripts/proteomics/feature_detection_proteomics`
+5. `scripts/metabolomics/mass_accuracy_calculator`
+6. `scripts/metabolomics/isotope_pattern_matcher`
+7. `scripts/metabolomics/metabolite_feature_detection`
+
+Expected: All 7 pass ruff lint and all tests pass (or skip with `pyopenms not installed`).
+
+- [ ] **Step 2: Fix any failures and recommit**
+
+If any script fails lint or tests, fix the issue and create a new commit with the fix.
+
+- [ ] **Step 3: Final commit if any fixes were needed**
+
+```bash
+git add -u
+git commit -m "Fix validation issues found during final check"
+```

From 5a38336e59c3f76c4a383e40482f65bb396ca0a0 Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:23:28 +0100
Subject: [PATCH 04/16] Add ruff.toml with E/F/W/I rule set, line-length 120

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ruff.toml | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 ruff.toml

diff --git a/ruff.toml b/ruff.toml
new file mode 100644
index 0000000..b73353b
--- /dev/null
+++ b/ruff.toml
@@ -0,0 +1,4 @@
+line-length = 120
+
+[lint]
+select = ["E", "F", "W", "I"]

From 1b94ea99d1fc6bda09722770652525b7cf051161 Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:24:54 +0100
Subject: [PATCH 05/16] Migrate peptide_mass_calculator to per-script directory
 structure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../peptide_mass_calculator/README.md         |  12 ++
 .../peptide_mass_calculator.py                | 133 ++++++++++++++++++
 .../peptide_mass_calculator/requirements.txt  |   1 +
 .../peptide_mass_calculator/tests/conftest.py |  15 ++
 .../tests/test_peptide_mass_calculator.py     |  44 ++++++
 5 files changed, 205 insertions(+)
 create mode 100644 scripts/proteomics/peptide_mass_calculator/README.md
 create mode 100644 scripts/proteomics/peptide_mass_calculator/peptide_mass_calculator.py
 create mode 100644 scripts/proteomics/peptide_mass_calculator/requirements.txt
 create mode 100644 scripts/proteomics/peptide_mass_calculator/tests/conftest.py
 create mode 100644 scripts/proteomics/peptide_mass_calculator/tests/test_peptide_mass_calculator.py

diff --git a/scripts/proteomics/peptide_mass_calculator/README.md b/scripts/proteomics/peptide_mass_calculator/README.md
new file mode 100644
index 0000000..5cfcaf0
--- /dev/null
+++ b/scripts/proteomics/peptide_mass_calculator/README.md
@@ -0,0 +1,12 @@
+# Peptide Mass Calculator
+
+Calculate monoisotopic and average masses for peptide sequences, and compute
+b-ion / y-ion fragment series.
+
+## Usage
+
+```bash
+python peptide_mass_calculator.py --sequence PEPTIDEK
+python peptide_mass_calculator.py --sequence PEPTM[147]IDEK --charge 2
+python peptide_mass_calculator.py --sequence ACDEFGHIK --fragments
+```
diff --git a/scripts/proteomics/peptide_mass_calculator/peptide_mass_calculator.py b/scripts/proteomics/peptide_mass_calculator/peptide_mass_calculator.py
new file mode 100644
index 0000000..8bc4893
--- /dev/null
+++ b/scripts/proteomics/peptide_mass_calculator/peptide_mass_calculator.py
@@ -0,0 +1,133 @@
+"""
+Peptide Mass Calculator
+=======================
+Calculate monoisotopic and average masses for peptide sequences using pyopenms.
+
+Supports:
+- Plain amino acid sequences (e.g. "PEPTIDEK")
+- Modified sequences in bracket notation (e.g. "PEPTM[147]IDEK")
+- Fragment ion mass series (b-ions and y-ions)
+- Multiple charge states
+
+Usage
+-----
+    python peptide_mass_calculator.py --sequence PEPTIDEK
+    python peptide_mass_calculator.py --sequence PEPTM[147]IDEK --charge 2
+    python peptide_mass_calculator.py --sequence ACDEFGHIK --fragments
+"""
+
+import argparse
+import sys
+
+try:
+    import pyopenms as oms
+except ImportError:
+    sys.exit(
+        "pyopenms is required. Install it with:  pip install pyopenms"
+    )
+
+PROTON = 1.007276
+
+
+def peptide_masses(sequence: str, charge: int = 1) -> dict:
+    """Return monoisotopic and average masses for the given peptide sequence.
+
+    Parameters
+    ----------
+    sequence:
+        Amino acid sequence, optionally with bracket-enclosed modifications,
+        e.g. ``"PEPTM[147]IDEK"``.
+    charge:
+        Desired charge state for m/z calculation (default 1).
+
+    Returns
+    -------
+    dict
+        Dictionary with keys ``monoisotopic_mass``, ``average_mass``,
+        ``mz_monoisotopic``, and ``mz_average``.
+    """
+    aa_seq = oms.AASequence.fromString(sequence)
+    mono = aa_seq.getMonoWeight()
+    avg = aa_seq.getAverageWeight()
+    return {
+        "sequence": sequence,
+        "charge": charge,
+        "monoisotopic_mass": mono,
+        "average_mass": avg,
+        "mz_monoisotopic": (mono + charge * PROTON) / charge,
+        "mz_average": (avg + charge * PROTON) / charge,
+    }
+
+
+def fragment_ions(sequence: str) -> dict:
+    """Compute singly charged b-ion and y-ion series for a peptide.
+
+    Parameters
+    ----------
+    sequence:
+        Plain or modified amino acid sequence.
+
+    Returns
+    -------
+    dict
+        Dictionary with keys ``b_ions`` and ``y_ions``, each a list of
+        ``(index, mass)`` tuples.
+    """
+    aa_seq = oms.AASequence.fromString(sequence)
+    n = aa_seq.size()
+
+    b_ions = []
+    for i in range(1, n):
+        prefix = aa_seq.getPrefix(i)
+        b_ions.append((i, prefix.getMonoWeight(oms.Residue.ResidueType.BIon, 1)))
+
+    y_ions = []
+    for i in range(1, n):
+        suffix = aa_seq.getSuffix(i)
+        y_ions.append((i, suffix.getMonoWeight(oms.Residue.ResidueType.YIon, 1)))
+
+    return {"b_ions": b_ions, "y_ions": y_ions}
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Calculate peptide/fragment masses using pyopenms."
+    )
+    parser.add_argument(
+        "--sequence",
+        required=True,
+        help="Amino acid sequence (e.g. PEPTIDEK or PEPTM[147]IDEK)",
+    )
+    parser.add_argument(
+        "--charge",
+        type=int,
+        default=1,
+        help="Charge state for m/z calculation (default: 1)",
+    )
+    parser.add_argument(
+        "--fragments",
+        action="store_true",
+        help="Also compute b-ion and y-ion series",
+    )
+    args = parser.parse_args()
+
+    info = peptide_masses(args.sequence, args.charge)
+    print(f"Sequence          : {info['sequence']}")
+    print(f"Charge            : {info['charge']}+")
+    print(f"Monoisotopic mass : {info['monoisotopic_mass']:.6f} Da")
+    print(f"Average mass      : {info['average_mass']:.6f} Da")
+    print(f"m/z (mono)        : {info['mz_monoisotopic']:.6f}")
+    print(f"m/z (avg)         : {info['mz_average']:.6f}")
+
+    if args.fragments:
+        ions = fragment_ions(args.sequence)
+        print("\n--- b-ions ---")
+        for idx, mass in ions["b_ions"]:
+            print(f"  b{idx:>2}  {mass:.6f} Da")
+        print("\n--- y-ions ---")
+        for idx, mass in ions["y_ions"]:
+            print(f"  y{idx:>2}  {mass:.6f} Da")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/proteomics/peptide_mass_calculator/requirements.txt b/scripts/proteomics/peptide_mass_calculator/requirements.txt
new file mode 100644
index 0000000..7ce28ec
--- /dev/null
+++ b/scripts/proteomics/peptide_mass_calculator/requirements.txt
@@ -0,0 +1 @@
+pyopenms
diff --git a/scripts/proteomics/peptide_mass_calculator/tests/conftest.py b/scripts/proteomics/peptide_mass_calculator/tests/conftest.py
new file mode 100644
index 0000000..1a21ede
--- /dev/null
+++ b/scripts/proteomics/peptide_mass_calculator/tests/conftest.py
@@ -0,0 +1,15 @@
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
diff --git a/scripts/proteomics/peptide_mass_calculator/tests/test_peptide_mass_calculator.py b/scripts/proteomics/peptide_mass_calculator/tests/test_peptide_mass_calculator.py
new file mode 100644
index 0000000..a56b16e
--- /dev/null
+++ b/scripts/proteomics/peptide_mass_calculator/tests/test_peptide_mass_calculator.py
@@ -0,0 +1,44 @@
+"""Tests for peptide_mass_calculator."""
+
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestPeptideMassCalculator:
+    def test_basic_mass(self):
+        from peptide_mass_calculator import peptide_masses
+
+        result = peptide_masses("PEPTIDEK")
+        assert result["sequence"] == "PEPTIDEK"
+        assert result["charge"] == 1
+        assert 927.0 < result["monoisotopic_mass"] < 928.0
+        assert result["mz_monoisotopic"] > result["monoisotopic_mass"]
+
+    def test_charge_state(self):
+        from peptide_mass_calculator import peptide_masses
+
+        r1 = peptide_masses("PEPTIDEK", charge=1)
+        r2 = peptide_masses("PEPTIDEK", charge=2)
+        assert r2["mz_monoisotopic"] < r1["mz_monoisotopic"]
+
+    def test_fragment_ions(self):
+        from peptide_mass_calculator import fragment_ions
+
+        ions = fragment_ions("PEPTIDEK")
+        seq_len = len("PEPTIDEK")
+        assert len(ions["b_ions"]) == seq_len - 1
+        assert len(ions["y_ions"]) == seq_len - 1
+
+    def test_modified_sequence(self):
+        from peptide_mass_calculator import peptide_masses
+
+        result = peptide_masses("PEPTM[147]IDEK")
+        assert result["monoisotopic_mass"] > 0
+
+    def test_mz_formula(self):
+        from peptide_mass_calculator import PROTON, peptide_masses
+
+        r = peptide_masses("PEPTIDEK", charge=2)
+        expected = (r["monoisotopic_mass"] + 2 * PROTON) / 2
+        assert abs(r["mz_monoisotopic"] - expected) < 1e-6

From bd44bf735509abc34ab764c1bf1d42001b7a2dfb Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:26:55 +0100
Subject: [PATCH 06/16] Migrate protein_digest to per-script directory
 structure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 scripts/proteomics/protein_digest/README.md   |  12 ++
 .../protein_digest/protein_digest.py          | 163 ++++++++++++++++++
 .../protein_digest/requirements.txt           |   1 +
 .../protein_digest/tests/conftest.py          |  15 ++
 .../tests/test_protein_digest.py              |  47 +++++
 5 files changed, 238 insertions(+)
 create mode 100644 scripts/proteomics/protein_digest/README.md
 create mode 100644 scripts/proteomics/protein_digest/protein_digest.py
 create mode 100644 scripts/proteomics/protein_digest/requirements.txt
 create mode 100644 scripts/proteomics/protein_digest/tests/conftest.py
 create mode 100644 scripts/proteomics/protein_digest/tests/test_protein_digest.py

diff --git a/scripts/proteomics/protein_digest/README.md b/scripts/proteomics/protein_digest/README.md
new file mode 100644
index 0000000..c05870e
--- /dev/null
+++ b/scripts/proteomics/protein_digest/README.md
@@ -0,0 +1,12 @@
+# Protein In-Silico Digest
+
+Perform in-silico enzymatic digestion of a protein sequence and report
+the resulting peptides with their masses.
+
+## Usage
+
+```bash
+python protein_digest.py --sequence MKVLWAALLVTFLAGCQAK... --enzyme Trypsin
+python protein_digest.py --sequence MKVLWAALLVTFLAGCQAK... --enzyme Lys-C --missed-cleavages 2
+python protein_digest.py --list-enzymes
+```
diff --git a/scripts/proteomics/protein_digest/protein_digest.py b/scripts/proteomics/protein_digest/protein_digest.py
new file mode 100644
index 0000000..417c260
--- /dev/null
+++ b/scripts/proteomics/protein_digest/protein_digest.py
@@ -0,0 +1,163 @@
+"""
+Protein In-Silico Digest
+========================
+Digest a protein sequence with a chosen enzyme and report the resulting
+peptides together with their masses using pyopenms.
+
+Supported enzymes (examples): Trypsin, Lys-C, Arg-C, Asp-N, Glu-C, Chymotrypsin
+For the full list call:  python protein_digest.py --list-enzymes
+
+Usage
+-----
+    python protein_digest.py --sequence MKVLWAALLVTFLAGCQAKVEQAVETEPEPELRQQTEWQSGQRWELAL \
+        --enzyme Trypsin
+    python protein_digest.py --sequence MKVLWAALLVTFLAGC --enzyme Lys-C --missed-cleavages 2
+"""
+
+import argparse
+import sys
+
+try:
+    import pyopenms as oms
+except ImportError:
+    sys.exit(
+        "pyopenms is required. Install it with:  pip install pyopenms"
+    )
+
+
+def list_enzymes() -> list:
+    """Return all enzyme names registered in the pyopenms ProteaseDB."""
+    db = oms.ProteaseDB()
+    raw_names = []
+    db.getAllNames(raw_names)
+    return sorted(
+        n.decode() if isinstance(n, bytes) else n for n in raw_names
+    )
+
+
+def digest_protein(
+    sequence: str,
+    enzyme: str = "Trypsin",
+    missed_cleavages: int = 0,
+    min_length: int = 6,
+    max_length: int = 40,
+) -> list:
+    """Digest a protein sequence in silico.
+
+    Parameters
+    ----------
+    sequence:
+        Single-letter amino acid sequence of the protein.
+    enzyme:
+        Enzyme name as known to pyopenms ProteaseDB (default: ``"Trypsin"``).
+    missed_cleavages:
+        Maximum number of missed cleavages allowed (default: 0).
+    min_length:
+        Minimum peptide length to include (default: 6).
+    max_length:
+        Maximum peptide length to include (default: 40).
+
+    Returns
+    -------
+    list of dict
+        Each entry contains ``sequence``, ``start``, ``end``,
+        ``monoisotopic_mass``, and ``missed_cleavages``.
+    """
+    protein_seq = oms.AASequence.fromString(sequence)
+    digest = oms.ProteaseDigestion()
+    digest.setEnzyme(enzyme)
+    digest.setMissedCleavages(missed_cleavages)
+
+    peptides = []
+    digest.digest(protein_seq, peptides, min_length, max_length)
+
+    results = []
+    for pep in peptides:
+        pep_str = pep.toString()
+        mass = pep.getMonoWeight()
+        results.append(
+            {
+                "sequence": pep_str,
+                "length": pep.size(),
+                "monoisotopic_mass": mass,
+            }
+        )
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="In-silico protein digestion using pyopenms."
+    )
+    parser.add_argument(
+        "--sequence",
+        help="Single-letter amino acid sequence of the protein",
+    )
+    parser.add_argument(
+        "--enzyme",
+        default="Trypsin",
+        help="Digestion enzyme name (default: Trypsin)",
+    )
+    parser.add_argument(
+        "--missed-cleavages",
+        type=int,
+        default=0,
+        dest="missed_cleavages",
+        help="Maximum missed cleavages (default: 0)",
+    )
+    parser.add_argument(
+        "--min-length",
+        type=int,
+        default=6,
+        dest="min_length",
+        help="Minimum peptide length (default: 6)",
+    )
+    parser.add_argument(
+        "--max-length",
+        type=int,
+        default=40,
+        dest="max_length",
+        help="Maximum peptide length (default: 40)",
+    )
+    parser.add_argument(
+        "--list-enzymes",
+        action="store_true",
+        dest="list_enzymes",
+        help="List all available enzyme names and exit",
+    )
+    args = parser.parse_args()
+
+    if args.list_enzymes:
+        enzymes = list_enzymes()
+        print("Available enzymes:")
+        for name in enzymes:
+            print(f"  {name}")
+        return
+
+    if not args.sequence:
+        parser.error("--sequence is required unless --list-enzymes is used.")
+
+    peptides = digest_protein(
+        args.sequence,
+        enzyme=args.enzyme,
+        missed_cleavages=args.missed_cleavages,
+        min_length=args.min_length,
+        max_length=args.max_length,
+    )
+
+    print(
+        f"Enzyme: {args.enzyme}  |  Missed cleavages ≤ {args.missed_cleavages}  "
+        f"|  Length {args.min_length}–{args.max_length}"
+    )
+    print(f"Total peptides: {len(peptides)}\n")
+    print(f"{'#':>4}  {'Sequence':<40}  {'Length':>6}  {'Mono Mass (Da)':>14}")
+    print("-" * 72)
+    for i, pep in enumerate(peptides, 1):
+        print(
+            f"{i:>4}  {pep['sequence']:<40}  {pep['length']:>6}  "
+            f"{pep['monoisotopic_mass']:>14.6f}"
+        )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/proteomics/protein_digest/requirements.txt b/scripts/proteomics/protein_digest/requirements.txt
new file mode 100644
index 0000000..7ce28ec
--- /dev/null
+++ b/scripts/proteomics/protein_digest/requirements.txt
@@ -0,0 +1 @@
+pyopenms
diff --git a/scripts/proteomics/protein_digest/tests/conftest.py b/scripts/proteomics/protein_digest/tests/conftest.py
new file mode 100644
index 0000000..1a21ede
--- /dev/null
+++ b/scripts/proteomics/protein_digest/tests/conftest.py
@@ -0,0 +1,15 @@
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
diff --git a/scripts/proteomics/protein_digest/tests/test_protein_digest.py b/scripts/proteomics/protein_digest/tests/test_protein_digest.py
new file mode 100644
index 0000000..d6370a5
--- /dev/null
+++ b/scripts/proteomics/protein_digest/tests/test_protein_digest.py
@@ -0,0 +1,47 @@
+"""Tests for protein_digest."""
+
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestProteinDigest:
+    PROTEIN = "MKVLWAALLVTFLAGCQAKVEQAVETEPEPELRQQTEWQSGQRWELAL"
+
+    def test_tryptic_digest_returns_peptides(self):
+        from protein_digest import digest_protein
+
+        peptides = digest_protein(self.PROTEIN, enzyme="Trypsin", min_length=1)
+        assert len(peptides) > 0
+
+    def test_peptide_structure(self):
+        from protein_digest import digest_protein
+
+        peptides = digest_protein(self.PROTEIN, enzyme="Trypsin", min_length=1)
+        for pep in peptides:
+            assert "sequence" in pep
+            assert "monoisotopic_mass" in pep
+            assert pep["monoisotopic_mass"] > 0
+
+    def test_missed_cleavages(self):
+        from protein_digest import digest_protein
+
+        peps_0 = digest_protein(self.PROTEIN, enzyme="Trypsin", missed_cleavages=0, min_length=1)
+        peps_2 = digest_protein(self.PROTEIN, enzyme="Trypsin", missed_cleavages=2, min_length=1)
+        assert len(peps_2) >= len(peps_0)
+
+    def test_length_filter(self):
+        from protein_digest import digest_protein
+
+        peptides = digest_protein(
+            self.PROTEIN, enzyme="Trypsin", min_length=5, max_length=20, missed_cleavages=2
+        )
+        for pep in peptides:
+            assert 5 <= pep["length"] <= 20
+
+    def test_list_enzymes(self):
+        from protein_digest import list_enzymes
+
+        enzymes = list_enzymes()
+        assert "Trypsin" in enzymes
+        assert len(enzymes) > 5

From a5ec12f6c556ea60e1baecf605209311f41cd088 Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:28:25 +0100
Subject: [PATCH 07/16] Migrate spectrum_file_info to per-script directory with
 synthetic test data

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../proteomics/spectrum_file_info/README.md   |  11 ++
 .../spectrum_file_info/requirements.txt       |   1 +
 .../spectrum_file_info/spectrum_file_info.py  | 136 ++++++++++++++++++
 .../spectrum_file_info/tests/conftest.py      |  15 ++
 .../tests/test_spectrum_file_info.py          |  57 ++++++++
 5 files changed, 220 insertions(+)
 create mode 100644 scripts/proteomics/spectrum_file_info/README.md
 create mode 100644 scripts/proteomics/spectrum_file_info/requirements.txt
 create mode 100644 scripts/proteomics/spectrum_file_info/spectrum_file_info.py
 create mode 100644 scripts/proteomics/spectrum_file_info/tests/conftest.py
 create mode 100644 scripts/proteomics/spectrum_file_info/tests/test_spectrum_file_info.py

diff --git a/scripts/proteomics/spectrum_file_info/README.md b/scripts/proteomics/spectrum_file_info/README.md
new file mode 100644
index 0000000..272d836
--- /dev/null
+++ b/scripts/proteomics/spectrum_file_info/README.md
@@ -0,0 +1,11 @@
+# Mass Spectrum File Info
+
+Summarise the contents of an mzML file: spectra counts by MS level,
+retention time range, m/z range, and TIC statistics.
+
+## Usage
+
+```bash
+python spectrum_file_info.py --input sample.mzML
+python spectrum_file_info.py --input sample.mzML --tic
+```
diff --git a/scripts/proteomics/spectrum_file_info/requirements.txt b/scripts/proteomics/spectrum_file_info/requirements.txt
new file mode 100644
index 0000000..7ce28ec
--- /dev/null
+++ b/scripts/proteomics/spectrum_file_info/requirements.txt
@@ -0,0 +1 @@
+pyopenms
diff --git a/scripts/proteomics/spectrum_file_info/spectrum_file_info.py b/scripts/proteomics/spectrum_file_info/spectrum_file_info.py
new file mode 100644
index 0000000..936c451
--- /dev/null
+++ b/scripts/proteomics/spectrum_file_info/spectrum_file_info.py
@@ -0,0 +1,136 @@
+"""
+Mass Spectrum File Info
+=======================
+Read an mzML (or mzXML) file and print a summary of its contents:
+number of spectra, MS levels, retention time range, m/z range,
+and basic TIC statistics.
+
+Usage
+-----
+    python spectrum_file_info.py --input sample.mzML
+    python spectrum_file_info.py --input sample.mzML --tic
+"""
+
+import argparse
+import sys
+
+try:
+    import pyopenms as oms
+except ImportError:
+    sys.exit(
+        "pyopenms is required. Install it with:  pip install pyopenms"
+    )
+
+
+def summarise_experiment(exp: oms.MSExperiment) -> dict:
+    """Summarise a loaded MSExperiment object.
+
+    Parameters
+    ----------
+    exp:
+        Loaded ``pyopenms.MSExperiment`` instance.
+
+    Returns
+    -------
+    dict
+        Summary statistics for the experiment.
+    """
+    spectra = exp.getSpectra()
+    if not spectra:
+        return {"n_spectra": 0}
+
+    ms_levels = {}
+    rt_min = float("inf")
+    rt_max = float("-inf")
+    mz_min = float("inf")
+    mz_max = float("-inf")
+    tic_values = []
+
+    for spec in spectra:
+        level = spec.getMSLevel()
+        ms_levels[level] = ms_levels.get(level, 0) + 1
+        rt = spec.getRT()
+        rt_min = min(rt_min, rt)
+        rt_max = max(rt_max, rt)
+
+        mzs, intensities = spec.get_peaks()
+        if len(mzs) > 0:
+            mz_min = min(mz_min, float(mzs.min()))
+            mz_max = max(mz_max, float(mzs.max()))
+            tic_values.append(float(intensities.sum()))
+
+    return {
+        "n_spectra": len(spectra),
+        "ms_levels": ms_levels,
+        "rt_range_sec": (rt_min, rt_max),
+        "mz_range": (mz_min, mz_max),
+        "tic_total": sum(tic_values),
+        "tic_max": max(tic_values) if tic_values else 0.0,
+        "tic_per_spectrum": tic_values,
+    }
+
+
+def load_file(path: str) -> oms.MSExperiment:
+    """Load an mzML file into an MSExperiment.
+
+    Parameters
+    ----------
+    path:
+        Path to the mzML file.
+
+    Returns
+    -------
+    pyopenms.MSExperiment
+    """
+    exp = oms.MSExperiment()
+    oms.MzMLFile().load(path, exp)
+    return exp
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Summarise an mzML file using pyopenms."
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        metavar="FILE",
+        help="Path to an mzML file",
+    )
+    parser.add_argument(
+        "--tic",
+        action="store_true",
+        help="Print per-spectrum TIC values",
+    )
+    args = parser.parse_args()
+
+    print(f"Loading {args.input} …")
+    exp = load_file(args.input)
+    summary = summarise_experiment(exp)
+
+    if summary["n_spectra"] == 0:
+        print("No spectra found in file.")
+        return
+
+    print(f"\n{'File':<22}: {args.input}")
+    print(f"{'Total spectra':<22}: {summary['n_spectra']}")
+    for level, count in sorted(summary["ms_levels"].items()):
+        print(f"  {'MS' + str(level) + ' spectra':<20}: {count}")
+    rt_min, rt_max = summary["rt_range_sec"]
+    print(
+        f"{'RT range':<22}: {rt_min:.2f} – {rt_max:.2f} s  "
+        f"({rt_min/60:.2f} – {rt_max/60:.2f} min)"
+    )
+    mz_lo, mz_hi = summary["mz_range"]
+    print(f"{'m/z range':<22}: {mz_lo:.4f} – {mz_hi:.4f}")
+    print(f"{'Total TIC':<22}: {summary['tic_total']:.3e}")
+    print(f"{'Max spectrum TIC':<22}: {summary['tic_max']:.3e}")
+
+    if args.tic:
+        print("\n--- Per-spectrum TIC ---")
+        for i, tic in enumerate(summary["tic_per_spectrum"], 1):
+            print(f"  Spectrum {i:>5}: {tic:.3e}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/proteomics/spectrum_file_info/tests/conftest.py b/scripts/proteomics/spectrum_file_info/tests/conftest.py
new file mode 100644
index 0000000..1a21ede
--- /dev/null
+++ b/scripts/proteomics/spectrum_file_info/tests/conftest.py
@@ -0,0 +1,15 @@
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
diff --git a/scripts/proteomics/spectrum_file_info/tests/test_spectrum_file_info.py b/scripts/proteomics/spectrum_file_info/tests/test_spectrum_file_info.py
new file mode 100644
index 0000000..0ea2b5d
--- /dev/null
+++ b/scripts/proteomics/spectrum_file_info/tests/test_spectrum_file_info.py
@@ -0,0 +1,57 @@
+"""Tests for spectrum_file_info."""
+
+import pytest
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestSpectrumFileInfo:
+    def _make_experiment(self, n_spectra=5, ms_level=1):
+        """Create a synthetic MSExperiment for testing."""
+        import numpy as np
+        import pyopenms as oms
+
+        exp = oms.MSExperiment()
+        for i in range(n_spectra):
+            spec = oms.MSSpectrum()
+            spec.setMSLevel(ms_level)
+            spec.setRT(60.0 * i)
+            mzs = np.array([100.0 + j for j in range(10)], dtype=np.float64)
+            intensities = np.array([1000.0 * (j + 1) for j in range(10)], dtype=np.float64)
+            spec.set_peaks([mzs, intensities])
+            exp.addSpectrum(spec)
+        return exp
+
+    def test_summarise_nonempty(self):
+        from spectrum_file_info import summarise_experiment
+
+        exp = self._make_experiment(n_spectra=3)
+        summary = summarise_experiment(exp)
+        assert summary["n_spectra"] == 3
+        assert 1 in summary["ms_levels"]
+
+    def test_summarise_empty(self):
+        import pyopenms as oms
+        from spectrum_file_info import summarise_experiment
+
+        exp = oms.MSExperiment()
+        summary = summarise_experiment(exp)
+        assert summary["n_spectra"] == 0
+
+    def test_rt_range(self):
+        from spectrum_file_info import summarise_experiment
+
+        exp = self._make_experiment(n_spectra=5)
+        summary = summarise_experiment(exp)
+        rt_min, rt_max = summary["rt_range_sec"]
+        assert rt_min == 0.0
+        assert rt_max == 240.0
+
+    def test_mz_range(self):
+        from spectrum_file_info import summarise_experiment
+
+        exp = self._make_experiment(n_spectra=2)
+        summary = summarise_experiment(exp)
+        mz_min, mz_max = summary["mz_range"]
+        assert mz_min == pytest.approx(100.0)
+        assert mz_max == pytest.approx(109.0)

From 24367852263babb9062f015d47333a8dc27ccb86 Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:30:11 +0100
Subject: [PATCH 08/16] Migrate feature_detection_proteomics to per-script
 directory with synthetic test data

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../feature_detection_proteomics/README.md    | 11 +++
 .../feature_detection_proteomics.py           | 99 +++++++++++++++++++
 .../requirements.txt                          |  1 +
 .../tests/conftest.py                         | 15 +++
 .../test_feature_detection_proteomics.py      | 34 +++++++
 5 files changed, 160 insertions(+)
 create mode 100644 scripts/proteomics/feature_detection_proteomics/README.md
 create mode 100644 scripts/proteomics/feature_detection_proteomics/feature_detection_proteomics.py
 create mode 100644 scripts/proteomics/feature_detection_proteomics/requirements.txt
 create mode 100644 scripts/proteomics/feature_detection_proteomics/tests/conftest.py
 create mode 100644 scripts/proteomics/feature_detection_proteomics/tests/test_feature_detection_proteomics.py

diff --git a/scripts/proteomics/feature_detection_proteomics/README.md b/scripts/proteomics/feature_detection_proteomics/README.md
new file mode 100644
index 0000000..94de59d
--- /dev/null
+++ b/scripts/proteomics/feature_detection_proteomics/README.md
@@ -0,0 +1,11 @@
+# Feature Detection for Proteomics
+
+Detect peptide isotope features in centroided LC-MS/MS data using the
+`FeatureFinderCentroided` algorithm. Output is written as a featureXML file.
+
+## Usage
+
+```bash
+python feature_detection_proteomics.py --input sample.mzML
+python feature_detection_proteomics.py --input sample.mzML --output features.featureXML
+```
diff --git a/scripts/proteomics/feature_detection_proteomics/feature_detection_proteomics.py b/scripts/proteomics/feature_detection_proteomics/feature_detection_proteomics.py
new file mode 100644
index 0000000..bbde892
--- /dev/null
+++ b/scripts/proteomics/feature_detection_proteomics/feature_detection_proteomics.py
@@ -0,0 +1,99 @@
+"""
+Feature Detection for Proteomics LC-MS Data
+============================================
+Detect peptide features (isotope envelopes) in an mzML file using the
+pyopenms FeatureFinderCentroided algorithm.  Results are written to a
+featureXML file which can be opened in TOPPView.
+
+Usage
+-----
+    python feature_detection_proteomics.py --input sample.mzML
+    python feature_detection_proteomics.py --input sample.mzML --output features.featureXML
+"""
+
+import argparse
+import sys
+
+try:
+    import pyopenms as oms
+except ImportError:
+    sys.exit(
+        "pyopenms is required. Install it with:  pip install pyopenms"
+    )
+
+
+def detect_features(
+    input_path: str,
+    output_path: str,
+) -> oms.FeatureMap:
+    """Run FeatureFinderCentroided on an mzML file.
+
+    Parameters
+    ----------
+    input_path:
+        Path to the centroided mzML file.
+    output_path:
+        Path for the output featureXML file.
+
+    Returns
+    -------
+    pyopenms.FeatureMap
+        Map of detected features.
+    """
+    exp = oms.MSExperiment()
+    print(f"Loading {input_path} …")
+    oms.MzMLFile().load(input_path, exp)
+    exp.updateRanges()
+
+    feature_map = oms.FeatureMap()
+    seeds = oms.FeatureMap()
+
+    ff = oms.FeatureFinderAlgorithmPicked()
+    params = ff.getParameters()
+    ff.run(exp, feature_map, params, seeds)
+
+    feature_map.setUniqueIds()
+    oms.FeatureXMLFile().store(output_path, feature_map)
+    print(f"Detected {feature_map.size()} features → {output_path}")
+    return feature_map
+
+
+def print_feature_summary(feature_map: oms.FeatureMap) -> None:
+    """Print a tabular summary of detected features."""
+    if feature_map.size() == 0:
+        print("No features detected.")
+        return
+
+    print(f"\n{'#':>5}  {'RT (s)':>10}  {'m/z':>12}  {'Charge':>6}  {'Intensity':>14}")
+    print("-" * 56)
+    for i, feature in enumerate(feature_map, 1):
+        print(
+            f"{i:>5}  {feature.getRT():>10.2f}  {feature.getMZ():>12.4f}  "
+            f"{feature.getCharge():>6}  {feature.getIntensity():>14.3e}"
+        )
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Detect peptide features in an mzML file using pyopenms."
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        metavar="FILE",
+        help="Centroided mzML input file",
+    )
+    parser.add_argument(
+        "--output",
+        metavar="FILE",
+        help="Output featureXML file (default: <input>.featureXML)",
+    )
+    args = parser.parse_args()
+
+    output_path = args.output or args.input.replace(".mzML", ".featureXML")
+    feature_map = detect_features(args.input, output_path)
+    print_feature_summary(feature_map)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/proteomics/feature_detection_proteomics/requirements.txt b/scripts/proteomics/feature_detection_proteomics/requirements.txt
new file mode 100644
index 0000000..7ce28ec
--- /dev/null
+++ b/scripts/proteomics/feature_detection_proteomics/requirements.txt
@@ -0,0 +1 @@
+pyopenms
diff --git a/scripts/proteomics/feature_detection_proteomics/tests/conftest.py b/scripts/proteomics/feature_detection_proteomics/tests/conftest.py
new file mode 100644
index 0000000..1a21ede
--- /dev/null
+++ b/scripts/proteomics/feature_detection_proteomics/tests/conftest.py
@@ -0,0 +1,15 @@
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
diff --git a/scripts/proteomics/feature_detection_proteomics/tests/test_feature_detection_proteomics.py b/scripts/proteomics/feature_detection_proteomics/tests/test_feature_detection_proteomics.py
new file mode 100644
index 0000000..66cbdfa
--- /dev/null
+++ b/scripts/proteomics/feature_detection_proteomics/tests/test_feature_detection_proteomics.py
@@ -0,0 +1,34 @@
+"""Tests for feature_detection_proteomics."""
+
+import os
+import tempfile
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestFeatureDetectionProteomics:
+    def test_detect_features_returns_feature_map(self):
+        import numpy as np
+        import pyopenms as oms
+        from feature_detection_proteomics import detect_features
+
+        # Create a minimal synthetic experiment with a few peaks
+        exp = oms.MSExperiment()
+        for i in range(10):
+            spec = oms.MSSpectrum()
+            spec.setMSLevel(1)
+            spec.setRT(60.0 + i * 2.0)
+            mzs = np.array([500.0, 500.5, 501.0], dtype=np.float64)
+            intensities = np.array([1e4, 5e3, 1e3], dtype=np.float64)
+            spec.set_peaks([mzs, intensities])
+            exp.addSpectrum(spec)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            input_path = os.path.join(tmpdir, "test.mzML")
+            output_path = os.path.join(tmpdir, "test.featureXML")
+            oms.MzMLFile().store(input_path, exp)
+
+            fm = detect_features(input_path, output_path)
+            assert isinstance(fm, oms.FeatureMap)
+            assert os.path.exists(output_path)

From 70019e4e8aa22c8131ab4f535d41353199a8b679 Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:31:42 +0100
Subject: [PATCH 09/16] Migrate mass_accuracy_calculator to per-script
 directory structure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../mass_accuracy_calculator/README.md        |  12 ++
 .../mass_accuracy_calculator.py               | 140 ++++++++++++++++++
 .../mass_accuracy_calculator/requirements.txt |   1 +
 .../tests/conftest.py                         |  15 ++
 .../tests/test_mass_accuracy_calculator.py    |  40 +++++
 5 files changed, 208 insertions(+)
 create mode 100644 scripts/metabolomics/mass_accuracy_calculator/README.md
 create mode 100644 scripts/metabolomics/mass_accuracy_calculator/mass_accuracy_calculator.py
 create mode 100644 scripts/metabolomics/mass_accuracy_calculator/requirements.txt
 create mode 100644 scripts/metabolomics/mass_accuracy_calculator/tests/conftest.py
 create mode 100644 scripts/metabolomics/mass_accuracy_calculator/tests/test_mass_accuracy_calculator.py

diff --git a/scripts/metabolomics/mass_accuracy_calculator/README.md b/scripts/metabolomics/mass_accuracy_calculator/README.md
new file mode 100644
index 0000000..6bb621b
--- /dev/null
+++ b/scripts/metabolomics/mass_accuracy_calculator/README.md
@@ -0,0 +1,12 @@
+# Mass Accuracy Calculator
+
+Calculate mass accuracy (ppm error) between a theoretical value derived
+from a peptide sequence or molecular formula and observed m/z values.
+
+## Usage
+
+```bash
+python mass_accuracy_calculator.py --sequence PEPTIDEK --observed 803.4560
+python mass_accuracy_calculator.py --formula C6H12O6 --observed 181.0709
+python mass_accuracy_calculator.py --sequence ACDEFGHIK --charge 2 --observed 554.2478 554.2480
+```
diff --git a/scripts/metabolomics/mass_accuracy_calculator/mass_accuracy_calculator.py b/scripts/metabolomics/mass_accuracy_calculator/mass_accuracy_calculator.py
new file mode 100644
index 0000000..b8c1b7a
--- /dev/null
+++ b/scripts/metabolomics/mass_accuracy_calculator/mass_accuracy_calculator.py
@@ -0,0 +1,140 @@
+"""
+Mass Accuracy Calculator
+========================
+Calculate the mass accuracy (ppm error) between a theoretical mass
+(or peptide/formula string) and one or more observed m/z values.
+
+Supports both:
+- Amino acid sequence inputs  (e.g. ``PEPTIDEK``)
+- Empirical formula inputs    (e.g. ``C6H12O6``)
+
+Usage
+-----
+    # Peptide sequence
+    python mass_accuracy_calculator.py --sequence PEPTIDEK --observed 803.4560
+
+    # Molecular formula (charge 1 default)
+    python mass_accuracy_calculator.py --formula C6H12O6 --observed 181.0709
+
+    # Multiple observed values at charge 2
+    python mass_accuracy_calculator.py --sequence ACDEFGHIK --charge 2 \\
+        --observed 554.2478 554.2480 554.2482
+"""
+
+import argparse
+import sys
+
+try:
+    import pyopenms as oms
+except ImportError:
+    sys.exit(
+        "pyopenms is required. Install it with:  pip install pyopenms"
+    )
+
+PROTON = 1.007276
+
+
+def theoretical_mz_from_sequence(sequence: str, charge: int) -> float:
+    """Compute the theoretical m/z for a peptide sequence.
+
+    Parameters
+    ----------
+    sequence:
+        Amino acid sequence, optionally with bracket-enclosed modifications.
+    charge:
+        Charge state.
+
+    Returns
+    -------
+    float
+        Theoretical m/z value.
+    """
+    aa_seq = oms.AASequence.fromString(sequence)
+    mass = aa_seq.getMonoWeight()
+    return (mass + charge * PROTON) / charge
+
+
+def theoretical_mz_from_formula(formula: str, charge: int) -> float:
+    """Compute the theoretical m/z for a molecular formula.
+
+    Parameters
+    ----------
+    formula:
+        Empirical formula string, e.g. ``"C6H12O6"``.
+    charge:
+        Charge state (used for proton addition).
+
+    Returns
+    -------
+    float
+        Theoretical m/z value (monoisotopic).
+    """
+    ef = oms.EmpiricalFormula(formula)
+    mass = ef.getMonoWeight()
+    return (mass + charge * PROTON) / charge
+
+
+def ppm_error(theoretical: float, observed: float) -> float:
+    """Calculate the mass accuracy in parts-per-million (ppm).
+
+    Parameters
+    ----------
+    theoretical:
+        Theoretical m/z value.
+    observed:
+        Observed m/z value.
+
+    Returns
+    -------
+    float
+        PPM error (positive = observed > theoretical).
+    """
+    return (observed - theoretical) / theoretical * 1e6
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Compute m/z mass accuracy (ppm error) using pyopenms."
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument(
+        "--sequence",
+        help="Peptide sequence (e.g. PEPTIDEK)",
+    )
+    group.add_argument(
+        "--formula",
+        help="Molecular formula (e.g. C6H12O6)",
+    )
+    parser.add_argument(
+        "--charge",
+        type=int,
+        default=1,
+        help="Charge state (default: 1)",
+    )
+    parser.add_argument(
+        "--observed",
+        nargs="+",
+        type=float,
+        required=True,
+        metavar="MZ",
+        help="Observed m/z value(s)",
+    )
+    args = parser.parse_args()
+
+    if args.sequence:
+        theoretical = theoretical_mz_from_sequence(args.sequence, args.charge)
+        label = f"sequence={args.sequence}"
+    else:
+        theoretical = theoretical_mz_from_formula(args.formula, args.charge)
+        label = f"formula={args.formula}"
+
+    print(f"Theoretical m/z ({label}, charge {args.charge}+): {theoretical:.6f}")
+    print(f"\n{'Observed m/z':>14}  {'PPM error':>10}")
+    print("-" * 28)
+    for obs in args.observed:
+        ppm = ppm_error(theoretical, obs)
+        print(f"{obs:>14.6f}  {ppm:>+10.4f}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/metabolomics/mass_accuracy_calculator/requirements.txt b/scripts/metabolomics/mass_accuracy_calculator/requirements.txt
new file mode 100644
index 0000000..7ce28ec
--- /dev/null
+++ b/scripts/metabolomics/mass_accuracy_calculator/requirements.txt
@@ -0,0 +1 @@
+pyopenms
diff --git a/scripts/metabolomics/mass_accuracy_calculator/tests/conftest.py b/scripts/metabolomics/mass_accuracy_calculator/tests/conftest.py
new file mode 100644
index 0000000..1a21ede
--- /dev/null
+++ b/scripts/metabolomics/mass_accuracy_calculator/tests/conftest.py
@@ -0,0 +1,15 @@
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
diff --git a/scripts/metabolomics/mass_accuracy_calculator/tests/test_mass_accuracy_calculator.py b/scripts/metabolomics/mass_accuracy_calculator/tests/test_mass_accuracy_calculator.py
new file mode 100644
index 0000000..fb2d3de
--- /dev/null
+++ b/scripts/metabolomics/mass_accuracy_calculator/tests/test_mass_accuracy_calculator.py
@@ -0,0 +1,40 @@
+"""Tests for mass_accuracy_calculator."""
+
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestMassAccuracyCalculator:
+    def test_sequence_theoretical(self):
+        from mass_accuracy_calculator import theoretical_mz_from_sequence
+
+        mz = theoretical_mz_from_sequence("PEPTIDEK", 1)
+        assert 928.0 < mz < 929.0
+
+    def test_formula_theoretical(self):
+        from mass_accuracy_calculator import theoretical_mz_from_formula
+
+        mz = theoretical_mz_from_formula("C6H12O6", 1)
+        assert 181.0 < mz < 182.0
+
+    def test_ppm_zero_error(self):
+        from mass_accuracy_calculator import ppm_error
+
+        assert ppm_error(500.0, 500.0) == 0.0
+
+    def test_ppm_positive_error(self):
+        from mass_accuracy_calculator import ppm_error
+
+        assert ppm_error(500.0, 500.001) > 0
+
+    def test_ppm_negative_error(self):
+        from mass_accuracy_calculator import ppm_error
+
+        assert ppm_error(500.0, 499.999) < 0
+
+    def test_ppm_known_value(self):
+        from mass_accuracy_calculator import ppm_error
+
+        ppm = ppm_error(1000.0, 1000.001)
+        assert abs(ppm - 1.0) < 0.001

From b575f69ba1b538074ee5c487c606fe19de5fa66b Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:33:17 +0100
Subject: [PATCH 10/16] Migrate isotope_pattern_matcher to per-script directory
 structure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../isotope_pattern_matcher/README.md         |  11 ++
 .../isotope_pattern_matcher.py                | 169 ++++++++++++++++++
 .../isotope_pattern_matcher/requirements.txt  |   1 +
 .../isotope_pattern_matcher/tests/conftest.py |  15 ++
 .../tests/test_isotope_pattern_matcher.py     |  50 ++++++
 5 files changed, 246 insertions(+)
 create mode 100644 scripts/metabolomics/isotope_pattern_matcher/README.md
 create mode 100644 scripts/metabolomics/isotope_pattern_matcher/isotope_pattern_matcher.py
 create mode 100644 scripts/metabolomics/isotope_pattern_matcher/requirements.txt
 create mode 100644 scripts/metabolomics/isotope_pattern_matcher/tests/conftest.py
 create mode 100644 scripts/metabolomics/isotope_pattern_matcher/tests/test_isotope_pattern_matcher.py

diff --git a/scripts/metabolomics/isotope_pattern_matcher/README.md b/scripts/metabolomics/isotope_pattern_matcher/README.md
new file mode 100644
index 0000000..e56d2a7
--- /dev/null
+++ b/scripts/metabolomics/isotope_pattern_matcher/README.md
@@ -0,0 +1,11 @@
+# Isotope Pattern Generator & Matcher
+
+Generate theoretical isotope distributions for any molecular formula and
+optionally compute a cosine similarity score against observed peaks.
+
+## Usage
+
+```bash
+python isotope_pattern_matcher.py --formula C6H12O6
+python isotope_pattern_matcher.py --formula C6H12O6 --peaks 181.0709,100.0 182.0742,6.7 183.0775,0.4
+```
diff --git a/scripts/metabolomics/isotope_pattern_matcher/isotope_pattern_matcher.py b/scripts/metabolomics/isotope_pattern_matcher/isotope_pattern_matcher.py
new file mode 100644
index 0000000..f0510d4
--- /dev/null
+++ b/scripts/metabolomics/isotope_pattern_matcher/isotope_pattern_matcher.py
@@ -0,0 +1,169 @@
+"""
+Isotope Pattern Generator & Matcher
+=====================================
+Generate the theoretical isotope distribution for a molecular formula
+and optionally compare it against an observed spectrum to compute a
+cosine similarity score using pyopenms.
+
+Usage
+-----
+    # Generate isotope pattern for glucose
+    python isotope_pattern_matcher.py --formula C6H12O6
+
+    # Compare against observed peaks (m/z intensity pairs on stdin or --peaks)
+    python isotope_pattern_matcher.py --formula C6H12O6 \\
+        --peaks 181.0709,100.0 182.0742,6.7 183.0775,0.4
+"""
+
+import argparse
+import math
+import sys
+
+try:
+    import pyopenms as oms
+except ImportError:
+    sys.exit(
+        "pyopenms is required. Install it with:  pip install pyopenms"
+    )
+
+
+def get_isotope_distribution(
+    formula: str,
+    max_isotopes: int = 5,
+) -> list:
+    """Compute the theoretical isotope distribution for a molecular formula.
+
+    Parameters
+    ----------
+    formula:
+        Empirical formula string, e.g. ``"C6H12O6"``.
+    max_isotopes:
+        Maximum number of isotope peaks to return (default: 5).
+
+    Returns
+    -------
+    list of (mz, relative_abundance)
+        Sorted by m/z; relative abundances sum to 100.
+    """
+    ef = oms.EmpiricalFormula(formula)
+    isotope_dist = ef.getIsotopeDistribution(
+        oms.CoarseIsotopePatternGenerator(max_isotopes)
+    )
+    peaks = [(p.getMZ(), p.getIntensity()) for p in isotope_dist.getContainer()]
+    if not peaks:
+        return []
+    max_ab = max(ab for _, ab in peaks)
+    return [(mz, ab / max_ab * 100) for mz, ab in peaks]
+
+
+def cosine_similarity(
+    theoretical: list,
+    observed: list,
+    mz_tolerance: float = 0.02,
+) -> float:
+    """Compute cosine similarity between theoretical and observed peak lists.
+
+    Parameters
+    ----------
+    theoretical:
+        List of ``(mz, intensity)`` tuples for the theoretical pattern.
+    observed:
+        List of ``(mz, intensity)`` tuples for the observed spectrum.
+    mz_tolerance:
+        Maximum m/z difference to match a pair of peaks (default: 0.02 Da).
+
+    Returns
+    -------
+    float
+        Cosine similarity in [0, 1].
+    """
+    theo_vec = []
+    obs_vec = []
+    for tmz, tint in theoretical:
+        matched = 0.0
+        for omz, oint in observed:
+            if abs(omz - tmz) <= mz_tolerance:
+                matched = oint
+                break
+        theo_vec.append(tint)
+        obs_vec.append(matched)
+
+    dot = sum(t * o for t, o in zip(theo_vec, obs_vec))
+    norm_t = math.sqrt(sum(t ** 2 for t in theo_vec))
+    norm_o = math.sqrt(sum(o ** 2 for o in obs_vec))
+    if norm_t == 0 or norm_o == 0:
+        return 0.0
+    return dot / (norm_t * norm_o)
+
+
+def parse_peaks(peak_strings: list) -> list:
+    """Parse ``"mz,intensity"`` strings into ``(float, float)`` tuples."""
+    peaks = []
+    for s in peak_strings:
+        parts = s.split(",")
+        if len(parts) != 2:
+            raise ValueError(
+                f"Expected 'mz,intensity' format, got: {s!r}"
+            )
+        peaks.append((float(parts[0]), float(parts[1])))
+    return peaks
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate theoretical isotope patterns and optionally "
+                    "compare them against observed peaks using pyopenms."
+    )
+    parser.add_argument(
+        "--formula",
+        required=True,
+        help="Molecular formula (e.g. C6H12O6)",
+    )
+    parser.add_argument(
+        "--max-isotopes",
+        type=int,
+        default=5,
+        dest="max_isotopes",
+        help="Maximum isotope peaks to compute (default: 5)",
+    )
+    parser.add_argument(
+        "--peaks",
+        nargs="+",
+        metavar="MZ,INTENSITY",
+        help="Observed peaks as 'mz,intensity' pairs for similarity scoring",
+    )
+    parser.add_argument(
+        "--tolerance",
+        type=float,
+        default=0.02,
+        metavar="DA",
+        help="m/z tolerance in Da for peak matching (default: 0.02)",
+    )
+    args = parser.parse_args()
+
+    distribution = get_isotope_distribution(args.formula, args.max_isotopes)
+    if not distribution:
+        print("Could not compute isotope distribution for the given formula.")
+        return
+
+    print(f"Isotope distribution for {args.formula}:")
+    print(f"\n{'Peak':>5}  {'m/z':>12}  {'Relative Abundance (%)':>22}")
+    print("-" * 44)
+    for i, (mz, rel_ab) in enumerate(distribution):
+        bar = "#" * int(rel_ab / 5)
+        print(f"  M+{i}  {mz:>12.4f}  {rel_ab:>6.2f} %  {bar}")
+
+    if args.peaks:
+        observed = parse_peaks(args.peaks)
+        sim = cosine_similarity(distribution, observed, args.tolerance)
+        print(f"\nCosine similarity vs. observed peaks: {sim:.4f}")
+        if sim >= 0.9:
+            print("  ✓ Excellent match (≥ 0.90)")
+        elif sim >= 0.7:
+            print("  ~ Good match (≥ 0.70)")
+        else:
+            print("  ✗ Poor match (< 0.70)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/metabolomics/isotope_pattern_matcher/requirements.txt b/scripts/metabolomics/isotope_pattern_matcher/requirements.txt
new file mode 100644
index 0000000..7ce28ec
--- /dev/null
+++ b/scripts/metabolomics/isotope_pattern_matcher/requirements.txt
@@ -0,0 +1 @@
+pyopenms
diff --git a/scripts/metabolomics/isotope_pattern_matcher/tests/conftest.py b/scripts/metabolomics/isotope_pattern_matcher/tests/conftest.py
new file mode 100644
index 0000000..1a21ede
--- /dev/null
+++ b/scripts/metabolomics/isotope_pattern_matcher/tests/conftest.py
@@ -0,0 +1,15 @@
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
diff --git a/scripts/metabolomics/isotope_pattern_matcher/tests/test_isotope_pattern_matcher.py b/scripts/metabolomics/isotope_pattern_matcher/tests/test_isotope_pattern_matcher.py
new file mode 100644
index 0000000..a0999cb
--- /dev/null
+++ b/scripts/metabolomics/isotope_pattern_matcher/tests/test_isotope_pattern_matcher.py
@@ -0,0 +1,50 @@
+"""Tests for isotope_pattern_matcher."""
+
+import pytest
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestIsotopePatternMatcher:
+    def test_glucose_pattern(self):
+        from isotope_pattern_matcher import get_isotope_distribution
+
+        dist = get_isotope_distribution("C6H12O6", max_isotopes=3)
+        assert len(dist) == 3
+        assert dist[0][1] == pytest.approx(100.0)
+        assert dist[1][1] < dist[0][1]
+
+    def test_pattern_mz_ordering(self):
+        from isotope_pattern_matcher import get_isotope_distribution
+
+        dist = get_isotope_distribution("C12H22O11", max_isotopes=4)
+        mzs = [mz for mz, _ in dist]
+        assert mzs == sorted(mzs)
+
+    def test_cosine_similarity_perfect(self):
+        from isotope_pattern_matcher import cosine_similarity
+
+        peaks = [(100.0, 50.0), (101.0, 20.0), (102.0, 5.0)]
+        sim = cosine_similarity(peaks, peaks, mz_tolerance=0.01)
+        assert abs(sim - 1.0) < 1e-9
+
+    def test_cosine_similarity_no_overlap(self):
+        from isotope_pattern_matcher import cosine_similarity
+
+        theoretical = [(100.0, 50.0), (101.0, 20.0)]
+        observed = [(200.0, 50.0), (201.0, 20.0)]
+        sim = cosine_similarity(theoretical, observed, mz_tolerance=0.01)
+        assert sim == 0.0
+
+    def test_parse_peaks(self):
+        from isotope_pattern_matcher import parse_peaks
+
+        result = parse_peaks(["181.0709,100.0", "182.0742,6.7"])
+        assert len(result) == 2
+        assert result[0] == (181.0709, 100.0)
+
+    def test_parse_peaks_invalid(self):
+        from isotope_pattern_matcher import parse_peaks
+
+        with pytest.raises(ValueError):
+            parse_peaks(["181.0709"])

From 85d6fd393c182e519786ca1d7e2babcb2e5ade90 Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:35:07 +0100
Subject: [PATCH 11/16] Migrate metabolite_feature_detection to per-script
 directory with synthetic test data

Fix FeatureFindingMetabo.run() API change in pyopenms >= 3.x: third argument
is now output_chromatograms list, not a chrom_fwhm float.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../metabolite_feature_detection/README.md    |  11 ++
 .../metabolite_feature_detection.py           | 145 ++++++++++++++++++
 .../requirements.txt                          |   1 +
 .../tests/conftest.py                         |  15 ++
 .../test_metabolite_feature_detection.py      |  34 ++++
 5 files changed, 206 insertions(+)
 create mode 100644 scripts/metabolomics/metabolite_feature_detection/README.md
 create mode 100644 scripts/metabolomics/metabolite_feature_detection/metabolite_feature_detection.py
 create mode 100644 scripts/metabolomics/metabolite_feature_detection/requirements.txt
 create mode 100644 scripts/metabolomics/metabolite_feature_detection/tests/conftest.py
 create mode 100644 scripts/metabolomics/metabolite_feature_detection/tests/test_metabolite_feature_detection.py

diff --git a/scripts/metabolomics/metabolite_feature_detection/README.md b/scripts/metabolomics/metabolite_feature_detection/README.md
new file mode 100644
index 0000000..fb87e19
--- /dev/null
+++ b/scripts/metabolomics/metabolite_feature_detection/README.md
@@ -0,0 +1,11 @@
+# Metabolite Feature Detection
+
+Detect small-molecule features in centroided LC-MS data using the
+`FeatureFinderMetabo` pipeline. Output is written as a featureXML file.
+
+## Usage
+
+```bash
+python metabolite_feature_detection.py --input sample.mzML
+python metabolite_feature_detection.py --input sample.mzML --output features.featureXML --noise 1e5
+```
diff --git a/scripts/metabolomics/metabolite_feature_detection/metabolite_feature_detection.py b/scripts/metabolomics/metabolite_feature_detection/metabolite_feature_detection.py
new file mode 100644
index 0000000..2e88c08
--- /dev/null
+++ b/scripts/metabolomics/metabolite_feature_detection/metabolite_feature_detection.py
@@ -0,0 +1,145 @@
+"""
+Metabolite Feature Detection
+=============================
+Detect small-molecule features (isotope envelopes) in an LC-MS mzML file
+using the pyopenms FeatureFinderMetabo algorithm.  Results are written to a
+featureXML file which can be opened in TOPPView.
+
+Usage
+-----
+    python metabolite_feature_detection.py --input sample.mzML
+    python metabolite_feature_detection.py --input sample.mzML --output features.featureXML --noise 1e5
+"""
+
+import argparse
+import sys
+
+try:
+    import pyopenms as oms
+except ImportError:
+    sys.exit(
+        "pyopenms is required. Install it with:  pip install pyopenms"
+    )
+
+
+def detect_metabolite_features(
+    input_path: str,
+    output_path: str,
+    noise_threshold: float = 1e4,
+) -> oms.FeatureMap:
+    """Run FeatureFinderMetabo on an mzML file.
+
+    Parameters
+    ----------
+    input_path:
+        Path to the centroided mzML file.
+    output_path:
+        Path for the output featureXML file.
+    noise_threshold:
+        Minimum peak intensity to consider during mass tracing (default 1e4).
+
+    Returns
+    -------
+    pyopenms.FeatureMap
+        Map of detected metabolite features.
+    """
+    exp = oms.MSExperiment()
+    print(f"Loading {input_path} …")
+    oms.MzMLFile().load(input_path, exp)
+    exp.updateRanges()
+
+    # --- Mass tracing ---
+    mass_traces = []
+    mt_params = oms.MassTraceDetection().getDefaults()
+    mt_params.setValue("noise_threshold_int", noise_threshold)
+    mt_det = oms.MassTraceDetection()
+    mt_det.setParameters(mt_params)
+    mt_det.run(exp, mass_traces, 0)
+    print(f"Mass traces found: {len(mass_traces)}")
+
+    # --- Elution peak detection ---
+    mass_traces_split = []
+    mass_traces_final = []
+    epd_params = oms.ElutionPeakDetection().getDefaults()
+    epd = oms.ElutionPeakDetection()
+    epd.setParameters(epd_params)
+    epd.detectPeaks(mass_traces, mass_traces_split)
+    if epd.getParameters().getValue("width_filtering") == "auto":
+        epd.filterByPeakWidth(mass_traces_split, mass_traces_final)
+    else:
+        mass_traces_final = mass_traces_split
+
+    # --- Feature detection ---
+    feature_map = oms.FeatureMap()
+    output_chromatograms = []  # pyopenms >= 3.x requires a list here
+    ffm_params = oms.FeatureFindingMetabo().getDefaults()
+    ffm = oms.FeatureFindingMetabo()
+    ffm.setParameters(ffm_params)
+    ffm.run(mass_traces_final, feature_map, output_chromatograms)
+
+    feature_map.setUniqueIds()
+    oms.FeatureXMLFile().store(output_path, feature_map)
+    print(f"Detected {feature_map.size()} metabolite features → {output_path}")
+    return feature_map
+
+
+def print_feature_summary(feature_map: oms.FeatureMap, top_n: int = 20) -> None:
+    """Print a tabular summary of the top-N most intense features."""
+    if feature_map.size() == 0:
+        print("No features detected.")
+        return
+
+    features = list(feature_map)
+    features.sort(key=lambda f: f.getIntensity(), reverse=True)
+
+    display = features[:top_n]
+    print(
+        f"\nTop {len(display)} features (by intensity):\n"
+        f"{'#':>5}  {'RT (s)':>10}  {'m/z':>12}  {'Charge':>6}  {'Intensity':>14}"
+    )
+    print("-" * 56)
+    for i, feature in enumerate(display, 1):
+        print(
+            f"{i:>5}  {feature.getRT():>10.2f}  {feature.getMZ():>12.4f}  "
+            f"{feature.getCharge():>6}  {feature.getIntensity():>14.3e}"
+        )
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Detect metabolite features in an mzML file using pyopenms."
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        metavar="FILE",
+        help="Centroided mzML input file",
+    )
+    parser.add_argument(
+        "--output",
+        metavar="FILE",
+        help="Output featureXML file (default: <input>.featureXML)",
+    )
+    parser.add_argument(
+        "--noise",
+        type=float,
+        default=1e4,
+        metavar="THRESHOLD",
+        help="Noise intensity threshold for mass tracing (default: 1e4)",
+    )
+    parser.add_argument(
+        "--top",
+        type=int,
+        default=20,
+        metavar="N",
+        help="Number of top features to print (default: 20)",
+    )
+    args = parser.parse_args()
+
+    output_path = args.output or args.input.replace(".mzML", "_metabolites.featureXML")
+    feature_map = detect_metabolite_features(args.input, output_path, args.noise)
+    print_feature_summary(feature_map, args.top)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/metabolomics/metabolite_feature_detection/requirements.txt b/scripts/metabolomics/metabolite_feature_detection/requirements.txt
new file mode 100644
index 0000000..7ce28ec
--- /dev/null
+++ b/scripts/metabolomics/metabolite_feature_detection/requirements.txt
@@ -0,0 +1 @@
+pyopenms
diff --git a/scripts/metabolomics/metabolite_feature_detection/tests/conftest.py b/scripts/metabolomics/metabolite_feature_detection/tests/conftest.py
new file mode 100644
index 0000000..1a21ede
--- /dev/null
+++ b/scripts/metabolomics/metabolite_feature_detection/tests/conftest.py
@@ -0,0 +1,15 @@
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
diff --git a/scripts/metabolomics/metabolite_feature_detection/tests/test_metabolite_feature_detection.py b/scripts/metabolomics/metabolite_feature_detection/tests/test_metabolite_feature_detection.py
new file mode 100644
index 0000000..400007f
--- /dev/null
+++ b/scripts/metabolomics/metabolite_feature_detection/tests/test_metabolite_feature_detection.py
@@ -0,0 +1,34 @@
+"""Tests for metabolite_feature_detection."""
+
+import os
+import tempfile
+
+from conftest import requires_pyopenms
+
+
+@requires_pyopenms
+class TestMetaboliteFeatureDetection:
+    def test_detect_features_returns_feature_map(self):
+        import numpy as np
+        import pyopenms as oms
+        from metabolite_feature_detection import detect_metabolite_features
+
+        # Create a minimal synthetic experiment
+        exp = oms.MSExperiment()
+        for i in range(20):
+            spec = oms.MSSpectrum()
+            spec.setMSLevel(1)
+            spec.setRT(30.0 + i * 3.0)
+            mzs = np.array([180.063, 181.066, 182.070], dtype=np.float64)
+            intensities = np.array([1e5, 1e4, 1e3], dtype=np.float64)
+            spec.set_peaks([mzs, intensities])
+            exp.addSpectrum(spec)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            input_path = os.path.join(tmpdir, "test.mzML")
+            output_path = os.path.join(tmpdir, "test.featureXML")
+            oms.MzMLFile().store(input_path, exp)
+
+            fm = detect_metabolite_features(input_path, output_path, noise_threshold=1e2)
+            assert isinstance(fm, oms.FeatureMap)
+            assert os.path.exists(output_path)

From 731329992793b0b201d939235b52702145519ffb Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:36:34 +0100
Subject: [PATCH 12/16] Add validate-script and contribute-script Claude Code
 skills

- validate-script: isolated venv validation (ruff + pytest) for any script
- contribute-script: guided workflow for creating new pyopenms tools

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/skills/contribute-script.md | 109 ++++++++++++++++++++++++++++
 .claude/skills/validate-script.md   |  34 +++++++++
 2 files changed, 143 insertions(+)
 create mode 100644 .claude/skills/contribute-script.md
 create mode 100644 .claude/skills/validate-script.md

diff --git a/.claude/skills/contribute-script.md b/.claude/skills/contribute-script.md
new file mode 100644
index 0000000..f43f7c4
--- /dev/null
+++ b/.claude/skills/contribute-script.md
@@ -0,0 +1,109 @@
+---
+name: contribute-script
+description: Guide creation of a new pyopenms script contribution — scaffolding through validation
+---
+
+# Contribute Script
+
+Guide an AI agent through creating a new pyopenms CLI tool for the agentomics repo. Follow every step — this is a rigid skill.
+
+## Prerequisites
+
+Read `AGENTS.md` in the repo root for the full contributor guide and code patterns.
+
+## Steps
+
+### 1. Understand the tool
+
+Ask the user:
+- What does this tool do? What pyopenms functionality does it use?
+- What gap in OpenMS/pyopenms does it fill?
+
+### 2. Determine the domain
+
+Ask: Is this a **proteomics** or **metabolomics** tool? If neither fits, discuss whether a new domain directory is needed.
+
+### 3. Pick a name
+
+Choose a descriptive snake_case name for the tool (e.g. `peptide_mass_calculator`, `isotope_pattern_matcher`). Confirm with the user.
+
+### 4. Create a feature branch
+
+```bash
+git checkout -b add/<tool_name>
+```
+
+### 5. Scaffold the directory
+
+```bash
+mkdir -p scripts/<domain>/<tool_name>/tests
+```
+
+Create these files:
+
+**`requirements.txt`:**
+```
+pyopenms
+```
+Add any additional dependencies the script needs (one per line, no version pins).
+
+**`tests/conftest.py`:**
+```python
+import sys
+import os
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
+```
+
+### 6. Write the script
+
+Create `scripts/<domain>/<tool_name>/<tool_name>.py` following these patterns:
+
+- Module-level docstring with description, supported features, and CLI usage examples
+- pyopenms import guard:
+  ```python
+  try:
+      import pyopenms as oms
+  except ImportError:
+      sys.exit("pyopenms is required. Install it with:  pip install pyopenms")
+  ```
+- `PROTON = 1.007276` constant where mass-to-charge calculations are needed
+- Importable functions as the primary interface (with type hints and numpy-style docstrings)
+- `main()` function with argparse CLI
+- `if __name__ == "__main__": main()` guard
+
+### 7. Write tests
+
+Create `scripts/<domain>/<tool_name>/tests/test_<tool_name>.py`:
+
+- Import `requires_pyopenms` from conftest
+- Decorate test classes with `@requires_pyopenms`
+- Use `from <tool_name> import <function>` inside test methods
+- For file-I/O scripts: generate synthetic data using pyopenms objects in test fixtures, write to `tempfile.TemporaryDirectory()`
+- Cover: basic functionality, edge cases, key parameters
+
+### 8. Write README
+
+Create `scripts/<domain>/<tool_name>/README.md` with a brief description and CLI usage examples.
+
+### 9. Validate
+
+Invoke the `validate-script` skill on the new script directory. Both ruff and pytest must pass.
+
+### 10. Commit
+
+```bash
+git add scripts/<domain>/<tool_name>/
+git commit -m "Add <tool_name>: <brief description>"
+```
diff --git a/.claude/skills/validate-script.md b/.claude/skills/validate-script.md
new file mode 100644
index 0000000..5d21baa
--- /dev/null
+++ b/.claude/skills/validate-script.md
@@ -0,0 +1,34 @@
+---
+name: validate-script
+description: Validate a pyopenms script in an isolated venv — runs ruff lint and pytest
+---
+
+# Validate Script
+
+Validate any script in the agentomics repo by running ruff and pytest in a fresh isolated venv.
+
+## Steps (follow exactly — rigid skill)
+
+1. **Identify the script directory.** If the user provided a path, use it. Otherwise, ask which script to validate. The path should be `scripts/<domain>/<tool_name>/`.
+
+2. **Verify the directory structure.** Confirm it contains:
+   - `<tool_name>.py`
+   - `requirements.txt`
+   - `tests/` directory with at least one `test_*.py` file
+
+3. **Create a temporary venv and run validation.** Execute these commands:
+
+   ```bash
+   SCRIPT_DIR=<path-to-script-directory>
+   VENV_DIR=$(mktemp -d)
+   python -m venv "$VENV_DIR"
+   "$VENV_DIR/bin/python" -m pip install -r "$SCRIPT_DIR/requirements.txt"
+   "$VENV_DIR/bin/python" -m pip install pytest ruff
+   "$VENV_DIR/bin/python" -m ruff check "$SCRIPT_DIR/"
+   PYTHONPATH="$SCRIPT_DIR" "$VENV_DIR/bin/python" -m pytest "$SCRIPT_DIR/tests/" -v
+   rm -rf "$VENV_DIR"
+   ```
+
+4. **Report results.** Summarize pass/fail for both ruff and pytest. If either fails, show the relevant error output so the user can fix it.
+
+5. **Clean up.** Ensure the temporary venv is removed even if validation fails.

From 9c280ad238bffe2a65efc46810ef63136fa0e38b Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:37:08 +0100
Subject: [PATCH 13/16] Add AGENTS.md platform-agnostic AI contributor guide

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 AGENTS.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a8c849d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,106 @@
+# AGENTS.md — AI Contributor Guide
+
+This file instructs AI agents (Claude Code, GitHub Copilot, Cursor, Gemini, etc.) how to contribute scripts to the agentomics repository.
+
+## Project Purpose
+
+Agentomics is a collection of standalone CLI tools built with [pyopenms](https://pyopenms.readthedocs.io/) for proteomics and metabolomics workflows. These tools fill gaps not yet covered by OpenMS/pyopenms. All code in this repo is written by AI agents.
+
+## Contribution Requirements
+
+Every script must be a **self-contained directory** under `scripts/<domain>/<tool_name>/`:
+
+```
+scripts/<domain>/<tool_name>/
+├── <tool_name>.py        # The tool itself
+├── requirements.txt      # pyopenms + any script-specific deps (no version pins)
+├── README.md             # Brief description + CLI usage examples
+└── tests/
+    ├── conftest.py       # Shared test config (see below)
+    └── test_<tool_name>.py
+```
+
+### Rules
+
+- `<domain>` is `proteomics` or `metabolomics`
+- `requirements.txt` always includes `pyopenms` with no version pin — builds against latest
+- No cross-script imports — each script is fully independent
+- No `__init__.py` files — these are NOT Python packages
+- No scripts that duplicate functionality already in OpenMS/pyopenms
+
+## Code Patterns
+
+### Script structure
+
+Every script must have:
+
+1. **Module docstring** with description, features, and usage examples
+2. **pyopenms import guard:**
+   ```python
+   import sys
+   try:
+       import pyopenms as oms
+   except ImportError:
+       sys.exit("pyopenms is required. Install it with:  pip install pyopenms")
+   ```
+3. **Importable functions** as the primary interface (with type hints and numpy-style docstrings)
+4. **`main()` function** with argparse CLI
+5. **`if __name__ == "__main__": main()`** guard
+6. **`PROTON = 1.007276`** constant where mass-to-charge calculations are needed
+
+### Test structure
+
+Every `tests/conftest.py` must contain:
+
+```python
+import sys
+import os
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+try:
+    import pyopenms  # noqa: F401
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+requires_pyopenms = pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not installed")
+```
+
+Test files:
+- Decorate test classes with `@requires_pyopenms` from conftest
+- Import script functions inside test methods: `from <tool_name> import <function>`
+- For file-I/O scripts: generate synthetic data using pyopenms objects, write to `tempfile.TemporaryDirectory()`
+
+## Validation
+
+Every script must pass validation in an **isolated venv** before it can be merged. Run these commands from the repo root:
+
+```bash
+SCRIPT_DIR=scripts/<domain>/<tool_name>
+VENV_DIR=$(mktemp -d)
+python -m venv "$VENV_DIR"
+"$VENV_DIR/bin/python" -m pip install -r "$SCRIPT_DIR/requirements.txt"
+"$VENV_DIR/bin/python" -m pip install pytest ruff
+"$VENV_DIR/bin/python" -m ruff check "$SCRIPT_DIR/"
+PYTHONPATH="$SCRIPT_DIR" "$VENV_DIR/bin/python" -m pytest "$SCRIPT_DIR/tests/" -v
+rm -rf "$VENV_DIR"
+```
+
+Both ruff and pytest must pass with zero errors.
+
+## Linting
+
+Ruff is configured in `ruff.toml` at the repo root:
+- Line length: 120
+- Rules: E (pycodestyle errors), F (pyflakes), W (pycodestyle warnings), I (isort)
+
+## What NOT to Do
+
+- Do not add cross-script imports
+- Do not add dependencies to a shared/root requirements file
+- Do not create scripts that duplicate existing pyopenms CLI tools or OpenMS TOPP tools
+- Do not pin pyopenms to a specific version
+- Do not add `__init__.py` files

From ec6b25dda2a3215e01aef6fab498c4dbcfc4f80f Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:37:42 +0100
Subject: [PATCH 14/16] Add GitHub Actions CI workflow for per-script isolated
 validation

Detects changed script directories on PR, validates each in parallel
with its own venv: pip install from script's requirements.txt, ruff lint,
pytest. Uses Python 3.11 for pyopenms wheel availability.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .github/workflows/validate.yml | 65 ++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 .github/workflows/validate.yml

diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
new file mode 100644
index 0000000..d545c8b
--- /dev/null
+++ b/.github/workflows/validate.yml
@@ -0,0 +1,65 @@
+name: Validate Scripts
+
+on:
+  pull_request:
+    paths:
+      - 'scripts/**'
+
+jobs:
+  detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.detect.outputs.matrix }}
+      has_changes: ${{ steps.detect.outputs.has_changes }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - id: detect
+        name: Detect changed script directories
+        run: |
+          # Note: github.base_ref is only available on pull_request events
+          # Find all script directories that changed in this PR
+          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- 'scripts/' \
+            | grep -oP 'scripts/[^/]+/[^/]+/' \
+            | sort -u \
+            | jq -R -s -c 'split("\n") | map(select(length > 0))')
+
+          if [ "$CHANGED" = "[]" ] || [ -z "$CHANGED" ]; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            echo "matrix=[]" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+            echo "matrix=$CHANGED" >> "$GITHUB_OUTPUT"
+          fi
+
+  validate:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.has_changes == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        script_dir: ${{ fromJson(needs.detect-changes.outputs.matrix) }}
+    name: Validate ${{ matrix.script_dir }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Create venv and install dependencies
+        run: |
+          python -m venv /tmp/validate_venv
+          /tmp/validate_venv/bin/python -m pip install -r ${{ matrix.script_dir }}requirements.txt
+          /tmp/validate_venv/bin/python -m pip install pytest ruff
+
+      - name: Lint with ruff
+        run: |
+          /tmp/validate_venv/bin/python -m ruff check ${{ matrix.script_dir }}
+
+      - name: Run tests
+        run: |
+          PYTHONPATH=${{ matrix.script_dir }} /tmp/validate_venv/bin/python -m pytest ${{ matrix.script_dir }}tests/ -v

From 9f3e0e1a31b319649dc2ebe470029aca6aee879b Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:38:25 +0100
Subject: [PATCH 15/16] Update CLAUDE.md and README.md for per-script directory
 structure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 38 ++++++++++++++++++++++++++++++++++-
 2 files changed, 97 insertions(+), 1 deletion(-)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..edf56cb
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Purpose
+
+Agentomics is a collection of standalone CLI tools built with [pyopenms](https://pyopenms.readthedocs.io/) for proteomics and metabolomics workflows. These tools fill gaps not yet covered by OpenMS/pyopenms. All code in this repo is agentic-only development — written entirely by AI agents.
+
+## Commands
+
+```bash
+# Install dependencies for a specific script
+pip install -r scripts/proteomics/peptide_mass_calculator/requirements.txt
+
+# Lint a specific script
+ruff check scripts/proteomics/peptide_mass_calculator/
+
+# Run tests for a specific script
+PYTHONPATH=scripts/proteomics/peptide_mass_calculator python -m pytest scripts/proteomics/peptide_mass_calculator/tests/ -v
+
+# Lint all scripts
+ruff check scripts/
+
+# Run a script directly
+python scripts/proteomics/peptide_mass_calculator/peptide_mass_calculator.py --sequence PEPTIDEK --charge 2
+python scripts/metabolomics/isotope_pattern_matcher/isotope_pattern_matcher.py --formula C6H12O6
+```
+
+## Architecture
+
+### Per-Script Directory Structure
+
+Each script is a self-contained directory under `scripts/<domain>/<tool_name>/`:
+
+```
+scripts/<domain>/<tool_name>/
+├── <tool_name>.py        # The tool (importable functions + argparse CLI)
+├── requirements.txt      # pyopenms + script-specific deps
+├── README.md             # Usage examples
+└── tests/
+    ├── conftest.py       # requires_pyopenms marker + sys.path setup
+    └── test_<tool_name>.py
+```
+
+Domains: `proteomics/`, `metabolomics/`
+
+### Key Patterns
+
+- pyopenms import wrapped in try/except with user-friendly error message
+- Mass-to-charge: `(mass + charge * PROTON) / charge` with `PROTON = 1.007276`
+- Every script has dual interface: importable functions + argparse CLI + `__main__` guard
+- Tests use `@requires_pyopenms` skip marker from conftest.py
+- File-I/O scripts use synthetic test data generated with pyopenms objects
+
+## Contributing
+
+See `AGENTS.md` for the full AI contributor guide. Two Claude Code skills are available:
+
+- **`contribute-script`** — guided workflow for adding a new script
+- **`validate-script`** — validate any script in an isolated venv (ruff + pytest)
diff --git a/README.md b/README.md
index fd929c9..448bbae 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,38 @@
 # agentomics
-A repository of agentic created tools in proteomics using pyopenms
+
+A repository of agentic-created tools using [pyopenms](https://pyopenms.readthedocs.io/) for proteomics and metabolomics.
+
+All code in this repo is written by AI agents. See [AGENTS.md](AGENTS.md) for the contributor guide.
+
+## Requirements
+
+```bash
+pip install pyopenms
+```
+
+## Scripts
+
+### Proteomics
+
+| Script | Description |
+|--------|-------------|
+| [`peptide_mass_calculator`](scripts/proteomics/peptide_mass_calculator/) | Monoisotopic/average masses and b/y fragment ions for peptide sequences |
+| [`protein_digest`](scripts/proteomics/protein_digest/) | In-silico enzymatic protein digestion |
+| [`spectrum_file_info`](scripts/proteomics/spectrum_file_info/) | Summary statistics for mzML files |
+| [`feature_detection_proteomics`](scripts/proteomics/feature_detection_proteomics/) | Peptide feature detection from LC-MS/MS data |
+
+### Metabolomics
+
+| Script | Description |
+|--------|-------------|
+| [`mass_accuracy_calculator`](scripts/metabolomics/mass_accuracy_calculator/) | m/z mass accuracy (ppm error) for sequences or formulas |
+| [`isotope_pattern_matcher`](scripts/metabolomics/isotope_pattern_matcher/) | Theoretical isotope distributions and cosine similarity scoring |
+| [`metabolite_feature_detection`](scripts/metabolomics/metabolite_feature_detection/) | Metabolite feature detection from LC-MS data |
+
+## Validation
+
+Each script is validated in an isolated venv. See [AGENTS.md](AGENTS.md) for validation commands.
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE).

From 6ca1237b84940522ea34f992d9d1f1c108cb0b5e Mon Sep 17 00:00:00 2001
From: Timo Sachsenberg <timo.sachsenberg@uni-tuebingen.de>
Date: Tue, 24 Mar 2026 20:42:45 +0100
Subject: [PATCH 16/16] Fix review findings: add bulk-test command, fix
 algorithm name in README

- Add 'run all tests' one-liner to CLAUDE.md
- Fix feature_detection_proteomics README to reference
  FeatureFinderAlgorithmPicked (pyopenms 3.5.0+ API)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                                 | 3 +++
 scripts/proteomics/feature_detection_proteomics/README.md | 2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index edf56cb..d889959 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,6 +21,9 @@ PYTHONPATH=scripts/proteomics/peptide_mass_calculator python -m pytest scripts/p
 # Lint all scripts
 ruff check scripts/
 
+# Run all tests across all scripts
+for d in scripts/*/*/; do PYTHONPATH="$d" python -m pytest "$d/tests/" -v; done
+
 # Run a script directly
 python scripts/proteomics/peptide_mass_calculator/peptide_mass_calculator.py --sequence PEPTIDEK --charge 2
 python scripts/metabolomics/isotope_pattern_matcher/isotope_pattern_matcher.py --formula C6H12O6
diff --git a/scripts/proteomics/feature_detection_proteomics/README.md b/scripts/proteomics/feature_detection_proteomics/README.md
index 94de59d..19522f9 100644
--- a/scripts/proteomics/feature_detection_proteomics/README.md
+++ b/scripts/proteomics/feature_detection_proteomics/README.md
@@ -1,7 +1,7 @@
 # Feature Detection for Proteomics
 
 Detect peptide isotope features in centroided LC-MS/MS data using the
-`FeatureFinderCentroided` algorithm. Output is written as a featureXML file.
+`FeatureFinderAlgorithmPicked` algorithm. Output is written as a featureXML file.
 
 ## Usage