mddd-cli 7.0.0 → 7.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/.agents/skills/md-audit/SKILL.md +36 -34
  2. package/.agents/skills/md-edit/SKILL.md +38 -50
  3. package/.agents/skills/md-impl/SKILL.md +58 -48
  4. package/.agents/skills/md-new/SKILL.md +29 -40
  5. package/.agents/templates/spec-template.md +22 -40
  6. package/AGENTS.md +111 -90
  7. package/bin/cli.js +1 -1
  8. package/package.json +1 -1
  9. package/readme.md +101 -15
package/.agents/skills/md-audit/SKILL.md CHANGED
@@ -1,38 +1,40 @@
1
- [ROLE: SECURITY & QUALITY AUDITOR] [STRICT CONTRACT]
2
-
3
1
  ```mermaid
4
- %% @spec-version v1.3.2
5
- stateDiagram-v2
6
- [*] --> Evaluation: Quality Assessment.
7
- Evaluation --> MakeSpec: Co-located .spec.md.
8
-
9
- state MakeSpec {
10
- [*] --> SpecExists: Check for existing .spec.md.
11
- SpecNotFound --> CreateSpec: Create .spec.md from "src/templates/spec-template.md".
12
- SpecExists --> Break: Audit only.
13
- Break --> [*]
14
- }
15
-
16
- CreateSpec --> RenderTopology: Create new co-located .spec.md.
17
-
18
- state RenderTopology {
19
- [*] --> CheckCode: Analyze current code structure and dependencies
20
- CheckCode --> EvaluatedCodeIsClean: Map exact architecture as coese (v1.0.0 - stable)
21
- CheckCode --> EvaluatedCodeIsChaotic: Draw BOTH current chaotic logic AND ideal target refactored graph (v1.0.0 - draft)
22
- }
23
-
24
- RenderTopology --> CheckDiagram: Use "npx md validate <path/to/spec.md>" to validate diagram syntax
25
-
26
- state CheckDiagram {
27
- [*] --> DiagramValid: Proceed to next step
28
- DiagramInvalid --> RenderTopology: Re-render until valid
29
- }
30
-
31
- CheckDiagram --> DiscoveryAnalysis: Identify potential vulnerabilities and code quality issues
32
- DiscoveryAnalysis --> WriteToAuditTag: Document findings and recommendations in the .spec.md file
33
- WriteToAuditTag: Inject payloads inside <details> block
34
- WriteToAuditTag --> EnforceImmutability: Lock Production Code File
35
- EnforceImmutability --> [*]
2
+ %% @spec-version v1.3.3
3
+ graph TD
4
+ Start((Start)) --> Evaluation{Quality Assessment}
5
+
6
+ Evaluation -->|Co-located .spec.md| MakeSpec
7
+
8
+ subgraph MakeSpec[Check Existing Spec]
9
+ direction TB
10
+ M1{Spec exists?}
11
+ M1 -->|No| M2[Create .spec.md from .agents/templates/spec-template.md]
12
+ M1 -->|Yes| M3[Audit only]
13
+ M3 --> Break([Break])
14
+ end
15
+
16
+ M2 --> RenderTopology
17
+
18
+ subgraph RenderTopology[Analyze Code]
19
+ direction TB
20
+ R1[Analyze code structure and dependencies]
21
+ R1 --> R2{Chaotic or Coese?}
22
+ R2 -->|Coese| R3[Map exact architecture — stable]
23
+ R2 -->|Chaotic| R4[Draw current + ideal refactored graph — draft]
24
+ end
25
+
26
+ RenderTopology --> CheckDiagram
27
+
28
+ subgraph CheckDiagram[Validate Syntax]
29
+ direction TB
30
+ C1{Diagram valid?}
31
+ C1 -->|Yes| C2[Proceed]
32
+ C1 -->|No| RenderTopology
33
+ end
34
+
35
+ CheckDiagram --> D[Identify vulnerabilities and code quality issues]
36
+ D --> W[Document findings in .spec.md <details> block]
37
+ W --> End((End))
36
38
  ```
37
39
 
38
40
  ```mermaid
package/.agents/skills/md-edit/SKILL.md CHANGED
@@ -1,56 +1,44 @@
1
1
  [ROLE: ARCHITECT] [STRICT CONTRACT]
2
2
 
3
3
  ```mermaid
4
- %% @spec-version v1.3.1
5
- stateDiagram-v2
6
- [*] --> Read TargetSpec: Read Target .spec.md
7
- Read TargetSpec --> ParseVersion: Parse Current SPEC_VERSION
8
- ParseVersion --> ApplyAdjustments: Apply requested Mermaid/Matrix Adjustments
9
- ApplyAdjustments --> EvaluateScope: Evaluate Mutation Scope
10
-
11
- state EvaluateScope {
12
- [*] --> TypoFix: Typo / Label Fix
13
- [*] --> NewNode: New Node / Flow Path / Factor
14
- [*] --> BreakingChange: Breaking Overhaul / Restructure
15
- }
16
-
17
- EvaluateScope --> IncrementVersion: Increment Version Based on Scope
18
-
19
- state IncrementVersion {
20
- [*] --> IncrementPatch: Increment Patch: Bump Z in X.Y.Z
21
- [*] --> IncrementMinor: Increment Minor: Bump Y in X.Y.Z
22
- [*] --> IncrementMajor: Increment Major: Bump X in X.Y.Z
23
- }
24
-
25
- IncrementVersion --> CheckDiagram: Use "npx md validate <path/to/spec.md>" to validate diagram syntax
26
-
27
- state CheckDiagram {
28
- [*] --> TryRender
29
- TryRender --> DiagramValid: Render succeeded
30
- TryRender --> IncrementRetry: Render failed
31
- IncrementRetry --> TryRender: Retry count < 5
32
- IncrementRetry --> RenderFailed: Retry count >= 5
33
- }
34
-
35
- CheckDiagram --> WriteToFile: Write validated .spec.md to target path
36
- WriteToFile --> VerifyWrite
37
- state VerifyWrite {
38
- [*] --> WriteSuccess: File written successfully
39
- [*] --> WriteError: File write failed (permissions / disk / path)
40
- }
41
- WriteError --> AwaitHumanReview: Error: manual intervention required
42
-
43
- WriteSuccess --> DiscoveryAnalysis: Identify potential vulnerabilities and code quality issues
44
- DiscoveryAnalysis --> AwaitHumanReview: Flag discovered issues for human review
45
- RenderFailed --> AwaitHumanReview: Error: Mermaid CLI validation failed after 5 attempts
46
-
47
- state AwaitHumanReview {
48
- [*] --> Approved: Resume CI/CD pipeline
49
- [*] --> ChangesRequested: Loop back to ApplyAdjustments
50
- [*] --> Aborted: Terminate session
51
- }
52
-
53
- AwaitHumanReview --> [*]: Pause Code & Test Generation
4
+ %% @spec-version v1.3.2
5
+ graph TD
6
+ Start((Start)) --> Read[Read target .spec.md]
7
+ Read --> Parse[Parse SPEC_VERSION]
8
+ Parse --> Apply[Apply requested diagram/matrix adjustments]
9
+ Apply --> Scope{Evaluate mutation scope}
10
+
11
+ Scope -->|Typo / label fix| PatchBump[Increment PATCH]
12
+ Scope -->|New node / flow / factor| MinorBump[Increment MINOR]
13
+ Scope -->|Breaking restructure| MajorBump[Increment MAJOR]
14
+
15
+ PatchBump --> Validate
16
+ MinorBump --> Validate
17
+ MajorBump --> Validate
18
+
19
+ subgraph Validate[Validate & Write]
20
+ direction TB
21
+ V1[Try render with npx md validate] --> V2{Render result?}
22
+ V2 -->|Success| V3[Write to target path]
23
+ V2 -->|Failed, retries < 5| V1
24
+ V2 -->|Failed, retries >= 5| V4[[RENDER_FAILED]]
25
+ V3 --> V5{Write result?}
26
+ V5 -->|Success| V6[Proceed]
27
+ V5 -->|Error| V7[[WRITE_ERROR]]
28
+ end
29
+
30
+ V6 --> Audit[Identify vulnerabilities and issues]
31
+ Audit --> Review
32
+ V4 --> Review
33
+ V7 --> Review
34
+
35
+ subgraph Review[Await Human Review]
36
+ direction TB
37
+ R1{Await decision}
38
+ R1 -->|Approved| R2([End])
39
+ R1 -->|Changes requested| Apply
40
+ R1 -->|Aborted| R3([End])
41
+ end
54
42
  ```
55
43
 
56
44
  ```mermaid
package/.agents/skills/md-impl/SKILL.md CHANGED
@@ -1,54 +1,64 @@
1
1
  [ROLE: SOFTWARE ENGINEER] [STRICT CONTRACT]
2
2
 
3
3
  ```mermaid
4
- %% @spec-version v1.3.1
5
- stateDiagram-v2
6
- state ImplWorkflow {
7
- [*] --> IngestSpec: [Inherits Parent Context] Ingest Signed .spec.md
8
- IngestSpec --> ParseVersion: Parse Matrix Rows & Version Header
9
- ParseVersion --> VerifyRequest: Verify Code/Chat Request Against Decision Matrix
10
- VerifyRequest -->|Matches 100%| CheckTarget: Check File Target State
11
- VerifyRequest -->|Human Asks to Skip/Add Extraneous Scope| TriggerDefense: Trigger Prompt Injection Defense
12
-
13
- CheckTarget -->|New File| GenerateCode: Generate Full Structural Code from Scratch
14
- CheckTarget -->|Existing File| IdempotentOverwrite: Idempotent Overwrite - Read & Output Full File
15
-
16
- GenerateCode --> GenerateTests: Generate Truth-Table Unit Tests
17
- IdempotentOverwrite --> DataLossCheck: Check for Data Loss Risk
18
- DataLossCheck -->|No Risk| GenerateTests
19
- DataLossCheck -->|Risk Detected| AlertUser: Alert User & Pause Generation
20
-
21
- GenerateTests --> RunTests: Run Generated Tests
22
- RunTests -->|All Pass| PromoteSpec: Promote .spec.md from draft to stable
23
- RunTests -->|Any Fail| FixCode: Fix Code/Tests & Retry
24
-
25
- PromoteSpec --> UpdateVersion: Update SPEC_VERSION to vSameVersion - stable
26
- UpdateVersion --> AppendHistory: Append Audit History: impl complete
27
- AppendHistory --> PersistSpec: Persist Updated .spec.md to Disk
28
- PersistSpec --> AwaitHumanReview: Pause for User Approval Before Lock
29
- }
30
-
31
- state AwaitHumanReview {
32
- [*] --> LockApproved: User approves immutability lock
33
- [*] --> ChangesRequested: User requests changes → loop back to GenerateCode/IdempotentOverwrite
34
- [*] --> Aborted: Terminate session without lock
35
- }
36
-
37
- LockApproved --> LockCodeImmutability: Lock Code Immutability for Stable Version
38
-
39
- state LockCodeImmutability {
40
- [*] --> SetGitHook: Install pre-commit hook blocking edits to stable files
41
- SetGitHook --> SetSpecFlag: Set .spec.md immutable flag (SPEC_IMMUTABLE: true)
42
- SetGitHook --> SetFilePermissions: chmod 444 on production code files
43
- SetFilePermissions --> VerifyLock: Verify git diff shows no modifications
44
- VerifyLock --> LockComplete: Lock verified & confirmed
45
- LockComplete --> [*]
46
- }
47
-
48
- LockCodeImmutability --> [*]
49
-
50
- TriggerDefense --> RefuseCoding: Refuse Coding & Demand Spec Refinement via md-edit
51
- RefuseCoding --> [*]
4
+ %% @spec-version v1.3.2
5
+ graph TD
6
+ Start((Start)) --> Ingest[Ingest signed .spec.md]
7
+ Ingest --> Parse[Parse matrix rows & version header]
8
+ Parse --> Verify{Verify request against decision matrix}
9
+
10
+ Verify -->|100% match| CheckTarget{Check target state}
11
+ Verify -->|Skip / extraneous scope| Defense[[PROMPT INJECTION DEFENSE]]
12
+ Defense --> Refuse[Refuse — demand spec refinement via md-edit]
13
+ Refuse --> End((End))
14
+
15
+ CheckTarget -->|New file| GenCode[Generate code from scratch]
16
+ CheckTarget -->|Existing file| Overwrite[Idempotent overwrite]
17
+
18
+ Overwrite --> DataLossCheck{Data loss risk?}
19
+
20
+ subgraph DataLossCheck[Evaluate Data Loss Risk]
21
+ direction TB
22
+ D1[File exists + will be overwritten?]
23
+ D2[Changes outside spec scope?]
24
+ D3[Uncommitted changes?]
25
+ D1 --> D4{Any risk factor true?}
26
+ D2 --> D4
27
+ D3 --> D4
28
+ D4 -->|Yes| Alert[[ALERT — pause generation]]
29
+ D4 -->|No| Proceed
30
+ end
31
+
32
+ GenCode --> Proceed
33
+ Proceed --> GenTests[Generate truth-table unit tests]
34
+ GenTests --> Run{All tests pass?}
35
+ Run -->|Yes| Promote[Promote .spec.md: draft → stable]
36
+ Run -->|No| Fix[Fix code/tests & retry]
37
+ Fix --> Proceed
38
+
39
+ Promote --> Update[Update SPEC_VERSION to stable]
40
+ Update --> History[Append audit history]
41
+ History --> Persist[Persist .spec.md to disk]
42
+ Persist --> Review
43
+
44
+ subgraph Review[Await Human Approval]
45
+ direction TB
46
+ R1{Await decision}
47
+ R1 -->|Lock approved| Lock
48
+ R1 -->|Changes requested| GenCode
49
+ R1 -->|Aborted| End
50
+ end
51
+
52
+ subgraph Lock[Lock Code Immutability]
53
+ direction TB
54
+ L1[Install pre-commit hook]
55
+ L2[Set SPEC_IMMUTABLE: true]
56
+ L3[chmod 444 on production files]
57
+ L4[Verify git diff = clean]
58
+ L1 --> L2 --> L3 --> L4 --> L5([Lock confirmed])
59
+ end
60
+
61
+ Lock --> End((End))
52
62
  ```
53
63
 
54
64
  ```mermaid
package/.agents/skills/md-new/SKILL.md CHANGED
@@ -1,44 +1,33 @@
1
1
  [ROLE: ARCHITECT] [STRICT CONTRACT]
2
2
 
3
3
  ```mermaid
4
- %% @spec-version v1.3.1
5
- stateDiagram-v2
6
- [*] --> TargetVerification
7
-
8
- state TargetVerification {
9
- [*] --> CheckFileExistence: Does .spec.md already exist at target path?
10
- FileExists --> Break: Existing .specs are immutable. Switch to edit mode.
11
- FileNotFound --> EvaluateContext: File Does Not Exist
12
- }
13
-
14
- state EvaluateContext {
15
- [*] --> DeepAnalysis: Evaluate target context and goal
16
- DeepAnalysis --> DiagramTypeInference: Infer appropriate diagram type and template
17
- DiagramTypeInference --> InferNodes: Identify key nodes and relationships to be represented
18
- }
19
-
20
- EvaluateContext --> GenerateBlueprint: Create .spec.md from "src/templates/spec-template.md".
21
- GenerateBlueprint --> FormatSpecOutput: Format blueprint into target .spec.md structure
22
- FormatSpecOutput --> CheckDiagram: Use "npx md validate <path/to/spec.md>" to validate diagram syntax
23
-
24
- state CheckDiagram {
25
- [*] --> DiagramValid: Proceed to next step
26
- DiagramInvalid --> GenerateBlueprint: Re-generate blueprint with adjustments until valid
27
- }
28
-
29
- CheckDiagram --> WriteToFile: Write validated .spec.md to target path
30
- WriteToFile --> InitializeVersion: Set initial SPEC_VERSION
31
-
32
- state InitializeVersion {
33
- [*] --> SetDraftVersion: Set SPEC_VERSION to v1.0.0-draft
34
- }
35
-
36
- InitializeVersion --> AppendCreationAudit: Record creation metadata
37
-
38
- state AppendCreationAudit {
39
- [*] --> LogCreation: Append audit entry: "Created via md-new" with timestamp
40
- }
41
-
42
- AppendCreationAudit --> AwaitHumanReview: Pause for user to review and adjust generated diagram
43
- AwaitHumanReview --> [*]
4
+ %% @spec-version v1.3.2
5
+ graph TD
6
+ Start((Start)) --> CheckTarget{Target .spec.md exists?}
7
+
8
+ CheckTarget -->|Yes| Break([Break — existing specs are immutable. Use md-edit])
9
+ CheckTarget -->|No| Evaluate
10
+
11
+ subgraph Evaluate[Evaluate Context]
12
+ direction TB
13
+ E1[Analyze target context and goal]
14
+ E1 --> E2[Infer diagram type and template]
15
+ E2 --> E3[Identify key nodes and relationships]
16
+ end
17
+
18
+ Evaluate --> Blueprint[Create .spec.md from .agents/templates/spec-template.md]
19
+ Blueprint --> Format[Format into target .spec.md structure]
20
+ Format --> CheckDiagram
21
+
22
+ subgraph CheckDiagram[Validate Syntax]
23
+ direction TB
24
+ C1{Diagram valid?}
25
+ C1 -->|Yes| C2[Proceed]
26
+ C1 -->|No| Blueprint
27
+ end
28
+
29
+ CheckDiagram --> Write[Write validated .spec.md to path]
30
+ Write --> Init[Set SPEC_VERSION to v1.0.0-draft]
31
+ Init --> Audit[Append audit entry: 'Created via md-new' with timestamp]
32
+ Audit --> Review([Pause for user review])
44
33
  ```
package/.agents/templates/spec-template.md CHANGED
@@ -3,20 +3,11 @@
3
3
  # {{Feature Title}} — Specification
4
4
 
5
5
  > ⚠️ **This is a freshly generated MDDD spec template.**
6
- > Replace every `{{placeholder}}`, remove this banner, and refine the diagram + matrix
7
- > with the real business context before marking the spec as `stable`.
6
+ > 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.
8
7
 
9
8
  ---
10
9
 
11
- ## 1. Context
12
-
13
- Describe **what** this spec governs and **why** it exists.
14
-
15
- - **Related specs:** {{parent_domain_spec, sibling_features}}
16
-
17
- ---
18
-
19
- ## 2. Behavioral Flow (Mermaid)
10
+ ## 1. Behavioral Flow (Mermaid)
20
11
 
21
12
  > Pick the diagram type that best fits the topology using mermaid-diagrams skill.
22
13
 
@@ -40,44 +31,35 @@ Every node MUST correspond to a concrete state, action, or decision found in the
40
31
 
41
32
  ---
42
33
 
43
- ## 3. Decision Matrix
34
+ ## 2. Decision Matrix
44
35
 
45
36
  The matrix below is the **deterministic truth table** that resolves the flow above.
46
- Each row maps a combination of **Primitive Factors** → a `Proposed Action` → a `Decision` (`✅ ALLOW` / `❌ DENY`) → an optional `Transition State`.
37
+ Each row maps a combination of **Primitive Factors** → a `Action` → `States/Validations(✅|❌)` → `Result`.
47
38
 
48
- ### 3.1 Primitive Factors
39
+ **Resolution rules** (per MDDD protocol):
49
40
 
50
- | Factor | Type | Allowed Values | Default |
51
- | :--- | :--- | :--- | :--- |
52
- | `{{Factor 1 (e.g. Active Tenant?)}}` | Binary | `✅ YES` / `❌ NO` | — |
53
- | `{{Factor 2 (e.g. Active Billing Tier?)}}` | Categorical | `FREE`, `PRO`, `ENTERPRISE` | — |
54
- | `{{Factor N}}` | Binary / Categorical | … | — |
41
+ 1. ALL columns must match a system state.
42
+ 2. If no row fully matches → `HaltWithConflict`.
43
+ 3. If multiple rows match → `HaltWithConflict`.
55
44
 
56
- > Use `-` (dash) as a wildcard when a column does not affect the decision.
57
-
58
- ### 3.2 Resolution Table
45
+ ---
59
46
 
60
- | {{Factor 1}} | {{Factor 2}} | … | Proposed Action | Decision | Transition State |
61
- | :---: | :---: | :---: | :--- | :---: | :--- |
62
- | ❌ NO | - | - | `{{ACTION_NAME}}` | ❌ DENY | - |
63
- | ✅ YES | - | - | `{{ACTION_NAME}}` | ✅ ALLOW | `{{NEW_STATE}}` |
47
+ ## 3. Tasks
64
48
 
65
- **Resolution rules** (per MDDD protocol, section 3.3):
49
+ Atomic, executable checklist. Each item MUST be traceable
50
+ back to a node in the Behavioral Flow or a row in the Decision Matrix.
66
51
 
67
- 1. ALL columns must match the current system state.
68
- 2. If no row fully matches → `HaltWithConflict` (section 5).
69
- 3. If multiple rows match → `HaltWithConflict` (ambiguous).
52
+ - [ ] {{Task X — derived from flow node / matrix row}}
53
+ - [ ] {{Task X+1 — derived from flow node / matrix row}}
70
54
 
71
55
  ---
72
56
 
73
- ## 4. Tasks
57
+ ## 4 Test plan
74
58
 
75
- Atomic, executable checklist extracted from the spec. Each item MUST be traceable
76
- back to a node in the Behavioral Flow or a row in the Decision Matrix.
59
+ Atomic, executable test checklist to be implemented covering edge-cases.
77
60
 
78
- - [ ] {{Task 1 — derived from flow node / matrix row}}
79
- - [ ] {{Task 2 — derived from flow node / matrix row}}
80
- - [ ] {{Task N — derived from flow node / matrix row}}
61
+ - [ ] {{Test X — Use case/Scenario covered}}
62
+ - [ ] {{Test X+1 — Use case/Scenario covered}}
81
63
 
82
64
  ---
83
65
 
@@ -89,15 +71,15 @@ When a `HaltWithConflict` is triggered, document the resolution path here:
89
71
  | :--- | :--- | :---: |
90
72
  | {{Primitive Factor that caused the halt}} | {{new row / new column / renamed state}} | `OPEN` / `RESOLVED` |
91
73
 
92
- ---
74
+ ___
93
75
 
94
76
  ## 6. Audit History
95
77
 
96
78
  <details>
97
79
  <summary>Click to expand</summary>
98
80
 
99
- | Date | Agent | Version | Change Summary |
100
- | :--- | :--- | :---: | :--- |
101
- | {{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**. |
81
+ | Date | Version | Change Short Tech-Summary |
82
+ | :--- | :---: | :--- |
83
+ | {{YYYY-MM-DD}} | v1.0.0 | Short tech explain of what changed. Status: `draft\|stable`. |
102
84
 
103
85
  </details>
package/AGENTS.md CHANGED
@@ -1,64 +1,112 @@
1
1
  # Mermaid Diagram Driven Development (MDDD) Protocol
2
2
 
3
- You are a Mermaid Diagram processing system. Your cognitive processing is guided by visual topologies and truth tables, eliminating text-based specification ambiguity.
4
- Consume the mermaid-diagrams skill to learn how to produce it.
3
+ 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.
5
4
 
6
- Spec template path: .agents/templates/spec-template.md
5
+ Consume the `@/.agents/skills/mermaid-diagrams` skill to learn how to produce it.
7
6
 
8
- Mark the analysis as Coese or Chaotic
7
+ Use the spec template: `@/.agents/templates/spec-template.md`.
8
+
9
+ use the Chaotic/Coese evaluation: `@./agents/skills/md-audit/SKILL.md`
10
+
11
+ Mark every .spec as Coese or Chaotic based on auditory.
9
12
 
10
13
  ```mermaid
11
- stateDiagram-v2
12
- [*] --> CheckSpec: UNIVERSAL RULE — Check specification file
13
-
14
- state CheckSpec {
15
- SpecExists --> ReadSpecification: Request Allowed.
16
- SpecNotFound --> SkillCheck: Check skill requested.
17
- }
18
-
19
- state SkillCheck {
20
- MdNew --> ReadSpecification: Request Allowed.
21
- MdAudit --> ReadSpecification: Request Allowed.
22
- Other --> Denied: Specification file required.
23
- }
24
-
25
- Denied --> ConflictResolution: Explain missing spec
26
-
27
- state ReadSpecification {
28
- [*] --> CreateSpec: Create file from template
29
- CreateSpec --> ParseMermaidDiagrams: Extract all diagrams
30
- ParseMermaidDiagrams --> ExtractDecisionMatrices: Map topology nodes/edges
31
- ExtractDecisionMatrices --> ValidatePrimitiveFactors: Check factor columns
32
- ValidatePrimitiveFactors --> [*]: Spec loaded into context
33
- }
34
-
35
- ReadSpecification --> CheckDecisionMatrix: Evaluate Primitive Factors
36
- CheckDecisionMatrix --> HaltWithConflict: Constraint Violation / Feature Creep
37
- CheckDecisionMatrix --> ExecuteAction: Strict Match Confirmed
38
- HaltWithConflict --> ConflictResolution: Auto-detect conflict source
39
-
40
- state ConflictResolution {
41
- ExplainConflict --> LogConflict: Document in Audit History
42
- LogConflict --> ProposeAlternatives: Suggest decision matrix changes
43
- ProposeAlternatives --> UserDecision: Await human input
44
- UserDecision --> CheckDecisionMatrix: Matrix updated
45
- UserDecision --> HaltProcess: User cancels
46
- }
47
-
48
- HaltProcess --> UpdateDetailsFooter: Record aborted attempt
49
- ExecuteAction --> MutateState: Apply File/Code Changes
50
- MutateState --> UpdateVersionHeader: Apply Semantic Version Rules (MAJOR.MINOR.PATCH)
51
- UpdateVersionHeader --> UpdateDetailsFooter: Append Audit History entry
52
- UpdateDetailsFooter --> [*]
14
+ graph TD
15
+ Start((Start)) --> CheckSpec{Spec exists?}
16
+
17
+ CheckSpec -->|Yes| ExistingSpec
18
+ CheckSpec -->|No| SkillCheck{Check requested skill}
19
+
20
+ SkillCheck -->|md-new| NewSpec[New Specification]
21
+ SkillCheck -->|md-audit| AuditCode[Audit Legacy Code]
22
+ SkillCheck -->|other skill| DENIED[[DENIED]]
23
+ SkillCheck -->|unknown| DENIED
24
+
25
+ subgraph NewSpec[New Specification]
26
+ direction TB
27
+ NS1[Fill spec-template] --> NS2[Read user request]
28
+ NS2 --> NS3[Write specification]
29
+ end
30
+
31
+ subgraph AuditCode[Audit Legacy Code]
32
+ direction TB
33
+ A1[Consume md-audit SKILL.md] --> A2[Read legacy code file]
34
+ A2 --> A3[Load related files]
35
+ A3 --> A4[Deep code analysis]
36
+ A4 --> A5{Chaotic or Coese?}
37
+ A5 -->|Coese — high quality| A6[Write spec from template]
38
+ A5 -->|Chaotic — low quality| A7[Draft proposal spec]
39
+ A6 --> A8[Enter SpecMod]
40
+ A7 --> A8
41
+ end
42
+
43
+ subgraph SpecMod[Spec Modification]
44
+ direction TB
45
+ S1[Plan the edit] --> S2[Apply changes to spec]
46
+ S2 --> S3[Extract all mermaid diagrams]
47
+ S3 --> S4[Map topology → decision matrix]
48
+ S4 --> S5[Validate primitive factors]
49
+ S5 --> S6[Code review]
50
+ end
51
+
52
+ subgraph ExistingSpec[Existing Spec Flow]
53
+ direction TB
54
+ E1[Read skill content] --> E2{Which skill?}
55
+ E2 -->|md-impl| MdImpl
56
+ E2 -->|md-edit| MdEdit
57
+
58
+ subgraph MdImpl[Implementation]
59
+ direction TB
60
+ I1[Read spec status] --> I2{Draft or Stable?}
61
+ I2 -->|Draft| I3[Implement code]
62
+ I3 --> I4[Implement tests]
63
+ I4 --> I5[Run tests]
64
+ I5 --> I6[Code review]
65
+ I2 -->|Stable| ConflictTrigger{Halt — spec is stable}
66
+ end
67
+
68
+ subgraph MdEdit[Edit Spec]
69
+ direction TB
70
+ Ed1[Read spec content] --> Ed2[Read user request]
71
+ Ed2 --> Ed3[Enter SpecMod]
72
+ end
73
+
74
+ MdImpl --> ValidateChanges[Validate changes]
75
+ MdEdit --> ValidateChanges
76
+ ValidateChanges --> UpdateSpec[Update spec status draft/stable]
77
+ end
78
+
79
+ NewSpec --> SpecMod
80
+ AuditCode --> SpecMod
81
+ ExistingSpec -.-> SpecMod
82
+ ConflictTrigger --> ConflictRes
83
+
84
+ subgraph ConflictRes[Conflict Resolution]
85
+ direction TB
86
+ C1[Explain conflict to user] --> C2[Propose alternatives]
87
+ C2 --> C3{Await human decision}
88
+ C3 -->|Accept proposal| C4[Update decision matrix]
89
+ C3 -->|Cancel| Cancelled([Cancelled])
90
+ end
91
+
92
+ NS3 --> Conclude
93
+ A8 --> Conclude
94
+ UpdateSpec --> Conclude
95
+ C4 --> Conclude
96
+
97
+ subgraph Conclude[Finalize]
98
+ direction TB
99
+ Co1[Validate with npx md validate] --> Co2[Check parent/child consistency]
100
+ end
101
+
102
+ Conclude --> End([End])
53
103
  ```
54
104
 
55
- ### 2 Reverse Consistency (Parent → Child)
105
+ ## 2. Reverse Consistency
56
106
 
57
- When a parent domain spec is modified, the following MUST be verified:
58
-
59
- 2.1. **Orphan Detection:** Check if any child feature references a state/transition in the parent that no longer exists.
60
- 2.2. **Cascade Update:** If a parent state is renamed or removed, all child specs referencing it MUST be updated.
61
- 2.3. **Version Bump:** Parent changes increment MINOR version. Child specs affected by the change increment PATCH version.
107
+ ### 2.1. **Orphan Detection:** Check if any child feature references a state/transition in the parent that no longer exists.
108
+ ### 2.2. **Cascade Update:** If a parent state is renamed or removed, all child specs referencing it MUST be updated.
109
+ ### 2.3. **Version Bump:** Parent changes increment MINOR version. Child specs affected by the change increment PATCH version.
62
110
 
63
111
  ## 3. Decision Matrix & Primitive Factors
64
112
 
@@ -68,13 +116,13 @@ A **Decision Matrix** is a Markdown truth table that maps combinations of **Prim
68
116
 
69
117
  ### 3.2 Primitive Factors
70
118
 
71
- **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`.
119
+ **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`.
72
120
 
73
121
  | Factor Type | Example | Allowed Values |
74
122
  | --- | --- | --- |
75
- | Binary | `Active Tenant?` | `✅ YES` / `❌ NO` |
123
+ | Binary | `Active Tenant?` | `✅`, `❌` |
76
124
  | Categorical | `Active Billing Tier?` | `FREE`, `PRO`, `ENTERPRISE` |
77
- | Negated Binary | `Global Kill Switch Active?` | `✅ YES` (blocked) / `❌ NO` (normal) |
125
+ | Negated Binary | `Global Kill Switch Active?` | `✅`, `❌` |
78
126
 
79
127
  ### 3.3 Matrix Resolution Rule
80
128
 
@@ -88,9 +136,9 @@ For each row:
88
136
 
89
137
  | Active Tenant? | Premium App? | Active Billing Tier? | User Has Role Admin? | App Whitelisted? | Global Kill Switch? | Proposed Action | Decision | Transition State |
90
138
  | --- | --- | --- | --- | --- | --- | --- | --- | --- |
91
- | ❌ NO | - | - | - | - | - | `BOOT_APP` | ❌ DENY | - |
92
- | ✅ YES | ✅ YES | **ENTERPRISE** | ✅ YES | ✅ YES | ❌ NO | `INSTALL_APP` | ✅ ALLOW | `INSTALLED` |
93
- | ✅ YES | - | - | - | - | ✅ YES | `BOOT_APP` | ❌ DENY | `MUTED_ISOLATION` |
139
+ | ❌ | - | - | - | - | - | `BOOT_APP` | ❌ | - |
140
+ | ✅ | ✅ | **ENTERPRISE** | ✅ | ✅ | ❌ | `INSTALL_APP` | ✅ | `INSTALLED` |
141
+ | ✅ | - | - | - | - | ✅ | `BOOT_APP` | ❌ | `MUTED_ISOLATION` |
94
142
 
95
143
  > `-` = wildcard / any value matches.
96
144
 
@@ -112,10 +160,10 @@ Each change MUST append a row to the **Change History** table at the bottom of t
112
160
 
113
161
  ```
114
162
  ## Change History
115
- | Version | Date | Author | Change Description | Change Type |
116
- | --- | --- | --- | --- | --- |
117
- | 1.1.0 | 2025-06-01 | AI | Added refund retry logic state | MINOR |
118
- | 1.0.0 | 2025-05-15 | AI | Initial spec creation | MAJOR |
163
+ | Version | Date | Change Description |
164
+ | --- | --- | --- |
165
+ | 1.1.0 | 2025-06-01 | Added refund retry logic state
166
+ | 1.0.0 | 2025-05-15 | Initial spec creation
119
167
  ```
120
168
 
121
169
  ## 5. Conflict Resolution Protocol
@@ -141,31 +189,4 @@ graph TD
141
189
  D --> G[Human Review Required]
142
190
  G --> H[Update Child Spec]
143
191
  H --> F
144
- F --> I[Done — Log in Audit History]
145
- ```
146
-
147
- ## UNIVERSAL RULE
148
-
149
- The UNIVERSAL RULE is now integrated into the main processing diagram at the top. Its essence:
150
-
151
- **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.
152
-
153
- Diagrams: Always use "npx md validate <path/to/diagram.md>" to validate diagram syntax (Mandatory)
154
-
155
- ```mermaid
156
- %% @spec-version v2.0.0
157
- %% @protocol-version 1.0.0
158
- stateDiagram-v2
159
- [*] --> CheckSpec: Before any action — verify spec exists
160
-
161
- state CheckSpec {
162
- SpecExists --> Allowed: Proceed with requested skill.
163
- SpecNotFound --> Denied: Only md-new / md-audit allowed.
164
- }
165
-
166
- Denied --> [*]: Halt — "No .spec.md file found. Use md-new or md-audit."
167
- Allowed --> Action: Execute requested skill.
168
- Action --> Verify: Validate output.
169
- Verify --> [*]: Success.
170
- Verify --> Action: Retry if criteria not met.
171
- ```
192
+ F --> I[Done — Log in Audit History]
package/bin/cli.js CHANGED
@@ -21,7 +21,7 @@ const program = new Command();
21
21
  program
22
22
  .name('md')
23
23
  .description('Manager for co-located specifications for Mermaid Diagram Driven Development (MDDD)')
24
- .version('7.0.0');
24
+ .version('7.1.0');
25
25
 
26
26
  // ==========================================
27
27
  // COMMAND: md init
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mddd-cli",
3
- "version": "7.0.0",
3
+ "version": "7.1.0",
4
4
  "description": "Official CLI for modular, co-located, and versioned Mermaid Diagram Driven Development (MDDD).",
5
5
  "type": "module",
6
6
  "exports": "./bin/cli.js",
package/readme.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Mermaid Diagram Driven Development (MDDD) CLI 🚀
2
2
 
3
- ![npm](https://img.shields.io/npm/v/mddd-cli)
4
- ![npm](https://img.shields.io/npm/l/mddd-cli)
5
- ![Node](https://img.shields.io/node/v/mddd-cli)
3
+ ![npm](https://img.shields.io/npm/v/mddd-cli?style=flat-square&logo=npm&color=CB3837)
4
+ ![npm](https://img.shields.io/npm/l/mddd-cli?style=flat-square)
5
+ ![Node](https://img.shields.io/node/v/mddd-cli?style=flat-square&logo=node.js&color=339933)
6
6
 
7
7
  ---
8
8
 
@@ -184,6 +184,33 @@ After running `md init`, your AI will understand these shortcuts when you type t
184
184
  | `md-edit` | Requests changes to an existing `.spec.md` file (increments semantic version). |
185
185
  | `md-audit` | Analyzes legacy code and proposes visual refactoring (Mermaid). |
186
186
  | `md-impl` | Generates code and tests strictly based on the `.spec.md` layout, managing version history. |
187
+ | `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. |
188
+
189
+ ---
190
+
191
+ ## 🗺️ Architecture Context Map
192
+
193
+ The `mddd-context-map` skill teaches the AI agent to produce a **product architecture diagram** that visualizes your system at **multiple levels**:
194
+
195
+ - **Macro areas (domains)** — each MACRO spec represents a high-level domain or business capability.
196
+ - **Micro components/services** — MICRO specs are the building blocks inside each domain.
197
+ - **Data flows** — connections between users, UI, backend, serverless functions, and external infrastructure.
198
+
199
+ The output is a stylized **`flowchart LR`** that combines domain grouping with internal components and external integrations, using `classDef` styling to differentiate node types:
200
+
201
+ | Node Class | Purpose | Visual |
202
+ | :--- | :--- | :--- |
203
+ | `userNode` | People, personas, roles | Warm yellow |
204
+ | `systemNode` | Internal services/components | Professional blue |
205
+ | `externalNode` | Third-party APIs, partner systems | Stand-out red-orange |
206
+ | `infraNode` | Databases, queues, caches | Subdued italic gray |
207
+
208
+ ### How to use
209
+
210
+ 1. Initialize your project with `md init` (this copies the architecture template to `.agents/templates/`).
211
+ 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.
212
+ 3. The output is saved to `ARCHITECTURE.spec.md` at the project root.
213
+ 4. Every diagram is validated with `npx md validate` before being written.
187
214
 
188
215
  ---
189
216
 
@@ -208,8 +235,9 @@ src/
208
235
  ## 📦 CLI Commands
209
236
 
210
237
  | Command | Description |
211
- | --- | --- |
238
+ | :--- | :--- |
212
239
  | `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. |
240
+ | `md status` | Generates a beautiful MDDD coverage report with metrics from all `.spec.md` files. Shows specs classification (Cohesive/Chaotic), task progress, version changes, and impact metrics. |
213
241
 
214
242
  ### Project Architecture
215
243
 
@@ -222,10 +250,25 @@ bin/
222
250
 
223
251
  src/
224
252
  ├── commands/ # Command layer
225
- │ └── init.js
226
- └── services/ # Shared services with DI
227
- ├── FileSystemService.js
228
- └── InitService.js
253
+ │ ├── init.js # Init command
254
+ │ ├── listSpecs.js # List specs command
255
+ │ ├── status.js # Status command
256
+ │ ├── status.spec.md # Status spec
257
+ │ └── validator.js # Validator utility
258
+ ├── services/ # Shared services with DI
259
+ │ ├── FileSystemService.js
260
+ │ ├── FileSystemService.spec.md
261
+ │ ├── InitService.js
262
+ │ ├── InitService.spec.md
263
+ │ └── SpecFinderService.js
264
+ └── workflows/
265
+ └── mddd-preview.yml.js # GitHub Actions workflow
266
+
267
+ tests/
268
+ ├── commands/
269
+ │ ├── init.spec.js
270
+ │ ├── listSpecs.spec.js
271
+ │ └── status.spec.js
229
272
  ```
230
273
 
231
274
  ---
@@ -248,7 +291,7 @@ If you encounter any issues, open a [GitHub Issue](https://github.com/JulioCRFil
248
291
 
249
292
  ## 📄 License
250
293
 
251
- Distributed under the MIT license. See the [LICENSE](https://www.google.com/search?q=LICENSE) file for more information.
294
+ Distributed under the MIT license. See the [LICENSE](./LICENSE) file for more information.
252
295
 
253
296
  ---
254
297
  <a id="portuguese"></a>
@@ -424,6 +467,33 @@ Após rodar o `md init`, a sua IA passará a entender estes atalhos quando você
424
467
  | `md-edit` | Solicita alterações em um arquivo `.spec.md` existente (incrementa a versão semântica). |
425
468
  | `md-audit` | Analisa código legado e propõe refatoração visual (Mermaid). |
426
469
  | `md-impl` | Gera código e testes baseando-se estritamente na estrutura do `.spec.md`, gerenciando o histórico de versões. |
470
+ | `mddd-context-map` | Gera um diagrama de arquitetura do produto em múltiplos níveis (flowchart LR) a partir de todos os arquivos `.spec.md`. Classifica specs como MACRO/MICRO, mapeia fluxos de dados e produz um `ARCHITECTURE.spec.md` com nós estilizados e arestas rotuladas. |
471
+
472
+ ---
473
+
474
+ ## 🗺️ Mapa de Contexto da Arquitetura
475
+
476
+ A skill `mddd-context-map` ensina o agente de IA a produzir um **diagrama de arquitetura do produto** que visualiza o sistema em **múltiplos níveis**:
477
+
478
+ - **Áreas Macro (domínios)** — cada spec MACRO representa um domínio ou capacidade de negócio de alto nível.
479
+ - **Micro componentes/serviços** — specs MICRO são os blocos construtivos dentro de cada domínio.
480
+ - **Fluxos de dados** — conexões entre usuários, UI, backend, funções serverless e infraestrutura externa.
481
+
482
+ O output é um **`flowchart LR`** estilizado que combina agrupamento por domínio com componentes internos e integrações externas, usando `classDef` para diferenciar os tipos de nós:
483
+
484
+ | Classe de Nó | Propósito | Visual |
485
+ | :--- | :--- | :--- |
486
+ | `userNode` | Pessoas, personas, perfis | Amarelo quente |
487
+ | `systemNode` | Serviços/componentes internos | Azul profissional |
488
+ | `externalNode` | APIs de terceiros, sistemas parceiros | Vermelho-alaranjado |
489
+ | `infraNode` | Bancos de dados, filas, caches | Cinza itálico sutil |
490
+
491
+ ### Como usar
492
+
493
+ 1. Inicialize seu projeto com `md init` (isso copia o template de arquitetura para `.agents/templates/`).
494
+ 2. Peça à IA para gerar o mapa de contexto — ela escaneará todos os arquivos `.spec.md`, classificará como MACRO/MICRO e comporá o diagrama.
495
+ 3. O output é salvo em `ARCHITECTURE.spec.md` na raiz do projeto.
496
+ 4. Cada diagrama é validado com `npx md validate` antes de ser escrito.
427
497
 
428
498
  ---
429
499
 
@@ -448,8 +518,9 @@ src/
448
518
  ## 📦 Comandos da CLI
449
519
 
450
520
  | Comando | Descrição |
451
- | --- | --- |
521
+ | :--- | :--- |
452
522
  | `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. |
523
+ | `md status` | Gera um relatório bonito de cobertura MDDD com métricas de todos os arquivos `.spec.md`. Mostra classificação dos specs (Coeso/Caótico), progresso de tarefas, mudanças de versão e métricas de impacto. |
453
524
 
454
525
  ### Arquitetura do Projeto
455
526
 
@@ -462,10 +533,25 @@ bin/
462
533
 
463
534
  src/
464
535
  ├── commands/ # Camada de comandos
465
- │ └── init.js
466
- └── services/ # Serviços compartilhados com DI
467
- ├── FileSystemService.js
468
- └── InitService.js
536
+ │ ├── init.js # Comando init
537
+ │ ├── listSpecs.js # Comando listSpecs
538
+ │ ├── status.js # Comando status
539
+ │ ├── status.spec.md # Spec do status
540
+ │ └── validator.js # Utilitário de validação
541
+ ├── services/ # Serviços compartilhados com DI
542
+ │ ├── FileSystemService.js
543
+ │ ├── FileSystemService.spec.md
544
+ │ ├── InitService.js
545
+ │ ├── InitService.spec.md
546
+ │ └── SpecFinderService.js
547
+ └── workflows/
548
+ └── mddd-preview.yml.js # Workflow do GitHub Actions
549
+
550
+ tests/
551
+ ├── commands/
552
+ │ ├── init.spec.js
553
+ │ ├── listSpecs.spec.js
554
+ │ └── status.spec.js
469
555
  ```
470
556
 
471
557
  ---
@@ -488,4 +574,4 @@ Se encontrar qualquer problema, abra uma [Issue no GitHub](https://github.com/Ju
488
574
 
489
575
  ## 📄 Licença
490
576
 
491
- Distribuído sob a licença MIT. Veja o arquivo [LICENSE](https://www.google.com/search?q=LICENSE) para mais informações.
577
+ Distribuído sob a licença MIT. Veja o arquivo [LICENSE](./LICENSE) para mais informações.