vault-dash/AGENTS.md

policy: subagent_usage: required: true rules: - prefer sub-agents for parallelizable implementation work - use sub-agents when implementing independent roadmap items - create worktrees for sub-agents working on the same codebase - review sub-agent output before merging to main - use agent: implementation-reviewer for code quality checks - use agent: qa-validator for end-to-end validation - chain sub-agents for multi-step workflows (plan → implement → review) - always use sub-agents unless the task is trivial or requires direct interaction

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

local_first: required: true rules: - use local Docker/OrbStack before deploy - deploy only after local behavior is verified

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

development_flow: tdd: [red, orange, green] build_rule: - make build must enforce lint first - if build is green, lint is already green

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

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

compatibility: rules: - preserve shared domain compatibility across parallel worktrees - LombardPortfolio must remain available for strategy/core compatibility until intentionally removed everywhere

learnings: nicegui: - ui.header must be a top-level page layout element - do not nest ui.header inside ui.column or similar containers

options_page: - loading all expiries/chains before first paint can make the page appear broken - render fast first, then load incrementally

nicegui_fastapi: - pages should not assume request.app.state is the right access path for shared services - prefer an explicit runtime/service registry

docker_dev: - do not mount the whole repo over /app when the image contains required runtime scripts - prefer narrower mounts like ./app and ./config

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

forgejo_ci: viewing_job_logs: web_ui: url: "http://git.uncloud.vpn:3000/bu5hm4nn/vault-dash/actions" steps: - Navigate to Actions tab in Forgejo UI (VPN access required) - Click on the workflow run to see job status - Expand failing job (lint/test/type-check/build/deploy) - Click on failed step to see detailed logs runner_logs: ssh: "ssh root@5.75.141.4" command: "docker logs forgejo-runner --tail 100" job_workspace: "/opt/forgejo-runner/data/" common_failures: missing_dependency: symptom: "ModuleNotFoundError: No module named 'X'" fix: "Add package to requirements.txt AND .forgejo/workflows/deploy.yaml (test + type-check jobs)" type_error: symptom: "error: Incompatible types..." fix: "Run mypy app --ignore-missing-imports locally to reproduce" test_failure: symptom: "FAILED test_name" fix: "Run failing test locally with pytest -xvs"

pre_merge_checklist:

• run pytest tests/ -v --tb=short locally and ensure all new/changed tests pass
• run /review to get implementation review and QA validation
• verify CI passes on Forgejo (lint, test, type-check, build, deploy)
• address all review comments before merging to main