From cfb6abd84278fa229b81eddf6c21a00fb49c2b47 Mon Sep 17 00:00:00 2001 From: Bu5hm4nn Date: Wed, 25 Mar 2026 11:18:31 +0100 Subject: [PATCH] docs: compact agent policy into yaml --- AGENTS.md | 129 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 67 insertions(+), 62 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8d56c71..e8311b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,73 +1,78 @@ -# AGENTS.md +policy: + test_loop: + required: true + rules: + - run the app locally after changes + - run real tests against the running app + - for UI work, prefer Playwright/browser-visible checks + - verify the exact changed route/page -## Engineering Rules + local_first: + required: true + rules: + - use local Docker/OrbStack before deploy + - deploy only after local behavior is verified -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. + confidence: + rules: + - browser-visible behavior beats log-only confidence + - do not treat returned HTML as success if the page still has runtime/UI errors + - do not claim a feature is live unless the rendered UI consumes it -2. **Local Docker first, deploy later.** - - Use local Docker/OrbStack for fast feedback. - - Only deploy after local behavior is verified. + development_flow: + tdd: [red, orange, green] + build_rule: + - make build must enforce lint first + - if build is green, lint is already green -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. + review: + required_before_merge: true + install_tool: review_install_agents + rules: + - install review agents with the review_install_agents tool before running the review workflow if needed + - use the full parallel review flow before merging worktree or sub-agent changes to main + - do not merge based only on compile/test results -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. + backlog: + review_after_each_sprint: true + source_of_truth: + - docs/roadmap/ROADMAP.yaml + - docs/roadmap/backlog + - docs/roadmap/in-progress + - docs/roadmap/done + - docs/roadmap/blocked + - docs/roadmap/cancelled + rules: + - add newly discovered backlog items + - reorder priorities and dependencies based on new knowledge + - capture follow-up work explicitly -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. + compatibility: + rules: + - preserve shared domain compatibility across parallel worktrees + - LombardPortfolio must remain available for strategy/core compatibility until intentionally removed everywhere -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). +learnings: + nicegui: + - ui.header must be a top-level page layout element + - do not nest ui.header inside ui.column or similar containers -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. + options_page: + - loading all expiries/chains before first paint can make the page appear broken + - render fast first, then load incrementally -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. + nicegui_fastapi: + - pages should not assume request.app.state is the right access path for shared services + - prefer an explicit runtime/service registry -9. **Review the backlog after each sprint.** - - After each completed sprint or merged feature slice, review `docs/roadmap/ROADMAP.yaml` and the per-task YAML files. - - 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. + docker_dev: + - do not mount the whole repo over /app when the image contains required runtime scripts + - prefer narrower mounts like ./app and ./config -## 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 +validation_checklist: + - local Docker stack starts cleanly + - /health returns OK + - changed page opens in browser automation + - no visible 500/runtime error + - screenshot artifact captured when useful + - relevant logs checked