jflow

Work-model buat ngirim software pakai tim AI agent — bukan starter kit kode.

Kebanyakan "template AI agent" ngasih lo prompt. Ini ngasih lo model operasi: siapa ngerjain apa, siapa nge-review siapa, apa yang nge-block merge, dan — yang paling penting — gimana sistemnya jadi makin susah rusak seiring waktu.

---

Satu ide yang jadi dasarnya

Kebanyakan setup agent gagal dengan cara yang sama: doc-nya bilang A, config-nya ngelakuin B.

Lo tulis "QA agent itu read-only" di file markdown. Gak ada yang nge-enforce. Enam bulan kemudian lo nemu semua agent ternyata jalan full-tools di model paling mahal — dan gak ada yang sadar.

Itu beneran kejadian di sini. Dan itu alasan repo ini bentuknya kayak gini:

Aturan yang gak di-enforce sama primitive itu bukan aturan. Itu harapan.

Makanya tiap klaim di docs/AGENT_WORKFLOW.md itu wajib salah satu dari dua: (a) nunjuk ke config yang nge-enforce dia, atau (b) ngaku terang-terangan kalau dia cuma di-enforce disiplin, bukan mesin. Gak ada klaim yang boleh ngumpet di tengah-tengah.

---

Isinya apa

1. Sebelas peran — model di-PIN, tools di-scope

Bukan "spawn agent general-purpose terus berdoa". Tiap peran itu definisi nyata di .claude/agents/:

Peran	Tugas	Boleh ngoding?
Orchestrator	Plan · review · gate · koordinasi. Pegang docs + config proses.	❌ gak pernah
Architect	Desain subsystem, jaga docs teknis	docs doang
Coder	Implement 1 story end-to-end. Plan dulu, baru eksekusi.	✅
Implementor	Fix non-story: CI, Docker, config, hotfix	✅
QA	Verifikasi fungsional adversarial — nyoba MECAHIN, bukan konfirmasi	❌ read-only
UAT	Jadi persona user. Jawab: "user dapet value yang dijanjiin?"	❌ read-only
Evaluator	Review kualitas/security/guardrail + trajectory audit	❌ read-only
Product Research · Web Designer · Content Writer · Legal	Sesuai kebutuhan	scoped

"Read-only" di sini bukan janji di prosa — itu tools: di file definisi agent-nya.

Pemisahan QA vs UAT itu disengaja. QA buktiin fiturnya jalan. UAT buktiin user dapet yang dijanjiin. Fitur bisa lolos QA tapi gagal UAT — jalan mulus, tapi gak ngasih value apa-apa. Kebanyakan setup cuma punya yang pertama.

2. Guard hook yang nge-block hal-hal yang gak bisa dijaga doc

.claude/hooks/guard.js nolak, di lapisan tool-call:

• stage/commit secret (.env, *.pem, credentials*)
• bulk-stage (git add -A / git add .) — commit file spesifik
• ngedit docs/*.html yang generated pakai tangan (edit .md-nya, terus regen)
• commit yang nambahin console.log / debugger ke file produksi

3. Loop story dengan gate 6 checklist

coder PLAN → orch REVIEW → coder EXECUTE → QA ∥ UAT ∥ Evaluator → orch GATE → docs + LEARN

Story belum DONE sampai enam-enamnya lolos: kode · QA · eval · regression · docs sinkron · pelajaran ke-capture.

Plus: cap fixer (maks 2 putaran buat issue yang sama), terus aturan keras — HARAM fix ke-3 berbasis hipotesis. Lo wajib ambil data mentah dulu. Nebak itu ngabisin siklus; probe yang nyelesein.

4. Learning loop (§2d) — bagian yang jarang ada di template lain

Model-nya gak belajar. SISTEM-nya yang belajar.

Tiap kegagalan wajib ninggalin bekas permanen di artefak, sampai dia jadi gak mungkin kambuh secara struktural:

Kegagalan	Artefak yang WAJIB dibikin
Bug nyampe user	→ golden case baru (EVAL) atau skenario test (TEST_PLAN)
Agent ngulang salah yang sama ≥2×	→ aturan keras di AGENTS.md + 1 baris di prompt agent-nya
Guardrail dilanggar	→ check baru di regression gate
Doc drift	→ entry di concept index
Dependency gak ke-front-load	→ update checklist plan-gate

Dicatat di docs/FAILURE_LOG.md, dibaca tiap akhir fase.

Threshold-nya sengaja ketat — cuma escape, rework, dan recurrence yang di-log. QA fail di percobaan pertama itu kerja normal, bukan pelajaran. Log semuanya → jadi noise → lo berhenti bacanya → loop-nya mati. Target realistis: ~1-3 entry per minggu, bukan 20.

Ini bukan RL atau fine-tuning. Ini ratchet. Dia compounding, dan bisa diaudit.

5. Docs yang gak bisa drift diam-diam

• .md = satu-satunya sumber. .html di-generate (node scripts/build-docs.mjs) — ngedit dia pakai tangan di-block.
• BUSINESS_GOALS.md = akar: kalau antar-dokumen konflik soal arah, dia yang menang.
• DOC_MAP.md punya concept index — ubah satu konsep, langsung keliatan semua section yang harus ikut berubah.
• Sinkronisasi docs itu bagian dari GATE, bukan nice-to-have. Story dengan docs basi = belum done.

---

Struktur repo

.claude/            enforcement pack — ini yang bikin doc-nya jadi NYATA
  agents/           11 definisi peran (model di-PIN, tools di-scope)
  hooks/guard.js    PreToolUse guard
  settings.json     wiring hook
docs/               17 spec (.md = sumber, .html = generated)
  AGENT_WORKFLOW.md ← model operasinya. MULAI DARI SINI.
  FAILURE_LOG.md    ← learning ratchet
scripts/            build-docs.mjs (docs → html) · notify-discord.mjs
AGENTS.md           orientasi + aturan keras (agent baca ini duluan)
CLAUDE.md           instruksi buat orchestrator
START_HERE.md       runbook: cara fork ini jadi proyek baru

Cara mulai

1. Baca docs/AGENT_WORKFLOW.md. Itu produk aslinya. Sisanya cuma pendukung.
2. Ikutin START_HERE.md buat fork jadi proyek baru — dia mulai dari interview, dan itu disengaja. Ngisi template sebelum lo tau jawabannya = cara paling cepet dapet spec yang cantik tapi gak kepake.
3. Setup .claude/ terus VERIFIKASI — jangan percaya config. Spawn agent murah, pastiin dia beneran lapor pakai model murah. Coba bulk-stage, pastiin beneran ke-DENY. Kalau salah satu gak kejadian, config-nya belum ke-load — dan lo balik lagi ke "harapan".

Batasan (jujur)

• Dibikin buat Claude Code. Pack .claude/ itu Claude-specific. Model operasinya enggak — tapi lapisan enforcement-nya lo yang harus port sendiri.
• Learning loop di-enforce DISIPLIN, bukan mesin — dan doc-nya ngaku gitu. Apakah dia bertahan pas minggu lagi sibuk? Itu tergantung lo. (Ada catatan di §2d.5 gimana cara ngerasin dia pakai hook kalau lo mau.)
• Ini opinionated. Coder plan-first, QA adversarial, UAT persona terpisah, gate 6 item. Kalau lo mau agent yang gaspol tanpa review, ini bakal kerasa friction. Friction itu emang intinya.

Lisensi

MIT — lihat LICENSE.