Berkontribusi ke Apothem — Panduan Pengembang

Panduan ini membantu pengembang memelihara dan memperluas ekosistem Apothem dengan standar kualitas SOTA.

Rujukan Cepat: Jenis ArtefakCopy Anchor Link

Panduan ini mencakup lima jenis artefak, masing-masing dengan tujuan yang spesifik. Aturan, command, helper, dan skill membawa frontmatter YAML; hook didaftarkan di hooks.json dan settings.json dan tidak membawa frontmatter. Output-style adalah kelas artefak tambahan dengan dua kunci frontmatter wajib, name dan description; lihat Skema Frontmatter.

Kontrak Adapter HarnessCopy Anchor Link

Fakta identitas dan kapabilitas harness berada di src/apothem/lib/harness_registry.py. Sebuah perubahan harness selesai hanya ketika permukaan-permukaan berikut selaras:

Adapter bercakupan proyek harus menyetel requires_project = True, menerima project: Path | None pada metode siklus hidup, dan menolak akar proyek yang hilang atau tidak aman sebelum penulisan. Adapter bercakupan pengguna harus menjaga jalur tetap berada di bawah akar konfigurasi pengguna yang terdokumentasi milik harness.

Kebijakan Fixture GoldenCopy Anchor Link

tests/fixtures/harness-golden-plans.json mencatat bentuk install-plan publik untuk seluruh tujuh belas harness registri: ID publik, mode materialisasi, jalur kohor/templat sumber, dan jalur target ternormalisasi di bawah <ROOT>. Ketika perilaku target registri, manifest, atau templat berubah secara sengaja, perbarui fixture golden dalam commit yang sama dengan perubahan sumber agar diff menunjukkan delta perilakunya.

Validasi Sebelum PenulisanCopy Anchor Link

Driver pemasangan bersama memvalidasi setiap sumber dan target sebelum penulisan pertama. Driver ini menolak sumber manifest yang hilang, traversal target, jalur target di luar akar yang dipilih, dan penyeberangan symlink. Dry-run menjalankan validasi yang sama dan mengembalikan hasil skipped atau unchanged yang terstruktur tanpa membuat berkas.

Redaksi dan Data ContohCopy Anchor Link

Diagnostik profil meredaksi bidang token, rahasia, kata sandi, kredensial, kunci API, kunci privat, otorisasi, auth, dan bidang berbentuk header. Dokumentasi, fixture, contoh, dan cuplikan JSON menggunakan example.invalid, Example User, example-user, dan placeholder yang jelas, bukan rahasia atau akun pribadi yang tampak nyata.

Sebelum Anda Menulis: Skema KanonisCopy Anchor Link

Kontrak yang dapat dibaca mesin dan ditegakkan oleh gerbang adalah JSON Schema per kelas di bawah src/apothem/schemas/*.schema.json — additionalProperties menolak kunci yang tidak dikenal, sehingga gerbang konformitas memegang keputusan akhir. Dua proyeksi yang dapat dibaca manusia mengikutinya: site/content/docs/reference/frontmatter-schema.mdx (indeks kunci wajib) dan site/content/docs/reference/artifact-schema.mdx (templat per kelas dan contoh terapan). Ketika sebuah halaman bertentangan dengan JSON Schema, skemanya yang berlaku.

• Baca JSON Schema untuk jenis artefak Anda di bawah src/apothem/schemas/
• Baca site/content/docs/reference/artifact-schema.mdx § "Schema" untuk templat dan contoh terapan
• Salin bidang yang diwajibkan, isi nilai wajib, tambahkan bidang opsional sesuai kebutuhan

Pemeriksaan Cepat FrontmatterCopy Anchor Link

Setiap frontmatter artefak harus lolos pemeriksaan berikut. Terapkan pemeriksaan version, updated, dan portability hanya pada kelas yang membawa kuncinya: aturan tidak membawa satu pun dari ketiganya, dan skill tidak membawa portability.

✓ Valid YAML syntax (use tools: `yamllint` or PowerShell `ConvertFrom-Yaml` where available)
✓ All mandatory fields present (per schema for artifact type)
✓ name: uses kebab-case
✓ version: semantic MAJOR.MINOR.PATCH
✓ updated: ISO 8601 date (YYYY-MM-DD)
✓ description: single-line, non-empty
✓ scope fields valid per artifact type (rules: pathFilter + alwaysApply; CLAUDE.md root: scope)
✓ portability: string, for example `universal` (the schemas do not enumerate its values)
✓ No typos in field names — must match canonical schema exactly
✓ Optional fields use correct enum values

Konvensi PenamaanCopy Anchor Link

Nama Artefak (kebab-case)Copy Anchor Link

• Aturan: operational-mandates, clean-room-generation, context-management
• Command: plan-execute, plan-spec, plan-generate
• Helper: codebase-explorer, convention-auditor, quality-gate
• Skill: plan-suite, ecosystem-audit

Pola: huruf kecil, tanda hubung di antara kata, tanpa spasi atau garis bawah.

Penamaan BerkasCopy Anchor Link

• Aturan: {name}.md
• Command: {name}.md
• Helper: {name}.md
• Skill: Di dalam folder src/apothem/skills/{name}/SKILL.md (huruf besar-kecil persis: SKILL.md)
• Hook: Di dalam folder src/apothem/hooks/. Semua penangan peristiwa ditulis dengan Python. Setiap command hook dalam templat settings.json Claude Code menggunakan bentuk exec: command adalah placeholder interpreter ${PYTHON_BIN}, yang di-resolve saat pemasangan, dan args berisi jalur skrip beserta argumennya. Templat tersebut menjalankan ${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py <event> [<message-name>] dan ${HARNESS_ROOT}/.apothem/support/conformity/gate.py --hook dengan jalur absolut, sehingga salinan yang terpasang tidak memerlukan paket apothem yang dapat diimpor. Plugin Claude Code mendaftarkan hook di src/apothem/hooks/hooks.json sebagai gantinya, berupa command shell yang menjalankan hooks/lib/bootstrap.sh melalui bash; stub itu menemukan Python dan menjalankan dispatch.py, sehingga penangan tetap berupa Python. Daftarkan hook baru di hooks.json dan di templat settings.json Claude Code. dispatch.py merutekan SessionStart ke session_start_bootstrap.main() dan setiap peristiwa lain yang masuk daftar izin ke emit_hook_context.main(). Satu-satunya stub shell yang diizinkan di bawah src/apothem/hooks/ atau scripts/ adalah enam berkas pelokasi dan bootstrap (find-python.{ps1,sh}, find-pwsh.{ps1,sh}, bootstrap.{ps1,sh}); berkas .ps1 / .sh lain mana pun gagal dalam pemeriksaan higiene scripts/dev/validate_hooks.py.

Rujukan SilangCopy Anchor Link

Saat merujuk artefak lain, gunakan nama yang persis:

• Aturan: "operational-mandates" (nilai bidang name)
• Command: /plan-execute (dengan garis miring untuk dokumentasi bagi manusia; tanpa garis miring di dalam kode)
• Helper: codebase-explorer (nilai bidang name)
• Skill: plan-suite (nilai bidang name)

Jangan pernah menggunakan jalur berkas atau nama yang terpotong di dalam prosa.

Portabilitas: Windows vs. UnixCopy Anchor Link

Setiap command HARUS mendeklarasikan status portabilitasnya secara eksplisit dalam bidang portability. Sebuah helper BOLEH mendeklarasikannya. Skill, aturan, dan output-style tidak membawa bidang portability.

UniversalCopy Anchor Link

• Bekerja secara identik di Windows, macOS, dan Linux
• Tanpa asumsi shell
• Jalur menggunakan garis miring maju (/)
• Tanpa jalur absolut yang di-hardcode
• Tanpa sintaks PowerShell khusus Windows

portability: "universal"

Universal dengan Peringatan WindowsCopy Anchor Link

• Universal di seluruh host POSIX; peringatan yang disebutkan berlaku pada varian platform Windows yang dideklarasikan di dalam konten
• Dokumentasikan peringatan tersebut secara eksplisit di dalam konten
• Contoh: "Symlink tidak didukung di Windows sebelum Win 10"

portability: "universal-with-windows-caveats"

Dokumentasikan peringatan tersebut dalam sebuah catatan tepat setelah judul.

Khusus Unix / Khusus WindowsCopy Anchor Link

• Dibatasi secara eksplisit ke satu platform
• Jarang di Apothem — sebagian besar seharusnya universal
• Gunakan hanya jika fitur khusus platform bersifat esensial

portability: "unix-only"

Dokumentasikan alasannya di bagian pertama artefak.

Cakupan: Selalu Aktif vs. Difilter JalurCopy Anchor Link

Selalu AktifCopy Anchor Link

Aturan berlaku di mana saja. Lima aturan selalu aktif: agnostic-posture, authority-inquiry, session-closure, context-management, dan indeks aturan (apothem-rule-index). Himpunan ini kecil karena setiap aturan yang selalu aktif memakan konteks di setiap sesi.

pathFilter: ""
alwaysApply: true

Difilter JalurCopy Anchor Link

Aturan berlaku secara kondisional berdasarkan jalur berkas.

pathFilter: "**/*.py, **/*.toml"
alwaysApply: false

pathFilter menggunakan pola glob (format yang sama dengan .gitignore). Ketika sebuah berkas cocok dengan filter tersebut, aturan menjadi aktif.

Semantik VersiCopy Anchor Link

Setiap artefak berversi membawa versi semantiknya sendiri (MAJOR.MINOR.PATCH). Command dan skill mewajibkannya, helper dan output-style BOLEH membawanya, dan aturan tidak membawanya:

• PATCH — perubahan perilaku yang memperbaiki direktif yang sudah ada tanpa merusak kontrak.
• MINOR — perubahan aditif yang tidak merusak: bagian opsional baru, bidang frontmatter opsional baru, contoh baru. Konsumen yang sudah ada tetap berfungsi tanpa perubahan.
• MAJOR — perubahan skema atau kontrak yang merusak: bagian yang dihapus, bidang yang diganti namanya, perilaku direktif yang sudah ada yang diubah, perubahan yang mengharuskan artefak hilir beradaptasi.

Perbaikan salah ketik, perbaikan tautan, pemformatan, serta suntingan yang hanya menyentuh komentar atau dokumentasi tidak mengubah versi. Hanya perubahan perilaku yang menaikkannya. Suntingan semacam itu tetap memperbarui tanggal updated artefak.

Contoh:

• vX.Y.Z → vX.Y.(Z+1) (PATCH: direktif yang diperbaiki sehingga perilakunya berubah)
• vX.Y.Z → vX.Y.Z (tanpa kenaikan: perbaikan salah ketik atau tautan; updated berubah)
• vX.Y.Z → vX.(Y+1).0 (MINOR: menambahkan bagian opsional baru)
• v0.Y.Z → v(0+1).0.0 (MAJOR: kontrak dinyatakan stabil; artefak baru dimulai pada v0.Y.Z)
• vX.Y.Z → v(X+1).0.0 (MAJOR: menghapus bidang frontmatter wajib)

Naikkan version dan updated bersama-sama pada setiap suntingan yang mengubah perilaku pada artefak yang membawa keduanya. Tambahkan baris yang sesuai ke CHANGELOG.md tingkat ekosistem untuk rilis yang membundel perubahan artefak.

Revisi suite rencanaCopy Anchor Link

Aturan artefak di atas tidak berlaku untuk suite rencana. Versi suite rencana adalah nilai vX.Y.Z yang tercatat di header MASTER-PLAN.md dan tabel Revision History-nya. Perbaikan salah ketik pada suite rencana merupakan revisi yang menaikkan nomor PATCH. Langkah 10.2 dari /plan-review menetapkan klasifikasi dan menambahkan baris Revision History.

• vX.Y.Z → vX.Y.(Z+1) (suite rencana, perbaikan salah ketik: PATCH)
• vX.Y.Z → vX.Y.Z (artefak, perbaikan salah ketik: tanpa kenaikan; aturan artefak di atas)

Kapan Menyunting ArtefakCopy Anchor Link

AturanCopy Anchor Link

• Perlakukan struktur Mandatory/Optional sebagai struktur penopang — merestrukturisasinya berdampak berantai ke setiap artefak yang bergantung padanya.
• Perhalus Anti-Patterns, contoh Seriousness Scaling, dan sitasi seiring pemahaman yang makin mendalam.
• Catat alasan setiap perubahan struktural di berkas topik memori yang relevan.

CommandCopy Anchor Link

• Bentuk argumen adalah bagian dari kontrak publik — ubah secara tidak kompatibel hanya dengan niat yang eksplisit dan propagasikan perubahannya ke setiap pemanggil (kenaikan MAJOR).
• Jaga langkah alur kerja dan kontrak pengembalian tetap ringkas dan mutakhir.
• Dokumentasikan urutan langkah yang tidak jelas secara inline.

HelperCopy Anchor Link

• Jaga disallowedTools seminimal mungkin namun tetap memadai; dokumentasikan alasannya ketika daftar itu berubah.
• Perhalus Operating Principles dan Return Contracts seiring peran helper makin matang (kenaikan MINOR).
• Lacak pergeseran kapabilitas secara inline agar pemanggil dapat mengkalibrasi ulang ekspektasinya.

SkillCopy Anchor Link

• Jaga langkah Procedure dan Examples tetap selaras dengan kenyataan.
• Sinyal deteksi harus mencerminkan ungkapan pengguna yang sebenarnya dalam penggunaan saat ini.
• Pecah sebuah skill begitu panjangnya melewati ~150 baris (lihat auto-memory.md § Topic File Management).

Langkah demi Langkah: Menambahkan Aturan BaruCopy Anchor Link

1. Nilai OrtogonalitasCopy Anchor Link

Apakah aturan ini tumpang tindih dengan aturan yang sudah ada? Cari konten terkait di src/apothem/rules/.

Jika tumpang tindihnya >50%, pertimbangkan untuk memperluas aturan yang sudah ada sebagai gantinya. Lihat persistent-conventions-vigilance.md § Artifact Evolution.

2. Tulis KontenCopy Anchor Link

Ikuti struktur berikut:

• Judul: # Rule: {Title}
• Bagian Purpose
• Obligations / Core directives (bernomor, tertaut)
• Tabel Seriousness Scaling (selalu diwajibkan)
• Bagian Anti-Patterns
• Bagian Enforcement

3. Buat FrontmatterCopy Anchor Link

Gunakan skema dari site/content/docs/reference/artifact-schema.mdx § Schema: Rules. Setel:

• name: pengenal kebab-case
• description: ringkasan satu baris untuk registri
• pathFilter: daftar glob untuk aturan yang difilter jalur; string kosong ("") untuk aturan yang selalu aktif
• alwaysApply: true untuk aturan yang selalu aktif, false untuk aturan yang difilter jalur

Aturan hanya membawa keempat bidang ini — tanpa version / updated / scope / portability / implements.

Aturan baru bersifat difilter jalur. Aturan baru yang selalu aktif mengharuskan daftar inti dan batas atas byte dinaikkan dalam perubahan yang sama: daftar di tests/unit/test_always_on_core.py dan batas atas di conformity/always_on_budget_grep.py. Aturan pendamping (<parent>-<aspect>) mengambil pathFilter induknya, atau yang lebih sempit.

Contoh:

---
name: "my-new-rule"
description: "Brief one-liner"
pathFilter: "**/*.py"
alwaysApply: false
---

4. Perbarui README AturanCopy Anchor Link

Tambahkan satu baris ke tabel untuk keluarga aturan tersebut di bagian Rule families dalam src/apothem/rules/README.md:

| `my-new-rule.md` | One-line concern of the new rule. |

Pilih tabel keluarga yang bidang perhatiannya sesuai dengan aturan tersebut. Sebutkan juga aturan itu pada baris src/apothem/rules/apothem-rule-index.md untuk situasi yang memerlukannya; tests/unit/test_always_on_core.py gagal ketika sebuah aturan tidak ada di indeks.

5. Tambahkan ke CHANGELOG.mdCopy Anchor Link

Tambahkan sebuah baris di bawah bagian ### Added rilis berikutnya yang menjelaskan aturan baru tersebut.

6. Jalankan ValidasiCopy Anchor Link

Panggil skill ecosystem-audit untuk memverifikasi aturan baru, dengan fokus pada area aturan:

Invoke the ecosystem-audit skill with --focus rules --fix

Pastikan tidak ada kesalahan yang dilaporkan untuk aturan baru Anda.

Langkah demi Langkah: Menambahkan Command BaruCopy Anchor Link

Command adalah slash command seperti /plan-spec, /plan-execute, /security-audit, dan sebagainya.

1. Tentukan PeranCopy Anchor Link

Command adalah alur kerja yang dipicu oleh pengguna. Model menjalankannya sendiri hanya ketika setelan disable-model-invocation miliknya bernilai false (langkah 2). Tanyakan:

• Apakah ini alur kerja yang dijalankan pengguna dengan mengetik /command-name?
• Apakah alur kerja ini mengorkestrasi beberapa langkah?
• Mungkinkah alur kerja ini mengalami timeout atau memerlukan masukan pengguna di tengah eksekusi?

Jika jawabannya "tidak" untuk salah satu pertanyaan ini, kemungkinan besar itu adalah skill, bukan command.

2. Buat BerkasCopy Anchor Link

Jalur: src/apothem/commands/{name}.md

Frontmatter (dari site/content/docs/reference/artifact-schema.mdx § Schema: Commands):

---
name: "my-command"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this command does"
argument-hint: "[path/to/input] [--flag VALUE]"
disable-model-invocation: false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

disable-model-invocation: true membuat sebuah command hanya dapat dipanggil oleh operator; dengan false, model dapat menjalankannya ketika sebuah permintaan cocok dengan deskripsinya. Nilai bawaannya adalah false untuk command yang hanya-baca dan bersifat penasihat, dengan deskripsi yang diawali kasus penggunaannya; 35 dari 45 command menggunakannya. Sebuah command tetap true ketika command itu mengubah status di luar pohon kerja atau bergantung pada operator yang memilih saatnya (10 command). Tabel pemanggilan di src/apothem/commands/README.md mencantumkan setelan setiap command; tambahkan satu baris untuk command baru. Jaga allowed-tools tetap hanya-baca: harness yang mematuhinya menjalankan alat-alat tersebut tanpa bertanya. Berikan alat yang berefek samping hanya sebagai aturan bercakupan, seperti Bash(git log *); skema menolak "*" dan salah satu dari Bash, PowerShell, Write, Edit, NotebookEdit, atau WebFetch yang ditulis tanpa cakupan.

3. Tulis KontenCopy Anchor Link

Struktur:

• Judul: # /{name} — Human-Readable Title
• Bagian Role (siapa yang mengeksekusi ini)
• Instruksi tingkat tinggi
• Bagian Workflow dengan langkah-langkah
• Kontrak pengembalian / format keluaran

Emisi skill pada satu harness memecah setiap command menjadi SKILL.md yang ramping ditambah berkas references/ per bagian H2. Berikan command satu bagian ## Workflow, tutup setiap code fence, dan klasifikasikan setiap jenis H2 baru di src/apothem/lib/claude_skill_split.py; tests/unit/test_claude_skill_split.py gagal pada jenis yang belum diklasifikasikan. Aturannya ada di kontrak Skill-emission split dalam src/apothem/commands/README.md.

4. Perbarui README dan CHANGELOG.mdCopy Anchor Link

Tambahkan satu baris ke tabel untuk bagian command tersebut di src/apothem/commands/README.md, selain baris tabel pemanggilan dari langkah 2; tambahkan satu baris CHANGELOG di bawah bagian ### Added rilis berikutnya.

5. ValidasiCopy Anchor Link

Panggil skill ecosystem-audit, dengan fokus pada command:

Invoke the ecosystem-audit skill with --focus commands --fix

Langkah demi Langkah: Menambahkan Helper BaruCopy Anchor Link

Helper adalah definisi pekerja terdelegasi persisten untuk pekerjaan paralel.

1. Identifikasi PolaCopy Anchor Link

Apakah helper ini cocok dengan salah satu pola tim yang tercantum di bawah?

• Tim Riset: hanya-baca, pengumpulan informasi
• Tim Audit: verifikasi, pemeriksaan konsistensi
• Tim Implementasi: perubahan kode paralel
• Tim Kualitas: lint, pengujian, pemeriksaan tipe, keamanan
• Tim Dokumentasi: pembaruan dokumentasi
• Lainnya: tugas khusus

2. Buat BerkasCopy Anchor Link

Jalur:

src/apothem/agents/{name}.md

Frontmatter:

---
name: "my-helper"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this helper specializes in"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit"
maxTurns: 15
portability: "universal"
---

Hilangkan model, effort, dan permissionMode agar helper mewarisi pilihan sesi (postur agnostik), dan hilangkan memory kecuali helper memerlukan cakupan memori persisten (user, project, atau local).

3. Tulis KontenCopy Anchor Link

Bagian:

• Operating Principles (hanya-baca, berbasis bukti, putusan biner, menyeluruh)
• Workflow (langkah-langkah bernomor)
• Return Contract (token maksimum, struktur, bidang wajib)

4. Perbarui README dan CHANGELOG.mdCopy Anchor Link

Tambahkan satu baris ke tabel Index di src/apothem/agents/README.md; tambahkan satu baris CHANGELOG di bawah bagian ### Added rilis berikutnya.

5. UjiCopy Anchor Link

Jalankan helper dalam skenario nyata dan verifikasi bahwa helper bekerja seperti yang didokumentasikan.

Langkah demi Langkah: Menambahkan Skill BaruCopy Anchor Link

Skill adalah teknik yang dapat dipakai ulang dan dapat dideteksi.

1. Identifikasi Keterpakaian UlangCopy Anchor Link

Sebelum menulis skill:

• Apakah Anda telah menemui masalah/teknik ini 3 kali atau lebih?
• Apakah teknik ini dapat dideteksi? (Apakah ada pola permintaan pengguna yang menandakannya?)
• Dapatkah Anda mengodifikasinya secara dapat direproduksi?

Jika jawaban ketiganya ya, tulis sebuah skill.

2. Buat StrukturCopy Anchor Link

%%{ init: { "theme": "neutral" } }%%
%% verified: 2026-04-27 %%
%% provenance: site/content/docs/reference/artifact-schema.mdx (skill artifact schema) %%
%% cross-reference: src/apothem/skills/plan-suite/SKILL.md (canonical example) %%
flowchart TD
    accTitle: New skill directory structure
    accDescr: Top-down flowchart of the directory structure for a new skill under src/apothem/skills: a {skill-name} folder holding the required SKILL.md plus optional examples and templates subfolders.
    SKILLS["src/apothem/skills/"]
    SKILLS --> NAME["{skill-name}/"]
    NAME --> SKILLMD["SKILL.md<br/>(main definition · required)"]
    NAME --> EX["examples/<br/>(optional · example workflows)"]
    NAME --> TPL["templates/<br/>(optional · reusable templates)"]

3. Tulis SKILL.mdCopy Anchor Link

Frontmatter:

---
name: "skill-name"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
argument-hint: "[args]"               # optional; if userInvocable
---

Struktur konten:

• Purpose
• When to Use This Skill
• Prerequisites
• Step-by-Step Procedure
• Common Mistakes
• Examples

4. Perbarui README dan CHANGELOG.mdCopy Anchor Link

Tambahkan satu baris ke tabel Index dan satu baris untuk setiap berkas skill tersebut ke tabel Folder contents di src/apothem/skills/README.md; tambahkan satu baris CHANGELOG di bawah bagian ### Added rilis berikutnya.

5. ValidasiCopy Anchor Link

Panggil skill ecosystem-audit, dengan fokus pada skill:

Invoke the ecosystem-audit skill with --focus skills --fix

Daftar Periksa Validasi Sebelum CommitCopy Anchor Link

• Frontmatter lolos pemeriksaan sintaks YAML
• Semua bidang wajib ada sesuai skema
• Bidang name menggunakan kebab-case
• version (hanya kelas berversi; aturan tidak membawanya) bersifat semantik (MAJOR.MINOR.PATCH) dan telah dinaikkan jika perilaku berubah
• updated cocok dengan tanggal hari ini untuk setiap artefak yang Anda sentuh dan yang membawa bidang tersebut
• Bidang portability disetel dan valid (wajib pada command, opsional pada helper)
• CHANGELOG.md memuat perubahan dalam kategori yang sesuai di bawah bagian rilis berikutnya
• Tidak ada rujukan internal rencana (kepatuhan CM-7)
• Rujukan silang konsisten dengan artefak lain
• Artefak baru terdaftar di indeks README foldernya
• Artefak telah diuji (jika berlaku)
• Skill ecosystem-audit berjalan tanpa kesalahan
• Konten mengikuti konvensi struktural (format judul, bagian, dan sebagainya)

Merujuk Artefak LainCopy Anchor Link

Gunakan konvensi persis berikut:

Merujuk AturanCopy Anchor Link

See `src/apothem/rules/operational-mandates.md` or shorthand: the Operational Mandates rule.
In prose: ... per CM-1–10 (Operational Mandates rule) ...

Merujuk CommandCopy Anchor Link

See `/plan-execute` command. Or: Run `/plan-execute`.
In prose: The `/plan-execute` command handles phase execution.

Merujuk HelperCopy Anchor Link

Deploy the `codebase-explorer` delegated worker.
In prose: The codebase-explorer worker finds patterns.

Merujuk SkillCopy Anchor Link

Use the `plan-suite` skill.
In prose: The plan-suite skill provides the Master Plan Suite template.

Merujuk Bagian CLAUDE.mdCopy Anchor Link

See CLAUDE.md § Harness Adapter Pattern.
Or: § Plans Discipline.

Linting dan FormatCopy Anchor Link

Semua artefak menggunakan:

• Markdown: GFM (GitHub Flavored Markdown)
• YAML: sesuai YAML 1.2
• Akhir baris: LF (gaya Unix)
• Pengodean: UTF-8
• Lebar baris: Soft wrap pada 100 karakter untuk konten (tanpa hard break)

Gunakan formatter / linter Ruff untuk berkas Python. Untuk Markdown, gunakan prettier atau alat yang setara.

Pengujian dan PengukuranCopy Anchor Link

Menjalankan suiteCopy Anchor Link

python -m pytest                      # unit, integration, property, conformity, scripts
python -m pytest tests/property       # Hypothesis properties (profile loader, frontmatter, merge)

Suite ini hermetis: suite lolos ketika checkout berada di bawah $TMPDIR dan ketika python di PATH tidak memiliki prasyarat CLI, karena pengujian integrasi menjalankan interpreter yang menjalankan pytest dan mentokenisasi jalur sementara dan jalur sumber yang bersarang, dimulai dari yang terpanjang.

Cakupan pengujian per paketCopy Anchor Link

CI mengukur tiga paket dan menahan masing-masing pada batas bawahnya sendiri. Tidak satu pun dari paket tersebut digabungkan ke paket lain.

Angka tersebut adalah cakupan baris ditambah cabang, persentase yang sama yang dilaporkan coverage.py dengan branch = true; artefak metrik juga mencatat angka yang hanya menghitung pernyataan di bawah coverage_lines. Setiap batas bawah paket adalah nilai baris ditambah cabang yang terukur, dibulatkan ke bawah. Naikkan batas bawah ketika cakupan meningkat; jangan pernah menurunkannya agar sebuah perubahan lolos. Untuk memeriksa secara lokal:

python -m pytest --cov=src/apothem --cov-report=json:coverage.json
python scripts/dev/collect_metrics.py --coverage-json coverage.json --check-floors \
  --skip-hooks --skip-coldstart --harness zed

Artefak metrikCopy Anchor Link

Job metrics di CI menjalankan scripts/dev/collect_metrics.py pada setiap push dan pull request serta mengunggah metrics.json (schema_version: 1). Setiap nilai yang null membawa alasannya di bawah nulls.

Berkas mana yang dihitung sebagai dimuat saat peluncuran ditentukan oleh aturan per harness yang diambil dari permukaan instruksi terdokumentasi milik setiap vendor. Daftar yang hanya membawa deskripsi (skill, command, subagen) tidak dihitung. Teks aturan tersebut juga ditulis ke dalam artefak di bawah rules.always_on_bytes:

antigravity     ~/.gemini/{GEMINI,AGENTS}.md, ~/.gemini/config/{GEMINI,AGENTS}.md,
                ~/.gemini/config/rules/*.md with trigger: always_on, project
                GEMINI.md and AGENTS.md. The plugin rules/ folder is not a
                documented launch surface.
claude-code     ~/.claude/CLAUDE.md and ~/.claude/rules/**/*.md without paths:
                frontmatter, plus the project equivalents.
codebuddy       .codebuddy/rules/**/*.md (project and home) unless
                alwaysApply: false, plus CODEBUDDY.md.
codex           ~/.codex/AGENTS.md and the project AGENTS.md.
cursor          .cursor/rules/**/*.mdc with alwaysApply: true, and AGENTS.md.
gemini-cli      ~/.gemini/GEMINI.md and the project GEMINI.md.
github-copilot  .github/copilot-instructions.md and the project AGENTS.md.
hermes          ~/.hermes/SOUL.md, project .hermes.md, AGENTS.md, CLAUDE.md.
                The support tree and apothem/rules/ are not launch surfaces.
kimi-code       ~/.kimi-code/AGENTS.md, project AGENTS.md and .kimi-code/AGENTS.md.
kiro            .kiro/steering/**/*.md with inclusion: always or no inclusion
                key, and the project AGENTS.md.
open-claw       Workspace bootstrap files ~/.openclaw/workspace/*.md.
opencode        ~/.config/opencode/AGENTS.md, the project AGENTS.md, and every
                file the instructions globs in opencode.json match.
qwen-code       The context files named by context.fileName in
                ~/.qwen/settings.json (default QWEN.md), in ~/.qwen/ and the project.
trae            .trae/rules/**/*.md with alwaysApply: true, and
                ~/.trae/user_rules/*.md.
windsurf        .devin/rules/**/*.md and .windsurf/rules/**/*.md with
                trigger: always_on, the global global_rules.md, and AGENTS.md.
zed             The first of .rules, .cursorrules, .windsurfrules, .clinerules,
                .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md,
                GEMINI.md in the project, plus ~/.config/zed/AGENTS.md.
glm             Nothing: GLM is a model backend and loads no instruction files.

Eval perilakuCopy Anchor Link

Suite di bawah evals/ mengukur perilaku, bukan bentuk: 148 kasus pemicu (setiap command, skill, dan subagen yang dapat dipanggil model terpicu oleh permintaan dalam domainnya dan tetap diam pada permintaan yang nyaris cocok, dan enam command yang hanya dipanggil pengguna tidak berjalan dengan sendirinya), 32 kasus hasil (satu per tahap rencana, tahap riset, dan dimensi audit) dan 6 pasangan efek aturan (teks aturan sampel dalam keadaan disertakan dan tidak disertakan). Kasus-kasus tersebut adalah data biasa yang divalidasi tanpa biaya oleh python -m pytest tests/unit/test_eval_suite.py; menjalankannya dikenai biaya dan dilakukan secara manual. Lihat Menjalankan eval perilaku untuk alur kerja Evals, eksekusi lokal, dan cara menambahkan kasus. Setelah menyunting aturan yang memiliki pasangan, jalankan python scripts/dev/sync_eval_rule_cases.py.

BenchmarkCopy Anchor Link

make benchmarks menjalankan driver per kelas di bawah src/apothem/benchmarks/, kecuali bench_agents.py. Setiap driver keluar dengan 0 lolos, 1 melebihi anggaran, 2 galat (eksekusi yang diukur tidak berjalan), atau 3 tidak diukur.

• bench_hooks.py menjalankan setiap command shell: bash yang didaftarkan oleh hooks/hooks.json, sebagaimana tertulis, pada payload nyata per peristiwa dan matcher, lalu melaporkan median waktu total, command yang paling lambat (diperiksa terhadap anggaran peristiwa tersebut), dan jumlah karakter yang disuntikkan. Command yang tidak dapat berjalan sebagaimana terdaftar (exit 126 ketika sebuah skrip tidak memiliki bit eksekusinya) adalah galat, bukan lolos.
• bench_agents.py melaporkan NOT MEASURED (exit 3): spawn subagen memerlukan harness host dan pemanggilan model. make benchmarks tidak menjalankannya.

Pemeriksaan anggaran selalu aktif (always-on-budget-grep) menghitung kata yang dipisahkan spasi dengan mengecualikan bagian Bindings dan baris penunjuk pendamping. Laporan JSON-nya juga memuat always-on-loaded: jumlah byte, karakter, dan kata dari isi tanpa frontmatter yang dimuat oleh sebuah harness, dijumlahkan atas seluruh aturan selalu aktif. Ketika diarahkan ke direktori aturan yang dikirimkan, pemeriksaan ini juga gagal ketika jumlah tersebut melampaui batas atas byte (dilaporkan sebagai always-on-ceiling-bytes) atau indeks aturan melampaui batas atasnya sendiri. Claude Code memuat salinan aturannya tanpa bagian Bindings, sehingga ukuran yang dimuatnya lebih kecil daripada angka yang dilaporkan pemeriksaan ini.

Audit Ekosistem: Menjalankan ValidasiCopy Anchor Link

Dua permukaan validasi yang saling melengkapi mencakup ekosistem:

Dapat diperiksa mesin (validator Python) — jalankan sebelum setiap commit:

python scripts/dev/validate_hooks.py       # Hook structure + Python-only hygiene
python scripts/dev/validate_ecosystem.py   # Full tree + frontmatter + delegated hook checks
python scripts/dev/chaos_pass.py           # Adversarial sweep across configured hooks
pytest tests                                    # Unit tests for the hook runtime

Digerakkan asisten — untuk audit rujukan silang, naratif, dan konvensi:

/ecosystem-audit --focus all --fix

Perintah ini menjalankan hal berikut secara paralel:

• Audit struktur: Akurasi registri, keberadaan berkas, validitas frontmatter
• Audit artefak: Rujukan silang, cakupan mandat, urutan pipeline
• Audit memori: Klaim berkas memori vs. keadaan sistem berkas

Keluaran yang diharapkan: PASS dengan nol temuan dari kedua permukaan.

Jika FINDINGS dilaporkan:

• Tinjau tingkat keparahan setiap temuan (Critical / Important / Advisory)
• Tangani butir Critical segera
• Rencanakan butir Important untuk siklus berikutnya
• Pertimbangkan butir Advisory untuk iterasi berikutnya

Pertanyaan?Copy Anchor Link

Lihat:

• Skema frontmatter: site/content/docs/reference/artifact-schema.mdx
• Siklus hidup artefak: src/apothem/rules/persistent-conventions-vigilance.md § Artifact Evolution
• Mandat operasional: src/apothem/rules/operational-mandates.md CM-1–10
• Rujukan suite rencana: src/apothem/skills/plan-suite/master-template.md
• Catatan rilis: CHANGELOG.md