rodo-spec 0.0.0-stage → 2.2.0

package/dist/kit/project-template/RULES.md

@@ -0,0 +1,278 @@
+# روش RODO: راهنمای آدم‌ها (نسخهٔ کیت ۲.۲.۰)
+
+> این فایل برای شماست، نه برای AI. AI همین قواعد را از `.agents/skills/rodo/` می‌خواند.
+> اگر فقط ۲ دقیقه وقت دارید، «شروع سریع» و بخش ۱، ۳ و ۴ را بخوانید.
+
+## شروع سریع
+
+1. نیازتان را ساده به AI بگویید. AI فایل `AGENTS.md` را می‌خواند، **یک کارت** برنامه‌ریزی می‌کند و `simple.md` (چه چیزی می‌گیرید) و `spec.md` (قواعد فنی) را می‌نویسد.
+2. `simple.md` را بخوانید. اگر چیزی درست نیست بگویید؛ AI پیش از کدنویسی کارت را درست می‌کند.
+3. AI کارت را قدم‌به‌قدم انجام می‌دهد. با `rodo status` و `rodo resume` می‌بینید کجاست.
+4. وقتی کارت تمام شد، AI فایل `MAP.md` (چه تمام شد) و `MEMORY.md` (تصمیم‌ها) را به‌روز می‌کند.
+5. تغییرهای خیلی کوچک کارت نمی‌خواهند؛ یک خط در `CHANGELOG.md` کافی است.
+6. اختیاری: با `rodo init` به برد وصل شوید تا کارت‌ها را در وب ببینید؛ `rodo sync` دو طرف را هم‌گام نگه می‌دارد.
+
+دستورهای مفید: `rodo new "عنوان"` (پوشهٔ کارت تازه با فایل‌هایش)، `rodo validate`، `rodo status`، `rodo resume`، `rodo test`، `rodo doctor`.
+
+
+---
+
+## ۱. این روش در یک نگاه
+
+RODO یک **روش کار** است، نه یک نگهبان. هیچ ابزاری جلوی ذخیره کردن کار (commit) یا ادامهٔ کار را نمی‌گیرد. AI این روش را دنبال می‌کند چون پروژه را برای شما، هم‌تیمی‌ها و جلسهٔ بعدی AI قابل فهم نگه می‌دارد.
+
+پروژه مثل حافظهٔ آدم سه لایه دارد:
+
+| لایه | مثل | فایل | کی خوانده می‌شود |
+|---|---|---|---|
+| **نقشه** | «الان کجای کاریم؟» | `rodo/<پروژه>/MAP.md` و `MEMORY.md` | همیشه، اول از همه |
+| **قانون** | «چطور کار می‌کنیم؟» | مهارت `.agents/skills/rodo/` | یک بار در هر جلسه |
+| **پرونده** | «جزئیات همین کار» | پوشهٔ هر کارت در `rodo/<پروژه>/cycles/` | فقط وقتی لازم است |
+
+**سه کاری که AI همیشه می‌کند:**
+1. اول نقشه و حافظه را می‌خواند.
+2. **سندهای پروژه را می‌سازد و درست نگه می‌دارد.** اگر کد چیزی را عوض کند که در سندی نوشته شده، همان سند را هم درست می‌کند.
+3. **برای هر قابلیت، تغییر یا بهبود تازه یک کارت می‌سازد** و از روی کارت کار می‌کند. فقط تغییرهای خیلی کوچک (بخش ۴) کارت نمی‌خواهند.
+
+**دو نقش AI داریم:** **برنامه‌ریز** (نیاز شما را به کارت و سند تبدیل می‌کند؛ برای این نقش یک مدل قوی پیشنهاد می‌شود) و **کدنویس** (کارت را قدم‌به‌قدم انجام می‌دهد). انتخاب مدل با شماست.
+
+---
+
+## ۲. پوشه‌ها و فایل‌ها
+
+```
+AGENTS.md                      اشاره‌گر به مهارت
+.agents/skills/rodo/           مهارت AI (مال کیت است؛ rodo init به‌روزش می‌کند)
+rodo/
+├── kit.json                   نسخهٔ کیت نصب‌شده
+└── <پروژه>/                   هر پوشه با project.json یک پروژه است و به یک برد وصل است
+    ├── project.json           اتصال به برد و تنظیمات (بدون رمز)
+    ├── MAP.md                 نقشه: پروژه چیست، کجاییم، چه تمام شده، چه لغو شده، بعدی چیست
+    ├── MEMORY.md              تصمیم‌های مهم: هر کدام یک خط با «چون»
+    ├── CHANGELOG.md           تغییرهای کوچک بدون کارت: هر کدام یک خط
+    ├── RULES.md               همین فایل
+    ├── project/
+    │   ├── brief.md           پروژه به زبان ساده
+    │   ├── architecture.md    بخش‌ها و فناوری‌ها، و چرا
+    │   └── glossary.md        واژه‌های پروژه و معنی‌شان
+    ├── inbox/                 کارت‌هایی که در وب ساخته شده‌اند (در Git نیست)
+    └── cycles/
+        └── 002-discount-code/    یک کارت و سندهایش (هیچ‌وقت جابه‌جا نمی‌شود)
+            ├── card.rodo.md          کارت: وضعیت، قدم‌ها، یادداشت پیشرفت (با برد RODO هم‌گام می‌شود، در Git نیست)
+            ├── simple.md             توضیح ساده (پیشنهادی؛ در وب فقط‌خواندنی نشان داده می‌شود)
+            ├── spec.md               سند فنی با قانون‌های شماره‌دار R1، R2، ... (پیشنهادی برای قابلیت‌ها)
+            ├── design.md             طراحی (فقط برای کار بزرگ)
+            └── acceptance.feature    سناریوهای تست (اختیاری، پیشنهادی)
+```
+
+- **چرخه** یعنی یک کارت به‌علاوهٔ سندهایش. نام پوشه: سه رقم + نام کوتاه انگلیسی، مثل `002-discount-code`.
+- **کارت‌ها (`*.rodo.md`) در Git نیستند**؛ از راه برد RODO بین دستگاه‌ها می‌روند. بقیهٔ فایل‌های `rodo/` در Git هستند.
+- **زبان:** سندهای ساده فارسی، سندهای فنی انگلیسی (در `project.json` قابل تغییر).
+- **وضعیت کارت** همیشه یکی از این پنج تاست:
+
+| وضعیت | یعنی | چه کسی می‌گذارد |
+|---|---|---|
+| `todo` | برنامه‌ریزی شده، هنوز شروع نشده | برنامه‌ریز |
+| `in_progress` | در حال کار | کدنویس، وقتی کار را شروع می‌کند |
+| `blocked` (گیر کرده) | کار جلو نمی‌رود: AI دو بار روی یک مشکل شکست خورده، یا منتظر چیزی است (جواب شما، یک رمز یا کلید دسترسی، کارت دیگر). دلیلش به زبان ساده در کلید `statusReason:` بالای کارت نوشته می‌شود، و «نوع مانع» (`blockerType`) هم دارد | خود AI؛ به شما هم می‌گوید |
+| `cancelled` (لغوشده) | شما تصمیم گرفتید این کار انجام نشود. کارت **پاک نمی‌شود**؛ دلیل در کلید `statusReason:` و یک خط در `MAP.md` زیر «لغوشده» | فقط با اجازهٔ شما |
+| `done` | تمام شده (و اگر کارت تست دارد، تست‌ها پاس شده‌اند) | کدنویس |
+- **قالب کارت را ابزار RODO (watcher) بررسی می‌کند** و اشکال‌ها را به شکل هشدار یا خطا در ترمینال و در وب نشان می‌دهد. این بررسی هیچ‌وقت جلوی کار یا commit را نمی‌گیرد.
+
+---
+
+## ۳. چرخهٔ کار
+
+| قدم | چه کسی | چه اتفاقی می‌افتد |
+|---|---|---|
+| ۱ | **شما** | نیازتان را ساده می‌گویید. |
+| ۲ | **برنامه‌ریز** | کارت و سندها را می‌سازد: توضیح ساده، سند فنی، و اگر بخواهید سناریوهای تست. |
+| ۳ | **شما (اختیاری)** | اگر خواستید، `simple.md` و سناریوها را می‌خوانید و در وب قدم «تأیید کاربر» را تیک می‌زنید. اگر کارت این قدم را دارد، کدنویس تا تیک شما صبر می‌کند. |
+| ۴ | **کدنویس** | قدم‌ها را یکی‌یکی انجام می‌دهد و تیک می‌زند. آخر هر جلسه «یادداشت پیشرفت» را به‌روز می‌کند. |
+| ۵ | **تست (اختیاری، پیشنهادی)** | اگر کارت سناریو دارد، Playwright آن‌ها را واقعاً اجرا می‌کند. قدم «تست پذیرش پاس شد» فقط بعد از اجرای موفق تیک می‌خورد. |
+| ۶ | **کدنویس** | بستن: کارت `done`، یک خط در `MAP.md` زیر «انجام‌شده»، تصمیم‌ها در `MEMORY.md`. |
+
+**تأیید و تست اختیاری‌اند،** ولی پیشنهاد می‌شوند: تأیید وقتی چیزی که کاربر می‌بیند عوض می‌شود، و تست برای هر قابلیت. هیچ وضعیتی به آن‌ها گره نخورده.
+
+**یک قانون مهم دربارهٔ تست:** AI هیچ‌وقت حق ندارد سناریو یا تست را ضعیف کند تا کدش پاس شود (مثلاً سناریو را پاک کند یا عدد درست را به عدد غلط تغییر دهد).
+
+---
+
+## ۴. کی کارت لازم است و کی نه؟
+
+AI قبل از هر تغییر این سؤال را از خودش می‌پرسد:
+
+> **بعد از این تغییر، آیا جمله‌ای در یک کارت، `simple.md`، یک قانون `spec.md` یا یک سناریو غلط می‌شود، یا کاربر چیز متفاوتی می‌بیند یا می‌تواند انجام دهد؟**
+
+- **نه ← تغییر کوچک، بدون کارت.** AI فقط یک خط به `CHANGELOG.md` اضافه می‌کند: تاریخ، چه چیزی عوض شد، چرا، و کدام فایل‌ها.
+  `- 2026-10-14 | رنگ دکمهٔ «افزودن به سبد» سبز شد | خواستهٔ مریم برای دیده شدن بهتر | src/catalog.css`
+- **بله ← کارت.** اگر کارتی باز (`todo`، `in_progress` یا `blocked`) همین رفتار را توضیح می‌دهد، همان کارت و سندهایش به‌روز می‌شوند؛ وگرنه کارت تازه ساخته می‌شود.
+- **مطمئن نیست ← کارت**، یا از شما می‌پرسد.
+
+| تغییر | کارت؟ | چرا |
+|---|---|---|
+| غلط املایی در توضیح کد یا یک سند | نه | رفتار همان است |
+| غلط املایی در متنی از صفحه که هیچ سناریو یا spec آن را نقل نکرده | نه | چیزی که نوشته شده غلط نمی‌شود |
+| مرتب کردن کد (عوض کردن نام متغیر، تکه کردن تابع)، تست‌ها هنوز پاس | نه | رفتار همان است |
+| رنگ، فاصله یا فونتی که هیچ سناریو یا spec به آن اشاره نکرده | نه | فقط ظاهر |
+| به‌روز کردن یک کتابخانه بدون تغییر قابل دیدن | نه | رفتار همان است |
+| باگ: کد کاری را که spec و سناریو می‌گویند درست انجام نمی‌داد و حالا انجام می‌دهد | نه | سندها از اول درست بودند |
+| متن دکمه‌ای که یک سناریو نقلش کرده («اعمال» ← «اعمال کد») | **بله** | جملهٔ سناریو غلط می‌شود |
+| پیام خطایی که یک قانون spec کلمه‌به‌کلمه آورده | **بله** | قانون عوض می‌شود |
+| حداقل خرید از ۲۰۰ به ۱۵۰ هزار تومان | **بله** | عدد یک قانون عوض می‌شود |
+| دکمه، فیلد، صفحه یا گزینهٔ تازه | **بله** | رفتار تازه = کارت تازه |
+
+---
+
+## ۵. وسط کار نظرم عوض شد
+
+| کی | چه کنیم |
+|---|---|
+| **قبل از شروع کدنویسی** | همان کارت و سندهایش ویرایش می‌شوند. |
+| **وسط کدنویسی، تغییر کوچک** (همان قابلیت) | AI کارت، سناریو و spec همان کارت را به‌روز می‌کند و به شما می‌گوید چه عوض شد. |
+| **قابلیت بزرگ تازه** | کارت تازه. کارت جاری بزرگ نمی‌شود. |
+
+---
+
+## ۶. کار گیر کرد یا نیمه‌کاره ماند
+
+- **یادداشت پیشرفت:** هر کارت فعال یک بخش `## Progress notes` دارد که AI آخر هر جلسه پر می‌کند:
+  ```
+  - Updated: 2026-10-12
+  - Done: کادر کد تخفیف ساخته شد
+  - Remaining: پیام خطای تاریخ گذشته
+  ```
+  پس جلسهٔ بعد (حتی با مدل یا آدم دیگر) می‌داند از کجا ادامه دهد.
+- **دو بار شکست روی یک مشکل:** AI می‌ایستد، وضعیت کارت را `blocked` می‌کند و در کلید `statusReason:` به زبان ساده می‌نویسد چه شده. مثلاً:
+  `statusReason: پیام خطای «کد منقضی شده» نشان داده نمی‌شود؛ دو راه را امتحان کردم و نشد`
+  **شما تصمیم می‌گیرید:** توضیح بیشتر، امتحان با مدل قوی‌تر، یا لغو.
+- **منتظر چیزی:** اگر AI بدون چیزی که خودش نمی‌تواند فراهم کند جلو نمی‌رود (جواب شما، کلید دسترسی یک سرویس، تمام شدن کارت دیگر)، باز هم `blocked`:
+  `statusReason: منتظر کلید API سرویس پیامک از مسعود`
+- **گیر باز شد:** وضعیت به `in_progress` برمی‌گردد و `statusReason` و `blockerType` برداشته می‌شوند.
+- **لغو:** فقط با اجازهٔ شما. وضعیت کارت `cancelled` می‌شود، دلیل در `statusReason:` نوشته می‌شود، چرخه در `MAP.md` زیر «لغوشده» با همان دلیل نوشته می‌شود و یک خط در `MEMORY.md`. **کارت و پوشه و سندهایش پاک نمی‌شوند** تا بعداً معلوم باشد چه چیزی و چرا کنار گذاشته شد. اگر بعداً پشیمان شدید، به AI بگویید؛ کارت دوباره `todo` می‌شود.
+
+---
+
+## ۷. باگ‌ها
+
+- **رفتار توضیح‌داده‌شده عوض می‌شود:** کارت.
+- **رفتار عوض نمی‌شود** (کد کاری را که سندها می‌گویند درست انجام نمی‌داد): رفع + یک خط در `CHANGELOG.md`.
+
+---
+
+## ۸. قانون‌های طلایی
+
+1. **اول نقشه.** هر جلسهٔ AI با `rodo sync` و `rodo resume` شروع می‌شود (نقشه و حافظه هم خوانده می‌شوند).
+2. **هر قابلیت، تغییر یا بهبود = یک کارت.** تغییر کوچک بی‌اثر بر رفتار = یک خط CHANGELOG.
+3. **سندها همیشه درست.** کدی که سند را غلط کند، سند را هم درست می‌کند.
+4. **تأیید و تست اختیاری ولی پیشنهادی.** ولی تست هیچ‌وقت ضعیف نمی‌شود تا پاس شود.
+5. **دو شکست پشت سر هم = توقف و پرسیدن از شما.**
+6. **هیچ چیزی پاک نمی‌شود** مگر شما بگویید.
+7. **`MAP.md` و `MEMORY.md` آخر هر کارت به‌روز می‌شوند،** نه وسط کار؛ چون اگر چند نفر هم‌زمان این دو فایل را عوض کنند، Git تداخل (merge conflict) می‌گیرد.
+8. **کارت‌ها در Git نیستند؛ سندها هستند.**
+
+---
+
+## شروع و پایان هر جلسهٔ AI
+- **شروع:** AI اول فقط نگاه می‌کند که مخزن گیت از نسخهٔ دور عقب است یا نه. خودش `git pull`، `git fetch`، `git merge` یا `git rebase` نمی‌زند. اگر عقب باشد، یک بار به شما می‌گوید تا خودتان به‌روز کنید، و با فایل‌های موجود ادامه می‌دهد. فایل کارت با `rodo sync` می‌آید؛ نقشه، حافظه، مشخصات و `simple.md` با گیت. بعد `rodo sync` و `rodo resume` را اجرا می‌کند و فقط فایل‌هایی را می‌خواند که کارت به آن‌ها ارجاع داده است.
+- **پایان:**
+  - AI «یادداشت پیشرفت» را به‌روز می‌کند؛
+  - اگر کارت تست دارد، `rodo test` را اجرا می‌کند؛
+  - آخر سر `rodo sync` را اجرا می‌کند تا کارت‌ها به سایت بروند.
+- اگر اینترنت یا سرور در دسترس نباشد، کار ادامه پیدا می‌کند و چیزی گم نمی‌شود. sync بعدی همه را می‌فرستد.
+
+## گیر کردن
+- «گیر کرده» یک نوع دارد:
+  - تصمیم: شما باید انتخاب کنید؛
+  - نیازمندی: هدف روشن نیست؛
+  - فنی؛
+  - تست؛
+  - محیط: ابزار یا سرور؛
+  - بیرونی: منتظر کسی یا چیزی؛
+  - دسترسی: کلید یا اجازه کم است.
+- دلیل آن هم به زبان ساده در کلید `statusReason:` بالای کارت نوشته می‌شود.
+- اگر **یک خطای یکسان دو بار** پیش بیاید، AI می‌ایستد و کارت را «گیر کرده» می‌کند. خطاهای مختلف حساب نمی‌شوند.
+
+## نیاز به تصمیم
+- وقتی فقط شما می‌توانید انتخاب کنید، AI یک سؤال با چند گزینه در کارت می‌نویسد. کارت «گیر کرده (تصمیم)» می‌شود.
+- شما در سایت، روی کارت، یکی از گزینه‌ها را انتخاب می‌کنید (یا جواب خودتان را می‌نویسید).
+- AI در جلسهٔ بعد جواب را می‌خواند و ادامه می‌دهد. AI هرگز به‌جای شما جواب نمی‌دهد.
+
+## محدوده
+- کارت می‌تواند بگوید چه کارهایی **مجاز** و چه کارهایی **ممنوع** است.
+- اگر AI به کاری خارج از محدوده برسد، آن را بی‌صدا انجام نمی‌دهد. در یادداشت پیشرفت می‌نویسد و یک کارت تازه پیشنهاد می‌دهد.
+
+## پاک شدن بیش از ۱۰ کارت
+
+اگر `rodo sync` بگوید بیش از ۱۰ کارت پاک شده (`ARCHIVE_CONFIRM_REQUIRED`)، AI باید **بایستد و از شما بپرسد**. خودش تأیید نمی‌کند و هشدار را نادیده نمی‌گیرد.
+
+## رمزها
+- هیچ رمز، کلید یا توکنی در فایل‌های RODO، کارت‌ها یا پیام‌ها نوشته نمی‌شود.
+- اگر `rodo sync` چیزی شبیه رمز ببیند، آن کارت را نمی‌فرستد و خطا می‌دهد.
+
+## برد تازه
+- فقط خود شما می‌توانید با `rodo init` در ترمینال برد تازه بسازید. باید نام برد را تایپ کنید.
+- AI هرگز برد نمی‌سازد.
+
+## سه اندازهٔ کار
+- **کار کوچک:** مثل درست کردن یک غلط املایی. کارت لازم ندارد و سؤالی پرسیده نمی‌شود. فقط یک خط در `CHANGELOG.md` نوشته می‌شود.
+- **کار معمولی:** مثل یک قابلیت ساده. یک توضیح ساده (`simple.md`) و یک سند فنی دارد.
+- **کار بزرگ:** مثل وصل شدن به درگاه پرداخت. علاوه بر آن‌ها یک سند طراحی هم دارد، و بهتر است یک AI دیگر کار را بازبینی کند.
+- اگر AI شک داشته باشد که کار کوچک است یا نه، آن را کوچک حساب نمی‌کند (کارت می‌سازد). اگر بین معمولی و بزرگ شک داشته باشد، معمولی را انتخاب می‌کند و به شما می‌گوید.
+
+## فقط سؤال‌های مهم
+- AI قبل از برنامه‌ریزی فقط سؤالی را می‌پرسد که جوابش نتیجهٔ کار را عوض می‌کند، یا برگرداندنش گران است.
+- هر بار حداکثر ۵ سؤال، و بیشتر با گزینه‌های آماده. کنار هر سؤال می‌گوید اگر نظری نداشته باشید چه چیزی را انتخاب می‌کند.
+- برای چیزهای کم‌اهمیت خودش یک انتخاب امن می‌کند و آن را یادداشت می‌کند.
+- سؤالی که وسط کار پیش بیاید و کار بدون جواب شما جلو نرود، همان «نیاز به تصمیم» است و روی سایت جواب می‌دهید.
+
+## سندها همیشه با کد یکی‌اند
+- قبل از کار، AI می‌نویسد کدام سندهای فعلی پروژه با این تغییر عوض می‌شوند.
+- آخر کار بررسی می‌کند که آن سندها واقعاً به‌روز شده باشند و هنوز با کد بخوانند.
+- سندهای کارهای تمام‌شده یا لغوشده هرگز بازنویسی نمی‌شوند؛ تصمیم تازه در کارت تازه و در `MEMORY.md` نوشته می‌شود.
+- RODO خودش چیزی را اجرا نمی‌کند؛ فقط می‌گوید کدام بررسی‌ها برای این کار مناسب است و ابزارهای خود پروژه آن‌ها را اجرا می‌کنند.
+
+---
+
+## ۹. مثال کوتاه: فروشگاه گل مریم
+
+مریم یک گل‌فروشی در شیراز دارد (نمونهٔ کامل در پوشهٔ `example/` کیت).
+
+1. **مریم:** «یه کد تخفیف ده درصدی می‌خوام، فقط برای خریدهای بالای دویست تومن، تا آخر آبان.»
+2. **برنامه‌ریز** کارت `002-discount-code` را می‌سازد. در `spec.md` قانون‌ها شماره دارند، مثلاً **R2**: «جمع سبد باید دست‌کم ۲۰۰٬۰۰۰ تومان باشد». مریم تست می‌خواهد، پس سناریوها هم نوشته می‌شوند و سناریوی مربوط برچسب `@R2` می‌گیرد. مریم تأیید هم می‌خواهد، پس اولین قدم کارت «تأیید کاربر» است.
+3. **مریم** در وب دو فایل را می‌خواند و قدم «تأیید کاربر» را تیک می‌زند.
+4. **کدنویس** قدم‌ها را انجام می‌دهد و آخر جلسه می‌نویسد: `Done: فهرست کدها و تابع applyDiscount`، `Remaining: کادر کد در صفحهٔ سبد`.
+5. **تست:** سناریوی «حروف کوچک» رد می‌شود. کدنویس **کد را درست می‌کند، نه سناریو را**. بار دوم همه پاس می‌شوند.
+6. **بستن:** کارت `done`، یک خط در `MAP.md` و یک تصمیم در `MEMORY.md`: «هر سفارش فقط یک کد تخفیف می‌گیرد. چون مریم نمی‌خواهد تخفیف‌ها روی هم جمع شوند.»
+
+**یک تغییر کوچک:** مریم: «رنگ دکمه رو سبز کن.» هیچ سناریویی دربارهٔ رنگ نیست، پس کارت لازم نیست؛ AI یک خط به `CHANGELOG.md` اضافه می‌کند.
+**یک تغییر نه‌چندان کوچک:** مریم: «متن دکمهٔ "اعمال" رو بکن "اعمال کد".» یک سناریو می‌گوید «"اعمال" را می‌زند»، پس این تغییر کارت می‌خواهد (یا به‌روز کردن کارت بازِ همان قابلیت).
+**یک کارت لغوشده:** کادوپیچی (`003-gift-wrap`) لغو شد چون مریم فعلاً کادوپیچی نمی‌کند. کارتش با `status: cancelled` و `statusReason: مریم فعلاً کادوپیچی نمی‌کند` مانده و در `MAP.md` زیر «لغوشده» با همین دلیل آمده.
+
+---
+
+## ۱۰. ابزارها
+
+| ابزار | کارش |
+|---|---|
+| `rodo init` | کیت را نصب یا به‌روز می‌کند و پروژه را به یک برد وصل می‌کند. برد تازه فقط با تایپ نام برد ساخته می‌شود |
+| `rodo sync` | اول و آخر هر جلسه: کارت‌ها را با برد هم‌گام می‌کند |
+| `rodo resume` | خلاصهٔ کار برای شروع یک جلسهٔ تازه |
+| `rodo status` | برد و فایل‌های محلی را کنار هم نشان می‌دهد |
+| `rodo test` | دستور تست کارت را اجرا و امضای شکست را ثبت می‌کند |
+| `rodo validate` | قالب کارت‌ها را بررسی می‌کند و فقط گزارش می‌دهد |
+| `rodo doctor` | مشکل‌های راه‌اندازی را پیدا می‌کند |
+
+---
+
+## ۱۱. سؤال‌های رایج
+
+**باید Gherkin یاد بگیرم؟** نه. سناریو را مثل یک داستان کوتاه بخوانید: «اگر این باشد، وقتی این کار را بکنم، این را می‌بینم.»
+
+**اگر AI تیک «تأیید کاربر» را در فایل بزند؟** فایده ندارد. سرور RODO تیک این قدم را فقط از وب و از یک آدم می‌پذیرد و watcher فایل را به حالت سرور برمی‌گرداند.
+
+**اگر AI فایل کارت را خراب کند؟** watcher در خط اول کارت `<!-- RODO_ERROR: ... -->` می‌نویسد و اشکال را در ترمینال و وب نشان می‌دهد. AI یا شما درستش می‌کنید؛ خط خطا خودش پاک می‌شود. کار و commit هیچ‌وقت متوقف نمی‌شوند.
+
+**فرق `blocked` و `cancelled` چیست؟** `blocked` یعنی «فعلاً نمی‌شود، ولی هنوز می‌خواهیم»؛ با رفع مشکل ادامه پیدا می‌کند. `cancelled` یعنی «دیگر نمی‌خواهیم»؛ فقط شما می‌توانید آن را بگویید.
+
+**کدام مدل AI؟** انتخاب شما. فقط برای برنامه‌ریزی یک مدل قوی پیشنهاد می‌شود، چون اشتباه در برنامه گران‌تر از اشتباه در یک قدم کد است.

package/dist/kit/project-template/project/architecture.md

@@ -0,0 +1,19 @@
+# معماری
+
+## بخش‌ها
+
+| بخش | فناوری | مسیر در مخزن | چرا این انتخاب |
+|---|---|---|---|
+| {{مثلاً وب‌سایت}} | {{Next.js}} | `{{src/}}` | {{دلیل}} |
+
+## دادهٔ اصلی
+
+{{موجودیت‌ها و رابطه‌هایشان، کوتاه}}
+
+## تست
+
+- تست پذیرش (اختیاری، پیشنهادی): `playwright-bdd`. سناریوها در `rodo/<project>/cycles/*/acceptance.feature`، step definitionها در `{{e2e/steps/}}`. همه: `{{npm run test:acceptance}}`. چرخه‌های لغوشده برچسب `@cancelled` دارند و در `playwright.config` با `tags: 'not @cancelled'` کنار گذاشته می‌شوند. یک چرخه: دستور `testCommand` در `project.json`.
+
+## قواعدی که همه باید بدانند
+
+- {{مثلاً: همهٔ قیمت‌ها به تومان و عدد صحیح ذخیره می‌شوند}}

package/dist/kit/project-template/project/brief.md

@@ -0,0 +1,17 @@
+# {{نام پروژه}} به زبان ساده
+
+## برای چه کسی است
+
+{{مشتری یا کاربر اصلی، یک جمله}}
+
+## چه مشکلی را حل می‌کند
+
+{{دو یا سه جمله}}
+
+## چه چیزی را عمداً انجام نمی‌دهد
+
+- {{مثلاً: ارسال به شهرهای دیگر}}
+
+## موفقیت یعنی چه
+
+- {{یک نشانهٔ قابل اندازه‌گیری}}

package/dist/kit/project-template/project/glossary.md

@@ -0,0 +1,7 @@
+# واژه‌نامه
+
+> هر واژه همان معنایی را دارد که اینجا نوشته شده؛ در سناریوها و spec همین واژه‌ها به کار می‌روند.
+
+| واژه | معنی | در کد |
+|---|---|---|
+| {{سبد خرید}} | {{فهرست محصولاتی که مشتری هنوز نخریده}} | `{{Cart}}` |

package/dist/kit/project-template/project.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 2,
+  "projectSlug": "{{slug}}",
+  "name": "{{name}}",
+  "serverUrl": null,
+  "boardId": null,
+  "repoFingerprint": null,
+  "language": { "simple": "fa", "technical": "en" },
+  "testCommand": null,
+  "stepsDirs": []
+}

package/dist/kit/project-template-en/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Small changes
+
+> One line for every small change that does not change behaviour described in a card, spec or scenario (no card needed).
+> Format: `- YYYY-MM-DD | what changed | why | files`
+
+- {{DATE}} | added the RODO method | so the AI and people work from one map and current docs | `rodo/`

package/dist/kit/project-template-en/MAP.md

@@ -0,0 +1,24 @@
+# Project map: {{name}}
+
+> Every card and its docs live in `rodo/<project>/cycles/NNN-slug/`. Update this file when a card is finished or cancelled (not in the middle of coding), so several people can work at once without Git conflicts. The state of current work is in the cards.
+> Keep it short (about 40 lines). Read this first.
+
+## What this project is
+
+{{one or two plain sentences}}
+
+## Where we are
+
+{{one or two sentences: the last thing that was finished}}
+
+## Done
+
+> One line per finished cycle: a link to the cycle, e.g. `- [001 Delete a note](cycles/001-delete-note/simple.md)`.
+
+## Cancelled
+
+> One line per cancelled cycle: the link, then " — ", then the reason.
+
+## Next
+
+- {{next idea}}

package/dist/kit/project-template-en/MEMORY.md

@@ -0,0 +1,6 @@
+# Decision memory
+
+> One line per important decision: what was decided, because why. Added when a card is finished or cancelled. Decisions are never deleted; if one changes, write a new line and say which line it replaces.
+> Format: `- YYYY-MM-DD — decision. Because reason. (cycle NNN)`
+
+- {{DATE}} — The project follows the RODO method. Because the AI and the people should work from one map, cards and up-to-date docs.

package/dist/kit/project-template-en/RULES.md

@@ -0,0 +1,69 @@
+# The RODO method: guide for people (kit 2.2.0)
+
+> This file is for you, not for the AI. The AI reads the same rules from `.agents/skills/rodo/`.
+
+## Quick start (2 minutes)
+
+1. Ask your AI assistant for a feature in plain words. It reads `AGENTS.md`, plans **one card** and writes `simple.md` (what you get) and `spec.md` (the technical rules).
+2. Read `simple.md`. If something is wrong, say so; the AI fixes the card before coding.
+3. The AI codes the card step by step and ticks the checklist. You can follow it with `rodo status` and `rodo resume`.
+4. When the card is done, the AI updates `MAP.md` (what is finished) and `MEMORY.md` (the decisions).
+5. Small fixes that do not change described behaviour get one line in `CHANGELOG.md` instead of a card.
+6. Optional: connect a board with `rodo init` to see and edit the cards on the web; `rodo sync` keeps both sides in step.
+
+Useful commands: `rodo new "<title>"` (a new cycle folder with its files), `rodo validate`, `rodo status`, `rodo resume`, `rodo test`, `rodo doctor`.
+
+## 1. The method at a glance
+
+RODO is a **way of working**, not a gate. No tool blocks a commit or stops work. The AI follows it because it keeps the project understandable for you, your teammates and the next AI session.
+
+| Layer | Like | Files | When it is read |
+|---|---|---|---|
+| **Map** | "Where are we?" | `rodo/<project>/MAP.md`, `MEMORY.md` | always, first |
+| **Rules** | "How do we work?" | `.agents/skills/rodo/` | once per session |
+| **Case file** | "Details of this piece of work" | `rodo/<project>/cycles/NNN-slug/` | only when needed |
+
+The AI always: reads the map first; keeps the docs true (when code changes something a doc describes, the doc changes in the same work); makes a card for every new feature, change or improvement.
+
+## 2. Folders and files
+
+```
+AGENTS.md                      pointer to the skill
+.agents/skills/rodo/           the AI skill (owned by the kit; rodo init updates it)
+rodo/
+├── kit.json                   installed kit version
+└── <project>/
+    ├── project.json           board binding and settings (no secrets)
+    ├── MAP.md                 what the project is, where we are, done, cancelled, next
+    ├── MEMORY.md              important decisions, one line each with "because"
+    ├── CHANGELOG.md           small changes without a card, one line each
+    ├── RULES.md               this file
+    ├── project/               brief, architecture, glossary (always current)
+    └── cycles/NNN-slug/       one folder per card: card.rodo.md, simple.md, spec.md, design.md, acceptance.feature
+```
+
+## 3. Statuses (exactly five)
+
+`todo` planned · `in_progress` being worked on · `blocked` cannot go on (needs `blockerType` and a plain `statusReason`) · `cancelled` you decided not to do it (needs `statusReason`; the card stays) · `done` finished.
+
+## 4. When is a card needed?
+
+For every new feature, change or improvement, and for every change to behaviour that a card, spec or scenario describes. Not for a typo, style, refactor or a fix that does not change described behaviour: those get one `CHANGELOG.md` line.
+
+## 5. Your part
+
+- Answer the AI's questions (it asks only what matters, at most 5 at a time).
+- When a card asks for a decision (`## Decision:`), answer it on the web; the AI never answers for you.
+- Approval steps (`[approval]`) are ticked only by a person, on the web.
+- If the AI says it is stuck (the same failure twice), choose: clarify, try a stronger model, or cancel.
+
+## 6. Cards and Git
+
+- Without a board, card files (`*.rodo.md`) are committed to Git like any other file.
+- With a board, card files live on the board and arrive through `rodo sync`; `rodo init` adds them to `.gitignore`.
+- `rodo sync` never loses your text: when the board wins a conflict, your file is saved in `rodo/<project>/.rodo/conflicts/`.
+
+## 7. Never
+
+- No secrets (passwords, keys, tokens) in any file under `rodo/`, in cards or in commit messages.
+- The AI never deletes files without your OK, never creates boards, and never answers decisions or ticks approvals.

package/dist/kit/project-template-en/project/architecture.md

@@ -0,0 +1,19 @@
+# Architecture
+
+## Parts
+
+| Part | Technology | Path in the repo | Why this choice |
+|---|---|---|---|
+| {{e.g. website}} | {{Next.js}} | `{{src/}}` | {{reason}} |
+
+## Main data
+
+{{entities and how they relate, briefly}}
+
+## Tests
+
+- Acceptance tests are optional and recommended. Scenarios live in `rodo/<project>/cycles/*/acceptance.feature`; one cycle runs with `testCommand` in `project.json` (`{NNN}` is replaced by the cycle number). Cancelled cycles are tagged `@cancelled` and skipped.
+
+## Rules everyone must know
+
+- {{e.g. all prices are stored as whole cents}}

package/dist/kit/project-template-en/project/brief.md

@@ -0,0 +1,17 @@
+# {{name}} in plain words
+
+## Who it is for
+
+{{the main user or customer, one sentence}}
+
+## What problem it solves
+
+{{two or three sentences}}
+
+## What it deliberately does not do
+
+- {{for example: shipping to other cities}}
+
+## What success means
+
+- {{one measurable sign}}

package/dist/kit/project-template-en/project/glossary.md

@@ -0,0 +1,7 @@
+# Glossary
+
+> Each word means exactly what is written here; scenarios and specs use these words.
+
+| Word | Meaning | In the code |
+|---|---|---|
+| {{cart}} | {{the products a customer has not bought yet}} | `{{Cart}}` |

package/dist/kit/project-template-en/project.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 2,
+  "projectSlug": "{{slug}}",
+  "name": "{{name}}",
+  "serverUrl": null,
+  "boardId": null,
+  "repoFingerprint": null,
+  "language": { "simple": "en", "technical": "en" },
+  "testCommand": null,
+  "stepsDirs": []
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "rodo-spec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.2.0",
+  "description": "RODO method CLI \u2014 install the kit, manage cards, sync with the board",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/n3xus-ir/rodo-spec.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/n3xus-ir/rodo-spec#readme",
+  "keywords": [
+    "rodo",
+    "rodo-spec",
+    "kanban",
+    "cli",
+    "spec",
+    "ai-agent"
+  ],
+  "bin": {
+    "rodo": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "pnpm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@rodo/card-format": "workspace:*",
+    "@rodo/protocol": "workspace:*",
+    "@rodo/rodo-kit": "workspace:*",
+    "@types/node": "^22.0.0",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "yaml": "^2.7.0"
+  }
+}