Spec-Driven Development Pipeline

flowchart LR
    subgraph L4["Layer 4: Visibility"]
        direction TB
        KB[GitLab Kanban Board]
        WH[Webhooks]
    end

    subgraph L3["Layer 3: Orchestration"]
        direction TB
        CI[GitLab CI/CD]
        TR[Triage]
        SP[Spec]
        B1[ ]
        PL[Plan]
        B2[ ]
        B3[ ]
        IM[Implement]
        SC[Security]
        TS[Test]
        CI --> TR --> SP --> B1 --> PL --> B2 --> B3 --> IM --> SC --> TS
    end

    subgraph L2["Layer 2: Methodology"]
        direction TB
        SK[Spec-Kit CLI]
        S1["/speckit.clarify"]
        S2["/speckit.specify"]
        S3["/speckit.checklist"]
        S4["/speckit.plan"]
        S5["/speckit.tasks"]
        S6["/speckit.analyze"]
        S7["/speckit.implement"]
        B4[ ]
        B5[ ]
        SK ~~~ S1 ~~~ S2 ~~~ S3 ~~~ S4 ~~~ S5 ~~~ S6 ~~~ S7 ~~~ B4 ~~~ B5
    end

    subgraph L15["Layer 1.5: Bridge"]
        direction TB
        GL[glab CLI / MCP-GitLab]
        TK[GL_TOKEN Auth]
    end

    subgraph L0["Layer 1: Execution"]
        direction TB
        CC[Claude Code CLI]
        PM[PM Agent]
        AR[Architect]
        DV[Developer]
        SE[Security]
        QA[QA Agent]
        CC --> PM & AR & DV & SE & QA
    end

    %% Connections to enforce left-to-right order
    KB --> CI
    CI -.-> SK

    %% Layer 3 to Layer 2 (horizontal arrows - aligned)
    TR -.-> S1
    SP -.-> S2
    B1 -.-> S3
    PL -.-> S4
    B2 -.-> S5
    B3 -.-> S6
    IM -.-> S7

    %% Layer 2 to Layer 1.5 to Layer 1
    B5 --> GL
    GL --> CC

    style L4 fill:#10b981,stroke:#059669
    style L3 fill:#60a5fa,stroke:#3b82f6
    style L2 fill:#f59e0b,stroke:#d97706
    style L15 fill:#e94560,stroke:#dc2626
    style L0 fill:#8b5cf6,stroke:#7c3aed
    style B1 fill:none,stroke:none
    style B2 fill:none,stroke:none
    style B3 fill:none,stroke:none
    style B4 fill:none,stroke:none
    style B5 fill:none,stroke:none
                

sequenceDiagram
    participant H as Human
    participant GL as GitLab
    participant CI as CI/CD Pipeline
    participant CC as Claude Code
    participant SK as Spec-Kit
    participant KB as Kanban Board

    H->>GL: Create Issue
    GL->>CI: Pipeline trigger (issue event)
    CI->>CC: Triage stage (complexity + clarity)

    alt Issue is VAGUE
        CC->>KB: Update status::needs-clarification
        CC->>SK: /speckit.clarify
        SK-->>CC: Clarifying questions
        CC->>GL: Post questions as comment
        Note over H,GL: Pipeline BLOCKS - awaiting human answers
        H->>GL: Answer clarifying questions
        GL->>CI: Pipeline trigger (comment event)
        CC->>GL: Consolidate answers into issue
    end

    CC->>KB: Update status::spec-ready

    CI->>CC: Specification stage
    CC->>SK: /speckit.specify
    SK-->>CC: Structured spec (WHAT + WHY)
    CC->>GL: Commit spec.md to repo

    CI->>CC: Quality gates stage
    CC->>SK: /speckit.checklist
    SK-->>CC: Domain checklists (security, UX, etc.)

    alt Checklist FAILS
        CC->>GL: Post failed items
        CC->>KB: Keep status::spec-checklist
        Note over H,GL: Loop back to clarify gaps
    end

    CC->>KB: Update status::spec-review

    Note over H,KB: HUMAN GATE: Reviews spec...

    H->>GL: Approve spec (label change)
    GL->>CI: Pipeline trigger (label event)

    CI->>CC: Planning stage
    CC->>SK: /speckit.plan
    SK-->>CC: plan.md + data-model + contracts
    CC->>GL: Commit plan artifacts

    CI->>CC: Task generation stage
    CC->>SK: /speckit.tasks
    SK-->>CC: tasks.md (granular, ordered)
    CC->>GL: Commit tasks

    CI->>CC: Consistency analysis stage
    CC->>SK: /speckit.analyze
    SK-->>CC: Cross-artifact validation

    alt Analysis FAILS
        CC->>GL: Post inconsistencies found
        Note over CI,CC: Loop back to plan or tasks
    end

    CC->>KB: Update status::ready-to-implement

    CI->>CC: Implementation stage
    CC->>SK: /speckit.implement
    SK-->>CC: Execute tasks in order
    CC->>GL: Create MR with changes
    CC->>KB: Update status::code-review

    CI->>CC: Security review
    CC->>GL: Add security findings

    CI->>CC: Testing stage
    CC->>GL: Add test results

    Note over H,KB: HUMAN GATE: Reviews MR...

    H->>GL: Merge MR
    GL->>KB: Update status::done