docs(plugin-development): enhance creation of rules for generating custom_experiments with agents

.cursor/commands/review.md

@@ -0,0 +1,17 @@
+# review
+
+- Review the changes in the current branch
+- Be picky
+- Use general-development rules to evaluate code
+- Link comments to code
+- Format report with following sections (omit if not relevant)
+  - Overview: What is changed
+  - Bugs: Any potential bugs
+  - Critical Issues: Critical problems with implementation or
+    structure
+  - Medium Issues: Issues that should be considered but may not need to be
+    fixed now
+  - Style Issues: Any style changes that should be made
+  - Linting Issues: Issues raised by the linters. black, ruff or
+    markdownlint-cli2 lints will block commits
+- Write review to md file also

.cursor/rules/general-development.mdc

@@ -0,0 +1,142 @@
+---
+description: General development guidelines for ad-ado - code style, testing, quality checks, and commit standards
+alwaysApply: true
+---
+
+# General Development Guidelines for ado
+
+These guidelines apply to all code development in the ad-orchestrator codebase.
+
+## Code Structure
+
+- **orchestrator**: main Python package
+  - **schema**: pydantic models for properties, entities, experiments,
+    and measurement results
+  - **core**: pydantic models and associated code for the core resource
+    types managed by ado:
+    - discoveryspace
+    - operation
+    - samplestore
+    - datacontainer
+    - actuatorconfiguration
+  - **modules/actuators**: defines actuators, custom experiments, and their
+    associated management code (plugins, registry)
+  - **modules/operators**: defines operators and their associated management
+    code (plugins, collections, orchestration)
+  - **utilities**: common utilities
+  - **cli**: ado CLI
+  - **metastore**: code defining and interacting with the metastore, which
+    stores core resource types
+- **tests**: unit and integration tests (pytest)
+- **plugins**: actuator, operator, and custom_experiment plugins
+- **website**: mkdocs website and documentation
+- **examples**: examples of using ado
+
+### Structure Guidelines
+
+- Place new code in the most specific existing subpackage.
+- Do not create new top-level packages unless explicitly instructed.
+
+---
+
+## Code Style
+
+- Use PEP8 naming conventions for new code.
+- **Exception**: use camelCase for fields of pydantic models.
+- Do not modify existing names unless explicitly asked, even if they do not
+  follow PEP8.
+- Use type annotations on all functions and methods, including return types.
+- Add docstrings to all functions and methods.
+- Use the pydantic annotated form for pydantic fields
+  (see `orchestrator/schema/entity.py`).
+- Use discriminated unions when a type is a union
+  (see `ExperimentType` in `orchestrator/schema/experiment.py`).
+- Use the `Defaultable` type from `orchestrator/utilities/pydantic` for
+  pydantic fields that:
+  - accept `None`, but
+  - are always defaulted to a different type.
+- Use absolute imports within the repository unless the file already uses
+  relative imports.
+
+---
+
+## Developer Tools
+
+- All development tools (ruff, black, pytest, etc.) are available in the
+  project's **uv-managed virtual environment**.
+- Do not install tools globally.
+- Use the following pattern to execute tools:
+
+    uv run TOOLNAME
+
+---
+
+## Code Development
+
+Use Test Driven Development
+
+- Write tests first
+    - Do not create mock implementations
+- Run pytest: confirm tests fail
+- Implement the code to be tested
+- Run pytest: check tests
+- Iterate until tests pass
+
+## Writing Tests
+
+- Check for existing fixtures before creating new ones:
+  - `tests/fixtures/`
+- Do not mock by default; prefer integration tests.
+- Test the full lifecycle for pydantic models:
+    create → dump → create from dump
+
+## Code Linting
+
+- Linting must be run after any code changes and must pass before running tests.
+- Run **black** after changes:
+
+    uv run black $DIR
+
+- Run **ruff** after changes:
+
+    uv run ruff check --fix $DIR
+
+- Fix any issues reported by ruff that it could not fix automatically.
+- Run black and ruff at directory level for efficiency (e.g. `orchestrator/`,
+  `plugins/`, `tests/`).
+- Run the mkdocs linter on markdown files (*.md) that have added or modified:
+
+    uv run markdownlint-cli2 NEW_OR_CHANGED_MARKDOWN_FILE --fix
+
+- Run if YAML changed or added
+
+    pre-commit run yamlfmt
+
+---
+
+## Code Testing
+
+- Each subpackage has a corresponding test directory under `tests/`, for example:
+  - `schema/`
+  - `core/`
+  - `actuators/`
+  - `operators/`
+  - `metastore/`
+  - `cli/`
+- As a final validation step, run tests for all impacted subpackages.
+- All tests must pass before submitting changes.
+- Ensure the virtual environment is correctly set up before running tests:
+
+    uv sync --reinstall --group test --group dev
+
+---
+
+## YAML Testing
+
+- Test any new or modified ado resource YAML using:
+
+    ado create RESOURCETYPE -f FILE --dry-run
+
+---
+
+- For plugin development, see [plugin-development.mdc](plugin-development.mdc)