speexor 0.1.0

package/docs/PRD02.md

@@ -0,0 +1,299 @@
+# PRD: Agent Orchestrator — "Speexor" v2
+
+**Codename:** Speexor — Autonomous Recursive Agent Fleet
+**Versi:** 2.0 — Pengembangan dari v1
+**Penulis:** Aditya (dengan bantuan Claude)
+**Tanggal:** 30 Juni 2026
+**Status:** Draft
+
+> Dokumen ini adalah evolusi dari PRD v1 (`PRD-Agent-Orchestrator.md`). Semua bagian dari v1 (plugin architecture 7 slot, GitHub-first tracker/SCM, CLI dasar, tech stack) **tetap berlaku sebagai fondasi**. PRD ini menambahkan layer baru di atasnya: **Recursive Autonomous Task Decomposition** dan **Realtime Observability Dashboard**, yang menjadi pembeda utama dibanding AO maupun v1 sebelumnya.
+
+---
+
+## 1. Apa yang Berubah dari v1
+
+| Aspek          | v1                                    | v2                                                                                                                               |
+| -------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Unit kerja     | 1 task = 1 agent = 1 PR               | 1 task = pohon task (task → subtask → subtask...) dikerjakan banyak agent/subagent paralel                                       |
+| Pembuatan task | Manual dari issue tracker             | Agent **otomatis memecah** task jadi subtask, dan **membuat task baru** dari hasil kerja subagent (emergent task)                |
+| Hierarki agent | Flat (orchestrator → worker)          | Berjenjang: Orchestrator → Agent → Subagent → (Sub-subagent jika perlu)                                                          |
+| Visibilitas    | Dashboard status PR/CI                | Dashboard real-time: task tree, agent/subagent yang hidup, skill yang dipakai, command/library/tool yang dieksekusi — semua live |
+| Filosofi       | Otomatisasi feedback loop (CI/review) | Otomatisasi penuh dari **planning** sampai **eksekusi paralel** sampai **self-expanding task graph**                             |
+
+Inti dari v2: kamu kasih **1 task tingkat tinggi** ("bangun fitur leaderboard"), sistem akan:
+
+1. Memecahnya jadi task graph (bukan list linear — graph karena ada dependency antar subtask).
+2. Spawn agent per subtask yang independen, paralel.
+3. Setiap agent bisa spawn subagent lagi kalau subtask-nya masih terlalu besar (rekursif, dengan depth limit).
+4. Dari hasil kerja subagent, sistem bisa **membuat task baru** secara otonom (mis. subagent nemu bug saat implementasi → otomatis jadi task baru "fix bug X", atau nemu kebutuhan refactor → task baru "refactor module Y").
+5. Semua ini terlihat real-time di dashboard: task tree yang hidup, agent yang sedang jalan, skill yang dipakai, command yang dieksekusi.
+
+---
+
+## 2. Problem Statement (Tambahan dari v1)
+
+v1 menyelesaikan masalah "1 agent per terminal tidak scalable". Tapi v1 masih mengasumsikan **kamu yang memecah task jadi issue-issue kecil secara manual** sebelum dikasih ke orchestrator. Masalah baru yang muncul setelah v1 berjalan:
+
+1. **Decomposition masih manual** — kamu tetap harus berpikir "task ini perlu dipecah jadi apa" sebelum CLI/dashboard bisa jalan.
+2. **Task statis** — begitu task selesai didefinisikan, tidak ada mekanisme untuk task baru muncul otomatis dari temuan di lapangan (bug, edge case, missing dependency).
+3. **Tidak ada visibilitas proses berpikir agent** — kamu cuma lihat hasil akhir (PR, status CI), tidak lihat agent sedang pakai skill apa, command apa, library apa saat itu juga.
+4. **Subagent invisible** — kalau satu agent men-spawn subagent untuk bagian kerjanya, kamu tidak punya cara melihat struktur hierarki itu di v1.
+
+v2 menjawab semua ini dengan **Recursive Task Decomposition Engine** + **Realtime Observability Layer**.
+
+---
+
+## 3. Tujuan Produk v2 (Goals)
+
+| #   | Goal                                                 | Metrik Keberhasilan                                                                                                                 |
+| --- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| G1  | Decompose 1 high-level task jadi task graph otomatis | Dari 1 task input, sistem hasilkan ≥80% subtask yang valid (executable, scoped jelas) tanpa intervensi manual                       |
+| G2  | Spawn agent/subagent paralel sesuai task graph       | N subtask independen dieksekusi simultan tanpa race condition antar worktree                                                        |
+| G3  | Self-expanding task graph dari hasil kerja subagent  | Subagent dapat mengusulkan/membuat task baru (bug, refactor, follow-up) yang otomatis masuk graph dan divalidasi sebelum dieksekusi |
+| G4  | Observability real-time penuh                        | Dashboard menampilkan task tree, status agent/subagent, skill aktif, command/library yang dieksekusi — update < 1 detik delay       |
+| G5  | Kontrol kedalaman rekursi & biaya                    | Depth limit & budget limit per task graph agar tidak runaway spawn agent                                                            |
+| G6  | Tetap kompatibel dengan fondasi v1                   | Plugin architecture, GitHub-first tracker/SCM, multi-provider routing tetap dipakai sebagai infrastruktur eksekusi                  |
+
+### Non-Goals v2
+
+- Tidak membangun model AI planner sendiri — decomposition tetap menggunakan LLM agent (lewat provider yang sudah dikonfigurasi), bukan algoritma planning kustom dari nol.
+- Tidak full otomatis merge tanpa review manusia (tetap sejalan filosofi v1: auto-merge default `false`).
+- Tidak menyediakan UI drag-and-drop untuk edit task graph manual di v2 — fokus dulu ke automation, manual override task graph masuk v2.5/v3 (lihat Roadmap).
+
+---
+
+## 4. Konsep Inti: Task Graph & Hierarki Agent
+
+### 4.1 Task Graph (bukan task list)
+
+Task direpresentasikan sebagai **DAG (Directed Acyclic Graph)**, bukan list linear, karena subtask bisa punya dependency (subtask B butuh hasil subtask A).
+
+```
+Task Node:
+- id
+- title
+- description
+- status: pending | decomposing | ready | in_progress | blocked | review | done | failed
+- parentId (null jika root task)
+- depth (0 = root)
+- dependsOn: [taskId]
+- createdBy: "user" | "agent:<agentId>" | "subagent:<subagentId>"
+- assignedAgent: agentId | null
+- worktree: path | null
+- skillsUsed: [skillName]
+- commandsExecuted: [{ command, timestamp, exitCode }]
+- result: { summary, prUrl?, filesChanged?, newTasksProposed: [taskId] }
+```
+
+### 4.2 Hierarki Eksekusi
+
+```
+Orchestrator Agent (root, 1 per task graph)
+ ├── Agent A (subtask 1)
+ │     ├── Subagent A.1 (sub-subtask, jika subtask 1 masih terlalu besar)
+ │     └── Subagent A.2
+ ├── Agent B (subtask 2, paralel dengan A)
+ └── Agent C (subtask 3, depends on subtask 1 → mulai setelah A done)
+```
+
+- **Depth limit default: 3** (Orchestrator → Agent → Subagent → Sub-subagent), dikonfigurasi di YAML.
+- Setiap level punya **worktree sendiri** (mengikuti workspace plugin dari v1), tapi subagent dari agent yang sama **berbagi branch parent** (commit ke sub-branch yang nanti di-merge ke branch agent induk sebelum agent induk buka PR ke base branch).
+
+### 4.3 Siklus Hidup Task (Decompose → Execute → Emit)
+
+1. **Decompose**: Orchestrator menerima task root, panggil LLM dengan prompt khusus "decomposition skill" untuk memecah jadi subtask graph dengan dependency.
+2. **Validate**: Setiap subtask hasil decompose dicek scoped-nya (tidak terlalu besar/kecil) — kalau masih besar, ditandai `decomposing` lagi secara rekursif sampai depth limit atau dianggap "atomic enough".
+3. **Execute**: Subtask yang `ready` (semua dependency `done`) di-spawn jadi agent/subagent.
+4. **Emit**: Saat agent menyelesaikan kerja, hasilnya dianalisis — kalau ada temuan baru (bug, kebutuhan refactor, missing test), agent **mengusulkan task baru** lewat skill "task-proposal". Task baru ini masuk graph dengan status `pending_approval` (lihat Governance di §5.3) sebelum dieksekusi.
+5. **Repeat** sampai semua node graph berstatus `done`/`failed`, lalu orchestrator menyusun summary akhir + daftar PR untuk direview kamu.
+
+---
+
+## 5. Functional Requirements Baru (di atas v1)
+
+### 5.1 Recursive Decomposition Engine
+
+- FR-21: `speexor task submit "<deskripsi task>"` — entry point user untuk memberi 1 task tingkat tinggi.
+- FR-22: Engine memanggil **Planner Agent** (role khusus, bisa pakai provider berbeda dari worker — mis. model reasoning kuat untuk planning, model lebih murah untuk eksekusi rutin) untuk menghasilkan task graph awal.
+- FR-23: Setiap subtask dievaluasi otomatis: jika estimasi scope > threshold (dikonfigurasi, mis. "lebih dari 1 file inti" atau "butuh >1 konsep berbeda"), subtask di-decompose lagi secara rekursif.
+- FR-24: Depth limit & **max total node per graph** dikonfigurasi di `speexor.config.yaml` (default: depth 3, max 50 node) untuk mencegah explosion.
+- FR-25: Decomposition menghasilkan dependency edge (`dependsOn`) berdasarkan analisis konten (mis. "subtask schema DB" harus selesai sebelum "subtask API endpoint").
+
+### 5.2 Parallel Execution Engine
+
+- FR-26: Scheduler menjalankan semua node yang `ready` (dependency terpenuhi) secara paralel, dibatasi `maxConcurrentAgents` per project (resource control, relevan untuk constraint mesin lokal kamu).
+- FR-27: Setiap agent/subagent berjalan di worktree terisolasi; subagent dari agent yang sama bekerja di sub-branch dari branch agent induk.
+- FR-28: Agent induk melakukan merge sub-branch subagent miliknya sendiri sebelum lanjut/PR (konflik ditangani agent induk dulu, baru eskalasi ke orchestrator/manusia jika gagal).
+- FR-29: Jika satu node `failed`, node yang depend padanya otomatis `blocked` dan orchestrator memberi opsi: retry, reassign ke agent lain, atau eskalasi ke user.
+
+### 5.3 Self-Expanding Task Graph & Governance
+
+- FR-30: Setiap agent punya skill "propose-task" yang dipanggil saat menemukan kerja baru di luar scope subtask-nya (bug, technical debt, missing edge case).
+- FR-31: Task yang diusulkan otomatis masuk graph dengan status `pending_approval`.
+- FR-32: **Governance rule** dikonfigurasi per project: `autoApproveProposedTasks: false` (default) — task baru menunggu approval kamu di dashboard sebelum dieksekusi; bisa di-set `true` untuk kategori low-risk (mis. "test-only" atau "lint-fix") agar langsung jalan.
+- FR-33: Setiap task yang diusulkan menyertakan `proposedBy` (agent/subagent id) dan `reason` (alasan kenapa task ini perlu) untuk transparansi.
+- FR-34: Loop protection: task baru tidak boleh membuat task duplikat/identik (deduplication check berbasis similarity sebelum masuk graph).
+
+### 5.4 Realtime Observability Dashboard
+
+Ini adalah perluasan besar dari Dashboard MVP di v1 (§8.6 v1), dengan requirement baru:
+
+- FR-35: **Task Tree View** — visualisasi graph (bukan list) yang menunjukkan root task, semua subtask, dependency, dan status warna (pending/in_progress/blocked/done/failed) — update via WebSocket real-time.
+- FR-36: **Agent Fleet View** — daftar semua agent & subagent yang sedang hidup, dengan hierarki parent-child, masing-masing menunjukkan: task yang dikerjakan, runtime/uptime, provider/model yang dipakai.
+- FR-37: **Live Activity Feed per Agent** — stream real-time yang menunjukkan:
+  - Skill yang sedang dipanggil agent saat itu (mis. "menggunakan skill: code-review", "menggunakan skill: test-writer").
+  - Command yang dieksekusi (shell command, git command, test runner) beserta exit code.
+  - Library/dependency yang baru ditambahkan/diubah agent (parse dari diff `package.json`, `requirements.txt`, dll secara live).
+  - Tool/plugin MCP yang dipanggil agent (jika agent backend mendukung MCP, log tool call-nya).
+- FR-38: **Drill-down**: klik 1 node task → lihat agent yang menanganinya, subagent di bawahnya, log lengkap, dan diff kode yang dihasilkan sejauh ini.
+- FR-39: **Pending Approval Inbox** — panel khusus untuk task yang diusulkan otomatis (FR-31), dengan tombol approve/reject langsung dari dashboard.
+- FR-40: **Cost & Resource Panel** (lanjutan dari v1 §8.6 FR-23) — breakdown cost per task node, bukan cuma per project, supaya kelihatan subtask mana yang paling mahal.
+- FR-41: Update real-time via WebSocket dengan target latency < 1 detik dari event terjadi di agent sampai muncul di dashboard.
+
+### 5.5 Event & Telemetry Schema
+
+- FR-42: Setiap agent wajib emit event terstruktur ke message bus internal (bukan cuma raw stdout), dengan skema minimal:
+
+```json
+{
+  "eventType": "skill_invoked | command_executed | file_changed | task_proposed | status_changed",
+  "agentId": "string",
+  "taskId": "string",
+  "timestamp": "ISO8601",
+  "payload": { "...sesuai eventType" }
+}
+```
+
+- FR-43: Event bus internal (mis. via in-process EventEmitter + persist ke SQLite untuk history) menjadi single source of truth yang dikonsumsi dashboard via WebSocket gateway.
+- FR-44: Adapter agent (OpenCode/Claude Code/Aider/Codex) wajib di-instrument untuk emit event ini — kalau agent backend tidak punya hook native, gunakan **command wrapper** (intercept shell command & file write agent lewat proxy/wrapper proses) sebagai fallback agar tetap observable.
+
+---
+
+## 6. Arsitektur Tambahan (di atas 7 Plugin Slot v1)
+
+| Komponen Baru               | Tanggung Jawab                                                                                      |
+| --------------------------- | --------------------------------------------------------------------------------------------------- |
+| **Planner Engine**          | Memanggil Planner Agent, decompose task jadi graph, validasi scope, deteksi dependency              |
+| **Task Graph Store**        | Persist task graph (SQLite/Prisma), termasuk history perubahan status & versi graph                 |
+| **Scheduler**               | Menentukan node mana yang `ready`, alokasi agent sesuai `maxConcurrentAgents`, retry/reassign logic |
+| **Governance Engine**       | Approval flow untuk task yang diusulkan otomatis, dedup check, risk classification                  |
+| **Event Bus**               | Central pub-sub untuk semua event agent/subagent, dikonsumsi dashboard real-time                    |
+| **Instrumentation Wrapper** | Lapisan intercept command/file-write agent untuk agent backend yang tidak native emit event         |
+
+Struktur monorepo bertambah:
+
+```
+packages/
+├── core/                  # (v1) lifecycle, plugin contracts
+├── planner-engine/        # (v2) decomposition logic, prompt templates
+├── task-graph/            # (v2) graph data model + persistence
+├── scheduler/             # (v2) parallel execution scheduler
+├── governance/            # (v2) approval flow, dedup, risk rules
+├── event-bus/             # (v2) pub-sub + persistence
+├── instrumentation/        # (v2) command/file wrapper untuk observability
+├── dashboard-api/          # (v1, diperluas) WebSocket gateway untuk task tree & live feed
+├── dashboard-web/          # (v1, diperluas) Task Tree View, Agent Fleet View, dst
+└── agent-*/                # (v1) adapter per agent backend
+```
+
+---
+
+## 7. Konfigurasi Baru (`speexor.config.yaml` v2)
+
+```yaml
+$schema: https://.../config.schema.v2.json
+decomposition:
+  maxDepth: 3
+  maxNodesPerGraph: 50
+  plannerProvider: opencode # provider khusus untuk planning, bisa beda dari eksekusi
+  plannerModel: deepseek-reasoner
+
+scheduler:
+  maxConcurrentAgents: 4 # per project, sesuaikan resource mesin lokal
+  retryOnFailure: 2
+
+governance:
+  autoApproveProposedTasks: false
+  autoApproveCategories: ["lint-fix", "test-only"]
+  duplicateSimilarityThreshold: 0.85
+
+observability:
+  eventRetentionDays: 30
+  liveFeedBufferSize: 200 # jumlah event terakhir yang ditahan per agent di memory
+
+projects:
+  brainclash:
+    repo: aditya/brainclash
+    path: ~/projects/brainclash
+    agentDefaults:
+      planner: claude-code
+      worker: opencode
+```
+
+---
+
+## 8. Non-Functional Requirements Tambahan
+
+| Kategori                  | Requirement                                                                                                                               |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **Latency Observability** | Event dari agent ke dashboard ≤ 1 detik (FR-41)                                                                                           |
+| **Skalabilitas Graph**    | Sistem tetap responsif dengan graph hingga 50 node aktif (sesuai `maxNodesPerGraph` default)                                              |
+| **Keamanan Governance**   | Task yang diusulkan agent tidak pernah auto-execute kalau kategori tidak ada di `autoApproveCategories`                                   |
+| **Auditability**          | Semua keputusan otomatis (decompose, approve, reject, merge) tercatat dengan alasan (`reason` field), bisa ditelusuri lewat dashboard/log |
+| **Idempotency**           | Re-run task graph yang sama tidak menghasilkan task duplikat (dedup check FR-34)                                                          |
+| **Cost Guard**            | Budget limit per task graph (opsional), agar runaway recursive decomposition tidak membengkakkan biaya API                                |
+
+---
+
+## 9. Roadmap v2 (Lanjutan dari Roadmap v1)
+
+> Asumsi: M0–M3 dari v1 (Foundation, Single Agent E2E, GitHub Integration, Multi-Agent Adapter) **sudah selesai/berjalan** sebagai prasyarat sebelum mulai roadmap v2 ini.
+
+| Fase                                        | Scope                                                                                                                                      | Estimasi   |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| **M7 — Task Graph Core**                    | Data model Task Graph, persistence, status lifecycle, dependency resolution (tanpa decomposition otomatis dulu — graph manual via API/CLI) | 2 minggu   |
+| **M8 — Planner Engine**                     | Recursive decomposition otomatis dari 1 task root, validasi scope, depth limit                                                             | 2-3 minggu |
+| **M9 — Parallel Scheduler**                 | Eksekusi paralel node `ready`, isolasi worktree/sub-branch, retry/reassign logic                                                           | 2 minggu   |
+| **M10 — Self-Expanding Graph & Governance** | Skill "propose-task", approval flow, dedup check                                                                                           | 1-2 minggu |
+| **M11 — Event Bus & Instrumentation**       | Event schema, pub-sub, instrumentation wrapper untuk agent backend tanpa native hook                                                       | 2 minggu   |
+| **M12 — Realtime Dashboard v2**             | Task Tree View, Agent Fleet View, Live Activity Feed, Pending Approval Inbox, Cost-per-node panel                                          | 3 minggu   |
+| **M13 — Hardening & Cost Guard**            | Budget limit, loop protection testing, chaos test (banyak agent gagal bersamaan)                                                           | 1-2 minggu |
+
+Total tambahan estimasi: **~13-17 minggu** setelah fondasi v1 selesai.
+
+---
+
+## 10. Risiko Baru & Mitigasi (Khusus v2)
+
+| Risiko                                                                         | Dampak | Mitigasi                                                                                                                     |
+| ------------------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Recursive decomposition runaway** — task terus dipecah tanpa henti           | Tinggi | `maxDepth` & `maxNodesPerGraph` hard limit, scope validator sebelum decompose lagi                                           |
+| **Task graph membuat task duplikat berulang**                                  | Sedang | Dedup similarity check (FR-34) sebelum task baru masuk graph                                                                 |
+| **Subagent konflik merge ke branch agent induk**                               | Sedang | Agent induk wajib resolve konflik sub-branch sebelum lanjut; eskalasi ke orchestrator/manusia jika gagal >N kali             |
+| **Observability overhead memperlambat agent**                                  | Sedang | Event emit async, non-blocking; instrumentation wrapper ringan (intercept, bukan full proxy semua I/O)                       |
+| **Biaya membludak karena planner + banyak worker paralel**                     | Tinggi | Cost guard per graph, planner pakai provider lebih murah untuk subtask kecil, model reasoning kuat hanya untuk root planning |
+| **Governance approval jadi bottleneck** (kamu kebanjiran approval request)     | Sedang | `autoApproveCategories` untuk task low-risk, batch approval UI di dashboard                                                  |
+| **Agent backend tanpa native event hook (mis. Aider) sulit di-observe detail** | Sedang | Instrumentation wrapper fallback (FR-44) — minimal observability tetap ada meski tidak sedetail agent yang native support    |
+
+---
+
+## 11. Metrik Sukses v2
+
+- Dari 1 task kalimat natural language, sistem menghasilkan task graph valid (executable, scoped wajar) tanpa kamu edit manual decomposition-nya.
+- Bisa lihat real-time di dashboard: berapa agent/subagent hidup, sedang pakai skill apa, command apa — tanpa buka terminal manual sama sekali.
+- Minimal 1 contoh kasus task baru yang diusulkan otomatis oleh subagent (bukan kamu) berhasil diapprove dan dieksekusi sampai PR.
+- Tidak ada insiden runaway cost/spawn agent tak terkendali selama pengujian internal.
+
+---
+
+## 12. Open Questions (Update dari v1)
+
+1. Apakah Planner Agent (untuk decomposition) sebaiknya selalu pakai provider reasoning-kuat (lebih mahal) atau bisa adaptif tergantung kompleksitas task root?
+2. Bagaimana strategi merge konflik kalau 2 subagent independen ternyata menyentuh file yang sama meski berbeda worktree (mis. shared config file)?
+3. Apakah "skill yang sedang digunakan agent" akan didefinisikan dari sistem skill kamu sendiri (CEO Orchestrator, 261+ skills) atau skill native dari masing-masing agent backend (OpenCode skill, Claude Code skill)? Ini menentukan desain Instrumentation Wrapper.
+4. Seberapa granular Live Activity Feed perlu ditampilkan — apakah setiap keystroke/tool-call, atau di-summarize per "langkah logis" supaya dashboard tidak noise?
+5. Apakah governance approval untuk task baru perlu notifikasi push (desktop/Telegram) atau cukup pasif menunggu di dashboard?
+
+---
+
+_PRD v2 ini dibangun di atas fondasi v1 (plugin architecture, GitHub-first, multi-provider routing). Rekomendasi: selesaikan M0-M3 v1 sebagai working baseline dulu sebelum masuk M7 (Task Graph Core), karena scheduler & event bus v2 butuh runtime/workspace/agent adapter dari v1 sudah stabil._