Document workflow with Mermaid charts (flowchart, sequence diagram) #1377
Description
Hello,
I think README.md or a separate doc should provide a workflow Mermaid diagram (flowchart)
Here is an example
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#6366f1', 'primaryTextColor': '#fff', 'primaryBorderColor': '#4f46e5', 'lineColor': '#94a3b8', 'secondaryColor': '#f1f5f9', 'tertiaryColor': '#e2e8f0'}}}%%
flowchart TD
subgraph SETUP["🚀 Setup Phase"]
A[("📦 Install Specify CLI<br/><code>uv tool install specify-cli</code>")]
B["🔧 Initialize Project<br/><code>specify init <project></code>"]
A --> B
end
subgraph FOUNDATION["📜 Foundation Phase"]
C["📋 /speckit.constitution<br/><i>Create project principles &<br/>development guidelines</i>"]
C1[("📄 constitution.md<br/><i>Governing principles</i>")]
C --> C1
end
subgraph SPECIFICATION["✨ Specification Phase"]
D["📝 /speckit.specify<br/><i>Define WHAT & WHY<br/>(not tech stack)</i>"]
D1[("📄 spec.md<br/><i>User stories &<br/>functional requirements</i>")]
D --> D1
E{"Need<br/>clarification?"}
D1 --> E
F["❓ /speckit.clarify<br/><i>Answer structured questions<br/>to reduce ambiguity</i>"]
E -->|Yes| F
F --> D1
end
subgraph PLANNING["🔨 Planning Phase"]
G["🏗️ /speckit.plan<br/><i>Define tech stack &<br/>architecture</i>"]
G1[("📄 plan.md<br/><i>Implementation plan</i>")]
G2[("📄 research.md<br/><i>Tech research</i>")]
G3[("📄 data-model.md<br/><i>Data structures</i>")]
G4[("📄 api-spec.json<br/><i>API contracts</i>")]
G --> G1
G --> G2
G --> G3
G --> G4
end
subgraph TASKING["📋 Task Breakdown Phase"]
H["📌 /speckit.tasks<br/><i>Generate actionable<br/>task list</i>"]
H1[("📄 tasks.md<br/><i>Ordered tasks with<br/>dependencies</i>")]
H --> H1
I{"Run<br/>analysis?"}
H1 --> I
J["🔍 /speckit.analyze<br/><i>Cross-artifact<br/>consistency check</i>"]
I -->|Optional| J
J --> H1
end
subgraph IMPLEMENTATION["⚡ Implementation Phase"]
K["🚀 /speckit.implement<br/><i>Execute all tasks<br/>in order</i>"]
K1[("💻 Working<br/>Application")]
K --> K1
end
subgraph VALIDATION["✅ Validation"]
L["🧪 Test & Validate"]
M{"Issues<br/>found?"}
L --> M
M -->|Yes| K
M -->|No| N["🎉 Feature Complete"]
end
%% Main Flow Connections
B --> C
C1 --> D
E -->|No| G
G4 --> H
I -->|Continue| K
K1 --> L
%% Styling
classDef setupNode fill:#10b981,stroke:#059669,color:#fff
classDef foundationNode fill:#8b5cf6,stroke:#7c3aed,color:#fff
classDef specNode fill:#3b82f6,stroke:#2563eb,color:#fff
classDef planNode fill:#f59e0b,stroke:#d97706,color:#fff
classDef taskNode fill:#ec4899,stroke:#db2777,color:#fff
classDef implNode fill:#ef4444,stroke:#dc2626,color:#fff
classDef artifactNode fill:#f1f5f9,stroke:#94a3b8,color:#334155
classDef decisionNode fill:#fef3c7,stroke:#fbbf24,color:#78350f
classDef successNode fill:#22c55e,stroke:#16a34a,color:#fff
class A,B setupNode
class C foundationNode
class D,F specNode
class G planNode
class H,J taskNode
class K implNode
class C1,D1,G1,G2,G3,G4,H1 artifactNode
class E,I,M decisionNode
class K1,L,N successNode
Deep wiki also provide this kind of document
https://deepwiki.com/github/spec-kit
An interesting chart to also add to doc could be sequence diagram
sequenceDiagram
autonumber
participant Dev as 👤 Developer
participant CLI as 🔧 Specify CLI
participant Agent as 🤖 AI Agent
participant FS as 📁 File System
participant Git as 🌿 Git
%% ===== SETUP PHASE =====
rect rgb(16, 185, 129, 0.1)
Note over Dev,Git: 🚀 SETUP PHASE
Dev->>CLI: uv tool install specify-cli
CLI-->>Dev: ✅ CLI installed
Dev->>CLI: specify init <project> --ai claude
CLI->>FS: Create project structure
CLI->>FS: Copy templates & scripts
CLI->>Git: Initialize repository
CLI-->>Dev: ✅ Project initialized
end
%% ===== FOUNDATION PHASE =====
rect rgb(139, 92, 246, 0.1)
Note over Dev,Git: 📜 FOUNDATION PHASE
Dev->>Agent: Launch AI agent in project
Dev->>Agent: /speckit.constitution<br/>Create principles for code quality,<br/>testing, UX, performance
Agent->>Agent: Generate governing principles
Agent->>FS: Write .specify/memory/constitution.md
Agent-->>Dev: ✅ Constitution created
end
%% ===== SPECIFICATION PHASE =====
rect rgb(59, 130, 246, 0.1)
Note over Dev,Git: ✨ SPECIFICATION PHASE
Dev->>Agent: /speckit.specify<br/>Define WHAT & WHY<br/>(functional requirements)
Agent->>Agent: Analyze requirements
Agent->>Agent: Generate user stories
Agent->>Git: Create feature branch (e.g., 001-feature)
Agent->>FS: Write specs/<feature>/spec.md
Agent-->>Dev: ✅ Specification created
opt Clarification Needed
Dev->>Agent: /speckit.clarify
Agent->>Dev: Ask structured questions
Dev->>Agent: Provide answers
Agent->>FS: Update spec.md with clarifications
end
opt Additional Refinement
Dev->>Agent: Free-form refinements
Agent->>FS: Update spec.md
end
Dev->>Agent: Validate review checklist
Agent->>FS: Update checklist in spec.md
Agent-->>Dev: ✅ Specification validated
end
%% ===== PLANNING PHASE =====
rect rgb(245, 158, 11, 0.1)
Note over Dev,Git: 🏗️ PLANNING PHASE
Dev->>Agent: /speckit.plan<br/>Define tech stack & architecture
Agent->>Agent: Research technologies
Agent->>Agent: Design architecture
par Generate Planning Artifacts
Agent->>FS: Write specs/<feature>/plan.md
and
Agent->>FS: Write specs/<feature>/research.md
and
Agent->>FS: Write specs/<feature>/data-model.md
and
Agent->>FS: Write specs/<feature>/contracts/api-spec.json
and
Agent->>FS: Write specs/<feature>/quickstart.md
end
Agent-->>Dev: ✅ Implementation plan created
opt Deep Research Needed
Dev->>Agent: Research specific technologies
Agent->>Agent: Web research for latest docs
Agent->>FS: Update research.md
end
Dev->>Agent: Audit & validate plan
Agent->>Agent: Cross-check for completeness
Agent->>FS: Refine plan artifacts
Agent-->>Dev: ✅ Plan validated
end
%% ===== TASK BREAKDOWN PHASE =====
rect rgb(236, 72, 153, 0.1)
Note over Dev,Git: 📋 TASK BREAKDOWN PHASE
Dev->>Agent: /speckit.tasks
Agent->>FS: Read plan.md & spec.md
Agent->>Agent: Break down into ordered tasks
Agent->>Agent: Identify dependencies
Agent->>Agent: Mark parallel tasks [P]
Agent->>FS: Write specs/<feature>/tasks.md
Agent-->>Dev: ✅ Task breakdown created
opt Consistency Analysis
Dev->>Agent: /speckit.analyze
Agent->>FS: Read all artifacts
Agent->>Agent: Cross-artifact validation
Agent->>FS: Update tasks if needed
Agent-->>Dev: ✅ Analysis complete
end
end
%% ===== IMPLEMENTATION PHASE =====
rect rgb(239, 68, 68, 0.1)
Note over Dev,Git: ⚡ IMPLEMENTATION PHASE
Dev->>Agent: /speckit.implement
Agent->>FS: Read tasks.md
Agent->>Agent: Validate prerequisites
loop For Each Task
Agent->>Agent: Execute task
Agent->>FS: Create/modify source files
Agent->>Agent: Run tests (if TDD)
Agent-->>Dev: 📊 Progress update
end
Agent->>FS: Application code complete
Agent-->>Dev: ✅ Implementation complete
end
%% ===== VALIDATION PHASE =====
rect rgb(34, 197, 94, 0.1)
Note over Dev,Git: ✅ VALIDATION PHASE
Dev->>Dev: Test application
alt Issues Found
Dev->>Agent: Report errors/issues
Agent->>FS: Fix source files
Agent-->>Dev: 🔧 Issues resolved
Dev->>Dev: Re-test application
else No Issues
Dev->>Git: Commit changes
Dev->>Git: Create Pull Request
Note over Dev,Git: 🎉 Feature Complete!
end
end