Skip to content
← Semua dokumen spesifikasi

DWP specification

Versi 1.2. 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.

Tambahan di v1.2. Empat kemampuan tambahan, tanpa perubahan yang merusak: (1) lapisan status rencana yang dapat dibaca mesin (manifest.json + state.json, lihat Status rencana); (2) tingkatan rigor proporsional (micro / standard / deep, lihat Rigor proporsional); (3) bagian Delta opsional dalam anatomi tugas untuk perubahan perilaku brownfield; dan (4) Protokol Resume DWP dipromosikan menjadi ritual enam langkah yang bernama dan dapat dikutip. Rencana v1.1 yang ada 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.

Struktur rencana

Sebuah rencana MUST berupa sebuah direktori di bawah .dwp/plans/ bernama PLAN_<slug>/. Direktori itu MUST berisi:

  • README.md — ikhtisar rencana, tujuan, tabel tugas, dan status.
  • Satu berkas per tugas, bernama <n>.task_<slug>.md.
  • PROGRESS.md — log eksekusi yang berjalan.

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

Setiap berkas tugas MUST berisi sembilan 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. Steps — tindakan konkret yang berurutan untuk dilakukan.
  4. Acceptance criteria — daftar periksa kondisi yang mendefinisikan selesai.
  5. Validation — perintah atau test yang dijalankan untuk memverifikasi.
  6. Files — path yang diperkirakan akan dibuat atau diubah.
  7. Dependencies — tugas lain atau prasyarat eksternal.
  8. Risks — apa yang bisa salah, dan mitigasinya.
  9. 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).

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, dan gate validasi tugas (test yang ada tetap hijau) adalah yang menegakkannya.

Validation gate dan test

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. Test adalah bagian kelas satu dari gate ini, bukan tambahan opsional — itulah yang membuat kode yang dikirim sebuah rencana andal dan dapat diverifikasi.

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 (jalur bahagia ditambah kasus tepi dan kasus kesalahan yang bermakna), mengikuti konvensi test dan ekspektasi cakupan repositori.
  • Validation-nya MUST menjalankan test repositori bersama dengan pemeriksaan lint, type-check, dan format-nya — pemeriksaan kualitas kode lengkap yang didefinisikan repositori — bukan build saja. “Ia berhasil di-build” bukanlah gate yang memadai untuk sebuah perubahan perilaku.
  • Test yang ada MUST tetap hijau. Sebuah perubahan yang merusak test yang mencakup kode terdampak MUST memperbarui test tersebut ke perilaku baru yang dimaksudkan; ia MUST NOT menghapus, melewati, atau melemahkan sebuah test semata-mata untuk memaksa gate lulus.

Tugas dokumentasi-murni, konfigurasi, atau riset dikecualikan dari pembuatan test tetapi tetap MUST menjalankan validation gate apa pun yang didefinisikan repositori. Kedalaman pengujian sebanding dengan ukuran perubahan dan kematangan repositori. Di mana sebuah repositori sama sekali tidak memiliki toolchain test atau lint, agent MUST NOT diam-diam melewati disiplin ini — ia bersandar pada toolchain yang diusulkan selama onboarding (lihat Conformance).

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 gate Security Review wajib 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 tugas akhir Security 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. Oleh karena itu setiap rencana berakhir dengan tiga tugas akhir wajib — Security Review, lalu Skills & Agents Discovery, lalu Executive Report — dan sebuah temuan keamanan kritis memblokir penyelesaian sampai ia diperbaiki atau diterima secara eksplisit.

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

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:

Tingkatan Kapan Bentuk
micro Satu perubahan atomik: satu concern, kira-kira satu sesi, tanpa koordinasi. Perbaikan bug, perubahan teks, penyesuaian konfigurasi. Tidak ada folder rencana. Agent menyatakan tujuan, acceptance criteria, dan validation gate secara inline dalam percakapan, mengeksekusi, memvalidasi, melakukan commit.
standard Pekerjaan multi-langkah dengan cakupan nyata: sebuah fitur, sebuah refactor, sebuah migrasi dalam satu repo. Tingkatan default. Rencana penuh: folder rencana, tugas sembilan bagian, tugas akhir wajib.
deep Pekerjaan berjangka panjang yang mencakup kelompok paralel, repositori turunan, atau beberapa sesi tanpa pengawasan. Rencana standard ditambah kemampuan orchestrator dan/atau team-agents, dan lapisan status.

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.

Pemberian versi

Spesifikasi ini mengikuti semantic versioning.