Membuat Workspace Khusus agar Hermes Bekerja Lebih Terarah

Masalahnya bukan sekadar memilih model

Ketika pertama kali menggunakan AI agent, godaan terbesarnya adalah membiarkan agent bekerja langsung di mana saja: menjalankan command, mengubah file, mengirim notifikasi, atau memanggil API eksternal.

Cara itu memang cepat untuk eksperimen. Namun, setelah workflow bertambah, saya menemukan masalah yang sama berulang kali:

context percakapan bercampur dengan business logic;
command penting hanya hidup di prompt;
hasil pekerjaan sulit diaudit;
scheduler menyimpan terlalu banyak detail implementasi;
perubahan eksternal tidak memiliki approval dan verification yang konsisten.

Karena itu saya membuat karina-workspace: sebuah repository khusus yang menjadi execution plane untuk Hermes.

Idenya sederhana: Hermes memutuskan dan berkomunikasi; workspace menjalankan operasi melalui kontrak yang dapat diperiksa.

Memisahkan otak percakapan dari execution plane

Hermes tetap menjadi interface utama. Saya menggunakannya dari Telegram dan CLI untuk memahami permintaan, menyimpan context, memilih skill, dan mengarahkan pekerjaan.

Workspace tidak menggantikan Hermes. Workspace menyediakan kemampuan yang lebih deterministik melalui satu CLI bernama kw.

Merender diagram...

Dengan boundary ini, Hermes tidak perlu mengetahui detail cara menulis transaksi, menjalankan watcher, atau mengirim delivery. Hermes cukup memanggil kemampuan yang memiliki input, output, dan lifecycle yang jelas.

Repository sebagai kontrak kerja

Struktur penting di workspace saya terlihat seperti ini:

src/kw/kernel/                    # lifecycle umum
src/kw/capabilities/<name>/       # vertical domain slices
src/kw/adapters/                  # adapter konkret
src/kw/composition.py             # wiring built-in handlers
config/jobs.toml                  # jadwal canonical
config/projects.toml              # registry project
agent/skills/<name>/SKILL.md      # router percakapan tipis
docs/                             # arsitektur dan runbook

Ada beberapa aturan yang sengaja dibuat keras:

kernel/ tidak boleh mengimpor capability atau adapter konkret.
Logic domain berada di vertical slice, bukan di CLI yang besar.
composition.py menjadi satu tempat untuk merangkai implementasi konkret.
Credential, token, chat ID, dan data runtime tidak masuk repository.
Hermes profile hanya menyimpan identity, environment, scheduler launcher, dan thin skills.

Aturan ini membuat repository mudah dipahami baik oleh manusia maupun agent. Jika saya ingin menambahkan domain baru, saya tahu lokasi capability, adapter, konfigurasi, dan test yang harus dicari.

Mengapa semua capability lewat CLI?

Saya memilih CLI karena ia memberi kontrak yang sederhana dan mudah diuji. Setiap command dapat dipanggil oleh manusia, Hermes, atau scheduler, dan hasilnya tersedia sebagai JSON.

Contoh pemeriksaan workspace:

.venv/bin/kw doctor --json
.venv/bin/kw capability list --json
.venv/bin/kw job list --json

Contoh output tidak harus dipahami sebagai prose. Program lain dapat membaca struktur hasilnya, memeriksa ok, mengambil data, dan bereaksi terhadap error secara konsisten.

Untuk operasi project, workspace juga menyediakan registry agar Hermes tidak menebak-nebak lokasi repository:

.venv/bin/kw project list --json
.venv/bin/kw project show achmadya-dev/achmadya.dev --json
.venv/bin/kw project preflight achmadya-dev/achmadya.dev --json
.venv/bin/kw project sync achmadya-dev/achmadya.dev --json

preflight memeriksa path, remote, branch, status dirty, dan divergence sebelum coding dimulai. sync hanya melakukan fetch dan fast-forward pull pada kondisi yang aman. Jika repository dirty, detached, conflict, atau diverged, command berhenti, bukan memaksa reset --hard.

External write harus memiliki lifecycle

Read-only operation relatif mudah. Bagian yang lebih berbahaya adalah mutation: membuat event, menulis transaksi, membuat issue, melakukan commit, atau push ke remote.

Untuk itu saya menggunakan lifecycle berikut:

plan payload
  → simpan payload yang frozen + hash
  → approval eksplisit
  → execute payload yang sama
  → read-back verification
  → simpan result dan status

Contoh sederhananya:

.venv/bin/kw finance transaction plan \
  --date 2026-08-04 \
  --description "Contoh transaksi" \
  --amount 25000 \
  --cashflow Pengeluaran \
  --account Cash \
  --json

.venv/bin/kw action approve ACTION_ID --actor madya --json
.venv/bin/kw action execute ACTION_ID --json
.venv/bin/kw action show ACTION_ID --json

Hal pentingnya bukan nama command tersebut, tetapi sifat payload-nya: setelah disetujui, payload tidak dibangun ulang dari context percakapan. Yang dieksekusi adalah payload yang sama dengan yang telah disetujui.

API acknowledgement juga belum cukup sebagai bukti. Jika resource dapat dibaca kembali, adapter melakukan verification melalui read-back. Dengan begitu, status success berarti lebih dari sekadar “request berhasil dikirim”.

Scheduler hanya memicu job

Sebelumnya mudah untuk membuat banyak cron entry yang masing-masing berisi business logic. Saya menggantinya dengan satu scheduler generik Hermes yang membaca manifest job dari workspace.

Hermes scheduler
      → kw job run <job-id> --json
      → JobRuntime
      → handler capability
      → persisted run result

Jadwal canonical berada di config/jobs.toml, sedangkan handler nyata didaftarkan di composition root. Scheduler tidak perlu tahu cara watcher mengambil data atau bagaimana hasilnya diproses.

Beberapa job yang berjalan melalui pola ini antara lain watcher employment, freelance, investing, finance import, dan server health. Command manualnya tetap sama dengan jalur scheduler:

.venv/bin/kw job run employment.watch --json
.venv/bin/kw job latest employment.watch --json

Dengan pola ini, saya dapat menguji job di luar Hermes dan memeriksa hasil terakhir tanpa membuka transcript percakapan.

Producer tidak mengirim Telegram langsung

Notifikasi juga dipisahkan menjadi dua fase:

watcher
  → evaluate
  → enqueue_once ke durable outbox
  → delivery drain
  → Telegram

Producer hanya memasukkan delivery ke outbox dengan idempotency key. Job delivery kemudian melakukan formatting, retry, dan dead-letter handling.

Pemisahan ini menyelesaikan beberapa masalah praktis:

watcher tidak gagal total hanya karena Telegram sedang bermasalah;
pesan yang sama tidak dikirim berulang kali secara tidak sengaja;
delivery yang gagal dapat di-retry secara eksplisit;
hasil watcher dan hasil pengiriman dapat diaudit terpisah.

Untuk menjaga privasi, route Telegram dan credential berada di private overlay yang di-ignore Git. Repository hanya menyimpan schema dan nama route, bukan nilai rahasianya.

Skills dibuat tipis dan dimiliki repository

Saya tidak menaruh semua logic di skill Hermes. Skill berfungsi sebagai router percakapan: menjelaskan kapan memakai capability tertentu, command apa yang relevan, dan constraint apa yang harus dipatuhi.

Implementasi tetap berada di src/kw/. Ini penting karena skill bukan boundary keamanan dan bukan pengganti test. Skill dapat membantu Hermes memilih command, tetapi command tersebut tetap melakukan validasi dan enforcement di sisi workspace.

Profile Hermes memuat agent/skills/ sebagai external directory. Artinya skill dapat direview, dites, dan di-version-control bersama kode workspace. Saya menghindari duplicate skill di profile-local karena duplicate dapat mengambil precedence dan membuat behavior sulit dilacak.

Apa yang saya dapatkan

Membuat workspace khusus tidak membuat agent otomatis pintar. Yang berubah adalah bentuk masalahnya menjadi lebih terkelola:

keputusan percakapan dipisahkan dari eksekusi;
command memiliki kontrak JSON yang dapat diuji;
operasi berisiko memiliki approval dan verification;
scheduler hanya memicu job canonical;
notifikasi memiliki outbox dan retry;
project coding memiliki registry dan preflight;
skill menjadi dokumentasi operasional yang tipis, bukan tempat business logic tersembunyi.

Bagi saya, ini adalah cara praktis mengubah Hermes dari chatbot yang bisa menjalankan tool menjadi sistem kerja yang punya boundary, state, dan bukti.

Workspace tersebut masih terus berkembang. Namun prinsip utamanya tetap sama: agent boleh fleksibel dalam memahami tujuan, tetapi eksekusi harus memiliki kontrak yang deterministik dan dapat diverifikasi.

Cari sesuatu