ducoterra
022da8e2bc
Foundation (phase 01, verified): - FastAPI app: /api/health, /api/suggestions, /api/chat (placeholder), static frontend served locally (no CDN) - Postgres 17 + pgvector via db/Containerfile + compose.yaml (podman compose up -d db), Alembic initial migration (documents, chunks with vector(768), query_log) - LLM client targeting https://aipi.reeseapps.com/v1 (turbo/embed); scripts/llm_probe.py verified models + 768-dim embeddings live - Conditional debugpy: imported only when DEBUGPY=1 (attach on demand, :5678); logging config for clean single-line logs - Frontend shell: mobile-first chat + Sources pages, tokens, a11y baselines - Tests: 24 unit+integration (99% coverage on app/), ruff + pyright clean, Playwright smoke E2E (3 tests) against a deterministic mock LLM - Planning: .agent/PLAN.md (architecture + LOCKED decisions), AGENTS.md, 6 user stories, 7 phase files (one story / one phase / one Playwright suite each)
3.1 KiB
3.1 KiB
AGENTS.md — Operating Rules for All Agents on This Repo
- Always read
.agent/PLAN.mdfirst. It contains the architecture, the LOCKED DECISIONS, the UI/UX standards, the data model, and the roadmap. Do not design anything that contradicts it. - Follow the phased execution protocol in
.agent/phases/. Work through.agent/phases/todo/in numeric order. When a phase is complete, move its file to.agent/phases/complete/. - Strictly adhere to the LOCKED DECISIONS (PLAN §2). If you believe a LOCKED decision is wrong, stop and flag it — do not silently deviate.
- "One Story, One Phase": each user story in
.agent/user_stories/corresponds to a distinct execution phase that includes its own dedicated Playwright E2E test suite (one test file per story, run in isolation). - "UI Structure Check": before finalizing any UI component, verify that
it follows the layout principles in
.agent/PLAN.md§7 (proper container usage, centered 46rem chat column, full-width tables on Sources — no skinny wasted-space lists) and meets WCAG 2.1 AA basics (semantic landmarks, labels, contrast ≥4.5:1, focus-visible, aria-live for the stream). - "No CDN Rule": all CSS, JS, fonts, and images must be served statically
from within the FastAPI application. No
<script src="https://…">or<link href="https://…">tags in HTML templates unless bundled locally. An integration test enforces this on the index page. - "Debugpy Check": any new entrypoint must keep the conditional import —
debugpyis imported only whenDEBUGPY=1(seeapp/core/debugging.py); default off, never imported otherwise. - Git protocol: Git is mandatory. One atomic, professional commit per
completed phase (Conventional Commits, e.g.
feat(rag): stream RAG answers over SSE with source citations). Always append--no-gpg-sign(the repo also setscommit.gpgsign=false)..agent/is gitignored by design — usegit add -f .agent/…when a commit must record plan changes. - Test gates are non-negotiable: a phase is complete only when unit +
integration tests pass,
app/coverage is >90% (uv run pytest --cov=app --cov-report=term-missing), and the phase's Playwright E2E file passes in isolation (uv run pytest tests/e2e/test_<story>.py -v --no-cov). - Amply log, visibly feed back: server-side, log the required per-turn line (PLAN §9); UI-side, honor the "never stale" feedback contract (PLAN §7.4).
Quick reference
podman compose up -d db # start Postgres 17 + pgvector
cp .env.example .env # once; then edit
uv run alembic upgrade head # apply migrations
uv run uvicorn app.main:app --reload # dev server (add DEBUGPY=1 to debug)
uv run pytest # unit + integration
uv run pytest --cov=app --cov-report=term-missing
uv run playwright install chromium # once
uv run pytest tests/e2e/test_smoke.py -v --no-cov
uv run ruff check . && uv run pyright # lint + types