74 lines
3.2 KiB
Markdown
74 lines
3.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## Engineering Rules
|
|
|
|
1. **Always close the test loop.**
|
|
- Do not stop after code changes.
|
|
- Run the app locally.
|
|
- Run real tests against the running app.
|
|
- For UI work, prefer real browser tests (Playwright) over assumptions.
|
|
- Verify the exact route/page that changed.
|
|
|
|
2. **Local Docker first, deploy later.**
|
|
- Use local Docker/OrbStack for fast feedback.
|
|
- Only deploy after local behavior is verified.
|
|
|
|
3. **Browser-visible behavior beats log-only confidence.**
|
|
- A route returning HTML is not sufficient.
|
|
- Confirm page content renders and no runtime/500 error is visible.
|
|
|
|
4. **When using parallel worktrees, preserve shared domain models.**
|
|
- New feature branches must not silently remove compatibility types used elsewhere.
|
|
- In this project, `LombardPortfolio` is still required by strategy/core modules.
|
|
|
|
5. **Do not claim a feature is live unless the UI is wired to it.**
|
|
- Backend service existence is not enough.
|
|
- The rendered page must actually consume the live data path.
|
|
|
|
6. **Always work with TDD principles: Red, Orange, Green.**
|
|
- Start by making the failure visible with a test or reproducible check (Red).
|
|
- Iterate toward partial progress while keeping the failure scoped and observable (Orange).
|
|
- Finish only when the behavior is implemented and the test loop passes cleanly (Green).
|
|
|
|
7. **Linting is part of the build, not an optional extra step.**
|
|
- `make build` must enforce linting first.
|
|
- Do not treat lint as a separate, skippable preflight.
|
|
- If the build is green, lint must already be green.
|
|
|
|
8. **Run the `/review` skill before merging worktrees back.**
|
|
- Any worktree/sub-agent implementation must go through `/review` before integration to `main`.
|
|
- Do not merge worktree changes back based only on compile/test results.
|
|
- Review first, then integrate.
|
|
|
|
9. **Review the backlog after each sprint.**
|
|
- After each completed sprint or merged feature slice, review `docs/ROADMAP.md`.
|
|
- Add any new backlog items uncovered during implementation, testing, review, or deployment.
|
|
- Reorder priorities and update dependencies based on new knowledge.
|
|
- Capture follow-up work explicitly instead of relying on memory or chat context.
|
|
|
|
## Project Learnings
|
|
|
|
### NiceGUI layout constraint
|
|
- `ui.header()` must be a top-level page layout element.
|
|
- Do not nest `ui.header()` inside `ui.column()` or other containers.
|
|
|
|
### Options page performance lesson
|
|
- Loading all expiries/chains before first paint can make the page appear broken.
|
|
- Prefer rendering fast, then loading data incrementally.
|
|
|
|
### FastAPI/NiceGUI integration lesson
|
|
- NiceGUI page handlers should not assume `request.app.state.*` is always the right access path for shared services.
|
|
- Use an explicit runtime/service registry if needed.
|
|
|
|
### Docker development lesson
|
|
- Avoid mounting the whole repo over `/app` when the image contains required runtime scripts.
|
|
- Mount narrower paths in dev (`./app`, `./config`) to preserve image-managed files like entrypoints.
|
|
|
|
## Validation Checklist for UI Changes
|
|
- [ ] Local Docker stack starts cleanly
|
|
- [ ] `/health` returns OK
|
|
- [ ] Changed page opens in browser automation
|
|
- [ ] No visible 500/runtime error
|
|
- [ ] Screenshot artifact captured
|
|
- [ ] Relevant logs checked
|