From ea05ea93670e6d8d495bbd62a7ae7e068802db08 Mon Sep 17 00:00:00 2001 From: Tibo De Peuter Date: Sat, 21 Mar 2026 15:14:25 +0100 Subject: [PATCH] chore: rework agent rules and skills to use standard .agents directory --- .agents/rules/architecture.md | 20 ++++++++++++++++++++ .agents/rules/general.md | 15 +++++++++++++++ .agents/rules/git-workflow.md | 25 +++++++++++++++++++++++++ .agents/rules/method.md | 14 ++++++++++++++ .agents/skills/lint/SKILL.md | 24 ++++++++++++++++++++++++ .agents/skills/test/SKILL.md | 25 +++++++++++++++++++++++++ 6 files changed, 123 insertions(+) create mode 100644 .agents/rules/architecture.md create mode 100644 .agents/rules/general.md create mode 100644 .agents/rules/git-workflow.md create mode 100644 .agents/rules/method.md create mode 100644 .agents/skills/lint/SKILL.md create mode 100644 .agents/skills/test/SKILL.md diff --git a/.agents/rules/architecture.md b/.agents/rules/architecture.md new file mode 100644 index 0000000..e1e71fa --- /dev/null +++ b/.agents/rules/architecture.md @@ -0,0 +1,20 @@ +# Architecture and Code Formatting Rules + +When writing or modifying code in this project, adhere strictly to the following rules: + +## 1. Core Frameworks & Tooling +- **PPO & CleanRL**: Proximal Policy Optimization (PPO) is the baseline algorithm. Use CleanRL as the starting framework for PPO, ensuring adaptation for continuous action spaces. +- **JAX / Flax**: All Artificial Neural Network (ANN) controller architectures must be implemented using Flax (neural networks in JAX). Ensure full compatibility with the JAX/Flax ecosystem. +- **MuJoCo**: The simulation environment uses a MuJoCo brittle star. Ensure that XML structures (sensors, actuators, joints, morphology) respect realistic constraints and adhere to the project requirements. + +## 2. Clean Code Principles +- **Naming Conventions**: Variables and functions must have consistent, intention-revealing names. A descriptive name is universally preferred over a short name with an explanatory comment. +- **Single Responsibility Function Design**: Functions must be modular. Minimize arguments and completely avoid boolean flag arguments that control execution behavior. +- **Commenting**: Code explains the "how". Comments are strictly reserved for explaining the "why". +- **No Commented-out Code**: The AI must **never** generate commented-out or dead code. Delete it using version control instead. +- **YAGNI & Complexity Management**: You Aren't Gonna Need It. Avoid premature optimization or unnecessary abstraction. Only introduce complexity with documented justification. Break large functions into small, testable blocks. +- **No Notebooks for Core Logic**: Jupyter Notebooks are explicitly forbidden for general software development as they discourage modularity. They should only be used for prototyping, tutorials, or post-processing analysis. + +## 3. Formatting & Linting +- **Ruff**: Output perfectly formatted code adhering to the Google style standard. Always format and lint the code using `ruff` (see `pyproject.toml` and `ruff.toml`). +- **Separation of Concerns**: Configuration code must be completely separated from implementation logic. Core logic must never be mixed with scripts or notebooks. diff --git a/.agents/rules/general.md b/.agents/rules/general.md new file mode 100644 index 0000000..c62f3ed --- /dev/null +++ b/.agents/rules/general.md @@ -0,0 +1,15 @@ +# General AI Agent Rules + +When assisting with this project, the AI Agent must strictly abide by these overarching operational rules: + +## 1. Scientific Integrity +- **No Hallucinations**: You must never fabricate results, hallucinate citations, or generate false empirical claims. Do not guess what happened if a process fails; rely strictly on outputs and logs. + +## 2. Agent Operational Constraints +- **Absolute Paths**: Always use absolute paths when making tool calls or reading/writing files. +- **Refactoring Guardrails**: Do not commence massive files/directory refactors or major system migrations without explicitly communicating the plan and asking for user clarification or approval first. +- **No Boilerplate Feedback**: The AI must not produce generic boilerplate summaries or overly generic advice. Ensure all outputs are completely contextual, robust, and well-reasoned. + +## 3. Communication +- **Artifacts and UI**: Use artifacts (like `implementation_plan.md` or `task.md`) appropriately for tracking design phases and updates. +- **Explicit Documenting**: If performing design choices, list them explicitly. Keep the output focused on the exact task. diff --git a/.agents/rules/git-workflow.md b/.agents/rules/git-workflow.md new file mode 100644 index 0000000..5398e6c --- /dev/null +++ b/.agents/rules/git-workflow.md @@ -0,0 +1,25 @@ +# Git Workflow & Repository Structure Rules + +When performing Git operations and managing the repository layout, follow these rules: + +## 1. Committing Practices +- **Frequent & Small**: Produce small, logical commits instead of massive monolithic ones. +- **Conventional Commits**: Commit messages must adhere to the Conventional Commits specification (e.g., `feat: ...`, `fix: ...`, `refactor: ...`). +- **Single Functionality**: Each commit should relate to exactly one piece of functionality or distinct structural change. + +## 2. Branching & Merging +- **Branch `dev`**: The `dev` branch is the primary integration branch for pushing and merging code. +- **Branch `main`**: Only stable, finalized releases may be pushed to `main`. +- **Feature Branches**: Organize distinct work into logical feature branches when pushing to the remote server, maintaining an organized Git history. + +## 3. Artifact Management & Exclusions +- **LFS Only**: Data files, trained models, and large datasets must **never** be committed directly to Git. Ensure they are tracked with Git Large File Storage (LFS). + +## 4. Repository Layout Strictness +Ensure generated code is meticulously placed in the correct directories: +- `src/` for algorithms, network designs, and core agent modules. +- `env/` for MuJoCo wrappers and environment definitions. +- `config/` for experiment configurations (using json, gin, or yaml). +- `experiments/` for executable scripts. +- `docs/` for ReadTheDocs or Doxygen documentation, and decision logs. +- `tests/` for unit tests and verification scripts. diff --git a/.agents/rules/method.md b/.agents/rules/method.md new file mode 100644 index 0000000..40e4b20 --- /dev/null +++ b/.agents/rules/method.md @@ -0,0 +1,14 @@ +# Methodology and Process Rules + +The agent must adhere to the following scientific and operational practices, focused on robustness and reproducibility: + +## 1. Scientific Context & Methodology +- **Research Focus**: Maintain focus on the project's objective: studying how controller modularity affects learning speed, coordination, and fault tolerance in brittle-star locomotion. +- **Hypothesis-Driven Design**: Base execution on clear hypotheses. Document all design decisions prior to implementation (in `/docs/decisions/` or via Artifacts/Plans). +- **Scaffolding Approach**: Start development with simple setups before scaling to complex environments and varying morphologies. +- **Value of Negative Results**: Understand that a controller failing to learn locomotion, when coupled with a thorough analysis of the failure, holds strong scientific value. Do not artificially force a positive result. + +## 2. Reproducibility Protection +- **Dependency Management (uv)**: This project strictly prefers `uv`. Do **not** manually modify the `uv.lock` file. Add dependencies via `uv add ` and sync environments via `uv sync --frozen` (or via devcontainers). +- **Consistent Initialization**: The AI must avoid hidden randomness. Ensure that all runs use consistent seed initialization. +- **Experiment Tracking**: Use Weights & Biases (wandb) for tracking and logging all experiments and parameters. Ensure every experiment-friendly parameter is properly logged. diff --git a/.agents/skills/lint/SKILL.md b/.agents/skills/lint/SKILL.md new file mode 100644 index 0000000..b5a70cf --- /dev/null +++ b/.agents/skills/lint/SKILL.md @@ -0,0 +1,24 @@ +--- +name: Lint and Format Code +description: Instructions for checking code style and formatting using Ruff. +--- + +# Skill: Lint and Format Code + +The goal of this skill is to enforce the project's adherence to the Google style standard and to maintain high code quality across the python source files. + +## Instructions + +1. **Format Code**: To automatically format all Python files according to the `ruff.toml` specifications: + ```bash + uv run ruff format . + ``` + +2. **Check for Lints / Auto-fix**: To check the repository for style violations and automatically fix safe corrections: + ```bash + uv run ruff check --fix . + ``` + +## Important Considerations +- The `ruff.toml` file at the root handles all lint and format configuration. Do not ignore configurations when applying fixes. +- If Ruff points out complex errors that cannot be auto-fixed, analyze the code and manually address the violations, prioritizing descriptive naming and adherence to the single-responsibility principle. diff --git a/.agents/skills/test/SKILL.md b/.agents/skills/test/SKILL.md new file mode 100644 index 0000000..93a939b --- /dev/null +++ b/.agents/skills/test/SKILL.md @@ -0,0 +1,25 @@ +--- +name: Run Tests +description: Instructions for executing the project test suite to verify code correctness. +--- + +# Skill: Run Tests + +The goal of this skill is to verify that the project is functioning correctly after development changes. + +## Instructions + +1. **Verify Environment**: The project operates dynamically with hardware acceleration (GPU via JAX) and uses `uv` for dependency/execution management. +2. **Execute Tests**: + - To run basic verification (e.g., checking JAX initialization and hardware detection), run the test script: + ```bash + uv run python -m tests.test_jax_init + ``` + - If a broader suite of modular tests is added (e.g., `pytest`), execute tests in the `tests/` directory with: + ```bash + uv run pytest tests/ + ``` + +## Important Considerations +- If you are running tests inside the local environment without a Devcontainer, verify whether `uv sync --frozen` (for CPU) or `uv sync --frozen --extra cuda` (for GPU) has been executed to avoid import errors. +- Do not run bare `python ...` without `uv run` locally, unless you are strictly operating inside a pre-activated `.venv` inside a Devcontainer.