porthole/.agents

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