Contributing (CONTRIBUTING.md)

Project Nature

LOKI is a standalone CLI application and autonomous agent, not an importable Python library. All features should be designed around ergonomic CLI flags, terminal feedback (Rich), self-contained HTML reports, and autonomous workflows.

Development Setup

# 1. Clone the repository
git clone https://github.com/MatiSca99/LOKI.git
cd LOKI
# 2. Create and activate a virtual environment
python -m venv .venv
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# Linux / macOS:
source .venv/bin/activate
# 3. Install in editable mode & download Chromium
pip install -e .
playwright install chromium

Coding & Commit Standards

• 100% English repository artifacts: All code, variable names, docstrings, CLI output, comments, documentation, and commit messages must be in English.
• Python 3.10+ & UTF-8 streams: Use modern type annotations (list[str], dict[str, Any], str | None) and keep sys.stdout.reconfigure(encoding="utf-8", errors="replace") intact for Windows compatibility.
• Aggressive Playwright clicks: Chaos persona click bursts must use force=True, timeout=1000, no_wait_after=True so attacks never hang on disabled or covered elements.
• Graceful AI degradation: Every AI feature (rules.md evaluation, loki fix, --auto-heal) must degrade gracefully with a SKIPPED or offline fallback status when API keys are absent.
• Conventional Commits: Prefix commits with feat:, fix:, docs:, refactor:, chore:, or ci:.

Pre-PR Verification Checklist

• python -m loki.cli --help exits with code 0.
• Smoke-test chaos changes against playground/index.html (python -m http.server 8000 --directory playground).
• Ensure no .loki/runs/, .loki.bak backups, or API keys are staged in Git.