Make a repository ready

Goal

This example assumes you have completed Get started with Particle Life: skills loaded, CLI authenticated, Git key available, and a compatible runner online.

Unlike the basic example, this lab starts from a branch without a Discovery-ready benchmark. You will fork it, author a harness that writes artemis_results.json, push, import your fork, and run a short Discovery.

What you will learn

• when a repository is not yet Artemis-ready;
• how to author a headless harness that emits numeric metrics;
• how to verify compile → test → benchmark before import; and
• how to run Discovery against a repository you own.

Teaching seed

Use the public lab branch:

https://github.com/turintech/particle-life
branch: lab/no-benchmark
commit: 92b0b7d0e55f39361d7f5d01cc37d19932213237

That revision keeps CMake, the simulation library, checksum tests, and a timed ./build/particle_life benchmark path that prints fps= to stdout. It does not provide tools/benchmark.py or write artemis_results.json.

1. Fork and clone the lab branch

Skill: repo-prepare-fork

Ask the assistant to fork turintech/particle-life under your account (explicit permission required), then clone your fork and check out lab/no-benchmark at the commit above.

gh repo fork turintech/particle-life --clone=true
cd particle-life
git fetch origin lab/no-benchmark
git checkout lab/no-benchmark
git rev-parse HEAD   # expect 92b0b7d0e55f39361d7f5d01cc37d19932213237

Checkpoint: the checkout is your fork, on lab/no-benchmark, at the lab commit.

2. Author the harness

Skill: repo-command-setup (companion HARNESS.md)

Ask the assistant to add a repository-owned headless script (typically tools/benchmark.py) that:

1. requires build/particle_life;
2. removes any stale artemis_results.json / .csv;
3. runs a timed workload equivalent to 2,200 particles and 30 frames after warmup (wrapping ./build/particle_life benchmark 2200 30 is fine);
4. writes numeric {"simulation_fps": ...} to artemis_results.json at the repository root;
5. stays headless — no visualization window.

Keep ctest as the correctness gate. Do not weaken checksum determinism to chase speed.

Checkpoint: the harness exists in the working tree and is ready to verify.

3. Verify the three commands

Skill: repo-command-setup

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel
ctest --test-dir build --output-on-failure
rm -f artemis_results.json artemis_results.csv
python3 tools/benchmark.py --no-visualize   # or the script path you chose
test -f artemis_results.json

Confirm artemis_results.json contains a numeric simulation_fps. Record the exact compile, test, and benchmark command strings for Discovery.

Checkpoint: all three commands pass from the repository root and the results file is fresh and numeric.

4. Push, then import your fork

Push the harness commit to your fork:

git add tools/benchmark.py   # plus any supporting files
git commit -m "Add Discovery-ready simulation_fps harness"
git push -u origin lab/no-benchmark

Skill: project-import

Import the fork URL and lab/no-benchmark branch — not upstream main:

artemis project import \
  --git-url https://github.com/<your-account>/particle-life \
  --key-id <key-id> \
  --branch lab/no-benchmark \
  --name particle-life-harness-lab

Wait until importedStatus is success, then confirm the imported gitHash matches your harness commit.

Checkpoint: Artemis project UUID exists and points at your harness revision.

5. Run a short Discovery

Skills: discovery-start, then discovery-inspect

artemis discovery create \
  --project <project-id> \
  --task "Maximize simulation_fps without changing simulation behavior or weakening the correctness tests." \
  --versions 5 \
  --compile-cmd "cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel" \
  --test-cmd "ctest --test-dir build --output-on-failure" \
  --benchmark-cmd "python3 tools/benchmark.py --no-visualize" \
  --target-files src/simulation.cpp \
  --target-files src/simulation.hpp \
  --runner <runner-name> \
  --mode automatic \
  --model <model-catalogue-uuid>

Use the same verified commands inline. Monitor with discovery get / versions list until the baseline is finalised and at least one version has measured simulation_fps.

Checkpoint: Discovery ran on your user-owned harness; rank candidates by measured simulation_fps, not only fitness.

What to expect

• The lab teaches the Artemis metrics contract: stdout timing alone is not enough.
• First harness drafts often forget headless mode, stale results files, or writing at the repo root — local verification catches those before import.
• Discovery is still stochastic; a successful lab proves the repository is ready, not that every run finds a large speedup.

Optional next steps

• Verifying commands on a runner when you must iterate commands on the runner and pull script fixes into the project.
• Steer a running discovery to redirect a live run and expand its budget.
• Adapt the same harness pattern to your own repository: choose a metric, add a correctness gate, emit artemis_results.json, verify, import, discover.