Improve cuopt-developer skill content and sibling-skill routing

.claude-plugin/marketplace.json

@@ -12,13 +12,13 @@
       "name": "cuopt-user-rules",
       "source": "./skills/cuopt-user-rules",
       "skills": "./",
-      "description": "Base behavior rules for using NVIDIA cuOpt. Read first when helping users with cuOpt (routing, LP/MILP, QP, installation, server)."
+      "description": "Base rules for end users calling NVIDIA cuOpt (routing/LP/MILP/QP/install/server). Not for cuOpt internals — use cuopt-developer for those."
     },
     {
       "name": "cuopt-developer",
       "source": "./skills/cuopt-developer",
       "skills": "./",
-      "description": "Contribute to NVIDIA cuOpt codebase including C++/CUDA, Python, server, docs, and CI. Use when the user wants to modify solver internals, add features, submit PRs, or understand the codebase architecture."
+      "description": "Modify, build, test, debug, and contribute to NVIDIA cuOpt (C++/CUDA, Python, server, CI). Use for solver internals, PRs, DCO, and code conventions."
     },
     {
       "name": "cuopt-installation-common",
@@ -38,12 +38,6 @@
       "skills": "./",
       "description": "Install cuOpt for C — conda, locate lib/headers, verification. Use when the user is installing or verifying the C API."
     },
-    {
-      "name": "cuopt-installation-developer",
-      "source": "./skills/cuopt-installation-developer",
-      "skills": "./",
-      "description": "Developer installation — build cuOpt from source, run tests. Use when the user wants to set up a dev environment to contribute or modify cuOpt."
-    },
     {
       "name": "numerical-optimization-formulation",
       "source": "./skills/numerical-optimization-formulation",

AGENTS.md

@@ -9,8 +9,8 @@ AI agent skills for NVIDIA cuOpt optimization engine. Skills live in **`skills/`
 ## Skills directory (flat)
 
 ### Rules
-- `skills/cuopt-user-rules/` — User-facing behavior and conventions; read first when helping users with cuOpt (routing, LP, MILP, QP, install, server). Choose skills from the index below by task, problem type, and interface (Python / C / CLI).
-- `skills/cuopt-developer/` — Contributing and development; use when the user is building from source, contributing code, or working on cuOpt internals.
+- `skills/cuopt-user-rules/` — Base rules for end users calling cuOpt (routing, LP, MILP, QP, install, server). Not for cuOpt internals — see `skills/cuopt-developer/`. Read first for user-facing tasks; choose skills from the index below by task and interface.
+- `skills/cuopt-developer/` — Modify, build, test, debug, and contribute to cuOpt internals (C++/CUDA, Python, server, CI). Use for solver internals, PRs, DCO, and code conventions.
 - `skills/skill-evolution/` — Skill evolution: after solving a non-trivial problem, propose skill updates to capture generalizable learnings.
 
 ### Common (concepts only; no API code)
@@ -22,7 +22,6 @@ AI agent skills for NVIDIA cuOpt optimization engine. Skills live in **`skills/`
 ### API (implementation; one interface per skill)
 - `skills/cuopt-installation-api-python/`
 - `skills/cuopt-installation-api-c/`
-- `skills/cuopt-installation-developer/` (build from source)
 - `skills/cuopt-numerical-optimization-api-python/` (LP, MILP, QP)
 - `skills/cuopt-numerical-optimization-api-c/` (LP, MILP, QP)
 - `skills/cuopt-numerical-optimization-api-cli/` (LP, MILP, QP)

skills/cuopt-developer/resources/build_and_test.md

@@ -0,0 +1,43 @@
+# Build & Test
+
+Read this for component-level build commands, run-test commands, and `PARALLEL_LEVEL` detail. **Pre-flight checks** (CUDA driver compatibility, conda env activation, dataset setup) live in [SKILL.md → Build & Test → Pre-flight Checks](../SKILL.md#pre-flight-checks-required-before-first-build-or-test) — always run those first.
+
+## PARALLEL_LEVEL
+
+`PARALLEL_LEVEL` controls the number of parallel compile jobs. It defaults to `$(nproc)` (all cores), which can cause OOM on machines with limited RAM — CUDA compilation needs roughly 4–8 GB per job. Set it based on available RAM:
+
+```bash
+export PARALLEL_LEVEL=8   # adjust based on available RAM
+```
+
+## Build Everything
+
+```bash
+./build.sh
+```
+
+## Build Specific Components
+
+```bash
+./build.sh --help                                       # Lists build options
+./build.sh libcuopt                                     # C++ library
+./build.sh libmps_parser libcuopt --skip-routing-build --skip-tests-build --skip-c-python-adapters --cache-tool=ccache  # native LP/MIP-focused build without routing/tests/adapters
+./build.sh cuopt                                        # Python package
+./build.sh cuopt_server                                 # Server
+./build.sh docs                                         # Documentation
+```
+
+## Run Tests
+
+> Activate the conda env used to build first (`conda activate <env-name>`) and ensure datasets are fetched — see [Pre-flight Checks](../SKILL.md#pre-flight-checks-required-before-first-build-or-test) in SKILL.md.
+
+```bash
+# C++ tests
+ctest --test-dir cpp/build
+
+# Python tests
+pytest -v python/cuopt/cuopt/tests
+
+# Server tests
+pytest -v python/cuopt_server/tests
+```

skills/cuopt-developer/resources/contributing.md

@@ -0,0 +1,96 @@
+# Contributing — Commits, PRs, and Common Tasks
+
+Read this for anything related to committing, pushing, opening PRs, or making structural changes to cuOpt (adding a solver parameter, dependency, server endpoint, or CUDA kernel).
+
+## Before You Commit
+
+### 1. Install Pre-commit Hooks
+
+Run once per clone to have style checks run automatically on every `git commit`:
+
+```bash
+pre-commit install
+```
+
+If a hook fails, the commit is blocked — fix the issues and commit again. To check all files manually (e.g., before pushing), run `pre-commit run --all-files --show-diff-on-failure`.
+
+### 2. Make Meaningful Commits
+
+Group related changes into logical commits rather than committing all files at once. Each commit should represent one coherent change (e.g., separate the C++ change from the Python binding update from the test addition). This makes `git log` and `git bisect` useful for debugging later.
+
+### 3. Sign Your Commits (DCO Required)
+
+```bash
+git commit -s -m "Your message"
+```
+
+To fix a prior commit missing the sign-off, use `git commit --amend -s` (or an interactive rebase for older commits). Do **not** use `--no-verify` to bypass the DCO check.
+
+### 4. Use Forks for Pull Requests
+
+Never push branches directly to the main cuOpt repository. Use the fork workflow:
+
+```bash
+# 1. Clone the main repo
+git clone git@github.com:NVIDIA/cuopt.git
+cd cuopt
+
+# 2. Add your fork as a remote
+git remote add fork git@github.com:<your-username>/cuopt.git
+
+# 3. Create a branch from the appropriate base
+git checkout -b my-feature-branch
+
+# 4. Make changes, commit, then push to your fork
+git push fork my-feature-branch
+
+# 5. Create PR from your fork → upstream base branch
+```
+
+This applies to both human contributors and AI agents. Agents must never push to the upstream repo directly — provide the push command for the user to review and execute from their fork.
+
+### Pull Requests Created by Agents
+
+When an AI agent creates a pull request, it **must be a draft PR** (`gh pr create --draft`). This gives the developer time to review and iterate on the changes before any reviewers get pinged. The developer marks it as ready for review when satisfied.
+
+### PR Descriptions
+
+Keep PR summaries **short and informative**. State what changed and why in a few bullet points. Avoid verbose explanations, full file listings, or restating the diff. Reviewers read the code — the summary should give them context, not a transcript.
+
+## Common Tasks
+
+### Adding a Solver Parameter
+
+1. Add to settings struct in `cpp/include/cuopt/` and wire into `set_parameter_from_string()` in `cpp/src/`
+2. Expose in Python — if using the string-based interface, the parameter is auto-discovered (no `.pyx` change needed). Add a convenience method in `SolverSettings` if warranted. See [python_bindings.md](python_bindings.md) for the full checklist.
+3. Add to server schema (`docs/cuopt/source/cuopt_spec.yaml`) if applicable
+4. Add tests at C++ and Python levels
+5. Rebuild: `./build.sh libcuopt && ./build.sh cuopt`
+6. Update documentation
+
+### Adding a Dependency
+
+All dependencies are managed through `dependencies.yaml` — never edit `conda/environments/*.yaml` or `pyproject.toml` files directly. The file uses [RAPIDS dependency-file-generator](https://github.com/rapidsai/dependency-file-generator) format:
+
+1. Find the appropriate group in `dependencies.yaml` (e.g., `build_cpp`, `run_common`, `test_python_common`)
+2. Add the package under the correct `output_types` (`conda`, `requirements`, `pyproject`, or a combination)
+3. Run `pre-commit run --all-files` — the RAPIDS dependency file generator hook regenerates downstream files automatically
+4. Verify: check that `conda/environments/` and relevant `pyproject.toml` files were updated
+
+### Adding a Server Endpoint
+
+1. Add route in `python/cuopt_server/cuopt_server/webserver.py`
+2. Update OpenAPI spec `docs/cuopt/source/cuopt_spec.yaml`
+3. Add tests in `python/cuopt_server/tests/`
+4. Update documentation
+
+### Modifying CUDA Kernels
+
+1. Edit kernel in `cpp/src/`
+2. Follow stream-ordering patterns
+3. Run C++ tests: `ctest --test-dir cpp/build`
+4. Run benchmarks to check performance
+
+## Third-Party Code
+
+**Always ask before including external code.** When copying or adapting external code, you must attribute it properly, verify license compatibility, and flag it in the PR. See the [Third-Party Code section in CONTRIBUTING.md](../../../CONTRIBUTING.md#third-party-code) for the full process.

skills/cuopt-developer/resources/conventions.md

@@ -0,0 +1,81 @@
+# Coding Conventions, Error Handling, and Memory Management
+
+Read this for cuOpt code style: naming, file extensions, include order, error handling, memory management, and test impact.
+
+## C++ Naming
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Variables | `snake_case` | `num_locations` |
+| Functions | `snake_case` | `solve_problem()` |
+| Classes | `snake_case` | `data_model` |
+| Test cases | `PascalCase` | `SolverTest` |
+| Device data | `d_` prefix | `d_locations_` |
+| Host data | `h_` prefix | `h_data_` |
+| Template params | `_t` suffix | `value_t` |
+| Private members | `_` suffix | `n_locations_` |
+
+## File Extensions
+
+| Extension | Usage |
+|-----------|-------|
+| `.hpp` | C++ headers |
+| `.cpp` | C++ source |
+| `.cu` | CUDA source (nvcc required) |
+| `.cuh` | CUDA headers with device code |
+
+## Include Order
+
+1. Local headers
+2. RAPIDS headers
+3. Related libraries
+4. Dependencies
+5. STL
+
+## Python Style
+
+- Follow PEP 8
+- Use type hints
+- Tests use pytest
+
+## Error Handling
+
+### Runtime Assertions
+
+```cpp
+CUOPT_EXPECTS(condition, "Error message");
+CUOPT_FAIL("Unreachable code reached");
+```
+
+### CUDA Error Checking
+
+```cpp
+RAFT_CUDA_TRY(cudaMemcpy(...));
+```
+
+## Memory Management
+
+```cpp
+// ❌ WRONG
+int* data = new int[100];
+
+// ✅ CORRECT - use RMM
+rmm::device_uvector<int> data(100, stream);
+```
+
+- All operations should accept `cuda_stream_view`
+- Views (`*_view` suffix) are non-owning
+
+Read existing code in `cpp/src/` for real examples of RMM allocation, stream-ordering, RAFT utilities, and kernel launch patterns.
+
+## Test Impact Check
+
+**Before any behavioral change, ask:**
+
+1. What scenarios must be covered?
+2. What's the expected behavior contract?
+3. Where should tests live?
+   - C++ gtests: `cpp/tests/`
+   - Python pytest: `python/.../tests/`
+
+**Add at least one regression test for new behavior.**

skills/cuopt-developer/resources/first_time_setup.md

@@ -0,0 +1,32 @@
+# First-Time Dev Environment Setup
+
+Read this when a contributor is setting up the cuOpt dev environment for the first time — clone, conda env, initial build, initial test run. Once that's working, the rest of `cuopt-developer` (build/test commands, conventions, contribution workflow) takes over.
+
+## Required questions
+
+Ask these before issuing commands:
+
+1. **OS and GPU** — Linux? Which CUDA version does the GPU driver support (run `nvidia-smi`, top-right "CUDA Version")?
+2. **Goal** — Contributing upstream, or local fork/modification?
+3. **Component** — C++/CUDA core, Python bindings, server, docs, or CI?
+
+The component answer scopes which part of the codebase to read first and which build target to use (e.g. `./build.sh libcuopt` vs `./build.sh cuopt`).
+
+## Setup walk-through (conceptual)
+
+1. **Clone** the cuOpt repo (and submodules, if any).
+2. **Pre-flight checks** — CUDA driver compatibility, conda env selection and activation, `PARALLEL_LEVEL`, dataset setup. Walk through these before the first build using SKILL.md → [Pre-flight Checks](../SKILL.md#pre-flight-checks-required-before-first-build-or-test). Skipping any of them surfaces as confusing build- or runtime errors later.
+3. **First build** — once the env is active, run `./build.sh` (or a component-scoped variant). Targets and `PARALLEL_LEVEL` tuning live in [build_and_test.md](build_and_test.md).
+4. **First test run** — fetch datasets per `CONTRIBUTING.md` first, then run the C++/Python test suites from [build_and_test.md](build_and_test.md). A passing build + test confirms the env is wired up correctly.
+5. **Optional** — `pre-commit install` to run style checks on every `git commit` (see [contributing.md](contributing.md)).
+
+Use the repo's `README` and `CONTRIBUTING.md` as the canonical source for exact versions and any deviations.
+
+## After setup
+
+Once `./build.sh` and the test suites succeed, the env is verified. From here, ongoing build/test/debug/contribute work is covered by the rest of `cuopt-developer`:
+
+- Build/test commands and `PARALLEL_LEVEL` — [build_and_test.md](build_and_test.md)
+- Pre-commit, DCO sign-off, fork PR workflow — [contributing.md](contributing.md)
+- C++/Python/CUDA naming, memory, testing conventions — [conventions.md](conventions.md)
+- Build/CI failure diagnosis — [troubleshooting.md](troubleshooting.md)

skills/cuopt-developer/resources/troubleshooting.md

@@ -0,0 +1,25 @@
+# Troubleshooting & CI Gotchas
+
+Read this when a build, test, or CI step fails — symptoms, causes, fixes.
+
+## Common Pitfalls
+
+| Problem | Solution |
+|---------|----------|
+| Cython changes not reflected | Rerun: `./build.sh cuopt` |
+| Missing `nvcc` | Set `$CUDACXX` or add CUDA to `$PATH` |
+| OOM during build | Lower `PARALLEL_LEVEL` (e.g., `export PARALLEL_LEVEL=8`) |
+| CUDA out of memory | Reduce problem size |
+| Build fails with CUDA errors on older driver | Conda installs `cuda-nvcc` for the latest supported CUDA (e.g., 13.1), but the user's GPU driver may not support it. Have the user check with `nvidia-smi` — the top-right shows max CUDA version. Provide this command for the user to run (do not run it yourself): `conda install cuda-nvcc=12.9` (or whichever version their driver supports). See [CUDA compatibility matrix](https://docs.nvidia.com/deploy/cuda-compatibility/) |
+| Slow debug library loading | Device symbols cause delay |
+
+## CI Gotchas
+
+| Failure | Cause | Fix |
+|---------|-------|-----|
+| Style check | Formatting drift | Run `pre-commit run --all-files` and commit fixes |
+| DCO sign-off | Missing `-s` flag | `git commit --amend -s` (or rebase to fix older commits) |
+| Dependency mismatch | Edited `pyproject.toml` or `conda/environments/` directly | Edit `dependencies.yaml` instead, let pre-commit regenerate |
+| Skill validation | Missing frontmatter or version mismatch | Run `./ci/utils/validate_skills.sh` locally to diagnose |
+
+For CI scripts and pipeline details, see [ci/README.md](../../../ci/README.md).