mdrules 0.0.0-stage → 0.1.0

package/templates/docs/architecture.md

@@ -0,0 +1,21 @@
+---
+type: architecture
+status: pending
+updated: {{date}}
+---
+
+# Architecture
+
+## Structure
+
+```tree
+src/
+  # describe the main folders here
+```
+
+## Flow
+
+```mermaid
+flowchart LR
+  User --> App --> Data[(Storage)]
+```

package/templates/docs/decisions.md

@@ -0,0 +1,11 @@
+---
+type: decision
+status: in-progress
+updated: {{date}}
+---
+
+# Decisions
+
+| id | date | decision | reason |
+|---|---|---|---|
+| D1 | {{date}} | | |

package/templates/docs/phases/README.md

@@ -0,0 +1,25 @@
+---
+type: note
+updated: {{date}}
+---
+
+# Phases
+
+Create one file per phase as the project evolves, e.g. `01-setup.md`:
+
+```md
+---
+type: phase
+phase: 1
+status: pending
+updated: {{date}}
+---
+
+# Setup
+
+## Goal
+
+## Tasks
+
+- [ ] ...
+```

package/templates/docs/rules.md

@@ -0,0 +1,11 @@
+---
+type: rules
+status: in-progress
+updated: {{date}}
+---
+
+# Rules
+
+| id | rule | why |
+|---|---|---|
+| R1 | | |

package/templates/docs/tasks.md

@@ -0,0 +1,15 @@
+---
+type: tasks
+status: in-progress
+updated: {{date}}
+---
+
+# Tasks
+
+## Now
+
+- [ ] First task
+
+## Later
+
+- [ ] Next task

package/templates/main.md

@@ -0,0 +1,15 @@
+# {{name}}
+
+## Overview
+
+<!-- What this project is and who it is for. -->
+
+## Docs
+
+| File | Purpose |
+|---|---|
+| `docs/architecture.md` | System design, components and data flow |
+| `docs/rules.md` | Project rules and conventions |
+| `docs/tasks.md` | Current task list |
+| `docs/decisions.md` | Decision log |
+| `docs/phases/` | One file per phase, created as the project evolves |

package/templates/rules/ask-before-commit.md

@@ -0,0 +1,4 @@
+---
+title: Ask before committing
+---
+- Never commit, push or open pull requests without asking first.

package/templates/rules/lang-es-code-en.md

@@ -0,0 +1,5 @@
+---
+title: Spanish conversation, English code
+---
+- Write prompts answers and explanations in Spanish.
+- Write code, comments, commit messages and every `.md` file in English.

package/templates/rules/pnpm-only.md

@@ -0,0 +1,4 @@
+---
+title: pnpm only
+---
+- Never use npm or yarn; always use pnpm (`pnpm add`, `pnpm dlx`, `pnpm exec`).

package/templates/skill/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: mdrules
+description: Conventions for every .md file in this project (CLAUDE.md, AGENTS.md, docs/) and the translation sync. Use when creating or editing any .md file, when finishing a task or phase, at the start of a session, or when the user runs /mdrules sync.
+---
+
+# mdrules
+
+The user reads and edits this project's Markdown in **mdrules**, a visual editor. Write `.md` files so it can present them well.
+
+## Language
+
+- Every `.md` file is written in the project's **source language**, declared in the main doc's "Working rules" section (`<!-- mdrules:source-lang:xx -->`, default English). Frontmatter keys are always English.
+- Translations live in `.mdrules/i18n/<lang>/<same path>` (hidden, git-ignored). Never treat them as sources.
+
+## Frontmatter
+
+Put this at the top of docs that track work:
+
+
+
+```yaml
+---
+type: phase        # phase | tasks | rules | architecture | decision | note
+status: pending    # pending | in-progress | done | blocked
+phase: 2           # only for type: phase (ordering)
+updated: YYYY-MM-DD
+---
+```
+
+- Update `status` and `updated` whenever you change the doc.
+- Phases: one file per phase in `docs/phases/NN-name.md`, created when the phase starts being planned.
+
+## Content conventions
+
+| Need | Use |
+|---|---|
+| Tasks / progress | GFM checklists `- [ ]` / `- [x]`; optional `#tag` and `@priority` at the end |
+| Rules, decisions, lists of records | GFM tables, first column `id` |
+| Folder / module structure | a ` ```tree ` block: indented lines; two spaces + `#` starts a description |
+| Flows, sequences, states | a ` ```mermaid ` block |
+
+When you finish a task: tick its checkbox, update the doc's `status`/`updated`, and set the phase to `done` when all its tasks are done.
+
+Never edit the section between `<!-- mdrules:rules:start -->` and `<!-- mdrules:rules:end -->` by hand; it is generated from the user's rule presets.
+
+## Translation sync (`/mdrules sync`)
+
+Run this when the user asks for `/mdrules sync`, at the start of a session, and after you edit any `.md` file.
+
+1. `mdrules sync --status --json` (use `pnpm exec mdrules` if it is a local dependency). It returns:
+   `{ sourceLang, langs, foreign: [{ path, detected }], files: [{ path, lang, status, translation }] }`.
+2. **Files not in the source language** (`foreign`): ask the user, in one question listing them, whether to convert each one to `sourceLang`.
+   - Yes: rewrite the file in place in the source language, keeping structure, code, links and markers byte-identical.
+   - No: `mdrules sync --keep <path> [<path>...]` so they are not offered again.
+3. **Translations** (`files`, one entry per enabled language), by status:
+   - `missing` or `outdated`: translate the source `path` into `lang`, write it to `translation`.
+   - `pending-sync`: the user edited the translation. Apply their changes to the source `path` (translated into the source language, untouched parts byte-identical), then regenerate `translation` — and the other languages' translations of that file.
+   - `conflict`: both changed. Merge into the source file (source wins on contradictions), regenerate the translations, and tell the user what conflicted.
+   - `synced`: nothing to do.
+4. `mdrules sync --mark --lang <lang> <path> [<path>...]` for every translation you wrote (without `--lang` it marks every enabled language).
+
+Translation rules: keep frontmatter keys, code blocks, `tree` and `mermaid` identifiers, link targets, table structure and the `<!-- ... -->` markers unchanged; translate only human text (including frontmatter values like titles, but not `status`/`type` values).