Automated workflows for Claude Code. Features spec-driven development for new features (Requirements → Design → Tasks → Implementation) and streamlined bug fix workflow for quick issue resolution (Report → Analyze → Fix → Verify).
Install and run in any project directory:
npx @pimzino/claude-code-spec-workflowThat's it! The workflow will be automatically set up in your project.
# Run once in your project directory
npx @pimzino/claude-code-spec-workflow
# Test the setup
npx @pimzino/claude-code-spec-workflow test# Install globally
npm install -g @pimzino/claude-code-spec-workflow
# Use anywhere
claude-spec-setup# Install as dev dependency
npm install --save-dev @pimzino/claude-code-spec-workflow
# Run via package.json script
npx claude-spec-setupThe setup automatically creates:
- 📁 .claude/ directory structure with all necessary files
- 📝 13 slash commands (8 spec workflow + 5 bug fix workflow)
- 🎯 Steering documents for persistent project context
- 🤖 Auto-generated task commands for each spec
- 📋 Document templates for both workflows
- ⚙️ Configuration files for workflow automation
- 🔧 NPX-based task command generation for dynamic task commands
- 📖 Complete workflow instructions embedded in each command
- Creates persistent project context documents
- Analyzes your codebase and gathers project information
- Generates product.md, tech.md, and structure.md
- Ensures all specs align with your project's vision and standards
- Generates user stories and acceptance criteria
- Uses EARS format (WHEN/IF/THEN statements)
- Aligns with product vision from steering documents
- Ensures comprehensive requirement coverage
- Creates technical architecture and design
- Follows technical standards from steering documents
- Includes Mermaid diagrams for visualization
- Plans components, interfaces, and data models
- Breaks design into atomic coding tasks
- Respects project structure conventions
- References specific requirements
- Focuses on test-driven development
- Executes tasks systematically
- Follows all steering document guidelines
- Validates against requirements
- Ensures quality and consistency
- Documents the bug with structured format
- Captures expected vs actual behavior
- Records reproduction steps and environment
- Assesses impact and severity
- Investigates root cause systematically
- Maps affected code locations
- Plans fix strategy and approach
- Considers alternative solutions
- Implements targeted, minimal fix
- Follows project coding standards
- Adds appropriate tests
- Preserves existing functionality
- Verifies bug is resolved
- Tests for regressions
- Confirms code quality
- Documents resolution
After setup, use these commands in Claude Code:
# Set up steering documents (recommended first step!)
/spec-steering-setup
# Create a new feature spec
/spec-create user-authentication "Secure login system"
# Generate requirements document
/spec-requirements
# Create design document
/spec-design
# Generate implementation tasks
/spec-tasks
# Execute specific tasks (two ways):
/spec-execute 1 # Traditional way
/user-authentication-task-1 # New auto-generated command
# Execute subtasks
/user-authentication-task-2.1 # Auto-generated for subtasks
# Check status
/spec-status
# List all specs
/spec-list# Start a new bug fix
/bug-create login-timeout "Users getting logged out too quickly"
# Analyze the bug
/bug-analyze
# Implement the fix
/bug-fix
# Verify the fix works
/bug-verify
# Check bug status
/bug-statusUse Spec Workflow for:
- New features or major functionality
- Complex changes requiring design planning
- Features that need detailed requirements gathering
- Long-term development projects
Use Bug Fix Workflow for:
- Fixing existing functionality
- Small, targeted changes
- Quick issue resolution
- Troubleshooting and debugging
The workflow now automatically creates individual commands for each task:
- Easier execution:
/user-auth-task-1instead of/spec-execute 1 user-authentication - Better organization: Commands grouped by spec in
.claude/commands/{spec-name}/ - Auto-completion: Claude Code can suggest spec-specific commands
- Clear purpose: Each command shows exactly what task it executes
Monitor your specs and tasks with a beautiful web dashboard:
# Start the dashboard
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard
# Start on custom port
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --port 8080
# Auto-open in browser
npx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard --open
# Alternative: If you have the package installed globally
npm install -g @pimzino/claude-code-spec-workflow
claude-spec-dashboardDashboard Features:
- Real-time updates - See changes as they happen
- Steering documents status - Visual indicators for product.md, tech.md, and structure.md
- Progress tracking - Visual progress bars for each spec
- Task breakdown - Expandable task lists with status
- Code reuse visibility - See leverage references at a glance
- Git integration - Shows current branch with GitHub links
- Modern UI - Built with Tailwind CSS and petite-vue
- Lightweight - No heavy frameworks, just fast tools
- WebSocket powered - Instant updates when files change
# 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 testSteering documents provide persistent project context that guides all spec development:
- Product vision and purpose
- Target users and their needs
- Key features and objectives
- Success metrics
- Technology stack and frameworks
- Development tools and practices
- Technical constraints and requirements
- Third-party integrations
- 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.
- Works out of the box with any project
- Auto-detects project type (Node.js, Python, Java, etc.)
- Validates Claude Code installation
- Beautiful CLI with progress indicators
- Confirmation prompts for safety
- Helpful error messages and guidance
- Complete workflow instructions in each command file
- Creates comprehensive directory structure
- Includes all necessary templates and configs
- TypeScript implementation
- Comprehensive error handling
- Follows npm best practices
- Persistent project context across all specs
- Automatic alignment with project standards
- Consistent code generation
- Reduced need for repetitive explanations
your-project/
├── .claude/
│ ├── commands/
│ │ ├── spec-create.md
│ │ ├── spec-requirements.md
│ │ ├── spec-design.md
│ │ ├── spec-tasks.md
│ │ ├── spec-execute.md
│ │ ├── spec-status.md
│ │ ├── spec-list.md
│ │ ├── spec-steering-setup.md # NEW!
│ │ └── {spec-name}/ # Auto-generated
│ │ ├── task-1.md
│ │ ├── task-2.md
│ │ └── task-2.1.md
│ ├── steering/ # NEW!
│ │ ├── product.md # Product vision & goals
│ │ ├── tech.md # Technical standards
│ │ └── structure.md # Project conventions
│ ├── templates/
│ │ ├── requirements-template.md
│ │ ├── design-template.md
│ │ └── tasks-template.md
│ ├── specs/
│ │ └── (your specs will be created here)
│ └── spec-config.json
The package includes a built-in test command:
# Test setup in temporary directory
npx @pimzino/claude-code-spec-workflow test- Node.js 16.0.0 or higher
- Claude Code installed and configured
- Any project directory
❓ 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# Show verbose output
DEBUG=* npx @pimzino/claude-code-spec-workflow
# Check package version
npx @pimzino/claude-code-spec-workflow --versioncd my-awesome-project
npx @pimzino/claude-code-spec-workflow
claude
# Type: /spec-create user-dashboard "User profile management"# Setup multiple projects
for dir in project1 project2 project3; do
npx @pimzino/claude-code-spec-workflow --project $dir --yes
doneContributions are welcome! Please see our Contributing Guide.
MIT License - see LICENSE for details.
See CHANGELOG.md for version history.
Transform your development workflow with automated spec-driven development! 🚀
Made with ❤️ by Pimzino
@pimzino - for the initial setup @boundless-oss - Adding steering documents @mquinnv - spec workflow dashboard feature
