rodo-spec 2.2.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +286 -286
  3. package/dist/index.js +20 -3
  4. package/dist/kit/.agents/skills/rodo/SKILL.md +5 -2
  5. package/dist/kit/.agents/skills/rodo/coder.md +2 -1
  6. package/dist/kit/.agents/skills/rodo/onboarding.md +1 -1
  7. package/dist/kit/.agents/skills/rodo/planner.md +1 -0
  8. package/dist/kit/.agents/skills/rodo/project-docs.md +41 -0
  9. package/dist/kit/KIT_VERSION +1 -1
  10. package/dist/kit/MIGRATION.md +10 -0
  11. package/dist/kit/agents-block.md +1 -1
  12. package/dist/kit/kit-manifest.json +38 -13
  13. package/dist/kit/project-template/RULES.md +10 -2
  14. package/dist/kit/project-template/project/how-it-works.md +13 -0
  15. package/dist/kit/project-template/project/project-overview.md +15 -0
  16. package/dist/kit/project-template-en/RULES.md +10 -3
  17. package/dist/kit/project-template-en/project/how-it-works.md +13 -0
  18. package/dist/kit/project-template-en/project/project-overview.md +15 -0
  19. package/package.json +50 -50
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 RODO contributors
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 RODO contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,286 +1,286 @@
1
- # rodo-spec
2
-
3
- [![npm version](https://img.shields.io/npm/v/rodo-spec.svg)](https://www.npmjs.com/package/rodo-spec)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
5
- [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
6
-
7
- > **RODO is a way of working, not a gate.**
8
- > It structures autonomous engineering cycles into predictable, reviewable, and human-aligned iterations through plain Markdown specifications and deterministic CLI automation.
9
-
10
- ---
11
-
12
- ## Overview
13
-
14
- Modern software development often struggles to bridge high-level intentions with concrete agentic or human execution. `rodo-spec` introduces a disciplined protocol and developer toolkit (`rodo`) that captures intent, architecture, constraints, memory, and validation criteria directly in version-controlled Markdown artifacts.
15
-
16
- Whether you run purely offline in **method-only mode** or connect with a shared RODO Kanban server, the framework guarantees that agents and developers always operate with full context, clear guardrails, and deterministic testing criteria.
17
-
18
- ---
19
-
20
- ## Project Layout Tree
21
-
22
- When initialized within a repository, RODO organizes agent capabilities, project knowledge, and cycle specifications into a clean, predictable hierarchy:
23
-
24
- ```text
25
- .
26
- ├── AGENTS.md # Pointer to the RODO skill for AI assistants
27
- ├── .agents/
28
- │ └── skills/
29
- │ └── rodo/ # Agent operational skills, playbooks & templates
30
- └── rodo/
31
- ├── kit.json # Installed RODO kit version & file checksums
32
- └── <project>/
33
- ├── project.json # Project settings & optional board binding (no secrets)
34
- ├── MAP.md # System topology, current state, done & next cycles
35
- ├── MEMORY.md # Append-only cross-cycle decisions & rationale
36
- ├── RULES.md # Human-readable guide to the RODO method
37
- ├── CHANGELOG.md # One-line log for small changes that need no card
38
- ├── project/
39
- │ ├── brief.md # Plain-language project overview
40
- │ ├── architecture.md # Stack, components, data model & test setup
41
- │ └── glossary.md # Domain terms and definitions
42
- └── cycles/
43
- └── NNN-slug/ # Discrete feature/task cycle (e.g., 001-auth-flow)
44
- ├── card.rodo.md # Cycle card metadata, checklist, refs & progress notes
45
- ├── simple.md # Plain-language summary of what the user gets
46
- ├── spec.md # Technical rules (R1, R2...), acceptance & doc impact
47
- ├── design.md # Architectural design (for major changes)
48
- └── acceptance.feature # Optional Gherkin scenarios tagged @R1, @R2...
49
- ```
50
-
51
- ---
52
-
53
- ## Installation
54
-
55
- ### Prerequisites
56
-
57
- - **Node.js**: `>= 20.0.0`
58
- - **npm**, **pnpm**, or **yarn**
59
-
60
- ### Global Install via npm (Recommended)
61
-
62
- ```bash
63
- npm install -g rodo-spec
64
- ```
65
-
66
- Or run directly with `npx`:
67
-
68
- ```bash
69
- npx rodo-spec --help
70
- ```
71
-
72
- ### Install from Source / GitHub
73
-
74
- ```bash
75
- git clone https://github.com/alishafiee1/rodo-spec.git
76
- cd rodo-spec
77
- pnpm install
78
- pnpm run build
79
- npm link --workspace=packages/cli
80
- ```
81
-
82
- ---
83
-
84
- ## Quick Start (Offline / Method-Only Mode)
85
-
86
- You can use RODO as a 100% offline methodology without signing up or connecting to any remote server. In method-only mode, `card.rodo.md` files are tracked directly in Git alongside `simple.md` and `spec.md`.
87
-
88
- ### 1. Initialize your project
89
- ```bash
90
- rodo init --method-only --project myapp --lang en
91
- ```
92
-
93
- ### 2. Scaffold your first cycle card
94
- ```bash
95
- rodo new "My first feature"
96
- ```
97
- This generates `rodo/myapp/cycles/001-my-first-feature/` containing `card.rodo.md`, `simple.md`, and `spec.md` (add `--major` to also generate `design.md` and `acceptance.feature`, or `--slug <kebab-slug>` when the title is non-Latin).
98
-
99
- ### 3. Validate your specifications
100
- Check that your cards and cycle documents meet all format rules:
101
- ```bash
102
- rodo validate --strict
103
- ```
104
-
105
- ### 4. Resume or inspect current progress
106
- ```bash
107
- rodo resume
108
- ```
109
-
110
- ### 5. Run tests associated with the active card
111
- ```bash
112
- rodo test
113
- ```
114
-
115
- ### 6. Review cycle and workspace health
116
- ```bash
117
- rodo status --local
118
- rodo doctor
119
- ```
120
-
121
- ---
122
-
123
- ## Connecting to a RODO Board (3 Ways)
124
-
125
- You can connect an existing method-only project—or initialize a brand-new project—with a RODO Kanban board server (default: `https://rodo.n3xus.ir`) at any time. Connecting binds `rodo/<project>/project.json` to the board and runs the initial sync automatically.
126
-
127
- ### Way 1: One-Step Connect Code from the Web Board (Fastest)
128
- Open your board on the web (`https://rodo.n3xus.ir`), click **"Connect Device" («اتصال دستگاه»)** to generate a one-time code, and run:
129
- ```bash
130
- rodo init --project myapp --connect RODO-XXXX-XXXX
131
- ```
132
- This logs in your device, binds `rodo/myapp/` to that exact board, and syncs all cards in a single step—no separate `rodo login` needed.
133
-
134
- ### Way 2: Log In & Bind to an Existing Board (Interactive List or Board ID)
135
- ```bash
136
- # 1. Authenticate your device (via browser device code or --connect <code>)
137
- rodo login
138
-
139
- # 2a. Pick a board interactively from your workspaces
140
- rodo init --project myapp
141
-
142
- # 2b. Or bind directly by passing the board ID
143
- rodo init --project myapp --board <boardId>
144
- ```
145
-
146
- ### Way 3: Log In & Create a New Board from the Terminal
147
- If your device token was approved with board-creation permission (`boards:create`):
148
- ```bash
149
- rodo login
150
- rodo init --project myapp --create-board
151
- ```
152
- You will be prompted to select the workspace and project and confirm the new board title.
153
-
154
- ### Ongoing Synchronization
155
- Once connected, run `rodo sync` at the start and end of every work session:
156
- ```bash
157
- rodo sync
158
- ```
159
-
160
- - **Default Server**: `https://rodo.n3xus.ir`
161
- - **Custom Server**: Pass `--server <url>` or set `export RODO_SERVER="https://rodo.n3xus.ir"`.
162
-
163
- ---
164
-
165
- ## Commands Table
166
-
167
- The CLI executable is `rodo`. Global flags `--project <slug>`, `--lang <fa|en>`, `--json`, and `--verbose` can be used with any command.
168
-
169
- | Command | Arguments / Flags | Description |
170
- | :--- | :--- | :--- |
171
- | `rodo init` | `[--method-only] [--project <slug>] [--name <name>] [--lang <fa\|en>] [--connect <code>] [--board <id>] [--create-board] [--server <url>] [--no-kit-update] [--dry-run] [--yes-files]` | Installs or updates the RODO kit, scaffolds `rodo/<project>/`, and optionally binds & syncs with a board. |
172
- | `rodo new` | `"<title>" [--slug <kebab-slug>] [--major] [--dry-run] [--project <slug>]` | Creates the next `rodo/<project>/cycles/NNN-slug/` folder with `card.rodo.md`, `simple.md`, and `spec.md`. |
173
- | `rodo resume` | `[card] [--full] [--project <slug>]` | Prints compact context of the active or specified card for an AI session (`--full` includes architecture & `simple.md`). |
174
- | `rodo validate` | `[paths...] [--strict] [--project <slug>]` | Validates card files and cycle references (`--strict` exits with code `1` on errors for CI). |
175
- | `rodo test` | `[card] [--adapter <web\|api\|cli\|mobile\|iot\|other>] [--project <slug>]` | Runs the card's test command and tracks repeated failure signatures (`RODO_STUCK`). |
176
- | `rodo status` | `[--local] [--project <slug>]` | Displays cards and their state side-by-side (board vs. local, or `--local` offline). |
177
- | `rodo sync` | `[--offline] [--dry-run] [--pull-only] [--push-only] [--confirm-archive] [--check] [--project <slug>]` | Pulls, merges, pushes, and writes back card files with the bound RODO board (`--offline` validates only). |
178
- | `rodo doctor` | `[--project <slug>]` | Runs read-only health checks on Node, Git, kit files, `.gitignore`, server connectivity, and cards. |
179
- | `rodo login` | `[--server <url>] [--connect <code>] [--rotate]` | Logs in with a browser device code or a one-time `--connect` code (`--rotate` replaces the current token). |
180
- | `rodo logout` | `[--server <url>]` | Revokes this device token on the server and deletes the local token. |
181
- | `rodo devices` | `[--server <url>]` | Shows the web URL for managing connected devices (`<server>/devices`) and this device's token scopes. |
182
- | `rodo version` | `[--json]` | Displays the CLI version, bundled kit version, and Node.js runtime version. |
183
-
184
- ---
185
-
186
- ## Monorepo Packages
187
-
188
- This repository is maintained as a monorepo consisting of modular packages:
189
-
190
- - **[`packages/protocol`](packages/protocol)**: Wire contract, sync API payload shapes, and card status rules between the CLI and a RODO board server.
191
- - **[`packages/card-format`](packages/card-format)**: Parser, canonical serializer, 3-way merge engine, secret scanner, and validator for `*.rodo.md` files.
192
- - **[`packages/rodo-kit`](packages/rodo-kit)**: Bundled AI skill (`.agents/skills/rodo/`), Persian & English project templates, and migration manifest.
193
- - **[`packages/cli`](packages/cli)**: The end-user command-line binary (`rodo`) published to npm as `rodo-spec`.
194
-
195
- ---
196
-
197
- ## License
198
-
199
- This project is licensed under the [MIT License](LICENSE).
200
-
201
- ---
202
-
203
- ## راهنمای سریع (فارسی)
204
-
205
- رودو (**RODO**) یک روش کار و جعبه‌ابزار خط فرمان (`rodo`) برای توسعهٔ ساختاریافتهٔ نرم‌افزار با همکاری انسان و هوش مصنوعی است. RODO یک دروازهٔ مسدودکننده نیست؛ هیچ ابزاری جلوی `commit` یا ادامهٔ کار را نمی‌گیرد، بلکه باعث می‌شود نقشهٔ پروژه (`MAP.md`)، تصمیم‌ها (`MEMORY.md`)، توضیح ساده (`simple.md`) و مشخصات فنی (`spec.md`) همیشه با کد هماهنگ بمانند.
206
-
207
- ### ۱. نصب
208
-
209
- پیشنیاز: **Node.js نسخهٔ ۲۰ یا بالاتر**. برای نصب سراسری از طریق `npm`:
210
-
211
- ```bash
212
- npm i -g rodo-spec
213
- ```
214
-
215
- ### ۲. شروع سریع بدون سرور (حالت آفلاین / Method-Only)
216
-
217
- اگر می‌خواهید بدون نیاز به سرور یا حساب کاربری، روی مخزن گیت خود کار کنید (در این حالت فایل‌های `card.rodo.md` هم داخل گیت ذخیره می‌شوند):
218
-
219
- ```bash
220
- # ۱. راه‌اندازی کیت و پوشهٔ پروژه به زبان فارسی
221
- rodo init --method-only --project myapp --lang fa
222
-
223
- # ۲. ساخت اولین چرخه و کارت جدید (برای عناوین فارسی حتماً --slug انگلیسی بدهید)
224
- rodo new "پیاده‌سازی احراز هویت" --slug auth-feature
225
-
226
- # ۳. اعتبارسنجی ساختار کارت‌ها و مشاهدهٔ وضعیت محلی
227
- rodo validate --strict
228
- rodo status --local
229
- ```
230
-
231
- ### ۳. اتصال به سرور و تختهٔ RODO (به ۳ روش)
232
-
233
- هر زمان که بخواهید کارت‌های پروژه را روی برد وب RODO (به‌طور پیش‌فرض `https://rodo.n3xus.ir`) ببینید و همگام‌سازی کنید، می‌توانید یکی از سه روش زیر را به کار ببرید:
234
-
235
- #### روش اول: اتصال تک‌مرحله‌ای با کد اتصال از داخل برد وب (سریع‌ترین روش)
236
- وارد برد خود در وب‌سایت `https://rodo.n3xus.ir` شوید، روی دکمهٔ **«اتصال دستگاه»** کلیک کنید تا کد یک‌بارمصرف ساخته شود و سپس در ترمینال بزنید:
237
-
238
- ```bash
239
- rodo init --project myapp --connect RODO-XXXX-XXXX
240
- ```
241
- این دستور هم‌زمان ورود دستگاه، اتصال پروژهٔ `rodo/myapp/` به همان برد و اولین همگام‌سازی (`sync`) کارت‌ها را انجام می‌دهد و نیازی به اجرای جداگانهٔ `rodo login` ندارد.
242
-
243
- #### روش دوم: ورود و اتصال به برد موجود (انتخاب از لیست یا با شناسهٔ برد)
244
- ```bash
245
- # ۱. ورود به حساب کاربری (با کد تایید مرورگر)
246
- rodo login
247
-
248
- # ۲-الف. نمایش لیست بردهای شما در ترمینال و انتخاب شمارهٔ برد
249
- rodo init --project myapp
250
-
251
- # ۲-ب. یا اتصال مستقیم با دادن شناسهٔ برد (boardId)
252
- rodo init --project myapp --board <boardId>
253
- ```
254
-
255
- #### روش سوم: ورود و ساخت تختهٔ (برد) جدید از داخل ترمینال
256
- اگر هنگام تایید دستگاه در وب، تیک مجوز ساخت برد (`boards:create`) را زده باشید:
257
- ```bash
258
- rodo login
259
- rodo init --project myapp --create-board
260
- ```
261
- ابزار از شما فضای کاری و پروژه را می‌پرسد و پس از تایید نام برد، تختهٔ جدید را روی سرور می‌سازد و کارت‌های محلی را به آن ارسال می‌کند.
262
-
263
- #### همگام‌سازی مستمر در طول کار (`rodo sync`)
264
- پس از اتصال به برد، در شروع و پایان هر جلسهٔ کاری دستور زیر را اجرا کنید تا تغییرات وب و فایل‌های محلی با هم ادغام و همگام شوند:
265
-
266
- ```bash
267
- rodo sync
268
- ```
269
-
270
- > **نکته:** آدرس پیش‌فرض سرور `https://rodo.n3xus.ir` است. برای استفاده از سرور دیگر می‌توانید متغیر محیطی `RODO_SERVER` را تنظیم کنید یا فلگ `--server <url>` را بدهید.
271
-
272
- ### ۴. دستورات پرکاربرد روزانه
273
-
274
- ```bash
275
- # دریافت خلاصهٔ وضعیت و زمینهٔ کارت فعال برای دادن به دستیار هوش مصنوعی
276
- rodo resume
277
-
278
- # اجرای دستور تست تعریف‌شده برای کارت و پایش شکست‌های تکراری
279
- rodo test
280
-
281
- # بررسی سلامت کلی محیط، گیت، کیت و اتصال سرور
282
- rodo doctor
283
-
284
- # مشاهدهٔ آدرس مدیریت دستگاه‌های متصل و وضعیت توکن فعلی
285
- rodo devices
286
- ```
1
+ # rodo-spec
2
+
3
+ [![npm version](https://img.shields.io/npm/v/rodo-spec.svg)](https://www.npmjs.com/package/rodo-spec)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
5
+ [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
6
+
7
+ > **RODO is a way of working, not a gate.**
8
+ > It structures autonomous engineering cycles into predictable, reviewable, and human-aligned iterations through plain Markdown specifications and deterministic CLI automation.
9
+
10
+ ---
11
+
12
+ ## Overview
13
+
14
+ Modern software development often struggles to bridge high-level intentions with concrete agentic or human execution. `rodo-spec` introduces a disciplined protocol and developer toolkit (`rodo`) that captures intent, architecture, constraints, memory, and validation criteria directly in version-controlled Markdown artifacts.
15
+
16
+ Whether you run purely offline in **method-only mode** or connect with a shared RODO Kanban server, the framework guarantees that agents and developers always operate with full context, clear guardrails, and deterministic testing criteria.
17
+
18
+ ---
19
+
20
+ ## Project Layout Tree
21
+
22
+ When initialized within a repository, RODO organizes agent capabilities, project knowledge, and cycle specifications into a clean, predictable hierarchy:
23
+
24
+ ```text
25
+ .
26
+ ├── AGENTS.md # Pointer to the RODO skill for AI assistants
27
+ ├── .agents/
28
+ │ └── skills/
29
+ │ └── rodo/ # Agent operational skills, playbooks & templates
30
+ └── rodo/
31
+ ├── kit.json # Installed RODO kit version & file checksums
32
+ └── <project>/
33
+ ├── project.json # Project settings & optional board binding (no secrets)
34
+ ├── MAP.md # System topology, current state, done & next cycles
35
+ ├── MEMORY.md # Append-only cross-cycle decisions & rationale
36
+ ├── RULES.md # Human-readable guide to the RODO method
37
+ ├── CHANGELOG.md # One-line log for small changes that need no card
38
+ ├── project/
39
+ │ ├── brief.md # Plain-language project overview
40
+ │ ├── architecture.md # Stack, components, data model & test setup
41
+ │ └── glossary.md # Domain terms and definitions
42
+ └── cycles/
43
+ └── NNN-slug/ # Discrete feature/task cycle (e.g., 001-auth-flow)
44
+ ├── card.rodo.md # Cycle card metadata, checklist, refs & progress notes
45
+ ├── simple.md # Plain-language summary of what the user gets
46
+ ├── spec.md # Technical rules (R1, R2...), acceptance & doc impact
47
+ ├── design.md # Architectural design (for major changes)
48
+ └── acceptance.feature # Optional Gherkin scenarios tagged @R1, @R2...
49
+ ```
50
+
51
+ ---
52
+
53
+ ## Installation
54
+
55
+ ### Prerequisites
56
+
57
+ - **Node.js**: `>= 20.0.0`
58
+ - **npm**, **pnpm**, or **yarn**
59
+
60
+ ### Global Install via npm (Recommended)
61
+
62
+ ```bash
63
+ npm install -g rodo-spec
64
+ ```
65
+
66
+ Or run directly with `npx`:
67
+
68
+ ```bash
69
+ npx rodo-spec --help
70
+ ```
71
+
72
+ ### Install from Source / GitHub
73
+
74
+ ```bash
75
+ git clone https://github.com/alishafiee1/rodo-spec.git
76
+ cd rodo-spec
77
+ pnpm install
78
+ pnpm run build
79
+ npm link --workspace=packages/cli
80
+ ```
81
+
82
+ ---
83
+
84
+ ## Quick Start (Offline / Method-Only Mode)
85
+
86
+ You can use RODO as a 100% offline methodology without signing up or connecting to any remote server. In method-only mode, `card.rodo.md` files are tracked directly in Git alongside `simple.md` and `spec.md`.
87
+
88
+ ### 1. Initialize your project
89
+ ```bash
90
+ rodo init --method-only --project myapp --lang en
91
+ ```
92
+
93
+ ### 2. Scaffold your first cycle card
94
+ ```bash
95
+ rodo new "My first feature"
96
+ ```
97
+ This generates `rodo/myapp/cycles/001-my-first-feature/` containing `card.rodo.md`, `simple.md`, and `spec.md` (add `--major` to also generate `design.md` and `acceptance.feature`, or `--slug <kebab-slug>` when the title is non-Latin).
98
+
99
+ ### 3. Validate your specifications
100
+ Check that your cards and cycle documents meet all format rules:
101
+ ```bash
102
+ rodo validate --strict
103
+ ```
104
+
105
+ ### 4. Resume or inspect current progress
106
+ ```bash
107
+ rodo resume
108
+ ```
109
+
110
+ ### 5. Run tests associated with the active card
111
+ ```bash
112
+ rodo test
113
+ ```
114
+
115
+ ### 6. Review cycle and workspace health
116
+ ```bash
117
+ rodo status --local
118
+ rodo doctor
119
+ ```
120
+
121
+ ---
122
+
123
+ ## Connecting to a RODO Board (3 Ways)
124
+
125
+ You can connect an existing method-only project—or initialize a brand-new project—with a RODO Kanban board server (default: `https://rodo.n3xus.ir`) at any time. Connecting binds `rodo/<project>/project.json` to the board and runs the initial sync automatically.
126
+
127
+ ### Way 1: One-Step Connect Code from the Web Board (Fastest)
128
+ Open your board on the web (`https://rodo.n3xus.ir`), click **"Connect Device" («اتصال دستگاه»)** to generate a one-time code, and run:
129
+ ```bash
130
+ rodo init --project myapp --connect RODO-XXXX-XXXX
131
+ ```
132
+ This logs in your device, binds `rodo/myapp/` to that exact board, and syncs all cards in a single step—no separate `rodo login` needed.
133
+
134
+ ### Way 2: Log In & Bind to an Existing Board (Interactive List or Board ID)
135
+ ```bash
136
+ # 1. Authenticate your device (via browser device code or --connect <code>)
137
+ rodo login
138
+
139
+ # 2a. Pick a board interactively from your workspaces
140
+ rodo init --project myapp
141
+
142
+ # 2b. Or bind directly by passing the board ID
143
+ rodo init --project myapp --board <boardId>
144
+ ```
145
+
146
+ ### Way 3: Log In & Create a New Board from the Terminal
147
+ If your device token was approved with board-creation permission (`boards:create`):
148
+ ```bash
149
+ rodo login
150
+ rodo init --project myapp --create-board
151
+ ```
152
+ You will be prompted to select the workspace and project and confirm the new board title.
153
+
154
+ ### Ongoing Synchronization
155
+ Once connected, run `rodo sync` at the start and end of every work session:
156
+ ```bash
157
+ rodo sync
158
+ ```
159
+
160
+ - **Default Server**: `https://rodo.n3xus.ir`
161
+ - **Custom Server**: Pass `--server <url>` or set `export RODO_SERVER="https://rodo.n3xus.ir"`.
162
+
163
+ ---
164
+
165
+ ## Commands Table
166
+
167
+ The CLI executable is `rodo`. Global flags `--project <slug>`, `--lang <fa|en>`, `--json`, and `--verbose` can be used with any command.
168
+
169
+ | Command | Arguments / Flags | Description |
170
+ | :--- | :--- | :--- |
171
+ | `rodo init` | `[--method-only] [--project <slug>] [--name <name>] [--lang <fa\|en>] [--connect <code>] [--board <id>] [--create-board] [--server <url>] [--no-kit-update] [--dry-run] [--yes-files]` | Installs or updates the RODO kit, scaffolds `rodo/<project>/`, and optionally binds & syncs with a board. |
172
+ | `rodo new` | `"<title>" [--slug <kebab-slug>] [--major] [--dry-run] [--project <slug>]` | Creates the next `rodo/<project>/cycles/NNN-slug/` folder with `card.rodo.md`, `simple.md`, and `spec.md`. |
173
+ | `rodo resume` | `[card] [--full] [--project <slug>]` | Prints compact context of the active or specified card for an AI session (`--full` includes architecture & `simple.md`). |
174
+ | `rodo validate` | `[paths...] [--strict] [--project <slug>]` | Validates card files and cycle references (`--strict` exits with code `1` on errors for CI). |
175
+ | `rodo test` | `[card] [--adapter <web\|api\|cli\|mobile\|iot\|other>] [--project <slug>]` | Runs the card's test command and tracks repeated failure signatures (`RODO_STUCK`). |
176
+ | `rodo status` | `[--local] [--project <slug>]` | Displays cards and their state side-by-side (board vs. local, or `--local` offline). |
177
+ | `rodo sync` | `[--offline] [--dry-run] [--pull-only] [--push-only] [--confirm-archive] [--check] [--project <slug>]` | Pulls, merges, pushes, and writes back card files with the bound RODO board (`--offline` validates only). |
178
+ | `rodo doctor` | `[--project <slug>]` | Runs read-only health checks on Node, Git, kit files, `.gitignore`, server connectivity, and cards. |
179
+ | `rodo login` | `[--server <url>] [--connect <code>] [--rotate]` | Logs in with a browser device code or a one-time `--connect` code (`--rotate` replaces the current token). |
180
+ | `rodo logout` | `[--server <url>]` | Revokes this device token on the server and deletes the local token. |
181
+ | `rodo devices` | `[--server <url>]` | Shows the web URL for managing connected devices (`<server>/devices`) and this device's token scopes. |
182
+ | `rodo version` | `[--json]` | Displays the CLI version, bundled kit version, and Node.js runtime version. |
183
+
184
+ ---
185
+
186
+ ## Monorepo Packages
187
+
188
+ This repository is maintained as a monorepo consisting of modular packages:
189
+
190
+ - **[`packages/protocol`](packages/protocol)**: Wire contract, sync API payload shapes, and card status rules between the CLI and a RODO board server.
191
+ - **[`packages/card-format`](packages/card-format)**: Parser, canonical serializer, 3-way merge engine, secret scanner, and validator for `*.rodo.md` files.
192
+ - **[`packages/rodo-kit`](packages/rodo-kit)**: Bundled AI skill (`.agents/skills/rodo/`), Persian & English project templates, and migration manifest.
193
+ - **[`packages/cli`](packages/cli)**: The end-user command-line binary (`rodo`) published to npm as `rodo-spec`.
194
+
195
+ ---
196
+
197
+ ## License
198
+
199
+ This project is licensed under the [MIT License](LICENSE).
200
+
201
+ ---
202
+
203
+ ## راهنمای سریع (فارسی)
204
+
205
+ رودو (**RODO**) یک روش کار و جعبه‌ابزار خط فرمان (`rodo`) برای توسعهٔ ساختاریافتهٔ نرم‌افزار با همکاری انسان و هوش مصنوعی است. RODO یک دروازهٔ مسدودکننده نیست؛ هیچ ابزاری جلوی `commit` یا ادامهٔ کار را نمی‌گیرد، بلکه باعث می‌شود نقشهٔ پروژه (`MAP.md`)، تصمیم‌ها (`MEMORY.md`)، توضیح ساده (`simple.md`) و مشخصات فنی (`spec.md`) همیشه با کد هماهنگ بمانند.
206
+
207
+ ### ۱. نصب
208
+
209
+ پیشنیاز: **Node.js نسخهٔ ۲۰ یا بالاتر**. برای نصب سراسری از طریق `npm`:
210
+
211
+ ```bash
212
+ npm i -g rodo-spec
213
+ ```
214
+
215
+ ### ۲. شروع سریع بدون سرور (حالت آفلاین / Method-Only)
216
+
217
+ اگر می‌خواهید بدون نیاز به سرور یا حساب کاربری، روی مخزن گیت خود کار کنید (در این حالت فایل‌های `card.rodo.md` هم داخل گیت ذخیره می‌شوند):
218
+
219
+ ```bash
220
+ # ۱. راه‌اندازی کیت و پوشهٔ پروژه به زبان فارسی
221
+ rodo init --method-only --project myapp --lang fa
222
+
223
+ # ۲. ساخت اولین چرخه و کارت جدید (برای عناوین فارسی حتماً --slug انگلیسی بدهید)
224
+ rodo new "پیاده‌سازی احراز هویت" --slug auth-feature
225
+
226
+ # ۳. اعتبارسنجی ساختار کارت‌ها و مشاهدهٔ وضعیت محلی
227
+ rodo validate --strict
228
+ rodo status --local
229
+ ```
230
+
231
+ ### ۳. اتصال به سرور و تختهٔ RODO (به ۳ روش)
232
+
233
+ هر زمان که بخواهید کارت‌های پروژه را روی برد وب RODO (به‌طور پیش‌فرض `https://rodo.n3xus.ir`) ببینید و همگام‌سازی کنید، می‌توانید یکی از سه روش زیر را به کار ببرید:
234
+
235
+ #### روش اول: اتصال تک‌مرحله‌ای با کد اتصال از داخل برد وب (سریع‌ترین روش)
236
+ وارد برد خود در وب‌سایت `https://rodo.n3xus.ir` شوید، روی دکمهٔ **«اتصال دستگاه»** کلیک کنید تا کد یک‌بارمصرف ساخته شود و سپس در ترمینال بزنید:
237
+
238
+ ```bash
239
+ rodo init --project myapp --connect RODO-XXXX-XXXX
240
+ ```
241
+ این دستور هم‌زمان ورود دستگاه، اتصال پروژهٔ `rodo/myapp/` به همان برد و اولین همگام‌سازی (`sync`) کارت‌ها را انجام می‌دهد و نیازی به اجرای جداگانهٔ `rodo login` ندارد.
242
+
243
+ #### روش دوم: ورود و اتصال به برد موجود (انتخاب از لیست یا با شناسهٔ برد)
244
+ ```bash
245
+ # ۱. ورود به حساب کاربری (با کد تایید مرورگر)
246
+ rodo login
247
+
248
+ # ۲-الف. نمایش لیست بردهای شما در ترمینال و انتخاب شمارهٔ برد
249
+ rodo init --project myapp
250
+
251
+ # ۲-ب. یا اتصال مستقیم با دادن شناسهٔ برد (boardId)
252
+ rodo init --project myapp --board <boardId>
253
+ ```
254
+
255
+ #### روش سوم: ورود و ساخت تختهٔ (برد) جدید از داخل ترمینال
256
+ اگر هنگام تایید دستگاه در وب، تیک مجوز ساخت برد (`boards:create`) را زده باشید:
257
+ ```bash
258
+ rodo login
259
+ rodo init --project myapp --create-board
260
+ ```
261
+ ابزار از شما فضای کاری و پروژه را می‌پرسد و پس از تایید نام برد، تختهٔ جدید را روی سرور می‌سازد و کارت‌های محلی را به آن ارسال می‌کند.
262
+
263
+ #### همگام‌سازی مستمر در طول کار (`rodo sync`)
264
+ پس از اتصال به برد، در شروع و پایان هر جلسهٔ کاری دستور زیر را اجرا کنید تا تغییرات وب و فایل‌های محلی با هم ادغام و همگام شوند:
265
+
266
+ ```bash
267
+ rodo sync
268
+ ```
269
+
270
+ > **نکته:** آدرس پیش‌فرض سرور `https://rodo.n3xus.ir` است. برای استفاده از سرور دیگر می‌توانید متغیر محیطی `RODO_SERVER` را تنظیم کنید یا فلگ `--server <url>` را بدهید.
271
+
272
+ ### ۴. دستورات پرکاربرد روزانه
273
+
274
+ ```bash
275
+ # دریافت خلاصهٔ وضعیت و زمینهٔ کارت فعال برای دادن به دستیار هوش مصنوعی
276
+ rodo resume
277
+
278
+ # اجرای دستور تست تعریف‌شده برای کارت و پایش شکست‌های تکراری
279
+ rodo test
280
+
281
+ # بررسی سلامت کلی محیط، گیت، کیت و اتصال سرور
282
+ rodo doctor
283
+
284
+ # مشاهدهٔ آدرس مدیریت دستگاه‌های متصل و وضعیت توکن فعلی
285
+ rodo devices
286
+ ```
package/dist/index.js CHANGED
@@ -11057,7 +11057,7 @@ function ensureBlock(path, block, kit20Hashes, importsAgents, dryRun = false) {
11057
11057
  // package.json
11058
11058
  var package_default = {
11059
11059
  name: "rodo-spec",
11060
- version: "2.2.1",
11060
+ version: "2.3.0",
11061
11061
  description: "RODO method CLI \u2014 install the kit, manage cards, sync with the board",
11062
11062
  license: "MIT",
11063
11063
  type: "module",
@@ -14022,7 +14022,7 @@ async function runInit(ctx, a) {
14022
14022
  out.line(`project rodo/${slug2}/: ${existsSync14(join14(projectDir, "project.json")) ? "exists (missing files would be added)" : "would be created"}`);
14023
14023
  } else {
14024
14024
  const isNew = !existsSync14(join14(projectDir, "project.json"));
14025
- const lang = isNew ? await chooseLanguage(ctx) : "fa";
14025
+ const lang = isNew ? await chooseLanguage(ctx) : readProject(projectDir, slug2).project?.language.simple ?? "fa";
14026
14026
  const created = scaffoldProject(root, slug2, a.name ?? slug2, lang);
14027
14027
  if (isNew) data.language = lang;
14028
14028
  out.line(created.length ? `rodo/${slug2}/: created ${created.length} file(s)` : `rodo/${slug2}/: nothing to add`);
@@ -14769,7 +14769,18 @@ async function runTest(ctx, query, a) {
14769
14769
  }
14770
14770
 
14771
14771
  // src/commands/validate.ts
14772
- import { resolve as resolve3 } from "path";
14772
+ import { existsSync as existsSync18, readFileSync as readFileSync17 } from "fs";
14773
+ import { join as join19, resolve as resolve3 } from "path";
14774
+ var PROJECT_DOC_LIMITS = { "project/project-overview.md": 500, "project/how-it-works.md": 900 };
14775
+ var wordCount = (text) => text.replace(/<!--[\s\S]*?-->/g, " ").split(/\s+/).filter(Boolean).length;
14776
+ function longProjectDocs(dir) {
14777
+ return Object.entries(PROJECT_DOC_LIMITS).flatMap(([path, limit]) => {
14778
+ const abs = join19(dir, path);
14779
+ if (!existsSync18(abs)) return [];
14780
+ const words = wordCount(readFileSync17(abs, "utf8"));
14781
+ return words > limit ? [{ path, code: "PROJECT_DOC_TOO_LONG", line: null, message: `PROJECT_DOC_TOO_LONG: ${words} words, the limit is ${limit}; shorten it` }] : [];
14782
+ });
14783
+ }
14773
14784
  async function runValidate(ctx, paths, o = {}) {
14774
14785
  const { d, refs } = load(ctx, false);
14775
14786
  const only = paths.map((p) => resolve3(ctx.cwd, p));
@@ -14778,6 +14789,8 @@ async function runValidate(ctx, paths, o = {}) {
14778
14789
  for (const ref of refs) {
14779
14790
  const cards = scanCards(d.root, ref, only);
14780
14791
  const s = sum(cards);
14792
+ const docs = only.length || ref.legacy ? [] : longProjectDocs(ref.dir);
14793
+ s.warnings += docs.length;
14781
14794
  total.files += s.files;
14782
14795
  total.errors += s.errors;
14783
14796
  total.warnings += s.warnings;
@@ -14785,6 +14798,10 @@ async function runValidate(ctx, paths, o = {}) {
14785
14798
  ctx.out.line(`rodo/${ref.legacy ? "" : ref.slug} \u25B8 ${s.files} files \xB7 errors ${s.errors} \xB7 warnings ${s.warnings}`);
14786
14799
  printFindings(ctx, cards);
14787
14800
  for (const c of cards) files.push({ project: ref.slug, path: c.path, errors: c.errors.map(slim2), warnings: c.warnings.map(slim2) });
14801
+ for (const f of docs) {
14802
+ ctx.out.line(` ${mark.warn} ${f.path} ${f.message}`);
14803
+ files.push({ project: ref.slug, path: f.path, errors: [], warnings: [{ code: f.code, line: f.line, message: f.message }] });
14804
+ }
14788
14805
  }
14789
14806
  ctx.out.flush({ version: 2, files, summary: total });
14790
14807
  return o.strict && total.errors > 0 ? 1 : 0;
package/dist/kit/.agents/skills/rodo/SKILL.md CHANGED
@@ -5,7 +5,7 @@ description: RODO project method. Use whenever the repo has a rodo/ folder or *.
5
5
 
6
6
  > یادداشت فارسی: این مهارت برای AI است. نسخهٔ انسانی همین قواعد در `rodo/<project>/RULES.md` است. RODO فقط «روش کار» است: هیچ ابزاری جلوی commit، تست یا کار را نمی‌گیرد.
7
7
 
8
- # RODO method (kit 2.2.1)
8
+ # RODO method (kit 2.3.0)
9
9
 
10
10
  RODO is a way of working, not a gate. Nothing blocks a commit, a test or a status. You follow it because it keeps the project understandable for the user, for teammates and for the next AI session.
11
11
 
@@ -86,6 +86,7 @@ A card may have `scope: {allowed: [...], forbidden: [...]}`. Stay inside `allowe
86
86
  | The repo has code but no `rodo/<project>/` yet | `onboarding.md` |
87
87
  | Typo, style, refactor or a fix that does not change described behaviour | `small-change.md` |
88
88
  | You write or fix tests (optional, recommended) | `testing.md` |
89
+ | You write or update `project/project-overview.md` or `project/how-it-works.md` | `project-docs.md` |
89
90
 
90
91
  ## Workflow levels
91
92
 
@@ -122,7 +123,7 @@ Do not turn ordinary clarification questions into `## Decision:` sections, and d
122
123
 
123
124
  | Kind | Files | Rule |
124
125
  |---|---|---|
125
- | **CURRENT** (canonical) | `rodo/<project>/project/*`, `MAP.md`, `MEMORY.md` | Must describe the code as it is now. Update them in the same work. `MEMORY.md` is append-only: add a new line that says which line it replaces; never rewrite old lines. |
126
+ | **CURRENT** (canonical) | `rodo/<project>/project/*`, `MAP.md`, `MEMORY.md` | Must describe the code as it is now. Update them in the same work. `MEMORY.md` is append-only: add a new line that says which line it replaces; never rewrite old lines. One exception: a planned part in `project-overview.md` (unticked) or `how-it-works.md` (marked `(planned)`) may describe work not built yet (`project-docs.md`). |
126
127
  | **ACTIVE CYCLE** | the docs of the card you are working on (`simple.md`, `spec.md`, `design.md`, `acceptance.feature`) | Must match the code when the card is done. |
127
128
  | **HISTORICAL** | docs of `done` and `cancelled` cycles | Never rewritten. A later card refers to them; a new decision goes into the new card and `MEMORY.md`. |
128
129
 
@@ -142,6 +143,8 @@ Run the checks that fit this change with the project's own tools; RODO runs noth
142
143
  project.json board binding and settings (no secrets)
143
144
  MAP.md MEMORY.md RULES.md CHANGELOG.md
144
145
  project/{brief,architecture,glossary}.md
146
+ project/project-overview.md the project for a client, parts with ticks
147
+ project/how-it-works.md how each part works, for a beginner
145
148
  cycles/NNN-slug/
146
149
  card.rodo.md the card (synced with the board, not in git)
147
150
  simple.md plain explanation (shown read-only on the web)
package/dist/kit/.agents/skills/rodo/coder.md CHANGED
@@ -71,7 +71,8 @@ The folder does not move.
71
71
  1. Card: `status: done`.
72
72
  2. `MAP.md`: add the cycle under `## انجام‌شده` (one line, link to simple.md or the card folder) and update "الان کجاییم".
73
73
  3. `MEMORY.md`: append each `## Decisions` line of spec.md as `- YYYY-MM-DD — <decision>. چون <reason>. (cycle NNN)`.
74
- 4. Commit the MAP and MEMORY change. Later changes to this behaviour need a new card; changes that do not touch behaviour go to `small-change.md`.
74
+ 4. `project/project-overview.md` and `project/how-it-works.md`: make them match what was built and tick the part if all of it is finished (`project-docs.md`).
75
+ 5. Commit the MAP, MEMORY and project docs change. Later changes to this behaviour need a new card; changes that do not touch behaviour go to `small-change.md`.
75
76
 
76
77
  ## Rules
77
78
 
package/dist/kit/.agents/skills/rodo/onboarding.md CHANGED
@@ -8,7 +8,7 @@ Goal: create `rodo/<project>/` so the project can follow the method, without cha
8
8
 
9
9
  1. **Read, do not write.** Read README, existing docs, package files, folder structure, git log (last ~100 commits), and TODO/FIXME comments. Skim code by folder; do not read every file.
10
10
  2. **Create the skeleton**: run `rodo init --method-only --project <slug>` (if the CLI is installed), or copy `project-template/` into `rodo/<slug>/` yourself. It never overwrites an existing file. Set `language` in `project.json` if the user wants other languages.
11
- 3. **brief.md and architecture.md**: describe what exists today. Mark guesses with `(حدس)` so the user can confirm.
11
+ 3. **brief.md and architecture.md**: describe what exists today. Mark guesses with `(حدس)` so the user can confirm. Then write `project/project-overview.md` and `project/how-it-works.md` the same way (`project-docs.md`), ticking only parts that already work.
12
12
  4. **MEMORY.md**: decisions visible in the code or docs (framework, database, auth method...). One line each with the reason if known, else `چون: نامعلوم`.
13
13
  5. **Finished work → done cycles.** For each finished feature a user can see, create `rodo/<project>/cycles/NNN-slug/` with:
14
14
  - `simple.md` whose FIRST line is `<!-- rodo:onboarded -->`, then 3-6 simple lines;
package/dist/kit/.agents/skills/rodo/planner.md CHANGED
@@ -24,6 +24,7 @@ Yes, for every new feature, change or improvement, and for every change to behav
24
24
  - List the current documents this change will make wrong or must extend.
25
25
  - Use `MAP.md`, `MEMORY.md`, `project/*`, the active cycle, the card's refs, and a code search (Graphify or similar, if available in the project).
26
26
  - Write the list in `spec.md` `## Documentation Impact` (`- <path> — <what changes>`, or `- none — <why>`).
27
+ - **Project docs first:** if a new feature or major change does not fit `project/project-overview.md` or `project/how-it-works.md`, update them before BUILD, following `project-docs.md`. If they are still templates, fill them first.
27
28
  - QUICK: do this in your head and fix any doc you made wrong (small-change.md).
28
29
 
29
30
  ## Classify
package/dist/kit/.agents/skills/rodo/project-docs.md ADDED
@@ -0,0 +1,41 @@
1
+ > یادداشت فارسی: قانون نگارش دو سند سادهٔ پروژه: `project-overview.md` برای کارفرما و `how-it-works.md` برای یک مبتدی. این سندها همیشه کوتاه می‌مانند و پیش از شروع کار با طرح تازه هماهنگ می‌شوند. همهٔ مسیرها نسبت به `rodo/<project>/` هستند.
2
+
3
+ # Project docs playbook
4
+
5
+ Two short documents explain the whole project to people. Write them in the language of `language.simple` in `project.json`. They do not replace `brief.md` or `architecture.md`; those stay as they are.
6
+
7
+ | File | Reader | Answers | Limit |
8
+ |---|---|---|---|
9
+ | `project/project-overview.md` | the client | what is this project, what parts does it have, which are finished | 500 words |
10
+ | `project/how-it-works.md` | the owner, a beginner who builds with AI | what is it built from, how does each part work, what does each part make easier | 900 words |
11
+
12
+ ## project-overview.md
13
+
14
+ - Write it like a plan you hand to a client. Short sentences, no jargon.
15
+ - **No technology names** (no framework, database or service names). Describe what the user gets.
16
+ - Sections: what this project is, goals, parts of the project.
17
+ - One line per part: `- [ ] **Name**: two or three sentences`. Name parts the way a client would, not after cycles or folders.
18
+ - Planned parts stay visible, unticked. Cancelled parts are removed.
19
+ - `[x]` means the part is finished and works. Never tick a part that is only planned, half done or untested when it has tests.
20
+
21
+ ## how-it-works.md
22
+
23
+ - Write like an experienced engineer explaining to an intern, in plain words. Technology names are welcome; explain each one the first time it appears.
24
+ - Start with the big picture: a few sentences on what happens when a user does something, and which part talks to which.
25
+ - One `##` section per part or piece of infrastructure, each answering: what is it and how does it work, and what does it make easier (what would be hard without it).
26
+ - Use one example from this project in place of a general definition.
27
+ - Depth follows importance: a main part may get a paragraph, a small helper one or two sentences.
28
+ - Never write secrets, passwords, keys or server addresses that are not public.
29
+
30
+ ## When to update them
31
+
32
+ 1. **Planning (before work starts).** In Documentation Impact, ask: does this new feature or major change fit what these two files say? If not, update them before BUILD. A new part goes in the overview unticked. In `how-it-works.md` mark a part that does not exist yet with `(planned)`. List both files in `spec.md` `## Documentation Impact`.
33
+ 2. **Closing a card.** Make the text match what was really built, remove `(planned)`, and tick the part in the overview if all of it is finished. A part that needs more cards stays unticked.
34
+ 3. **QUICK changes** do not touch these files, unless a sentence in them became false.
35
+ 4. **Empty or template files** (they still contain `{{`): the next planner fills them from the code and the current docs before planning its card. Mark anything you could not confirm with `(guess)`, or `(حدس)` in Persian.
36
+
37
+ ## Staying short
38
+
39
+ - Never let a file grow past its limit. `rodo validate` warns with `PROJECT_DOC_TOO_LONG`; it never blocks anything.
40
+ - To add something when a file is full, shorten or merge what is there. Do not add a second file or an appendix.
41
+ - These files describe the project as a whole. History belongs in `MAP.md`, decisions in `MEMORY.md`, details in `architecture.md` and `spec.md`.
package/dist/kit/KIT_VERSION CHANGED
@@ -1 +1 @@
1
- 2.2.1
1
+ 2.3.0
package/dist/kit/MIGRATION.md CHANGED
@@ -2,6 +2,16 @@
2
2
 
3
3
  Kit 2.1+ is installed and updated by `rodo init` (the 2.0 scripts `rodo-install.cjs` and `rodo-update.cjs` are replaced by it). Do the steps for every version you skipped.
4
4
 
5
+ ## 2.2.1 → 2.3.0 (two plain project docs)
6
+
7
+ What changes:
8
+ - **New files.** `project/project-overview.md` (for a client, parts with ticks) and `project/how-it-works.md` (for a beginner). The writing rules are in the new skill file `project-docs.md`.
9
+ - **Planner and coder.** The planner updates these files before work starts when a new feature or major change does not fit them; the coder makes them true and ticks the part when a card closes.
10
+ - **`rodo validate`** warns `PROJECT_DOC_TOO_LONG` when one of them passes its word limit. It never blocks anything.
11
+ - **`rodo init`** uses the project's own language when it adds missing files to an existing project.
12
+
13
+ Steps: run `rodo init`. It adds the two files without touching existing ones. The next planner session fills them in. `RULES.md` is never replaced: compare it with the kit's new one (new section on the two docs). Commit: `git commit -am "chore: RODO kit 2.3.0"`.
14
+
5
15
  ## 2.1.0 → 2.2.0 (English templates, rodo new, safer sync)
6
16
 
7
17
  What changes:
package/dist/kit/agents-block.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <!-- rodo:start -->
2
- This repo uses the RODO method (kit 2.2.1). Before any work: read `.agents/skills/rodo/SKILL.md`,
2
+ This repo uses the RODO method (kit 2.3.0). Before any work: read `.agents/skills/rodo/SKILL.md`,
3
3
  run `rodo sync`, then `rodo resume`. At the end of every session run `rodo sync`.
4
4
  RODO projects: see `rodo/*/project.json`. Never write secrets into rodo files. Never create boards.
5
5
  Never run `git pull`, `git fetch`, `git merge` or `git rebase`. If the repo is behind, tell the user once.
package/dist/kit/kit-manifest.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "2.2.1",
2
+ "version": "2.3.0",
3
3
  "files": [
4
4
  {
5
5
  "src": ".agents/skills/rodo/SKILL.md",
@@ -21,6 +21,11 @@
21
21
  "dest": ".agents/skills/rodo/planner.md",
22
22
  "owner": "kit"
23
23
  },
24
+ {
25
+ "src": ".agents/skills/rodo/project-docs.md",
26
+ "dest": ".agents/skills/rodo/project-docs.md",
27
+ "owner": "kit"
28
+ },
24
29
  {
25
30
  "src": ".agents/skills/rodo/small-change.md",
26
31
  "dest": ".agents/skills/rodo/small-change.md",
@@ -89,9 +94,6 @@
89
94
  "CLAUDE.md": [
90
95
  "sha256:336cc4fbf19beaada7ccf9986414fa91851a8d7a07dfb3ccbe800a69eed0ab49"
91
96
  ],
92
- ".agents/skills/rodo/SKILL.md": [
93
- "sha256:a06382e130c46d0d7fc8ebfed4610a829496be1d0830ba79bf3135fa2da7b05b"
94
- ],
95
97
  ".agents/skills/rodo/coder.md": [
96
98
  "sha256:6a5b3632e4c3b8065e8611fea5c267719bd9eddc797a7987723f78ef055e49b4"
97
99
  ],
@@ -101,18 +103,12 @@
101
103
  ".agents/skills/rodo/planner.md": [
102
104
  "sha256:36e6082c88920c2bf03f51e2e1a93f92cd2d06406d42a1cda357a65ca85f89e3"
103
105
  ],
106
+ ".agents/skills/rodo/SKILL.md": [
107
+ "sha256:a06382e130c46d0d7fc8ebfed4610a829496be1d0830ba79bf3135fa2da7b05b"
108
+ ],
104
109
  ".agents/skills/rodo/small-change.md": [
105
110
  "sha256:7bb7ceb277773e1ec4ed351ce0591e39dc5ba0911e0a32cce358ae16e2358c12"
106
111
  ],
107
- ".agents/skills/rodo/templates/CHANGELOG.md": [
108
- "sha256:74b575d434805ef245587bf704f0cda130d2cd0fb37e2499834853e0f372a059"
109
- ],
110
- ".agents/skills/rodo/templates/MAP.md": [
111
- "sha256:9597d20bc5871cd5699f03e18b16356d06f212de37afe52ddfd3fd3f3e7ed200"
112
- ],
113
- ".agents/skills/rodo/templates/MEMORY.md": [
114
- "sha256:68920278b000efa6b64cc206553720e14cb8af3a4154623e5babef3a745c0e03"
115
- ],
116
112
  ".agents/skills/rodo/templates/acceptance.feature": [
117
113
  "sha256:0156ea9eb06f09de596a52a5ad2b1852b351d9cbe7a28230a4f90a2138a4b131"
118
114
  ],
@@ -125,12 +121,21 @@
125
121
  ".agents/skills/rodo/templates/card.rodo.md": [
126
122
  "sha256:6639b0b83bf25d8355f576b367e8fa10b51b0f5e7f100b5257c78cb4d3d0cc6a"
127
123
  ],
124
+ ".agents/skills/rodo/templates/CHANGELOG.md": [
125
+ "sha256:74b575d434805ef245587bf704f0cda130d2cd0fb37e2499834853e0f372a059"
126
+ ],
128
127
  ".agents/skills/rodo/templates/config.json": [
129
128
  "sha256:0c07d153aad92e647a8211a54cf696cfad5ac1445593383738da4cf29108f669"
130
129
  ],
131
130
  ".agents/skills/rodo/templates/glossary.md": [
132
131
  "sha256:0a5b2eff02a30ad5753547929789c8f3a6e39158ab65b433198e9845df42dfb6"
133
132
  ],
133
+ ".agents/skills/rodo/templates/MAP.md": [
134
+ "sha256:9597d20bc5871cd5699f03e18b16356d06f212de37afe52ddfd3fd3f3e7ed200"
135
+ ],
136
+ ".agents/skills/rodo/templates/MEMORY.md": [
137
+ "sha256:68920278b000efa6b64cc206553720e14cb8af3a4154623e5babef3a745c0e03"
138
+ ],
134
139
  ".agents/skills/rodo/templates/simple.md": [
135
140
  "sha256:b81908a8886698cce148400113a2525f6c44cf34c8e412290ba1652b3b928b6f"
136
141
  ],
@@ -181,6 +186,16 @@
181
186
  "src": "project-template/project/glossary.md",
182
187
  "dest": "project/glossary.md",
183
188
  "owner": "project"
189
+ },
190
+ {
191
+ "src": "project-template/project/how-it-works.md",
192
+ "dest": "project/how-it-works.md",
193
+ "owner": "project"
194
+ },
195
+ {
196
+ "src": "project-template/project/project-overview.md",
197
+ "dest": "project/project-overview.md",
198
+ "owner": "project"
184
199
  }
185
200
  ],
186
201
  "projectTemplateEn": [
@@ -223,6 +238,16 @@
223
238
  "src": "project-template-en/project/glossary.md",
224
239
  "dest": "project/glossary.md",
225
240
  "owner": "project"
241
+ },
242
+ {
243
+ "src": "project-template-en/project/how-it-works.md",
244
+ "dest": "project/how-it-works.md",
245
+ "owner": "project"
246
+ },
247
+ {
248
+ "src": "project-template-en/project/project-overview.md",
249
+ "dest": "project/project-overview.md",
250
+ "owner": "project"
226
251
  }
227
252
  ]
228
253
  }
package/dist/kit/project-template/RULES.md CHANGED
@@ -1,4 +1,4 @@
1
- # روش RODO: راهنمای آدم‌ها (نسخهٔ کیت ۲.۲.۱)
1
+ # روش RODO: راهنمای آدم‌ها (نسخهٔ کیت ۲.۳.۰)
2
2
 
3
3
  > این فایل برای شماست، نه برای AI. AI همین قواعد را از `.agents/skills/rodo/` می‌خواند.
4
4
  > اگر فقط ۲ دقیقه وقت دارید، «شروع سریع» و بخش ۱، ۳ و ۴ را بخوانید.
@@ -54,7 +54,9 @@ rodo/
54
54
  ├── project/
55
55
  │ ├── brief.md پروژه به زبان ساده
56
56
  │ ├── architecture.md بخش‌ها و فناوری‌ها، و چرا
57
- │ └── glossary.md واژه‌های پروژه و معنی‌شان
57
+ │ ├── glossary.md واژه‌های پروژه و معنی‌شان
58
+ │ ├── project-overview.md طرح کلی برای کارفرما: بخش‌ها با تیک انجام‌شده‌ها
59
+ │ └── how-it-works.md هر بخش چطور کار می‌کند، به زبان ساده برای مبتدی
58
60
  ├── inbox/ کارت‌هایی که در وب ساخته شده‌اند (در Git نیست)
59
61
  └── cycles/
60
62
  └── 002-discount-code/ یک کارت و سندهایش (هیچ‌وقت جابه‌جا نمی‌شود)
@@ -232,6 +234,12 @@ AI قبل از هر تغییر این سؤال را از خودش می‌پرس
232
234
  - سندهای کارهای تمام‌شده یا لغوشده هرگز بازنویسی نمی‌شوند؛ تصمیم تازه در کارت تازه و در `MEMORY.md` نوشته می‌شود.
233
235
  - RODO خودش چیزی را اجرا نمی‌کند؛ فقط می‌گوید کدام بررسی‌ها برای این کار مناسب است و ابزارهای خود پروژه آن‌ها را اجرا می‌کنند.
234
236
 
237
+ ## دو سند سادهٔ پروژه
238
+ - `project-overview.md` طرح کلی برای کارفرماست: پروژه چیست، چه بخش‌هایی دارد و کنار بخش‌های تمام‌شده تیک خورده است.
239
+ - `how-it-works.md` برای شماست: پروژه از چه ساخته شده، هر بخش چطور کار می‌کند و کجای کار را راحت می‌کند.
240
+ - اگر قابلیت تازه یا تغییر بزرگ با این دو سند نخواند، AI پیش از شروع کار آن‌ها را به‌روز می‌کند و بخش تازه بدون تیک اضافه می‌شود. موقع بستن کارت، متن با واقعیت یکی و تیک زده می‌شود.
241
+ - این دو سند هیچ‌وقت از یکی دو صفحه بیشتر نمی‌شوند. `rodo validate` اگر طولانی شوند هشدار می‌دهد.
242
+
235
243
  ---
236
244
 
237
245
  ## ۹. مثال کوتاه: فروشگاه گل مریم
package/dist/kit/project-template/project/how-it-works.md ADDED
@@ -0,0 +1,13 @@
1
+ # {{نام پروژه}}: چطور کار می‌کند
2
+
3
+ <!-- برای یک مبتدی. مثل یک متخصص باتجربه که به کارآموز توضیح می‌دهد. حداکثر ۹۰۰ کلمه. طول هر بخش به اهمیت آن بستگی دارد. قانون کامل: .agents/skills/rodo/project-docs.md -->
4
+
5
+ ## نمای کلی
6
+
7
+ {{چند جمله: وقتی کاربر کاری می‌کند، درخواست از کدام بخش‌ها می‌گذرد و کدام بخش با کدام حرف می‌زند}}
8
+
9
+ ## {{نام بخش یا زیرساخت، مثلاً پایگاه داده}}
10
+
11
+ **چیست و چطور کار می‌کند:** {{به زبان ساده، با یک مثال از همین پروژه}}
12
+
13
+ **کجای کار را راحت می‌کند:** {{اگر این بخش نبود چه کاری سخت می‌شد}}
package/dist/kit/project-template/project/project-overview.md ADDED
@@ -0,0 +1,15 @@
1
+ # {{نام پروژه}}: طرح کلی
2
+
3
+ <!-- برای کارفرما. زبان ساده، بدون نام فناوری، حداکثر ۵۰۰ کلمه. تیک فقط وقتی زده می‌شود که آن بخش واقعاً تمام شده باشد. قانون کامل: .agents/skills/rodo/project-docs.md -->
4
+
5
+ ## این پروژه چیست
6
+
7
+ {{دو یا سه جمله: این پروژه چیست، برای چه کسی است و چه مشکلی را حل می‌کند}}
8
+
9
+ ## هدف‌ها
10
+
11
+ - {{چیزی که با تمام شدن پروژه به دست می‌آید}}
12
+
13
+ ## بخش‌های پروژه
14
+
15
+ - [ ] **{{نام بخش}}**: {{دو یا سه جمله دربارهٔ اینکه این بخش برای کاربر چه کاری می‌کند}}
package/dist/kit/project-template-en/RULES.md CHANGED
@@ -1,4 +1,4 @@
1
- # The RODO method: guide for people (kit 2.2.1)
1
+ # The RODO method: guide for people (kit 2.3.0)
2
2
 
3
3
  > This file is for you, not for the AI. The AI reads the same rules from `.agents/skills/rodo/`.
4
4
 
@@ -38,7 +38,7 @@ rodo/
38
38
  ├── MEMORY.md important decisions, one line each with "because"
39
39
  ├── CHANGELOG.md small changes without a card, one line each
40
40
  ├── RULES.md this file
41
- ├── project/ brief, architecture, glossary (always current)
41
+ ├── project/ brief, architecture, glossary, project-overview, how-it-works (always current)
42
42
  └── cycles/NNN-slug/ one folder per card: card.rodo.md, simple.md, spec.md, design.md, acceptance.feature
43
43
  ```
44
44
 
@@ -63,7 +63,14 @@ For every new feature, change or improvement, and for every change to behaviour
63
63
  - With a board, card files live on the board and arrive through `rodo sync`; `rodo init` adds them to `.gitignore`.
64
64
  - `rodo sync` never loses your text: when the board wins a conflict, your file is saved in `rodo/<project>/.rodo/conflicts/`.
65
65
 
66
- ## 7. Never
66
+ ## 7. The two plain project docs
67
+
68
+ - `project-overview.md` is the plan for a client: what the project is, its parts, and a tick beside the finished ones.
69
+ - `how-it-works.md` is for you: what the project is built from, how each part works and what it makes easier.
70
+ - If a new feature or major change does not fit them, the AI updates them before work starts and a new part goes in unticked. When the card closes, the text is made true and the part is ticked.
71
+ - They never grow past one or two pages; `rodo validate` warns if they do.
72
+
73
+ ## 8. Never
67
74
 
68
75
  - No secrets (passwords, keys, tokens) in any file under `rodo/`, in cards or in commit messages.
69
76
  - 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/how-it-works.md ADDED
@@ -0,0 +1,13 @@
1
+ # {{name}}: how it works
2
+
3
+ <!-- For a beginner. Written like an experienced engineer explaining to an intern. At most 900 words. Each part is as long as its importance needs. Full rules: .agents/skills/rodo/project-docs.md -->
4
+
5
+ ## The big picture
6
+
7
+ {{a few sentences: when a user does something, which parts the request passes through and which part talks to which}}
8
+
9
+ ## {{part or infrastructure name, for example the database}}
10
+
11
+ **What it is and how it works:** {{in plain words, with an example from this project}}
12
+
13
+ **What it makes easier:** {{what would be hard without it}}
package/dist/kit/project-template-en/project/project-overview.md ADDED
@@ -0,0 +1,15 @@
1
+ # {{name}}: overview
2
+
3
+ <!-- For the client. Plain words, no technology names, at most 500 words. Tick a part only when it is really finished. Full rules: .agents/skills/rodo/project-docs.md -->
4
+
5
+ ## What this project is
6
+
7
+ {{two or three sentences: what it is, who it is for and what problem it solves}}
8
+
9
+ ## Goals
10
+
11
+ - {{what the project delivers when it is finished}}
12
+
13
+ ## Parts of the project
14
+
15
+ - [ ] **{{part name}}**: {{two or three sentences on what this part does for the user}}
package/package.json CHANGED
@@ -1,50 +1,50 @@
1
- {
2
- "name": "rodo-spec",
3
- "version": "2.2.1",
4
- "description": "RODO method CLI — install the kit, manage cards, sync with the board",
5
- "license": "MIT",
6
- "type": "module",
7
- "repository": {
8
- "type": "git",
9
- "url": "https://github.com/alishafiee1/rodo-spec.git",
10
- "directory": "packages/cli"
11
- },
12
- "homepage": "https://github.com/alishafiee1/rodo-spec#readme",
13
- "keywords": [
14
- "rodo",
15
- "rodo-spec",
16
- "kanban",
17
- "cli",
18
- "spec",
19
- "ai-agent"
20
- ],
21
- "bin": {
22
- "rodo": "dist/index.js"
23
- },
24
- "files": [
25
- "dist",
26
- "README.md",
27
- "LICENSE"
28
- ],
29
- "engines": {
30
- "node": ">=20"
31
- },
32
- "scripts": {
33
- "build": "tsup",
34
- "prepack": "pnpm run build",
35
- "test": "vitest run",
36
- "typecheck": "tsc --noEmit"
37
- },
38
- "devDependencies": {
39
- "@rodo/card-format": "workspace:*",
40
- "@rodo/protocol": "workspace:*",
41
- "@rodo/rodo-kit": "workspace:*",
42
- "@types/node": "^22.0.0",
43
- "commander": "^12.1.0",
44
- "picocolors": "^1.1.1",
45
- "tsup": "^8.3.5",
46
- "typescript": "^5.7.2",
47
- "vitest": "^2.1.8",
48
- "yaml": "^2.7.0"
49
- }
50
- }
1
+ {
2
+ "name": "rodo-spec",
3
+ "version": "2.3.0",
4
+ "description": "RODO method CLI — install the kit, manage cards, sync with the board",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/alishafiee1/rodo-spec.git",
10
+ "directory": "packages/cli"
11
+ },
12
+ "homepage": "https://github.com/alishafiee1/rodo-spec#readme",
13
+ "keywords": [
14
+ "rodo",
15
+ "rodo-spec",
16
+ "kanban",
17
+ "cli",
18
+ "spec",
19
+ "ai-agent"
20
+ ],
21
+ "bin": {
22
+ "rodo": "dist/index.js"
23
+ },
24
+ "files": [
25
+ "dist",
26
+ "README.md",
27
+ "LICENSE"
28
+ ],
29
+ "engines": {
30
+ "node": ">=20"
31
+ },
32
+ "scripts": {
33
+ "build": "tsup",
34
+ "prepack": "pnpm run build",
35
+ "test": "vitest run",
36
+ "typecheck": "tsc --noEmit"
37
+ },
38
+ "devDependencies": {
39
+ "@rodo/card-format": "workspace:*",
40
+ "@rodo/protocol": "workspace:*",
41
+ "@rodo/rodo-kit": "workspace:*",
42
+ "@types/node": "^22.0.0",
43
+ "commander": "^12.1.0",
44
+ "picocolors": "^1.1.1",
45
+ "tsup": "^8.3.5",
46
+ "typescript": "^5.7.2",
47
+ "vitest": "^2.1.8",
48
+ "yaml": "^2.7.0"
49
+ }
50
+ }