Imported from luatducvo/3D-scene (
AGENTS.md). Install upstream withnpx skills add luatducvo/3D-scene. Copyright stays with the author.
Working in this repository
Photos of a room become a metric 3D Scene with Objects, a Scene Graph and grounded question
answering. The backend is one uv workspace: pyproject.toml, uv.lock and main.py sit at the
repository root, code under backend/. The frontend is a Next.js app in frontend/.
Read before you work
- Reading or changing code under
backend/orfrontend/: that folder's AGENTS.md (backend, frontend) for its rules and done check. - Any ticket: docs/SPEC.md for scope and acceptance. ADRs in docs/adr/ amend it where their status line says so (0004, 0005, 0006, 0008, 0009).
- Unfamiliar code or a cross-module change: docs/architecture/overview.md, then the page for the area: pipeline (Stages, Workspace, Job runner, Publication), compute (Targets, compute contract, GPU image, providers), api (endpoints, SSE, lifecycle rules, schema, QA agent), frontend, extending (new Algorithm, Relation, QA tool, layer, provider).
- Naming a domain concept: CONTEXT.md; use its terms, never its Avoid words.
- GPU adapters or a live run: docs/GPU-INTEGRATION.md.
Commands
uv run main.py --help from the repository root lists every command. uv run main.py test runs
pytest against a disposable Postgres container, so Docker must be running; test-unit runs the
tests without the db marker and needs no Docker. lint and format run Ruff with the rules in
pyproject.toml. Extra arguments go to pytest or Ruff. The backend-api and backend-worker
entries in .claude/launch.json run the fake pipeline on the test database that test starts. Frontend scripts are in frontend/package.json; its done check is in
frontend/AGENTS.md.
Rules
- Test through the agreed seams in SPEC with fake Algorithms (
*.fake) andScriptedLLM; automated tests never need a GPU. Record live GPU checks in the GPU-INTEGRATION live check log, separately from local test results. - After changing API routes or models, run
uv run main.py openapi, thennpm run api:syncinfrontend/.frontend/src/lib/api/schema.d.tsis generated. - Repository text is English (code, comments, logs, API messages, docs); only
frontend/messages/*.jsonis localized. - Keep docs live: a behavior change updates the architecture page that describes it in the same
change. A hard-to-reverse, surprising trade-off gets the next ADR number in
docs/adr/. - Before reporting a change as done, run
/done-checkand include its report. - Agents may commit when the user asks; agents never push.
Issue tracker
Issues live as local markdown files under .scratch/<feature>/issues/. See docs/agents/issue-tracker.md.
Triage labels
Default five triage roles plus this repo's delivery states, recorded on the **Status:** line. See docs/agents/triage-labels.md.
Domain docs
Single-context: CONTEXT.md plus ADRs in docs/adr/. See docs/agents/domain.md.
