mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-05-05 19:19:35 +00:00
342 lines
8.5 KiB
Markdown
342 lines
8.5 KiB
Markdown
# AGENTS.md
|
||
|
||
## 🧠 Project Overview
|
||
|
||
This project is a Python-based application. Agents working in this directory must adhere to Python 3.11+ best practices, with clear module separation, test coverage, security hygiene, and readable documentation.
|
||
|
||
---
|
||
|
||
## 📁 Project Structure
|
||
|
||
Agents must follow the directory structure below:
|
||
|
||
```
|
||
project-root/
|
||
│
|
||
├── src/ # Application source code
|
||
│ └── <package_name>/ # Python modules/packages
|
||
│
|
||
├── tests/ # Unit + integration tests
|
||
│ └── __init__.py
|
||
│
|
||
├── scripts/ # Utility and CLI scripts
|
||
│
|
||
├── docs/ # Documentation (Markdown or reStructuredText)
|
||
│
|
||
├── .github/ # GitHub Actions workflows
|
||
│
|
||
├── pyproject.toml # Project metadata & tool configs (preferred)
|
||
├── requirements.txt # Legacy dependency spec (optional)
|
||
├── .env.example # Environment variable template
|
||
└── AGENTS.md # Agent configuration (this file)
|
||
```
|
||
|
||
Do not create files outside this structure unless explicitly instructed.
|
||
|
||
---
|
||
|
||
## 🧪 Testing & Validation
|
||
|
||
Before submitting changes, agents **must** ensure all tests and linters pass:
|
||
|
||
```bash
|
||
# Set up environment (once)
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -e .[dev]
|
||
|
||
# Run unit tests
|
||
pytest --cov=src --cov-report=term --cov-report=xml
|
||
|
||
# Run linters
|
||
ruff check src/ tests/
|
||
mypy src/
|
||
black --check src/
|
||
```
|
||
|
||
### ✅ Required Quality Gates
|
||
|
||
- Code coverage: ≥ 90%
|
||
- Type coverage: 100% via `mypy`
|
||
- No linter errors (ruff + mypy)
|
||
- No black formatting issues
|
||
|
||
Agents must **not** commit code that fails these checks.
|
||
|
||
---
|
||
|
||
## 🧹 Code Style
|
||
|
||
- Use **PEP8 + PEP257** standards.
|
||
- Prefer `pyproject.toml` for tool configuration (Black, Ruff, Mypy, etc.).
|
||
- Function names: `snake_case`
|
||
- Class names: `PascalCase`
|
||
- Constant names: `UPPER_SNAKE_CASE`
|
||
- Use f-strings, not `%` or `.format()` for string interpolation.
|
||
- Keep function length under 50 lines where possible.
|
||
|
||
---
|
||
|
||
## 🔒 Security Guidelines
|
||
|
||
Agents must:
|
||
|
||
- Never commit `.env` files, secrets, or tokens.
|
||
- Use `dotenv` to load secrets during local execution.
|
||
- Avoid using `eval()`, `exec()`, or subprocess calls unless sandboxed and essential.
|
||
- Avoid external internet access during execution unless configured via API keys.
|
||
|
||
---
|
||
|
||
## 🧪 Testing Philosophy
|
||
|
||
- Use `pytest` with fixtures, mocking (`unittest.mock` or `pytest-mock`), and parameterized tests.
|
||
- Aim for 1:1 parity between modules and test modules.
|
||
- Include boundary cases and exception tests.
|
||
|
||
---
|
||
|
||
## 🧾 Commit & PR Conventions
|
||
|
||
Agents must format commits using **Conventional Commits**:
|
||
|
||
```
|
||
feat: add user authentication module
|
||
fix: correct path handling in file parser
|
||
docs: update README with usage example
|
||
```
|
||
|
||
Pull Requests should include:
|
||
|
||
- A concise title (≤ 72 chars)
|
||
- A summary of what changed and why
|
||
- Before/after behavior (if applicable)
|
||
- Testing evidence (CI, screenshots, coverage)
|
||
|
||
---
|
||
|
||
## 📦 Dependency Management
|
||
|
||
- Use **`pyproject.toml`** (via Poetry or PEP 621 standard)
|
||
- Prefer `pip install .[dev]` over `requirements.txt`
|
||
- Dev dependencies go under `[tool.poetry.group.dev.dependencies]` or similar
|
||
- Avoid `pip freeze` output for lockfiles — use `poetry.lock` or `requirements.lock` if necessary
|
||
|
||
---
|
||
|
||
## 🤖 Agent Behavior Summary
|
||
|
||
- Respect the file and folder structure
|
||
- Never break existing tests
|
||
- Follow Pythonic style and formatting
|
||
- Automate validation where possible
|
||
- Explain large changes via commit messages and PR descriptions
|
||
- Use comments where logic is non-obvious
|
||
|
||
---
|
||
|
||
Happy coding! 🐍
|
||
|
||
|
||
---
|
||
|
||
## ⚙️ Setup Script Requirement
|
||
|
||
Every project must include a `setup.sh` script at the root level that ensures:
|
||
|
||
- Python 3.11+ is installed
|
||
- Poetry is installed (via `install.python-poetry.org`)
|
||
- All dependencies are installed using `poetry install`
|
||
|
||
If this script does not exist, the agent must create it. It should be idempotent and safe to re-run.
|
||
|
||
Run it like this:
|
||
|
||
```bash
|
||
chmod +x setup.sh
|
||
./setup.sh
|
||
```
|
||
|
||
|
||
---
|
||
|
||
## 🖥 OS-Specific Setup Scripts (Expanded)
|
||
|
||
Agents must maintain the following OS-specific setup scripts:
|
||
|
||
- `setup_linux.sh`
|
||
- `setup_mac.sh`
|
||
- `setup_windows.ps1`
|
||
|
||
These scripts must:
|
||
- Ensure Python 3.11+ is present (install if missing)
|
||
- Install Poetry (if not already installed)
|
||
- Run `poetry install` to install dependencies
|
||
- Be idempotent and safe to re-run
|
||
|
||
A user must be able to simply clone the repo, run the appropriate script, and be ready to work.
|
||
|
||
Refer to `README.md` for user-friendly execution instructions.
|
||
|
||
---
|
||
|
||
## 🖥 OS-Specific Setup Scripts (Expanded)
|
||
|
||
Agents must maintain the following **OS-specific setup scripts** in the project root:
|
||
|
||
- `setup_linux.sh` – for Ubuntu, Debian, Fedora, Arch, etc.
|
||
- `setup_mac.sh` – for macOS (Intel/ARM); must auto-install Homebrew if missing
|
||
- `setup_windows.ps1` – for Windows 10+ using PowerShell
|
||
|
||
Each script must:
|
||
- Ensure Python 3.11+ is installed
|
||
- Install Poetry if missing
|
||
- Run `poetry install` to fetch dependencies
|
||
- Be idempotent and safe to re-run
|
||
- Provide clear terminal output
|
||
|
||
These scripts should allow a contributor to clone the project, run one script, and be ready to develop.
|
||
|
||
---
|
||
|
||
### 🐧 setup_linux.sh
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
set -e
|
||
|
||
echo "🔍 Checking Python 3.11+..."
|
||
if ! python3 --version | grep -q "3.11"; then
|
||
echo "Installing Python 3.11..."
|
||
if command -v apt &>/dev/null; then
|
||
sudo apt update
|
||
sudo apt install -y python3.11 python3.11-venv python3.11-dev
|
||
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1
|
||
elif command -v dnf &>/dev/null; then
|
||
sudo dnf install -y python3.11
|
||
elif command -v pacman &>/dev/null; then
|
||
sudo pacman -S --noconfirm python
|
||
else
|
||
echo "❌ Unsupported Linux package manager."
|
||
exit 1
|
||
fi
|
||
fi
|
||
|
||
echo "✅ Python version: $(python3 --version)"
|
||
|
||
echo "🔍 Checking for Poetry..."
|
||
if ! command -v poetry &>/dev/null; then
|
||
echo "📦 Installing Poetry..."
|
||
curl -sSL https://install.python-poetry.org | python3 -
|
||
export PATH="$HOME/.local/bin:$PATH"
|
||
else
|
||
echo "✅ Poetry is installed: $(poetry --version)"
|
||
fi
|
||
|
||
echo "📦 Installing dependencies..."
|
||
poetry install
|
||
|
||
echo "✅ Linux setup complete. Use 'poetry shell' to activate environment."
|
||
```
|
||
|
||
---
|
||
|
||
### 🍎 setup_mac.sh
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
set -e
|
||
|
||
echo "🔍 Checking Python 3.11+..."
|
||
if ! python3 --version | grep -q "3.11"; then
|
||
echo "Installing Python 3.11 using Homebrew..."
|
||
if ! command -v brew &>/dev/null; then
|
||
echo "📦 Installing Homebrew..."
|
||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||
export PATH="/opt/homebrew/bin:$PATH"
|
||
fi
|
||
brew install python@3.11
|
||
brew link python@3.11 --force
|
||
fi
|
||
|
||
echo "✅ Python version: $(python3 --version)"
|
||
|
||
echo "🔍 Checking for Poetry..."
|
||
if ! command -v poetry &>/dev/null; then
|
||
echo "📦 Installing Poetry..."
|
||
curl -sSL https://install.python-poetry.org | python3 -
|
||
export PATH="$HOME/.local/bin:$PATH"
|
||
else
|
||
echo "✅ Poetry is installed: $(poetry --version)"
|
||
fi
|
||
|
||
echo "📦 Installing dependencies..."
|
||
poetry install
|
||
|
||
echo "✅ macOS setup complete. Use 'poetry shell' to activate environment."
|
||
```
|
||
|
||
---
|
||
|
||
### 🪟 setup_windows.ps1
|
||
|
||
```powershell
|
||
# PowerShell script
|
||
Write-Host "🔍 Checking Python 3.11+..."
|
||
$pythonVersion = python --version
|
||
if (-not ($pythonVersion -like "*3.11*")) {
|
||
Write-Host "Installing Python 3.11..."
|
||
Invoke-WebRequest -Uri "https://www.python.org/ftp/python/3.11.5/python-3.11.5-amd64.exe" -OutFile "python_installer.exe"
|
||
Start-Process -Wait -FilePath "./python_installer.exe" -ArgumentList "/quiet InstallAllUsers=1 PrependPath=1"
|
||
Remove-Item "python_installer.exe"
|
||
}
|
||
|
||
Write-Host "✅ Python version: $(python --version)"
|
||
|
||
Write-Host "🔍 Checking for Poetry..."
|
||
if (-not (Get-Command poetry -ErrorAction SilentlyContinue)) {
|
||
Write-Host "📦 Installing Poetry..."
|
||
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
|
||
$env:Path += ";$env:USERPROFILE\.poetry\bin"
|
||
}
|
||
|
||
Write-Host "📦 Installing dependencies..."
|
||
poetry install
|
||
|
||
Write-Host "✅ Windows setup complete. Run 'poetry shell' to activate environment."
|
||
```
|
||
|
||
---
|
||
|
||
### 📘 Instructing Users in README.md
|
||
|
||
Also ensure `README.md` includes this section:
|
||
|
||
```markdown
|
||
## 🖥 Setup Instructions
|
||
|
||
Run the setup script for your operating system:
|
||
|
||
**Linux:**
|
||
```bash
|
||
chmod +x setup_linux.sh
|
||
./setup_linux.sh
|
||
```
|
||
|
||
**macOS:**
|
||
```bash
|
||
chmod +x setup_mac.sh
|
||
./setup_mac.sh
|
||
```
|
||
|
||
**Windows (PowerShell):**
|
||
```powershell
|
||
.\setup_windows.ps1
|
||
```
|
||
|
||
After installation:
|
||
```bash
|
||
poetry shell
|
||
```
|
||
```
|