Migrasi ke OPSX

Panduan ini membantu Anda beralih dari alur kerja OpenSpec lama ke OPSX. Migrasi dirancang agar lancar—pekerjaan Anda yang sudah ada tetap terjaga, dan sistem baru menawarkan fleksibilitas lebih.

Apa yang Berubah?

OPSX menggantikan alur kerja terkunci fase dengan pendekatan berbasis tindakan yang lebih cair. Berikut adalah perubahan utamanya:

Aspek	Lama	OPSX
Perintah	/openspec:proposal, /openspec:apply, /openspec:archive	Default: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (perintah alur kerja tambahan opsional)
Alur Kerja	Membuat semua artefak sekaligus	Membuat secara bertahap atau sekaligus—pilihan Anda
Kembali ke belakang	Gerbang fase yang canggung	Alami—perbarui artefak kapan saja
Kustomisasi	Struktur tetap	Berbasis skema, sepenuhnya dapat dimodifikasi
Konfigurasi	CLAUDE.md dengan penanda + project.md	Konfigurasi bersih di openspec/config.yaml

Perubahan filosofi: Pekerjaan tidak bersifat linier. OPSX berhenti berpura-pura sebaliknya.

---

Sebelum Memulai

Pekerjaan Anda yang Ada Tetap Aman

Proses migrasi dirancang dengan mengutamakan pelestarian:

• Perubahan aktif di openspec/changes/ — Sepenuhnya dipertahankan. Anda dapat melanjutkannya dengan perintah OPSX.
• Perubahan yang diarsipkan — Tidak tersentuh. Riwayat Anda tetap utuh.
• Spesifikasi utama di openspec/specs/ — Tidak tersentuh. Ini adalah sumber kebenaran Anda.
• Konten Anda di CLAUDE.md, AGENTS.md, dll. — Dipertahankan. Hanya blok penanda OpenSpec yang dihapus; semua yang Anda tulis tetap ada.

Yang Dihapus

Hanya file yang dikelola OpenSpec yang akan diganti:

Apa	Mengapa
Direktori/file perintah slash lawas	Digantikan oleh sistem skills baru
openspec/AGENTS.md	Pemicu alur kerja usang
Penanda OpenSpec di CLAUDE.md, AGENTS.md, dll.	Tidak lagi diperlukan

Lokasi perintah lawas berdasarkan alat (contoh—alat Anda mungkin berbeda):

• Claude Code: .claude/commands/openspec/
• Cursor: .cursor/commands/openspec-*.md
• Devin Desktop, sebelumnya Windsurf: .windsurf/workflows/openspec-*.md
• Cline: .clinerules/workflows/openspec-*.md
• Roo: .roo/commands/openspec-*.md
• GitHub Copilot: .github/prompts/openspec-*.prompt.md (hanya ekstensi IDE; tidak didukung di Copilot CLI)
• Codex: OpenSpec sekarang menggunakan path kanonik .agents/skills/openspec-*. File SKILL.md yang dikelola OpenSpec di bawah path .codex/skills sebelumnya hanya direkonsiliasi setelah pengganti ada; file kustom dan salinan divergen tetap di tempatnya. Jika pohon .agents yang belum ditandai sudah berisi skills OpenSpec, OpenSpec mempertahankan rendering Codex ($openspec-*) atau generik (/openspec-*) yang ada alih-alih menebak dari direktori lawas. Pilih codex secara eksplisit dengan openspec init untuk beralih kepemilikan. Pembersihan prompt lawas tetap hanya menargetkan nama file prompt Codex yang ada dalam daftar putih OpenSpec di $CODEX_HOME/prompts atau ~/.codex/prompts.
• Dan lainnya (Augment, Continue, Amazon Q, dll.)

Migrasi mendeteksi alat-alat yang telah Anda konfigurasikan dan membersihkan file lawasnya.

Daftar penghapusan mungkin tampak panjang, tetapi semua ini adalah file yang awalnya dibuat oleh OpenSpec. Konten Anda sendiri tidak pernah dihapus.

Yang Perlu Perhatian Anda

Satu file memerlukan migrasi manual:

openspec/project.md — File ini tidak dihapus secara otomatis karena mungkin berisi konteks proyek yang telah Anda tulis. Anda perlu:

1. Tinjau isinya
2. Pindahkan konteks yang berguna ke openspec/config.yaml (lihat panduan di bawah)
3. Hapus file tersebut bila sudah siap

Mengapa kami membuat perubahan ini:

project.md yang lama bersifat pasif—agen mungkin membacanya, mungkin tidak, mungkin melupakan apa yang telah dibaca. Kami menemukan keandalannya tidak konsisten.

Konteks config.yaml yang baru secara aktif disuntikkan ke setiap permintaan perencanaan OpenSpec. Ini berarti konvensi proyek, tumpukan teknologi, dan aturan Anda selalu hadir saat AI membuat artefak. Keandalan lebih tinggi.

Imbalannya:

Karena konteks disuntikkan ke setiap permintaan, Anda perlu ringkas. Fokus pada yang benar-benar penting:

• Tumpukan teknologi dan konvensi utama
• Batasan tidak jelas yang perlu diketahui AI
• Aturan yang sering diabaikan sebelumnya

Jangan khawatir untuk membuatnya sempurna. Kami masih mempelajari apa yang paling cocok di sini, dan kami akan terus meningkatkan cara injeksi konteks bekerja seiring eksperimen kami.

---

Menjalankan Migrasi

Baik openspec init maupun openspec update mendeteksi file lawas dan memandu Anda melalui proses pembersihan yang sama. Gunakan yang sesuai dengan situasi Anda:

• Instalasi baru secara default menggunakan profil core (propose, explore, apply, update, sync, archive).
• Instalasi yang dimigrasikan mempertahankan alur kerja terpasang sebelumnya dengan menulis profil custom bila diperlukan.

Menggunakan openspec init

Jalankan ini jika Anda ingin menambahkan alat baru atau mengkonfigurasi ulang alat yang disiapkan:

openspec init

Perintah init mendeteksi file lawas dan memandu Anda melalui pembersihan:

Meningkatkan ke OpenSpec baru

OpenSpec sekarang menggunakan keterampilan agen (agent skills), standar yang sedang berkembang di kalangan
agen pengkodean. Ini menyederhanakan pengaturan Anda sambil menjaga semuanya tetap berfungsi seperti sebelumnya.

File yang akan dihapus
Tidak ada konten pengguna yang perlu dipertahankan:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

File yang akan diperbarui
Penanda OpenSpec akan dihapus, konten Anda dipertahankan:
  • CLAUDE.md
  • AGENTS.md

Butuh perhatian Anda
  • openspec/project.md
    Kami tidak akan menghapus file ini. Ini mungkin berisi konteks proyek yang berguna.

    openspec/config.yaml yang baru memiliki bagian "context:" untuk konteks perencanaan.
    Ini disertakan dalam setiap permintaan OpenSpec dan bekerja lebih andal
    dibandingkan pendekatan project.md lama.

    Tinjau project.md, pindahkan konten yang berguna ke bagian context di config.yaml,
    lalu hapus file tersebut bila sudah siap.

? Tingkatkan dan bersihkan file lawas? (Y/n)

Yang terjadi saat Anda mengatakan ya:

1. Direktori perintah slash lawas dihapus
2. Penanda OpenSpec dihapus dari CLAUDE.md, AGENTS.md, dll. (konten Anda tetap ada)
3. openspec/AGENTS.md dihapus
4. Skills baru dipasang di .claude/skills/
5. openspec/config.yaml dibuat dengan skema default

Menggunakan openspec update

Jalankan ini jika Anda hanya ingin memigrasikan dan menyegarkan alat yang ada ke versi terbaru:

openspec update

Perintah update juga mendeteksi dan membersihkan artefak lawas, lalu menyegarkan skills/perintah yang dihasilkan agar sesuai dengan profil dan pengaturan pengiriman Anda saat ini.

Lingkungan Non-Interaktif / CI

Untuk migrasi dengan skrip:

openspec init --force --tools claude

Flag --force melewati prompt dan otomatis menerima pembersihan.

Ini termasuk pembersihan file prompt Codex yang dikelola OpenSpec di direktori prompt Codex global. Pembersihan hanya menargetkan nama file prompt Codex lawas yang ada dalam daftar putih OpenSpec, menghapusnya hanya setelah skills pengganti .agents/skills/openspec-* ada, dan mempertahankan semua file lainnya.

---

Migrasi project.md ke config.yaml

openspec/project.md yang lama adalah file markdown bebas bentuk untuk konteks proyek. openspec/config.yaml yang baru terstruktur dan—yang penting—disuntikkan ke setiap permintaan perencanaan sehingga konvensi Anda selalu ada saat AI bekerja.

Sebelum (project.md)

# Konteks Proyek

Ini adalah monorepo TypeScript yang menggunakan React dan Node.js.
Kami menggunakan Jest untuk pengujian dan mengikuti aturan ESLint yang ketat.
API kami bersifat RESTful dan didokumentasikan di docs/api.md.

## Konvensi

- Semua API publik harus menjaga kompatibilitas mundur
- Fitur baru harus menyertakan pengujian
- Gunakan format Given/When/Then untuk spesifikasi

Setelah (config.yaml)

schema: spec-driven

context: |
  Tumpukan teknologi: TypeScript, React, Node.js
  Pengujian: Jest dengan React Testing Library
  API: RESTful, didokumentasikan di docs/api.md
  Kami menjaga kompatibilitas mundur untuk semua API publik

rules:
  proposal:
    - Sertakan rencana rollback untuk perubahan berisiko
  specs:
    - Gunakan format Given/When/Then untuk skenario
    - Rujuk pola yang ada sebelum menciptakan yang baru
  design:
    - Sertakan diagram sekuens untuk alur kompleks

Perbedaan Utama

project.md	config.yaml
Markdown bebas bentuk	YAML terstruktur
Satu gumpalan teks	Konteks terpisah dan aturan per artefak
Tidak jelas kapan digunakan	Konteks muncul di SEMUA artefak; aturan hanya muncul di artefak yang cocok
Tidak ada pemilihan skema	Bidang schema: eksplisit menetapkan alur kerja default

Apa yang Disimpan, Apa yang Dibuang

Saat memigrasikan, bersikaplah selektif. Tanyakan pada diri sendiri: "Apakah AI memerlukan ini untuk setiap permintaan perencanaan?"

Kandidat bagus untuk context:

• Tumpukan teknologi (bahasa, kerangka kerja, basis data)
• Pola arsitektur utama (monorepo, microservices, dll.)
• Batasan tidak jelas ("kami tidak bisa menggunakan pustaka X karena...")
• Konvensi kritis yang sering diabaikan

Pindahkan ke rules: saja

• Pemformatan khusus artefak ("gunakan Given/When/Then dalam spesifikasi")
• Kriteria peninjauan ("proposal harus menyertakan rencana rollback")
• Ini hanya muncul untuk artefak yang cocok, membuat permintaan lain lebih ringan

Tinggalkan sepenuhnya

• Praktik terbaik umum yang sudah diketahui AI
• Penjelasan bertele-tele yang bisa diringkas
• Konteks historis yang tidak memengaruhi pekerjaan saat ini

Langkah-Langkah Migrasi

1. Buat config.yaml (jika belum dibuat oleh init):

   schema: spec-driven

2. Tambahkan konteks Anda (ringkas—ini masuk ke setiap permintaan):

   context: |
     Latar belakang proyek Anda di sini.
     Fokus pada apa yang benar-benar perlu diketahui AI.

3. Tambahkan aturan per artefak (opsional):

   rules:
     proposal:
       - Panduan khusus proposal Anda
     specs:
       - Aturan penulisan spesifikasi Anda

4. Hapus project.md setelah Anda memindahkan semuanya yang berguna.

Jangan terlalu dipikirkan. Mulailah dengan yang penting dan iterasi. Jika Anda melihat AI melewatkan sesuatu yang penting, tambahkan. Jika konteks terasa membengkak, pangkas. Ini adalah dokumen yang hidup.

Butuh Bantuan? Gunakan Prompt Ini

Jika Anda tidak yakin cara menyaring project.md Anda, tanyakan asisten AI Anda:

Saya sedang memigrasikan dari project.md OpenSpec lama ke format config.yaml yang baru.

Berikut project.md saya saat ini:
[tempel konten project.md Anda]

Tolong bantu saya membuat config.yaml dengan:
1. Bagian `context:` yang ringkas (ini disuntikkan ke setiap permintaan perencanaan, jadi buatlah padat—fokus pada tumpukan teknologi, batasan utama, dan konvensi yang sering diabaikan)
2. `rules:` untuk artefak spesifik jika ada konten yang spesifik artefak (misalnya, "gunakan Given/When/Then" termasuk dalam aturan spesifikasi, bukan konteks global)

Tinggalkan hal-hal generik yang sudah diketahui model AI. Bersikap tegaslah tentang keringkasan.

AI akan membantu Anda mengidentifikasi apa yang penting vs. apa yang bisa dipangkas.

---

Perintah Baru

Ketersediaan perintah bergantung pada profil:

Default (profil core):

Perintah	Tujuan
/opsx:propose	Membuat perubahan dan menghasilkan artefak perencanaan dalam satu langkah
/opsx:explore	Memikirkan ide tanpa struktur
/opsx:apply	Menerapkan tugas dari tasks.md
/opsx:update	Merevisi artefak perencanaan suatu perubahan dan menjaganya tetap koheren
/opsx:sync	Menggabungkan spesifikasi delta ke spesifikasi utama
/opsx:archive	Menyelesaikan dan mengarsipkan perubahan

Alur kerja diperluas (seleksi kustom):

Perintah	Tujuan
/opsx:new	Memulai perancah perubahan baru
/opsx:continue	Membuat artefak berikutnya (satu per satu)
/opsx:ff	Fast-forward—buat artefak perencanaan sekaligus
/opsx:verify	Memvalidasi implementasi sesuai spesifikasi
/opsx:bulk-archive	Mengarsipkan beberapa perubahan sekaligus
/opsx:onboard	Alur kerja onboarding end-to-end terpandu

Aktifkan perintah diperluas dengan openspec config profile, lalu jalankan openspec update.

Pemetaan Perintah dari Legacy

Legacy	Setara OPSX
/openspec:proposal	/opsx:propose (default) atau /opsx:new lalu /opsx:ff (diperluas)
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

Kemampuan Baru

Kemampuan ini adalah bagian dari set perintah alur kerja diperluas.

Pembuatan artefak granular:

/opsx:continue

Membuat satu artefak setiap kali berdasarkan ketergantungan. Gunakan ini saat Anda ingin meninjau setiap langkah.

Mode eksplorasi:

/opsx:explore

Memikirkan ide bersama mitra sebelum berkomitmen pada suatu perubahan.

Memahami Arsitektur Baru

Dari Phase-Locked ke Fluid

Alur kerja lama memaksa kemajuan linear:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

Jika Anda sedang dalam implementasi dan menyadari desainnya salah?
Sayang sekali. Gerbang fase tidak memungkinkan Anda kembali dengan mudah.

OPSX menggunakan aksi, bukan fase:

         ┌───────────────────────────────────────────────┐
         │           ACTIONS (not phases)                │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    any order                  │
         └───────────────────────────────────────────────┘

Dependency Graph

Artefak membentuk graf terarah. Dependensi adalah enabler, bukan gerbang:

                        proposal
                       (root node)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (requires:                  (requires:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (requires:
                     specs, design)

Ketika Anda menjalankan /opsx:continue, sistem memeriksa apa yang siap dan menawarkan artefak berikutnya. Anda juga dapat membuat beberapa artefak yang siap dalam urutan apa pun.

Skills vs Commands

Sistem lama menggunakan file perintah khusus alat:

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSX menggunakan standar skills yang berkembang:

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Skills dikenali di berbagai alat coding AI dan menyediakan metadata yang lebih kaya.

Codex hanya menggunakan skills di OPSX. OpenSpec tidak lagi menghasilkan file prompt khusus Codex; gunakan direktori .agents/skills/openspec-* yang dihasilkan sebagai gantinya.

---

Melanjutkan Perubahan yang Sudah Ada

Perubahan yang sedang Anda kerjakan bekerja mulus dengan perintah OPSX.

Punya perubahan aktif dari alur kerja lama?

/opsx:apply add-my-feature

OPSX membaca artefak yang ada dan melanjutkan dari tempat Anda berhenti.

Ingin menambahkan artefak lebih lanjut ke perubahan yang sudah ada?

/opsx:continue add-my-feature

Menampilkan apa yang siap dibuat berdasarkan apa yang sudah ada.

Perlu melihat status?

openspec status --change add-my-feature

---

Sistem Konfigurasi Baru

Struktur config.yaml

# Wajib: Skema default untuk perubahan baru
schema: spec-driven

# Opsional: Konteks proyek (maks 50KB)
# Disuntikkan ke SEMUA instruksi artefak
context: |
  Latar belakang proyek Anda, tech stack,
  konvensi, dan batasan.

# Opsional: Aturan per-artefak
# Hanya disuntikkan ke artefak yang cocok
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Document fallback strategies
  tasks:
    - Break into 2-hour maximum chunks

Resolusi Skema

Saat menentukan skema mana yang akan digunakan, OPSX memeriksa secara berurutan:

1. CLI flag: --schema <name> (prioritas tertinggi)
2. Metadata perubahan: .openspec.yaml di direktori perubahan
3. Konfigurasi proyek: openspec/config.yaml
4. Default: spec-driven

Skema yang Tersedia

Skema	Artefak	Paling Cocok Untuk
spec-driven	proposal → specs → design → tasks	Sebagian besar proyek

Daftarkan semua skema yang tersedia:

openspec schemas

Skema Kustom

Buat alur kerja Anda sendiri:

openspec schema init my-workflow

Atau fork dari yang sudah ada:

openspec schema fork spec-driven my-workflow

Lihat Customization untuk detailnya.

---

Pemecahan Masalah

"Legacy files detected in non-interactive mode"

Anda menjalankan di lingkungan CI atau non-interaktif. Gunakan:

openspec init --force

Perintah tidak muncul setelah migrasi

Restart IDE Anda. Skills dideteksi saat startup.

"Unknown artifact ID in rules"

Periksa apakah kunci rules: Anda cocok dengan ID artefak skema Anda:

• spec-driven: proposal, specs, design, tasks

Jalankan ini untuk melihat ID artefak yang valid:

openspec schemas --json

Konfigurasi tidak diterapkan

1. Pastikan file berada di openspec/config.yaml (bukan .yml)
2. Validasi sintaks YAML
3. Perubahan konfigurasi berlaku segera—tidak perlu restart

project.md tidak dimigrasi

Sistem sengaja mempertahankan project.md karena mungkin berisi konten kustom Anda. Tinjau secara manual, pindahkan bagian yang berguna ke config.yaml, lalu hapus file tersebut.

Ingin melihat apa yang akan dibersihkan?

Jalankan init dan tolak prompt pembersihan—Anda akan melihat ringkasan deteksi lengkap tanpa ada perubahan yang dilakukan.

---

Referensi Cepat

File Setelah Migrasi

project/
├── openspec/
│   ├── specs/                    # Tidak berubah
│   ├── changes/                  # Tidak berubah
│   │   └── archive/              # Tidak berubah
│   └── config.yaml               # BARU: Konfigurasi proyek
├── .claude/
│   └── skills/                   # BARU: Skills OPSX
│       ├── openspec-propose/     # default core profile
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # expanded profile adds new/continue/ff/etc.
├── CLAUDE.md                     # Penanda OpenSpec dihapus, konten Anda dipertahankan
└── AGENTS.md                     # Penanda OpenSpec dihapus, konten Anda dipertahankan

Yang Hilang

• .claude/commands/openspec/ — diganti oleh .claude/skills/
• openspec/AGENTS.md — tidak berlaku lagi
• openspec/project.md — migrasi ke config.yaml, lalu hapus
• Blok penanda OpenSpec di CLAUDE.md, AGENTS.md, dll.

Command Cheatsheet

/opsx:propose      Mulai dengan cepat (default core profile)
/opsx:apply        Implementasi tugas
/opsx:archive      Selesai dan arsipkan

# Alur kerja diperluas (jika diaktifkan):
/opsx:new          Buat kerangka perubahan
/opsx:continue     Buat artefak berikutnya
/opsx:ff           Buat artefak perencanaan

---

Mendapatkan Bantuan

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Dokumentasi: docs/opsx.md untuk referensi OPSX lengkap