Disiplin Plan — Memori Kerja Efemeral Lokal-Proyek

Referensi normatif kanonis untuk kontributor hilir. Dokumen ini mencerminkan seksi Disiplin Rencana pada spesifikasi proyek (Spec §3); ia adalah referensi mandiri yang dikirim bersama repo yang dipublikasikan. Disiplin yang diperkenalkan di sini bersifat fondasional; setiap arahan di bawah ini bersifat MUST (HARUS) kecuali ditandai secara eksplisit sebaliknya. Rasional arsitekturalnya dicatat di ADR-0001.

1. Definisi & BatasanCopy Anchor Link

Sebuah rencana adalah setiap artefak kerja sementara yang disengaja dan dihasilkan selama penalaran tentang suatu proyek, termasuk namun tidak terbatas pada:

• Sketsa arsitektur, penelusuran desain sistem, dan dekomposisi komponen.
• Struktur pemecahan kerja, daftar tugas multi-langkah, dan pohon dekomposisi.
• Strategi refaktor, penelusuran migrasi, dan urutan rollout.
• Jurnal debugging, log hipotesis, dan catatan reproduksi.
• Catatan eksplorasi, tulisan spike, draf prompt, dan transkrip asisten yang disimpan untuk digunakan nanti.
• Dokumen apa pun yang ditulis untuk berpikir, bukan untuk dikirim.

Rencana secara kategoris berbeda dari kelas-kelas berdampingan berikut:

Rencana mendahului ADR. Ketika sebuah rencana mengerucut menjadi keputusan yang tahan lama, keputusan itu dipromosikan menjadi ADR (§4 Siklus Hidup); rencana itu sendiri diarsipkan atau dibuang.

2. Lokasi, Visibilitas & PenamaanCopy Anchor Link

• Path. <project-root>/.apothem/plans/ adalah satu-satunya rumah kanonis. Pohon <project-root>/.plans/ warisan tidak lagi kanonis — tingkatkan dengan apothem migrate-workspace (§5). Bukan direktori konfigurasi harness (misalnya ~/.claude/plans/, ~/.claude/.plans/, atau ~/.codex/.plans/). Bukan folder scratch desktop. Bukan ~/notes/. Bukan tmp/plans/.
• Visibilitas. Folder didaftarkan di .gitignore proyek sesuai snippet kanonis pada §6. Harness HARUS memverifikasi keberadaan entri ini sebelum penulisan apa pun; jika tidak ada, ia menambahkan entri dengan komentar header satu baris dan tautan ke dokumen ini.
• Konvensi nama berkas. YYYY-MM-DD--<kebab-case-slug>.md. Untuk ruang kerja yang lebih besar, kelompokkan di bawah .apothem/plans/<area>/YYYY-MM-DD--<slug>.md.
  • Contoh: .apothem/plans/2026-04-30--auth-refactor-strategy.md, .apothem/plans/api/2026-04-30--rate-limit-rollout.md.
• Indeks. .apothem/plans/INDEX.md opsional (juga di-gitignore) dapat mengagregasi tautan dan status; jika berkas itu ada, harness memeliharanya pada setiap penulisan rencana.
• Arsip. Rencana yang mengerucut atau ditinggalkan dipindahkan ke .apothem/plans/_archive/. Tidak pernah dihapus tanpa konfirmasi pertanyaan terstruktur yang eksplisit.
• Header penulis pada rencana. Rencana dikecualikan dari baris SPDX header penulis (sesuai site/content/docs/reference/authorship-header.mdx §Daftar Pengecualian). Rencana adalah artefak sementara yang di-gitignore; menerapkan penanda provenans permanen pada memori kerja sementara adalah kesalahan kategori. Frontmatter (§3) membawa provenans rencana.

3. Skema Frontmatter (tervalidasi)Copy Anchor Link

Setiap berkas rencana memuat:

---
title: <human-readable title>
project: <git-remote-url-or-canonical-local-path>
created: <ISO-8601 timestamp>
updated: <ISO-8601 timestamp>
status: draft | in-progress | converged | abandoned
tags: [<kebab>, ...]
supersedes: <prior-plan-relative-path or null>
promotes-to: <ADR path or null>
---

Skema JSON untuk rencana ada di src/apothem/schemas/plan.schema.json. Perintah slash /plan (dan validator plans-discipline-language) memvalidasi terhadap skema itu pada setiap penulisan.

4. Siklus Hidup & Alur Kerja PromosiCopy Anchor Link

1. Draf — pembuatan awal; status: draft.
2. Sedang dikerjakan — sedang diiterasi secara aktif; status: in-progress; updated disegarkan pada setiap suntingan material.
3. Konvergensi — sebuah keputusan tahan lama mengkristal:
   1. Ekstrak keputusan itu menjadi ADR baru di lokasi ADR yang diratifikasi proyek.
   2. Atur promotes-to rencana ke path ADR.
   3. Atur status: converged.
   4. Opsional, pindahkan ke .apothem/plans/_archive/.
4. Pengabaian — arah ditinggalkan; status: abandoned; arsipkan atau, dengan pertanyaan terstruktur yang eksplisit, buang.
5. Penggantian — ketika rencana baru menggantikan yang lama, atur supersedes rencana baru ke path rencana lama, dan atur status rencana lama sesuai.

Promosi adalah satu-satunya jalur yang membuat konten rencana menjadi tahan lama, terkendali versi, dan terlihat oleh rekan tim. Tidak ada rencana yang pernah bermigrasi utuh ke dalam sumber yang di-commit.

5. Protokol Migrasi — Sekali Saja, Dari Direktori Rencana Harness ke .apothem/plans/ Per-ProyekCopy Anchor Link

Catatan. Protokol ini berlaku untuk proyek hilir yang mengadopsi Disiplin Rencana untuk pertama kali, ketika artefak perencanaan sebelumnya berada di dalam direktori konfigurasi harness (misalnya ~/.claude/plans/, ~/.claude/.plans/, atau path setara untuk harness lain). Kasus rekursif untuk ekosistem itu sendiri diselesaikan dengan men-gitignore status rencana lokal-harness alih-alih memindahkannya secara fisik ke dalam sumber.

Perkakas. Untuk proyek yang sudah berada pada tata letak warisan — pohon <project-root>/.plans/ bersaudara ditambah penyimpanan per-harness <project-root>/.apothem/<harness>/{memory,contexts,learning} — perintah apothem migrate-workspace menggabungkan keduanya ke dalam direktori kerja bersama <project-root>/.apothem/{plans,memory,learning,contexts}. Perintah ini idempoten dan tidak merusak: ia mencadangkan setiap sumber yang dikonsumsi, memindahkan .plans/ ke .apothem/plans/, menggabungkan penyimpanan memori dan konteks per-harness secara union, menggabungkan sinyal pembelajaran dengan concatenate lalu dedup, dan tidak pernah menimpa catatan yang bertentangan. Jalankan apothem migrate-workspace --dry-run untuk melihat pratinjau pemindahan terlebih dahulu.

Migrasi bersifat idempoten dan dapat dibalik hingga saat direktori rencana lokal-harness dihapus (setelah itu, tarball cadangan di ./.audit/plans-backup-<timestamp>.tar.gz menjadi artefak rollback). Contoh di bawah menggunakan ~/.claude/plans/; ganti dengan path yang setara untuk harness yang aktif.

Langkah 1 — Inventaris. Setiap berkas di bawah direktori rencana lokal-harness dienumerasi dan diklasifikasikan sebagai plan-artifact (quarantined).

Langkah 2 — Peta provenans. Sebuah catatan provenans dibangun untuk setiap rencana, dengan proyek tujuan yang disimpulkan dan skor kepercayaan yang diturunkan dari field project pada frontmatter, sinyal pemindaian badan (URL repo, nama paket, path absolut), dan isyarat kontekstual.

Langkah 3 — Konfirmasi pemetaan. Peta lengkap disajikan kepada operator sebagai satu pertanyaan terstruktur yang terkonsolidasi (atau urutan yang dikelompokkan rapat ketika jumlah berkas melampaui ukuran satu prompt yang nyaman). Untuk setiap rencana, operator memilih di antara:

• Konfirmasi proyek tujuan yang disimpulkan.
• Tetapkan ulang ke proyek lain (opsi ini menampilkan daftar proyek yang diketahui operator).
• Tunda — pindahkan ke ~/.claude/.audit/orphan-plans/<original-name> untuk diurutkan nanti.
• Buang — hanya dengan pertanyaan terstruktur yang eksplisit dan dikonfirmasi terpisah (tindakan ini bersifat destruktif).

Ketika kepercayaan bernilai high untuk banyak rencana, prompt menawarkan fasilitas confirm-all-high-confidence untuk memadatkan bolak-balik sekaligus tetap menampilkan setiap keputusan individual dalam log.

Langkah 4 — Persiapan proyek sebelum pemindahan. Untuk setiap proyek tujuan yang unik:

1. Verifikasi bahwa root proyek ada dan dapat dibaca.
2. Verifikasi bahwa itu adalah repositori git (untuk root non-git, tampilkan melalui saluran pertanyaan terstruktur apakah akan dilanjutkan, diinisialisasi, atau dilewati).
3. Pastikan <project-root>/.apothem/plans/ ada; buat dengan mkdir -p jika belum.
4. Verifikasi bahwa .gitignore proyek memuat snippet kanonis dari §6; jika belum ada, tambahkan dengan komentar header yang mengakui migrasi ini.
5. Verifikasi bahwa <project-root>/.apothem/plans/ belum dilacak oleh git; jika sudah (kesalahan kontributor sebelumnya), tampilkan melalui saluran pertanyaan terstruktur dengan opsi untrack-and-keep, untrack-and-remove-from-history, abort.

Langkah 5 — Pindahkan. Untuk setiap pasangan rencana → tujuan yang telah dikonfirmasi:

1. Hitung nama berkas tujuan: jika sumber memiliki frontmatter, normalkan sesuai §3; jika tidak, bungkus badan dengan frontmatter (status draft, field project diisi, created diambil dari mtime, tags [migrated]) lalu ganti nama menjadi YYYY-MM-DD--<slug>.md.
2. Jika ada tabrakan nama di tujuan, tambahkan -imported-<unix-timestamp> dan catat penggantian nama tersebut.
3. Salin berkas (mempertahankan mtime), verifikasi bahwa SHA-256 cocok di tujuan, lalu hapus tautan sumber (unlink).
4. Tambahkan entri ke <project-root>/.apothem/plans/_migration-manifest.md (juga di-gitignore) yang mencatat: path lokal-harness asli, path tujuan, SHA-256 asli, timestamp, dan jawaban pertanyaan terstruktur yang mengotorisasi pemindahan ini.

Langkah 6 — Verifikasi. Setelah semua pemindahan selesai:

1. Pastikan direktori rencana lokal-harness kosong (rencana yatim, jika ada, berada di dalam direktori audit/karantina harness tersebut di luar direktori yang akan dihapus).
2. Pastikan setiap proyek tujuan memiliki .apothem/plans/ yang terisi dan sebuah manifest.
3. Periksa sampel dengan SHA-256 bahwa konten yang dimigrasikan cocok dengan aslinya.

Langkah 7 — Tarball dan penghapusan. Buat ./.audit/plans-backup-<ISO-timestamp>.tar.gz yang berisi seluruh pohon rencana lokal-harness sebelum pemindahan (diekstrak dari snapshot sementara yang diambil pada Langkah 1). Kemudian, melalui pertanyaan terstruktur final yang mengonfirmasi kesiapan, hapus direktori rencana lokal-harness yang kini kosong.

Langkah 8 — Rekam audit. Hasilkan ./.audit/plans-migration.md yang merangkum setiap pemindahan, setiap berkas yang ditunda, setiap pembuangan, setiap penggantian nama karena tabrakan, dan setiap penambahan gitignore.

6. Snippet .gitignore Hilir (kanonis, salin-tempel)Copy Anchor Link

Setiap proyek yang mengadopsi ekosistem ini HARUS menambahkan blok berikut ke .gitignore-nya:

# Apothem working directory (project-local shared state: plans, memory,
# learning, contexts; gitignored — never committed). The sole canonical plans
# home is `.apothem/plans/`.
# See: <repo-url>/blob/main/site/content/docs/reference/plans-discipline.mdx
# Ignore the CONTENTS of this directory (not the directory) so the
# `.keep` negation below can take effect.
.apothem/*
!.apothem/.keep

Pengecualian .keep yang opsional mempertahankan keberadaan direktori pada alat yang memangkas path kosong, tanpa membocorkan konten. Apakah akan menyertakan .keep diputuskan per proyek melalui saluran pertanyaan terstruktur pada pemanggilan pertama /plan. Baris .apothem/* + !.apothem/.keep adalah snippet kanonis; proyek yang masih memuat pohon <project-root>/.plans/ warisan menjalankan apothem migrate-workspace (§5) untuk meningkatkannya menjadi .apothem/plans/.

7. Mekanisme Penegakan-SendiriCopy Anchor Link

Disiplin ini harus bertahan di setiap sesi mendatang. Permukaan penegakan berikut bersifat wajib dan terkode dalam ekosistem yang dipublikasikan:

1. AGENTS.md dan permukaan instruksi cermin — blok perilaku wajib tingkat-atas yang menyatakan: "Artefak perencanaan ditulis ke <project-root>/.apothem/plans/ — satu-satunya rumah rencana kanonis (pohon <project-root>/.plans/ warisan ditingkatkan melalui apothem migrate-workspace) — tidak pernah ke direktori konfigurasi harness mana pun (misalnya ~/.codex/ atau ~/.claude/) dan tidak pernah ke lokasi global. Aturan ini tidak dapat ditawar; kutip §3 spesifikasi proyek pada setiap keputusan terkait." Blok ini dideteksi oleh validator plans-discipline-language.
2. Berkas instruksi dalam-repo per-harness — mencerminkan direktif yang sama dalam bingkai yang sesuai dengan permukaan instruksi harness tersebut (§4 Plans Discipline); dideteksi oleh validator yang sama pada setiap permukaan harness yang terdaftar.
3. Output-style default — ketika sebuah respons akan menghasilkan konten berbentuk rencana (strategi multi-langkah, dekomposisi, penelusuran desain, jurnal debugging), style merutekan artefak ke penulisan .apothem/plans/ lokal-proyek alih-alih mencetaknya inline lalu membuangnya. Style secara eksplisit menginstruksikan: "Jika root proyek tidak dapat ditemukan, hentikan dengan pertanyaan terstruktur yang menanyakan kepada operator di mana harus membuat rencana."
4. Setiap prompt pekerja terdelegasi — membawa stanza Output Surface yang menamai .apothem/plans/ sebagai tujuan untuk artefak perencanaan apa pun, dan stanza Anti-Pattern yang menamai direktori rencana lokal-harness sebagai terlarang.
5. Slash command /plan khusus — menerima slug + badan, menulis ke <project-root>/.apothem/plans/YYYY-MM-DD--<slug>.md dengan frontmatter yang benar, memastikan .gitignore tujuan sudah benar, dan menolak menulis ke path root konfigurasi harness.
6. Hook pre-tool-use — plan-write-guard — mencegat setiap pemanggilan alat penulisan berkas. Jika path target cocok dengan lokasi rencana lokal-harness (misalnya ~/.claude/plans/... atau ~/.codex/.plans/...) atau path ekosistem global lain yang diidentifikasi secara heuristik sebagai berbentuk rencana, hook memblokir penulisan dan memunculkan pertanyaan terstruktur yang mengusulkan pengalihan ke .apothem/plans/ proyek saat ini.
7. Validator CI — no-global-plans menggagalkan build jika memori kerja rencana yang di-commit muncul kembali dalam pohon yang dipublikasikan; plans-discipline-language gagal jika direktif kanonis hilang dari berkas instruksi harness terdaftar mana pun atau dari output-style default. Permukaan target kanonis validator (dipertahankan sebagai kontrak sistem berkas) tercantum dalam blok berpagar di bawah.

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

8. Pre-commit hooks — mencerminkan hal di atas secara lokal sehingga disiplin ditegakkan sebelum commit apa pun masuk.

8. Anti-Pola (terlarang secara kategoris)Copy Anchor Link

• Menulis rencana di dalam direktori konfigurasi harness (misalnya ~/.claude/plans/ atau ~/.codex/.plans/) atau lokasi global lain mana pun.
• Meng-commit rencana ke riwayat git proyek (hook saat-commit seharusnya menolak ini).
• Mencampur rencana dengan ADR (siklus hidup berbeda, lokasi berbeda, status commit berbeda).
• Rencana tanpa frontmatter, rencana tanpa nama berkas berawalan tanggal, atau rencana tanpa field project.
• Rencana lintas-proyek (satu rencana, dua proyek). Pisahkan — satu rencana per proyek.
• Berbagi rencana antar mesin melalui sinkronisasi konfigurasi harness (misalnya ~/.claude untuk Claude Code) — argumen struktural untuk menjaga rencana tetap lokal-proyek: repo proyek adalah mekanisme sinkronisasi, pada kesempatan langka ketika rencana perlu dibagikan — dan pembenaran itu sendiri merupakan sinyal bahwa konten tersebut harus dipromosikan menjadi ADR.
• Konten rencana yang disisipkan ke dalam prompt pekerja terdelegasi, badan skill, atau output-style. Permukaan tersebut adalah konfigurasi perilaku yang tahan lama; rencana adalah memori kerja sementara.
• Menerapkan baris SPDX header penulis ke berkas rencana (rencana dikecualikan secara desain — §2, site/content/docs/reference/authorship-header.mdx §Daftar Pengecualian).

Lihat JugaCopy Anchor Link

• ADR-0001 — rasional arsitektural, alternatif yang dipertimbangkan, dan trade-off yang diterima.
• site/content/docs/reference/authorship-header.mdx — disiplin baris SPDX header penulis (rencana dikecualikan secara kategoris).
• Halaman konvensi harness — konvensi harness multi-permukaan (Disiplin Rencana muncul sebagai klaim bersama di setiap berkas instruksi harness terdaftar dan setiap permukaan opsional yang diikuti). Path:

site/content/docs/reference/ai-conventions.mdx

• Spesifikasi proyek §3 — teks kanonis lengkap yang dicerminkan di sini.