harmonyhub-py AGENTS.md

harmonyhub-py

---

1) Golden Rules

1. Think → Memory → Tools → Code → Memory. Use code-reasoning; search Memory and claude-context first; minimal diff; write learnings back.
2. Tests are truth. Failures → fix code first. Change tests only if clearly wrong spec.
3. Minimal diff. Add tests before code. Keep simple.
4. Consistency > cleverness. Follow SOPs and stack idioms.
5. Memory multiplies. Persist decisions, patterns, error signatures, proven fixes.
6. Files ≤ 1000 lines. Exceed → refactor (see §5).
7. No extensive docs/summaries/comments unless requested.
8. No --autogenerate for Alembic migrations; write manually.
9. No cat to create files; use tools.
10. Log default: logger.debug. Important events: logger.info. Issues only: logger.warning/error. No print.
11. Caveman skill applies to all writes here.

Prefer local changes over cross-module refactors.

---

2) Task Bootstrap Pattern

<!-- plan:start
goal: <one line clear goal>
constraints:
- Python 3.13; Reflex UI; FastAPI; SQLAlchemy 2.0; Alembic; Pydantic; appkit_mantine;
- logging: no f-strings in logger calls
- files ≤ 1000 lines; apply design patterns where appropriate
- minimal diff; add/adjust tests first
definition_of_done:
- tests pass; coverage ≥ 80% (non-Reflex classes & Reflex states); lint/type checks clean; memory updated
steps:
1) Search Memory for "<keywords>"
2) Draft/adjust failing test to capture expected behavior
3) Implement minimal code change
4) Run task test; iterate until green
5) Update Memory: decisions, patterns, error→fix
plan:end -->

---

3) Tooling Decision Matrix

Situation	Primary	Secondary	Store to Memory
API/pattern uncertainty	Context7	—	Canonical snippet + link; edge cases
Ecosystem bug/issue	DuckDuckGo	Context7	Minimal repro; versions; workaround
Repeated test failure	Memory (search)	Context7	Error signature → fix; root cause
New feature scaffold	Context7	—	How‑to snippet; checklist
House style/tooling	This file	Context7	Checklist results