62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# `.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.
|