Skip to content
Deep Work Plan hadir di Product Hunt hari ini Dukung kami
← Semua dokumen spesifikasi

Conformance

Versi 1.3. Status: Stabil. Dokumen ini mendefinisikan apa artinya sebuah repositori menjadi konforman terhadap Deep Work Plan — yaitu, AI-first dan dapat dikemudikan agent. Kata kunci MUST, MUST NOT, SHOULD, SHOULD NOT, dan MAY harus ditafsirkan sebagaimana dijelaskan dalam RFC 2119.

Konformansi ada agar “AI-first” menjadi properti yang objektif dan dapat diperiksa, bukan sekadar kesan. Sebuah repositori entah memenuhi kriteria di bawah atau tidak. Sub-skill verify (/dwp-verify) memeriksanya secara mekanis.

Sebuah repositori yang konforman

Sebuah repositori konforman DWP MUST memenuhi semua hal berikut. Setiap artefak MUST dipikirkan untuk repositori — disesuaikan dengan bahasa, framework, dan perintahnya yang nyata. Sebuah stub generik, sebuah placeholder, atau konten yang disalin dari repositori lain tidak memenuhi sebuah kriteria.

  1. AGENTS.md di akar. Repositori MUST berisi sebuah AGENTS.md di akar yang mencakup (a) sebuah indeks dokumentasi, (b) aturan-aturan wajib untuk repositori, dan (c) sebuah blok Quick Commands yang perintah-perintahnya nyata dan dapat dijalankan di repositori ini. Perintah placeholder (misalnya, npm test di repositori yang tidak memakai npm) MUST NOT muncul. Indeks MUST NOT menautkan sebuah berkas docs/ yang tidak ada, dan berkas ini SHOULD tetap berada dalam anggaran 150–500 baris, memindahkan detail ke docs/ dan menautkannya alih-alih tumbuh tanpa batas.
  2. CLAUDE.md me-resolve ke AGENTS.md. Sebuah CLAUDE.md MUST ada dan me-resolve ke AGENTS.md (sebuah symlink, atau padanan yang menjamin satu sumber kebenaran). Keduanya MUST NOT menyimpang.
  3. Sebuah hierarki docs/. Repositori MUST berisi sebuah direktori docs/ yang mencakup kategori-kategori standar (arsitektur, standar, pengujian, perintah pengembangan, keamanan, dan onboarding agent) dengan konten nyata yang spesifik repositori. Modul kompleks SHOULD membawa README.md-nya sendiri. Panduan pengujian MUST mendefinisikan toolchain test, lint, dan type-check yang nyata — atau, untuk sebuah repositori yang tidak memiliki satu pun, sebuah penyiapan konkret yang diusulkan dari stack selama onboarding. Sebuah panduan pengujian yang kosong atau “tanpa test” tidak memenuhi kriteria ini: tanpa cara yang terdefinisi untuk memvalidasi perilaku, sebuah rencana tidak memiliki validation gate yang objektif.
  4. Sebuah rumah .agents/. Repositori MUST berisi sebuah direktori .agents/ dengan agents/, commands/, dan skills/, ditambah sebuah katalog di bawah .agents/docs/ yang sesuai dengan apa yang ada di disk. Command dwp-* MUST menjadi delegator tipis ke skill yang terpasang. Sebuah path .claude MUST me-resolve ke .agents.
  5. Sebuah ruang kerja .dwp/ yang di-gitignore. Repositori MUST berisi sebuah direktori .dwp/ dengan plans/, dan .dwp/ MUST di-gitignore. Sebuah ruang scratch tmp/ SHOULD ada dan SHOULD di-gitignore.
  6. Skill metodologi dapat di-resolve. Skill Deep Work Plan MUST terpasang atau dirujuk sedemikian rupa sehingga sebuah agent di repositori dapat memanggil sub-skill-nya.

Sebuah repositori sepenuhnya konforman dengan nol addon opsional. Addon opsional (devcontainer, Dailybot, dependency-upgrade, design-system) MUST NOT diwajibkan untuk konformansi. Sejak standar 2.3.0 tinjauan lokal AI Diff Reviewer (skill vendored + berkas ekstensi) adalah bagian dari baseline: ketiadaannya adalah kegagalan bagi repositori yang menyatakan 2.3.0 atau lebih baru, dan sebuah temuan versi-harness bagi repositori lama. Permukaan CI-nya tetap opsional.

Sebuah rencana yang terbentuk baik

Sebuah Deep Work Plan di .dwp/plans/ terbentuk baik ketika:

  1. Setiap tugas MUST mendeklarasikan lingkup, acceptance criteria, dan setidaknya satu validation gate (sebuah perintah atau pemeriksaan yang secara objektif lulus atau gagal) yang eksplisit.
  2. Setiap tugas yang menambahkan fungsionalitas inti baru atau mengubah perilaku produk MUST menyertakan cakupan test otomatis untuk perilaku itu dalam acceptance criteria-nya, dan MUST menjalankan test repositori bersama dengan pemeriksaan lint dan type-check-nya dalam validation gate-nya — bukan build saja. Test yang ada MUST tetap hijau; sebuah perubahan perilaku MUST memperbarui test yang dirusaknya alih-alih menghapus atau melewatinya. Tugas dokumentasi-murni, konfigurasi, atau riset dikecualikan dari pembuatan test tetapi tetap menjalankan gate repositori.
  3. Setiap tugas yang menyentuh autentikasi, penanganan input, secret atau konfigurasi, permukaan jaringan, atau dependensi MUST membawa ekspektasi keamanan dari perubahan itu dalam acceptance criteria-nya, dan setiap commit MUST bebas dari materi secret.
  4. Rencana MUST mempersistenkan kemajuan sehingga pekerjaan bertahan dari interupsi dan dapat dilanjutkan oleh agent yang berbeda. Sebuah tugas MUST NOT dicatat completed selama salah satu catatan validation gate-nya masih menunjukkan sebuah jalannya yang gagal dan belum terselesaikan, dan log penyelesaian sebuah tugas MUST NOT bertentangan dengan status tercatatnya (misalnya sebuah tugas completed yang log-nya masih membaca “Status: pending” adalah sebuah cacat, bukan sebuah keberhasilan).
  5. Rencana MUST ditutup dengan tinjauan akhir yang tercatat miliknya. Sebuah rencana yang ditulis di bawah versi ini MUST diakhiri dengan tepat satu Final Review wajib — pemeriksaan keamanan, validasi status akhir, dan rekonsiliasi skills. Sebuah rencana yang ditulis di bawah versi sebelumnya diakhiri dengan tiga tugas akhir wajib (Security Review, Skills & Agents Discovery, Executive Report) dan tetap konforman. Sebuah temuan keamanan kritis memblokir penyelesaian sampai diperbaiki atau diterima secara eksplisit. Penyelesaian itu sendiri adalah sebuah transaksi yang terverifikasi dan dapat dipulihkan, bukan sekadar pergantian status: tugas terminal ditutup melalui sebuah langkah publikasi yang dijaga, yang memvalidasi artefak-artefak rencana yang selesai sebelum menulis status dan meninggalkan sebuah tanda terima FINALIZATION.json yang dapat diperiksa secara mekanis; sebuah publikasi yang terinterupsi dipulihkan dari bukti, tidak pernah secara diam-diam dinyatakan ulang selesai. Bukti pointer apa pun yang dirujuk sebuah catatan gate MUST bisa diselesaikan di dalam folder rencana itu sendiri — sebuah pointer yang menggantung atau keluar dari folder adalah sebuah temuan, bukan bukti yang sah.
  6. Tugas SHOULD berlabuh kembali ke tujuan rencana sebelum mengeksekusi, untuk mencegah penyimpangan sepanjang rentang yang panjang.

Memverifikasi konformansi

Konformansi SHOULD diverifikasi secara mekanis ketimbang dengan inspeksi. Menjalankan /dwp-verify menghasilkan laporan lulus/gagal terhadap kriteria di atas: keberadaan dan kenyataan-konten AGENTS.md, resolusi CLAUDE.md, kategori-kategori docs/, kecocokan katalog-versus-disk .agents/, status gitignore .dwp/ dan tmp/, dan — untuk sebuah rencana — bahwa setiap tugas membawa acceptance criteria dan sebuah validation gate, dengan cakupan test untuk tugas yang mengubah perilaku dan tinjauan akhir yang tercatat hadir. Untuk sebuah rencana, ia juga memeriksa bahwa markdown rencana dan status yang dapat dibaca mesinnya sepakat (sebuah desinkronisasi antara README dan state.json adalah sebuah temuan, tidak pernah sebuah keberhasilan yang diam-diam), bahwa tugas-tugas yang selesai membawa bukti gate dan log yang tidak bertentangan, dan — di mana sebuah rencana yang selesai mencapainya — bahwa sebuah tanda terima publikasi mendukung penyelesaian yang diklaim. Pemeriksanya bersifat sadar-versi: ia MUST menerima rencana lama (tiga tugas akhir wajib, tanpa Touched Surface) sebagai konforman, dan MUST menolak rencana yang menyatakan versi ini namun secara objektif tidak valid di bawahnya. Ia juga melaporkan baris provenans DWP standard: yang hilang atau usang sebagai temuan yang menyebutkan upgrade harness tertarget. Lapisan mekanis jujur tentang batasnya: tanpa interpreter yang mampu (Python 3.9+), ia berakhir dengan keluaran bukan nol dan vonis UNVERIFIED eksplisit alih-alih melewati pemeriksaannya — sebuah pemeriksa tidak pernah melaporkan hasil yang tidak ia verifikasi.

Sebuah repositori SHOULD diverifikasi ulang setelah onboarding dan setelah setiap rencana yang selesai, sehingga konformansi dipelihara ketimbang ditegaskan sekali saja.