GMW/AGENTS.md

GMW — Agent Development Guide

Rule #1: No code without a spec. Setiap perubahan signifikan dimulai dari spec di docs/specs/. Baca spec → verifikasi facts → implement → verify → commit. Gunakan todo.md (TODO list terdokumentasi) untuk melacak progress.

Project overview

GMW (Go Mod Watch) adalah Discord bot + dashboard untuk AI-powered moderation. Monorepo berisi 3 service utama:

Service	Path	Port	Tech
discord-gateway	services/discord-gateway/	4016 (metrics)	discord.js-selfbot-v13, Piscina, Drizzle ORM, pino
backend	services/backend/	4001	Express, oRPC, Drizzle ORM, Redis pub/sub, Vitest
frontend	services/frontend/	4017 (standalone)	Next.js 16 App Router, React 19, Tailwind v4, SWR

Data flow

Discord → discord-gateway → Redis pub/sub → backend (:4001) ←→ frontend Next.js SSR
                                                   ↑ REST /api/*
                                                   └ WS /ws

• Gateway = event-driven (no HTTP, except Prometheus :4016/metrics)
• Backend = HTTP + WebSocket server, serves the frontend
• Frontend = SSR (RSC) + client hydration, proxied by nginx :4009

Konvensi dokumentasi: docs/

Semua dokumen kerja ada di docs/, bukan di .hermes/:

docs/
├── README.md                  # Panduan workflow (spec-driven + todo)
├── spec-template.md           # Template spec standar
├── todo-template.md           # Template todo list
└── specs/                     # Semua spec & implementation plan
    ├── YYYY-MM-DD_<slug>-spec.md    # Spec (apa & mengapa)
    └── YYYY-MM-DD_<slug>.md         # Plan/fix (spec + plan dalam satu file)

Service-specific docs: services/<service>/docs/specs/.

Workflow: Spec-Driven Development

Checklist wajib untuk setiap perubahan signifikan

1. Tulis spec → docs/specs/YYYY-MM-DD_<slug>-spec.md
2. Tulis todo.md → daftar task konkret yang bisa diceklis
3. Verifikasi facts → baca kode aktual, konfirmasi referensi file:line
4. Keputusan desain → pilih approach, dokumentasikan alternatif yang ditolak
5. Implementasi → ikuti spec + todo step-by-step
6. Verifikasi → jalankan semua verification steps dari spec
7. Commit → reference spec di commit message

Todo list (todo.md)

Setiap tugas berjalan WAJIB punya todo.md. Format:

# Todo — <judul tugas>

## Task
- [ ] Tulis spec
- [ ] Verifikasi facts (baca kode: file:line)
- [ ] Implementasi tahap 1: ...
- [ ] Implementasi tahap 2: ...
- [ ] Verifikasi: pnpm typecheck / lint / build / test
- [ ] Commit + push

Aturan:

• Task harus konkret & verifiable — bukan "fix bug", tapi "ubah X di file Y".
• Ceklis [x] saat selesai, jangan menunggu batch di akhir.
• Gunakan docs/todo-template.md sebagai template.
• Simpan todo.md di docs/ untuk tugas lintas-service, atau di services/<service>/docs/ untuk tugas satu service.

Spec template

Salin docs/spec-template.md untuk setiap spec baru. Sections:

1. Problem — apa yang rusak/missing, dengan evidence
2. Root cause — analisis teknis (bukan symptom)
3. Behavior target — perilaku setelah fix, daftar verifiable
4. Verified facts — fakta dari pembacaan kode, citation ke file:line
5. Keputusan desain — pilihan + rationale + alternatif ditolak
6. Perubahan file — semua file yang disentuh, per service
7. Schema/type changes — perubahan tipe/DB
8. Verification — command executable + expected outcome

Kapan perlu spec + todo.md

Perlu: fitur baru, bug fix non-trivial, refactor behavior-changing, perubahan DB schema, perubahan API contract, perubahan arsitektur.

Tidak perlu: typo fix, dep bump, format/lint auto-fix, test-only, README update.

Baca selengkapnya di docs/README.md.

Coding conventions

General

• TypeScript strict mode — semua service
• Biome — formatting + linting (pnpm format, pnpm lint)
• Bun — package manager (bun install, bun run)
• Bisa bilingual — code comments & specs boleh Indonesia/English

Per-service conventions

discord-gateway

• Event-driven — no HTTP server (except metrics). Listeners → Redis pub/sub.
• Module pattern: src/modules/<module>/ — each module encapsulates own logic.
• Piscina pools: text pool (4 threads) + media pool (2 threads), each with own pg Pool.
• Logger: createChildLogger('module-name') — never raw console.
• Config: Zod-validated env in shared/config/index.ts — single source of truth.
• DB: Drizzle ORM. Migrations in drizzle/migrations/.
• Invariant: LLM is the only judge. Never reintroduce regex content classification.
• Invariant: Discord tokens sanitized before reaching LLM.
• Lihat services/discord-gateway/AGENTS.md untuk detail.

backend

• Modular MVC: modules/<module>/ — schema → repository → service → controller → routes.
• No cross-module repo imports — each module owns its data.
• Data flows up only: Repository → Service → Controller.
• Error hierarchy: AppError subclasses with code + statusCode.
• Config: Zod-validated env in shared/config/index.ts.
• API: oRPC for type-safe procedures + standard Express routes.
• Lihat services/backend/AGENTS.md untuk detail.

frontend

• SSR-first: page.tsx (server component) → fetch via src/lib/api/server.ts → pass to view.tsx (client).
• No auth: all endpoints public.
• Never hardcode host: same-origin or GMW_BACKEND_URL only.
• WebSocket: src/lib/ws/ — auto-reconnecting, typed events.
• Local dev: NEXT_PUBLIC_API_URL, NEXT_PUBLIC_WS_URL, GMW_BACKEND_URL.
• Lihat services/frontend/AGENTS.md untuk detail Next.js rules.

Build & Verify

# Per service (run from service root)
pnpm typecheck          # TypeScript strict
pnpm lint               # Biome check
pnpm build              # Compile
pnpm test               # Vitest (gateway & backend only)
pnpm format             # Biome auto-format

Commit conventions

<type>(<scope>): <subject>

<optional body>

Ref: docs/specs/<spec-file>.md

Types: feat, fix, refactor, test, docs, chore, build, ci

Deployment

CI/CD: GitHub Actions → build → deploy to production server via Nix flakes.

• Gateway: nixos-rebuild or systemctl restart gmw-discord-gateway
• Backend: nixos-rebuild or systemctl restart gmw-backend
• Frontend: Next.js standalone, proxied by nginx :4009

Remember

• Spec dulu, code belakangan.
• Todo list (todo.md) wajib untuk tugas yang berjalan — ceklis tiap selesai.
• Verified facts harus dari pembacaan kode aktual, bukan asumsi.
• Setiap change harus verifiable — tulis command di spec.
• One spec = one focused change. Don't mix unrelated features.