mdrules 0.1.0 → 0.2.0

package/templates/method/skills/mdrules-close-session/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: mdrules-close-session
+description: Closes a work session in a project that follows the mdrules method, recording what was done and the next step of every task touched, and updating task indexes and phases.
+---
+
+# Close the session (mdrules method)
+
+1. Identify the tasks worked on in this session.
+2. For each one, in its file:
+   - Add a log entry at the top of "Log": date, what was done, key files and decisions.
+   - Rewrite "Next step" in one or two actionable lines (for `blocked`: what it waits on).
+   - Tick the acceptance criteria that are met; set `status` and `updated` in the frontmatter.
+3. If a status changed, move the task's line to the right section of its `TASKS.md` (and of every
+   area index that links it).
+4. If a task is `done`, tick it in its phase (`docs/phases/NN-*.md`). When every task and every item
+   of "Definition of done" is ticked, set the phase to `status: done`; when the first task starts,
+   set it to `in-progress`. Update `updated`.
+5. If an architecture decision was made or changed, update it in its one place (the area's
+   `docs/ARCHITECTURE.md` or the root `docs/architecture/`), never in the main doc.
+6. Summarize for the user in three lines: what was done, the next step, and anything open.

package/templates/method/skills/mdrules-new-task/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: mdrules-new-task
+description: Creates a task file in this project's docs (the mdrules method) when the user asks for a new task. Uses the task template, the next ID of the area, and updates the task index and the phase.
+---
+
+# New task (mdrules method)
+
+Create tasks only when the user asks; you may propose them first.
+
+1. Gather what is missing, in one question: title, goal, area (in a monorepo; the map in the main doc
+   lists areas and their prefixes), phase, and dependencies.
+2. Folder and prefix: the area's `docs/tasks/` with its prefix; cross-area or single-project tasks go
+   in the root `docs/tasks/` (prefix in the root `docs/TASKS.md` title, `T` by default).
+3. Next ID: the highest `<PREFIX>-NNN` in that folder + 1, three digits.
+4. Copy the root `docs/tasks/_TEMPLATE.md` to `<folder>/<ID>-<short-slug>.md`. Fill the frontmatter
+   (`id`, `status: pending`, `area`, `phase`, `depends`, `created` and `updated` = today), the title,
+   the goal and the acceptance criteria as a checklist.
+5. Add `- [<ID>](tasks/<file>.md) <title>` under "Pending" in that folder's `TASKS.md`. For a
+   cross-area task, also link it from each affected area's `TASKS.md`; never copy it.
+6. If it belongs to a phase, add `- [ ] [<ID>](<relative path>) <title>` under "Tasks" in
+   `docs/phases/NN-*.md`.
+7. Show the task to the user. Do not start working on it until they say so.

package/templates/proposals/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: mdrules-proposals
+description: Write temporary proposals the user answers in mdrules (options with ASCII or Mermaid diagrams, choices to tick, comments like in Word), then apply their answer to every affected doc and delete the proposal. Use when an answer would be long or has options or a design to validate, when the user asks for a proposal, or when they say a proposal is answered.
+---
+
+# Proposals (mdrules)
+
+A proposal is a **temporary** file for one decision. Write one instead of a chat answer when:
+
+- the answer would be long, or has several options, diagrams or a design to validate; or
+- the user asks for a proposal.
+
+For a short answer or a single obvious option, just answer in the chat.
+
+Write the file, tell the user its path in one line, and wait. They open it in mdrules, tick options and
+add comments, then tell you it is answered. Once applied, the decision lives in the docs it affects and
+the proposal is deleted.
+
+## Where
+
+{{where}}.
+
+## Format
+
+````md
+---
+type: proposal
+status: open          # open → answered (set by the user in mdrules); deleted once applied
+updated: YYYY-MM-DD
+affects: [docs/tasks/T-004-login.md, docs/architecture/auth.md]   # docs the decision will change
+---
+
+# Proposal: <topic>
+
+## Context
+
+<!-- Two or three lines: what needs deciding and why now. -->
+
+## Option A: <name> (recommended)
+
+```text
+ Browser ──REST──▶ Gateway ──gRPC──▶ Users ──▶ (Postgres)
+```
+
+What it means, pros and cons in a few bullets.
+
+## Option B: <name>
+
+```mermaid
+flowchart LR
+  Browser --> Users --> DB[(Postgres)]
+```
+
+## Your choice
+
+<!-- choose: one -->
+- [ ] A: <name>
+- [ ] B: <name>
+
+## Also include
+
+- [ ] <optional extra the user can tick>
+
+## Open questions
+
+1. <question>
+
+   <!-- choose: one -->
+   - [ ] <answer>
+   - [ ] <answer>
+````
+
+- Diagrams: a ` ```text ` block with box-drawing characters for small sketches, ` ```mermaid ` for
+  flows and sequences. mdrules renders both.
+- In ASCII diagrams use only single-width characters (box drawing `┌─┐│└┘▶`, letters, `#`, `-`); shading
+  blocks like `▓░` are wider in many fonts and break the alignment.
+- `<!-- choose: one -->` right before a checklist makes it single choice in mdrules (radio buttons);
+  without it, any number can be ticked.
+- Put your recommendation first and say why.
+
+## Comments
+
+The user comments like in Word. A comment is an HTML comment right after the block it refers to,
+indented like that block (inside a list item: aligned with the item's text):
+
+```md
+- [x] A: gateway validates
+  <!-- comment by Rafael, 2026-10-22, on "gateway validates": What if the gateway goes down? -->
+```
+
+Answer each comment with a reply right below it (or below the last reply), same indentation:
+
+```md
+  <!-- reply by AI, 2026-10-22: Two Cloud Run instances minimum; added to the architecture. -->
+```
+
+Never delete or rewrite the user's comments: they resolve them in mdrules. Never put `-->` inside a
+comment's text.
+
+- `affects`: the docs that depend on this decision (tasks, phases, architecture, vision, other
+  proposals…), so the user sees what their choice will change.
+
+## When the user answers
+
+1. Read the ticked options, the open questions and every comment without a reply from you.
+2. If something is unclear or a comment raises a new question, reply to that comment, keep
+   `status: open`, and tell the user what you need. Don't apply anything yet.
+3. Otherwise apply the decision to every doc that depends on it: the ones in `affects` and any other
+   you find (a task's goal or acceptance criteria, a phase's task list, an architecture table, the
+   vision…). Record it in its one place: in the mdrules method, the architecture file for design
+   decisions, and a line in the log of the task it belongs to (`<date>: decided <what> (proposal
+   <name>)`).
+4. Delete the proposal file: it was temporary, the decision now lives in those docs.
+5. Tell the user in a few lines what you changed and where.

package/templates/sdd/openspec/openspec/README.md

@@ -0,0 +1,89 @@
+# OpenSpec guide
+
+This project uses [OpenSpec](https://github.com/Fission-AI/OpenSpec): agree on **what** to build in
+Markdown before writing code, so you and the AI work from the same spec.
+
+## Structure
+
+```tree
+openspec/
+  config.yaml          # project context and rules for the AI (edit in your code editor)
+  specs/               # how the system behaves TODAY, one folder per domain
+    auth/
+      spec.md
+  changes/             # proposed work, one folder per change
+    add-2fa/
+      proposal.md      # why and what
+      design.md        # how (optional, for non-trivial changes)
+      tasks.md         # checklist the AI works through
+      specs/auth/spec.md   # delta: requirements added, modified or removed
+    archive/           # finished changes, dated
+```
+
+## Lifecycle
+
+```mermaid
+flowchart LR
+  Propose[Propose a change] --> Review[Review proposal, specs and tasks]
+  Review --> Apply[Apply: implement the tasks]
+  Apply --> Archive[Archive: deltas merge into specs/]
+```
+
+| Step | Command (if OpenSpec is installed) | Or ask the AI |
+|---|---|---|
+| Explore an idea | `/opsx:explore` | "Let's think through X before proposing anything." |
+| Propose | `/opsx:propose add 2FA` | "Create an OpenSpec change `add-2fa` with proposal, tasks and spec deltas." |
+| Implement | `/opsx:apply` | "Implement the tasks of `add-2fa`, ticking each one." |
+| Finish | `/opsx:archive` | "Archive `add-2fa` and merge its deltas into `openspec/specs/`." |
+
+## Examples
+
+**`changes/add-2fa/proposal.md`**
+
+```md
+# Proposal: Add two-factor authentication
+
+## Why
+Accounts are protected by a password only.
+
+## What changes
+- Users can enable TOTP codes from their settings.
+- Login asks for the code when 2FA is enabled.
+
+## Out of scope
+- SMS codes.
+```
+
+**`changes/add-2fa/specs/auth/spec.md`** (delta)
+
+```md
+## ADDED Requirements
+
+### Requirement: Two-factor login
+The system SHALL ask for a one-time code after the password when 2FA is enabled.
+
+#### Scenario: Valid code
+- **WHEN** the user enters a valid code
+- **THEN** they are logged in
+```
+
+**`changes/add-2fa/tasks.md`**
+
+```md
+## 1. Backend
+- [ ] 1.1 Store the TOTP secret per user
+- [ ] 1.2 Verify codes on login
+
+## 2. Frontend
+- [ ] 2.1 Settings screen to enable 2FA
+```
+
+## Installing OpenSpec
+
+The `/opsx:*` commands come from the OpenSpec CLI. If they are missing, install it (needs Node.js) and
+run its setup here; it keeps the files you already have:
+
+```bash
+npm install -g @fission-ai/openspec
+openspec init
+```

package/templates/sdd/openspec/openspec/config.yaml

@@ -0,0 +1,12 @@
+schema: spec-driven
+
+# Project context (optional): constraints an agent can't infer from the code.
+# context: |
+#   Designs and tasks must cover Windows, macOS and Linux
+
+# Per-artifact rules (optional).
+# rules:
+#   proposal:
+#     - Always state what is out of scope
+#   tasks:
+#     - Break tasks into chunks of at most 2 hours

package/templates/sdd/speckit/.specify/memory/constitution.md

@@ -0,0 +1,30 @@
+# [PROJECT_NAME] Constitution
+
+<!-- The principles every feature must respect. Fill it in, or run /speckit-constitution and let the AI
+     draft it from a conversation. Replace every [PLACEHOLDER]. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Test-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Tests are written and approved before the implementation. -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. Simplicity -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Start with the simplest thing that works; no speculative abstractions. -->
+
+### [PRINCIPLE_3_NAME]
+[PRINCIPLE_3_DESCRIPTION]
+
+## Constraints
+
+[CONSTRAINTS]
+<!-- Example: TypeScript only; Postgres; must run on Node 20+. -->
+
+## Governance
+
+This constitution overrides other practices. Amendments are documented here with their reason.
+
+**Version**: 1.0.0 | **Ratified**: {{date}} | **Last amended**: {{date}}

package/templates/sdd/speckit/specs/README.md

@@ -0,0 +1,82 @@
+# Spec Kit guide
+
+This project uses [GitHub Spec Kit](https://github.com/github/spec-kit): every feature goes from an
+idea to a spec, a plan and a task list before any code is written.
+
+## Structure
+
+```tree
+.specify/
+  memory/constitution.md   # principles every feature must respect
+  templates/               # templates the commands fill (installed by Spec Kit)
+specs/
+  001-user-login/          # one folder per feature, numbered
+    spec.md                # what and why: user stories, requirements
+    plan.md                # how: stack, architecture, data model
+    tasks.md               # ordered checklist, by user story
+    research.md            # optional: findings behind the plan
+    data-model.md          # optional
+    contracts/             # optional: API definitions
+```
+
+## Flow
+
+```mermaid
+flowchart LR
+  C[Constitution] --> S[Specify] --> Q[Clarify] --> P[Plan] --> T[Tasks] --> I[Implement]
+```
+
+| Step | Command (if Spec Kit is installed) | Or ask the AI |
+|---|---|---|
+| Principles | `/speckit-constitution` | "Fill `.specify/memory/constitution.md` with our principles." |
+| Spec | `/speckit-specify users can log in with email` | "Write `specs/001-user-login/spec.md`: user stories, requirements, success criteria. No tech choices." |
+| Clarify (optional) | `/speckit-clarify` | "Ask me about anything ambiguous in the spec." |
+| Plan | `/speckit-plan use Next.js and Postgres` | "Write `plan.md` for 001 with the stack and data model." |
+| Tasks | `/speckit-tasks` | "Break the plan into `tasks.md`, grouped by user story." |
+| Build | `/speckit-implement` | "Implement the tasks of 001 in order, ticking each one." |
+
+## Examples
+
+**`specs/001-user-login/spec.md`**
+
+```md
+# Feature Specification: User login
+
+## User Scenarios
+
+### User Story 1 - Log in with email (Priority: P1)
+A registered user logs in with email and password to reach their dashboard.
+
+**Acceptance Scenarios**:
+1. **Given** a registered user, **When** they enter valid credentials, **Then** they see their dashboard.
+2. **Given** a wrong password, **When** they submit, **Then** they see an error and stay logged out.
+
+## Requirements
+- **FR-001**: The system MUST lock an account after 5 failed attempts.
+
+## Success Criteria
+- **SC-001**: 95% of logins complete in under 2 seconds.
+```
+
+**`specs/001-user-login/tasks.md`**
+
+```md
+## Phase 1: User Story 1 - Log in with email (P1)
+- [ ] T001 [US1] Create the users table in src/db/schema.ts
+- [ ] T002 [P] [US1] Login form in src/app/login/page.tsx
+- [ ] T003 [US1] POST /api/login in src/app/api/login/route.ts
+```
+
+`[P]` marks tasks that can run in parallel.
+
+## Installing Spec Kit
+
+The `/speckit-*` commands come from the Spec Kit CLI, which needs [uv](https://docs.astral.sh/uv/)
+(Python). If they are missing:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh     # install uv
+uvx --from git+https://github.com/github/spec-kit.git specify init --here --integration claude
+```
+
+It keeps the files you already have, including the constitution.

package/templates/skill/SKILL.md

@@ -14,21 +14,20 @@ The user reads and edits this project's Markdown in **mdrules**, a visual editor
 
 ## Frontmatter
 
-Put this at the top of docs that track work:
-
-
+Docs that track work start with a frontmatter block; the mdrules dashboard reads it:
 
 ```yaml
 ---
-type: phase        # phase | tasks | rules | architecture | decision | note
-status: pending    # pending | in-progress | done | blocked
-phase: 2           # only for type: phase (ordering)
+type: task         # vision | architecture | phase | tasks | task | note
+status: pending    # pending | in-progress | blocked | done
+phase: 2           # phases: their order; tasks: the phase they belong to
 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.
+- If the main doc has a "Workflow (mdrules method)" section, follow it: it says where vision,
+  architecture, phases and tasks live, and how to start and close a session.
 
 ## Content conventions
 
@@ -39,8 +38,6 @@ updated: YYYY-MM-DD
 | 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`)
@@ -48,7 +45,9 @@ Never edit the section between `<!-- mdrules:rules:start -->` and `<!-- mdrules:
 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 }] }`.
+   `{ sourceLang, langs, names, foreign: [{ path, detected }], files: [{ path, lang, status, translation }] }`.
+   `names` maps each language code to its name (`ja` → `Japanese`): translate into that language, also for
+   codes the user added by hand.
 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.

package/dist/web/assets/channel-BWmWik05.js

@@ -1 +0,0 @@
-import{ot as e,st as t}from"./chunk-DSNLSHJZ-C_3sVqJn.js";var n=(n,r)=>t.lang.round(e.parse(n)[r]);export{n as t};

package/dist/web/assets/flowDiagram-IUGLLWBU-Dq34jEaq.js

@@ -1 +0,0 @@
-import"./src-BJB85M8z.js";import"./chunk-DSNLSHJZ-C_3sVqJn.js";import"./chunk-7S6XSTFO-DoKaEIP0.js";import"./chunk-YZO67HFG--IdJYNXK.js";import"./chunk-AQDTSKZB-DktDdZ_o.js";import"./chunk-UHW7PFBP-BkreF8rs.js";import"./chunk-HAGFOTED-DhCQIE99.js";import"./chunk-ZAUX2LTX-DmenwPIM.js";import"./chunk-WQQL4CDK-GsIKInJ-.js";import"./chunk-55XCU76K-DgZ0btzr.js";import"./chunk-XXDRQBXY-Bbz14gys.js";import"./chunk-VQ5W62QI-Cb7PeOKH.js";import"./chunk-HNE4Q36P-D_sbl6UM.js";export{n as diagram}from"./chunk-NQOKRVIF-UuKYBp6F.js";import"./mermaid.core-DpHqjC1s.js";