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

Install the workflow globally

 `npm i -g @pimzino/claude-code-spec-workflow`

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:

Requirements → User stories + acceptance criteria
Design → Technical architecture + diagrams
Tasks → Atomic, agent-friendly breakdown
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

// 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 === 'object' &&
    obj !== null &&
    'path' in obj &&
    'name' in obj &&
    'specs' in obj &&
    Array.isArray((obj as Project).specs)
  );
}

// Result type for error handling
type Result<T, E = Error> = 
  | { success: true; data: T }
  | { success: false; error: E };

function parseProjectData(data: unknown): Result<Project> {
  if (isValidProject(data)) {
    return { success: true, data };
  }
  return { success: false, error: new Error('Invalid project data') };
}

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 unions
Result pattern for error handling
Runtime validation with type guards for external data

📚 Documentation

Full Documentation
Tunnel Feature Guide - Comprehensive tunnel documentation
Tunnel Examples - Ready-to-use tunnel scripts
Claude Code Docs
TypeScript API Reference - Generated from JSDoc comments

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.

📄 License

MIT License - see LICENSE for details.

🏷️ Changelog

See CHANGELOG.md for version history.

🚦 When To Use What

Scenario	Recommended Approach
New feature, well-defined	`/spec-execute` or individual task commands
Complex/experimental feature	`/spec-execute` (manual control)
Bug in existing code	Bug workflow (`/bug-create` → `/bug-verify`)
Learning the codebase	Manual execution with individual commands
Production deployment	Full spec workflow with completion review

🚀 Installation & Setup

Installation

# Install globally (recommended)
npm install -g @pimzino/claude-code-spec-workflow

# Verify installation
claude-code-spec-workflow --version

Setup Options

# Basic setup
claude-code-spec-workflow

# Advanced options
claude-code-spec-workflow --project /path --force --yes

During setup you choose:

✅ Enable agents? Enhanced automation vs simpler setup
✅ Project analysis Auto-detection of frameworks and patterns

📚 Examples

Recommendation: Use Claude Opus 4 to generate the spec documentation '/spec-create', then use Claude Sonnet 4 for the implementation i.e. '/spec-execute' or '/{spec-name}-task-'.

Basic Workflow Example

# 1. Install globally (one time)
npm install -g @pimzino/claude-code-spec-workflow

# 2. Setup project (one time)
cd my-project
claude-code-spec-workflow

# 3. Create steering documents (recommended)
claude
/spec-steering-setup

# 4. Create feature spec
/spec-create user-authentication "Secure login system"

# 5. Execute tasks
/spec-execute 1 user-authentication

# 6. Monitor progress
/spec-status user-authentication

Bug Fix Example

/bug-create login-timeout "Users logged out too quickly"
/bug-analyze
/bug-fix
/bug-verify

⚡ Context Optimization Commands

The package includes optimized commands for efficient document loading across all document types:

get-steering-context

Load all steering documents at once for context sharing:

claude-code-spec-workflow get-steering-context

Output: Formatted markdown with all steering documents (product.md, tech.md, structure.md)

get-spec-context

Load all specification documents at once for context sharing:

claude-code-spec-workflow get-spec-context feature-name

Output: Formatted markdown with all spec documents (requirements.md, design.md, tasks.md)

get-template-context

Load templates by category for context sharing:

# Load all templates
claude-code-spec-workflow get-template-context

# Load specific template category
claude-code-spec-workflow get-template-context spec    # Spec templates
claude-code-spec-workflow get-template-context bug     # Bug templates
claude-code-spec-workflow get-template-context steering # Steering templates

Output: Formatted markdown with requested templates

Smart Document Handling

High-redundancy documents (steering, specs, templates): Use optimized bulk loading
Low-redundancy documents (bug reports): Use direct file reading for simplicity
Selective delegation: Main agents load full context, but pass only relevant portions to sub-agents
Individual files: Continue using get-content for edge cases

Benefits

60-80% token reduction compared to individual file loading
Faster execution with cached context across all workflows
Automatic fallback to individual get-content when needed
Session-based caching with intelligent file change detection

Hierarchical Context Management

The system implements a sophisticated hierarchical context management strategy for maximum efficiency:

Main Agents (Commands like /spec-execute, /spec-create):

Load ALL context once at the beginning using optimized commands
Store complete context for task coordination and decision-making
Distribute selective context to sub-agents without requiring reloads

Sub-Agents (Agents like spec-task-executor):

Priority 1: Use provided context from task instructions (steering, specification, task details)
Priority 2: Fallback to loading context only if not provided above
Never redundantly load context when it's already been provided by main agents

Context Distribution Pattern:

Main Agent loads: Steering + Full Spec + Task Details
↓ Delegates to Sub-Agent with:
├── Complete Steering Context
├── Selective Spec Context (Requirements + Design only)
├── Specific Task Details
└── Clear instruction: "Do NOT reload context"

This approach eliminates redundant loading while ensuring each agent has exactly the context it needs.

🛟 Troubleshooting

Common Issues

❓ "Command not found"

# Install globally first
npm install -g @pimzino/claude-code-spec-workflow

# Then use the command
claude-code-spec-workflow

❓ "Claude Code not detected"

npm install -g @anthropic-ai/claude-code

❓ "Permission errors"

claude-code-spec-workflow --project ~/my-project

📋 Requirements

Node.js 16.0.0+
Claude Code installed
Any project directory

🔗 Links

📄 License & Credits

MIT License - LICENSE

Made with ❤️ by Pimzino

Special Thanks:

@pimzino - Initial setup
@boundless-oss - Steering documents
@mquinnv - Dashboard feature

Powered by: Claude Code • Mermaid • TypeScript

Name		Name	Last commit message	Last commit date
Latest commit History 416 Commits
.claude		.claude
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
docs		docs
examples/tunnel		examples/tunnel
scripts		scripts
src-tauri		src-tauri
src		src
tests		tests
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
esbuild.config.js		esbuild.config.js
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
test-bug-parser.js		test-bug-parser.js
test-exposed-gql-parser.js		test-exposed-gql-parser.js
tsconfig.json		tsconfig.json

License

Pimzino/claude-code-spec-workflow

Folders and files

Latest commit

History

Repository files navigation

Claude Code Spec Workflow

☕ Support This Project

📦 Installation

Thats it, you are ready to go!

✨ What You Get

🔄 Workflows Overview

📊 Spec Workflow (New Features)

🐛 Bug Fix Workflow (Quick Fixes)

🎯 Steering Setup (Project Context)

🛠️ Commands Reference

🎯 Key Features

🤖 Intelligent Task Execution

🧠 Specialized Agents (Optional)

⚡ Complete Context Optimization (NEW!)

📊 Real-Time Dashboard

🔗 Dashboard Tunnel (NEW!)

📊 Command Line Options

Setup Commands

Dashboard Commands

🎯 Steering Documents (NEW!)

Product Document (product.md)

Technology Document (tech.md)

Structure Document (structure.md)

🎨 Features

✅ Zero Configuration

✅ Interactive Setup

✅ Smart File Management

✅ Professional Quality

✅ Steering Document Integration

✅ TypeScript Dashboard Frontend

🏗️ Project Structure After Setup

🧪 Testing

📋 Requirements

🔧 Troubleshooting

Common Issues

Debug Information

🌟 Examples

Basic Usage

Advanced Usage

🔧 TypeScript Development

Frontend Dashboard Development

Type Definitions

Build Commands

Type Safety Features

Type Usage Examples

Development Guidelines

📚 Documentation

🤝 Contributing

📄 License

🏷️ Changelog

🚦 When To Use What

🚀 Installation & Setup

Installation

Setup Options

📚 Examples

⚡ Context Optimization Commands

get-steering-context

get-spec-context

get-template-context

Smart Document Handling

Benefits

Hierarchical Context Management

🛟 Troubleshooting

📋 Requirements

🔗 Links

📄 License & Credits

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Product Document (`product.md`)

Technology Document (`tech.md`)

Structure Document (`structure.md`)

Packages