From 3b33730105ce7e04a60f8d38d230798d4483669c Mon Sep 17 00:00:00 2001 From: Florian Asche Date: Fri, 24 Jul 2026 17:35:34 +0200 Subject: [PATCH] feat(ai): integrate Kilo agent framework and coding instructions (#366) * feat(ai): integrate Kilo agent framework and coding instructions Add configuration files, agent definitions, and skill sets to enable AI-driven development workflows and standardized agent behavior. --- .kilo/.gitignore | 8 ++ .kilo/command/lint.md | 14 +++ .kilo/command/run.md | 14 +++ .kilo/command/setup.md | 14 +++ .kilo/command/tests.md | 15 +++ .kilo/skill/review-pr/REVIEW_STANDARDS.md | 70 ++++++++++++ .kilo/skill/review-pr/SKILL.md | 44 ++++++++ AGENTS.md | 129 ++++++++++++++++++++++ kilo.json | 5 + 9 files changed, 313 insertions(+) create mode 100644 .kilo/.gitignore create mode 100644 .kilo/command/lint.md create mode 100644 .kilo/command/run.md create mode 100644 .kilo/command/setup.md create mode 100644 .kilo/command/tests.md create mode 100644 .kilo/skill/review-pr/REVIEW_STANDARDS.md create mode 100644 .kilo/skill/review-pr/SKILL.md create mode 100644 AGENTS.md create mode 100644 kilo.json diff --git a/.kilo/.gitignore b/.kilo/.gitignore new file mode 100644 index 0000000..e0bf7fb --- /dev/null +++ b/.kilo/.gitignore @@ -0,0 +1,8 @@ +node_modules +package.json +package-lock.json +pnpm-lock.yaml +bun.lock +yarn.lock +worktrees +agent-manager.json \ No newline at end of file diff --git a/.kilo/command/lint.md b/.kilo/command/lint.md new file mode 100644 index 0000000..b8c4e47 --- /dev/null +++ b/.kilo/command/lint.md @@ -0,0 +1,14 @@ +# Lint Command + +Runs all linting checks for the project (black, isort, flake8, mypy, pylint). + +## Usage + +``` +/lint # Run all linting checks +/lint --auto # Auto-fix formatting issues (black, isort) +``` + +## Command + +./script/lint \ No newline at end of file diff --git a/.kilo/command/run.md b/.kilo/command/run.md new file mode 100644 index 0000000..b0b9e7f --- /dev/null +++ b/.kilo/command/run.md @@ -0,0 +1,14 @@ +# Run Command + +Runs the Linux Voice Assistant application. + +## Usage + +``` +/run # Run the application +/run --help # Show CLI help +``` + +## Command + +./script/run \ No newline at end of file diff --git a/.kilo/command/setup.md b/.kilo/command/setup.md new file mode 100644 index 0000000..3e30d54 --- /dev/null +++ b/.kilo/command/setup.md @@ -0,0 +1,14 @@ +# Setup Command + +Installs project dependencies in a virtual environment. + +## Usage + +``` +/setup # Install dependencies +/setup --dev # Install dev dependencies (linting, testing tools) +``` + +## Command + +./script/setup \ No newline at end of file diff --git a/.kilo/command/tests.md b/.kilo/command/tests.md new file mode 100644 index 0000000..d925c14 --- /dev/null +++ b/.kilo/command/tests.md @@ -0,0 +1,15 @@ +# Test Command + +Runs the pytest unit tests for the project. + +## Usage + +``` +/tests # Run all tests +/tests # Run tests in specific path +/tests -k # Run tests matching pattern +``` + +## Command + +./script/tests \ No newline at end of file diff --git a/.kilo/skill/review-pr/REVIEW_STANDARDS.md b/.kilo/skill/review-pr/REVIEW_STANDARDS.md new file mode 100644 index 0000000..83472b7 --- /dev/null +++ b/.kilo/skill/review-pr/REVIEW_STANDARDS.md @@ -0,0 +1,70 @@ +# PR Review Standards + +## Review Philosophy + +- Only comment when confident an issue exists +- Be concise: one sentence per comment when possible +- Focus on actionable feedback, not observations +- When reviewing text, only comment on clarity issues if the text is genuinely confusing or could lead to errors + +## What to Analyze + +Review all code changes for: + +- Code quality and style consistency with the existing codebase +- Potential bugs or issues +- Performance implications +- Blocking IO in async code +- Security concerns +- Test coverage +- Documentation updates if needed + +## Project Standards + +Respect the project standards as outlined in AGENTS.md. Any deviations must be raised as `[PROBLEM]`. + +Key standards for LVA: +- Python 3.11, 3.12, 3.13 supported +- Black formatting with 200 char line length +- isort import sorting with black profile +- mypy type checking with strict settings +- pylint code quality checks (many checks disabled in pyproject.toml) + +## Architecture-Specific Checks + +- `linux_voice_assistant/wake_word.py` - Wake word model loading is hardware-dependent, verify no assumptions about specific hardware +- `linux_voice_assistant/mpv_player.py` - Audio output requires `libmpv-dev`, check for proper error handling +- `linux_voice_assistant/webrtc.py` - Noise suppression/gain algorithms need careful review for audio quality +- `linux_voice_assistant/satellite.py` - ESPHome API protocol handling must be robust + +## CI Context + +Lint runs on Python 3.13, tests run on Python 3.12 with libmpv-dev. + +### What CI Checks + +- **Lint**: `.github/workflows/lint.yml` runs all linting checks +- **Tests**: `.github/workflows/tests.yml` runs pytest unit tests + +## Skip These (Low Value) + +Do not comment on: + +- Style/formatting (pre-commit handles this) +- Test failures (CI catches this) +- Missing dependencies (CI catches this) +- Minor naming suggestions +- Suggestions to add comments +- Logging suggestions unless security-related + +## Issue Categories + +Categorize every issue as: + +- `[CRITICAL]` — must fix before merging (bugs, security issues, broken functionality) +- `[PROBLEM]` — should fix (code quality, bad patterns, missing tests) +- `[SUGGESTION]` — optional improvement (style, minor refactors, nice-to-haves) + +## PR Title + +The PR title must be a functional description of the change. It must NOT contain conventional commit prefixes such as `feat:`, `fix:`, `refactor:`, `chore:`, etc. Labels categorize PRs, not the title. Flag as `[PROBLEM]` if the title uses such prefixes. \ No newline at end of file diff --git a/.kilo/skill/review-pr/SKILL.md b/.kilo/skill/review-pr/SKILL.md new file mode 100644 index 0000000..7ff1bb5 --- /dev/null +++ b/.kilo/skill/review-pr/SKILL.md @@ -0,0 +1,44 @@ +name: review-pr +description: Use when asked to review a GitHub pull request, PR link is shared, or user says /review-pr + +# Review GitHub Pull Request + +Review the GitHub pull request: $ARGUMENTS. + +## Steps + +1. Run `gh pr view` to get PR details and description. +2. Run `gh pr diff` to see all changes. +3. Compare the local commit hash with the remote PR head commit. + - Make sure to do your work in a git worktree to avoid affecting the checked out branch. + - If they don't match, run `gh pr checkout` to check out the PR locally. + - **HARD STOP**: If `gh pr checkout` fails for ANY reason, STOP immediately. Do NOT attempt workarounds. Alert about the failure and wait for instructions. + - After checkout, verify the local commit hash matches the remote one. If they still don't match, STOP. +4. Run `gh pr checks` to see CI status. +5. Apply the review standards defined in `REVIEW_STANDARDS.md` (same directory). +6. Output review feedback to the CONSOLE only. DO NOT act on GitHub (no posting comments, no approving, no requesting changes). + +## Output Format + +List specific comments per file/line that need attention. Do not list things that are already correct. + +Each comment: + +1. State the severity ([CRITICAL], [PROBLEM], [SUGGESTION]) +2. State the problem (1 sentence) +3. Why it matters (1 sentence, if needed) +4. Suggested fix (snippet or specific action) + +End with an overall assessment and summary: + +``` +Overall assessment: +- [CRITICAL] +- [PROBLEM] +- [SUGGESTION] +``` + +## Constraints + +- DO NOT make any changes to the code. +- No need to run tests or linters, just review the code changes. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b0dab0f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,129 @@ +# Project Context for AI Agents + +## Behaviour + +- NEVER automatically reply on Github (PRs or Discussions) without explicit consent from the developer. +- Always run `./script/lint` and `./script/tests` after code changes to ensure standards are met. + +## Project Overview + +**Linux Voice Assistant (LVA)** - A Linux-based voice satellite software for Home Assistant using the ESPHome protocol. + +### Purpose +- Provides voice control and interaction for Home Assistant via the Assist integration +- Runs on x64/ARM64 Linux hardware with PulseAudio/PipeWire audio support +- Performs local wake word detection (OpenWakeWord/MicroWakeWord) and on-device processing + +### Architecture +- **Protocol**: ESPHome API via `aioesphomeapi` for Home Assistant integration +- **Wake Words**: Supports both OpenWakeWord and MicroWakeWord engines +- **Audio**: Uses `soundcard` library for input, `python-mpv` for output +- **Peripherals**: WebSocket API for LEDs, buttons, HAT boards +- **Discovery**: mDNS/ZeroConf for auto-discovery by Home Assistant + +### Key Components +- `linux_voice_assistant/__main__.py` - Main entry point with CLI argument parsing +- `linux_voice_assistant/satellite.py` - VoiceSatelliteProtocol implementation (ESPHome API) +- `linux_voice_assistant/wake_word.py` - Wake word model loading and detection +- `linux_voice_assistant/webrtc.py` - WebRTC noise gain/NS processing +- `linux_voice_assistant/mpv_player.py` - MPV-based media player +- `linux_voice_assistant/entity.py` - Entity definitions (MediaPlayer, MuteSwitch, etc.) +- `linux_voice_assistant/api_server.py` - Peripheral WebSocket API server +- `linux_voice_assistant/models.py` - Preferences and ServerState dataclasses + +## Development Commands + +### Setup +```bash +./script/setup --dev # Install dev dependencies in virtual environment +``` + +### Linting +```bash +./script/lint # Run all linting checks +./script/lint_black # Black formatting check (add --auto to fix) +./script/lint_isort # isort import sorting check (add --auto to fix) +./script/lint_flake8 # flake8 style checks +./script/lint_mypy # mypy type checking +./script/lint_pylint # pylint code quality checks +``` + +### Testing +```bash +./script/tests # Run pytest unit tests +``` + +## Code Quality Standards + +- **Python**: 3.11, 3.12, 3.13 supported +- **Formatting**: Black (200 char line length, py312/py312 target) +- **Import Sorting**: isort with black profile +- **Type Checking**: mypy with strict settings +- **Linting**: pylint (many checks disabled in pyproject.toml for practical reasons) + +## Testing Strategy + +- Unit tests in `tests/unit/` using pytest with asyncio mode +- Test helper `make_state()` in `tests/unit/conftest.py` for creating state fixtures +- Mocks used heavily for hardware dependencies (audio devices, MPV, wake words) + +## CI/CD + +- GitHub Actions for lint checks and unit tests +- Tests run on Python 3.12 with libmpv-dev system dependency +- Lint runs on Python 3.13 + +## Branching and PRs + +- All PRs target `main` (primary development branch). `stable` is for production releases. +- PRs labeled `bugfix` + `backport-to-stable` are automatically backported to `stable` — use only for bugs also present in `stable`. + +## Agent Commands + +When making code changes, run these commands in order: + +1. **Format code**: `./script/lint_black --auto` and `./script/lint_isort --auto` +2. **Run linting**: `./script/lint` +3. **Run tests**: `./script/tests` + +## Code Style + +### Comments + +Only use comments to explain complex, multi-line blocks of code. Do not comment obvious operations. Inline comments are there to explain code parts that need explaining - keep them when editing code. + +### Docstring Format + +Use Sphinx-style docstrings with `:param:` syntax. For simple functions, a single-line docstring is fine. The docstring should provide clarity to the caller, not explain how it works technically. + +```python +def my_function(param1: str, param2: int, param3: bool = False) -> str: + """ + Brief one-line description of the function. + :param param1: Description of what param1 is used for. + :param param2: Description of what param2 is used for. + :param param3: Description of what param3 is used for. + """ +``` + +Do **not** use Google-style (`Args:`) or bullet-style (`- param:`) docstrings. + +### File structure + +Private methods should be at the bottom of the file, public at the top. + +## Verification Checklist + +Before claiming completion: +- [ ] Ran `./script/lint` - all checks passed +- [ ] Ran `./script/tests` - all tests passed +- [ ] For audio-related changes: Note that hardware testing (microphone/speaker) was NOT performed +- [ ] Did NOT claim hardware behavior is verified unless actually exercised +- [ ] Changes are focused on one feature or fix per change + +## Areas Requiring Extra Care + +- `linux_voice_assistant/wake_word.py` - Wake word model loading is hardware-dependent +- `linux_voice_assistant/mpv_player.py` - Audio output requires `libmpv-dev` +- `linux_voice_assistant/webrtc.py` - Noise suppression/gain algorithms +- `linux_voice_assistant/satellite.py` - ESPHome API protocol handling \ No newline at end of file diff --git a/kilo.json b/kilo.json new file mode 100644 index 0000000..ce7e891 --- /dev/null +++ b/kilo.json @@ -0,0 +1,5 @@ +{ + "$schema": "https://app.kilo.ai/config.json", + "model": "kilo/codegemma-2b:free", + "instructions": ["AGENTS.md"] +} \ No newline at end of file