⚡ AlihSpec — Spec-Driven Project Conversion Framework

Alihkan codebase ke bahasa apa pun dengan spesifikasi hidup, 16 pilar universal & zero logic drift.
Shift any codebase across stacks through living specs, 16 universal conversion pillars, dual checkpoints, and AST-level precision.

Framework sistematis untuk mengonversi proyek perangkat lunak dari satu bahasa/framework ke bahasa/framework lain menggunakan metodologi Spec-Driven Development (SDD), 7 Golden Directives, dan AI Coding Agents berstandar enterprise. Berfungsi ganda sebagai Workspace Template terisolasi maupun Portable AI Agent Skill.

🌟 Mengapa Menggunakan AlihSpec?

• ⚡ ~70% Lebih Cepat (~3x Lipat): Memangkas siklus trial-and-error dan mengeliminasi 75% waktu debugging pasca-generate (Lihat Benchmark Efisiensi).
• 🛡️ 16 Pilar Pelajaran Universal Konversi: Melindungi sistem dari risiko drift di 4 kuadran: Konfigurasi/Gateway, Kontrak/DTO, Database/ACID, hingga I/O/Observability (Baca Panduan Master Evaluasi).
• 🔬 Zero Logic Drift & Deep AST Inspection: Aturan bisnis, query parameters, percabangan if/switch, dan relasi database dibedah baris-demi-baris dan terkunci di specs/ sebelum coding dimulai.
• 🛑 Dual Validation Checkpoints: Verifikasi silang otomatis (Checkpoint 1: Spec vs Source, Checkpoint 2: Task vs Spec) untuk menjamin kualitas sebelum kode target ditulis.
• 🚫 Strict No Dummy Fallback: Menjamin 100% query database riil di layer Repository tanpa hardcoded mock/fake values.
• 🧠 Dual-Mode (Template & Portable AI Skill): Dapat digunakan sebagai workspace template baru atau disalin sebagai skill .agents/ langsung ke repo proyek lama tanpa mengotori folder root (Sandbox Capsule Strategy).
• 🤖 Multi-Agent Native Steering: Dilengkapi instruksi guardrails bawaan untuk Antigravity, Cursor, Claude Code, Windsurf, Cline/Roo Code, Kiro, dan GitHub Copilot.
• 📦 10 Presets Bawaan + Custom Engine: Dukungan siap pakai untuk Laravel, Go, NestJS, FastAPI, Django, Rails, Spring Boot, CodeIgniter, Express, dan custom stack.
• 🟣 Starter Template Support: Fleksibilitas menggunakan boilerplate target pilihan Anda via reference-target/.

📌 Apa itu SDD (Spec-Driven Development)?

Spec-Driven Development berarti merumuskan spesifikasi hidup terlebih dahulu, memvalidasinya terhadap source code, baru mengimplementasikan kodenya lapis demi lapis (layer-by-layer).

Dalam konteks konversi proyek, SDD mendefinisikan:

1. Deep AST Inspection: Membedah seluruh parameter query, percabangan respon, dan relasi tabel dari controller sumber baris-demi-baris.
2. Arsitektur & Pattern Mapping: Pemetaan konsep bahasa sumber ➔ bahasa target (misal: Eloquent ➔ GORM, FormRequest ➔ DTO, Middleware ➔ Interceptors).
3. Standar Penerimaan (Acceptance Criteria): Kontrak JSON, pointer nullability parity, dan aturan bisnis yang harus dipenuhi oleh AI tanpa kompromi.

🚨 7 Golden Directives for AI Agents (MANDATORY)

Setiap Agent AI yang mengeksekusi konversi di AlihSpec wajib mematuhi 7 aturan utama berikut:

💎 8 Standar Mutu Kritis Enterprise

AlihSpec menerapkan 8 standar presisi enterprise untuk mencegah bug laten di produksi:

1. 🕒 DateTime & Timezone Parity: Format serialisasi tanggal (YYYY-MM-DD HH:mm:ss / ISO 8601) dan timezone wajib identik dengan API sumber.
2. 💰 Currency & Numeric Precision: Dilarang menggunakan float64 untuk mata uang/koin/poin; wajib gunakan int64 (basis sen terkecil) atau exact decimal.
3. 📑 Pagination Envelope Parity: Metadata pagination (current_page, from, last_page, per_page, total) dan perhitungan offset (page-1)*per_page harus 1:1 presisi.
4. ⚠️ Validation Error Envelope Parity: Format error HTTP 422 berupa Object of String Arrays {"errors": {"field": ["msg"]}}.
5. 🔒 Concurrency & Row-Level Locking: Mutasi saldo, kuota, atau stok wajib menggunakan transaksi dan Row-Level Locking (SELECT ... FOR UPDATE).
6. 🗑️ Soft Delete Leakage Prevention: Query manual JOIN atau Raw SQL wajib menyertakan AND [table].deleted_at IS NULL.
7. 🔑 JWT Claims Key Parity: Key payload token JWT (sub, uid, user_id, role) wajib konsisten dengan sistem autentikasi sumber.
8. 🛡️ Empty State Contract: Koleksi list kosong wajib mengembalikan array kosong [] (bukan null), dan entitas tunggal tidak ditemukan mengembalikan HTTP 404 / null.

📚 Landasan Teori & Standar Industri yang Dirujuk

Seluruh 7 Direktif, 16 Pilar Universal, dan 8 Standar Mutu di AlihSpec diturunkan dari standar internasional dan literatur rekayasa perangkat lunak terkemuka (Baca Rujukan Lengkap di evaluate/framework-evaluation.md):

• 🏛️ Pola Arsitektur: Clean Architecture (Robert C. Martin), Patterns of Enterprise Application Architecture & Strangler Fig Pattern (Martin Fowler).
• 🌐 Protokol Web & API: IETF RFC 7519 (JWT Claims), RFC 3339 / ISO 8601 (DateTime/Timezone), RFC 7807 & 9110 (HTTP Status & Error Payloads), RFC 3986 (URI Syntax).
• 🗄️ Integritas Database: ISO/IEC 9075 SQL Standard, ACID Transaction Model & Pessimistic Row-Level Locking (SELECT ... FOR UPDATE).
• ⚙️ Metodologi Modern: The Twelve-Factor App Methodology (Strict Config Parity & Graceful Shutdown), The Go Programming Language Specification, dan IEEE / ISO/IEC 25010 Software Quality Model.
• 🔬 Studi Kasus Empiris: Post-mortem audit konversi sistem monolitik enterprise (Laravel Eloquent ➔ Go Fiber Clean Architecture).

🔄 Workflow Konversi 5 Fase (Dual Checkpoints)

[Fase 1] ➔ Deep Source Inspection (Bedah baris-demi-baris) ➔ specs/overview.md
[Fase 2] ➔ Tulis Spesifikasi Modul di specs/modules/[module].md (DoD Checklist)
              ↳ 🛑 CHECKPOINT 1: Spec vs Source Cross-Validation
[Fase 3] ➔ Buat Task Breakdown di tasks/ (Layer-by-Layer)
              ↳ 🛑 CHECKPOINT 2: Task vs Spec Alignment
[Fase 4] ➔ Eksekusi Koding di output/ (DTO ➔ Domain ➔ Repo ➔ Service ➔ Handler)
[Fase 5] ➔ Testing, Integritas Framework & QA Audit (100% Zero Failure)

🗂️ Struktur Folder Lengkap

alih-spec/
│
├── .agents/              # 🧠 Native AI Agent Skills & Customization
│   └── skills/
│       └── alih-spec/    # Skill AlihSpec bawaan (SKILL.md, 16 pillars, AST guide)
│
├── .sdd/                 # ⚙️ Konfigurasi framework, active mapping & presets
│   ├── config.yaml       # File konfigurasi utama proyek konversi
│   ├── mapping/          # Aturan pemetaan pola (patterns.md, conventions.md)
│   └── presets/          # Katalog preset bawaan (laravel-to-go, django-to-fastapi, dll.)
│
├── source/               # 🔵 Proyek asli (READ-ONLY reference — jangan dimodifikasi)
├── reference-target/     # 🟣 Template starter target pilihan (OPSIONAL, READ-ONLY)
│
├── specs/                # 📋 Single Source of Truth (Spesifikasi Arsitektur & Bisnis)
│   ├── overview.md       # Ringkasan domain, modul, routes, & relasi database
│   ├── architecture.md   # Pola arsitektur target, struktur layer & folder output
│   ├── data-models/      # Dokumentasi skema tabel & relasi DB (schema.md)
│   ├── modules/          # Spesifikasi per-modul detail dengan DoD & Branching Matrix
│   └── api-contracts/    # Kontrak API OpenAPI / Swagger (openapi.yaml)
│
├── tasks/                # ✅ Antrean pengerjaan modular & master progress index
│   ├── _index.md         # Dashboard master status progress seluruh task
│   ├── phase-1-foundation/   # Task setup scaffold, DB layer & auth
│   ├── phase-2-core-modules/ # Task implementasi modul bisnis utama
│   └── phase-3-integration/  # Task router gateway, E2E testing & polish
│
├── context/              # 🧠 Context Engine & Guardrails untuk AI Agent
│   ├── AGENTS.md         # Instruksi master wajib baca untuk seluruh AI agent
│   ├── RULES.md          # Registry aturan bisnis & architectural guardrails
│   ├── conventions.md    # Standar konvensi penamaan & koding bahasa target
│   ├── tech-stack.md     # Spesifikasi detail stack & dependency target
│   ├── VIBE.md           # Bank 13 prompt presisi tinggi untuk full vibe coding
│   ├── qa-checklist.md   # Checklist audit mutu sebelum rilis
│   └── glossary.md       # Kamus istilah & padanan konsep lintas bahasa
│
├── evaluate/             # 🔬 Pusat Evaluasi & Pelajaran Konversi Lintas Bahasa
│   ├── README.md                    # Panduan tata kelola evaluasi & case studies
│   └── framework-evaluation.md      # Master context: 16 pilar universal & guardrails
│
├── output/               # 🟢 Hasil konversi murni (seluruh kode target ditulis di sini)
├── docs/                 # 📚 Audit trail, Architecture Decisions (ADR) & Benchmark
│   ├── START-HERE.md     # Panduan orientasi memilih jalur pengerjaan
│   ├── efficiency-benchmark.md # Metrik kuantitatif efisiensi & scorecard KPI
│   ├── decisions.md      # Catatan Architecture Decision Records (ADR)
│   ├── progress.md       # Log progres harian & milestone
│   ├── mapping-log.md    # Log pencatatan deviasi teknis sumber ➔ target
│   ├── changelog.md      # Catatan riwayat versi
│   ├── guide-vibe-coding.md # Panduan lengkap alur Vibe Coding
│   └── guide-manual.md   # Panduan lengkap alur Manual / Semi-Auto
│
└── scripts/              # 🛠️ CLI automation suite ('alih')

🚀 Dua Cara Menggunakan AlihSpec

AlihSpec dirancang fleksibel dengan 2 mode penggunaan:

flowchart LR
    A["AlihSpec"] --> B["Mode A: Dedicated Workspace Template\n(Clone Repo AlihSpec)"]
    A --> C["Mode B: Portable AI Agent Skill\n(Copy .agents/ ke Proyek Mana Pun)"]
    B --> D["Input di source/ ➔ Output di output/"]
    C --> E["Kapsul Terisolasi di alih-conversion/"]

1️⃣ Mode A: Dedicated Workspace Template (Alur Standar)

Cocok jika Anda ingin workspace migrasi yang bersih dan terisolasi secara menyeluruh sejak awal.

1. Clone Template:

   git clone https://github.com/hanifalkauni/alih-spec.git my-conversion
   cd my-conversion
   

2. Salin Kode Sumber: Salin kode proyek lama Anda ke dalam folder source/ (opsional: starter target di reference-target/).
3. Inisialisasi: Jalankan .\scripts\alih.ps1 init (atau bash scripts/alih.sh init).
4. Pilih Jalur Kerja:
   • 🤖 Vibe Coding Guide: Gunakan prompt queue otomatis.
   • ✍️ Manual Guide: Kontrol arsitektur & spec writing terperinci.
   • ⚡ Prompt Bank (VIBE.md): Bank 13 prompt enterprise siap pakai.

2️⃣ Mode B: Portable AI Agent Skill (.agents/skills/alih-spec/)

Cocok jika Anda ingin langsung mengonversi di dalam repository proyek lama tanpa perlu memindahkan source code atau meng-clone seluruh template!

1. Pasang Skill: Cukup salin folder .agents/ ke dalam root folder proyek lama Anda (atau pasang di global config AI IDE Anda ~/.gemini/config/skills/).
2. Buka Proyek di AI IDE (Antigravity IDE, Cursor, Claude Code, Windsurf, dll.).
3. Kirimkan Prompt Konversi ke AI Chat:

   Tolong konversikan modul auth dan order dari proyek ini ke Go Fiber Clean Architecture menggunakan skill alih-spec.
   

4. 🛡️ Sandbox Capsule Strategy (Zero Root Pollution):
   • AI otomatis membaca kode lama Anda secara STRICT READ-ONLY.
   • AI TIDAK AKAN MENGOTORI root folder Anda. Seluruh spesifikasi, task, dan output kode target akan dibungkus rapi di dalam satu folder sandbox terisolasi:

     my-laravel-app/            # 🔵 Proyek Asli Anda (Aman & Tidak Tersentuh)
     ├── app/
     ├── routes/
     ├── database/
     ├── .agents/skills/alih-spec/
     │
     └── alih-conversion/       # 📦 Folder Kapsul Terisolasi
         ├── specs/             # Living specs & API contracts
         ├── tasks/             # Antrean task & progress (_index.md)
         ├── output/            # 🟢 Kode target Clean Architecture
         └── docs/              # Catatan ADR & mapping log
     

   • Nama Cadangan Fallback: Jika alih-conversion/ sudah ada di repo Anda, AI otomatis menggunakan nama alternatif: .alih-spec/, _conversion/, atau conversion-[target]/.

📦 Presets Bawaan Siap Pakai (.sdd/presets/)

🛠️ CLI Automation Suite (alih)

Framework ini dilengkapi CLI bawaan di folder scripts/:

🧠 Instruksi untuk AI Agent

Jika Anda adalah AI Coding Assistant (Antigravity, Cursor, Kiro, Copilot, Windsurf, Claude Code, Cline) yang membaca workspace ini:

1. 👉 Wajib membaca context/AGENTS.md terlebih dahulu sebelum menulis atau mengubah kode apa pun.
2. 🔬 Pahami 16 Pilar Universal & 7 Direktif di evaluate/framework-evaluation.md untuk memastikan paritas arsitektural dan mencegah shallow specs.
3. 📜 Cek context/RULES.md untuk memastikan tidak ada aturan bisnis atau batasan arsitektur yang terlewat.

📚 Peta Dokumentasi & Audit Trail

📄 Lisensi

Didistribusikan di bawah lisensi open-source MIT License. Lihat LICENSE untuk informasi lebih lanjut.

AlihSpec v1.0.0 • Dibuat untuk ekosistem AI Coding modern berpresisi enterprise 🚀