feat(docs): Add comprehensive agent guides and templates for spec-driven development
This commit is contained in:
asepharyana
+131
@@ -0,0 +1,131 @@
|
||||
# docs/ — Spec-Driven Development Hub
|
||||
|
||||
Direktori ini adalah pusat dari workflow **spec-driven development** di GMW.
|
||||
Semua perubahan signifikan dimulai dari satu spec, **sebelum kode ditulis**,
|
||||
dan setiap tugas yang berjalan dilacak lewat `todo.md`.
|
||||
|
||||
## Struktur
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md # Dokumen ini
|
||||
├── spec-template.md # Template standar untuk semua spec
|
||||
├── todo-template.md # Template todo list
|
||||
└── specs/ # Semua spec dan implementation plan
|
||||
├── YYYY-MM-DD_<slug>-spec.md # Spec (apa & mengapa)
|
||||
└── YYYY-MM-DD_<slug>.md # Plan/fix (bisa langsung spec+plan)
|
||||
```
|
||||
|
||||
### Naming convention
|
||||
|
||||
```
|
||||
YYYY-MM-DD_<slug>-spec.md # Spec baru untuk fitur/fix
|
||||
YYYY-MM-DD_<slug>.md # Plan yang sudah include spec di dalamnya
|
||||
```
|
||||
|
||||
Contoh:
|
||||
- `2026-08-30_recordings-v2-features-spec.md` — spec untuk Recordings v2
|
||||
- `2026-08-24-attachment-delay-fix.md` — spec + plan untuk attachment delay fix
|
||||
|
||||
### Service-specific docs
|
||||
|
||||
```
|
||||
services/<service>/docs/specs/ # Spec yang spesifik untuk 1 service
|
||||
```
|
||||
|
||||
## Workflow: Spec-Driven Development
|
||||
|
||||
### Prinsip utama
|
||||
|
||||
> **No code without a spec.** Semua perubahan signifikan harus punya spec
|
||||
> terlebih dahulu. Spec adalah kontrak: apa yang akan dibangun, mengapa,
|
||||
> dan bagaimana memverifikasinya.
|
||||
|
||||
### Todo list (`todo.md`) — WAJIB
|
||||
|
||||
Setiap tugas berjalan (implementasi fitur/fix) harus punya `todo.md`:
|
||||
|
||||
```markdown
|
||||
# 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 `todo.md`:
|
||||
- Task **konkret & verifiable** — "ubah X di file Y", bukan "fix bug".
|
||||
- Satu task `[in_progress]` pada satu waktu; ceklis `[x]` segera setelah selesai.
|
||||
- Gunakan `docs/todo-template.md` sebagai template.
|
||||
- Simpan `todo.md` di `docs/` (tugas lintas-service) atau di
|
||||
`services/<service>/docs/` (tugas satu service).
|
||||
|
||||
### Kapan perlu spec + todo
|
||||
|
||||
| Perlu spec + todo | Tidak perlu |
|
||||
|---|---|
|
||||
| Fitur baru | Typo fix |
|
||||
| Bug fix non-trivial | Dependency bump (dependabot) |
|
||||
| Refactor yang mengubah behavior | Format/lint auto-fix |
|
||||
| Perubahan DB schema | Test-only change |
|
||||
| Perubahan API contract | README/doc update |
|
||||
| Perubahan arsitektur | Variable rename |
|
||||
|
||||
### Workflow step-by-step
|
||||
|
||||
1. **Tulis spec** — Salin `docs/spec-template.md`, isi semua section yang relevan.
|
||||
- **Verified facts**: baca kode yang terpengaruh, catat temuan dengan file:line.
|
||||
- **Root cause**: analisis sebab (jangan hanya describe symptom).
|
||||
- **Decisions**: pilih pendekatan, jelaskan alternatif yang ditolak.
|
||||
- **Verification**: command executable, bukan "should work".
|
||||
- Simpan sebagai `docs/specs/YYYY-MM-DD_<slug>-spec.md`.
|
||||
|
||||
2. **Tulis `todo.md`** — Pecah spec jadi task konkret yang bisa diceklis
|
||||
(gunakan `docs/todo-template.md`), dengan urutan implementasi yang logis.
|
||||
|
||||
3. **Review spec** — Baca ulang spec sendiri. Cek:
|
||||
- Apakah verified facts benar-benar verified (bukan asumsi)?
|
||||
- Apakah file changes lengkap (tidak ada yang terlewat)?
|
||||
- Apakah verification steps executable?
|
||||
- Jika spec untuk user request: pastikan user setuju dengan approach.
|
||||
|
||||
4. **Implement** — Ikuti spec + todo step-by-step. Ceklis `[x]` setiap task
|
||||
yang selesai. Jika menemukan sesuatu yang berubah dari asumsi spec,
|
||||
**update spec dulu**, baru implement.
|
||||
|
||||
5. **Verify** — Jalankan semua verification steps di spec. Catat hasilnya.
|
||||
|
||||
6. **Commit** — Reference spec di commit message:
|
||||
```
|
||||
feat(module): deskripsi singkat
|
||||
|
||||
Ref: docs/specs/YYYY-MM-DD_<slug>-spec.md
|
||||
```
|
||||
|
||||
### Tips menulis spec yang baik
|
||||
|
||||
- **Evidence-based**: setiap klaim harus ada sumbernya (file:line, log, error).
|
||||
- **Actionable**: orang lain (atau AI agent) harus bisa implementasi dari spec saja.
|
||||
- **Verifiable**: setiap requirement harus bisa di-test secara eksplisit.
|
||||
- **Scoped**: satu spec = satu perubahan terfokus. Jangan campur 3 fitur dalam 1 spec.
|
||||
- **Bahasa campuran**: narrative boleh Indonesia/English, istilah teknis pakai English.
|
||||
|
||||
### Role of AI agents
|
||||
|
||||
AI coding agents (Shiro Neko / Hermes) **harus**:
|
||||
- Membaca spec sebelum menulis kode
|
||||
- Membuat & meng-update `todo.md` untuk setiap tugas berjalan
|
||||
- Verifikasi fakta dari kode aktual (bukan dari asumsi training data)
|
||||
- Update spec jika temuan baru mengubah approach
|
||||
- Jalankan verification steps setelah implementasi
|
||||
- Reference spec di commit message
|
||||
|
||||
AI agents **tidak boleh**:
|
||||
- Langsung implement tanpa membaca/menulis spec
|
||||
- Mengabaikan verified facts yang bertentangan dengan asumsi
|
||||
- Skip verification steps
|
||||
- Mengerjakan tugas tanpa todo list yang jelas
|
||||
@@ -0,0 +1,80 @@
|
||||
# Spec: <Judul singkat, aktif, deskriptif>
|
||||
|
||||
Status: **DRAFT** | **APPROVED** | **IN PROGRESS** | **DONE**
|
||||
Date: YYYY-MM-DD
|
||||
Author: <nama/agent>
|
||||
Related: <link ke spec/plan terkait jika ada>
|
||||
Todo: <link ke todo.md untuk tugas ini, jika ada>
|
||||
|
||||
## Problem
|
||||
|
||||
<Deskripsi masalah atau keinginan. Apa yang rusak? Apa yang belum ada?
|
||||
Sebutkan siapa yang melaporkan (user/bot/audit) dan konteksnya.
|
||||
Gunakan **evidence**: log, error, metrik, atau observasi langsung.>
|
||||
|
||||
## Root cause
|
||||
|
||||
<Analisis teknis mengapa masalah ini terjadi. Jika bug: trace dari symptom ke cause.
|
||||
Jika fitur baru: jelaskan gap saat ini. Referensikan file + line number yang relevan.>
|
||||
|
||||
## Behavior target
|
||||
|
||||
<Deskripsi eksplisit perilaku yang diharapkan setelah fix/fitur.
|
||||
Buat list bernomor. Setiap item harus bisa di-verify.>
|
||||
|
||||
## Verified facts
|
||||
|
||||
>Fakta-fakta teknis yang **sudah diverifikasi** dari pembacaan kode, log produksi,
|
||||
>atau eksperimen langsung. Setiap fakta harus citation ke file:line.
|
||||
>Jika belum diverifikasi, tulis `UNVERIFIED` dan rencana verifikasi.
|
||||
|
||||
- `path/to/file.ts:42` — <apa yang terjadi di sini>
|
||||
- `path/to/file.ts:88` — <apa yang terjadi di sini>
|
||||
- Kolom DB `table.column` — <tipe, constraint, index>
|
||||
- Config `ENV_VAR` default <value> — <dibaca di mana>
|
||||
|
||||
## Keputusan desain
|
||||
|
||||
<Pilihan desain yang dibuat, beserta rationale (mengapa bukan alternatif lain).
|
||||
Format: nomor, judul singkat, penjelasan.>
|
||||
|
||||
1. **<Judul keputusan>**: <penjelasan + rationale>
|
||||
- Alternatif yang ditolak: <apa + mengapa ditolak>
|
||||
|
||||
## Perubahan file
|
||||
|
||||
>Daftar **semua file** yang perlu diubah/ditambah/dihapus, dikelompokkan per service.
|
||||
>Untuk setiap file: sebutkan **apa yang berubah** (bukan copy-paste kode).
|
||||
|
||||
### Gateway (`services/discord-gateway/`)
|
||||
- `src/modules/<module>/<file>.ts` — <ringkasan perubahan>
|
||||
|
||||
### Backend (`services/backend/`)
|
||||
- `src/modules/<module>/<file>.ts` — <ringkasan perubahan>
|
||||
|
||||
### Frontend (`services/frontend/`)
|
||||
- `src/<path>/<file>.ts|tsx` — <ringkasan perubahan>
|
||||
|
||||
### Database / Config
|
||||
- <migration file atau config change jika ada>
|
||||
|
||||
## Schema/type changes
|
||||
|
||||
<Perubahan tipe, interface, atau DB schema. Jika tidak ada, tulis "TIDAK ada perubahan.">
|
||||
|
||||
## Verification
|
||||
|
||||
>**Harus spesifik dan executable.** Jangan tulis "works correctly".
|
||||
>Tulis command yang bisa dijalankan dan expected outcome.
|
||||
|
||||
- **Typecheck**: `<service> pnpm typecheck` — clean
|
||||
- **Lint**: `<service> pnpm lint` — no errors
|
||||
- **Build**: `<service> pnpm build` — compiles
|
||||
- **Test**: `<service> pnpm test` — all pass (+ test baru jika ada)
|
||||
- **Smoke test**: <langkah manual untuk verifikasi visual/behavioral>
|
||||
- **DB**: <query untuk cek data jika applicable>
|
||||
- **Deploy**: CI green → deploy → cek <specific observable>
|
||||
|
||||
## Notes (opsional)
|
||||
|
||||
<Catatan tambahan: risiko, fallback, future work, atau hal yang sengaja di-scope-out.>
|
||||
@@ -3,8 +3,8 @@
|
||||
Status: **P1–P3 DONE + 4th CRITICAL FIX deployed (f1a7b0c2); DAVE Ready + MLS handshake CONFIRMED live; P4 = waiting on active streamer to confirm video-burst→mp4**
|
||||
Date: 2026-08-31
|
||||
Author: Hermes
|
||||
Related: `.hermes/plans/2026-08-31_video-receive-eager-selfbot-connection-spec.md` (superseded by this)
|
||||
`.hermes/plans/2026-08-31_video-receive-phaseC-spec.md` (Phase C build, selfbot path — dead)
|
||||
Related: `docs/specs/2026-08-31_video-receive-eager-selfbot-connection-spec.md` (superseded by this)
|
||||
`docs/specs/2026-08-31_video-receive-phaseC-spec.md` (Phase C build, selfbot path — dead)
|
||||
|
||||
## Problem / Ground truth (established from live logs 2026-08-31)
|
||||
GMW must record OTHER members' screen-share + camera video in a voice channel it
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Status: PLANNED
|
||||
Date: 2026-08-31
|
||||
Author: Hermes
|
||||
Related: `.hermes/plans/2026-08-31_video-receive-phaseC-spec.md` (Phase C build, made Option A this fix)
|
||||
Related: `docs/specs/2026-08-31_video-receive-phaseC-spec.md` (Phase C build, made Option A this fix)
|
||||
|
||||
## Symptom (from live logs, 2026-08-31 ~12:34)
|
||||
A user was actively screen-sharing + on camera in the recorded voice channel.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Status: PLANNED (not built)
|
||||
Date: 2026-08-31
|
||||
Author: Hermes
|
||||
Related: `.hermes/plans/2026-08-30_video-record-receive-spec.md` (Phase A/B — raw UDP hook, superseded for receive)
|
||||
Related: `docs/specs/2026-08-30_video-record-receive-spec.md` (Phase A/B — raw UDP hook, superseded for receive)
|
||||
|
||||
## TL;DR — what changed vs Phase A/B
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Status: PLANNED (not yet built)
|
||||
Date: 2026-09-02
|
||||
Author: Hermes
|
||||
Related: `.hermes/plans/2026-08-31_video-receive-phaseC-spec.md` (auto-receive, superseded
|
||||
Related: `docs/specs/2026-08-31_video-receive-phaseC-spec.md` (auto-receive, superseded
|
||||
for selfbot), `gmw-ops/references/selfbot-presence-detection-limits.md`,
|
||||
`gmw-ops/references/discord-voice-fork-video-receive.md`
|
||||
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# Todo — <judul tugas>
|
||||
|
||||
Status: **IN PROGRESS** | **BLOCKED** | **DONE**
|
||||
Spec: <link ke spec: `docs/specs/YYYY-MM-DD_<slug>-spec.md`>
|
||||
Date: YYYY-MM-DD
|
||||
|
||||
## Task
|
||||
|
||||
> Urutan implementasi sesuai spec. Task harus konkret & verifiable
|
||||
> ("ubah X di file Y"), bukan "fix bug". Satu task dikerjakan pada satu
|
||||
> waktu; ceklis `[x]` segera setelah selesai.
|
||||
|
||||
- [ ] Tulis spec
|
||||
- [ ] Verifikasi facts (baca kode: `file:line`)
|
||||
- [ ] Implementasi tahap 1: <apa + file mana>
|
||||
- [ ] Implementasi tahap 2: <apa + file mana>
|
||||
- [ ] Implementasi tahap 3: <apa + file mana>
|
||||
- [ ] Typecheck: `pnpm typecheck` — clean
|
||||
- [ ] Lint: `pnpm lint` — no errors
|
||||
- [ ] Test: `pnpm test` — all pass
|
||||
- [ ] Build: `pnpm build` — compiles
|
||||
- [ ] Daftar ulang hasil verifikasi di spec
|
||||
- [ ] Commit + push (reference spec di commit message)
|
||||
|
||||
## Notes
|
||||
|
||||
<Blocking issue, temuan yang mengubah approach, atau hal yang perlu dicatat.>
|
||||
Reference in New Issue
Block a user