# `.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.