Plan mermaid diagrams feature implementation

.github/workflows/ci.yml

@@ -193,3 +193,46 @@ jobs:
           # Check for agents
           echo "Checking agents..."
           find plugin/agents -type d -mindepth 1 -maxdepth 1 | wc -l | xargs -I {} echo "Found {} agents"
+
+  diagrams:
+    name: Validate Diagram Generation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate diagrams
+        run: npm run generate-diagrams
+
+      - name: Check for uncommitted changes
+        run: |
+          echo "Checking if diagrams are up to date..."
+
+          if git diff --exit-code docs/diagrams/; then
+            echo "✅ Diagrams are up to date"
+          else
+            echo "❌ Diagram files have uncommitted changes"
+            echo "Please run 'npm run generate-diagrams' and commit the changes"
+            git diff docs/diagrams/
+            exit 1
+          fi
+
+      - name: Validate metadata file exists
+        run: |
+          if [ -f "docs/diagrams/diagram-metadata.json" ]; then
+            echo "✅ Metadata file found"
+            cat docs/diagrams/diagram-metadata.json | jq empty && echo "✅ Valid metadata JSON"
+          else
+            echo "❌ Metadata file missing"
+            exit 1
+          fi

README.md

@@ -56,6 +56,26 @@ Transform any application into a fully-specified, spec-driven project with compl
 
 **Two Paths - Choose Your Route:**
 
+<!-- DIAGRAM: workflow-start -->
+### Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> analyze
+    analyze --> reverse-engineer
+    reverse-engineer --> create-specs
+    create-specs --> gap-analysis
+    gap-analysis --> complete-spec
+    complete-spec --> implement
+    analyze --> cruise-control: auto
+    implement --> [*]
+    cruise-control --> [*]
+```
+
+*Last generated: 2025-11-17T09:10:43.225Z*
+<!-- DIAGRAM: workflow-end -->
+
+
 ### 🔀 Path A: Greenfield (Shift to New Stack)
 **Use when:** Rebuilding in a different tech stack or platform
 

docs/architecture.md

@@ -0,0 +1,32 @@
+# System Architecture
+
+
+## System Architecture
+
+<!-- DIAGRAM: architecture-start -->
+### Component Architecture
+
+```mermaid
+graph TB
+
+    subgraph "MCP Server"
+        mcp_tools[7 MCP Tools]
+        mcp_resources[Resources Layer]
+        mcp_utils[Utilities]
+    end
+
+    subgraph "Claude Code Plugin"
+        plugin_skills[7 Skills]
+        plugin_agents[2 Agents]
+    end
+
+    claude[Claude AI]
+
+    claude --> plugin_skills
+    plugin_skills --> mcp_tools
+    mcp_tools --> mcp_utils
+    mcp_utils --> mcp_resources
+```
+
+*Last generated: 2025-11-17T09:10:43.227Z*
+<!-- DIAGRAM: architecture-end -->

docs/diagrams/architecture.mmd

@@ -0,0 +1,19 @@
+graph TB
+
+    subgraph "MCP Server"
+        mcp_tools[7 MCP Tools]
+        mcp_resources[Resources Layer]
+        mcp_utils[Utilities]
+    end
+
+    subgraph "Claude Code Plugin"
+        plugin_skills[7 Skills]
+        plugin_agents[2 Agents]
+    end
+
+    claude[Claude AI]
+
+    claude --> plugin_skills
+    plugin_skills --> mcp_tools
+    mcp_tools --> mcp_utils
+    mcp_utils --> mcp_resources

docs/diagrams/class-file-utils.mmd

@@ -0,0 +1 @@
+classDiagram

docs/diagrams/class-security.mmd

@@ -0,0 +1,9 @@
+classDiagram
+    class SecurityValidator {
+        -string[] allowedBasePaths
+        +constructor(allowedBasePaths: string[]) void
+        +validateDirectory(directory: string) string
+        +validateFilePath(directory: string, filename: string) string
+        +sanitizeShellInput(input: string) string
+        +pathExists(filePath: string) Promise<boolean>
+    }

docs/diagrams/class-state-manager.mmd

@@ -0,0 +1,49 @@
+classDiagram
+    class StateManager {
+        -string stateFile
+        -string STATE_VERSION
+        +constructor(directory: string) void
+        -validateState(data: any) ValidationResult
+        -safeJsonParse(text: string) any
+        -atomicWrite(state: State) Promise<void>
+        +load() Promise<State>
+        +createInitialState(directory: string, route: Route) State
+        +initialize(directory: string, route: Route) Promise<State>
+        +update(updater: (state: State) => State) Promise<State>
+        +updateRoute(route: Route) Promise<State>
+        +completeStep(stepId: StepId, details: any) Promise<State>
+        -getNextStep(currentStep: StepId) StepId | null
+        +exists() Promise<boolean>
+    }
+
+    class AutoConfig {
+        <<interface>>
+        +'defer' | 'prompt' | 'skip' clarifications_strategy
+        +'none' | 'p0' | 'p0_p1' | 'all' implementation_scope
+        +boolean pause_between_gears
+    }
+
+    class State {
+        <<interface>>
+        +string version
+        +string created
+        +string updated
+        +Route path
+        +StepId | null currentStep
+        +StepId[] completedSteps
+        +{
+    projectName: string;
+    projectPath: string;
+    pathDescription?: string;
+  } metadata
+        +Record<string, any> stepDetails
+        +boolean auto_mode
+        +AutoConfig auto_config
+        +any config
+    }
+
+    class ValidationResult {
+        <<interface>>
+        +boolean valid
+        +string[] errors
+    }

docs/diagrams/diagram-metadata.json

@@ -0,0 +1,68 @@
+{
+  "diagrams": [
+    {
+      "name": "Workflow State Machine",
+      "type": "stateDiagram-v2",
+      "path": "/home/user/stackshift/docs/diagrams/workflow.mmd",
+      "lines": 10,
+      "nodes": 9
+    },
+    {
+      "name": "System Architecture",
+      "type": "graph",
+      "path": "/home/user/stackshift/docs/diagrams/architecture.mmd",
+      "lines": 19,
+      "nodes": 6
+    },
+    {
+      "name": "Class Diagram: security",
+      "type": "classDiagram",
+      "path": "/home/user/stackshift/docs/diagrams/class-security.mmd",
+      "lines": 10,
+      "nodes": 1
+    },
+    {
+      "name": "Class Diagram: state-manager",
+      "type": "classDiagram",
+      "path": "/home/user/stackshift/docs/diagrams/class-state-manager.mmd",
+      "lines": 50,
+      "nodes": 4
+    },
+    {
+      "name": "Class Diagram: file-utils",
+      "type": "classDiagram",
+      "path": "/home/user/stackshift/docs/diagrams/class-file-utils.mmd",
+      "lines": 1,
+      "nodes": 0
+    },
+    {
+      "name": "Sequence Diagram: analyze",
+      "type": "sequenceDiagram",
+      "path": "/home/user/stackshift/docs/diagrams/sequence-analyze.mmd",
+      "lines": 21,
+      "nodes": 16
+    },
+    {
+      "name": "Sequence Diagram: reverse-engineer",
+      "type": "sequenceDiagram",
+      "path": "/home/user/stackshift/docs/diagrams/sequence-reverse-engineer.mmd",
+      "lines": 23,
+      "nodes": 18
+    },
+    {
+      "name": "Sequence Diagram: create-specs",
+      "type": "sequenceDiagram",
+      "path": "/home/user/stackshift/docs/diagrams/sequence-create-specs.mmd",
+      "lines": 22,
+      "nodes": 16
+    }
+  ],
+  "generatedAt": "2025-11-17T09:10:43.287Z",
+  "stackshiftVersion": "1.0.0",
+  "stats": {
+    "totalDiagrams": 8,
+    "generationTimeMs": 64,
+    "sourceFilesParsed": 3,
+    "errors": 0
+  }
+}

docs/diagrams/sequence-analyze.mmd

@@ -0,0 +1,21 @@
+sequenceDiagram
+    participant Claude as Claude AI
+    participant Tool as Analyze Tool
+    participant Utils as Utilities
+    participant State as StateManager
+    participant FileUtils as FileUtils
+    participant Security as SecurityValidator
+
+    Claude -> Tool: analyze(directory)
+    activate Tool
+    Tool -> Security: validateDirectory()
+    Security -> Tool: validated path
+    Tool -> FileUtils: findFiles(patterns)
+    FileUtils -> Tool: file list
+    Tool -> Utils: detectTechStack(files)
+    Utils -> Tool: tech stack info
+    Tool -> State: update(analysisResults)
+    State -> Tool: state updated
+    deactivate Tool
+    Tool -> Claude: analysis complete
+    Note over State: State persisted to .stackshift-state.json

docs/diagrams/sequence-create-specs.mmd

@@ -0,0 +1,22 @@
+sequenceDiagram
+    participant Claude as Claude AI
+    participant Tool as Create-specs Tool
+    participant Utils as Utilities
+    participant State as StateManager
+    participant SpecWriter as Spec Writer
+    participant FileUtils as FileUtils
+
+    Claude -> Tool: createSpecs()
+    activate Tool
+    Tool -> State: load()
+    State -> Tool: business logic
+    Tool -> SpecWriter: generateSpec(businessLogic)
+    Note over SpecWriter: Convert to Spec Kit format
+    SpecWriter -> Tool: spec documents
+    Tool -> FileUtils: writeSpecs(specs)
+    FileUtils -> Tool: files written
+    Tool -> State: update(specsCreated)
+    State -> Tool: state updated
+    deactivate Tool
+    Tool -> Claude: specs created
+    Note over State: Specs written to spec-kit/

docs/diagrams/sequence-reverse-engineer.mmd

@@ -0,0 +1,23 @@
+sequenceDiagram
+    participant Claude as Claude AI
+    participant Tool as Reverse-engineer Tool
+    participant Utils as Utilities
+    participant State as StateManager
+    participant AST as AST Parser
+    participant FileUtils as FileUtils
+
+    Claude -> Tool: reverseEngineer()
+    activate Tool
+    Tool -> State: load()
+    State -> Tool: current state
+    Tool -> FileUtils: readSourceFiles()
+    FileUtils -> Tool: source code
+    Tool -> AST: parse(sourceCode)
+    AST -> Tool: AST nodes
+    Tool -> Utils: extractBusinessLogic(ast)
+    Utils -> Tool: business logic
+    Tool -> State: update(reverseEngineeringResults)
+    State -> Tool: state updated
+    deactivate Tool
+    Tool -> Claude: reverse engineering complete
+    Note over State: Business logic extracted

docs/diagrams/workflow.mmd

@@ -0,0 +1,10 @@
+stateDiagram-v2
+    [*] --> analyze
+    analyze --> reverse-engineer
+    reverse-engineer --> create-specs
+    create-specs --> gap-analysis
+    gap-analysis --> complete-spec
+    complete-spec --> implement
+    analyze --> cruise-control: auto
+    implement --> [*]
+    cruise-control --> [*]