mddd-cli 7.0.0 → 7.1.1

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

@@ -1,38 +1,40 @@
-[ROLE: SECURITY & QUALITY AUDITOR] [STRICT CONTRACT]
-
 ```mermaid
-%% @spec-version v1.3.2
-stateDiagram-v2
-    [*] --> Evaluation: Quality Assessment.
-    Evaluation --> MakeSpec: Co-located .spec.md.
-
-    state MakeSpec {
-        [*] --> SpecExists: Check for existing .spec.md.
-        SpecNotFound --> CreateSpec: Create .spec.md from "src/templates/spec-template.md".
-        SpecExists --> Break: Audit only.
-        Break --> [*]
-    }
-    
-    CreateSpec --> RenderTopology: Create new co-located .spec.md.
-    
-    state RenderTopology {
-        [*] --> CheckCode: Analyze current code structure and dependencies
-        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)
-    }
-    
-    RenderTopology --> CheckDiagram: Use "npx md validate <path/to/spec.md>" to validate diagram syntax
-
-    state CheckDiagram {
-        [*] --> DiagramValid: Proceed to next step
-        DiagramInvalid --> RenderTopology: Re-render until valid
-    }
-
-    CheckDiagram --> DiscoveryAnalysis: Identify potential vulnerabilities and code quality issues
-    DiscoveryAnalysis --> WriteToAuditTag: Document findings and recommendations in the .spec.md file
-    WriteToAuditTag: Inject payloads inside <details> block
-    WriteToAuditTag --> EnforceImmutability: Lock Production Code File
-    EnforceImmutability --> [*]
+%% @spec-version v1.3.3
+graph TD
+    Start((Start)) --> Evaluation{Quality Assessment}
+
+    Evaluation -->|Co-located .spec.md| MakeSpec
+
+    subgraph MakeSpec[Check Existing Spec]
+        direction TB
+        M1{Spec exists?}
+        M1 -->|No| M2[Create .spec.md from .agents/templates/spec-template.md]
+        M1 -->|Yes| M3[Audit only]
+        M3 --> Break([Break])
+    end
+
+    M2 --> RenderTopology
+
+    subgraph RenderTopology[Analyze Code]
+        direction TB
+        R1[Analyze code structure and dependencies]
+        R1 --> R2{Chaotic or Coese?}
+        R2 -->|Coese| R3[Map exact architecture — stable]
+        R2 -->|Chaotic| R4[Draw current + ideal refactored graph — draft]
+    end
+
+    RenderTopology --> CheckDiagram
+
+    subgraph CheckDiagram[Validate Syntax]
+        direction TB
+        C1{Diagram valid?}
+        C1 -->|Yes| C2[Proceed]
+        C1 -->|No| RenderTopology
+    end
+
+    CheckDiagram --> D[Identify vulnerabilities and code quality issues]
+    D --> W[Document findings in .spec.md <details> block]
+    W --> End((End))
 ```
 
 ```mermaid

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

@@ -1,56 +1,44 @@
 [ROLE: ARCHITECT] [STRICT CONTRACT]
 
 ```mermaid
-%% @spec-version v1.3.1
-stateDiagram-v2
-    [*] --> Read TargetSpec: Read Target .spec.md
-    Read TargetSpec --> ParseVersion: Parse Current SPEC_VERSION
-    ParseVersion --> ApplyAdjustments: Apply requested Mermaid/Matrix Adjustments
-    ApplyAdjustments --> EvaluateScope: Evaluate Mutation Scope
-
-    state EvaluateScope {
-        [*] --> TypoFix: Typo / Label Fix
-        [*] --> NewNode: New Node / Flow Path / Factor
-        [*] --> BreakingChange: Breaking Overhaul / Restructure
-    }
-    
-    EvaluateScope --> IncrementVersion: Increment Version Based on Scope
-
-    state IncrementVersion {
-        [*] --> IncrementPatch: Increment Patch: Bump Z in X.Y.Z
-        [*] --> IncrementMinor: Increment Minor: Bump Y in X.Y.Z
-        [*] --> IncrementMajor: Increment Major: Bump X in X.Y.Z
-    }
-
-    IncrementVersion --> CheckDiagram: Use "npx md validate <path/to/spec.md>" to validate diagram syntax
-
-    state CheckDiagram {
-        [*] --> TryRender
-        TryRender --> DiagramValid: Render succeeded
-        TryRender --> IncrementRetry: Render failed
-        IncrementRetry --> TryRender: Retry count < 5
-        IncrementRetry --> RenderFailed: Retry count >= 5
-    }
-        
-    CheckDiagram --> WriteToFile: Write validated .spec.md to target path
-    WriteToFile --> VerifyWrite
-    state VerifyWrite {
-        [*] --> WriteSuccess: File written successfully
-        [*] --> WriteError: File write failed (permissions / disk / path)
-    }
-    WriteError --> AwaitHumanReview: Error: manual intervention required
-
-    WriteSuccess --> DiscoveryAnalysis: Identify potential vulnerabilities and code quality issues
-    DiscoveryAnalysis --> AwaitHumanReview: Flag discovered issues for human review
-    RenderFailed --> AwaitHumanReview: Error: Mermaid CLI validation failed after 5 attempts
-
-    state AwaitHumanReview {
-        [*] --> Approved: Resume CI/CD pipeline
-        [*] --> ChangesRequested: Loop back to ApplyAdjustments
-        [*] --> Aborted: Terminate session
-    }
-    
-    AwaitHumanReview --> [*]: Pause Code & Test Generation
+%% @spec-version v1.3.2
+graph TD
+    Start((Start)) --> Read[Read target .spec.md]
+    Read --> Parse[Parse SPEC_VERSION]
+    Parse --> Apply[Apply requested diagram/matrix adjustments]
+    Apply --> Scope{Evaluate mutation scope}
+
+    Scope -->|Typo / label fix| PatchBump[Increment PATCH]
+    Scope -->|New node / flow / factor| MinorBump[Increment MINOR]
+    Scope -->|Breaking restructure| MajorBump[Increment MAJOR]
+
+    PatchBump --> Validate
+    MinorBump --> Validate
+    MajorBump --> Validate
+
+    subgraph Validate[Validate & Write]
+        direction TB
+        V1[Try render with npx md validate] --> V2{Render result?}
+        V2 -->|Success| V3[Write to target path]
+        V2 -->|Failed, retries < 5| V1
+        V2 -->|Failed, retries >= 5| V4[[RENDER_FAILED]]
+        V3 --> V5{Write result?}
+        V5 -->|Success| V6[Proceed]
+        V5 -->|Error| V7[[WRITE_ERROR]]
+    end
+
+    V6 --> Audit[Identify vulnerabilities and issues]
+    Audit --> Review
+    V4 --> Review
+    V7 --> Review
+
+    subgraph Review[Await Human Review]
+        direction TB
+        R1{Await decision}
+        R1 -->|Approved| R2([End])
+        R1 -->|Changes requested| Apply
+        R1 -->|Aborted| R3([End])
+    end
 ```
 
 ```mermaid

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

@@ -1,54 +1,64 @@
 [ROLE: SOFTWARE ENGINEER] [STRICT CONTRACT]
 
 ```mermaid
-%% @spec-version v1.3.1
-stateDiagram-v2
-    state ImplWorkflow {
-        [*] --> IngestSpec: [Inherits Parent Context] Ingest Signed .spec.md
-        IngestSpec --> ParseVersion: Parse Matrix Rows & Version Header
-        ParseVersion --> VerifyRequest: Verify Code/Chat Request Against Decision Matrix
-        VerifyRequest -->|Matches 100%| CheckTarget: Check File Target State
-        VerifyRequest -->|Human Asks to Skip/Add Extraneous Scope| TriggerDefense: Trigger Prompt Injection Defense
-
-        CheckTarget -->|New File| GenerateCode: Generate Full Structural Code from Scratch
-        CheckTarget -->|Existing File| IdempotentOverwrite: Idempotent Overwrite - Read & Output Full File
-        
-        GenerateCode --> GenerateTests: Generate Truth-Table Unit Tests
-        IdempotentOverwrite --> DataLossCheck: Check for Data Loss Risk
-        DataLossCheck -->|No Risk| GenerateTests
-        DataLossCheck -->|Risk Detected| AlertUser: Alert User & Pause Generation
-
-        GenerateTests --> RunTests: Run Generated Tests
-        RunTests -->|All Pass| PromoteSpec: Promote .spec.md from draft to stable
-        RunTests -->|Any Fail| FixCode: Fix Code/Tests & Retry
-
-        PromoteSpec --> UpdateVersion: Update SPEC_VERSION to vSameVersion - stable
-        UpdateVersion --> AppendHistory: Append Audit History: impl complete
-        AppendHistory --> PersistSpec: Persist Updated .spec.md to Disk
-        PersistSpec --> AwaitHumanReview: Pause for User Approval Before Lock
-    }
-
-    state AwaitHumanReview {
-        [*] --> LockApproved: User approves immutability lock
-        [*] --> ChangesRequested: User requests changes → loop back to GenerateCode/IdempotentOverwrite
-        [*] --> Aborted: Terminate session without lock
-    }
-
-    LockApproved --> LockCodeImmutability: Lock Code Immutability for Stable Version
-
-    state LockCodeImmutability {
-        [*] --> SetGitHook: Install pre-commit hook blocking edits to stable files
-        SetGitHook --> SetSpecFlag: Set .spec.md immutable flag (SPEC_IMMUTABLE: true)
-        SetGitHook --> SetFilePermissions: chmod 444 on production code files
-        SetFilePermissions --> VerifyLock: Verify git diff shows no modifications
-        VerifyLock --> LockComplete: Lock verified & confirmed
-        LockComplete --> [*]
-    }
-
-    LockCodeImmutability --> [*]
-
-    TriggerDefense --> RefuseCoding: Refuse Coding & Demand Spec Refinement via md-edit
-    RefuseCoding --> [*]
+%% @spec-version v1.3.2
+graph TD
+    Start((Start)) --> Ingest[Ingest signed .spec.md]
+    Ingest --> Parse[Parse matrix rows & version header]
+    Parse --> Verify{Verify request against decision matrix}
+
+    Verify -->|100% match| CheckTarget{Check target state}
+    Verify -->|Skip / extraneous scope| Defense[[PROMPT INJECTION DEFENSE]]
+    Defense --> Refuse[Refuse — demand spec refinement via md-edit]
+    Refuse --> End((End))
+
+    CheckTarget -->|New file| GenCode[Generate code from scratch]
+    CheckTarget -->|Existing file| Overwrite[Idempotent overwrite]
+
+    Overwrite --> DataLossCheck{Data loss risk?}
+
+    subgraph DataLossCheck[Evaluate Data Loss Risk]
+        direction TB
+        D1[File exists + will be overwritten?]
+        D2[Changes outside spec scope?]
+        D3[Uncommitted changes?]
+        D1 --> D4{Any risk factor true?}
+        D2 --> D4
+        D3 --> D4
+        D4 -->|Yes| Alert[[ALERT — pause generation]]
+        D4 -->|No| Proceed
+    end
+
+    GenCode --> Proceed
+    Proceed --> GenTests[Generate truth-table unit tests]
+    GenTests --> Run{All tests pass?}
+    Run -->|Yes| Promote[Promote .spec.md: draft → stable]
+    Run -->|No| Fix[Fix code/tests & retry]
+    Fix --> Proceed
+
+    Promote --> Update[Update SPEC_VERSION to stable]
+    Update --> History[Append audit history]
+    History --> Persist[Persist .spec.md to disk]
+    Persist --> Review
+
+    subgraph Review[Await Human Approval]
+        direction TB
+        R1{Await decision}
+        R1 -->|Lock approved| Lock
+        R1 -->|Changes requested| GenCode
+        R1 -->|Aborted| End
+    end
+
+    subgraph Lock[Lock Code Immutability]
+        direction TB
+        L1[Install pre-commit hook]
+        L2[Set SPEC_IMMUTABLE: true]
+        L3[chmod 444 on production files]
+        L4[Verify git diff = clean]
+        L1 --> L2 --> L3 --> L4 --> L5([Lock confirmed])
+    end
+
+    Lock --> End((End))
 ```
 
 ```mermaid

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

@@ -1,44 +1,33 @@
 [ROLE: ARCHITECT] [STRICT CONTRACT]
 
 ```mermaid
-%% @spec-version v1.3.1
-stateDiagram-v2
-    [*] --> TargetVerification
-
-    state TargetVerification {
-        [*] --> CheckFileExistence: Does .spec.md already exist at target path?
-        FileExists --> Break: Existing .specs are immutable. Switch to edit mode.
-        FileNotFound --> EvaluateContext: File Does Not Exist
-    }
-
-    state EvaluateContext {
-        [*] --> DeepAnalysis: Evaluate target context and goal
-        DeepAnalysis --> DiagramTypeInference: Infer appropriate diagram type and template
-        DiagramTypeInference --> InferNodes: Identify key nodes and relationships to be represented
-    }
-
-    EvaluateContext --> GenerateBlueprint: Create .spec.md from "src/templates/spec-template.md".
-    GenerateBlueprint --> FormatSpecOutput: Format blueprint into target .spec.md structure
-    FormatSpecOutput --> CheckDiagram: Use "npx md validate <path/to/spec.md>" to validate diagram syntax
-
-    state CheckDiagram {
-        [*] --> DiagramValid: Proceed to next step
-        DiagramInvalid --> GenerateBlueprint: Re-generate blueprint with adjustments until valid
-    }
-        
-    CheckDiagram --> WriteToFile: Write validated .spec.md to target path
-    WriteToFile --> InitializeVersion: Set initial SPEC_VERSION
-
-    state InitializeVersion {
-        [*] --> SetDraftVersion: Set SPEC_VERSION to v1.0.0-draft
-    }
-
-    InitializeVersion --> AppendCreationAudit: Record creation metadata
-
-    state AppendCreationAudit {
-        [*] --> LogCreation: Append audit entry: "Created via md-new" with timestamp
-    }
-
-    AppendCreationAudit --> AwaitHumanReview: Pause for user to review and adjust generated diagram
-    AwaitHumanReview --> [*]
+%% @spec-version v1.3.2
+graph TD
+    Start((Start)) --> CheckTarget{Target .spec.md exists?}
+
+    CheckTarget -->|Yes| Break([Break — existing specs are immutable. Use md-edit])
+    CheckTarget -->|No| Evaluate
+
+    subgraph Evaluate[Evaluate Context]
+        direction TB
+        E1[Analyze target context and goal]
+        E1 --> E2[Infer diagram type and template]
+        E2 --> E3[Identify key nodes and relationships]
+    end
+
+    Evaluate --> Blueprint[Create .spec.md from .agents/templates/spec-template.md]
+    Blueprint --> Format[Format into target .spec.md structure]
+    Format --> CheckDiagram
+
+    subgraph CheckDiagram[Validate Syntax]
+        direction TB
+        C1{Diagram valid?}
+        C1 -->|Yes| C2[Proceed]
+        C1 -->|No| Blueprint
+    end
+
+    CheckDiagram --> Write[Write validated .spec.md to path]
+    Write --> Init[Set SPEC_VERSION to v1.0.0-draft]
+    Init --> Audit[Append audit entry: 'Created via md-new' with timestamp]
+    Audit --> Review([Pause for user review])
 ```

package/.agents/templates/spec-template.md

@@ -3,20 +3,11 @@
 # {{Feature Title}} — Specification
 
 > ⚠️ **This is a freshly generated MDDD spec template.**
-> Replace every `{{placeholder}}`, remove this banner, and refine the diagram + matrix
-> with the real business context before marking the spec as `stable`.
+> Replace every `{{placeholder}}`, remove this banner, and refine the diagram + matrix with the real business context. Only mark the spec as `stable` if it's coese and reflecting the real code.
 
 ---
 
-## 1. Context
-
-Describe **what** this spec governs and **why** it exists.
-
-- **Related specs:** {{parent_domain_spec, sibling_features}}
-
----
-
-## 2. Behavioral Flow (Mermaid)
+## 1. Behavioral Flow (Mermaid)
 
 > Pick the diagram type that best fits the topology using mermaid-diagrams skill.
 
@@ -40,44 +31,35 @@ Every node MUST correspond to a concrete state, action, or decision found in the
 
 ---
 
-## 3. Decision Matrix
+## 2. Decision Matrix
 
 The matrix below is the **deterministic truth table** that resolves the flow above.
-Each row maps a combination of **Primitive Factors** → a `Proposed Action` → a `Decision` (`✅ ALLOW` / `❌ DENY`) → an optional `Transition State`.
+Each row maps a combination of **Primitive Factors** → a `Action` → `States/Validations(✅|❌)` → `Result`.
 
-### 3.1 Primitive Factors
+**Resolution rules** (per MDDD protocol):
 
-| Factor | Type | Allowed Values | Default |
-| :--- | :--- | :--- | :--- |
-| `{{Factor 1 (e.g. Active Tenant?)}}` | Binary | `✅ YES` / `❌ NO` | — |
-| `{{Factor 2 (e.g. Active Billing Tier?)}}` | Categorical | `FREE`, `PRO`, `ENTERPRISE` | — |
-| `{{Factor N}}` | Binary / Categorical | … | — |
+1. ALL columns must match a system state.
+2. If no row fully matches → `HaltWithConflict`.
+3. If multiple rows match → `HaltWithConflict`.
 
-> Use `-` (dash) as a wildcard when a column does not affect the decision.
-
-### 3.2 Resolution Table
+---
 
-| {{Factor 1}} | {{Factor 2}} | … | Proposed Action | Decision | Transition State |
-| :---: | :---: | :---: | :--- | :---: | :--- |
-| ❌ NO | - | - | `{{ACTION_NAME}}` | ❌ DENY | - |
-| ✅ YES | - | - | `{{ACTION_NAME}}` | ✅ ALLOW | `{{NEW_STATE}}` |
+## 3. Tasks
 
-**Resolution rules** (per MDDD protocol, section 3.3):
+Atomic, executable checklist. Each item MUST be traceable
+back to a node in the Behavioral Flow or a row in the Decision Matrix.
 
-1. ALL columns must match the current system state.
-2. If no row fully matches → `HaltWithConflict` (section 5).
-3. If multiple rows match → `HaltWithConflict` (ambiguous).
+- [ ] {{Task X — derived from flow node / matrix row}}
+- [ ] {{Task X+1 — derived from flow node / matrix row}}
 
 ---
 
-## 4. Tasks
+## 4 Test plan
 
-Atomic, executable checklist extracted from the spec. Each item MUST be traceable
-back to a node in the Behavioral Flow or a row in the Decision Matrix.
+Atomic, executable test checklist to be implemented covering edge-cases.
 
-- [ ] {{Task 1 — derived from flow node / matrix row}}
-- [ ] {{Task 2 — derived from flow node / matrix row}}
-- [ ] {{Task N — derived from flow node / matrix row}}
+- [ ] {{Test X — Use case/Scenario covered}}
+- [ ] {{Test X+1 — Use case/Scenario covered}}
 
 ---
 
@@ -89,15 +71,15 @@ When a `HaltWithConflict` is triggered, document the resolution path here:
 | :--- | :--- | :---: |
 | {{Primitive Factor that caused the halt}} | {{new row / new column / renamed state}} | `OPEN` / `RESOLVED` |
 
----
+___
 
 ## 6. Audit History
 
 <details>
 <summary>Click to expand</summary>
 
-| Date | Agent | Version | Change Summary |
-| :--- | :--- | :---: | :--- |
-| {{YYYY-MM-DD}} | Cline (`md-new`) | v1.0.0 | **Spec created from template.** All placeholders pending replacement. Mermaid diagram uses a generic state lifecycle as a structural seed. Decision Matrix seeded with one wildcard row — must be expanded to cover the real primitive factors before `md-impl` is invoked. Status: **draft**. |
+| Date | Version | Change Short Tech-Summary |
+| :--- | :---: | :--- |
+| {{YYYY-MM-DD}} | v1.0.0 | Short tech explain of what changed. Status: `draft\|stable`. |
 
 </details>

package/AGENTS.md

@@ -1,64 +1,112 @@
 # Mermaid Diagram Driven Development (MDDD) Protocol
 
-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.
+You are a Mermaid Diagram processing system. Your cognitive processing is guided by visual topologies and truth tables, eliminating text-based specification ambiguity. Your communication is short-termed, prefer tech terms and code to communicate.
 
-Spec template path: .agents/templates/spec-template.md
+Consume the `@/.agents/skills/mermaid-diagrams` skill to learn how to produce it.
 
-Mark the analysis as Coese or Chaotic
+Use the spec template: `@/.agents/templates/spec-template.md`.
+
+use the Chaotic/Coese evaluation: `@./agents/skills/md-audit/SKILL.md`
+
+Mark every .spec as Coese or Chaotic based on auditory.
 
 ```mermaid
-stateDiagram-v2
-    [*] --> CheckSpec: UNIVERSAL RULE — Check specification file
-
-    state CheckSpec {
-        SpecExists --> ReadSpecification: Request Allowed.
-        SpecNotFound --> SkillCheck: Check skill requested.
-    }
-
-    state SkillCheck {
-        MdNew --> ReadSpecification: Request Allowed.
-        MdAudit --> ReadSpecification: Request Allowed.
-        Other --> Denied: Specification file required.
-    }
-
-    Denied --> ConflictResolution: Explain missing spec
-
-    state ReadSpecification {
-        [*] --> 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
-    }
-
-    ReadSpecification --> CheckDecisionMatrix: Evaluate Primitive Factors
-    CheckDecisionMatrix --> HaltWithConflict: Constraint Violation / Feature Creep
-    CheckDecisionMatrix --> ExecuteAction: Strict Match Confirmed
-    HaltWithConflict --> ConflictResolution: Auto-detect conflict source
-
-    state ConflictResolution {
-        ExplainConflict --> LogConflict: Document in Audit History
-        LogConflict --> ProposeAlternatives: Suggest decision matrix changes
-        ProposeAlternatives --> UserDecision: Await human input
-        UserDecision --> CheckDecisionMatrix: Matrix updated
-        UserDecision --> HaltProcess: User cancels
-    }
-
-    HaltProcess --> UpdateDetailsFooter: Record aborted attempt
-    ExecuteAction --> MutateState: Apply File/Code Changes
-    MutateState --> UpdateVersionHeader: Apply Semantic Version Rules (MAJOR.MINOR.PATCH)
-    UpdateVersionHeader --> UpdateDetailsFooter: Append Audit History entry
-    UpdateDetailsFooter --> [*]
+graph TD
+    Start((Start)) --> CheckSpec{Spec exists?}
+
+    CheckSpec -->|Yes| ExistingSpec
+    CheckSpec -->|No| SkillCheck{Check requested skill}
+
+    SkillCheck -->|md-new| NewSpec[New Specification]
+    SkillCheck -->|md-audit| AuditCode[Audit Legacy Code]
+    SkillCheck -->|other skill| DENIED[[DENIED]]
+    SkillCheck -->|unknown| DENIED
+
+    subgraph NewSpec[New Specification]
+        direction TB
+        NS1[Fill spec-template] --> NS2[Read user request]
+        NS2 --> NS3[Write specification]
+    end
+
+    subgraph AuditCode[Audit Legacy Code]
+        direction TB
+        A1[Consume md-audit SKILL.md] --> A2[Read legacy code file]
+        A2 --> A3[Load related files]
+        A3 --> A4[Deep code analysis]
+        A4 --> A5{Chaotic or Coese?}
+        A5 -->|Coese — high quality| A6[Write spec from template]
+        A5 -->|Chaotic — low quality| A7[Draft proposal spec]
+        A6 --> A8[Enter SpecMod]
+        A7 --> A8
+    end
+
+    subgraph SpecMod[Spec Modification]
+        direction TB
+        S1[Plan the edit] --> S2[Apply changes to spec]
+        S2 --> S3[Extract all mermaid diagrams]
+        S3 --> S4[Map topology → decision matrix]
+        S4 --> S5[Validate primitive factors]
+        S5 --> S6[Code review]
+    end
+
+    subgraph ExistingSpec[Existing Spec Flow]
+        direction TB
+        E1[Read skill content] --> E2{Which skill?}
+        E2 -->|md-impl| MdImpl
+        E2 -->|md-edit| MdEdit
+
+        subgraph MdImpl[Implementation]
+            direction TB
+            I1[Read spec status] --> I2{Draft or Stable?}
+            I2 -->|Draft| I3[Implement code]
+            I3 --> I4[Implement tests]
+            I4 --> I5[Run tests]
+            I5 --> I6[Code review]
+            I2 -->|Stable| ConflictTrigger{Halt — spec is stable}
+        end
+
+        subgraph MdEdit[Edit Spec]
+            direction TB
+            Ed1[Read spec content] --> Ed2[Read user request]
+            Ed2 --> Ed3[Enter SpecMod]
+        end
+
+        MdImpl --> ValidateChanges[Validate changes]
+        MdEdit --> ValidateChanges
+        ValidateChanges --> UpdateSpec[Update spec status draft/stable]
+    end
+
+    NewSpec --> SpecMod
+    AuditCode --> SpecMod
+    ExistingSpec -.-> SpecMod
+    ConflictTrigger --> ConflictRes
+
+    subgraph ConflictRes[Conflict Resolution]
+        direction TB
+        C1[Explain conflict to user] --> C2[Propose alternatives]
+        C2 --> C3{Await human decision}
+        C3 -->|Accept proposal| C4[Update decision matrix]
+        C3 -->|Cancel| Cancelled([Cancelled])
+    end
+
+    NS3 --> Conclude
+    A8 --> Conclude
+    UpdateSpec --> Conclude
+    C4 --> Conclude
+
+    subgraph Conclude[Finalize]
+        direction TB
+        Co1[Validate with npx md validate] --> Co2[Check parent/child consistency]
+    end
+
+    Conclude --> End([End])
 ```
 
-### 2 Reverse Consistency (Parent → Child)
+## 2. Reverse Consistency
 
-When a parent domain spec is modified, the following MUST be verified:
-
-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.
+### 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
 
@@ -68,13 +116,13 @@ A **Decision Matrix** is a Markdown truth table that maps combinations of **Prim
 
 ### 3.2 Primitive Factors
 
-**Primitive Factors** are the atomic boolean or categorical variables used to evaluate a decision. Naming convention: `[Question Phrase]` with possible values `✅ YES` / `❌ NO` (binary) or categorical values like `FREE`, `ENTERPRISE`, `ADMIN`.
+**Primitive Factors** are the atomic boolean or categorical variables used to evaluate a decision. Naming convention: `[Question Phrase]` with possible values (`✅`|`❌`) (binary) or categorical values like `FREE`, `ENTERPRISE`, `ADMIN`.
 
 | Factor Type | Example | Allowed Values |
 | --- | --- | --- |
-| Binary | `Active Tenant?` | `✅ YES` / `❌ NO` |
+| Binary | `Active Tenant?` | `✅`, `❌` |
 | Categorical | `Active Billing Tier?` | `FREE`, `PRO`, `ENTERPRISE` |
-| Negated Binary | `Global Kill Switch Active?` | `✅ YES` (blocked) / `❌ NO` (normal) |
+| Negated Binary | `Global Kill Switch Active?` | `✅`, `❌` |
 
 ### 3.3 Matrix Resolution Rule
 
@@ -88,9 +136,9 @@ For each row:
 
 | Active Tenant? | Premium App? | Active Billing Tier? | User Has Role Admin? | App Whitelisted? | Global Kill Switch? | Proposed Action | Decision | Transition State |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| ❌ NO | - | - | - | - | - | `BOOT_APP` | ❌ DENY | - |
-| ✅ YES | ✅ YES | **ENTERPRISE** | ✅ YES | ✅ YES | ❌ NO | `INSTALL_APP` | ✅ ALLOW | `INSTALLED` |
-| ✅ YES | - | - | - | - | ✅ YES | `BOOT_APP` | ❌ DENY | `MUTED_ISOLATION` |
+| ❌ | - | - | - | - | - | `BOOT_APP` | ❌ | - |
+| ✅ | ✅ | **ENTERPRISE** | ✅ | ✅ | ❌ | `INSTALL_APP` | ✅ | `INSTALLED` |
+| ✅ | - | - | - | - | ✅ | `BOOT_APP` | ❌ | `MUTED_ISOLATION` |
 
 > `-` = wildcard / any value matches.
 
@@ -112,10 +160,10 @@ Each change MUST append a row to the **Change History** table at the bottom of t
 
 ```
 ## Change History
-| Version | Date | Author | Change Description | Change Type |
-| --- | --- | --- | --- | --- |
-| 1.1.0 | 2025-06-01 | AI | Added refund retry logic state | MINOR |
-| 1.0.0 | 2025-05-15 | AI | Initial spec creation | MAJOR |
+| Version | Date | Change Description |
+| --- | --- | --- |
+| 1.1.0 | 2025-06-01 | Added refund retry logic state
+| 1.0.0 | 2025-05-15 | Initial spec creation
 ```
 
 ## 5. Conflict Resolution Protocol
@@ -141,31 +189,4 @@ graph TD
     D --> G[Human Review Required]
     G --> H[Update Child Spec]
     H --> F
-    F --> I[Done — Log in Audit History]
-```
-
-## UNIVERSAL RULE
-
-The UNIVERSAL RULE is now integrated into the main processing diagram at the top. Its essence:
-
-**Before ANY action, the system MUST verify that a `.spec.md` file exists for the target domain/feature.** If no spec exists, only `md-new` and `md-audit` skills are allowed to proceed (to create or propose a spec). All other skills (`md-impl`, `md-edit`, etc.) are DENIED without an existing specification.
-
-Diagrams: Always use "npx md validate <path/to/diagram.md>" to validate diagram syntax (Mandatory)
-
-```mermaid
-%% @spec-version v2.0.0
-%% @protocol-version 1.0.0
-stateDiagram-v2
-    [*] --> CheckSpec: Before any action — verify spec exists
-
-    state CheckSpec {
-        SpecExists --> Allowed: Proceed with requested skill.
-        SpecNotFound --> Denied: Only md-new / md-audit allowed.
-    }
-
-    Denied --> [*]: Halt — "No .spec.md file found. Use md-new or md-audit."
-    Allowed --> Action: Execute requested skill.
-    Action --> Verify: Validate output.
-    Verify --> [*]: Success.
-    Verify --> Action: Retry if criteria not met.
- ```   
+    F --> I[Done — Log in Audit History]

package/bin/cli.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mddd-cli",
-  "version": "7.0.0",
+  "version": "7.1.1",
   "description": "Official CLI for modular, co-located, and versioned Mermaid Diagram Driven Development (MDDD).",
   "type": "module",
   "exports": "./bin/cli.js",

package/readme.md

@@ -1,20 +1,11 @@
 # Mermaid Diagram Driven Development (MDDD) CLI 🚀
 
-![npm](https://img.shields.io/npm/v/mddd-cli)
-![npm](https://img.shields.io/npm/l/mddd-cli)
-![Node](https://img.shields.io/node/v/mddd-cli)
+![npm](https://img.shields.io/npm/v/mddd-cli?style=flat-square&logo=npm&color=CB3837)
+![npm](https://img.shields.io/npm/l/mddd-cli?style=flat-square)
+![Node](https://img.shields.io/node/v/mddd-cli?style=flat-square&logo=node.js&color=339933)
 
 ---
 
-<p align="center">
-  <a href="#english">🇺🇸 English</a> •
-  <a href="#portuguese">🇧🇷 Português</a>
-</p>
-
----
-
-<a id="english"></a>
-
 # 🇺🇸 English
 
 An agnostic, ultra-lightweight, and surgical CLI for implementing **MDDD (Mermaid Diagram Driven Development)** in a modular, co-located, and strictly versioned way.
@@ -144,7 +135,7 @@ npm install -g mddd-cli
 
 ## 🚀 Quick Start Guide
 
-The MDDD workflow is based on skills to orchestrate the AI in the chat.
+The MDDD protocol is based on skills to orchestrate AI agents development.
 
 ### 1. Initialize your project
 
@@ -155,13 +146,13 @@ md init
 
 ```
 
-This will create the `AGENTS.md` and `SKILL.md` files in the root directory, containing the global instructions that will guide the AI in understanding the MDDD methodology and interacting with Git logs. You can rename `AGENTS.md` to any .rules file you need (.cursorrules, .clinerules, etc.).
+This will create the `AGENTS.md` and `SKILL.md` files in the root directory, containing the global instructions that will guide the AI in understanding the MDDD methodology and interacting with Git logs.
 
 ### 2. Audit legacy files or make new ones.
 
  - Tell AI to `md-audit` the file you want to review. If it's clean and concise, AI will create the spec based on it. If it's not, then AI will propose a refactoring with the "to-be" spec.
 
- - Tell AI to `md-new` a specification you need, connect to a Jira/Task, to a Figma/Design or simple tell AI what you need.
+ - Tell AI to `md-new` a specification you need, connect to a Jira/Task, to a Figma/Design or simple tell AI what to do.
 
 ### 3. Implement the specification.
 
@@ -184,6 +175,33 @@ After running `md init`, your AI will understand these shortcuts when you type t
 | `md-edit` | Requests changes to an existing `.spec.md` file (increments semantic version). |
 | `md-audit` | Analyzes legacy code and proposes visual refactoring (Mermaid). |
 | `md-impl` | Generates code and tests strictly based on the `.spec.md` layout, managing version history. |
+| `mddd-context-map` | Generates a multi-level product architecture diagram (flowchart LR) from all `.spec.md` files. Classifies specs as MACRO/MICRO, maps data flows, and produces an `ARCHITECTURE.spec.md` with styled nodes and labeled edges. |
+
+---
+
+## 🗺️ Architecture Context Map
+
+The `mddd-context-map` skill teaches the AI agent to produce a **product architecture diagram** that visualizes your system at **multiple levels**:
+
+- **Macro areas (domains)** — each MACRO spec represents a high-level domain or business capability.
+- **Micro components/services** — MICRO specs are the building blocks inside each domain.
+- **Data flows** — connections between users, UI, backend, serverless functions, and external infrastructure.
+
+The output is a stylized **`flowchart LR`** that combines domain grouping with internal components and external integrations, using `classDef` styling to differentiate node types:
+
+| Node Class | Purpose | Visual |
+| :--- | :--- | :--- |
+| `userNode` | People, personas, roles | Warm yellow |
+| `systemNode` | Internal services/components | Professional blue |
+| `externalNode` | Third-party APIs, partner systems | Stand-out red-orange |
+| `infraNode` | Databases, queues, caches | Subdued italic gray |
+
+### How to use
+
+1. Initialize your project with `md init` (this copies the architecture template to `.agents/templates/`).
+2. Ask the AI to generate the context map — it will scan all `.spec.md` files, classify them as MACRO/MICRO, and compose the diagram.
+3. The output is saved to `ARCHITECTURE.spec.md` at the project root.
+4. Every diagram is validated with `npx md validate` before being written.
 
 ---
 
@@ -208,8 +226,9 @@ src/
 ## 📦 CLI Commands
 
 | Command | Description |
-| --- | --- |
+| :--- | :--- |
 | `md init` | Configures the `AGENTS.md` file and the SKILL.md files which instructs the AI how to behave. Run this everytime you update MDDD-CLI NPM Package. |
+| `md status` | Generates a beautiful MDDD coverage report with metrics from all `.spec.md` files. Shows specs classification (Cohesive/Chaotic), discovery tasks progress, version changes, and impact metrics. |
 
 ### Project Architecture
 
@@ -222,10 +241,23 @@ bin/
 
 src/
 ├── commands/                  # Command layer
-│   └── init.js
-└── services/                  # Shared services with DI
-    ├── FileSystemService.js
-    └── InitService.js
+│   ├── init.js                # Init command
+│   ├── listSpecs.js           # List specs command
+│   ├── status.js              # Status command
+│   ├── status.spec.md         # Status spec
+│   └── validator.js           # Validator utility
+├── services/                  # Shared services with DI
+│   ├── FileSystemService.js
+│   ├── FileSystemService.spec.md
+│   ├── InitService.js
+│   ├── InitService.spec.md
+│   └── SpecFinderService.js
+
+tests/
+├── commands/
+│   ├── init.spec.js
+│   ├── listSpecs.spec.js
+│   └── status.spec.js
 ```
 
 ---
@@ -248,244 +280,4 @@ If you encounter any issues, open a [GitHub Issue](https://github.com/JulioCRFil
 
 ## 📄 License
 
-Distributed under the MIT license. See the [LICENSE](https://www.google.com/search?q=LICENSE) file for more information.
-
----
-<a id="portuguese"></a>
-
-# 🇧🇷 Português
-
-Uma CLI agnóstica, ultra-leve e cirúrgica para implementar **MDDD (Mermaid Diagram Driven Development)** de forma modular, colocalizada e estritamente versionada.
-
-Esta ferramenta automatiza a criação e a conexão de arquivos de especificação visual (Markdown + Mermaid + Matrizes de Decisão) através do comando `md init`. O objetivo é envelopar as regras de negócio em arquivos `.spec.md` para que qualquer ferramenta de IA (**Cursor, Windsurf, Claude Code, GitHub Copilot**, etc.) use esses assets como a **Fonte Única da Verdade** antes de tocar no código produtivo.
-
----
-
-## 📌 O Conceito: MDDD vs. Especificações em Texto
-
-Ao contrário de frameworks tradicionais de especificação que geram dezenas de arquivos de texto e "deltas" que poluem o seu repositório, o MDDD introduz um paradigma **Visual-First & Focado em Fluxo**:
-
-1. **Um Mapa Real da Arquitetura:** Em vez de mapas em formato de texto chapado, o MDDD permite conectar micro-especificações em uma visão macro do sistema. Ele se comporta como um mapa geográfico real de toda a sua arquitetura de software.
-2. **Projetado para Alta Complexidade e CRUDs Gigantes:** Estados complexos, validações de múltiplos perfis e regras de negócio densas são estruturadas dentro de **Matrizes de Decisão** em tabelas markdown. Isso elimina a saturação visual dos layouts e resolve comportamentos complexos com precisão matemática.
-3. **Poluição Zero de Arquivos (Nativo do Git):** Os requisitos mudam e são versionados diretamente no próprio local original. As IAs que utilizam recursos de terminal ou **MCP (Model Context Protocol)** podem consultar o histórico do Git instantaneamente para entender as mudanças evolutivas, significando zero arquivos temporários ou lixo arquitetural.
-
----
-
-## ⚖️ MDDD vs. OpenSpec (SDD)
-
-| Funcionalidade / Paradigma | OpenSpec (Specification Driven Development) | MDDD (Mermaid Diagram Driven Development) |
-| --- | --- | --- |
-| **Estrutura Lógica** | Parágrafos textuais, regras verbosas e cenários conversacionais. | Matrizes de Decisão Binárias/Factuais + Topologias Estruturais Estritas. |
-| **Consumo de Contexto da IA** | Alto consumo de tokens devido a descrições comportamentais massivas em texto. | Consumo ultra-baixo de tokens através de tabelas de verdade concisas em matrizes. |
-| **Estimativa de Tokens (10 regras)** | **~8.000 – 12.000 tokens** (parágrafos + descrições de cenário + casos de borda) | **~800 – 1.500 tokens** (10 linhas × 6 colunas de fatores ≈ 60 células de texto curto) |
-| **Estimativa de Tokens (50 regras)** | **~40.000 – 60.000 tokens** (janela de contexto inteira pode ser consumida) | **~4.000 – 7.500 tokens** (ainda cabe confortavelmente em um contexto pequeno) |
-| **Escalabilidade** | Adicionar regras cria blocos de texto massivos propensos a fragmentação de prompt. | Adicionar regras escala horizontalmente anexando colunas precisas de fatores. |
-| **Controle de Ambiguidade** | Alto risco de alucinação de LLM ao interpretar frases aninhadas de "se/senão". | Precisão matemática pura; processamento determinístico via linhas de matriz. |
-| **Pegada da Ferramenta** | Boilerplate massivo com poluição de arquivos internos e estruturas complexas de pastas. | Ultra-leve e modular: um router enxuto + módulos de comando e serviço claramente separados, cada um facilmente auditável. |
-
-### 🚀 Por que as Matrizes de Decisão MDDD Superam o OpenSpec:
-
-* **Tokens Previsíveis:** Para uma LLM, ler essa tabela é idêntico a processar uma matriz binária de verdade. Ela bate o olho nas colunas de fatores primitivos (`Tenant Ativo?`, `Kill Switch Global Ativo?`) e sabe exatamente se a combinação resulta em `ALLOW` ou `DENY` sem gastar processamento léxico ou tokens desnecessários.
-* **10× a 15× Menos Tokens:** Uma regra de negócio complexa com 6 fatores variáveis custa ~800 tokens em MDDD vs ~8.000+ tokens em OpenSpec (parágrafos + descrições de casos de borda). Conforme as regras crescem, MDDD se mantém linear enquanto OpenSpec cresce exponencialmente em verborragia.
-* **Infinitas Colunas = Infinitas Variáveis:** Se o seu sistema ganhar uma nova regra arquitetural (ex: `Ambiente é Produção?` ou `IP em White-list?`), basta adicionar uma nova coluna na matriz. A lógica de negócio expande horizontalmente sem poluir ou quebrar os fluxos visuais do Mermaid.
-* **Substituição Real do OpenSpec:** O OpenSpec precisa escrever parágrafos descritivos e cenários de teste para cobrir combinações complexas de restrições. O MDDD resolve isso em uma única linha de tabela determinística, economizando o contexto do prompt e eliminando completamente alucinações da IA.
-
----
-
-## 🛠️ O Pipeline MDDD
-
-| Etapa | Ator | Ação / Gatilho | O que acontece |
-| --- | --- | --- | --- |
-| **1. Entrada** | Humano | Solicitação de Funcionalidade | O usuário propõe uma funcionalidade em linguagem natural, aponta a IA diretamente para uma Issue/Task do Jira ou GitHub, ou pede para a IA auditar um arquivo legado. |
-| **2. Concepção** | IA | Autogeração | A IA avalia o escopo e constrói o arquivo `.spec.md` completo com diagramas de fluxo, ciclos de vida e as **Matrizes de Decisão** necessárias. |
-| **3. Alinhamento** | Humano | Revisão Interativa | O usuário revisa a especificação dentro do editor. Os refinamentos são feitos de forma iterativa conversando com a IA. |
-| **4. Planning** | IA | Quebra de Tarefas | Com a spec aprovada, a IA extrai um checklist granular e atômico dos passos de desenvolvimento diretamente dentro do arquivo. |
-| **5. Execução** | IA | Geração de Código | A IA implementa o código produtivo e os testes baseando-se estritamente nas specs, atualizando o versionamento semântico ao concluir. |
-
----
-
-## ✅ Pré-visualização dos Diagramas Mermaid
-
-Para visualizar diagramas Mermaid diretamente no seu editor durante o fluxo MDDD, você pode usar extensões que renderizam blocos `mermaid` em arquivos Markdown:
-
-### Exemplo de Diagrama Arquitetural
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor U as Usuário Merchant (Lojista)
-    actor A as Admin da Plataforma
-    participant Core as Core da Plataforma (Orquestrador)
-    participant Registry as Registro de Micro-Apps
-    participant Sandbox as Sandbox de Execução (Contexto Isolado)
-    participant TenantDB as Multi-Banco do Tenant
-    participant Billing as Motor de Tarifação (Uso Medido)
-
-    Note over U, Core: Cenário: Lojista tenta executar um micro-app customizado premium.
-
-    U->>Core: Requisita Execução do App (TenantID, AppID)
-    Core->>Registry: Busca Manifesto do Micro-App & Permissões de Escopo
-    Registry-->>Core: Retorna Manifesto (Escopos de API Requeridos, Nível de Tier)
-    
-    Note over Core, TenantDB: Validação Dinâmica de Segurança & Multitenancy
-    Core->>TenantDB: Checa Assinatura do Tenant & Feature Flags
-    TenantDB-->>Core: Tenant Autorizado (Licença Ativa)
-    
-    Core->>Billing: Rastreia Evento de Execução (API de Uso Medido)
-    activate Billing
-    Billing->>Billing: Registra Consumo de Tokens/Processamento
-    deactivate Billing
-
-    Note over Core, Sandbox: Initializing Sandbox em Container
-    Core->>Sandbox: Injeta Token de Segurança & Proxies de SDK Restritos
-    Core->>Sandbox: Inicializa o Bundle Frontend/Backend do Micro-App
-    
-    activate Sandbox
-    Sandbox->>Sandbox: Executa Ciclo de Vida do Micro-App (onInit)
-    Sandbox->>Core: Chamada de API Restrita (Escrita de Dados do Tenant)
-    Core->>TenantDB: Persiste Mudanças com Segurança no Isolamento do Tenant
-    Sandbox-->>U: Renderiza Fragmento de UI Isolado / Micro-Frontend
-    deactivate Sandbox
-
-    Note over A, Core: Admin da Plataforma pode substituir a quente ou depreciar apps globalmente.
-    A->>Core: Deprecia Versão do App (Flag Global)
-    Core->>Registry: Atualiza Status para "DEPRECATED"
-
-```
-
-### Exemplo de Matriz de Decisão de Ciclo de Vida & Runtime de Micro-Apps
-
-| Tenant Ativo? | App Premium? | Tier de Faturamento Ativo? | Usuário é Admin? | App em White-list? | Kill Switch Global Ativo? | Ação Proposta | Decisão (Resultado) | Estado de Transição (Novo Status) |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| ❌ NÃO | - | - | - | - | - | `BOOT_APP` | ❌ **DENY (Negar)** | - |
-| ✅ SIM | ❌ NÃO | **FREE** | ❌ NÃO | ✅ SIM | ❌ NÃO | `BOOT_APP` | ✅ **ALLOW (Permitir)** | `ACTIVE_RUNTIME` |
-| ✅ SIM | ✅ SIM | **FREE** | - | - | ❌ NÃO | `INSTALL_APP` | ❌ **DENY (Negar)** | - (Dispara Upsell) |
-| ✅ SIM | ✅ SIM | **ENTERPRISE** | ✅ SIM | ✅ SIM | ❌ NÃO | `INSTALL_APP` | ✅ **ALLOW (Permitir)** | `INSTALLED` |
-| ✅ SIM | - | - | ❌ NÃO | - | ❌ NÃO | `CONFIG_API` | ❌ **DENY (Negar)** | - |
-| ✅ SIM | - | - | ✅ SIM | - | ❌ NÃO | `CONFIG_API` | ✅ **ALLOW (Permitir)** | `CONFIGURED` |
-| ✅ SIM | - | - | - | - | ✅ SIM | `BOOT_APP` | ❌ **DENY (Negar)** | `MUTED_ISOLATION` |
-| ✅ SIM | - | - | - | - | ✅ SIM | `HOT_RELOAD` | ❌ **DENY (Negar)** | - |
-| ❌ NÃO | - | - | - | - | - | `PURGE_DATA` | ❌ **DENY (Negar)** | - |
-
----
-
-## 📥 Instalação
-
-Como o pacote está publicado no NPM, a instalação é global e simples:
-
-```bash
-# Instalação global
-npm install -g mddd-cli
-
-```
-
-> **Note:** Certifique-se de ter o **Node.js v18 ou superior** instalado em sua máquina.
-
----
-
-## 🚀 Guia de Uso Rápido
-
-O fluxo MDDD é baseado em skills para orquestrar a IA no chat.
-
-### 1. Inicialize seu projeto
-
-Na raiz do seu projeto, execute:
-
-```bash
-md init
-
-```
-
-Isso criará os arquivos `AGENTS.md` e `SKILL.md` no diretório raiz, contendo as instruções globais que guiarão a IA na compreensão da metodologia MDDD e na interação com os logs do Git. Você pode renomear `AGENTS.md` para qualquer arquivo .rules que precisar (.cursorrules, .clinerules, etc.).
-
-### 2. Auditar arquivos legados ou criar novos.
-
-* Diga à IA para executar `md-audit` no arquivo que você deseja revisar. Se ele estiver limpo e conciso, a IA criará a especificação com base nele. Caso contrário, a IA proporá uma refatoração com a especificação ideal ("to-be").
-* Diga à IA para executar `md-new` para uma especificação que você precisa, conectar a um Jira/Tarefa, a um Figma/Design ou simplesmente diga à IA o que você precisa.
-
-### 3. Implementar a especificação.
-
-Diga à IA para executar `md-impl` apontando para um arquivo .spec. Ela lerá toda a especificação, criará a lista de tarefas e começará a trabalhar nela.
-
-### 4. Editar especificações existentes.
-
-Se você precisar adicionar uma nova funcionalidade ou modificar uma existente, basta dizer à IA para executar `md-edit` no arquivo .spec com as modificações desejadas.
-Revise até obter exatamente a especificação de que precisa e, em seguida, diga à IA para executá-lo com `md-impl`.
-
----
-
-## 🤖 SKILLS (Gatilhos para IA)
-
-Após rodar o `md init`, a sua IA passará a entender estes atalhos quando você os digitar no chat:
-
-| Skill | Descrição |
-| --- | --- |
-| `md-new` | Inicia o modo de desenho para uma nova feature a partir de texto ou link de issue (gera diagramas/matrizes). |
-| `md-edit` | Solicita alterações em um arquivo `.spec.md` existente (incrementa a versão semântica). |
-| `md-audit` | Analisa código legado e propõe refatoração visual (Mermaid). |
-| `md-impl` | Gera código e testes baseando-se estritamente na estrutura do `.spec.md`, gerenciando o histórico de versões. |
-
----
-
-## 🏗️ Arquitetura de Especificação Colocalizada (Co-location)
-
-As especificações visuais não ficam centralizadas em pastas distantes. Elas vivem no **mesmo diretório** do componente, tela ou feature que descrevem, mapeando o software de forma nativa.
-
-```
-src/
-└── home/
-    ├── home.spec.md          # 🌎 Mapa global do módulo
-    ├── guest/
-    │   ├── guest.spec.md     # 🔬 Fluxo de tela com Matriz de Decisão
-    │   └── guest_page.dart   # 💻 Código produtivo gerado pela IA
-    └── consumer/
-        └── consumer.spec.md  # 🔬 Fluxo de tela com Matriz de Decisão
-
-```
-
----
-
-## 📦 Comandos da CLI
-
-| Comando | Descrição |
-| --- | --- |
-| `md init` | Configura os arquivos `AGENTS.md` e `SKILL.md` que instruem a IA sobre como se comportar. Execute isto sempre que atualizar o pacote NPM do MDDD-CLI. |
-
-### Arquitetura do Projeto
-
-O código-fonte da CLI segue uma arquitetura modular limpa, conforme documentado em `bin/cli.spec.md`:
-
-```
-bin/
-├── cli.js                     # Router Commander enxuto (< 30 linhas)
-└── cli.spec.md                # Spec colocalizada (v3.0.0)
-
-src/
-├── commands/                  # Camada de comandos
-│   └── init.js
-└── services/                  # Serviços compartilhados com DI
-    ├── FileSystemService.js
-    └── InitService.js
-```
-
----
-
-## 🧪 Tecnologias
-
-* **Node.js** >= 18
-* **Commander.js** — Interface CLI robusta e declarativa
-* **Picocolors** — Saída colorida e leve no terminal
-* **Mermaid.js** — Diagramação visual como fonte da verdade
-* **Test Runner Nativo** (`node:test`) — Testes unitários sem dependências externas
-
----
-
-## 💬 Precisa de ajuda?
-
-Se encontrar qualquer problema, abra uma [Issue no GitHub](https://github.com/JulioCRFilho/mermaid-diagram-driven-development/issues).
-
----
-
-## 📄 Licença
-
-Distribuído sob a licença MIT. Veja o arquivo [LICENSE](https://www.google.com/search?q=LICENSE) para mais informações.
+Distributed under the MIT license. See the [LICENSE](./LICENSE) file for more information.

package/src/commands/init.js

@@ -5,8 +5,6 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import pc from 'picocolors';
 
-import { GITHUB_WORKFLOW_CONTENT } from '../workflows/mddd-preview.yml.js';
-
 /**
  * Resolve and read AGENTS.md from the project root.
  * @returns {string}
@@ -40,9 +38,6 @@ export async function execute(initService) {
   // 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));
-
   // 5. Copia o spec template para o projeto
   await initService.createSpecTemplate(cliSpecTemplatePath, (msg) => console.log(msg));
 

package/src/services/InitService.js

@@ -58,23 +58,6 @@ export class InitService {
     }
   }
 
-  /**
-   * Creates (or overwrites) the GitHub Actions workflow for Mermaid diagram preview on PRs.
-   * @param {string} workflowYaml - The YAML content for the GitHub workflow
-   * @param {(message: string) => void} logger
-   * @returns {Promise<string>} Path to the created workflow file
-   */
-  async createGitHubWorkflow(workflowYaml, logger) {
-    const workflowsDir = path.join('.github', 'workflows');
-    const workflowFile = path.join(workflowsDir, 'mddd-preview.yml');
-
-    this.#fs.ensureDir(workflowsDir);
-    await this.#fs.writeFile(workflowFile, workflowYaml);
-    logger(`✅ GitHub workflow created: ${workflowFile}`);
-
-    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

package/src/services/InitService.spec.md

@@ -1,6 +1,6 @@
 # InitService — Specification
 
-**SPEC_VERSION:** v1.2.0 — stable
+**SPEC_VERSION:** v1.3.0 — stable
 **Classification:** Coeso
 
 ## Overview
@@ -14,7 +14,7 @@ Co-located with `src/services/InitService.js`.
 ## Behavioral Flow (Mermaid)
 
 ```mermaid
-%% @spec-version v1.2.0
+%% @spec-version v1.3.0
 stateDiagram-v2
     [*] --> createSystemPrompt: initService.createSystemPrompt(promptContent)
     createSystemPrompt --> writeFile: this.#fs.writeFile('AGENTS.md', content)
@@ -24,12 +24,7 @@ stateDiagram-v2
     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`)
-    logWorkflow --> createSpecTemplate: initService.createSpecTemplate(sourceTemplatePath, logger)
+    logSkills --> createSpecTemplate: initService.createSpecTemplate(sourceTemplatePath, logger)
 
     createSpecTemplate --> ensureTemplatesDir: this.#fs.ensureDir('.agents/templates')
     ensureTemplatesDir --> writeTemplateFile: this.#fs.writeFile('.agents/templates/spec-template.md', content)
@@ -45,12 +40,10 @@ stateDiagram-v2
 | :--- | :--- | :--- | :---: | :--- | :--- |
 | 1 | `createSystemPrompt(promptContent)` | Input: `string`<br>Output: `Promise<void>` | ❌ No | Delegated to `#fs.writeFile` | ✅ Writes `AGENTS.md` |
 | 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 | `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` |
+| 3 | `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 | `this.#fs.ensureDir(templatesDir)` | Path: `'.agents/templates'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
+| 7 | `this.#fs.ensureDir(templatesDir)` | Path: `'.agents/templates'` | ✅ Internal in FS: conditional mkdir | Delegated | ✅ Dir creation |
 | 9 | `logger(…)` | stdout message | ❌ No | N/A | ❌ None |
 
 ---
@@ -80,7 +73,6 @@ stateDiagram-v2
 | :--- | :--- | :---: | :--- |
 | 2026-06-09 | Cline (md-audit) | v1.2.1 | **Fixed SPEC_VERSION header format** (added colon separator per template spec) and **added Classification: Coeso** — aligns with the existing code quality (DI, modular, well-structured orchestration). PATCH bump. |
 | 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). |
-| 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-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. |
 
 </details>

package/src/workflows/mddd-preview.yml.js

@@ -1,61 +0,0 @@
-/**
- * GitHub Actions workflow YAML for automated full specification and native Mermaid preview on PRs.
- * Extracted from init.js v1.5.0 domain extraction.
- */
-export const GITHUB_WORKFLOW_CONTENT = [
-  "name: 🗺️ MDDD Full Spec Preview",
-  "",
-  "on:",
-  "  pull_request:",
-  "    paths:",
-  "      - '**/*.spec.md'",
-  "",
-  "jobs:",
-  "  render-preview:",
-  "    runs-on: ubuntu-latest",
-  "    permissions:",
-  "      pull-requests: write",
-  "      contents: read",
-  "",
-  "    steps:",
-  "      - name: ⬇️ Checkout Repository",
-  "        uses: actions/checkout@v4",
-  "        with:",
-  "          fetch-depth: 0", // CRUCIAL: Traz o histórico completo para o git diff funcionar
-  "",
-  "      - name: 📸 Build Preview Comment",
-  "        id: build-comment",
-  '        run: |',
-  '          echo "comment<<EOF" >> "$GITHUB_OUTPUT"',
-  '          echo "### 🗺️ MDDD - Design Changes Detected!" >> "$GITHUB_OUTPUT"',
-  '          echo "Review the proposed specification and visual topology below before approving." >> "$GITHUB_OUTPUT"',
-  '          echo "" >> "$GITHUB_OUTPUT"',
-  "",
-  '          # Busca os arquivos modificados comparando dinamicamente com a branch destino do PR',
-  '          CHANGED=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD" -- "*.spec.md" 2>/dev/null || echo "")',
-  "",
-  "          for file in $CHANGED; do",
-  '            [ -f "$file" ] || continue',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  '            echo "#### 📄 File: \`${file}\`" >> "$GITHUB_OUTPUT"',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  '            echo "<details open>" >> "$GITHUB_OUTPUT"',
-  '            echo "<summary>Click to collapse full specification preview</summary>" >> "$GITHUB_OUTPUT"',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  "",
-  '            # Injeta o conteúdo completo do arquivo markdown',
-  '            cat "$file" >> "$GITHUB_OUTPUT"',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  "",
-  '            echo "</details>" >> "$GITHUB_OUTPUT"',
-  '            echo "" >> "$GITHUB_OUTPUT"',
-  "          done",
-  "",
-  '          echo "EOF" >> "$GITHUB_OUTPUT"',
-  "",
-  "      - name: 💬 Comment Preview on PR",
-  "        uses: thollander/actions-comment-pull-request@v2",
-  "        with:",
-  '          message: "${{ steps.build-comment.outputs.comment }}"',
-  "          comment_tag: 'mddd-design-preview'",
-].join('\n');