FrameWorkers — Cursor rules

# FrameWorkers — Cursor rules

Multi-agent stack: Flask backend + Assistant + Director; creative pipeline agents live under `agents/`. **Architecture and APIs belong in repo / package READMEs** — read them when needed; this file is only binding principles.

## Where things live
- `dynamic-task-stack/` — Backend (`:5002`): Task Stack `/api/`, Assistant `/api/assistant/`, workspace under `Runtime/`.
- `director_agent/`, `director_nostack/` — Orchestrators over HTTP only (no shared imports with `interface/`).
- `agents/` — All agent framework + pipeline agents; `Assistant` uses `from agents import …` and `AGENT_REGISTRY`.
- `inference/` — LLM / multimodal; **no imports from other top-level packages**.
- `interface/` — Vue 3 + Vite; HTTP client `src/services/api.js`, polling `polling.js`.

## Environment (new shell sessions)
- Many shells (and Cursor’s tool terminal) start **without** your login profile, so **`conda` may be missing** until you run **`source ~/.bashrc`** (or the file that registers Miniconda on your machine). Then **`conda`** should be on `PATH` (often `…/miniconda3/bin`).
- **Always** run **`conda activate frameworkers`** **before** Python, tests, or other project commands (`pytest`, `python -m …`, backend/director runs, etc.). Use the **same** shell for the follow-up command.
- If unsure which envs exist, run **`conda env list`** after the steps above; project work targets the **`frameworkers`** env (not necessarily `base`).

## Invariants (do not break)
- `POST /api/assistant/execute`: `agent_id`, `task_id`, nested `execute_fields`. **`global_memory` is top-level on execution inputs**, not inside `execute_fields` / `InputBundleV2`; **`_memory_brief` in execute_fields is ignored.**
- Post-success global memory summary is **strict** (failure → error response); no silent empty fallback.
- LLM agent outputs: **JSON only** (no markdown fences); unknown → `""` / `[]`, not `null`; top-level `meta` matches `agents/common_schema.Meta` only (no extra keys such as `project_id`).
- Asset / content ID conventions and evaluator layers: follow agent package READMEs and existing schemas.

## Principles (MUST)
1. **Doc-first** — Code changes include updates to that package’s `README.md`. Cross-package contracts (HTTP API, schemas, descriptors) → update **every** affected README.
2. **Read-before-write** — Read the relevant README(s), then the target file(s) and direct dependencies; reuse existing helpers, avoid duplicate patterns.
3. **Full-stack** — If you change backend routes or response shapes: sync `interface/src/services/api.js`, Vue consumers, and `director_agent/api_client.py` as needed.
4. **Cross-package consistency** — Registry, descriptors, shared models: search across packages and keep a single coherent contract.
5. **No silent LLM / JSON fallbacks** — Do not hide failures by re-parsing markdown, substring-recovering JSON, or retrying without JSON mode. Product-level fallbacks are allowed only if **logged** and **documented** in README. `LLMClient.chat_json`: see `inference/README.md`.
6. **Focused changes** — Edit only what the task requires; match local naming, style, and abstractions.

## When layout or entrypoints change
Update **root `README.md` and/or the affected package READMEs** (and trim this file if any pointer here becomes wrong). Keep `.cursorrules` principle-oriented, not a second architecture doc.