1
Fork 0

chore: rework agent rules and skills to use standard .agents directory

This commit is contained in:
Tibo De Peuter 2026-03-21 15:14:25 +01:00
parent 466e4de872
commit ea05ea9367
Signed by: tdpeuter
GPG key ID: 38297DE43F75FFE2
6 changed files with 123 additions and 0 deletions

View file

@ -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.

15
.agents/rules/general.md Normal file
View file

@ -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.

View file

@ -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.

14
.agents/rules/method.md Normal file
View file

@ -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 <package>` 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.