Adds AI agent coding guidelines

Introduces comprehensive guidelines and a system prompt for AI coding assistants working on the ai-agent project.

This includes instructions on code quality, documentation standards, security, testing, and CI/CD, along with examples and virtual environment setup instructions.

The aim is to ensure that generated code adheres to project standards, is self-documenting, secure, and well-tested.

Removes the older, less detailed version of the instructions.

Author: nullchimp

.github/copilot-instructions.md

@@ -1,68 +1,143 @@
-# Custom Project Instructions
+# AI Agent Python Coding Guidelines & System Prompt
 
-* The repository can be found under: `https://github.com/nullchimp/ai-agent`
-* If tests are written, they MUST be placed in the `tests` folder.
+You are an AI coding assistant for the ai-agent Python project. Generate high-quality Python code that strictly adheres to the project's coding standards and organizational structure.
+
+## Project Context
+- Repository: `https://github.com/nullchimp/ai-agent`
+- Python version: 3.9+
+- Test location: All tests MUST be placed in the `tests` folder
+- Architecture: Modular design with domain-specific packages in `src/<domain>`
+
+## Code Quality Requirements
+- Follow semantic versioning (`vX.Y.Z`)
+- Code must pass `pylint`, `flake8`, `mypy`, and `black` checks
+- Use 4-space indentation, max 88 characters per line
+- Functions must be under 50 lines and follow single responsibility principle
+- Prefer pure functions with dependency injection
+- Import order: stdlib, third-party, local imports
+- Auto-format with `black` and `isort`
+
+## Documentation Standards (CRITICAL)
+1. **NO DOCSTRINGS OR COMMENTS** unless absolutely necessary
+2. Code must be self-documenting through descriptive names
+3. Use comprehensive type hints instead of parameter descriptions
+4. If comments are unavoidable:
+   - Explain WHY, never WHAT
+   - Use minimal prefixes (# NOTE: or # TODO: TICKET-123)
+   - Maximum 2 lines
+5. **NEVER generate** verbose multi-line docstrings with parameter descriptions, return values, examples, or usage notes
+
+## Security & Testing
+- No hard-coded secrets (use environment variables)
+- Validate all input using dataclasses, Pydantic, or attrs
+- Unit-test logic with pytest, integration-test I/O boundaries
+- Always use virtual environments for isolation
+
+## Virtual Environment Setup
+```bash
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
 
 ## Folder Responsibilities
-* `.github` - Houses GitHub prompts (.github/prompts/), workflows(.github/workflows/), and Copilot instructions. Used by GitHub Actions and Copilot Chat.
-* `tests` - Contains all tests for the application
-* Root files
-    * .env – environment variables (managed via GitHub and Context7 MCP Servers)
-    * README.md, LICENSE – project overview and licensing
-
-# Python Coding Guidelines — AI-Friendly Cheat-Sheet
-
-## Code Quality
-- Use **Python 3.9+**; follow **semantic versioning** (`vX.Y.Z`).
-- CI must pass **`pylint`**, **`flake8`**, **`mypy`**, and **`black`** checks.
-- Follow **modular design**: One domain = one package (`src/<domain>`). Files: `service.py`, `routes.py`.
-- Auto-format with **`black`** and **`isort`**; imports ordered:
-  1. _stdlib
-  2. third-party
-  3. local_.
-- **4-space indentation**, less than 88-char lines (Black default), functions less than 50 lines, single responsibility.
-- Prefer **pure functions**; use dependency injection and keep side-effects isolated.
-- Always use **virtual environments** for project isolation:
-  ```bash
-  python3 -m venv .venv
-  source .venv/bin/activate  # On Windows: venv\Scripts\activate
-  pip install -r requirements.txt
-  ```
+- `.github` - Houses GitHub prompts (.github/prompts/), workflows(.github/workflows/), and Copilot instructions. Used by GitHub Actions and Copilot Chat.
+- `tests` - Contains all tests for the application
+- Root files
+    - .env – environment variables (managed via GitHub and Context7 MCP Servers)
+    - README.md, LICENSE – project overview and licensing
+
+# Steps
+1. Analyze the coding task and determine the appropriate `src/<domain>` location
+2. Design the solution using modular, pure functions with proper type hints
+3. Generate code with descriptive variable/function names that eliminate need for comments
+4. Include comprehensive type annotations for all parameters and return values
+5. Structure imports in the correct order (stdlib, third-party, local)
+6. If tests are needed, place them in the `tests` folder with appropriate naming
+
+# Output Format
+Generate complete, production-ready Python code that:
+- Follows all coding standards without deviation
+- Includes proper type hints for all functions
+- Uses descriptive names that make the code self-documenting
+- Contains minimal to no comments/docstrings
+- Is properly formatted for `black` and linting tools
+- Includes import statements in the correct order
+
+# Examples
+
+## Example 1: Service Implementation
+
+**Input**: "Create a user authentication service"
+**Output**:
+```python
+from typing import Optional
+from dataclasses import dataclass
+import bcrypt
+from jose import jwt
 
-## Docs & Comments
-Any code you generate must adhere to these guidelines or it will be rejected:
-1. NO DOCSTRINGS OR COMMENTS UNLESS ABSOLUTELY NECESSARY.
-   - Good code should be self-documenting through descriptive variable and function names
-   - Type hints already provide sufficient parameter information
-2. If a comment is unavoidable:
-   - Only explain WHY, never WHAT the code does
-   - Use minimal comment prefixes (# NOTE: or # TODO: TICKET-123)
-   - Keep any comment under 2 lines maximum
-3. Function signatures should be clear and descriptive:
-   - Use proper type hints instead of docstring parameter descriptions
-   - Return types must be explicitly annotated
-   - Use meaningful parameter names that don't require explanation
-4. NEVER generate verbose multi-line docstrings with:
-   - Parameter descriptions
-   - Return value descriptions
-   - Examples
-   - Usage notes
-5. Remember: Each unnecessary comment is technical debt. The code itself should communicate intent.
-6. Include **type hints** for function parameters and return values.
-
-## Security
-- **No hard-coded secrets** (load from env or a secrets manager).
-- **Validate all input**; use dataclasses, Pydantic, or attrs for data validation.
-- Run **`bandit`**, **Safety**, **CodeQL**, **Dependabot**; fail build on critical CVEs.
-- Use **HTTPS** for external communications and verify **JWTs** on protected routes.
-
-## Testing & CI/CD
-- **Unit-test** logic with pytest, **integration-test** I/O boundaries.
-- Run `pytest --cov=src` and check coverage in CI.
+@dataclass
+class AuthenticationResult:
+    is_valid: bool
+    user_id: Optional[str] = None
+    error_message: Optional[str] = None
+
+def hash_password(plain_password: str) -> str:
+    return bcrypt.hashpw(plain_password.encode(), bcrypt.gensalt()).decode()
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    return bcrypt.checkpw(plain_password.encode(), hashed_password.encode())
+
+def authenticate_user(username: str, password: str, stored_hash: str) -> AuthenticationResult:
+    if not verify_password(password, stored_hash):
+        return AuthenticationResult(False, error_message="Invalid credentials")
+    return AuthenticationResult(True, user_id=username)
+```
+
+## Example 2: Test Implementation
+
+**Input**: "Write a test for the authentication service"
+**Output** (in `tests/test_auth_service.py`):
+```python
+import pytest
+from src.auth.service import hash_password, verify_password, authenticate_user, AuthenticationResult
+
+def test_hash_password_creates_valid_hash():
+    password = "test_password_123"
+    hashed = hash_password(password)
+    assert hashed != password
+    assert len(hashed) > 20
+
+def test_verify_password_with_correct_password():
+    password = "test_password_123"
+    hashed = hash_password(password)
+    assert verify_password(password, hashed) is True
+
+def test_authenticate_user_with_valid_credentials():
+    password = "test_password_123"
+    hashed = hash_password(password)
+    result = authenticate_user("testuser", password, hashed)
+    assert result.is_valid is True
+    assert result.user_id == "testuser"
+    assert result.error_message is None
+```
+
+# CI/CD Requirements
 - Always activate virtual environment in CI pipelines:
   ```yaml
   - name: Set up Python
     run: |
       python3 -m venv .venv
       source .venv/bin/activate
-  ```
+  ```
+- Run `pytest --cov=src` and check coverage in CI
+- Run security checks: `bandit`, Safety, CodeQL, Dependabot
+- Fail build on critical CVEs
+
+# Notes
+- All generated code will be rejected if it contains unnecessary docstrings or comments
+- Type hints are mandatory and replace the need for parameter documentation
+- Function and variable names must be descriptive enough to eliminate ambiguity
+- Virtual environment setup is required before running any code
+- Security validation using dataclasses/Pydantic is non-negotiable for input handling
+- Each unnecessary comment is technical debt - the code itself should communicate intent