From b46297c58f0967c8572862d2558892b168878ead Mon Sep 17 00:00:00 2001 From: pseco Date: Fri, 20 Feb 2026 10:50:32 +0100 Subject: [PATCH 1/2] Add project coding standards and guidelines for Python (PEP 8) --- .github/copilot-instructions.md | 71 +++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..b2636c8 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,71 @@ +--- +applyTo: "**" +--- + +# Project General Coding Standards (Python - PEP 8) + +## Naming Conventions + +- Follow PEP 8 naming conventions strictly +- Use `snake_case` for variables, functions, and methods +- Use `PascalCase` for class names +- Use `UPPER_CASE` for constants +- Prefix internal/private attributes with a single underscore (`_`) +- Avoid single-letter variable names unless in very small scopes (e.g., loops) + +--- + +## Code Style & Formatting + +- Follow PEP 8 guidelines for formatting +- Use 4 spaces for indentation (never tabs) +- Limit lines to 79 characters when possible (max 88 if using Black) +- Add a blank line between logical sections of code +- Keep imports organized: + 1. Standard library + 2. Third-party packages + 3. Local imports +- Avoid wildcard imports (`from module import *`) +- Remove unused imports and variables + +--- + +## Clean Code Principles + +- Write small, focused functions that do **one thing only** +- Prefer functions over long procedural blocks +- Keep functions under ~30 lines when possible +- Use descriptive and meaningful names +- Avoid code duplication (DRY principle) +- Prefer explicit code over implicit behavior +- Avoid deeply nested logic (max 2–3 levels) +- Use early returns to reduce nesting +- Keep classes focused and cohesive +- Write code that is easy to read and maintain + +--- + +## Function Design + +- Always use functions when logic can be reused or isolated +- Add type hints to all function signatures +- Keep functions pure when possible (avoid side effects) +- Document functions using docstrings (PEP 257 style) + +Example: + +```python +def calculate_average(values: list[float]) -> float: + """ + Calculate the average of a list of numbers. + + Args: + values: A list of float numbers. + + Returns: + The arithmetic mean of the values. + """ + if not values: + raise ValueError("The values list cannot be empty.") + + return sum(values) / len(values) \ No newline at end of file From 88eab98aba87d8c94d73d6ca9c6402a2cd2b33c4 Mon Sep 17 00:00:00 2001 From: pseco Date: Fri, 20 Feb 2026 14:43:28 +0100 Subject: [PATCH 2/2] first agent templates approach --- .github/agents/El listo.agent.md | 7 ++ Agents.md | 115 +++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 .github/agents/El listo.agent.md create mode 100644 Agents.md diff --git a/.github/agents/El listo.agent.md b/.github/agents/El listo.agent.md new file mode 100644 index 0000000..31ee404 --- /dev/null +++ b/.github/agents/El listo.agent.md @@ -0,0 +1,7 @@ +--- +name: El_listo +description: Describe what this custom agent does and when to use it. +argument-hint: The inputs this agent expects, e.g., "a task to implement" or "a question to answer". +# tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo'] # specify the tools this agent can use. If not set, all enabled tools are allowed. +--- +Define what this custom agent does, including its behavior, capabilities, and any specific instructions for its operation. \ No newline at end of file diff --git a/Agents.md b/Agents.md new file mode 100644 index 0000000..cb7744c --- /dev/null +++ b/Agents.md @@ -0,0 +1,115 @@ +# Agents.md + +# Project Context — Python (General) + +This repository is a general Python project. Ensure a virtual environment exists, create it with `uv` if missing, keep `requirements.txt` accurate, and then follow the user's instructions. + +--- + +## Environment + +- Virtual env: prefer `uv` to manage the venv and installs. + - Create: `uv venv` (optionally `--python `). + - Use: activate `.venv` or run commands via `uv run `. +- Dependencies: + - If `requirements.txt` exists: `uv pip install -r requirements.txt`. + - When packages are added/removed, update `requirements.txt` to stay accurate. + - Default policy: freeze exact versions unless the user specifies otherwise (e.g., `uv pip freeze > requirements.txt`). +- Never assume the environment is active. + - Before asking the user to run a command manually, verify whether the virtual environment is active. + - If not active, instruct explicitly how to activate it: + - Unix/macOS: `source .venv/bin/activate` + - Prefer `uv run ` to avoid activation issues. + +--- + +## Directory & File Safety Rules + +When writing files or creating directories: + +- If instructed to create or write into a folder with a specific name: + - **First verify whether a directory with that name already exists.** + - Do NOT create it blindly. + - If it exists, reuse it unless the user explicitly requests overwriting. + - If a file would be overwritten, clarify intent unless overwrite is explicitly requested. + +- Avoid duplicating folder structures. +- Do not create parallel directories with similar names (e.g., `src` and `src_new`) unless explicitly requested. +- Maintain consistent project structure conventions. +- Respect existing naming conventions. + +--- + +## Command Execution Policy + +When suggesting commands to the user: + +1. Ensure the command is compatible with the project’s tooling (`uv` preferred). +2. Avoid global installs. +3. Avoid OS-specific assumptions unless specified. +4. If the command modifies the environment (e.g., installing packages): + - Make sure `requirements.txt` is updated accordingly. +5. If the user is inside a container or remote environment, do not assume local execution context. +6. Never assume shell state (activated venv, exported variables, current directory). Always be explicit. + +--- + +## Operating Model + +- Ask quick clarifying questions if versions, entry points, or expected behaviors are ambiguous. +- Prefer small, incremental changes with brief plans for multi-step work. +- Do not commit secrets. +- Avoid committing large build artifacts unless requested. +- Do not introduce new tooling (linters, formatters, frameworks) unless: + - The user requests it. + - It is strictly necessary to complete the task. +- Avoid unnecessary architectural refactors. +- Prioritize minimal, reversible changes. + +--- + +## Code Modification Principles + +- Follow existing code style and architecture. +- Avoid unnecessary refactors. +- Keep changes minimal and scoped. +- Preserve backward compatibility unless explicitly told otherwise. +- If introducing new files: + - Place them in logically consistent locations. + - Avoid breaking import paths. +- Do not remove or rename files unless explicitly instructed. + +--- + +## Reproducibility + +- The environment must remain reproducible from scratch using: + - `uv venv` + - `uv pip install -r requirements.txt` +- No hidden dependencies. +- No reliance on undeclared system packages unless clearly documented. +- Ensure all runtime dependencies are declared. + +--- + +## Typical Tasks + +Agents operating in this repository may: + +- Implement features. +- Fix bugs. +- Run tests. +- Update documentation. +- Improve structure when explicitly requested. +- Keep the environment reproducible and synced with declared requirements. + +--- + +## Safety & Determinism Rules + +- Do not perform destructive actions (e.g., delete directories, drop databases) unless explicitly instructed. +- Do not overwrite configuration files without confirmation. +- Always prefer deterministic operations. +- If uncertain about intent, ask before acting. + +---