# claude-dev-suite

**Repository Path**: changwensong/claude-dev-suite

## Basic Information

- **Project Name**: claude-dev-suite
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dev-Suite

[![Version](https://img.shields.io/badge/version-1.1.1-blue.svg)](https://github.com/claude-dev-suite/claude-dev-suite)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**A comprehensive AI-powered development toolkit that extends Claude Code with specialized agents, MCP servers, and visual orchestration.**

---

## Table of Contents

- [What is Dev-Suite?](#what-is-dev-suite)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Key Features](#key-features)
  - [Web Dashboard & Orchestrator](#web-dashboard--orchestrator)
  - [Code Generator](#code-generator)
  - [MCP Servers](#mcp-servers)
  - [Specialized Agents](#specialized-agents)
  - [Skills & Knowledge Base](#skills--knowledge-base)
    - [Knowledge Base Architecture](#knowledge-base-architecture)
  - [Project Templates](#project-templates)
  - [Custom Agents Builder](#custom-agents-builder)
  - [Recipes & Automations](#recipes--automations)
  - [Hooks Management](#hooks-management)
  - [Upgrade System](#upgrade-system)
  - [Electron Desktop App](#electron-desktop-app)
- [Installation Modes](#installation-modes)
- [Usage](#usage)
- [Configuration](#configuration)
- [MCP Servers Reference](#mcp-servers-reference)
- [Agents Reference](#agents-reference)
- [Commands Reference](#commands-reference)
- [Upgrading](#upgrading)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)

---

## What is Dev-Suite?

Dev-Suite transforms Claude Code into a full-stack development powerhouse by providing:

- **47 Specialized Agents** - Domain experts for React, Angular, Vue, Svelte, Spring Boot, ASP.NET Core, Python, FastAPI, Rust, Go, Deno, data engineering, industrial automation (DCS/PLC), testing (Jest/Vitest/Playwright/pytest/Testcontainers), security, DevOps, cloud (AWS/Azure/GCP), mobile (React Native/Flutter), messaging, and more
- **10 MCP Servers** - Extend Claude with 79 tools for documentation, databases, Docker, API testing, logs, performance profiling, security scanning, and more
- **337+ Skills** - Framework-specific knowledge bases with quick-reference guides, covering frontend, backend, databases, testing, infrastructure, messaging, industrial automation, AI integration, and more
- **Web Dashboard & Electron App** - Visual project configuration with stack detection and component selection
- **10 Project Templates** - Scaffolding for React, Next.js, Spring Boot, FastAPI, NestJS, and more
- **Task Orchestrator** - Submit complex multi-agent tasks from the GUI with real-time streaming updates
- **Custom Agents Builder** - Create and edit custom agents directly from the dashboard
- **Recipes & Automations** - Pre-built automation workflows for common development tasks
- **Hooks Management** - Configure Git hooks and Claude Code hooks from the dashboard
- **Upgrade System** - Update dev-suite components with intelligent conflict detection
- **Analytics Dashboard** - Track knowledge base usage and correlate with executed jobs
- **121+ Technologies** - On-demand documentation via Git-based knowledge base

**Key Principle**: Dev-Suite is a **source repository** that initializes your projects. It lives alongside your projects and provides centralized resources that multiple projects can reference.

---

## Prerequisites

- **Node.js v20+** - Required to build MCP servers and run the dashboard
- **npm** - Comes with Node.js
- **Git** - Required for cloning dev-suite and the knowledge base
- **Claude Code** - The Anthropic CLI tool that dev-suite extends

Optional:
- **Docker** - Required if using the docker-manager MCP server
- **Database** - Required if using the database-query MCP server (PostgreSQL, MySQL, etc.)

---

## Quick Start

### 1. Clone Dev-Suite

```bash
git clone https://github.com/claude-dev-suite/claude-dev-suite.git
cd claude-dev-suite
```

### 2. Initialize Your Project

```bash
# Launch interactive web dashboard
./init-project.sh /path/to/your-project

# Windows PowerShell
.\init-project.ps1 C:\path\to\your-project

# Quick mode (auto-detect + apply best preset)
./init-project.sh /path/to/your-project --quick
```

The script will:
1. Check Node.js installation (v20+)
2. Build MCP servers if needed (`npm install && npm run build`)
3. Launch the web dashboard at `http://localhost:3456`
4. Guide you through a 5-step wizard to configure your project

### 3. Restart Claude Code

Once initialization completes, **restart Claude Code** to load the new MCP servers and agents.

### 4. Start Using Dev-Suite

After restarting Claude Code, everything works automatically:

- **Agents** are routed based on your prompts (e.g., asking about React triggers the `react-expert`)
- **MCP tools** are available as Claude Code tools (e.g., `fetch_docs`, `execute_query`)
- **Skills** provide context-specific knowledge to agents
- **Slash commands** are available (e.g., `/docs react hooks`)

---

## Key Features

### Web Dashboard & Orchestrator

The **Web Dashboard** (launched via `init-project.sh`) provides:

#### **Visual Configuration Wizard**
- **Auto-Detection**: Scans `package.json`, `pom.xml`, `Cargo.toml`, `docker-compose.yml`, etc.
- **Stack Detection**: Identifies React, Spring Boot, PostgreSQL, Git provider, and more
- **Agent Selection**: Pre-selects agents based on detected technologies
- **MCP Selection**: Pre-selects MCP servers with environment variable configuration
- **One-Click Install**: Generates all config files (`.mcp.json`, `.dev-suite.json`, `CLAUDE.md`)

#### **Task Orchestrator** 🔥 NEW

Submit complex multi-agent tasks directly from the GUI:

```
Dashboard GUI → Submit Task → Claude Code (via MCP) → Execute → Stream Results → Dashboard
```

**Features**:
- **Real-time streaming** via WebSocket (port 3457)
- **Interactive input support** (y/n confirmations, file selections)
- **Job queue management** with status tracking
- **Live output updates** as agents execute
- **Result recap** with agent outputs, files changed, test results, build status

**How to use**:
1. Open dashboard: `./init-project.sh .` or via MCP tool `dashboard_open`
2. Navigate to **Orchestrator** tab
3. Enter task description (e.g., "Add user authentication with JWT")
4. Submit → Claude Code polls for task → Executes agents → Streams results back
5. View recap with links to changed files

#### **Analytics Dashboard** 📊 NEW

Track development activity and knowledge base usage:

- **KB Usage Statistics**: Most-accessed technologies, topics, search queries
- **Agent Performance**: Execution counts, average duration
- **Technology Trends**: Correlate KB queries with orchestrator jobs
- **Timeline View**: Hourly/daily usage patterns

Access at: `http://localhost:3456/analytics` (when dashboard is running)

#### **Code Generator** NEW

Spec-driven code generation with AI refinement:

```
Dashboard → Upload Spec → Deterministic Generation → AI Refinement → Accept/Reject
```

**Supported formats**: OpenAPI (JSON/YAML), AsyncAPI, TypeSpec, Protobuf, BPMN

**Features**:
- **9 target languages/frameworks**: TypeScript (Express, Fastify, NestJS, Koa), Java (Spring), Python (FastAPI, Flask), Go (Gin, Echo)
- **Convention-aware**: Reads `.prettierrc`, `tsconfig.json`, ESLint config to match project style
- **AI refinement**: Uses specialized agents + refinement skill for naming, imports, and code quality
- **5-step wizard**: Technology → Upload Spec → Configure → Preview → Generate
- **File browser**: Preview generated code before accepting

**How to use**:
1. Open dashboard and navigate to **Code Generator** tab
2. Select spec technology (OpenAPI, AsyncAPI, etc.)
3. Upload your spec file (drag-and-drop supported)
4. Choose target language, framework, and output directory
5. Preview → Generate → Optionally refine with Claude

---

### MCP Servers

10 specialized MCP servers extend Claude Code with powerful tools:

| Server | Tools | Description |
|--------|-------|-------------|
| **documentation** | 4 | Fetch docs for 121+ technologies via Git-based KB |
| **database-query** | 9 | SQL queries, schema inspection, migrations |
| **docker-manager** | 8 | Containers, images, Compose services |
| **api-tester** | 6 | HTTP requests, collection import, mock servers |
| **api-explorer** | 7 | OpenAPI schema explorer, endpoint details |
| **log-analyzer** | 10 | Multi-format log parsing, pattern detection |
| **performance-profiler** | 13 | CPU/memory profiling, bottleneck detection, HAR replay |
| **code-quality** | 7 | Complexity analysis, dead code, duplicates, import graph |
| **security-scanner** | 6 | Dependency audit, secrets scan, SAST |
| **dashboard-bridge** | 9 | Dashboard control, orchestrator queue |

**Total**: **79 tools** available to Claude Code

See [MCP Servers Reference](#mcp-servers-reference) for detailed documentation.

---

### Specialized Agents

Domain experts with deep knowledge in specific technologies:

**47 agents** organized by domain:

#### Core Agents
- **architect** - System design, architecture decisions, trade-offs
- **code-reviewer** - Code quality, best practices, refactoring
- **python-expert** - Python 3.10-3.14, async patterns, package management, ruff, pydantic
- **typescript-expert** - TypeScript 5, advanced types, strict configuration
- **nodejs-expert** - Event loop, async patterns, streams, worker threads
- **dashboard-refactor-expert** - Dashboard React/TypeScript refactoring
- **claude-code-extension-expert** - Claude Code extensions, skills, hooks, MCP plugins
- **documentation-expert** - JSDoc, TSDoc, API documentation generation

#### Frontend Agents
- **react-expert** - React 19, hooks, performance optimization
- **nextjs-expert** - App Router, RSC, Server Actions, caching
- **vue-expert** - Vue 3, Composition API, Pinia
- **svelte-expert** - Svelte 5, SvelteKit, stores
- **angular-expert** - Angular 17+, signals, standalone components, SSR

#### Backend Agents
- **spring-boot-expert** - Spring Boot 3, JPA, Security, REST APIs
- **nestjs-expert** - Modules, guards, pipes, Prisma integration
- **fastapi-expert** - Python async, Pydantic, SQLAlchemy
- **streamlit-expert** - Streamlit Python web apps, session state, caching, multipage
- **rust-expert** - Actix-web, Axum, Rocket, Warp
- **go-expert** - Gin, Fiber, Echo, Chi
- **deno-expert** - Fresh, Oak, TypeScript-first runtime
- **dotnet-expert** - ASP.NET Core 8+, Entity Framework Core, Blazor, SignalR

#### Data Agents
- **data-engineering-expert** - pandas, openpyxl, lxml, bulk data pipelines, Excel/XML/CSV, UTF-16 file formats

#### Industrial Automation Agents
- **dcs-analyst** - ABB Freelance PRT/DMF/CSV file analysis, tag extraction, DCS reverse engineering
- **freelance-engineer** - ABB Freelance engineering file generation, PRT/DMF bulk templating
- **automation-architect** - DCS/PLC automation pipeline design, cross-platform strategies (ABB, Siemens, Emerson, Honeywell)

#### Database Agents
- **prisma-expert** - Schema design, queries, migrations
- **sql-expert** - PostgreSQL, MySQL, query optimization
- **mongodb-expert** - Document modeling, aggregations, Spring Data MongoDB

#### Testing Agents
- **vitest-expert** - Unit testing, mocking, coverage
- **playwright-expert** - E2E testing, locators, assertions
- **spring-boot-integration-test-expert** - @SpringBootTest, Testcontainers
- **python-integration-test-expert** - pytest, testcontainers-python, pytest-django, FastAPI TestClient, factory_boy, Celery, Pact
- **smoke-test-expert** - Post-implementation verification, live HTTP testing, fix orchestration
- **qa-expert** - Test strategy, quality assurance

#### Infrastructure & Security
- **docker-expert** - Containerization, Compose, best practices
- **devops-expert** - CI/CD, GitHub Actions, deployment
- **security-expert** - OWASP, authentication, authorization

#### Quality & Open Source
- **integration-validator-expert** - API contract validation, frontend-backend alignment
- **open-source-expert** - OSS readiness, licensing, community health, compliance

#### Cloud & Mobile Agents
- **cloud-expert** - AWS, Azure, GCP, Terraform, serverless, API gateway, service mesh
- **mobile-expert** - React Native, Flutter, Expo, push notifications, payments

#### Messaging & Performance
- **messaging-expert** - Kafka, RabbitMQ, NATS, SQS, event-driven architecture
- **performance-expert** - Profiling, optimization, bottlenecks
- **log-analyst** - Log analysis, debugging, observability

See [Agents Reference](#agents-reference) for trigger keywords and skills.

---

### Skills & Knowledge Base

**337+ Skills** organized by category:

- **Frontend**: React, Vue, Angular, Svelte, Next.js, Nuxt, TailwindCSS, shadcn/ui
- **Backend**: Spring Boot, NestJS, Express, FastAPI, ASP.NET Core, Rust, Go, Deno frameworks
- **Databases**: PostgreSQL, MySQL, MongoDB, Redis
- **ORM/ODM**: Prisma, Drizzle, TypeORM, SQLAlchemy, Spring Data JPA
- **Testing**: Vitest, Jest, Playwright, Cypress, Testcontainers (Java), testcontainers-python, pytest, pytest-django, FastAPI testing, factory_boy, Celery testing, Pact (contract testing), Messaging Testing (Kafka, RabbitMQ, multi-broker)
- **State Management**: TanStack Query/Router, Redux Toolkit, Zustand, Pinia
- **API Design**: REST, GraphQL, tRPC, OpenAPI
- **Infrastructure**: Docker, Kubernetes, GitHub Actions
- **Security**: JWT, OAuth2, NextAuth, OWASP
- **Best Practices**: Git Workflow, Clean Code, Performance Optimization

#### Knowledge Base Architecture

The knowledge base provides **on-demand documentation for 121+ technologies** via a separate Git repository: [github.com/claude-dev-suite/knowledge_base](https://github.com/claude-dev-suite/knowledge_base)

**How it works**:

```
Agent needs docs → documentation MCP → Git sparse checkout → Cache (2h TTL) → Return to agent
```

1. An agent (or you) requests documentation via `fetch_docs({ technology: "react", topic: "hooks" })`
2. The **documentation MCP server** checks the local cache (`.kb-cache/`)
3. If cached and fresh (< 2 hours), it returns the cached content immediately
4. If not cached or stale, it performs a **Git sparse checkout** to fetch only the requested files from the KB repository
5. The content is cached locally for subsequent requests

**The three-layer knowledge system**:

```
┌─────────────────────────────────────────────┐
│  Layer 1: Skills (.claude/skills/)          │  Always loaded in agent context
│  Quick-reference guides, patterns, rules    │  Instant access, no network needed
├─────────────────────────────────────────────┤
│  Layer 2: Quick-Refs (skills/*/quick-ref/)  │  Detailed guides per topic
│  Each references KB docs for deep dives     │  Loaded on demand by agent
├─────────────────────────────────────────────┤
│  Layer 3: Knowledge Base (Git repo)         │  Full documentation
│  121+ technologies, fetched via MCP server  │  On-demand, cached 2 hours
└─────────────────────────────────────────────┘
```

- **Layer 1 (Skills)**: Concise rules and patterns loaded directly into the agent context. No network required.
- **Layer 2 (Quick-Refs)**: More detailed guides within skill folders. Each quick-ref links to KB docs for full documentation.
- **Layer 3 (Knowledge Base)**: Complete documentation stored in a separate Git repository, fetched on-demand by the documentation MCP server with local caching.

**Configuration**:

```bash
# Optional: use a custom KB repository (defaults to official repo)
KB_REPO_URL=https://github.com/claude-dev-suite/knowledge_base.git

# Optional: cache TTL in seconds (default: 7200 = 2 hours)
KB_CACHE_TTL=7200
```

**Adding documentation to the KB**:

1. Clone the KB repository: `git clone https://github.com/claude-dev-suite/knowledge_base.git`
2. Add markdown files under `knowledge/{technology}/{topic}.md`
3. Update the relevant category file in `mcp-servers/documentation/src/docs-index/` (e.g., `testing.ts`, `backend.ts`) to register the new technology — `docs-index.ts` is a re-export aggregator, do not edit it directly
4. Commit and push - the documentation MCP server will fetch new docs automatically on next request

---

### Project Templates

10 ready-to-use scaffolding templates for quick project setup:

| Template | Description |
|----------|-------------|
| **api-nodejs** | Node.js API starter |
| **express-api** | Express.js REST API |
| **frontend-react** | React frontend with Vite |
| **react-tanstack** | React with TanStack Query + Router |
| **nextjs-standalone** | Next.js App Router standalone |
| **fullstack-nextjs-nestjs** | Next.js + NestJS monorepo |
| **springboot-api** | Spring Boot 3 REST API |
| **springboot-react-fullstack** | Spring Boot + React fullstack |
| **python-fastapi** | FastAPI Python backend |
| **vue-nuxt** | Vue.js with Nuxt 3 |

Templates are used during the initialization wizard (Step 0) and provide pre-configured project structure, dependencies, and dev-suite integration.

---

### Custom Agents Builder

Create and manage custom agents directly from the dashboard:

- **Visual Editor** - Write agent markdown with YAML frontmatter
- **Skill Association** - Link agents to specific skills and MCP servers
- **Instant Deployment** - Agents are saved to `.claude/agents/` and immediately available
- **Edit & Delete** - Manage existing custom agents from the dashboard

---

### Recipes & Automations

Pre-built automation workflows for common development tasks:

- Browse and apply built-in automation recipes
- Recipes combine agent actions, hooks, and tool configurations
- Apply recipes to quickly set up common patterns (testing pipelines, linting, code review flows)

---

### Hooks Management

Configure Git hooks and Claude Code hooks from the dashboard:

- **Git Hooks** - Pre-commit, pre-push, commit-msg hooks
- **Claude Code Hooks** - Event-based automation (on file write, on tool call)
- **Visual Configuration** - Edit hooks through the dashboard UI
- **Template Support** - Pre-configured hook templates for common workflows

---

### Upgrade System

Keep dev-suite components up to date with intelligent upgrade management:

- **Version Detection** - Check for available updates to agents, skills, and MCP servers
- **New Component Discovery** - Proactively notifies when new agents or MCP servers are added to dev-suite after your installation, with one-click install
- **Conflict Detection** - 3-way merge to identify conflicts with local customizations
- **Upgrade History** - Track all upgrades with rollback capability
- **Selective Updates** - Choose which components to upgrade

---

### Electron Desktop App

The dashboard is available as a native desktop application:

- Cross-platform support (Windows, macOS, Linux)
- Fast startup with optimized splash screen
- Auto-updater for seamless version updates
- Native system tray integration
- Same features as the web dashboard

---

## Installation Modes

### Interactive Mode (Default)

```bash
./init-project.sh /path/to/project
```

Launches web dashboard at `http://localhost:3456` with 5-step wizard:
1. **Detection** - Auto-detect stack, databases, Git provider
2. **Agents** - Select specialized experts (pre-selected based on stack)
3. **MCP Servers** - Select tools (pre-selected based on stack)
4. **Environment** - Configure database URLs, API tokens
5. **Install** - Generate config files and copy components

### Quick Mode

```bash
./init-project.sh /path/to/project --quick
```

Auto-detects stack and applies best-matching preset with minimal prompts.

### Non-Interactive Mode

```bash
./init-project.sh /path/to/project --non-interactive --project-type fullstack
```

Uses detected values or defaults, no user input required.

---

## Usage

### Daily Development with Agents

After initialization, agents work **automatically** in Claude Code. When you ask questions or give tasks, Claude Code routes them to the appropriate agent based on keywords:

```
You: "Add a login form with validation"
→ Claude Code activates react-expert (detects React/frontend keywords)
→ Agent uses react skills + documentation MCP for best practices

You: "Why is this SQL query slow?"
→ Claude Code activates sql-expert (detects SQL/query keywords)
→ Agent uses database-query MCP to run EXPLAIN and analyze

You: "Review this PR for security issues"
→ Claude Code activates code-reviewer + security-expert
→ Agents use code-quality and security-scanner MCP tools
```

### Using MCP Tools Directly

MCP tools are available as Claude Code tools. You can ask Claude to use them:

```
"Fetch the React hooks documentation"
→ fetch_docs({ technology: "react", topic: "hooks" })

"List all Docker containers"
→ docker_ps({ all: true })

"Scan this project for vulnerabilities"
→ scan_all({ path: "." })
```

### Using the Dashboard

The dashboard can be reopened at any time for project management:

```bash
# Reopen dashboard for current project
./init-project.sh .

# Or via Claude Code MCP tool
# Ask Claude: "Open the dashboard"
→ dashboard_open()
```

**Dashboard tabs**:
- **Wizard** - Re-run the initialization wizard or use templates
- **Manage** - Add/remove agents, MCP servers, hooks, custom agents, recipes (with proactive new-component notifications)
- **Orchestrator** - Submit multi-agent tasks with real-time progress
- **Analytics** - View knowledge base usage statistics
- **Git** - Visual git operations (branches, commits, diffs, GitHub CLI auth detection with automatic login prompts)
- **Updates** - Check for and apply dev-suite updates

### Using the Orchestrator

For complex tasks that require multiple agents:

1. Open the dashboard (`./init-project.sh .`)
2. Go to the **Orchestrator** tab
3. Describe your task (e.g., "Refactor the auth module and add tests")
4. Submit the job
5. Claude Code picks up the task, executes agents, and streams results back
6. View the recap with changed files, test results, and build status

### Using Templates

To scaffold a new project from a template:

1. Open the dashboard
2. In the wizard, select **"Start from Template"** mode
3. Choose a template (e.g., `fullstack-nextjs-nestjs`)
4. Configure project-specific options
5. The template generates the project structure with dev-suite pre-configured

---

## Configuration

### Generated Files

After initialization, your project will contain:

```
your-project/
├── .mcp.json                    # MCP server configuration
├── .dev-suite.json              # Stack and component configuration
├── CLAUDE.md                    # Agent routing rules (auto-generated)
├── .claude/
│   ├── agents/                  # Selected specialized agents
│   ├── skills/                  # Related skills
│   └── commands/                # Slash commands (/init-project, /docs, etc.)
└── .mcp-servers/                # Installed MCP servers (built from dev-suite)
    ├── documentation/
    ├── database-query/
    └── ...
```

### `.dev-suite.json` Example

```json
{
  "version": "1.0.0",
  "project": {
    "name": "my-app",
    "type": "fullstack",
    "isMonorepo": false
  },
  "mcpServers": [
    "documentation",
    "database-query",
    "docker-manager",
    "api-tester",
    "dashboard-bridge"
  ],
  "stacks": {
    "frontend": {
      "framework": "react",
      "metaFramework": "nextjs",
      "styling": "tailwindcss",
      "stateManagement": "zustand+tanstack-query"
    },
    "backend": {
      "runtime": "nodejs",
      "framework": "nestjs",
      "apiStyle": "rest"
    },
    "database": {
      "type": "postgresql",
      "orm": "prisma"
    },
    "testing": {
      "unit": "vitest",
      "e2e": "playwright"
    }
  },
  "git": {
    "provider": "github",
    "repository": "https://github.com/owner/my-app",
    "tokenEnvVar": "GITHUB_TOKEN"
  },
  "agents": {
    "enabled": [
      "architect",
      "code-reviewer",
      "react-expert",
      "nextjs-expert",
      "nestjs-expert",
      "prisma-expert",
      "vitest-expert",
      "playwright-expert",
      "docker-expert"
    ]
  }
}
```

### Environment Variables

Create a `.env` file in your project root:

```bash
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/dbname

# Optional: Dashboard ports
DASHBOARD_PORT=3456
ORCHESTRATOR_WS_PORT=3457

# Optional: Documentation KB (defaults to official repo)
KB_REPO_URL=https://github.com/claude-dev-suite/knowledge_base.git
KB_CACHE_TTL=7200
```

**Security Note**: Never commit `.env` files. API tokens are only referenced by variable name in `.dev-suite.json`.

---

## MCP Servers Reference

### Documentation Server

Fetch on-demand documentation for 121+ technologies via Git-based knowledge base.

**Tools**:
- `fetch_docs({ technology, topic, source?, refresh? })` - Get documentation for a topic
- `search_docs({ query, technologies? })` - Search across all docs
- `list_topics({ technology })` - List available topics for a technology
- `list_versions({ technology })` - List supported versions

**Example**:
```typescript
fetch_docs({ technology: "spring-boot", topic: "security" })
```

---

### Database Query Server

Execute safe SQL queries and manage database schemas.

**Tools**:
- `execute_query({ sql, params?, limit?, offset? })` - Execute SELECT queries
- `list_tables()` - List all tables with row counts
- `describe_table({ table })` - Get table schema details
- `get_schema({ table?, compact? })` - Get full database schema
- `explain_query({ sql, params?, verbose? })` - Analyze query performance
- `compare_schemas({ targetDatabaseUrl, tables? })` - Compare schemas
- `find_slow_queries({ table? })` - Identify potential performance issues
- `generate_migration({ targetDatabaseUrl, migrationName? })` - Generate migration script
- `backup_restore({ operation, backupPath?, format?, tables? })` - Backup/restore database

**Requires**: `DATABASE_URL` environment variable

---

### Docker Manager Server

Manage Docker containers, images, and Compose services.

**Tools**:
- `docker_ps({ all? })` - List running containers
- `docker_container({ container, action, tail? })` - Manage container (start/stop/logs/inspect)
- `docker_compose({ action, service?, build?, detach? })` - Manage Compose services
- `docker_images({ action, image? })` - Manage images
- `docker_stats({ container? })` - View resource usage
- `docker_networks()` - List networks
- `docker_volumes()` - List volumes
- `cleanup_unused({ target?, dryRun?, force? })` - Remove unused resources

---

### API Tester Server

Test REST APIs with requests, collection import, and mock servers.

**Tools**:
- `http_request({ method, url, headers?, body?, timeout? })` - Make HTTP request
- `health_check({ url, endpoints? })` - Check API health
- `batch_request({ requests, sequential? })` - Execute multiple requests
- `import_collection({ filePath, format?, variables? })` - Import Postman or Insomnia collection (auto-detects format)
- `generate_tests({ specPath, outputFormat?, includeNegativeTests? })` - Generate test cases from OpenAPI
- `mock_server({ action, specPath?, port?, delay? })` - Start/stop mock server

---

### API Explorer Server

Explore OpenAPI/Swagger schemas and endpoints.

**Tools**:
- `list_api_endpoints()` - List configured API endpoints
- `get_api_schema({ alias?, format?, refresh? })` - Fetch OpenAPI schema
- `list_api_paths({ alias?, method?, tag?, limit? })` - List API paths
- `get_api_endpoint_details({ path, method, alias?, resolveRefs? })` - Get endpoint details
- `get_api_models({ alias?, model?, compact?, limit? })` - Get schema models/DTOs
- `search_api({ query, alias?, searchIn?, limit? })` - Search across specs
- `detect_api_frameworks({ path?, maxDepth?, includeConfidence? })` - Detect API frameworks

**Configuration**: API endpoints configured via `.dev-suite.json` or auto-detected from OpenAPI specs.

---

### Log Analyzer Server

Parse and analyze logs in multiple formats (Spring Boot, Node.js, Python, Nginx, Kubernetes, etc.).

**Tools**:
- `parse_logs({ filePath, format?, levels?, filter?, limit? })` - Parse log entries
- `find_errors({ filePath, format?, groupByException?, includeWarnings? })` - Find and group errors
- `analyze_patterns({ filePath, format?, minOccurrences? })` - Detect problematic patterns
- `aggregate_stats({ filePath, format?, groupBy? })` - Aggregate statistics
- `correlate_events({ filePaths, correlationField, targetValue? })` - Correlate events across logs
- `tail_logs({ filePath, lines?, format?, levels?, filter? })` - Get last N log lines
- `search_logs({ filePaths, query, useRegex?, caseSensitive?, limit? })` - Search across logs
- `compare_logs({ baselineFile, comparisonFile, format?, compareBy? })` - Compare log files
- `export_report({ filePath, outputFormat, format?, title? })` - Generate analysis report
- `watch_logs({ action, filePath?, format?, alertLevels?, alertPatterns? })` - Real-time monitoring

**Supported formats**: Spring Boot, Logback, Winston, Pino, Python, JSON, Nginx, Apache, Kubernetes, Syslog

---

### Performance Profiler Server

Profile CPU, memory, and endpoint performance.

**Tools**:
- `profile_script({ scriptPath, runtime?, duration?, args? })` - Profile script execution
- `profile_function({ modulePath, functionName, runtime, iterations?, args? })` - Profile specific function
- `benchmark_code({ code, runtime, iterations?, warmup? })` - Benchmark code snippet
- `analyze_memory({ scriptPath, runtime?, duration?, snapshotInterval? })` - Analyze memory usage
- `measure_startup({ scriptPath, runtime?, runs? })` - Measure startup time
- `find_bottlenecks({ scriptPath, runtime?, threshold? })` - Identify performance bottlenecks
- `attach_profiler({ pid?, port?, processName?, duration? })` - Attach to running Java process (JFR)
- `profile_endpoint({ url, method?, iterations?, concurrency?, headers?, body? })` - Profile HTTP endpoint
- `list_java_processes()` - List running Java processes
- `import_har({ harPath, flowName, filterHost?, excludeStaticAssets? })` - Import HAR file from DevTools
- `list_flows()` - List saved request flows
- `replay_flow({ flowName, baseUrl?, variables?, withProfiling?, respectTiming? })` - Replay saved flow
- `stress_test_flow({ flowName, users, duration, baseUrl?, rampUp?, variables? })` - Load test a flow

**Supported runtimes**: Node.js, Java, Python

---

### Code Quality Server

Analyze code complexity, duplicates, and dependencies.

**Tools**:
- `analyze_complexity({ path, threshold?, includeAll? })` - Analyze cyclomatic/cognitive complexity
- `find_duplicates({ path, minLines?, minTokens? })` - Detect code duplication
- `check_style({ path, fix?, rules? })` - Run linting (ESLint/Biome/Pylint/Checkstyle)
- `detect_antipatterns({ path, patterns?, thresholds? })` - Detect code smells
- `find_dead_code({ path, includeTests?, confidence? })` - Find unused code
- `analyze_import_graph({ path, excludeNodeModules?, maxDepth? })` - Analyze import graph and detect circular dependencies
- `code_metrics({ path, sortBy?, limit? })` - Calculate code metrics (LOC, SLOC, etc.)

---

### Security Scanner Server

Scan for vulnerabilities, secrets, and security issues.

**Tools**:
- `scan_dependencies({ path, packageManager?, severityThreshold? })` - Scan dependencies (npm audit, pip-audit)
- `scan_secrets({ path, tool?, scanHistory?, excludePaths? })` - Scan for hardcoded secrets (gitleaks, trufflehog)
- `scan_code({ path, rules? })` - SAST with Semgrep
- `scan_container({ target, type, severityThreshold? })` - Scan Docker images (Trivy)
- `check_tools()` - Check installed security tools
- `scan_all({ path, include?, containerTarget? })` - Run all scans in parallel

**External tools used** (auto-detected): npm audit, pip-audit, cargo audit, gitleaks, trufflehog, semgrep, trivy

---

### Dashboard Bridge Server

Control the dashboard and orchestrator from Claude Code.

**Tools**:
- `dashboard_open({ page?, projectPath? })` - Open dashboard in browser
- `dashboard_status()` - Check if dashboard is running
- `dashboard_start({ devSuiteDir? })` - Start dashboard server
- `dashboard_get_config({ projectPath })` - Read dev-suite configuration
- `dashboard_list_agents()` - List available agents
- `dashboard_detect_stack({ projectPath })` - Detect project stack
- `get_orchestrator_task({ claim? })` - Poll for orchestrator tasks from GUI
- `report_orchestrator_status({ jobId, status, message?, currentAgent?, recap?, summary? })` - Report task progress
- `list_pending_jobs()` - List pending orchestrator jobs

**Use case**: Claude Code polls `get_orchestrator_task()` to receive tasks submitted via the dashboard GUI, then reports progress back.

---

## Agents Reference

### Core Agents

| Agent | Triggers | Skills | MCP Servers |
|-------|----------|--------|-------------|
| **architect** | architecture, design, scalability, trade-offs | system-design | documentation |
| **code-reviewer** | review, code quality, refactor, best practices | clean-code | code-quality |
| **typescript-expert** | TypeScript, types, generics | typescript | documentation |
| **nodejs-expert** | Node.js, npm, modules | nodejs | documentation |
| **documentation-expert** | JSDoc, TSDoc, API docs, README | tsdoc, jsdoc | documentation |
| **python-expert** | Python, async, typing, uv, poetry | python | documentation |
| **accessibility-expert** | a11y, WCAG, ARIA, keyboard navigation | wcag | documentation |
| **log-analyst** | logs, debugging, errors, stack traces | logging | log-analyzer |
| **performance-expert** | performance, profiling, optimization, bottleneck | performance | performance-profiler |

### Frontend Agents

| Agent | Triggers | Skills | MCP Servers |
|-------|----------|--------|-------------|
| **react-expert** | React, components, hooks, JSX | react, tanstack-query, zustand | documentation, code-quality |
| **nextjs-expert** | Next.js, App Router, Server Components | nextjs | documentation |
| **vue-expert** | Vue, Composition API, Pinia | vue, nuxt | documentation |
| **svelte-expert** | Svelte, SvelteKit, stores | svelte, sveltekit | documentation |
| **electron-expert** | Electron, desktop apps | electron | documentation |
| **tauri-expert** | Tauri, Rust desktop apps | tauri | documentation |
| **angular-expert** | Angular, signals, standalone, SSR, NgRx | angular, angular-routing, angular-forms, angular-http, angular-testing, angular-material, angular-ssr, ngrx, typescript | documentation |

### Backend Agents

| Agent | Triggers | Skills | MCP Servers |
|-------|----------|--------|-------------|
| **spring-boot-expert** | Spring Boot, @Entity, @Controller, @Service | spring-boot, spring-data-jpa, spring-security | documentation, api-tester |
| **nestjs-expert** | NestJS, modules, guards, pipes | nestjs, prisma | documentation, api-tester |
| **fastapi-expert** | FastAPI, Pydantic, async Python | fastapi, sqlalchemy | documentation, api-tester |
| **rust-expert** | Rust, Actix-web, Axum, Rocket, Warp | rust, actix-web, axum | documentation |
| **go-expert** | Go, Gin, Fiber, Echo, Chi | go, gin, fiber | documentation |
| **deno-expert** | Deno, Fresh, Oak | deno, fresh | documentation |
| **dotnet-expert** | ASP.NET Core, EF Core, Blazor, SignalR, C# | aspnet-core, aspnet-minimal-api, aspnet-middleware, aspnet-signalr, aspnet-blazor, aspnet-identity, aspnet-validation, entity-framework-core, csharp, xunit | documentation, api-tester |

### Database Agents

| Agent | Triggers | Skills | MCP Servers |
|-------|----------|--------|-------------|
| **prisma-expert** | Prisma, schema, migrations | prisma | documentation |
| **sql-expert** | SQL, PostgreSQL, MySQL, queries | postgresql, mysql | documentation, database-query |
| **mongodb-expert** | MongoDB, aggregations, Spring Data MongoDB | mongodb, spring-data-mongodb | documentation |

### Testing Agents

| Agent | Triggers | Skills | MCP Servers |
|-------|----------|--------|-------------|
| **vitest-expert** | Vitest, Jest, unit tests, describe | vitest | documentation, code-quality |
| **playwright-expert** | Playwright, E2E, page.goto, locator | playwright | documentation |
| **spring-boot-integration-test-expert** | @SpringBootTest, @DataJpaTest, Testcontainers | spring-boot-test, testcontainers | documentation |
| **python-integration-test-expert** | pytest integration, testcontainers python, pytest-django, FastAPI test, factory_boy, celery test, pact python | python-integration, testcontainers-python, pytest-django, fastapi-testing, factory-boy | documentation |
| **smoke-test-expert** | smoke test, verify implementation, test endpoints, end-to-end verification | smoke-test, rest-assured, testcontainers | api-tester, database-query, docker-manager, log-analyzer, documentation |

### Infrastructure & DevOps

| Agent | Triggers | Skills | MCP Servers |
|-------|----------|--------|-------------|
| **docker-expert** | Docker, Dockerfile, docker-compose, containers | docker, docker-compose | docker-manager |
| **devops-expert** | CI/CD, GitHub Actions, GitLab CI, deployment | github-actions, ci-cd | docker-manager |

### Messaging Agents

| Agent | Triggers | Skills | MCP Servers |
|-------|----------|--------|-------------|
| **messaging-expert** | Kafka, RabbitMQ, NATS, SQS, event streaming | kafka, rabbitmq, nats | documentation |

### Quality & Open Source Agents

| Agent | Triggers | Skills | MCP Servers |
|-------|----------|--------|-------------|
| **qa-expert** | QA, test strategy, quality assurance | testing-strategy | documentation |
| **integration-validator-expert** | API contracts, frontend-backend alignment | integration-validation | documentation, api-explorer |
| **open-source-expert** | OSS, licensing, community health, compliance | open-source | documentation, code-quality |

### Security Agent

| Agent | Triggers | Skills | MCP Servers |
|-------|----------|--------|-------------|
| **security-expert** | security, authentication, authorization, JWT | jwt, oauth2, owasp, secrets-management | security-scanner, documentation |

---

## Commands Reference

Slash commands available in Claude Code after initialization:

| Command | Description |
|---------|-------------|
| `/init-project [preset]` | Initialize dev-suite for a project with optional preset |
| `/docs <technology> [topic]` | Access documentation for a technology |
| `/generate <type>` | Generate code scaffolding (components, APIs, tests) |
| `/show-config` | Display current dev-suite configuration |
| `/reconfigure` | Modify existing configuration (add/remove agents, MCP servers) |
| `/health-check` | Validate installation and diagnose issues |
| `/sync-dev-suite` | Update dev-suite components to latest version |
| `/ui-wizard` | Launch configuration dashboard |
| `/uninstall` | Remove dev-suite components (interactive, preserves user content) |
| `/uninstall-dev-suite` | Full dev-suite removal with complete cleanup |

---

## Upgrading

### Via Dashboard (Recommended)

The easiest way to upgrade is through the **Updates** tab in the dashboard:

1. Open the dashboard: `./init-project.sh .`
2. Navigate to the **Updates** tab
3. Review available updates and select components to upgrade
4. Click **Apply Updates** — dev-suite handles conflict detection automatically

### Manual Upgrade

```bash
# 1. Pull the latest dev-suite
cd dev-suite
git pull origin main

# 2. Rebuild all MCP servers
cd mcp-servers && npm install && npm run build

# 3. Sync installed projects (run in each project)
/path/to/dev-suite/init-project.sh /path/to/your-project
```

Then restart Claude Code to reload the updated MCP servers.

### From v1.0.x to v1.1.x

No breaking changes. Run the manual upgrade steps above. New components (agents, skills, MCP servers) added since your installation are surfaced automatically in the dashboard **Manage** tab with a one-click install option.

---

## Monorepo Support

Dev-Suite automatically detects monorepo structures:

```
my-project/
├── frontend/                  # React, Vue, etc.
│   └── package.json
├── backend/                   # Spring Boot, NestJS, etc.
│   └── pom.xml
└── docker-compose.yml
```

**Detected patterns**:
- Frontend: `frontend`, `client`, `web`, `app`, `*-frontend`
- Backend: `backend`, `server`, `api`, `*-backend`

The wizard generates `.dev-suite.json` with relative paths:

```json
{
  "project": {
    "isMonorepo": true,
    "frontendPath": "frontend",
    "backendPath": "backend"
  }
}
```

---

## Contributing

Contributions are welcome! To add new features:

### Adding a New MCP Server

1. Create directory: `mcp-servers/{server-name}/`
2. Add `package.json`, `metadata.json`, `src/index.ts`
3. Update `mcp-servers/package.json` workspaces
4. Build: `npm install && npm run build` from `mcp-servers/`

### Adding a New Agent

1. Create file: `agents/{category}/{name}-expert.md`
2. Add YAML frontmatter with skills and MCP servers
3. Write agent content (role, responsibilities, examples)

### Adding a New Skill

1. Create directory: `skills/{category}/{technology}/`
2. Add `SKILL.md` with skill definition
3. Optionally add `quick-ref/` guides

See [CLAUDE.md](CLAUDE.md) for detailed development guidelines.

---

## Troubleshooting

### Dashboard doesn't launch

- Check Node.js version: `node --version` (must be v20+)
- Check if MCP servers are built: `ls mcp-servers/*/dist/index.js`
- Check if port 3456 is in use: `netstat -an | findstr 3456` (Windows) or `lsof -i :3456` (Linux/macOS)
- Try rebuilding: `cd mcp-servers && npm install && npm run build`

### MCP servers not detected in Claude Code

- Verify `.mcp.json` exists in your project root and has valid JSON
- Check that all paths in `.mcp.json` are absolute
- Restart Claude Code after initialization
- Check that MCP server dist files exist: `ls .mcp-servers/*/dist/index.js`

### Agent not routing correctly

- Verify `CLAUDE.md` exists in your project root and contains agent routing rules
- Check that agent `.md` files exist in `.claude/agents/`
- Verify YAML frontmatter syntax in agent files

### Database MCP not connecting

- Check `DATABASE_URL` environment variable is set correctly
- Test the connection string manually: `psql $DATABASE_URL` (PostgreSQL)
- Ensure the database server is running

### Knowledge base not fetching docs

- Check Git is installed: `git --version`
- Verify internet connectivity (KB repo is on GitHub)
- Try forcing a refresh: ask Claude to `fetch_docs({ technology: "react", topic: "hooks", refresh: true })`
- Check cache directory permissions: `.kb-cache/`

---

## License

MIT License - see [LICENSE](LICENSE) for details.

---

**Questions or Issues?**

- 📖 Knowledge Base: [github.com/claude-dev-suite/knowledge_base](https://github.com/claude-dev-suite/knowledge_base)
- 🌐 Dashboard: `http://localhost:3456` (when running)
- 🔌 WebSocket: `ws://localhost:3457` (orchestrator)

---

**Built with ❤️ for Claude Code developers**