52 lines
No EOL
3.3 KiB
Markdown
52 lines
No EOL
3.3 KiB
Markdown
# Collaboration Playbook (AGENTS.md)
|
||
|
||
## 1. Roles & Responsibilities
|
||
- **Frontend Lead** (`@frontend-lead`): Owns the Next.js/TanStack PWA, UI consistency, and Supabase integration.
|
||
- **Backend Lead** (`@backend-lead`): Maintains the FastAPI service, data models, audit logging, and security hardening.
|
||
- **DevOps / CI‑CD Engineer** (`@devops-engineer`): Manages GitHub Actions pipelines, Docker images, Coolify deployments, and monitoring.
|
||
- **Quality Assurance** (`@qa-engineer`): Writes and reviews automated tests, conducts code reviews, and verifies security compliance.
|
||
- **Product Owner** (`@product-owner`): Prioritises backlog items, defines acceptance criteria, and ensures alignment with freight‑forwarding use‑cases.
|
||
|
||
## 2. Pull‑Request Workflow
|
||
1. **Branch Naming** – `feature/<short‑description>` or `bugfix/<issue‑id>`.
|
||
2. **Commit Conventions** – Use conventional commits (e.g., `feat: add soft‑delete endpoint`, `fix: correct audit timestamp`).
|
||
3. **PR Title** – Clear, prefixed with type (`feat:`, `fix:`, `chore:`).
|
||
4. **PR Description** – Include:
|
||
- What problem it solves.
|
||
- How it aligns with the freight‑forwarding roadmap (tracking, bidding, payments).
|
||
- Any required migrations or DB changes.
|
||
- Screenshots or API examples if UI changes.
|
||
5. **Review Process** – At least one reviewer from a different role must approve.
|
||
- Frontend PR → reviewed by Backend Lead (or QA).
|
||
- Backend PR → reviewed by Frontend Lead (or QA).
|
||
6. **Merging** – Squash and merge; delete the branch after merge.
|
||
7. **Post‑merge** – CI runs automatically; if successful, the DevOps Engineer triggers the Coolify deployment via the webhook.
|
||
|
||
## 3. Backlog & Issue Tagging
|
||
- **Labels** (GitHub):
|
||
- `enhancement` – new feature (e.g., in‑app bidding).
|
||
- `bug` – defect or security issue.
|
||
- `tech‑debt` – refactoring, performance, or security improvements.
|
||
- `api‑change` – breaking change to the FastAPI contract.
|
||
- `frontend` – UI/PWA related work.
|
||
- `backend` – backend service changes.
|
||
- **Milestones** – Align with release cycles (e.g., `v1.0‑beta`, `v1.0‑release`).
|
||
- **Sprint Planning** – Use the `kanban-worker` skill to break down high‑level epics into actionable tickets.
|
||
|
||
## 4. Commit & Release Cadence
|
||
- **Daily** – Small, incremental commits; push to `main` after CI passes.
|
||
- **Weekly** – Dedicated “integration” day to test end‑to‑end flows (API ↔ PWA ↔ Supabase).
|
||
- **Release** – Tag a new version (`vX.Y.Z`) after a successful deployment to Coolify and verification of critical paths (auth, soft‑delete, audit log).
|
||
|
||
## 5. Security & Compliance
|
||
- All API endpoints must validate input and return proper HTTP status codes.
|
||
- Sensitive data (DB passwords, Supabase keys) are stored in GitHub Secrets and injected at runtime.
|
||
- Audit logs are immutable; they are shipped to a separate log store (e.g., CloudWatch) via a background worker.
|
||
- Run `npm audit` and `pip audit` in CI; fail the job on high‑severity findings.
|
||
|
||
## 6. Communication Channels
|
||
- **Slack/Discord** – `#freight‑dev` for quick questions; `#announcements` for release notes.
|
||
- **GitHub Discussions** – For design proposals and long‑term roadmap discussions.
|
||
- **Weekly Sync** – 30‑minute video call to review progress, blockers, and upcoming priorities.
|
||
|
||
*Document last updated: 2026‑06‑10* |