Spesifikasi Skema Artefak

Templat frontmatter YAML per-kelas dan field wajib untuk semua artefak ekosistem Apothem.

Sumber kebenaran. Kontrak yang terbaca mesin dan ditegakkan gerbang adalah JSON Schema per-kelas di bawah src/apothem/schemas/ (agent.schema.json, command.schema.json, skill.schema.json, …). Skema skill dan command mendeklarasikan additionalProperties: false, sehingga menolak kunci yang tidak dikenal; skema agent, output-style, dan plan mendeklarasikan additionalProperties: true. Halaman ini dan frontmatter-schema.mdx adalah dua proyeksi yang dapat dibaca manusia dari skema-skema tersebut — halaman ini memuat templat dan contoh lengkap per-kelas, sedangkan frontmatter-schema memuat indeks kunci wajib yang ringkas. Jika sebuah halaman tidak sesuai dengan JSON Schema, skema yang berlaku.

IkhtisarCopy Anchor Link

Semua artefak di pohon sumber Apothem (di bawah src/apothem/ dan permukaan konfigurasi root) harus menyertakan blok frontmatter YAML (di antara pembatas ---) dengan field wajib dan opsional yang spesifik untuk tipe artefaknya. Dokumen ini mendefinisikan skema kanonik untuk setiap tipe.

Aturan Universal:

• Frontmatter mematuhi YAML 1.2
• Semua nilai string menggunakan tanda kutip ganda, dan string kosong ditulis ""
• Urutan field: field wajib lebih dulu, field opsional dikelompokkan menurut relevansi
• Komentar dalam frontmatter menggunakan # dengan spasi: # comment
• Nilai jalur harus relatif (tanpa / di awal) dan menggunakan garis miring maju (/) untuk kompatibilitas lintas platform

Konvensi Versioning (kelas artefak berversi — command, pembantu, skill, CLAUDE.md):

• version bersifat semantik (MAJOR.MINOR.PATCH). Naikkan MAJOR untuk perubahan skema atau kontrak yang tidak kompatibel; MINOR untuk perubahan aditif yang tidak merusak (field opsional baru, bagian tambahan, anti-pola tambahan); PATCH untuk perubahan perilaku yang memperbaiki direktif yang sudah ada tanpa merusak kontrak.
• Perbaikan salah ketik, perbaikan tautan, pemformatan, serta suntingan yang hanya menyentuh komentar atau dokumentasi tidak mengubah version. Hanya perubahan perilaku yang menaikkannya.
• updated adalah tanggal ISO 8601 (YYYY-MM-DD) dari suntingan terbaru. Nilainya harus berubah pada setiap kenaikan version, dan juga berubah pada perbaikan salah ketik atau tautan yang tidak menaikkan versi.
• Artefak baru dimulai pada v0.Y.Z. Promosi ke vX.Y.Z menandakan bahwa kontrak artefak cukup stabil untuk menjadi komitmen publik.
• Suite rencana berada di luar konvensi ini. Perbaikan salah ketik pada suite rencana menaikkan nomor PATCH dari versi suite (vX.Y.Z menjadi vX.Y.(Z+1)) dan menambahkan baris Revision History. Panduan pengembang menjelaskan aturan suite rencana pada bagian revisi suite rencana.

Skema: AturanCopy Anchor Link

Pola jalur: src/apothem/rules/*.md

Tujuan: Mandat perilaku dan direktif operasional.

Field WajibCopy Anchor Link

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

Field OpsionalCopy Anchor Link

Aturan tidak membawa field frontmatter opsional, dan — tidak seperti kelas artefak lainnya — juga tidak membawa field version / updated / scope / portability. Empat field wajib di atas adalah kontrak frontmatter aturan yang lengkap, yang ditegakkan oleh frontmatter_grep.

ContohCopy Anchor Link

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

Skema: CommandCopy Anchor Link

Pola jalur: src/apothem/commands/*.md

Tujuan: Definisi slash command (/plan-execute, /freshify, dsb.).

Field WajibCopy Anchor Link

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

Field OpsionalCopy Anchor Link

Command tidak membawa field frontmatter opsional — delapan field wajib di atas adalah kontrak frontmatter command yang lengkap, yang ditegakkan oleh command.schema.json (additionalProperties: false).

ContohCopy Anchor Link

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

# /plan-execute — Execute a Specific Phase
...

Skema: PembantuCopy Anchor Link

Pola jalur:

src/apothem/agents/*.md

Tujuan: Definisi pembantu persisten (disebut juga pekerja terdelegasi) untuk eksplorasi paralel, audit, dan gerbang kualitas.

Field WajibCopy Anchor Link

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

Field OpsionalCopy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

ContohCopy Anchor Link

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
portability: "universal"
---

You are a codebase exploration specialist...

Skema: SkillCopy Anchor Link

Pola jalur: src/apothem/skills/*/SKILL.md

Tujuan: Definisi teknik yang dapat digunakan ulang, dengan sinyal deteksi dan prosedur eksekusi.

Field WajibCopy Anchor Link

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
---

Field OpsionalCopy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

ContohCopy Anchor Link

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

Skema: HookCopy Anchor Link

Pola jalur: blok hooks pada settings.json ditambah implementasi Python di bawah src/apothem/hooks/.

Tujuan: Mendeklarasikan validator yang dipicu peristiwa dan handler manajemen status yang dipanggil host pada titik siklus hidup yang terdefinisi dengan jelas.

Skema Berkas PengaturanCopy Anchor Link

Kunci tingkat atas hooks memetakan nama peristiwa ke array blok matcher:

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

Bentuk -m apothem.hooks.dispatch diperuntukkan bagi pengembangan dari checkout sumber dengan PYTHONPATH=src.

Peristiwa WajibCopy Anchor Link

Templat Claude Code mendaftarkan empat peristiwa: SessionStart, PreToolUse, PostToolUse, dan Stop. scripts/dev/validate_hooks.py memeriksa settings.json untuk lima peristiwa pada tabel di bawah, yang merupakan kumpulan yang berbeda, dan melaporkan setiap peristiwa yang tidak ditemukannya sebagai peringatan, bukan kegagalan. PostToolUse terdaftar tetapi bukan salah satu dari kelima peristiwa itu. PreCompact dan PostCompact termasuk di antara kelima peristiwa itu tetapi tidak didaftarkan pada Claude Code (referensi hook), sehingga pemeriksa memberi peringatan untuk keduanya di sana.

Nilai timeout mencerminkan anggaran peristiwa hook kanonik — tabel di bawah mereproduksinya demi kemudahan pembaca; sumber kanonik yang berlaku.

dispatch.py juga menerima UserPromptSubmit dan Notification dalam daftar izin peristiwanya demi kompatibilitas ke depan; tidak satu pun dari keduanya terhubung di templat yang dikirimkan. Tambahkan blok matcher dengan pola bentuk-exec yang sama untuk mengaktifkannya.

Lapisan PythonCopy Anchor Link

Setiap perintah hook dirutekan melalui dispatcher Python yang sama:

ValidasiCopy Anchor Link

scripts/dev/validate_hooks.py menegakkan kontrak hook:

• settings.json dapat diurai sebagai JSON dan mendeklarasikan masing-masing dari lima peristiwa pada tabel; peristiwa yang hilang adalah peringatan, bukan kegagalan.
• Ketiga skrip Python ada dan dapat diurai sebagai Python yang valid.
• Semua berkas pesan yang dirujuk oleh argumen --context-file ada.
• Tidak ada jalur pengguna absolut yang di-hardcode (C:\Users\... dsb.) yang muncul di src/apothem/hooks/**.py.
• Artefak shell di bawah src/apothem/hooks/ dan scripts/ dibatasi pada stub locator / bootstrap yang disetujui.

Skema: CLAUDE.mdCopy Anchor Link

Jalur: CLAUDE.md (root)

Tujuan: Instruksi Claude Code yang berlingkup proyek.

Frontmatter YAML WajibCopy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

BagianCopy Anchor Link

CLAUDE.md ditulis dalam bagian-bagian prosa, yang dijelaskan di CLAUDE.md. Tidak ada validator yang mewajibkan daftar bagian yang tetap: scripts/dev/validate_ecosystem.py memeriksa kunci frontmatter di atas.

Daftar Periksa ValidasiCopy Anchor Link

Setiap artefak harus memenuhi pemeriksaan berikut:

Validasi FrontmatterCopy Anchor Link

• YAML valid secara sintaksis (tanpa galat penguraian)
• Semua field wajib untuk tipe artefak tersebut ada
• name mengikuti konvensi kebab-case
• version bersifat semantik (MAJOR.MINOR.PATCH)
• updated berformat tanggal ISO 8601 (YYYY-MM-DD)
• description berupa string yang tidak kosong dan terdiri dari satu baris
• Field opsional cocok dengan nilai enum yang diharapkan (jika berlaku)
• Tidak ada salah ketik pada nama field (gunakan nama kanonik dari skema)
• Tidak ada spasi berlebih atau masalah format

Validasi KontenCopy Anchor Link

• Konten dimulai pada baris baru setelah --- penutup; pada berkas keluarga Markdown, baris header SPDX kanonik adalah konten pertama setelahnya
• Tidak ada rujukan internal rencana (kepatuhan CM-7)
• Rujukan silang dapat di-resolve (jika mencantumkan artefak lain)
• Tautan menggunakan jalur relatif dengan garis miring maju

Validasi PortabilitasCopy Anchor Link

• Tidak ada jalur absolut yang di-hardcode (gunakan jalur relatif)
• Tidak ada sintaks khusus Windows dalam artefak berlingkup universal
• Pemisah jalur menggunakan garis miring maju
• Variabel lingkungan menggunakan format yang tidak bergantung pada platform (${VAR} atau format native tool)

CatatanCopy Anchor Link

• Konsistensi sebagai Keamanan: Frontmatter kanonik memungkinkan validasi otomatis, perkakas, dan verifikasi lintas artefak. Penyimpangan cepat menumpuk.
• Deklarasi Portabilitas: Tidak semua artefak dapat bersifat universal. Deklarasikan batasan secara eksplisit — lebih baik mendokumentasikan sebuah catatan peringatan daripada mengirimkan bug yang senyap.
• Kebab-case untuk Nama: Mudah digunakan dalam URL, skrip, dan konteks baris perintah. Hindari spasi, garis bawah, dan camelCase untuk nama.
• Higiene Kenaikan Versi: Setiap suntingan yang mengubah perilaku harus menaikkan version dan updated bersamaan. Perbaikan salah ketik, perbaikan tautan, dan perubahan format tidak mengubah versi; bagian opsional atau anti-pola baru menaikkan MINOR; reorganisasi struktural atau perubahan kontrak menaikkan MAJOR.