rodo-spec 0.0.0-stage → 2.2.0

package/dist/kit/.agents/skills/rodo/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: rodo
+description: RODO project method. Use whenever the repo has a rodo/ folder or *.rodo.md cards, or the user asks to plan a feature, code a card, fix a bug, onboard a project or make a small change. Tells you how to start and close a session (rodo sync, rodo resume), what to read, when a card is needed, and which playbook to follow.
+---
+
+> یادداشت فارسی: این مهارت برای AI است. نسخهٔ انسانی همین قواعد در `rodo/<project>/RULES.md` است. RODO فقط «روش کار» است: هیچ ابزاری جلوی commit، تست یا کار را نمی‌گیرد.
+
+# RODO method (kit 2.2.0)
+
+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.
+
+## Projects in this repo
+
+Every folder `rodo/<project>/` with a `project.json` is one RODO project, bound to one board. Work in the project the user names; if there is only one, use it; if unsure, ask. Paths below are relative to `rodo/<project>/`.
+
+## Session start (every session, every change)
+
+1. If this folder is a git repository, look only (`git status -sb`, or how many commits `HEAD` is behind `@{upstream}`). Do **not** run `git pull`, `git fetch`, `git merge` or `git rebase`. Card files (`*.rodo.md`) arrive through `rodo sync`. MAP, MEMORY, `spec.md` and `simple.md` arrive through Git. If the branch is behind its remote, or you cannot tell, tell the user once and ask them to update the repo when they are ready. Then keep going with the files already on disk.
+2. Run `rodo sync` (all projects) or `rodo sync --project <slug>`. It pulls board changes into the card files. If it says OFFLINE or exits 4 (login needed), continue working and tell the user once.
+3. Run `rodo resume` (or `rodo resume <card>`) and read its output. Use `rodo resume --full` only for planning or deep debugging.
+4. If the tool is not installed, read `MAP.md`, `MEMORY.md` and the active card yourself.
+5. Read ONLY the files listed under the card's `## Refs` and the code they point to. Do not read the whole repository.
+6. If the card has an unticked `[approval]` step: stop, tell the user it waits for their approval on the web, and do nothing else on that card.
+7. If the card has an answered `## Decision:` (a `- Answer:` line): apply the answer, then set `status: in_progress` and remove `statusReason` and `blockerType` if the card was blocked only for that decision.
+
+## Session close (every session, before you stop)
+
+1. Update `## Progress notes`: `- Updated:`, `- Done:`, `- Remaining:` (free text). The reason for `blocked` / `cancelled` goes in the `statusReason` key, not in the notes.
+2. Report what you changed, in plain words.
+3. If the card has a test command, run `rodo test` (recommended, not required). Report the result honestly.
+4. Record new decisions (spec.md `## Decisions`; MEMORY.md when the card closes).
+5. Update any doc your change made wrong (same commit).
+6. Check scope (below).
+7. Run `rodo sync`. If it reports errors for a card you touched, fix them and run it again (at most twice), then tell the user what is left.
+8. If `rodo sync` reports `ARCHIVE_CONFIRM_REQUIRED` (more than 10 card files deleted): **stop and ask the user**. List the cards, and say why they are gone. Never add `--confirm-archive` yourself, never restore or delete files to make the warning go away, and never skip it silently. Only run `rodo sync --confirm-archive` after the user explicitly says yes in this session.
+
+## What you always do
+
+1. **A card for every new feature, change or improvement** (planner.md). A small change that does not change described behaviour gets one CHANGELOG line instead (small-change.md).
+2. **A raw request** from the user that is not planned yet becomes a `todo` card with `## Goal` and `## Why` in its description (template `templates/request.rodo.md`; no separate request document).
+3. **Keep the docs true.** Code and current documentation are one system: when code changes something a current document describes, the document changes in the same piece of work. Historical cycle documents are preserved as they were (see "Documents: current, active, historical").
+4. **Never delete files** without the user's OK.
+5. **No secrets** (passwords, API keys, tokens, private keys, connection strings) in any file under `rodo/`, in cards, in Progress notes, in commit messages or in your replies. Refer to them by name ("the payment API key") only.
+
+## Fields you must never write
+
+`id`, `tempId`, `boardId`, `updatedAt`, `locked`, any `<!-- rodo:… -->` comment, the first-line `<!-- RODO_ERROR … -->`, and `- Answer:` lines under a decision. `rodo sync` writes them. If a file starts with `RODO_ERROR`, fix the cause; sync removes the line.
+
+## Statuses (exactly five)
+
+| Status | Meaning | Who sets it |
+|---|---|---|
+| `todo` | planned, not started (also: a raw request) | planner |
+| `in_progress` | being worked on | coder, when work starts |
+| `blocked` | cannot go on. Needs `blockerType` and a plain reason in `statusReason:` | you, by yourself; tell the user |
+| `cancelled` | the user decided not to do it; the card stays, with `statusReason: <reason>` | only with the user's OK |
+| `done` | finished; if tests were run, they passed (tests stay optional, D6) | coder |
+
+`blockerType`: `decision` (the user must choose) · `requirement` (the goal is unclear) · `technical` (you cannot solve it) · `test` (a test cannot run or keeps failing) · `environment` (tool, server, dependency) · `external` (waiting for someone/something outside) · `permission` (an access key or right is missing).
+
+## Stuck rule (failure signature)
+
+`rodo test` prints a failure signature (12 hex characters) and writes `- Last failure: <sig> ×<n>`. When the **same signature** appears twice (`×2`, or `RODO_STUCK`), stop: set `status: blocked`, `blockerType: test` (or `technical`), write the problem in plain words in `statusReason:`, and ask the user: clarify, try a stronger model, or cancel. Different failures do not count: fix them and go on. Without `rodo test`, apply the same rule yourself: same error message at the same place twice = stuck. This is also the limit of the FIX → VERIFY loop.
+
+## Needs a decision
+
+This is for choices that come up **during work**; questions before planning are Clarification (see "Ask only what matters"). When only the user can choose (behaviour, wording, priority, trade-off), do not guess. Add to the card, after `## Refs`:
+
+    ## Decision: <one short question in the simple language>
+
+    - A: <option>
+    - B: <option>
+
+(2–6 options, keys A–F.) Set `status: blocked`, `blockerType: decision`, `statusReason: waiting for your decision: <question>`, run `rodo sync`, and tell the user to answer on the web. Never write the `- Answer:` line yourself.
+
+## Scope
+
+A card may have `scope: {allowed: [...], forbidden: [...]}`. Stay inside `allowed`; never touch `forbidden`. When you find work outside the scope (or a new requirement): do not do it silently. Write `- Out of scope: <item> → new card` in Progress notes, tell the user, and (planner) create a new `todo` card for it. A small change of the same feature: update the card and its docs and tell the user.
+
+## Pick your role, then open one playbook
+
+| Situation | Playbook |
+|---|---|
+| New feature, change, improvement; a request; a stuck card the user sent back | `planner.md` |
+| You were given a card to implement or continue | `coder.md` |
+| The repo has code but no `rodo/<project>/` yet | `onboarding.md` |
+| Typo, style, refactor or a fix that does not change described behaviour | `small-change.md` |
+| You write or fix tests (optional, recommended) | `testing.md` |
+
+## Workflow levels
+
+Every request gets one level. The yes/no classification questions are in `planner.md` ("Classify"). Documents are recommendations; nothing is forced.
+
+- **QUICK** — the small-change rule (`small-change.md`): no card, one `CHANGELOG.md` line, a one-line docs glance.
+- **STANDARD** — a card, `spec.md` and a short `simple.md`; `acceptance.feature` optional.
+- **MAJOR** — like STANDARD plus `design.md` and `acceptance.feature`; an independent review is recommended.
+
+    UNDERSTAND -> DOC IMPACT -> CLASSIFY (provisional)
+        QUICK:              change + 1 CHANGELOG line + one-line docs glance -> DONE
+        STANDARD / MAJOR:   CLARIFY (only important, <= 5)
+                            -> RECLASSIFY if scope changed
+                            -> DOCS/PLAN (spec; simple; design if MAJOR)
+                            -> TASKS -> BUILD
+                            -> VERIFY (fitting checks + doc consistency)
+                            -> REVIEW (optional; recommended for MAJOR)
+                            -> FIX <-> VERIFY ... same failure twice -> BLOCKED
+                            -> DONE
+
+## Ask only what matters
+
+**Ask only when** the answer changes expected behaviour, when there are several reasonable options, when a wrong choice would be costly to undo, or when there is no safe default. Otherwise choose a low-risk, reversible default, write it in `spec.md` `## Decisions` as `<decision> (default, not asked). Because <reason>.`, and go on. The goal is less rework, not more conversation.
+
+**Clarification** happens **before planning**, in the conversation, about *what* to build. The card is `todo` (or does not exist yet). Answers go into `spec.md` `## Decisions`. The status does not change.
+
+**Needs Decision** happens **during work** (`in_progress`), when only the user can choose and you cannot go on. Use a `## Decision:` section on the card, set `status: blocked` and `blockerType: decision`, and the user answers on the web ("Needs a decision" below, unchanged).
+
+Do not turn ordinary clarification questions into `## Decision:` sections, and do not stop mid-work for trivial choices (use the ask rule).
+
+## Documents: current, active, historical
+
+**Code and current documentation are one system.** When code changes something a current document describes, the document changes in the same piece of work. Historical cycle documents are preserved as they were, unless they are explicitly marked current.
+
+| Kind | Files | Rule |
+|---|---|---|
+| **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. |
+| **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. |
+| **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`. |
+
+Before planning, list the current docs this change will make wrong in `spec.md` `## Documentation Impact` (planner.md). In VERIFY, check that each of them was updated (coder.md "Verify and fix").
+
+## Verify and review
+
+Run the checks that fit this change with the project's own tools; RODO runs nothing itself. Always include documentation consistency. Write `- Verified: <check> ✓/✗, …` in Progress notes. FIX → VERIFY until it passes or the stuck rule applies. An independent review is optional (recommended for MAJOR) and never replaces tests. The menu and the details are in `coder.md` "Verify and fix".
+
+## Project layout
+
+    AGENTS.md                         pointer to this skill
+    .agents/skills/rodo/              this skill (kit-owned; updated by rodo init)
+    rodo/
+      kit.json                        installed kit version
+      <project>/
+        project.json                  board binding and settings (no secrets)
+        MAP.md  MEMORY.md  RULES.md  CHANGELOG.md
+        project/{brief,architecture,glossary}.md
+        cycles/NNN-slug/
+          card.rodo.md                the card (synced with the board, not in git)
+          simple.md                   plain explanation (shown read-only on the web)
+          spec.md                     technical rules **R1**, **R2** …
+          design.md                   design for MAJOR changes (optional)
+          acceptance.feature          scenarios tagged @R1 … (optional)
+        inbox/                        cards created on the web (not in git)
+
+Card format details: the comments in `templates/card.rodo.md` and `rodo validate`. Templates come in two languages: `templates/` (Persian) and `templates/en/` (English); use the one that matches `language.simple` in `project.json`. `rodo new "<title>"` creates `cycles/NNN-slug/` with the card, `simple.md` and `spec.md` from them.
+
+## Tools
+
+| Command | Use |
+|---|---|
+| `rodo sync` | start and end of every session |
+| `rodo resume [card] [--full]` | context for a new session |
+| `rodo status` | board vs local, side by side |
+| `rodo test [card]` | run the card's test command, record the failure signature |
+| `rodo new "<title>"` | create the next cycle folder with `card.rodo.md`, `simple.md`, `spec.md` (`--major` adds `design.md` and `acceptance.feature`) |
+| `rodo validate` | check card files (never blocks; `--strict` exits 1 on errors, for CI) |
+| `rodo doctor` | find setup problems |
+| `rodo init` | install/update the kit, bind a board. **Never create a board yourself**: if a board is needed, ask the user to run `rodo init` in their terminal. |
+
+Optional, if available in the project: Graphify (code map, for Documentation Impact and finding affected code) and Context7 (current library docs). Never install them yourself; RODO works without them.

package/dist/kit/.agents/skills/rodo/coder.md

@@ -0,0 +1,82 @@
+> یادداشت فارسی: دستورالعمل کدنویس. از روی کارت کار کن، فقط ارجاع‌ها را بخوان، قدم‌به‌قدم جلو برو، سندها را درست نگه دار، و آخر هر جلسه «Progress notes» را به‌روز کن. همهٔ مسیرها نسبت به `rodo/<project>/` هستند.
+
+# Coder playbook
+
+You implement one card. Any model may do this; the user chooses.
+
+## Before you start (every session)
+
+Follow "Session start" in SKILL.md (git check without pulling → rodo sync → rodo resume → refs only → approval check → answered decisions). Then set `status: in_progress`.
+
+## Doing the steps
+
+For each unticked step, in order:
+1. Do only what the step says.
+2. Check it (unit test, build, or the command the step names).
+3. Tick it `- [x]`; add `[hours: H:MM]` only if you know the real time.
+4. Commit with the card number in the message, e.g. `feat: discount code input [cycle 002]`, so people can find the work later.
+
+If your change makes a project doc wrong (`project/*`, the card's `spec.md`), fix the doc in the same commit.
+
+## Tests (if the card has scenarios)
+
+- Step definitions go in the folder from `project.json` `stepsDirs`. They must really drive the app (browser, API or CLI) and really assert. See `testing.md`.
+- Run the card's tests with `rodo test` (it uses the card's `test.command`, or `testCommand` from `project.json`). Tick `تست پذیرش پاس شد` only after a real passing run.
+- **Never weaken a scenario or test to make code pass:** no deleting scenarios, loosening assertions, `@skip`/`.only`/`test.fixme`, or changing an expected value to match buggy output. If a scenario looks wrong, explain why to the user; change it only if they agree.
+
+## Scope changes while coding
+
+- Out of the card's `scope` or a new requirement: do not do it silently. Write `- Out of scope: <item> → new card` in Progress notes and tell the user.
+- Small change in the same feature: update the scenario/spec/steps of this card, tell the user, continue (wait if there is an unticked approval item).
+- Big new feature: do not add it. Write it under `- Remaining:` as "needs a new card" and tell the user.
+
+## Stuck
+
+Use the stuck rule in SKILL.md: same failure signature twice → `status: blocked`, `blockerType: test` or `technical`, a plain `statusReason:`, ask the user. Waiting for an answer, a key or another card → `status: blocked` with the matching `blockerType` (`decision`, `permission`, `external`). If only the user can choose, write a `## Decision:` section (SKILL.md). When solved: `status: in_progress`, remove `statusReason` and `blockerType`. Never set `cancelled` yourself; only with the user's OK.
+
+## Verify and fix
+
+**VERIFY** — pick the checks that fit this change and run them with the project's own tools (RODO runs nothing itself):
+- build, typecheck, lint;
+- unit, integration, e2e;
+- architecture rules, security checks;
+- acceptance (the card's `test` command via `rodo test`, or the acceptance criteria checked one by one);
+- documentation consistency (below).
+
+Write the result in Progress notes as `- Verified: <check> ✓/✗, …`.
+
+**Documentation Consistency** (part of VERIFY):
+- Check that every file listed under Documentation Impact was updated.
+- Check that the CURRENT docs and the active cycle docs still describe the code.
+- If something does not match: FIX, then VERIFY again.
+- If a current doc contradicts a `MEMORY.md` decision, stop and ask the user (as small-change.md already says).
+
+**REVIEW (optional; recommended for MAJOR)** — an independent AI session or model reads the change and checks:
+- requirement coverage; acceptance criteria;
+- regressions; architecture fit;
+- missing tests; maintainability;
+- unintended changes.
+
+A review never replaces tests. Its findings go back to FIX.
+
+**FIX loop** — FIX → VERIFY until everything passes (→ DONE) or the stuck rule applies: the **same failure twice** (same failure signature, or the same error at the same place) → `status: blocked` with `blockerType: test` or `technical` (SKILL.md "Stuck rule"). Different failures do not count.
+
+## End of every session
+
+Follow "Session close" in SKILL.md. Always finish with `rodo sync`.
+
+## Close (all steps ticked)
+
+The folder does not move.
+1. Card: `status: done`.
+2. `MAP.md`: add the cycle under `## انجام‌شده` (one line, link to simple.md or the card folder) and update "الان کجاییم".
+3. `MEMORY.md`: append each `## Decisions` line of spec.md as `- YYYY-MM-DD — <decision>. چون <reason>. (cycle NNN)`.
+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`.
+
+## Rules
+
+- Never tick an approval item or change its text. Only a person can approve, in the web app. Never answer a `## Decision:` yourself.
+- Never edit `id:` lines or `<!-- rodo:... -->` comments.
+- Do not change `members`, `startAt`, `dueAt`, `priority` unless the user asks: the team owns them.
+- Never delete files you did not create in this card without asking.
+- Keep changes inside the steps. Unrelated fixes go to `small-change.md` or a new card.

package/dist/kit/.agents/skills/rodo/onboarding.md

@@ -0,0 +1,28 @@
+> یادداشت فارسی: برای پوشه‌ای که از قبل کد دارد ولی هنوز `rodo/` ندارد. هیچ چیزی پاک نمی‌شود و جابه‌جایی‌ها اول پیشنهاد می‌شوند.
+
+# Onboarding playbook (existing folder)
+
+Goal: create `rodo/<project>/` so the project can follow the method, without changing any existing file.
+
+## Steps
+
+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.
+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.
+3. **brief.md and architecture.md**: describe what exists today. Mark guesses with `(حدس)` so the user can confirm.
+4. **MEMORY.md**: decisions visible in the code or docs (framework, database, auth method...). One line each with the reason if known, else `چون: نامعلوم`.
+5. **Finished work → done cycles.** For each finished feature a user can see, create `rodo/<project>/cycles/NNN-slug/` with:
+   - `simple.md` whose FIRST line is `<!-- rodo:onboarded -->`, then 3-6 simple lines;
+   - `card.rodo.md` with `status: done`, refs to `simple.md` and the main code files, and steps as ticked items if they are known. No approval item: past work is not re-approved.
+   List each one under "انجام‌شده" in `MAP.md`.
+   No `spec.md` or `acceptance.feature` is needed for onboarded done cycles.
+6. **Unfinished work → pending cycles.** For each TODO, half-done feature, or open issue, create `rodo/<project>/cycles/NNN-slug/` with the same two files and `status: todo`, listed under "بعدی" in `MAP.md`. Before anyone codes it, the planner completes it like any new card (`spec.md` with rules `**R1**`..., optional `acceptance.feature` and approval item) and removes the `rodo:onboarded` line.
+7. **MAP.md**: sections `## انجام‌شده`, `## لغوشده` (abandoned work, with the reason after `—`), `## بعدی`, plus "الان کجاییم" in a few lines. Onboarded done cycles need no `acceptance-result.json`.
+8. **Proposals, not actions.** Write `rodo/<project>/onboarding-report.md` with: docs that could move into `rodo/<project>/project/`, duplicated or outdated docs, and files that look unused. Each line: current path → proposed action → reason. Do NOT move or delete anything until the user approves each line.
+9. Add `*.rodo.md` and `.rodo/` to `.gitignore` only if the user agrees. If they decline, tell them cards may end up in git and continue.
+10. Show the user MAP.md and the report. If the RODO CLI is installed, `rodo validate` lists card-format warnings; fix what it reports.
+11. **Last step:** ask the user to run `rodo init` in their own terminal to connect the board (the AI never creates boards).
+
+## Never
+
+- Never delete, rename, or rewrite existing files during onboarding.
+- Never invent history. If you are unsure whether something is finished, make it a pending cycle and say so.

package/dist/kit/.agents/skills/rodo/planner.md

@@ -0,0 +1,95 @@
+> یادداشت فارسی: دستورالعمل برنامه‌ریز. برای هر قابلیت، تغییر یا بهبود تازه یک کارت و سندهایش را می‌سازد. برای این نقش یک مدل قوی پیشنهاد می‌شود، ولی انتخاب با کاربر است. همهٔ مسیرها نسبت به `rodo/<project>/` هستند.
+
+# Planner playbook
+
+You turn a request into one card (with its docs) that any model can implement without asking questions.
+
+## Planner as router
+
+understand → documentation impact → classify → clarify → reclassify (if the answers changed the scope) → create the documents for the level → task breakdown (the card checklist) → hand off.
+
+## Inputs you read
+
+1. Run `rodo sync`, then read `MAP.md`, `MEMORY.md`, `project.json` (languages), `project/*`.
+2. Only the code and earlier cycles the request touches. Search; do not read the whole repo.
+
+## Is a card needed?
+
+Yes, for every new feature, change or improvement, and for every change to behaviour that a card, spec or scenario describes. No, only for small changes that do not change described behaviour (see `small-change.md`). If an existing open card covers the request, update that card instead of making a new one.
+
+**Requests:** if the user only describes a need and does not want planning now, create a `todo` card in `inbox/` (or the next cycle folder) with `## Goal` and `## Why` (`templates/request.rodo.md`). Planning later turns it into a cycle: move the file into `cycles/NNN-slug/card.rodo.md`; its id stays.
+
+## Documentation Impact (after understand, before classify)
+
+- List the current documents this change will make wrong or must extend.
+- 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).
+- Write the list in `spec.md` `## Documentation Impact` (`- <path> — <what changes>`, or `- none — <why>`).
+- QUICK: do this in your head and fix any doc you made wrong (small-change.md).
+
+## Classify
+
+**Step 1 — QUICK?** Ask the small-change question (`small-change.md`). "No" → **QUICK**: follow `small-change.md` (no card, one CHANGELOG line, a one-line docs glance). Not sure → not QUICK.
+
+**Step 2 — MAJOR?** If **any** answer is yes, it is **MAJOR**:
+1. Does it add or change architecture: a new module, service, package, external integration or dependency, or how existing parts talk to each other?
+2. Does it need a coordinated design across several areas, beyond the usual "one screen + its API"?
+3. Does it change a public API or contract that other code or users rely on, or the data model in a way that needs existing data migrated?
+4. Does it touch security, authentication, money, or deleting data?
+5. Would a wrong approach be expensive to undo (roughly more than a day of rework)?
+6. Are there two or more reasonable technical approaches with real trade-offs?
+
+**Otherwise STANDARD.** Not sure between STANDARD and MAJOR → STANDARD, and say so in one line. The level is provisional until Clarify is done. Write it on the card as `workflow: standard` or `workflow: major` (optional field, local only). The card size rule (one card ≈ 1–5 days; bigger → split) still applies; follow-up cards of a MAJOR change link to the same `design.md` in their `## Refs`.
+
+## Clarify (before planning)
+
+- Ask only the important ambiguities (the ask rule in SKILL.md), **at most 5 questions per round**.
+- Prefer multiple choice (`A`, `B`, `C` … plus "other: …"). For each question, say in one line why it matters and which default you will use if the user has no preference.
+- Low-risk, reversible choices are not asked: choose the default and record it.
+- Write the answers in `spec.md` `## Decisions` (and in `simple.md` when the user will see the difference).
+- Questions still open go under `spec.md` `## Open Questions`. Do not start BUILD while an open question would change the expected behaviour.
+- QUICK changes normally skip this step. If the answers change the size or risk of the change, classify again.
+
+## Documents per level
+
+| Level | Documents (all recommended; nothing is forced) |
+|---|---|
+| QUICK | none; one `CHANGELOG.md` line |
+| STANDARD | `spec.md` (with Acceptance criteria, Documentation Impact, Open Questions, Decisions); a short `simple.md` (it is the human brief shown on the web, and the validator warns `CYCLE_SIMPLE_MISSING`); `acceptance.feature` optional |
+| MAJOR | `simple.md` + `design.md` + `spec.md` + `acceptance.feature`; architecture decisions in `design.md` `## Decisions` plus one `MEMORY.md` line |
+
+`simple.md` is the **human brief**: what the user gets, why, what is not included, one example. **No implementation details.** Technical details go in `spec.md` and `design.md`. There is no ADR folder.
+
+## Steps
+
+1. **Understand and restate** the need in 2-3 simple sentences in the simple language. Then Documentation Impact, Classify, Clarify (above).
+2. **Size.** One card = one thing a user can see and test, about 1-5 days, 3-12 steps. Bigger: propose a split and ask which part comes first.
+3. **Number and folder.** Run `rodo new "<title>"` (it picks the next free `NNN` and an English slug and fills the templates), or do it by hand: next free `NNN` in `cycles/` (finished and cancelled folders keep their numbers), slug short English `a-z0-9-`, create `cycles/NNN-slug/`.
+4. **Write the docs from `templates/`** for the level:
+   - `simple.md` (simple language, max ~250 words, no technical words).
+   - `spec.md` (technical language): numbered bold rules `**R1**`, `**R2**` ..., data, API, screens, files to create or change, then `## Acceptance criteria`, `## Documentation Impact`, `## Open Questions`, `## Decisions` (one line each, with "because"). Write the acceptance criteria before BUILD.
+   - `design.md` for MAJOR only.
+   - `acceptance.feature` (optional, recommended): scenario text in the simple language, English keywords, tag `@cycle-NNN`, and tag each scenario or `Rule:` with the rule IDs it proves (`@R2`). Concrete values; one visible behaviour per scenario. Ask the user whether they want tests for this card if unsure.
+   - `card.rodo.md`: a short title (no number: the number comes from the folder), short description, `status: todo`, `workflow: standard` or `major`, `scope: {allowed, forbidden}` (3–8 short items each), `test: {adapter, command}` if the card has a runnable test (adapter `web`, `api`, `cli`, `mobile`, `iot` or `other`), `## Refs` to the docs above and any code the coder must read (paths start with `/rodo/<project>/`), `## Checklist: قدم‌ها` (English projects: `## Checklist: Steps`) with one item per step (small, checkable, says what "done" means). Add the optional approval item first if the user wants to approve (only a person ticks it on the web); add a step-definitions step and the last item `تست پذیرش پاس شد` (English: `Acceptance test passed`) only if the card has scenarios.
+5. **Glossary:** add new words the docs use.
+6. **Hand over:** tell the user which files to read (`simple.md`, and `design.md` or `acceptance.feature` if there are any) and, if the card has an approval item, that approval = ticking `تأیید کاربر` in the web app. Run `rodo sync`.
+
+## Changing scope
+
+- **Before coding:** edit the same card and docs.
+- **During coding, small change in the same feature:** update `simple.md`, `spec.md`, the scenario and the steps of the same card; tell the user what changed.
+- **Big new feature:** a new card. Never stretch a running card.
+
+## When a card is stuck
+
+The coder sets `status: blocked`, a `blockerType` and the reason in `statusReason:` (after the same failure twice, or while waiting for something). The user decides:
+1. **Clarify:** you fix `spec.md` (and scenarios if needed), write the decision in `## Decisions`, set `status: in_progress` and remove `statusReason` and `blockerType`.
+2. **Stronger model:** nothing to change; the user reruns the coder with another model.
+3. **Cancel:** with the user's OK, set `status: cancelled` and the reason in `statusReason:`, add the cycle under `## لغوشده` in MAP.md with the reason after `—`, add a MEMORY line, tag its scenarios `@cancelled`. Keep the card file and the folder.
+
+## Never
+
+- Never write production code in this role, except tiny examples inside `spec.md`.
+- Never tick an approval item or answer a decision.
+- Never create a board. Never run `rodo init --create-board`.
+- Never weaken a scenario to make the implementation easier.
+- Never put details in the card description; they go in `spec.md`.

package/dist/kit/.agents/skills/rodo/small-change.md

@@ -0,0 +1,44 @@
+> یادداشت فارسی: تغییر کوچکی که رفتار توضیح‌داده‌شده در کارت‌ها، spec یا سناریوها را عوض نمی‌کند کارت نمی‌خواهد؛ فقط یک خط در `rodo/<project>/CHANGELOG.md` (تاریخ، چه، چرا، فایل‌ها).
+
+# Small change playbook (no card)
+
+This is the QUICK level.
+
+## The decision rule
+
+Ask one question before you start:
+
+> **After this change, would any sentence in a card, a `simple.md`, a `spec.md` rule or an `acceptance.feature` scenario become false, or would a user see or be able to do something different?**
+
+- **No → small change.** No card. Make the change and add ONE line to `CHANGELOG.md`.
+- **Yes → card.** If an open card (`todo`, `in_progress` or `blocked`) describes this behaviour, update that card and its docs. Otherwise create a new card (`planner.md`). Finished (`done`) and `cancelled` cards are not reopened; a new card refers to the old one.
+- **Not sure → treat it as "Yes"**, or ask the user.
+
+## Examples
+
+| Change | Card? | Why |
+|---|---|---|
+| Typo in a code comment or a doc | No | Behaviour is the same |
+| Typo in a page text that no scenario or spec quotes | No | Nothing described becomes false |
+| Rename variables, split a function, move a file (refactor); tests still pass | No | Same behaviour |
+| Colour, spacing or font that no scenario or spec mentions | No | Style only |
+| Dependency update with no visible change | No | Same behaviour |
+| Bug: the code did not do what the spec/scenario already says, and the fix makes it do exactly that | No | The docs were already right |
+| Button text that a scenario quotes (e.g. «اعمال» → «اعمال کد») | **Yes** | The scenario sentence becomes false |
+| An error message that a spec rule lists word for word | **Yes** | The rule changes |
+| Minimum order 200,000 → 150,000 toman | **Yes** | A rule's value changes |
+| A new button, field, page or option | **Yes** | New behaviour = new card |
+| A bug fix that changes what users see compared to the spec | **Yes** | Described behaviour changes |
+
+## Steps
+
+1. Read `MAP.md` and `MEMORY.md` (or run `rodo resume`).
+2. Apply the decision rule. If the answer is "Yes", stop here and go to `planner.md`.
+3. Make the change.
+4. **Docs glance (one line):** if the change makes a project doc wrong (`rodo/<project>/project/*`, `MAP.md`, a `spec.md` file path or name), fix that doc too. If it contradicts a line in `MEMORY.md`, stop and ask the user.
+5. Append ONE line to `CHANGELOG.md`, newest at the bottom:
+   `- YYYY-MM-DD | what changed | why | files`
+   Example: `- 2026-10-14 | رنگ دکمهٔ «افزودن به سبد» سبز شد | خواستهٔ مریم برای دیده شدن بهتر | src/catalog.css`
+6. Commit (code + CHANGELOG line together).
+
+A small change needs no `rodo sync` unless a card changed.

package/dist/kit/.agents/skills/rodo/templates/acceptance.feature

@@ -0,0 +1,18 @@
+# سناریوهای پذیرش (اختیاری، ولی پیشنهاد می‌شود). هیچ‌وقت سناریو را ضعیف نکنید تا کد پاس شود.
+# کلیدواژه‌ها انگلیسی‌اند (برای ابزار)، متن به زبان ساده. هر سناریو با شمارهٔ قانون spec.md برچسب می‌خورد (@R1).
+@cycle-{{NNN}}
+Feature: {{عنوان چرخه}}
+
+  @R1
+  Rule: {{یک قانون از simple.md}}
+
+    Scenario: {{مسیر اصلی}}
+      Given {{وضعیت اولیه با عدد واقعی}}
+      When {{کاری که کاربر می‌کند}}
+      Then {{چیزی که کاربر می‌بیند}}
+
+    @R2
+    Scenario: {{حالت خطا}}
+      Given {{...}}
+      When {{...}}
+      Then {{پیام دقیقی که کاربر می‌بیند}}

package/dist/kit/.agents/skills/rodo/templates/card.rodo.md

@@ -0,0 +1,33 @@
+---
+schemaVersion: 2
+title: "{{عنوان کوتاه}}"
+status: todo
+# statusReason: ...   # only when status is blocked or cancelled: the reason in plain words
+priority: medium
+# workflow: standard   # optional: quick | standard | major; local only, never sent to the board
+members: []
+scope:
+  allowed: []
+  forbidden: []
+---
+
+{{دو تا پنج خط ساده: کاربر چه چیزی می‌گیرد. جزئیات در spec.md است.}}
+
+## Progress notes
+
+- Updated: {{YYYY-MM-DD}}
+- Done: هنوز شروع نشده
+- Remaining: همهٔ قدم‌ها
+
+## Refs
+
+- [توضیح ساده](/rodo/{{project}}/cycles/{{NNN-slug}}/simple.md)
+- [سند فنی](/rodo/{{project}}/cycles/{{NNN-slug}}/spec.md)
+<!-- [سناریوهای پذیرش](/rodo/{{project}}/cycles/{{NNN-slug}}/acceptance.feature) — uncomment only after that file exists -->
+
+## Checklist: قدم‌ها
+
+<!-- - [ ] تأیید کاربر: simple.md و سناریوها [approval] — add only when the user asked for a human approval (D5) -->
+- [ ] {{قدم ۱: کار مشخص + نشانهٔ انجام شدن}}
+- [ ] {{قدم ۲}}
+- [ ] تست پذیرش پاس شد

package/dist/kit/.agents/skills/rodo/templates/design.md

@@ -0,0 +1,15 @@
+# {{NNN}} — {{title}}: design
+
+> Only for MAJOR changes. Written in the technical language. The coder reads it together with spec.md.
+
+## Problem
+## Proposed approach
+## Architecture impact
+## Components affected
+## Data / API impact
+## Trade-offs
+## Risks
+## Alternatives considered
+## Decisions
+
+- {{decision}}. Because {{reason}}. (also one line in MEMORY.md)

package/dist/kit/.agents/skills/rodo/templates/en/acceptance.feature

@@ -0,0 +1,18 @@
+# Acceptance scenarios (optional, recommended). Never weaken a scenario to make the code pass.
+# Keywords are English (for the tools); tag each scenario with the spec.md rule it proves (@R1).
+@cycle-{{NNN}}
+Feature: {{cycle title}}
+
+  @R1
+  Rule: {{one rule from simple.md}}
+
+    Scenario: {{main path}}
+      Given {{starting state with real values}}
+      When {{what the user does}}
+      Then {{what the user sees}}
+
+    @R2
+    Scenario: {{error case}}
+      Given {{...}}
+      When {{...}}
+      Then {{the exact message the user sees}}

package/dist/kit/.agents/skills/rodo/templates/en/card.rodo.md

@@ -0,0 +1,32 @@
+---
+schemaVersion: 2
+title: "{{short title}}"
+status: todo
+# statusReason: ...   # only when status is blocked or cancelled: the reason in plain words
+priority: medium
+# workflow: standard   # optional: quick | standard | major; local only, never sent to the board
+members: []
+scope:
+  allowed: []
+  forbidden: []
+---
+
+{{two to five plain lines: what the user gets. Details are in spec.md.}}
+
+## Progress notes
+
+- Updated: {{YYYY-MM-DD}}
+- Done: not started yet
+- Remaining: all steps
+
+## Refs
+
+- [Plain explanation](/rodo/{{project}}/cycles/{{NNN-slug}}/simple.md)
+- [Technical spec](/rodo/{{project}}/cycles/{{NNN-slug}}/spec.md)
+<!-- [Acceptance scenarios](/rodo/{{project}}/cycles/{{NNN-slug}}/acceptance.feature) — uncomment only after that file exists -->
+
+## Checklist: Steps
+
+<!-- - [ ] User approval: simple.md and scenarios [approval] — add only when the user asked for a human approval -->
+- [ ] {{step 1: a concrete task + how you know it is done}}
+- [ ] {{step 2}}

package/dist/kit/.agents/skills/rodo/templates/en/request.rodo.md

@@ -0,0 +1,14 @@
+---
+schemaVersion: 2
+title: "{{request title}}"
+status: todo
+priority: medium
+---
+
+## Goal
+
+{{what the user wants, in one or two sentences}}
+
+## Why
+
+{{why it matters}}

package/dist/kit/.agents/skills/rodo/templates/en/simple.md

@@ -0,0 +1,21 @@
+# {{NNN}} — {{title}}
+
+## What you get
+
+{{two to four plain sentences}}
+
+## Why
+
+{{one or two sentences}}
+
+## Not in this cycle
+
+- {{item}}
+
+## An example
+
+{{a short story of use, with real numbers}}
+
+## If you want to approve (optional)
+
+Read this file and `acceptance.feature`. If the card has a "User approval" step and everything is right, tick it **on the web**; only a person can tick it. If something is wrong, comment here or on the card.

package/dist/kit/.agents/skills/rodo/templates/request.rodo.md

@@ -0,0 +1,14 @@
+---
+schemaVersion: 2
+title: "{{عنوان درخواست}}"
+status: todo
+priority: medium
+---
+
+## Goal
+
+{{کاربر چه چیزی می‌خواهد، در یک یا دو جمله}}
+
+## Why
+
+{{چرا مهم است}}

package/dist/kit/.agents/skills/rodo/templates/simple.md

@@ -0,0 +1,21 @@
+# {{NNN}} — {{عنوان}}
+
+## چه چیزی می‌گیرید
+
+{{دو تا چهار جملهٔ ساده}}
+
+## چرا
+
+{{یک یا دو جمله}}
+
+## چه چیزی در این چرخه نیست
+
+- {{مورد}}
+
+## یک مثال
+
+{{یک داستان کوتاه از استفاده، با عددهای واقعی}}
+
+## اگر می‌خواهید تأیید کنید (اختیاری)
+
+این فایل و `acceptance.feature` را بخوانید. اگر کارت قدم «تأیید کاربر» دارد و همه‌چیز درست است، آن را **در وب** تیک بزنید؛ فقط یک آدم می‌تواند این تیک را بزند. اگر چیزی درست نیست، همین‌جا یا روی کارت کامنت بگذارید. اگر برای این کار تأیید نمی‌خواهید، به AI بگویید آن قدم را نگذارد.