Cara-pakai penulisan & pipeline

Panduan langkah demi langkah berorientasi tugas untuk menulis artefak Apothem dan menjalankan pipeline rencana. Setiap panduan menjawab satu pertanyaan konkret.

Untuk resep penyiapan pertama kali — menambahkan harness, menyunting profil, menjalankan pemasang — lihat bagian Resep cara-pakai sebagai gantinya.

Pipeline suite rencanaCopy Anchor Link

Bagaimana saya memperhalus konten mentah menjadi spec?Copy Anchor Link

Panggil /plan-spec dengan konten mentah sebagai masukan. Peran Forge menjalankan enam fase transformasi (Discovery, Meticulous Consideration, Potency Mapping, Preservation Verification, Expertise Application, Question-Resolution Sweep) dan menghasilkan spec terkonsolidasi di .apothem/plans/{suite}/_spec/spec.md. Lihat src/apothem/commands/plan-spec.md untuk protokol lengkap.

Bagaimana saya membangkitkan suite rencana dari spec?Copy Anchor Link

Panggil /plan-generate .apothem/plans/{suite}/_spec/spec.md setelah /plan-spec menulis spec. Pembangkit menghasilkan berkas infrastruktur kanonis beserta berkas phases/NN-kebab-topic/PHASE.md per fase. Lihat src/apothem/commands/plan-generate.md.

Bagaimana saya meninjau rencana yang dihasilkan?Copy Anchor Link

Panggil /plan-review path/to/plan-suite/. Peninjau menerapkan sembilan teknik perencanaan dan menghasilkan kartu skor. Kartu skor yang gagal memblokir eksekusi pada SHARED+ sampai diselesaikan. Lihat src/apothem/commands/plan-review.md.

Bagaimana saya mengeksekusi rencana?Copy Anchor Link

Panggil /plan-execute path/to/plan-suite/ [phase-id]. Tanpa phase-id, fase yang tertunda berikutnya dijalankan. Dengan id tertentu, hanya fase tersebut yang dijalankan. Lihat src/apothem/commands/plan-execute.md.

Bagaimana saya memeriksa status rencana?Copy Anchor Link

Panggil /plan-status path/to/plan-suite/ [--verbose]. Laporan hanya-baca. Lihat src/apothem/commands/plan-status.md.

Menulis artefakCopy Anchor Link

Bagaimana saya menambahkan aturan baru?Copy Anchor Link

1. Pilih nama berkas kebab-case di bawah src/apothem/rules/, misalnya src/apothem/rules/my-new-rule.md.
2. Tulis frontmatter (name, description, pathFilter, alwaysApply).
3. Tulis badan dengan bagian kanonis: Purpose, Obligations, Seriousness Scaling, Anti-Patterns, Enforcement, Bindings.
4. Jalankan python scripts/dev/validate_ecosystem.py --check frontmatter-cohort untuk memverifikasi.

Pemuat aturan berbasis glob — ia mengambil setiap berkas yang cocok dengan src/apothem/rules/*.md, sehingga tidak diperlukan entri registri; menaruh berkas dengan nama kanonis ke dalam direktori itu adalah seluruh proses registrasi.

Bagaimana saya menambahkan pekerja terdelegasi baru?Copy Anchor Link

Pilih nama berkas kebab-case di bawah direktori yang ditunjukkan di bawah ini, dengan format my-worker.md:

src/apothem/agents/
src/apothem/agents/my-worker.md

Kemudian:

1. Tulis frontmatter — termasuk name, version, updated, description, tools, disallowedTools, maxTurns, dan effort.

2. Tulis system prompt sebagai badan.

Kohor pekerja terdelegasi dimuat berbasis glob dari src/apothem/agents/*.md, sehingga berkas dengan nama kanonis otomatis terbaca saat ditempatkan — tidak ada tabel registri yang perlu disunting.

Bagaimana saya menambahkan hook baru?Copy Anchor Link

1. Tulis pesan konteks di bawah src/apothem/hooks/messages/<event>-<scope>.md.
2. Pasang hook di settings.json.
3. Perbarui pipeline hook.
4. Jalankan python scripts/dev/validate_ecosystem.py.

Gerbang mutuCopy Anchor Link

Bagaimana saya menjalankan gerbang mutu lokal?Copy Anchor Link

python -m ruff check .
python -m ruff format --check .
python -m mypy
python -m pytest -q
python scripts/dev/validate_ecosystem.py
python scripts/dev/chaos_pass.py

Pipeline CI menjalankan kumpulan yang sama secara paralel.

Bagaimana saya memeriksa frontmatter satu kelas artefak?Copy Anchor Link

python scripts/dev/validate_ecosystem.py --check frontmatter-cohort