mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-11-13 09:13:30 +01:00
Bobby NoelteandClaude Opus 5.5
d68f040206
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>
94 lines
4.8 KiB
Markdown
94 lines
4.8 KiB
Markdown
# 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](https://github.com/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.
|