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

# TypeScript compilation and bundling
npm run build:frontend:dev   # Build frontend for development
npm run build:frontend:prod  # Build frontend for production (minified)
npm run watch:frontend       # Watch mode with auto-rebuild
npm run typecheck:frontend   # Type checking only (no output)
npm run typecheck           # Check both backend and frontend types

# Development workflow  
npm run dev:dashboard       # Start dashboard with hot reload (frontend + backend)
npm run dev:dashboard:backend-only  # Start only backend (for frontend debugging)

# Full build process
npm run build              # Complete build: TypeScript + frontend + static files
npm run lint               # Lint TypeScript files with auto-fix
npm run format             # Format code with Prettier

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

```typescript // Import dashboard types import type { Project, WebSocketMessage, AppState } from './dashboard.types';

// Type-safe project handling function selectProject(project: Project): void { console.log(Selected: ${project.name} (${project.specs.length} specs));

// Safe property access with optional chaining const steeringCount = project.steeringStatus?.totalDocs ?? 0; if (steeringCount > 0) { console.log(Steering docs: ${steeringCount}); } }

// WebSocket message handling with discriminated unions function handleMessage(message: WebSocketMessage): void { switch (message.type) { case 'initial': // TypeScript knows data is InitialData console.log(Loaded ${message.data.projects.length} projects); break; case 'update': // TypeScript knows data is UpdateData console.log(Updated project: ${message.data.projectPath}); break; case 'error': // TypeScript knows data is ErrorData console.error(Error: ${message.data.message}); break; } }

// Type guards for runtime validation function isValidProject(obj: unknown): obj is Project { return ( typeof obj === 'obje