Agents updates

.agents/skills/ramble-definition-author/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: ramble-definition-author
+description: "Guide for creating and editing Ramble Object Definitions (Applications, Modifiers, Package Managers, Workflow Managers, Systems, Platforms, Utilities) using Ramble's Python directive language."
+---
+
+# Ramble Definition Author Guide
+
+This skill provides step-by-step guidance for authoring and updating Ramble **Object Definitions** in Python.
+
+*Note*: For general codebase contribution rules, running unit tests, pytest fixtures (`make_workspace_from_config`), and style linters (`ramble style`), consult the [.agents/skills/ramble-developer/SKILL.md](../ramble-developer/SKILL.md) skill.
+
+---
+
+## 1. Repository Structure & Complete Object Types
+
+Ramble object definitions live in Python files inside dedicated subdirectories of a Ramble repository (such as `var/ramble/repos/builtin/` or custom user repositories).
+
+Valid object types and their structure are enumerated in `lib/ramble/ramble/repository.py` (`ObjectTypes` Enum):
+
+| Object Type | Repository Directory | Definition File | Base Class / Interface |
+| :--- | :--- | :--- | :--- |
+| **Applications** | `applications/<name>/` | `application.py` | `ExecutableApplication` or `Application` |
+| **Modifiers** | `modifiers/<name>/` | `modifier.py` | `BasicModifier` or `Modifier` |
+| **Package Managers** | `package_managers/<name>/` | `package_manager.py` | `PackageManager` |
+| **Workflow Managers** | `workflow_managers/<name>/` | `workflow_manager.py` | `WorkflowManager` |
+| **Systems** | `systems/<name>/` | `system.py` | `System` |
+| **Platforms** | `platforms/<name>/` | `platform.py` | `Platform` |
+| **Utilities** | `utilities/<name>/` | `utility.py` | `Utility` |
+
+---
+
+## 2. Base Classes and Inheritance
+
+When creating a new definition, determine whether to build from a fundamental base class or inherit from a concrete definition:
+
+1. **Fundamental Base Classes**:
+   Discover available base classes via CLI:
+   ```bash
+   ramble list --type base_classes
+   ```
+   *Common examples*: `executable-application` (for CLI-driven apps), `basic-modifier` (for simple modifiers).
+
+2. **Inheritable Concrete Definitions**:
+   Discover inheritable definitions via CLI:
+   ```bash
+   ramble list --type base_<object_type>
+   ```
+   *Examples*:
+   ```bash
+   ramble list --type base_applications
+   ramble list --type base_modifiers
+   ramble list --type base_package_managers
+   ramble list --type base_workflow_managers
+   ramble list --type base_systems
+   ramble list --type base_platforms
+   ramble list --type base_utilities
+   ```
+
+---
+
+## 3. Declarative Directives
+
+Ramble uses Python class directives defined in `lib/ramble/ramble/language/` (e.g., `application_language.py`, `modifier_language.py`, `shared_language.py`). Directives declare application behavior inside the class body.
+
+### Directive Categories
+
+#### A. Metadata
+- `name(...)`: Human-readable name.
+- `maintainers(...)`: GitHub handles of maintainers (e.g., `maintainers = ["github_user"]`).
+- `tags(...)`: List of tags for categorizing workloads/applications.
+
+#### B. Software Dependencies
+- `software_spec(...)`: Define package specs (typically Spack specs).
+  ```python
+  software_spec('gromacs_spec', spack_name='gromacs', default_spec='gromacs@2023')
+  ```
+- `define_compiler(...)`: Define compiler specifications.
+
+#### C. Executables & Workloads
+- `executable(...)`: Declare named command templates.
+  ```python
+  executable('run_sim', 'gmx mdrun -s {tpr_file} -deffnm {output_prefix}', implicit=False)
+  ```
+- `input_file(...)`: Declare data files to download or copy.
+- `workload(...)`: Combine executables and input files into named test cases.
+  ```python
+  workload('bench50', executables=['run_sim'])
+  ```
+
+#### D. Parameterization & Variables
+- `workload_variable(...)`: Define default variables for workloads.
+  ```python
+  workload_variable('n_threads', default='1', description='Number of OpenMP threads', workloads=['bench50'])
+  ```
+
+#### E. Results & FOMs (Figures of Merit)
+- `figure_of_merit(...)`: Extract performance data from log files using regex.
+  ```python
+  figure_of_merit('Performance', regexp=r'Performance:\s+(?P<fom>[0-9.]+)\s+ns/day', units='ns/day')
+  ```
+- `success_criteria(...)`: Define rules to check if an experiment succeeded.
+
+#### F. Templating
+- `register_template(...)`: Register template files to generate complex input/config files for executables.
+
+---
+
+## 4. Conditional Logic with `with when(...)`
+
+Apply directives conditionally based on variants, package managers, or target environments using the `with when(...)` context manager:
+
+```python
+with when('package_manager=spack'):
+    software_spec('mpi', spack_name='openmpi')
+
+with when('package_manager=user-managed'):
+    workload_variable('mpi_command', default='mpirun', description='User MPI launcher')
+```
+
+---
+
+## 5. Software Conflict Checks
+
+Before adding new `software_spec` definitions to an application:
+1. Summarize existing software definitions:
+   ```bash
+   ramble software-definitions --summary
+   ```
+2. Check for conflicts across definitions:
+   ```bash
+   ramble software-definitions --conflicts
+   ```
+3. Use consistent specs and versions across applications to encourage software reuse.
+
+---
+
+## 6. Development Best Practices & Developer Skill Link
+
+1. **Docstrings**: Provide informative docstrings on the class detailing what the application does, with links to source code and documentation.
+2. **Developer Guidelines**: For unit testing mock classes (setting `__module__`) and running style checks, refer to [.agents/skills/ramble-developer/SKILL.md](../ramble-developer/SKILL.md).

.agents/skills/ramble-developer/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: ramble-developer
+description: "Guide for Ramble codebase contributors on writing Python code, running unit tests (pytest), fixture usage (make_workspace_from_config), directive lazy-loading rules, and running style checks (ramble style)."
+---
+
+# Ramble Developer Guide
+
+This skill provides guidelines for AI agents contributing code, bug fixes, unit tests, or directives to the Ramble Python codebase.
+
+---
+
+## 1. Python Version Compatibility
+
+- **Supported Versions**: When making Python code changes, consult `bin/ramble` to determine officially supported Python versions.
+- **Compatibility Guardrails**: Ensure code works across all supported Python versions. Use feature detection (`hasattr`) or version checks (`sys.version_info`) when necessary to maintain backward compatibility.
+
+---
+
+## 2. Running Unit Tests
+
+Ramble uses `pytest` for unit testing. Tests **must** be run using the `ramble unit-test` wrapper command (not `pytest` directly) to ensure correct environment setup.
+
+### Test Execution Commands
+- **Run all tests in parallel**:
+  ```bash
+  ramble unit-test -n auto
+  ```
+- **Run tests serially**:
+  ```bash
+  ramble unit-test
+  ```
+- **Filter tests by name or pattern**:
+  ```bash
+  ramble unit-test -k gromacs
+  ```
+- **Get help on test options**:
+  ```bash
+  ramble unit-test --help
+  ramble unit-test --pytest-help
+  ```
+
+---
+
+## 3. Writing Unit Tests & Fixtures
+
+### `make_workspace_from_config` Fixture
+When creating and configuring workspaces in unit tests, **always** use the `make_workspace_from_config` fixture defined in `conftest.py`. Avoid creating workspace directories manually via `tmpdir` or writing raw YAML files to disk.
+
+#### Signature
+```python
+make_workspace_from_config(config_str=None, name=None, activate=False)
+```
+
+#### Behavior & Features
+- Accepts a raw YAML configuration string (`config_str`) defining the `ramble:` dictionary.
+- Automatically isolates workspace files under `mutable_mock_workspace_path` and mocks configuration scopes (`mutable_config`).
+- Returns `(ws, ws_name)` where `ws` is the `ramble.workspace.Workspace` object and `ws_name` is the string name of the workspace.
+- Pass `activate=True` if the test requires an activated workspace environment (`ramble.workspace.activate(ws)`).
+
+#### Example Unit Test
+```python
+def test_my_workspace_feature(make_workspace_from_config):
+    test_config = """
+ramble:
+  variants:
+    package_manager: spack
+    workflow_manager: slurm
+  variables:
+    n_nodes: 1
+    slurm_partition: standard
+    mpi_command: 'mpirun -n {n_ranks}'
+  applications:
+    hostname:
+      workloads:
+        local:
+          experiments:
+            test_exp: {}
+"""
+    ws, ws_name = make_workspace_from_config(test_config, activate=True)
+    # Test logic using ws or ws_name
+```
+
+---
+
+## 4. Implementing Directives & Mock Test Classes
+
+- **Lazy Directive Processing**: Directives in Ramble are processed lazily based on class module namespace (via `DirectiveMeta` in `lib/ramble/ramble/language/`).
+- **Crucial Rule for Mock Classes**: If creating a mock application or modifier class inside a unit test file to test a directive, you **must** explicitly set its `__module__` attribute to a valid Ramble namespace:
+  ```python
+  class MockApp(ExecutableApplication):
+      __module__ = "ramble.app"  # Required for DirectiveMeta to process directives!
+  ```
+  Without this explicit `__module__` assignment, `DirectiveMeta` will silently skip processing directives for your mock test class.
+
+---
+
+## 5. Running Style Checks
+
+Ramble enforces code formatting and type safety using `isort`, `black`, `flake8`, `mypy`, and `ruff`.
+
+### Commands
+- **Check changed files**:
+  ```bash
+  ramble style
+  ```
+- **Check all files in repository**:
+  ```bash
+  ramble style --all
+  ```
+- **Automatically fix style errors**:
+  ```bash
+  ramble style --fix
+  ramble style --all --fix
+  ```
+- **Filter specific tools**:
+  ```bash
+  # Run only isort and black
+  ramble style -t isort -t black
+
+  # Skip flake8 and mypy
+  ramble style -s flake8 -s mypy
+  ```
+
+### Mock Files and Style Checks
+When adding mock application or modifier files (e.g., in `var/ramble/repos/builtin.mock/`), ensure these files contain valid Python syntax, appropriate docstrings, and standard copyright headers. `ramble style` runs on the entire repository and will fail if mock files have syntax or formatting errors.

.agents/skills/ramble-documentation-author/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: ramble-documentation-author
+description: "Guide for authoring, updating, and building Ramble documentation in Sphinx/reStructuredText (reST) format under docs/."
+---
+
+# Ramble Documentation Author Guide
+
+This skill provides guidelines for writing, updating, and verifying Ramble documentation located in the `docs/` directory, which is published to Read The Docs.
+
+---
+
+## 1. Documentation Structure (`docs/`)
+
+Ramble documentation is written in **reStructuredText (`.rst`)** and managed by Sphinx. Key files and directories:
+
+- `docs/index.rst`: Main table of contents and introduction.
+- `docs/getting_started.rst`: Beginner tutorials and workspace quickstart.
+- `docs/workspace_config.rst`: Workspace configuration file specifications.
+- `docs/configuration_files.rst`: Detailed section syntax descriptions.
+- `docs/package_managers.rst`: Package manager integration guides (Spack, EESSI).
+- `docs/dev_guides/`: Developer guides for authoring applications, modifiers, workflow managers, etc.
+- `docs/command_index.rst`: Ramble CLI command reference.
+
+---
+
+## 2. reStructuredText (reST) Syntax Guidelines
+
+### Headings
+Use consistent underline characters for document hierarchy:
+
+```rst
+Document Title
+==============
+
+Section Title
+-------------
+
+Subsection Title
+~~~~~~~~~~~~~~~~
+
+Sub-subsection Title
+^^^^^^^^^^^^^^^^^^^^
+```
+
+### Directives & Alerts
+
+```rst
+.. note::
+   This is a helpful note regarding workspace variables.
+
+.. warning::
+   Overriding Spack compiler specs directly can cause concretization conflicts.
+
+.. code-block:: yaml
+
+   ramble:
+     variables:
+       n_nodes: 2
+```
+
+### Cross-Referencing & Links
+
+- **Document Links**: `:doc:\`workspace_config\`` or `:doc:\`Application Guide <dev_guides/application_dev_guide>\``
+- **Section References**: Use explicit targets:
+  ```rst
+  .. _my-custom-section:
+
+  My Custom Section
+  -----------------
+  Refer to :ref:`my-custom-section`.
+  ```
+- **External Links**: `` `Ramble Docs <https://ramble.readthedocs.io/>`_ ``
+
+---
+
+## 3. Building Documentation Locally
+
+Before submitting documentation changes, build the HTML documentation locally to verify formatting and check for syntax errors or broken links.
+
+### Build Steps
+1. Navigate to the `docs/` directory:
+   ```bash
+   cd docs
+   ```
+2. Build HTML output:
+   ```bash
+   make html
+   ```
+   *(Or using `sphinx-build`: `sphinx-build -b html . _build/html`)*
+3. Verify output in `docs/_build/html/index.html`.
+
+### Checking Links
+Run Sphinx linkcheck to ensure no external or internal links are broken:
+```bash
+make linkcheck
+```
+
+---
+
+## 4. Documentation Best Practices
+
+1. **Keep Examples Runnable**: Ensure all YAML configuration snippets in documentation reflect current Ramble schema and pass validation.
+2. **Document New CLI Commands & Directives**: When adding new directives in `lib/ramble/ramble/language/`, ensure corresponding documentation is added to the Developer Guides (`docs/dev_guides/`).
+3. **Check Build Warnings**: Treat Sphinx build warnings as errors—resolve any missing cross-reference target warnings during `make html`.