mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2026-11-13 09:13:30 +01:00

Files

T

Bobby NoelteandClaude Opus 5.5 d68f040206 feat(ai): add the mattpocock engineering skills for AI agents

Vendor the engineering skills of https://github.com/mattpocock/skills into
ai/skills/engineering, with their MIT license, and list them in AGENTS.md.
The agent-specific metadata (agents/openai.yaml) is kept for other agents.

Additional changes
- Add scripts/update_mattpocock_skills.py to compare the copy with upstream by
  git blob hashes from a blobless clone and to update it on request.
- Add tests/test_ai.py; it warns when the copy differs from upstream and caches
  the upstream hashes in the pytest cache for a day.
- Document the engineering skills in docs/develop/ai.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-11-09 12:45:20 +01:00

4.8 KiB

Raw Blame History

AGENTS.md — Akkudoktor-EOS

Akkudoktor-EOS is a Python-based energy management and optimization system. It provides energy forecasts, optimization, energy management plans, and integrations with local energy devices and controllers.

The project prioritizes reliable local operation, clear interfaces, maintainable code, testability, and type safety.

Rules for every change

Follow existing architecture and coding conventions.
Prefer small, focused changes that preserve established interfaces and behavior.
Use type annotations for functions, methods, and relevant variables.
Write Google-style docstrings for modules, classes, and public functions/methods, following surrounding code.
Keep code compatible with the supported Python version (pyproject.toml).
Avoid introducing unnecessary dependencies.
Use descriptive, domain-meaningful names.
Never use production assert for input validation or runtime error handling; use explicit exceptions.
Use existing logging facilities and conventions.
Follow existing patterns for config, validation, error reporting, resource management.
Preserve compatibility with existing tests and supported integrations unless a change explicitly requires otherwise.
Never use the workspace .venv: run uv, make and all Python tools in a virtual environment outside the workspace (UV_PROJECT_ENVIRONMENT), see ai/skills/python-environment/SKILL.md.

Skills

Detailed rules live in ai/skills/. Load the relevant skill for the task:

Skill	Load when
`ai/skills/application-configuration/SKILL.md`	Config, Pydantic models, defaults
`ai/skills/commit-messages/SKILL.md`	Creating/checking commit messages
`ai/skills/energy-domain/SKILL.md`	Optimization, adapters, units/signs
`ai/skills/filename-conventions/SKILL.md`	Creating/renaming files
`ai/skills/python-environment/SKILL.md`	Before running uv, make, pytest, mypy, ruff or any Python
`ai/skills/python-quality/SKILL.md`	Writing/modifying Python
`ai/skills/rest-api/SKILL.md`	Adding/changing REST endpoints, API error responses
`ai/skills/testing/SKILL.md`	Adding/updating tests, bug fixes

Engineering skills

General engineering workflows from mattpocock/skills (MIT, see ai/skills/engineering/LICENSE). The project rules above take precedence where they overlap.

Skill	Load when
`ai/skills/engineering/code-review/SKILL.md`	Reviewing a branch, PR or changes since a fixed point
`ai/skills/engineering/codebase-design/SKILL.md`	Designing module interfaces, seams, testability
`ai/skills/engineering/diagnosing-bugs/SKILL.md`	Diagnosing hard bugs and performance regressions
`ai/skills/engineering/domain-modeling/SKILL.md`	Domain terminology, glossary, ADRs
`ai/skills/engineering/pr/SKILL.md`	Writing a PR body
`ai/skills/engineering/prototype/SKILL.md`	Throwaway prototype to answer a design question
`ai/skills/engineering/research/SKILL.md`	Researching a question against primary sources
`ai/skills/engineering/tdd/SKILL.md`	Test-first features or bug fixes
`ai/skills/engineering/wizard/SKILL.md`	Interactive bash wizard for steps only a human can do

Load these only when the user asks for them by name:

Skill	Purpose
`ai/skills/engineering/ask-matt/SKILL.md`	Pick the skill or flow that fits a situation
`ai/skills/engineering/grill-with-docs/SKILL.md`	Interview to sharpen a plan, writing ADRs and glossary
`ai/skills/engineering/implement/SKILL.md`	Implement work from a spec or tickets
`ai/skills/engineering/implement-spec/SKILL.md`	Implement the result of `to-spec` and `to-tickets`
`ai/skills/engineering/improve-codebase-architecture/SKILL.md`	Report deepening opportunities, then grill one
`ai/skills/engineering/retro/SKILL.md`	Retrospective on a coding session
`ai/skills/engineering/setup-matt-pocock-skills/SKILL.md`	One-time setup of issue tracker, labels, domain docs
`ai/skills/engineering/to-spec/SKILL.md`	Turn the conversation into a spec on the tracker
`ai/skills/engineering/to-tickets/SKILL.md`	Break a plan into tracer-bullet tickets
`ai/skills/engineering/triage/SKILL.md`	Triage issues and external PRs
`ai/skills/engineering/wayfinder/SKILL.md`	Plan large work as decision tickets

Completion checklist

Before considering a change complete:

New and renamed files comply with the filename rules in pyproject.toml.
The filename linter passes.
Tests have been added or updated as appropriate.
Relevant pytest tests pass.
Ruff checks pass.
Mypy checks pass where applicable.
Configuration and documentation updated when necessary.
No unrelated changes or unnecessary exceptions introduced.