DWP specification

Versi 4.0.0. Status: Stabil. Dokumen ini adalah spesifikasi normatif untuk metodologi Deep Work Plan (DWP). Kata kunci MUST, MUST NOT, SHOULD, SHOULD NOT, dan MAY harus ditafsirkan sebagaimana dijelaskan dalam RFC 2119.

Bersifat menambah pada 2.4.0, tanpa perubahan yang merusak. (1) Bagian Touched Surface — kontrak antara apa yang diubah sebuah tugas dan apa yang harus divalidasi, dengan pemilihan gate berdasarkan kelas risiko (isolated / seam / shared-core / unknown); (2) validasi penuh menjadi persyaratan status akhir yang dijalankan dalam satu-satunya Final Review wajib milik rencana, dengan aturan penggunaan-ulang bukti yang eksplisit; (3) keputusan skills per-tugas berpindah ke dalam tugas pemiliknya, dan Executive Report menjadi opsional, atas permintaan; (4) sebuah alur create yang sadar-mode — mode trust melakukan materialisasi secara langsung sambil tetap menjalankan analisis dan pemeriksaan kualitas; (5) materialisasi rencana Lite-first — create terpandu menghasilkan sebuah rencana Lite yang langsung dapat dieksekusi, alih-alih draf yang tidak dapat dieksekusi, yang dapat dipromosikan menjadi rencana Full kapan saja (lihat Rencana Lite); dan (6) sebuah matriks kompatibilitas yang eksplisit: rencana dan repositori dari versi sebelumnya tetap konforman.

Standar 4.0.0. Lompatan versi menyelaraskan nomor standar dengan lini produk — 2.x bersifat historis dan tidak ada standar 3.x — serta tidak mengubah satu pun persyaratan dari 2.4.0. Rencana dan repositori dari versi lebih awal tetap konforman.

Definisi

Sebuah Deep Work Plan adalah artefak terstruktur berbasis Markdown saja yang menggambarkan tugas teknik yang kompleks yang terurai menjadi unit-unit pekerjaan yang berurutan dan dapat ditinjau, dirancang untuk dibuat, dieksekusi, dan dipelihara oleh AI coding agent yang bekerja secara otonom.

DWP bersifat spec-driven: rencana adalah spesifikasi, dan agent MUST mengeksekusi terhadap acceptance criteria dan validation gate-nya yang eksplisit alih-alih berimprovisasi. Spesifikasi — bukan transkrip obrolan — adalah sumber kebenaran yang tahan lama, sehingga pekerjaan dapat diverifikasi dan dapat dilanjutkan lintas sesi dan agent. Ia juga harness engineering yang dibuat portabel: konteks, control loop, pengaman, dan status yang dapat dilanjutkan yang membuat agent andal dipasang ke dalam repositori itu sendiri sebagai Markdown polos, sehingga agent konforman mana pun MAY mengemudikan repositori tanpa framework khusus alat.

Alur create — satu langkah, sadar-mode

Alur create mengumpulkan tujuan, konteks, batasan, dan kerangka tugas satu kali, melakukan analisis kebutuhan-nya (cakupan, pengurutan dependensi antar tugas, pemilihan validasi dari Touched Surface, tingkatan rigor proporsional), lalu melakukan materialisasi sesuai mode yang dipilih pengembang:

• Mode terpandu (default). Alur langsung melakukan materialisasi sebuah rencana Lite — sebuah proposal kompak yang sudah dapat dieksekusi dengan catatan tugas inline {#task-N}, dapat ditinjau dalam satu kali jalan — dan meminta pengembang untuk mempertahankannya sebagai Lite, mempromosikannya menjadi rencana Full, meminta perubahan, atau berhenti. Tidak ada draf perantara yang tidak dapat dieksekusi yang dihasilkan.
• Mode trust (trust / auto). Alur melakukan materialisasi representasi yang dipilih (Lite, atau Lite yang segera diikuti oleh promosi ke Full) secara langsung, tanpa langkah tinjauan — pengembang telah melepaskannya. Analisis kebutuhan, pengurutan dependensi, dan sebuah pemeriksaan kualitas rencana tetap berjalan: trust melepaskan tinjauannya, bukan analisisnya. Sebuah rencana mode trust dicatat sebagai disetujui di muka untuk eksekusi tanpa pengawasan.

Kedua mode memutuskan format rencana (Lite atau Full) sebagai bagian dari analisis kebutuhan yang sama, tidak pernah sebagai pemikiran belakangan. Lihat Rencana Lite untuk siklus hidup representasi, pembuatan-dan-pemilihan, serta promosi secara lengkap.

Struktur rencana

Sebuah rencana MUST berupa sebuah direktori di bawah .dwp/plans/ bernama PLAN_<slug>/, dalam salah satu dari dua representasi:

• Full. Direktori itu MUST berisi README.md (ikhtisar rencana, tujuan, tabel tugas, dan status), satu berkas per tugas bernama <n>.task_<slug>.md, dan PROGRESS.md (log eksekusi yang berjalan).
• Lite. Catatan tugas yang kompak dan sepenuhnya dapat dieksekusi hidup inline di README.md di balik jangkar {#task-N} yang stabil, alih-alih berkas tugas terpisah — setiap catatan tetap membawa sebuah tujuan, Touched Surface, acceptance criteria, validasi, dan log penyelesaian. PROGRESS.md tetap REQUIRED. Sebuah rencana Lite MAY dipromosikan menjadi Full kapan saja. Lihat Rencana Lite untuk siklus hidup lengkapnya alih-alih menduplikasinya di sini.

Sebuah rencana MAY juga membawa lapisan status yang dapat dibaca mesin: manifest.json (identitas statis, ditulis sekali saat materialisasi) dan state.json (status eksekusi per-tugas yang berjalan). Lapisan status RECOMMENDED untuk rencana baru dan REQUIRED untuk eksekusi tanpa pengawasan dan untuk ruang kerja agent tanpa git. Lihat Status rencana.

Anatomi tugas

Berkas tugas

1. 01 Title
2. 02 Context
3. 03 Read Before Starting
4. 04 Goal
5. 05 Touched Surface
6. 06 Instructions
7. 07 Acceptance Criteria
8. 08 Outputs
9. 09 Validation
10. 10 Execution Checklist + Completion & Log

Setiap berkas tugas MUST berisi sepuluh bagian ini, secara berurutan:

1. Goal — pernyataan satu paragraf tentang apa yang dicapai tugas.
2. Context — latar belakang, tautan, dan mengapa tugas ini ada.
3. Touched Surface — kontrak antara apa yang diubah tugas dan apa yang harus divalidasi.
4. Steps — tindakan konkret yang berurutan untuk dilakukan.
5. Acceptance criteria — daftar periksa kondisi yang mendefinisikan selesai.
6. Validation — perintah atau test yang dijalankan untuk memverifikasi, dipilih dari Touched Surface.
7. Files — path yang diperkirakan akan dibuat atau diubah.
8. Dependencies — tugas lain atau prasyarat eksternal.
9. Risks — apa yang bisa salah, dan mitigasinya.
10. Completion & Log — penanda status ditambah catatan kronologis.

Sebuah tugas MAY juga menyertakan bagian Delta (RECOMMENDED untuk perubahan perilaku brownfield — lihat di bawah) dan bagian Rollback (RECOMMENDED untuk migrasi, perubahan infrastruktur, atau deployment).

Touched Surface

Touched Surface adalah kontrak antara apa yang diubah sebuah tugas dan apa yang harus divalidasi. Ia ada agar validasi dipilih berdasarkan efek, bukan berdasarkan kebiasaan, dan agar pembaca di kemudian hari dapat melihat mengapa sebuah gate dipilih. Sebuah tugas yang mengubah perilaku MUST mencatat:

• Permukaan yang direncanakan — path, modul, paket, atau konfigurasi yang hendak diubah tugas, ditulis sebelum penyuntingan.
• Permukaan aktual — daftar hasil rekonsiliasi setelah penyuntingan, diambil dari diff yang nyata. Agent MUST merekonsiliasi permukaan yang direncanakan dan yang aktual sebelum memilih gate.
• Konsumen yang terdampak — modul, paket, atau layanan yang bergantung pada permukaan aktual, sejauh pemetaan terdokumentasi repositori dapat menetapkannya. Di mana ia tidak dapat, entri itu MUST menyatakannya.
• Kelas risiko — salah satu dari: isolated (terbatas pada satu modul dan test-nya); seam (mengubah sebuah kontrak, persistensi, routing, serialisasi, auth, atau perkabelan framework antar kolaborator); shared/core (diimpor secara luas, atau sebuah perubahan dependensi, migrasi, konfigurasi build/test, skema, atau toolchain); unknown (pemetaannya hilang, usang, atau belum diverifikasi).
• Pemetaan test yang dipakai — pemetaan atau alat terdokumentasi mana yang menghasilkan pemilihan itu.
• Gate yang dipilih dan alasannya — perintah persisnya dan mengapa perintah itu mencakup permukaan aktual.

Berkas konfigurasi, skema, manifes dependensi, template, fixture, migrasi, dan berkas instruksi agent dapat mengubah perilaku dan MUST diklasifikasikan berdasarkan efeknya, tidak pernah berdasarkan ekstensi berkas. Sebuah tugas yang hanya mengubah prosa, komentar, atau artefak riset MAY menyatakan permukaannya tidak berlaku dan tetap menjalankan pemeriksaan non-runtime repositori.

Bagian Delta (perubahan brownfield)

Sebagian besar pekerjaan nyata memodifikasi perilaku yang ada alih-alih menciptakan perilaku baru. Sebuah tugas yang mengubah cara kerja sistem yang ada SHOULD membawa bagian Delta yang menggambarkan perubahan sebagai kontrak sebelum/sesudah yang eksplisit, menggunakan tiga judul daftar:

• ADDED — perilaku yang ada setelah tugas dan tidak ada sebelumnya.
• MODIFIED — perilaku yang ada di keduanya, dinyatakan sebagai was: … → now: ….
• REMOVED — perilaku yang ada sebelumnya dan secara sengaja hilang setelahnya.

Setiap entri MUST berupa perilaku yang dapat diamati — respons endpoint, flag CLI, status UI, nilai default — bukan detail implementasi. Bagian Delta adalah diff peninjau pada tingkat perilaku: acceptance criteria memverifikasi entri ADDED/MODIFIED, dan entri REMOVED adalah izin eksplisit untuk menghapus. Apa pun yang tidak terdaftar sebagai REMOVED MUST tetap berfungsi.

Validation gate — dipilih berdasarkan kelas risiko

Validasi adalah gate yang mengubah klaim penyelesaian menjadi bukti penyelesaian: sebuah tugas MUST NOT ditandai selesai sampai setiap perintah di bagian Validation-nya telah dijalankan dan lulus. Gate sebuah tugas yang mengubah perilaku dipilih dari Touched Surface-nya yang telah direkonsiliasi, berdasarkan kelas risiko:

Sebuah perubahan perilaku MUST menghasilkan pemilihan test yang tidak kosong dan relevan — sebuah selector yang tidak valid atau runner yang memilih nol test bukanlah cakupan. Di mana peta pengujian repositori sudah usang, pemanggilan yang benar diturunkan dan pembaruan pemetaannya dicatat; sebuah perintah kecil yang hilang tidak pernah menuntut jalannya onboarding penuh. Di mana tidak ada pemanggilan bercakupan sempit, suite lengkap yang berlaku yang dipakai — perilaku lama, tidak pernah sebuah kesalahan.

Ketika sebuah tugas menambahkan fungsionalitas inti baru atau secara material mengubah perilaku yang ada, acceptance criteria-nya MUST menyertakan cakupan test otomatis untuk perilaku yang baru atau berubah, dan validasinya menjalankan test repositori bersama dengan pemeriksaan lint, type-check, dan format — bukan build saja. Test yang ada MUST tetap hijau.

Validasi status akhir

Gate per-tugas memvalidasi apa yang disentuh setiap tugas; ia tidak menggantikan validasi rencana secara keseluruhan. Sebelum sebuah rencana selesai, validasi lengkap yang berlaku milik repositori MUST dijalankan dan lulus pada status relevan terakhir, setelah perubahan substantif terakhir — di dalam Final Review. Jalannya validasi yang lebih luas lebih awal terjadi pada batas integrasi atau setelah perubahan shared/core, bukan menurut jadwal berdasarkan jumlah tugas. Sebuah hasil yang lulus MAY dipakai ulang hanya dengan bukti bahwa masukan yang relevan setara; jika tidak, ia dijalankan ulang. Setiap kali gate dijalankan ia meninggalkan catatan ringkas: perintah, cakupan, revisi, hasil, dan sebuah path bukti.

Disiplin keamanan

Keamanan bersifat kelas satu dengan cara yang sama seperti test, dan ia mengikuti model dua lapis yang sama: disiplin per-tugas selama pekerjaan berlangsung, ditambah pemeriksaan keamanan dari Final Review atas seluruh kumpulan perubahan di akhir. Setiap kali sebuah tugas menyentuh autentikasi atau otorisasi, penanganan input, secrets atau konfigurasi, permukaan jaringan, berkas, atau shell, atau dependensi:

• Acceptance criteria-nya MUST menyatakan ekspektasi keamanan dari perubahan tersebut — input divalidasi dan di-escape, tidak ada material rahasia di dalam kode atau fixture, pemeriksaan auth dipertahankan atau diperkuat — konsisten dengan docs/SECURITY.md.
• Setiap commit MUST dipastikan bebas dari secrets atau kredensial sebelum ia mendarat, termasuk fixture test dan contoh dokumentasi. Sebuah secret dalam commit yang telah didorong MUST diperlakukan sebagai bocor dan dirotasi, bukan sekadar dihapus.
• Di mana pekerjaan yang sensitif terhadap keamanan bersifat substansial, sebuah tugas hardening khusus SHOULD ditempatkan tepat setelah tugas-tugas implementasi dan sebelum tugas test komprehensif, sehingga temuan diperbaiki sebelum test mengodekan perilaku tersebut dan setiap temuan menjadi kasus regresi alih-alih pengerjaan ulang.

Disiplin per-tugas ini tidak menggantikan pemeriksaan keamanan Final Review: pemeriksaan per-tugas menangkap masalah di commit tempat masalah itu lahir, sementara gate akhir mengaudit seluruh rencana — termasuk tugas test dan dokumentasi itu sendiri.

Siklus hidup rencana — Final Review

Setiap rencana konforman yang ditulis di bawah versi ini berakhir dengan tepat satu tugas wajib: Final Review (tugas N). Dua tanggung jawab yang ditempatkan versi sebelumnya pada tugas-tugas penutup terpisah dipindahkan: keputusan skills berpindah ke dalam tugas yang menghasilkan polanya, dan Executive Report menjadi artefak opsional atas permintaan. Tidak ada bagian dari pemeriksaan keamanan yang dilonggarkan.

Final Review MUST, secara berurutan:

(a) Pemeriksaan keamanan — meninjau seluruh kumpulan perubahan rencana yang terakumulasi untuk secret yang di-hardcode, risiko injeksi, permukaan serangan baru, auth yang melemah, dan data sensitif di dalam log atau dokumen; mengaudit dependensi yang diperkenalkan; memverifikasi bahwa docs/SECURITY.md masih mencerminkan kenyataan; menulis laporan tinjauan keamanan bahkan ketika bersih. Sebuah temuan kritis diperbaiki — atau diterima secara eksplisit oleh pengguna — sebelum rencana selesai.

(b) Validasi status akhir — validasi lengkap yang berlaku milik repositori dijalankan dan lulus pada status relevan terakhir.

(c) Rekonsiliasi skills — setiap tugas membawa sebuah disposisi skills dan setiap kandidat yang tercatat memiliki disposisi; tidak ada laporan penemuan kedua.

(d) Penyelesaian — melaporkan penyelesaian beserta deliverable, bukti validasi, dan keterbatasan; menawarkan Executive Report satu kali. Rencana selesai, terjawab atau tidak tawaran itu.

Final Review berjalan secara berurutan setelah semua tugas lain dan tidak pernah ditempatkan dalam kelompok paralel.

Keputusan skills per-tugas

Pertanyaan “apakah pekerjaan ini menghasilkan pola yang dapat dipakai ulang dan layak menjadi sebuah skill atau agent?” dijawab di dalam tugas yang menghasilkan pola itu, selagi buktinya masih ada dalam konteks. Completion & Log setiap tugas membawa sebuah disposisi skills: tidak ada, memperbarui skill yang ada, membuat artefak yang dinamai, atau sebuah penundaan disertai alasan. Penulisan yang beralasan terjadi di dalam tugas itu, sebelum validation gate dan commit-nya, setelah memeriksa katalog yang ada untuk duplikat.

Executive report — opsional, atas permintaan

Executive Report tidak lagi menjadi tugas wajib. Saat penyelesaian, agent menawarkannya satu kali; ia dihasilkan hanya atas permintaan eksplisit, dipenuhi dari bukti yang tahan lama tanpa memutar ulang rencana. Tanpa jawaban, atau pada eksekusi tanpa pengawasan, rencana tetap selesai tanpa laporan yang dihasilkan.

Protokol penyelesaian tugas

Setelah melewati validasi dan sebelum beralih ke tugas berikutnya, agent MUST, secara berurutan: (1) menandai tugas [x] di README rencana; (2) menambah hitungan status rencana; (3) mengisi Completion & Log tugas tanpa nilai placeholder; (4) menambahkan entri 3–5 poin di PROGRESS.md; (5) melakukan commit (di mana rencana melakukan commit) dengan format {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) di mana rencana membawa lapisan status, menulis ulang state.json secara atomik — tugas completed, catatan gate, catatan outcome, hash commit.

Keenam langkah membentuk satu transaksi logis. Sebuah agent yang terinterupsi di tengah protokol MUST NOT memulai tugas berikutnya — ia harus menyelesaikan atau membatalkan penyelesaian parsial terlebih dahulu.

Protokol Resume DWP

Resume MUST dimungkinkan hanya dari berkas rencana ditambah log git, tanpa status eksternal. Di ruang kerja tanpa git — lihat Arketipe §3 — state.json rencana REQUIRED dan menggantikan log git.

Sebuah agent yang melanjutkan — sesi baru, agent yang berbeda, giliran daemon terjadwal, atau sesi cloud yang bangun — MUST melakukan ritual ini, secara berurutan:

1. Re-anchor. Baca README rencana: tujuan, panduan global, daftar tugas.
2. Temukan checkpoint. Temukan tugas pertama yang tidak dicentang di README; baca log git dan git status (atau checkpoint di state.json di mana git tidak ada).
3. Rekonsiliasi status. Di mana state.json ada, bandingkan dengan kotak centang README; pada desinkronisasi, regenerasi dari markdown sebelum melanjutkan.
4. Periksa seam. Baca Completion & Log tugas pada titik resume dan entri PROGRESS.md terakhir — tanah yang terakhir diverifikasi oleh sesi sebelumnya.
5. Smoke-test. Jalankan validasi berdiri termurah repositori untuk mengonfirmasi dunia masih bekerja sebelum membangun di atasnya. Smoke test yang gagal diselidiki terlebih dahulu, tidak dibangun di atasnya.
6. Lanjutkan secara atomik. Eksekusi tepat tugas berikutnya; jangan lakukan batch ke depan.

Agent MUST mempercayai tanda selesai ([x]) dan MUST NOT memvalidasi ulang tugas yang selesai kecuali pengguna secara eksplisit memintanya, atau smoke test gagal dengan cara yang mengimplikasikan tugas yang selesai.

Loop eksekusi

DWP mendefinisikan lima operasi:

• create — Menghasilkan rencana baru dari sebuah tujuan.
• execute — Mengeksekusi rencana tugas demi tugas.
• refine — Memodifikasi rencana yang ada.
• resume — Melanjutkan rencana yang terhenti.
• status — Melaporkan status rencana tanpa mengeksekusi.

Ruang kerja keluaran

Ruang kerja keluaran

• .dwp/ diabaikan git · sekali pakai
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ laporan
• SECURITY_REVIEW.md tinjauan keamanan
• EXECUTIVE_REPORT.md laporan eksekutif

Semua artefak DWP MUST berada di bawah direktori .dwp/ yang di-gitignore di akar repositori.

Status rencana yang dapat dibaca mesin

Sebuah rencana MAY membawa lapisan status yang dapat dibaca mesin — manifest.json (identitas statis) dan state.json (status per-tugas berjalan, catatan validation gate, catatan outcome, checkpoint, status terblokir). Rencana markdown tetap menjadi sumber kebenaran; lapisan JSON adalah proyeksi turunan, diregenerasi pada titik protokol dan direkonsiliasi saat resume.

Lapisan status RECOMMENDED untuk rencana baru, REQUIRED untuk eksekusi tanpa pengawasan, dan REQUIRED untuk ruang kerja agent tanpa git. Lihat definisi normatif lengkap di Status rencana.

Rigor proporsional

Rigor MUST sebanding dengan pekerjaan. Seremonial pada perubahan sepele adalah kegagalan metodologi, bukan keamanan ekstra. Setiap pekerjaan jatuh tepat pada satu tingkatan:

Sebuah agent yang diminta membuat rencana untuk pekerjaan tingkatan micro MUST menyatakan bahwa rencana tidak proporsional dan menawarkan bentuk inline sebagai gantinya. Folder rencana MUST NOT dibuat untuk perubahan satu berkas yang sepele.

Pekerjaan tingkatan micro tetap menjaga hal yang tidak bisa dinegosiasikan: tujuan yang eksplisit, validation gate yang berjalan dan lulus, serta disiplin test untuk perubahan perilaku. Tingkatan mengubah kemasan, tidak pernah gate-nya.

Ketika cakupan berkembang di tengah jalan — sebuah tugas micro menemukan cakupan nyata, sebuah rencana standard memunculkan sub-repositori — agent MUST berhenti dan mempromosikan pekerjaan ke tingkatan berikutnya alih-alih meregangkan yang sekarang.

Kompatibilitas

Rencana dan repositori dari versi sebelumnya tetap konforman, dan sebuah pemeriksa konformansi MUST membedakan artefak lama yang dikenal (diterima) dari artefak yang menyatakan versi ini namun secara objektif tidak valid di bawahnya (ditolak):

Pemberian versi

Spesifikasi ini mengikuti semantic versioning.