diff --git a/AGENTS.md b/AGENTS.md index be609e9..c69707c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,7 @@ This repo holds **two independently-deployed services**. They share a repo so th Three rules follow from this, and breaking any of them breaks a deploy: 1. **Two dependency sets, never merged.** `backend/` and `agent/` each own a `pyproject.toml` + `uv.lock` and resolve independently. They *cannot* be combined: Command Center locks `mcp` 1.28.1 (via `fastmcp`), the agent locks 2.2.0 — different majors. Dependabot watches both separately. -2. **CI is path-filtered.** `deploy.yml` carries `paths-ignore: agent/**`; `agent.yml` carries `paths: agent/**`. Without these, an agent-only change would rebuild and redeploy Command Center. **If you ever add required status checks to `master`, read the CAUTION comment at the top of `deploy.yml` first** — a path-skipped workflow reports nothing, so a required check would hang every PR that doesn't touch its paths. +2. **CI path filtering is asymmetric, and that is deliberate.** `push` is filtered (`deploy.yml` ignores `agent/**`; `agent.yml` only matches `agent/**`), so a change to one service never redeploys the other. `pull_request` is **never** filtered. `master` requires four status checks — `Backend tests (sqlite)`, `Backend tests (postgres)`, `Frontend audit + build`, `Agent checks` — and GitHub reports *no status at all* for a workflow a path filter skipped, so a filtered PR trigger would hang every PR that missed it, presenting as a stuck check rather than a config error. Adding `paths:` to a `pull_request` trigger in this repo will break merging. 3. **Both packages are named `app`.** `backend/app` and `agent/app` collide on import. Never put `agent/` on `sys.path` in backend tests — load agent modules by file path instead, as `backend/tests/test_agent_contract.py` does. The agent stays a separate deployment on purpose: its runs hold an LLM connection for up to 270s (`kill_timeout = 300` in `agent/fly.toml`) and must not compete with HLS segment serving on Command Center's 1 GB machine. It is also what makes self-hosting the agent (per-org `osa_` keys, `AGENT_MODE=poll`) possible.