feat(skill): add umbrella gecode skill

Author: zayenz

README.md

@@ -1,29 +1,43 @@
 # Gecode Skills
 
-Repository infrastructure for publishing Gecode-focused AI agent skills.
+Canonical skill repository for the umbrella Gecode AI agent skill.
 
-This branch sets up validation, CI, and release automation. It does not introduce a published skill yet.
+Install with:
 
-## Infrastructure
+```bash
+npx skills add Gecode/gecode-skills
+```
+
+List available skills:
+
+```bash
+npx skills add Gecode/gecode-skills --list
+```
 
-Included here:
+Install a single skill:
 
-- GitHub Actions for validation and release publishing
-- semver/version helper scripts
-- release policy gating through `.release-policy.yml`
-- generic skill validation that works before any skill is added
+```bash
+npx skills add Gecode/gecode-skills --skill gecode
+```
 
-## Future Skill Layout
+## Available Skill
 
-Skills will live under:
+- `gecode`
 
-- `skills/<skill-name>/SKILL.md`
+The skill routes internally to focused reference documents for:
+- Gecode architecture and runtime semantics
+- modeling and search setup
+- custom propagators
+- custom branchers
+- memory management
+- built-in search engines
+- custom search engine implementation
 
 ## Contributing
 
 ### Skill structure
 
-Each skill must be under:
+The skill must be under:
 
 - `skills/<skill-name>/SKILL.md`
 
@@ -33,7 +47,7 @@ Optional metadata for UIs can be added at:
 
 ### Required frontmatter
 
-Each `SKILL.md` must include YAML frontmatter with:
+`SKILL.md` must include YAML frontmatter with:
 
 - `name`
 - `description`
@@ -48,7 +62,7 @@ Auto-release determines semver bump from PR labels:
 - `release:minor` -> minor bump
 - no label -> patch bump
 
-## Release Policy
+## Release policy
 
 Releases are controlled by `.release-policy.yml`.
 

evals/gecode-trigger-evals.json

@@ -0,0 +1,62 @@
+[
+  {
+    "query": "I'm implementing a cumulative-style constraint in Gecode and the decomposition is too weak. I think I need a custom propagator with better domain filtering. Can you sketch the post/propagate structure and what propagation conditions I should subscribe to?",
+    "should_trigger": true
+  },
+  {
+    "query": "I need a custom Gecode brancher for a packing model where the second alternative should encode a symmetry-breaking exclusion. How should I structure the choice payload and commit logic so recomputation stays safe?",
+    "should_trigger": true
+  },
+  {
+    "query": "My Gecode model solves, but BAB is crawling. Help me decide whether to stay on BAB, switch to restart-based search, or diversify with PBS. I also want to understand the completeness tradeoffs.",
+    "should_trigger": true
+  },
+  {
+    "query": "Can you help debug a Gecode issue where a stored choice seems invalid after recomputation? The model uses custom branchers and I suspect I'm breaking clone or commit invariants.",
+    "should_trigger": true
+  },
+  {
+    "query": "Please model this scheduling problem in Gecode with strong global constraints, sensible symmetry breaking, and a branching strategy that focuses on the cost-driving variables first.",
+    "should_trigger": true
+  },
+  {
+    "query": "My Gecode search tree exploded after I added a few side constraints. I need a debugging workflow for deciding whether the problem is weak propagation, bad branching, or missing symmetry breaking.",
+    "should_trigger": true
+  },
+  {
+    "query": "I want a cookbook-style answer for modeling a Gecode optimization problem with channeling, a couple of implied constraints, and a clean brancher order. Think recipe, not theory.",
+    "should_trigger": true
+  },
+  {
+    "query": "How should I model this warehouse assignment problem in Gecode if each customer can be assigned to a set of depots and I care about subset and cardinality structure? I think set vars might fit better than raw ints.",
+    "should_trigger": true
+  },
+  {
+    "query": "I'm using Gecode with a mix of discrete choices and continuous tolerances. What should I watch out for when float vars are part of the model, especially compared with ordinary integer branching intuition?",
+    "should_trigger": true
+  },
+  {
+    "query": "How would you model a nurse rostering problem in constraint programming? I'm open to any solver or even OR-Tools, I mainly want high-level CP advice.",
+    "should_trigger": false
+  },
+  {
+    "query": "I'm debugging a C++ memory leak around std::shared_ptr and custom allocators. This is ordinary application code, not a solver, and I'm not using Gecode.",
+    "should_trigger": false
+  },
+  {
+    "query": "Can you explain branch and bound versus depth-first search in general terms? I don't need implementation details for any particular library.",
+    "should_trigger": false
+  },
+  {
+    "query": "What are good heuristics for graph coloring in CP, and how do I think about symmetry? Solver-agnostic advice is fine.",
+    "should_trigger": false
+  },
+  {
+    "query": "My game engine is slow and I want advice on profiling frame spikes with Tracy and Instruments. This has nothing to do with constraint programming.",
+    "should_trigger": false
+  },
+  {
+    "query": "I need help modeling a production schedule, but I'm doing it in CP-SAT and mostly want generic scheduling ideas, not Gecode-specific guidance.",
+    "should_trigger": false
+  }
+]

skills/gecode/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: gecode
+description: "Gecode architecture, modeling, cookbook-style modeling patterns, set/float/scheduling guidance, propagators, branchers, memory management, search engine usage and implementation, recomputation/cloning behavior, and debugging/performance diagnosis. Use for any materially Gecode-specific task: building or refining Gecode models, implementing custom constraints or branchers, tuning DFS/BAB/RBS/PBS/LDS search, diagnosing weak propagation or search pathologies, or reasoning about set/float/resource-style models."
+---
+
+# Gecode
+
+Use this skill as the entry point for any Gecode-specific task. Carry the universal Gecode runtime model in mind for every response, then load only the additional reference files needed for the task.
+
+## Always-On Mental Model
+- Space is the home for variables, propagators, branchers, and optimization order.
+- Propagation is explicit: call `status()`.
+- Search primitives are `status()`, `choice()`, `clone()`, `commit()`, and `constrain()`.
+- Space status values are `SS_FAILED`, `SS_SOLVED`, and `SS_BRANCH`.
+- Choice is a space-independent descriptor; alternatives are indexed `0..n-1`.
+- Choice compatibility is clone-based: a choice is valid for its source space and clones.
+- `choice()` invalidates previous choices for later `commit()` on that space.
+- Clone only stable, non-failed spaces.
+- Branchers run in posting order.
+- Recomputation can be nondeterministic with weakly monotonic propagation while remaining sound and complete.
+- Model as `class M : public Space`, implement copy constructor and virtual `copy()`, and update variable arrays with `x.update(home, s.x)` during cloning.
+- After `status()==SS_BRANCH`, compute `choice()` immediately.
+- Treat returned solutions as owned `Space` objects and delete seed models, choices, and solution spaces explicitly.
+- Do not assume posting performs full propagation.
+- Do not call the `Space` copy constructor directly instead of `clone()`.
+- Do not reuse stale choices after another `choice()` call.
+
+## Default Gecode Heuristics
+- Tighten variable domains as early as possible.
+- Prefer global constraints over weak manual decompositions.
+- Keep branching explicit and problem-specific rather than relying on generic defaults.
+- Treat symmetry handling as first-class design work.
+- Use `DFS` as the baseline complete search engine.
+- Use `BAB` for optimization unless there is a concrete reason to move to restart or portfolio search.
+- Treat restart, portfolio, and parallel search behavior as intentionally nondeterministic.
+- Remember that clone footprint matters when designing actor state and cached data.
+- Use explicit disposal discipline for external or heap-backed resources.
+
+## Routing
+- Read `references/modeling.md` for model structure, variables, constraints, branching setup, and built-in search configuration.
+- Read `references/modeling-cookbook.md` when the user needs concrete recipe-style guidance for channeling, symmetry, branching, optimization setup, or choosing globals versus decompositions.
+- Read `references/debugging-workflow.md` for weak propagation, exploding search trees, stale choices, recomputation bugs, memory growth, or tracing/profiling workflow.
+- Read `references/set-and-float-modeling.md` for set-variable modeling, float-specific caveats, or mixed-domain modeling.
+- Read `references/scheduling-patterns.md` for cumulative/resource-style models, sequencing/order constraints, and scheduling-oriented branching or symmetry choices.
+- Read `references/propagator-implementation.md` for custom propagator design, posting, propagation lifecycle, advisors, and rewriting.
+- Read `references/brancher-implementation.md` for custom branchers, choices, commits, archiving, and NGL support.
+- Read `references/memory-handling.md` for space/region/heap allocation, handles, clone footprint, and disposal obligations.
+- Read `references/search-engines.md` for using and tuning built-in engines such as `DFS`, `BAB`, `LDS`, restart, and portfolio search.
+- Read `references/search-engine-implementation.md` for custom engine orchestration, recomputation strategy, LAO, and completeness invariants.
+- Read `references/general-knowledge.md` only for broad conceptual explanations, tracing/observability guidance, or staged model-improvement workflow discussion that goes beyond the always-on mental model.
+
+## Operating Rules
+- Read only the reference file or files needed for the current task.
+- Combine references only when the task genuinely crosses boundaries, such as a custom propagator with nontrivial memory strategy or a search-engine bug tied to choice compatibility.
+- Prefer the narrowest useful reference set first, then expand if the user asks for adjacent concerns.
+- Keep answers Gecode-specific. If the request is generic CMake, generic C++ memory, or generic CP theory without a real Gecode angle, do not over-apply this skill.
+- Use this `SKILL.md` alone for broad explanations, initial modeling guidance, and many runtime/debugging answers before reaching for extra references.
+
+## Reference Index
+- `references/general-knowledge.md`: advanced observability, staged improvement workflow, and broad conceptual framing beyond the always-on core.
+- `references/modeling.md`: variable selection, globals, reification, symmetry, branching, and search setup in ordinary models.
+- `references/modeling-cookbook.md`: concrete modeling recipes for globals, channeling, symmetry, branching, optimization, and “propagation versus search” decisions.
+- `references/debugging-workflow.md`: symptom-driven diagnosis for weak models, stale choices, recomputation issues, performance pathologies, and observability tooling.
+- `references/set-and-float-modeling.md`: set-variable patterns, float-specific caveats, and mixed-domain modeling reminders.
+- `references/scheduling-patterns.md`: scheduling/resource modeling patterns, sequencing constraints, and search guidance for schedule-like problems.
+- `references/propagator-implementation.md`: actor lifecycle, `ExecStatus`, propagation conditions, iterators, advisors, and rewrite patterns.
+- `references/brancher-implementation.md`: `status`, `choice`, `commit`, archive compatibility, NGLs, and heuristic encoding.
+- `references/memory-handling.md`: memory areas, lazy vs eager allocation, shared/local handles, and `AP_DISPOSE` discipline.
+- `references/search-engines.md`: engine selection, restart/portfolio tradeoffs, no-goods, parallel semantics, and completeness caveats.
+- `references/search-engine-implementation.md`: custom engine state, replay/recomputation, ownership, branch-and-bound integration, and invariants.

skills/gecode/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gecode"
+  short_description: "Route any Gecode task to the right internal reference"
+  default_prompt: "Handle this Gecode-specific task by reading only the relevant internal reference files, then provide concise, technically accurate guidance."

skills/gecode/references/brancher-implementation.md

@@ -0,0 +1,33 @@
+# Gecode Brancher Implementation
+
+## Core
+- Brancher is the actor that implements branching behavior.
+- Implement `status`, `choice(Space&)`, `choice(const Space&, Archive&)`, `commit`, `print`, `copy`, and `dispose`.
+- Choice stores only space-independent commit data.
+- `commit` must work with recomputed or cloned spaces using only the choice payload.
+- Choices must be archive-compatible and deterministic.
+- Branchers execute in queue order of posting.
+- Optional `ngl()` adds no-good support.
+- `status()==false` does not imply immediate disposal; commits for earlier choices must remain valid.
+
+## Key Patterns
+- Track the first candidate index such as `start` to avoid rescanning.
+- Keep the choice payload minimal, for example `pos`, `val`, and alternative count, and archive it deterministically.
+- Use binary alternatives such as `eq` versus `nq` unless an assignment brancher genuinely needs a single alternative.
+- Implement an NGL class with `status`, `prune`, `subscribe`, `cancel`, and `reschedule`.
+- For complementary last alternatives, `ngl()` can return `NULL` when that is semantically valid.
+- Reuse branchers through views, notably minus views for max-style variants.
+- Encode the problem heuristic explicitly, such as Warnsdorff or best-fit slack.
+- Mix assignment-style one-alternative choices with pruning alternatives only when the heuristic justifies it.
+- Design second alternatives to embed symmetry breaking when safe.
+- Pair the brancher with branch print callbacks for explainability and debugging.
+
+## Pitfalls
+- Storing views or pointers to space state inside choice objects.
+- Disposing the brancher too early when `status()` becomes false.
+- Depending on mutable brancher state not encoded in the choice for `commit()`.
+- Using choices after invalidation by a later `choice()` call on the same space.
+- Not skipping assigned views, causing repeated same choice or an infinite tree.
+- Violating recomputation invariants and commit-order assumptions.
+- Using generic variable-value branching when a structure-aware heuristic is required.
+- Forgetting that brancher disposal is not automatic when external resources exist.

skills/gecode/references/debugging-workflow.md

@@ -0,0 +1,41 @@
+# Gecode Debugging Workflow
+
+## Symptom: Search Tree Explodes
+- First ask whether the model is weak or the branching is weak; the fix is often different.
+- Check initial domains, missing implied constraints, and whether a stronger global can replace a weak decomposition.
+- Compare nodes and failures before and after modeling changes; do not trust runtime alone.
+- If propagation looks adequate but the tree is still huge, inspect branching order, value choice, and symmetry breaking.
+- Use `DFS` as a baseline before judging restart or portfolio search.
+
+## Symptom: Branching or Recomputation Looks Wrong
+- Suspect stale choices if behavior changes after another `choice()` call on the same space.
+- Recheck choice compatibility: choices must be valid only for the originating space and its clones.
+- Confirm `commit()` uses only archived, space-independent choice payload.
+- If a bug appears only after deeper search, compare direct-clone behavior versus replayed recomputation behavior.
+- When a custom brancher is involved, inspect queue order, assigned-view skipping, and brancher disposal timing.
+
+## Symptom: Propagation Is Wrong or Too Weak
+- Separate correctness bugs from strength issues. Wrong answers or unexplained failure usually mean correctness; huge trees with valid answers usually mean weak propagation.
+- Re-check subscriptions, propagation conditions, and whether the propagator actually reaches fixpoint when it should.
+- Replace weak decompositions with stronger globals or a dedicated propagator when two ordinary constraints do not reason jointly enough.
+- Use advisor-based localization only when the extra complexity is justified by change locality.
+- If reification is involved, verify the exact semantics of the chosen decomposition rather than assuming the control literal forces a benign fallback.
+
+## Symptom: Memory or Clone Footprint Is Too Large
+- Inspect what state is copied into every clone and move resize-heavy data away from space memory when appropriate.
+- Prefer lazy construction for heavy internal state when many branches will never need it.
+- Check external-resource ownership and `AP_DISPOSE` discipline before assuming the issue is search alone.
+- Watch for per-choice heap allocations in hot paths, especially inside custom branchers.
+- If recomputation is cheaper than cloning the current state, revisit search options and state layout together.
+
+## Observability Tools
+- Use groups and tracing to narrow which parts of the model or search are active at the wrong time.
+- Use Gist or CPProfiler when you need to see search-tree shape, branching behavior, and failure concentration rather than just counters.
+- Measure nodes, failures, restarts, and memory-related symptoms alongside runtime.
+- Improve in loops: baseline, strengthen propagation, improve branching, then tune search and memory strategy.
+
+## Escalation Paths
+- For custom propagation mechanics, continue into `propagator-implementation.md`.
+- For stale-choice, commit, or NGL issues, continue into `brancher-implementation.md`.
+- For memory ownership and clone-footprint problems, continue into `memory-handling.md`.
+- For restart, no-good, and completeness behavior, continue into `search-engines.md` or `search-engine-implementation.md` depending on whether you are using or implementing engines.

skills/gecode/references/general-knowledge.md

@@ -0,0 +1,11 @@
+# Gecode General Knowledge
+
+## Advanced Framing
+- Use groups and tracing for observability and selective control.
+- Improve models in loops: baseline, stronger propagation, better branching, then tuned search.
+- Measure with nodes, time, and restarts, not runtime alone.
+- Treat symmetry handling as a first-class design concern, not post-processing.
+
+## Conceptual Pitfalls
+- Assuming parallel search preserves sequential solution order or runtime profile.
+- Assuming one modeling pass is enough; most nontrivial case studies need staged refinement.

skills/gecode/references/memory-handling.md

@@ -0,0 +1,32 @@
+# Gecode Memory Handling
+
+## Core
+- Memory areas are space, region, heap, and space freelists.
+- `alloc`, `realloc`, and `free` follow C++ object lifecycle semantics.
+- Space memory is reclaimed automatically on space deletion and fits stable-size actor data.
+- Region is a temporary arena with implicit free on region destruction.
+- Heap is for frequently resized or dynamic structures.
+- Search memory profile favors pristine clones, so allocation timing matters.
+- Shared handles point to cross-space or cross-thread shared heap objects with reference counting.
+- Local handles point to per-space shared objects copied on cloning.
+
+## Key Patterns
+- Allocate fixed actor members in home space.
+- Allocate resize-heavy buffers on the heap and free them in `dispose()`.
+- Build heavy internal state lazily on first propagation when possible.
+- Choose eager, lazy, or hybrid allocation based on clone footprint and expected hit rate.
+- Use regions for short-lived iterators and temporary buffers.
+- Call `Region::free()` at clear control-flow boundaries to maximize reuse.
+- Use `SharedHandle` for immutable or global lookup data.
+- Use `LocalHandle` for shared per-space mutable state.
+- Use `IntSharedArray` or related shared arrays for read-only large data reused across clones.
+- For brancher choices using heap buffers, pair allocation and free, and register `AP_DISPOSE`.
+- Use `Region` for per-choice scratch arrays to avoid heap churn.
+
+## Pitfalls
+- Frequent resize in space memory causing fragmentation.
+- Forgetting `home.notice(..., AP_DISPOSE)` for external or heap resources.
+- Forgetting the matching `home.ignore(..., AP_DISPOSE)` in the dispose path.
+- Assuming identical alignment guarantees across space, heap, and region memory.
+- Leaking ownership assumptions across cloning boundaries.
+- Allocating per-choice temporary arrays on the heap in hot paths.