Skip to content

Document workflow with Mermaid charts (flowchart, sequence diagram) #439

New issue
New issue
Open
Open
Document workflow with Mermaid charts (flowchart, sequence diagram)#439
@s-celles

Description

@s-celles
s-celles
opened on Jan 4, 2026

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions