codehava-agent-kit 1.0.0

package/templates/AGENTS.md

@@ -0,0 +1,268 @@
+# AGENTS.md — Instruksi AI untuk Proyek Ini
+> Letakkan file ini di **root folder project** (sejajar `package.json`).
+> Dibaca otomatis oleh Antigravity, Cursor, Claude Code, dan AI IDE lainnya.
+> **Stack diverifikasi: Maret 2026**
+
+---
+
+## 🎯 Identitas Proyek
+
+- **Nama Proyek:** [nama proyek]
+- **Tipe:** [Web App / Mobile / Marketplace]
+- **Stack:** Next.js **16.1** (App Router) + Flutter **3.41.2** + PostgreSQL **17** + Prisma **7** + Better Auth **1.5**
+- **Runtime:** Node.js **22 LTS**
+- **Data Fetching:** Server Components (default) + TanStack Query (client mutations/realtime)
+- **Arsitektur:** Modular Monolith — 1 Next.js app + 1 BullMQ worker container
+- **Payment:** Xendit (split payment / disbursement) — hanya app dengan transaksi keuangan
+- **Realtime:** Socket.io + BullMQ **5.x** (Redis **7.4 LTS**, shared instance)
+- **Push Notif:** Firebase FCM — **hanya `firebase_messaging`**, Analytics/Crashlytics JANGAN diaktifkan
+- **Storage:** NEO Object Storage Biznet Gio (S3-compatible, Indonesia)
+- **CDN:** Cloudflare Free (DPA wajib di-accept) + NEO untuk serve file upload
+- **Deploy:** Coolify di VPS Biznet Gio (Indonesia — comply UU PDP)
+- **IDE:** Antigravity
+- **Stack diverifikasi:** Maret 2026
+
+---
+
+## 📁 Dokumen Referensi
+
+| Dokumen | Lokasi | Berisi |
+|---------|--------|--------|
+| PRD | `docs/01-PRD.md` | Fitur, user stories (REQ-XXX), scope MVP |
+| Tech Design | `docs/02-TECH-DESIGN.md` | Stack, schema DB, API contracts, code patterns |
+| UI Guidelines | `docs/03-UI-GUIDELINES.md` | Komponen shadcn, warna, Flutter design |
+| Backlog | `docs/04-BACKLOG.md` | Task aktif sprint ini |
+| Deployment | `docs/05-DEPLOYMENT.md` | Coolify, Dockerfile, CI/CD, backup |
+| Dev Log | `docs/06-DEVELOPMENT-LOG.md` | Kenapa setiap keputusan teknis dibuat |
+| Feature Specs | `specs/NNN-nama-fitur.md` | Blueprint fitur sebelum coding |
+
+**Antigravity agent config:**
+
+| File | Fungsi |
+|------|--------|
+| `.antigravity/rules.md` | Rules selalu aktif tiap sesi |
+| `.agent/skills/` | 8 skills — auto-load saat relevan |
+| `.agent/workflows/` | 6 workflows — panggil via `/nama` |
+| `.agent/mcp_config.json` | Config MCP servers |
+
+---
+
+## ⚙️ 10 Aturan Coding — WAJIB
+
+### 1. Tanya dulu, coding belakangan
+Jika ada ambiguitas → tanya sebelum generate kode panjang.
+Untuk fitur size M atau L: cek `specs/` dulu — jika ada spec, ikuti acceptance criteria di sana.
+
+### 2. Satu fokus per sesi
+Jika diminta buat form login → **hanya buat form login**. Jangan ubah layout atau routing.
+
+### 3. Jangan hapus kode tanpa konfirmasi
+Tampilkan dulu apa yang akan dihapus → minta konfirmasi sebelum lanjut.
+
+### 4. TypeScript strict — no `any`, import Prisma dari generated path
+```typescript
+// ❌ Prisma 7: ini sudah tidak valid
+import { User } from '@prisma/client'
+
+// ✅ Prisma 7: pakai generated path
+import { User } from '@/generated/prisma'
+```
+
+### 5. Error handling wajib di setiap async function
+```typescript
+try {
+  const data = await prisma.user.findMany({ take: 20 })
+} catch (error) {
+  console.error('[user:findMany]', error)
+  throw error
+}
+```
+
+### 6. Loading + Empty + Error state wajib
+Setiap komponen yang fetch data HARUS punya ketiga state ini.
+
+### 7. Cek komponen yang sudah ada dulu
+Sebelum buat komponen baru → cek `/components/ui/` dan `/components/[feature]/`.
+
+### 8. Mobile-first untuk semua UI Web
+```tsx
+<div className="flex flex-col md:flex-row gap-4">
+```
+
+### 9. Env vars tidak pernah di-hardcode
+```typescript
+// ❌ const url = "https://xendit.co"
+// ✅ const url = process.env.XENDIT_BASE_URL
+```
+
+### 10. Next.js 16 — `params` DAN `headers()` wajib di-await
+```typescript
+// ❌ Next.js 14 style — error di Next.js 16
+export default function Page({ params }: { params: { id: string } }) {
+  const { id } = params
+}
+const session = await auth.api.getSession({ headers: headers() })
+
+// ✅ Next.js 16 — params dan headers() sekarang async
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+}
+const session = await auth.api.getSession({ headers: await headers() })
+```
+
+### Format commit
+```
+feat(auth): tambah login Google OAuth
+fix(payment): perbaiki webhook Xendit tidak terproses
+chore(deps): update Next.js ke 16.1
+```
+
+---
+
+## 🗄️ Database (Prisma 7 + PostgreSQL 17)
+
+### Setup Client Singleton (`lib/db/index.ts`)
+```typescript
+import { PrismaClient } from '@/generated/prisma'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! })
+const globalForPrisma = globalThis as unknown as { prisma: PrismaClient }
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({ adapter })
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma
+```
+
+### Schema Generator (`prisma/schema.prisma`)
+```prisma
+generator client {
+  provider = "prisma-client"
+  output   = "../src/generated/prisma"
+}
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+```
+
+### Aturan Query
+- Selalu `take` + `skip` pada `findMany` — tidak ada query tanpa limit
+- Soft delete: `deletedAt DateTime?` — jangan hard delete data penting
+- Semua tabel: `createdAt @default(now())` + `updatedAt @updatedAt`
+- Multi-tabel: `prisma.$transaction(async (tx) => { ... })`
+- Migration dev: `npx prisma migrate dev` | Production: `npx prisma migrate deploy`
+
+---
+
+## 💳 Xendit Payment
+
+```typescript
+// Webhook — WAJIB await headers()
+export async function POST(req: Request) {
+  const callbackToken = (await headers()).get('x-callback-token')
+  if (callbackToken !== process.env.XENDIT_CALLBACK_TOKEN) {
+    return Response.json({ error: 'Unauthorized' }, { status: 403 })
+  }
+  const payload = await req.json()
+  await paymentQueue.add('process-webhook', payload, { attempts: 3 })
+  return Response.json({ received: true })
+}
+```
+
+**Aturan:** Selalu verifikasi `x-callback-token`. Enqueue ke BullMQ — jangan proses langsung.
+
+---
+
+## 🔌 Socket.io + BullMQ
+
+```typescript
+// Worker emit ke client setelah job selesai
+worker.on('completed', (job, result) => {
+  io.to(`user_${result.userId}`).emit('payment:updated', result)
+})
+
+// Redis client
+export const redis = new Redis(process.env.REDIS_URL!, {
+  maxRetriesPerRequest: null,  // required untuk BullMQ
+})
+```
+
+---
+
+## 🔒 Security + UU PDP
+
+```typescript
+// API Route — WAJIB await headers()
+const session = await auth.api.getSession({ headers: await headers() })
+if (!session) return Response.json({ error: 'Unauthorized' }, { status: 401 })
+```
+
+- ✅ Semua input divalidasi Zod sebelum masuk DB
+- ✅ Firebase: hanya `firebase_messaging` — Analytics/Crashlytics = OFF
+- ✅ Cloudflare DPA + Firebase DPT wajib di-accept (sekali oleh admin)
+- ✅ Log tidak print password, token, NIK, nomor rekening
+- ✅ Data sensitif (NIK, rekening) dienkripsi dengan pgcrypto di DB
+
+---
+
+## 📝 Format Prompt Efektif
+
+```
+[KONTEKS] Fitur: [nama fitur]
+[SPEC] Baca specs/NNN-nama.md jika ada
+[TUGAS] Yang perlu dibuat: [deskripsi spesifik]
+[CONSTRAINT] Jangan ubah: [file/komponen yang tidak boleh diubah]
+use context7
+```
+
+## ⚡ Workflows
+
+### Planning (sebelum coding)
+| Command | Gunakan ketika |
+|---------|----------------|
+| `/vibe-plan` | **Mulai project baru** — research → PRD → tech design → build plan |
+
+### Build (saat coding)
+| Command | Gunakan ketika |
+|---------|----------------|
+| `/new-feature` | Mulai fitur baru size M/L |
+| `/db-migrate` | Ada perubahan schema Prisma |
+| `/deploy` | Push ke production |
+| `/health-check` | Ada masalah atau monitoring rutin |
+| `/git-commit` | Commit dengan format benar |
+| `/dev-reset` | Environment dev bermasalah |
+
+## 🔌 MCP Servers
+
+- **Context7** — docs real-time Next.js 16, Prisma 7, Better Auth, BullMQ → `use context7`
+- **GitHub** — issues, PR, commits dari IDE
+- **PostgreSQL** — schema dan query DB development (jangan production!)
+- **Playwright** — E2E testing browser otomatis
+- **Sentry** — production errors langsung ke context
+- **Docker** — container logs dan status
+
+Config lengkap di `.agent/mcp_config.json`
+
+---
+
+## 🧠 Skills — Daftar Lengkap
+
+### Planning Skills (jalankan sebelum coding project baru)
+| Skill | Trigger |
+|-------|---------|
+| `vibe-research` | "riset dulu", "validasi ide", "analisa kompetitor" |
+| `vibe-prd` | "buat PRD", "definisikan fitur", "scope MVP" |
+| `vibe-techdesign` | "pilih stack", "desain arsitektur", "buat ERD" |
+| `vibe-buildplan` | "buat sprint plan", "breakdown task", "berapa sprint" |
+
+### Build Skills (dipakai saat coding)
+| Skill | Trigger |
+|-------|---------|
+| `prisma-7-patterns` | Coding DB, schema, migrate |
+| `xendit-integration` | Payment, webhook, split |
+| `nextjs-api-route` | Buat `route.ts`, Server Action |
+| `better-auth-patterns` | Auth, login, session |
+| `bullmq-worker` | Background job, queue |
+| `uu-pdp-feature-check` | Fitur yang sentuh data pribadi |
+| `feature-spec-writer` | Plan fitur baru, size M/L |
+| `neo-storage` | Upload file, presigned URL |

package/templates/docs/00A-PROJECT-CHARTER.md

@@ -0,0 +1,33 @@
+# Project Charter
+> Document Status: Draft / Reviewed / Approved
+> Date: [YYYY-MM-DD]
+> Project Sponsor: [Sponsor Name]
+> Project Manager: [PM Name]
+
+## 1. Tujuan Proyek (Project Purpose/Justification)
+Menjelaskan mengapa proyek ini dilakukan. Masalah bisnis apa yang sedang diselesaikan atau peluang apa yang ingin dimanfaatkan?
+
+## 2. Sasaran Proyek & Kriteria Sukses (Objectives & Success Criteria)
+Sasaran proyek (bersifat *measurable* dan spesifik).
+- **Scope (Ruang Lingkup):** [contoh: Meluncurkan aplikasi Android dan Web minimal]
+- **Time (Waktu):** [contoh: MVP rampung dalam 2 bulan]
+- **Cost (Biaya):** [contoh: Anggaran cloud dan lisensi di bawah $500/bulan]
+- **Kualitas:** [contoh: Pengadopsian awal 1000 pengguna]
+
+## 3. Persyaratan Tingkat Tinggi (High-Level Requirements)
+Fitur atau kapabilitas utama sistem secara makro (dari sisi non-teknis). 
+
+## 4. Risiko Tingkat Tinggi (High-Level Risks)
+Daftar risiko utama yang bisa menggagalkan proyek beserta *mitigation plan* ringkas.
+
+## 5. Ringkasan Milestone (Summary Milestone Schedule)
+- Phase 1: Requirement Gathering (Minggu 1-2)
+- Phase 2: UI/UX & Architecture (Minggu 3-4)
+- Phase 3: MVP Development (Minggu 5-8)
+- Phase 4: UAT & Launch (Minggu 9)
+
+## 6. Daftar Pemangku Kepentingan (Stakeholder List)
+| Nama / Peran | Jabatan / Pengaruh | Kontak / Catatan |
+|-------------|---------------------|------------------|
+| [Nama] | Sponsor/CEO | Pengambil keputusan akhir |
+| [Nama] | Pengguna Akhir | Target tester MVP |

package/templates/docs/00B-BRD.md

@@ -0,0 +1,25 @@
+# Business Requirements Document (BRD)
+> Project: [Nama Proyek]
+> Date: [YYYY-MM-DD]
+
+## 1. Executive Summary
+Rangkuman singkat mengenai inisiatif bisnis ini—siapa yang membutuhkan dan nilai apa yang akan didapatkan perusahaan jika ini berhasil diimplementasikan.
+
+## 2. Business Objectives
+Apa gol strategis inisiatif ini? (Contoh: Mengurangi beban CS hingga 40%, atau menigkatkan retensi pengguna baru sebesar 15%).
+
+## 3. Business Scope (In-Scope & Out-of-Scope)
+- **In-Scope:** Proses, operasional, atau departemen yang tercakup oleh produk.
+- **Out-of-Scope:** Proses yang secara eksplisit tidak akan dilayani pada iterasi rilis ini.
+
+## 4. Business Process Model (As-Is / To-Be)
+- **As-Is Process:** Bagaimana proses berjalan saat ini tanpa produk ini.
+- **To-Be Process:** Bagaimana produk baru ini akan merampingkan/memperbarui proses lama. (Bisa digambarkan dengan *Flowchart* tekstual).
+
+## 5. Business Use Cases
+Kasus penggunaan yang diuraikan dari lensa tujuan bisnis.
+- **BUC-01:** Customer bisa memproses komplain pengembalian dana mandiri. (Gol: Mengurangi interaksi CS manual).
+- **BUC-02:** Sistem mendeteksi anomali fraud transaksi tinggi. (Gol: Preventif kerugian asuransi).
+
+## 6. Asumsi Bisnis & Constraints (Hambatan)
+Asumsi-asumsi (contoh: user diasumsikan memiliki koneksi internet) dan constraints (contoh: integrasi bergantung pada kesiapan API bank).

package/templates/docs/01-PRD.md

@@ -0,0 +1,122 @@
+# 01 — Product Requirements Document (PRD)
+> Isi dokumen ini sebelum mulai coding sprint pertama.
+> AI membaca ini sebagai konteks utama untuk memahami produk yang dibangun.
+
+---
+
+## 1. Ringkasan Produk
+
+| Field | Isi |
+|-------|-----|
+| **Nama Produk** | [nama aplikasi] |
+| **Tipe** | [Web App / Mobile App / Marketplace] |
+| **Versi** | v0.1 — MVP |
+| **Tanggal** | [tanggal] |
+| **Owner** | [nama PIC] |
+
+### Elevator Pitch
+> Aplikasi ini membantu **[siapa]** untuk **[melakukan apa]** sehingga **[manfaat utama]**.
+
+---
+
+## 2. Masalah & Target Pengguna
+
+### Problem Statement
+[Jelaskan masalah nyata yang ada. Apa pain point pengguna saat ini?]
+
+### Target Pengguna
+| Segmen | Deskripsi | Pain Point Utama |
+|--------|-----------|--------------------|
+| User Utama | [contoh: pemilik toko online] | [contoh: susah kelola pesanan] |
+| User Sekunder | [contoh: pelanggan toko] | [contoh: checkout ribet] |
+| Admin | [contoh: operator platform] | [contoh: rekonsiliasi manual] |
+
+---
+
+## 3. Fitur MVP
+
+> **Prinsip:** Hanya fitur yang WAJIB untuk validasi bisnis. Sisanya masuk backlog.
+
+### ✅ In Scope
+| ID | Fitur | Deskripsi | Prioritas |
+|----|-------|-----------|-----------| 
+| F01 | Autentikasi | Login email, Google OAuth, session 7 hari | P0 |
+| F02 | [nama fitur] | [deskripsi singkat] | P0 |
+| F03 | [nama fitur] | [deskripsi singkat] | P1 |
+| F04 | Pembayaran | Xendit payment link, webhook, split payment | P0 |
+| F05 | Notifikasi | FCM push notif, email via Resend | P1 |
+
+### ❌ Out of Scope MVP
+- [fitur yang sengaja ditunda]
+- [fitur nice-to-have]
+
+---
+
+## 4. User Stories
+
+> Format: **Sebagai [siapa], saya ingin [aksi], agar [tujuan].**
+
+### Autentikasi
+- [ ] **REQ-001** Sebagai pengguna baru, saya ingin mendaftar dengan email/Google, agar bisa akses aplikasi
+- [ ] **REQ-002** Sebagai pengguna, saya ingin login dan sesi tersimpan 7 hari, agar tidak perlu login ulang
+- [ ] **REQ-003** Sebagai pengguna, saya ingin reset password via email, agar bisa akses akun jika lupa
+
+### [Modul Utama — ganti sesuai aplikasi]
+- [ ] **REQ-010** Sebagai [role], saya ingin [aksi], agar [tujuan]
+- [ ] **REQ-011** Sebagai [role], saya ingin [aksi], agar [tujuan]
+
+### Pembayaran (Xendit)
+- [ ] **REQ-020** Sebagai pembeli, saya ingin membayar via VA/QRIS/e-wallet
+- [ ] **REQ-021** Sebagai penjual, saya ingin dana langsung masuk rekening saya (split)
+- [ ] **REQ-022** Sebagai admin, saya ingin melihat status semua transaksi
+
+### Notifikasi
+- [ ] **REQ-030** Sebagai pengguna, saya ingin dapat push notif saat ada update penting
+- [ ] **REQ-031** Sebagai pengguna, saya ingin dapat email konfirmasi pembayaran
+
+### UU PDP — Hak Pengguna (Wajib sesuai UU PDP No. 27/2022)
+- [ ] **REQ-040** Sebagai pengguna, saya ingin dapat menghapus akun + semua data saya
+- [ ] **REQ-041** Sebagai pengguna, saya ingin dapat mengunduh semua data pribadi saya
+- [ ] **REQ-042** Sebagai pengguna, saya ingin dapat mencabut consent marketing kapan saja
+
+---
+
+## 5. Non-Functional Requirements
+
+| Kategori | Requirement | Target |
+|----------|-------------|--------|
+| Performance | Load halaman utama | < 2 detik |
+| Availability | Uptime | 99.9% |
+| Security | Auth | Session DB (Better Auth 1.5) |
+| Security | Payment | Xendit callback token verified |
+| Security | Data sensitif | Enkripsi at-rest (pgcrypto) |
+| Scalability | Concurrent users (MVP) | 100 users |
+| Mobile | Platform | Android + iOS (Flutter 3.41.2) |
+| Storage | File upload max | 5 MB |
+| Regulasi | Compliance | UU PDP No. 27/2022 |
+
+---
+
+## 6. Success Metrics
+
+| Metric | Target MVP (Bulan 1) | Cara Ukur |
+|--------|---------------------|-----------|
+| Registrasi user | [target] | DB count |
+| Transaksi berhasil | [target] | Xendit dashboard |
+| Uptime | 99.9% | Uptime Kuma |
+
+---
+
+## 7. Constraints & Asumsi
+
+### Constraints
+- Tim: 2–3 orang
+- Timeline MVP: [target tanggal]
+- Budget infra: [estimasi/bulan]
+- Regulasi: UU PDP No. 27/2022 (berlaku penuh Oktober 2024)
+
+### Asumsi
+- User memiliki smartphone Android/iOS
+- Merchant sudah terdaftar sebagai sub-merchant di Xendit
+- Semua user WNI — tidak perlu multi-currency untuk MVP
+- Primary database di Indonesia (Biznet Gio) untuk comply data residency

package/templates/docs/01B-SRS-LENGKAP.md

@@ -0,0 +1,60 @@
+# Software Requirements Specification (SRS)
+> Sistem: [Nama Proyek/Sistem]
+> Versi: [1.0]
+> Tanggal: [YYYY-MM-DD]
+
+## 1. Pendahuluan
+### 1.1 Tujuan
+Dokumen ini mendefinisikan persyaratan fungsional dan non-fungsional, serta arsitektur dari sistem [Nama Proyek]. Tujuannya adalah memastikan pemahaman yang sama antara pemangku kepentingan dan tim pengembang (termasuk AI agent) mengenai target spesifik dari pengembangan peranti lunak.
+
+### 1.2 Ruang Lingkup (Scope)
+Penjelasan ringkas mengenai batasan sistem. Apa yang akan dikembangkan dalam MVP dan apa yang termasuk di luar fase (Out of Scope).
+
+### 1.3 Referensi
+- `docs/01-PRD.md` (Product Requirements Document terkait MVP)
+- `docs/tech-design.md` (Spesifikasi Teknis)
+
+---
+
+## 2. Deskripsi Keseluruhan
+### 2.1 Konteks Sistem
+Diagram tingkat tinggi atau deskripsi interaksi sistem dengan entitas eksternal (sistem pihak ketiga, pengguna akhir, layanan integrasi seperti Payment Gateway Xendit).
+
+### 2.2 Karakteristik Pengguna
+Identifikasi setiap aktor. (Contoh: Admin, End-User, Guest).
+
+---
+
+## 3. Spesifikasi Persyaratan Fungsi (Functional Requirements)
+Spesifikasikan dengan format *Use Case* atau cerita pengguna (User Stories) dengan rincian yang lebih dalam dibandingkan MVP PRD.
+
+### 3.1 Layanan Otentikasi
+1. Sistem harus mengijinkan user masuk menggunakan OAuth Google (Better Auth).
+2. Sistem wajib mengelola sesi kadaluwarsa pengguna secara otomatis.
+
+### 3.2 Modul Utama [Nama Modul]
+_Rincian setiap interaksi yang terjadi pada sistem..._
+
+---
+
+## 4. Persyaratan Non-Fungsional (Non-Functional Requirements / NFR)
+### 4.1 Keamanan (Security)
+- Sistem harus mengamankan data sensitif pengguna (seperti NIK) menggunakan enkripsi pgcrypto pada database PostgreSQL.
+- Transmisi data wajib dibalut di bawah HTTPS.
+- Proteksi terhadap *SQL Injection* dan *XSS* wajib ditegakkan (Zod Validations & Parameterized Queries).
+
+### 4.2 Kinerja (Performance)
+1. Kecepatan *load* halaman klien (LCP - Largest Contentful Paint) harus kurang dari 2.5 detik.
+2. *Webhook* transaksi harus mampu memproses antrean `BullMQ` dengan konkurensi minimal 10 task tanpa membebani thread antarmuka.
+
+### 4.3 Privasi Data (UU PDP Compliance)
+Hak pengguna untuk mengakses, mengunduh (*data portability*), dan menghapus data personal (Right to Erasure) wajib tersedia secara mandiri di halaman pengaturan akun.
+
+---
+
+## 5. Pemodelan Data & Lingkungan
+### 5.1 Spesifikasi Skema Database
+Diagram ERD secara tekstual atau penjelasan tabel utama (misal: relasi `Users` ke `Transactions` dalam rancangan Prisma 7).
+
+### 5.2 Strategi Backup & Pemulihan
+Rincian metode *snapshot* di lingkungan produksi atau penyimpanan file pengguna yang direkam menuju NEO Object Storage Biznet.