Initial commit

.agents/README.md

@@ -0,0 +1,61 @@
+# `.agents/` — Subagent Briefs
+
+This directory contains one Markdown brief per subagent referenced by `PLAN.md`. Each brief defines:
+- the **assigned LLM model** to use,
+- the subagent’s **mission**,
+- responsibilities and guardrails,
+- expected **deliverables** and **definition of done**.
+
+These files are intended to be used by a human or an orchestration tool that can spawn specialized agents per task.
+
+---
+
+## Agent roster
+
+| Agent | Model | File |
+|---|---|---|
+| `orchestrator` | `github-copilot/gpt-5.2` | `./.agents/orchestrator.md` |
+| `backend-api` | `github-copilot/claude-sonnet-4.5` | `./.agents/backend-api.md` |
+| `worker-media` | `github-copilot/claude-sonnet-4.5` | `./.agents/worker-media.md` |
+| `frontend-ui` | `github-copilot/gpt-5.2` | `./.agents/frontend-ui.md` |
+| `k8s-infra` | `github-copilot/claude-sonnet-4.5` | `./.agents/k8s-infra.md` |
+| `qa-review` | `github-copilot/claude-haiku-4.5` | `./.agents/qa-review.md` |
+
+---
+
+## How to use
+
+### 1) Pick tasks from `PLAN.md`
+In `PLAN.md`, use the **Task breakdown (MVP)** section as the source of truth for what needs to be done.
+
+### 2) Assign each task to the appropriate agent
+- API/DB/presigning routes → `backend-api`
+- Media processing and derived generation → `worker-media`
+- UI tree + responsive layout → `frontend-ui`
+- Helm/manifests/affinity/Tailscale ingress → `k8s-infra`
+- Test plan + edge cases review → `qa-review`
+- Cross-team coordination, contract alignment → `orchestrator`
+
+### 3) Run agents in parallel where safe
+Good parallel splits:
+- `backend-api` and `worker-media` can implement in parallel if they agree on DB/job payloads.
+- `frontend-ui` can proceed in parallel once API response shapes are agreed.
+- `k8s-infra` can proceed in parallel once container ports/env vars are known.
+
+### 4) Maintain contracts and avoid drift
+Before an agent starts, the `orchestrator` should confirm:
+- DB schema fields and enums
+- MinIO key conventions
+- API request/response shapes
+- Worker job payloads and retry/idempotency rules
+
+### 5) Update `PLAN.md` when decisions change
+If any “Locked” decision changes (endpoints, prefixes, storage policy), update `PLAN.md` first, then propagate to agents.
+
+---
+
+## Conventions
+
+- **Never delete/mutate** external archive objects under `originals/`.
+- Presigned URLs returned to browsers must use **tailnet HTTPS** on `minio.<tailnet-fqdn>` to avoid mixed-content blocking.
+- Prefer Pi-friendly defaults: low worker concurrency, avoid scheduling heavy pods on Pi 3.