Baike.dev
All toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
C

claude-code-spec-workflow

> 编程语言
Open source

Automated workflows for Claude Code. Features spec-driven development for new features (Requirements → Design → Tasks → Implementation) and streamlined bug fix

3.8K stars0 likes0 views
WebsiteGitHub

About

Automated workflows for Claude Code. Features spec-driven development for new features (Requirements → Design → Tasks → Implementation) and streamlined bug fix

Claude Code Spec Workflow

⚠️ IMPORTANT NOTICE: Development focus has shifted to the MCP (Model Context Protocol) version of this workflow system. The MCP version provides enhanced features, real-time dashboard, and broader AI tool compatibility.

** View the new Spec Workflow MCP →**

This Claude Code-specific version remains available for existing users but will receive limited updates. Automated workflows for Claude Code with intelligent task execution.

Transform your development with structured workflows: Requirements → Design → Tasks → Implementation for new features, plus streamlined Report → Analyze → Fix → Verify for bug fixes.

☕ Support This Project

Installation

  1. Install the workflow globally
npm i -g @pimzino/claude-code-spec-workflow
  1. Run the setup command in your project directory
claude-code-spec-workflow

Thats it, you are ready to go!

✨ What You Get

  • ** Complete .claude/ structure** - All files and directories
  • ** 10 slash commands** - 5 spec workflow + 5 bug fix workflow
  • ** Intelligent task execution** - Automated implementation
  • ** 4 specialized agents** - Enhanced automation
  • ** Real-time dashboard** - Monitor progress visually
  • ** Auto-generated commands** - One command per task
  • ** Document templates** - Professional spec documents
  • ⚙️ Project steering - Persistent context and standards
  • ⚡ Smart optimization - Intelligent context sharing and caching

Workflows Overview

Spec Workflow (New Features)

Complete automation in one command:

/spec-create feature-name "Description"

What happens:

  1. Requirements → User stories + acceptance criteria
  2. Design → Technical architecture + diagrams
  3. Tasks → Atomic, agent-friendly breakdown
  4. Commands → Auto-generated task commands (optional)

Execute tasks:

# Manual control
/spec-execute 1 feature-name
/feature-name-task-1        # Auto-generated

Bug Fix Workflow (Quick Fixes)

/bug-create issue-name "Description"  # Document the bug
/bug-analyze                          # Find root cause
/bug-fix                             # Implement solution
/bug-verify                          # Confirm resolution

Steering Setup (Project Context)

/spec-steering-setup  # Creates product.md, tech.md, structure.md

️ Commands Reference

Spec Workflow Commands
Command Purpose
/spec-steering-setup Create project context documents
/spec-create <name> Complete spec workflow
/spec-execute <task-id> Manual task execution
/<name>-task-<id> Auto-generated task commands
/spec-status Show progress
/spec-list List all specs
Bug Fix Commands
Command Purpose
/bug-create <name> Document bug with structured format
/bug-analyze Investigate root cause
/bug-fix Implement targeted solution
/bug-verify Verify resolution
/bug-status Show bug fix progress

Key Features

Intelligent Task Execution

  • Streamlined task implementation
  • Context-aware execution with full specification context
  • Agent-based implementation with spec-task-executor

Specialized Agents (Optional)

4 AI agents for enhanced automation:

Core Workflow: spec-task-executor, spec-requirements-validator, spec-design-validator, spec-task-validator

Note: Agents are optional - everything works with built-in fallbacks.

⚡ Complete Context Optimization (NEW!)

  • Universal context sharing - Steering, specification, AND template documents optimized
  • 60-80% token reduction - Eliminates redundant document fetching across all document types
  • Triple optimization commands - get-steering-context, get-spec-context, and get-template-context
  • Smart document handling - Bug documents use direct reading (no redundancy), templates use bulk loading (high redundancy)
  • Improved performance - Faster agent execution with cached context across all workflows
  • Automatic fallback - Maintains reliability with individual get-content when optimization unavailable
  • Session-based caching - Intelligent file change detection and cache invalidation

Real-Time Dashboard

npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard
  • Live progress tracking
  • WebSocket updates
  • Git integration
  • Modern UI with Tailwind CSS

Dashboard Tunnel (NEW!)

Share your dashboard securely with external stakeholders through temporary HTTPS URLs:

# Start dashboard with tunnel
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --tunnel

# With password protection
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --tunnel --tunnel-password mySecret123

# Choose specific provider
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --tunnel --tunnel-provider cloudflare

Tunnel Features:

  • ** Secure HTTPS URLs** - Share dashboard with managers, clients, or remote team members
  • ️ Read-Only Access - External viewers cannot modify any project data
  • ** Optional Password** - Protect access with password authentication
  • ** Multiple Providers** - Automatic fallback between Cloudflare and ngrok
  • ** Usage Analytics** - Track who accessed your dashboard and when
  • ⏰ Auto-Expiration - Tunnels close when you stop the dashboard
  • ** Zero Configuration** - Works out of the box with built-in providers

Command Line Options

Setup Commands

# Setup in current directory
npx @pimzino/claude-code-spec-workflow

# Setup in specific directory
npx @pimzino/claude-code-spec-workflow --project /path/to/project

# Force overwrite existing files
npx @pimzino/claude-code-spec-workflow --force

# Skip confirmation prompts
npx @pimzino/claude-code-spec-workflow --yes

# Test the setup
npx @pimzino/claude-code-spec-workflow test

Dashboard Commands

# Basic dashboard
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard

# Dashboard with tunnel (share externally)
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --tunnel

# Full tunnel configuration
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard \
  --tunnel \
  --tunnel-password mySecret123 \
  --tunnel-provider cloudflare \
  --port 3000 \
  --open

Steering Documents (NEW!)

Steering documents provide persistent project context that guides all spec development:

Product Document (product.md)

  • Product vision and purpose
  • Target users and their needs
  • Key features and objectives
  • Success metrics

Technology Document (tech.md)

  • Technology stack and frameworks
  • Development tools and practices
  • Technical constraints and requirements
  • Third-party integrations

Structure Document (structure.md)

  • File organization patterns
  • Naming conventions
  • Import patterns
  • Code organization principles

Run /spec-steering-setup to create these documents. Claude will analyze your project and help you define these standards.

Features

✅ Zero Configuration

  • Works out of the box with any project
  • Auto-detects project type (Node.js, Python, Java, etc.)
  • Validates Claude Code installation

✅ Interactive Setup

  • Beautiful CLI with progress indicators
  • Confirmation prompts for safety
  • Helpful error messages and guidance

✅ Smart File Management

  • Complete workflow instructions in each command file
  • Creates comprehensive directory structure
  • Includes all necessary templates and configs

✅ Professional Quality

  • Full TypeScript implementation with strict type checking
  • Frontend converted to TypeScript for enhanced dashboard development
  • 95%+ type coverage with no implicit any types
  • Modern build pipeline with esbuild bundling and source maps
  • Comprehensive error handling
  • Follows npm best practices

✅ Steering Document Integration

  • Persistent project context across all specs
  • Automatic alignment with project standards
  • Consistent code generation
  • Reduced need for repetitive explanations

✅ TypeScript Dashboard Frontend

  • Type-safe frontend code with comprehensive interfaces
  • Real-time WebSocket communication with typed message handling
  • Petite-vue integration with custom type definitions
  • Build pipeline supporting development and production bundles
  • Strict null checking and modern TypeScript patterns
  • JSDoc documentation for all exported functions

️ Project Structure After Setup

your-project/
├── .claude/
│   ├── commands/           # 14 slash commands + auto-generated
│   ├── steering/          # product.md, tech.md, structure.md
│   ├── templates/         # Document templates
│   ├── specs/            # Generated specifications
│   ├── bugs/             # Bug fix workflows
│   └── agents/           # AI agents (enabled by default)

Testing

The package includes a built-in test command:

# Test setup in temporary directory
npx @pimzino/claude-code-spec-workflow test

Requirements

  • Node.js 16.0.0 or higher
  • Claude Code installed and configured
  • Any project directory

Troubleshooting

Common Issues

❓ Command not found after NPX

# Make sure you're using the correct package name
npx @pimzino/claude-code-spec-workflow

❓ Setup fails with permission errors

# Try with different directory permissions
npx @pimzino/claude-code-spec-workflow --project ~/my-project

❓ Claude Code not detected

# Install Claude Code first
npm install -g @anthropic-ai/claude-code

Debug Information

# Show verbose output
DEBUG=* npx @pimzino/claude-code-spec-workflow

# Check package version
npx @pimzino/claude-code-spec-workflow --version

Examples

Basic Usage

cd my-awesome-project
npx @pimzino/claude-code-spec-workflow
claude
# Type: /spec-create user-dashboard "User profile management"

Advanced Usage

# Setup multiple projects
for dir in project1 project2 project3; do
  npx @pimzino/claude-code-spec-workflow --project $dir --yes
done

TypeScript Development

Frontend Dashboard Development

The dashboard frontend is fully implemented in TypeScript for enhanced type safety and developer experience:

Type Definitions

// Core dashboard types
interface Project {
  path: string;
  name: string;
  level: number;
  hasActiveSession: boolean;
  specs: Spec[];
  bugs: Bug[];
  steeringStatus?: SteeringStatus;
}

// WebSocket message types with discriminated unions
type WebSocketMessage = 
  | { type: 'initial'; data: InitialData }
  | { type: 'update'; data: UpdateData }
  | { type: 'error'; data: ErrorData }
  | { type: 'tunnel-status'; data: TunnelStatusData };

Build Commands

…

Type Safety Features

  • Strict TypeScript configuration with null checks
  • Runtime type validation with type guards
  • WebSocket message typing for real-time updates
  • State management types for reactive UI components
  • Error handling types with Result pattern
  • Petite-vue integration with custom type definitions

Type Usage Examples

…

Development Guidelines

  • JSDoc documentation on all exported functions
  • 95%+ type coverage maintained (no implicit any types)
  • Modern TypeScript patterns (optional chaining, nullish coalescing)
  • Type guards preferred over type assertions
  • Interfaces for object shapes, union types for discriminated uni

Issues· 2 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

TypeScript

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集，为前端与全栈提供静态类型
P
Python
通用编程语言，广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言