mddd-cli 4.2.3 → 4.4.0

package/.agents/skills/md-audit/SKILL.md

@@ -17,7 +17,7 @@ stateDiagram-v2
     
     state RenderTopology {
         [*] --> CheckCode: Analyze current code structure and dependencies
-        CheckCode --> EvaluatedCodeIsClean: Map exact architecture as-is (v1.0.0 - stable)
+        CheckCode --> EvaluatedCodeIsClean: Map exact architecture as coese (v1.0.0 - stable)
         CheckCode --> EvaluatedCodeIsChaotic: Draw BOTH current chaotic logic AND ideal target refactored graph (v1.0.0 - draft)
     }
     

package/.agents/skills/mermaid-diagrams/README.md

@@ -64,13 +64,6 @@ diagramType
 - **Notes and comments** - Add context and explanations
 - **Alt/loop/opt blocks** - Complex flow control in sequences
 
-### Integration Support
-
-- **GitHub/GitLab** - Automatic rendering in Markdown files
-- **VS Code** - Preview with Markdown Mermaid extension
-- **Notion, Obsidian, Confluence** - Built-in support
-- **Export** - PNG, SVG, PDF via Mermaid Live or CLI
-
 ## Usage Examples
 
 ### Example 1: Document a Domain Model
@@ -233,7 +226,6 @@ For comprehensive syntax and advanced features, see:
 - **[Mermaid Live Editor](https://mermaid.live)** - Interactive editor with instant preview and export
 - **[Official Documentation](https://mermaid.js.org)** - Comprehensive syntax reference
 - **Mermaid CLI** - `npm install -g @mermaid-js/mermaid-cli` for batch exports
-- **VS Code Extension** - "Markdown Preview Mermaid Support" for live preview
 - **GitHub** - Native rendering in all `.md` files
 
 ## Support

package/.agents/skills/mermaid-diagrams/SKILL.md

@@ -184,7 +184,6 @@ flowchart LR
 
 **Native support in:**
 - GitHub/GitLab - Automatically renders in Markdown
-- VS Code - With Markdown Mermaid extension
 - Notion, Obsidian, Confluence - Built-in support
 
 **Export options:**

package/{src → .agents}/templates/spec-template.md

@@ -1,6 +1,6 @@
-# {{Feature Title}} — Specification
+**SPEC_VERSION:** v1.0.0 — draft|stable
 
-**SPEC_VERSION:** v1.0.0 — draft
+# {{Feature Title}} — Specification
 
 > ⚠️ **This is a freshly generated MDDD spec template.**
 > Replace every `{{placeholder}}`, remove this banner, and refine the diagram + matrix
@@ -12,11 +12,6 @@
 
 Describe **what** this spec governs and **why** it exists.
 
-- **Domain:** `{{domain_name}}`
-- **Feature / Module:** `{{feature_name}}`
-- **Scope (in):** {{what is covered}}
-- **Scope (out):** {{what is explicitly NOT covered}}
-- **Owners:** {{team_or_person}}
 - **Related specs:** {{parent_domain_spec, sibling_features}}
 
 ---

package/bin/cli.js

@@ -17,7 +17,7 @@ const program = new Command();
 program
   .name('md')
   .description('Manager for co-located specifications for Mermaid Diagram Driven Development (MDDD)')
-  .version('4.2.3');
+  .version('4.4.0');
 
 // ==========================================
 // COMMAND: md init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mddd-cli",
-  "version": "4.2.3",
+  "version": "4.4.0",
   "description": "Official CLI for modular, co-located, and versioned Mermaid Diagram Driven Development (MDDD).",
   "type": "module",
   "exports": "./bin/cli.js",
@@ -10,7 +10,8 @@
   "files": [
     "src",
     "system_prompt.md",
-    ".agents/skills"
+    ".agents/skills",
+    ".agents/templates"
   ],
   "engines": {
     "node": ">=18.0.0"

package/readme.md

@@ -67,8 +67,6 @@ Unlike traditional specification frameworks that generate dozens of text files a
 
 ## ✅ Mermaid Diagram Preview
 
-To preview Mermaid diagrams directly in your editor during the MDDD workflow, you can use extensions that render ````mermaid```` blocks in Markdown files:
-
 ### Architectural Diagram Example
 
 ```mermaid
@@ -130,26 +128,6 @@ sequenceDiagram
 
 ---
 
-### VS Code and derivated
-
-* **Markdown Preview Mermaid Support** — Adds Mermaid diagram support to the native Markdown preview.
-* **Mermaid Editor** — Visual editor with side-by-side preview and export.
-* **bierner.markdown-mermaid** — Official extension that extends the Markdown preview to render Mermaid.
-
-### JetBrains (IntelliJ, WebStorm, GoLand, etc.)
-
-* Native Mermaid support starting from **2024.1** — Just open the `.spec.md` file and use the built-in Markdown preview.
-
-### Other Editors
-
-* **Neovim/Vim:** Use plugins like `iamcco/markdown-preview.nvim` (with `markdown-preview` configured for Mermaid).
-* **Sublime Text:** `Mermaid` package from Package Control that adds preview and snippets.
-* **Markdown Editors:** Tools like [Typora](https://typora.io), [Obsidian](https://obsidian.md), and [Notion](https://notion.so) already have native Mermaid support — just paste the `.spec.md` file and the diagram will render automatically.
-
-> 💡 **Tip:** The better you can visualize the diagrams, the easier it is to validate business flows before implementation.
-
----
-
 ## 📥 Installation
 
 Since the package is published on NPM, installation is global and simple:
@@ -391,26 +369,6 @@ sequenceDiagram
 
 ---
 
-### VS Code e derivados
-
-* **Markdown Preview Mermaid Support** — Adiciona suporte a diagramas Mermaid no preview nativo do Markdown.
-* **Mermaid Editor** — Editor visual com preview lado a lado e exportação.
-* **bierner.markdown-mermaid** — Extensão oficial que estende o preview de Markdown para renderizar Mermaid.
-
-### JetBrains (IntelliJ, WebStorm, GoLand, etc.)
-
-* Suporte nativo a Mermaid a partir do **2024.1** — Basta abrir o arquivo `.spec.md` e usar o preview de Markdown integrado.
-
-### Outros Editores
-
-* **Neovim/Vim:** Utilize plugins como `iamcco/markdown-preview.nvim` (com `markdown-preview` configurado para Mermaid).
-* **Sublime Text:** Pacote `Mermaid` no Package Control que adiciona preview e snippets.
-* **Markdown Editors:** Ferramentas como [Typora](https://typora.io), [Obsidian](https://obsidian.md) e [Notion](https://notion.so) já possuem suporte nativo a Mermaid — basta colar o arquivo `.spec.md` e o diagrama será renderizado automaticamente.
-
-> 💡 **Dica:** Quanto melhor você conseguir visualizar os diagramas, mais fácil será validar os fluxos de negócio antes da implementação.
-
----
-
 ## 📥 Instalação
 
 Como o pacote está publicado no NPM, a instalação é global e simples:

package/src/commands/init.js

@@ -26,18 +26,25 @@ function readSystemPrompt() {
 export async function execute(initService) {
   const systemPrompt = readSystemPrompt();
 
-  // 1. Descobre o caminho absoluto real da pasta oculta interna do pacote da CLI
-  // Subindo de: src/commands/ -> src/ -> raiz do pacote CLI -> .agents/skills
+  // 1. Resolve o caminho absoluto da raiz do pacote CLI
   const currentFile = fileURLToPath(import.meta.url);
-  const cliSkillsSourceDir = path.resolve(path.dirname(currentFile), '..', '..', '.agents', 'skills');
+  const cliRootDir = path.resolve(path.dirname(currentFile), '..', '..');
+
+  // 2. Caminhos de origem dentro do pacote da CLI
+  const cliSkillsSourceDir = path.join(cliRootDir, '.agents', 'skills');
+  const cliSpecTemplatePath = path.join(cliRootDir, '.agents', 'templates', 'spec-template.md');
 
   await initService.createSystemPrompt(systemPrompt);
-  
-  // 2. Passa o caminho da pasta oculta de origem para o serviço clonar recursivamente
+
+  // 3. Passa o caminho da pasta oculta de origem para o serviço clonar recursivamente
   await initService.createSkills(cliSkillsSourceDir, (msg) => console.log(msg));
-  
+
+  // 4. Cria o workflow do GitHub
   await initService.createGitHubWorkflow(GITHUB_WORKFLOW_CONTENT, (msg) => console.log(msg));
 
-  console.log(pc.green('\n🚀 Universal [system_prompt.md] and SKILLS generated successfully in the project root!'));
+  // 5. Copia o spec template para o projeto
+  await initService.createSpecTemplate(cliSpecTemplatePath, (msg) => console.log(msg));
+
+  console.log(pc.green('\n🚀 Universal [system_prompt.md], SKILLS, and spec template generated successfully in the project root!'));
   console.log(pc.green('Run the "md init" command whenever you update the MDDD-CLI NPM package.'));
 }

package/src/services/InitService.js

@@ -74,4 +74,25 @@ export class InitService {
 
     return workflowFile;
   }
-}
+
+  /**
+   * Copies the spec template file from the CLI package to the project's .agents/templates/ directory.
+   * @param {string} sourceTemplatePath - Absolute path to the CLI source spec-template.md
+   * @param {(message: string) => void} logger
+   * @returns {Promise<void>}
+   */
+  async createSpecTemplate(sourceTemplatePath, logger) {
+    const templatesDir = path.join('.agents', 'templates');
+    const targetFile = path.join(templatesDir, 'spec-template.md');
+
+    if (!fs.existsSync(sourceTemplatePath)) {
+      throw new Error(`Source spec template not found at: ${sourceTemplatePath}`);
+    }
+
+    this.#fs.ensureDir(templatesDir);
+
+    const content = fs.readFileSync(sourceTemplatePath, 'utf-8');
+    await this.#fs.writeFile(targetFile, content);
+    logger(`✅ Spec template copied: ${targetFile}`);
+  }
+}

package/src/services/InitService.spec.md

@@ -1,6 +1,6 @@
 # InitService — Specification
 
-**SPEC_VERSION: v1.1.0 — stable**
+**SPEC_VERSION: v1.2.0 — stable**
 
 ## Overview
 
@@ -13,24 +13,27 @@ Co-located with `src/services/InitService.js`.
 ## Behavioral Flow (Mermaid)
 
 ```mermaid
-%% @spec-version v1.1.0
+%% @spec-version v1.2.0
 stateDiagram-v2
     [*] --> createSystemPrompt: initService.createSystemPrompt(promptContent)
     createSystemPrompt --> writeFile: this.#fs.writeFile('system_prompt.md', content)
-    writeFile --> createSkills: initService.createSkills(skills, logger)
+    writeFile --> createSkills: initService.createSkills(sourceSkillsDir, logger)
 
-    createSkills --> iterateSkills: for [skillName, content] of Object.entries(skills)
-    iterateSkills --> ensureSkillFolder: this.#fs.ensureDir(skillFolder)
-    ensureSkillFolder --> writeSkillFile: this.#fs.writeFile(skillFile, content)
-    writeSkillFile --> consoleLog: logger( `✅ Skill encapsulated ${skillFile}`)
-    consoleLog --> iterateSkills: next entry
-    iterateSkills --> returnCreated: return created[]
-    returnCreated --> createGitHubWorkflow: initService.createGitHubWorkflow(workflowYaml, logger)
+    createSkills --> ensureAgentsDir: this.#fs.ensureDir('.agents')
+    ensureAgentsDir --> ensureTargetSkillsDir: this.#fs.ensureDir('.agents/skills')
+    ensureTargetSkillsDir --> cpSyncSkills: fs.cpSync(source, target, recursive)
+    cpSyncSkills --> logSkills: logger per copied skill
+    logSkills --> createGitHubWorkflow: initService.createGitHubWorkflow(workflowYaml, logger)
 
     createGitHubWorkflow --> ensureWorkflowDir: this.#fs.ensureDir('.github/workflows')
     ensureWorkflowDir --> writeWorkflowFile: this.#fs.writeFile('.github/workflows/mddd-preview.yml', content)
-    writeWorkflowFile --> logWorkflow: logger(`✅ GitHub workflow created ${workflowPath}`)
-    logWorkflow --> [*]
+    writeWorkflowFile --> logWorkflow: logger(`✅ GitHub workflow created`)
+    logWorkflow --> createSpecTemplate: initService.createSpecTemplate(sourceTemplatePath, logger)
+
+    createSpecTemplate --> ensureTemplatesDir: this.#fs.ensureDir('.agents/templates')
+    ensureTemplatesDir --> writeTemplateFile: this.#fs.writeFile('.agents/templates/spec-template.md', content)
+    writeTemplateFile --> logTemplate: logger(`✅ Spec template copied`)
+    logTemplate --> [*]
 ```
 
 ---
@@ -40,13 +43,14 @@ stateDiagram-v2
 | Step | Method | I/O | Conditional Branch? | Error Handling | FS Side Effect |
 | :--- | :--- | :--- | :---: | :--- | :--- |
 | 1 | `createSystemPrompt(promptContent)` | Input: `string`<br>Output: `Promise<void>` | ❌ No | Delegated to `#fs.writeFile` | ✅ Writes `system_prompt.md` |
-| 2 | `createSkills(skills, logger)` | Input: `Record<string,string>` + logger fn<br>Output: `Promise<string[]>` | ❌ No (iteration only) | Delegated to `#fs` methods | ✅ Creates `.agents/`, `.agents/skills/`, `skillName/SKILL.md` per entry |
+| 2 | `createSkills(sourceSkillsDir, logger)` | Input: `string` (source dir) + logger fn<br>Output: `Promise<void>` | ✅ Checks `fs.existsSync(sourceSkillsDir)` | Throws `Error` if source dir not found | ✅ Creates `.agents/`, `.agents/skills/`, copies all skill folders recursively |
 | 3 | `createGitHubWorkflow(workflowYaml, logger)` | Input: `string` + logger fn<br>Output: `Promise<string>` | ❌ No | Delegated to `#fs` methods | ✅ Creates `.github/workflows/mddd-preview.yml` |
-| 4 | `this.#fs.ensureDir(agentsDir)` | Path: `'.agents'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
-| 5 | `this.#fs.ensureDir(skillsDir)` | Path: `'.agents/skills'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
-| 6 | `this.#fs.ensureDir(skillFolder)` | Path: per skill | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 4 | `createSpecTemplate(sourceTemplatePath, logger)` | Input: `string` (source path) + logger fn<br>Output: `Promise<void>` | ✅ Checks `fs.existsSync(sourceTemplatePath)` | Throws `Error` if source file not found | ✅ Creates `.agents/templates/`, writes `spec-template.md` |
+| 5 | `this.#fs.ensureDir(agentsDir)` | Path: `'.agents'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 6 | `this.#fs.ensureDir(skillsDir)` | Path: `'.agents/skills'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
 | 7 | `this.#fs.ensureDir(workflowsDir)` | Path: `'.github/workflows'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
-| 8 | `logger(…)` | stdout message | ❌ No | N/A | ❌ None |
+| 8 | `this.#fs.ensureDir(templatesDir)` | Path: `'.agents/templates'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 9 | `logger(…)` | stdout message | ❌ No | N/A | ❌ None |
 
 ---
 
@@ -75,5 +79,6 @@ stateDiagram-v2
 | :--- | :--- | :---: | :--- |
 | 2026-05-28 | Cline (md-audit) | v1.0.0 | **Spec created by md-audit.** Reverse-engineered from `src/services/InitService.js` (52 lines). Code classified as **Clean / Service with DI**. All orchestration steps documented with primitive factor analysis. No modifications to production code. |
 | 2026-05-28 | Cline (md-edit) | v1.1.0 | **New method `createGitHubWorkflow`.** Added to support `md init` creating `.github/workflows/mddd-preview.yml`. Updated behavioral flow diagram with new states. Updated Decision Matrix with steps 3, 7, 8. SPEC_VERSION bumped from v1.0.0 to v1.1.0 (minor — new method). Status promoted from **draft** to **stable** — implementation and tests verified. |
+| 2026-06-04 | Cline (md-edit) | v1.2.0 | **New method `createSpecTemplate`.** Added to support `md init` copying `.agents/templates/spec-template.md` from the CLI package to the project. Reads the template file content via `fs.readFileSync`, ensures `.agents/templates/` dir exists, then writes `spec-template.md` via `#fs.writeFile`. Updated behavioral flow diagram with new states (`createSpecTemplate → ensureTemplatesDir → writeTemplateFile → logTemplate`). Updated Decision Matrix with steps 4, 8. SPEC_VERSION bumped from v1.1.0 to v1.2.0 (minor — new method). |
 
 </details>

package/system_prompt.md

@@ -3,9 +3,11 @@
 You are a Mermaid Diagram processing system. Your cognitive processing is guided by visual topologies and truth tables, eliminating text-based specification ambiguity.
 Consume the mermaid-diagrams skill to learn how to produce it.
 
+Spec template path: .agents/templates/spec-template.md
+
+Mark the analysis as Coese or Chaotic
+
 ```mermaid
-%% @spec-version v2.0.0
-%% @protocol-version 1.0.0
 stateDiagram-v2
     [*] --> CheckSpec: UNIVERSAL RULE — Check specification file
 
@@ -17,14 +19,14 @@ stateDiagram-v2
     state SkillCheck {
         MdNew --> ReadSpecification: Request Allowed.
         MdAudit --> ReadSpecification: Request Allowed.
-        MdEdit --> ReadSpecification: Request Allowed.
         Other --> Denied: Specification file required.
     }
 
     Denied --> ConflictResolution: Explain missing spec
 
     state ReadSpecification {
-        [*] --> ParseMermaidDiagrams: Extract all %% @spec-version diagrams
+        [*] --> CreateSpec: Create file from template
+        CreateSpec --> ParseMermaidDiagrams: Extract all diagrams
         ParseMermaidDiagrams --> ExtractDecisionMatrices: Map topology nodes/edges
         ExtractDecisionMatrices --> ValidatePrimitiveFactors: Check factor columns
         ValidatePrimitiveFactors --> [*]: Spec loaded into context
@@ -50,71 +52,13 @@ stateDiagram-v2
     UpdateDetailsFooter --> [*]
 ```
 
-## 0. Spec File Format (.spec.md)
-
-Every `.spec.md` file MUST follow this structure:
-
-```
-%% @spec-version 1.0.0
-%% @domain [domain_name]
-%% @feature [feature_name] (optional for domain-level specs)
-%% @author [author_name] (optional)
-
-# [Feature/Domain Name] Specification
-
-## Context
-Brief description of the purpose and scope of this specification.
-
-## Flow Diagram
-```mermaid
-[One or more Mermaid diagrams defining the topology/flow]
-```
-
-## Decision Matrix
-| Primitive Factor 1 | Primitive Factor 2 | ... | Proposed Action | Decision |
-| --- | --- | --- | --- | --- |
-| ✅ YES / ❌ NO | ✅ YES / ❌ NO | ... | `ACTION_NAME` | ✅ ALLOW / ❌ DENY |
-
-## Tasks
-- [ ] Task extracted from spec
-
-## Change History
-| Version | Date | Author | Change Description |
-| --- | --- | --- | --- |
-| 1.0.0 | YYYY-MM-DD | ... | Initial spec creation |
-```
-
-## 1. Co-location Architecture Tree
-
-src/
-└── [domain_name]/
-    ├── [domain_name].spec.md                   # 🌎 Macro Module Domain
-    ├── [feature_name]/
-    │   ├── [feature_name].spec.md              # 🔬 Micro Flow Contract + Decision Matrix
-    │   └── [feature_name].[extension]          # 💻 Target Production Code File (Any Extension)
-    └── ...                                     # Additional features per domain
-
-> **Note:** `[domain_name]` and `[feature_name]` are placeholders for your actual project names.
-> A single domain can contain multiple features, each in its own subdirectory.
-
-## 2. Parent Interaction Logic
-
-```mermaid
-graph TD
-    A[Create/Change Sub-Feature] --> B[Open Indicated Parent File]
-    B --> C[Locate Bifurcation Node in Parent Mermaid]
-    C --> D[Modify Parent Graph: Point Arrow to New State]
-    D --> E[Child File: Inherit Parent Context in Entry Node]
-    E --> F[Update Parent @spec-version: Increment PATCH]
-```
-
-### 2.1 Reverse Consistency (Parent → Child)
+### 2 Reverse Consistency (Parent → Child)
 
 When a parent domain spec is modified, the following MUST be verified:
 
-1. **Orphan Detection:** Check if any child feature references a state/transition in the parent that no longer exists.
-2. **Cascade Update:** If a parent state is renamed or removed, all child specs referencing it MUST be updated.
-3. **Version Bump:** Parent changes increment MINOR version. Child specs affected by the change increment PATCH version.
+2.1. **Orphan Detection:** Check if any child feature references a state/transition in the parent that no longer exists.
+2.2. **Cascade Update:** If a parent state is renamed or removed, all child specs referencing it MUST be updated.
+2.3. **Version Bump:** Parent changes increment MINOR version. Child specs affected by the change increment PATCH version.
 
 ## 3. Decision Matrix & Primitive Factors
 
@@ -162,23 +106,11 @@ Every `.spec.md` file carries a `%% @spec-version` header. Use **Semantic Versio
 | **MINOR** | Adding: new states/transitions, new factor columns, new features without breaking existing rows. | `1.2.3` → `1.3.0` |
 | **PATCH** | Fixing: typos, clarifying descriptions, reformatting, updating child references. | `1.2.3` → `1.2.4` |
 
-### 4.2 Version Header Format
-
-The `%% @spec-version` comment MUST be the **first line** of the `.spec.md` file:
-
-```markdown
-%% @spec-version 1.0.0
-%% @domain payment
-%% @feature refund-flow
-```
-
-### 4.3 Audit History (Change Log)
+### 4.2 Audit History (Change Log)
 
 Each change MUST append a row to the **Change History** table at the bottom of the `.spec.md` file:
 
 ```
-%% @spec-version 1.1.0
-
 ## Change History
 | Version | Date | Author | Change Description | Change Type |
 | --- | --- | --- | --- | --- |