Agent Instructions

Working rules for agents in this repo. A merge of the Karpathy coding guidelines and the Chain of Truth method: validated artifacts are the source of truth, AI is a generator and accelerator.

Please Response in extremely concise and precise.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

State your assumptions explicitly. If uncertain, ask.
If multiple interpretations exist, present them — don't pick silently.
If a simpler approach exists, say so. Push back when warranted.
If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

No features beyond what was asked.
No abstractions for single-use code.
No "flexibility" or "configurability" that wasn't requested.
No error handling for impossible scenarios.
If you write 200 lines and it could be 50, rewrite it.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

Don't "improve" adjacent code, comments, or formatting.
Don't refactor things that aren't broken.
Match existing style, even if you'd do it differently.
If you notice unrelated dead code, mention it — don't delete it.
Remove imports/variables/functions that your changes made unused.

The test: every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Turn tasks into verifiable goals, and for multi-step work state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]

This repo has no automated tests, so verification means running something: hit the endpoint, run the job, look at the files it produced.

5. Chain of Truth — documents first, then code

docs/ is the source of truth, not the chat prompt.

Document	Contents
`docs/requirements.md`	Numbered `REQ-xxx` requirements. Changes only with the user's approval.
`docs/design.md`	Data schema, API contract, disk layout. Each section names the `REQ-xxx` it serves.
`docs/tasks.md`	Implementation steps + verification criteria, status `[TODO]`/`[DONE]`.

The rules:

Before writing feature code, make sure a REQ-xxx covers it. If none does, propose adding one to the user first.
Once a task is finished and verified, flip its status in docs/tasks.md to [DONE] in the same commit.
If the implementation diverges from docs/design.md, update the design — never let a document lie.
Use relative paths in markdown (./, ../), not absolute ones.

6. Repo rules

Package manager: uv. No pip, poetry, or bare python/python3. Dependencies live in requirements.txt; install them with uv pip install -r requirements.txt and run scripts with uv run. The Docker image installs the same file, so the two environments cannot drift.
File size limit: 400 lines. Any new or refactored file that exceeds it must be split into smaller, logical modules.
**sam3/ is a vendor copy** of Meta's library. It's a dependency, not app code — don't add scripts there or edit anything inside it.
Never write into the user's video archive. All output goes under data/.
Secrets (HF_TOKEN) come from .env only; they never belong in code or docs.

7. UI/UX

Frontend work follows ui-ux-pro-max: generate the design system first (style, palette, typography), then build against it, then validate before delivering. Consistency across pages beats per-page cleverness.

This app is a dense internal tool, not a landing page. Its screens are for long review sessions in front of a screen: the video frame and the annotation canvas are the content, everything else is chrome and stays quiet. No decorative gradients, no marketing motion.

Pre-delivery checklist — a UI task is not [DONE] until all of it passes:

No emoji as icons (SVG only: Heroicons/Lucide)
cursor: pointer on every clickable element
Hover states with smooth transitions (150–300 ms)
Text contrast at least 4.5:1
Focus states visible for keyboard navigation
prefers-reduced-motion respected
Responsive at 375 / 768 / 1024 / 1440 px

The review editor also has to survive keyboard-only use — see docs/design.md, "Frontend".

8. Domain invariants

Two things are easy to break without noticing, and breaking either makes the whole system lie:

Stable val split. Once a frame lands in val, it stays in val forever. Otherwise he base-vs-new mAP comparison is meaningless.
One set_image per image. Sam3Processor.set_image() runs the vision backbone; set_text_prompt()only re-runs the grounding head against the cachedbackbone_out. n N-prompt job calls set_image` once per image and loops prompts over that same tate. Don't restructure this into set_image-per-prompt.

9. Scalability & Portability

Never hardcode something that will change across environments.

Hardware Agnosticism: Do not hardcode hardware requirements (e.g., GPU configurations in docker-compose.yml) directly into base configuration files. Instead, use dynamic startup scripts (like start.sh) or environment overrides to detect the host's capabilities and inject the appropriate settings automatically.
Portability: The app must be fully deployable and scalable on any device (from a CPU-only laptop to a massive multi-GPU rig) without requiring manual code edits to run.
Dynamic Configuration: Do not hardcode absolute IP addresses, local network paths, or machine-specific environment variables in code. Rely on relative paths and configuration files to ensure maximum scalability.

6.0 KiB Raw Blame History Unescape Escape