Cara menyiapkan spesifikasi SurveyDesk dengan Agent On Rails

SurveyDesk adalah produk referensi Spec-Driven kami: operator native iOS/Android, web publik anonim, API lokal OpenAPI + SQLite yang netral bahasa (referensi Python; Java boleh), dan FormSpec sebagai kontrak form. Bagian sulitnya bukan menamai folder — melainkan mendapatkan pohon spesifikasi yang lengkap dan bisa direview sebelum siapa pun membuka Cursor. Agent On Rails kini melakukan itu dari bahasa alami.

Apa yang akan Anda dapatkan

Ketika teks yang ditempel menggambarkan SurveyDesk (survey desk local-first, FormSpec, operator mobile native, web anonim), Agent On Rails menulis paket referensi yang sama dengan exemplar SurveyDesk — bukan file stub yang dipotong per kalimat.

• specs/product — visi, persona, brand, perjalanan demo
• specs/requirements — kontrak SHALL SD-001 … SD-012
• specs/domain — survey, FormSpec, response, lifecycle, results
• specs/api/openapi.yaml — draft lokal /v1/surveys
• specs/adr — ADR-001 … ADR-009 (monorepo, SQLite, web anonim, mobile, …)
• specs/acceptance — fitur Gherkin
• specs/regeneration — prompt P1–P6 + kontrak supaya agent lain bisa membangun ulang

1. Pasang Agent On Rails

Anda butuh Python 3.11+ dan CLI aor. Jalur tercepat di Mac adalah aplikasi setup bertanda tangan dari https://agent-on-rails.suherman.net — seret Agent On Rails ke Applications, buka, dan biarkan wizard memasang aor.

Atau pasang dari terminal:

pipx install git+https://github.com/agent-on-rails/agent-on-rails-cli.git
aor --version

2. Bootstrap folder control plane

Agent On Rails menyimpan docs dan specs di folder kontrak — bukan di repo aplikasi. Init membuat AGENTS.md, product/, specs/, adr/, policies/, dan plans/. Belum ada apps/.

aor init ./survey-desk --name SurveyDesk
cd survey-desk

Dari wizard desktop: pilih folder, isi SurveyDesk sebagai nama produk, lalu lanjut ke Gather. Wizard menjalankan aor init untuk Anda sebelum extract.

3. Gather dari bahasa alami

Ini cerita produk SurveyDesk yang kami pakai sebagai input gather. Simpan sebagai requirements.md (atau tempel di wizard desktop), lalu jalankan aor gather. Ketika teksnya cocok dengan SurveyDesk seperti ini, Agent On Rails menulis paket referensi lengkap — bukan stub yang dipotong per kalimat.

Build a product called SurveyDesk: a local-first survey desk. No cloud tenant, no login for respondents.

Operators use native mobile apps only (Swift + SwiftUI on iPhone and iPad Simulator; Kotlin + Jetpack Compose on Android phone and tablet Emulator). They create surveys, drag-and-drop reorder form fields, open (start) and close (end) collection, copy a public URL, and watch results refresh within 2 seconds. Operator UI is English. iPad and Android tablet use a left sidebar + detail; phones use a stack. Block FormSpec edits while a survey is open.

Respondents use a public React + Next.js web app. Anonymous — no account. They fill an open survey at /s/{publicSlug} and see a thank-you state. Optional public live results when showPublicResults is true.

Local HTTP JSON API (default 127.0.0.1:8787) over SQLite (./data/survey-desk.sqlite). Reference implementation: Python 3.11+ FastAPI (language-neutral OpenAPI — Java or any language welcome). Lifecycle: draft → open → closed. Reject submit unless open; reject FormSpec patch while open; close rejects further responses.

Form fields: short_text, long_text, single_choice, multi_choice, rating_1_5, yes_no.

Brand: primary #0878F8, ink #001838, green #10A868, purple #7828F8, rating gold #F8B000. Transparent logo in chrome, not an opaque JPG plate.

Non-goals: multi-tenant SaaS, SSO, email invites, SurveyMonkey parity, complex branching, payments, file uploads, non-English UI.

Demo: create “Session feedback”, add rating + single choice + short text, open, anonymous web submit, instant results, close, further submit rejected.

Lalu gather (LLM opsional; --stub bekerja offline untuk paket referensi yang sama ketika NL mirip SurveyDesk):

# Optional: OpenAI-compatible endpoint (omit + use --stub offline)
export AOR_LLM_BASE_URL=https://ai.dentalimplantsandveneers.com.au/v1
export AOR_LLM_API_KEY=…

# Save the story above as requirements.md, then:
aor gather run --file ./requirements.md --force
# shows outline → type y to confirm → writes specs/

# Same story, offline:
aor gather run --stub --force --file ./requirements.md

1. 01Extract outline (nama produk, visi, judul requirement, ADR).
2. 02Manusia mengonfirmasi atau mengedit outline — belum ada yang ditulis.
3. 03Setelah konfirmasi, tulis paket referensi SurveyDesk di bawah specs/.
4. 04Tempel specs/regeneration/source-requirements.md dengan NL yang ditangkap.

Di wizard desktop loop yang sama visual: tempel cerita di atas → Extract outline → Confirm & write drafts. Gunakan --force (default on di wizard) jika Anda mengganti paket stub sebelumnya.

4. Periksa pohon spesifikasi

ls specs/product specs/requirements specs/domain specs/api specs/adr specs/acceptance specs/regeneration
ls specs/requirements
# SD-001-product-surfaces.md … SD-012-acceptance.md

Anda harus melihat dua belas file requirement SD-* dengan judul nyata (Product surfaces, Local-first, Form Spec, …) — bukan fragmen seperti “called SurveyDesk: a”. Itu bug stub lama; gather sekarang menulis paket referensi untuk NL mirip SurveyDesk.

5. Setujui sebelum agent mengimplementasi

Draft belum menjadi otoritas. Buka aor (TUI), review SD-001…SD-012 dan ADR, lalu setujui spesifikasi yang siap dibangun. Baru kemudian plan → run → serahkan task terbatas ke Cursor / Claude / Codex.

1. aor — buka terminal UI
2. Review specs → Approve (hanya manusia)
3. Plan spesifikasi yang disetujui → Run → implementasi di sibling app repo
4. Evidence + final review manusia sebelum done

Mengapa SurveyDesk menjadi template

Produk lain tetap mendapat layout berbentuk SurveyDesk dari gather — folder sama, draft yang digenerate. SurveyDesk sendiri dikhususkan karena kami sudah membuktikan paket lengkap: domain FormSpec, kontrak UX operator mobile, prompt regenerasi P1–P6. Itulah bentuk yang kami inginkan sebagai awal setiap proyek SDD yang serius.

• Situs produk + unduhan: https://agent-on-rails.suherman.net
• Dokumentasi setup: https://agent-on-rails.suherman.net/docs
• Terkait: Spec-Driven Development di situs ini — https://suherman.net/id/articles/spec-driven-development
• Terkait: Eskalasi & watchdog Agent On Rails — https://suherman.net/id/articles/agent-on-rails-escalation-watchdog

Intinya: jangan menyerahkan ide SurveyDesk kosong ke coding agent. Pasang Agent On Rails, init folder kontrak, gather cerita SurveyDesk, konfirmasi outline, dan jadikan paket spesifikasi referensi sebagai otoritas. Setujui apa yang akan dibangun. Baru — dan hanya setelah itu — biarkan agent mengimplementasi terhadap SD-001…SD-012.