# pimzino/claude-code-spec-workflow architecture

> Architecture diagram of the GitHub repository pimzino/claude-code-spec-workflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pimzino/claude-code-spec-workflow
- Repository: https://github.com/pimzino/claude-code-spec-workflow

## Overview

##### Project type and purpose
- This is an open-source TypeScript‐based CLI library and dashboard tool called **Claude Code Spec Workflow**.
- It provides automated workflows for feature specification and bug fixing via slash commands, a pluggable agent system, and a real-time web dashboard.

##### File structure
- Top‐level files: configuration (tsconfig.json, eslint, jest), scripts/, package.json, README, LICENSE.
- src/cli.ts & index.ts: CLI entrypoints that wire up commands.
- src/dashboard/: a lightweight HTTP/WebSocket server (server.ts, multi-server.ts) plus public/ (HTML + JS UI).
- src/markdown/: all Markdown templates and command/agent definitions.
- src/* utility modules: get-content.ts, get-tasks.ts, git.ts, steering.ts, task-generator.ts, etc.
- Tests under tests/ mirror parser, dashboard, utils, steering, task-generator, etc.

##### Key insights from README
- **Core components**: CLI, orchestrator, 16 AI agents (optional), Markdown templates, real-time dashboard.
- **Workflows**: spec workflow (requirements→design→tasks→execution) and bug-fix workflow (report→analyze→fix→verify).
- **External dependencies**: Claude Code API, file system (.claude folder), Git integration, WebSocket for dashboard updates.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLIMain["CLI Entrypoint (src/cli.ts)"]:::core
        CLIDashboard["Dashboard CLI Entrypoint (src/dashboard/cli.ts)"]:::core
    end

    %% Workflow Orchestrator
    subgraph "Workflow Orchestrator"
        OrchestratorIndex["index.ts"]:::core
        GetTasks["get-tasks.ts"]:::core
        GetContent["get-content.ts"]:::core
        Steering["steering.ts"]:::core
        Update["update.ts"]:::core
        TaskGen["task-generator.ts"]:::core
        Setup["setup.ts"]:::core
        TemplatesUtil["templates.ts"]:::core
        UsingAgents["using-agents.ts"]:::core
        Utils["utils.ts"]:::core
    end

    %% Agent Plugins
    AgentPlugins["Agent Plugins (src/markdown/agents/)"]:::plugin

    %% Command Definitions
    Commands["Command Definitions (src/markdown/commands/)"]:::plugin

    %% Markdown Templates & Artifacts
    Templates["Markdown Templates (src/markdown/templates/)"]:::persistence

    %% File System
    FSDir[".claude Folder"]:::persistence

    %% Git Integration
    GitInt["Git Integration (src/git.ts)"]:::external

    %% Dashboard Backend
    subgraph "Dashboard Backend"
        DBServer["server.ts"]:::dashboard
        DBMulti["multi-server.ts"]:::dashboard
        DBWatcher["watcher.ts"]:::dashboard
        DBParser["parser.ts"]:::dashboard
        DBProjDisc["project-discovery.ts"]:::dashboard
        DBLogger["logger.ts"]:::dashboard
    end

    %% Dashboard Frontend
    subgraph "Dashboard Frontend"
        FrontIndex["index.html"]:::dashboard
        FrontApp["app.js"]:::dashboard
        FrontMulti["multi.html"]:::dashboard
        FrontMultiApp["multi-app.js"]:::dashboard
        FrontShared["shared-components.js"]:::dashboard
    end

    %% Support Scripts
    SupportScript["Copy Static Script (scripts/copy-static.js)"]:::core

    %% External Services
    subgraph "External Services"
        ClaudeAPI["Claude Code API"]:::external
        GitRemote["Git Remote"]:::external
    end

    %% Connections
    CLIMain -->|invoke CLI| OrchestratorIndex
    CLIDashboard -->|invoke CLI| OrchestratorIndex

    OrchestratorIndex -->|schedules tasks| GetTasks
    OrchestratorIndex -->|reads content| GetContent
    OrchestratorIndex -->|steering logic| Steering
    OrchestratorIndex -->|updates workflow| Update
    OrchestratorIndex -->|generates tasks| TaskGen
    OrchestratorIndex -->|initial setup| Setup
    OrchestratorIndex -->|loads templates| TemplatesUtil
    OrchestratorIndex -->|manages agents| UsingAgents
    OrchestratorIndex -->|utility funcs| Utils

    OrchestratorIndex -->|invoke| AgentPlugins
    OrchestratorIndex -->|load commands| Commands
    OrchestratorIndex -->|apply templates| Templates
    OrchestratorIndex -->|persist artifacts| FSDir
    OrchestratorIndex -->|commit docs| GitInt
    OrchestratorIndex -->|emit events| DBServer

    AgentPlugins -->|call AI| ClaudeAPI
    GitInt -->|push changes| GitRemote

    DBServer -->|serve HTTP| FrontIndex
    DBServer -->|serve JS| FrontApp
    DBMulti -->|serve multi HTTP| FrontMulti
    DBMulti -->|serve multi JS| FrontMultiApp
    DBServer -->|update UI| DBWatcher
    DBWatcher -->|parse updates| DBParser
    DBParser -->|discover projects| DBProjDisc
    DBLogger -->|log events| FSDir

    SupportScript -->|copy assets| FrontIndex

    FrontIndex -->|load shared| FrontShared

    %% Click Events
    click CLIMain "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/cli.ts"
    click CLIDashboard "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/cli.ts"
    click OrchestratorIndex "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/index.ts"
    click GetTasks "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/get-tasks.ts"
    click GetContent "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/get-content.ts"
    click Steering "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/steering.ts"
    click Update "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/update.ts"
    click TaskGen "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/task-generator.ts"
    click Setup "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/setup.ts"
    click TemplatesUtil "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/templates.ts"
    click UsingAgents "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/using-agents.ts"
    click Utils "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/utils.ts"
    click AgentPlugins "https://github.com/pimzino/claude-code-spec-workflow/tree/main/src/markdown/agents/"
    click Commands "https://github.com/pimzino/claude-code-spec-workflow/tree/main/src/markdown/commands/"
    click Templates "https://github.com/pimzino/claude-code-spec-workflow/tree/main/src/markdown/templates/"
    click GitInt "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/git.ts"
    click DBServer "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/server.ts"
    click DBMulti "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/multi-server.ts"
    click DBWatcher "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/watcher.ts"
    click DBParser "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/parser.ts"
    click DBProjDisc "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/project-discovery.ts"
    click DBLogger "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/logger.ts"
    click FrontIndex "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/public/index.html"
    click FrontApp "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/public/app.js"
    click FrontMulti "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/public/multi.html"
    click FrontMultiApp "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/public/multi-app.js"
    click FrontShared "https://github.com/pimzino/claude-code-spec-workflow/blob/main/src/dashboard/public/shared-components.js"
    click SupportScript "https://github.com/pimzino/claude-code-spec-workflow/blob/main/scripts/copy-static.js"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef plugin fill:#90EE90,stroke:#333,stroke-width:1px
    classDef persistence fill:#FFA500,stroke:#333,stroke-width:1px
    classDef dashboard fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke-dasharray: 5 5,stroke-width:1px
```
