Document workflow with Mermaid charts (flowchart, sequence diagram)

[s-celles]

Hello,

Coming from Kiro and Github Spec Kit I felt the need to better understand how OpenSpec workflow is working.

Here is a try (similar to github/spec-kit#1377 ) with the following prompt:

Create Mermaid diagram (flowchart, sequence diagram) for https://github.com/Fission-AI/OpenSpec
Create a Markdown file with mermaid embedded

with Claude Caude Opus 4.5

OpenSpec - Mermaid Diagrams

Spec-driven development for AI coding assistants
Repository: github.com/Fission-AI/OpenSpec

---

Table of Contents

1. Main Workflow
2. Interaction Sequence
3. Folder Structure
4. Change Folder Contents
5. Spec Delta Format
6. AI Tool Integration
7. Archive Process
8. System Overview

---

1. Main Workflow

The OpenSpec workflow consists of four phases: Draft, Review, Implement, and Archive.

flowchart TD
    subgraph DRAFT["📝 1. Draft Phase"]
        A[Developer identifies feature/change] --> B[Request AI to create proposal]
        B --> C[AI scaffolds change folder]
        C --> D["Creates proposal.md, tasks.md, spec deltas"]
    end

    subgraph REVIEW["🔍 2. Review & Align Phase"]
        E[Review proposal with AI] --> F{Specs acceptable?}
        F -->|No| G[Refine specs/tasks]
        G --> E
        F -->|Yes| H[Approve plan]
    end

    subgraph IMPLEMENT["⚙️ 3. Implementation Phase"]
        I[AI implements tasks] --> J[Mark tasks complete]
        J --> K{All tasks done?}
        K -->|No| I
        K -->|Yes| L[Implementation complete]
    end

    subgraph ARCHIVE["📦 4. Archive Phase"]
        M[Archive the change] --> N[Merge spec deltas into source specs]
        N --> O[Move change folder to archive/]
        O --> P[Updated specs become new source of truth]
    end

    D --> E
    H --> I
    L --> M

    style DRAFT fill:#e1f5fe,stroke:#01579b
    style REVIEW fill:#fff3e0,stroke:#e65100
    style IMPLEMENT fill:#e8f5e9,stroke:#1b5e20
    style ARCHIVE fill:#f3e5f5,stroke:#4a148c

Loading

---

2. Interaction Sequence

This sequence diagram shows the communication flow between the Developer, AI Assistant, OpenSpec CLI, and the File System throughout the complete workflow.

sequenceDiagram
    participant Dev as 👤 Developer
    participant AI as 🤖 AI Assistant
    participant CLI as ⚙️ OpenSpec CLI
    participant FS as 📁 File System

    rect rgb(225, 245, 254)
        Note over Dev,FS: 1. Draft Phase
        Dev->>AI: Create proposal for "add profile filters"
        AI->>FS: Create openspec/changes/add-profile-filters/
        AI->>FS: Write proposal.md
        AI->>FS: Write tasks.md
        AI->>FS: Write specs/profile/spec.md (delta)
        AI-->>Dev: Change folder created ✓
    end

    rect rgb(255, 243, 224)
        Note over Dev,FS: 2. Review Phase
        Dev->>CLI: openspec list
        CLI-->>Dev: Shows active changes
        Dev->>CLI: openspec validate add-profile-filters
        CLI-->>Dev: Validation results
        Dev->>CLI: openspec show add-profile-filters
        CLI-->>Dev: Displays proposal, tasks, specs
        Dev->>AI: Add acceptance criteria for filters
        AI->>FS: Updates spec.md and tasks.md
        AI-->>Dev: Specs updated ✓
    end

    rect rgb(232, 245, 233)
        Note over Dev,FS: 3. Implementation Phase
        Dev->>AI: Implement the change
        loop For each task
            AI->>FS: Implement task
            AI->>FS: Mark task complete in tasks.md
        end
        AI-->>Dev: All tasks complete ✓
    end

    rect rgb(243, 229, 245)
        Note over Dev,FS: 4. Archive Phase
        Dev->>CLI: openspec archive add-profile-filters --yes
        CLI->>FS: Merge spec deltas into openspec/specs/
        CLI->>FS: Move change to openspec/archive/
        CLI-->>Dev: Change archived successfully ✓
    end

Loading

---

3. Folder Structure

OpenSpec organizes files into three main directories: specs/ (source of truth), changes/ (active work), and archive/ (completed changes).

flowchart TB
    subgraph ROOT["📁 Project Root"]
        subgraph OPENSPEC["📁 openspec/"]
            direction TB
            
            subgraph SPECS["📁 specs/<br/><i>Source of Truth</i>"]
                S1["📄 auth/spec.md"]
                S2["📄 profile/spec.md"]
                S3["📄 payments/spec.md"]
            end
            
            subgraph CHANGES["📁 changes/<br/><i>Active Proposals</i>"]
                C1["📁 add-2fa/"]
                C2["📁 add-profile-filters/"]
            end
            
            subgraph ARCHIVE["📁 archive/<br/><i>Completed</i>"]
                A1["📁 add-login/"]
                A2["📁 fix-session/"]
            end
            
            PM["📄 project.md"]
            AG["📄 AGENTS.md"]
        end
    end

    style SPECS fill:#c8e6c9,stroke:#2e7d32
    style CHANGES fill:#fff9c4,stroke:#f9a825
    style ARCHIVE fill:#e0e0e0,stroke:#616161

Loading

---

4. Change Folder Contents

Each change folder contains everything needed to understand and implement a feature change.

flowchart LR
    subgraph CHANGE["📁 openspec/changes/add-2fa/"]
        direction TB
        P["📄 proposal.md"]
        T["📄 tasks.md"]
        D["📄 design.md"]
        
        subgraph DELTA["📁 specs/"]
            DS1["📄 auth/spec.md"]
        end
    end

    P --> INTENT["💡 Why & What<br/><i>Intent and scope</i>"]
    T --> WORK["✅ Checklist<br/><i>Implementation tasks</i>"]
    D --> DECISIONS["🏗️ Technical<br/><i>Design decisions</i>"]
    DELTA --> ADDITIONS["📝 Delta<br/><i>ADDED/MODIFIED/REMOVED</i>"]

    style P fill:#bbdefb,stroke:#1976d2
    style T fill:#c5cae9,stroke:#303f9f
    style D fill:#d1c4e9,stroke:#512da8
    style DELTA fill:#fff9c4,stroke:#f9a825

Loading

---

5. Spec Delta Format

Deltas describe changes to specifications using ADDED, MODIFIED, and REMOVED sections.

flowchart TB
    subgraph DELTA["📄 Delta Spec Structure"]
        direction LR
        ADDED["## ADDED<br/>Requirements"]
        MODIFIED["## MODIFIED<br/>Requirements"]
        REMOVED["## REMOVED<br/>Requirements"]
    end

    subgraph FORMAT["Requirement Format"]
        direction TB
        HEADER["### Requirement: Name"]
        DESC["The system SHALL/MUST..."]
        SCENARIO["#### Scenario: Name"]
        STEPS["- WHEN condition<br/>- THEN outcome"]
    end

    ADDED --> HEADER
    MODIFIED --> HEADER
    REMOVED --> HEADER
    HEADER --> DESC
    DESC --> SCENARIO
    SCENARIO --> STEPS

    style ADDED fill:#c8e6c9,stroke:#2e7d32
    style MODIFIED fill:#fff9c4,stroke:#f9a825
    style REMOVED fill:#ffcdd2,stroke:#c62828
    style FORMAT fill:#e3f2fd,stroke:#1565c0

Loading

Example Delta

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required

---

6. AI Tool Integration

OpenSpec integrates with AI coding assistants through native slash commands or the AGENTS.md convention.

flowchart TB
    subgraph OPENSPEC["⚙️ OpenSpec"]
        INIT["openspec init"]
        UPDATE["openspec update"]
    end

    subgraph NATIVE["🔌 Native Slash Commands"]
        direction TB
        CC["Claude Code<br/><code>/openspec:proposal</code>"]
        CU["Cursor<br/><code>/openspec-proposal</code>"]
        GC["Gemini CLI<br/><code>/openspec:proposal</code>"]
        GH["GitHub Copilot<br/><code>/openspec-proposal</code>"]
        WS["Windsurf<br/><code>/openspec-proposal</code>"]
        RC["RooCode<br/><code>/openspec-proposal</code>"]
        CX["Codex<br/><code>/openspec-proposal</code>"]
    end

    subgraph AGENTSMD["📄 AGENTS.md Compatible"]
        AMP["Amp"]
        JU["Jules"]
        OT["Other Tools"]
    end

    INIT --> NATIVE
    INIT --> AGENTSMD
    UPDATE --> NATIVE
    UPDATE --> AGENTSMD

    style OPENSPEC fill:#e3f2fd,stroke:#1565c0
    style NATIVE fill:#e8f5e9,stroke:#2e7d32
    style AGENTSMD fill:#fff3e0,stroke:#ef6c00

Loading

Supported Commands

Command	Purpose
/openspec:proposal	Create a new change proposal
/openspec:apply	Implement tasks from a change
/openspec:archive	Archive completed change

---

7. Archive Process

When a change is archived, spec deltas are merged into the source specs and the change folder is preserved in the archive.

flowchart LR
    subgraph BEFORE["Before Archive"]
        direction TB
        B1["📁 changes/add-2fa/"]
        B2["└── specs/auth/spec.md<br/><i>(delta with ADDED)</i>"]
        B3["📁 specs/auth/"]
        B4["└── spec.md<br/><i>(current truth)</i>"]
    end

    CMD["⚙️ openspec archive<br/>add-2fa --yes"]

    subgraph AFTER["After Archive"]
        direction TB
        A1["📁 archive/add-2fa/"]
        A2["<i>(preserved for history)</i>"]
        A3["📁 specs/auth/"]
        A4["└── spec.md<br/><i>(merged & updated)</i>"]
    end

    B1 --> CMD
    B3 --> CMD
    CMD --> A1
    CMD --> A3

    style BEFORE fill:#fff9c4,stroke:#f9a825
    style CMD fill:#e1bee7,stroke:#7b1fa2
    style AFTER fill:#c8e6c9,stroke:#2e7d32

Loading

---

8. System Overview

Complete architecture showing the relationship between all OpenSpec components.

flowchart TB
    subgraph HUMAN["👤 Human"]
        DEV[Developer]
    end

    subgraph AI_TOOLS["🤖 AI Assistants"]
        direction LR
        CLAUDE[Claude Code]
        CURSOR[Cursor]
        COPILOT[GitHub Copilot]
        GEMINI[Gemini CLI]
        OTHER[Others...]
    end

    subgraph CLI_CMDS["⚙️ OpenSpec CLI"]
        direction TB
        INIT["init"]
        LIST["list"]
        SHOW["show"]
        VALIDATE["validate"]
        ARCHIVE["archive"]
        VIEW["view"]
    end

    subgraph FILES["📁 OpenSpec Files"]
        direction TB
        SPECS["specs/<br/><i>Source of Truth</i>"]
        CHANGES["changes/<br/><i>Active Work</i>"]
        ARCH_DIR["archive/<br/><i>History</i>"]
        PROJECT["project.md"]
        AGENTS["AGENTS.md"]
    end

    DEV <-->|"Natural language<br/>requests"| AI_TOOLS
    AI_TOOLS <-->|"Slash commands<br/>& AGENTS.md"| CLI_CMDS
    AI_TOOLS <-->|"Read/Write<br/>specs & tasks"| FILES
    CLI_CMDS <-->|"Manage<br/>files"| FILES
    DEV <-->|"CLI<br/>commands"| CLI_CMDS

    style HUMAN fill:#e3f2fd,stroke:#1565c0
    style AI_TOOLS fill:#f3e5f5,stroke:#7b1fa2
    style CLI_CMDS fill:#e8f5e9,stroke:#2e7d32
    style FILES fill:#fff3e0,stroke:#ef6c00

Loading

---

Quick Reference

CLI Commands

openspec init               # Initialize OpenSpec in a project
openspec list               # View active change folders
openspec view               # Interactive dashboard
openspec show <change>      # Display change details
openspec validate <change>  # Check spec formatting
openspec archive <change>   # Archive completed change
openspec update             # Update AI tool integrations

Workflow Summary

Draft → Review → Implement → Archive
  │        │         │          │
  │        │         │          └── Merge deltas into specs/
  │        │         └── AI implements tasks
  │        └── Refine until specs are approved
  └── AI creates proposal + tasks + spec deltas

---

Generated for OpenSpec - Spec-driven development for AI coding assistants