# 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 →](https://github.com/Pimzino/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
```bash
npm i -g @pimzino/claude-code-spec-workflow
```
2. Run the setup command in your project directory
```bash
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:**
```bash
/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:**
```bash
# Manual control
/spec-execute 1 feature-name
/feature-name-task-1 # Auto-generated
```
### **Bug Fix Workflow** (Quick Fixes)
```bash
/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)
```bash
/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 ` | Complete spec workflow |
| `/spec-execute ` | Manual task execution |
| `/-task-` | Auto-generated task commands |
| `/spec-status` | Show progress |
| `/spec-list` | List all specs |
Bug Fix Commands
| Command | Purpose |
|---------|---------|
| `/bug-create ` | 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**
```bash
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:
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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**
```bash
# Make sure you're using the correct package name
npx @pimzino/claude-code-spec-workflow
```
**❓ Setup fails with permission errors**
```bash
# Try with different directory permissions
npx @pimzino/claude-code-spec-workflow --project ~/my-project
```
**❓ Claude Code not detected**
```bash
# Install Claude Code first
npm install -g @anthropic-ai/claude-code
```
### Debug Information
```bash
# Show verbose output
DEBUG=* npx @pimzino/claude-code-spec-workflow
# Check package version
npx @pimzino/claude-code-spec-workflow --version
```
## Examples
### Basic Usage
```bash
cd my-awesome-project
npx @pimzino/claude-code-spec-workflow
claude
# Type: /spec-create user-dashboard "User profile management"
```
### Advanced Usage
```bash
# 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
```typescript
// 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