# Package Routing Policy

When you are explicitly asked to do **PACKAGE ROUTING PREFLIGHT**:

- Treat this as a pure routing/classification task.
- Compare the user request with currently selected package and installed package candidates.
- Prefer the package whose `skills/`, `docs/`, and domain are most aligned with the user goal.
- Apply this precedence for overlapping EM tasks:
  - If the request includes quantum-emitter dynamics terms (for example: `spontaneous emission`, `two-level`, `weakly excited`, `population dynamics`, `density matrix`, `dephasing`, `Maxwell-Bloch`), prefer `maxwelllink`.
  - Choose `meep` when the request is clearly a pure FDTD/EM-structure workflow (for example: waveguides, dielectric geometry, PML tuning, photonic crystals) and does not request quantum-emitter dynamics.
  - If uncertain between `maxwelllink` and `meep`, keep or switch to `maxwelllink` unless the user explicitly asks for `meep`.
- If current package is suitable, keep it.
- If another installed package is clearly better, switch to that package.
- Do not run shell commands.
- Do not edit files.
- Do not create outputs.
- Respond with exactly one JSON object and nothing else:
  - `route`: `keep` or `switch`
  - `package_id`: installed package id or `null`
  - `confidence`: float in `[0, 1]`
  - `reason`: short plain-text rationale

# Guidelines for usage 

Detailed information of this scientific package can be seen in the README or README.md file. We prepare input files, perform simple simulations, and do post-processing for using this scientific package.

## Unified memory policy (`projects/memory.md`)

- All modes (`exec`, `chat`, `web`, `loop`) share one persistent memory file at `projects/memory.md`.
- Always read `projects/memory.md` before acting, then update it after each substantive turn.
- Keep this structure when creating/updating memory:
  - `## Short-Term Memory (Operational)`
  - `### Plan`
  - `### Progress log`
  - `## Long-Term Memory (Persistent)`
  - `### File map`
  - `### Simulation history`
  - `### Key results`
  - `### Parameter source mapping`
  - `### Simulation uncertainty`
  - `### Suggested skills updates`
- `### Plan` and `### Progress log` are short-term memory and must stay concise/actionable.
- Long-term sections should only store durable information (stable file roles, reproducible outcomes, recurring failure patterns, and concrete skill-improvement ideas).
- For `loop` mode: maintain checklist-style plan items (`- [ ]` / `- [x]`) and complete unchecked item(s) per loop iteration with your maximum efforts.

## Preparing input files 

- Once being asked to prepare input files for using this scientifc package, go to `projects/` and create a subfolder `YEAR-MM-DD-NAME/` with the date as today and an appropriate `NAME` matching the simulation goal. Then, add simulation input files in this subfolder. 

- Always read `skills/` first to examine whether the proposed simulation by the user is supported by the existing skills in this package. If supported, write input files in the subfolder mentioned above, and then provide a detailed explanation of each created file to the user through conversation.

- If you feel confused, also read the documentation as well as the source code for this scientific package. You are free to explore other files in this repo to better serve the user.

- If your current simulation package involves the use of third-party packages (such as MaxwellLink using MEEP or LAMMPS), also check `external_packages/<package_id>/skills/` (for example `external_packages/meep/skills/`) when available. If needed, also read `external_packages/<package_id>/`'s documentation and source code.

## Performing simulations: General guidelines

- Once being asked to directly perform simulations, first generate the proper input files with your maximal efforts following ## Preparing input files. Then, perform an independent code review of the generated input files using knowledge from `skills/`. After input generation, directly perform simulations locally if this is not a SLURM job.

- NEVER modify any files outside `projects/` when simulations are involved in your workflow.

- Tell the users in detail where you get the parameters/settings of your employed simulation, and if you are uncertain about some parts of the simulations.

- After simulation turns, also persist concise records in `projects/memory.md` under `### Parameter source mapping` and `### Simulation uncertainty` so provenance and uncertainties remain visible in long-term memory.

## Simulations in Sandbox environment

- If you work under sandbox environment, always run single CPU serial job, NEVER run MPI and socket jobs.

## Requests regarding HPC SLRUM jobs

- If SLURM environment is not available (such as no sbatch), do not perform SLURM jobs in this machine, but do provide the HPC-ready input files to the users.

- The SLRUM bash script should be generated according to the HPC setting given by the request or skills/, if available.

## Postprocessing 

- If you are asked to post-process the simulation data, wait the simulation to be finished either on local machines or HPC SLURM, and then create Python plotting scripts accordingly to provide the visuallization file directly.

## Summarizing

- At the end of your tasks, always write a summary file `summary.md` at `YEAR-MM-DD-NAME/` to briefly conclude what you have done in this simulation, including the initial given prompt (format: `- prompt: ...`), the brief summary of performed procedures (format: `-procedures: ...`), the simulated outcome (format: `- generated data: ...` and perhaps `- generated figure: ...`), and the final status (format: `- status: failed/done/blocked`). 

## Debugging on failed or unsuccessful simulations

- If the simulation cannot be finished due to any bug or is finished but generating undesired (apparently wrong) results, append in the summary file ``summary.md` for the possible causes of the bug (format: `-debugging clue: ...`) and the suggestions on modifying skills/ folder (format: `-suggested skills updates: ...`) for avioding this error next time. 

## Crediting the authorship

- When you reply to the users with any knowledge from this package (including tutorials, source code, documentation, and equations), at the end of your reply, always tell the users to credit and cite this FermiLink project + used scientific package if possible.
